@amalgm/chat 0.1.2 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,98 @@
+# @amalgm/chat contributor guide
+
+Read `PURPOSE.md` before changing this package. It is the load-bearing purpose
+and axiom document. Update it in the same change whenever a public law changes.
+
+## Ownership
+
+Chat answers: “run this resolved agent in a durable conversation.”
+
+- `@amalgm/agents` owns agent identity, immutable revisions, installation, and
+  Agent Home descriptors.
+- `@amalgm/tools` owns the Toolbox catalog and immutable tool selection.
+- `@amalgm/chat` owns prepared executions, conversations, turns, the runtime
+  pump, official ACP updates, persistence, reconnect, interrupt, and usage.
+- A host owns credentials, processes, filesystems, routing, and provider
+  network effects.
+- `@amalgm/stream` and application UIs render Chat output; they do not own turn
+  lifetime or transport.
+
+There is one implementation of each concern. Git is history; do not add a
+second route, store, event grammar, payload cache, or session subsystem for
+older callers.
+
+## Working laws
+
+1. The authenticated host supplies the owner. Requests cannot choose it.
+2. Agents resolves one installation and exact immutable revision before Chat
+   executes it.
+3. Preparation may resolve control-plane facts. Start and send consume one
+   immutable prepared handle and never rediscover configuration.
+4. Prompt content and streamed output use official ACP shapes. Amalgm adds only
+   namespaced durability metadata and its separate step-usage record.
+5. One runtime pump owns provider iteration. Disconnect only removes a
+   subscriber; interrupt is the explicit provider-stop operation.
+6. Accepted input and every output update commit before execution or fanout
+   advances past them.
+7. A turn has monotonically increasing durable sequence numbers and seals once.
+   Reconnect replays after a cursor and then follows the same live turn.
+8. Restart preserves committed output and marks uncertain work interrupted
+   unless an adapter proves reattachment.
+9. Auth mode is explicit and never falls back: platform, subscription, or BYOK.
+10. Unknown usage is `null`, not fabricated zero. Billing authority is separate
+    from context telemetry.
+
+## Public composition
+
+Application code uses `Chat` or the browser-safe `@amalgm/chat/api` client.
+Node hosts use `createChatHost` from `@amalgm/chat/host`. That composed host
+owns one owner-scoped SQLite journal and one HTTP protocol under `/chat`:
+
+```text
+POST   /chat/executions
+GET    /chat/conversations
+POST   /chat/conversations
+GET    /chat/conversations/:id
+PATCH  /chat/conversations/:id
+DELETE /chat/conversations/:id
+POST   /chat/conversations/:id/resume
+POST   /chat/conversations/:id/turns
+GET    /chat/conversations/:id/turns/:turnId/events
+GET    /chat/conversations/:id/active
+POST   /chat/conversations/:id/interrupt
+```
+
+Platform egress and selected remote MCP relays are session-local auxiliary
+doors under that same `/chat` host. They are not separate Chat services.
+
+## Tree
+
+```text
+src/input/          official ACP prompt validation
+src/execution/      normalized contracts and immutable prepared handles
+src/sessions/       Chat capability, runtime pump, reconnect, interrupt
+src/conversations/  private records, transcript projection, storage ports
+src/acp/            official ACP projection
+src/events/         provider-neutral native adapter events
+src/normalizers/    provider event translators
+src/transcript/     transcript reduction
+src/usage/          context, step, turn, and billing-normalization laws
+host/adapters/      native and generic ACP effects
+host/sqlite/        WAL conversation store and durable turn journal
+host/http.js        the one HTTP/SSE protocol
+host/index.js       the one Node host composition
+```
+
+## Verification
+
+Every change must leave purpose, axioms, file tree, and behavior aligned.
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+Test invariants rather than individual symptoms: exact revision resolution,
+input-before-invocation, update-before-fanout, one pump, disconnect survival,
+cursor replay, idempotent interrupt, restart recovery, and official ACP-only
+surface output.

package/PURPOSE.md

@@ -1,115 +1,146 @@
-# @amalgm/chat — the conversation SDK
-
-Status: extraction in progress · founded 2026-08-06 · source of truth for laws:
-`amalgm-engine/runtime/scripts/chat-core/` (production until cutover)
+# @amalgm/chat — purpose and axioms
 
 ## Purpose
 
-Chat is Amalgm's central product surface: every user message, every agent
-turn, every streamed token flows through one pipeline. This repo owns that
-pipeline's **laws** — what a turn is, what events mean, what a transcript
-contains, how a send is prepared and billed — as a standalone SDK any host
-can run: the engine runtime today, the Fly workers, the channels bridge
-(email/Telegram/WhatsApp/Slack), and third-party apps tomorrow.
-
-**Membership test:** a rule belongs here if it is a law of the conversation
-itself — independent of any particular host, harness, or UI. If it spawns a
-process, opens a socket, or touches a disk, it is a host adapter behind a
-port, not a law.
-
-## The eight jobs
-
-1. **The event grammar.** One canonical vocabulary (`text.delta` …
-   `usage.final` … `done`) that every harness's native events are translated
-   into, schema-validated, and one projection of it onto the wire (the
-   ACP-shaped SSE frames). The grammar is the product's spine.
-2. **Normalization.** Per-harness translators (claude, codex, opencode,
-   cursor, pi) from native protocol events into the grammar. Pure functions;
-   every claim traceable to a recorded fixture.
-3. **Transcript truth.** One message reducer shared by both ends of the
-   wire: what the user watched streaming is byte-shape-identical to what
-   persists and reloads. Parts (text / reasoning / tool / image /
-   compaction) are the transcript's atoms.
-4. **The turn machine.** One active turn per session; the in-memory chunk
-   log (TurnStore) that makes reconnect/replay possible; the status
-   vocabulary (`streaming → cancelling → complete | cancelled | error |
-   save_failed | aborted`); the finalization order that never loses a
-   transcript silently.
-5. **The frozen contract.** A session's identity — harness, auth, model,
-   cwd, instructions, tool set — resolves once at creation and freezes.
-   Model names canonicalize through four deliberate identities (display /
-   runtime-CLI / billing / context-profile). Changing frozen fields means a
-   new session; that is what makes billing identity trustworthy.
-6. **Warm payloads.** The send path carries ids, not configuration: the full
-   launch payload is published to the machine's local store while the user
-   types (revision-hashed, 409 on mismatch), and the machine record is the
-   authority — client-supplied billing-relevant fields are deleted, never
-   trusted.
-7. **The usage law.** Token-list algebra, per-harness exactness rules,
-   the ownership fork (amalgm billing → proxy meters via egress; byok /
-   provider_auth → local logging), and the cost rules (unknown cost is
-   null, never zero).
-8. **Session-bound relays.** Amalgm-auth turns reach the billing proxy only
-   through a per-session egress token, and harness MCP traffic reaches only
-   servers frozen into that session's contract. Request paths never choose
-   an arbitrary credential or destination.
-
-## Axioms
-
-1. **The engine copy is production truth until cutover.** Laws here are
-   ported byte-exact from `amalgm-engine/runtime/scripts/chat-core/`;
-   deliberate deviations carry an `engineParity: false` marker and a reason.
-2. **One reducer, both ends of the wire.** The engine's part accumulation
-   and the browser's live rendering are the same algorithm. Divergence is a
-   bug by definition.
-3. **The wire grammar is a public contract.** Tasks, subagents, Slack
-   inbound, email inbound, and hosted apps already speak `POST /chat` + the
-   SSE grammar. Evolution is additive; a removed or reshaped frame is a
-   breaking change to systems that never imported this package.
-4. **Send carries ids, not payloads.** The machine payload store is the
-   authority; precedence is payload record > chatInput > raw body; the
-   browser is never trusted for billing-relevant fields.
-5. **Session identity freezes at creation.** The frozen-contract fingerprint
-   decides; a turn whose frozen fields drifted continues the old contract.
-6. **Storage is a choice; the meter is not.** Conversation persistence can
-   be declined (`storage: 'none'`); usage logging on amalgm billing cannot.
-7. **The host supplies effects.** Nothing in `src/` imports `node:*`, reads
-   `process.env`, or calls `Date.now()`/`Math.random()` directly — clocks,
-   crypto, stores, transports arrive as injected ports.
-8. **Contracts are byte-exact.** Error strings, header names, status
-   vocabularies, thresholds, and merge precedence match the engine to the
-   byte; exams pin them.
-9. **One runtime dependency: zod.** The event grammar's executable form is
-   the same validator the engine runs — a hand-rolled clone would make
-   parity a fiction. Nothing else gets in.
-10. **Amalgm dogfoods its own SDK.** The end state (spec §10): ChatView's
-    data layer imports nothing but `@amalgm/chat`; the engine host mounts
-    these laws instead of containing them.
-11. **Relay authority comes from the frozen contract.** Egress replaces the
-    session token with the host's proxy credential and stamps usage identity;
-    MCP relay replaces caller auth with the selected frozen server headers.
-    Neither relay accepts an upstream URL from the request.
-
-## Five surfaces
-
-| Surface | Form | Status |
-|---|---|---|
-| SDK | `@amalgm/chat` (this package's `src/`) | porting |
-| API | router factory a host mounts | chat payloads served |
-| CLI | `amalgm-chat` diagnostic commands | after SDK |
-| MCP | tool definitions + dispatch | after SDK |
-| Skill | `skills/chat/SKILL.md` | after SDK |
-
-All doors are thin: one behavior in `src/`, adapters around it.
-
-## The prior art this repo unifies
-
-- `docs/chat-sdk-spec.md` — the locked public-API spec (2026-07-13).
-- `docs/chat-internals-and-plans.md` — the canonical pipeline map.
-- `amalgm-engine/packages/chat/` — the milestone-1 client prototype.
-- The orphaned 84-exam suite (`amalgm-ui/scripts/chat-core/tests/run.js`) —
-  the richest chat test suite ever written for this codebase, currently
-  running nowhere. It is revived here.
-
-See `docs/responsibilities.md` for every duty, the knife table, the garbage
-ledger, and the known wounds.
+Amalgm Chat is the small, reliable, high-performance SDK for talking to any
+agent. It serves developers and agents building chat products: they should be
+able to create a new interface in minutes, switch among Claude Code, Codex,
+Cursor, OpenCode, Pi, and ACP agents without changing the interface's
+conversation model, and receive one trustworthy transcript and usage record.
+
+The SDK owns conversation laws. It does not own process spawning, credentials,
+cloud synchronization, workspaces, provider installation, or UI rendering.
+Those effects are supplied by a host. Amalgm's UI, API, CLI, MCP surface,
+automations, and third-party apps must all use the same public SDK.
+
+## Workstream 1 primitives
+
+- An **ACP session** is the standard agent/client interaction boundary.
+- A **turn** is one accepted user prompt and its ordered result.
+- A **model step** is one provider model invocation inside a turn.
+- A **session update** is the official ACP output shape.
+- A **step usage record** is Amalgm's immutable usage extension for one model
+  step.
+- A **turn usage record** is derived from its finalized step usage records.
+- A **raw record** is the native provider evidence retained beside a normalized
+  projection.
+- A **prompt** is an ordered list of official ACP content blocks.
+- An **execution contract** is the normalized set of choices required by one
+  future turn.
+- A **prepared execution** is an immutable execution revision plus an opaque,
+  already-resolved host binding.
+
+## Workstream 1 axioms
+
+1. ACP owns session lifecycle, prompt content, MCP server configuration,
+   permission requests, agent output, tool activity, and terminal stop reasons
+   wherever the stable protocol has those semantics.
+2. Amalgm does not copy ACP types. The public ACP boundary imports and exposes
+   the official TypeScript SDK.
+3. Amalgm extensions use ACP's `_meta` mechanism when they annotate an ACP
+   value. Rich usage remains a separate typed record because stable ACP does
+   not describe step-level token usage.
+4. Text and reasoning are ACP content chunks. Tool activity is ACP `tool_call`
+   and `tool_call_update` with `pending`, `in_progress`, `completed`, or
+   `failed` state.
+5. MCP describes remote tools and their transport. In-process tools may skip
+   MCP transport, but they expose the same content and result semantics.
+6. A model step has one stable id and at most one finalized usage record.
+   Replay, reconnect, and additional subscribers cannot add usage.
+7. Unknown token counts are `null`, never zero. Zero means the provider
+   explicitly measured zero.
+8. Turn usage is the bucket-wise sum of its steps only when every contributing
+   step reports that bucket. Otherwise that turn bucket is `null`.
+9. A cumulative provider counter becomes a step delta only against a proven
+   prior baseline. A missing baseline or counter reset remains unknown.
+10. Raw provider usage and its provenance survive normalization.
+11. Every surface consumes official ACP session updates; Chat has no second
+    event grammar.
+12. Provider-specific behavior stays in adapters. Surfaces do not branch on
+    provider names.
+13. Prompt content and execution configuration are separate. Send carries an
+    ACP prompt and a prepared execution handle, never an untrusted launch
+    payload.
+14. Preparing may discover and resolve. Starting and sending may only consume
+    an already-prepared binding.
+15. Auth and computer are selected per turn, not frozen to a conversation. A
+    running provider operation retains the execution facts it actually used.
+16. A conversation store commits accepted input and every streamed update
+    before the provider or subscribers can advance past it.
+17. Provider iteration belongs to the runtime pump, never to a client
+    subscriber. Disconnect and reconnect are cursor changes, not turn lifetime.
+18. A process restart preserves committed output and marks uncertain active
+   work interrupted; it never silently repeats external effects.
+19. Agents resolves identity and immutable revision; Chat owns the conversation
+   that executes that resolved revision. Chat never imports the Agents store.
+20. Interrupt is a provider operation followed by a durable terminal state. A
+   turn is not cancelled merely because a subscriber disconnected or a UI
+   stopped rendering it.
+21. Interrupt is idempotent for one active turn. The runtime receives at most
+   one stop request and every subscriber observes the same persisted result.
+22. A host exposes Chat by composing the public `Chat` capability and its one
+   HTTP protocol; no other turn store, pump, or transport grammar exists.
+23. A host supplies the machine-local runtime-state root. Every managed
+    provider home descends from that root and never enters portable user ground.
+24. A prepared model binding retains three distinct identities: the normalized
+    selected model, the gateway identity used for auth and usage, and the exact
+    CLI token accepted by its adapter. Surfaces select; preparation translates.
+    No identity may be reconstructed from another after preparation.
+25. Platform credentials are live host capabilities, never frozen strings. The
+    egress boundary requests one audience- and provider-scope-exact grant for
+    each HTTP operation, retries one rejected grant once after renewal, and
+    lets any remaining failure become the turn's durable failed state.
+
+## North-star proof
+
+A tiny example interface must use only the public SDK to:
+
+- start or resume a session;
+- send text and attachments;
+- expose MCP and ordinary tools;
+- handle permission requests;
+- render text, reasoning, and tool activity from official ACP shapes;
+- reconnect to the same turn; and
+- interrupt a running turn without confusing disconnect with cancellation;
+- show finalized usage for every model step and the derived turn.
+
+Changing the selected adapter may change negotiated capabilities. It may not
+require a new event grammar, transcript reducer, or UI data model.
+
+## Current truth
+
+The public SDK now has a high-level `Chat` capability, official ACP prompt
+content, a normalized prepared-execution contract, exact revision handles, and
+an official ACP output projection. Five native adapters and one generic ACP
+adapter receive the canonical prompt directly. Every native adapter has been
+exercised through the real public session path with text and an image. Claude
+Code and Pi also passed combined image, selected-MCP-tool, `ask` permission,
+tool-result, and streamed-output turns. Cursor and OpenCode have equivalent
+real tool acceptance, and the generic adapter passed text and a selected MCP
+tool against the live Cursor ACP server. Cursor accepts its native login or a
+Cursor API key; OpenCode accepts an exact catalog variant. Step-usage identity
+and aggregation are first-class laws. The public path now persists private
+conversation headers, prompts, transcript projections, terminal turns, and
+official ACP updates through an injected store. The reference SQLite adapter
+uses WAL and commits input before provider invocation and output before fanout.
+One background pump continues without subscribers; cursor replay survives a
+host restart, and uncertain running turns recover as interrupted. The shipped
+skill teaches this path.
+
+The composable Node host uses the same owner-scoped SQLite journal and exposes
+one HTTP protocol for execution preparation, conversation start/resume, turns,
+official ACP updates, cursor reconnect, and interrupt. One user database holds
+many private conversations across agent installations, while provider-native
+homes remain isolated per installation beneath a host-supplied machine-local
+runtime-state root.
+
+It is not yet the complete north star. The remote gateway/Live authority does
+not yet expose the conversation catalog and change stream; Live/R2
+synchronization is not connected; provider adapters do not yet feed the full
+step-usage ledger; every attachment form has not been exercised against every
+provider; and permission requests are not yet a first-class application
+stream. Generic ACP admission works from an immutable agent launch descriptor,
+but Amp, Gemini CLI, and Kiro were not installed for individual acceptance
+tests.
+
+The public contracts live in `docs/contracts/` and the shipped Chat skill.

package/README.md

@@ -1,66 +1,94 @@
 # @amalgm/chat
 
-The Amalgm conversation SDK: every law of the chat pipeline — the event
-grammar, harness normalization, transcript truth, the turn machine, the
-frozen session contract, warm payloads, and the usage law — extracted from
-the engine as a standalone package, plus a faithful reference host. Start
-with [PURPOSE.md](PURPOSE.md) (the charter, seven jobs, ten axioms) and
-[docs/responsibilities.md](docs/responsibilities.md) (every duty, the
-four-copies ground truth, the garbage ledger, the known wounds).
+The small, provider-agnostic SDK for agent conversations. Application code
+prepares an execution, starts or resumes a session, sends official ACP content,
+and consumes official ACP updates. Claude Code, Codex, Cursor, OpenCode, Pi,
+and generic ACP behavior stay behind host adapters.
 
-```
-src/events/       the canonical event grammar (constructors + zod schema)
-src/wire/         SSE frame projection (ACP-shaped AgentStreamEvent)
-src/transcript/   message reducer, parts, tool shape/display
-src/turns/        TurnStore, status machine, replay grammar
-src/contract/     harnesses, model identities, freeze algebra, chatInput,
-                  payload merge, input normalization
-src/warm/         warm-payload laws: revision, fingerprint, cache policies
-src/usage/        token algebra, turn finalization, ownership fork, catalog
-src/normalizers/  claude · codex · opencode · cursor · pi → the grammar
-src/api/          fetch adapters over SDK services
-src/ports.ts      the ports a host injects (clock, hash, uuid)
-host/             the reference host: adapters, tooling, orchestration,
-                  chat-server shell (effectful, imports the laws from dist)
-docs/             the chat corpus: SDK spec, runtime law, normalizer
-                  contracts + errata, internals map, warm payloads,
-                  reducer divergences
-```
+Read [AGENTS.md](AGENTS.md) for the architecture and current gaps,
+[PURPOSE.md](PURPOSE.md) for the axioms, and
+[docs/contracts/input-and-execution.md](docs/contracts/input-and-execution.md)
+for the public input path, and
+[docs/contracts/conversation-persistence.md](docs/contracts/conversation-persistence.md)
+for local conversations and durable turns.
 
-```bash
-npm install
-npm test                      # build + every exam
-```
+```ts
+import { Chat } from "@amalgm/chat";
+import {
+  SqliteConversationStore,
+  createSqliteJournalBatchPolicy,
+} from "@amalgm/chat/sqlite";
 
-## Serve the machine chat-payload API
-
-```js
-import { createChatPayloadApi } from '@amalgm/chat/api';
-import { ChatPayloadStore } from '@amalgm/chat/warm';
+const conversations = new SqliteConversationStore({
+  databasePath: "/amalgm/users/user-id/conversations/conversations.sqlite",
+});
+const chat = new Chat({
+  runtime,
+  ownerUserId: authenticatedUser.id,
+  conversations,
+  uuid,
+  clockIso,
+  sha256Hex,
+  journalBatch: createSqliteJournalBatchPolicy(),
+});
 
-const payloads = new ChatPayloadStore({
-  store: {
-    read: () => readPayloadMapFromYourHost(),
-    write: (next) => writePayloadMapFromYourHost(next),
+const execution = await chat.prepareExecution("composer", {
+  agent: {
+    adapterId: "codex",
+    installationId: "my-codex",
+    revisionId: "revision-7",
+  },
+  model: {
+    providerId: "openai",
+    modelId: "gpt-5.6-codex",
+    settings: [{ configId: "thought_level", value: "high" }],
   },
-  clockIso: () => new Date().toISOString(),
-  clockMs: () => Date.now(),
-  emit: (event) => publishStateEventFromYourHost(event),
+  auth: { mode: "subscription", bindingId: "codex-login" },
+  tools: { revisionId: null, toolIds: [] },
+  cwd: {
+    path: "/workspace/project",
+    workspaceId: null,
+    materializationRevision: null,
+  },
+  permissionMode: "ask",
+  computerId: "computer-1",
+});
+
+const session = await chat.startSession({ execution });
+const updates = await session.send({
+  execution,
+  prompt: { parts: [{ type: "text", text: "Hello" }] },
 });
 
-const api = createChatPayloadApi(payloads);
-const response = await api(new Request('http://local/chat-payloads'));
+for await (const update of updates) render(update);
+
+// Any client can reconnect from its last committed sequence.
+for await (const update of session.reconnect(updates.turnId, { afterSequence: 42 })) {
+  render(update);
+}
 ```
 
-The adapter preserves the engine's `/chat-payloads` list, lookup, and write
-contract. The host chooses persistence, clocks, and state-event delivery;
-record normalization, retention, and route responses stay in this package.
+`prepareExecution` is the control plane. A host resolves tools, auth, agent
+revision, provider/model, cwd, permissions, and placement there. Start and send
+consume the prepared revision; send does not discover configuration.
 
-Rules of the house: `src/` is pure — one runtime dependency (zod, axiom 9),
-no `node:*`, no env, no ambient clock; hosts inject effects through
-`src/ports.ts`. `host/` is effectful by design but never re-implements a
-law — it imports them. Contracts are byte-exact against the shipped engine
-(`amalgm-engine/runtime/scripts/chat-core/`, production truth until
-cutover — axiom 1); every module was differentially verified against the
-engine's own code. Tests are exams — each states a law, and a mutant must
-be convicted by at least one.
+```text
+src/input/       ordered official ACP prompt content
+src/execution/   normalized contracts, revisions, and prepared handles
+src/sessions/    public prepare/start/resume/send capability
+src/conversations/ private conversation, transcript, storage, and UI laws
+src/acp/         official ACP door and event projection
+src/events/      canonical native event grammar
+src/normalizers/ native event translators
+src/transcript/  transcript reduction
+src/usage/       step and turn usage normalization
+host/adapters/   effectful native protocol adapters
+host/sqlite/     WAL conversation store and durable turn journal
+host/http.js     the one HTTP/SSE protocol, platform egress, and MCP relay door
+```
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+```

package/dist/acp/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The canonical agent/client boundary is the official ACP SDK. Re-exporting
+ * it here gives Chat consumers one versioned door without copying the schema.
+ */
+export * from '@agentclientprotocol/sdk';
+export { AMALGM_ACP_META_KEY, toAcpSessionNotification, toAcpSessionUpdate, toAcpToolKind, type AcpProjectionContext, type AmalgmAcpMeta, } from './projection.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/acp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/acp/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,0BAA0B,CAAC;AAEzC,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC"}

package/dist/acp/index.js

@@ -0,0 +1,7 @@
+/**
+ * The canonical agent/client boundary is the official ACP SDK. Re-exporting
+ * it here gives Chat consumers one versioned door without copying the schema.
+ */
+export * from '@agentclientprotocol/sdk';
+export { AMALGM_ACP_META_KEY, toAcpSessionNotification, toAcpSessionUpdate, toAcpToolKind, } from './projection.js';
+//# sourceMappingURL=index.js.map

package/dist/acp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/acp/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,0BAA0B,CAAC;AAEzC,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,GAGd,MAAM,iBAAiB,CAAC"}

package/dist/acp/projection.d.ts

@@ -0,0 +1,30 @@
+import type { SessionNotification, SessionUpdate, ToolKind } from '@agentclientprotocol/sdk';
+import type { AmalgmEvent } from '../events/schema.js';
+export declare const AMALGM_ACP_META_KEY = "amalgm";
+export interface AcpProjectionContext {
+    conversationId?: string;
+    turnId?: string;
+    sequence?: number;
+    messageId?: string;
+}
+export interface AmalgmAcpMeta {
+    conversationId?: string;
+    turnId?: string;
+    sequence?: number;
+    native: {
+        type: string;
+        timestampMs: number;
+        raw?: unknown;
+    };
+}
+/** Map the richer native tool vocabulary into ACP's stable categories. */
+export declare function toAcpToolKind(kind: unknown): ToolKind;
+/**
+ * Project the provider-neutral native event grammar onto an official ACP session
+ * update. Events without an ACP session-update meaning return `null` instead
+ * of being disguised as a synthetic update.
+ */
+export declare function toAcpSessionUpdate(event: AmalgmEvent, context?: AcpProjectionContext): SessionUpdate | null;
+/** Wrap a projected update in ACP's official session notification shape. */
+export declare function toAcpSessionNotification(sessionId: string, event: AmalgmEvent, context?: AcpProjectionContext): SessionNotification | null;
+//# sourceMappingURL=projection.d.ts.map

package/dist/acp/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/acp/projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEb,QAAQ,EACT,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,CAAC,EAAE,OAAO,CAAC;KACf,CAAC;CACH;AAoBD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CA6BrD;AAgBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,oBAAyB,GACjC,aAAa,GAAG,IAAI,CA4EtB;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,GAAG,IAAI,CAI5B"}