63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# 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.
|