Chat package handoff

Ownership

packages/chat owns framework-neutral application definitions, the closed component manifest, component props validation, and the semantic fallback API from ADR-0003/ADR-0007. ChatDefinition.chat is the upstream ChatConfig; do not mirror its fields or add a controller.

Read first

Conversation boundary

createChatSession may wrap only the upstream adapter boundary. It must not consume streams, mutate controller state, execute tools, or persist messages. Route precedence is declaration order; transition targets come from the active state definition. Every renderer creates a fresh session per definition mount.

Conversation declarations compile to @agentskit/statechart. Use its published definition, immutable instance, and transition contracts; do not recreate generic state validation or transition assignment locally. This package retains only application route matching, adapter fallback, actions, traces, decision replay, and the existing session projection.

resumeChatSession persists only the application envelope described by ADR-0011. Canonical messages must remain in upstream ChatMemory. Validate stored snapshots before hydration, bind them to session + definition revision, and keep terminal confirmations terminal.

Deterministic route callbacks receive stable session/message identity per ADR-0018. Component-producing routes derive instance IDs from the message identity; never use definition-global counters or constant IDs for repeatable interactive routes.

Component boundary

Model or route frames are untrusted. Resolve them against definition.components; unknown or invalid frames are inert. Selection events express intent only and never execute an action. Standard AgentsKit UIElement types remain upstream.

The standard application catalog is defined in src/catalog.ts. Every entry must ship schema, declared events, accessibility, capabilities, fallback, shared fixture, seven native presentations, and a regenerated parity report. Generic interactions remain intent-only; do not execute navigation, downloads, approvals, or tools in the catalog contract.

Actionable choices use createActionConfirmation and the released upstream ChatReturn.proposeToolCall. Never validate or execute tools locally. Confirmation handles bind application-session metadata; authentication and durable audit remain outside this package.

Authorization uses createCapabilityPolicy + withActionPolicy. Trusted context must come from a host closure, never a protocol frame or message. AgentsKit owns enforcement through authorizeToolCall; this package owns only capability composition and trace projection.

Ask service boundary

Docs, Registry, and Playbook must consume createAskAdapter and createAskSessionMemory. Do not recreate the Ask schema, NDJSON decoder, fetch loop, citation projection, or browser message store in a host. Host-specific visual tools may use projectTool, but the returned component frame remains runtime validated. Use a new canonical storage key and pass prior formats through legacyKeys.

Deterministic answer boundary

createDeterministicAnswerResolver performs only normalized whole-query equality over a bounded artifact and resolves an explicit ambiguous choice by entry ID. Do not add fuzzy, prefix, semantic, embedding, or model matching. createDeterministicAnswerAdapter may decide locally or delegate to an injected upstream AdapterFactory; it preserves streaming latency and cancellation while observing bounded output only to attach the unified backend envelope. Corrupt artifacts escalate without crashing startup, stale artifacts escalate, fallback.mode is enforced, and missing fallback becomes an offline response. The public contract is accepted by ADR-0024 with HITL approval recorded on 2026-07-13.

Checks

pnpm --filter @agentskit/chat lint
pnpm --filter @agentskit/chat test

Chat package handoff

Chat package handoff

Ownership

Read first

Conversation boundary

Component boundary

Ask service boundary

Deterministic answer boundary

Checks

On this page