Hosted UI and Event Replay
KsADK 0.8.3 separates Hosted UI transport, interactive presentation,
and runtime audit. OpenAI Responses remains the compatibility baseline, AG-UI
is an optional transport, A2UI represents structured activities, and
RuntimeEvent is the sole persistence and replay boundary. UI evolution does
not change the original model-call protocol.
Release boundary
This page describes interfaces and boundaries in the 0.8.3 source. It does not claim that npm/PyPI publication is complete. A real hosted deployment must still validate its gateway, authentication, runner, database, and provider credentials.
Protocol Selection
| Layer | Role | Behavior when unavailable |
|---|---|---|
| OpenAI Responses | established /v1/responses and /v1/chat/completions request/response semantics | always available as the compatibility baseline |
| AG-UI | optional streaming transport between Hosted UI and runtime | fall back to Responses when the capability is not negotiated |
| A2UI | structured activities/components and user actions | does not replace model, tool, or approval policy |
| RuntimeEvent v2 | canonical session events, state, audit, and replay record | unknown event types cannot bypass conformance validation |
AG-UI/A2UI is not a second model API. A client selects it only after Hosted bootstrap advertises the capability; existing Responses clients can remain unchanged.
Interaction State
The state of approvals, forms, and other actionable activities must be projected from persisted RuntimeEvents, rather than only browser memory. When a user submits an action, the runtime must validate actor, pending state, tool receipt, and policy again; the button itself is not authorization.
After a reload, the UI should reload session history and project a pending interaction. A completed approval must not execute again. If it behaves otherwise, replay the event order and terminal state first, then inspect the runner's native interrupt/resume capability.
Read-Only Replay
The two command entry points are equivalent:
ksadk replay <session-id>
agentengine replay <session-id> --after-seq-id 120 --before-seq-id 260 --format jsonThe command reads the new event model from RuntimeEventStore. Its shared
parser projects text, reasoning, tools, artifacts, and run status; known but
unclassified events (including A2UI/A2A extensions) remain ordered extras. It
does not:
- call a model provider;
- run a tool, MCP, sandbox, or approval action again;
- guess-convert legacy
assistant_messageSessionEvent records to RuntimeEvent.
--after-seq-id is exclusive and --before-seq-id is an exclusive upper
bound. Read the full session first, then reduce to the cursors around the
failure to distinguish a missing event, an unprojected event, and an action
that was rejected or consumed.
Migration and Triage Order
- Keep the existing Responses call and first verify that session and RuntimeEvent persistence work.
- Read Hosted bootstrap capabilities; only enable AG-UI/A2UI after negotiation succeeds.
- For reloads, disconnects, or duplicate approvals, use
ksadk replayto locate the event cursor and terminal state. - For LangGraph/ADK interrupt or resume, then validate the framework-native checkpoint configuration. New integrations must not depend on legacy LangChain continuity.
For browser debugging, see Local Web UI. For session and checkpoint semantics, see Sessions, Runtime, and Files.