logisheets-logician 1.11.0

package/dist/projection.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure projections from the event stream to:
+ *   - Agent IR messages (Anthropic-compatible shape, used as canonical IR
+ *     by all LlmClient implementations — Anthropic adapters consume it
+ *     directly, other providers translate into their wire format)
+ *                                     → toLlmMessages
+ *   - UI-friendly chat bubbles        → toUiBubbles
+ *
+ * Both are referentially transparent: same events → same output, no I/O.
+ * The agent loop calls toLlmMessages before each request; the UI calls
+ * toUiBubbles whenever events change. Cache-control breakpoints for
+ * prompt caching are NOT placed here — they're a property of the
+ * request, not the message content.
+ */
+import type { ConversationEvent, SystemNoteEvent, ToolCallEvent } from './conversation.js';
+export type AgentRole = 'user' | 'assistant';
+export type AgentContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | AgentContentBlock[];
+    is_error?: boolean;
+};
+export interface AgentMessage {
+    role: AgentRole;
+    content: string | AgentContentBlock[];
+}
+/**
+ * Hook for materializing blob refs into real payloads. The store-aware
+ * caller (agent loop) passes a resolver; pure callers can omit it and
+ * blob refs render as a short placeholder.
+ */
+export type BlobResolver = (ref: string) => string | null;
+export interface ToLlmMessagesOpts {
+    /** Resolve `{kind:'blob_ref', ref}` payloads into strings. */
+    resolveBlob?: BlobResolver;
+    /**
+     * Cap on a single tool_result's serialized size, in chars. Larger
+     * payloads are truncated with a trailing "(... truncated, N more
+     * chars)" marker. Default 8000.
+     */
+    max_tool_result_chars?: number;
+    /**
+     * Drop tool_results older than this index (0-based, counting only
+     * tool_result events). Use to keep ancient results out of context
+     * once they're no longer load-bearing. -1 disables (default).
+     */
+    truncate_tool_results_before?: number;
+}
+/**
+ * Project events into the agent IR (Anthropic-compatible).
+ *
+ * Rules:
+ *   - user_message       → {role: 'user', content: text}
+ *   - assistant_text +
+ *     tool_call          → merged into one {role: 'assistant', content: [...]}
+ *                          per turn_id
+ *   - tool_result        → {role: 'user', content: [{type:'tool_result', ...}]}
+ *   - user_confirm       → dropped (internal signal)
+ *   - system_note:debug  → dropped
+ *   - system_note:ui_only→ dropped
+ *   - system_note:summary→ {role: 'user', content: text} with a
+ *                          "[summary]" prefix so the model recognizes it
+ */
+export declare function toLlmMessages(events: readonly ConversationEvent[], opts?: ToLlmMessagesOpts): AgentMessage[];
+/**
+ * Each bubble is one row in the chat UI. tool_call + tool_result are
+ * fused into a single ToolBubble so the UI renders one collapsible card
+ * per tool invocation rather than two stacked rows.
+ */
+export type ChatBubble = UserBubble | AssistantTextBubble | ToolBubble | NoteBubble;
+export interface UserBubble {
+    kind: 'user';
+    id: string;
+    ts: number;
+    text: string;
+}
+export interface AssistantTextBubble {
+    kind: 'assistant_text';
+    id: string;
+    ts: number;
+    text: string;
+    turn_id: string;
+    /** Set on the last assistant_text of a turn for tail spacing. */
+    last_in_turn: boolean;
+}
+export interface ToolBubble {
+    kind: 'tool';
+    id: string;
+    ts: number;
+    turn_id: string;
+    tool_use_id: string;
+    name: string;
+    input: unknown;
+    /** Populated once the matching tool_result arrives. */
+    output?: unknown;
+    error?: string;
+    duration_ms?: number;
+    /** True from request → response window. */
+    pending: boolean;
+    /** Captures the user's decision on a confirmation prompt. */
+    user_confirm?: {
+        approved: boolean;
+        reason?: string;
+    };
+}
+export interface NoteBubble {
+    kind: 'note';
+    id: string;
+    ts: number;
+    text: string;
+    /** 'summary' notes are also worth showing; 'debug' is filtered out. */
+    severity: 'info' | 'summary';
+}
+export interface ToUiBubblesOpts {
+    /** Include debug-level system_notes (for a "show internals" toggle). */
+    include_debug?: boolean;
+}
+export declare function toUiBubbles(events: readonly ConversationEvent[], opts?: ToUiBubblesOpts): ChatBubble[];
+/** Type guard, exposed for downstream tooling. */
+export declare function isToolCall(e: ConversationEvent): e is ToolCallEvent;
+export declare function isSystemNote(e: ConversationEvent): e is SystemNoteEvent;

package/dist/projection.js

@@ -0,0 +1,249 @@
+/**
+ * Pure projections from the event stream to:
+ *   - Agent IR messages (Anthropic-compatible shape, used as canonical IR
+ *     by all LlmClient implementations — Anthropic adapters consume it
+ *     directly, other providers translate into their wire format)
+ *                                     → toLlmMessages
+ *   - UI-friendly chat bubbles        → toUiBubbles
+ *
+ * Both are referentially transparent: same events → same output, no I/O.
+ * The agent loop calls toLlmMessages before each request; the UI calls
+ * toUiBubbles whenever events change. Cache-control breakpoints for
+ * prompt caching are NOT placed here — they're a property of the
+ * request, not the message content.
+ */
+/**
+ * Project events into the agent IR (Anthropic-compatible).
+ *
+ * Rules:
+ *   - user_message       → {role: 'user', content: text}
+ *   - assistant_text +
+ *     tool_call          → merged into one {role: 'assistant', content: [...]}
+ *                          per turn_id
+ *   - tool_result        → {role: 'user', content: [{type:'tool_result', ...}]}
+ *   - user_confirm       → dropped (internal signal)
+ *   - system_note:debug  → dropped
+ *   - system_note:ui_only→ dropped
+ *   - system_note:summary→ {role: 'user', content: text} with a
+ *                          "[summary]" prefix so the model recognizes it
+ */
+export function toLlmMessages(events, opts = {}) {
+    var _a, _b, _c;
+    const max = (_a = opts.max_tool_result_chars) !== null && _a !== void 0 ? _a : 8000;
+    const dropBefore = (_b = opts.truncate_tool_results_before) !== null && _b !== void 0 ? _b : -1;
+    const messages = [];
+    let toolResultIdx = -1;
+    // Buffer for in-progress assistant turn. Same turn_id collapses
+    // multiple assistant_text + tool_call events into one message.
+    let pendingTurnId = null;
+    let pendingBlocks = [];
+    const flushAssistant = () => {
+        if (pendingTurnId === null)
+            return;
+        if (pendingBlocks.length > 0) {
+            messages.push({ role: 'assistant', content: pendingBlocks });
+        }
+        pendingTurnId = null;
+        pendingBlocks = [];
+    };
+    for (const e of events) {
+        switch (e.kind) {
+            case 'user_confirm':
+                // internal — never crosses to LLM
+                continue;
+            case 'system_note':
+                if (e.visibility !== 'summary')
+                    continue;
+                flushAssistant();
+                messages.push({
+                    role: 'user',
+                    content: `[summary] ${e.text}`,
+                });
+                continue;
+            case 'user_message':
+                flushAssistant();
+                messages.push({ role: 'user', content: e.text });
+                continue;
+            case 'assistant_text':
+                if (pendingTurnId !== e.turn_id) {
+                    flushAssistant();
+                    pendingTurnId = e.turn_id;
+                }
+                pendingBlocks.push({ type: 'text', text: e.text });
+                continue;
+            case 'tool_call':
+                if (pendingTurnId !== e.turn_id) {
+                    flushAssistant();
+                    pendingTurnId = e.turn_id;
+                }
+                pendingBlocks.push({
+                    type: 'tool_use',
+                    id: e.tool_use_id,
+                    name: e.name,
+                    input: (_c = e.input) !== null && _c !== void 0 ? _c : {},
+                });
+                continue;
+            case 'tool_result': {
+                flushAssistant();
+                toolResultIdx++;
+                if (toolResultIdx < dropBefore)
+                    continue;
+                const serialized = serializeToolOutput(e, opts.resolveBlob, max);
+                messages.push({
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'tool_result',
+                            tool_use_id: e.tool_use_id,
+                            content: serialized.content,
+                            is_error: serialized.is_error,
+                        },
+                    ],
+                });
+                continue;
+            }
+        }
+    }
+    flushAssistant();
+    return messages;
+}
+function serializeToolOutput(e, resolveBlob, max) {
+    if (e.error) {
+        return { content: e.error.slice(0, max), is_error: true };
+    }
+    let raw = stringifyOutput(e.output, resolveBlob);
+    if (raw.length > max) {
+        const dropped = raw.length - max;
+        raw = raw.slice(0, max) + `\n(… truncated, ${dropped} more chars)`;
+    }
+    return { content: raw };
+}
+function stringifyOutput(output, resolveBlob) {
+    if (typeof output === 'string')
+        return output;
+    if (output && typeof output === 'object') {
+        const ref = output.kind === 'blob_ref' &&
+            typeof output.ref === 'string'
+            ? output.ref
+            : null;
+        if (ref) {
+            const resolved = resolveBlob ? resolveBlob(ref) : null;
+            return resolved !== null && resolved !== void 0 ? resolved : `(blob ${ref} — not resolved)`;
+        }
+    }
+    try {
+        return JSON.stringify(output);
+    }
+    catch (_a) {
+        return String(output);
+    }
+}
+export function toUiBubbles(events, opts = {}) {
+    const bubbles = [];
+    /** tool_use_id → index in bubbles array, for back-patching results. */
+    const toolBubbleByUseId = new Map();
+    for (const e of events) {
+        switch (e.kind) {
+            case 'user_message':
+                bubbles.push({
+                    kind: 'user',
+                    id: e.id,
+                    ts: e.ts,
+                    text: e.text,
+                });
+                continue;
+            case 'assistant_text':
+                bubbles.push({
+                    kind: 'assistant_text',
+                    id: e.id,
+                    ts: e.ts,
+                    text: e.text,
+                    turn_id: e.turn_id,
+                    last_in_turn: false,
+                });
+                continue;
+            case 'tool_call': {
+                const idx = bubbles.push({
+                    kind: 'tool',
+                    id: e.id,
+                    ts: e.ts,
+                    turn_id: e.turn_id,
+                    tool_use_id: e.tool_use_id,
+                    name: e.name,
+                    input: e.input,
+                    pending: true,
+                }) - 1;
+                toolBubbleByUseId.set(e.tool_use_id, idx);
+                continue;
+            }
+            case 'tool_result': {
+                const idx = toolBubbleByUseId.get(e.tool_use_id);
+                if (idx === undefined) {
+                    // Orphan tool_result — surface as a note for debugging.
+                    bubbles.push({
+                        kind: 'note',
+                        id: e.id,
+                        ts: e.ts,
+                        text: `orphan tool_result for ${e.tool_use_id}`,
+                        severity: 'info',
+                    });
+                    continue;
+                }
+                const tb = bubbles[idx];
+                tb.output = e.output;
+                tb.error = e.error;
+                tb.duration_ms = e.duration_ms;
+                tb.pending = false;
+                continue;
+            }
+            case 'user_confirm': {
+                const idx = toolBubbleByUseId.get(e.tool_use_id);
+                if (idx !== undefined) {
+                    const tb = bubbles[idx];
+                    tb.user_confirm = {
+                        approved: e.approved,
+                        reason: e.reason,
+                    };
+                }
+                continue;
+            }
+            case 'system_note': {
+                if (e.visibility === 'debug' && !opts.include_debug)
+                    continue;
+                if (e.visibility === 'ui_only' || e.visibility === 'summary') {
+                    bubbles.push({
+                        kind: 'note',
+                        id: e.id,
+                        ts: e.ts,
+                        text: e.text,
+                        severity: e.visibility === 'summary' ? 'summary' : 'info',
+                    });
+                }
+                continue;
+            }
+        }
+    }
+    // Tag the last assistant_text of each turn so the UI can add trailing
+    // spacing / show a "done" marker without inspecting siblings at render.
+    const lastAssistantIdxByTurn = new Map();
+    for (let i = 0; i < bubbles.length; i++) {
+        const b = bubbles[i];
+        if (b.kind === 'assistant_text')
+            lastAssistantIdxByTurn.set(b.turn_id, i);
+    }
+    for (const i of lastAssistantIdxByTurn.values()) {
+        ;
+        bubbles[i].last_in_turn = true;
+    }
+    return bubbles;
+}
+// ---------------------------------------------------------------------------
+// Helpers re-exported for tests / external composition
+// ---------------------------------------------------------------------------
+/** Type guard, exposed for downstream tooling. */
+export function isToolCall(e) {
+    return e.kind === 'tool_call';
+}
+export function isSystemNote(e) {
+    return e.kind === 'system_note';
+}

package/dist/storage.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Storage abstraction for conversations + events + blobs.
+ *
+ * The logician package never imports a concrete storage backend.
+ * Hosts plug one in:
+ *   - Watson (browser craft)        → IdbConversationStore via Dexie
+ *   - Node CLI / MCP server          → FileConversationStore (json-on-disk)
+ *   - Tests / smoke runs / REPLs     → MemoryConversationStore (this file)
+ *
+ * Same pattern as `WorkbookClient` in tool.ts — declare the surface
+ * here, let the platform provide the implementation.
+ */
+import type { Conversation, ConversationEvent, ConversationExport, ConversationSummary } from './conversation.js';
+export interface ConversationStoreOpts {
+    /** Cap on listEvents() output for safety; 0 means no cap. */
+    max_events_per_query?: number;
+}
+/**
+ * Persistence surface used by the agent loop. All methods are async so
+ * IDB / fs / network backends fit without changing call sites.
+ */
+export interface ConversationStore {
+    createConversation(meta: Omit<Conversation, 'id' | 'created_at' | 'updated_at'> & {
+        id?: string;
+    }): Promise<Conversation>;
+    getConversation(id: string): Promise<Conversation | null>;
+    listConversations(filter?: {
+        workbook_id?: string;
+        limit?: number;
+    }): Promise<ConversationSummary[]>;
+    updateConversation(id: string, patch: Partial<Pick<Conversation, 'title' | 'extra'>>): Promise<void>;
+    deleteConversation(id: string): Promise<void>;
+    /**
+     * Append a single event. Implementations should `updated_at` the
+     * parent conversation atomically with the insert.
+     */
+    appendEvent(event: ConversationEvent): Promise<void>;
+    /**
+     * Batched append. Useful when replaying a remote sync or restoring
+     * a workbook-archived conversation. Atomic on backends that support
+     * transactions; otherwise best-effort sequential.
+     */
+    appendEvents(events: ConversationEvent[]): Promise<void>;
+    /** Read events in ts-ascending order. */
+    listEvents(conversation_id: string, opts?: {
+        since_ts?: number;
+        limit?: number;
+    }): Promise<ConversationEvent[]>;
+    /** Returns a stable ref string the caller stores in the event. */
+    putBlob(value: string | Uint8Array): Promise<string>;
+    getBlob(ref: string): Promise<string | Uint8Array | null>;
+    deleteBlob(ref: string): Promise<void>;
+    /**
+     * Reactive subscription. Browser stores (IDB/Dexie) implement this
+     * to drive UI updates; headless backends may omit it.
+     * Returns an unsubscribe function.
+     */
+    subscribeEvents?(conversation_id: string, cb: (events: ConversationEvent[]) => void): () => void;
+    exportConversation?(id: string): Promise<ConversationExport>;
+    importConversation?(bundle: ConversationExport): Promise<string>;
+}
+/**
+ * Volatile store. Survives the lifetime of the process, nothing more.
+ * Useful for:
+ *   - tests
+ *   - node CLI runs that don't care about persistence across invocations
+ *   - Watson MVP before IdbConversationStore lands
+ */
+export declare class MemoryConversationStore implements ConversationStore {
+    private conversations;
+    /** Events grouped by conversation_id, kept sorted by ts. */
+    private events;
+    private blobs;
+    private subscribers;
+    private blobCounter;
+    createConversation(meta: Omit<Conversation, 'id' | 'created_at' | 'updated_at'> & {
+        id?: string;
+    }): Promise<Conversation>;
+    getConversation(id: string): Promise<Conversation | null>;
+    listConversations(filter?: {
+        workbook_id?: string;
+        limit?: number;
+    }): Promise<ConversationSummary[]>;
+    updateConversation(id: string, patch: Partial<Pick<Conversation, 'title' | 'extra'>>): Promise<void>;
+    deleteConversation(id: string): Promise<void>;
+    appendEvent(event: ConversationEvent): Promise<void>;
+    appendEvents(events: ConversationEvent[]): Promise<void>;
+    listEvents(conversation_id: string, opts?: {
+        since_ts?: number;
+        limit?: number;
+    }): Promise<ConversationEvent[]>;
+    putBlob(value: string | Uint8Array): Promise<string>;
+    getBlob(ref: string): Promise<string | Uint8Array | null>;
+    deleteBlob(ref: string): Promise<void>;
+    subscribeEvents(conversation_id: string, cb: (events: ConversationEvent[]) => void): () => void;
+    exportConversation(id: string): Promise<ConversationExport>;
+    importConversation(bundle: ConversationExport): Promise<string>;
+    private notify;
+}

package/dist/storage.js

@@ -0,0 +1,223 @@
+/**
+ * Storage abstraction for conversations + events + blobs.
+ *
+ * The logician package never imports a concrete storage backend.
+ * Hosts plug one in:
+ *   - Watson (browser craft)        → IdbConversationStore via Dexie
+ *   - Node CLI / MCP server          → FileConversationStore (json-on-disk)
+ *   - Tests / smoke runs / REPLs     → MemoryConversationStore (this file)
+ *
+ * Same pattern as `WorkbookClient` in tool.ts — declare the surface
+ * here, let the platform provide the implementation.
+ */
+// ---------------------------------------------------------------------------
+// In-memory implementation
+// ---------------------------------------------------------------------------
+/**
+ * Volatile store. Survives the lifetime of the process, nothing more.
+ * Useful for:
+ *   - tests
+ *   - node CLI runs that don't care about persistence across invocations
+ *   - Watson MVP before IdbConversationStore lands
+ */
+export class MemoryConversationStore {
+    constructor() {
+        this.conversations = new Map();
+        /** Events grouped by conversation_id, kept sorted by ts. */
+        this.events = new Map();
+        this.blobs = new Map();
+        this.subscribers = new Map();
+        this.blobCounter = 0;
+    }
+    async createConversation(meta) {
+        var _a;
+        const id = (_a = meta.id) !== null && _a !== void 0 ? _a : randomId('conv');
+        const now = nowMs();
+        const conv = {
+            ...meta,
+            id,
+            created_at: now,
+            updated_at: now,
+        };
+        this.conversations.set(id, conv);
+        this.events.set(id, []);
+        return conv;
+    }
+    async getConversation(id) {
+        var _a;
+        return (_a = this.conversations.get(id)) !== null && _a !== void 0 ? _a : null;
+    }
+    async listConversations(filter) {
+        let rows = [...this.conversations.values()];
+        if ((filter === null || filter === void 0 ? void 0 : filter.workbook_id) !== undefined) {
+            rows = rows.filter((c) => c.workbook_id === filter.workbook_id);
+        }
+        rows.sort((a, b) => b.updated_at - a.updated_at);
+        if (filter === null || filter === void 0 ? void 0 : filter.limit)
+            rows = rows.slice(0, filter.limit);
+        return rows.map((c) => {
+            var _a, _b;
+            return ({
+                id: c.id,
+                title: c.title,
+                workbook_id: c.workbook_id,
+                updated_at: c.updated_at,
+                event_count: (_b = (_a = this.events.get(c.id)) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0,
+            });
+        });
+    }
+    async updateConversation(id, patch) {
+        const c = this.conversations.get(id);
+        if (!c)
+            return;
+        if (patch.title !== undefined)
+            c.title = patch.title;
+        if (patch.extra !== undefined)
+            c.extra = patch.extra;
+        c.updated_at = nowMs();
+    }
+    async deleteConversation(id) {
+        this.conversations.delete(id);
+        this.events.delete(id);
+        this.subscribers.delete(id);
+    }
+    async appendEvent(event) {
+        const bucket = this.events.get(event.conversation_id);
+        if (!bucket) {
+            throw new Error(`appendEvent: conversation not found: ${event.conversation_id}`);
+        }
+        bucket.push(event);
+        const conv = this.conversations.get(event.conversation_id);
+        if (conv)
+            conv.updated_at = event.ts;
+        this.notify(event.conversation_id, bucket);
+    }
+    async appendEvents(events) {
+        if (events.length === 0)
+            return;
+        // Group by conversation for one notify per affected conversation.
+        const touched = new Set();
+        for (const e of events) {
+            const bucket = this.events.get(e.conversation_id);
+            if (!bucket) {
+                throw new Error(`appendEvents: conversation not found: ${e.conversation_id}`);
+            }
+            bucket.push(e);
+            const conv = this.conversations.get(e.conversation_id);
+            if (conv && e.ts > conv.updated_at)
+                conv.updated_at = e.ts;
+            touched.add(e.conversation_id);
+        }
+        for (const cid of touched) {
+            this.notify(cid, this.events.get(cid));
+        }
+    }
+    async listEvents(conversation_id, opts) {
+        var _a;
+        const bucket = (_a = this.events.get(conversation_id)) !== null && _a !== void 0 ? _a : [];
+        let rows = bucket;
+        if ((opts === null || opts === void 0 ? void 0 : opts.since_ts) !== undefined) {
+            const since = opts.since_ts;
+            rows = rows.filter((e) => e.ts >= since);
+        }
+        if (opts === null || opts === void 0 ? void 0 : opts.limit)
+            rows = rows.slice(0, opts.limit);
+        // bucket is already in insertion order, which matches ts-ascending
+        // because appendEvent never inserts out-of-order events.
+        return rows.slice();
+    }
+    async putBlob(value) {
+        const ref = `blob_${++this.blobCounter}_${randomShort()}`;
+        this.blobs.set(ref, value);
+        return ref;
+    }
+    async getBlob(ref) {
+        var _a;
+        return (_a = this.blobs.get(ref)) !== null && _a !== void 0 ? _a : null;
+    }
+    async deleteBlob(ref) {
+        this.blobs.delete(ref);
+    }
+    subscribeEvents(conversation_id, cb) {
+        var _a;
+        let set = this.subscribers.get(conversation_id);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(conversation_id, set);
+        }
+        set.add(cb);
+        // Fire once with current snapshot.
+        cb([...((_a = this.events.get(conversation_id)) !== null && _a !== void 0 ? _a : [])]);
+        return () => {
+            set.delete(cb);
+        };
+    }
+    async exportConversation(id) {
+        var _a;
+        const conversation = this.conversations.get(id);
+        if (!conversation)
+            throw new Error(`exportConversation: not found: ${id}`);
+        const events = ((_a = this.events.get(id)) !== null && _a !== void 0 ? _a : []).slice();
+        // Inline every blob referenced by these events.
+        const blobs = {};
+        for (const e of events) {
+            if (e.kind !== 'tool_result')
+                continue;
+            const ref = extractBlobRef(e.output);
+            if (ref) {
+                const v = this.blobs.get(ref);
+                if (v !== undefined)
+                    blobs[ref] = v;
+            }
+        }
+        return { conversation, events, blobs };
+    }
+    async importConversation(bundle) {
+        const { conversation, events, blobs } = bundle;
+        this.conversations.set(conversation.id, { ...conversation });
+        this.events.set(conversation.id, [...events]);
+        for (const [ref, v] of Object.entries(blobs)) {
+            this.blobs.set(ref, v);
+        }
+        return conversation.id;
+    }
+    notify(conversation_id, snapshot) {
+        const set = this.subscribers.get(conversation_id);
+        if (!set || set.size === 0)
+            return;
+        const frozen = [...snapshot];
+        for (const cb of set) {
+            try {
+                cb(frozen);
+            }
+            catch (_a) {
+                // Subscribers shouldn't throw; swallow to protect the store.
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Recognise `{kind: 'blob_ref', ref: '...'}` payloads in tool_result.output
+ * so exportConversation can inline the referenced blob.
+ */
+function extractBlobRef(output) {
+    if (output &&
+        typeof output === 'object' &&
+        output.kind === 'blob_ref' &&
+        typeof output.ref === 'string') {
+        return output.ref;
+    }
+    return null;
+}
+function nowMs() {
+    return Date.now();
+}
+function randomId(prefix) {
+    return `${prefix}_${nowMs().toString(36)}_${randomShort()}`;
+}
+function randomShort() {
+    return Math.random().toString(36).slice(2, 10);
+}