@amalgm/chat 0.2.2 → 0.2.4

package/skills/chat/SKILL.md

@@ -1,97 +1,308 @@
 ---
 name: chat
-description: Build and verify provider-agnostic agent chat with the Amalgm Chat SDK. Use for chat interfaces, ACP prompt and update shapes, prepared execution, SQLite conversations, durable streams, Claude Code, Codex, Cursor, OpenCode, Pi, MCP tools, permissions, model-step usage, reconnect, or adapter conformance.
+description: Build provider-agnostic agent chat with the Chat SDK (@amalgm/chat) — use it whenever you integrate Claude Code, Codex, Cursor, OpenCode, Pi, or any ACP agent into a chat interface with durable conversations, streaming updates, reconnect, and normalized usage.
 ---
 
-# Build with Amalgm Chat
-
-Keep application code on the public SDK. Keep native behavior in host adapters.
-
-## Establish the contract
-
-Read [references/contracts.md](references/contracts.md) before changing input,
-execution preparation, sessions, adapters, or usage. In a source checkout, also
-read the repository `AGENTS.md`; it contains current architecture and known gaps.
-
-Use these package doors:
-
-- `@amalgm/chat` or `/sessions` for `Chat`, start, resume, and send;
-- `/input` for ordered ACP prompt content;
-- `/execution` for prepared execution contracts and handles;
-- `/acp` for official ACP types and session updates;
-- `/usage` for model-step usage and turn aggregation.
-- `/conversations` for owner-scoped records and UI projections;
-- `/sqlite` for the WAL-backed reference conversation store.
-
-Do not copy ACP types into application code.
-
-## Follow the user path
-
-1. Prepare while the user composes. Resolve the exact agent revision, provider-
-   scoped model, model settings, auth binding, tool revision, cwd, permission
-   mode, and computer.
-2. Start or resume with the returned `{ id, revision }` handle.
-3. Send an ordered ACP prompt with that handle.
-4. Render official ACP updates without provider branches.
-5. Treat `send()` as one background runtime pump and its returned iterable as
-   a subscriber. Reconnect by turn id and committed sequence.
-
-Never fetch models, credentials, tools, preferences, agent configuration, or a
-workspace because the user pressed Enter. A missing or stale prepared revision
-must fail explicitly.
-
-## Preserve semantics
-
-- Pass text and attachments as ACP content blocks. Never flatten or discard an
-  attachment. Translate it natively or return a typed unsupported-capability
-  result.
-- Treat model identity as `(agent revision, provider, model)`.
-- Treat auth and computer as per-turn selections. Never silently fall back to a
-  different auth mode.
-- Expose ordinary tools and MCP tools through one MCP-shaped capability model.
-  The resolved selection is complete; never add an ambient MCP server.
-- Use the five native adapters for Claude Code, Codex, Cursor, OpenCode, and Pi.
-  Register every other compliant agent through the generic `acp` adapter and
-  an immutable launch descriptor; do not add product-name branches for Amp,
-  Gemini CLI, Kiro, or later ACP agents.
-- Require every adapter to apply an input exactly or throw a typed unsupported
-  error before prompting. Capability negotiation is validation, not fallback.
-- Render `agent_message_chunk`, `agent_thought_chunk`, `tool_call`, and
-  `tool_call_update`. Use ACP tool states.
-- Use `@amalgm/stream` for rendering only; it is not the durable journal.
-- Persist accepted input before provider invocation. Commit every update before
-  fanout, seal terminal state once, and recover uncertain running turns as
-  interrupted after restart.
-- Use bounded SQLite batches for content deltas. Tool, terminal, permission,
-  warning, and other control updates flush immediately.
-- Never sync a live SQLite file. Live synchronizes logical conversation rows,
-  sealed turns, update batches, messages, and provider checkpoints.
-
-## Normalize usage honestly
-
-Create one finalized usage record per provider model invocation. Keep input,
-output, cache-read, and cache-write tokens nullable. Derive turn usage from its
-steps. Preserve the raw provider record. Never use ACP context fullness as a
-billing ledger or turn missing values into zero.
-
-## Verify through real sessions
-
-Test laws with fixtures, then start a real session through `Chat`; do not stop at
-calling an adapter helper. For every claimed adapter, verify start/resume, text
-and supported attachments, tools, permissions, normalized updates, terminal
-state, and usage. Record unsupported capabilities literally.
-
-Use the adapter capability matrix and generic ACP launch shape in
-[references/contracts.md](references/contracts.md). A generic ACP conformance
-run does not prove that every named ACP product is installed or authenticated;
-record each product acceptance separately.
-
-Run:
+# Chat
+
+Chat is a provider-agnostic SDK for building agent conversations. Your
+application prepares an execution (which agent, model, auth, tools, and
+workspace), starts or resumes a session, sends prompts as official
+[Agent Client Protocol (ACP)](https://agentclientprotocol.com) content, and
+renders official ACP updates — the same code path for Claude Code, Codex,
+Cursor, OpenCode, Pi, and any compliant ACP agent. Every turn is journaled to
+SQLite before it streams, so clients can disconnect, reconnect from their last
+committed sequence, and recover cleanly after a restart. Token usage is
+normalized per model step so you always know what a turn actually consumed.
+
+## Installation
 
 ```bash
-npm test
-npm pack --dry-run
+npm install @amalgm/chat
+```
+
+Chat requires Node 20 or later. The bundled SQLite conversation store uses
+`better-sqlite3`, a native module that compiles during install on platforms
+without a prebuilt binary.
+
+## Quickstart
+
+The fastest path is the composed host: it wires the native runtime, the SQLite
+conversation store, and crash recovery for you.
+
+```ts
+import { createChatHost } from "@amalgm/chat/host";
+
+const host = await createChatHost({
+  ownerUserId: "user-1",
+  databasePath: "./conversations.sqlite",
+});
+
+// 1. Prepare the execution while the user is composing.
+const execution = await host.chat.prepareExecution("composer", {
+  agent: { adapterId: "claude_code", installationId: "default", revisionId: "rev-1" },
+  model: { providerId: "anthropic", modelId: "sonnet", settings: [] },
+  auth: { mode: "subscription", bindingId: "default" },
+  tools: { revisionId: null, toolIds: [] },
+  cwd: { path: process.cwd(), workspaceId: null, materializationRevision: null },
+  permissionMode: "ask",
+  computerId: "computer-1",
+});
+
+// 2. Start a session and send an ordered ACP prompt.
+const session = await host.chat.startSession({ execution });
+const stream = await session.send({
+  execution,
+  prompt: { parts: [{ type: "text", text: "Summarize this repository." }] },
+});
+
+// 3. Render official ACP updates — no provider branches.
+for await (const update of stream) {
+  if (update.sessionUpdate === "agent_message_chunk" && update.content.type === "text") {
+    process.stdout.write(update.content.text);
+  }
+}
+
+await host.close();
+```
+
+`createChatHost` also accepts your own `conversations` store or `runtime` if
+you need to replace either half, and it returns `recoveredTurns` — the turns
+that were still running when the previous process died.
+
+## Core concepts
+
+### Prepared execution
+
+Everything a turn needs is resolved ahead of time into an `ExecutionContract`:
+the exact agent revision, the provider-scoped model and its settings, the auth
+binding, the selected tool set, the working directory, the permission mode
+(`"ask"` or `"full_access"`), and the computer that runs it. Call
+`chat.prepareExecution(id, contract)` while the user is composing; it returns a
+small `ExecutionHandle` of `{ id, revision }`. Any changed field produces a new
+revision, and preparing the same contract twice is a no-op.
+
+`startSession` and `send` only consume a prepared handle — they never fetch
+models, credentials, tools, or workspaces themselves. This keeps pressing Enter
+instant, and it means a stale handle fails explicitly with
+`EXECUTION_REVISION_MISMATCH` instead of silently re-resolving to something the
+user did not pick. The full contract shape is in
+[references/contracts.md](references/contracts.md).
+
+### Sessions, turns, and updates
+
+A session is one durable conversation. Each `send()` creates a turn: the
+accepted prompt is persisted first, then one background pump runs the provider
+and commits every update to the journal before fanning it out to subscribers.
+The iterable that `send()` returns is just a subscriber — dropping it does not
+stop the turn, and any number of clients can attach to the same live turn.
+
+Updates are official ACP `SessionUpdate` values: `agent_message_chunk` (text),
+`agent_thought_chunk` (reasoning), `tool_call` and `tool_call_update` (tool
+identity, input, and state), plus ACP permission requests and stop reasons.
+Every update carries `_meta.amalgm.{conversationId, turnId, sequence}` so you
+can resume precisely, and the raw native event is preserved under
+`_meta.amalgm.native`. Render the ACP grammar and your UI works for every
+supported agent.
+
+### Durable conversations
+
+Conversations, messages, turns, and update journals live in an owner-scoped
+store. Production hosts should use `SqliteConversationStore` from
+`@amalgm/chat/sqlite` (WAL-backed) together with
+`createSqliteJournalBatchPolicy()`, which batches high-frequency content deltas
+while flushing tool, permission, and terminal updates immediately. A turn ends
+in exactly one status: `completed`, `failed`, `cancelled`, or `interrupted`.
+After a process restart, `chat.recoverInterruptedTurns()` (called automatically
+by `createChatHost`) marks turns that were still `running` as `interrupted` —
+their committed updates remain replayable, and nothing is silently reported as
+completed.
+
+### Usage
+
+One turn can contain many model steps. Each step records nullable
+`inputTokens`, `outputTokens`, `cacheReadTokens`, and `cacheWriteTokens`, plus
+the model identity, the source and exactness of the numbers, and the raw
+provider record as evidence. Turn usage is aggregated from steps only, and a
+bucket stays `null` when any contributing step is unknown — missing data is
+never turned into zero. The `@amalgm/chat/usage` entry point exports the
+normalization helpers (`normalizeUsage`, `aggregateTurnUsage`,
+`finalizeTurnUsage`) and a model catalog with `calculateCost`.
+
+## Working with sessions
+
+### Send text and attachments
+
+Prompts are ordered lists of ACP content blocks. Attachments travel as ACP
+`image`, `audio`, `resource`, or `resource_link` blocks with bytes or
+references already prepared — they are delivered to the agent natively, never
+flattened into text. `promptFromText` from `@amalgm/chat/input` builds the
+common case:
+
+```ts
+import { promptFromText } from "@amalgm/chat/input";
+
+const stream = await session.send({
+  execution,
+  prompt: promptFromText("What does this diagram show?", [
+    { type: "image", mimeType: "image/png", data: base64Png },
+  ]),
+});
 ```
 
-Do not claim parity from one successful provider. Record current limitations in
-`PURPOSE.md` or the owning contract document.
+If the selected agent cannot accept a block, the send fails up front with a
+typed `UNSUPPORTED_PROMPT_PART` error — no part of your input is silently
+dropped.
+
+### Reconnect after a disconnect
+
+Track the highest `_meta.amalgm.sequence` you have rendered. After a network
+drop or page reload, reattach to the same turn from that cursor:
+
+```ts
+for await (const update of session.reconnect(turnId, { afterSequence: 42 })) {
+  render(update);
+}
+```
+
+Reconnect replays the committed journal past your cursor and then continues
+live if the turn is still running. `stream.completion` resolves to the sealed
+turn record when you need the final status, and `session.interrupt()` requests
+a stop for the active turn.
+
+### Resume a stored conversation
+
+```ts
+const session = await chat.resumeSession({ sessionId, execution });
+// or, over the composed host's store, without re-preparing:
+const { session: resumed, latestTurn } = await chat.resumeStoredSession(sessionId);
+```
+
+Conversation identity survives changing the model, auth mode, or computer
+between turns — the adapter transparently opens a new native provider session
+when it must. Sessions also expose `inspect()`, `messages()`,
+`updateTitle(title)`, and `close()`; the `Chat` instance adds
+`listConversations()`, `archiveSession(id)`, `activeTurn(id)`,
+`latestTurn(id)`, and `replayTurn(id, turnId, afterSequence)`.
+
+## Supported agents
+
+Five agents have native adapters; every other compliant ACP agent registers
+through the generic `acp` adapter with an immutable launch descriptor — there
+are no product-name branches to wait for.
+
+| Adapter id | Agent | Auth modes | Model settings |
+| --- | --- | --- | --- |
+| `claude_code` | Claude Code | platform, subscription, BYOK | reasoning, speed |
+| `codex` | Codex | platform, subscription, BYOK | reasoning, speed |
+| `cursor` | Cursor | subscription, BYOK API key | the advertised model's exact parameters |
+| `opencode` | OpenCode | platform, subscription, BYOK | exact model-catalog variant |
+| `pi` | Pi | platform, subscription, BYOK | reasoning |
+| `acp` | any ACP agent | declared by the revision | negotiated ACP config options |
+
+Ordinary tools and MCP tools flow through one MCP-shaped capability model: the
+prepared tool selection is complete, and no adapter adds an ambient MCP server
+behind your back. Capability negotiation is validation — an adapter applies
+your input exactly or throws a typed unsupported error before prompting. The
+generic ACP launch shape and the full capability matrix are in
+[references/contracts.md](references/contracts.md).
+
+Use the official ACP `McpServer` union from `@amalgm/chat/execution` for every
+prepared capability. Tools, Agents, Chat, and other platform products are
+selected MCP servers, not adapter-specific built-ins. Compose machine, project,
+and exact Agent-revision instructions during preparation; adapters consume the
+prepared bundle through a genuine native system/developer field. ACP v1 has no
+system-prompt field, so require the advertised `amalgm.dev`
+`sessionInstructions` extension for non-empty instructions. Never prepend
+instructions to `session/prompt` content.
+
+## The HTTP surface
+
+The host package ships one HTTP/SSE handler over the same capability, for
+serving Chat to browser or remote clients:
+
+```ts
+import { createServer } from "node:http";
+import { createChatHost } from "@amalgm/chat/host";
+
+const host = await createChatHost({ ownerUserId: "user-1", databasePath: "./chat.sqlite" });
+createServer(async (request, response) => {
+  if (await host.handleHttp(request, response)) return;
+  response.writeHead(404).end();
+}).listen(8080);
+```
+
+Routes are mounted under `/chat` by default (configurable via
+`createChatHttpHandler({ chat, prefix })`):
+
+| Method and path | Purpose |
+| --- | --- |
+| `POST /chat/executions` | prepare an execution (`{ id, execution }` → handle) |
+| `GET /chat/conversations` | list conversations |
+| `POST /chat/conversations` | start a session |
+| `GET /chat/conversations/:id` | conversation record, messages, latest turn |
+| `POST /chat/conversations/:id/resume` | resume (with or without a new handle) |
+| `POST /chat/conversations/:id/turns` | send a prompt; streams SSE updates |
+| `GET /chat/conversations/:id/turns/:turnId/events` | reconnect from `afterSequence` or `Last-Event-ID` |
+| `POST /chat/conversations/:id/interrupt` | interrupt the active turn |
+| `GET /chat/conversations/:id/active` | the running turn, if any |
+| `PATCH /chat/conversations/:id` | rename, or mark seen with `{ newMessages: false }` |
+| `DELETE /chat/conversations/:id` | archive |
+
+Error responses carry `{ error: { code, message } }` with the same codes the
+SDK throws.
+
+## Error handling
+
+Chat fails loudly with typed errors; every error object carries a stable
+`code` string.
+
+| Code | Meaning |
+| --- | --- |
+| `INVALID_EXECUTION_CONTRACT` | a contract field is missing or malformed |
+| `EXECUTION_NOT_PREPARED` | the handle's id was never prepared on this host |
+| `EXECUTION_REVISION_MISMATCH` | the handle is stale; re-prepare and retry |
+| `INVALID_PROMPT` | the prompt is empty or contains an invalid block |
+| `UNSUPPORTED_PROMPT_PART` | the selected agent cannot accept a content block |
+| `UNSUPPORTED_EXECUTION_INPUT` | the agent cannot apply part of the contract |
+| `SESSION_NOT_FOUND` / `SESSION_ALREADY_EXISTS` | session id problems |
+| `SESSION_BUSY` | the session already has a running turn |
+| `SESSION_AGENT_MISMATCH` | the new handle targets a different agent installation |
+| `SUBSCRIBER_BACKPRESSURE` | one slow subscriber overflowed its buffer and was disconnected (the turn keeps running) |
+| `INTERRUPT_UNSUPPORTED` | the adapter cannot stop this turn |
+
+A failed or interrupted turn surfaces on the stream as a `TurnStreamError`
+whose `turn` property is the sealed record:
+
+```ts
+import { TurnStreamError } from "@amalgm/chat";
+
+try {
+  for await (const update of stream) render(update);
+} catch (error) {
+  if (error instanceof TurnStreamError) showTurnFailure(error.code, error.turn);
+  else throw error;
+}
+```
+
+The sealed turn is still stored, so a reconnecting client sees the same
+terminal state.
+
+## Package entry points
+
+| Entry point | Contents |
+| --- | --- |
+| `@amalgm/chat` | `Chat`, `ChatSession`, `ChatTurnStream`, session errors |
+| `@amalgm/chat/sessions` | the same session capability, plus option types |
+| `@amalgm/chat/input` | `PromptInput`, `promptFromText`, `normalizePrompt` |
+| `@amalgm/chat/execution` | `ExecutionContract`, handles, revisions, contract errors |
+| `@amalgm/chat/acp` | the official ACP SDK re-exported, plus `_meta` projection types |
+| `@amalgm/chat/usage` | step and turn usage normalization, model catalog, `calculateCost` |
+| `@amalgm/chat/conversations` | conversation, turn, and message record types |
+| `@amalgm/chat/sqlite` | `SqliteConversationStore`, `createSqliteJournalBatchPolicy` |
+| `@amalgm/chat/host` | `createChatHost`, `NativeChatRuntime`, `createChatHttpHandler` |
+
+Import ACP types from `@amalgm/chat/acp` rather than copying them into your
+application; the SDK versions that boundary for you. Advanced entry points
+(`/events`, `/transcript`, `/normalizers`, `/api`) expose the native event
+grammar and transcript reduction for hosts that build custom runtimes.

package/skills/chat/references/contracts.md

@@ -1,33 +1,40 @@
-# Chat SDK contract
+# Contract reference
 
-Load this reference when building a chat surface or changing a provider adapter.
+The exact shapes Chat accepts and emits. Everything here is importable from
+the package entry points — never copy these types into application code.
 
 ## Prompt
 
 ```ts
+import type { PromptInput } from "@amalgm/chat/input";
+
 type PromptInput = {
   parts: ContentBlock[]; // official ACP ContentBlock
 };
 ```
 
 The list is non-empty and ordered. Attachments are ACP `image`, `audio`,
-`resource`, or `resource_link` blocks. The host must prepare bytes or references
-before send.
+`resource`, or `resource_link` blocks; prepare bytes or references before
+calling `send`. Attachments are delivered natively — if the selected agent
+cannot accept a block, the send fails with `UNSUPPORTED_PROMPT_PART` instead
+of flattening or dropping it.
 
-## Prepared execution
+## Execution contract
 
 ```ts
+import type { ExecutionContract } from "@amalgm/chat/execution";
+
 type ExecutionContract = {
   agent: { adapterId: string; installationId: string; revisionId: string };
   model: {
     providerId: string;
     modelId: string;
-    settings: SetSessionConfigOptionRequest[];
+    settings: ModelSetting[]; // ACP SetSessionConfigOptionRequest, minus session identity
   };
   auth: { mode: "platform" | "subscription" | "byok"; bindingId: string };
   tools: { revisionId: string | null; toolIds: string[] };
   cwd: {
-    path: string;
+    path: string; // absolute
     workspaceId: string | null;
     materializationRevision: string | null;
   };
@@ -36,9 +43,13 @@ type ExecutionContract = {
 };
 ```
 
-Preparation resolves this to an opaque host binding and returns an
-`ExecutionHandle` containing only `id` and `revision`. Any changed field creates
-a new revision. Start and send consume a prepared handle; they never prepare.
+`chat.prepareExecution(id, contract)` resolves this to an opaque host binding
+and returns an `ExecutionHandle` containing only `{ id, revision }`. Any
+changed field creates a new revision. `startSession` and `send` consume a
+prepared handle; they never prepare, discover, or silently re-resolve. Model
+identity is always the triple `(agent revision, provider, model)`, and auth
+and computer are per-turn selections — Chat never falls back to a different
+auth mode on its own.
 
 ## Session path
 
@@ -46,38 +57,34 @@ a new revision. Start and send consume a prepared handle; they never prepare.
 const execution = await chat.prepareExecution("composer", contract);
 const session = await chat.startSession({ execution });
 
-for await (const update of await session.send({
+const stream = await session.send({
   execution,
   prompt: { parts: [{ type: "text", text: "Hello" }] },
-})) {
-  render(update);
-}
+});
+for await (const update of stream) render(update);
 ```
 
-Construct `Chat` with the authenticated `ownerUserId`, a
-`ConversationStorePort`, and a host clock. Production hosts should use
-`SqliteConversationStore` from `@amalgm/chat/sqlite` plus
-`createSqliteJournalBatchPolicy()`.
-
-`send()` begins one background provider pump after the input transaction
-commits. Iterating its result subscribes to the durable turn; it does not own
-provider execution. Reconnect with `session.reconnect(turnId, {
-afterSequence })`. Every yielded update carries
-`_meta.amalgm.{conversationId,turnId,sequence}`.
+`send()` starts one background provider pump after the input transaction
+commits. Iterating the returned `ChatTurnStream` subscribes to the durable
+turn; it does not own provider execution, and `stream.completion` resolves to
+the sealed turn. Reconnect with `session.reconnect(turnId, { afterSequence })`.
+Every yielded update carries `_meta.amalgm.{conversationId, turnId, sequence}`.
 
-On startup call `chat.recoverInterruptedTurns()` before admitting new work.
-Committed updates remain replayable. Running turns become `interrupted` unless
-an adapter later supplies a proven reattachment path.
+Use `chat.resumeSession({ sessionId, execution })` for an existing
+conversation, or `chat.resumeStoredSession(sessionId)` to reuse its stored
+execution. Conversation identity survives an explicit auth or computer change
+between turns; the adapter may open a different native provider session
+underneath.
 
-Use `chat.resumeSession({ sessionId, execution })` for an existing conversation.
-The conversation identity survives an explicit auth or computer change between
-turns. The adapter may need a different native provider session.
+On process startup, call `chat.recoverInterruptedTurns()` before admitting new
+work (`createChatHost` does this for you). Committed updates remain
+replayable; turns that were `running` become `interrupted`.
 
-## Adapter admission and exact inputs
+## Adapters and exact inputs
 
 The adapter ids are `claude_code`, `codex`, `cursor`, `opencode`, `pi`, and
-`acp`. The first five are native adapters. The final path admits any
-compliant ACP agent from its resolved immutable revision:
+`acp`. The first five are native adapters; the `acp` adapter admits any
+compliant ACP agent from an immutable launch descriptor:
 
 ```ts
 acpLaunch: {
@@ -103,29 +110,48 @@ acpLaunch: {
 | Pi | platform, subscription, BYOK | reasoning only |
 | ACP | revision-declared modes | negotiated ACP config options |
 
-Every path takes the complete selected tool set (no ambient MCP server), an
-absolute prepared cwd, `ask` or `full_access`,
-an immutable agent revision, a provider-scoped model, and an execution
-computer. Optional prompt/MCP/config capabilities are negotiated for ACP.
-Anything that cannot be applied throws `UNSUPPORTED_EXECUTION_INPUT` or
-`UNSUPPORTED_PROMPT_PART`; no selected input disappears.
+Every adapter receives the complete selected tool set (no ambient MCP server),
+an absolute prepared cwd, `ask` or `full_access`, an immutable agent revision,
+a provider-scoped model, and an execution computer. Optional prompt, MCP, and
+config capabilities are negotiated for generic ACP agents. Anything an adapter
+cannot apply throws `UNSUPPORTED_EXECUTION_INPUT` or `UNSUPPORTED_PROMPT_PART`
+before prompting — no selected input disappears.
+
+## Capabilities and instructions
+
+Import `McpServer` from `@amalgm/chat/execution`; it is the official
+`@agentclientprotocol/sdk` union. A host resolves the immutable Toolbox
+selection to the complete `McpServer[]` during preparation. Amalgm Tools,
+Agents, and Chat use this same selected-server path when exposed as platform
+tools. Product `_meta` is descriptive and never grants a capability.
+
+The host also resolves one instruction bundle from machine, project, and exact
+Agent-revision inputs. Native adapters use the bundle through a real
+system/developer-instruction field. For ACP agents, non-empty instructions
+require `agentCapabilities._meta["amalgm.dev"].sessionInstructions === true`;
+Chat then supplies the bundle under the same namespace on `session/new`,
+`session/load`, or `session/resume`. Instructions never become user
+`session/prompt` blocks.
 
 ## Output
 
 ACP is the public update grammar:
 
-- `agent_message_chunk`: text;
-- `agent_thought_chunk`: reasoning;
-- `tool_call`: tool identity, input, and initial state;
-- `tool_call_update`: input/result deltas and state;
+- `agent_message_chunk` — assistant text;
+- `agent_thought_chunk` — reasoning;
+- `tool_call` — tool identity, input, and initial state;
+- `tool_call_update` — input/result deltas and ACP tool states;
 - ACP permission requests and stop reasons.
 
-Amalgm extensions retain durable ids/cursors, raw events, ownership, and richer
-usage without changing the ACP meaning.
+The `_meta.amalgm` extension adds durable ids and cursors, the raw native
+event, and richer usage without changing the ACP meaning of any update. Render
+the ACP grammar and every supported agent works without provider branches.
 
 ## Usage
 
 One turn can contain many model steps. Each step reports nullable
 `inputTokens`, `outputTokens`, `cacheReadTokens`, and `cacheWriteTokens`, plus
-source, exactness, model identity, and raw evidence. Aggregate the turn from
-steps only. A bucket remains `null` when any contributing step is unknown.
+source, exactness, model identity, and the raw provider record as evidence.
+Turn usage is aggregated from steps only, and a bucket remains `null` when any
+contributing step is unknown — Chat never converts missing values to zero, and
+ACP context-fullness signals are not a billing ledger.