myshell-tools 2.4.0 → 2.7.0

package/dist/commands/login.js

@@ -1,60 +1,253 @@
 /**
- * src/commands/login.ts — `myshell-tools login [claude|codex]`.
+ * src/commands/login.ts — `myshell-tools login [claude|codex] [--code|--browser]`.
  *
  * Frictionless authentication: rather than make the user remember each vendor's
  * CLI auth command, we delegate to the provider's OWN OAuth flow and inherit the
  * terminal so the browser/device sign-in works in place.
  *
- * Security: myshell-tools never sees, handles, or stores raw credentials. Each
- * CLI manages its own tokens; we only trigger its login. (This is what keeps the
- * "use your subscription, no API keys" model honest.)
+ * Two sign-in methods:
+ *   - 'browser': the provider's default flow, which spins up a localhost
+ *     callback server and opens a browser. Great on a laptop; FAILS inside
+ *     containers / over SSH (Replit, Codespaces, etc.) where localhost can't be
+ *     reached from the user's browser.
+ *   - 'code':   a no-localhost flow that works anywhere.
+ *       · claude → `claude setup-token`: prints a link; the user signs in at
+ *         claude.ai, copies the authorization code, and pastes it back here.
+ *         After the command exits, we prompt the user to paste the minted token
+ *         (sk-ant-oat…), persist it, and inject it into process.env so that
+ *         subsequent `claude auth status` and `claude -p …` calls see it.
+ *       · codex  → `codex login --device-auth`: prints a URL + one-time code;
+ *         the user authorizes their ChatGPT account on any device.
+ *
+ * When no method is forced, we auto-detect: headless/remote environments default
+ * to 'code' (so the localhost trap is avoided), everything else to 'browser'.
+ *
+ * Security: myshell-tools never stores raw API keys or passwords.  The Claude
+ * OAuth token (sk-ant-oat…) is captured only after the user explicitly pastes
+ * it and is stored in ~/.myshell-tools/credentials.json (mode 0o600).
  */
+import readline from 'node:readline';
 import { execa } from 'execa';
 import { detectProvider, getInstallCommand } from '../providers/detect.js';
 import { bold, dim, green, red } from '../ui/theme.js';
-/** Each provider's interactive sign-in command. */
+import { extractClaudeToken, saveClaudeToken } from '../infra/credentials.js';
+/** Each provider's default (browser/localhost) sign-in command. */
 const LOGIN_COMMAND = {
     claude: { bin: 'claude', args: ['auth', 'login'] },
     codex: { bin: 'codex', args: ['login'] },
+    // opencode ships free models — no credentials required. `opencode auth login` adds
+    // a premium provider/subscription (e.g. anthropic, openai, or opencode-zen).
+    opencode: { bin: 'opencode', args: ['auth', 'login'] },
+};
+/**
+ * Each provider's no-localhost ("code") sign-in command, plus the human steps
+ * we print before handing over the terminal so the user knows what to expect.
+ */
+const LOGIN_CODE_COMMAND = {
+    claude: {
+        bin: 'claude',
+        args: ['setup-token'],
+        guidance: 'A sign-in link will appear below.\n' +
+            '  1. Open it in any browser and sign in at claude.ai.\n' +
+            '  2. Copy the authorization code it shows you.\n' +
+            '  3. Paste the code back here at the prompt and press Enter.',
+    },
+    codex: {
+        bin: 'codex',
+        args: ['login', '--device-auth'],
+        guidance: 'A URL and a one-time code will appear below.\n' +
+            '  1. On any device, open the URL.\n' +
+            '  2. Enter the code shown and authorize your ChatGPT account.\n' +
+            '  3. Sign-in completes here automatically once authorized.',
+    },
+    opencode: {
+        bin: 'opencode',
+        args: ['auth', 'login'],
+        guidance: 'Free models need no login.\n' +
+            '  This starts `opencode auth login` to add a premium provider or subscription\n' +
+            '  (e.g. anthropic, openai, or opencode-zen).\n' +
+            '  myshell-tools never sees the credentials — opencode manages them.',
+    },
 };
 export function isProviderId(value) {
-    return value === 'claude' || value === 'codex';
+    return value === 'claude' || value === 'codex' || value === 'opencode';
+}
+/**
+ * Decide whether the current environment can actually reach a localhost OAuth
+ * callback / open a browser. Pure (env + platform in, boolean out) so it is
+ * hermetically testable.
+ *
+ * Returns true for environments where the browser/localhost flow typically
+ * fails and the code method should be preferred:
+ *   - Known cloud IDEs / containers (Replit, Codespaces, Gitpod).
+ *   - SSH sessions (no local browser).
+ *   - Linux with no X11/Wayland display (headless box — nothing to open).
+ */
+export function isHeadlessEnv(env, platform) {
+    if (env['REPL_ID'] !== undefined ||
+        env['REPLIT_DEV_DOMAIN'] !== undefined ||
+        env['CODESPACES'] !== undefined ||
+        env['GITPOD_WORKSPACE_ID'] !== undefined) {
+        return true;
+    }
+    if (env['SSH_CONNECTION'] !== undefined || env['SSH_TTY'] !== undefined) {
+        return true;
+    }
+    if (platform === 'linux' &&
+        (env['DISPLAY'] === undefined || env['DISPLAY'] === '') &&
+        (env['WAYLAND_DISPLAY'] === undefined || env['WAYLAND_DISPLAY'] === '')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Resolve the sign-in method to use. An explicit choice always wins; otherwise
+ * fall back to environment auto-detection (headless → 'code', else 'browser').
+ * Pure / testable.
+ */
+export function resolveLoginMethod(explicit, env, platform) {
+    if (explicit !== undefined)
+        return explicit;
+    return isHeadlessEnv(env, platform) ? 'code' : 'browser';
 }
 /**
  * Run the interactive sign-in flow for one provider (or all installed providers
  * when no argument is given). Returns 0 on success, 1 only for an invalid
  * argument — individual sign-in failures are reported but do not fail the command.
+ *
+ * @param opts.method   - Force 'browser' or 'code'. When omitted, the method is
+ *   auto-detected from the environment via {@link resolveLoginMethod}.
+ * @param opts.readLine - Injected line-reader for the token-paste prompt (used
+ *   by the menu so it shares the single readline interface). When absent, a
+ *   temporary readline interface is created and immediately closed after one line.
  */
-export async function runLogin(out, providerArg) {
+export async function runLogin(out, providerArg, opts) {
     let targets;
     if (providerArg !== undefined) {
         if (!isProviderId(providerArg)) {
-            out.write(red(`Unknown provider "${providerArg}". Use: claude or codex.\n`, out.color));
+            out.write(red(`Unknown provider "${providerArg}". Use: claude, codex, or opencode.\n`, out.color));
             return 1;
         }
         targets = [providerArg];
     }
     else {
-        targets = ['claude', 'codex'];
+        targets = ['claude', 'codex', 'opencode'];
     }
+    const method = resolveLoginMethod(opts?.method, process.env, process.platform);
     for (const id of targets) {
         const status = await detectProvider(id);
         if (!status.installed) {
             out.write(dim(`${id}: not installed — skipping. Install with: ${getInstallCommand(id)}\n`, out.color));
             continue;
         }
-        out.write(bold(`\nSigning in to ${id} — a browser window may open…\n`, out.color));
-        const { bin, args } = LOGIN_COMMAND[id];
-        // stdio:'inherit' hands the terminal to the provider CLI so its OAuth/device
-        // flow runs in place. reject:false so we report rather than throw.
-        const result = await execa(bin, [...args], { stdio: 'inherit', reject: false });
+        // stdio:'inherit' hands the terminal to the provider CLI so its OAuth /
+        // device / paste flow runs in place. reject:false so we report rather than throw.
+        let result;
+        if (method === 'code') {
+            const { bin, args, guidance } = LOGIN_CODE_COMMAND[id];
+            out.write(bold(`\nSigning in to ${id} — code method (no localhost needed).\n`, out.color));
+            out.write(dim(guidance + '\n', out.color));
+            result = await execa(bin, [...args], { stdio: 'inherit', reject: false });
+        }
+        else {
+            const { bin, args } = LOGIN_COMMAND[id];
+            out.write(bold(`\nSigning in to ${id} — a browser window may open…\n`, out.color));
+            result = await execa(bin, [...args], { stdio: 'inherit', reject: false });
+        }
         if (result.exitCode === 0) {
             out.write(green(`✓ ${id} sign-in complete.\n`, out.color));
+            // --- Claude code-method token capture -----------------------------------
+            // `claude setup-token` mints a long-lived token (sk-ant-oat01-…) and PRINTS
+            // it to the terminal but does NOT persist it.  After the command exits we
+            // prompt the user to paste the token so we can store it and inject it into
+            // process.env — making `claude auth status` report loggedIn:true and making
+            // every subsequent `claude -p …` spawn work without manual env-var setup.
+            if (id === 'claude' && method === 'code') {
+                await captureClaudeToken(out, opts?.readLine);
+            }
         }
         else {
             out.write(red(`✗ ${id} sign-in did not complete (exit ${result.exitCode ?? 'unknown'}).\n`, out.color));
+            // The classic container failure mode is a dead localhost callback. Point
+            // the user at the code method, which sidesteps localhost entirely.
+            if (method === 'browser') {
+                out.write(dim(`If the browser/localhost step failed, try the code method instead:\n` +
+                    `  myshell-tools login ${id} --code\n`, out.color));
+            }
         }
     }
     return 0;
 }
+// ---------------------------------------------------------------------------
+// Token capture helper (internal — exported for tests via credentials.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Prompt the user to paste the token shown by `claude setup-token`, extract
+ * it, persist it, and inject it into `process.env.CLAUDE_CODE_OAUTH_TOKEN`.
+ *
+ * Uses the injected `readLine` when provided (menu shares its single readline
+ * interface). Otherwise creates a temporary readline interface, reads ONE line,
+ * and immediately closes it (so stdin is not held open).
+ *
+ * Never throws — a blank or invalid paste is reported as a dim advisory note.
+ */
+async function captureClaudeToken(out, readLine) {
+    out.write('\nPaste the token shown above (starts with sk-ant-oat) and press Enter' +
+        ' — or leave blank to skip:\n> ');
+    let pasted;
+    if (readLine !== undefined) {
+        // Menu injected its own reader — use it directly, do NOT create a second
+        // readline interface (that would double-consume stdin).
+        pasted = await readLine();
+    }
+    else {
+        // CLI direct path — create a temporary readline, read one line, close.
+        pasted = await readOneLineFromStdin();
+    }
+    const token = extractClaudeToken(pasted ?? '');
+    if (token !== null) {
+        try {
+            await saveClaudeToken(token);
+            process.env['CLAUDE_CODE_OAUTH_TOKEN'] = token;
+            out.write(green('✓ Claude token saved — claude is now ready.\n', out.color));
+        }
+        catch {
+            out.write(dim('Could not save token to disk — you can re-run `myshell-tools login claude --code` later.\n', out.color));
+        }
+    }
+    else {
+        out.write(dim('Token not captured. Re-run `myshell-tools login claude --code` and paste the\n' +
+            'sk-ant-oat… value (NOT an Anthropic API key starting with sk-ant-api).\n', out.color));
+    }
+}
+/**
+ * Create a temporary readline interface on process.stdin, read exactly one
+ * line, and close the interface. Returns the trimmed line or null on EOF.
+ *
+ * This is used only from the `myshell-tools login` direct CLI path where no
+ * shared readline interface exists.
+ */
+function readOneLineFromStdin() {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: false,
+        });
+        let resolved = false;
+        rl.once('line', (raw) => {
+            resolved = true;
+            rl.close();
+            resolve(raw.trim());
+        });
+        rl.once('close', () => {
+            if (!resolved) {
+                resolved = true;
+                resolve(null);
+            }
+        });
+    });
+}
+// Re-export extractClaudeToken so test/unit/credentials.test.ts can import it
+// directly from credentials.ts (where it is defined). No re-export needed here.
 //# sourceMappingURL=login.js.map

package/dist/commands/login.js.map

@@ -1 +1 @@
-{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/commands/login.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAG9B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAEvD,mDAAmD;AACnD,MAAM,aAAa,GAAmF;IACpG,MAAM,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAClD,KAAK,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;CACzC,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,OAAO,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAe,EAAE,WAAoB;IAClE,IAAI,OAAqB,CAAC;IAC1B,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,EAAE,CAAC;YAC/B,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,qBAAqB,WAAW,4BAA4B,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YACxF,OAAO,CAAC,CAAC;QACX,CAAC;QACD,OAAO,GAAG,CAAC,WAAW,CAAC,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACtB,GAAG,CAAC,KAAK,CACP,GAAG,CAAC,GAAG,EAAE,6CAA6C,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAC5F,CAAC;YACF,SAAS;QACX,CAAC;QAED,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,iCAAiC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QACnF,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;QACxC,6EAA6E;QAC7E,mEAAmE;QACnE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAEhF,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,KAAK,CACP,GAAG,CAAC,KAAK,EAAE,mCAAmC,MAAM,CAAC,QAAQ,IAAI,SAAS,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAC7F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/commands/login.ts"],"names":[],"mappings":"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"}

package/dist/core/assess.js

@@ -12,70 +12,10 @@
  *
  * Pure module: no I/O, no time, no randomness.
  */
+import { lastJsonObjectWithKey } from './json-envelope.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/**
- * Attempt to extract the last JSON object from `text` that looks like a
- * confidence envelope.  Returns the raw parsed object or null.
- *
- * Strategy: scan backwards for the last `{...}` block that contains at least
- * the `confidence` key, then try to parse it.  This is robust to:
- *  - trailing whitespace / newlines
- *  - the model emitting extra text after the envelope (we pick the LAST match)
- *  - duplicate envelopes (last one wins — the model may have regenerated it)
- *  - garbage / truncated JSON elsewhere in the output
- */
-function extractEnvelope(text) {
-    // Find all candidates: substrings that start with '{' and end with '}'
-    // We do this by iterating over all '{' positions and trying to match the
-    // closing '}', handling depth.  We collect all valid JSON objects and
-    // return the last one that has a 'confidence' key.
-    const candidates = [];
-    let i = 0;
-    while (i < text.length) {
-        const start = text.indexOf('{', i);
-        if (start === -1)
-            break;
-        // Walk forward tracking brace depth to find the matching '}'
-        let depth = 0;
-        let j = start;
-        let foundClose = false;
-        while (j < text.length) {
-            if (text[j] === '{') {
-                depth++;
-            }
-            else if (text[j] === '}') {
-                depth--;
-                if (depth === 0) {
-                    foundClose = true;
-                    break;
-                }
-            }
-            j++;
-        }
-        if (foundClose) {
-            const candidate = text.slice(start, j + 1);
-            try {
-                const parsed = JSON.parse(candidate);
-                if (parsed !== null &&
-                    typeof parsed === 'object' &&
-                    !Array.isArray(parsed) &&
-                    'confidence' in parsed) {
-                    candidates.push(parsed);
-                }
-            }
-            catch {
-                // Not valid JSON — skip
-            }
-        }
-        i = start + 1;
-    }
-    if (candidates.length === 0)
-        return null;
-    // Return the last valid envelope (handles duplicate/regenerated envelopes)
-    return candidates[candidates.length - 1] ?? null;
-}
 /**
  * Clamp a number to [0, 1].
  */
@@ -119,7 +59,7 @@ export function assess(output) {
     }
     let envelope;
     try {
-        envelope = extractEnvelope(output);
+        envelope = lastJsonObjectWithKey(output, 'confidence');
     }
     catch {
         return NULL_RESULT;

package/dist/core/assess.js.map

@@ -1 +1 @@
-{"version":3,"file":"assess.js","sourceRoot":"","sources":["../../src/core/assess.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"assess.js","sourceRoot":"","sources":["../../src/core/assess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAa3D,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;GAEG;AACH,SAAS,OAAO,CAAC,CAAS;IACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,CAAU;IAC5B,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACrC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,CAAC;IAC5D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc;IACnC,MAAM,WAAW,GAAe;QAC9B,UAAU,EAAE,IAAI;QAChB,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,wBAAwB;QAChC,WAAW,EAAE,KAAK;KACnB,CAAC;IAEF,kCAAkC;IAClC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,QAA4B,CAAC;IACjC,IAAI,CAAC;QACH,QAAQ,GAAG,qBAAqB,CAAC,MAAM,EAAE,YAAY,CAAuB,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,+CAA+C;IAC/C,IAAI,OAAO,QAAQ,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9E,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACtD,MAAM,MAAM,GACV,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACtE,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;QACxB,CAAC,CAAC,0BAA0B,CAAC;IAEjC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACvD,CAAC"}

package/dist/core/budget.d.ts

@@ -0,0 +1,26 @@
+/**
+ * src/core/budget.ts — pure per-task cost budget helpers.
+ *
+ * Purity rules (enforced by test/arch/guards.test.ts):
+ *  - No imports of fs / path / child_process
+ *  - No console.* calls
+ *  - No Date.now() / Math.random() / new Date()
+ *  - No process.exit()
+ */
+/**
+ * Returns `true` when `spentUsd` has reached or exceeded the budget cap, so
+ * that orchestrate() must stop spending.
+ *
+ * Returns `false` (no cap) when:
+ *  - `maxCostUsd` is `null` or `undefined`
+ *  - `maxCostUsd` is ≤ 0 (non-positive cap is treated as "uncapped")
+ */
+export declare function budgetExceeded(spentUsd: number, maxCostUsd: number | null | undefined): boolean;
+/**
+ * Returns how many USD remain in the budget, or `null` when uncapped.
+ *
+ * The returned value may be zero or negative if the cap has already been
+ * reached; callers should use {@link budgetExceeded} to make gate decisions
+ * rather than checking the sign here.
+ */
+export declare function remainingBudget(spentUsd: number, maxCostUsd: number | null | undefined): number | null;

package/dist/core/budget.js

@@ -0,0 +1,37 @@
+/**
+ * src/core/budget.ts — pure per-task cost budget helpers.
+ *
+ * Purity rules (enforced by test/arch/guards.test.ts):
+ *  - No imports of fs / path / child_process
+ *  - No console.* calls
+ *  - No Date.now() / Math.random() / new Date()
+ *  - No process.exit()
+ */
+/**
+ * Returns `true` when `spentUsd` has reached or exceeded the budget cap, so
+ * that orchestrate() must stop spending.
+ *
+ * Returns `false` (no cap) when:
+ *  - `maxCostUsd` is `null` or `undefined`
+ *  - `maxCostUsd` is ≤ 0 (non-positive cap is treated as "uncapped")
+ */
+export function budgetExceeded(spentUsd, maxCostUsd) {
+    if (maxCostUsd === null || maxCostUsd === undefined || maxCostUsd <= 0) {
+        return false;
+    }
+    return spentUsd >= maxCostUsd;
+}
+/**
+ * Returns how many USD remain in the budget, or `null` when uncapped.
+ *
+ * The returned value may be zero or negative if the cap has already been
+ * reached; callers should use {@link budgetExceeded} to make gate decisions
+ * rather than checking the sign here.
+ */
+export function remainingBudget(spentUsd, maxCostUsd) {
+    if (maxCostUsd === null || maxCostUsd === undefined || maxCostUsd <= 0) {
+        return null;
+    }
+    return maxCostUsd - spentUsd;
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/core/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,UAAqC;IAErC,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACvE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,QAAQ,IAAI,UAAU,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,UAAqC;IAErC,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,UAAU,GAAG,QAAQ,CAAC;AAC/B,CAAC"}

package/dist/core/history.d.ts

@@ -0,0 +1,35 @@
+/**
+ * src/core/history.ts — compact prior conversation history for context injection.
+ *
+ * Produces a bounded, human-readable summary of prior SessionEntry turns to be
+ * injected into the next provider prompt, giving stateless one-shot providers
+ * (claude -p / codex exec) awareness of earlier conversation context.
+ *
+ * Purity rules (enforced by test/arch/guards.test.ts):
+ *  - No imports of fs / path / child_process
+ *  - No console.* calls
+ *  - No Date.now() / Math.random() / new Date()
+ *  - No process.exit()
+ */
+import type { SessionEntry } from './types.js';
+export interface CompactHistoryOptions {
+    /** Maximum total characters in the returned string. Default: 6000. */
+    readonly maxChars?: number;
+    /** Maximum number of conversation turns to include. Default: 12. */
+    readonly maxTurns?: number;
+}
+/**
+ * Compact prior conversation history into a bounded string for context injection.
+ *
+ * - Takes the MOST RECENT up-to-`maxTurns` entries (preserves chronological order).
+ * - Strips confidence-envelope JSON from assistant turns before including them.
+ * - Enforces `maxChars` by dropping the OLDEST included turns first until under budget.
+ * - If a single turn's content alone exceeds `maxChars`, truncates it with a marker.
+ * - Returns '' for empty / undefined input.
+ *
+ * Pure: no I/O, no Date, no Math.random. Never throws.
+ *
+ * @param entries - The prior conversation entries (oldest first).
+ * @param opts    - Optional bounds overrides.
+ */
+export declare function compactHistory(entries: readonly SessionEntry[], opts?: CompactHistoryOptions): string;

package/dist/core/history.js

@@ -0,0 +1,116 @@
+/**
+ * src/core/history.ts — compact prior conversation history for context injection.
+ *
+ * Produces a bounded, human-readable summary of prior SessionEntry turns to be
+ * injected into the next provider prompt, giving stateless one-shot providers
+ * (claude -p / codex exec) awareness of earlier conversation context.
+ *
+ * Purity rules (enforced by test/arch/guards.test.ts):
+ *  - No imports of fs / path / child_process
+ *  - No console.* calls
+ *  - No Date.now() / Math.random() / new Date()
+ *  - No process.exit()
+ */
+import { lastJsonObjectBoundsWithKey } from './json-envelope.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_CHARS = 6000;
+const DEFAULT_MAX_TURNS = 12;
+const TRUNCATION_MARKER = ' …[truncated]';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Strip any trailing confidence-envelope JSON block from an assistant's content.
+ *
+ * The envelope is a trailing `{ ... }` object that contains `"confidence"`.
+ * Uses {@link lastJsonObjectBoundsWithKey} to locate the last such block, then
+ * removes it (and surrounding whitespace) from the content.
+ *
+ * Never throws — returns the original content on any parse failure.
+ */
+function stripEnvelope(content) {
+    try {
+        const match = lastJsonObjectBoundsWithKey(content, 'confidence');
+        if (match === null) {
+            return content;
+        }
+        // Remove the envelope and any leading whitespace/newline before it
+        const before = content.slice(0, match.start).replace(/\s+$/, '');
+        const after = content.slice(match.end).replace(/^\s+/, '');
+        return after.length > 0 ? `${before}\n${after}` : before;
+    }
+    catch {
+        return content;
+    }
+}
+/**
+ * Map a SessionEntry role to the display label used in the history block.
+ */
+function roleLabel(role) {
+    if (role === 'user')
+        return 'User';
+    if (role === 'assistant')
+        return 'Assistant';
+    return 'System';
+}
+/**
+ * Compact prior conversation history into a bounded string for context injection.
+ *
+ * - Takes the MOST RECENT up-to-`maxTurns` entries (preserves chronological order).
+ * - Strips confidence-envelope JSON from assistant turns before including them.
+ * - Enforces `maxChars` by dropping the OLDEST included turns first until under budget.
+ * - If a single turn's content alone exceeds `maxChars`, truncates it with a marker.
+ * - Returns '' for empty / undefined input.
+ *
+ * Pure: no I/O, no Date, no Math.random. Never throws.
+ *
+ * @param entries - The prior conversation entries (oldest first).
+ * @param opts    - Optional bounds overrides.
+ */
+export function compactHistory(entries, opts) {
+    try {
+        if (!Array.isArray(entries) || entries.length === 0) {
+            return '';
+        }
+        const maxChars = opts?.maxChars ?? DEFAULT_MAX_CHARS;
+        const maxTurns = opts?.maxTurns ?? DEFAULT_MAX_TURNS;
+        // Take the most recent up-to-maxTurns entries, then keep chronological order
+        const window = entries.slice(-maxTurns);
+        // Format each entry into a display line
+        const formatted = window.map((entry) => {
+            const label = roleLabel(entry.role);
+            const rawContent = entry.role === 'assistant' ? stripEnvelope(entry.content) : entry.content;
+            const content = rawContent.trim();
+            return `${label}: ${content}`;
+        });
+        // Enforce maxChars by dropping oldest turns first
+        // Each formatted turn is separated by '\n\n'
+        let kept = formatted.slice(); // copy so we can mutate
+        while (kept.length > 0) {
+            const joined = kept.join('\n\n');
+            if (joined.length <= maxChars) {
+                return joined;
+            }
+            // Drop the oldest turn
+            kept = kept.slice(1);
+        }
+        // If we get here, even a single turn is too long — truncate it
+        if (formatted.length > 0) {
+            const last = formatted[formatted.length - 1];
+            if (last !== undefined && last.length > maxChars) {
+                const truncated = last.slice(0, maxChars - TRUNCATION_MARKER.length) + TRUNCATION_MARKER;
+                return truncated;
+            }
+            if (last !== undefined) {
+                return last;
+            }
+        }
+        return '';
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=history.js.map

package/dist/core/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/core/history.ts"],"names":[],"mappings":"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"}