ai-chatbot/services/pascal-editor/wiki/architecture/agent-runtime.md

AI Agent Runtime

How the standalone editor lets a conversational agent operate saved scenes through Pascal MCP.

Applies to: apps/editor/app/api/agent/**, apps/editor/components/ai-design-agent-panel.tsx, apps/editor/lib/pascal-agent-*.ts.

The editor owns the chat surface and model call. Pascal MCP remains the only agent mutation boundary; the UI must not translate natural language directly into scene-store writes.

Process Isolation

SceneBridge uses an in-process scene store, so one long-lived MCP process cannot safely hold active scenes for multiple users. The Agent API therefore starts one stdio MCP child process per chat turn. Every child process:

1. Opens the shared SQLite scene store.
2. Loads exactly the scene supplied by the authenticated route.
3. Runs the bounded model/tool loop.
4. Saves the final draft and closes.

Do not replace this with a global MCP client unless SceneBridge first becomes request-scoped and concurrency-safe.

Scene Scope

The server loads the scene before the model receives tools. Cross-project lifecycle tools such as create_project, list_scenes, load_scene, rename_scene, and delete_scene are removed from the model tool set. save_scene is wrapped so the model cannot override the active scene ID or persist an arbitrary graph payload.

Authentication and ownership checks belong before MCP startup. A host that embeds the editor must map its authenticated user and project to the requested scene ID before forwarding a chat turn.

Hosted scene routes read only the reverse-proxy-provided X-Pascal-User-Id. When PASCAL_REQUIRE_HOST_USER=true, missing or malformed identities are rejected. The same identity is written as ownerId on scene creation and is checked by list, load, save, rename, delete, event-stream, server-rendered scene, and Agent paths.

In production the Agent API also requires PASCAL_AGENT_PROXY_SECRET. The trusted reverse proxy must remove any client-supplied copy of X-Pascal-Agent-Proxy-Secret and inject its own value. The Pascal port must not be publicly reachable; this service-level gate complements, but does not replace, host-level user and scene ownership checks.

Execution Limits

Every turn has independent limits for model/tool steps, individual tool time, and total duration. The client can abort the response stream; cancellation closes the MCP child process. Agent prompts require draft saves during work and validation plus collision checks before the final checkpoint.

UI Contract

The AI Designer panel is a host-provided sidebar tab. It uses the editor's existing color tokens and responsive sidebar behavior. Tool calls render as compact activity rows; raw scene payloads are not shown or stored in browser history. Only user and assistant text is retained locally until a host-owned conversation store is connected.