shortcutxl 0.3.42 → 0.3.43

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## [0.3.41]
+## [0.3.43]
+
+- **Security & stability** — Internal hardening fixes across the runtime.
+
+## [0.3.42]
 
 - **Hosted MCP OAuth** — ShortcutXL now supports OAuth-authenticated hosted MCP servers. Configure a hosted MCP in `mcp.json`, then log in from `/mcp` or `/login`, see `login required` status when auth is missing, and log out again directly from the MCP menu.
 - **Agent context cleanup** — Simplified agent context and prompt behavior for cleaner single-turn and multi-turn execution.

package/agent-docs/xll-skill.md

@@ -51,7 +51,7 @@ Rules: function name = formula name, args are `float`/`str`/`None`, return `floa
 | | `/exec` | `modules/` |
 |---|---|---|
 | **Use for** | One-shot actions, layout, formatting | Custom formulas, live data, tick loops |
-| **Imports** | Disabled (all symbols pre-injected) | `xl_func`, `xl_app`, `xl_batch`, `schedule_call`, `xl_log` |
+| **Imports** | Allowed (safe stdlib only; blacklist blocks `os`, `subprocess`, `socket`, etc.) | `xl_func`, `xl_app`, `xl_batch`, `schedule_call`, `xl_log` |
 
 Never mix the two.
 

package/dist/app/agent-session.d.ts

@@ -93,6 +93,8 @@ export interface AgentSessionConfig {
     initialToolNames?: string[];
     /** Optional initial mode name used to seed runtime permission policy. */
     initialModeName?: string;
+    /** Optional fixed permission policy for isolated runtimes such as subagents. */
+    initialPermissionPolicy?: RuntimePermissionPolicy;
     /** Model registry for API key resolution and model discovery */
     modelRegistry: ModelRegistry;
     /** Mutable ref used by Agent to access the current ExtensionRunner */

package/dist/app/approvals/tool-approval.d.ts

@@ -7,6 +7,7 @@ import type { TSchema } from '@sinclair/typebox';
 import type { ToolDefinition, ToolExecutionContext } from '../../core/core-types.js';
 import { type ApprovalChoice, type ApprovalGate, type ApprovalRequest } from './types.js';
 export declare function withPreApproval<T extends TSchema, D>(tool: ToolDefinition<T>, approval: ApprovalGate<D>, buildRequest: (params: Record<string, unknown>, ctx: ToolExecutionContext | undefined) => ApprovalRequest<D> | Promise<ApprovalRequest<D>>, options?: {
+    alwaysPrompt?: boolean;
     isContentSafe?: (params: Record<string, unknown>, ctx: ToolExecutionContext | undefined) => boolean | Promise<boolean>;
     onRequested?: (request: ApprovalRequest<D>) => void;
     onAccepted?: (request: ApprovalRequest<D>, choice: ApprovalChoice) => void;

package/dist/app/approvals/types.d.ts

@@ -52,4 +52,14 @@ export interface BashApprovalData {
     /** Connection names whose credentials will be injected. */
     connections?: string[];
 }
+export interface TaskSpawnApprovalData {
+    subagentType: string;
+    name: string;
+    query: string;
+    model?: string;
+    /** Task spawn approval is all-or-nothing: approved children run as full workers. */
+    fullWorker: true;
+    /** True when this subagent can recursively spawn more full-worker children. */
+    canSpawnSubagents: boolean;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/app/excel-config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Discover ShortcutXL paths by calling GET /config on the XLL's HTTP server.
+ *
+ * Returns { xll_dir, modules_path } or null if Excel isn't running.
+ * Retries a few times on startup since Excel may still be loading the XLL.
+ */
+interface ExcelConfig {
+    xllDir: string;
+    modulesPath: string;
+}
+/**
+ * Fetch XLL config from the running Excel instance.
+ * Retries up to `maxRetries` times with `intervalMs` between attempts.
+ * Returns null if Excel/XLL is unreachable after all retries.
+ */
+export declare function fetchExcelConfig(options?: {
+    maxRetries?: number;
+    intervalMs?: number;
+    url?: string;
+}): Promise<ExcelConfig | null>;
+export {};
+//# sourceMappingURL=excel-config.d.ts.map

package/dist/app/excel-session.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Read the ShortcutXL session file written by the XLL's HTTP server.
+ *
+ * The XLL generates a random bearer token on startup and writes it
+ * (along with the port) to %APPDATA%\ShortcutXL\session.json.
+ * The agent reads this file to authenticate requests to the XLL.
+ *
+ * Format: { "port": 8080, "token": "hex..." }
+ */
+/**
+ * Clear the cached session so the next readXllSession() re-reads from disk.
+ * Useful after Excel restarts.
+ */
+export declare function clearXllSessionCache(): void;
+/**
+ * Check if the XLL reported an initialization error in session.json.
+ * Returns the error string, or undefined if no error.
+ */
+export declare function readXllSessionError(): string | undefined;
+/**
+ * Authenticated fetch to the XLL HTTP server.
+ *
+ * Injects the bearer token from the session file and retries once on 403
+ * (handles stale cached token after Excel restart).
+ */
+export declare function xllFetch(url: string, init?: RequestInit): Promise<Response>;
+//# sourceMappingURL=excel-session.d.ts.map

package/dist/app/extensions/index.impl.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extension system for lifecycle events and custom tools.
+ */
+export type { SlashCommandInfo, SlashCommandLocation, SlashCommandSource } from '../../app/extensions/slash-commands.js';
+export { createExtensionRuntime, discoverAndLoadExtensions, loadExtensionFromFactory, loadExtensions } from './loader.js';
+export { ExtensionRunner } from './runner.js';
+export type { ExtensionErrorListener, ForkHandler, NavigateTreeHandler, NewSessionHandler, RunnerEmitEvent, ShutdownHandler, SwitchSessionHandler } from './runner.js';
+export type { AgentToolResult, AgentToolUpdateCallback, CompactOptions, ContextEvent, ContextEventResult, ContextUsage, Extension, ExtensionAPI, ExtensionActions, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionHandler, ExtensionRuntime, ExtensionSessionSetupStore, ExtensionSessionView, ExtensionUIContext, ExtensionUIDialogOptions, InputEvent, InputEventResult, InputSource, LoadExtensionsResult, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionCompactEvent, SessionEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolInfo, ToolResultEvent, ToolResultEventResult, TurnEndEvent, TurnStartEvent, UserBashEvent, UserBashEventResult } from './types.js';
+export { wrapToolWithExtensions, wrapToolsWithExtensions } from './wrapper.js';
+//# sourceMappingURL=index.impl.d.ts.map

package/dist/app/new-sheet/sheet-exec.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Sheet exec tool — execute TypeScript code against a headless spreadsheet engine.
+ *
+ * Drop-in replacement for excel-exec (COM). Same tool name (excel_exec),
+ * same schema shape, but runs code in-process against @mog-sdk/node's
+ * the @mog-sdk/node workbook via a VM sandbox.
+ *
+ * Workbook lifecycle mirrors COM: workbooks persist across executions,
+ * are referenced by name (basename for loaded files, "Book1" etc. for new),
+ * and the agent manages open/create/save/close explicitly.
+ *
+ * Mutation tracking via Proxy wrappers records every setCell/clear call.
+ * After execution, mutations are resolved to CellEdit[] and formatted into
+ * the same cell diff summary the COM path produces.
+ *
+ * Code is TypeScript (transpiled to JS before execution).
+ */
+import type { ToolDefinition } from '../../core/core-types.js';
+import type { CellEdit } from './cell-diff/types.js';
+import type { SheetEnginePool } from './sheet-engine.js';
+interface SheetExecResult {
+    ok: boolean;
+    output?: string;
+    error?: string;
+    logs?: string[];
+    change_count?: number;
+    edit_ranges?: string[];
+    dirty_cells?: CellEdit[];
+}
+declare const schema: import("@sinclair/typebox").TObject<{
+    description: import("@sinclair/typebox").TString;
+    code: import("@sinclair/typebox").TString;
+}>;
+export declare function createSheetExecTool(pool: SheetEnginePool): ToolDefinition<typeof schema, SheetExecResult>;
+export {};
+//# sourceMappingURL=sheet-exec.d.ts.map

package/dist/app/permissions/approval-surface.d.ts

@@ -14,7 +14,7 @@ export interface ApprovalExecutionDecisionInput {
     isSafe: boolean;
     isAutoApproved: boolean;
     alwaysRequireExplicitApproval: boolean;
-    denyOnHeadlessApproval?: boolean;
+    allowHeadlessApproval?: boolean;
 }
 export type ApprovalExecutionDecision = 'allow' | 'prompt' | 'deny';
 /** Determines whether the current execution context can display approval UI. */

package/dist/app/permissions/runtime-approval-flow.d.ts

@@ -6,13 +6,15 @@
  */
 import type { ToolExecutionContext } from '../../core/core-types.js';
 import type { RuntimeFilesystemPermissionPolicy, RuntimeShellPermissionPolicy } from '../../core/permission-policy.js';
-import { type ApprovalChoice, type ApprovalRequest, type BashApprovalData, type FileAccessApprovalData } from '../approvals/types.js';
+import { type ApprovalChoice, type ApprovalRequest, type BashApprovalData, type FileAccessApprovalData, type TaskSpawnApprovalData } from '../approvals/types.js';
 import type { SettingsManager } from '../settings-manager.js';
 export declare function describeFilesystemApprovalChoice(request: ApprovalRequest<FileAccessApprovalData>, choice: ApprovalChoice): string | undefined;
 export declare function buildFilesystemApprovalRequest(absolutePath: string, access: 'read' | 'write', policy: RuntimeFilesystemPermissionPolicy): Promise<ApprovalRequest<FileAccessApprovalData>>;
 export declare function isFilesystemInvocationSafe(absolutePath: string, access: 'read' | 'write', policy: RuntimeFilesystemPermissionPolicy, ctx: ToolExecutionContext | undefined): Promise<boolean>;
 export declare function applyFilesystemApprovalChoice(choice: ApprovalChoice, request: ApprovalRequest<FileAccessApprovalData>, access: 'read' | 'write', settingsManager: SettingsManager, ctx: ToolExecutionContext | undefined): ToolExecutionContext | undefined;
 export declare function buildShellApprovalRequest(params: Record<string, unknown>, toolName: string): ApprovalRequest<BashApprovalData>;
+export declare function buildTaskSpawnApprovalRequest(payload: TaskSpawnApprovalData): ApprovalRequest<TaskSpawnApprovalData>;
 export declare function isShellInvocationSafe(policy: RuntimeShellPermissionPolicy | undefined): boolean;
 export declare function applyShellApprovalChoice(ctx: ToolExecutionContext | undefined, params: Record<string, unknown>): ToolExecutionContext | undefined;
+export declare function applyTaskSpawnApprovalChoice(ctx: ToolExecutionContext | undefined, _request: ApprovalRequest<TaskSpawnApprovalData>): ToolExecutionContext | undefined;
 //# sourceMappingURL=runtime-approval-flow.d.ts.map

package/dist/app/permissions/runtime-permission-bypass.d.ts

@@ -0,0 +1,5 @@
+export type PermissionBypassSelect = (title: string, options: string[]) => Promise<string | undefined>;
+export declare function formatPermissionBypassStatus(enabled: boolean): string;
+export declare function formatPermissionBypassStatusMessage(enabled: boolean): string;
+export declare function confirmRuntimePermissionBypass(select: PermissionBypassSelect): Promise<boolean>;
+//# sourceMappingURL=runtime-permission-bypass.d.ts.map

package/dist/app/permissions/tool-gates.d.ts

@@ -1,6 +1,6 @@
 import type { ToolDefinition } from '../../core/core-types.js';
 import { BASH, EDIT, EXECUTE_CODE, FIND, GREP, LS, READ, TASK, WRITE } from '../../tool-names.js';
-import { type ApprovalGate, type BashApprovalData, type FileAccessApprovalData } from '../approvals/types.js';
+import { type ApprovalGate, type BashApprovalData, type FileAccessApprovalData, type TaskSpawnApprovalData } from '../approvals/types.js';
 import type { ShortcutClientLogger } from '../observability/client-logging/client-logger.js';
 import type { SettingsManager } from '../settings-manager.js';
 export type PermissionedRuntimeToolName = typeof READ | typeof WRITE | typeof EDIT | typeof LS | typeof FIND | typeof GREP | typeof BASH | typeof EXECUTE_CODE | typeof TASK;
@@ -42,7 +42,7 @@ export declare const TOOL_GATES: {
         readonly kind: "self-gated";
     };
     readonly task: {
-        readonly kind: "self-gated";
+        readonly kind: "task";
     };
 };
 export declare const PERMISSIONED_RUNTIME_TOOL_NAMES: PermissionedRuntimeToolName[];
@@ -52,6 +52,7 @@ export interface RegisterRuntimeToolDeps {
     settingsManager?: SettingsManager;
     filesystemApproval?: ApprovalGate<FileAccessApprovalData>;
     shellApproval?: ApprovalGate<BashApprovalData>;
+    taskApproval?: ApprovalGate<TaskSpawnApprovalData>;
     observability?: Pick<ShortcutClientLogger, 'info' | 'warn' | 'error'>;
 }
 export declare function registerRuntimeTool(tools: ToolDefinition<any, any>[], tool: ToolDefinition<any, any>, deps: RegisterRuntimeToolDeps): void;

package/dist/app/prompts/com-api-reference.json

@@ -1,215 +1,146 @@
-{
-  "interfaces": {
-    "Workbook": {
-      "docstring": "Workbook wrapper.\nUsage:\n    wb = Workbook(app.Workbooks(\"MyFile.xlsx\"))\n\nRaw COM access:\n    wb._wb  \u2014 the underlying COM Workbook object for direct platform API calls.\n    Example: wb._wb.Worksheets(\"Sheet1\").Visible = False",
-      "functions": {
-        "getSheetNames": {
-          "signature": "def getSheetNames() -> list[str]",
-          "docstring": "Get the names of all sheets in the workbook.",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "getWorkbookSummary": {
-          "signature": "def getWorkbookSummary() -> str",
-          "docstring": "Get sheet names and used ranges for this workbook.\nReturns lines like:\n    Sheets and their used ranges:\n      Sheet1: A1:D10 (active)\n      Inputs: (empty)",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "getSheet": {
-          "signature": "def getSheet(name: str) -> 'Worksheet'",
-          "docstring": "Get a sheet by name, returned as a wrapped Worksheet.",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "addSheet": {
-          "signature": "def addSheet(name: str, index: int | None = None) -> 'Worksheet'",
-          "docstring": "Add a new sheet at 0-based index. index=0 inserts before the first sheet.\nOmit index for Excel's default position.\nExample: wb.addSheet(\"NewSheet\", 0)  # insert as first sheet",
-          "tags": [
-            "action"
-          ]
-        },
-        "moveSheet": {
-          "signature": "def moveSheet(name: str, index: int) -> None",
-          "docstring": "Move a sheet to 0-based index. index=0 moves to first, index=Count-1 moves to last.\nExample: wb.moveSheet(\"Data\", 0)  # move to first position",
-          "tags": [
-            "action"
-          ]
-        },
-        "calculate": {
-          "signature": "def calculate() -> None",
-          "docstring": "Recalculate the entire workbook.\nDependent formulas don't update until after code block completes \u2014 read in a follow-up block.",
-          "tags": [
-            "action"
-          ]
-        },
-        "errorCheck": {
-          "signature": "def errorCheck(ranges: list[str] | None = None) -> str",
-          "docstring": "Scan for errors (#REF!, #DIV/0!, #NAME?, #VALUE!, #N/A, #NULL!, #NUM!). Ranges MUST include a sheet name (\"Sheet1\" or \"Sheet1!A1:D50\") \u2014 bare ranges like \"A1:D50\" will fail.\n      Args:\n          ranges: Optional sheet names (\"Sheet1\") or ranges (\"Sheet1!A1:D50\"). Omit to check all.\n      Returns:\n          \"No issues found.\" or \"Errors (N):\nSheet1!A1: #REF!\n...\"",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "copyPasteRange": {
-          "signature": "def copyPasteRange(from_range: str, to_address: str, paste_type: str = 'all', ) -> None",
-          "docstring": "Copy range within same workbook via range.Copy + PasteSpecial.\nAddresses must include sheet name. Do NOT use Sheet.Copy (broken via pywin32).\nExample: wb.copyPasteRange(\"Sheet1!A1:D10\", \"Sheet2!A1\", paste_type=\"values\")",
-          "tags": [
-            "action"
-          ]
-        },
-        "getNamedRangeInfo": {
-          "signature": "def getNamedRangeInfo(max_count: int = 50) -> str",
-          "docstring": "Get named ranges. Returns formatted string with name, reference, scope, and comment.\nExample output: \"Named Ranges (2):\\n  Name: TaxRate | Ref: =Settings!$B$2 | Scope: workbook | Comment: ...\"\nReturns \"No named ranges found.\" if none exist.",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        }
-      }
-    },
-    "Worksheet": {
-      "docstring": "Worksheet wrapper.\nUsage:\n    sheet = wb.getSheet(\"Sheet1\")\n\nRaw COM access:\n    sheet._ws  \u2014 the underlying COM Worksheet object for direct platform API calls.\n    Use for borders, text orientation, cell protection, and other properties not covered by the wrapper.\n    Example: sheet._ws.Range(\"A1\").Borders(9).LineStyle = 1  # xlEdgeBottom, xlContinuous",
-      "functions": {
-        "getSheetSummary": {
-          "signature": "def getSheetSummary() -> str",
-          "docstring": "Overview: name, used range, tables (with style/banded/header/total props),\npivots (with range), conditional formats (type/range/priority/stopIfTrue),\nautofilter (with filtering status), charts (with type).",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "getUsedRange": {
-          "signature": "def getUsedRange() -> str",
-          "docstring": "Get the used range address like \"A1:F20\", or \"\" if empty.",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "getCell": {
-          "signature": "def getCell(address: str, include_style: bool = True) -> str",
-          "docstring": "Formatted cell string: \"value(=FORMULA) (style_json)\". Formula always included.\nZero with custom format appends [0]: \"$ - [0]\".\nExample:\n    print(sheet.getCell(\"A1\"))\n    print(sheet.getCell(\"A1\", include_style=False))",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "getCellRange": {
-          "signature": "def getCellRange(range_addr: str, include_style: bool = True) -> str",
-          "docstring": "Markdown-like range: \"A1:Name | B1:Value\\nA2:Alice | B2:100\". Uses display text. Max 3000 cells.\nAppends \"--- Style patterns ---\" section when include_style=True.",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "getRawCellData": {
-          "signature": "def getRawCellData(address: str, formula: bool = False) -> Any",
-          "docstring": "Get raw data value from a cell, preserving data type. Set formula=True to get the formula string.",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "getRawRangeData": {
-          "signature": "def getRawRangeData(range_addr: str, formula: bool = False) -> list[list[Any]]",
-          "docstring": "Get raw data for a range as 2D list. Always returns 2D list even for single row/column.",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "regexSearch": {
-          "signature": "def regexSearch(patterns: list[str], match_case: bool = False) -> list[dict]",
-          "docstring": "Regex search across used range using display text. Returns [{\"address\": \"A1\", \"value\": \"display text\"}, ...].\nExample: sheet.regexSearch([\"revenue\", \"cost\"])",
-          "tags": [
-            "action",
-            "ask"
-          ]
-        },
-        "setCell": {
-          "signature": "def setCell(address: str, value: Any, number_format: str | None = None, note: str | None = None, ) -> None",
-          "docstring": "Write value or formula. \"=\" prefix = formula. None or \"\" clears the cell.\nExamples:\n    sheet.setCell(\"A1\", 8000)\n    sheet.setCell(\"C1\", 0.15, number_format=\"0%\", note=\"Tax rate\")\n    sheet.setCell(\"B1\", \"=SUM(A1:A10)\")",
-          "tags": [
-            "action"
-          ]
-        },
-        "setCellRange": {
-          "signature": "def setCellRange(range_addr: str, values: list[list[Any]], number_format: str | None = None, ) -> None",
-          "docstring": "Bulk write \u2014 ALWAYS use for >100 cells. \"=\" prefix = formula.\nExamples:\n    sheet.setCellRange(\"A1:B2\", [[1, 2], [3, 4]])\n    sheet.setCellRange(\"A1:B2\", [[\"=SUM(C1)\", \"=SUM(D1)\"], [5, 6]], number_format=\"$#,##0\")",
-          "tags": [
-            "action"
-          ]
-        },
-        "autoFill": {
-          "signature": "def autoFill(source_range: str, target_range: str, fill_mode: str = 'auto', ) -> None",
-          "docstring": "Drag-fill. Source must be contained within target.\nUse fill_mode=\"constant\" when copying a single value without incrementing.\nWARNING: Single numeric value with \"auto\" creates incrementing sequence (0,1,2,3...).\nExample: sheet.autoFill(\"A1:A2\", \"A1:A10\")",
-          "tags": [
-            "action"
-          ]
-        },
-        "addPicture": {
-          "signature": "def addPicture(name: str, base64_data: str, anchor_cell: str) -> None",
-          "docstring": "Add a picture from base64-encoded PNG or JPEG data. No data URI prefix.\nExample: sheet.addPicture(\"chart1\", base64_string, \"F2\")",
-          "tags": [
-            "action"
-          ]
-        },
-        "setIBTextColors": {
-          "signature": "def setIBTextColors(range_addr: str, ignored_constants: list[int] | None = None, colors: dict | None = None, ) -> None",
-          "docstring": "IB text colors for numeric inputs only. Text strings and booleans are left untouched.\n- Blue/16711680: hard-coded numeric constants (int/float)\n- Black/0: formulas (same-sheet references)\n- Green/32768: formulas with cross-sheet references (contains '!')\nColors are BGR integers (native COM format).\nExample: sheet.setIBTextColors(\"A1:D10\", ignored_constants=[0])",
-          "tags": [
-            "action"
-          ]
-        }
-      }
-    }
-  },
-  "helpers": {
-    "hex_to_bgr": {
-      "signature": "def hex_to_bgr(hex_str: str) -> int",
-      "docstring": "Convert \"#RRGGBB\" hex string to BGR integer for Excel COM.\nExample: ws.Range(\"A1\").Font.Color = hex_to_bgr(\"#FF0000\")  # red",
-      "tags": [
-        "action",
-        "ask"
-      ]
-    },
-    "index_to_address": {
-      "signature": "def index_to_address(row: int, col: int) -> str",
-      "docstring": "Convert 0-based (row, col) to Excel address: index_to_address(0, 0) \u2192 \"A1\".",
-      "tags": [
-        "action",
-        "ask"
-      ]
-    },
-    "address_to_index": {
-      "signature": "def address_to_index(address: str) -> tuple[int, int]",
-      "docstring": "Parse \"A1\" into (row, col) 0-based tuple: address_to_index(\"B3\") \u2192 (2, 1).",
-      "tags": [
-        "action",
-        "ask"
-      ]
-    },
-    "col_letter": {
-      "signature": "def col_letter(index: int) -> str",
-      "docstring": "Convert 0-based column index to letter: col_letter(26) \u2192 \"AA\".",
-      "tags": [
-        "action",
-        "ask"
-      ]
-    },
-    "col_index": {
-      "signature": "def col_index(letter: str) -> int",
-      "docstring": "Convert column letter to 0-based index: col_index(\"AA\") \u2192 26.",
-      "tags": [
-        "action",
-        "ask"
-      ]
-    }
-  }
-}
+{
+  "interfaces": {
+    "Workbook": {
+      "docstring": "Workbook wrapper.\nUsage:\n    wb = Workbook(app.Workbooks(\"MyFile.xlsx\"))\n\nRaw COM access:\n    wb._wb  \u2014 the underlying COM Workbook object for direct platform API calls.\n    Example: wb._wb.Worksheets(\"Sheet1\").Visible = False",
+      "functions": {
+        "getSheetNames": {
+          "signature": "def getSheetNames() -> list[str]",
+          "docstring": "Get the names of all sheets in the workbook.",
+          "tags": ["action", "ask"]
+        },
+        "getWorkbookSummary": {
+          "signature": "def getWorkbookSummary() -> str",
+          "docstring": "Get sheet names and used ranges for this workbook.\nReturns lines like:\n    Sheets and their used ranges:\n      Sheet1: A1:D10 (active)\n      Inputs: (empty)",
+          "tags": ["action", "ask"]
+        },
+        "getSheet": {
+          "signature": "def getSheet(name: str) -> 'Worksheet'",
+          "docstring": "Get a sheet by name, returned as a wrapped Worksheet.",
+          "tags": ["action", "ask"]
+        },
+        "addSheet": {
+          "signature": "def addSheet(name: str, index: int | None = None) -> 'Worksheet'",
+          "docstring": "Add a new sheet at 0-based index. index=0 inserts before the first sheet.\nOmit index for Excel's default position.\nExample: wb.addSheet(\"NewSheet\", 0)  # insert as first sheet",
+          "tags": ["action"]
+        },
+        "moveSheet": {
+          "signature": "def moveSheet(name: str, index: int) -> None",
+          "docstring": "Move a sheet to 0-based index. index=0 moves to first, index=Count-1 moves to last.\nExample: wb.moveSheet(\"Data\", 0)  # move to first position",
+          "tags": ["action"]
+        },
+        "calculate": {
+          "signature": "def calculate() -> None",
+          "docstring": "Recalculate the entire workbook.\nDependent formulas don't update until after code block completes \u2014 read in a follow-up block.",
+          "tags": ["action"]
+        },
+        "errorCheck": {
+          "signature": "def errorCheck(ranges: list[str] | None = None) -> str",
+          "docstring": "Scan for errors (#REF!, #DIV/0!, #NAME?, #VALUE!, #N/A, #NULL!, #NUM!). Ranges MUST include a sheet name (\"Sheet1\" or \"Sheet1!A1:D50\") \u2014 bare ranges like \"A1:D50\" will fail.\n      Args:\n          ranges: Optional sheet names (\"Sheet1\") or ranges (\"Sheet1!A1:D50\"). Omit to check all.\n      Returns:\n          \"No issues found.\" or \"Errors (N):\nSheet1!A1: #REF!\n...\"",
+          "tags": ["action", "ask"]
+        },
+        "copyPasteRange": {
+          "signature": "def copyPasteRange(from_range: str, to_address: str, paste_type: str = 'all', ) -> None",
+          "docstring": "Copy range within same workbook via range.Copy + PasteSpecial.\nAddresses must include sheet name. Do NOT use Sheet.Copy (broken via pywin32).\nExample: wb.copyPasteRange(\"Sheet1!A1:D10\", \"Sheet2!A1\", paste_type=\"values\")",
+          "tags": ["action"]
+        },
+        "getNamedRangeInfo": {
+          "signature": "def getNamedRangeInfo(max_count: int = 50) -> str",
+          "docstring": "Get named ranges. Returns formatted string with name, reference, scope, and comment.\nExample output: \"Named Ranges (2):\\n  Name: TaxRate | Ref: =Settings!$B$2 | Scope: workbook | Comment: ...\"\nReturns \"No named ranges found.\" if none exist.",
+          "tags": ["action", "ask"]
+        }
+      }
+    },
+    "Worksheet": {
+      "docstring": "Worksheet wrapper.\nUsage:\n    sheet = wb.getSheet(\"Sheet1\")\n\nRaw COM access:\n    sheet._ws  \u2014 the underlying COM Worksheet object for direct platform API calls.\n    Use for borders, text orientation, cell protection, and other properties not covered by the wrapper.\n    Example: sheet._ws.Range(\"A1\").Borders(9).LineStyle = 1  # xlEdgeBottom, xlContinuous",
+      "functions": {
+        "getSheetSummary": {
+          "signature": "def getSheetSummary() -> str",
+          "docstring": "Overview: name, used range, tables (with style/banded/header/total props),\npivots (with range), conditional formats (type/range/priority/stopIfTrue),\nautofilter (with filtering status), charts (with type).",
+          "tags": ["action", "ask"]
+        },
+        "getUsedRange": {
+          "signature": "def getUsedRange() -> str",
+          "docstring": "Get the used range address like \"A1:F20\", or \"\" if empty.",
+          "tags": ["action", "ask"]
+        },
+        "getCell": {
+          "signature": "def getCell(address: str, include_style: bool = True) -> str",
+          "docstring": "Formatted cell string: \"value(=FORMULA) (style_json)\". Formula always included.\nZero with custom format appends [0]: \"$ - [0]\".\nExample:\n    print(sheet.getCell(\"A1\"))\n    print(sheet.getCell(\"A1\", include_style=False))",
+          "tags": ["action", "ask"]
+        },
+        "getCellRange": {
+          "signature": "def getCellRange(range_addr: str, include_style: bool = True) -> str",
+          "docstring": "Markdown-like range: \"A1:Name | B1:Value\\nA2:Alice | B2:100\". Uses display text. Max 3000 cells.\nAppends \"--- Style patterns ---\" section when include_style=True.",
+          "tags": ["action", "ask"]
+        },
+        "getRawCellData": {
+          "signature": "def getRawCellData(address: str, formula: bool = False) -> Any",
+          "docstring": "Get raw data value from a cell, preserving data type. Set formula=True to get the formula string.",
+          "tags": ["action", "ask"]
+        },
+        "getRawRangeData": {
+          "signature": "def getRawRangeData(range_addr: str, formula: bool = False) -> list[list[Any]]",
+          "docstring": "Get raw data for a range as 2D list. Always returns 2D list even for single row/column.",
+          "tags": ["action", "ask"]
+        },
+        "regexSearch": {
+          "signature": "def regexSearch(patterns: list[str], match_case: bool = False) -> list[dict]",
+          "docstring": "Regex search across used range using display text. Returns [{\"address\": \"A1\", \"value\": \"display text\"}, ...].\nExample: sheet.regexSearch([\"revenue\", \"cost\"])",
+          "tags": ["action", "ask"]
+        },
+        "setCell": {
+          "signature": "def setCell(address: str, value: Any, number_format: str | None = None, note: str | None = None, ) -> None",
+          "docstring": "Write value or formula. \"=\" prefix = formula. None or \"\" clears the cell.\nExamples:\n    sheet.setCell(\"A1\", 8000)\n    sheet.setCell(\"C1\", 0.15, number_format=\"0%\", note=\"Tax rate\")\n    sheet.setCell(\"B1\", \"=SUM(A1:A10)\")",
+          "tags": ["action"]
+        },
+        "setCellRange": {
+          "signature": "def setCellRange(range_addr: str, values: list[list[Any]], number_format: str | None = None, ) -> None",
+          "docstring": "Bulk write \u2014 ALWAYS use for >100 cells. \"=\" prefix = formula.\nExamples:\n    sheet.setCellRange(\"A1:B2\", [[1, 2], [3, 4]])\n    sheet.setCellRange(\"A1:B2\", [[\"=SUM(C1)\", \"=SUM(D1)\"], [5, 6]], number_format=\"$#,##0\")",
+          "tags": ["action"]
+        },
+        "autoFill": {
+          "signature": "def autoFill(source_range: str, target_range: str, fill_mode: str = 'auto', ) -> None",
+          "docstring": "Drag-fill. Source must be contained within target.\nUse fill_mode=\"constant\" when copying a single value without incrementing.\nWARNING: Single numeric value with \"auto\" creates incrementing sequence (0,1,2,3...).\nExample: sheet.autoFill(\"A1:A2\", \"A1:A10\")",
+          "tags": ["action"]
+        },
+        "addPicture": {
+          "signature": "def addPicture(name: str, base64_data: str, anchor_cell: str) -> None",
+          "docstring": "Add a picture from base64-encoded PNG or JPEG data. No data URI prefix.\nExample: sheet.addPicture(\"chart1\", base64_string, \"F2\")",
+          "tags": ["action"]
+        },
+        "setIBTextColors": {
+          "signature": "def setIBTextColors(range_addr: str, ignored_constants: list[int] | None = None, colors: dict | None = None, ) -> None",
+          "docstring": "IB text colors for numeric inputs only. Text strings and booleans are left untouched.\n- Blue/16711680: hard-coded numeric constants (int/float)\n- Black/0: formulas (same-sheet references)\n- Green/32768: formulas with cross-sheet references (contains '!')\nColors are BGR integers (native COM format).\nExample: sheet.setIBTextColors(\"A1:D10\", ignored_constants=[0])",
+          "tags": ["action"]
+        }
+      }
+    }
+  },
+  "helpers": {
+    "hex_to_bgr": {
+      "signature": "def hex_to_bgr(hex_str: str) -> int",
+      "docstring": "Convert \"#RRGGBB\" hex string to BGR integer for Excel COM.\nExample: ws.Range(\"A1\").Font.Color = hex_to_bgr(\"#FF0000\")  # red",
+      "tags": ["action", "ask"]
+    },
+    "index_to_address": {
+      "signature": "def index_to_address(row: int, col: int) -> str",
+      "docstring": "Convert 0-based (row, col) to Excel address: index_to_address(0, 0) \u2192 \"A1\".",
+      "tags": ["action", "ask"]
+    },
+    "address_to_index": {
+      "signature": "def address_to_index(address: str) -> tuple[int, int]",
+      "docstring": "Parse \"A1\" into (row, col) 0-based tuple: address_to_index(\"B3\") \u2192 (2, 1).",
+      "tags": ["action", "ask"]
+    },
+    "col_letter": {
+      "signature": "def col_letter(index: int) -> str",
+      "docstring": "Convert 0-based column index to letter: col_letter(26) \u2192 \"AA\".",
+      "tags": ["action", "ask"]
+    },
+    "col_index": {
+      "signature": "def col_index(letter: str) -> int",
+      "docstring": "Convert column letter to 0-based index: col_index(\"AA\") \u2192 26.",
+      "tags": ["action", "ask"]
+    }
+  }
+}