Agent runtime integration

The desktop app talks to a local agent runtime process (one per conversation slot) and forwards model traffic through the Ssscript web API. This page summarizes runtime behaviors and gateway capabilities.

@plan structured output (json_schema)

For prompts that start with @plan, the app asks runtime for JSON-shaped output using a small schema (summary, steps, risks, openQuestions). The UI renders a Structured plan card when parsing succeeds.

• If the server rejects json_schema (HTTP 400), the app retries once without structured output and falls back to plain text, still showing a plan card from the assistant text when possible.
• If there are no file diffs (normal for the plan agent), the run is treated as success: review the plan, then Dismiss (same as clearing a pending diff without touching files).

Runtime auth.set (proxy API key)

When AI runs through the Clerk-authenticated proxy, the app passes the current JWT to runtime via POST /auth/ssscript before each prompt, and once after workspace init when a token is available.

• If the server does not implement this route or rejects the call, you see a single activity line: Runtime auth sync unavailable; using runtime server env for API key.
• Process env still applies: runtime can still read provider keys from process environment. Runtime auth is an extra path so rotated tokens can apply without restarting the child process when supported.

Parallel work across conversation slots

Each carousel slot uses its own runtime provider instance and server slot id (separate port/process per slot). You can leave slot A requesting, switch to slot B, and send another prompt; state updates are scoped per slot (createSlotWriter).

Preconnect / init now passes forSlotId: activeSlotId() so background work targets the visible slot consistently.

Incremental / streaming diff

Runtime streams message parts (reasoning, tools, text deltas, patch hints). The app:

• Surfaces patch file lists in the activity stream (unchanged).
• On patch events, debounces a best-effort session.diff call without messageID and emits a short working copy preview status line when the API returns partial workspace diffs.

Limitation: session.diff with messageID is still used for the final pending diff after the prompt completes. There is no guarantee every runtime build returns meaningful cumulative diffs before the assistant message finishes; when preview polling returns nothing, only the final diff (or plan) is shown.

Activity stream merging & SSE lifecycle

The app shows live assistant/status text by merging streaming chunks from runtime (message.part.updated text deltas). Token boundaries do not always include spaces, so:

• The provider does not strip leading whitespace on status activity payloads (only trailing), so the UI can tell “new token starts here” vs “continuation”.
• App.tsx merges consecutive status lines with small heuristics (word glue vs space, English contractions like you + 'd).

Each prompt run also opens an SSE subscription to GET /event for the same runtime base URL. When the prompt finishes, the subscription is aborted and the client waits briefly for the stream task to settle before returning. That avoids the next session.prompt / session.messages call hitting a half-closed HTTP connection (which could surface as error sending request on the second message in a conversation). If you still see transport errors, retry after runtime restarts; the app also treats error sending request as a connectivity class error for messaging.

Optional MCP: Figma Dev Mode (desktop)

The runtime ships with a figma MCP server entry pointing at the Figma desktop app’s local endpoint (http://127.0.0.1:3845/mcp). It is disabled by default so opening a project does not always probe localhost.

1. In the Figma desktop app, open a design file, enter Dev Mode, and enable the desktop MCP server in the inspect panel (Figma docs).
2. Merge into ~/.config/ssscript/agent-runtime.json or the project’s .ssscript/agent.json:

{
  "mcpServers": {
    "figma": { "enabled": true }
  }
}

(You can override url if Figma changes the local port.)

3. In the app, use @figma for an agent profile aimed at design-to-code with MCP, or use @build / @general with the same MCP tools exposed.