@teaflask/assistant 0.0.0 → 0.6.0

package/dist/core/suspension-queue.js

@@ -0,0 +1,46 @@
+export function decisionKeyOf(decision) {
+    return `${decision.kind}:${decision.card.interruptId}`;
+}
+export function approvalAwaitsMember(card) {
+    return card.status.kind === "actionable" || card.status.kind === "submitting";
+}
+export function elicitationAwaitsMember(card) {
+    return card.status === "actionable" || card.status === "submitting";
+}
+export function suspensionQueueOf(approvals, elicitations, rowIndexByToolCallId) {
+    const pending = [
+        ...approvals
+            .filter(approvalAwaitsMember)
+            .map((card) => ({ kind: "approval", card })),
+        ...elicitations
+            .filter(elicitationAwaitsMember)
+            .map((card) => ({ kind: "elicitation", card })),
+    ];
+    return pending
+        .map((decision, arrival) => ({ decision, arrival }))
+        .sort((a, b) => {
+        const rowA = _rowIndexOf(a.decision, rowIndexByToolCallId);
+        const rowB = _rowIndexOf(b.decision, rowIndexByToolCallId);
+        if (rowA !== rowB) {
+            return rowA - rowB;
+        }
+        if (a.decision.kind !== b.decision.kind) {
+            return a.decision.kind === "approval" ? -1 : 1;
+        }
+        return a.arrival - b.arrival;
+    })
+        .map((entry) => entry.decision);
+}
+export function clampedCursorOf(cursor, queueLength) {
+    if (queueLength <= 0) {
+        return 0;
+    }
+    return Math.min(Math.max(cursor, 0), queueLength - 1);
+}
+function _rowIndexOf(decision, rowIndexByToolCallId) {
+    const toolCallId = decision.card.toolCallId;
+    if (toolCallId === null) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return rowIndexByToolCallId.get(toolCallId) ?? Number.POSITIVE_INFINITY;
+}

package/dist/core/tail-slot-pool.d.ts

@@ -0,0 +1,13 @@
+export declare class TailSlotPool {
+    private readonly capacity;
+    private readonly holders;
+    private readonly waiters;
+    private readonly listeners;
+    constructor(capacity?: number);
+    subscribe: (listener: () => void) => (() => void);
+    holds: (leaseId: string) => boolean;
+    waiting: (leaseId: string) => boolean;
+    acquire(leaseId: string): boolean;
+    release(leaseId: string): void;
+    private _emit;
+}

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

@@ -0,0 +1,52 @@
+const MAX_LIVE_TAILS = 3;
+export class TailSlotPool {
+    capacity;
+    holders = new Set();
+    waiters = [];
+    listeners = new Set();
+    constructor(capacity = MAX_LIVE_TAILS) {
+        this.capacity = capacity;
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    holds = (leaseId) => this.holders.has(leaseId);
+    waiting = (leaseId) => this.waiters.includes(leaseId);
+    acquire(leaseId) {
+        if (this.holders.has(leaseId)) {
+            return true;
+        }
+        if (this.holders.size >= this.capacity) {
+            if (!this.waiters.includes(leaseId)) {
+                this.waiters.push(leaseId);
+                this._emit();
+            }
+            return false;
+        }
+        this.holders.add(leaseId);
+        this._emit();
+        return true;
+    }
+    release(leaseId) {
+        const waiting = this.waiters.indexOf(leaseId);
+        if (waiting !== -1) {
+            this.waiters.splice(waiting, 1);
+        }
+        if (!this.holders.delete(leaseId)) {
+            return;
+        }
+        const promoted = this.waiters.shift();
+        if (promoted !== undefined) {
+            this.holders.add(promoted);
+        }
+        this._emit();
+    }
+    _emit() {
+        for (const listener of [...this.listeners]) {
+            listener();
+        }
+    }
+}

package/dist/core/time-labels.d.ts

@@ -0,0 +1,7 @@
+export declare const RECENT_WINDOW_DAYS = 7;
+export declare function startOfLocalDayMs(now: Date, daysBack: number): number;
+export interface ConversationalTime {
+    label: string;
+    full: string;
+}
+export declare function conversationalTimeOf(iso: string, nowMs?: number): ConversationalTime | null;

package/dist/core/time-labels.js

@@ -0,0 +1,47 @@
+export const RECENT_WINDOW_DAYS = 7;
+const WEEKDAY_LABEL_DAYS_BACK = 6;
+export function startOfLocalDayMs(now, daysBack) {
+    return new Date(now.getFullYear(), now.getMonth(), now.getDate() - daysBack).getTime();
+}
+let recentFormat = null;
+let datedFormat = null;
+let datedWithYearFormat = null;
+let fullFormat = null;
+export function conversationalTimeOf(iso, nowMs = Date.now()) {
+    const parsed = Date.parse(iso);
+    if (Number.isNaN(parsed)) {
+        return null;
+    }
+    const date = new Date(parsed);
+    const now = new Date(nowMs);
+    fullFormat ??= new Intl.DateTimeFormat(undefined, {
+        dateStyle: "long",
+        timeStyle: "short",
+    });
+    const full = fullFormat.format(date);
+    if (parsed >= startOfLocalDayMs(now, WEEKDAY_LABEL_DAYS_BACK)) {
+        recentFormat ??= new Intl.DateTimeFormat(undefined, {
+            weekday: "long",
+            hour: "numeric",
+            minute: "2-digit",
+        });
+        return { label: recentFormat.format(date), full };
+    }
+    if (date.getFullYear() === now.getFullYear()) {
+        datedFormat ??= new Intl.DateTimeFormat(undefined, {
+            month: "short",
+            day: "numeric",
+            hour: "numeric",
+            minute: "2-digit",
+        });
+        return { label: datedFormat.format(date), full };
+    }
+    datedWithYearFormat ??= new Intl.DateTimeFormat(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+    });
+    return { label: datedWithYearFormat.format(date), full };
+}

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

@@ -0,0 +1,11 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+import type { ToolCallDisplay } from "./tool-call-display.js";
+export declare const EMPTY_TOOL_CALL_DISPLAY_ANCHORS: ReadonlyMap<string, ToolCallDisplay>;
+export declare function toolCallDisplayAnchorOf(value: unknown): {
+    toolCallId: string;
+    display: ToolCallDisplay;
+} | null;
+export declare function withToolCallDisplayAnchored(previous: ReadonlyMap<string, ToolCallDisplay>, toolCallId: string, display: ToolCallDisplay): ReadonlyMap<string, ToolCallDisplay>;
+export declare function wellFormedToolCallDisplayAnchorsOf(stored: ReadonlyMap<string, ToolCallDisplay>): ReadonlyMap<string, ToolCallDisplay>;
+export declare function restDisplayAnchorsOf(value: unknown): ReadonlyMap<string, ToolCallDisplay>;
+export declare function toolCallDisplayRecorder(onDisplayAnchored: (toolCallId: string, display: ToolCallDisplay) => void): AgentSubscriber;

package/dist/core/tool-call-display-anchors.js

@@ -0,0 +1,186 @@
+import { TOOL_CALL_ANNOTATED_EVENT_NAME } from "../contract/events.js";
+const DISPLAY_TEXT_MAX_CHARS = 500;
+const TOKEN_MAX_CHARS = 64;
+const VIEW_KEY_MAX_CHARS = 128;
+export const EMPTY_TOOL_CALL_DISPLAY_ANCHORS = new Map();
+export function toolCallDisplayAnchorOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const { tool_call_id: toolCallId, display } = value;
+    if (typeof toolCallId !== "string" || toolCallId === "") {
+        return null;
+    }
+    if (typeof display !== "object" || display === null) {
+        return null;
+    }
+    const { caption, progress_text, complete_text, error_text, icon, view } = display;
+    const narrowed = {};
+    const captionText = _displayTextOf(caption);
+    if (captionText !== undefined) {
+        narrowed.caption = captionText;
+    }
+    const progressText = _displayTextOf(progress_text);
+    if (progressText !== undefined) {
+        narrowed.progressText = progressText;
+    }
+    const completeText = _displayTextOf(complete_text);
+    if (completeText !== undefined) {
+        narrowed.completeText = completeText;
+    }
+    const errorText = _displayTextOf(error_text);
+    if (errorText !== undefined) {
+        narrowed.errorText = errorText;
+    }
+    const iconToken = _tokenOf(icon);
+    if (iconToken !== undefined) {
+        narrowed.icon = iconToken;
+    }
+    const viewRef = _viewRefOf(view);
+    if (viewRef !== undefined) {
+        narrowed.view = viewRef;
+    }
+    if (narrowed.caption === undefined &&
+        narrowed.progressText === undefined &&
+        narrowed.completeText === undefined &&
+        narrowed.errorText === undefined &&
+        narrowed.icon === undefined &&
+        narrowed.view === undefined) {
+        return null;
+    }
+    return { toolCallId, display: narrowed };
+}
+export function withToolCallDisplayAnchored(previous, toolCallId, display) {
+    const existing = previous.get(toolCallId);
+    if (existing === undefined) {
+        const next = new Map(previous);
+        next.set(toolCallId, display);
+        return next;
+    }
+    if ((existing.caption !== undefined || display.caption === undefined) &&
+        (existing.progressText !== undefined ||
+            display.progressText === undefined) &&
+        (existing.completeText !== undefined ||
+            display.completeText === undefined) &&
+        (existing.errorText !== undefined || display.errorText === undefined) &&
+        (existing.icon !== undefined || display.icon === undefined) &&
+        (existing.view !== undefined || display.view === undefined)) {
+        return previous;
+    }
+    const merged = {};
+    const caption = existing.caption ?? display.caption;
+    if (caption !== undefined) {
+        merged.caption = caption;
+    }
+    const progressText = existing.progressText ?? display.progressText;
+    if (progressText !== undefined) {
+        merged.progressText = progressText;
+    }
+    const completeText = existing.completeText ?? display.completeText;
+    if (completeText !== undefined) {
+        merged.completeText = completeText;
+    }
+    const errorText = existing.errorText ?? display.errorText;
+    if (errorText !== undefined) {
+        merged.errorText = errorText;
+    }
+    const icon = existing.icon ?? display.icon;
+    if (icon !== undefined) {
+        merged.icon = icon;
+    }
+    const view = existing.view ?? display.view;
+    if (view !== undefined) {
+        merged.view = view;
+    }
+    const next = new Map(previous);
+    next.set(toolCallId, merged);
+    return next;
+}
+export function wellFormedToolCallDisplayAnchorsOf(stored) {
+    const seeded = new Map();
+    const entries = stored;
+    for (const [toolCallId, display] of entries) {
+        if (typeof toolCallId !== "string" || !_isWellFormedDisplay(display)) {
+            continue;
+        }
+        seeded.set(toolCallId, display);
+    }
+    return seeded;
+}
+export function restDisplayAnchorsOf(value) {
+    const anchors = new Map();
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return anchors;
+    }
+    for (const [toolCallId, display] of Object.entries(value)) {
+        const anchor = toolCallDisplayAnchorOf({
+            tool_call_id: toolCallId,
+            display,
+        });
+        if (anchor !== null) {
+            anchors.set(anchor.toolCallId, anchor.display);
+        }
+    }
+    return anchors;
+}
+export function toolCallDisplayRecorder(onDisplayAnchored) {
+    return {
+        onCustomEvent({ event }) {
+            if (event.name !== TOOL_CALL_ANNOTATED_EVENT_NAME) {
+                return;
+            }
+            const anchor = toolCallDisplayAnchorOf(event.value);
+            if (anchor !== null) {
+                onDisplayAnchored(anchor.toolCallId, anchor.display);
+            }
+        },
+    };
+}
+function _displayTextOf(text) {
+    if (typeof text !== "string" || text.trim() === "") {
+        return undefined;
+    }
+    return text.slice(0, DISPLAY_TEXT_MAX_CHARS);
+}
+function _tokenOf(token) {
+    if (typeof token !== "string" || token.trim() === "") {
+        return undefined;
+    }
+    return token.slice(0, TOKEN_MAX_CHARS);
+}
+function _viewRefOf(view) {
+    if (typeof view !== "object" || view === null) {
+        return undefined;
+    }
+    const { key, version } = view;
+    if (typeof key !== "string" ||
+        key.trim() === "" ||
+        key.length > VIEW_KEY_MAX_CHARS) {
+        return undefined;
+    }
+    if (typeof version !== "number" ||
+        !Number.isInteger(version) ||
+        version < 1) {
+        return undefined;
+    }
+    return { key, version };
+}
+function _isWellFormedDisplay(display) {
+    if (typeof display !== "object" || display === null) {
+        return false;
+    }
+    const { caption, progressText, completeText, errorText, icon, view } = display;
+    const fieldsAreWellTypedOrAbsent = (caption === undefined || typeof caption === "string") &&
+        (progressText === undefined || typeof progressText === "string") &&
+        (completeText === undefined || typeof completeText === "string") &&
+        (errorText === undefined || typeof errorText === "string") &&
+        (icon === undefined || typeof icon === "string") &&
+        (view === undefined || _viewRefOf(view) !== undefined);
+    return (fieldsAreWellTypedOrAbsent &&
+        (caption !== undefined ||
+            progressText !== undefined ||
+            completeText !== undefined ||
+            errorText !== undefined ||
+            icon !== undefined ||
+            view !== undefined));
+}

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

@@ -0,0 +1,28 @@
+export type ToolCallState = "input-streaming" | "input-available" | "output-available" | "output-error" | "denied" | "cancelled" | "refused" | "superseded";
+export interface ToolCallDisplay {
+    caption?: string;
+    progressText?: string;
+    completeText?: string;
+    errorText?: string;
+    icon?: string;
+    view?: {
+        key: string;
+        version: number;
+    };
+}
+export interface ToolCallViewModel {
+    toolName: string;
+    state: ToolCallState;
+    toolCallId?: string;
+    input: string;
+    argsText?: string;
+    output?: string;
+    offloaded?: boolean;
+    errorText?: string;
+    refusalText?: string;
+    display?: ToolCallDisplay;
+    argsSchema?: Record<string, unknown>;
+    resultSchema?: Record<string, unknown>;
+}
+export declare function humanizedToolName(name: string): string;
+export declare function toolRowHeadlineOf(view: ToolCallViewModel): string;

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

@@ -0,0 +1,69 @@
+export function humanizedToolName(name) {
+    return name.replace(/[-_]+/g, " ").trim();
+}
+export function toolRowHeadlineOf(view) {
+    const caption = view.display?.caption;
+    if (caption !== undefined) {
+        return _captionedHeadlineOf(caption, view.state);
+    }
+    const displayText = _displayTextFor(view);
+    if (displayText !== undefined) {
+        return displayText;
+    }
+    const name = humanizedToolName(view.toolName);
+    switch (view.state) {
+        case "input-streaming":
+            return name;
+        case "input-available":
+            return `Running ${name}…`;
+        case "output-available":
+            return `Ran ${name}`;
+        case "output-error":
+            return `${name} failed`;
+        case "denied":
+            return `You didn't approve ${name}`;
+        case "cancelled":
+            return `Didn't run ${name}`;
+        case "refused":
+            return `Didn't ${name}`;
+        case "superseded":
+            return `Didn't finish ${name}`;
+    }
+}
+function _captionedHeadlineOf(caption, state) {
+    switch (state) {
+        case "input-streaming":
+        case "input-available":
+        case "output-available":
+            return caption;
+        case "output-error":
+            return `${caption} · failed`;
+        case "denied":
+            return `${caption} · not approved`;
+        case "cancelled":
+            return `${caption} · didn't run`;
+        case "refused":
+            return `${caption} · declined`;
+        case "superseded":
+            return `${caption} · didn't finish`;
+    }
+}
+function _displayTextFor(view) {
+    switch (view.state) {
+        case "input-streaming":
+        case "input-available":
+            return view.display?.progressText;
+        case "output-available":
+            return view.display?.completeText;
+        case "output-error":
+            return view.display?.errorText;
+        case "denied":
+            return undefined;
+        case "cancelled":
+            return undefined;
+        case "refused":
+            return undefined;
+        case "superseded":
+            return undefined;
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { ToolCallState, ToolCallViewModel } from "./tool-call-display.js";
+import type { ToolViewRegistry, ToolViewResolution } from "./tool-view.js";
+export declare const TOOL_CALL_ICONS: readonly ["search", "file", "terminal", "question", "memory", "delegation", "routine", "todo", "navigation", "generic"];
+export type ToolCallIcon = (typeof TOOL_CALL_ICONS)[number];
+export interface ToolCallPresentation {
+    headline: string;
+    icon: ToolCallIcon;
+    status: ToolCallState;
+    settledSummary: string;
+    currentWorkLabel: string;
+    toolView: ToolViewResolution;
+}
+export declare function toolCallPresentationOf(view: ToolCallViewModel, registry?: ToolViewRegistry, options?: {
+    awaitingDecision?: boolean;
+}): ToolCallPresentation;

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

@@ -0,0 +1,139 @@
+import { toolRowHeadlineOf } from "./tool-call-display.js";
+import { toolResultEnvelopePayloadOf } from "./tool-result-envelope.js";
+import { STEP_CAPTION_ARG_KEY, withoutStepCaption } from "./step-caption.js";
+import { resolvedToolViewsOf } from "./tool-view.js";
+export const TOOL_CALL_ICONS = [
+    "search",
+    "file",
+    "terminal",
+    "question",
+    "memory",
+    "delegation",
+    "routine",
+    "todo",
+    "navigation",
+    "generic",
+];
+export function toolCallPresentationOf(view, registry, options) {
+    const headline = toolRowHeadlineOf(view);
+    const resolved = resolvedToolViewsOf(view.display?.view, view.toolName, registry);
+    let call;
+    const awaitingDecision = options?.awaitingDecision === true;
+    return {
+        headline,
+        icon: _iconOf(view.display?.icon),
+        status: view.state,
+        settledSummary: headline,
+        currentWorkLabel: toolRowHeadlineOf({ ...view, state: "input-available" }),
+        toolView: {
+            views: resolved.views,
+            icons: resolved.icons,
+            get call() {
+                call ??= _toolViewCallOf(view, awaitingDecision);
+                return call;
+            },
+        },
+    };
+}
+function _iconOf(token) {
+    if (token !== undefined &&
+        TOOL_CALL_ICONS.includes(token)) {
+        return token;
+    }
+    return "generic";
+}
+function _toolViewCallOf(view, awaitingDecision) {
+    const call = {
+        toolName: view.toolName,
+        toolCallId: view.toolCallId ?? "",
+        status: view.state,
+        awaitingDecision,
+        args: _argsOf(view.argsText ?? view.input),
+    };
+    if (view.output !== undefined) {
+        const output = view.output;
+        call.resultText = output;
+        let structured;
+        const structure = () => (structured ??= _structuredResultOf(output));
+        Object.defineProperties(call, {
+            result: {
+                enumerable: true,
+                configurable: true,
+                get: () => structure().result,
+            },
+            truncated: {
+                enumerable: true,
+                configurable: true,
+                get: () => structure().truncated,
+            },
+        });
+    }
+    if (view.offloaded === true) {
+        call.offloaded = true;
+    }
+    if (view.errorText !== undefined) {
+        call.errorText = view.errorText;
+    }
+    if (view.refusalText !== undefined) {
+        call.refusalText = view.refusalText;
+    }
+    if (view.argsSchema !== undefined) {
+        call.argsSchema = view.argsSchema;
+    }
+    if (view.resultSchema !== undefined) {
+        call.resultSchema = view.resultSchema;
+    }
+    return call;
+}
+function _structuredResultOf(output) {
+    const parsed = _jsonDocumentOf(output);
+    if (parsed === undefined) {
+        return {};
+    }
+    const box = toolResultEnvelopePayloadOf(parsed.document);
+    return box === null ? { truncated: true } : { result: box.payload };
+}
+const EMPTY_ARGS = Object.freeze({});
+function _argsOf(argsText) {
+    const parsed = _jsonDocumentOf(argsText);
+    if (parsed === undefined || !_isRecord(parsed.document)) {
+        return EMPTY_ARGS;
+    }
+    if (!(STEP_CAPTION_ARG_KEY in parsed.document)) {
+        return parsed.document;
+    }
+    return _captionlessArgsOf(parsed.document);
+}
+const _captionlessArgs = new WeakMap();
+function _captionlessArgsOf(document) {
+    const memoized = _captionlessArgs.get(document);
+    if (memoized !== undefined) {
+        return memoized;
+    }
+    const rest = withoutStepCaption(document);
+    const args = Object.keys(rest).length === 0 ? EMPTY_ARGS : rest;
+    _captionlessArgs.set(document, args);
+    return args;
+}
+const JSON_MEMO_MAX_ENTRIES = 512;
+const _jsonMemo = new Map();
+function _jsonDocumentOf(text) {
+    const memoized = _jsonMemo.get(text);
+    if (memoized !== undefined) {
+        return memoized;
+    }
+    try {
+        const parsed = { document: JSON.parse(text) };
+        if (_jsonMemo.size >= JSON_MEMO_MAX_ENTRIES) {
+            _jsonMemo.clear();
+        }
+        _jsonMemo.set(text, parsed);
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function _isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,5 @@
+export declare const EMPTY_TOOL_CANCEL_ANCHORS: ReadonlySet<string>;
+export declare const toolCallCancelledOf: (event: unknown) => boolean;
+export declare const withToolCancelAnchored: (previous: ReadonlySet<string>, toolCallId: string) => ReadonlySet<string>;
+export declare const wellFormedToolCancelAnchorsOf: (stored: ReadonlySet<string>) => ReadonlySet<string>;
+export declare const toolCancelRecorder: (onAnchored: (toolCallId: string) => void) => import("@ag-ui/client").AgentSubscriber;

package/dist/core/tool-cancel-anchors.js

@@ -0,0 +1,7 @@
+import { toolFlagAnchorsOf } from "./tool-flag-anchors.js";
+const anchors = toolFlagAnchorsOf("cancelled");
+export const EMPTY_TOOL_CANCEL_ANCHORS = anchors.empty;
+export const toolCallCancelledOf = anchors.flagOf;
+export const withToolCancelAnchored = anchors.withAnchored;
+export const wellFormedToolCancelAnchorsOf = anchors.wellFormedOf;
+export const toolCancelRecorder = anchors.recorderOf;

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

@@ -0,0 +1,6 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+export declare const EMPTY_TOOL_DECISION_ANCHORS: ReadonlySet<string>;
+export declare function toolDecisionAnchorOf(name: string, value: unknown): string | null;
+export declare function withToolDecisionAnchored(previous: ReadonlySet<string>, toolCallId: string): ReadonlySet<string>;
+export declare function wellFormedToolDecisionAnchorsOf(stored: ReadonlySet<string>): ReadonlySet<string>;
+export declare function toolDecisionRecorder(onDecisionAnchored: (toolCallId: string) => void): AgentSubscriber;