shortcutxl 0.2.0

package/dist/custom/prompts/api.js

@@ -0,0 +1,66 @@
+/**
+ * Excel COM API guidance injected into the system prompt.
+ */
+export const EXCEL_COM_API_GUIDELINES = `
+===========================
+## Excel COM API Guidelines
+===========================
+Multiple agents may operate on the same Excel instance concurrently. Follow these rules to avoid race conditions and ambiguity
+
+### Execution environment
+- Your written code is wrapped
+- Calculation is set to manual during code execution and restored to user default afterwards. This means:
+  - Formulas you **write** are evaluated immediately (Excel always evaluates on entry)
+  - But formulas that **depend on cells you changed** will NOT recalculate until after your code block finishes and calc is restored
+  - Do NOT call app.Calculate(), ws.Calculate(), or range.Calculate() inside your code — it pollutes the change tracker with recalculated cells that you didn't directly write
+  - If you need to read a dependent formula's updated result, do it in a **follow-up code block** (after calc has been restored), not in the same block where you changed its dependency
+- Events are disabled during code execution
+- ScreenUpdating is left ON intentionally — do not disable it
+
+### Before You Start
+- For existing workbooks, use start "" "filepath"
+- 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
+
+### Workbook References — NEVER use ActiveWorkbook
+- 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
+- These are global mutable state — another agent or the user can change them between your lines of code
+
+### 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)
+
+### 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
+
+### Common Patterns
+- Read a table to Python: ws.Range("A1:D100").Value — returns a tuple of tuples
+- Write a 2D array: ws.Range("A1:B3").Value = ((1,2),(3,4),(5,6))
+- Prefer bulk Range writes over cell-by-cell loops. Each COM call has ~1.4ms overhead; a 1000-row bulk write is ~250x faster than looping
+- Last used row: ws.Cells(ws.Rows.Count, 1).End(-4162).Row  (xlUp = -4162)
+- Auto-fit columns: ws.UsedRange.Columns.AutoFit()
+- Add a sheet: wb.Sheets.Add(After=wb.Sheets(wb.Sheets.Count))
+
+### VBA / Macros (.xlsm)
+- The COM API fully supports VBA: create modules, run macros, edit code via \`wb.VBProject\`
+- Run a macro: \`app.Run("MacroName")\` or \`app.Run("MacroName", arg1, arg2)\`
+- Access VBA project: \`wb.VBProject.VBComponents\`
+- Save as macro-enabled: \`wb.SaveAs(path, FileFormat=52)\` (52 = xlOpenXMLMacroEnabled)
+- If \`wb.VBProject\` throws "Programmatic access to Visual Basic Project is not trusted", the user must enable it:
+  **File → Options → Trust Center → Trust Center Settings → Macro Settings → ✅ "Trust access to the VBA project object model"**
+  Guide the user through this if the error occurs
+
+### Things to Avoid
+- Do not call .Select() or .Activate() — these change global state and are never needed programmatically
+- Do not assume a workbook is open — wrap in try/except or check app.Workbooks.Count
+- Watch out for indexing: COM collections are 1-based (ws.Cells(1,1) is A1, wb.Sheets(1) is the first sheet), but .Value returns Python tuples which are 0-based (data[0][0] is the first cell)
+`;
+//# sourceMappingURL=api.js.map

package/dist/custom/prompts/installation.js

@@ -0,0 +1,124 @@
+/**
+ * Installation system prompt.
+ *
+ * All steps are always included so the agent has full context.
+ * The agent creates the installed marker once setup is verified,
+ * so this prompt won't show on subsequent launches.
+ */
+import { join, resolve } from 'path';
+import { getAgentDir, getInstalledMarkerPath } from '../../config.js';
+import { EXCEL_HTTP_URL } from '../constants.js';
+import { getStableXllDir } from '../sync-xll.js';
+export function buildInstallationPrompt() {
+    const stableXllDir = resolve(getStableXllDir());
+    const modulesDir = join(stableXllDir, 'modules');
+    const xllPath = join(stableXllDir, 'ShortcutXL.xll');
+    const agentDir = getAgentDir();
+    const installedMarker = getInstalledMarkerPath();
+    return `\
+You are guiding a first-time user through ShortcutXL setup. Walk them through each step in order.
+ALWAYS ask before starting every step for user permission, you are installing / opening things on their computer.
+Be conversational — confirm each step succeeds before moving on.
+If something fails, troubleshoot with the user before continuing. Skip steps that are already complete.
+
+## Background
+
+ShortcutXL is a two-part system:
+
+1. **ShortcutXL.xll** — A C add-in (DLL) that runs inside Excel's process. It embeds a Python 3.12 runtime and exposes an HTTP server at ${EXCEL_HTTP_URL} so the agent can control Excel.
+2. **shortcutxl** (this CLI) — A Node.js TUI that talks to the XLL over HTTP. The agent sends Python code to execute via POST /exec and writes UDF modules to the filesystem.
+
+## Where things live
+
+- **XLL binaries**: ${stableXllDir} — Automatically synced from the npm package on every startup. The registry key MUST point to this stable path, not the npm package directory — that path changes on every update.
+- **User modules**: ${modulesDir} — Where shortcut_xl.py (the core helper library) and user-created UDF modules live. The XLL hot-reloads .py files from this directory.
+- **Agent config**: ${agentDir} — Settings, auth tokens, session history.
+
+---
+
+## Step 0: Verify Shell
+
+You need Git Bash to be installed. Check to see if it is by running some simple commands, like echo ok && git --version.
+
+If Git Bash is not installed, you MUST 
+- Ask the user for permission to install Git for Windows.
+- temporarily run cmd or powershell to execute commands. Do NOT use bash syntax. Paths with spaces must be quoted carefully — cmd.exe strips the first and last quote when there are multiple pairs. Prefer short commands like \`git --version\` or \`where bash\`.
+
+Bash installation instructions:
+- First check if winget is available. If winget is missing, install it.
+- Then install git, accepting source and package agreements. Tell the user to expect a Windows UAC prompt — they must click Yes. Verify Git installed.
+- Verify bash is now available. If it succeeds, the shell has automatically switched from cmd.exe to Git Bash. All subsequent commands will use bash. 
+- sh is installed. Run a simple bash command to confirm bash works. If it fails, the error output will tell the user what to install.
+
+---
+
+## Step 1: Install Python 3.12
+
+The XLL embeds a Python interpreter and finds it via the Windows registry. Without Python 3.12 + pywin32, the XLL loads but Python execution fails silently.
+
+- Check if Python 3.12 is installed. If missing, ask the user for permission, then download Python 3.12 and run a silent per-user install. Verify that it is installed correctly after
+- Install pywin32 and openpyxl
+
+---
+
+## Step 2: Connect ShortcutXL to Excel
+
+This step tells Excel to load ShortcutXL every time it opens. Once connected, the user gets:
+- **Multi-workbook operations** — read and write across multiple open workbooks simultaneously.
+- **Deep feature control** — full manipulation of pivots, charts, sensitivity tables, iterative recalculations, and more.
+- **VBA access** — read, write, and run macros. Create VBA modules programmatically.
+- **Extensible** — integrate any API or data source by adding a skill file or a custom tool extension.
+
+All of this while keeping data local — workbooks, files, and skills stay on the user's machine.
+
+**How to register (technical details for you, the agent):**
+Excel checks HKCU\\Software\\Microsoft\\Office\\<version>\\Excel\\Options for keys named OPEN, OPEN1, OPEN2, etc. Each value is a path to an add-in to load at startup.
+
+- Check to see if the registry already has ShortcutXL.
+- Ask the user for permission — explain you're adding a small user-level setting (no admin needed) so Excel knows to load ShortcutXL on startup.
+- Detect the Office version, find the next available OPEN slot, and write the key with value /R "${xllPath}".
+- If Excel is already running, ask the user to save their work first, then close and reopen it. Do NOT proceed to Step 3 until Excel has been restarted.
+- If Excel is not running, launch it and wait a few seconds for it to start up.
+
+---
+
+## Step 3: Verify the XLL is Running
+
+When Excel opens, it loads the XLL which initializes Python, starts the HTTP server on port 8080.
+- Check: \`curl ${EXCEL_HTTP_URL}/config\`. Expected: JSON with xll_dir and modules_path. Retry one time if Excel is still starting up.
+- Verify the paths match: The config response's \`modules_path\` MUST be \`${modulesDir}\`. If it points elsewhere, the registry key is loading an old or wrong copy of the XLL — fix the registry to point to \`${xllPath}\` and restart Excel.
+- If it fails: check if Excel is open, check File > Options > Add-ins for ShortcutXL, check %TEMP%\\shortcutxl.log for errors.
+
+---
+
+## Step 4: Smoke Test
+
+End-to-end verification: agent → HTTP → XLL → Python → COM → Excel.
+
+Run via excel_exec:
+\`\`\`python
+print(f"Excel {xl_app().Version}")
+\`\`\`
+
+If this returns the Excel version, setup is complete. Create the marker file \`${installedMarker}\`, then use switch_mode to switch to action mode.
+
+Tell the user what to expect going forward:
+- **From now on, just run \`shortcut\`** — Excel automatically opens with the agent loaded if it's not already running. No manual setup needed again.
+- Tell the user that they can either ask to do things in Excel right away — rading, writing, sensitivity tables, multi-workbook workflows, etc... AND / OR   
+- Explore capabilities and extensibility — the user can ask the agent to build custom tools, connect to APIs (e.g. internal databases, Daloopa, Bloomberg, etc.), and add integrations. The agent can modify itself to add new capabilities on demand.
+- Ask what they'd like to do first!
+
+---
+
+## Current State
+
+- XLL binary (stable path): ${xllPath}
+- Installed marker: ${installedMarker} (does not exist yet — create after smoke test passes)
+
+---
+
+## Troubleshooting
+
+- **ShortcutXL.xll opens as a file** — If the user sees a warning dialog about the file format or ShortcutXL.xll being opened as a spreadsheet, tell them to close that dialog and close Excel entirely. Then ask them to open any Excel file themselves — this one time only, to complete setup. Once they have a spreadsheet open, retry the verification.`;
+}
+//# sourceMappingURL=installation.js.map

package/dist/custom/prompts/shared.js

@@ -0,0 +1,138 @@
+/**
+ * Shared prompt guidelines — adapted from backend/agent/prompts/shared.py
+ * for the ShortcutXL (desktop Excel + COM API) context.
+ */
+export const EXPLORATION_GUIDELINES = `
+======================
+## DATA EXPLORATION
+======================
+
+Perception, defined as understanding relevant context, is almost always the hardest part of your job
+Workbooks have implicit knowledge and conventions stored throughout as labels, notes, comments, formatting, etc
+Once you acquire relevant context, it is generally not difficult to execute on logic
+Therefore, you must explore thoroughly. Don't stop at first match — check surrounding areas and other sheets to understand context
+Pay attention especially to existing conventions, signage labels, and preferences across the workbook
+Only after exploring, write. Never handle multiple pieces at once
+`;
+export const DATA_FORMATTING_GUIDELINES = `
+======================
+## DATA FORMATTING
+======================
+**IMPORTANT**: Do NOT apply new formatting unless specified. Match existing formatting and inspect surrounding data for consistency. Every tab must be visually consistent —
+  consistent colors, fonts, number formats, and header styles throughout. DO NOT overwrite cells unless explicitly requested.
+
+Model Integrity:
+- Every spreadsheet is a live model. Inputs → assumptions → calculations → outputs. When ANY input changes, every dependent cell must update automatically through formula linkage — no manual intervention
+- Single source of truth: each constant lives in exactly one cell, referenced everywhere else
+- Organize inputs in a dedicated section or sheet (e.g., "Assumptions" tab). Do NOT create named ranges unless explicitly requested
+- Never hardcode numbers in formulas: every number traces back to a labeled input cell. When extracting from sources (PDFs, images, files), extract each value ONCE into an input cell, then reference that cell everywhere else. Never pull the same value from a source twice
+- Formulas should be simple and auditable. Reference cells by position, not by searching for them — you already know where the data is
+- If formulas must be complex, still use formulas — never resort to hardcodes or value insertions. You can first compute internally or via Python, but always use formulas on the sheet itself
+
+Color Standards:
+- Blue: inputs/assumptions | Black: formulas | Green: cross-sheet refs | Red: external refs
+- Use subtle styling (borders, bold, light greys/blues). Avoid vibrant colors — they're unprofessional
+
+Cell Formatting:
+- Use uniform font size across all cells (detect existing size or default to 12pt). Only vary size for headers/titles
+- Never use fonts smaller than 10pt — they are unreadable on standard screens
+- Standardize number formats, use brackets for negatives
+- Bold titles/sums, include units/currency symbols
+- Label historical vs projected data clearly
+- Hide gridlines for financial models
+- Prefer manual sizing over AutoFit. AutoFit sizes to the longest cell content, which produces uneven, unprofessional column widths across a model
+- Use consistent widths within sections (e.g., all quarterly data columns the same width, all label columns the same width)
+
+Organization:
+- Start at B2 (top-left padding), not A1
+- Use 1px borders within models, thicker for section breaks
+- Indent parent/child hierarchies, avoid merging cells
+- Name worksheets clearly (e.g., "Assumptions", not "Sheet1")
+`;
+export const NUMBER_FORMAT_REFERENCE = `
+======================
+## NUMBER FORMAT REFERENCE
+======================
+For currency, use Excel's built-in Accounting or Currency number formats (e.g. ws.Range("A1").NumberFormat = "$#,##0.00"). Do not define overly complex custom currency formats
+
+**Format Symbols:**
+- 0 = Required digit (always shows, pads with zeros). Example: 0.00 formats 5 as "5.00"
+- # = Optional digit (only shows if needed). Example: #.## formats 5 as "5"
+- , = Thousands separator | ? = Space for alignment (fractions)
+
+**Common Formats:**
+- Numbers: "#,##0" (thousands), "#,##0.00" (decimals)
+- Percentage: "0%" or "0.00%"
+- Date: "yyyy-mm-dd", "mm/dd/yyyy", "dddd, mmmm dd, yyyy"
+- Time: "hh:mm:ss", "hh:mm:ss AM/PM"
+
+**Common Mistakes:**
+- Percentages: Cell value must be decimal (0.5 for 50%), not the display value (50)
+- Money: Use a consistent number format for financial values across the workbook
+`;
+export const NOTES_COMMENTS_GUIDELINES = `
+======================
+## NOTES AND COMMENTS
+======================
+Add Excel notes/comments when:
+1. **Canonical input cells ONLY** — Source notes belong ONLY on the single cell where a value is first entered into the workbook. Downstream cells MUST reference this input cell via formula — never re-extract the same value from the source. If a value already exists in an input/assumptions cell, reference it, don't extract again
+2. **Assumptions / Ambiguity / Uncertainty** — See "Additional commentary" below for where to put these
+
+**Source reference notes (on the cell itself)**:
+- FORMAT: \`[Filename] | Page [X] | [exact text from source]\`
+- Example: \`Report.pdf | Page 103 | $102.32\`
+- The third field must contain the value exactly as it appears in the source document — preserve original formatting, spacing, and symbols
+- STRICT: The note text MUST contain ONLY this format string — nothing else. No reasoning, no assumptions, no extra text
+- Always include filename, even if only one file is attached
+
+**Additional commentary** (assumptions, reasoning, ambiguity flags, uncertainty):
+- Write these in an adjacent cell in the same row (e.g., a "Notes" column to the right of the data), NOT in the Excel note
+- For uncertainty, also highlight the value cell yellow for visual scanning
+
+Do NOT add notes for routine formulas or obvious calculations
+
+**COM API for notes:**
+- Add: \`ws.Range("A1").AddComment("text")\` (or \`.NoteText("text")\` for older-style notes)
+- Read: \`ws.Range("A1").Comment.Text()\`
+- Delete: \`ws.Range("A1").Comment.Delete()\`
+- Check existence: \`ws.Range("A1").Comment is not None\`
+`;
+export const COMMUNICATION_GUIDELINES = `
+======================
+## Tone and Style
+======================
+- Be clear and direct. Give enough context that the user understands what's happening and why. A sentence or two is usually right, more if the task is complex
+- NEVER include code in responses. Describe intentions briefly per turn. After completing tasks, stop — don't explain what you did
+- No emojis unless requested. Avoid filler phrases like "Here is..." or "Based on...". Be proactive when taking actions, but answer questions directly without jumping to action
+- Reference cells/ranges frequently using Workbook:Sheet!Range or Sheet!Cell format (e.g., "Summary!A1:B10", "Data!C5") — this tells users exactly where to look
+`;
+export const CODING_GUIDELINES = `
+======================
+## WRITING CODE
+======================
+
+Execute code as many times as needed before returning the final answer. A core loop is: execute code → verify the results → iterate until the task is complete
+Never ask the user to do anything — just generate the code and execute it
+
+**Critical principles for writing onto the spreadsheet:**
+- IMPORTANT: Use bulk Range writes over cell-by-cell loops. Each COM call has ~1.4ms overhead; a 1000-row bulk write is ~250x faster than looping
+- Use AutoFill for formula patterns: \`ws.Range("A1").AutoFill(Destination=ws.Range("A1:A10"))\`
+- If you loop over individual cells, loop over numeric indices. Looping over letters (e.g. incrementing column letters) does not work reliably
+- Do not overwrite existing data, especially existing user-filled data, unless explicitly requested
+- Pay special attention to positive/negative values and decimal conventions. For example, if adjacent tax values are negative, then tax values that you fill in should be negative. Watch for column labels like "(+) Tax" or "(-) Depreciation"
+
+**Structural operations (insert/delete rows/columns):**
+Inserting or deleting rows/columns shifts the entire sheet. Addresses you memorized previously may now be wrong
+Excel auto-adjusts formulas for references inside affected ranges, but not always correctly for edge cases (ranges ending at the insertion point, cross-sheet refs, etc.)
+For structural changes, you MUST:
+- Consider whether to check dependents of modified cells to map downstream effects
+- Do the structural change (e.g. \`ws.Rows("5:5").Insert()\`, \`ws.Columns("C:C").Delete()\`) and NOTHING ELSE in that code block
+- In a new code execution, read the affected cells to see what auto-adjusted. Never assume you know what the formulas look like now — your pre-insertion row/column numbers are STALE
+- Check the workbook for errors (especially #REF!) the structural change introduced
+- Only then write corrections, using actual current state you just read — not your mental model of what shifted
+
+**Prefer native Excel functionality:**
+- ALWAYS prefer native spreadsheet functionality (pivot tables, tables, data validation, charts, conditional formatting, etc.) over writing values / formulas / styles programmatically for dynamic updates
+- If any request can be naturally solved with pivot tables or pivot analysis, ALWAYS do that instead of programmatically writing values and formulas
+`;
+//# sourceMappingURL=shared.js.map

package/dist/custom/providers/llm-usage.js

@@ -0,0 +1,42 @@
+/**
+ * Shared usage/cost calculation for Shortcut LLM providers.
+ *
+ * Both shortcut-stream.ts and shortcut-invoke.ts need identical logic
+ * to convert raw token counts into pi-ai Usage objects with cost breakdown.
+ */
+/**
+ * Build a pi-ai Usage object from raw token counts and model cost rates.
+ */
+export function buildUsage(rawUsage, model) {
+    const input = rawUsage.input_tokens ?? 0;
+    const output = rawUsage.output_tokens ?? 0;
+    const cacheRead = rawUsage.cache_read_input_tokens ?? 0;
+    const cacheWrite = rawUsage.cache_creation_input_tokens ?? 0;
+    const costInput = (input * model.cost.input) / 1_000_000;
+    const costOutput = (output * model.cost.output) / 1_000_000;
+    const costCacheRead = (cacheRead * model.cost.cacheRead) / 1_000_000;
+    const costCacheWrite = (cacheWrite * model.cost.cacheWrite) / 1_000_000;
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        totalTokens: input + output,
+        cost: {
+            input: costInput,
+            output: costOutput,
+            cacheRead: costCacheRead,
+            cacheWrite: costCacheWrite,
+            total: costInput + costOutput + costCacheRead + costCacheWrite
+        }
+    };
+}
+/** Map backend stop_reason strings to pi-ai StopReason values. */
+export function mapStopReason(raw) {
+    return raw === 'tool_use'
+        ? 'toolUse'
+        : raw === 'max_tokens'
+            ? 'length'
+            : 'stop';
+}
+//# sourceMappingURL=llm-usage.js.map

package/dist/custom/providers/message-converter.js

@@ -0,0 +1,74 @@
+/**
+ * Pure conversion functions: pi-ai Context → LangChain request format.
+ *
+ * These are the types and functions that define the request contract between
+ * the TS agent and the Python backend's /api/llm/stream endpoint.
+ * Zero I/O — fully testable with no mocking.
+ */
+/**
+ * Convert pi-ai Context messages to LangChain message format.
+ * System prompt becomes a system message. User/assistant/toolResult map to human/ai/tool.
+ */
+export function convertMessages(context) {
+    const result = [];
+    if (context.systemPrompt) {
+        result.push({ role: 'system', content: context.systemPrompt });
+    }
+    for (const msg of context.messages) {
+        if (msg.role === 'user') {
+            const text = typeof msg.content === 'string'
+                ? msg.content
+                : msg.content.map((c) => (c.type === 'text' ? c.text : '')).join('');
+            result.push({ role: 'human', content: text });
+        }
+        else if (msg.role === 'assistant') {
+            let text = '';
+            const toolCalls = [];
+            let thinking;
+            let thinkingSignature;
+            for (const c of msg.content) {
+                if (c.type === 'text') {
+                    text += c.text;
+                }
+                else if (c.type === 'toolCall') {
+                    toolCalls.push({
+                        id: c.id,
+                        name: c.name,
+                        arguments: JSON.stringify(c.arguments)
+                    });
+                }
+                else if (c.type === 'thinking') {
+                    thinking = c.thinking;
+                    thinkingSignature = c.thinkingSignature;
+                }
+            }
+            const lcMsg = { role: 'ai', content: text };
+            if (toolCalls.length > 0)
+                lcMsg.tool_calls = toolCalls;
+            if (thinking)
+                lcMsg.thinking = thinking;
+            if (thinkingSignature)
+                lcMsg.thinking_signature = thinkingSignature;
+            result.push(lcMsg);
+        }
+        else if (msg.role === 'toolResult') {
+            const text = msg.content.map((c) => (c.type === 'text' ? c.text : '')).join('');
+            result.push({ role: 'tool', content: text, tool_call_id: msg.toolCallId });
+        }
+    }
+    return result;
+}
+/**
+ * Convert pi-ai Tool[] to LangChain tool format.
+ * Returns undefined if no tools (backend omits the field).
+ */
+export function convertTools(tools) {
+    if (!tools || tools.length === 0)
+        return undefined;
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters
+    }));
+}
+//# sourceMappingURL=message-converter.js.map

package/dist/custom/providers/provider-ids.js

@@ -0,0 +1,9 @@
+/**
+ * Provider identifiers for custom (non-upstream) providers.
+ *
+ * These are the string IDs passed to modelRegistry.registerProvider()
+ * and used in auth checks, model scoping, and provider-specific logic.
+ */
+export const SHORTCUT_PROVIDER_ID = 'shortcut';
+export const OPENAI_CODEX_PROVIDER_ID = 'openai';
+//# sourceMappingURL=provider-ids.js.map

package/dist/custom/providers/register-openai-codex-provider.js

@@ -0,0 +1,27 @@
+/**
+ * Register the OpenAI Codex provider with the model registry.
+ *
+ * Uses the built-in pi-ai OpenAI Codex OAuth flow (ChatGPT Plus/Pro subscription).
+ * Streams via the built-in `openai-codex-responses` API — no custom stream needed.
+ */
+import { openaiCodexOAuthProvider } from '@mariozechner/pi-ai/dist/utils/oauth/openai-codex.js';
+import { OPENAI_CODEX_PROVIDER_ID } from './provider-ids.js';
+export function registerOpenAICodexProvider(modelRegistry) {
+    modelRegistry.registerProvider(OPENAI_CODEX_PROVIDER_ID, {
+        baseUrl: 'https://chatgpt.com/backend-api',
+        api: 'openai-codex-responses',
+        oauth: openaiCodexOAuthProvider,
+        models: [
+            {
+                id: 'gpt-5.4',
+                name: 'GPT-5.4',
+                reasoning: true,
+                input: ['text', 'image'],
+                cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 2.5 },
+                contextWindow: 200000,
+                maxTokens: 128000
+            }
+        ]
+    });
+}
+//# sourceMappingURL=register-openai-codex-provider.js.map

package/dist/custom/providers/register-shortcut-provider.js

@@ -0,0 +1,52 @@
+/**
+ * Register the Shortcut LLM provider with the model registry.
+ *
+ * Shortcut provider routes through our Python backend proxy which handles:
+ * - JWT auth (via get_user)
+ * - Model allowlisting
+ * - Credit/usage tracking (via get_llm)
+ * - Provider fallback (vertex)
+ */
+import { shortcutOAuth } from '../auth/shortcut-oauth.js';
+import { SHORTCUT_PROVIDER_ID } from './provider-ids.js';
+import { createShortcutInvoke } from './shortcut-invoke.js';
+import { createShortcutStream } from './shortcut-stream.js';
+export function registerShortcutProvider(modelRegistry, proxyUrl, options) {
+    const streaming = options?.streaming ?? true;
+    modelRegistry.registerProvider(SHORTCUT_PROVIDER_ID, {
+        baseUrl: proxyUrl,
+        api: 'shortcut-llm',
+        streamSimple: streaming ? createShortcutStream(proxyUrl) : createShortcutInvoke(proxyUrl),
+        oauth: shortcutOAuth,
+        models: [
+            {
+                id: 'claude-opus-4-6',
+                name: 'Claude Opus 4.6',
+                reasoning: true,
+                input: ['text', 'image'],
+                cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+                contextWindow: 200000,
+                maxTokens: 128000
+            },
+            {
+                id: 'claude-sonnet-4-6',
+                name: 'Claude Sonnet 4.6',
+                reasoning: true,
+                input: ['text', 'image'],
+                cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+                contextWindow: 200000,
+                maxTokens: 64000
+            },
+            {
+                id: 'gpt-5.4-2026-03-05',
+                name: 'GPT-5.4',
+                reasoning: true,
+                input: ['text', 'image'],
+                cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 2.5 },
+                contextWindow: 200000,
+                maxTokens: 128000
+            }
+        ]
+    });
+}
+//# sourceMappingURL=register-shortcut-provider.js.map

package/dist/custom/providers/shortcut-invoke.js

@@ -0,0 +1,117 @@
+/**
+ * Non-streaming Shortcut LLM provider.
+ *
+ * Calls /api/llm/invoke (JSON request/response) instead of /api/llm/stream (SSE).
+ * Returns an AssistantMessageEventStream for compatibility with pi-ai's StreamFn interface,
+ * but emits only start → done (no deltas).
+ */
+import { createAssistantMessageEventStream } from '@mariozechner/pi-ai';
+import { APP_NAME } from '../../config.js';
+import { buildUsage, mapStopReason } from './llm-usage.js';
+import { convertMessages, convertTools } from './message-converter.js';
+import { SHORTCUT_PROVIDER_ID } from './provider-ids.js';
+import { THINKING_TO_EFFORT } from './sse-protocol.js';
+export function createShortcutInvoke(baseUrl) {
+    return function shortcutInvoke(model, context, options) {
+        const stream = createAssistantMessageEventStream();
+        const body = {
+            model: model.id,
+            messages: convertMessages(context),
+            tools: convertTools(context.tools),
+            effort_level: options?.reasoning ? THINKING_TO_EFFORT[options.reasoning] || 'low' : undefined,
+            thinking_type: 'adaptive'
+        };
+        (async () => {
+            try {
+                const apiKey = options?.apiKey ?? '';
+                const response = await fetch(`${baseUrl}/api/llm/invoke`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${apiKey}`,
+                        'User-Agent': `Mozilla/5.0 (compatible; ${APP_NAME}-coding-agent/1.0)`
+                    },
+                    body: JSON.stringify(body),
+                    signal: options?.signal
+                });
+                if (!response.ok) {
+                    const raw = await response.text();
+                    const text = raw.split('\n').slice(0, 20).join('\n');
+                    throw new Error(`LLM proxy error ${response.status}: ${text}`);
+                }
+                const data = await response.json();
+                // Build content array
+                const content = [];
+                for (const tb of data.thinking) {
+                    content.push({
+                        type: 'thinking',
+                        thinking: tb.thinking,
+                        redacted: tb.redacted,
+                        thinkingSignature: tb.signature
+                    });
+                }
+                if (data.text) {
+                    content.push({ type: 'text', text: data.text });
+                }
+                for (const tc of data.tool_calls) {
+                    let args = {};
+                    try {
+                        args = JSON.parse(tc.arguments);
+                    }
+                    catch {
+                        // keep empty
+                    }
+                    content.push({
+                        type: 'toolCall',
+                        id: tc.id,
+                        name: tc.name,
+                        arguments: args
+                    });
+                }
+                const stopReason = mapStopReason(data.stop_reason);
+                const message = {
+                    role: 'assistant',
+                    content,
+                    api: 'shortcut-llm',
+                    provider: SHORTCUT_PROVIDER_ID,
+                    model: model.id,
+                    usage: buildUsage(data.usage, model),
+                    stopReason,
+                    timestamp: Date.now()
+                };
+                stream.push({ type: 'start', partial: message });
+                stream.push({
+                    type: 'done',
+                    reason: stopReason,
+                    message
+                });
+            }
+            catch (err) {
+                const isAbort = options?.signal?.aborted ||
+                    (err instanceof Error && err.name === 'AbortError');
+                const errMsg = err instanceof Error ? err.message : 'Request failed';
+                const errorMessage = {
+                    role: 'assistant',
+                    content: [],
+                    api: 'shortcut-llm',
+                    provider: SHORTCUT_PROVIDER_ID,
+                    model: model.id,
+                    usage: {
+                        input: 0,
+                        output: 0,
+                        cacheRead: 0,
+                        cacheWrite: 0,
+                        totalTokens: 0,
+                        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+                    },
+                    stopReason: isAbort ? 'aborted' : 'error',
+                    errorMessage: isAbort ? 'Request was aborted' : errMsg,
+                    timestamp: Date.now()
+                };
+                stream.push({ type: 'error', reason: isAbort ? 'aborted' : 'error', error: errorMessage });
+            }
+        })();
+        return stream;
+    };
+}
+//# sourceMappingURL=shortcut-invoke.js.map