joomengine-code-ai.md

JoomEngine Code AI integration

This describes the current optional AI implementation. The experience roadmap defines the current requirements, and AI API validation records the provider matrix, fixture coverage and outstanding live checks. The original scope and checkpoints remain historical records; their earlier evidence is not a blanket verification of this expanded integration.

Interfaces

src/code/ai-provider-registry.mjs supplies the ordered public preset catalog. OpenAI, Anthropic / Claude and Google / Gemini precede the wider direct-provider/inference-service catalog; Other / Local AI API is last. It records each service's endpoint, protocol, discovery strategy, preference rules and required account fields.

src/code/ai-provider.mjs provides the self-contained createChatProvider({provider, baseURL, protocol, model, apiKey, region, workspaceId, resource, accountId, route, accessKeyId, secretAccessKey, sessionToken}). Its stream({messages, tools, signal, onDelta}) method handles the implemented Chat Completions, Responses, Anthropic Messages, Gemini, Cohere and Perplexity Agent protocols. It returns complete assistant/tool-call messages and retains necessary provider-native continuation fields. Incomplete streams never execute partial tools. Cancellation aborts fetch, redirects are rejected, cookies are omitted and provider error bodies are not forwarded. dispose() aborts pending requests and clears retained API and AWS credentials.

listModels({signal, currentModel}) performs bounded GET-only discovery with provider-specific pagination and capability filtering. It retains a still-available model or chooses from maintained preferences; static/manual fallbacks are identified separately from live discovery. src/code/ai-connection-settings.mjs keys settings by the full connection identity and cancels stale catalog operations, so changing a custom URL, protocol or account field cannot reuse the previous connection's key or model result. The exact endpoint and account limitations belong in AI API validation, not duplicated lists of assumed-compatible providers.

src/code/ai-review.mjs provides two services:

• createAiReview({workspace, isDirty, onApplied}) prepares reviewed sets without writing. accept(id) sends one batch operation with worker-checked file and directory-tree revisions; reject(id) writes nothing. undo(id) calls the shared worker recovery service. Dirty buffers are checked immediately before apply and recovery. Partial failures report the exact completed and failed operations; a resolved set cannot be blindly replayed. Existing UTF-8 BOM presence and uniform CRLF/LF/CR endings are preserved during preparation; the reviewed after string encodes to exactly the applied bytes. Mixed existing endings require deliberate editor normalization before proposing again, and malformed Unicode proposals are rejected. New files retain their provided format.
• createAiWorkspaceTools({workspace, review, scope, selectedPaths}) exposes list_files, read_file, search_files and propose_changes; selectedPaths remains a compatibility entry point. The model has no apply, shell, PHP execution or credential-setting tool. The host uses the scoped contract, defaulting to Current file. setScope, getScope and UI-only browse support Current file, Selected files/folders and Entire project. context({selection, openFiles, activePath, scope, signal}) accepts open-document descriptors {path, canonicalPath, content, unsaved}, includes eligible unsaved buffers and resolves selected folders recursively. Scope and exclusions constrain initial context, subsequent read/list/search tools, proposal targets and directory descendants. Entire project permits bounded retrieval rather than a whole-installation upload. Default limits are 64 selected paths, 128 KiB per file, 512 KiB context and bounded traversal/search results; omissions and truncation are reported. Sensitive paths and embedded credential patterns still require deliberate exact-file selection. Both current and original buffer canonical paths are checked; an alias or selected parent folder does not authorize a sensitive target.

workspace.request(operation, args) is the same authoritative root-confined bridge used by the editor, with slash-prefixed workspace paths. It must serialize batch and recover with normal PHP requests. isDirty(path, recursive) must inspect the authoritative editor models, including descendants for directory operations. onApplied(result) receives one result for a successful or partial batch; it must use the normal saved-change/refresh workflow and must not bypass manual refresh.

src/code/ai-panel.mjs provides createIsolatedAiPanel({container, tools, review, getContext, t, messages, sessionKey, locale, direction}). Use tools.context inside getContext; do not assemble an unrestricted Joomla installation dump. Accounts and AI API settings open this same surface. The context browser lives inside it. The owner and detached companion reuse the site-scoped review/tool service and authoritative editor models. dispose() disconnects a view and cancels its work; it does not erase the owning session's connection vault.

src/code/ai-connections.mjs runs the session broker in a separate opaque sandbox outside per-site UI teardown. Connection settings and masked keys follow panel close/reopen, Code visibility, detach/redock and site changes. Conversation records are site/session scoped and bounded. Direct sandbox-to-broker ports carry connection and conversation state without routing their payloads through the owner-facing workspace channel. Explicit Clear removes shared session credentials/conversations; owner-page reload/closure ends the in-memory vault.

Credential boundary

The existing Joomla preview is same-origin and is not a security sandbox. Consequently, the key, model, provider URL, prompt entry and provider fetch run inside an iframe with only sandbox="allow-scripts". The iframe has an opaque origin, no same-origin DOM/storage access, no forms, no popups, and a restrictive CSP. Its provider and panel code are embedded under a nonce, so it needs no external scripts or opaque-origin module imports. The provider must accept CORS requests from the opaque origin (Origin: null).

The host validates the exact frame window, opaque origin and one-time nonce before transferring the workspace MessagePort. The sandbox validates its parent origin and window. That port carries bounded context/read requests, proposed changes and explicit review actions, never API keys or credential exports. A separate authenticated broker handshake transfers direct isolated-channel capabilities; the host control channel attaches ports without reading connection payloads. Provider/catalog requests start from settings and actions inside the isolated panel. View disposal cancels its requests; explicit file mutations already accepted by the user retain the worker's normal completion/recovery semantics.

This isolates credential memory from Joomla script access. It does not make the same-origin host page immune to DOM replacement or phishing by a malicious Joomla extension: such code can alter the surrounding host UI. A separate trusted editor origin or a separately isolated Joomla preview is needed to address that broader host-integrity threat. Do not describe the entire Playground as a hostile-code security sandbox.

No key is written to project files, persistent browser storage, deployment URLs, export metadata, logs, snapshots or the owner-facing workspace channel. Keys are retained only in isolated session memory and its direct panel/broker channels. The UI clears them explicitly and owner-session teardown ends that memory. Browser or provider failures remain local to the AI feature.

Provider verification status

Named presets and native adapters are implemented, including Other/local endpoints with optional keys. Their presence is not a claim that every account, model or browser CORS policy has been exercised. Development-status labels were removed from the product UI; the validation requirement remains documented here and in AI API validation.

No provider API keys were supplied for this implementation. The expanded integration still needs checks from the deployed HTTPS Playground's isolated context, using an actual provider and a configured local endpoint:

1. Authentication, model discovery and opaque-origin CORS behavior.
2. Incremental text, complete tool calls and provider-native conversation continuation.
3. Scoped reads and a reviewed, explicitly accepted change.
4. Cancelled streams, useful errors and continued local editing.
5. Chromium/Firefox behavior, including local-network and mixed-content restrictions.

No proxy or local port scanning is added. Bedrock Runtime supports optional AWS credentials for native, read-only foundation-model and inference-profile discovery signed with WebCrypto SigV4. Those credentials remain inside the opaque session vault and are separate from the Bedrock bearer key used for chat. Without AWS discovery credentials, Runtime accepts a manual model/profile ID; Mantle retains its own compatible catalog. Native listings do not prove Chat Completions/tool support, so Runtime requires a deliberate model choice. See the validation matrix for regional routing, Azure deployment aliases, Fireworks deployment availability and manual catalogs. Aborting browser fetch is not a guarantee about server-side billing or cancellation.

Focused checks

node --test test/code-ai.test.mjs test/code-ai-providers.test.mjs test/code-ai-connections.test.mjs exercises the current deterministic provider, connection and review contracts. The suites cover native protocol streams/catalog pagination, full connection identity, stale catalog cancellation and scoped context alongside fragmented UTF-8 SSE and tool calls, cancellation, endpoint/request limits, key-safe errors, read-only preparation/rejection, batch apply/recovery, disk/dirty-buffer/folder membership conflicts, partial failure without replay, and sensitive context exclusion.

node --test test/code-ai-browser.mjs verifies the isolated UI with a deterministic provider in Chromium and Firefox. It uses the repository test server with COOP same-origin, COEP credentialless and CORP same-origin. The scenario checks Origin: null, inaccessible credential DOM, no key in host messages, no writes before acceptance, explicit acceptance/recovery, clearing and disposal. This is a sandbox/protocol check, not a real provider connectivity test or an end-to-end Joomla/IDE test.

Historical evidence: the earlier deterministic sandbox scenario passed Chromium and Firefox CI for implementation commit 2256a32, and Chromium locally in that earlier environment. This does not establish current expanded-provider or session-broker coverage. Current local Chromium/Firefox execution is blocked by host process/socket restrictions; use the current PR's CI results and AI API validation for the new change's evidence. Authenticated provider/local-server verification remains separate. The optional PLAYGROUND_BROWSERS and PLAYGROUND_CHROMIUM_EXECUTABLE / PLAYGROUND_FIREFOX_EXECUTABLE variables select browsers and local executable paths without changing production behavior.