shortcutxl 0.2.18 → 0.2.19

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.2.19]
+
+- **Sandbox & security hardening** — Code execution can now optionally run inside a sandbox (/sandbox) that blocks unauthorized file writes, reads, and in-bound and out-bound network traffic.
+- **Clearer privacy controls** - You can opt out of conversation uploads to our servers for complete privacy.
+
 ## [0.2.18]
 
 - **Fixed startup crash** — Resolved a circular import in the Python modules that caused "internal error" on every Excel action.

package/agent-docs/xll-skill.md

@@ -12,14 +12,14 @@ Two channels to control Excel:
 ```
 POST http://localhost:8080/exec
 Content-Type: application/json
-{"code": "from shortcut_xl import xl_app\napp = xl_app()\napp.Range('A1').Value = 42"}
+{"code": "app.Range('A1').Value = 42"}
 ```
 
 Returns `{"ok": true, "output": "..."}` or `{"ok": false, "error": "..."}`.
 
-**Only import `xl_app` in `/exec`.** Never use `xl_batch`, `schedule_call`, or `xl_log` — those cause cross-thread COM errors. You already have direct main-thread access.
+**Import statements are disabled in `/exec`.** The sandbox pre-injects everything you need: `app` (Excel.Application COM object), `Workbook`, `Worksheet`, and helper functions. Standard Python builtins work normally. Do NOT use `import`.
 
-`xl_app()` returns `Excel.Application` — same API as VBA. Use `print()` to read values back.
+`app` is the Excel.Application COM object — same API as VBA. Use `print()` to read values back.
 
 ---
 
@@ -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** | `xl_app` only | `xl_func`, `xl_app`, `xl_batch`, `schedule_call`, `xl_log` |
+| **Imports** | Disabled (all symbols pre-injected) | `xl_func`, `xl_app`, `xl_batch`, `schedule_call`, `xl_log` |
 
 Never mix the two.
 

package/dist/cli/args.js

@@ -135,6 +135,9 @@ export function parseArgs(args, extensionFlags) {
         else if (arg === '--subagent') {
             result.subagent = true;
         }
+        else if (arg === '--dev-mode') {
+            result.devMode = true;
+        }
         else if (arg === '--offline') {
             result.offline = true;
         }

package/dist/config.js

@@ -179,6 +179,9 @@ export const VERSION = pkg.version;
 export const NPM_PACKAGE_NAME = pkg.name || 'shortcutxl';
 // e.g., SHORTCUT_CODING_AGENT_DIR
 export const ENV_AGENT_DIR = `${APP_NAME.toUpperCase()}_CODING_AGENT_DIR`;
+// -- Sandbox defaults ------------------------------------------------------
+/** Default sandbox network mode. 'proxy' gives domain-level control with user approval. */
+export const DEFAULT_SANDBOX_NETWORK = 'proxy';
 // -- Package & update URLs -------------------------------------------------
 /** npm registry URL for version checks. */
 export const NPM_REGISTRY_URL = `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`;
@@ -267,6 +270,18 @@ export function getPromptsDir() {
 export function getSessionsDir() {
     return join(getAgentDir(), 'sessions');
 }
+/** Get path to WSL distro storage directory (imported distro lives here) */
+export function getWslDir() {
+    return join(getAgentDir(), 'wsl');
+}
+/** Get path to the shipped Alpine rootfs tarball (bundled in the npm package) */
+export function getAlpineRootfsPath() {
+    return join(getPackageDir(), 'wsl', 'alpine-minirootfs.tar.gz');
+}
+/** Get path to persistent pip packages directory (mounted rw into sandbox) */
+export function getPipPackagesDir() {
+    return join(getAgentDir(), 'pip-packages');
+}
 /** Get path to debug log file */
 export function getDebugLogPath() {
     return join(getAgentDir(), `${APP_NAME}-debug.log`);
@@ -279,8 +294,6 @@ export function getInstalledMarkerPath() {
 export function isInstalled() {
     return existsSync(getInstalledMarkerPath());
 }
-/** Enable dev-only features (e.g. /export, verbose tool-download messages). */
-export const DEV_MODE = process.env.SHORTCUT_DEV_MODE === '1';
 /** Get path to ShortcutXL.xll (stable user-local copy at ~/.shortcut/agent/xll/). */
 export function getXllPath() {
     return join(getAgentDir(), "xll", "ShortcutXL.xll");

package/dist/core/agent-session.js

@@ -141,6 +141,21 @@ export class AgentSession {
             l(event);
         }
     }
+    /**
+     * Remove the last errored assistant message and its synthetic error
+     * toolResult messages from agent state. When a streaming call fails
+     * mid-response, agent-loop appends [assistant(error), toolResult, ...]
+     * — this removes the entire group so retries start from a clean state.
+     */
+    _removeLastErrorGroup() {
+        const messages = this.agent.state.messages;
+        let i = messages.length - 1;
+        while (i >= 0 && messages[i].role === 'toolResult')
+            i--;
+        if (i >= 0 && messages[i].role === 'assistant' && messages[i].stopReason === 'error') {
+            this.agent.replaceMessages(messages.slice(0, i));
+        }
+    }
     // Track last assistant message for auto-compaction check
     _lastAssistantMessage = undefined;
     /** Internal handler for agent events - shared by subscribe and reconnect */
@@ -272,12 +287,7 @@ export class AgentSession {
             // Check for retryable errors first (overloaded, rate limit, server errors)
             if (isRetryableError(msg, this._checkContextOverflow)) {
                 const didRetry = await this._retry.handleRetryableError(msg, this.settingsManager.getRetrySettings(), {
-                    removeLastAssistantMessage: () => {
-                        const messages = this.agent.state.messages;
-                        if (messages.length > 0 && messages[messages.length - 1].role === 'assistant') {
-                            this.agent.replaceMessages(messages.slice(0, -1));
-                        }
-                    },
+                    removeLastAssistantMessage: () => this._removeLastErrorGroup(),
                     continue: () => {
                         setTimeout(() => {
                             this.agent.continue().catch(() => { });
@@ -1141,13 +1151,7 @@ export class AgentSession {
                 });
             }
         },
-        removeLastAssistantMessage: () => {
-            const messages = this.agent.state.messages;
-            const lastMsg = messages[messages.length - 1];
-            if (lastMsg?.role === 'assistant' && lastMsg.stopReason === 'error') {
-                this.agent.replaceMessages(messages.slice(0, -1));
-            }
-        },
+        removeLastAssistantMessage: () => this._removeLastErrorGroup(),
         continueAgent: () => {
             setTimeout(() => {
                 this.agent.continue().catch(() => { });

package/dist/core/footer-data-provider.js

@@ -103,6 +103,8 @@ export class FooterDataProvider {
     initialCreditBalance = null;
     /** True when the active model uses credits (suppresses $cost even when balance fetch fails) */
     _usesCredits = false;
+    // SHORTCUT PATCH: sandbox indicator for footer
+    _sandboxActive = false;
     getCreditBalance() {
         return this.creditBalance;
     }
@@ -125,6 +127,13 @@ export class FooterDataProvider {
     setUsesCredits(value) {
         this._usesCredits = value;
     }
+    // SHORTCUT PATCH: sandbox indicator
+    get sandboxActive() {
+        return this._sandboxActive;
+    }
+    setSandboxActive(value) {
+        this._sandboxActive = value;
+    }
     /** Internal: cleanup */
     dispose() {
         if (this.gitWatcher) {

package/dist/core/sdk.js

@@ -189,6 +189,7 @@ export async function createAgentSession(options = {}) {
         customTools: options.customTools,
         modelRegistry,
         initialActiveToolNames,
+        baseToolsOverride: options.baseToolsOverride,
         extensionRunnerRef,
         prePromptContext: options.prePromptContext
     });

package/dist/core/settings-manager.js

@@ -1,12 +1,23 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import lockfile from 'proper-lockfile';
-import { CONFIG_DIR_NAME, getAgentDir } from '../config.js';
+import { homedir } from 'os';
+import { CONFIG_DIR_NAME, DEFAULT_SANDBOX_NETWORK, getAgentDir } from '../config.js';
 /** Display labels for the approval mode (footer + /settings). */
 export const APPROVAL_MODE = {
     ASK: 'Ask before edits',
     AUTO: 'Approve all edits',
 };
+/** Concrete sandbox defaults — always called at runtime so paths resolve correctly. */
+export function getDefaultSandboxSettings() {
+    return {
+        mode: 'disabled',
+        readPaths: [homedir()],
+        writePaths: [getAgentDir()],
+        network: DEFAULT_SANDBOX_NETWORK,
+        allowedDomains: [],
+    };
+}
 /** Deep merge settings: project/overrides take precedence, nested objects merge recursively */
 function deepMergeSettings(base, overrides) {
     const result = { ...base };
@@ -573,6 +584,67 @@ export class SettingsManager {
     getCodeBlockIndent() {
         return this.settings.markdown?.codeBlockIndent ?? '  ';
     }
+    getSandboxSettings() {
+        return this.settings.sandbox ?? {};
+    }
+    getSandboxMode() {
+        return this.settings.sandbox?.mode ?? 'disabled';
+    }
+    /** Ensure globalSettings.sandbox exists with full defaults. */
+    ensureSandboxDefaults() {
+        if (!this.globalSettings.sandbox) {
+            this.globalSettings.sandbox = { ...getDefaultSandboxSettings() };
+            this.markModified('sandbox');
+        }
+        return this.globalSettings.sandbox;
+    }
+    setSandboxMode(mode) {
+        this.ensureSandboxDefaults().mode = mode;
+        this.markModified('sandbox', 'mode');
+        this.save();
+    }
+    getSandboxNetworkMode() {
+        return this.settings.sandbox?.network ?? DEFAULT_SANDBOX_NETWORK;
+    }
+    setSandboxNetworkMode(mode) {
+        this.ensureSandboxDefaults().network = mode;
+        this.markModified('sandbox', 'network');
+        this.save();
+    }
+    getSandboxAllowedDomains() {
+        return this.settings.sandbox?.allowedDomains ?? [];
+    }
+    setSandboxAllowedDomains(domains) {
+        this.ensureSandboxDefaults().allowedDomains = domains;
+        this.markModified('sandbox', 'allowedDomains');
+        this.save();
+    }
+    addSandboxAllowedDomain(domain) {
+        const sandbox = this.ensureSandboxDefaults();
+        const domains = [...(sandbox.allowedDomains ?? [])];
+        if (!domains.includes(domain)) {
+            domains.push(domain);
+            sandbox.allowedDomains = domains;
+            this.markModified('sandbox', 'allowedDomains');
+            this.save();
+        }
+    }
+    setSandboxReadPaths(paths) {
+        this.ensureSandboxDefaults().readPaths = paths;
+        this.markModified('sandbox', 'readPaths');
+        this.save();
+    }
+    setSandboxWritePaths(paths) {
+        this.ensureSandboxDefaults().writePaths = paths;
+        this.markModified('sandbox', 'writePaths');
+        this.save();
+    }
+    resetSandboxToDefaults() {
+        const mode = this.globalSettings.sandbox?.mode ?? 'disabled';
+        this.globalSettings.sandbox = { ...getDefaultSandboxSettings(), mode };
+        this.markModified('sandbox');
+        this.save();
+    }
     // Session-scoped auto-approve. Initialized from the persistent
     // settings.autoApprove default, then toggled freely via Shift+Tab.
     _autoApprove;
@@ -597,5 +669,23 @@ export class SettingsManager {
         this.markModified('autoApprove');
         this.save();
     }
+    /** Whether session traces and ClickHouse logs are uploaded. Default: true. */
+    getTelemetry() {
+        return this.settings.telemetry ?? true;
+    }
+    setTelemetry(enabled) {
+        this.globalSettings.telemetry = enabled;
+        this.markModified('telemetry');
+        this.save();
+    }
+    /** Whether dev mode is enabled (file tools, AGENTS.md, verbose logging). Default: false. */
+    getDevMode() {
+        return this.settings.devMode ?? false;
+    }
+    setDevMode(enabled) {
+        this.globalSettings.devMode = enabled;
+        this.markModified('devMode');
+        this.save();
+    }
 }
 //# sourceMappingURL=settings-manager.js.map

package/dist/core/slash-commands.js

@@ -20,12 +20,10 @@ const ALL_BUILTIN_SLASH_COMMANDS = [
     { name: 'skills', description: 'Show loaded skills' },
     { name: 'reload', description: 'Reload extensions, skills, prompts, and themes' }
 ];
-/** Dev-only slash commands, consumed by custom/dev/ to keep env checks out of vendor code. */
-export const ALL_DEV_SLASH_COMMANDS = ALL_BUILTIN_SLASH_COMMANDS.filter((cmd) => cmd.dev);
-/** All builtin command names (including dev), used to prevent extension collisions. */
+/** All builtin command names, used to prevent extension collisions. */
 export const ALL_BUILTIN_SLASH_COMMAND_NAMES = new Set(ALL_BUILTIN_SLASH_COMMANDS.map((cmd) => cmd.name));
-/** Returns the base (non-dev) slash commands. Dev commands are added via custom/dev/. */
+/** Returns all builtin slash commands. */
 export function getBuiltinSlashCommands() {
-    return ALL_BUILTIN_SLASH_COMMANDS.filter((cmd) => !cmd.dev);
+    return ALL_BUILTIN_SLASH_COMMANDS;
 }
 //# sourceMappingURL=slash-commands.js.map

package/dist/core/tools/bash.js

@@ -19,13 +19,38 @@ Execute a bash command in the current working directory. Returns stdout and stde
 Output is truncated to ${DEFAULT_MAX_CHARS} characters. If truncated, full output is saved to a temp file. \
 Default timeout is 30 seconds. Override with the timeout parameter for long-running commands.
 
-Python 3 and pip are available for data processing, scripting, and package installation.
-- ALWAYS use bash to execute python and other commands instead of through the 
+Python and pip are available for data processing, scripting, and package installation.
+- ALWAYS use bash to execute python code instead going through the excel COM interface -- that channel reserved for Excel communication
+- Use python / python3 (not via an absolute path) to invoke Python.
 
 On Windows, this tool runs Git Bash (MSYS2), not a native shell. Two consequences:
 1. Forward-slash flags get auto-converted to paths — use double slashes for literal flags (e.g., reg query //v).
 2. This tool holds stdout/stderr pipes open until all child processes exit. To launch a process without blocking, use Git Bash's built-in \`start\` with the program name (e.g., \`start excel\`).
 
+**Conventions:**
+- When creating files, tell users the file path.
+- Stop retrying after 1-2 unexplained failures.`;
+// SHORTCUT PATCH: sandbox-mode description replaces Windows caveats with Linux instructions
+const TOOL_DESCRIPTION_SANDBOX = `\
+Execute a bash command in a sandboxed Linux environment (WSL2 + bubblewrap). Returns stdout and stderr. \
+Output is truncated to ${DEFAULT_MAX_CHARS} characters. If truncated, full output is saved to a temp file. \
+Default timeout is 30 seconds. Override with the timeout parameter for long-running commands.
+
+Commands run in an isolated Linux sandbox with restricted filesystem access.
+- Use Linux paths: the Windows drive C:\\ is mounted at /mnt/c/ (e.g., C:\\Users\\jane → /mnt/c/Users/jane)
+- The working directory is always writable. The user's home directory is readable.
+- File tools (Read, Edit, Glob, Grep) still use Windows paths — only bash uses Linux paths
+- Network access is controlled by sandbox settings — if a command fails due to network, tell the user to enable it in settings
+
+**Filesystem access**: Read and write mounts are configured in the sandbox section of the agent settings file. \
+If you get "Read-only file system" or "No such file or directory" for a path that should exist, \
+check the sandbox settings and tell the user — they can add paths via /sandbox settings.
+
+Python 3 and pip are available for data processing, scripting, and package installation.
+- \`pip install <pkg>\` works — packages are installed to a persistent user directory that survives across commands.
+- ALWAYS use bash to execute python and other commands.
+- Use python (not python3 or an absolute path) to invoke Python.
+
 **Conventions:**
 - When creating files, tell users the file path.
 - Stop retrying after 1-2 unexplained failures.`;
@@ -43,7 +68,9 @@ const bashSchema = Type.Object({
         description: 'A short description of what the command does for non-technical users.'
     }),
     command: Type.String({ description: 'Bash command to execute' }),
-    timeout: Type.Optional(Type.Number({ description: 'Timeout in seconds (default: 30). Increase for long-running commands.' }))
+    timeout: Type.Optional(Type.Number({
+        description: 'Timeout in seconds (default: 30). Increase for long-running commands.'
+    }))
 });
 /**
  * Default bash operations using local shell
@@ -154,10 +181,11 @@ const defaultBashOperations = {
 export function createBashTool(cwd, options) {
     const ops = options?.operations ?? defaultBashOperations;
     const commandPrefix = options?.commandPrefix;
+    const description = options?.sandboxActive ? TOOL_DESCRIPTION_SANDBOX : TOOL_DESCRIPTION;
     return {
         name: TOOL_NAME,
         label: TOOL_LABEL,
-        description: TOOL_DESCRIPTION,
+        description,
         parameters: bashSchema,
         execute: async (_toolCallId, { command, timeout: explicitTimeout }, signal, onUpdate) => {
             const timeout = explicitTimeout ?? 30;

package/dist/custom/agents/index.js

@@ -11,11 +11,11 @@
  */
 export { actionAgent } from './action.js';
 export { installationAgent } from './installation.js';
-import { cloneAgent } from './clone.js';
+// import { cloneAgent } from './clone.js';
 import { documentReaderAgent } from './document-reader.js';
 import { generalAgent } from './general.js';
 /** All subagent definitions (used internally by accessor functions below) */
-const SUBAGENTS = [cloneAgent, documentReaderAgent, generalAgent];
+const SUBAGENTS = [documentReaderAgent, generalAgent];
 /** Get a subagent config by name */
 export function getSubagent(name) {
     return SUBAGENTS.find((a) => a.name === name);
@@ -35,7 +35,6 @@ Include file paths, sheet names, cell ranges, and specific instructions in the q
 When multiple tasks are needed, launch them concurrently. NEVER call them sequentially — each agent takes time to complete.
 
 Choose the subagent_type carefully based on the task:
-- clone: agent clone with bash, edit, excel_exec, and task — use for complex tasks needing editing and subagent delegation
 - document_reader: PDFs, images, document extraction (has llm_analysis for multimodal + bash for programmatic extraction)
 - general: research, computation, Excel tasks (has excel_exec + bash + llm_analysis)`;
     const lines = [preamble];

package/dist/custom/auth/keep-alive.js

@@ -0,0 +1,23 @@
+/**
+ * Standalone token keep-alive process.
+ *
+ * Keeps OAuth tokens in auth.json fresh by running the proactive refresh timer.
+ * Used by the benchmark runner to prevent LoginRequiredError when spawning
+ * many short-lived agent processes concurrently.
+ *
+ * Usage: node dist/cli.js keep-alive
+ *        pnpm.cmd exec tsx src/custom/auth/keep-alive.ts
+ */
+import { AuthStorage } from '../../core/auth-storage.js';
+import { startProactiveRefresh } from './refresh-timer.js';
+const PROVIDER_ID = 'shortcut';
+const authStorage = AuthStorage.create();
+// Do an initial refresh immediately
+await authStorage.getApiKey(PROVIDER_ID);
+// Then keep refreshing on a timer
+startProactiveRefresh(authStorage, PROVIDER_ID);
+// Stay alive until killed
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+setInterval(() => { }, 60_000);
+//# sourceMappingURL=keep-alive.js.map

package/dist/custom/constants.js

@@ -25,7 +25,7 @@ export const SHORTCUT_AUTH_URL = process.env.SHORTCUT_AUTH_URL ?? ENV[ACTIVE_ENV
 /** API service — credit balance, billing. */
 export const SHORTCUT_API_URL = process.env.SHORTCUT_API_URL ?? ENV[ACTIVE_ENV].apiUrl;
 // -- Dev mode --------------------------------------------------------------
-// DEV_MODE lives in config.ts (layer-0) so modes/ can import it without boundary violations.
+// Dev mode is now a settings.json flag (settingsManager.getDevMode()), not an env var.
 // -- Excel XLL -------------------------------------------------------------
 /** ShortcutXL HTTP server (always localhost — runs in-process with Excel). */
 export const EXCEL_HTTP_URL = process.env.EXCEL_HTTP_URL ?? 'http://127.0.0.1:8080';

package/dist/custom/context/workbook-summary.js

@@ -10,9 +10,8 @@
  * followed by the full summary for the LLM.
  */
 import { EXCEL_HTTP_URL } from '../constants.js';
+import { xllFetch } from '../excel-session.js';
 const SUMMARY_CODE = `
-from shortcut_xl import xl_app
-app = xl_app()
 if app.Workbooks.Count == 0:
     print("")
 else:
@@ -40,7 +39,7 @@ else:
 export async function fetchWorkbookSummary(httpUrl) {
     const baseUrl = httpUrl ?? EXCEL_HTTP_URL;
     try {
-        const response = await fetch(`${baseUrl}/exec`, {
+        const response = await xllFetch(`${baseUrl}/exec`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ code: SUMMARY_CODE }),

package/dist/custom/dev/index.js

@@ -1,17 +1,10 @@
 /**
- * Centralized dev-mode hooks for SHORTCUT_DEV_MODE=1.
+ * Trace hooks — HTML export of session traces after each query.
  *
- * All dev-only behaviors are registered here so they're easy to discover,
- * audit, and extend. The composition root (main.ts) calls getDevHooks()
- * once and wires the returned hooks into the session/mode options.
- *
- * To add a new dev-mode feature:
- *   1. Create a file in custom/dev/ with the implementation
- *   2. Wire it into DevHooks and getDevHooks() below
- *   3. Consume the hook in main.ts
+ * Always active (not dev-gated). The composition root (main.ts) calls
+ * getTraceHooks() once and wires the returned hooks into the mode options.
  */
 import { exec } from 'child_process';
-import { ALL_DEV_SLASH_COMMANDS } from '../../core/slash-commands.js';
 import { exportDevTraces } from './trace-export.js';
 function openInBrowser(filePath) {
     const cmd = process.platform === 'win32'
@@ -22,10 +15,9 @@ function openInBrowser(filePath) {
     exec(cmd, () => { });
 }
 /**
- * Build all dev-mode hooks for the given session.
- * Returns undefined when dev mode is off — callers can use optional chaining.
+ * Build trace hooks for the given session.
  */
-export function getDevHooks(session) {
+export function getTraceHooks(session) {
     // -- Trace export after each query --
     let lastTracePaths = [];
     const onAgentEnd = () => {
@@ -38,7 +30,7 @@ export function getDevHooks(session) {
         });
     };
     // -- /trace command: open all traces in browser --
-    const onDevCommand = (command, showStatus) => {
+    const onCommand = (command, showStatus) => {
         if (command !== '/trace')
             return false;
         if (lastTracePaths.length === 0) {
@@ -51,9 +43,8 @@ export function getDevHooks(session) {
         return true;
     };
     return {
-        slashCommands: ALL_DEV_SLASH_COMMANDS,
         onAgentEnd,
-        onDevCommand
+        onCommand
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/custom/dev/trace-export.js

@@ -1,9 +1,8 @@
 /**
- * Dev-mode HTML export of session traces after each query.
+ * HTML export of session traces after each query.
  *
- * When SHORTCUT_DEV_MODE=1, exports the main session JSONL and any subagent
- * JSONLs to HTML after each agent_end event. File paths are shown in the
- * footer via extension statuses (one line per trace).
+ * Exports the main session JSONL and any subagent JSONLs to HTML after
+ * each agent_end event. The /trace command opens them in the browser.
  */
 import { existsSync } from 'fs';
 import { basename, dirname, join } from 'path';

package/dist/custom/excel-config.js

@@ -5,6 +5,7 @@
  * Retries a few times on startup since Excel may still be loading the XLL.
  */
 import { EXCEL_HTTP_URL } from './constants.js';
+import { xllFetch } from './excel-session.js';
 /**
  * Fetch XLL config from the running Excel instance.
  * Retries up to `maxRetries` times with `intervalMs` between attempts.
@@ -16,7 +17,7 @@ export async function fetchExcelConfig(options) {
     const baseUrl = options?.url ?? EXCEL_HTTP_URL;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
-            const response = await fetch(`${baseUrl}/config`);
+            const response = await xllFetch(`${baseUrl}/config`);
             if (!response.ok)
                 continue;
             const data = (await response.json());

package/dist/custom/excel-session.js

@@ -0,0 +1,76 @@
+/**
+ * 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..." }
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+let cachedSession = null;
+function getSessionFilePath() {
+    const appData = process.env.APPDATA;
+    if (!appData) {
+        throw new Error('APPDATA environment variable not set');
+    }
+    return join(appData, 'ShortcutXL', 'session.json');
+}
+/**
+ * Read the XLL session file. Returns { port, token } or null if unavailable.
+ * Caches the result — the token is stable for the lifetime of the Excel process.
+ */
+export function readXllSession() {
+    if (cachedSession)
+        return cachedSession;
+    try {
+        const raw = readFileSync(getSessionFilePath(), 'utf-8');
+        const data = JSON.parse(raw);
+        if (typeof data.port === 'number' && typeof data.token === 'string' && data.token.length > 0) {
+            cachedSession = { port: data.port, token: data.token };
+            return cachedSession;
+        }
+    }
+    catch {
+        // File doesn't exist or is malformed — XLL may not be running
+    }
+    return null;
+}
+/**
+ * Clear the cached session so the next readXllSession() re-reads from disk.
+ * Useful after Excel restarts.
+ */
+export function clearXllSessionCache() {
+    cachedSession = null;
+}
+/**
+ * Get the Authorization header value for XLL requests, or undefined
+ * if no session file is available (falls back to unauthenticated).
+ */
+export function getXllAuthHeader() {
+    const session = readXllSession();
+    return session ? `Bearer ${session.token}` : 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 async function xllFetch(url, init) {
+    const headers = new Headers(init?.headers);
+    const auth = getXllAuthHeader();
+    if (auth)
+        headers.set('Authorization', auth);
+    let response = await fetch(url, { ...init, headers });
+    if (response.status === 403) {
+        clearXllSessionCache();
+        const freshAuth = getXllAuthHeader();
+        if (freshAuth)
+            headers.set('Authorization', freshAuth);
+        response = await fetch(url, { ...init, headers });
+    }
+    return response;
+}
+//# sourceMappingURL=excel-session.js.map