shortcutxl 0.2.12 → 0.2.13

package/agent-docs/examples/sdk/README.md

@@ -1,144 +1,144 @@
-# SDK Examples
-
-Programmatic usage of shortcutxl via `createAgentSession()`.
-
-## Examples
-
-| File | Description |
-|------|-------------|
-| `01-minimal.ts` | Simplest usage with all defaults |
-| `02-custom-model.ts` | Select model and thinking level |
-| `03-custom-prompt.ts` | Replace or modify system prompt |
-| `04-skills.ts` | Discover, filter, or replace skills |
-| `05-tools.ts` | Built-in tools, custom tools |
-| `06-extensions.ts` | Logging, blocking, result modification |
-| `07-context-files.ts` | AGENTS.md context files |
-| `08-slash-commands.ts` | File-based slash commands |
-| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
-| `10-settings.ts` | Override compaction, retry, terminal settings |
-| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
-| `12-full-control.ts` | Replace everything, no discovery |
-
-## Running
-
-```bash
-cd packages/coding-agent
-npx tsx examples/sdk/01-minimal.ts
-```
-
-## Quick Reference
-
-```typescript
-import { getModel } from "shortcutxl";
-import {
-  AuthStorage,
-  createAgentSession,
-  DefaultResourceLoader,
-  ModelRegistry,
-  SessionManager,
-  SettingsManager,
-  codingTools,
-  readOnlyTools,
-  readTool, bashTool, editTool, writeTool,
-} from "shortcutxl";
-
-// Auth and models setup
-const authStorage = AuthStorage.create();
-const modelRegistry = new ModelRegistry(authStorage);
-
-// Minimal
-const { session } = await createAgentSession({ authStorage, modelRegistry });
-
-// Custom model
-const model = getModel("anthropic", "claude-opus-4-5");
-const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
-
-// Modify prompt
-const loader = new DefaultResourceLoader({
-  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
-});
-await loader.reload();
-const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
-
-// Read-only
-const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });
-
-// In-memory
-const { session } = await createAgentSession({
-  sessionManager: SessionManager.inMemory(),
-  authStorage,
-  modelRegistry,
-});
-
-// Full control
-const customAuth = AuthStorage.create("/my/app/auth.json");
-customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
-const customRegistry = new ModelRegistry(customAuth);
-
-const resourceLoader = new DefaultResourceLoader({
-  systemPromptOverride: () => "You are helpful.",
-  extensionFactories: [myExtension],
-  skillsOverride: () => ({ skills: [], diagnostics: [] }),
-  agentsFilesOverride: () => ({ agentsFiles: [] }),
-  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
-});
-await resourceLoader.reload();
-
-const { session } = await createAgentSession({
-  model,
-  authStorage: customAuth,
-  modelRegistry: customRegistry,
-  resourceLoader,
-  tools: [readTool, bashTool],
-  customTools: [{ tool: myTool }],
-  sessionManager: SessionManager.inMemory(),
-  settingsManager: SettingsManager.inMemory(),
-});
-
-// Run prompts
-session.subscribe((event) => {
-  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-    process.stdout.write(event.assistantMessageEvent.delta);
-  }
-});
-await session.prompt("Hello");
-```
-
-## Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `authStorage` | `AuthStorage.create()` | Credential storage |
-| `modelRegistry` | `new ModelRegistry(authStorage)` | Model registry |
-| `cwd` | `process.cwd()` | Working directory |
-| `agentDir` | `~/.shortcut/agent` | Config directory |
-| `model` | From settings/first available | Model to use |
-| `thinkingLevel` | From settings/"off" | off, low, medium, high |
-| `tools` | `codingTools` | Built-in tools |
-| `customTools` | `[]` | Additional tool definitions |
-| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes |
-| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
-| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
-
-## Events
-
-```typescript
-session.subscribe((event) => {
-  switch (event.type) {
-    case "message_update":
-      if (event.assistantMessageEvent.type === "text_delta") {
-        process.stdout.write(event.assistantMessageEvent.delta);
-      }
-      break;
-    case "tool_execution_start":
-      console.log(`Tool: ${event.toolName}`);
-      break;
-    case "tool_execution_end":
-      console.log(`Result: ${event.result}`);
-      break;
-    case "agent_end":
-      console.log("Done");
-      break;
-  }
-});
-```
+# SDK Examples
+
+Programmatic usage of shortcutxl via `createAgentSession()`.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tools, custom tools |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-slash-commands.ts` | File-based slash commands |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+
+## Running
+
+```bash
+cd packages/coding-agent
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "shortcutxl";
+import {
+  AuthStorage,
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+  codingTools,
+  readOnlyTools,
+  readTool, bashTool, editTool, writeTool,
+} from "shortcutxl";
+
+// Auth and models setup
+const authStorage = AuthStorage.create();
+const modelRegistry = new ModelRegistry(authStorage);
+
+// Minimal
+const { session } = await createAgentSession({ authStorage, modelRegistry });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
+
+// Read-only
+const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
+});
+
+// Full control
+const customAuth = AuthStorage.create("/my/app/auth.json");
+customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+const customRegistry = new ModelRegistry(customAuth);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  model,
+  authStorage: customAuth,
+  modelRegistry: customRegistry,
+  resourceLoader,
+  tools: [readTool, bashTool],
+  customTools: [{ tool: myTool }],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `authStorage` | `AuthStorage.create()` | Credential storage |
+| `modelRegistry` | `new ModelRegistry(authStorage)` | Model registry |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.shortcut/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `codingTools` | Built-in tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_end":
+      console.log("Done");
+      break;
+  }
+});
+```

package/agent-docs/xll-spec.md

@@ -1,110 +1,110 @@
-# ShortcutXL
-
-A native Excel add-in (`.xll`) written in C that turns Excel into a programmable surface for an AI agent. The agent runs locally on Windows as a TypeScript/Node.js CLI with a terminal TUI. It controls Excel through two channels: writing Python files for custom functions, and sending code blocks over HTTP for direct manipulation.
-
-See `../agent/PLAN.md` for the agent architecture (loop, multiagent, session management).
-
----
-
-## Architecture
-
-```
-┌─ Windows ──────────────────────────────────────────┐
-│                                                     │
-│  Terminal (PowerShell / Windows Terminal)            │
-│  └─ Agent CLI (Node.js, TypeScript)                 │
-│     ├─ TUI (shortcutxl)                          │
-│     ├─ Supervisor agent loop                        │
-│     │   ├─ POST /exec → localhost:8080 ────────────┼──► HTTP
-│     │   ├─ writes .py → modules/ ──────────────────┼──► filesystem
-│     │   └─ Task tool → spawns worker agents         │
-│     └─ shortcutxl (Anthropic, OpenAI, Google)   │
-│                                                     │
-│  Excel.exe                                          │
-│  └─ ShortcutXL (in-process)                        │
-│     ├─ HTTP server (:8080)                          │
-│     │   ├─ GET /config (paths)                      │
-│     │   └─ POST /exec (run Python)                  │
-│     ├─ fs_watcher (hot-reload)                      │
-│     ├─ CPython 3.12 (embedded)                      │
-│     └─ COM → all open workbooks                     │
-│                                                     │
-└─────────────────────────────────────────────────────┘
-```
-
-On startup the agent calls `GET /config` to discover the `modules/` path and is ready to go. Both agent and Excel run natively on Windows — no WSL boundary, no filesystem translation.
-
----
-
-## Two Channels
-
-### 1. `POST /exec` — imperative actions
-
-Agent sends a Python code block. The XLL runs it in the embedded runtime with full COM access to Excel. The result (stdout + stderr) is returned.
-
-```
-POST http://localhost:8080/exec
-{"code": "from shortcut_xl import xl_app\napp = xl_app()\napp.Range('A1:D1').Value = [['Name','Revenue','Growth','Status']]\napp.Range('A1:D1').Font.Bold = True"}
-
-→ {"ok": true, "output": ""}
-```
-
-Use this for: writing cells, reading data, formatting, creating charts, any one-shot action.
-
-### 2. Filesystem — custom functions
-
-Agent writes `.py` files with `@xl_func` decorators to `modules/`. The XLL watches the directory, hot-reloads within ~200ms, and registers them as native Excel formulas.
-
-```python
-# modules/dashboard.py
-from shortcut_xl import xl_func
-
-@xl_func
-def revenue_ytd(region):
-    return {"EMEA": 1.2e6, "NA": 3.4e6}.get(region, 0)
-```
-
-In Excel: `=revenue_ytd("EMEA")` → `1200000`
-
-Use this for: custom worksheet functions that Excel's calc engine calls repeatedly, tick loops, animations.
-
-### Why two channels
-
-| Need | Channel | Reason |
-|---|---|---|
-| Write cells, format, charts | `/exec` | One-shot, result discarded after execution |
-| Custom formulas (`=foo()`) | filesystem | Excel calls them on every recalculation |
-| Tick loops, animations | filesystem | Persistent code running on a timer |
-
-HTTP gives the agent a simple request/response interface for one-shot operations. The filesystem channel handles the only thing HTTP can't: registering functions with Excel's calc engine via `xlfRegister`, which requires in-process code that persists between calls.
-
----
-
-## What Runs Where
-
-| Component | Where | Why |
-|---|---|---|
-| Agent CLI (LLM calls, orchestration, TUI) | Windows, Node.js process | Native filesystem + HTTP to Excel, no cross-OS friction |
-| ShortcutXL (HTTP, fs_watcher, Python, COM) | Windows, inside excel.exe | In-process access to Excel's internals |
-| `modules/*.py` | Windows filesystem | Agent writes directly, XLL watches for changes |
-
----
-
-## Installation
-
-**Installer (recommended):** MSI drops `ShortcutXL.xll` + embedded Python runtime. Writes registry key:
-
-```
-HKCU\Software\Microsoft\Office\<version>\Excel\Options
-  OPEN = /R "C:\Program Files\Shortcut\ShortcutXL.xll"
-```
-
-Excel loads it automatically on every startup.
-
-**Manual:** Excel → File → Options → Add-ins → Manage: Excel Add-ins → Browse → select `ShortcutXL.xll`.
-
----
-
-## Platform
-
-Windows only. The XLL API is a Windows DLL interface. The custom spreadsheet engine (see `new-sheet-spec.md`) is the cross-platform path.
+# ShortcutXL
+
+A native Excel add-in (`.xll`) written in C that turns Excel into a programmable surface for an AI agent. The agent runs locally on Windows as a TypeScript/Node.js CLI with a terminal TUI. It controls Excel through two channels: writing Python files for custom functions, and sending code blocks over HTTP for direct manipulation.
+
+See `../agent/PLAN.md` for the agent architecture (loop, multiagent, session management).
+
+---
+
+## Architecture
+
+```
+┌─ Windows ──────────────────────────────────────────┐
+│                                                     │
+│  Terminal (PowerShell / Windows Terminal)            │
+│  └─ Agent CLI (Node.js, TypeScript)                 │
+│     ├─ TUI (shortcutxl)                          │
+│     ├─ Supervisor agent loop                        │
+│     │   ├─ POST /exec → localhost:8080 ────────────┼──► HTTP
+│     │   ├─ writes .py → modules/ ──────────────────┼──► filesystem
+│     │   └─ Task tool → spawns worker agents         │
+│     └─ shortcutxl (Anthropic, OpenAI, Google)   │
+│                                                     │
+│  Excel.exe                                          │
+│  └─ ShortcutXL (in-process)                        │
+│     ├─ HTTP server (:8080)                          │
+│     │   ├─ GET /config (paths)                      │
+│     │   └─ POST /exec (run Python)                  │
+│     ├─ fs_watcher (hot-reload)                      │
+│     ├─ CPython 3.12 (embedded)                      │
+│     └─ COM → all open workbooks                     │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+On startup the agent calls `GET /config` to discover the `modules/` path and is ready to go. Both agent and Excel run natively on Windows — no WSL boundary, no filesystem translation.
+
+---
+
+## Two Channels
+
+### 1. `POST /exec` — imperative actions
+
+Agent sends a Python code block. The XLL runs it in the embedded runtime with full COM access to Excel. The result (stdout + stderr) is returned.
+
+```
+POST http://localhost:8080/exec
+{"code": "from shortcut_xl import xl_app\napp = xl_app()\napp.Range('A1:D1').Value = [['Name','Revenue','Growth','Status']]\napp.Range('A1:D1').Font.Bold = True"}
+
+→ {"ok": true, "output": ""}
+```
+
+Use this for: writing cells, reading data, formatting, creating charts, any one-shot action.
+
+### 2. Filesystem — custom functions
+
+Agent writes `.py` files with `@xl_func` decorators to `modules/`. The XLL watches the directory, hot-reloads within ~200ms, and registers them as native Excel formulas.
+
+```python
+# modules/dashboard.py
+from shortcut_xl import xl_func
+
+@xl_func
+def revenue_ytd(region):
+    return {"EMEA": 1.2e6, "NA": 3.4e6}.get(region, 0)
+```
+
+In Excel: `=revenue_ytd("EMEA")` → `1200000`
+
+Use this for: custom worksheet functions that Excel's calc engine calls repeatedly, tick loops, animations.
+
+### Why two channels
+
+| Need | Channel | Reason |
+|---|---|---|
+| Write cells, format, charts | `/exec` | One-shot, result discarded after execution |
+| Custom formulas (`=foo()`) | filesystem | Excel calls them on every recalculation |
+| Tick loops, animations | filesystem | Persistent code running on a timer |
+
+HTTP gives the agent a simple request/response interface for one-shot operations. The filesystem channel handles the only thing HTTP can't: registering functions with Excel's calc engine via `xlfRegister`, which requires in-process code that persists between calls.
+
+---
+
+## What Runs Where
+
+| Component | Where | Why |
+|---|---|---|
+| Agent CLI (LLM calls, orchestration, TUI) | Windows, Node.js process | Native filesystem + HTTP to Excel, no cross-OS friction |
+| ShortcutXL (HTTP, fs_watcher, Python, COM) | Windows, inside excel.exe | In-process access to Excel's internals |
+| `modules/*.py` | Windows filesystem | Agent writes directly, XLL watches for changes |
+
+---
+
+## Installation
+
+**Installer (recommended):** MSI drops `ShortcutXL.xll` + embedded Python runtime. Writes registry key:
+
+```
+HKCU\Software\Microsoft\Office\<version>\Excel\Options
+  OPEN = /R "C:\Program Files\Shortcut\ShortcutXL.xll"
+```
+
+Excel loads it automatically on every startup.
+
+**Manual:** Excel → File → Options → Add-ins → Manage: Excel Add-ins → Browse → select `ShortcutXL.xll`.
+
+---
+
+## Platform
+
+Windows only. The XLL API is a Windows DLL interface. The custom spreadsheet engine (see `new-sheet-spec.md`) is the cross-platform path.

package/dist/core/auth-storage.js

@@ -11,6 +11,12 @@ import { dirname, join } from 'path';
 import lockfile from 'proper-lockfile';
 import { getAgentDir } from '../config.js';
 import { resolveConfigValue } from './resolve-config-value.js';
+/**
+ * Shared lock options so sync and async locks always use the same lock path.
+ * realpath: false ensures both create the same .lock directory on Windows,
+ * where fs.realpath can normalize paths differently.
+ */
+const LOCK_BASE_OPTIONS = { realpath: false };
 export class FileAuthStorageBackend {
     authPath;
     constructor(authPath = join(getAgentDir(), 'auth.json')) {
@@ -33,7 +39,7 @@ export class FileAuthStorageBackend {
         this.ensureFileExists();
         let release;
         try {
-            release = lockfile.lockSync(this.authPath, { realpath: false });
+            release = lockfile.lockSync(this.authPath, LOCK_BASE_OPTIONS);
             const current = existsSync(this.authPath) ? readFileSync(this.authPath, 'utf-8') : undefined;
             const { result, next } = fn(current);
             if (next !== undefined) {
@@ -61,6 +67,7 @@ export class FileAuthStorageBackend {
         };
         try {
             release = await lockfile.lock(this.authPath, {
+                ...LOCK_BASE_OPTIONS,
                 retries: {
                     retries: 10,
                     factor: 2,
@@ -245,7 +252,15 @@ export class AuthStorage {
         }
         try {
             this.storage.withLock((current) => {
-                const currentData = this.parseStorageData(current);
+                // If the existing file is corrupt, start from empty rather than failing.
+                // This recovers from partial writes (e.g., process killed mid-save).
+                let currentData;
+                try {
+                    currentData = this.parseStorageData(current);
+                }
+                catch {
+                    currentData = {};
+                }
                 const merged = { ...currentData };
                 if (credential) {
                     merged[provider] = credential;
@@ -327,6 +342,10 @@ export class AuthStorage {
             throw new Error(`Unknown OAuth provider: ${providerId}`);
         }
         const credentials = await provider.login(callbacks);
+        // Clear loadError so persistProviderChange doesn't silently skip the write.
+        // A successful login produces known-good credentials — safe to persist even
+        // if the initial file read failed (corrupt file, lock contention, etc.).
+        this.loadError = null;
         this.set(providerId, { type: 'oauth', ...credentials });
     }
     /**

package/package.json

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