@teaflask/assistant 0.3.0 → 0.7.0

package/dist/core/subagent-rows.d.ts

@@ -1,60 +1,105 @@
 export declare const DISPATCH_SUBAGENT_TOOL_NAME = "dispatch_subagent";
-/** One dispatch tool call, normalized from either tree's row shape by the
- *  caller — the dashboard's status union and the package's state union
- *  name the same facts differently, so each tree adapts its own. */
 export interface DispatchCall {
     toolCallId: string;
-    /** The call settled on the wire: a result or failure was recorded. */
     settled: boolean;
     failed: boolean;
     cancelled: boolean;
     result: string | undefined;
-    /** The wire's failure sentence, present only on failed calls — a
-     *  dispatcher failure's only explanation, since its result is prose,
-     *  never a receipt. (A door REFUSAL never reaches this module:
-     *  the projection keeps a refused dispatch out of the grouping,
-     *  because no child exists.) */
     errorText: string | undefined;
-    /** The raw streamed arguments JSON text — the label fallback while the
-     *  receipt hasn't landed. */
     argsText: string;
 }
-/** The dispatch receipt as the tool result carries it (the backend's
- *  DispatchReceipt, read leniently — a truncated result or a failure
- *  sentence parses to null fields, never throws). The wire's settled.status collapses to
- *  a boolean right here, so no surface ever compares status words. */
+/**
+ * The sub-agent tool's immediate reply confirming a dispatch, parsed. It is not
+ * the sub-agent's result, which arrives later in its own turn.
+ */
 export interface DispatchReceipt {
+    /**
+     * launched means a new sub-agent was started, attached means the same task
+     * was re-issued and joined the sub-agent already working on it, and
+     * already_settled means that sub-agent had already finished, with its
+     * outcome in `settled`.
+     */
     outcome: "launched" | "attached" | "already_settled";
+    /**
+     * The sub-agent's number within the conversation, counting from 0; the same
+     * number identifies it in DeliveredResult.ordinal.
+     */
     ordinal: number;
+    /**
+     * A short excerpt of the task given to the sub-agent. Can be empty when the
+     * stored reply was cut short.
+     */
     label: string;
+    /**
+     * The id of the sub-agent's own session. Null when the stored reply was cut
+     * short.
+     */
     childSessionId: string | null;
+    /**
+     * The finished sub-agent's outcome (whether it failed, plus an optional
+     * note) when outcome is already_settled; null otherwise.
+     */
     settled: {
         failed: boolean;
         note: string | null;
     } | null;
 }
+/** One sub-agent in a group of dispatches. */
 export interface SubagentGroupEntry {
+    /** The id of the tool call that dispatched this sub-agent. */
     toolCallId: string;
+    /**
+     * The dispatch's confirmation. Null until it arrives, or when the dispatch
+     * failed.
+     */
     receipt: DispatchReceipt | null;
-    /** The parent-authored label: the receipt's when it landed, else a
-     *  best-effort read of the streamed task text. */
+    /**
+     * A short excerpt of the sub-agent's task, read from the confirmation or,
+     * before it arrives, from the task text still streaming. Null when nothing
+     * readable is available yet.
+     */
     label: string | null;
-    /** Still working, as far as the wire alone can tell — a ledger join
-     *  (where the surface has one) refines this. */
+    /**
+     * True while the sub-agent is still working as of the package's latest
+     * successful check, and false once a check has seen it finish, whether or
+     * not the built-in transcript is on screen; before any check lands, or for
+     * a sub-agent whose confirmation never arrived, it reads as the dispatch
+     * reply last showed it. The package re-checks the conversation's sub-agents
+     * while any is unfinished and the checks keep succeeding; a
+     * subagent-delivery row then reports the result.
+     */
     running: boolean;
+    /**
+     * True when the dispatch failed, or when the dispatch's confirmation or the
+     * package's latest successful check reports that the sub-agent failed; a
+     * failure no check has seen yet reads false.
+     */
     failed: boolean;
+    /**
+     * True when the dispatch was cancelled or abandoned by a retry; the
+     * built-in UI labels this "interrupted".
+     */
     cancelled: boolean;
-    /** The row's explanation: the settled receipt's note, or a failed
-     *  call's failure sentence. A ledger join (where the surface has one)
-     *  may outrank it. */
+    /**
+     * An explanation to show beside the entry: why the dispatch failed, why the
+     * sub-agent failed, or the note its confirmation carried for a sub-agent
+     * that had already finished. Null when there is none; a sub-agent that
+     * finishes successfully while you watch leaves it null.
+     */
     note: string | null;
 }
+/**
+ * Consecutive sub-agent dispatches shown as one group, such as "Running 3
+ * subagents".
+ */
 export interface SubagentGroupRow {
+    /** Identifies a sub-agent group row. */
     kind: "subagent-group";
+    /** Stable unique key for this row, suitable as a React list key. */
     key: string;
+    /** The dispatched sub-agents, in the order they were dispatched. */
     entries: SubagentGroupEntry[];
 }
-/** The outcome tallies a group's summary line and trigger icon read. */
 export interface SubagentOutcomeCounts {
     running: number;
     failed: number;
@@ -66,43 +111,8 @@ export declare function subagentOutcomeCountsOf(entries: readonly {
     failed: boolean;
     cancelled: boolean;
 }[]): SubagentOutcomeCounts;
-/**
- * The group's summary line — the feature's most visible sentence, shared
- * so the dashboard and the widget can never phrase it differently. Every
- * settled outcome survives collapse: failures and interruptions ride the
- * suffix, and "Ran" counts only the calls that actually ran — a cancelled
- * dispatch never did, and a severed one's receipt never landed. The
- * suffix word is "interrupted", the word the entry pills already wear
- * for both shapes — never "cancelled", which would assert a
- * cancellation nobody performed on a retry-severed call.
- * (String() wrappers throughout, satisfying the package's
- * template-expression lint.)
- */
 export declare function subagentGroupHeadlineOf(counts: SubagentOutcomeCounts): string;
-/**
- * Collapse consecutive dispatch calls into group rows, leaving every
- * other row untouched. Grouping is strictly adjacent within the given
- * rows (one message's): parallel dispatches share one assistant turn and
- * read as one delegation moment; anything between two dispatches splits
- * them into two honest moments.
- */
 export declare function withSubagentGroups<Row>(rows: readonly Row[], asDispatchCall: (row: Row) => DispatchCall | null, keyOf: (row: Row) => string): (Row | SubagentGroupRow)[];
-/**
- * The receipt out of a dispatch call's result text: null for failure
- * sentences, garbage, and results still streaming. A truncated receipt
- * (the transcript store's overflow clip) recovers what its surviving
- * prefix carries — the backend orders outcome/ordinal/label first for
- * exactly this read.
- */
 export declare function dispatchReceiptOf(result: string | undefined): DispatchReceipt | null;
-/**
- * The parent-authored task as a label while no receipt exists yet: read
- * from the streamed arguments, whitespace-collapsed and clipped like the
- * ledger's excerpt. Tolerant of mid-stream JSON — a partial "task" string
- * still reads.
- */
 export declare function taskExcerptOf(argsText: string): string | null;
-/** The parent-authored task exactly as dispatched, unclipped — the
- *  child's opening brief. Tolerant of mid-stream JSON like the excerpt. */
 export declare function dispatchedTaskOf(argsText: string): string | null;
-//# sourceMappingURL=subagent-rows.d.ts.map

package/dist/core/subagent-rows.js

@@ -1,11 +1,4 @@
-// The transcript's subagent grouping: consecutive
-// dispatch_subagent tool calls inside one assistant message collapse into
-// one "Running N subagents" group row, each dispatch read from its
-// receipt. Pure and import-free; public via ./transcript, which the
-// dashboard imports rather than keeping a fork.
 export const DISPATCH_SUBAGENT_TOOL_NAME = "dispatch_subagent";
-/** The stored label's bound, mirrored from the ledger's question_excerpt
- *  clip — a streamed-args fallback must never out-length the real label. */
 const MAX_LABEL_CHARS = 200;
 export function subagentOutcomeCountsOf(entries) {
     let running = 0;
@@ -24,18 +17,6 @@ export function subagentOutcomeCountsOf(entries) {
     }
     return { running, failed, cancelled, total: entries.length };
 }
-/**
- * The group's summary line — the feature's most visible sentence, shared
- * so the dashboard and the widget can never phrase it differently. Every
- * settled outcome survives collapse: failures and interruptions ride the
- * suffix, and "Ran" counts only the calls that actually ran — a cancelled
- * dispatch never did, and a severed one's receipt never landed. The
- * suffix word is "interrupted", the word the entry pills already wear
- * for both shapes — never "cancelled", which would assert a
- * cancellation nobody performed on a retry-severed call.
- * (String() wrappers throughout, satisfying the package's
- * template-expression lint.)
- */
 export function subagentGroupHeadlineOf(counts) {
     const nounOf = (count) => (count === 1 ? "subagent" : "subagents");
     const suffixParts = [];
@@ -58,13 +39,6 @@ export function subagentGroupHeadlineOf(counts) {
     const ranCount = counts.total - counts.cancelled;
     return `Ran ${String(ranCount)} ${nounOf(ranCount)}${suffix}`;
 }
-/**
- * Collapse consecutive dispatch calls into group rows, leaving every
- * other row untouched. Grouping is strictly adjacent within the given
- * rows (one message's): parallel dispatches share one assistant turn and
- * read as one delegation moment; anything between two dispatches splits
- * them into two honest moments.
- */
 export function withSubagentGroups(rows, asDispatchCall, keyOf) {
     const out = [];
     let group = null;
@@ -89,18 +63,9 @@ export function withSubagentGroups(rows, asDispatchCall, keyOf) {
 }
 function _entryOf(call) {
     const receipt = dispatchReceiptOf(call.result);
-    // A landed receipt outranks the wire's call status: the dispatch tool
-    // answers immediately (the receipt is never the report), so a settled
-    // call whose receipt says "launched" names a child still working.
-    // already_settled means the child settled BY DEFINITION: a truncated
-    // receipt loses its settled payload (and its child_session_id, so no
-    // ledger join can correct it) — without the outcome check a coworker
-    // that already failed would spin forever.
     const stillDispatched = receipt !== null
         ? receipt.settled === null && receipt.outcome !== "already_settled"
         : !call.settled;
-    // A truncated receipt can carry an EMPTY label — fall through to the
-    // streamed task text rather than rendering a blank row.
     const receiptLabel = receipt !== null && receipt.label !== "" ? receipt.label : null;
     return {
         toolCallId: call.toolCallId,
@@ -112,13 +77,6 @@ function _entryOf(call) {
         note: receipt?.settled?.note ?? (call.failed ? (call.errorText ?? null) : null),
     };
 }
-/**
- * The receipt out of a dispatch call's result text: null for failure
- * sentences, garbage, and results still streaming. A truncated receipt
- * (the transcript store's overflow clip) recovers what its surviving
- * prefix carries — the backend orders outcome/ordinal/label first for
- * exactly this read.
- */
 export function dispatchReceiptOf(result) {
     if (result === undefined || result === "") {
         return null;
@@ -151,12 +109,6 @@ export function dispatchReceiptOf(result) {
         settled: _settledOf(record.settled),
     };
 }
-/**
- * The parent-authored task as a label while no receipt exists yet: read
- * from the streamed arguments, whitespace-collapsed and clipped like the
- * ledger's excerpt. Tolerant of mid-stream JSON — a partial "task" string
- * still reads.
- */
 export function taskExcerptOf(argsText) {
     const task = dispatchedTaskOf(argsText);
     if (task === null) {
@@ -165,8 +117,6 @@ export function taskExcerptOf(argsText) {
     const collapsed = task.split(/\s+/).filter(Boolean).join(" ");
     return collapsed === "" ? null : collapsed.slice(0, MAX_LABEL_CHARS);
 }
-/** The parent-authored task exactly as dispatched, unclipped — the
- *  child's opening brief. Tolerant of mid-stream JSON like the excerpt. */
 export function dispatchedTaskOf(argsText) {
     try {
         const parsed = JSON.parse(argsText);
@@ -184,9 +134,6 @@ export function dispatchedTaskOf(argsText) {
 function _isOutcome(value) {
     return (value === "launched" || value === "attached" || value === "already_settled");
 }
-// The wire's settled-status words as data, not comparisons — identifier
-// keys on purpose: status vocabulary is compared only inside lib/status,
-// and this seam collapses it to a boolean instead.
 const _SETTLED_STATUS_FAILED = {
     succeeded: false,
     failed: true,
@@ -196,11 +143,6 @@ function _settledOf(value) {
         return null;
     }
     const record = value;
-    // Own-key lookup only: a bare record read reaches Object.prototype, so
-    // an unrecognized status word like "constructor" would come back
-    // truthy instead of falling to the lenient-parse null. (The long form,
-    // not Object.hasOwn — the lib-es6 spelling the deleted dashboard fork
-    // imposed; kept because changing it buys nothing.)
     const status = String(record.status);
     const failed = Object.prototype.hasOwnProperty.call(_SETTLED_STATUS_FAILED, status)
         ? _SETTLED_STATUS_FAILED[status]
@@ -211,9 +153,6 @@ function _settledOf(value) {
     const note = record.note;
     return { failed, note: typeof note === "string" ? note : null };
 }
-// The truncation-proof read, mirrored from the backend's receipt prefix
-// law: compact JSON in declaration order, outcome and ordinal always
-// inside the surviving prefix.
 const _TRUNCATED_RECEIPT_PREFIX = /^\{"outcome":"(launched|attached|already_settled)","ordinal":(\d+)(?:,"label":"((?:[^"\\]|\\.)*))?/;
 function _receiptFromTruncatedPrefix(result) {
     const match = _TRUNCATED_RECEIPT_PREFIX.exec(result);
@@ -224,8 +163,6 @@ function _receiptFromTruncatedPrefix(result) {
     if (!_isOutcome(outcome)) {
         return null;
     }
-    // The label group may be absent on a very short prefix; typed as
-    // possibly-undefined explicitly rather than trusting the index read.
     const labelBody = match[3];
     return {
         outcome,
@@ -240,8 +177,6 @@ function _unescaped(jsonStringBody) {
         return JSON.parse(`"${jsonStringBody}"`);
     }
     catch {
-        // A prefix cut mid-escape: drop the dangling backslash and try once
-        // more — better a readable label than none.
         try {
             return JSON.parse(`"${jsonStringBody.replace(/\\$/, "")}"`);
         }
@@ -250,4 +185,3 @@ function _unescaped(jsonStringBody) {
         }
     }
 }
-//# sourceMappingURL=subagent-rows.js.map

package/dist/core/surface-registry.js

@@ -1,34 +1,12 @@
-// The yield signal: a page-wide registry of mounted assistant chromes, so
-// the always-present companion surface stands down automatically when a
-// full surface is already showing — the customer never configures routes.
-// Module-scoped, not React context: the companion and an <AssistantPage/>
-// may live under different provider instances, and detection must cross
-// the tree. The data-tf-assistant DOM attribute is no signal (a closed
-// palette keeps its dialog root mounted); surfaces announce themselves
-// here, the palette only while open. SSR-safe by construction: nothing
-// touches window, registration happens only inside browser effects, so the
-// server sees the frozen all-false snapshot. Never register at render time.
 import { closeCompanionDrawer } from "./companion-drawer-flag.js";
 const NO_SURFACES = Object.freeze({
     fullSurfaceMounted: false,
     transientOpen: false,
 });
-/**
- * Tracks which chromes are announced and derives a presence snapshot — the
- * useSyncExternalStore subscribe/getSnapshot pair. The snapshot object is
- * replaced only when the derived booleans change, so no-op registrations
- * (a second page, StrictMode's double mount) neither swap nor notify.
- * Registrations are unique tokens, not per-kind flags, so any interleaving
- * of register/unregister resolves correctly.
- */
 export class AssistantSurfaceRegistry {
     tokens = new Set();
     listeners = new Set();
     snapshot = NO_SURFACES;
-    /** Returns the matching unregister; calling it twice is a no-op. A
-     *  full surface taking the floor also closes the companion drawer for
-     *  good — leaving that surface by hand lands on the bare mark; a
-     *  transient chrome (the palette) never touches the flag. */
     register(kind) {
         if (kind === "full-surface") {
             closeCompanionDrawer();
@@ -57,8 +35,6 @@ export class AssistantSurfaceRegistry {
             return;
         }
         this.snapshot = next;
-        // Notify a copy: a listener that unsubscribes itself (or a sibling)
-        // mid-notify must not starve the rest of this round's delivery.
         for (const listener of [...this.listeners]) {
             listener();
         }
@@ -78,4 +54,3 @@ export class AssistantSurfaceRegistry {
     }
 }
 export const assistantSurfaceRegistry = new AssistantSurfaceRegistry();
-//# sourceMappingURL=surface-registry.js.map

package/dist/core/suspension-queue.js

@@ -1,37 +1,12 @@
-// The suspension slot's queue, pure of React: which decisions
-// are suspended on the member, in what order. A decision — an approval or
-// an ask_user question — is IN the queue exactly while it is actionable or
-// its submit is in flight; answered, stale and withdrawn ones never enter
-// (the transcript's quiet settled lines went with the meta-receipt rows;
-// the card footer and the row's state pill are the settled record).
-/** The queue identity of one decision — interrupt ids are the contract's
- *  opaque per-pause keys, unique across both families on the wire; the
- *  kind prefix keeps the key total even against a degenerate stream. */
 export function decisionKeyOf(decision) {
     return `${decision.kind}:${decision.card.interruptId}`;
 }
-// THE pending-decision predicate — the one spelling of which card statuses
-// count as "still waiting on the human", per family. Three consumers are
-// load-bearing in tandem: the row's "Needs input" pill, this queue, and
-// the FOLD's default openness (_groupAwaitsDecision, activity-rail.tsx) —
-// a fold holds itself open while a member awaits the decision and releases
-// when it settles. The ROW's placement hold is deliberately not a consumer:
-// it ends with the TURN, so it keys on the durable decision
-// anchor (the row's decisionBearing derivation, tool-call-rows.tsx), never
-// awaiting.
 export function approvalAwaitsMember(card) {
     return card.status.kind === "actionable" || card.status.kind === "submitting";
 }
 export function elicitationAwaitsMember(card) {
     return card.status === "actionable" || card.status === "submitting";
 }
-/**
- * The deterministic queue: ordered by where each decision's operation
- * arose in the transcript (the anchoring call's row index; orphans —
- * decisions whose call never streamed — go last), then approvals before
- * questions on an exact tie, then each family's own arrival order (the
- * inboxes preserve stream order, and the sort is stable over it).
- */
 export function suspensionQueueOf(approvals, elicitations, rowIndexByToolCallId) {
     const pending = [
         ...approvals
@@ -56,9 +31,6 @@ export function suspensionQueueOf(approvals, elicitations, rowIndexByToolCallId)
     })
         .map((entry) => entry.decision);
 }
-/** The pager cursor, clamped into the live queue: resolving the current
- *  decision keeps the position, so the next decision becomes current;
- *  a shrunken queue never strands the cursor past its end. */
 export function clampedCursorOf(cursor, queueLength) {
     if (queueLength <= 0) {
         return 0;
@@ -72,4 +44,3 @@ function _rowIndexOf(decision, rowIndexByToolCallId) {
     }
     return rowIndexByToolCallId.get(toolCallId) ?? Number.POSITIVE_INFINITY;
 }
-//# sourceMappingURL=suspension-queue.js.map

package/dist/core/tail-slot-pool.js

@@ -1,40 +1,12 @@
-// The live-tail budget. This is the sole copy:
-// the dashboard's forked twin (and the parity test that held the two to
-// one semantics) retired with the plan-run surface, the only dashboard
-// host that ever tailed. Dependency-free on purpose: the widget's
-// drill-in panel instantiates it with capacity 1 (one child stream
-// beside the held-open parent stream and the dispatches poll).
-// Each live tail is a full replay-then-tail SSE stream held open until
-// the child settles, on the SAME API origin as the parent's own stream —
-// and browsers cap HTTP/1.1 at six connections per origin. Three tails
-// plus the parent stream leaves headroom for the dispatches poll and
-// every ordinary read, whatever transport terminates the edge.
 const MAX_LIVE_TAILS = 3;
-/**
- * The live-tail budget. Consumers lease a slot by their OWN identity —
- * on this side the drill-in panel leases by its useId, one lease per
- * panel, never the child session id (two surfaces drilled into the same
- * child are two streams, and a shared key would collapse them into one
- * holder whose first release kills the survivor's tail) — idempotently,
- * so StrictMode's double effect is safe; the lease is released when the
- * stream ends or the panel closes. A consumer that finds the pool full
- * waits in arrival order: release() promotes the oldest waiter BEFORE
- * announcing, so a freed slot is genuinely handed on — a lease effect
- * only runs once per want-lifetime, and the promoted consumer learns it
- * holds through the store subscription, never through a re-run.
- */
 export class TailSlotPool {
     capacity;
     holders = new Set();
-    // Denied leases, in arrival order. A waiter leaves the queue when its
-    // row stops wanting (release covers both roles).
     waiters = [];
     listeners = new Set();
     constructor(capacity = MAX_LIVE_TAILS) {
         this.capacity = capacity;
     }
-    /** An external-store subscription (useSyncExternalStore's shape), so a
-     *  row re-reads its lease when any acquire/release moves the pool. */
     subscribe = (listener) => {
         this.listeners.add(listener);
         return () => {
@@ -42,9 +14,6 @@ export class TailSlotPool {
         };
     };
     holds = (leaseId) => this.holders.has(leaseId);
-    /** Whether this lease is queued behind a full pool — asked and DENIED,
-     *  never merely not-yet-asked: the distinction any waiting copy must
-     *  key on (an un-asked lease is not contention). */
     waiting = (leaseId) => this.waiters.includes(leaseId);
     acquire(leaseId) {
         if (this.holders.has(leaseId)) {
@@ -53,8 +22,6 @@ export class TailSlotPool {
         if (this.holders.size >= this.capacity) {
             if (!this.waiters.includes(leaseId)) {
                 this.waiters.push(leaseId);
-                // Announce the enqueue: a denied consumer's snapshot must be
-                // able to say "waiting", not just "not holding".
                 this._emit();
             }
             return false;
@@ -71,8 +38,6 @@ export class TailSlotPool {
         if (!this.holders.delete(leaseId)) {
             return;
         }
-        // Hand the freed slot on before announcing: by the time subscribers
-        // re-read their snapshots, the promoted row already holds.
         const promoted = this.waiters.shift();
         if (promoted !== undefined) {
             this.holders.add(promoted);
@@ -85,4 +50,3 @@ export class TailSlotPool {
         }
     }
 }
-//# sourceMappingURL=tail-slot-pool.js.map