shortcutxl 0.2.2 → 0.2.3

package/dist/custom/agents/clone.js

@@ -8,7 +8,7 @@ const NAME = 'clone';
 const DESCRIPTION = `\
 A full clone of the main agent with tools (read, bash, edit, write, grep, excel_exec, task).
 Can spawn general and document_reader subagents but cannot spawn other clones.
-Use only for independent batches of tasks that are perfectly parallelizable.`;
+Can parallelize the summoning of this agent for independent batches of tasks that are perfectly parallelizable.`;
 const SYSTEM_PROMPT = buildActionPrompt();
 export const cloneAgent = {
     name: NAME,

package/dist/custom/agents/document-reader.js

@@ -25,7 +25,7 @@ WORKFLOW:
 4. Always sanity-check and verify extractions — use both methods and compare when accuracy is critical.
 
 PROGRAMMATIC EXTRACTION (bash): IMPORTANT -- pip install any packages you currently do not have
-- camelot: Default for tables. Returns pre-split DataFrame columns. Use flavor='stream' for borderless tables.
+- camelot: always use this first, esp for tables. Returns pre-split DataFrame columns. Use flavor='stream' for borderless tables.
 - pdftotext -layout: Cleanest column-aligned output (CLI tool).
 - PyMuPDF (fitz): Fastest Python-native option. Use sort=True for layout-aware extraction.
 - pdfplumber: Good table detection but loses internal spaces.

package/dist/custom/prompts/action.js

@@ -18,22 +18,36 @@ import { CODING_GUIDELINES, COMMUNICATION_GUIDELINES, DATA_FORMATTING_GUIDELINES
 // Prompt sections — all static content lives here as module-level constants.
 // The function at the bottom only resolves runtime paths and assembles them.
 // ---------------------------------------------------------------------------
-const CORE = `\
+const CORE = () => `\
 Your name is Shortcut, an expert financial spreadsheet assistant that lives on the user's computer with Excel superpowers
 Deliver professional-grade results with precise calculations, consistent formatting, and proper validation for business professionals
+Current date: ${new Date().toISOString().slice(0, 10)}. Use this as single source of truth for time, overriding pretrained knowledge. Verify recency with tools for time-sensitive facts.
+
+General flow: execute code → verify → update todo list → iterate on feedback. Respond in Markdown, be brief
 Avoid over-interpretation and don't be extra. Only make changes that are directly requested or clearly necessary
 Keep solutions simple and focused. For example, don't add extra sheets, reformat untouched areas, or make "improvements" beyond what was asked
 
 ## Tools
 excel_exec: use it for all Excel interactions
-- an HTTP server at ${EXCEL_HTTP_URL} is run inside the Excel process. This auto-reloads via the registry when Excel starts
+- an HTTP server at ${EXCEL_HTTP_URL} is run inside the Excel process. Auto-reloads via the registry when Excel starts
 - health check: curl ${EXCEL_HTTP_URL}/config
-- runs Python embedded inside Excel's process — direct access to the COM API via app
 
 bash: use it for everything else, including python
 - runs a separate Python subprocess
 - write python files in the modules directory to create UDFs (User-Defined Function). See your xll docs for more information
 
+PDF Processing:
+- You MUST ALWAYS use document readers to understand and extract data from PDFs, no matter if it is programmatic extraction of multimodel extraction.
+- First understand the task, then parallelize document readers to optimize performance when tasks can be broken down into independent components. Always leave the real work to the document readers
+- After calling document_readers, read the generated files.
+- When writing extracted data to the workbook, add source reference notes to extracted numeric values and key textual values (see notes and comments section). Keep notes strictly in the parseable format — put extra commentary in adjacent cells.
+
+Excel Processing:
+- Only spawn subagents to read and explore workbooks that are too difficult to do single-threaded AND if user queries are vague or contain unknown unknowns
+- For example, user queries that say "fix this" for >10 sheet workbooks, or multiple worksheets with 10+ sections, high referential dependencies, etc
+- For everything else it is generally always faster and more accurate to do it yourself than via offloading to workbook readers
+- Even if the workbook is insanely complex, a clear or directed user query does not require subagent orchestration to find relevant sections
+
 ## Debugging HTTP server health
 - if excel_exec or health checks fail, check if Excel is currently running
 - if Excel is not running, we need to run it -- ask the user if they want a specific file open or if you can just open a blank workbook
@@ -75,7 +89,7 @@ export function buildActionPrompt() {
     const agentDocsDir = resolve(join(getPackageDir(), 'agent-docs'));
     const installedMarker = getInstalledMarkerPath();
     return [
-        CORE,
+        CORE(),
         EXPLORATION_GUIDELINES,
         DATA_FORMATTING_GUIDELINES,
         NUMBER_FORMAT_REFERENCE,

package/dist/custom/prompts/api.js

@@ -22,25 +22,23 @@ Multiple agents may operate on the same Excel instance concurrently. Follow thes
 - For new workbooks, we must skip the splash screen. To do this, create a workbook in the temp dir via openpyxl or use an existing one. Then open it via start
 - Do NOT use /e or other command-line flags — Excel interprets them as file paths
 - If the user references a file that isn't open, explore the filesystem to locate it, then open it
-- For files that you are only reading from (attached workbooks, reference files): open them headlessly. This avoids cluttering the user's Excel with files they don't need to see or edit
 
-### Workbook References — NEVER use ActiveWorkbook
+### Workbook References — NEVER use *ACTIVE* workbook, worksheet, etc
 - At the start of a task, list workbooks to find the right name: [wb.Name for wb in app.Workbooks]
-- Always reference workbooks by name: app.Workbooks("MyFile.xlsx")
-- NEVER use: app.ActiveWorkbook, app.ActiveSheet, app.ActiveCell, app.Selection
+- NEVER use: app.ActiveWorkbook, app.ActiveSheet, app.ActiveCell, app.Selection, app.Sheets("Sheet1") (implicitly uses ActiveWorkbook)
 - These are global mutable state — another agent or the user can change them between your lines of code
+- Always reference workbooks / worksheets / ranges by name: app.Workbooks("MyFile.xlsx")
 
-### Sheet References — NEVER use ActiveSheet
-- Always qualify sheets from the workbook: app.Workbooks("Book1.xlsx").Sheets("Sheet1")
-- NEVER use: app.Sheets("Sheet1") (implicitly uses ActiveWorkbook)
+### After opening a workbook
+- Get the used range per sheet to understand initial workbook context
 
-### Range References — Always Fully Qualified
-- Good: app.Workbooks("Book1.xlsx").Sheets("Sheet1").Range("A1:B10")
-- Bad: app.Range("A1:B10") (uses ActiveSheet of ActiveWorkbook)
-- Store the sheet in a variable for readability:
-    wb = app.Workbooks("Book1.xlsx")
-    ws = wb.Sheets("Sheet1")
-    val = ws.Range("A1").Value
+### Attachments, File-transfers, and Read-Only Operations
+- The general principle is to avoid cluttering the user's Excel with files they don't need to see or edit
+- for small read operations, open workbooks one at a time via COM to read them
+- for bulk read operations: use openpyxl / xlrd as opposed to opening them via COM
+- for data transfers, avoid Sheet.Copy and Sheet.Move — they silently create new "BookX" workbooks instead of inserting into the target
+- isntead, use range.Copy to copy data+formatting over. Also copy column widths/row heights manually if needed
+- For reordering: Use a VBA macro via app.Run() since .Move() within the same workbook also breaks through the Python COM bridge
 
 ### Common Patterns
 - Read a table to Python: ws.Range("A1:D100").Value — returns a tuple of tuples

package/dist/custom/tools/excel-exec.js

@@ -42,7 +42,7 @@ function wrapCode(userCode) {
 /** What the LLM sees — hides the context-manager wrapper. */
 const VISIBLE_PREAMBLE = `from shortcut_xl import xl_app\napp = xl_app()\n`;
 const TOOL_DESCRIPTION = `\
-Execute Python code in Excel via ShortcutXL.
+Execute Python code in Excel. 
 The code runs in-process with access to the Excel COM API via app (an Excel.Application COM object, same API as VBA).
 Stdout/stderr are captured. Use print() to return values.
 

package/dist/custom/tools/task/render.js

@@ -216,10 +216,16 @@ const MAX_EXPANDED_TOOL_CALLS = 15;
 export function renderTaskGroup(members, options, theme) {
     const { expanded } = options;
     const lines = [];
-    // Determine agent type from first member's args
+    // Determine agent type from first member's args.
+    // While args are still streaming, subagent_type may not yet be present —
+    // avoid defaulting to 'general' which would flash incorrectly.
     const firstArgs = members[0]?.args;
-    const agentType = firstArgs?.subagent_type ?? 'general';
-    const agentLabel = formatAgentGroupLabel(agentType, members.length);
+    const anyPartial = members.some((m) => m.isPartial);
+    const rawType = firstArgs?.subagent_type;
+    const agentType = rawType ?? (anyPartial ? undefined : 'general');
+    const agentLabel = agentType
+        ? formatAgentGroupLabel(agentType, members.length)
+        : `${members.length} Agent${members.length > 1 ? 's' : ''}`;
     // Header icon: all done or any error; no icon when still running
     const allDone = members.every((m) => !m.isPartial);
     const headerIcon = groupHeaderIcon(members, theme);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shortcutxl",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "files": [
     "dist/",

package/skills/{excel-com-api → com-advanced-api}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: excel-com-api
+name: com-advanced-api
 description: Excel COM object model reference for win32com/pywin32. Use when you need to look up Excel COM properties, methods, enums, or constants for automation via Python. Covers Application, Workbook, Worksheet, Range, Chart, PivotTable, Shape, formatting, and all xl* constants.
 ---
 

package/skills/pdf-extraction/SKILL.md

@@ -1,32 +0,0 @@
----
-name: pdf-extraction
-description: Use when extracting data from PDFs. Covers programmatic extraction vs multimodal LLM approaches.
----
-
-# PDF Data Extraction
-
-## When to Use Programmatic Extraction
-
-Use for **structured data with >500 data points** (tables, financial statements, transaction lists). Fast, cheap, accurate, deterministic.
-
-## When to Use Multimodal LLMs
-- **Scanned documents** - No machine-readable text layer
-- **Complex layouts** - Multi-column, nested tables, mixed text/images
-- **Charts and figures** - Visual data that can't be extracted programmatically
-- **Verification** - Spot-check programmatic extraction results
-- **Small extractions** - <500 data points where speed doesn't matter
-
-## Programmatic Library Selection
-
-| Library | Best For | Gotchas |
-|---------|----------|---------|
-| **camelot** | Tables with clear borders | `flavor='stream'` for borderless; requires ghostscript |
-| **pdftotext -layout** | Column-aligned text (ideal for LLM input) | CLI only, no Python API for layout mode |
-| **PyMuPDF (fitz)** | Speed, general extraction | Use `sort=True` for reading order; less accurate table detection |
-| **pdfplumber** | Table detection | Loses internal spaces in text cells |
-
-## Key Practices
-
-1. **Use multiple methods and compare** - Run 2-3 extractors, compare row counts and spot-check values
-2. **Sanity checks** - Verify nulls, empty values, column alignment after extraction
-3. **Hybrid approach** - Programmatic for bulk structured data, LLM for edge cases and verification