myshell-tools 2.4.0 → 2.6.0

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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"}

package/dist/core/json-envelope.d.ts

@@ -0,0 +1,49 @@
+/**
+ * src/core/json-envelope.ts — shared brace-depth JSON-envelope scanner.
+ *
+ * Provides reusable helpers that scan text for the LAST balanced `{...}` JSON
+ * object containing a given key.  Used by assess.ts (confidence envelope),
+ * review.ts (verdict envelope), and history.ts (envelope stripping) to avoid
+ * duplicated scanning logic.
+ *
+ * Honesty Contract: these functions NEVER throw on any input.  On parse failure
+ * or absent key they return null.  They never fabricate data.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+/**
+ * Scan `text` and return the LAST balanced `{...}` block that:
+ *  1. Parses as valid JSON,
+ *  2. Is a plain object (not null, not an array), and
+ *  3. Contains the given `key` as a direct property.
+ *
+ * Returns `null` when no matching block is found.  Never throws.
+ *
+ * Scanning semantics:
+ *  - All `{` positions are tried left-to-right.
+ *  - For each `{`, the matching `}` is located by tracking brace depth.
+ *  - All candidates that parse and contain `key` are collected; the LAST one
+ *    wins.  This handles duplicate/regenerated envelopes in model output.
+ *
+ * @param text - The text to scan (any string).
+ * @param key  - The property key that must be present in the JSON object.
+ */
+export declare function lastJsonObjectWithKey(text: string, key: string): Record<string, unknown> | null;
+/**
+ * Like {@link lastJsonObjectWithKey}, but also returns the character offsets of
+ * the matched block within `text` so callers can excise it.
+ *
+ * Returns `null` when no matching block is found.  Never throws.
+ *
+ * The returned `start` and `end` follow the same convention as
+ * `String.prototype.slice`: `text.slice(start, end)` reproduces the matched
+ * `{...}` block exactly.
+ *
+ * @param text - The text to scan (any string).
+ * @param key  - The property key that must be present in the JSON object.
+ */
+export declare function lastJsonObjectBoundsWithKey(text: string, key: string): {
+    readonly start: number;
+    readonly end: number;
+    readonly value: Record<string, unknown>;
+} | null;

package/dist/core/json-envelope.js

@@ -0,0 +1,117 @@
+/**
+ * src/core/json-envelope.ts — shared brace-depth JSON-envelope scanner.
+ *
+ * Provides reusable helpers that scan text for the LAST balanced `{...}` JSON
+ * object containing a given key.  Used by assess.ts (confidence envelope),
+ * review.ts (verdict envelope), and history.ts (envelope stripping) to avoid
+ * duplicated scanning logic.
+ *
+ * Honesty Contract: these functions NEVER throw on any input.  On parse failure
+ * or absent key they return null.  They never fabricate data.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+// ---------------------------------------------------------------------------
+// Core scanning loop (private)
+// ---------------------------------------------------------------------------
+/**
+ * Walk `text` left-to-right, collecting every balanced `{...}` block that
+ * parses as a plain JSON object and contains `key`.  Returns the last match
+ * (or null if none found).  Never throws.
+ */
+function scanLast(text, key) {
+    if (typeof text !== 'string' || text.length === 0)
+        return null;
+    let last = null;
+    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) &&
+                    key in parsed) {
+                    last = { start, end: j + 1, value: parsed };
+                }
+            }
+            catch {
+                // Not valid JSON — skip
+            }
+        }
+        i = start + 1;
+    }
+    return last;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Scan `text` and return the LAST balanced `{...}` block that:
+ *  1. Parses as valid JSON,
+ *  2. Is a plain object (not null, not an array), and
+ *  3. Contains the given `key` as a direct property.
+ *
+ * Returns `null` when no matching block is found.  Never throws.
+ *
+ * Scanning semantics:
+ *  - All `{` positions are tried left-to-right.
+ *  - For each `{`, the matching `}` is located by tracking brace depth.
+ *  - All candidates that parse and contain `key` are collected; the LAST one
+ *    wins.  This handles duplicate/regenerated envelopes in model output.
+ *
+ * @param text - The text to scan (any string).
+ * @param key  - The property key that must be present in the JSON object.
+ */
+export function lastJsonObjectWithKey(text, key) {
+    try {
+        const match = scanLast(text, key);
+        return match !== null ? match.value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Like {@link lastJsonObjectWithKey}, but also returns the character offsets of
+ * the matched block within `text` so callers can excise it.
+ *
+ * Returns `null` when no matching block is found.  Never throws.
+ *
+ * The returned `start` and `end` follow the same convention as
+ * `String.prototype.slice`: `text.slice(start, end)` reproduces the matched
+ * `{...}` block exactly.
+ *
+ * @param text - The text to scan (any string).
+ * @param key  - The property key that must be present in the JSON object.
+ */
+export function lastJsonObjectBoundsWithKey(text, key) {
+    try {
+        return scanLast(text, key);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=json-envelope.js.map

package/dist/core/json-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-envelope.js","sourceRoot":"","sources":["../../src/core/json-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;GAIG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,GAAW;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/D,IAAI,IAAI,GAAqB,IAAI,CAAC;IAElC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,MAAM;QAExB,6DAA6D;QAC7D,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,GAAG,KAAK,CAAC;QACd,IAAI,UAAU,GAAG,KAAK,CAAC;QACvB,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACvB,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACpB,KAAK,EAAE,CAAC;YACV,CAAC;iBAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC3B,KAAK,EAAE,CAAC;gBACR,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;oBAChB,UAAU,GAAG,IAAI,CAAC;oBAClB,MAAM;gBACR,CAAC;YACH,CAAC;YACD,CAAC,EAAE,CAAC;QACN,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC;gBACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC9C,IACE,MAAM,KAAK,IAAI;oBACf,OAAO,MAAM,KAAK,QAAQ;oBAC1B,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;oBACtB,GAAG,IAAK,MAAiB,EACzB,CAAC;oBACD,IAAI,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,MAAiC,EAAE,CAAC;gBACzE,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;QACH,CAAC;QAED,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAChB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,GAAW;IAEX,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAClC,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAY,EACZ,GAAW;IAEX,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/core/orchestrate.js

@@ -30,13 +30,32 @@ import { classify } from './classify.js';
 import { route } from './route.js';
 import { buildPrompt } from './prompt.js';
 import { assess } from './assess.js';
+import { compactHistory } from './history.js';
 import { getModelPricing, calculateCost } from '../infra/pricing.js';
 import { nextTierUp, pickReviewer } from './escalate.js';
 import { buildReviewPrompt, parseReviewVerdict } from './review.js';
+import { budgetExceeded } from './budget.js';
 // ---------------------------------------------------------------------------
-// Pure helper: should this IC output be cross-vendor reviewed?
+// Pure helper: should this output be cross-vendor reviewed?
 // ---------------------------------------------------------------------------
-function shouldReview(classification, assessment) {
+/**
+ * Decides whether a cross-vendor review should be triggered, given the task
+ * classification, assessment signals, and the active review policy.
+ *
+ * @param classification - Task classification (tier + risk).
+ * @param assessment     - Model self-assessment (confidence, escalate, needsReview).
+ * @param reviewPolicy   - Policy field; `undefined` is treated as `'auto'` for
+ *                         backward compatibility.
+ */
+function shouldReview(classification, assessment, reviewPolicy) {
+    // 'off' — never auto-review.
+    if (reviewPolicy === 'off')
+        return false;
+    // 'critical-only' — review only when risk is critical.
+    if (reviewPolicy === 'critical-only') {
+        return classification.risk === 'critical';
+    }
+    // 'auto' (or undefined, treated as 'auto') — original behaviour.
     return (classification.risk === 'high' ||
         classification.risk === 'critical' ||
         assessment.needsReview === true);
@@ -103,6 +122,12 @@ export async function* orchestrate(task, deps, signal) {
     let attempts = 0;
     let totalCostUsd = 0;
     let lastOutput = '';
+    // Compute history context once per orchestrate() call (before the loop).
+    // It is injected into the first-tier prompt to give stateless providers
+    // multi-turn context; the history does NOT grow during the loop.
+    const historyContext = deps.history !== undefined && deps.history.length > 0
+        ? compactHistory(deps.history)
+        : undefined;
     /**
      * Track which attempt indices have already been reviewed so that re-runs
      * (e.g. after a revise verdict) are not reviewed a second time and we
@@ -115,7 +140,7 @@ export async function* orchestrate(task, deps, signal) {
     mainLoop: while (attempts < deps.policy.maxAttempts) {
         attempts++;
         // --- Route for current tier ---
-        const decision = route(currentTier, available, deps.policy);
+        const decision = route(currentTier, available, deps.policy, deps.availableModels);
         const provider = deps.providers[decision.provider];
         if (provider === undefined) {
             yield {
@@ -125,10 +150,10 @@ export async function* orchestrate(task, deps, signal) {
             };
             break mainLoop;
         }
-        // --- Build prompt (with optional reviewer feedback on IC retry) ---
+        // --- Build prompt (with optional reviewer feedback on IC retry + history context) ---
         const prompt = currentTier === 'ic' && managerNotes !== undefined
-            ? buildPrompt(currentTier, task, managerNotes)
-            : buildPrompt(currentTier, task);
+            ? buildPrompt(currentTier, task, managerNotes, historyContext)
+            : buildPrompt(currentTier, task, undefined, historyContext);
         // --- Yield tier-start ---
         yield {
             type: 'tier-start',
@@ -262,7 +287,27 @@ export async function* orchestrate(task, deps, signal) {
         //    Guard: each attempt is reviewed at most once (prevents infinite loops).
         //    Guard: skip review if the only available reviewer is the same vendor
         //           (cross-vendor review is required; same-vendor-only → skip).
-        if (shouldReview(classification, assessment) && !reviewedAttempts.has(attempts)) {
+        //    Guard: skip review when budget is exhausted (gating new spend only).
+        if (shouldReview(classification, assessment, deps.policy.reviewPolicy) &&
+            !reviewedAttempts.has(attempts)) {
+            // Budget cap: do not start a review run if we have already spent the cap.
+            if (budgetExceeded(totalCostUsd, deps.policy.maxCostUsd)) {
+                yield {
+                    type: 'notice',
+                    level: 'warn',
+                    message: 'cost budget reached — accepting best result so far',
+                };
+                yield {
+                    type: 'final',
+                    success: true,
+                    output: lastOutput,
+                    tier: currentTier,
+                    totalCostUsd,
+                    sessionId: deps.session.id,
+                    attempts,
+                };
+                return;
+            }
             const reviewerId = pickReviewer(available, decision.provider);
             // Only proceed with a DIFFERENT-vendor reviewer (cross-vendor requirement).
             const reviewerProvider = reviewerId !== null && reviewerId !== decision.provider
@@ -276,7 +321,7 @@ export async function* orchestrate(task, deps, signal) {
                     message: `Review by ${reviewerId} (cross-vendor)`,
                 };
                 // Route reviewer at manager tier
-                const reviewDecision = route('manager', [reviewerId], deps.policy);
+                const reviewDecision = route('manager', [reviewerId], deps.policy, deps.availableModels);
                 const reviewPrompt = buildReviewPrompt(task, lastOutput);
                 // Yield tier-start for review run
                 yield {
@@ -432,6 +477,24 @@ export async function* orchestrate(task, deps, signal) {
                         return;
                     }
                     if (verdict.verdict === 'revise') {
+                        // Budget cap: do not retry current tier if we have spent the cap.
+                        if (budgetExceeded(totalCostUsd, deps.policy.maxCostUsd)) {
+                            yield {
+                                type: 'notice',
+                                level: 'warn',
+                                message: 'cost budget reached — accepting best result so far',
+                            };
+                            yield {
+                                type: 'final',
+                                success: true,
+                                output: lastOutput,
+                                tier: currentTier,
+                                totalCostUsd,
+                                sessionId: deps.session.id,
+                                attempts,
+                            };
+                            return;
+                        }
                         // Retry current tier with reviewer's notes
                         managerNotes = verdict.notes;
                         continue mainLoop;
@@ -439,6 +502,24 @@ export async function* orchestrate(task, deps, signal) {
                     // verdict === 'escalate'
                     const escalateTo = nextTierUp(currentTier);
                     if (escalateTo !== null) {
+                        // Budget cap: do not escalate to a new tier if we have spent the cap.
+                        if (budgetExceeded(totalCostUsd, deps.policy.maxCostUsd)) {
+                            yield {
+                                type: 'notice',
+                                level: 'warn',
+                                message: 'cost budget reached — accepting best result so far',
+                            };
+                            yield {
+                                type: 'final',
+                                success: true,
+                                output: lastOutput,
+                                tier: currentTier,
+                                totalCostUsd,
+                                sessionId: deps.session.id,
+                                attempts,
+                            };
+                            return;
+                        }
                         yield { type: 'escalate', from: currentTier, to: escalateTo, reason: 'reviewer escalation' };
                         currentTier = escalateTo;
                     }
@@ -452,6 +533,24 @@ export async function* orchestrate(task, deps, signal) {
             (assessment.confidence !== null && assessment.confidence < threshold);
         const nextTier = nextTierUp(currentTier);
         if (needEsc && nextTier !== null) {
+            // Budget cap: do not escalate to a new tier if we have spent the cap.
+            if (budgetExceeded(totalCostUsd, deps.policy.maxCostUsd)) {
+                yield {
+                    type: 'notice',
+                    level: 'warn',
+                    message: 'cost budget reached — accepting best result so far',
+                };
+                yield {
+                    type: 'final',
+                    success: true,
+                    output: lastOutput,
+                    tier: currentTier,
+                    totalCostUsd,
+                    sessionId: deps.session.id,
+                    attempts,
+                };
+                return;
+            }
             const escalateReason = assessment.reason !== 'model provided no reason' &&
                 assessment.reason !== 'no confidence envelope'
                 ? assessment.reason