@teaflask/assistant 0.3.0 → 0.7.0

package/dist/core/connection-epoch.d.ts

@@ -13,73 +13,86 @@ import { type ToolCallSchemas } from "./tool-schema-anchors.js";
 import { type AnchoredTurnFailReceipts } from "./turn-failed-anchors.js";
 import { type TurnUsage } from "./turn-usage-anchors.js";
 import { type UserTurnLedger } from "./user-turn-ledger.js";
-export interface MarkerAnchorsSnapshot {
-    /** Resume anchors: message id → the run_resumed marker's raw payload
-     *  (null for payload-less legacy markers), kept as provenance for the
-     *  wire (round, attempt) the key was derived from. Presence
-     *  drives the severance scan (a prior attempt's open calls read as
-     *  interrupted); the divider row it used to drive went with the
-     *  meta-receipt rows. */
+/**
+ * Lookup tables of extra facts the stream reports alongside the messages, keyed
+ * by message id, tool call id or memory id. transcriptRowsOf joins them into
+ * rows; read them directly only for custom rendering.
+ */
+export interface TranscriptMarkers {
+    /**
+     * Ids of messages where an interrupted response was retried. Calls left
+     * unfinished before that point in the same turn show as superseded; the
+     * values are internal and can be ignored.
+     */
     resumeAnchors: ReadonlyMap<string, unknown>;
-    /** Failure-receipt anchors: message id → the receipts of a
-     *  turn that settled failed outside any single tool, rendered after
-     *  the failed run's last message — the failure's durable record. */
+    /**
+     * Failure sentences for turns that failed outside any single tool call,
+     * keyed by the id of the message they are shown next to.
+     */
     turnFailedAnchors: ReadonlyMap<string, AnchoredTurnFailReceipts>;
-    /** Delivery-receipt anchors: message id → the settled
-     *  dispatches the machine-started delivery run pushed — the divider
-     *  naming them renders before that message. */
+    /**
+     * Finished sub-agent results reported by a turn the assistant started on
+     * its own, keyed by the id of that turn's first message.
+     */
     subagentDeliveryAnchors: ReadonlyMap<string, DeliveredResult[]>;
-    /** Errored tool calls, toolCallId → the wire's error text. */
+    /**
+     * Error text for tool calls that failed, keyed by tool call id; an empty
+     * string means the failure is described by the call's result text.
+     */
     toolErrorAnchors: ReadonlyMap<string, string>;
-    /** Cancelled tool calls (they never ran), by toolCallId. */
+    /**
+     * Ids of tool calls cancelled before they ran, for example because the user
+     * stopped the response.
+     */
     toolCancelAnchors: ReadonlySet<string>;
-    /** Refused calls: tool call id → the door's refusal sentence,
-     *  shown as the declined row's reason. */
+    /**
+     * The tool's explanation for each call it declined, keyed by tool call id.
+     */
     toolRefusalAnchors: ReadonlyMap<string, string>;
-    /** Offloaded tool calls (the wire's content is the offloader's
-     *  model-facing replacement, not the tool's output), by toolCallId. */
+    /**
+     * Ids of tool calls whose output was too large and was replaced by a
+     * shortened stand-in.
+     */
     toolOffloadAnchors: ReadonlySet<string>;
-    /** Decision-bearing tool calls: an approval_requested or
-     *  member-answerable tool_execution_requested marker named this
-     *  toolCallId. The placement hold's durable arm — the card stores
-     *  prune at the result and the settle by design, while TVC-014's hold
-     *  window is the turn. OPTIONAL because the snapshot type ships on the
-     *  `./transcript` composition surface — a host-built
-     *  snapshot without the member reads as empty, never breaks. */
+    /**
+     * Ids of tool calls the user was asked to approve or answer a question for.
+     * Treat a missing set as empty.
+     */
     toolDecisionAnchors?: ReadonlySet<string>;
-    /** Denied tool calls: the toolCallIds whose approval a
-     *  member declined — approval_resolved{approved:false} joined to its
-     *  approval_requested's tool_call_id in the resume store's ledger. The
-     *  state ladder's rung above `cancelled` (the stamp the wire gives a
-     *  denial). OPTIONAL for the same reason as toolDecisionAnchors: the
-     *  snapshot type ships on the `./transcript` composition surface, and
-     *  a host-built snapshot without the member reads as empty. */
+    /**
+     * Ids of tool calls whose approval the user declined. Treat a missing set
+     * as empty.
+     */
     toolDenialAnchors?: ReadonlySet<string>;
-    /** Annotated tool calls, toolCallId → the wire's display copy. */
+    /**
+     * Server-supplied captions, status text, icons and tool view references,
+     * keyed by tool call id.
+     */
     toolCallDisplayAnchors: ReadonlyMap<string, ToolCallDisplay>;
-    /** Registered tool schemas, toolCallId → the wire's
-     *  argsSchema / resultSchema. Absent call = no schema declared (or an
-     *  older history) — the view's fields stay `undefined`. */
+    /**
+     * The JSON Schemas declared for each call's arguments and result, keyed by
+     * tool call id; a call with no entry declared none.
+     */
     toolSchemaAnchors: ReadonlyMap<string, ToolCallSchemas>;
-    /** Block timing: block id (messageId/toolCallId) → the
-     *  earliest/latest server timestamps observed for it. Absent block =
-     *  duration unknown, never zero. */
+    /**
+     * Server timestamps for each message and tool call, keyed by message id or
+     * tool call id; a missing entry means the timing is unknown.
+     */
     blockTimingAnchors: ReadonlyMap<string, BlockTiming>;
-    /** Turn usage: turn id → the runtime's own token totals.
-     *  Absent turn = usage unknown; the number hides. */
-    turnUsageAnchors: ReadonlyMap<string, TurnUsage>;
-    /** Memory provenance: durable memory id → the end-user-safe
-     *  write receipt, in stream order. */
+    /**
+     * Every memory the assistant saved in this conversation, keyed by memory
+     * id, in the order saved.
+     */
     memoryProvenanceAnchors: ReadonlyMap<string, MemoryUpdated>;
-    /** Memory attribution: memory id → the assistant prose
-     *  message its footer renders under. A provenance record without an
-     *  attribution renders no footer — old histories degrade, never
-     *  synthesize. */
+    /**
+     * For each saved memory id, the id of the assistant message it is shown
+     * under; a memory with no entry is shown under no message.
+     */
     memoryAttributionAnchors: ReadonlyMap<string, string>;
 }
-/** The anchors' single source of truth is the resume store (it outlives
- *  every epoch); the snapshot re-validates on derivation so a stale shape
- *  degrades to missing rows, never a crash. */
+export interface MarkerAnchorsSnapshot extends TranscriptMarkers {
+    turnUsageAnchors: ReadonlyMap<string, TurnUsage>;
+}
 export declare function markerAnchorsOf(resume: StreamResumeStore): MarkerAnchorsSnapshot;
 export interface ConnectionEpochDeps {
     epochId: number;
@@ -88,30 +101,13 @@ export interface ConnectionEpochDeps {
     streamThreadId: string;
     ledger: UserTurnLedger;
     resume: StreamResumeStore;
-    /** Read fresh at each execution pass — the host's capability wiring
-     *  changes identity with provider re-renders. */
     handlersOf: () => ReadonlyMap<string, ExecutionHandler>;
-    /** The thread-lived approval inbox: pending asks must survive
-     *  this epoch, so the conversation owns it and the epoch borrows it. */
     approvalInbox: ApprovalInbox;
     publishApprovalCards: (cards: readonly ApprovalCardModel[]) => void;
-    /** Every execution-entries snapshot — the store derives the
-     *  member-answerable elicitation cards from it. */
     publishExecutionEntries: (entries: readonly ExecutionEntryModel[]) => void;
-    /** The resume store moved — the store re-derives the anchors snapshot. */
     publishMarkerAnchors: () => void;
-    /** The agent's message list moved — a shallow snapshot per change. */
     publishMessages: (messages: readonly Message[]) => void;
-    /** A replayed or live interrupt_answer_consumed marker: a
-     *  resume already carried this pause's answer into the agent, so the
-     *  pending-decision-gap derivation subtracts the id instead of
-     *  alarming. Store-lived (keyed by run AND round — the row's identity
-     *  is (run_id, round, interrupt_id), and the store matches the round
-     *  against the turn's awaiting_round exactly as the server's
-     *  subtraction does) — the fold must survive epoch turnover. */
     noteInterruptAnswerConsumed: (runId: string, interruptId: string, round: number) => void;
-    /** A non-abort connection failure (transport death or a server
-     *  RUN_ERROR) — the interruption banner's wire. */
     onStreamError: (error: Error) => void;
     refreshLedger: () => Promise<void>;
     onUserMessageInjected: (messageId: string) => void;
@@ -126,11 +122,7 @@ export interface ConnectionEpoch {
     executionInbox: ExecutionInbox;
     threadId: string;
     streamThreadId: string;
-    /** The REST side's door into the inbox: a mutation that
-     *  answers "did visible state change" publishes through this epoch's
-     *  own publisher, which also pokes the driver. */
     withExecutionInbox: (mutate: (inbox: ExecutionInbox) => boolean) => void;
     dispose: () => void;
 }
 export declare function beginConnectionEpoch(deps: ConnectionEpochDeps): ConnectionEpoch;
-//# sourceMappingURL=connection-epoch.d.ts.map

package/dist/core/connection-epoch.js

@@ -20,9 +20,6 @@ import { turnFailedMarkerRecorder, wellFormedFailAnchorsOf, } from "./turn-faile
 import { turnUsageRecorder, wellFormedTurnUsageAnchorsOf, } from "./turn-usage-anchors.js";
 import { messagesRecorder, streamErrorRecorder } from "./messages-cell.js";
 import { userTurnInjector } from "./user-turn-ledger.js";
-/** The anchors' single source of truth is the resume store (it outlives
- *  every epoch); the snapshot re-validates on derivation so a stale shape
- *  degrades to missing rows, never a crash. */
 export function markerAnchorsOf(resume) {
     return {
         resumeAnchors: new Map(resume.resumeAnchors),
@@ -51,11 +48,6 @@ export function beginConnectionEpoch(deps) {
     });
     const approvalInbox = deps.approvalInbox;
     const executionInbox = new ExecutionInbox();
-    // Each published entries snapshot pokes the driver to (re)schedule a
-    // drain — the automatic execution loop — and reaches the store, which
-    // derives the member-answerable elicitation cards from it (the
-    // driver's eligibility filter skips those kinds; the member is their
-    // executor).
     const publishEntries = (entries) => {
         driver.noteEntriesChanged(entries);
         deps.publishExecutionEntries(entries);
@@ -69,8 +61,6 @@ export function beginConnectionEpoch(deps) {
         publishEntries,
         onWorkflowRestarted: deps.onWorkflowRestarted,
     });
-    // Subscription order is behaviour: @ag-ui/client dispatches every
-    // subscriber of an event in attach order.
     const subscriptions = [
         ..._runMarkerSubscriptionsOf(agent, deps),
         ..._toolMarkerSubscriptionsOf(agent, deps),
@@ -98,23 +88,13 @@ export function beginConnectionEpoch(deps) {
                 subscription.unsubscribe();
             }
             driver.dispose();
-            // The store-driven run needs an explicit stop on retire — detach finalizes without a terminal event, the wire
-            // shape every recorder already handles.
             void agent.detachActiveRun().catch(() => undefined);
         },
     };
 }
-/** The run-lifecycle markers: resumption, consumed interrupt answers,
- *  turn failure receipts and subagent delivery dividers. */
 function _runMarkerSubscriptionsOf(agent, deps) {
     return [
         agent.subscribe(resumeMarkerRecorder((runId, messageId, markerValue, markerTimestamp) => {
-            // The resume store arbitrates: one anchor per RESUMPTION, ever
-            // (run id + the payload's own (round, attempt); round-less
-            // legacy rows by their stamped timestamp — the
-            // failed/delivery siblings' posture) — a filtered re-delivery
-            // flushing under a drifted message id records nothing. The anchor
-            // drives severance only; its divider went with the meta-receipt rows.
             if (deps.resume.recordResumeAnchor(runId, messageId, markerValue, markerTimestamp)) {
                 deps.publishMarkerAnchors();
             }
@@ -123,23 +103,17 @@ function _runMarkerSubscriptionsOf(agent, deps) {
             deps.noteInterruptAnswerConsumed(runId, consumed.interruptId, consumed.round);
         })),
         agent.subscribe(turnFailedMarkerRecorder((failedRunId, messageId, position, receipts) => {
-            // The resume store arbitrates: one receipt row per failed run,
-            // ever — a re-delivery can flush under a drifted message id.
             if (deps.resume.recordTurnFailedReceipts(failedRunId, messageId, position, receipts)) {
                 deps.publishMarkerAnchors();
             }
         })),
         agent.subscribe(subagentDeliveryMarkerRecorder((deliveryRunId, messageId, results) => {
-            // The resume store arbitrates: one divider per delivery run,
-            // ever — a re-delivery can flush under a drifted message id.
             if (deps.resume.recordSubagentDelivery(deliveryRunId, messageId, results)) {
                 deps.publishMarkerAnchors();
             }
         })),
     ];
 }
-/** The per-tool-call markers: each records into the resume store and
- *  publishes only when the store's collection identity moved. */
 function _toolMarkerSubscriptionsOf(agent, deps) {
     return [
         agent.subscribe(toolErrorRecorder((toolCallId, errorText) => {
@@ -171,8 +145,6 @@ function _toolMarkerSubscriptionsOf(agent, deps) {
             }
         })),
         agent.subscribe(toolDenialRecorder((marker) => {
-            // Gated on the DENIED half's identity, not the ledger's: an ask
-            // changes nothing the snapshot shows, so it must not repaint.
             const before = deps.resume.toolDenialLedger.denied;
             deps.resume.recordToolDenialMarker(marker);
             if (deps.resume.toolDenialLedger.denied !== before) {
@@ -202,42 +174,10 @@ function _toolMarkerSubscriptionsOf(agent, deps) {
         })),
     ];
 }
-/** Block timing, turn usage and memory provenance/attribution. */
 function _timingAndMemoryMarkerSubscriptionsOf(agent, deps) {
-    // The block-timing recorder's publish coalescer — see its subscriber
-    // below. True while a snapshot publish is already queued behind the
-    // macrotask window, so a burst of boundary events costs one rebuild,
-    // not one per event (and not one per subscriber await — the reason
-    // the window is a timer, not a microtask).
     let timingPublishQueued = false;
     return [
-        agent.subscribe(
-        // Timing is the one recorder here whose trigger is NOT a rare
-        // CUSTOM marker: it fires on every block boundary (~2 per block),
-        // and each firing moves the map (START creates the pair, END
-        // widens it). Publishing per firing would rebuild the whole
-        // twelve-collection snapshot ~2N times over an N-block replay —
-        // quadratic in transcript length — so the STORE write stays
-        // synchronous (the resume store is always current for reconnect
-        // seeding) while the derived-snapshot publish coalesces behind a
-        // MACROTASK window (setTimeout 0). A microtask window does not
-        // work here and must not come back: @ag-ui/client's
-        // defaultApplyEvents dispatches subscribers with one `await` per
-        // subscriber per event, and every await drains the microtask
-        // queue — a queueMicrotask publish fires before the NEXT
-        // SUBSCRIBER of the same event, coalescing nothing. The whole
-        // apply chain for a delivered chunk runs on one macrotask
-        // (concatMap's awaits are all microtasks), so a timer queued at
-        // the first moved boundary absorbs every boundary the chunk
-        // carries. No consumer needs the anchors cell current sooner: the
-        // cell has exactly one subscriber-driven React consumer, and live
-        // elapsed time ticks off the client's own "now", never off
-        // publishes. Change detection is the store's REVISION counter —
-        // the timing map mutates in place (see block-timing-anchors), so
-        // identity cannot be the gate. A post-teardown timer firing is
-        // harmless: publishMarkerAnchors is epoch-guarded and re-seeded
-        // synchronously on epoch swap.
-        blockTimingRecorder((blockId, observedAtMs) => {
+        agent.subscribe(blockTimingRecorder((blockId, observedAtMs) => {
             const before = deps.resume.blockTimingRevision;
             deps.resume.recordBlockTiming(blockId, observedAtMs);
             if (deps.resume.blockTimingRevision === before || timingPublishQueued) {
@@ -264,11 +204,6 @@ function _timingAndMemoryMarkerSubscriptionsOf(agent, deps) {
                     deps.publishMarkerAnchors();
                 }
             },
-            // Attribution publishes synchronously like its provenance
-            // sibling — memory markers are rare (one per real insert), so
-            // the timing coalescer's macrotask window buys nothing here, and
-            // a post-settle arrival must repaint without waiting for another
-            // event (the footer engages on genuinely late markers).
             onMemoryAttributed: (memoryId, messageId) => {
                 const before = deps.resume.memoryAttributionAnchors;
                 deps.resume.recordMemoryAttribution(memoryId, messageId);
@@ -279,8 +214,6 @@ function _timingAndMemoryMarkerSubscriptionsOf(agent, deps) {
         })),
     ];
 }
-/** The stream's own state: the resume cursor, the user-turn ledger, both
- *  inboxes, the message list and stream errors. */
 function _streamStateSubscriptionsOf(agent, deps, inboxes) {
     return [
         agent.subscribe(resumeSnapshotRecorder(() => agent.resumeCursor, deps.resume)),
@@ -290,10 +223,6 @@ function _streamStateSubscriptionsOf(agent, deps, inboxes) {
             onRunSettled: deps.onRunSettled,
         })),
         agent.subscribe(approvalInboxRecorder(inboxes.approvalInbox, deps.publishApprovalCards, () => {
-            // The parked contract's only wire signal is the stream simply
-            // ending; the handler consults REST, and reading isRunning at
-            // that later moment (not now) is what lets it dismiss a
-            // connection that already reconnected.
             deps.onQuietClose(() => agent.isRunning);
         })),
         agent.subscribe(executionInboxRecorder(inboxes.executionInbox, inboxes.publishEntries)),
@@ -301,4 +230,3 @@ function _streamStateSubscriptionsOf(agent, deps, inboxes) {
         agent.subscribe(streamErrorRecorder(deps.onStreamError)),
     ];
 }
-//# sourceMappingURL=connection-epoch.js.map

package/dist/core/consumed-interrupts.d.ts

@@ -3,24 +3,10 @@ export interface ConsumedInterrupt {
     interruptId: string;
     round: number;
 }
-/** The wire is distrusted by contract: a malformed value records
- *  nothing (the gap then alarms, never a crash). The
- *  payload's `family` is deliberately not read: the row-shape contract
- *  names it descriptive, not identity — (run_id, round, interrupt_id)
- *  is the whole fold key, and no client behavior branches on which
- *  signal family carried the answer. */
 export declare function interruptAnswerConsumedPayloadOf(value: unknown): ConsumedInterrupt | null;
-/**
- * Fires once per replayed or live consumption marker, named by the
- * server's own run id (the RUN_STARTED before it — the receipt-anchors
- * posture), so the store keys its consumed sets by run and a marker
- * from a superseded run can never subtract from the newest turn's gap.
- */
 export declare function consumedInterruptRecorder(onConsumed: (runId: string, consumed: ConsumedInterrupt) => void): AgentSubscriber;
 export declare class ConsumedInterruptFold {
     private readonly byRun;
-    /** Records one consumption; returns false when it was already known. */
     note(runId: string, interruptId: string, round: number): boolean;
     idsOf(runId: string | null | undefined, awaitingRound: number | null | undefined): ReadonlySet<string>;
 }
-//# sourceMappingURL=consumed-interrupts.d.ts.map

package/dist/core/consumed-interrupts.js

@@ -1,15 +1,4 @@
-// The consumed-interrupt fold: the stream's
-// interrupt_answer_consumed markers say a resume already carried a pause's
-// answer into the agent, so the id is no longer anyone's to answer — the
-// pending-decision-gap derivation subtracts it instead of alarming. This
-// module narrows the wire and names the run; the class below holds state.
 import { INTERRUPT_ANSWER_CONSUMED_EVENT_NAME, } from "../contract/events.js";
-/** The wire is distrusted by contract: a malformed value records
- *  nothing (the gap then alarms, never a crash). The
- *  payload's `family` is deliberately not read: the row-shape contract
- *  names it descriptive, not identity — (run_id, round, interrupt_id)
- *  is the whole fold key, and no client behavior branches on which
- *  signal family carried the answer. */
 export function interruptAnswerConsumedPayloadOf(value) {
     if (typeof value !== "object" || value === null) {
         return null;
@@ -21,12 +10,6 @@ export function interruptAnswerConsumedPayloadOf(value) {
     }
     return { interruptId: payload.interrupt_id, round: payload.round };
 }
-/**
- * Fires once per replayed or live consumption marker, named by the
- * server's own run id (the RUN_STARTED before it — the receipt-anchors
- * posture), so the store keys its consumed sets by run and a marker
- * from a superseded run can never subtract from the newest turn's gap.
- */
 export function consumedInterruptRecorder(onConsumed) {
     let currentRunId = null;
     return {
@@ -45,31 +28,14 @@ export function consumedInterruptRecorder(onConsumed) {
         },
     };
 }
-// The empty consumed-set the gap derivation reads for a run with no
-// recorded consumption — one frozen instance, so the derivation's
-// inputs stay reference-stable across publishes.
 const _NO_CONSUMED_IDS = new Set();
-// The consumed-interrupt fold, keyed by the server's run id
-// and, inside each run, by the consumed pause's round — the row's own
-// identity, (run_id, round, interrupt_id), matched against the turn's
-// awaiting_round exactly like the server's subtraction, so a consumed
-// answer can never subtract a later pause's id. A resume already
-// carried these answers into the agent, so the gap derivation
-// subtracts them instead of alarming. Store-lived on purpose (an
-// epoch swap must not forget a consumption the wire already proved)
-// and bounded: runs are pruned oldest-first past a small cap, since
-// only the newest turn's run is ever read.
 export class ConsumedInterruptFold {
     byRun = new Map();
-    /** Records one consumption; returns false when it was already known. */
     note(runId, interruptId, round) {
         let byRound = this.byRun.get(runId);
         if (byRound === undefined) {
             byRound = new Map();
             this.byRun.set(runId, byRound);
-            // Bounded by pruning whole runs oldest-first (Map preserves
-            // insertion order): only the newest turn's run is ever read, so
-            // anything past a handful of runs is dead weight.
             while (this.byRun.size > 8) {
                 const oldest = this.byRun.keys().next().value;
                 if (oldest === undefined) {
@@ -96,4 +62,3 @@ export class ConsumedInterruptFold {
         return this.byRun.get(runId)?.get(awaitingRound) ?? _NO_CONSUMED_IDS;
     }
 }
-//# sourceMappingURL=consumed-interrupts.js.map