logisheets-logician 1.11.0

package/README.md

@@ -0,0 +1,89 @@
+# logician
+
+The **AI agent core for [LogiSheets](https://github.com/logisky/LogiSheets)** — a
+platform-agnostic toolkit of LLM tools, prompts, and an agent loop for operating
+spreadsheets through the LogiSheets engine. It powers **Watson**, the in-app AI
+assistant, and is reusable from any host: the browser, a Node CLI, or an MCP
+server.
+
+`logician` is engine-neutral: it drives a workbook only through the
+`WorkbookClient` surface from
+[`logisheets-core`](https://www.npmjs.com/package/logisheets-core) /
+[`logisheets-web`](https://www.npmjs.com/package/logisheets-web), so the same
+agent runs in the browser and headless on Node.
+
+> **Status:** internal to the LogiSheets monorepo (`private`), evolving. The API
+> below is stable enough to build on but not yet semver-guaranteed.
+
+## What's inside
+
+- **Tool groups** — ready-made LLM tools grouped by capability, each a set of
+  typed `Tool`s with JSON-schema inputs:
+  - `INSPECT_TOOLS` — read the workbook (list blocks, describe a block, read a
+    selection, evaluate a formula, explain why a cell is locked, …).
+  - `EDIT_TOOLS` — mutate cells and blocks (set cells, add/delete block rows,
+    checkpoint, preview changes, …).
+  - `BUILDER_TOOLS` — higher-level authoring (create sheets and blocks, define
+    field rules and enum sets, …).
+  - `CRAFT_INTERACTION_TOOLS` — reach the host's craft overlay/widget state.
+- **`ToolRegistry`** — register tools and emit them as Anthropic tool
+  definitions (`toLlmTools()`).
+- **`Agent`** — an end-to-end turn loop (`runTurn`) that drives an LLM ↔ tools
+  cycle until the model finishes, with per-tool confirmation policies
+  (`once` / `always` / `destructive`) for safe, human-in-the-loop editing.
+- **Conversation store** — an event-sourced conversation model with adapters for
+  Anthropic messages (`toLlmMessages`) and host UIs (`toUiBubbles`), plus an
+  in-memory implementation.
+
+## Usage
+
+```ts
+import {
+    Agent,
+    ToolRegistry,
+    INSPECT_TOOLS,
+    EDIT_TOOLS,
+    BUILDER_TOOLS,
+    MemoryConversationStore,
+} from 'logisheets-logician'
+import type {WorkbookClient} from 'logisheets-web'
+
+declare const workbook: WorkbookClient // from the host (browser worker or Node)
+declare const llm: LlmClient // your Anthropic client adapter
+
+const registry = new ToolRegistry()
+registry.registerMany([...INSPECT_TOOLS, ...EDIT_TOOLS, ...BUILDER_TOOLS])
+
+const agent = new Agent({
+    store: new MemoryConversationStore(),
+    registry,
+    llm,
+    workbook,
+    systemPrompt: 'You operate a LogiSheets workbook on the user\'s behalf.',
+})
+
+await agent.runTurn(conversationId, 'Add a Revenue column and total it.')
+```
+
+The `confirm` callback lets the host approve destructive or policy-gated tool
+calls (the browser wires it to a modal; a CLI can prompt on stdin; headless hosts
+auto-approve).
+
+## Where it fits
+
+```
+logisheets-web / logisheets  (WASM engine)
+            │  WorkbookClient
+            ▼
+      logisheets-core
+            │
+            ▼
+        logician  ← LLM tools + agent loop
+            │
+   ┌────────┴─────────┐
+Watson (browser)   Node CLI / MCP server
+```
+
+## License
+
+MIT — part of the [LogiSheets](https://github.com/logisky/LogiSheets) project.

package/dist/agent/loop.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Agent loop — drive a multi-turn conversation:
+ *   user_message → LLM → (text + tool_use*) → execute tools → repeat
+ *   until stop_reason === 'end_turn'.
+ *
+ * The loop is platform-agnostic. It depends on:
+ *   - ConversationStore  (events + blobs)
+ *   - ToolRegistry        (handler dispatch)
+ *   - LlmClient            (Anthropic, or any drop-in)
+ *   - WorkbookClient      (passed through to tool handlers)
+ *   - host-provided confirm / log callbacks
+ *
+ * The Anthropic SDK is NOT imported here. Hosts wire up a concrete
+ * LlmClient (the browser craft uses fetch + the Messages REST API, the
+ * node CLI uses @anthropic-ai/sdk). Keeping the boundary thin lets us
+ * test the loop without network and swap providers later.
+ */
+import type { ConversationEvent } from '../conversation.js';
+import { type AgentContentBlock, type AgentMessage } from '../projection.js';
+import type { ConversationStore } from '../storage.js';
+import { toLlmTool, ToolRegistry } from '../tool.js';
+import type { WorkbookClient } from '../tool.js';
+import type { CraftInteractionsApi } from '../craft-interactions-api.js';
+export interface LlmCreateMessageParams {
+    model: string;
+    system: AgentSystemBlock[];
+    tools: ReturnType<typeof toLlmTool>[];
+    messages: AgentMessage[];
+    max_tokens: number;
+    signal?: AbortSignal;
+}
+export interface AgentSystemBlock {
+    type: 'text';
+    text: string;
+    /** Cache breakpoint marker. */
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}
+export interface LlmResponse {
+    /** Anthropic-style response content. */
+    content: AgentContentBlock[];
+    stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | string;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_creation_input_tokens?: number;
+        cache_read_input_tokens?: number;
+    };
+}
+export interface LlmClient {
+    createMessage(params: LlmCreateMessageParams): Promise<LlmResponse>;
+}
+export interface AgentOptions {
+    store: ConversationStore;
+    registry: ToolRegistry;
+    llm: LlmClient;
+    workbook: WorkbookClient;
+    /** Anthropic model id. Default 'claude-opus-4-8'. */
+    model?: string;
+    /** Cap on tokens per response. Default 4096. */
+    max_tokens?: number;
+    /** Base system prompt (instructions). Tool listing is auto-appended. */
+    systemPrompt: string;
+    /** Defensive cap on tool calls per user turn to prevent runaway loops. */
+    max_tool_iterations?: number;
+    /** Confirmation prompt for tools whose policy demands it. */
+    confirm?: (toolName: string, input: unknown, policy: 'once' | 'always' | 'destructive') => Promise<{
+        approved: boolean;
+        reason?: string;
+    }>;
+    /** Hook for surfacing in-flight notes to the host UI (toast / log line). */
+    log?: (msg: string) => void;
+    /** Optional craft-interaction capability surface; passed to every
+     *  ToolContext so craft-interaction tools can reach the host's
+     *  overlay-widget state. Omit on headless hosts. */
+    craftInteractions?: CraftInteractionsApi;
+}
+export declare class Agent {
+    private store;
+    private registry;
+    private llm;
+    private workbook;
+    private model;
+    private maxTokens;
+    private systemPrompt;
+    private maxToolIters;
+    private confirm;
+    private log;
+    private craftInteractions?;
+    constructor(opts: AgentOptions);
+    /**
+     * Run one user turn end-to-end: append the user_message, then loop
+     * LLM ↔ tools until the model emits end_turn or we hit a safety cap.
+     */
+    runTurn(conversation_id: string, userText: string, signal?: AbortSignal): Promise<void>;
+    private executeToolCall;
+    private buildSystem;
+    private appendNote;
+}
+export type { ConversationEvent };

package/dist/agent/loop.js

@@ -0,0 +1,260 @@
+/**
+ * Agent loop — drive a multi-turn conversation:
+ *   user_message → LLM → (text + tool_use*) → execute tools → repeat
+ *   until stop_reason === 'end_turn'.
+ *
+ * The loop is platform-agnostic. It depends on:
+ *   - ConversationStore  (events + blobs)
+ *   - ToolRegistry        (handler dispatch)
+ *   - LlmClient            (Anthropic, or any drop-in)
+ *   - WorkbookClient      (passed through to tool handlers)
+ *   - host-provided confirm / log callbacks
+ *
+ * The Anthropic SDK is NOT imported here. Hosts wire up a concrete
+ * LlmClient (the browser craft uses fetch + the Messages REST API, the
+ * node CLI uses @anthropic-ai/sdk). Keeping the boundary thin lets us
+ * test the loop without network and swap providers later.
+ */
+import { toLlmMessages, } from '../projection.js';
+export class Agent {
+    constructor(opts) {
+        var _a, _b, _c, _d, _e;
+        this.store = opts.store;
+        this.registry = opts.registry;
+        this.llm = opts.llm;
+        this.workbook = opts.workbook;
+        this.model = (_a = opts.model) !== null && _a !== void 0 ? _a : 'claude-opus-4-8';
+        this.maxTokens = (_b = opts.max_tokens) !== null && _b !== void 0 ? _b : 4096;
+        this.systemPrompt = opts.systemPrompt;
+        this.maxToolIters = (_c = opts.max_tool_iterations) !== null && _c !== void 0 ? _c : 16;
+        // Default confirm: auto-approve. Browser host overrides with a
+        // real modal. CLI host can override with stdin prompt.
+        this.confirm =
+            (_d = opts.confirm) !== null && _d !== void 0 ? _d : (async () => ({ approved: true }));
+        this.log = (_e = opts.log) !== null && _e !== void 0 ? _e : (() => { });
+        this.craftInteractions = opts.craftInteractions;
+    }
+    /**
+     * Run one user turn end-to-end: append the user_message, then loop
+     * LLM ↔ tools until the model emits end_turn or we hit a safety cap.
+     */
+    async runTurn(conversation_id, userText, signal) {
+        const userEvent = {
+            kind: 'user_message',
+            id: newEventId(),
+            conversation_id,
+            ts: nowMs(),
+            text: userText,
+        };
+        await this.store.appendEvent(userEvent);
+        const blobResolver = (ref) => {
+            // listEvents is async; the loop pre-hydrates blobs into a
+            // synchronous cache before each LLM call below. Default
+            // fallback returns null (projection emits a placeholder).
+            return null;
+        };
+        let iter = 0;
+        for (;;) {
+            if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                await this.appendNote(conversation_id, 'Turn aborted by user.', 'ui_only');
+                return;
+            }
+            if (iter++ > this.maxToolIters) {
+                await this.appendNote(conversation_id, `Tool-iteration cap (${this.maxToolIters}) reached. Stopping.`, 'ui_only');
+                return;
+            }
+            const events = await this.store.listEvents(conversation_id);
+            const messages = toLlmMessages(events, { resolveBlob: blobResolver });
+            const response = await this.llm.createMessage({
+                model: this.model,
+                system: this.buildSystem(),
+                tools: this.registry.toLlmTools(),
+                messages,
+                max_tokens: this.maxTokens,
+                signal,
+            });
+            const turn_id = newTurnId();
+            const toolCalls = [];
+            // First pass: persist every assistant content block as an event
+            // *before* executing any tool. This way a crash mid-tool-run
+            // leaves the assistant's intent on record and we can recover.
+            for (const block of response.content) {
+                if (block.type === 'text') {
+                    const e = {
+                        kind: 'assistant_text',
+                        id: newEventId(),
+                        conversation_id,
+                        ts: nowMs(),
+                        text: block.text,
+                        turn_id,
+                    };
+                    await this.store.appendEvent(e);
+                }
+                else if (block.type === 'tool_use') {
+                    const e = {
+                        kind: 'tool_call',
+                        id: newEventId(),
+                        conversation_id,
+                        ts: nowMs(),
+                        tool_use_id: block.id,
+                        name: block.name,
+                        input: block.input,
+                        turn_id,
+                    };
+                    await this.store.appendEvent(e);
+                    toolCalls.push({
+                        id: block.id,
+                        name: block.name,
+                        input: block.input,
+                    });
+                }
+                // tool_result blocks in the response don't happen — the
+                // model never produces them, only consumes them.
+            }
+            // Second pass: execute every tool the model asked for. Anthropic
+            // requires *all* tool_results for the previous turn before the
+            // next request, so we walk them sequentially here.
+            for (const call of toolCalls) {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                    return;
+                await this.executeToolCall(conversation_id, call, signal);
+            }
+            if (response.stop_reason === 'end_turn')
+                break;
+            if (response.stop_reason === 'max_tokens') {
+                await this.appendNote(conversation_id, 'Response truncated at max_tokens.', 'ui_only');
+                break;
+            }
+            // Any other stop_reason (incl. 'tool_use') — loop to next request.
+        }
+    }
+    // -----------------------------------------------------------------------
+    async executeToolCall(conversation_id, call, signal) {
+        var _a, _b;
+        const tool = this.registry.get(call.name);
+        const start = nowMs();
+        if (!tool) {
+            const e = {
+                kind: 'tool_result',
+                id: newEventId(),
+                conversation_id,
+                ts: nowMs(),
+                tool_use_id: call.id,
+                output: null,
+                error: `Unknown tool: ${call.name}`,
+                duration_ms: 0,
+            };
+            await this.store.appendEvent(e);
+            return;
+        }
+        // Confirmation gate.
+        const policy = (_a = tool.confirmation) !== null && _a !== void 0 ? _a : (tool.mutates ? 'always' : 'never');
+        if (policy !== 'never') {
+            const decision = await this.confirm(call.name, call.input, policy);
+            const ev = {
+                kind: 'user_confirm',
+                id: newEventId(),
+                conversation_id,
+                ts: nowMs(),
+                tool_use_id: call.id,
+                approved: decision.approved,
+                reason: decision.reason,
+            };
+            await this.store.appendEvent(ev);
+            if (!decision.approved) {
+                const e = {
+                    kind: 'tool_result',
+                    id: newEventId(),
+                    conversation_id,
+                    ts: nowMs(),
+                    tool_use_id: call.id,
+                    output: null,
+                    error: `User declined${decision.reason ? `: ${decision.reason}` : '.'}`,
+                    duration_ms: nowMs() - start,
+                };
+                await this.store.appendEvent(e);
+                return;
+            }
+        }
+        // Run handler.
+        const ctx = {
+            workbook: this.workbook,
+            signal: signal !== null && signal !== void 0 ? signal : new AbortController().signal,
+            confirm: async (msg, detail) => {
+                const d = await this.confirm(call.name, { message: msg, detail }, 'always');
+                return d.approved;
+            },
+            log: (msg) => this.log(`[${call.name}] ${msg}`),
+            craftInteractions: this.craftInteractions,
+        };
+        try {
+            const result = await tool.handler(call.input, ctx);
+            const e = {
+                kind: 'tool_result',
+                id: newEventId(),
+                conversation_id,
+                ts: nowMs(),
+                tool_use_id: call.id,
+                output: result.canceled
+                    ? { canceled: true }
+                    : (_b = result.data) !== null && _b !== void 0 ? _b : null,
+                duration_ms: nowMs() - start,
+            };
+            await this.store.appendEvent(e);
+        }
+        catch (err) {
+            const e = {
+                kind: 'tool_result',
+                id: newEventId(),
+                conversation_id,
+                ts: nowMs(),
+                tool_use_id: call.id,
+                output: null,
+                error: err instanceof Error ? err.message : String(err),
+                duration_ms: nowMs() - start,
+            };
+            await this.store.appendEvent(e);
+        }
+    }
+    buildSystem() {
+        // Two blocks so prompt caching works cleanly:
+        //   [0] = user-supplied system prompt (stable, cached)
+        //   [1] = tool list (also stable across a turn; we cache here too
+        //         because the same tools are reused across many turns)
+        // The Messages API treats every block as a sub-prompt; the last
+        // cache_control marker wins for that prefix.
+        return [
+            {
+                type: 'text',
+                text: this.systemPrompt,
+                cache_control: { type: 'ephemeral' },
+            },
+        ];
+    }
+    async appendNote(conversation_id, text, visibility) {
+        const e = {
+            kind: 'system_note',
+            id: newEventId(),
+            conversation_id,
+            ts: nowMs(),
+            text,
+            visibility,
+        };
+        await this.store.appendEvent(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// id / time helpers — kept local so the loop has no implicit globals
+// ---------------------------------------------------------------------------
+function newEventId() {
+    return `evt_${nowMs().toString(36)}_${shortRand()}`;
+}
+function newTurnId() {
+    return `turn_${nowMs().toString(36)}_${shortRand()}`;
+}
+function nowMs() {
+    return Date.now();
+}
+function shortRand() {
+    return Math.random().toString(36).slice(2, 10);
+}

package/dist/conversation.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Conversation event stream — the single source of truth for an
+ * agent session. UI transcripts and LLM `messages` arrays are both
+ * pure projections of this stream.
+ *
+ * Events are append-only. The agent loop never rewrites or deletes.
+ * Old events may be elided via summarization (a `system_note` replacing
+ * a prefix) but the original events remain for replay and debugging.
+ */
+/** Discriminated union of everything that can happen in a conversation. */
+export type ConversationEvent = UserMessageEvent | AssistantTextEvent | ToolCallEvent | ToolResultEvent | UserConfirmEvent | SystemNoteEvent;
+export interface BaseEvent {
+    /** Unique id, monotonically sortable (UUIDv7 or `${ts}-${rand}`). */
+    id: string;
+    /** Conversation foreign key. */
+    conversation_id: string;
+    /** Epoch ms when the event was recorded. */
+    ts: number;
+}
+export interface UserMessageEvent extends BaseEvent {
+    kind: 'user_message';
+    text: string;
+}
+export interface AssistantTextEvent extends BaseEvent {
+    kind: 'assistant_text';
+    text: string;
+    /**
+     * The model can emit multiple text blocks interleaved with tool calls
+     * in a single turn. `turn_id` groups events that belong to the same
+     * LLM response.
+     */
+    turn_id: string;
+}
+export interface ToolCallEvent extends BaseEvent {
+    kind: 'tool_call';
+    /** Anthropic's tool_use_id — used to correlate with tool_result. */
+    tool_use_id: string;
+    /** Fully-qualified tool name, e.g. "build__create_block". */
+    name: string;
+    /** Validated input object. */
+    input: unknown;
+    turn_id: string;
+}
+export interface ToolResultEvent extends BaseEvent {
+    kind: 'tool_result';
+    tool_use_id: string;
+    /**
+     * Output payload, or a blob ref when the value is large. Large outputs
+     * (e.g. describe_block with include_rows=true) should be stored via
+     * `ConversationStore.putBlob` and referenced here as
+     * `{kind: 'blob_ref', ref: '...'}` to keep events table compact.
+     */
+    output: unknown;
+    /** Set when the handler threw. `output` then holds an error summary. */
+    error?: string;
+    /** Total time the handler spent, ms. */
+    duration_ms: number;
+}
+export interface UserConfirmEvent extends BaseEvent {
+    kind: 'user_confirm';
+    tool_use_id: string;
+    approved: boolean;
+    /** Optional reason the user typed when rejecting. */
+    reason?: string;
+}
+export interface SystemNoteEvent extends BaseEvent {
+    kind: 'system_note';
+    text: string;
+    /**
+     * Tag used by projection logic to decide visibility. e.g.:
+     *   'summary'     — replaces an elided prefix, must enter LLM context
+     *   'ui_only'     — surface to user but skip in LLM messages
+     *   'debug'       — internal trace, neither projected to UI nor LLM
+     */
+    visibility: 'summary' | 'ui_only' | 'debug';
+}
+export interface Conversation {
+    id: string;
+    /** Auto-generated or user-renamed, shown in the sidebar. */
+    title: string;
+    /** Workbook this conversation is bound to. Optional for cross-workbook chats. */
+    workbook_id?: string;
+    /** Anthropic model id, e.g. "claude-opus-4-8". */
+    model: string;
+    created_at: number;
+    updated_at: number;
+    /** Optional free-form metadata for forward-compat (skill name, locale, …). */
+    extra?: Record<string, unknown>;
+}
+/** Lightweight shape for sidebars / pickers — no events. */
+export interface ConversationSummary {
+    id: string;
+    title: string;
+    workbook_id?: string;
+    updated_at: number;
+    /** Cached event count for the badge; null means "unknown, query if needed". */
+    event_count?: number;
+}
+/** Bundle returned by an export. */
+export interface ConversationExport {
+    conversation: Conversation;
+    events: ConversationEvent[];
+    /** Inlined blob payloads keyed by ref. */
+    blobs: Record<string, string | Uint8Array>;
+}

package/dist/conversation.js

@@ -0,0 +1,10 @@
+/**
+ * Conversation event stream — the single source of truth for an
+ * agent session. UI transcripts and LLM `messages` arrays are both
+ * pure projections of this stream.
+ *
+ * Events are append-only. The agent loop never rewrites or deletes.
+ * Old events may be elided via summarization (a `system_note` replacing
+ * a prefix) but the original events remain for replay and debugging.
+ */
+export {};

package/dist/craft-interactions-api.d.ts

@@ -0,0 +1,81 @@
+/**
+ * CraftInteractionsApi — the host capability surface for craft-defined
+ * cell-overlay widgets (radio groups, multi-select, point allocators,
+ * percent allocators, number sliders).
+ *
+ * Scope: BUILD + READ. This mirrors what the host injects into a craft
+ * iframe (`injectCraftInteractionAPIs`): a craft *registers* overlays onto
+ * block cells and *reads* what the user selected — it does NOT
+ * programmatically set selections (the user operates the overlay by
+ * clicking). Watson, being a craft that builds factory-simulator-like
+ * apps, needs exactly this build+read surface.
+ *
+ * Why an interface in logician (not an import of the host module):
+ * craft-interaction state is module singletons in the browser host
+ * (`src/core/craft-interactions`), which logician must not depend on —
+ * logician is platform-agnostic and reusable from a Node CLI / MCP server.
+ * The host implements this interface and passes it via
+ * `ToolContext.craftInteractions`; tools program against the interface
+ * only and report "not available" when it's absent.
+ *
+ * Method names and binding shapes mirror the injected window API 1:1, so
+ * the Watson host adapter is a thin pass-through:
+ *   { registerRadio: window.registerRadio, ... }
+ */
+/** A cell an overlay binds to. `row`/`col` are block-relative offsets —
+ *  the same coordinates the host singletons use. Tools resolve these from
+ *  (block ref, field, row_key) via the block schema before calling. */
+export interface InteractionCell {
+    groupId: string;
+    sheetIdx: number;
+    blockId: number;
+    row: number;
+    col: number;
+}
+export interface RadioBindingArg extends InteractionCell {
+    value: string;
+}
+export interface MultiSelectBindingArg extends InteractionCell {
+    value: string;
+}
+export type PointAllocatorBindingArg = InteractionCell;
+export type PercentAllocatorBindingArg = InteractionCell;
+export interface NumberSliderBindingArg extends InteractionCell {
+    min: number;
+    max: number;
+    step?: number;
+    initialValue?: number;
+}
+export interface PointAllocationInfo {
+    blockId: number;
+    row: number;
+    col: number;
+    points: number;
+}
+/**
+ * Register + read surface. All methods are synchronous: the host holds
+ * overlay bindings and the user's selections in memory, and registration
+ * does not touch the workbook transaction/undo stack.
+ */
+export interface CraftInteractionsApi {
+    registerRadio(binding: RadioBindingArg): void;
+    registerMultiSelect(binding: MultiSelectBindingArg): void;
+    setMultiSelectMax(groupId: string, max: number): void;
+    registerPointAllocator(binding: PointAllocatorBindingArg): void;
+    setPointPool(groupId: string, total: number): void;
+    registerPercentAllocator(binding: PercentAllocatorBindingArg): void;
+    registerNumberSlider(binding: NumberSliderBindingArg): void;
+    clearRadios(groupId?: string): void;
+    clearMultiSelects(groupId?: string): void;
+    clearPointAllocators(groupId?: string): void;
+    clearPercentAllocators(groupId?: string): void;
+    clearNumberSliders(groupId?: string): void;
+    getRadioSelection(groupId: string): string | undefined;
+    getMultiSelectSelections(groupId: string): readonly string[];
+    getPointPool(groupId: string): {
+        total: number;
+        used: number;
+        remaining: number;
+    };
+    getPointAllocations(groupId: string): readonly PointAllocationInfo[];
+}

package/dist/craft-interactions-api.js

@@ -0,0 +1,25 @@
+/**
+ * CraftInteractionsApi — the host capability surface for craft-defined
+ * cell-overlay widgets (radio groups, multi-select, point allocators,
+ * percent allocators, number sliders).
+ *
+ * Scope: BUILD + READ. This mirrors what the host injects into a craft
+ * iframe (`injectCraftInteractionAPIs`): a craft *registers* overlays onto
+ * block cells and *reads* what the user selected — it does NOT
+ * programmatically set selections (the user operates the overlay by
+ * clicking). Watson, being a craft that builds factory-simulator-like
+ * apps, needs exactly this build+read surface.
+ *
+ * Why an interface in logician (not an import of the host module):
+ * craft-interaction state is module singletons in the browser host
+ * (`src/core/craft-interactions`), which logician must not depend on —
+ * logician is platform-agnostic and reusable from a Node CLI / MCP server.
+ * The host implements this interface and passes it via
+ * `ToolContext.craftInteractions`; tools program against the interface
+ * only and report "not available" when it's absent.
+ *
+ * Method names and binding shapes mirror the injected window API 1:1, so
+ * the Watson host adapter is a thin pass-through:
+ *   { registerRadio: window.registerRadio, ... }
+ */
+export {};

package/dist/craft-interactions-core.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A {@link CraftInteractionsApi} implementation backed directly by
+ * logisheets-core's craft-interactions singletons.
+ *
+ * Use this when logician runs IN-PROCESS with the engine logic — i.e. a Node
+ * runtime (logisheets-runtime), or any non-iframe host. The browser/Watson
+ * path still uses the window-global adapter, because a craft iframe has its
+ * own module instances and must bridge to the *host page's* singletons across
+ * the iframe boundary; importing core there would yield a fresh, isolated
+ * store. In-process (Node), there is no boundary, so delegating straight to
+ * core is correct and removes the window dependency entirely.
+ */
+import type { CraftInteractionsApi } from './craft-interactions-api.js';
+export declare function createCoreCraftInteractions(): CraftInteractionsApi;