@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.2

package/dist/engine/friendly-error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Map a raw error into a user-friendly message with a concrete next step
+ * (TODO 3.4). The turn loop emits `{type:"error", error}` to the UI; routing
+ * the message through here turns opaque provider strings ("401", "ETIMEDOUT")
+ * into something a user can act on. Pure + testable — no I/O.
+ *
+ * Heuristic, message-pattern based: we don't have typed error codes from every
+ * provider, so we match on substrings. Unknown errors pass through unchanged
+ * (with no suggestion) rather than getting a misleading canned message.
+ */
+export interface FriendlyError {
+    message: string;
+    /** A concrete next step, or undefined when we have nothing useful to add. */
+    suggestion?: string;
+}
+export declare function friendlyError(err: unknown): FriendlyError;
+/** One-line form: "<message> (<suggestion>)" — what the UI shows. */
+export declare function formatFriendlyError(err: unknown): string;

package/dist/engine/friendly-error.js

@@ -0,0 +1,63 @@
+/**
+ * Map a raw error into a user-friendly message with a concrete next step
+ * (TODO 3.4). The turn loop emits `{type:"error", error}` to the UI; routing
+ * the message through here turns opaque provider strings ("401", "ETIMEDOUT")
+ * into something a user can act on. Pure + testable — no I/O.
+ *
+ * Heuristic, message-pattern based: we don't have typed error codes from every
+ * provider, so we match on substrings. Unknown errors pass through unchanged
+ * (with no suggestion) rather than getting a misleading canned message.
+ */
+const RULES = [
+    {
+        test: /\b(401|403|invalid api key|unauthorized|authentication)\b/i,
+        message: () => "Authentication failed — the API key was rejected.",
+        suggestion: "Check the provider's apiKey/authCommand in settings (run /login to reconfigure), then retry.",
+    },
+    {
+        test: /\b(429|rate.?limit|too many requests)\b/i,
+        message: () => "Rate limited by the provider.",
+        suggestion: "Wait a moment and retry, lower request frequency, or switch to a model with more headroom.",
+    },
+    {
+        test: /\b(timed? ?out|etimedout|esockettimedout|deadline)\b/i,
+        suggestion: "The request timed out — check your network, then retry. Long tasks can run in the background (run_in_background).",
+    },
+    {
+        test: /\b(econnrefused|enotfound|econnreset|network|fetch failed|socket hang up)\b/i,
+        message: () => "Network error reaching the provider.",
+        suggestion: "Check your connection and the provider baseUrl, then retry. Transient errors are retried automatically.",
+    },
+    {
+        test: /\bcontext (limit|length|window)|too long|maximum context|prompt is too long\b/i,
+        message: () => "The conversation exceeded the model's context window.",
+        suggestion: "Start a new session, /compact the history, or switch to a model with a larger context window.",
+    },
+    {
+        test: /\b(insufficient_quota|quota|billing|payment|credit)\b/i,
+        message: () => "The provider rejected the request for billing/quota reasons.",
+        suggestion: "Check the provider account's quota/billing, then retry.",
+    },
+    {
+        test: /\b(500|502|503|504|overloaded|server error|service unavailable)\b/i,
+        message: () => "The provider had a server-side error.",
+        suggestion: "This is usually transient — retry shortly, or switch models if it persists.",
+    },
+];
+export function friendlyError(err) {
+    const raw = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
+    for (const rule of RULES) {
+        if (rule.test.test(raw)) {
+            return {
+                message: rule.message ? rule.message(raw) : raw,
+                suggestion: rule.suggestion,
+            };
+        }
+    }
+    return { message: raw };
+}
+/** One-line form: "<message> (<suggestion>)" — what the UI shows. */
+export function formatFriendlyError(err) {
+    const f = friendlyError(err);
+    return f.suggestion ? `${f.message}\n→ ${f.suggestion}` : f.message;
+}

package/dist/engine/goal.d.ts

@@ -17,13 +17,158 @@ export interface GoalConfig {
     tokenBudget?: number;
     /** Hard cap on wall-clock duration of the whole goal run, in ms. */
     timeBudgetMs?: number;
+    /**
+     * Hard cap on total turns for this goal run. When set, it overrides the
+     * engine's interactive maxTurns default — a goal ("keep going until done")
+     * routinely needs more turns than a single interactive prompt, and the
+     * stop-hook keeps re-blocking completion, so the 100-turn interactive
+     * ceiling would silently truncate a long unattended goal. Drops
+     * non-positive values to "no override". See GOAL_DEFAULT_MAX_TURNS for the
+     * fallback applied when a goal is active but no explicit cap was given.
+     */
+    maxTurns?: number;
+    /**
+     * Max CONSECUTIVE times the on_stop judge may block termination before the
+     * loop forces a stop (the "stuck on an unsatisfiable goal" backstop). A goal
+     * that keeps legitimately making progress resets this every accepted turn, so
+     * this only bites when the judge re-blocks over and over with no completion.
+     * Overrides GOAL_DEFAULT_MAX_STOP_BLOCKS. Non-positive values are dropped.
+     */
+    maxStopBlocks?: number;
+    /**
+     * Epoch-ms timestamp of when the user last set/replaced this goal. The judge
+     * uses it to anchor RELATIVE deadlines written in the objective ("做到3点"、
+     * "until 15:00"): a bare "3点" is read as the first such time AFTER the goal
+     * was set, not after "now" — otherwise, once the clock passes the deadline,
+     * the judge could misread it as tomorrow's 3点 and never stop. Stamped at the
+     * override site (Engine), preserved through normalize so a resumed/inherited
+     * goal keeps its original anchor. Absent for goals created before this field
+     * existed → the judge falls back to reasoning from current time alone.
+     */
+    setAtMs?: number;
 }
+/**
+ * Default consecutive-stop-block cap for goal runs. The real safety net for an
+ * unattended goal is the token/time budget + maxTurns; this cap only stops a
+ * goal that the judge keeps re-blocking with NO progress between blocks. 8 was
+ * too tight — a complex goal can legitimately get "not yet" several times while
+ * advancing — so we allow a generous streak before declaring it stuck.
+ */
+export declare const GOAL_DEFAULT_MAX_STOP_BLOCKS = 25;
+/**
+ * Consecutive-stop-block cap for NON-goal (interactive) runs. The 25-block goal
+ * default is far too loose for a plain interactive session: a plugin `on_stop`
+ * hook that keeps returning continueSession would loop 25× before the backstop
+ * bites (~3× the model calls). Non-goal runs fall back to this tighter cap —
+ * the historical value before the goal feature raised the goal-mode default.
+ */
+export declare const INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS = 8;
+/**
+ * Resolve the consecutive-stop-block cap for a run. Precedence:
+ *   1. explicit `configMaxStopBlocks` (engine/caller override)
+ *   2. `goal.maxStopBlocks`
+ *   3. GOAL_DEFAULT_MAX_STOP_BLOCKS when a goal is active,
+ *      INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS otherwise (don't leak the loose goal
+ *      cap onto plain interactive runs — see B3 in the redesign doc).
+ * Pure + injectable so engine and tests agree.
+ */
+export declare function resolveMaxStopBlocks(configMaxStopBlocks: number | undefined, goal: GoalConfig | undefined): number;
+/**
+ * Turn ceiling applied when a goal is active and neither the GoalConfig nor
+ * the engine config set an explicit maxTurns. Higher than the interactive
+ * default (100) because goal runs are unattended and the stop-hook keeps the
+ * loop going until the objective is met — the real safety backstops are the
+ * token/time budgets and maxStopBlocks, not this ceiling. A round 300 gives
+ * long goals room while still bounding a pathological loop.
+ */
+export declare const GOAL_DEFAULT_MAX_TURNS = 300;
 /**
  * Coerce a raw goal input into a normalized GoalConfig, or undefined when
  * there is effectively no goal (empty objective). Drops non-positive
  * budgets (0 / negative → "no limit", same as absent).
  */
 export declare function normalizeGoal(raw: string | GoalConfig | undefined): GoalConfig | undefined;
+/**
+ * Decide the goal-set timestamp (setAtMs) to persist when a send supplies an
+ * explicit goal. Pure so the engine and tests agree on the anchor rule:
+ *   - A NEW or CHANGED objective → stamp `nowMs` (the user just expressed a
+ *     fresh goal; any relative deadline in it is anchored to now).
+ *   - The SAME objective continuing (bare re-send inheriting the stored goal) →
+ *     keep the stored anchor, so a re-send doesn't silently move the deadline.
+ *     Falls back to `nowMs` if the stored goal predates this field.
+ * `stored` is the previously-persisted active goal (or undefined for the first
+ * goal on a session).
+ */
+export declare function resolveGoalSetAt(explicitObjective: string, stored: GoalConfig | undefined, nowMs: number): number;
+/** Interactive (no-goal) turn ceiling — a single prompt rarely needs more. */
+export declare const INTERACTIVE_DEFAULT_MAX_TURNS = 100;
+/**
+ * Resolve the turn ceiling for a run, honoring goal mode.
+ *
+ * Precedence (first defined wins):
+ *   1. `configMaxTurns` — an explicit engine/caller override (always wins).
+ *   2. `goal.maxTurns`  — a per-goal cap from the GoalConfig.
+ *   3. `GOAL_DEFAULT_MAX_TURNS` when a goal is active (raise the unattended
+ *      ceiling above the interactive default).
+ *   4. `INTERACTIVE_DEFAULT_MAX_TURNS` otherwise.
+ *
+ * Pure + injectable so the engine and tests agree on the rule.
+ */
+export declare function resolveMaxTurns(configMaxTurns: number | undefined, goal: GoalConfig | undefined): number;
+/**
+ * How close a run is to either hard ceiling. Both maxTurns and maxStopBlocks
+ * can force-stop a goal, so the "approaching limit" UX must watch BOTH — the
+ * old code only watched maxTurns (turnsRemaining===2), but a re-blocked goal
+ * almost always hits the much-tighter stop-block cap first. See redesign doc.
+ */
+export interface LimitProximity {
+    /** Turns left before maxTurns (maxTurns - turnCount). */
+    turnsRemaining: number;
+    /** Consecutive blocks left before maxStopBlocks (cap - stopBlockCount). */
+    stopBlocksRemaining: number;
+    /** True when EITHER dimension is within its approach threshold. */
+    approaching: boolean;
+    /** Which ceiling is closest — drives UI copy and the extend default. */
+    nearest: "turns" | "stopBlocks";
+}
+/** Warn when this many turns (or fewer) remain before maxTurns. */
+export declare const APPROACH_TURNS = 5;
+/** Warn when this many consecutive blocks (or fewer) remain before the cap. */
+export declare const APPROACH_STOP_BLOCKS = 3;
+/**
+ * Compute proximity to the two stop ceilings. Pure so turn-loop and tests
+ * agree. `nearest` favors stopBlocks when both are near, because the stop-block
+ * cap (default 25) is reached far sooner than maxTurns (default 300) for a
+ * goal the judge keeps re-blocking — it's the limit that actually bites.
+ */
+export declare function limitProximity(turnCount: number, maxTurns: number, stopBlockCount: number, maxStopBlocks: number): LimitProximity;
+export interface GoalExtension {
+    addTurns?: number;
+    addTokenBudget?: number;
+    addTimeBudgetMs?: number;
+    /** Raise the consecutive-stop-block cap — the limit that usually bites. */
+    addStopBlocks?: number;
+}
+/**
+ * Compute the new turn ceiling + goal budgets after a mid-run extension
+ * (TODO 3.1). Pure so the TurnLoop and tests agree on the arithmetic:
+ *   - addTurns bumps the maxTurns ceiling (floored, positive only).
+ *   - addTokenBudget/addTimeBudgetMs raise the goal's caps. When a cap was
+ *     previously unset ("unlimited"), we seed it from CURRENT USAGE before
+ *     adding — `tokensUsed` for tokens, `elapsedMs` for time — so extending an
+ *     unbounded run sets a fresh cap ABOVE current usage rather than below it.
+ *     (Seeding time from 0 was bug B1: a long-running unbounded goal would get
+ *     a cap below its elapsed time and force-stop immediately on extend.)
+ *   - addStopBlocks is handled by the caller (TurnLoop.extend) against the live
+ *     config, not here, since it isn't part of the goal budget shape.
+ * `tokensUsed`/`elapsedMs` are the tracker's running totals (used only to seed
+ * unset caps). Returns the resulting limits; never mutates its inputs.
+ */
+export declare function applyGoalExtension(currentMaxTurns: number, goal: GoalConfig | undefined, tokensUsed: number, elapsedMs: number, ext: GoalExtension): {
+    maxTurns: number;
+    tokenBudget?: number;
+    timeBudgetMs?: number;
+};
 export interface GoalBudgetTracker {
     goal: GoalConfig;
     /** Wall-clock start (ms epoch), captured at run start. */

package/dist/engine/goal.js

@@ -10,6 +10,48 @@
  * it accumulates total tokens across turns and stamps a wall-clock start,
  * so an unattended goal run can't burn tokens or wall time without bound.
  */
+/**
+ * Default consecutive-stop-block cap for goal runs. The real safety net for an
+ * unattended goal is the token/time budget + maxTurns; this cap only stops a
+ * goal that the judge keeps re-blocking with NO progress between blocks. 8 was
+ * too tight — a complex goal can legitimately get "not yet" several times while
+ * advancing — so we allow a generous streak before declaring it stuck.
+ */
+export const GOAL_DEFAULT_MAX_STOP_BLOCKS = 25;
+/**
+ * Consecutive-stop-block cap for NON-goal (interactive) runs. The 25-block goal
+ * default is far too loose for a plain interactive session: a plugin `on_stop`
+ * hook that keeps returning continueSession would loop 25× before the backstop
+ * bites (~3× the model calls). Non-goal runs fall back to this tighter cap —
+ * the historical value before the goal feature raised the goal-mode default.
+ */
+export const INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS = 8;
+/**
+ * Resolve the consecutive-stop-block cap for a run. Precedence:
+ *   1. explicit `configMaxStopBlocks` (engine/caller override)
+ *   2. `goal.maxStopBlocks`
+ *   3. GOAL_DEFAULT_MAX_STOP_BLOCKS when a goal is active,
+ *      INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS otherwise (don't leak the loose goal
+ *      cap onto plain interactive runs — see B3 in the redesign doc).
+ * Pure + injectable so engine and tests agree.
+ */
+export function resolveMaxStopBlocks(configMaxStopBlocks, goal) {
+    if (typeof configMaxStopBlocks === "number" && configMaxStopBlocks > 0) {
+        return Math.floor(configMaxStopBlocks);
+    }
+    if (goal?.maxStopBlocks && goal.maxStopBlocks > 0)
+        return goal.maxStopBlocks;
+    return goal ? GOAL_DEFAULT_MAX_STOP_BLOCKS : INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS;
+}
+/**
+ * Turn ceiling applied when a goal is active and neither the GoalConfig nor
+ * the engine config set an explicit maxTurns. Higher than the interactive
+ * default (100) because goal runs are unattended and the stop-hook keeps the
+ * loop going until the objective is met — the real safety backstops are the
+ * token/time budgets and maxStopBlocks, not this ceiling. A round 300 gives
+ * long goals room while still bounding a pathological loop.
+ */
+export const GOAL_DEFAULT_MAX_TURNS = 300;
 /**
  * Coerce a raw goal input into a normalized GoalConfig, or undefined when
  * there is effectively no goal (empty objective). Drops non-positive
@@ -27,8 +69,110 @@ export function normalizeGoal(raw) {
         out.tokenBudget = obj.tokenBudget;
     if (typeof obj.timeBudgetMs === "number" && obj.timeBudgetMs > 0)
         out.timeBudgetMs = obj.timeBudgetMs;
+    if (typeof obj.maxTurns === "number" && obj.maxTurns > 0)
+        out.maxTurns = Math.floor(obj.maxTurns);
+    if (typeof obj.maxStopBlocks === "number" && obj.maxStopBlocks > 0) {
+        out.maxStopBlocks = Math.floor(obj.maxStopBlocks);
+    }
+    // Preserve a positive goal-set timestamp so a resumed/inherited goal keeps
+    // the anchor for relative deadlines. Non-positive/junk is dropped, matching
+    // the budget fields (a bogus anchor is worse than none).
+    if (typeof obj.setAtMs === "number" && obj.setAtMs > 0)
+        out.setAtMs = obj.setAtMs;
     return out;
 }
+/**
+ * Decide the goal-set timestamp (setAtMs) to persist when a send supplies an
+ * explicit goal. Pure so the engine and tests agree on the anchor rule:
+ *   - A NEW or CHANGED objective → stamp `nowMs` (the user just expressed a
+ *     fresh goal; any relative deadline in it is anchored to now).
+ *   - The SAME objective continuing (bare re-send inheriting the stored goal) →
+ *     keep the stored anchor, so a re-send doesn't silently move the deadline.
+ *     Falls back to `nowMs` if the stored goal predates this field.
+ * `stored` is the previously-persisted active goal (or undefined for the first
+ * goal on a session).
+ */
+export function resolveGoalSetAt(explicitObjective, stored, nowMs) {
+    const sameGoalContinues = !!stored && stored.objective === explicitObjective;
+    return sameGoalContinues ? stored.setAtMs ?? nowMs : nowMs;
+}
+/** Interactive (no-goal) turn ceiling — a single prompt rarely needs more. */
+export const INTERACTIVE_DEFAULT_MAX_TURNS = 100;
+/**
+ * Resolve the turn ceiling for a run, honoring goal mode.
+ *
+ * Precedence (first defined wins):
+ *   1. `configMaxTurns` — an explicit engine/caller override (always wins).
+ *   2. `goal.maxTurns`  — a per-goal cap from the GoalConfig.
+ *   3. `GOAL_DEFAULT_MAX_TURNS` when a goal is active (raise the unattended
+ *      ceiling above the interactive default).
+ *   4. `INTERACTIVE_DEFAULT_MAX_TURNS` otherwise.
+ *
+ * Pure + injectable so the engine and tests agree on the rule.
+ */
+export function resolveMaxTurns(configMaxTurns, goal) {
+    if (typeof configMaxTurns === "number" && configMaxTurns > 0)
+        return configMaxTurns;
+    if (goal)
+        return goal.maxTurns ?? GOAL_DEFAULT_MAX_TURNS;
+    return INTERACTIVE_DEFAULT_MAX_TURNS;
+}
+/** Warn when this many turns (or fewer) remain before maxTurns. */
+export const APPROACH_TURNS = 5;
+/** Warn when this many consecutive blocks (or fewer) remain before the cap. */
+export const APPROACH_STOP_BLOCKS = 3;
+/**
+ * Compute proximity to the two stop ceilings. Pure so turn-loop and tests
+ * agree. `nearest` favors stopBlocks when both are near, because the stop-block
+ * cap (default 25) is reached far sooner than maxTurns (default 300) for a
+ * goal the judge keeps re-blocking — it's the limit that actually bites.
+ */
+export function limitProximity(turnCount, maxTurns, stopBlockCount, maxStopBlocks) {
+    const turnsRemaining = maxTurns - turnCount;
+    const stopBlocksRemaining = maxStopBlocks - stopBlockCount;
+    const turnsNear = turnsRemaining <= APPROACH_TURNS;
+    const blocksNear = stopBlocksRemaining <= APPROACH_STOP_BLOCKS;
+    return {
+        turnsRemaining,
+        stopBlocksRemaining,
+        approaching: turnsNear || blocksNear,
+        nearest: blocksNear ? "stopBlocks" : "turns",
+    };
+}
+/**
+ * Compute the new turn ceiling + goal budgets after a mid-run extension
+ * (TODO 3.1). Pure so the TurnLoop and tests agree on the arithmetic:
+ *   - addTurns bumps the maxTurns ceiling (floored, positive only).
+ *   - addTokenBudget/addTimeBudgetMs raise the goal's caps. When a cap was
+ *     previously unset ("unlimited"), we seed it from CURRENT USAGE before
+ *     adding — `tokensUsed` for tokens, `elapsedMs` for time — so extending an
+ *     unbounded run sets a fresh cap ABOVE current usage rather than below it.
+ *     (Seeding time from 0 was bug B1: a long-running unbounded goal would get
+ *     a cap below its elapsed time and force-stop immediately on extend.)
+ *   - addStopBlocks is handled by the caller (TurnLoop.extend) against the live
+ *     config, not here, since it isn't part of the goal budget shape.
+ * `tokensUsed`/`elapsedMs` are the tracker's running totals (used only to seed
+ * unset caps). Returns the resulting limits; never mutates its inputs.
+ */
+export function applyGoalExtension(currentMaxTurns, goal, tokensUsed, elapsedMs, ext) {
+    let maxTurns = currentMaxTurns;
+    if (typeof ext.addTurns === "number" && ext.addTurns > 0) {
+        maxTurns += Math.floor(ext.addTurns);
+    }
+    let tokenBudget = goal?.tokenBudget;
+    let timeBudgetMs = goal?.timeBudgetMs;
+    if (goal) {
+        if (typeof ext.addTokenBudget === "number" && ext.addTokenBudget > 0) {
+            tokenBudget = (tokenBudget ?? tokensUsed) + Math.floor(ext.addTokenBudget);
+        }
+        if (typeof ext.addTimeBudgetMs === "number" && ext.addTimeBudgetMs > 0) {
+            // Seed an unset cap from elapsed time (not 0), mirroring the token branch,
+            // so the new cap lands above current usage. Fixes B1.
+            timeBudgetMs = (timeBudgetMs ?? elapsedMs) + Math.floor(ext.addTimeBudgetMs);
+        }
+    }
+    return { maxTurns, tokenBudget, timeBudgetMs };
+}
 /** Create a run-scoped tracker. `nowMs` is injected for testability. */
 export function createGoalBudgetTracker(goal, nowMs) {
     return { goal, startedAtMs: nowMs, tokensUsed: 0 };

package/dist/engine/image-policy.d.ts

@@ -150,3 +150,16 @@ export interface DropOversizedResult {
 }
 export declare function dropOversizedImages(images: readonly ParsedImage[]): DropOversizedResult;
 export declare function enforceImagePolicy(images: readonly ParsedImage[]): ImagePolicyVerdict;
+/**
+ * Collect the workspace file paths of any attached images that came from a
+ * real file (the desktop composer's path-attach flow sets ParsedImage.name to
+ * the absolute path). Pasted screenshots whose name is a bare filename, or any
+ * name that doesn't resolve to an existing file, are excluded.
+ *
+ * Pure given an `exists` predicate + `resolve` joiner, so it's unit-testable
+ * without touching the real fs. The engine passes `existsSync` and a
+ * cwd-aware joiner; downstream this surfaces the paths to the model so tools
+ * like GenerateImage(referenceImages) can use them (the path the composer
+ * already knew was otherwise dropped on the way to the LLM).
+ */
+export declare function collectAttachedImagePaths(images: ReadonlyArray<ParsedImage>, resolve: (name: string) => string, exists: (absPath: string) => boolean): string[];

package/dist/engine/image-policy.js

@@ -163,3 +163,27 @@ export function enforceImagePolicy(images) {
     }
     return { ok: true };
 }
+/**
+ * Collect the workspace file paths of any attached images that came from a
+ * real file (the desktop composer's path-attach flow sets ParsedImage.name to
+ * the absolute path). Pasted screenshots whose name is a bare filename, or any
+ * name that doesn't resolve to an existing file, are excluded.
+ *
+ * Pure given an `exists` predicate + `resolve` joiner, so it's unit-testable
+ * without touching the real fs. The engine passes `existsSync` and a
+ * cwd-aware joiner; downstream this surfaces the paths to the model so tools
+ * like GenerateImage(referenceImages) can use them (the path the composer
+ * already knew was otherwise dropped on the way to the LLM).
+ */
+export function collectAttachedImagePaths(images, resolve, exists) {
+    const out = [];
+    for (const img of images) {
+        const name = img.name?.trim();
+        if (!name)
+            continue;
+        const abs = resolve(name);
+        if (exists(abs))
+            out.push(abs);
+    }
+    return out;
+}

package/dist/engine/model-connections-pool.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bridge settings.modelConnections[] (the unified instance store) into
+ * ModelPool entries, so the engine sends requests using the new catalog-driven
+ * model selection. Pure: instances + catalog → ModelEntry[]. apiKeyRef is
+ * dereferenced via resolveInstance; protocol/baseUrl/token limits come from the
+ * resolved catalog entry + preset.
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §6.
+ */
+import { type ModelInstance, type Credential } from "../model-catalog/resolve.js";
+import type { CatalogEntry } from "../model-catalog/index.js";
+import type { ModelEntry } from "../llm/model-pool.js";
+export type { ModelInstance, Credential } from "../model-catalog/resolve.js";
+/**
+ * Convert text model connections into ModelPool register entries. Non-text
+ * instances and ones whose catalogId doesn't resolve are skipped.
+ */
+export declare function modelEntriesFromConnections(connections: ModelInstance[], credentials: Credential[], catalog: CatalogEntry[]): ModelEntry[];

package/dist/engine/model-connections-pool.js

@@ -0,0 +1,66 @@
+/**
+ * Bridge settings.modelConnections[] (the unified instance store) into
+ * ModelPool entries, so the engine sends requests using the new catalog-driven
+ * model selection. Pure: instances + catalog → ModelEntry[]. apiKeyRef is
+ * dereferenced via resolveInstance; protocol/baseUrl/token limits come from the
+ * resolved catalog entry + preset.
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §6.
+ */
+import { resolveInstance } from "../model-catalog/resolve.js";
+import { applyParams } from "../model-catalog/params.js";
+/** Map a catalog entry's protocol to the ModelPool `provider` (LLM client). */
+function clientProvider(entry) {
+    return entry.protocol === "anthropic-style" ? "anthropic" : "openai";
+}
+/**
+ * Map a connection's `paramValues.reasoning` to the engine's ReasoningSetting,
+ * so the new param store flows through the existing reasoning request pipeline
+ * (no new request-layer plumbing). enum→effort, number→budget, boolean→on/off.
+ */
+function reasoningFromParamValues(paramValues) {
+    const v = paramValues?.reasoning;
+    if (typeof v === "string") {
+        return { mode: "effort", effort: v };
+    }
+    if (typeof v === "number")
+        return { mode: "budget", budgetTokens: v };
+    if (typeof v === "boolean")
+        return v ? { mode: "on" } : { mode: "off" };
+    return undefined;
+}
+/**
+ * Convert text model connections into ModelPool register entries. Non-text
+ * instances and ones whose catalogId doesn't resolve are skipped.
+ */
+export function modelEntriesFromConnections(connections, credentials, catalog) {
+    const out = [];
+    for (const inst of connections) {
+        if (inst.tag !== "text")
+            continue;
+        const resolved = resolveInstance(inst, credentials, catalog);
+        if (!resolved)
+            continue;
+        const { entry, preset } = resolved;
+        const reasoning = reasoningFromParamValues(inst.paramValues);
+        // Generic param passthrough: map the connection's paramValues to request-body
+        // fields via each ParamSpec's wire.field. Exclude `reasoning` — it rides the
+        // dedicated entry.reasoning path (per-model dynamic translation in the client);
+        // emitting it here too would double-send it.
+        const passthroughParams = (preset?.params ?? []).filter((p) => p.name !== "reasoning");
+        const extraBody = applyParams(inst.paramValues ?? {}, passthroughParams);
+        const e = {
+            key: inst.id,
+            provider: clientProvider(entry),
+            model: resolved.model,
+            baseUrl: resolved.baseUrl,
+            needsKey: resolved.needsKey,
+            ...(resolved.apiKey !== undefined ? { apiKey: resolved.apiKey } : {}),
+            ...(preset?.maxContextTokens !== undefined ? { maxContextTokens: preset.maxContextTokens } : {}),
+            ...(preset?.maxOutputTokens !== undefined ? { maxOutputTokens: preset.maxOutputTokens } : {}),
+            ...(reasoning !== undefined ? { reasoning } : {}),
+            ...(Object.keys(extraBody).length > 0 ? { extraBody } : {}),
+        };
+        out.push(e);
+    }
+    return out;
+}

package/dist/engine/model-facade.d.ts

@@ -4,6 +4,16 @@
 import type { LLMClientBase } from "../llm/client-base.js";
 import type { Message, ToolDefinition, LLMResponse, StreamCallback } from "../types.js";
 import { Transcript } from "../session/transcript.js";
+/**
+ * Prompt-cache hit rate for one request, as CC computes it:
+ *   cacheRead / (cacheRead + cacheCreation + uncachedInput)
+ * where uncachedInput = promptTokens − cacheRead − cacheCreation (promptTokens
+ * already includes the cached portion). Returns undefined when the provider
+ * reported no cache info at all, so `llm.request` only carries the field when
+ * it's meaningful. Makes hit-rate observable in logs — the prerequisite for
+ * any caching tuning (docs/todo/prompt-cache-optimization.md §四 step 1).
+ */
+export declare function cacheHitRate(usage: LLMResponse["usage"]): number | undefined;
 export declare class ModelFacade {
     private readonly client;
     private readonly transcript;

package/dist/engine/model-facade.js

@@ -10,6 +10,29 @@ function nextReqId() {
     _reqSeq += 1;
     return `r${_reqSeq.toString(36)}`;
 }
+/**
+ * Prompt-cache hit rate for one request, as CC computes it:
+ *   cacheRead / (cacheRead + cacheCreation + uncachedInput)
+ * where uncachedInput = promptTokens − cacheRead − cacheCreation (promptTokens
+ * already includes the cached portion). Returns undefined when the provider
+ * reported no cache info at all, so `llm.request` only carries the field when
+ * it's meaningful. Makes hit-rate observable in logs — the prerequisite for
+ * any caching tuning (docs/todo/prompt-cache-optimization.md §四 step 1).
+ */
+export function cacheHitRate(usage) {
+    if (!usage)
+        return undefined;
+    const read = usage.cacheReadTokens ?? 0;
+    const creation = usage.cacheCreationTokens ?? 0;
+    if (read === 0 && creation === 0)
+        return undefined;
+    const prompt = usage.promptTokens ?? 0;
+    const uncached = Math.max(0, prompt - read - creation);
+    const denom = read + creation + uncached;
+    if (denom === 0)
+        return undefined;
+    return read / denom;
+}
 export class ModelFacade {
     client;
     transcript;
@@ -82,6 +105,7 @@ export class ModelFacade {
             toolCalls: response.toolCalls.length,
             textLen: response.text?.length ?? 0,
             usage: response.usage,
+            cacheHitRate: cacheHitRate(response.usage),
         });
         recordLLMResponse(sid, {
             text: response.text,
@@ -135,6 +159,7 @@ export class ModelFacade {
             toolCalls: response.toolCalls.length,
             textLen: response.text?.length ?? 0,
             usage: response.usage,
+            cacheHitRate: cacheHitRate(response.usage),
         });
         recordLLMResponse(sid, {
             text: response.text,

package/dist/engine/patch-orphaned-tools.js

@@ -79,6 +79,9 @@ export function patchOrphanedToolUses(messages) {
             type: "tool_result",
             tool_use_id: id,
             content: SYNTHETIC_ERROR_TEXT,
+            // Flag as an error so the Anthropic provider marks it is_error; otherwise
+            // the model reads the synthetic result as a successful tool output.
+            is_error: true,
         }));
         messages.splice(i + 1, 0, { role: "user", content: errorBlocks });
         // Mark these ids answered so a later assistant message referencing

package/dist/engine/resolve-llm-config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * resolveLLMConfigForTag — 单一入口:settings + tag + 可选偏好实例 id → LLMConfig。
+ * 所有非-engine 的 seed 场景(agent-server bootstrap / automation / dream / TUI
+ * 命令)都调它,避免各自手搓 { provider: settings.model.provider, ... }。
+ *
+ * 复用 modelEntriesFromConnections + 临时 ModelPool.toLLMConfig,与 engine 内部
+ * 长生命周期 pool 共享同一批零件,不逻辑分叉。
+ *
+ * 选择优先级:preferredId(命中才用)→ defaults[tag] → 首个可用连接。
+ * 返回 null = 该 tag 下没有任何可用连接,调用方据此抛明确错误。
+ *
+ * 本次只处理 text;image/video 已有独立 resolver(resolveImageProvider 等)。
+ */
+import type { LLMConfig } from "../types.js";
+import type { ValidatedSettings } from "../settings/schema.js";
+export declare function resolveLLMConfigForTag(settings: ValidatedSettings, tag: "text", preferredInstanceId?: string): LLMConfig | null;