shortcutxl 0.3.48 → 0.3.49

package/CHANGELOG.md

@@ -1,14 +1,20 @@
-# Changelog
-
-## [0.3.48]
-
-- **Background subagents** - Subagents can now work in the background, be steered during conversations, be revived for additional tasks once they are done, and have their statuses surfaced in the UI.
-- **Skill proposals** - ShortcutXL now automatically browses through past sessions and suggests new skills and skill modifications.
-
-## [0.3.47]
-
-- **GPT-5.5** — Upgraded the OpenAI reasoning model from GPT-5.4 to GPT-5.5 (400K context window, stronger reasoning). 
-- **Out-of-credits message** — When your credit balance runs out, ShortcutXL now shows a clear message instead of silently failing.
+# Changelog
+
+## [0.3.49]
+
+- **Transcript scrolling & rendering** - Long conversations now scroll more cleanly with mouse wheel, PageUp/PageDown, and Ctrl+Home/Ctrl+End support while the editor and footer stay pinned.
+- **Longer-running task agents** - Background task agents now get a 30-minute default timeout, reducing early timeouts on bigger jobs.
+- **Clearer path-based skills** - Skills loaded from custom folders are grouped by their real root paths so the agent can find and use them more reliably.
+
+## [0.3.48]
+
+- **Background subagents** - Subagents can now work in the background, be steered during conversations, be revived for additional tasks once they are done, and have their statuses surfaced in the UI.
+- **Skill proposals** - ShortcutXL now automatically browses through past sessions and suggests new skills and skill modifications.
+
+## [0.3.47]
+
+- **GPT-5.5** — Upgraded the OpenAI reasoning model from GPT-5.4 to GPT-5.5 (400K context window, stronger reasoning). 
+- **Out-of-credits message** — When your credit balance runs out, ShortcutXL now shows a clear message instead of silently failing.
 
 ## [0.3.46]
 

package/agent-docs/docs/tui.md

@@ -28,6 +28,8 @@ interface Component {
 
 The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
 
+Shortcut's interactive shell configures `ProcessTerminal` to use the terminal alternate screen buffer. The main transcript is an app-owned scroll viewport, not native terminal scrollback. In that shell, PageUp/PageDown, Ctrl+Home/Ctrl+End, and mouse wheel input scroll the transcript while the editor/footer remain pinned. Fullscreen custom views should clear/redraw inside the existing alternate buffer instead of entering or leaving alternate-buffer mode themselves.
+
 ## Focusable Interface (IME Support)
 
 Components that display a text cursor and need IME (Input Method Editor) support should implement the `Focusable` interface:
@@ -445,12 +447,34 @@ interface MyTheme {
 
 ## Debug logging
 
+`ProcessTerminal` only enters the alternate screen buffer (`CSI ? 1049 h`) when `useAlternateBuffer: true` is passed. Shortcut's interactive shell enables that mode; full-screen subviews should clear and redraw inside the existing TUI buffer instead of entering or leaving alternate buffer themselves.
+
+Set `SHORTCUT_TUI_RENDER_TRACE=1` to capture a structured JSONL trace of TUI rendering decisions, input events, overlay/focus state, cursor movement, changed line hashes/previews, and ANSI write summaries. By default this writes to `~/.shortcut/agent/tui-render-traces/<timestamp>-<pid>.jsonl`. Set it to a file path to choose the destination. Add `SHORTCUT_TUI_RENDER_TRACE_FULL=1` to include full rendered lines and full write buffers; leave it off for smaller logs.
+
+```bash
+SHORTCUT_TUI_RENDER_TRACE=1 shortcut
+SHORTCUT_TUI_RENDER_TRACE=C:\temp\shortcut-tui.jsonl SHORTCUT_TUI_RENDER_TRACE_FULL=1 shortcut
+```
+
 Set `SHORTCUT_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
 
 ```bash
 SHORTCUT_TUI_WRITE_LOG=/tmp/tui-ansi.log npx tsx packages/tui/test/chat-simple.ts
 ```
 
+Summarize a captured trace with:
+
+```bash
+npm run analyze:tui-trace -- C:\temp\shortcut-tui.jsonl
+npm run analyze:tui-trace -- C:\temp\shortcut-tui.jsonl --json
+```
+
+For deterministic repro coverage, run the PTY render matrix:
+
+```bash
+npm run test:pty -- tests/interactive/tui-render-matrix/tui-render-matrix.pty.test.ts
+```
+
 ## Performance
 
 Cache rendered output when possible:

package/agent-docs/examples/rpc-extension-ui.ts

@@ -274,7 +274,7 @@ async function main() {
 
   // -- TUI setup --
 
-  const terminal = new ProcessTerminal();
+  const terminal = new ProcessTerminal({ useAlternateBuffer: true });
   const tui = new TUI(terminal);
 
   const outputLog = new OutputLog();

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

@@ -137,7 +137,7 @@ export interface PromptOptions {
     expandPromptTemplates?: boolean;
     /** Image attachments */
     images?: ImageContent[];
-    /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */
+    /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Defaults to "steer". */
     streamingBehavior?: 'steer' | 'followUp';
     /** Source of input for extension input event handlers. Defaults to "interactive". */
     source?: InputSource;
@@ -322,9 +322,8 @@ export declare class AgentSession {
     /**
      * Send a prompt to the agent.
      * - Expands file-based prompt templates by default
-     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - During streaming, queues via steer() by default, or followUp() when requested
      * - Validates model and API key before sending (when not streaming)
-     * @throws Error if streaming and no streamingBehavior specified
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;

package/dist/app/agent-session.js

@@ -734,9 +734,8 @@ export class AgentSession {
     /**
      * Send a prompt to the agent.
      * - Expands file-based prompt templates by default
-     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - During streaming, queues via steer() by default, or followUp() when requested
      * - Validates model and API key before sending (when not streaming)
-     * @throws Error if streaming and no streamingBehavior specified
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     async prompt(text, options) {
@@ -756,12 +755,9 @@ export class AgentSession {
             currentText = parsedBudget.task;
         }
         const expandedText = currentText;
-        // If streaming, queue via steer() or followUp() based on option
+        // If streaming, queue via steer() by default; follow-up is opt-in.
         if (this.isStreaming) {
-            if (!options?.streamingBehavior) {
-                throw new Error("AgentController is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
-            }
-            if (options.streamingBehavior === 'followUp') {
+            if (options?.streamingBehavior === 'followUp') {
                 await this._queueFollowUp(expandedText, currentImages);
             }
             else {

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

@@ -1,146 +1,215 @@
-{
-  "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; read larger areas in smaller chunks.\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. Default \"auto\" increments hardcoded numeric literals; use fill_mode=\"constant\" to copy literal values, then read back destination cells and check for empty/NaN values.\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; read larger areas in smaller chunks.\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. Default \"auto\" increments hardcoded numeric literals; use fill_mode=\"constant\" to copy literal values, then read back destination cells and check for empty/NaN values.\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"
+      ]
+    }
+  }
+}

package/dist/app/subagents/clone/agent.js

@@ -6,7 +6,7 @@ import { BASH, EDIT, EXECUTE_CODE, GREP, READ, SEND_MESSAGE, TASK, WRITE } from
 import { buildActionPrompt } from '../../modes/action/prompt.js';
 import { buildCurrentSkillsSection } from '../../prompts/shared-guidelines.js';
 import { assembleSystemPrompt } from '../../system-prompt.js';
-import { DEFAULT_SUBAGENT_MODEL } from '../defaults.js';
+import { DEFAULT_SUBAGENT_MODEL, DEFAULT_SUBAGENT_TIMEOUT_SECONDS } from '../defaults.js';
 const NAME = 'clone';
 const DESCRIPTION = `\
 A full clone of the main agent with tools (read, bash, edit, write, grep, execute_code, task, send_message).
@@ -25,6 +25,6 @@ export const cloneAgent = {
     excludeSubagents: ['clone'],
     model: DEFAULT_SUBAGENT_MODEL,
     thinkingLevel: 'low',
-    timeoutSeconds: 900
+    timeoutSeconds: DEFAULT_SUBAGENT_TIMEOUT_SECONDS
 };
 //# sourceMappingURL=agent.js.map

package/dist/app/subagents/defaults.d.ts

@@ -1,3 +1,4 @@
 export declare const DEFAULT_SUBAGENT_MODEL: "shortcut/claude-opus-4-7";
+export declare const DEFAULT_SUBAGENT_TIMEOUT_SECONDS: number;
 export declare const TASK_MODEL_CHOICES: readonly ["shortcut/claude-opus-4-7", "shortcut/gpt-5.5-2026-04-23"];
 //# sourceMappingURL=defaults.d.ts.map

package/dist/app/subagents/defaults.js

@@ -1,4 +1,5 @@
 import { SHORTCUT_MODEL_REF } from '../../model-ids.js';
 export const DEFAULT_SUBAGENT_MODEL = SHORTCUT_MODEL_REF.ClaudeOpus47;
+export const DEFAULT_SUBAGENT_TIMEOUT_SECONDS = 30 * 60;
 export const TASK_MODEL_CHOICES = [DEFAULT_SUBAGENT_MODEL, SHORTCUT_MODEL_REF.Gpt55];
 //# sourceMappingURL=defaults.js.map

package/dist/app/subagents/document-reader/agent.js

@@ -6,7 +6,7 @@
  */
 import { getAgentTempDir } from '../../../config.js';
 import { BASH, LLM_ANALYSIS, WRITE } from '../../../tool-names.js';
-import { DEFAULT_SUBAGENT_MODEL } from '../defaults.js';
+import { DEFAULT_SUBAGENT_MODEL, DEFAULT_SUBAGENT_TIMEOUT_SECONDS } from '../defaults.js';
 const NAME = 'document_reader';
 const DESCRIPTION = `\
 Extract structured data from PDFs, images, and documents with high accuracy.
@@ -87,6 +87,6 @@ export const documentReaderAgent = {
     tools: [WRITE, BASH, LLM_ANALYSIS],
     model: DEFAULT_SUBAGENT_MODEL,
     thinkingLevel: 'low',
-    timeoutSeconds: 900
+    timeoutSeconds: DEFAULT_SUBAGENT_TIMEOUT_SECONDS
 };
 //# sourceMappingURL=agent.js.map

package/dist/app/subagents/general/agent.js

@@ -6,7 +6,7 @@
  */
 import { BASH, EXECUTE_CODE, LLM_ANALYSIS, WRITE } from '../../../tool-names.js';
 import { buildCurrentSkillsSection, getEnginePrompts, pushActionSharedGuidelines } from '../../prompts/shared-guidelines.js';
-import { DEFAULT_SUBAGENT_MODEL } from '../defaults.js';
+import { DEFAULT_SUBAGENT_MODEL, DEFAULT_SUBAGENT_TIMEOUT_SECONDS } from '../defaults.js';
 const NAME = 'general';
 const DESCRIPTION = `\
 General-purpose agent for research, computation, and web tasks. Uses include:
@@ -71,7 +71,7 @@ export function generalAgent() {
         tools: [WRITE, BASH, EXECUTE_CODE, LLM_ANALYSIS],
         model: DEFAULT_SUBAGENT_MODEL,
         thinkingLevel: 'low',
-        timeoutSeconds: 900
+        timeoutSeconds: DEFAULT_SUBAGENT_TIMEOUT_SECONDS
     };
 }
 //# sourceMappingURL=agent.js.map

package/dist/app/subagents/index.d.ts

@@ -6,7 +6,7 @@
  */
 export type { AgentDefinition } from '../agent-definition.js';
 export { cloneAgent } from './clone/agent.js';
-export { DEFAULT_SUBAGENT_MODEL, TASK_MODEL_CHOICES } from './defaults.js';
+export { DEFAULT_SUBAGENT_MODEL, DEFAULT_SUBAGENT_TIMEOUT_SECONDS, TASK_MODEL_CHOICES } from './defaults.js';
 export { documentReaderAgent } from './document-reader/agent.js';
 export { generalAgent } from './general/agent.js';
 export { verificationAgent } from './verification/agent.js';

package/dist/app/subagents/index.js

@@ -5,7 +5,7 @@
  * catalog, even after test resets.
  */
 export { cloneAgent } from './clone/agent.js';
-export { DEFAULT_SUBAGENT_MODEL, TASK_MODEL_CHOICES } from './defaults.js';
+export { DEFAULT_SUBAGENT_MODEL, DEFAULT_SUBAGENT_TIMEOUT_SECONDS, TASK_MODEL_CHOICES } from './defaults.js';
 export { documentReaderAgent } from './document-reader/agent.js';
 export { generalAgent } from './general/agent.js';
 export { verificationAgent } from './verification/agent.js';

package/dist/app/subagents/simulation/agent.js

@@ -7,7 +7,7 @@
 import { getAgentTempDir } from '../../../config.js';
 import { BASH, EXECUTE_CODE } from '../../../tool-names.js';
 import { getEnginePrompts, pushActionSharedGuidelines } from '../../prompts/shared-guidelines.js';
-import { DEFAULT_SUBAGENT_MODEL } from '../defaults.js';
+import { DEFAULT_SUBAGENT_MODEL, DEFAULT_SUBAGENT_TIMEOUT_SECONDS } from '../defaults.js';
 const NAME = 'simulation_agent';
 const DESCRIPTION = `\
 Read/write workbook analysis worker for scenario analysis, sensitivity testing, auditing formula linkages, debugging, prototyping changes, and other workbook-heavy tasks.`;
@@ -67,6 +67,6 @@ export const simulationAgent = {
     tools: [EXECUTE_CODE, BASH],
     model: DEFAULT_SUBAGENT_MODEL,
     thinkingLevel: 'low',
-    timeoutSeconds: 900
+    timeoutSeconds: DEFAULT_SUBAGENT_TIMEOUT_SECONDS
 };
 //# sourceMappingURL=agent.js.map