logisheets-logician 1.11.0

package/dist/tools/cells.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Cell tools — general (non-block) read/write of arbitrary cells by
+ * (sheet, row, col). The build/edit tools are block-shaped; these cover
+ * ordinary spreadsheet work: "what's in B2:D10", "put 5 in A1", "clear this
+ * range". Watson addresses cells by zero-based row/col; results echo A1 refs
+ * so the model can talk about them naturally.
+ */
+import type { Tool } from '../tool.js';
+/** A cell value in a form the model reads directly (null = empty). */
+type ScalarValue = string | number | boolean | null;
+interface RangeInput {
+    sheetIdx: number;
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+interface CellReadout {
+    ref: string;
+    value: ScalarValue;
+    /** Present only when the cell holds a formula. */
+    formula?: string;
+}
+export declare const getCells: Tool<RangeInput, {
+    range: string;
+    cells: CellReadout[];
+}>;
+interface CellWrite {
+    row: number;
+    col: number;
+    content: string | number | boolean | null;
+}
+interface SetCellsInput {
+    sheetIdx: number;
+    cells: ReadonlyArray<CellWrite>;
+}
+export declare const setCells: Tool<SetCellsInput, {
+    written: number;
+}>;
+export declare const clearCells: Tool<RangeInput, {
+    cleared: number;
+}>;
+interface FillInput {
+    sheetIdx: number;
+    srcStartRow: number;
+    srcStartCol: number;
+    srcEndRow: number;
+    srcEndCol: number;
+    dstStartRow: number;
+    dstStartCol: number;
+    dstEndRow: number;
+    dstEndCol: number;
+}
+export declare const fillCells: Tool<FillInput, {
+    filled: number;
+}>;
+export declare const CELL_TOOLS: Tool[];
+export {};

package/dist/tools/cells.js

@@ -0,0 +1,263 @@
+/**
+ * Cell tools — general (non-block) read/write of arbitrary cells by
+ * (sheet, row, col). The build/edit tools are block-shaped; these cover
+ * ordinary spreadsheet work: "what's in B2:D10", "put 5 in A1", "clear this
+ * range". Watson addresses cells by zero-based row/col; results echo A1 refs
+ * so the model can talk about them naturally.
+ */
+import { isErrorMessage } from 'logisheets-web/pure';
+function asClient(ctx) {
+    return ctx.workbook;
+}
+async function commit(client, payloads, label) {
+    const tx = { payloads, undoable: true, temp: false };
+    const result = await client.handleTransaction({ transaction: tx });
+    if (isErrorMessage(result))
+        throw new Error(`${label}: ${result.msg}`);
+    if (result.status.type === 'err')
+        throw new Error(`${label}: status code ${result.status.value}`);
+}
+function valueToScalar(v) {
+    if (v === 'empty')
+        return null;
+    switch (v.type) {
+        case 'number':
+            return v.value;
+        case 'str':
+            return v.value;
+        case 'bool':
+            return v.value;
+        case 'error':
+            return `#${v.value}`;
+        default:
+            return null;
+    }
+}
+function colToA1(col) {
+    let c = col + 1;
+    let s = '';
+    while (c > 0) {
+        const m = (c - 1) % 26;
+        s = String.fromCharCode(65 + m) + s;
+        c = (c - m - 1) / 26;
+    }
+    return s;
+}
+function a1(row, col) {
+    return `${colToA1(col)}${row + 1}`;
+}
+/** cap on how many cells one call may read/clear, to keep tool calls bounded. */
+const MAX_RANGE = 500;
+/** cap on how many cells one set_cells call may write. */
+const MAX_WRITE = 200;
+const RANGE_SCHEMA = {
+    sheetIdx: { type: 'integer', description: 'Zero-based sheet index.' },
+    startRow: { type: 'integer', description: 'Zero-based first row.' },
+    startCol: { type: 'integer', description: 'Zero-based first column.' },
+    endRow: { type: 'integer', description: 'Zero-based last row (inclusive).' },
+    endCol: { type: 'integer', description: 'Zero-based last column (inclusive).' },
+};
+function normalizeRange(i) {
+    return {
+        sheetIdx: i.sheetIdx,
+        startRow: Math.min(i.startRow, i.endRow),
+        startCol: Math.min(i.startCol, i.endCol),
+        endRow: Math.max(i.startRow, i.endRow),
+        endCol: Math.max(i.startCol, i.endCol),
+    };
+}
+export const getCells = {
+    namespace: 'cell',
+    name: 'get_cells',
+    description: [
+        'Read the values (and formulas) in a rectangular range of cells, addressed by zero-based (sheetIdx, startRow, startCol, endRow, endCol).',
+        'Returns only the non-empty cells, each with its A1 ref, value, and formula (if any). Use this for ordinary "what is in these cells" questions; for a single computed result you can also use build eval_formula.',
+        `Reads at most ${MAX_RANGE} cells per call — narrow the range if it is bigger.`,
+    ].join('\n'),
+    mutates: false,
+    confirmation: 'never',
+    inputSchema: { properties: RANGE_SCHEMA, required: Object.keys(RANGE_SCHEMA) },
+    handler: async (input, ctx) => {
+        const r = normalizeRange(input);
+        const count = (r.endRow - r.startRow + 1) * (r.endCol - r.startCol + 1);
+        if (count > MAX_RANGE)
+            throw new Error(`range covers ${count} cells (max ${MAX_RANGE}); narrow it`);
+        const client = asClient(ctx);
+        // getCells (not getCellInfos — the latter is unimplemented in the
+        // engine worker) returns the range's CellInfo[] row-major.
+        const res = await client.getCells({
+            sheetIdx: r.sheetIdx,
+            startRow: r.startRow,
+            startCol: r.startCol,
+            endRow: r.endRow,
+            endCol: r.endCol,
+        });
+        if (isErrorMessage(res))
+            throw new Error(`get_cells: ${res.msg}`);
+        const infos = res;
+        const width = r.endCol - r.startCol + 1;
+        const cells = [];
+        infos.forEach((info, i) => {
+            const value = valueToScalar(info.value);
+            const formula = info.formula || undefined;
+            if (value === null && !formula)
+                return; // skip empties → compact
+            const row = r.startRow + Math.floor(i / width);
+            const col = r.startCol + (i % width);
+            const out = { ref: a1(row, col), value };
+            if (formula)
+                out.formula = formula;
+            cells.push(out);
+        });
+        return {
+            data: { range: `${a1(r.startRow, r.startCol)}:${a1(r.endRow, r.endCol)}`, cells },
+            display: `Read ${cells.length} non-empty cell(s) in ${a1(r.startRow, r.startCol)}:${a1(r.endRow, r.endCol)}`,
+        };
+    },
+};
+function contentToString(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    return String(v);
+}
+export const setCells = {
+    namespace: 'cell',
+    name: 'set_cells',
+    description: [
+        'Write one or more arbitrary cells on a sheet in a single atomic transaction (one undo step). Each cell is addressed by zero-based row/col.',
+        "Content is a literal (string / number / boolean) or a formula prefixed with '='. null or '' clears the cell.",
+        'For cells that belong to a block, prefer edit set_block_cells (it respects the schema); use this for plain, non-block cells.',
+        `At most ${MAX_WRITE} cells per call.`,
+    ].join('\n'),
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer', description: 'Zero-based sheet index.' },
+            cells: {
+                type: 'array',
+                minItems: 1,
+                items: {
+                    type: 'object',
+                    properties: {
+                        row: { type: 'integer', description: 'Zero-based row.' },
+                        col: { type: 'integer', description: 'Zero-based column.' },
+                        content: {
+                            type: ['string', 'number', 'boolean', 'null'],
+                            description: "Literal value, or a formula starting with '='. null clears.",
+                        },
+                    },
+                    required: ['row', 'col', 'content'],
+                },
+            },
+        },
+        required: ['sheetIdx', 'cells'],
+    },
+    handler: async (input, ctx) => {
+        if (input.cells.length > MAX_WRITE)
+            throw new Error(`${input.cells.length} cells (max ${MAX_WRITE}) — split into batches`);
+        const payloads = input.cells.map((c) => ({
+            type: 'cellInput',
+            value: {
+                sheetIdx: input.sheetIdx,
+                row: c.row,
+                col: c.col,
+                content: contentToString(c.content),
+            },
+        }));
+        await commit(asClient(ctx), payloads, 'set_cells');
+        return {
+            data: { written: input.cells.length },
+            display: `Wrote ${input.cells.length} cell(s)`,
+        };
+    },
+};
+// ---------------------------------------------------------------------------
+// clear_cells — clear the values in a rectangular range
+// ---------------------------------------------------------------------------
+export const clearCells = {
+    namespace: 'cell',
+    name: 'clear_cells',
+    description: [
+        'Clear the contents of every cell in a rectangular range, addressed by zero-based (sheetIdx, startRow, startCol, endRow, endCol). One undo step.',
+        `Clears at most ${MAX_RANGE} cells per call.`,
+    ].join('\n'),
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: { properties: RANGE_SCHEMA, required: Object.keys(RANGE_SCHEMA) },
+    handler: async (input, ctx) => {
+        const r = normalizeRange(input);
+        const count = (r.endRow - r.startRow + 1) * (r.endCol - r.startCol + 1);
+        if (count > MAX_RANGE)
+            throw new Error(`range covers ${count} cells (max ${MAX_RANGE}); narrow it`);
+        const payloads = [];
+        for (let row = r.startRow; row <= r.endRow; row++)
+            for (let col = r.startCol; col <= r.endCol; col++)
+                payloads.push({
+                    type: 'cellClear',
+                    value: { sheetIdx: r.sheetIdx, row, col },
+                });
+        await commit(asClient(ctx), payloads, 'clear_cells');
+        return {
+            data: { cleared: count },
+            display: `Cleared ${a1(r.startRow, r.startCol)}:${a1(r.endRow, r.endCol)}`,
+        };
+    },
+};
+export const fillCells = {
+    namespace: 'cell',
+    name: 'fill',
+    description: [
+        'Autofill a destination range from a source range — the "drag the fill handle" operation. Continues number/date series, copies values, and shifts relative formula references. All coordinates zero-based.',
+        'The destination should extend the source (e.g. src A1:A1, dst A2:A10 to fill down from A1; or src A1:B1, dst A1:B10 to fill that pair down).',
+    ].join('\n'),
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            srcStartRow: { type: 'integer' },
+            srcStartCol: { type: 'integer' },
+            srcEndRow: { type: 'integer' },
+            srcEndCol: { type: 'integer' },
+            dstStartRow: { type: 'integer' },
+            dstStartCol: { type: 'integer' },
+            dstEndRow: { type: 'integer' },
+            dstEndCol: { type: 'integer' },
+        },
+        required: [
+            'sheetIdx',
+            'srcStartRow',
+            'srcStartCol',
+            'srcEndRow',
+            'srcEndCol',
+            'dstStartRow',
+            'dstStartCol',
+            'dstEndRow',
+            'dstEndCol',
+        ],
+    },
+    handler: async (input, ctx) => {
+        const client = asClient(ctx);
+        // The engine predicts the filled cells (series continuation, relative
+        // formula shifting), then we commit them as ordinary cell inputs.
+        const predicted = await client.predictFill(input);
+        if (isErrorMessage(predicted))
+            throw new Error(`fill: ${predicted.msg}`);
+        const inputs = predicted;
+        const payloads = inputs.map((ci) => ({
+            type: 'cellInput',
+            value: ci,
+        }));
+        await commit(client, payloads, 'fill');
+        return { data: { filled: payloads.length }, display: `Filled ${payloads.length} cell(s)` };
+    },
+};
+export const CELL_TOOLS = [
+    getCells,
+    setCells,
+    clearCells,
+    fillCells,
+];

package/dist/tools/comments.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Comment tools — threaded cell comments. A comment is a thread anchored at a
+ * cell, with one or more notes (a root note + replies). Watson can list, add,
+ * reply, edit, resolve, and delete.
+ *
+ * Authorship: comments Watson creates are attributed to "Watson (AI)" by
+ * default (honest — the assistant added them). The user can override the name
+ * per call (e.g. "add a comment as Alice"). There is no global "current user"
+ * in the open-source app, so we don't invent one.
+ */
+import type { Tool } from '../tool.js';
+export declare const listComments: Tool<{
+    sheetIdx: number;
+}, unknown>;
+export declare const addComment: Tool<{
+    sheetIdx: number;
+    row: number;
+    col: number;
+    content: string;
+    authorName?: string;
+}, {
+    commentId: string;
+    cell: string;
+}>;
+export declare const replyComment: Tool<{
+    sheetIdx: number;
+    parentId: string;
+    content: string;
+    authorName?: string;
+}, {
+    commentId: string;
+    cell: string;
+}>;
+export declare const editComment: Tool<{
+    sheetIdx: number;
+    commentId: string;
+    content: string;
+}, {
+    ok: true;
+}>;
+export declare const resolveComment: Tool<{
+    sheetIdx: number;
+    commentId: string;
+    resolved: boolean;
+}, {
+    ok: true;
+}>;
+export declare const deleteComment: Tool<{
+    sheetIdx: number;
+    commentId: string;
+}, {
+    ok: true;
+}>;
+export declare const COMMENT_TOOLS: Tool[];

package/dist/tools/comments.js

@@ -0,0 +1,234 @@
+/**
+ * Comment tools — threaded cell comments. A comment is a thread anchored at a
+ * cell, with one or more notes (a root note + replies). Watson can list, add,
+ * reply, edit, resolve, and delete.
+ *
+ * Authorship: comments Watson creates are attributed to "Watson (AI)" by
+ * default (honest — the assistant added them). The user can override the name
+ * per call (e.g. "add a comment as Alice"). There is no global "current user"
+ * in the open-source app, so we don't invent one.
+ */
+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}`);
+}
+const DEFAULT_AUTHOR = 'Watson (AI)';
+function newGuid() {
+    var _a, _b, _c;
+    const g = globalThis;
+    const uuid = (_c = (_b = (_a = g.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : `${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+    return `{${uuid}}`;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function colToA1(col) {
+    let c = col + 1;
+    let s = '';
+    while (c > 0) {
+        const m = (c - 1) % 26;
+        s = String.fromCharCode(65 + m) + s;
+        c = (c - m - 1) / 26;
+    }
+    return s;
+}
+function a1(row, col) {
+    return `${colToA1(col)}${row + 1}`;
+}
+async function readComments(client, sheetIdx) {
+    const res = await client.getComments({ sheetIdx });
+    if (isErrorMessage(res))
+        throw new Error(`comments: ${res.msg}`);
+    return res;
+}
+// ---------------------------------------------------------------------------
+export const listComments = {
+    namespace: 'comment',
+    name: 'list_comments',
+    description: 'List the comment threads on a sheet. Each thread is anchored at a cell (A1 ref) and holds one or more notes (root + replies), each with its id, author, text, timestamp, and resolved flag.',
+    mutates: false,
+    confirmation: 'never',
+    inputSchema: {
+        properties: { sheetIdx: { type: 'integer', description: 'Zero-based sheet index.' } },
+        required: ['sheetIdx'],
+    },
+    handler: async (input, ctx) => {
+        const comments = await readComments(asClient(ctx), input.sheetIdx);
+        const threads = comments.map((c) => ({
+            cell: a1(c.row, c.col),
+            row: c.row,
+            col: c.col,
+            notes: c.notes.map((n) => {
+                var _a, _b;
+                return ({
+                    id: n.id,
+                    author: (_b = (_a = n.author) === null || _a === void 0 ? void 0 : _a.displayName) !== null && _b !== void 0 ? _b : '',
+                    content: n.content,
+                    dt: n.dt,
+                    resolved: n.resolved,
+                    parentId: n.parentId,
+                });
+            }),
+        }));
+        return { data: { threads }, display: `${threads.length} comment thread(s)` };
+    },
+};
+export const addComment = {
+    namespace: 'comment',
+    name: 'add_comment',
+    description: 'Start a new comment thread on a cell (zero-based row/col). Attributed to "Watson (AI)" unless you pass authorName.',
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            row: { type: 'integer' },
+            col: { type: 'integer' },
+            content: { type: 'string' },
+            authorName: { type: 'string', description: 'Override the comment author name.' },
+        },
+        required: ['sheetIdx', 'row', 'col', 'content'],
+    },
+    handler: async (input, ctx) => {
+        const commentId = newGuid();
+        await commit(asClient(ctx), {
+            type: 'addComment',
+            value: {
+                sheetIdx: input.sheetIdx,
+                row: input.row,
+                col: input.col,
+                commentId,
+                author: { displayName: input.authorName || DEFAULT_AUTHOR },
+                dt: nowIso(),
+                content: input.content,
+                mentions: [],
+            },
+        }, 'add_comment');
+        return {
+            data: { commentId, cell: a1(input.row, input.col) },
+            display: `Commented on ${a1(input.row, input.col)}`,
+        };
+    },
+};
+export const replyComment = {
+    namespace: 'comment',
+    name: 'reply_comment',
+    description: 'Reply to an existing comment thread. Pass the parentId of any note in the thread (from list_comments).',
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            parentId: { type: 'string', description: 'Id of a note in the target thread.' },
+            content: { type: 'string' },
+            authorName: { type: 'string' },
+        },
+        required: ['sheetIdx', 'parentId', 'content'],
+    },
+    handler: async (input, ctx) => {
+        const client = asClient(ctx);
+        const comments = await readComments(client, input.sheetIdx);
+        const thread = comments.find((c) => c.notes.some((n) => n.id === input.parentId));
+        if (!thread)
+            throw new Error(`reply_comment: no thread contains "${input.parentId}"`);
+        const commentId = newGuid();
+        await commit(client, {
+            type: 'addComment',
+            value: {
+                sheetIdx: input.sheetIdx,
+                row: thread.row,
+                col: thread.col,
+                commentId,
+                parentId: input.parentId,
+                author: { displayName: input.authorName || DEFAULT_AUTHOR },
+                dt: nowIso(),
+                content: input.content,
+                mentions: [],
+            },
+        }, 'reply_comment');
+        return { data: { commentId, cell: a1(thread.row, thread.col) }, display: 'Replied' };
+    },
+};
+export const editComment = {
+    namespace: 'comment',
+    name: 'edit_comment',
+    description: 'Change the text of an existing comment note (by its id).',
+    mutates: true,
+    confirmation: 'always',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            commentId: { type: 'string' },
+            content: { type: 'string' },
+        },
+        required: ['sheetIdx', 'commentId', 'content'],
+    },
+    handler: async (input, ctx) => {
+        await commit(asClient(ctx), {
+            type: 'editComment',
+            value: {
+                sheetIdx: input.sheetIdx,
+                commentId: input.commentId,
+                content: input.content,
+                mentions: [],
+            },
+        }, 'edit_comment');
+        return { data: { ok: true }, display: 'Edited' };
+    },
+};
+export const resolveComment = {
+    namespace: 'comment',
+    name: 'resolve_comment',
+    description: 'Mark a comment thread resolved (or unresolved) by a note id.',
+    mutates: true,
+    confirmation: 'never',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            commentId: { type: 'string' },
+            resolved: { type: 'boolean' },
+        },
+        required: ['sheetIdx', 'commentId', 'resolved'],
+    },
+    handler: async (input, ctx) => {
+        await commit(asClient(ctx), { type: 'resolveComment', value: input }, 'resolve_comment');
+        return {
+            data: { ok: true },
+            display: input.resolved ? 'Resolved' : 'Reopened',
+        };
+    },
+};
+export const deleteComment = {
+    namespace: 'comment',
+    name: 'delete_comment',
+    description: 'Delete a comment note by its id. Deleting a thread\'s root note removes the whole thread.',
+    mutates: true,
+    confirmation: 'destructive',
+    inputSchema: {
+        properties: {
+            sheetIdx: { type: 'integer' },
+            commentId: { type: 'string' },
+        },
+        required: ['sheetIdx', 'commentId'],
+    },
+    handler: async (input, ctx) => {
+        await commit(asClient(ctx), { type: 'deleteComment', value: input }, 'delete_comment');
+        return { data: { ok: true }, display: 'Deleted' };
+    },
+};
+export const COMMENT_TOOLS = [
+    listComments,
+    addComment,
+    replyComment,
+    editComment,
+    resolveComment,
+    deleteComment,
+];

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

@@ -0,0 +1,22 @@
+/**
+ * Craft-interaction tools — let Watson BUILD craft-style cell-overlay
+ * widgets onto blocks, the way factory-simulator does, and READ back what
+ * the end user selected.
+ *
+ * Model (mirrors `injectCraftInteractionAPIs` in the host): a craft
+ * *registers* an overlay group onto specific block cells, then the end
+ * user operates it by clicking (choosing a radio option, dragging a
+ * slider, splitting a percentage). The craft cannot set selections
+ * programmatically — so these tools cover registration + clearing +
+ * reading results, not "operate".
+ *
+ * Addressing: cells are named by (block ref name, field name, row key) —
+ * the same altitude as `edit__set_block_cells`. Each tool resolves those
+ * to block-relative (row, col) offsets via the block schema before
+ * calling the host. The LLM never deals with raw coordinates.
+ *
+ * When the host has no craft-interaction surface (headless CLI), the
+ * tools return a structured "not available" result instead of throwing.
+ */
+import type { Tool } from '../tool.js';
+export declare const CRAFT_INTERACTION_TOOLS: Tool[];