@teaflask/assistant 0.0.0 → 0.6.0

package/dist/components/tool-views/view-dom.js

@@ -0,0 +1,360 @@
+import { BADGE_CLASS, BONES_CLASS, BONE_CLASS, CAPTION_ROW_CLASS, CARD_CLASS, CARD_TITLE_CLASS, FACT_LABEL_CLASS, FACT_LIST_CLASS, FACT_ROW_CLASS, FACT_VALUE_CLASS, LABEL_CLASS, NOTE_CLASS, PANE_CLASS, PANE_WRAPPER_CLASS, ROW_CLASS, ROW_ICON_CLASS, ROW_SECONDARY_CLASS, ROW_TEXT_CLASS, ROW_TITLE_CLASS, ROW_TRAIL_CLASS, SCROLL_REGION_CLASS, TERMINAL_CLASS, TERMINAL_OUTPUT_CLASS, TERMINAL_PROMPT_CLASS, TERMINAL_STDERR_CLASS, } from "./parts-classes.js";
+export { LABEL_CLASS, PANE_CLASS, PANE_WRAPPER_CLASS };
+export function el(tag, className, text) {
+    const node = document.createElement(tag);
+    if (className !== "") {
+        node.className = className;
+    }
+    if (text !== undefined) {
+        node.textContent = text;
+    }
+    return node;
+}
+export function pane(label, text) {
+    const wrapper = el("div", PANE_WRAPPER_CLASS);
+    wrapper.append(el("p", LABEL_CLASS, label));
+    const pre = el("pre", PANE_CLASS);
+    pre.append(el("code", "tf:font-mono", text));
+    wrapper.append(pre);
+    return wrapper;
+}
+export function terminal(options) {
+    const block = el("pre", TERMINAL_CLASS);
+    block.dataset.tfTerminal = "";
+    if (options.command !== null && options.command !== "") {
+        const line = el("code", "");
+        line.dataset.tfTerminalCommand = "";
+        line.append(el("span", TERMINAL_PROMPT_CLASS, "$ "));
+        line.append(document.createTextNode(options.command));
+        block.append(line);
+    }
+    if (options.output !== undefined && options.output !== "") {
+        const out = el("code", TERMINAL_OUTPUT_CLASS, options.output.replace(/\n$/, ""));
+        out.dataset.tfTerminalOutput = "";
+        block.append(out);
+    }
+    if (options.stderr !== undefined && options.stderr !== "") {
+        const err = el("code", TERMINAL_STDERR_CLASS, options.stderr.replace(/\n$/, ""));
+        err.dataset.tfTerminalStderr = "";
+        block.append(err);
+    }
+    return block;
+}
+export function scrollRegion(children) {
+    const region = el("div", SCROLL_REGION_CLASS);
+    region.dataset.tfScrollRegion = "";
+    region.append(...children);
+    return region;
+}
+export function card(children, title) {
+    const wrapper = el("div", "");
+    if (title !== undefined) {
+        wrapper.append(el("p", CARD_TITLE_CLASS, title));
+    }
+    const body = el("div", CARD_CLASS);
+    body.dataset.tfToolViewCard = "";
+    body.append(...children);
+    wrapper.append(body);
+    return wrapper;
+}
+export function listRow(options) {
+    const row = el("div", ROW_CLASS);
+    if (options.icon !== undefined) {
+        const tile = el("span", ROW_ICON_CLASS);
+        tile.append(options.icon);
+        row.append(tile);
+    }
+    const text = el("span", ROW_TEXT_CLASS);
+    text.append(el("span", ROW_TITLE_CLASS, options.title));
+    if (options.secondary !== undefined && options.secondary !== "") {
+        text.append(el("span", ROW_SECONDARY_CLASS, options.secondary));
+    }
+    if (options.below !== undefined) {
+        text.append(options.below);
+    }
+    row.append(text);
+    if (options.trailing !== undefined) {
+        const trail = el("span", ROW_TRAIL_CLASS);
+        trail.append(options.trailing);
+        row.append(trail);
+    }
+    return row;
+}
+export function factRows(facts) {
+    const list = el("dl", FACT_LIST_CLASS);
+    for (const [label, value] of facts) {
+        const row = el("div", FACT_ROW_CLASS);
+        row.append(el("dt", FACT_LABEL_CLASS, label));
+        const dd = el("dd", FACT_VALUE_CLASS);
+        dd.append(value);
+        row.append(dd);
+        list.append(row);
+    }
+    return list;
+}
+export function captionRow(text, trailing) {
+    const row = el("div", CAPTION_ROW_CLASS);
+    row.append(el("span", "tf:min-w-0", text));
+    if (trailing !== undefined) {
+        const trail = el("span", "tf:shrink-0");
+        trail.append(trailing);
+        row.append(trail);
+    }
+    return row;
+}
+export function badge(text) {
+    return el("span", BADGE_CLASS, text);
+}
+export function boneRows(count) {
+    const wrapper = el("div", BONES_CLASS);
+    wrapper.setAttribute("aria-hidden", "true");
+    for (let index = 0; index < count; index += 1) {
+        wrapper.append(el("span", `${BONE_CLASS} ${index === 0 ? "tf:w-1/2" : "tf:w-full"}`));
+    }
+    return wrapper;
+}
+export function note(text) {
+    return el("p", NOTE_CLASS, text);
+}
+export function recordOf(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function stringOf(value) {
+    return typeof value === "string" ? value : null;
+}
+export function statelessToolView(render) {
+    return {
+        mount(container, props) {
+            container.replaceChildren(render(props));
+            return {
+                update(next) {
+                    container.replaceChildren(render(next));
+                },
+                destroy() {
+                    container.replaceChildren();
+                },
+            };
+        },
+    };
+}
+export function settledWithResult(call) {
+    return call.status === "output-available" && call.offloaded !== true;
+}
+export function settledOutcomeNotesOf(call) {
+    const sentence = settledOutcomeNoteOf(call);
+    return sentence === null ? [] : [note(sentence)];
+}
+export function settledOutcomeNoteOf(call) {
+    switch (call.status) {
+        case "refused":
+            return "Declined — the call didn't run.";
+        case "output-error":
+            return "Failed — no result to render.";
+        case "denied":
+            return "Not approved — the call didn't run.";
+        case "cancelled":
+            return "This call didn't run.";
+        case "superseded":
+            return "Interrupted — the result never arrived.";
+        case "input-streaming":
+        case "input-available":
+        case "output-available":
+            break;
+    }
+    if (call.offloaded === true) {
+        return "The result was replaced by a shortened preview and isn't rendered here.";
+    }
+    return null;
+}
+export function actionEnvelopeOf(resultText) {
+    if (resultText === undefined) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(resultText);
+    }
+    catch {
+        return null;
+    }
+    const envelope = recordOf(parsed);
+    if (envelope?.ok !== true) {
+        return null;
+    }
+    const result = recordOf(envelope.result);
+    if (result === null) {
+        return null;
+    }
+    return {
+        status: typeof result.status === "number" ? result.status : null,
+        body: result.body,
+        truncated: result.truncated === true,
+    };
+}
+export function actionFailureOf(errorText) {
+    if (errorText === undefined) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(errorText);
+    }
+    catch {
+        return { message: errorText, detail: _failureDetailInSentence(errorText) };
+    }
+    const envelope = recordOf(parsed);
+    if (envelope?.ok !== false) {
+        return null;
+    }
+    const error = recordOf(envelope.error);
+    const message = error === null ? null : stringOf(error.message);
+    if (message === null) {
+        return null;
+    }
+    return {
+        message,
+        detail: _failureDetailRecordOf(error?.detail) ??
+            _failureDetailInSentence(message),
+    };
+}
+const SENTENCE_STATUS = / failed in this page: HTTP (\d{3}) (\S{1,80}) — /;
+const FIELDS_CLAUSE_OPEN = "Field problems: ";
+const FIELDS_CLAUSE_CLOSE = ". Do not assume";
+const JSON_STRING_LITERAL = /^"(?:[^"\\]|\\.)*"/;
+function _failureDetailInSentence(sentence) {
+    const status = SENTENCE_STATUS.exec(sentence);
+    if (status === null) {
+        return null;
+    }
+    const clause = _fieldsInClauseOf(sentence);
+    return {
+        status: Number(status[1]),
+        code: status[2],
+        fields: clause.fields,
+        ...(clause.omitted > 0 ? { fieldsOmitted: clause.omitted } : {}),
+    };
+}
+const NO_FIELDS = { fields: [], omitted: 0 };
+const OMITTED_TAIL = /^; and (\d+) more/;
+function _fieldsInClauseOf(sentence) {
+    const open = sentence.indexOf(FIELDS_CLAUSE_OPEN);
+    if (open === -1) {
+        return NO_FIELDS;
+    }
+    const fields = [];
+    let at = open + FIELDS_CLAUSE_OPEN.length;
+    for (;;) {
+        const first = _jsonStringAt(sentence, at);
+        if (first === null) {
+            return NO_FIELDS;
+        }
+        at += first.length;
+        let path = "";
+        let message = _decodedStringOf(first);
+        if (sentence.startsWith(": ", at)) {
+            const second = _jsonStringAt(sentence, at + 2);
+            if (second === null) {
+                return NO_FIELDS;
+            }
+            path = message ?? "";
+            message = _decodedStringOf(second);
+            at += 2 + second.length;
+        }
+        if (message === null) {
+            return NO_FIELDS;
+        }
+        fields.push({ path, message });
+        const tail = OMITTED_TAIL.exec(sentence.slice(at));
+        if (tail !== null) {
+            at += tail[0].length;
+            return sentence.startsWith(FIELDS_CLAUSE_CLOSE, at)
+                ? { fields, omitted: Number(tail[1]) }
+                : NO_FIELDS;
+        }
+        if (sentence.startsWith(FIELDS_CLAUSE_CLOSE, at)) {
+            return { fields, omitted: 0 };
+        }
+        if (!sentence.startsWith("; ", at)) {
+            return NO_FIELDS;
+        }
+        at += 2;
+    }
+}
+function _jsonStringAt(text, at) {
+    return JSON_STRING_LITERAL.exec(text.slice(at))?.[0] ?? null;
+}
+function _decodedStringOf(literal) {
+    try {
+        const decoded = JSON.parse(literal);
+        return typeof decoded === "string" ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+function _failureDetailRecordOf(value) {
+    const detail = recordOf(value);
+    if (detail === null) {
+        return null;
+    }
+    const code = stringOf(detail.code);
+    if (typeof detail.status !== "number" || code === null) {
+        return null;
+    }
+    const fields = [];
+    if (Array.isArray(detail.fields)) {
+        for (const entry of detail.fields) {
+            const field = recordOf(entry);
+            const path = field === null ? null : stringOf(field.path);
+            const message = field === null ? null : stringOf(field.message);
+            if (path !== null && message !== null) {
+                fields.push({ path, message });
+            }
+        }
+    }
+    const omitted = detail.fieldsOmitted;
+    return {
+        status: detail.status,
+        code,
+        fields,
+        ...(typeof omitted === "number" && Number.isInteger(omitted) && omitted > 0
+            ? { fieldsOmitted: omitted }
+            : {}),
+    };
+}
+export function humanFailureSentenceOf(errorText) {
+    const failure = actionFailureOf(errorText);
+    const sentence = failure === null ? errorText : failure.message;
+    return _beforeMarker(_beforeMarker(sentence, " Do not assume"), " Field problems:")
+        .replace(SENTENCE_STATUS, " failed in this page: ")
+        .trim();
+}
+function _beforeMarker(text, marker) {
+    const at = text.indexOf(marker);
+    return at === -1 ? text : text.slice(0, at);
+}
+export function fileGlyph() {
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("viewBox", "0 0 24 24");
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", "2");
+    svg.setAttribute("stroke-linecap", "round");
+    svg.setAttribute("stroke-linejoin", "round");
+    svg.setAttribute("aria-hidden", "true");
+    svg.setAttribute("class", "tf:size-3.5");
+    for (const d of [
+        "M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z",
+        "M14 2v4a2 2 0 0 0 2 2h4",
+        "M10 9H8",
+        "M16 13H8",
+        "M16 17H8",
+    ]) {
+        const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+        path.setAttribute("d", d);
+        svg.append(path);
+    }
+    return svg;
+}

package/dist/components/transcript.d.ts

@@ -0,0 +1,3 @@
+export declare function Transcript({ surface }: {
+    surface: string;
+}): import("react").JSX.Element | null;

package/dist/components/transcript.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { ActivityShelf, ComposerActivityOverlay } from "./activity-shelf.js";
+import { ApprovalsContext } from "./approval-context.js";
+import { AssistantTranscript } from "./assistant-transcript.js";
+import { Composer } from "./composer.js";
+import { RunStatusAnnouncer } from "./run-status-announcer.js";
+import { ElicitationsContext, } from "./elicitation-context.js";
+import { SurfaceBoundary } from "./surface-boundary.js";
+import { SuspensionSurfaces } from "./suspension-surfaces.js";
+import { SubagentCountPill } from "./subagent-count-pill.js";
+import { SubagentDelegationSurface } from "./subagent-delegation-surface.js";
+import { SubagentDispatchesContext, } from "./subagent-group-row.js";
+import { SubagentExecutionWorkContext } from "./subagent-execution-work.js";
+import { useAssistantSession } from "./teaflask-assistant-provider.js";
+import { useCell } from "./use-store-cell.js";
+import { useThreadDispatches } from "./use-thread-dispatches.js";
+import { useConversation } from "./conversation-context.js";
+import { useTranscript } from "./use-transcript.js";
+export function Transcript({ surface }) {
+    const { session, store } = useAssistantSession();
+    const { pendingSend } = useConversation();
+    const connection = useCell(store.connection);
+    const { approvalCards, approvalSurface, elicitationSurface } = useDecisionSurfaces(store);
+    const { rows, displayRows, running, turnOpen, decisionsPending, activity } = useTranscript({ surface });
+    const rowIndexByToolCallId = useMemo(() => _rowIndexByToolCallIdOf(displayRows), [displayRows]);
+    const dispatches = useThreadDispatches(session, connection?.threadId ?? null, rows, store.noteDispatchSettled, store.noteDispatchPaused);
+    const dispatchesJoin = useMemo(() => ({ byOrdinal: dispatches }), [dispatches]);
+    const coworkerWork = useCell(store.coworkerWork);
+    if (connection === null) {
+        return null;
+    }
+    return (_jsx(ApprovalsContext.Provider, { value: approvalSurface, children: _jsx(ElicitationsContext.Provider, { value: elicitationSurface, children: _jsxs(SubagentDelegationSurface, { dispatches: dispatches, threadId: connection.threadId, children: [_jsx(SubagentDispatchesContext.Provider, { value: dispatchesJoin, children: _jsx(SubagentExecutionWorkContext.Provider, { value: coworkerWork, children: _jsx(SurfaceBoundary, { surface: "message-list", children: _jsx(AssistantTranscript, { rows: displayRows, cards: approvalCards, live: running || pendingSend, turnOpen: turnOpen, decisionSurfacesInShelf: true }) }) }) }), _jsx(SurfaceBoundary, { surface: "status-announcer", degrade: "silent", children: _jsx(RunStatusAnnouncer, { status: activity.newestTurnStatus, decisionsPending: decisionsPending }) }), _jsxs("div", { "data-tf-composer-anchor": "", className: "tf:relative", children: [_jsx(SurfaceBoundary, { surface: "activity-overlay", children: _jsx(ComposerActivityOverlay, { activity: _jsx(SubagentCountPill, { dispatches: dispatches, threadId: connection.threadId }) }) }), _jsx(SurfaceBoundary, { surface: "activity-shelf", children: _jsx(ActivityShelf, { suspension: _jsx(SurfaceBoundary, { surface: "decisions", shelfItem: true, children: _jsx(SuspensionSurfaces, { rowIndexByToolCallId: rowIndexByToolCallId }) }) }) }), _jsx(Composer, { surface: surface })] })] }) }) }));
+}
+function useDecisionSurfaces(store) {
+    const approvalCards = useCell(store.approvals);
+    const approvalSurface = useMemo(() => ({
+        cards: approvalCards,
+        submitDecision: store.submitApprovalDecision,
+    }), [approvalCards, store]);
+    const elicitationCards = useCell(store.elicitations);
+    const elicitationSurface = useMemo(() => ({
+        cards: elicitationCards,
+        submitQuestionAnswers: store.submitQuestionAnswers,
+        cancelQuestionSet: store.cancelQuestionSet,
+        drafts: store.questionDrafts,
+    }), [elicitationCards, store]);
+    return { approvalCards, approvalSurface, elicitationSurface };
+}
+function _rowIndexByToolCallIdOf(displayRows) {
+    const indexByToolCallId = new Map();
+    displayRows.forEach((row, index) => {
+        if (row.kind === "tool-call") {
+            indexByToolCallId.set(row.toolCallId, index);
+        }
+    });
+    return indexByToolCallId;
+}

package/dist/components/use-agent-subscriber.d.ts

@@ -0,0 +1,3 @@
+import type { AbstractAgent, AgentSubscriber } from "@ag-ui/client";
+import type { DisposableAgentSubscriber } from "../core/disposable-subscriber.js";
+export declare function useAgentSubscriber(agent: Pick<AbstractAgent, "subscribe">, subscriberOf: () => AgentSubscriber | DisposableAgentSubscriber): void;

package/dist/components/use-agent-subscriber.js

@@ -0,0 +1,13 @@
+"use client";
+import { useEffect } from "react";
+export function useAgentSubscriber(agent, subscriberOf) {
+    useEffect(() => {
+        const made = subscriberOf();
+        const { subscriber, dispose } = "subscriber" in made ? made : { subscriber: made, dispose: undefined };
+        const subscription = agent.subscribe(subscriber);
+        return () => {
+            dispose?.();
+            subscription.unsubscribe();
+        };
+    }, [agent, subscriberOf]);
+}

package/dist/components/use-answer-list-fold.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from "react";
+export declare function useAnswerListFold(cursor: number, openDescription: string | null, customText: string): {
+    answersRef: RefObject<HTMLDivElement | null>;
+    foldBelow: boolean;
+    declareFold: () => void;
+};

package/dist/components/use-answer-list-fold.js

@@ -0,0 +1,31 @@
+"use client";
+import { useCallback, useEffect, useRef, useState, } from "react";
+export function useAnswerListFold(cursor, openDescription, customText) {
+    const [foldBelow, setFoldBelow] = useState(false);
+    const answersRef = useRef(null);
+    const declareFold = useCallback(() => {
+        const list = answersRef.current;
+        if (list === null) {
+            return;
+        }
+        const overflowing = list.scrollHeight > list.clientHeight + 1;
+        const atEnd = list.scrollTop + list.clientHeight >= list.scrollHeight - 4;
+        setFoldBelow(overflowing && !atEnd);
+    }, []);
+    useEffect(() => {
+        declareFold();
+        const list = answersRef.current;
+        if (list === null || typeof ResizeObserver === "undefined") {
+            return;
+        }
+        const observer = new ResizeObserver(declareFold);
+        observer.observe(list);
+        for (const child of list.children) {
+            observer.observe(child);
+        }
+        return () => {
+            observer.disconnect();
+        };
+    }, [declareFold, cursor, openDescription, customText]);
+    return { answersRef, foldBelow, declareFold };
+}

package/dist/components/use-assistant-activity.d.ts

@@ -0,0 +1,2 @@
+import type { AssistantActivitySnapshot } from "../core/activity.js";
+export declare function useAssistantActivity(): AssistantActivitySnapshot;

package/dist/components/use-assistant-activity.js

@@ -0,0 +1,7 @@
+"use client";
+import { useAssistantSession } from "./teaflask-assistant-provider.js";
+import { useCell } from "./use-store-cell.js";
+export function useAssistantActivity() {
+    const { store } = useAssistantSession();
+    return useCell(store.activity);
+}

package/dist/components/use-assistant-conversation.d.ts

@@ -0,0 +1,23 @@
+import type { ServingAssistantThread } from "../contract/threads.js";
+import type { ActiveConversation, ComposerContract } from "../core/conversation-store.js";
+import type { PendingDecisionGap } from "../core/pending-decision-gap.js";
+import type { ServingApiError } from "../transport/serving-error.js";
+export interface AssistantConversation {
+    setupError: ServingApiError | null;
+    conversation: ActiveConversation | null;
+    threads: ServingAssistantThread[];
+    historyExpected: boolean;
+    threadOpening: boolean;
+    reconnectNonce: number;
+    composerContract: ComposerContract;
+    sendError: string | null;
+    turnFailure: string | null;
+    showInterruptionBanner: boolean;
+    pendingDecisionGap: PendingDecisionGap | null;
+    retryStream: () => void;
+    refreshConversation: () => Promise<void>;
+    openThread: (thread: ServingAssistantThread) => void;
+    startNewConversation: () => void;
+    resumeStoredThread: () => void;
+}
+export declare function useAssistantConversation(): AssistantConversation;

package/dist/components/use-assistant-conversation.js

@@ -0,0 +1,26 @@
+"use client";
+import { useAssistantSession } from "./teaflask-assistant-provider.js";
+import { useCell } from "./use-store-cell.js";
+export function useAssistantConversation() {
+    const { setupError, store } = useAssistantSession();
+    const conversation = useCell(store.conversation);
+    const composerContract = useCell(store.composer);
+    return {
+        setupError,
+        conversation: conversation.active,
+        threads: conversation.threads,
+        historyExpected: conversation.historyExpected,
+        threadOpening: conversation.threadOpening,
+        reconnectNonce: conversation.reconnectNonce,
+        composerContract,
+        sendError: conversation.sendError,
+        turnFailure: conversation.turnFailure,
+        showInterruptionBanner: conversation.showInterruptionBanner,
+        pendingDecisionGap: conversation.pendingDecisionGap,
+        retryStream: store.retryStream,
+        refreshConversation: store.refreshConversation,
+        openThread: store.openThread,
+        startNewConversation: store.startNewConversation,
+        resumeStoredThread: store.resumeStoredThread,
+    };
+}

package/dist/components/use-assistant-surface-presence.d.ts

@@ -0,0 +1,2 @@
+import { type AssistantSurfacePresence } from "../core/surface-registry.js";
+export declare function useAssistantSurfacePresence(): AssistantSurfacePresence;

package/dist/components/use-assistant-surface-presence.js

@@ -0,0 +1,6 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { assistantSurfaceRegistry, } from "../core/surface-registry.js";
+export function useAssistantSurfacePresence() {
+    return useSyncExternalStore((listener) => assistantSurfaceRegistry.subscribe(listener), () => assistantSurfaceRegistry.getSnapshot(), () => assistantSurfaceRegistry.getSnapshot());
+}

package/dist/components/use-child-replay-stream.d.ts

@@ -0,0 +1,20 @@
+import type { Message } from "@ag-ui/core";
+import { type ThreadDispatch } from "../contract/dispatches.js";
+import type { MarkerAnchorsSnapshot } from "../core/connection-epoch.js";
+import type { TokenSession } from "../transport/token-session.js";
+type ChildStreamEnd = "open" | "clean" | "error";
+interface ChildReplayStream {
+    messages: readonly Message[];
+    streamEnd: ChildStreamEnd;
+    tailed: boolean;
+    slotDenied: boolean;
+    anchors: MarkerAnchorsSnapshot;
+    retry: () => void;
+}
+export declare function useChildReplayStream({ session, threadId, childSessionId, refreshLedger, }: {
+    session: TokenSession;
+    threadId: string;
+    childSessionId: string;
+    refreshLedger: () => Promise<ThreadDispatch | undefined>;
+}): ChildReplayStream;
+export {};