@amalgm/chat 0.1.0

package/dist/warm/revision.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Revision hash + client publish-dedupe policy — the pure laws of
+ * `amalgm-ui/lib/chat/machinePayloadClient.ts` (:7-51 and the decision
+ * sequence of `publishMachineChatPayload`, :61-71).
+ *
+ * Design doc: docs/warm-payloads.md ("Revision law").
+ *
+ * Note: the revision is NOT sha256 — the UI uses a djb2-xor string hash
+ * rendered base-36 (`machinePayloadClient.ts:41-47`), ported byte-exact
+ * below, so no Sha256HexPort is needed here. The maps themselves
+ * (in-flight promises, confirmed writes) and the fetch are host state;
+ * this module exports only the shapes, constants, and decision laws.
+ */
+import type { ChatViewPayload } from './payload.js';
+/** Store record shape as the client sees it — `machinePayloadClient.ts:7-12`. */
+export type MachineChatPayloadRecord = {
+    id: string;
+    revision: string;
+    payload: ChatViewPayload;
+    updatedAt?: string;
+};
+/** In-flight write memory, per (machine, payload) key — `machinePayloadClient.ts:17-22`. */
+export type PendingMachinePayloadWrite = {
+    revision: string;
+};
+export type ConfirmedMachinePayloadWrite = {
+    revision: string;
+    at: number;
+};
+/** `machinePayloadClient.ts:35` — confirmed-write memory lives 10 minutes. */
+export declare const CONFIRMED_WRITE_TTL_MS: number;
+/** Dedupe-map key law — `machinePayloadClient.ts:37-39`. */
+export declare function machinePayloadWriteKey(machineId: string | null | undefined, payloadId: string): string;
+/**
+ * Revision law: revision = hash of the stable JSON of the payload
+ * (`machinePayloadClient.ts:49-51`; callers feed it `stableJson(payload)`).
+ */
+export declare function chatPayloadRevision(payloadJson: string): string;
+/**
+ * Is a confirmed-write memory entry still fresh? — the guard at
+ * `machinePayloadClient.ts:69` (`Date.now() - confirmed.at < TTL`), with
+ * the clock injected.
+ */
+export declare function isConfirmedWriteFresh(confirmed: ConfirmedMachinePayloadWrite | null | undefined, nowMs: number): boolean;
+export type MachinePayloadPublishDecision = 
+/** No payload id — nothing to publish (`:61`). */
+'skip-no-payload-id'
+/** The live state stream already committed this revision (`:62`). */
+ | 'skip-committed'
+/** An identical write is already in flight — join its promise (`:65-66`). */
+ | 'join-pending'
+/** The server confirmed this revision within the TTL (`:68-71`). */
+ | 'skip-confirmed'
+/** Issue the PUT. */
+ | 'publish';
+/**
+ * The publish-dedupe decision sequence of `publishMachineChatPayload`
+ * (`machinePayloadClient.ts:61-71`), as a pure function. The caller looks up
+ * `pending`/`confirmed` from its own maps under `machinePayloadWriteKey` and
+ * acts on the verdict; map mutation and the fetch stay host.
+ */
+export declare function machinePayloadPublishDecision(args: {
+    payloadId: string | null;
+    revision: string;
+    committedRevision?: string | null;
+    pending?: PendingMachinePayloadWrite | null;
+    confirmed?: ConfirmedMachinePayloadWrite | null;
+    nowMs: number;
+}): MachinePayloadPublishDecision;
+//# sourceMappingURL=revision.d.ts.map

package/dist/warm/revision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.d.ts","sourceRoot":"","sources":["../../src/warm/revision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,iFAAiF;AACjF,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,4FAA4F;AAC5F,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAOF,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AAErD,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtG;AAUD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,4BAA4B,GAAG,IAAI,GAAG,SAAS,EAC1D,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,MAAM,MAAM,6BAA6B;AACvC,kDAAkD;AAChD,oBAAoB;AACtB,qEAAqE;GACnE,gBAAgB;AAClB,6EAA6E;GAC3E,cAAc;AAChB,oEAAoE;GAClE,gBAAgB;AAClB,qBAAqB;GACnB,SAAS,CAAC;AAEd;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,OAAO,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC5C,SAAS,CAAC,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAChD,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,6BAA6B,CAShC"}

package/dist/warm/revision.js

@@ -0,0 +1,63 @@
+/**
+ * Revision hash + client publish-dedupe policy — the pure laws of
+ * `amalgm-ui/lib/chat/machinePayloadClient.ts` (:7-51 and the decision
+ * sequence of `publishMachineChatPayload`, :61-71).
+ *
+ * Design doc: docs/warm-payloads.md ("Revision law").
+ *
+ * Note: the revision is NOT sha256 — the UI uses a djb2-xor string hash
+ * rendered base-36 (`machinePayloadClient.ts:41-47`), ported byte-exact
+ * below, so no Sha256HexPort is needed here. The maps themselves
+ * (in-flight promises, confirmed writes) and the fetch are host state;
+ * this module exports only the shapes, constants, and decision laws.
+ */
+/** `machinePayloadClient.ts:35` — confirmed-write memory lives 10 minutes. */
+export const CONFIRMED_WRITE_TTL_MS = 10 * 60 * 1000;
+/** Dedupe-map key law — `machinePayloadClient.ts:37-39`. */
+export function machinePayloadWriteKey(machineId, payloadId) {
+    return `${machineId?.trim() || '__default__'}\0${payloadId}`;
+}
+function hashString(input) {
+    let hash = 5381;
+    for (let index = 0; index < input.length; index += 1) {
+        hash = ((hash << 5) + hash) ^ input.charCodeAt(index);
+    }
+    return (hash >>> 0).toString(36);
+}
+/**
+ * Revision law: revision = hash of the stable JSON of the payload
+ * (`machinePayloadClient.ts:49-51`; callers feed it `stableJson(payload)`).
+ */
+export function chatPayloadRevision(payloadJson) {
+    return hashString(payloadJson);
+}
+/**
+ * Is a confirmed-write memory entry still fresh? — the guard at
+ * `machinePayloadClient.ts:69` (`Date.now() - confirmed.at < TTL`), with
+ * the clock injected.
+ */
+export function isConfirmedWriteFresh(confirmed, nowMs) {
+    if (!confirmed)
+        return false;
+    return nowMs - confirmed.at < CONFIRMED_WRITE_TTL_MS;
+}
+/**
+ * The publish-dedupe decision sequence of `publishMachineChatPayload`
+ * (`machinePayloadClient.ts:61-71`), as a pure function. The caller looks up
+ * `pending`/`confirmed` from its own maps under `machinePayloadWriteKey` and
+ * acts on the verdict; map mutation and the fetch stay host.
+ */
+export function machinePayloadPublishDecision(args) {
+    const { payloadId, revision, committedRevision, pending, confirmed, nowMs } = args;
+    if (!payloadId)
+        return 'skip-no-payload-id';
+    if (committedRevision === revision)
+        return 'skip-committed';
+    if (pending?.revision === revision)
+        return 'join-pending';
+    if (confirmed?.revision === revision && isConfirmedWriteFresh(confirmed, nowMs)) {
+        return 'skip-confirmed';
+    }
+    return 'publish';
+}
+//# sourceMappingURL=revision.js.map

package/dist/warm/revision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.js","sourceRoot":"","sources":["../../src/warm/revision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2BH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAErD,4DAA4D;AAC5D,MAAM,UAAU,sBAAsB,CAAC,SAAoC,EAAE,SAAiB;IAC5F,OAAO,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;AAC/D,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAA0D,EAC1D,KAAa;IAEb,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,KAAK,GAAG,SAAS,CAAC,EAAE,GAAG,sBAAsB,CAAC;AACvD,CAAC;AAcD;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,IAO7C;IACC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACnF,IAAI,CAAC,SAAS;QAAE,OAAO,oBAAoB,CAAC;IAC5C,IAAI,iBAAiB,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAC;IAC5D,IAAI,OAAO,EAAE,QAAQ,KAAK,QAAQ;QAAE,OAAO,cAAc,CAAC;IAC1D,IAAI,SAAS,EAAE,QAAQ,KAAK,QAAQ,IAAI,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC;QAChF,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/warm/store-policy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Machine-side chat-payload store policy — the pure laws of engine
+ * `runtime/scripts/amalgm-mcp/lib/chat-payloads.js` (CJS). SQLite
+ * (`local_meta` key `chat_payloads`), the transaction, and state-event
+ * emission stay host; this module owns the record shape, normalization,
+ * the TTL/cap constants, and the GC sweep decision.
+ */
+import type { ClockIsoPort } from '../ports.js';
+/** `chat-payloads.js:6-7` — store key and state-event resource name. */
+export declare const CHAT_PAYLOADS_META_KEY = "chat_payloads";
+export declare const CHAT_PAYLOADS_RESOURCE = "chat_payloads";
+export declare const CHAT_PAYLOAD_TTL_MS: number;
+export declare const CHAT_PAYLOAD_MAX_RECORDS = 300;
+/** Stored record shape — `chat-payloads.js:54-59`. Payload is untyped JSON machine-side. */
+export type ChatPayloadStoreRecord = {
+    id: string;
+    revision: string;
+    payload: Record<string, unknown>;
+    updatedAt: string;
+};
+/** `chat-payloads.js:17-19`. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** `chat-payloads.js:21-23`. */
+export declare function cleanString(value: unknown): string | null;
+/**
+ * Record normalization law — `chat-payloads.js:42-60`: id required (from
+ * `id`/`payloadId`/existing), payload required (from body else existing),
+ * revision falls back through `revision`/`payloadRevision`/existing to
+ * `'unknown'`, and `updatedAt` is stamped now (the engine's
+ * `new Date().toISOString()`, injected as `clockIso`).
+ */
+export declare function normalizeChatPayloadRecord(input: unknown, existing: ChatPayloadStoreRecord | null, clockIso: ClockIsoPort): ChatPayloadStoreRecord;
+/**
+ * `chat-payloads.js:62-65` — unparseable/absent updatedAt sorts as epoch 0.
+ * `Date.parse` here is a deterministic string parser, not a clock read —
+ * the purity axiom (src/ports.ts) bans ambient time/entropy, and the
+ * engine's law is defined in terms of `Date.parse` itself. `String(...)`
+ * mirrors the ToString coercion `Date.parse` applies to the engine's
+ * `record?.updatedAt || ''` argument.
+ */
+export declare function recordTimestamp(record: {
+    updatedAt?: unknown;
+} | null | undefined): number;
+/**
+ * GC sweep decision — the pure core of `sweepChatPayloadsOnce`
+ * (`chat-payloads.js:67-100`, the transaction body :74-86): keep only
+ * plain records with a non-blank id whose timestamp is on or after
+ * `now - 7d`; if more than 300 survive, keep the newest 300 by
+ * `updatedAt`. `changed === false` means the sweep writes nothing (the
+ * engine returns null and skips the SQLite UPDATE + state event). The
+ * once-per-process latch, the write, and the event stay host.
+ */
+export declare function sweepChatPayloads(current: Record<string, unknown>, nowMs: number): {
+    changed: boolean;
+    next: Record<string, ChatPayloadStoreRecord>;
+};
+//# sourceMappingURL=store-policy.d.ts.map

package/dist/warm/store-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-policy.d.ts","sourceRoot":"","sources":["../../src/warm/store-policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAMtD,eAAO,MAAM,mBAAmB,QAA0B,CAAC;AAC3D,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,4FAA4F;AAC5F,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,gCAAgC;AAChC,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED,gCAAgC;AAChC,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,sBAAsB,GAAG,IAAI,EACvC,QAAQ,EAAE,YAAY,GACrB,sBAAsB,CAkBxB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAG1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,MAAM,GACZ;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAA;CAAE,CAgBpE"}

package/dist/warm/store-policy.js

@@ -0,0 +1,89 @@
+/**
+ * Machine-side chat-payload store policy — the pure laws of engine
+ * `runtime/scripts/amalgm-mcp/lib/chat-payloads.js` (CJS). SQLite
+ * (`local_meta` key `chat_payloads`), the transaction, and state-event
+ * emission stay host; this module owns the record shape, normalization,
+ * the TTL/cap constants, and the GC sweep decision.
+ */
+/** `chat-payloads.js:6-7` — store key and state-event resource name. */
+export const CHAT_PAYLOADS_META_KEY = 'chat_payloads';
+export const CHAT_PAYLOADS_RESOURCE = 'chat_payloads';
+// Records are keyed by UI tab id and nothing deletes them when a tab closes, so
+// the map grows forever without a sweep. GC of a live tab's record is safe:
+// before every launch the client re-publishes unless its own confirmed-write
+// memory is fresher than 10 minutes.
+export const CHAT_PAYLOAD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const CHAT_PAYLOAD_MAX_RECORDS = 300;
+/** `chat-payloads.js:17-19`. */
+export function isPlainObject(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+/** `chat-payloads.js:21-23`. */
+export function cleanString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+/**
+ * Record normalization law — `chat-payloads.js:42-60`: id required (from
+ * `id`/`payloadId`/existing), payload required (from body else existing),
+ * revision falls back through `revision`/`payloadRevision`/existing to
+ * `'unknown'`, and `updatedAt` is stamped now (the engine's
+ * `new Date().toISOString()`, injected as `clockIso`).
+ */
+export function normalizeChatPayloadRecord(input, existing, clockIso) {
+    const body = isPlainObject(input) ? input : {};
+    const id = cleanString(body['id'] || body['payloadId'] || existing?.id);
+    if (!id)
+        throw new Error('chat payload id is required');
+    const payload = isPlainObject(body['payload'])
+        ? body['payload']
+        : isPlainObject(existing?.payload)
+            ? existing.payload
+            : null;
+    if (!payload)
+        throw new Error('chat payload is required');
+    return {
+        id,
+        revision: cleanString(body['revision'] || body['payloadRevision'] || existing?.revision) || 'unknown',
+        payload,
+        updatedAt: clockIso(),
+    };
+}
+/**
+ * `chat-payloads.js:62-65` — unparseable/absent updatedAt sorts as epoch 0.
+ * `Date.parse` here is a deterministic string parser, not a clock read —
+ * the purity axiom (src/ports.ts) bans ambient time/entropy, and the
+ * engine's law is defined in terms of `Date.parse` itself. `String(...)`
+ * mirrors the ToString coercion `Date.parse` applies to the engine's
+ * `record?.updatedAt || ''` argument.
+ */
+export function recordTimestamp(record) {
+    const parsed = Date.parse(String(record?.updatedAt || ''));
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/**
+ * GC sweep decision — the pure core of `sweepChatPayloadsOnce`
+ * (`chat-payloads.js:67-100`, the transaction body :74-86): keep only
+ * plain records with a non-blank id whose timestamp is on or after
+ * `now - 7d`; if more than 300 survive, keep the newest 300 by
+ * `updatedAt`. `changed === false` means the sweep writes nothing (the
+ * engine returns null and skips the SQLite UPDATE + state event). The
+ * once-per-process latch, the write, and the event stay host.
+ */
+export function sweepChatPayloads(current, nowMs) {
+    const cutoff = nowMs - CHAT_PAYLOAD_TTL_MS;
+    let kept = Object.values(current)
+        .filter((record) => isPlainObject(record) && Boolean(cleanString(record['id'])))
+        .filter((record) => recordTimestamp(record) >= cutoff);
+    if (kept.length > CHAT_PAYLOAD_MAX_RECORDS) {
+        kept = kept
+            .sort((a, b) => recordTimestamp(b) - recordTimestamp(a))
+            .slice(0, CHAT_PAYLOAD_MAX_RECORDS);
+    }
+    if (kept.length === Object.keys(current).length)
+        return { changed: false, next: current };
+    const next = {};
+    for (const record of kept)
+        next[record.id] = record;
+    return { changed: true, next };
+}
+//# sourceMappingURL=store-policy.js.map

package/dist/warm/store-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-policy.js","sourceRoot":"","sources":["../../src/warm/store-policy.ts"],"names":[],"mappings":"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"}

package/dist/wire/frames.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Wire projection — engine `chat-core/sse.js` (206 lines) ported byte-exact:
+ * amalgm events → the ACP-shaped `AgentStreamEvent` the browser consumes,
+ * SSE frame strings, frame id numbering, and the PromptUsage projection.
+ *
+ * Everything here is pure. The engine's `writeSseHeaders(res)` is the one
+ * host-side effect; its header set is exported as a constant and the
+ * res-writing helper takes a structural `writeHead` target so hosts can
+ * pass their own response object (no `node:http` import).
+ */
+type AnyRecord = Record<string, any>;
+/** A validated amalgm event or any event-shaped record (the engine projects unvalidated shapes too). */
+export type AmalgmEventLike = AnyRecord;
+/** Engine sse.js `context` parameter: per-stream identity + optional usage override for `done`. */
+export interface StreamContext {
+    sessionId?: unknown;
+    providerSessionId?: unknown;
+    usage?: AnyRecord | null;
+}
+export interface PromptTokenList {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    thought: number;
+    total: number;
+}
+/** The `usage` object carried by `usage_update` and `complete` frames (engine sse.js:6-41). */
+export interface PromptUsage {
+    tokenList: PromptTokenList | AnyRecord;
+    cumulativeTokenList: unknown;
+    previousCumulativeTokenList: unknown;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    thoughtTokens: number;
+    inputContextSize: unknown;
+    totalTokens: number;
+    contextUsedTokens: unknown;
+    contextLimit: unknown;
+    usedTokens: unknown;
+    lastUsedTokens: unknown;
+    maxTokens: unknown;
+    totalProcessedTokens: unknown;
+    costUsd: unknown;
+    marketCostUsd: unknown;
+    operation: unknown;
+    billable: boolean;
+    source: unknown;
+    exact: boolean;
+}
+/**
+ * Engine sse.js:6-41. Project any usage-ish record into PromptUsage.
+ * `totalTokens` obeys the token-total law (`usage.js:123-127`, ported at
+ * `src/usage/tokens.ts`): tokenList.total, else inputContextSize, else the
+ * sum of the four non-thought buckets.
+ */
+export declare function toPromptUsage(usage?: AnyRecord | null): PromptUsage | undefined;
+export interface AgentMessageChunkFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'agent_message_chunk';
+    content: {
+        type: 'text';
+        text: string;
+    };
+}
+export interface AgentMessageBoundaryFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'agent_message_boundary';
+    itemId: unknown;
+    reason: unknown;
+}
+export interface AgentThoughtChunkFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'agent_thought_chunk';
+    content: {
+        type: 'text';
+        text: string;
+    };
+}
+export interface ToolCallFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'tool_call';
+    toolCallId: unknown;
+    toolName: unknown;
+    title: unknown;
+    kind: unknown;
+    status: 'in_progress';
+    rawInput: unknown;
+    metadata: unknown;
+    timing: unknown;
+}
+export interface ToolCallUpdateFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'tool_call_update';
+    toolCallId: unknown;
+    toolName: unknown;
+    title: unknown;
+    kind: unknown;
+    status: unknown;
+    rawInput: unknown;
+    rawOutput: unknown;
+    error: unknown;
+    metadata: unknown;
+    timing: unknown;
+}
+export interface UsageUpdateFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'usage_update';
+    used: number;
+    size: number | null;
+    inputContextSize: unknown;
+    cost: {
+        amount: unknown;
+        currency: 'USD';
+    } | null;
+    usage: PromptUsage | undefined;
+}
+export interface CompactionStartedFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'compaction_boundary';
+    phase: 'started';
+    trigger: unknown;
+}
+export interface CompactionFinishedFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'compaction_boundary';
+    phase: 'finished';
+    trigger: unknown;
+    preTokens: unknown;
+    postTokens: unknown;
+    durationMs: unknown;
+}
+export interface SessionInfoUpdateFrame {
+    _type: 'update';
+    eventTimestamp: number;
+    sessionUpdate: 'session_info_update';
+}
+export interface ModelErrorFrame {
+    _type: 'model_error';
+    error: string;
+    requestedModel: string;
+    eventTimestamp: number;
+}
+export interface ErrorFrame {
+    _type: 'error';
+    message: string;
+    eventTimestamp: number;
+}
+export interface CompleteFrame {
+    _type: 'complete';
+    codeSessionId: unknown;
+    providerSessionId: unknown;
+    stopReason: unknown;
+    usage: PromptUsage | undefined;
+    eventTimestamp: number;
+}
+export interface TitleGeneratedFrame {
+    _type: 'title_generated';
+    sessionId: unknown;
+    title: unknown;
+}
+export type AgentStreamEvent = AgentMessageChunkFrame | AgentMessageBoundaryFrame | AgentThoughtChunkFrame | ToolCallFrame | ToolCallUpdateFrame | UsageUpdateFrame | CompactionStartedFrame | CompactionFinishedFrame | SessionInfoUpdateFrame | ModelErrorFrame | ErrorFrame | CompleteFrame;
+/** Engine sse.js:65-181. The amalgm-event → AgentStreamEvent projection; unknown types become `session_info_update`. */
+export declare function toAgentStreamEvent(e: AmalgmEventLike, context?: StreamContext): AgentStreamEvent;
+/** Engine sse.js:183-185. One SSE data frame: `data: <json>\n\n`. */
+export declare function frameFor(e: AmalgmEventLike, context?: StreamContext): string;
+/** Engine sse.js:187-189. */
+export declare function titleFrame({ sessionId, title }: {
+    sessionId?: unknown;
+    title?: unknown;
+}): string;
+/**
+ * Engine sse.js:191-196. Frame id numbering law: prepend `id: <n>\n` only
+ * for non-negative integers (Number-coerced), and never double-stamp a
+ * frame that already starts with `id:`.
+ */
+export declare function withSseId(frame: string, id: unknown): string;
+/** Engine sse.js:199-203 status code. */
+export declare const SSE_STATUS_CODE = 200;
+/** Engine sse.js:199-203 header set, exported for hosts that write headers themselves. */
+export declare const SSE_HEADERS: Readonly<{
+    'Content-Type': "text/event-stream";
+    'Cache-Control': "no-cache, no-transform";
+    Connection: "keep-alive";
+}>;
+/** Structural target for {@link writeSseHeaders} — any `http.ServerResponse`-like object. */
+export interface SseHeadTarget {
+    writeHead(statusCode: number, headers: Record<string, string>): unknown;
+}
+/**
+ * Engine sse.js:198-204. HOST-SIDE EFFECT: writes the SSE status + headers
+ * to the supplied response object. Pure with respect to imports — the
+ * response is injected; hosts on non-Node stacks should use
+ * {@link SSE_HEADERS} / {@link SSE_STATUS_CODE} directly.
+ */
+export declare function writeSseHeaders(res: SseHeadTarget): void;
+export {};
+//# sourceMappingURL=frames.d.ts.map

package/dist/wire/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/wire/frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAErC,wGAAwG;AACxG,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC;AAExC,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,GAAG,SAAS,CAAC;IACvC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,2BAA2B,EAAE,OAAO,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,WAAW,GAAG,SAAS,CAmC/E;AA2BD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,qBAAqB,CAAC;IACrC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,wBAAwB,CAAC;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,qBAAqB,CAAC;IACrC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,WAAW,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,kBAAkB,CAAC;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,cAAc,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,qBAAqB,CAAC;IACrC,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,qBAAqB,CAAC;IACrC,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,qBAAqB,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,gBAAgB,GACxB,sBAAsB,GACtB,yBAAyB,GACzB,sBAAsB,GACtB,aAAa,GACb,mBAAmB,GACnB,gBAAgB,GAChB,sBAAsB,GACtB,uBAAuB,GACvB,sBAAsB,GACtB,eAAe,GACf,UAAU,GACV,aAAa,CAAC;AAElB,wHAAwH;AACxH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,GAAE,aAAkB,GAAG,gBAAgB,CAoHpG;AAED,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAE5E;AAED,6BAA6B;AAC7B,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAEjG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,MAAM,CAK5D;AAED,yCAAyC;AACzC,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;EAItB,CAAC;AAEH,6FAA6F;AAC7F,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;CACzE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAMxD"}