output-surfaces

Operations of the Interactive Session API. Paths are relative to your deployment's API host.

GET /api/agent-session-api/sessions/{id}/output-surfaces/apps

List runnable output surface apps for this session.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/output-surfaces/apps/{appId}/logs

Stream stdout/stderr from the running output surface app as Server-Sent Events. Each frame is data: {"seq","ts","stream","line"}\n\n. The stream stays open until the client disconnects or the worker stops the app; closing the client connection aborts the upstream subscription on the worker.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/output-surfaces/apps/{appId}/restart

Hard-restart an output surface app (stop then spawn).

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/output-surfaces/apps/{appId}/stop

Stop an output surface app and release its port.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/output-surfaces/apps/{appId}/token/rotate

Revoke the current share token and mint a new one; updates the external URL.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/output-surfaces/remediate

Dispatch an agent remediation for a stuck output-surface app (install_failed / declaration_needed / crashed / stopped). The server reads the current SessionOutputSurfaceApp row as source of truth — status, kind, port, lastError, install metadata — and validates status matches the requested remediationKind (409 otherwise). Renders a templated prompt that includes the runtime port contract + per-kind cheatsheet, then injects it into the opencode session as a user message. The agent is instructed to edit files and then call the output_surface_rescan MCP tool — it must NOT run install or dev commands directly.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RemediateOutputSurfaceDto

POST /api/agent-session-api/sessions/{id}/output-surfaces/scan

Request the worker to rescan the workspace for runnable apps.

Authentication: bearer token (Authorization: Bearer <token>)