@teaflask/assistant 0.6.0 → 0.7.1

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

@@ -8,28 +8,96 @@ export interface DispatchCall {
     errorText: string | undefined;
     argsText: string;
 }
+/**
+ * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
 }
 export interface SubagentOutcomeCounts {

package/dist/core/thread-dispatch-ledger.js

@@ -0,0 +1,303 @@
+import { dispatchIsPaused, dispatchIsRunning, } from "../contract/dispatches.js";
+import { listThreadDispatches } from "../transport/serving-api.js";
+import { ObservableCell } from "./observable-cell.js";
+const POLL_INTERVAL_MS = 10_000;
+const MAX_CONSECUTIVE_READ_FAILURES = 3;
+const READ_BOUND_MS = 2 * POLL_INTERVAL_MS;
+export const EMPTY_THREAD_DISPATCHES = new Map();
+export function newestRowForSession(map, childSessionId) {
+    let newest;
+    for (const dispatch of map.values()) {
+        if (dispatch.child_session_id !== childSessionId) {
+            continue;
+        }
+        if (newest === undefined || dispatch.ordinal > newest.ordinal) {
+            newest = dispatch;
+        }
+    }
+    return newest;
+}
+export class ThreadDispatchLedger {
+    session;
+    cell = new ObservableCell(null);
+    demands = new Map();
+    timer = null;
+    timerThreadId = null;
+    busy = false;
+    readThreadId = null;
+    pendingThreadId = null;
+    failedThreadId = null;
+    consecutiveFailures = 0;
+    constructor(session) {
+        this.session = session;
+    }
+    settleListeners = new Map();
+    setSettleListener(token, listener) {
+        if (listener === null) {
+            this.settleListeners.delete(token);
+        }
+        else {
+            this.settleListeners.set(token, listener);
+        }
+    }
+    pauseListeners = new Map();
+    setPauseListener(token, listener) {
+        if (listener === null) {
+            this.pauseListeners.delete(token);
+        }
+        else {
+            this.pauseListeners.set(token, listener);
+        }
+    }
+    setDemand(token, demand) {
+        const held = this.demands.get(token);
+        if (demand === null) {
+            if (held === undefined) {
+                return;
+            }
+            this.demands.delete(token);
+        }
+        else {
+            if (held?.threadId === demand.threadId &&
+                held.delegated === demand.delegated &&
+                held.stillMoving === demand.stillMoving &&
+                held.joinKey === demand.joinKey) {
+                return;
+            }
+            this.demands.set(token, demand);
+        }
+        this._reconcile();
+    }
+    noteThreadAnswered(threadId) {
+        if (this.failedThreadId !== threadId || this.consecutiveFailures === 0) {
+            return;
+        }
+        this.failedThreadId = null;
+        this.consecutiveFailures = 0;
+        this._reconcile();
+    }
+    refresh(threadId) {
+        if (!this.busy) {
+            return this._readOnce(threadId);
+        }
+        if (this.followUp === null || this.followUpThreadId !== threadId) {
+            this.followUpThreadId = threadId;
+            this.followUp = (this.flight ?? Promise.resolve()).then(() => {
+                this.followUp = null;
+                this.followUpThreadId = null;
+                return this._readOnce(threadId);
+            });
+        }
+        return this.followUp;
+    }
+    followUp = null;
+    followUpThreadId = null;
+    _reconcile() {
+        let threadId = null;
+        let delegated = false;
+        let stillMoving = false;
+        for (const demand of this.demands.values()) {
+            threadId ??= demand.threadId;
+            delegated ||= demand.delegated;
+            stillMoving ||= demand.stillMoving;
+        }
+        if (this.pendingThreadId !== null && this.pendingThreadId !== threadId) {
+            this.pendingThreadId = null;
+        }
+        if (threadId === null || !delegated) {
+            this._stopTimer();
+            return;
+        }
+        if (this.readThreadId !== threadId) {
+            void this._readOnce(threadId);
+        }
+        if (!stillMoving) {
+            this._stopTimer();
+            return;
+        }
+        if (this.timer === null || this.timerThreadId !== threadId) {
+            this._stopTimer();
+            void this._readOnce(threadId);
+            this.timerThreadId = threadId;
+            this.timer = setInterval(() => {
+                void this._readOnce(threadId);
+            }, POLL_INTERVAL_MS);
+        }
+    }
+    _sameAsCurrent(next) {
+        const current = this.cell.get();
+        if (current?.threadId !== next.threadId) {
+            return false;
+        }
+        if (current.map.size !== next.map.size) {
+            return false;
+        }
+        for (const [ordinal, dispatch] of next.map) {
+            const held = current.map.get(ordinal);
+            if (held?.status !== dispatch.status ||
+                held.error !== dispatch.error ||
+                held.updated_at !== dispatch.updated_at) {
+                return false;
+            }
+        }
+        return true;
+    }
+    _stopTimer() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.timerThreadId = null;
+        }
+    }
+    _readOnce(threadId) {
+        if (this.busy) {
+            if (threadId !== this.readThreadId) {
+                this.pendingThreadId = threadId;
+            }
+            return this.flight ?? Promise.resolve();
+        }
+        this.busy = true;
+        this.readThreadId = threadId;
+        this.generation += 1;
+        const generation = this.generation;
+        let settleFlight;
+        const flight = new Promise((resolve) => {
+            settleFlight = resolve;
+        });
+        this.flight = flight;
+        setTimeout(() => {
+            this._releaseBoundedOutRead(threadId, generation);
+            settleFlight();
+        }, READ_BOUND_MS);
+        void this._read(threadId, generation, settleFlight);
+        return flight;
+    }
+    flight = null;
+    generation = 0;
+    _releaseBoundedOutRead(threadId, generation) {
+        if (generation !== this.generation || !this.busy) {
+            return;
+        }
+        this.generation += 1;
+        this.busy = false;
+        this.flight = null;
+        this._noteReadFailure(threadId);
+        this._replayParkedSwitch();
+    }
+    _noteReadFailure(threadId) {
+        this.consecutiveFailures =
+            this.failedThreadId === threadId ? this.consecutiveFailures + 1 : 1;
+        this.failedThreadId = threadId;
+        if (this.consecutiveFailures >= MAX_CONSECUTIVE_READ_FAILURES &&
+            this.timerThreadId === threadId) {
+            this._stopTimer();
+        }
+        if (this.cell.get()?.threadId !== threadId) {
+            this.readThreadId = null;
+        }
+    }
+    _replayParkedSwitch() {
+        const pending = this.pendingThreadId;
+        this.pendingThreadId = null;
+        if (pending !== null && pending !== this.readThreadId) {
+            void this._readOnce(pending);
+        }
+    }
+    adoptedThrough = 0;
+    async _read(threadId, generation, settleFlight) {
+        const live = () => generation === this.generation;
+        try {
+            const dispatches = await listThreadDispatches(this.session, threadId);
+            const adopts = live() ||
+                (generation > this.adoptedThrough &&
+                    (this.readThreadId === threadId || this.readThreadId === null));
+            if (!adopts) {
+                if (this.failedThreadId === threadId) {
+                    this.failedThreadId = null;
+                    this.consecutiveFailures = 0;
+                }
+                return;
+            }
+            this.readThreadId ??= threadId;
+            this.adoptedThrough = generation;
+            const previous = this.cell.get();
+            const next = {
+                threadId,
+                map: new Map(dispatches.map((dispatch) => [dispatch.ordinal, dispatch])),
+            };
+            if (!this._sameAsCurrent(next)) {
+                this.cell.set(next);
+            }
+            this.failedThreadId = null;
+            this.consecutiveFailures = 0;
+            if (_observedASettle(previous, next)) {
+                _fireEach(this.settleListeners);
+            }
+            if (_observedAPause(previous, next)) {
+                _fireEach(this.pauseListeners);
+            }
+        }
+        catch {
+            if (!live()) {
+                return;
+            }
+            this._noteReadFailure(threadId);
+        }
+        finally {
+            if (live()) {
+                this.busy = false;
+                this.flight = null;
+                settleFlight();
+                this._replayParkedSwitch();
+            }
+        }
+    }
+}
+function _fireEach(listeners) {
+    for (const listener of new Set(listeners.values())) {
+        try {
+            listener();
+        }
+        catch {
+        }
+    }
+}
+function _observedAPause(previous, next) {
+    const comparable = previous?.threadId === next.threadId ? previous : null;
+    for (const [ordinal, dispatch] of next.map) {
+        if (!dispatchIsPaused(dispatch)) {
+            continue;
+        }
+        const held = comparable?.map.get(ordinal);
+        if (held === undefined ||
+            !dispatchIsPaused(held) ||
+            held.updated_at !== dispatch.updated_at) {
+            return true;
+        }
+    }
+    return false;
+}
+function _observedASettle(previous, next) {
+    if (previous?.threadId !== next.threadId) {
+        return false;
+    }
+    for (const [ordinal, dispatch] of next.map) {
+        if (dispatchIsRunning(dispatch)) {
+            continue;
+        }
+        const held = previous.map.get(ordinal);
+        if (held === undefined || dispatchIsRunning(held)) {
+            return true;
+        }
+    }
+    return false;
+}
+const _ledgers = new WeakMap();
+export function threadDispatchLedgerFor(session) {
+    let ledger = _ledgers.get(session);
+    if (ledger === undefined) {
+        ledger = new ThreadDispatchLedger(session);
+        _ledgers.set(session, ledger);
+    }
+    return ledger;
+}

package/dist/core/tool-call-display.d.ts

@@ -1,27 +1,98 @@
+/**
+ * Where a call is in its life. "input-streaming" means the agent is still
+ * writing the arguments, "input-available" means they are complete and the call
+ * is running or waiting for approval, "output-available" means it finished with
+ * a result, and "output-error" means it failed; "denied" means the user didn't
+ * approve it, "cancelled" means it never ran, "refused" means Teaflask declined
+ * it before it reached the tool, and "superseded" means it started but was cut
+ * off when the run restarted, so its result never arrived.
+ */
 export type ToolCallState = "input-streaming" | "input-available" | "output-available" | "output-error" | "denied" | "cancelled" | "refused" | "superseded";
+/**
+ * Server-supplied display details for one tool call, namely its row's label,
+ * icon and view.
+ */
 export interface ToolCallDisplay {
+    /**
+     * A few words the agent wrote saying what the step is for. When present it
+     * is the row's label in every state, followed by a short state word if the
+     * call failed, was not approved, didn't run, was declined or didn't finish.
+     */
     caption?: string;
+    /** The row's label while the call runs, used when there is no caption. */
     progressText?: string;
+    /**
+     * The row's label once the call succeeds, used when there is no caption.
+     */
     completeText?: string;
+    /** The row's label when the call fails, used when there is no caption. */
     errorText?: string;
+    /**
+     * The kind of work the call is, one of TOOL_CALL_ICONS. Any other value
+     * shows the generic icon.
+     */
     icon?: string;
+    /**
+     * The view the server names for this call, as a key and version. A registry
+     * entry under that exact key with the same version is preferred over a
+     * match by tool name; Teaflask's own tools name built-in views with keys
+     * starting `teaflask.`.
+     */
     view?: {
         key: string;
         version: number;
     };
 }
+/**
+ * One tool or action call as a transcript row renders it. A custom `toolRow`
+ * receives it as `view`, and toolCallPresentationOf takes it.
+ */
 export interface ToolCallViewModel {
+    /** The tool's name. For an action, `action__<slug>`. */
     toolName: string;
+    /** Where the call is in its life. See ToolCallState. */
     state: ToolCallState;
+    /** Unique id of the call, when known. */
     toolCallId?: string;
+    /**
+     * The arguments as pretty-printed JSON, or the raw text while it is still
+     * streaming in.
+     */
     input: string;
+    /** The arguments as raw JSON text, exactly as streamed. */
     argsText?: string;
+    /**
+     * The raw result text. Undefined until the call finishes, and withheld for
+     * calls that failed, were not approved, didn't run, were declined or had
+     * their result replaced by a preview.
+     */
     output?: string;
+    /**
+     * True when the result was too large for the agent and was replaced by a
+     * shortened preview. `output` is then withheld.
+     */
     offloaded?: boolean;
+    /** Why the call failed, set when it failed. */
     errorText?: string;
+    /**
+     * Teaflask's reason for declining the call, set only when `state` is
+     * "refused".
+     */
     refusalText?: string;
+    /**
+     * The server's display details for the call (label text, icon, view), when
+     * it sent any.
+     */
     display?: ToolCallDisplay;
+    /**
+     * The JSON Schema of the tool's arguments, when it declared one. Undefined
+     * otherwise, never `{}`.
+     */
     argsSchema?: Record<string, unknown>;
+    /**
+     * The JSON Schema of the tool's successful result, when it declared one.
+     * Undefined otherwise.
+     */
     resultSchema?: Record<string, unknown>;
 }
 export declare function humanizedToolName(name: string): string;

package/dist/core/tool-call-presentation.d.ts

@@ -1,15 +1,48 @@
 import type { ToolCallState, ToolCallViewModel } from "./tool-call-display.js";
 import type { ToolViewRegistry, ToolViewResolution } from "./tool-view.js";
+/**
+ * Every icon kind a tool call row can show: search, file, terminal (running a
+ * command), question (asking the user), memory, delegation (sub-agents),
+ * routine (finding or preparing actions), todo, navigation (opening, reading or
+ * filling in your page) and generic.
+ */
 export declare const TOOL_CALL_ICONS: readonly ["search", "file", "terminal", "question", "memory", "delegation", "routine", "todo", "navigation", "generic"];
+/** One icon kind from TOOL_CALL_ICONS. */
 export type ToolCallIcon = (typeof TOOL_CALL_ICONS)[number];
+/**
+ * Everything needed to render one tool call row, as returned by
+ * toolCallPresentationOf.
+ */
 export interface ToolCallPresentation {
+    /**
+     * The row's label. It is the agent's caption or the server's text when
+     * there is one, else wording built from the tool name and state, such as
+     * "Running create ticket…" or "create ticket failed".
+     */
     headline: string;
+    /**
+     * The icon kind to show; "generic" when the server named none or one this
+     * version doesn't know.
+     */
     icon: ToolCallIcon;
+    /** The call's state. */
     status: ToolCallState;
-    settledSummary: string;
+    /**
+     * The call's running-state label, whatever its actual state. Used for a
+     * sub-agent's line saying what it is doing now.
+     */
     currentWorkLabel: string;
+    /**
+     * The tool views and icons that match the call, and the call they receive.
+     */
     toolView: ToolViewResolution;
 }
+/**
+ * Works out everything needed to render one tool call row: its label, icon,
+ * state, its running-state label and matching tool view. Pass your `toolViews`
+ * registry, and `awaitingDecision: true` while an approval or question tied to
+ * the call is waiting on the user.
+ */
 export declare function toolCallPresentationOf(view: ToolCallViewModel, registry?: ToolViewRegistry, options?: {
     awaitingDecision?: boolean;
 }): ToolCallPresentation;

package/dist/core/tool-call-presentation.js

@@ -23,7 +23,6 @@ export function toolCallPresentationOf(view, registry, options) {
         headline,
         icon: _iconOf(view.display?.icon),
         status: view.state,
-        settledSummary: headline,
         currentWorkLabel: toolRowHeadlineOf({ ...view, state: "input-available" }),
         toolView: {
             views: resolved.views,

package/dist/core/tool-schema-anchors.d.ts

@@ -1,7 +1,13 @@
 import type { AgentSubscriber } from "@ag-ui/client";
 import type { JsonSchema } from "./tool-view.js";
+/**
+ * The JSON Schemas a tool declared. Either field is absent when that schema was
+ * not declared.
+ */
 export interface ToolCallSchemas {
+    /** The JSON Schema of the tool's arguments. */
     argsSchema?: JsonSchema;
+    /** The JSON Schema of the tool's successful result. */
     resultSchema?: JsonSchema;
 }
 export declare const EMPTY_TOOL_SCHEMA_ANCHORS: ReadonlyMap<string, ToolCallSchemas>;