# 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.