@teaflask/assistant 0.0.0 → 0.6.0

package/dist/core/memory-provenance-anchors.js

@@ -0,0 +1,154 @@
+import { MEMORY_UPDATED_EVENT_NAME } from "../contract/events.js";
+import { newestAssistantProseIdOf } from "./assistant-prose.js";
+const SUMMARY_MAX_CHARS = 500;
+const TOKEN_MAX_CHARS = 64;
+export const EMPTY_MEMORY_PROVENANCE_ANCHORS = new Map();
+export function memoryUpdatedAnchorOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const { memory_id: memoryId, scope, summary, } = value;
+    if (typeof memoryId !== "string" || memoryId === "") {
+        return null;
+    }
+    if (typeof scope !== "string" || scope.trim() === "") {
+        return null;
+    }
+    if (typeof summary !== "string" || summary.trim() === "") {
+        return null;
+    }
+    return {
+        memoryId,
+        scope: scope.slice(0, TOKEN_MAX_CHARS),
+        summary: summary.slice(0, SUMMARY_MAX_CHARS),
+    };
+}
+export function withMemoryUpdateAnchored(previous, update) {
+    if (previous.has(update.memoryId)) {
+        return previous;
+    }
+    const next = new Map(previous);
+    next.set(update.memoryId, update);
+    return next;
+}
+export function wellFormedMemoryProvenanceAnchorsOf(stored) {
+    const seeded = new Map();
+    const entries = stored;
+    for (const [memoryId, update] of entries) {
+        if (typeof memoryId !== "string" || !_isWellFormedUpdate(update)) {
+            continue;
+        }
+        seeded.set(memoryId, update);
+    }
+    return seeded;
+}
+export const EMPTY_MEMORY_ATTRIBUTION_ANCHORS = new Map();
+export function withMemoryAttributed(previous, memoryId, messageId) {
+    if (previous.has(memoryId)) {
+        return previous;
+    }
+    const next = new Map(previous);
+    next.set(memoryId, messageId);
+    return next;
+}
+export function wellFormedMemoryAttributionAnchorsOf(stored) {
+    const seeded = new Map();
+    const entries = stored;
+    for (const [memoryId, messageId] of entries) {
+        if (typeof memoryId !== "string" ||
+            memoryId === "" ||
+            typeof messageId !== "string" ||
+            messageId === "") {
+            continue;
+        }
+        seeded.set(memoryId, messageId);
+    }
+    return seeded;
+}
+export function memoryFootersOf(provenance, attribution) {
+    const footers = new Map();
+    for (const [memoryId, update] of provenance) {
+        const messageId = attribution.get(memoryId);
+        if (messageId === undefined) {
+            continue;
+        }
+        const grouped = footers.get(messageId);
+        if (grouped === undefined) {
+            footers.set(messageId, [update]);
+        }
+        else {
+            grouped.push(update);
+        }
+    }
+    return footers;
+}
+export function memoryUpdatedRecorder(sink) {
+    let runLive = false;
+    let newestProseId = null;
+    let proseThisRun = false;
+    let pending = [];
+    const flush = () => {
+        if (newestProseId !== null && proseThisRun) {
+            for (const memoryId of pending) {
+                sink.onMemoryAttributed(memoryId, newestProseId);
+            }
+        }
+        pending = [];
+    };
+    return {
+        onRunInitialized() {
+            runLive = false;
+            newestProseId = null;
+            proseThisRun = false;
+            pending = [];
+        },
+        onRunStartedEvent({ messages }) {
+            runLive = true;
+            newestProseId = newestAssistantProseIdOf(messages);
+            proseThisRun = false;
+        },
+        onMessagesChanged({ messages }) {
+            const proseId = newestAssistantProseIdOf(messages);
+            if (proseId !== null && proseId !== newestProseId) {
+                newestProseId = proseId;
+                proseThisRun = true;
+            }
+        },
+        onCustomEvent({ event }) {
+            if (event.name !== MEMORY_UPDATED_EVENT_NAME) {
+                return;
+            }
+            const update = memoryUpdatedAnchorOf(event.value);
+            if (update === null) {
+                return;
+            }
+            sink.onMemoryAnchored(update);
+            if (runLive) {
+                pending.push(update.memoryId);
+            }
+            else if (newestProseId !== null && proseThisRun) {
+                sink.onMemoryAttributed(update.memoryId, newestProseId);
+            }
+        },
+        onRunFinishedEvent() {
+            runLive = false;
+            flush();
+        },
+        onRunErrorEvent() {
+            runLive = false;
+            flush();
+        },
+    };
+}
+function _isWellFormedUpdate(update) {
+    if (typeof update !== "object" || update === null) {
+        return false;
+    }
+    const { memoryId, scope, summary } = update;
+    return (typeof memoryId === "string" &&
+        memoryId !== "" &&
+        typeof scope === "string" &&
+        scope !== "" &&
+        typeof summary === "string" &&
+        summary !== "");
+}

package/dist/core/messages-cell.d.ts

@@ -0,0 +1,11 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
+export declare function messagesRecorder(publish: (messages: readonly Message[]) => void): AgentSubscriber;
+export declare function streamErrorRecorder(onStreamError: (error: Error) => void): AgentSubscriber;
+export declare function isAbortShaped(error: Error): boolean;
+export interface MessagesSnapshot {
+    messages: readonly Message[];
+    running: boolean;
+}
+export declare function messagesSnapshotRecorder(publish: (snapshot: MessagesSnapshot) => void): AgentSubscriber;
+export declare function connectionErrorRecorder(onStreamError: (error: Error) => void): AgentSubscriber;

package/dist/core/messages-cell.js

@@ -0,0 +1,49 @@
+export function messagesRecorder(publish) {
+    return {
+        onMessagesChanged({ messages }) {
+            publish([...messages]);
+        },
+    };
+}
+export function streamErrorRecorder(onStreamError) {
+    return {
+        onRunFailed({ error }) {
+            if (isAbortShaped(error)) {
+                return;
+            }
+            onStreamError(error);
+        },
+    };
+}
+export function isAbortShaped(error) {
+    return error.name === "AbortError" || /\baborted?\b/i.test(error.message);
+}
+export function messagesSnapshotRecorder(publish) {
+    return {
+        onMessagesChanged({ agent, messages }) {
+            publish({ messages: [...messages], running: agent.isRunning });
+        },
+        onRunStartedEvent({ agent }) {
+            publish({ messages: [...agent.messages], running: agent.isRunning });
+        },
+        onRunFinishedEvent({ agent }) {
+            publish({ messages: [...agent.messages], running: false });
+        },
+        onRunErrorEvent({ agent }) {
+            publish({ messages: [...agent.messages], running: false });
+        },
+    };
+}
+export function connectionErrorRecorder(onStreamError) {
+    return {
+        onRunFailed({ error }) {
+            if (isAbortShaped(error)) {
+                return;
+            }
+            onStreamError(error);
+        },
+        onRunErrorEvent({ event }) {
+            onStreamError(new Error(event.message));
+        },
+    };
+}

package/dist/core/observable-cell.d.ts

@@ -0,0 +1,12 @@
+export interface ReadonlyCell<T> {
+    get: () => T;
+    subscribe: (listener: () => void) => () => void;
+}
+export declare class ObservableCell<T> implements ReadonlyCell<T> {
+    private value;
+    private readonly listeners;
+    constructor(initial: T);
+    get: () => T;
+    set(next: T): void;
+    subscribe: (listener: () => void) => (() => void);
+}

package/dist/core/observable-cell.js

@@ -0,0 +1,25 @@
+export class ObservableCell {
+    value;
+    listeners = new Set();
+    constructor(initial) {
+        this.value = initial;
+    }
+    get = () => {
+        return this.value;
+    };
+    set(next) {
+        if (Object.is(this.value, next)) {
+            return;
+        }
+        this.value = next;
+        for (const listener of [...this.listeners]) {
+            listener();
+        }
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+}

package/dist/core/pending-decision-gap.d.ts

@@ -0,0 +1,36 @@
+import type { AssistantTurnStatus } from "../generated/models/assistantTurnStatus.js";
+export interface GapJudgeableTurn {
+    id: string;
+    status: AssistantTurnStatus;
+    run_id: string | null;
+    pending_interrupt_ids?: readonly string[];
+    unservable_interrupt_ids?: readonly string[];
+}
+interface InterruptHolder {
+    interruptId: string;
+}
+export interface PendingDecisionGap {
+    turnId: string;
+    missingInterruptIds: readonly string[];
+}
+export declare function pendingDecisionGapOf(turn: GapJudgeableTurn | null, approvalCards: readonly InterruptHolder[], elicitationCards: readonly InterruptHolder[], executionEntries: readonly InterruptHolder[], consumedInterruptIds?: ReadonlySet<string>): PendingDecisionGap | null;
+export declare function gapSignatureOf(gap: PendingDecisionGap): string;
+export declare const GAP_PROBE_SETTLE_MS = 2000;
+export interface PendingDecisionGapGateDeps {
+    publish: (gap: PendingDecisionGap | null) => void;
+    probe: () => void;
+    evidenceSettled: () => boolean;
+}
+export declare class PendingDecisionGapGate {
+    private readonly deps;
+    private timer;
+    private armedSignature;
+    private judged;
+    private loudSignature;
+    constructor(deps: PendingDecisionGapGateDeps);
+    judge(gap: PendingDecisionGap | null): void;
+    dispose(): void;
+    private _armWindow;
+    private _disarm;
+}
+export {};

package/dist/core/pending-decision-gap.js

@@ -0,0 +1,101 @@
+const EMPTY_CONSUMED_IDS = new Set();
+export function pendingDecisionGapOf(turn, approvalCards, elicitationCards, executionEntries, consumedInterruptIds = EMPTY_CONSUMED_IDS) {
+    if (turn === null) {
+        return null;
+    }
+    if (turn.status !== "awaiting_input" && turn.status !== "parked") {
+        return null;
+    }
+    if (turn.run_id === null || !Array.isArray(turn.pending_interrupt_ids)) {
+        return null;
+    }
+    const represented = new Set();
+    for (const card of approvalCards) {
+        represented.add(card.interruptId);
+    }
+    for (const card of elicitationCards) {
+        represented.add(card.interruptId);
+    }
+    for (const entry of executionEntries) {
+        represented.add(entry.interruptId);
+    }
+    const unservable = new Set(Array.isArray(turn.unservable_interrupt_ids)
+        ? turn.unservable_interrupt_ids.filter((id) => typeof id === "string")
+        : []);
+    const missing = turn.pending_interrupt_ids.filter((id) => typeof id === "string" &&
+        !represented.has(id) &&
+        !consumedInterruptIds.has(id) &&
+        !unservable.has(id));
+    if (missing.length === 0) {
+        return null;
+    }
+    return { turnId: turn.id, missingInterruptIds: missing };
+}
+export function gapSignatureOf(gap) {
+    return `${gap.turnId}:${[...gap.missingInterruptIds].sort().join(",")}`;
+}
+export const GAP_PROBE_SETTLE_MS = 2_000;
+export class PendingDecisionGapGate {
+    deps;
+    timer = null;
+    armedSignature = null;
+    judged = null;
+    loudSignature = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    judge(gap) {
+        this.judged = gap;
+        if (gap === null) {
+            this._disarm();
+            if (this.loudSignature !== null) {
+                this.loudSignature = null;
+                this.deps.publish(null);
+            }
+            return;
+        }
+        const signature = gapSignatureOf(gap);
+        if (this.loudSignature !== null) {
+            this._disarm();
+            if (signature !== this.loudSignature) {
+                this.loudSignature = signature;
+                this.deps.publish(gap);
+            }
+            return;
+        }
+        if (signature === this.armedSignature) {
+            return;
+        }
+        this._disarm();
+        this.armedSignature = signature;
+        this.deps.probe();
+        this._armWindow(signature);
+    }
+    dispose() {
+        this._disarm();
+    }
+    _armWindow(signature) {
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            const survivor = this.judged;
+            if (survivor === null || gapSignatureOf(survivor) !== signature) {
+                this.armedSignature = null;
+                return;
+            }
+            if (!this.deps.evidenceSettled()) {
+                this._armWindow(signature);
+                return;
+            }
+            this.armedSignature = null;
+            this.loudSignature = signature;
+            this.deps.publish(survivor);
+        }, GAP_PROBE_SETTLE_MS);
+    }
+    _disarm() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.armedSignature = null;
+    }
+}

package/dist/core/perch-clearance.d.ts

@@ -0,0 +1,19 @@
+export interface ClearancePoint {
+    x: number;
+    y: number;
+}
+export interface ClearanceRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export declare const PERCH_LIFT_STEPS_PX: readonly number[];
+export declare function probePointsOf(rect: ClearanceRect): ClearancePoint[];
+export declare function liftedBy(rect: ClearanceRect, liftPx: number): ClearanceRect;
+export declare function firstClearLiftFor(options: {
+    rect: ClearanceRect;
+    probe: (point: ClearancePoint) => boolean;
+    liftSteps?: readonly number[];
+}): number;
+export declare const INTERACTIVE_OBSTRUCTION_SELECTOR: string;

package/dist/core/perch-clearance.js

@@ -0,0 +1,53 @@
+export const PERCH_LIFT_STEPS_PX = [0, 56, 112, 168];
+const PROBE_EDGE_INSET_PX = 3;
+export function probePointsOf(rect) {
+    const left = rect.left + PROBE_EDGE_INSET_PX;
+    const right = rect.left + rect.width - PROBE_EDGE_INSET_PX;
+    const top = rect.top + PROBE_EDGE_INSET_PX;
+    const bottom = rect.top + rect.height - PROBE_EDGE_INSET_PX;
+    const centerX = rect.left + rect.width / 2;
+    const centerY = rect.top + rect.height / 2;
+    return [
+        { x: left, y: top },
+        { x: right, y: top },
+        { x: left, y: bottom },
+        { x: right, y: bottom },
+        { x: centerX, y: centerY },
+    ];
+}
+export function liftedBy(rect, liftPx) {
+    return { ...rect, top: rect.top - liftPx };
+}
+export function firstClearLiftFor(options) {
+    const { rect, probe } = options;
+    const liftSteps = options.liftSteps ?? PERCH_LIFT_STEPS_PX;
+    for (const lift of liftSteps) {
+        const lifted = liftedBy(rect, lift);
+        if (lifted.top < 0) {
+            break;
+        }
+        if (!probePointsOf(lifted).some(probe)) {
+            return lift;
+        }
+    }
+    return 0;
+}
+export const INTERACTIVE_OBSTRUCTION_SELECTOR = [
+    "a[href]",
+    "button",
+    "input",
+    "label",
+    "select",
+    "summary",
+    "textarea",
+    '[contenteditable="true"]',
+    '[role="button"]',
+    '[role="checkbox"]',
+    '[role="link"]',
+    '[role="menuitem"]',
+    '[role="option"]',
+    '[role="radio"]',
+    '[role="switch"]',
+    '[role="tab"]',
+    '[role="textbox"]',
+].join(", ");

package/dist/core/question-drafts.d.ts

@@ -0,0 +1,40 @@
+type ActiveChoice = {
+    kind: "option";
+    text: string;
+} | {
+    kind: "custom";
+} | null;
+export interface QuestionAnswerDraft {
+    active: ActiveChoice;
+    customText: string;
+}
+export interface QuestionSetDraft {
+    cursor: number;
+    answers: ReadonlyMap<string, QuestionAnswerDraft>;
+}
+export interface QuestionLike {
+    id: string;
+}
+export declare const MAX_ANSWER_TEXT_CHARS = 1900;
+export declare class QuestionDraftStore {
+    private readonly drafts;
+    private readonly listeners;
+    get: (interruptId: string) => QuestionSetDraft;
+    subscribe: (listener: () => void) => (() => void);
+    hasContent(interruptId: string): boolean;
+    selectOption(interruptId: string, questionId: string, text: string): void;
+    selectCustom(interruptId: string, questionId: string): void;
+    setCustomText(interruptId: string, questionId: string, text: string): void;
+    setCursor(interruptId: string, cursor: number): void;
+    clear(interruptId: string): void;
+    clearAll(): void;
+    private updateAnswer;
+    private notify;
+}
+export declare function answersOf(questions: readonly QuestionLike[], draft: QuestionSetDraft): {
+    id: string;
+    text: string;
+}[] | null;
+export declare function firstUnansweredIndexOf(questions: readonly QuestionLike[], draft: QuestionSetDraft): number;
+export declare function overLimitOf(questions: readonly QuestionLike[], draft: QuestionSetDraft, maxChars: number): string[];
+export {};

package/dist/core/question-drafts.js

@@ -0,0 +1,135 @@
+export const MAX_ANSWER_TEXT_CHARS = 1900;
+const EMPTY_ANSWER = { active: null, customText: "" };
+const EMPTY_SET = { cursor: 0, answers: new Map() };
+export class QuestionDraftStore {
+    drafts = new Map();
+    listeners = new Set();
+    get = (interruptId) => {
+        return this.drafts.get(interruptId) ?? EMPTY_SET;
+    };
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    hasContent(interruptId) {
+        const draft = this.drafts.get(interruptId);
+        if (draft === undefined) {
+            return false;
+        }
+        for (const answer of draft.answers.values()) {
+            if (answer.active !== null || answer.customText !== "") {
+                return true;
+            }
+        }
+        return false;
+    }
+    selectOption(interruptId, questionId, text) {
+        this.updateAnswer(interruptId, questionId, (answer) => ({
+            ...answer,
+            active: { kind: "option", text },
+        }));
+    }
+    selectCustom(interruptId, questionId) {
+        this.updateAnswer(interruptId, questionId, (answer) => ({
+            ...answer,
+            active: { kind: "custom" },
+        }));
+    }
+    setCustomText(interruptId, questionId, text) {
+        this.updateAnswer(interruptId, questionId, (answer) => ({
+            ...answer,
+            active: { kind: "custom" },
+            customText: normalizeCustomText(text),
+        }));
+    }
+    setCursor(interruptId, cursor) {
+        const current = this.get(interruptId);
+        if (current.cursor === cursor) {
+            return;
+        }
+        this.drafts.set(interruptId, { ...current, cursor });
+        this.notify();
+    }
+    clear(interruptId) {
+        if (this.drafts.delete(interruptId)) {
+            this.notify();
+        }
+    }
+    clearAll() {
+        if (this.drafts.size === 0) {
+            return;
+        }
+        this.drafts.clear();
+        this.notify();
+    }
+    updateAnswer(interruptId, questionId, change) {
+        const current = this.get(interruptId);
+        const before = current.answers.get(questionId) ?? EMPTY_ANSWER;
+        const after = change(before);
+        if (before.customText === after.customText &&
+            sameChoice(before.active, after.active)) {
+            return;
+        }
+        const answers = new Map(current.answers);
+        answers.set(questionId, after);
+        this.drafts.set(interruptId, { cursor: current.cursor, answers });
+        this.notify();
+    }
+    notify() {
+        for (const listener of [...this.listeners]) {
+            listener();
+        }
+    }
+}
+function sameChoice(a, b) {
+    if (a === null || b === null) {
+        return a === b;
+    }
+    if (a.kind !== b.kind) {
+        return false;
+    }
+    return a.kind === "option" && b.kind === "option" ? a.text === b.text : true;
+}
+function answerTextOf(draft) {
+    const active = draft?.active ?? null;
+    if (active === null || draft === undefined) {
+        return null;
+    }
+    if (active.kind === "option") {
+        return active.text;
+    }
+    return draft.customText.trim() === "" ? null : draft.customText;
+}
+export function answersOf(questions, draft) {
+    const answers = [];
+    for (const question of questions) {
+        const text = answerTextOf(draft.answers.get(question.id));
+        if (text === null) {
+            return null;
+        }
+        answers.push({ id: question.id, text });
+    }
+    return answers;
+}
+function normalizeCustomText(text) {
+    return text
+        .replace(/[\u000b\u000c]/g, "\n")
+        .replace(/[\u0000-\u0008\u000e-\u001f]/g, "");
+}
+export function firstUnansweredIndexOf(questions, draft) {
+    return questions.findIndex((question) => answerTextOf(draft.answers.get(question.id)) === null);
+}
+export function overLimitOf(questions, draft, maxChars) {
+    const over = [];
+    for (const question of questions) {
+        const answer = draft.answers.get(question.id);
+        if (answer !== undefined &&
+            answer.active?.kind === "custom" &&
+            answer.customText.length > maxChars) {
+            over.push(question.id);
+        }
+    }
+    return over;
+}

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

@@ -0,0 +1,11 @@
+import type { AnsweredQuestions } from "./elicitation-cards.js";
+import { type QuestionModel } from "./elicitation-pickers.js";
+export interface SettledQuestionsReceipt {
+    questions: readonly QuestionModel[];
+    answers: readonly {
+        id: string;
+        text: string;
+    }[];
+}
+export declare function settledQuestionsReceiptOfCard(questions: readonly QuestionModel[], answered: AnsweredQuestions | null): SettledQuestionsReceipt | null;
+export declare function settledQuestionsReceiptOf(toolName: string, argsText: string, resultText: string | undefined): SettledQuestionsReceipt | null;