logisheets-logician 1.11.0

package/dist/tool.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Tool — a single capability that the LLM can invoke.
+ *
+ * Design notes:
+ *   - `name` / `description` / `inputSchema` are what get serialized into the
+ *     LLM request's `tools` array (Anthropic / OpenAI compatible shape).
+ *   - `handler` is the local executor. It receives the validated input plus a
+ *     `ToolContext` that carries the workbook handle and any UI hooks.
+ *   - `confirmation` lets a tool opt into a user-confirmation step before the
+ *     handler runs — important for any write that touches the workbook.
+ *   - Tools are grouped under a `namespace` (e.g. "block", "craft.what_if")
+ *     so the final tool name exposed to the LLM is `${namespace}__${name}`.
+ *     This keeps capabilities from different crafts from colliding.
+ */
+import type { Client } from 'logisheets-web/pure';
+import type { CraftInteractionsApi } from './craft-interactions-api.js';
+/**
+ * Workbook client surface used by tool handlers. We re-export the `Client`
+ * type from `logisheets-web` so hosts can import it from a single place,
+ * and so a future headless adapter (logisheets-node) — which implements the
+ * same interface — can be plugged in without changes to tool code.
+ */
+export type WorkbookClient = Client;
+/** JSON Schema draft-07 subset; kept loose on purpose. */
+export type JSONSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+export type JSONSchema = {
+    /** A single type or a union (e.g. ['string', 'null'] for nullable). */
+    type?: JSONSchemaType | readonly JSONSchemaType[];
+    description?: string;
+    properties?: Record<string, JSONSchema>;
+    required?: readonly string[];
+    items?: JSONSchema;
+    enum?: readonly (string | number)[];
+    default?: unknown;
+    minItems?: number;
+    maxItems?: number;
+    minimum?: number;
+    maximum?: number;
+    [k: string]: unknown;
+};
+/** Confirmation policy for a tool invocation. */
+export type ConfirmationPolicy = 'never' | 'once' | 'always' | 'destructive';
+/** Hint to the model (and to the scheduler) about cost. */
+export type ToolCost = 'cheap' | 'normal' | 'expensive';
+/**
+ * Scoped read/write access to a craft's persisted state (the opaque per-document
+ * JSON a craft owns via the host's AppData). Present on the ToolContext only for
+ * craft-skill tools, scoped to that craft — so a tool can operate the craft's
+ * stateful feature (a game board, a saved config) and stay consistent with the
+ * craft's own persistence. The schema is the craft's business (it JSON-encodes
+ * it itself), exactly like `window.getCraftState()`/`setCraftState()` in a craft.
+ */
+export interface CraftStateAccess {
+    get(): string | undefined;
+    set(json: string): void;
+}
+/** Context passed to every tool handler. */
+export interface ToolContext {
+    /** The active LogiSheets workbook client. */
+    workbook: WorkbookClient;
+    /** Abort signal — fires if the user cancels the in-flight turn. */
+    signal: AbortSignal;
+    /** Ask the user to confirm an action; returns true if approved. */
+    confirm: (message: string, detail?: unknown) => Promise<boolean>;
+    /** Emit a progress / log line into the chat transcript. */
+    log: (msg: string) => void;
+    /**
+     * Persisted state of the craft this tool belongs to, scoped to that craft.
+     * Present only for craft-skill tools whose host wired a craftState provider;
+     * undefined for the built-in tools and headless hosts. A craft tool that
+     * needs it should degrade gracefully when it is absent.
+     */
+    craftState?: CraftStateAccess;
+    /**
+     * Craft-defined cell-overlay widgets (radio / multi-select / point /
+     * percent / slider). Optional: present only when the host has craft
+     * interactions (browser app). Absent in headless hosts — craft-
+     * interaction tools detect this and return a "not available" result
+     * rather than throwing.
+     */
+    craftInteractions?: CraftInteractionsApi;
+}
+/** Structured result returned by a handler. */
+export interface ToolResult<T = unknown> {
+    /** Payload shown back to the LLM as `tool_result.content`. */
+    data: T;
+    /** Optional human-readable summary rendered into the chat UI. */
+    display?: string;
+    /** Set when the user declined a confirmation. */
+    canceled?: boolean;
+}
+export interface Tool<Input = unknown, Output = unknown> {
+    namespace: string;
+    /** Tool name within the namespace. snake_case. No "__". */
+    name: string;
+    /** One-line description; the model uses this to decide when to call. */
+    description: string;
+    /** JSON Schema for the `input` argument. */
+    inputSchema: JSONSchema;
+    /** Whether this tool mutates workbook state. */
+    mutates: boolean;
+    /** Confirmation policy; defaults to 'never' for reads, 'always' for writes. */
+    confirmation?: ConfirmationPolicy;
+    /** Cost hint; defaults to 'normal'. */
+    cost?: ToolCost;
+    /**
+     * Multi-level category path for organizing tools into a tree (e.g.
+     * ['Data', 'Write'] or ['Structure', 'Sheets']). Purely organizational —
+     * NOT part of the LLM-facing id (`namespace__name`). Optional: when absent,
+     * a built-in default taxonomy is used (see tools/taxonomy.ts). A craft tool
+     * may set it to slot itself into the tree.
+     */
+    category?: readonly string[];
+    /** Execute the tool. Throw to signal an error to the LLM. */
+    handler: (input: Input, ctx: ToolContext) => Promise<ToolResult<Output>>;
+}
+/** Fully-qualified tool id as exposed to the LLM. */
+export declare function toolId(t: Pick<Tool, 'namespace' | 'name'>): string;
+/** Serialize a tool into the Anthropic `tools` array shape. */
+export declare function toLlmTool(t: Tool): {
+    name: string;
+    description: string;
+    input_schema: JSONSchema;
+};
+/**
+ * In-memory tool registry. Hosts populate this at startup (or lazily) and
+ * pass it to the Agent loop, which dispatches by fully-qualified id.
+ */
+export declare class ToolRegistry {
+    private tools;
+    register(tool: Tool): void;
+    registerMany(tools: ReadonlyArray<Tool>): void;
+    unregister(id: string): void;
+    get(id: string): Tool | undefined;
+    list(): Tool[];
+    toLlmTools(): ReturnType<typeof toLlmTool>[];
+}

package/dist/tool.js

@@ -0,0 +1,57 @@
+/**
+ * Tool — a single capability that the LLM can invoke.
+ *
+ * Design notes:
+ *   - `name` / `description` / `inputSchema` are what get serialized into the
+ *     LLM request's `tools` array (Anthropic / OpenAI compatible shape).
+ *   - `handler` is the local executor. It receives the validated input plus a
+ *     `ToolContext` that carries the workbook handle and any UI hooks.
+ *   - `confirmation` lets a tool opt into a user-confirmation step before the
+ *     handler runs — important for any write that touches the workbook.
+ *   - Tools are grouped under a `namespace` (e.g. "block", "craft.what_if")
+ *     so the final tool name exposed to the LLM is `${namespace}__${name}`.
+ *     This keeps capabilities from different crafts from colliding.
+ */
+/** Fully-qualified tool id as exposed to the LLM. */
+export function toolId(t) {
+    return `${t.namespace}__${t.name}`;
+}
+/** Serialize a tool into the Anthropic `tools` array shape. */
+export function toLlmTool(t) {
+    return {
+        name: toolId(t),
+        description: t.description,
+        input_schema: { type: 'object', ...t.inputSchema },
+    };
+}
+/**
+ * In-memory tool registry. Hosts populate this at startup (or lazily) and
+ * pass it to the Agent loop, which dispatches by fully-qualified id.
+ */
+export class ToolRegistry {
+    constructor() {
+        this.tools = new Map();
+    }
+    register(tool) {
+        const id = toolId(tool);
+        if (this.tools.has(id))
+            throw new Error(`Tool already registered: ${id}`);
+        this.tools.set(id, tool);
+    }
+    registerMany(tools) {
+        for (const t of tools)
+            this.register(t);
+    }
+    unregister(id) {
+        this.tools.delete(id);
+    }
+    get(id) {
+        return this.tools.get(id);
+    }
+    list() {
+        return [...this.tools.values()];
+    }
+    toLlmTools() {
+        return this.list().map(toLlmTool);
+    }
+}

package/dist/tools/block-ops.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Advanced block ops — move, resize, and remove whole blocks. Blocks are
+ * addressed by numeric blockId (from create_block's result or list_blocks'
+ * block_id field). Row/column edits inside a block live in the build tools
+ * (add_block_rows / delete_block_rows).
+ */
+import type { Tool } from '../tool.js';
+export declare const moveBlock: Tool<{
+    sheetIdx: number;
+    blockId: number;
+    newMasterRow: number;
+    newMasterCol: number;
+}, {
+    ok: true;
+}>;
+export declare const resizeBlock: Tool<{
+    sheetIdx: number;
+    blockId: number;
+    newRowCnt?: number;
+    newColCnt?: number;
+}, {
+    ok: true;
+}>;
+export declare const removeBlock: Tool<{
+    sheetIdx: number;
+    blockId: number;
+}, {
+    ok: true;
+}>;
+export declare const BLOCK_OPS_TOOLS: Tool[];

package/dist/tools/block-ops.js

@@ -0,0 +1,97 @@
+/**
+ * Advanced block ops — move, resize, and remove whole blocks. Blocks are
+ * addressed by numeric blockId (from create_block's result or list_blocks'
+ * block_id field). Row/column edits inside a block live in the build tools
+ * (add_block_rows / delete_block_rows).
+ */
+import { isErrorMessage } from 'logisheets-web/pure';
+function asClient(ctx) {
+    return ctx.workbook;
+}
+async function commit(client, payload, label) {
+    const tx = { payloads: [payload], undoable: true, temp: false };
+    const r = await client.handleTransaction({ transaction: tx });
+    if (isErrorMessage(r))
+        throw new Error(`${label}: ${r.msg}`);
+    if (r.status.type === 'err')
+        throw new Error(`${label}: status code ${r.status.value}`);
+}
+export const moveBlock = {
+    namespace: 'build',
+    name: 'move_block',
+    description: 'Move a whole block so its top-left (master) cell lands at a new zero-based (row, col). Get blockId from list_blocks or create_block.',
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            blockId: { type: 'integer' },
+            newMasterRow: { type: 'integer', description: 'New top-left row (zero-based).' },
+            newMasterCol: { type: 'integer', description: 'New top-left column (zero-based).' },
+        },
+        required: ['sheetIdx', 'blockId', 'newMasterRow', 'newMasterCol'],
+    },
+    handler: async (input, ctx) => {
+        await commit(asClient(ctx), {
+            type: 'moveBlock',
+            value: {
+                sheetIdx: input.sheetIdx,
+                id: input.blockId,
+                newMasterRow: input.newMasterRow,
+                newMasterCol: input.newMasterCol,
+            },
+        }, 'move_block');
+        return { data: { ok: true }, display: `Moved block ${input.blockId}` };
+    },
+};
+export const resizeBlock = {
+    namespace: 'build',
+    name: 'resize_block',
+    description: 'Resize a block to a new row and/or column count (omit one to leave that dimension unchanged). Get blockId from list_blocks.',
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            blockId: { type: 'integer' },
+            newRowCnt: { type: 'integer', description: 'New number of rows.' },
+            newColCnt: { type: 'integer', description: 'New number of columns.' },
+        },
+        required: ['sheetIdx', 'blockId'],
+    },
+    handler: async (input, ctx) => {
+        await commit(asClient(ctx), {
+            type: 'resizeBlock',
+            value: {
+                sheetIdx: input.sheetIdx,
+                id: input.blockId,
+                newRowCnt: input.newRowCnt,
+                newColCnt: input.newColCnt,
+            },
+        }, 'resize_block');
+        return { data: { ok: true }, display: `Resized block ${input.blockId}` };
+    },
+};
+export const removeBlock = {
+    namespace: 'build',
+    name: 'remove_block',
+    description: 'Remove a whole block (its schema and cells) by blockId. Get blockId from list_blocks.',
+    mutates: true,
+    confirmation: 'destructive',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            blockId: { type: 'integer' },
+        },
+        required: ['sheetIdx', 'blockId'],
+    },
+    handler: async (input, ctx) => {
+        await commit(asClient(ctx), { type: 'removeBlock', value: { sheetIdx: input.sheetIdx, id: input.blockId } }, 'remove_block');
+        return { data: { ok: true }, display: `Removed block ${input.blockId}` };
+    },
+};
+export const BLOCK_OPS_TOOLS = [
+    moveBlock,
+    resizeBlock,
+    removeBlock,
+];

package/dist/tools/builder.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Builder tools — let the LLM construct block-shaped models in a workbook
+ * from a natural-language description.
+ *
+ * Surface (10 tools, block-only — no raw (sheet,row,col) writes):
+ *   Structure  : create_sheet, create_block, add_block_rows, delete_block_rows
+ *   Rules      : set_field_rule, define_enum_set
+ *   Reflection : list_blocks, describe_block, eval_formula
+ *   Safety     : checkpoint / restore       (one tool, two ops)
+ *
+ * Handlers below are intentionally thin — they describe the contract.
+ * Real implementations will dispatch to the workbook client + block manager.
+ */
+import type { Tool } from '../tool.js';
+declare const FIELD_TYPE_ENUM: readonly ["string", "number", "boolean", "enum", "date", "datetime"];
+export declare const createSheet: Tool<{
+    name: string;
+}, {
+    sheet_idx: number;
+}>;
+interface CreateBlockInput {
+    sheet: string;
+    name: string;
+    position: {
+        row: number;
+        col: number;
+    };
+    fields: ReadonlyArray<{
+        name: string;
+        field_type?: (typeof FIELD_TYPE_ENUM)[number];
+        num_fmt?: string;
+        enum_id?: string;
+        user_editable?: boolean;
+    }>;
+    initial_rows?: ReadonlyArray<{
+        key: string;
+        values?: Record<string, unknown>;
+    }>;
+}
+export declare const createBlock: Tool<CreateBlockInput, {
+    block_id: number;
+}>;
+interface AddBlockRowsInput {
+    block: string;
+    rows: ReadonlyArray<{
+        key: string;
+        values?: Record<string, unknown>;
+    }>;
+}
+export declare const addBlockRows: Tool<AddBlockRowsInput, {
+    added: number;
+}>;
+interface DeleteBlockRowsInput {
+    block: string;
+    keys: ReadonlyArray<string>;
+}
+export declare const deleteBlockRows: Tool<DeleteBlockRowsInput, {
+    removed: number;
+}>;
+interface SetFieldRuleInput {
+    block: string;
+    field: string;
+    value_formula?: string | null;
+    validation?: string | null;
+    editability?: string | null;
+}
+export declare const setFieldRule: Tool<SetFieldRuleInput, {
+    applied: string[];
+}>;
+interface EnumVariantInput {
+    id: string;
+    label: string;
+    /** Hex color (#RRGGBB). Auto-assigned from a palette if omitted. */
+    color?: string;
+}
+interface DefineEnumSetInput {
+    id: string;
+    name?: string;
+    description?: string;
+    variants: ReadonlyArray<EnumVariantInput>;
+}
+interface DefineEnumSetOutput {
+    enum_id: string;
+    variant_count: number;
+    /** echoed variant id list so AI's next call (e.g. create_block with
+     *  field_type='enum') has the canonical id strings handy. */
+    variant_ids: string[];
+}
+export declare const defineEnumSet: Tool<DefineEnumSetInput, DefineEnumSetOutput>;
+/** Watson-session enum registry. Mirror of what's in the host's
+ *  enumSetManager when available, plus a fallback for headless. Read by
+ *  the create_block handler when a field declares `field_type: 'enum'`
+ *  so it can auto-inject a variant whitelist validation. */
+export declare const _enumSetCache: Map<string, {
+    id: string;
+    name: string;
+    description?: string;
+    variants: ReadonlyArray<{
+        id: string;
+        value: string;
+        color: string;
+    }>;
+}>;
+interface ListBlocksInput {
+    sheet?: string;
+}
+interface BlockSummary {
+    name: string;
+    /** Numeric block id — pass to move_block / resize_block / remove_block. */
+    block_id: number;
+    position: {
+        row: number;
+        col: number;
+    };
+    row_count: number;
+    col_count: number;
+}
+interface SheetBlockGroup {
+    sheet_name: string;
+    sheet_idx: number;
+    blocks: BlockSummary[];
+    /**
+     * Suggested (row, col) for the next new block on this sheet, assuming
+     * blocks don't share rows (one block per row range). A one-row gap
+     * is reserved after the bottom-most block for readability. Use this
+     * as the `position` argument to `create_block`. For an empty sheet
+     * this is (0, 0).
+     */
+    next_block_start: {
+        row: number;
+        col: number;
+    };
+}
+export declare const listBlocks: Tool<ListBlocksInput, SheetBlockGroup[]>;
+interface DescribeBlockInput {
+    name: string;
+    include_rows?: boolean;
+}
+interface FieldDescription {
+    name: string;
+    /** 0-based column index within the block. */
+    position: number;
+    /** Engine-computed cell value (raw template, no placeholder
+     *  expansion). `null` for free-form fields. */
+    value_formula: string | null;
+    /** Per-row boolean rule — host UI renders a warning marker when
+     *  it evaluates false. `null` if not declared. */
+    validation: string | null;
+    /** Per-row boolean rule — host permission patch gates writes
+     *  when it evaluates false. `null` if not declared. */
+    editability: string | null;
+}
+interface DescribeBlockOutput {
+    block: string;
+    sheet: string;
+    sheet_idx: number;
+    position: {
+        row: number;
+        col: number;
+    };
+    row_count: number;
+    col_count: number;
+    fields: FieldDescription[];
+    /** Row keys in block-row order. Always present (cheap). */
+    keys: string[];
+    /** Only when `include_rows=true`. Each entry maps every field name
+     *  to that cell's current value (string / number / boolean) or
+     *  null when empty. Formula errors surface as `"#ERR:..."` strings. */
+    rows?: Array<{
+        key: string;
+        values: Record<string, string | number | boolean | null>;
+    }>;
+}
+export declare const describeBlock: Tool<DescribeBlockInput, DescribeBlockOutput>;
+interface EvalFormulaInput {
+    expr: string;
+}
+interface EvalFormulaOutput {
+    /** Discriminated tag — `'empty'` when the formula returned an empty cell. */
+    type: 'str' | 'number' | 'bool' | 'error' | 'empty';
+    /** Coerced JSON value. Empty cells get `null`. Errors get the
+     *  engine's error code as a string. */
+    value: string | number | boolean | null;
+}
+export declare const evalFormula: Tool<EvalFormulaInput, EvalFormulaOutput>;
+interface CheckpointInput {
+    op: 'save' | 'restore' | 'delete' | 'list';
+    /** Required for save / restore / delete. Ignored for list. */
+    label?: string;
+    /** Human-readable note; only meaningful for save, echoed back by list. */
+    description?: string;
+}
+interface CheckpointOutput {
+    op: 'save' | 'restore' | 'delete' | 'list';
+    /** For save: total checkpoint count after the save.
+     *  For delete: true if the label existed. */
+    result?: number | boolean;
+    /** For list: enumerated checkpoints (newest first). */
+    checkpoints?: ReadonlyArray<{
+        label: string;
+        description?: string;
+    }>;
+}
+export declare const checkpoint: Tool<CheckpointInput, CheckpointOutput>;
+export declare const BUILDER_TOOLS: Tool[];
+export {};