@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

package/dist/chat-protocol/decode.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SSE wire-protocol decoder — a timer-free synchronous state machine,
+ * mechanically extracted from `useSseChatAdapter`'s inline
+ * `createDocStreamFn` parser. Byte-for-byte behavior parity with the
+ * legacy parser is the contract (the golden fixtures in
+ * `src/components/chat/hooks/__tests__/sse-stream-golden.test.ts` pin it
+ * through the full hook path), including its quirks:
+ *
+ *   - A leading `\0`-terminated block that fails JSON.parse flips the
+ *     stream into text mode and the WHOLE buffer (including the `\0`)
+ *     is emitted as answer text (legacy no-frame stream fallback). This
+ *     transition is marked `turn-start { implicit: true }`.
+ *   - In text mode only `\x1F` is scanned — literal `\0` / `\x1E` bytes
+ *     pass through into the answer; the FIRST literal `\x1F` flips into
+ *     trailer mode and everything after is captured as the trailer
+ *     (golden fixture (d) characterizes this mis-framing; the fix lives
+ *     in `encode.ts`'s sentinel stripping, NOT here).
+ *   - The `\x1E` sentinel and the `\x1F` trailer can arrive in ONE TCP
+ *     chunk (fixed-answer responses) — the post-sentinel slice is
+ *     re-scanned for the trailer sentinel.
+ *   - Multi-byte UTF-8 across chunk boundaries survives via a single
+ *     streaming TextDecoder (`{ stream: true }` on every push; no final
+ *     flush — a trailing partial code point is dropped, as legacy did).
+ *   - `end()` parses the accumulated trailer (malformed → silently
+ *     ignored) and drops any un-terminated leading buffer, as legacy did.
+ *     It is IDEMPOTENT (a deliberate deviation from legacy): repeat calls
+ *     emit nothing, so an adapter that ends in both its completion path
+ *     and its `finally` cannot double-count the usage frame.
+ *
+ * State flow: leading → (sentinel | parse-failure) → text → (\x1F) →
+ * trailer-accumulate → end().
+ *
+ * Server-safe: no React, no timers, TextDecoder only.
+ */
+import type { ChatStreamEvent } from './events';
+export interface SseFrameDecoder {
+    /** Feed raw response bytes; returns the events they produced. */
+    push(bytes: Uint8Array): ChatStreamEvent[];
+    /**
+     * Signal end-of-stream; parses the trailing usage frame if present.
+     * IDEMPOTENT — every call after the first returns `[]`. Adapters
+     * routinely call this from BOTH their completion path and a `finally`,
+     * and a re-emitted `usage`/`stage:'end'` event would double-count token
+     * usage (displayed cost doubles).
+     */
+    end(): ChatStreamEvent[];
+}
+/**
+ * Escape `<` so markdown renderers that pass HTML through (rehypeRaw)
+ * don't treat XML-like tokens in Claude's thinking output as elements.
+ * `<` → `&lt;` preserves the visible character without breaking
+ * blockquote `>` markers. Per-character, so it distributes over
+ * concatenation: escape(a + b) === escape(a) + escape(b) — callers may
+ * apply it per-delta or on the accumulated string interchangeably.
+ */
+export declare function escapeThinkingTags(text: string): string;
+export declare function createSseFrameDecoder(): SseFrameDecoder;
+//# sourceMappingURL=decode.d.ts.map

package/dist/chat-protocol/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/chat-protocol/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE/C,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,EAAE,CAAA;IAC1C;;;;;;OAMG;IACH,GAAG,IAAI,eAAe,EAAE,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqGD,wBAAgB,qBAAqB,IAAI,eAAe,CAmHvD"}

package/dist/chat-protocol/encode.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SSE wire-protocol encoders — the emit side of the framing contract in
+ * `./frames.ts`. Server-safe (TextEncoder only). The hub's stream route
+ * consumes these so emitter and decoder can never drift.
+ */
+import { type SseLeadingFrame, type SseTrailingUsageFrame } from './frames';
+/**
+ * Remove the SSE framing sentinel bytes (`\0`, `\x1E`, `\x1F`) from model
+ * text. Exported as a STANDALONE helper — not just folded into
+ * `encodeTextDelta` — because producers must strip at the point where they
+ * first take custody of the text, BEFORE any local accumulation.
+ *
+ * Concretely: the hub's `claude-util.ts` accumulates `state.answerText` for
+ * persistence + telemetry. If stripping only happened at encode time, the
+ * persisted/telemetered answer would diverge, character for character, from
+ * the bytes the user actually received whenever the model echoes a control
+ * byte. Both sides call this, so there is exactly ONE definition of "which
+ * bytes are framing" in the whole system — do not re-declare the regex.
+ *
+ * Idempotent and per-character, so it distributes over concatenation:
+ * `strip(a + b) === strip(a) + strip(b)` — safe to apply per-delta or on the
+ * accumulated string interchangeably.
+ */
+export declare function stripSentinelBytes(text: string): string;
+/** Encode one leading frame: JSON + `\0` terminator. */
+export declare function encodeLeadingFrame(frame: SseLeadingFrame): Uint8Array;
+/** Encode the single `\x1E` end-of-leading-frames sentinel. */
+export declare function encodeEndOfLeading(): Uint8Array;
+/**
+ * Encode a raw answer-text delta. STRIPS the framing sentinel bytes via
+ * `stripSentinelBytes` so model-echoed control bytes can no longer
+ * mis-frame the stream (a literal `\x1F` in the answer used to flip the
+ * client into trailer mode and swallow the rest of the answer PLUS the real
+ * usage trailer — characterized by golden fixture (d)). Forward-looking
+ * encoder fix only; the decoder's behavior is unchanged.
+ *
+ * Producers that ALSO accumulate the text locally (persistence, telemetry)
+ * must call `stripSentinelBytes` on their own copy — see its docblock.
+ */
+export declare function encodeTextDelta(text: string): Uint8Array;
+/** Encode the trailing usage frame: `\x1F` + JSON, no terminator
+ *  (runs to stream end). */
+export declare function encodeTrailingUsageFrame(frame: SseTrailingUsageFrame): Uint8Array;
+//# sourceMappingURL=encode.d.ts.map

package/dist/chat-protocol/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/chat-protocol/encode.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,UAAU,CAAA;AAQjB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,CAErE;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,IAAI,UAAU,CAE/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAExD;AAED;4BAC4B;AAC5B,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,qBAAqB,GAAG,UAAU,CAEjF"}

package/dist/chat-protocol/env-flag.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `envFlagEnabled` — THE cross-repo predicate for reading a boolean env flag.
+ *
+ * WHY IT LIVES HERE: the same flag is read on BOTH sides of the guide-chat
+ * seam and each side had grown its own reading of it. The hub parsed the
+ * value (`'0'` / `'false'` / `'off'` mean OFF); the producing app used bare
+ * `Boolean(process.env.X)`, under which every non-empty string — including
+ * `'0'` and `'false'` — is TRUE.
+ *
+ * That divergence failed OPEN on the one flag that gates a security boundary.
+ * `TRUSTED_INGRESS_SETS_REAL_IP` is an operator's assertion that a reverse
+ * proxy OVERWRITES the client-IP headers; without it those headers are
+ * attacker-writable and must not be read. An operator writing `=0` to mean
+ * "off" got the hub honoring that while the producer read `x-real-ip` /
+ * `x-forwarded-for` anyway and forwarded the value as `x-chat-ip`, which the
+ * hub then trusts verbatim under the service token. A rate-limit-bucket
+ * spoof, reachable through a plausible operator typo.
+ *
+ * Both repos already depend on this package and `./chat-protocol` is its
+ * server-safe subpath (no React, no browser APIs), so this is the one place
+ * both sides can share — same reasoning that moved `normalizeIpForBucketKey`
+ * here. Keep it as ONE definition: a second copy is what caused the drift.
+ *
+ * Contract:
+ *   - unset, empty, or whitespace-only  → `false`;
+ *   - `'0'`, `'false'`, `'off'`         → `false` (case- and
+ *     surrounding-whitespace-insensitive);
+ *   - any other non-empty value         → `true`.
+ *
+ * `process.env` is read PER CALL, never module-hoisted, so tests, preview and
+ * prod all observe the live value rather than whatever was present at
+ * module-eval time.
+ */
+export declare function envFlagEnabled(name: string): boolean;
+//# sourceMappingURL=env-flag.d.ts.map

package/dist/chat-protocol/env-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-flag.d.ts","sourceRoot":"","sources":["../../src/chat-protocol/env-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpD"}

package/dist/chat-protocol/events.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Normalized chat stream events — the transport-agnostic event union BOTH
+ * decoders (SSE byte framing in `./decode.ts`, NATS chunks in
+ * `./nats-decoder.ts`) emit. Phase 3 of the chat unification makes the
+ * reducer consume these directly; today the SSE adapter maps them back to
+ * legacy `MessageSegment` yields.
+ *
+ * Server-safe: no React, no browser APIs.
+ */
+import type { ApprovalRequestField, DecisionResolvedFrame, UsageTelemetry } from './frames';
+/** Optional envelope on every event. `seq` carries the transport's
+ *  stream sequence (JetStream `streamSeq` on NATS; unused on SSE). */
+interface ChatStreamEventBase {
+    seq?: number;
+}
+/** Stream entered answer-text mode (SSE: the `\x1E` sentinel or the
+ *  JSON-parse-failure fallback; NATS: MESSAGE_START).
+ *  `implicit` is true ONLY for the SSE fallback path where a
+ *  non-JSON leading buffer flips straight into text mode — consumers
+ *  that flush coalesced thinking on turn-start must SKIP the flush for
+ *  implicit starts (legacy adapter parity: the fallback path never
+ *  flushed pending thinking before the text). */
+export interface TurnStartEvent extends ChatStreamEventBase {
+    type: 'turn-start';
+    implicit?: boolean;
+}
+export interface TurnEndEvent extends ChatStreamEventBase {
+    type: 'turn-end';
+}
+/** Answer text delta. `leading: true` marks SSE `text-leading` frames
+ *  (model preamble prose emitted BEFORE the tool approval card). */
+export interface TextDeltaEvent extends ChatStreamEventBase {
+    type: 'text-delta';
+    text: string;
+    leading?: boolean;
+}
+/** Thinking delta — APPEND-ONLY contract: each event carries the next
+ *  verbatim slice; consumers accumulate. Decoders never diff. */
+export interface ThinkingDeltaEvent extends ChatStreamEventBase {
+    type: 'thinking-delta';
+    text: string;
+}
+/** Guide-body delta (NATS `GUIDE` chunk) — the assistant's how-to /
+ *  documentation answer, rendered as a titled "OpenFrame Guide" card rather
+ *  than bare prose. Same APPEND-ONLY contract as `text-delta` /
+ *  `thinking-delta`: each event carries the next verbatim slice and consumers
+ *  coalesce into the trailing `guide` segment. NATS-only today — the SSE
+ *  frame grammar has no guide frame — but it lives in the shared union
+ *  because the reducer is transport-agnostic. */
+export interface GuideDeltaEvent extends ChatStreamEventBase {
+    type: 'guide-delta';
+    text: string;
+}
+export interface StatusEvent extends ChatStreamEventBase {
+    type: 'status';
+    phase: 'thinking';
+}
+/** NATS tool execution progress (EXECUTING_TOOL / EXECUTED_TOOL). */
+export interface ToolExecutionEvent extends ChatStreamEventBase {
+    type: 'tool-execution';
+    data: {
+        type: 'EXECUTING_TOOL' | 'EXECUTED_TOOL';
+        integratedToolType: string;
+        toolFunction: string;
+        toolTitle?: string;
+        /**
+         * Human-readable "why this tool is running" line, rendered as the body of
+         * the tool card. Carried by the EXECUTING chunk ONLY — the EXECUTED one
+         * never repeats it, and the accumulator's merge keeps whatever the
+         * EXECUTING segment held (`toolData.toolExplanation ?? existing`). Omitting
+         * it from this contract blanks the card for the whole run, live and on
+         * replay, which is exactly what happened while it was missing here.
+         */
+        toolExplanation?: string;
+        parameters?: Record<string, unknown>;
+        result?: string;
+        success?: boolean;
+        toolExecutionRequestId?: string;
+    };
+}
+/** Single tool call inside a batch approval request (NATS). */
+export interface ApprovalToolCall {
+    toolExecutionRequestId: string;
+    toolName: string;
+    toolTitle?: string;
+    toolExplanation?: string;
+    toolType?: string;
+    requiresApproval: boolean;
+    approvalType?: string | null;
+    toolCallArguments?: Record<string, unknown> | null;
+}
+/** A tool call awaits user approval. SSE fills `command`/`fields`
+ *  (card-ready payload); NATS fills `command`/`explanation` or
+ *  `toolCalls` (batch form). */
+export interface ApprovalRequestEvent extends ChatStreamEventBase {
+    type: 'approval-request';
+    requestId: string;
+    /** SSE: the write tool's name. NATS: approval tier (USER/ADMIN/…). */
+    approvalType?: string;
+    command?: string;
+    explanation?: string;
+    fields?: ApprovalRequestField[];
+    toolCalls?: ApprovalToolCall[];
+    status?: 'pending';
+}
+/** An approval request was resolved (SSE `decision_resolved` frame /
+ *  NATS APPROVAL_RESULT chunk). */
+export interface ApprovalResolvedEvent extends ChatStreamEventBase {
+    type: 'approval-resolved';
+    requestId?: string;
+    status: 'approved' | 'rejected';
+    ok?: boolean;
+    toolName?: string;
+    approvalType?: string;
+    resolvedByName?: string | null;
+    receiptText?: string;
+    /** Inline post-approve card: the ref payload + its documentType +
+     *  the `[card://…]` marker (SSE only). */
+    cardRef?: unknown;
+    cardType?: string;
+    marker?: string;
+    result?: DecisionResolvedFrame['result'];
+    willAutoContinue?: boolean;
+}
+/** Per-turn metadata. Raw wire values pass through UNVALIDATED — the
+ *  consumer replicates the legacy truthiness/typeof gates (so a
+ *  malformed frame degrades identically to the pre-SSOT parser). */
+export interface ChatMetadataEvent extends ChatStreamEventBase {
+    type: 'metadata';
+    provider?: string | null;
+    modelLabel?: string | null;
+    /** Raw model id (SSE `meta.model`; NATS `modelName`). */
+    modelName?: string | null;
+    contextWindowMaxTokens?: number | null;
+    sources?: unknown;
+    refs?: unknown;
+    scrollAnchor?: unknown;
+    /** Server-minted conversation id (`ChatMetadataFrame.conversationId`),
+     *  passed through raw like every other catch-all field — the consumer
+     *  applies the `typeof === 'string' && truthy` gate. */
+    conversationId?: string | null;
+    routing?: {
+        routedComplexity: string;
+        routedModel?: string;
+        routedThinkingBudget: number | null;
+    };
+}
+/** SSE usage frames — raw wire keys (snake_case) preserved. */
+export interface UsageEvent extends ChatStreamEventBase {
+    type: 'usage';
+    stage: 'start' | 'end';
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    hit_rate_pct?: number;
+    telemetry?: UsageTelemetry;
+    /** Left OPAQUE on purpose: the consumer (`chat-stream-reducer`'s
+     *  `applySseUsage`) re-validates every nested field with the legacy
+     *  truthiness/typeof gates, so a malformed frame degrades identically
+     *  to the pre-SSOT parser. Typing it would imply guarantees the wire
+     *  does not make. */
+    breakdown?: unknown;
+    debug?: unknown;
+}
+/** NATS TOKEN_USAGE chunk (camelCase backend shape). */
+export interface TokenUsageEvent extends ChatStreamEventBase {
+    type: 'token-usage';
+    inputTokensSize: number;
+    outputTokensSize: number;
+    totalTokensSize: number;
+    contextSize: number;
+}
+export interface CompactionEvent extends ChatStreamEventBase {
+    type: 'compaction';
+    phase: 'start' | 'end';
+    summary?: string;
+}
+export interface ErrorEvent extends ChatStreamEventBase {
+    type: 'error';
+    title: string;
+    details?: string;
+}
+/** Non-assistant message on the stream (NATS): the user's own message
+ *  echo (`message-request`), an operator direct message, or a system
+ *  line. */
+/**
+ * Dialog participant owner type. The two members below are the ones clients
+ * BRANCH ON (admin-vs-not decides echo dedup and author styling); the union
+ * stays open (`string & {}`) because the wire may carry other roles that the
+ * client treats as "not admin". Always compare against `CHAT_OWNER_ADMIN`,
+ * never a bare `'ADMIN'` literal — a typo in a literal silently disables
+ * dedup instead of failing to compile.
+ */
+export type ChatOwnerType = 'ADMIN' | 'CLIENT' | (string & {});
+/** Canonical ADMIN owner-type token (see `ChatOwnerType`). */
+export declare const CHAT_OWNER_ADMIN = "ADMIN";
+export interface ParticipantEvent extends ChatStreamEventBase {
+    type: 'participant';
+    kind: 'message-request' | 'direct-message' | 'system';
+    text: string;
+    ownerType?: ChatOwnerType;
+    displayName?: string;
+    userId?: string;
+    contextItems?: Array<{
+        type: string;
+        id: string;
+        label: string;
+    }>;
+}
+export interface DialogClosedEvent extends ChatStreamEventBase {
+    type: 'dialog-closed';
+}
+export type ChatStreamEvent = TurnStartEvent | TurnEndEvent | TextDeltaEvent | ThinkingDeltaEvent | GuideDeltaEvent | StatusEvent | ToolExecutionEvent | ApprovalRequestEvent | ApprovalResolvedEvent | ChatMetadataEvent | UsageEvent | TokenUsageEvent | CompactionEvent | ErrorEvent | ParticipantEvent | DialogClosedEvent;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/chat-protocol/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/chat-protocol/events.ts"],"names":[],"mappings":"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"}

package/dist/chat-protocol/frames.d.ts

@@ -0,0 +1,213 @@
+/**
+ * SSE wire-protocol frame shapes — the byte-level contract between the
+ * hub's chat stream emitter (`multi-platform-hub/lib/utils/claude-util.ts`)
+ * and the lib's SSE decoder (`./decode.ts`).
+ *
+ * Wire format (custom byte framing, NOT standard SSE `data:` lines):
+ *
+ *   [JSON frame]\0 [JSON frame]\0 …  \x1E  <raw UTF-8 answer deltas>  \x1F [JSON usage trailer]
+ *
+ *   1. LEADING frames — each a JSON object terminated by `\0`
+ *      (FRAME_TERMINATOR). Status, metadata, routing, live thinking
+ *      deltas, usage:start, tool approval frames.
+ *   2. ONE `\x1E` byte (END_OF_LEADING) — flips the stream into raw
+ *      UTF-8 answer-text mode.
+ *   3. `\x1F` (TRAILER_SENTINEL) + one JSON usage frame running to
+ *      stream end (no terminator).
+ *
+ * Server-safe: no React, no browser APIs beyond TextEncoder/TextDecoder.
+ */
+/** Terminates every leading JSON frame. */
+export declare const FRAME_TERMINATOR = "\0";
+/** Record Separator — end of leading frames, start of raw answer text. */
+export declare const END_OF_LEADING = "\u001E";
+/** Unit Separator — start of the trailing usage JSON frame. */
+export declare const TRAILER_SENTINEL = "\u001F";
+/** Server-side routing complexity tiers. Mirror of the hub's
+ *  `lib/constants/ai-models.ts` union — kept as a lib-local literal type
+ *  so the wire SSOT has zero hub imports. The DECODER accepts any string
+ *  (older/newer servers may ship values outside this union). */
+export type RouteComplexity = 'trivial' | 'default' | 'complex' | 'deep';
+/**
+ * Routing decision frame. Emitted once per turn as a LEADING frame
+ * (between metadata and the `\x1E` end-of-leading-frames sentinel) when
+ * the server's `decideRoute()` produces a `Route`.
+ *
+ * Field names use the `routed*` prefix on PURPOSE — the client's
+ * catch-all leading-frame branch inspects `meta.model` / `meta.modelLabel`.
+ * A bare `model` field on this frame would OVERWRITE the metadata frame's
+ * modelLabel and break the <ModelDisplay> badge. The `routed` prefix
+ * sidesteps that collision.
+ *
+ * Older clients that don't recognize `kind: 'routing'` silently drop
+ * the frame (the catch-all only matches frames carrying known fields
+ * like `sources` / `refs` / `modelLabel`).
+ */
+export interface RoutingFrame {
+    kind: 'routing';
+    routedComplexity: RouteComplexity;
+    routedModel: string;
+    routedThinkingBudget: number;
+}
+/**
+ * Optional field on the trailing usage frame's `breakdown`. Surfaces
+ * per-route attribution to the admin test console so an operator can
+ * see "this turn ran on Haiku/trivial/$0.0005" without re-parsing the
+ * stream. Additive: clients that ignore unknown keys keep working.
+ */
+export interface RoutedAnswerBreakdown {
+    model: string;
+    complexity: RouteComplexity;
+    thinkingBudget: number;
+}
+/** First frame on every stream — lets the shell render "Thinking…"
+ *  within ~200ms, before any upstream byte arrives. */
+export interface StatusThinkingFrame {
+    status: 'thinking';
+}
+/** Per-turn metadata frame. The emitter sends `options.metadata`
+ *  verbatim; a separate refs-only frame may follow with the same shape.
+ *  All fields optional — the decoder's catch-all treats ANY frame that
+ *  didn't match a `kind` discriminant as metadata-ish. */
+export interface ChatMetadataFrame {
+    /** Retrieval sources for the source-chip strip. Host-defined row
+     *  shape (`ChatSource` on the adapter side) — opaque at wire level. */
+    sources?: unknown[];
+    /** Per-row refs for inline object cards, keyed `<type>:<id>`. */
+    refs?: Record<string, unknown>;
+    /** Raw model id (e.g. 'claude-sonnet-x'). Presence alone triggers the
+     *  client's meta merge; the value itself is not stored. */
+    model?: string;
+    modelLabel?: string;
+    provider?: string;
+    contextWindowMaxTokens?: number;
+    /** Per-message viewport-positioning hint ('top' | 'bottom'). */
+    scrollAnchor?: string;
+    /** SERVER-minted conversation trace id (`chat_conversations.id`),
+     *  echoed on every turn's leading metadata frame. The client never
+     *  generates ids — the first turn of a session goes out id-less, the
+     *  server mints one and echoes it here, and the adapter persists the
+     *  echoed id as its ONLY local state (see
+     *  `chat-conversation-storage.ts` on the consumer side). */
+    conversationId?: string;
+}
+/** Live adaptive-thinking delta. WIRE IS ALREADY DELTA (Anthropic
+ *  thinking_delta slices) — decoders must NOT diff or re-accumulate. */
+export interface ThinkingDeltaFrame {
+    kind: 'thinking-delta';
+    text: string;
+}
+/** Usage frame emitted as a LEADING frame right after Anthropic's
+ *  message_start (stage='start'). */
+export interface UsageStartFrame {
+    kind: 'usage';
+    stage: 'start';
+    input_tokens: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+}
+/** Model preamble prose written BEFORE a tool_use block — emitted as a
+ *  standalone leading frame so it isn't stranded behind the approval
+ *  card (the `\x1E` sentinel is suppressed on tool turns). */
+export interface TextLeadingFrame {
+    kind: 'text-leading';
+    text: string;
+}
+/** Tool invocation failed server-side (proposal persist error,
+ *  validation, ownership denial …). */
+export interface ToolErrorFrame {
+    kind: 'tool_error';
+    toolName?: string;
+    toolUseId?: string;
+    message: string;
+}
+export interface ApprovalRequestField {
+    label: string;
+    value: string;
+}
+/** The model called a write tool; the server persisted a proposal and
+ *  ships a card-ready payload. Shape mirrors the hub's `onToolUse`
+ *  return in `lib/data/doc-chat-utils.ts`. */
+export interface ApprovalRequestFrame {
+    kind: 'approval_request';
+    proposalId: string;
+    toolName: string;
+    title?: string;
+    fields?: ApprovalRequestField[];
+    preamble?: string | null;
+    args?: Record<string, unknown>;
+    expiresAt?: string;
+    ttlSeconds?: number;
+}
+/** Server-driven post-approve / post-reject frame (confirm-tool route).
+ *  Mirror of the hub's `DecisionResolvedFrame` in
+ *  `lib/data/chat-agent-utils.ts` (tool_name widened to string — the
+ *  known-write-tool whitelist is host-side knowledge). */
+export interface DecisionResolvedFrame {
+    kind: 'decision_resolved';
+    /** The proposal this decision resolved — locates the SOURCE approval
+     *  card so the shell can flip its status + append the receipt. */
+    proposalId: string;
+    ok: boolean;
+    action: 'approved' | 'rejected';
+    tool_name?: string;
+    result?: {
+        ticket_id?: string;
+        status?: string | null;
+        mirror_synced?: boolean;
+    };
+    card?: {
+        type: string;
+        marker: string;
+        ref: unknown;
+    };
+    /** True when the server WILL pipe an auto-continuation turn after
+     *  this frame. */
+    willAutoContinue: boolean;
+    /** Pre-rendered receipt copy from the source strategy's
+     *  `receiptRenderer` — client renders verbatim. */
+    receiptText?: string;
+}
+/** Every leading frame the emitter can produce. */
+export type SseLeadingFrame = StatusThinkingFrame | ChatMetadataFrame | RoutingFrame | ThinkingDeltaFrame | UsageStartFrame | TextLeadingFrame | ToolErrorFrame | ApprovalRequestFrame | DecisionResolvedFrame;
+/** Card/chip emission counts for admin adoption tooling. */
+export interface UsageTelemetry {
+    cards: number;
+    chips: number;
+    sentences: number;
+    answerLen: number;
+}
+/** Trailing usage frame — `\x1F` + JSON, runs to stream end (no
+ *  terminator). `stage: 'display'` is a legacy alias the decoder treats
+ *  identically to `'end'`. */
+export interface SseTrailingUsageFrame {
+    kind: 'usage';
+    stage: 'end' | 'display';
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    hit_rate_pct?: number;
+    telemetry?: UsageTelemetry;
+    /** Cross-call usage breakdown (Haiku rewriter / classifier /
+     *  summarizer + routed-answer attribution). */
+    breakdown?: {
+        haikuRewriter?: {
+            input: number;
+            output: number;
+        };
+        haikuClassifier?: {
+            input: number;
+            output: number;
+        };
+        haikuSummarizer?: {
+            input: number;
+            output: number;
+        };
+        routedAnswer?: RoutedAnswerBreakdown;
+    };
+    /** Gated deep-debug payload (only present when the request carried
+     *  the privileged debug secret). */
+    debug?: Record<string, unknown>;
+}
+//# sourceMappingURL=frames.d.ts.map

package/dist/chat-protocol/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/chat-protocol/frames.ts"],"names":[],"mappings":"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"}