@teaflask/assistant 0.6.0 → 0.7.0

package/dist/core/receipt-anchors.d.ts

@@ -1,6 +1,15 @@
 import type { AgentSubscriber } from "@ag-ui/client";
+/**
+ * Notice sentences attached to one message, split by whether they are shown
+ * before or after it.
+ */
 export interface AnchoredReceipts {
+    /**
+     * Sentences shown before the message. The package places failure notices
+     * after the message, so this is normally empty.
+     */
     before: string[];
+    /** Sentences shown after the message. */
     after: string[];
 }
 export declare function receiptOf(value: unknown): string | null;

package/dist/core/segment-timing.d.ts

@@ -1,13 +1,36 @@
+/**
+ * When a message or tool call started and ended, by the server's clock in
+ * milliseconds since the Unix epoch.
+ */
 export interface BlockTiming {
+    /** The earliest server timestamp seen for it, or null when unknown. */
     startedAtMs: number | null;
+    /**
+     * The latest server timestamp seen for it, or null when unknown. Equals
+     * startedAtMs until its end arrives.
+     */
     settledAtMs: number | null;
 }
+/**
+ * A duration that is either unknown (hide it) or measured in milliseconds;
+ * render a measured value under 1000 as "<1s" rather than "0s".
+ */
 export type SegmentDuration = {
     kind: "unknown";
 } | {
     kind: "measured";
     durationMs: number;
 };
+/**
+ * How long the given blocks took together, from the earliest to the latest
+ * server timestamp among them, or unknown when none has a timestamp.
+ */
 export declare function settledFoldDurationOf(members: readonly BlockTiming[]): SegmentDuration;
 export declare function durationLabelOf(durationMs: number): string;
+/**
+ * Time elapsed from the earliest server timestamp among the given blocks to
+ * `nowMs` (milliseconds since the Unix epoch), or unknown when none has a
+ * timestamp. Passing Date.now() includes any difference between the device
+ * clock and the server clock.
+ */
 export declare function activeFoldElapsedOf(members: readonly BlockTiming[], nowMs: number): SegmentDuration;

package/dist/core/subagent-delivery-anchors.d.ts

@@ -1,7 +1,14 @@
 import type { AgentSubscriber } from "@ag-ui/client";
+/** One finished sub-agent whose result a turn reports. */
 export interface DeliveredResult {
+    /**
+     * The sub-agent's number within the conversation, matching
+     * DispatchReceipt.ordinal of its dispatch.
+     */
     ordinal: number;
+    /** A short excerpt of the task the sub-agent was given. */
     label: string;
+    /** True when the sub-agent succeeded, false when it failed. */
     succeeded: boolean;
 }
 export declare const EMPTY_SUBAGENT_DELIVERY_ANCHORS: ReadonlyMap<string, DeliveredResult[]>;

package/dist/core/subagent-ledger-join.js

@@ -0,0 +1,176 @@
+import { dispatchFailed, dispatchIsPaused, dispatchIsRunning, } from "../contract/dispatches.js";
+import { subagentIdentityTokenOf } from "./agent-identity.js";
+import { DISPATCH_SUBAGENT_TOOL_NAME, dispatchReceiptOf, withSubagentGroups, } from "./subagent-rows.js";
+export function resolvedSubagentEntryOf(entry, byOrdinal) {
+    const ledger = entry.receipt != null ? byOrdinal.get(entry.receipt.ordinal) : undefined;
+    const ledgerLabel = ledger !== undefined && ledger.label !== "" ? ledger.label : null;
+    const childSessionId = ledger !== undefined && entry.receipt?.childSessionId != null
+        ? entry.receipt.childSessionId
+        : null;
+    const running = ledger !== undefined ? dispatchIsRunning(ledger) : entry.running;
+    const failed = ledger !== undefined ? dispatchFailed(ledger) : entry.failed;
+    return {
+        toolCallId: entry.toolCallId,
+        label: ledgerLabel ?? entry.label,
+        running,
+        failed,
+        cancelled: entry.cancelled,
+        note: (ledger !== undefined && dispatchFailed(ledger) ? ledger.error : null) ??
+            entry.note,
+        childSessionId,
+        identityToken: childSessionId !== null ? subagentIdentityTokenOf(childSessionId) : null,
+        ordinal: entry.receipt?.ordinal ?? null,
+        paused: ledger !== undefined && dispatchIsPaused(ledger),
+        startedAt: ledger !== undefined ? ledger.created_at : null,
+        settledAt: ledger !== undefined && !running ? ledger.updated_at : null,
+    };
+}
+export const RESUME_SUBAGENT_TOOL_NAME = "resume_subagent";
+export function demandInputOfRows(rows) {
+    const entries = [];
+    const resumeResults = [];
+    const deliveredOrdinals = [];
+    for (const row of rows) {
+        if (row.kind === "subagent-group") {
+            entries.push(...row.entries);
+        }
+        else if (row.kind === "tool-call" &&
+            row.toolName === RESUME_SUBAGENT_TOOL_NAME) {
+            resumeResults.push(row.result);
+        }
+        else if (row.kind === "subagent-delivery") {
+            deliveredOrdinals.push(...row.results.map((result) => result.ordinal));
+        }
+    }
+    return { entries, resumeResults, deliveredOrdinals };
+}
+export function demandInputOfMessages(messages, anchors) {
+    const results = new Map();
+    for (const message of messages) {
+        if (message.role === "tool" && typeof message.content === "string") {
+            results.set(message.toolCallId, message.content);
+        }
+    }
+    const calls = [];
+    const resumeResults = [];
+    for (const message of messages) {
+        if (message.role !== "assistant") {
+            continue;
+        }
+        for (const toolCall of message.toolCalls ?? []) {
+            const id = toolCall.id;
+            if (toolCall.function.name === RESUME_SUBAGENT_TOOL_NAME) {
+                resumeResults.push(results.get(id));
+                continue;
+            }
+            if (toolCall.function.name !== DISPATCH_SUBAGENT_TOOL_NAME) {
+                continue;
+            }
+            const failed = anchors.toolErrorAnchors.has(id);
+            const denied = !failed && (anchors.toolDenialAnchors?.has(id) ?? false);
+            const cancelled = !failed && !denied && anchors.toolCancelAnchors.has(id);
+            const refused = !failed && !denied && !cancelled && anchors.toolRefusalAnchors.has(id);
+            if (denied || refused) {
+                continue;
+            }
+            const result = results.get(id);
+            calls.push({
+                toolCallId: id,
+                settled: failed || cancelled || result !== undefined,
+                failed,
+                cancelled,
+                result,
+                errorText: undefined,
+                argsText: toolCall.function.arguments,
+            });
+        }
+    }
+    const entries = withSubagentGroups(calls, (call) => call, (call) => call.toolCallId).flatMap((row) => ("entries" in row ? row.entries : []));
+    const deliveredOrdinals = [];
+    for (const delivered of anchors.subagentDeliveryAnchors.values()) {
+        deliveredOrdinals.push(...delivered.map((result) => result.ordinal));
+    }
+    return { entries, resumeResults, deliveredOrdinals };
+}
+function aResumeAwaitsLedgerTruth(resumeResults, ledger) {
+    return resumeResults.some((result) => {
+        const receipt = dispatchReceiptOf(result);
+        if (receipt === null || receipt.outcome === "already_settled") {
+            return false;
+        }
+        const dispatched = ledger.get(receipt.ordinal);
+        return dispatched === undefined || dispatchIsRunning(dispatched);
+    });
+}
+function anySubagentStillRunning(entries, ledger) {
+    return entries.some((entry) => entry.receipt != null && resolvedSubagentEntryOf(entry, ledger).running);
+}
+export function dispatchDemandOf(input, byOrdinal) {
+    return {
+        delegated: input.entries.length > 0 ||
+            aResumeAwaitsLedgerTruth(input.resumeResults, EMPTY_BY_ORDINAL),
+        stillMoving: anySubagentStillRunning(input.entries, byOrdinal) ||
+            aResumeAwaitsLedgerTruth(input.resumeResults, byOrdinal),
+    };
+}
+const EMPTY_BY_ORDINAL = new Map();
+export function dispatchJoinKeyOf(input) {
+    const ordinals = new Set();
+    for (const entry of input.entries) {
+        if (entry.receipt !== null) {
+            ordinals.add(entry.receipt.ordinal);
+        }
+    }
+    for (const result of input.resumeResults) {
+        const receipt = dispatchReceiptOf(result);
+        if (receipt !== null) {
+            ordinals.add(receipt.ordinal);
+        }
+    }
+    return [...ordinals].sort((a, b) => a - b).join(",");
+}
+export function staleDeliveredOrdinalsKeyOf(input, byOrdinal) {
+    return [...new Set(input.deliveredOrdinals)]
+        .filter((ordinal) => {
+        const ledgerRow = byOrdinal.get(ordinal);
+        return ledgerRow !== undefined && dispatchIsRunning(ledgerRow);
+    })
+        .sort((a, b) => a - b)
+        .join(",");
+}
+export function withDispatchLedger(rows, byOrdinal) {
+    if (byOrdinal.size === 0) {
+        return rows;
+    }
+    let out = null;
+    for (const [index, row] of rows.entries()) {
+        if (row.kind !== "subagent-group") {
+            continue;
+        }
+        const joined = _joinedGroupRowOf(row, byOrdinal);
+        if (joined !== row) {
+            out ??= [...rows];
+            out[index] = joined;
+        }
+    }
+    return out ?? rows;
+}
+function _joinedGroupRowOf(row, byOrdinal) {
+    let entries = null;
+    for (const [index, entry] of row.entries.entries()) {
+        const resolved = resolvedSubagentEntryOf(entry, byOrdinal);
+        if (resolved.running === entry.running &&
+            resolved.failed === entry.failed &&
+            resolved.note === entry.note) {
+            continue;
+        }
+        entries ??= [...row.entries];
+        entries[index] = {
+            ...entry,
+            running: resolved.running,
+            failed: resolved.failed,
+            note: resolved.note,
+        };
+    }
+    return entries === null ? row : { ...row, entries };
+}

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;
+}