next-tjwater-agent/docs/agent-ui-protocol.md

Agent UI Protocol

Controlled content and display commands

answer-ui@1 describes retained answer content rendered by the frontend component catalog. Stable block_id, process/final phase and standalone [[ui:block_id]] anchors govern placement. Publishing or reading answer content never replays a map action.

Map, chart, overlay and SCADA display use a single flat command object: {action, ...typed fields}. Chat calls present_view({command, reason?}) with an optional concise purpose; tasks call publish_task_presentation({request_id, command}); Dev JSONL wraps the same command in {record_type:"presentation", command}. No executable JS, JSX, HTML, CSS, URL or arbitrary request is accepted. The former chat name/params action shape and frontend-action@1 are rejected; no migration adapter is provided.

The ten commands are locate_features, zoom_to_map, highlight_features, clear_highlights, open_chart, close_chart, set_overlay, clear_overlay, render_scada_analysis and clear_scada_analysis. Historical data must first be queried through an authorized MCP tool and then supplied to open_chart. Command definitions, including bounded GeoJSON, charts and target lists, are generated from the supply frontend's src/features/agent/presentation/command-schema.ts; the exported src/frontendAction/command.ts is also used with OpenCode's native Zod instance. Regenerate using node scripts/export-view-command-contract.mjs in the supply frontend; add --check to verify copies.

Chat transport and receipts

The frontend advertises frontend-action@2, and discovers supported actions through GET /api/v1/frontend-action-registry, schema_version frontend-action-registry@2.

Generation uses POST /api/v1/responses. A tjwater.frontend_action SSE event carries response_id, sequence_number and data containing:

{
  "version": "frontend-action@2",
  "actionId": "host-action-id",
  "toolCallId": "native-call-id",
  "sessionId": "session-id",
  "command": {"action":"highlight_features","layer":"pipes","feature_ids":["533793"],"effect":"pulse"},
  "risk": "view",
  "replayPolicy": "never",
  "issuedAt": 1710000000000,
  "expiresAt": 1710000015000
}

Session subscriptions carry the same data in a frontend_action event. The browser validates the active session and command, executes in stream order, and submits frontend-action-result@2 through POST /api/v1/frontend-actions/:action_id/result, with the scoped session header. Results contain actionId, status, output or error, and completedAt. Status is succeeded, failed, rejected, cancelled or expired. Locate/highlight output reports actual matched and missing IDs; publishing a tool call is not proof of display success. Duplicate delivery reuses the terminal receipt, not the map side effect. Session switches cancel running and queued work; expiry prevents later execution.

Task and preview lifetimes

Task display is asynchronous: Server verifies the task/run/generation, active lease, source session, evidence ownership and idempotency key before recording operational.presentation.requested. A recorded result does not mean a browser displayed it; tasks progress without any connected browser. New subscriptions take a fresh event baseline and do not replay historical display commands.

Task open_chart requires persisted evidence references. Task set_overlay can omit data; Server resolves immutable evidence into bounded GeoJSON. Supplied data must match that resolution and never overrides the stored snapshot. Chat and Dev supply resolved data for structural validation before rendering.

Chat, task following and Dev previews share the frontend command dispatcher but own independent map sources, SCADA layers and chart state. Clearing or switching one owner does not clear another. Dev JSONL is an explicit local preview/import/export container, not an alternative online business protocol. Plain data records and ui_block records do not execute embedded actions. The earlier agent-ui@1 registry has no active tool mappings and is not an action entry point.

Running and waiting input delivery

Text output has separate append, flush and close operations. Smoothing releases English words and bounded Chinese chunks at the configured interval (20 ms by default). A short tail that cannot form a regular chunk waits at most 100 ms after input starts or the last visible release; this deadline never dumps a whole queued paragraph. Text segment completion, tool transitions and permission/question waits drain preceding text at the same pace before the next event. Publishing present_answer also drains preceding text but leaves output open for later narration. Only terminal cleanup closes output. Cancellation immediately drains already-received text before native interruption; it does not manufacture a final answer. The first-token log records emission from this buffer, rather than input admission into it.

Ordinary chat and task collaboration share one final-answer handoff. A completed final_answer is held until all observed tools are terminal and the inbox close guard permits completion. The host then emits tjwater.final_answer exactly once before interrupting further native rewrites and waiting for native idle. Plain-text and component answers follow the same rule. Tool arguments are not published as partial JSON; answer content and component references must pass their existing validation before publication. Background task_execution keeps its native idle and Server completion checks; a chat answer never completes a business task.

Running text additions use POST /api/v1/responses with stream=false, conversation, tjwater.delivery="steer" | "queue" and a stable tjwater.input_id. HTTP 202/tjwater.response_input is an inbox receipt, not execution completion. The existing SSE connection carries tjwater.user_input pending/delivered states; delivered means the native inbox took the input. GET /api/v1/session/:session_id/inputs lists pending input; PATCH of its /:input_id delivery can change its mode before processing and returns 409 afterward. Restored session streams retain these semantics.

A pending host question or failed continuation does not disable input admission. With no active host turn, steer/queue messages enter the native inbox with resume=false and remain available for the next owned continuation. This does not answer a host question or launch inference. A lost delivery acknowledgement can be reconciled only after verifying both native consumption and completed related output. HTTP 409 with code RESPONSE_FINISHED means the input was rejected before admission because the turn has ended; the client may refresh state and send it as a new response. Other failures do not authorize automatic resubmission.