@teaflask/assistant 0.0.0 → 0.6.0

package/dist/core/execution-inbox.js

@@ -0,0 +1,243 @@
+import { TOOL_EXECUTION_REQUESTED_EVENT_NAME, TOOL_RESULT_RECORDED_EVENT_NAME, } from "../contract/events.js";
+import { isTerminalTurnStatus } from "./activity.js";
+import { MEMBER_ANSWERABLE_KINDS } from "./execution-kinds.js";
+import { coworkerExecutionRequestOf, executionRequestedPayloadOf, recordOrNull, } from "./execution-request-narrowing.js";
+export { coworkerExecutionRequestOf, executionRequestedPayloadOf, } from "./execution-request-narrowing.js";
+const PENDING = { kind: "pending" };
+export function toolResultRecordedPayloadOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.interrupt_id !== "string" || record.interrupt_id === "") {
+        return null;
+    }
+    return {
+        interruptId: record.interrupt_id,
+        ok: typeof record.ok === "boolean" ? record.ok : true,
+    };
+}
+export class ExecutionInbox {
+    currentRunId = null;
+    seenRunIds = new Set();
+    seenToolCallIds = new Set();
+    coworkerAsks = new Map();
+    entryList = [];
+    noteRunStarted(runId) {
+        this.currentRunId = runId;
+        if (this.seenRunIds.has(runId)) {
+            return false;
+        }
+        this.seenRunIds.add(runId);
+        return this._removeWhere((entry) => entry.asker.kind === "assistant" && entry.runId !== runId);
+    }
+    noteToolCallStart(toolCallId) {
+        this.seenToolCallIds.add(toolCallId);
+        return false;
+    }
+    noteExecutionRequested(payload) {
+        if (this.currentRunId === null) {
+            return false;
+        }
+        const runId = this.currentRunId;
+        if (this._hasEntry(payload.interrupt_id)) {
+            return false;
+        }
+        const coworkerAsk = this.coworkerAsks.get(payload.interrupt_id);
+        if (coworkerAsk !== undefined) {
+            if (MEMBER_ANSWERABLE_KINDS.has(payload.request.kind)) {
+                return false;
+            }
+            this.entryList.push(_entryOf(payload, this.seenToolCallIds, coworkerAsk.runId, coworkerAsk));
+            return true;
+        }
+        const newestRound = this._newestRoundOf(runId);
+        if (newestRound !== null && payload.round < newestRound) {
+            return false;
+        }
+        if (newestRound !== null && payload.round > newestRound) {
+            this._removeWhere((entry) => entry.asker.kind === "assistant" &&
+                entry.runId === runId &&
+                entry.round < payload.round);
+        }
+        this.entryList.push(_entryOf(payload, this.seenToolCallIds, runId, null));
+        return true;
+    }
+    adoptCoworkerRequests(turns) {
+        let changed = false;
+        const listed = new Set();
+        for (const turn of turns) {
+            for (const raw of turn.pending_coworker_executions ?? []) {
+                const request = coworkerExecutionRequestOf(raw);
+                if (request === null) {
+                    continue;
+                }
+                const interruptId = request.card.interrupt_id;
+                const ask = {
+                    asker: { kind: "coworker", ordinal: request.ordinal },
+                    turnId: turn.id,
+                    runId: turn.run_id ?? turn.id,
+                };
+                this.coworkerAsks.set(interruptId, ask);
+                if (MEMBER_ANSWERABLE_KINDS.has(request.card.request.kind)) {
+                    const dropped = this._removeWhere((entry) => entry.interruptId === interruptId);
+                    changed = dropped || changed;
+                    continue;
+                }
+                listed.add(interruptId);
+                const held = this.entryList.find((entry) => entry.interruptId === interruptId);
+                if (held === undefined) {
+                    this.entryList.push(_entryOf(request.card, this.seenToolCallIds, ask.runId, ask));
+                    changed = true;
+                }
+                else if (held.asker.kind === "assistant") {
+                    held.asker = ask.asker;
+                    held.turnId = ask.turnId;
+                    changed = true;
+                }
+            }
+        }
+        if (turns.length > 0) {
+            const removed = this._removeWhere((entry) => entry.asker.kind === "coworker" && !listed.has(entry.interruptId));
+            changed = removed || changed;
+        }
+        return changed;
+    }
+    markCoworkerRequestStale(interruptId) {
+        return this._staleWhere((entry) => entry.asker.kind === "coworker" && entry.interruptId === interruptId);
+    }
+    markCoworkerRequestsStale() {
+        return this._staleWhere((entry) => entry.asker.kind === "coworker");
+    }
+    noteToolResultRecorded(interruptId, ok) {
+        return this._transition(interruptId, ["pending", "executing"], {
+            kind: "reported",
+            ok,
+        });
+    }
+    noteToolCallResult(toolCallId) {
+        return this._removeWhere((entry) => entry.toolCallId === toolCallId);
+    }
+    noteRunFinished() {
+        return false;
+    }
+    reconcileWithTurns(turns) {
+        const settledRuns = new Set(turns
+            .filter((turn) => isTerminalTurnStatus(turn.status))
+            .map((turn) => turn.run_id)
+            .filter((runId) => runId !== null));
+        return this._removeWhere((entry) => entry.asker.kind === "assistant" && settledRuns.has(entry.runId));
+    }
+    noteRunError() {
+        return this._removeWhere((entry) => entry.asker.kind === "assistant");
+    }
+    beginExecution(interruptId) {
+        return this._transition(interruptId, ["pending"], { kind: "executing" });
+    }
+    settleReported(interruptId, ok) {
+        return this._transition(interruptId, ["executing"], {
+            kind: "reported",
+            ok,
+        });
+    }
+    settlePostFailed(interruptId) {
+        return this._transition(interruptId, ["executing"], PENDING);
+    }
+    markRunStale(runId) {
+        return this._staleWhere((entry) => entry.asker.kind === "assistant" && entry.runId === runId);
+    }
+    entries() {
+        return this.entryList.map((entry) => ({ ...entry }));
+    }
+    _hasEntry(interruptId) {
+        return this.entryList.some((entry) => entry.interruptId === interruptId);
+    }
+    _newestRoundOf(runId) {
+        const rounds = this.entryList
+            .filter((entry) => entry.asker.kind === "assistant" && entry.runId === runId)
+            .map((entry) => entry.round);
+        return rounds.length > 0 ? Math.max(...rounds) : null;
+    }
+    _staleWhere(doomed) {
+        let changed = false;
+        for (const entry of this.entryList) {
+            if (doomed(entry) &&
+                (entry.status.kind === "pending" || entry.status.kind === "executing")) {
+                entry.status = { kind: "stale" };
+                changed = true;
+            }
+        }
+        return changed;
+    }
+    _removeWhere(doomed) {
+        const kept = this.entryList.filter((entry) => !doomed(entry));
+        if (kept.length === this.entryList.length) {
+            return false;
+        }
+        this.entryList = kept;
+        return true;
+    }
+    _transition(interruptId, fromKinds, to) {
+        const entry = this.entryList.find((known) => known.interruptId === interruptId);
+        if (entry === undefined || !fromKinds.includes(entry.status.kind)) {
+            return false;
+        }
+        entry.status = to;
+        return true;
+    }
+}
+function _entryOf(payload, seenToolCallIds, runId, ask) {
+    return {
+        interruptId: payload.interrupt_id,
+        toolName: payload.tool_name,
+        toolCallId: payload.tool_call_id ?? null,
+        anchored: payload.tool_call_id != null && seenToolCallIds.has(payload.tool_call_id),
+        kind: payload.request.kind,
+        action: recordOrNull(payload.request.action),
+        intent: recordOrNull(payload.request.intent),
+        round: payload.round,
+        runId,
+        status: PENDING,
+        asker: ask?.asker ?? { kind: "assistant" },
+        turnId: ask?.turnId ?? null,
+    };
+}
+export function executionInboxRecorder(inbox, onEntriesChanged) {
+    const publishWhen = (changed) => {
+        if (changed) {
+            onEntriesChanged(inbox.entries());
+        }
+    };
+    return {
+        onRunStartedEvent({ event }) {
+            publishWhen(inbox.noteRunStarted(event.runId));
+        },
+        onCustomEvent({ event }) {
+            if (event.name === TOOL_EXECUTION_REQUESTED_EVENT_NAME) {
+                const payload = executionRequestedPayloadOf(event.value);
+                if (payload !== null) {
+                    publishWhen(inbox.noteExecutionRequested(payload));
+                }
+                return;
+            }
+            if (event.name === TOOL_RESULT_RECORDED_EVENT_NAME) {
+                const receipt = toolResultRecordedPayloadOf(event.value);
+                if (receipt !== null) {
+                    publishWhen(inbox.noteToolResultRecorded(receipt.interruptId, receipt.ok));
+                }
+            }
+        },
+        onToolCallStartEvent({ event }) {
+            publishWhen(inbox.noteToolCallStart(event.toolCallId));
+        },
+        onToolCallResultEvent({ event }) {
+            publishWhen(inbox.noteToolCallResult(event.toolCallId));
+        },
+        onRunFinishedEvent() {
+            publishWhen(inbox.noteRunFinished());
+        },
+        onRunErrorEvent() {
+            publishWhen(inbox.noteRunError());
+        },
+    };
+}

package/dist/core/execution-kinds.d.ts

@@ -0,0 +1,34 @@
+export declare const NAVIGATE_REQUEST_KIND = "builtin.navigate";
+export declare const HTTP_INTENT_REQUEST_KIND = "http_intent";
+export declare const READ_PAGE_REQUEST_KIND = "builtin.read_page";
+export declare const HIGHLIGHT_REQUEST_KIND = "builtin.highlight";
+export declare const PREFILL_FORM_REQUEST_KIND = "builtin.prefill_form";
+export declare const ASK_QUESTIONS_REQUEST_KIND = "builtin.ask_questions";
+export declare const MEMBER_ANSWERABLE_KINDS: ReadonlySet<string>;
+export declare const MAX_DELIVERY_ATTEMPTS = 3;
+type ExecutionErrorCode = "kind_unsupported" | "execution_failed";
+export interface ExecutionFailureDetail {
+    status: number;
+    code: string;
+    fields?: {
+        path: string;
+        message: string;
+    }[];
+    fieldsOmitted?: number;
+}
+interface ExecutionError {
+    code: ExecutionErrorCode;
+    message: string;
+    detail?: ExecutionFailureDetail;
+}
+export type ExecutionOutcome = {
+    ok: true;
+    result: Record<string, unknown>;
+} | {
+    ok: false;
+    error: ExecutionError;
+};
+export declare const KIND_UNSUPPORTED_OUTCOME: Extract<ExecutionOutcome, {
+    ok: false;
+}>;
+export {};

package/dist/core/execution-kinds.js

@@ -0,0 +1,18 @@
+export const NAVIGATE_REQUEST_KIND = "builtin.navigate";
+export const HTTP_INTENT_REQUEST_KIND = "http_intent";
+export const READ_PAGE_REQUEST_KIND = "builtin.read_page";
+export const HIGHLIGHT_REQUEST_KIND = "builtin.highlight";
+export const PREFILL_FORM_REQUEST_KIND = "builtin.prefill_form";
+export const ASK_QUESTIONS_REQUEST_KIND = "builtin.ask_questions";
+export const MEMBER_ANSWERABLE_KINDS = new Set([
+    ASK_QUESTIONS_REQUEST_KIND,
+]);
+export const MAX_DELIVERY_ATTEMPTS = 3;
+export const KIND_UNSUPPORTED_OUTCOME = {
+    ok: false,
+    error: {
+        code: "kind_unsupported",
+        message: "This page cannot perform this action itself. Tell the user what " +
+            "you were trying to do and how they can do it themselves.",
+    },
+};

package/dist/core/execution-request-narrowing.d.ts

@@ -0,0 +1,15 @@
+import type { ToolExecutionRequestedPayload } from "../contract/events.js";
+export interface CoworkerExecutionRequest {
+    ordinal: number;
+    label: string;
+    childSessionId: string;
+    card: ToolExecutionRequestedPayload;
+}
+export interface CoworkerRequestTurn {
+    id: string;
+    run_id: string | null;
+    pending_coworker_executions?: readonly unknown[] | null;
+}
+export declare function coworkerExecutionRequestOf(value: unknown): CoworkerExecutionRequest | null;
+export declare function executionRequestedPayloadOf(value: unknown): ToolExecutionRequestedPayload | null;
+export declare function recordOrNull(value: unknown): Record<string, unknown> | null;

package/dist/core/execution-request-narrowing.js

@@ -0,0 +1,64 @@
+export function coworkerExecutionRequestOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.ordinal !== "number" ||
+        typeof record.label !== "string" ||
+        typeof record.child_session_id !== "string") {
+        return null;
+    }
+    const card = executionRequestedPayloadOf(record.card);
+    if (card === null) {
+        return null;
+    }
+    return {
+        ordinal: record.ordinal,
+        label: record.label,
+        childSessionId: record.child_session_id,
+        card,
+    };
+}
+export function executionRequestedPayloadOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.interrupt_id !== "string" || record.interrupt_id === "") {
+        return null;
+    }
+    if (typeof record.tool_name !== "string") {
+        return null;
+    }
+    const request = _requestOf(record.request);
+    if (request === null) {
+        return null;
+    }
+    return {
+        interrupt_id: record.interrupt_id,
+        tool_name: record.tool_name,
+        tool_call_id: typeof record.tool_call_id === "string" ? record.tool_call_id : null,
+        round: typeof record.round === "number" ? record.round : 0,
+        request,
+    };
+}
+function _requestOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.kind !== "string" || record.kind === "") {
+        return null;
+    }
+    return {
+        kind: record.kind,
+        intent: recordOrNull(record.intent),
+        action: recordOrNull(record.action),
+    };
+}
+export function recordOrNull(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}

package/dist/core/host-fill.d.ts

@@ -0,0 +1 @@
+export declare function hostFillDeclines(fill: unknown): boolean;

package/dist/core/host-fill.js

@@ -0,0 +1,3 @@
+export function hostFillDeclines(fill) {
+    return fill === null || fill === undefined || typeof fill === "boolean";
+}

package/dist/core/hotkey.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_ASSISTANT_HOTKEY = "mod+k";
+export interface HotkeyEventLike {
+    key: string;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+}
+export interface HotkeyBinding {
+    key: string;
+    mod: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+}
+export declare function parseHotkey(spec: string): HotkeyBinding | null;
+export declare function hotkeyMatches(binding: HotkeyBinding, event: HotkeyEventLike): boolean;

package/dist/core/hotkey.js

@@ -0,0 +1,72 @@
+export const DEFAULT_ASSISTANT_HOTKEY = "mod+k";
+const MODIFIER_TOKENS = ["mod", "ctrl", "meta", "alt", "shift"];
+export function parseHotkey(spec) {
+    const binding = {
+        key: "",
+        mod: false,
+        ctrl: false,
+        meta: false,
+        alt: false,
+        shift: false,
+    };
+    for (const token of spec.toLowerCase().split("+")) {
+        if (_isModifierToken(token)) {
+            if (binding[token]) {
+                return null;
+            }
+            binding[token] = true;
+        }
+        else if (_isKeyToken(token)) {
+            if (binding.key !== "") {
+                return null;
+            }
+            binding.key = token;
+        }
+        else {
+            return null;
+        }
+    }
+    if (binding.key === "" || !_hasAnyModifier(binding)) {
+        return null;
+    }
+    if (_shiftIsTheOnlyModifier(binding) && _isPrintableKey(binding.key)) {
+        return null;
+    }
+    return binding;
+}
+export function hotkeyMatches(binding, event) {
+    if (event.key.toLowerCase() !== binding.key) {
+        return false;
+    }
+    if (event.altKey !== binding.alt || event.shiftKey !== binding.shift) {
+        return false;
+    }
+    if (_explicitlyNamedPrimaryIsUp(binding, event)) {
+        return false;
+    }
+    const unclaimedPrimariesDown = Number(event.metaKey && !binding.meta) +
+        Number(event.ctrlKey && !binding.ctrl);
+    return unclaimedPrimariesDown === (binding.mod ? 1 : 0);
+}
+function _isModifierToken(token) {
+    return MODIFIER_TOKENS.includes(token);
+}
+function _isKeyToken(token) {
+    return token !== "" && !/\s/.test(token);
+}
+function _hasAnyModifier(binding) {
+    return (binding.mod || binding.ctrl || binding.meta || binding.alt || binding.shift);
+}
+function _shiftIsTheOnlyModifier(binding) {
+    return (binding.shift &&
+        !binding.mod &&
+        !binding.ctrl &&
+        !binding.meta &&
+        !binding.alt);
+}
+function _isPrintableKey(key) {
+    return key.length === 1;
+}
+function _explicitlyNamedPrimaryIsUp(binding, event) {
+    return (binding.meta && !event.metaKey) || (binding.ctrl && !event.ctrlKey);
+}

package/dist/core/identity-pair.d.ts

@@ -0,0 +1,14 @@
+type GetEndUserToken = () => string | null | Promise<string | null>;
+export interface IdentityPairInput {
+    userId?: string | null;
+    getEndUserToken?: GetEndUserToken | null;
+}
+export interface NamedIdentity {
+    userId: string;
+    getEndUserToken: GetEndUserToken;
+}
+export declare const IDENTITY_PAIR_WARNING = "userId and getEndUserToken must be set together \u2014 a non-empty id with its vouch; the session runs anonymous until both are.";
+export declare function namedIdentityOf(input: IdentityPairInput): NamedIdentity | null;
+export declare function identityPairIsHalfSet(input: IdentityPairInput): boolean;
+export declare function namedUserIdOf(userId: string | null | undefined): string | undefined;
+export {};

package/dist/core/identity-pair.js

@@ -0,0 +1,18 @@
+export const IDENTITY_PAIR_WARNING = "userId and getEndUserToken must be set together — a non-empty id with its vouch; the session runs anonymous until both are.";
+export function namedIdentityOf(input) {
+    const userId = namedUserIdOf(input.userId);
+    const getEndUserToken = input.getEndUserToken ?? undefined;
+    return userId !== undefined && getEndUserToken !== undefined
+        ? { userId, getEndUserToken }
+        : null;
+}
+export function identityPairIsHalfSet(input) {
+    const nothingSet = (input.userId ?? undefined) === undefined &&
+        (input.getEndUserToken ?? undefined) === undefined;
+    return !nothingSet && namedIdentityOf(input) === null;
+}
+export function namedUserIdOf(userId) {
+    return userId === null || userId === undefined || userId === ""
+        ? undefined
+        : userId;
+}

package/dist/core/idle-recheck.d.ts

@@ -0,0 +1,3 @@
+import type { AssistantConversationStore } from "./conversation-store.js";
+export declare function syncIdleRecheck(store: AssistantConversationStore): void;
+export declare function clearIdleRecheck(store: AssistantConversationStore): void;

package/dist/core/idle-recheck.js

@@ -0,0 +1,27 @@
+import { turnHoldsAStream } from "./connection-driver.js";
+const IDLE_RECHECK_INTERVAL_MS = 60_000;
+export function syncIdleRecheck(store) {
+    const wanted = !store._disposed &&
+        store._leaseHolders.length > 0 &&
+        store._active !== null &&
+        !turnHoldsAStream(store);
+    if (!wanted) {
+        clearIdleRecheck(store);
+        return;
+    }
+    store._idleRecheckTimer ??= setInterval(() => {
+        if (store._idleRecheckInFlight) {
+            return;
+        }
+        store._idleRecheckInFlight = true;
+        void store.refreshConversation().finally(() => {
+            store._idleRecheckInFlight = false;
+        });
+    }, IDLE_RECHECK_INTERVAL_MS);
+}
+export function clearIdleRecheck(store) {
+    if (store._idleRecheckTimer !== null) {
+        clearInterval(store._idleRecheckTimer);
+        store._idleRecheckTimer = null;
+    }
+}

package/dist/core/memory-provenance-anchors.d.ts

@@ -0,0 +1,19 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+export interface MemoryUpdated {
+    memoryId: string;
+    scope: string;
+    summary: string;
+}
+export declare const EMPTY_MEMORY_PROVENANCE_ANCHORS: ReadonlyMap<string, MemoryUpdated>;
+export declare function memoryUpdatedAnchorOf(value: unknown): MemoryUpdated | null;
+export declare function withMemoryUpdateAnchored(previous: ReadonlyMap<string, MemoryUpdated>, update: MemoryUpdated): ReadonlyMap<string, MemoryUpdated>;
+export declare function wellFormedMemoryProvenanceAnchorsOf(stored: ReadonlyMap<string, MemoryUpdated>): ReadonlyMap<string, MemoryUpdated>;
+export declare const EMPTY_MEMORY_ATTRIBUTION_ANCHORS: ReadonlyMap<string, string>;
+export declare function withMemoryAttributed(previous: ReadonlyMap<string, string>, memoryId: string, messageId: string): ReadonlyMap<string, string>;
+export declare function wellFormedMemoryAttributionAnchorsOf(stored: ReadonlyMap<string, string>): ReadonlyMap<string, string>;
+export declare function memoryFootersOf(provenance: ReadonlyMap<string, MemoryUpdated>, attribution: ReadonlyMap<string, string>): ReadonlyMap<string, MemoryUpdated[]>;
+export interface MemoryUpdatedRecorderSink {
+    onMemoryAnchored: (update: MemoryUpdated) => void;
+    onMemoryAttributed: (memoryId: string, messageId: string) => void;
+}
+export declare function memoryUpdatedRecorder(sink: MemoryUpdatedRecorderSink): AgentSubscriber;