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

package/dist/engine/image-compression.js

@@ -0,0 +1,186 @@
+/**
+ * Engine-side image compression — the fallback for hosts that didn't
+ * pre-compress.
+ *
+ * The desktop renderer already compresses via <canvas> + Blob before
+ * sending; the TUI and MCP image-returning tools historically didn't.
+ * When the {@link enforceImagePolicy} gate would otherwise refuse a
+ * turn for "image too large", we try to bring the offender(s) under
+ * the limit first by:
+ *
+ *   1. Decoding the base64 payload.
+ *   2. Resizing the longest edge down to {@link IMAGE_TARGETS.targetMaxDimension}.
+ *   3. Re-encoding as JPEG at {@link IMAGE_TARGETS.jpegQuality}.
+ *
+ * jimp is the obvious pick — pure-JS, no native binaries, runs in
+ * both Node and Bun, supports PNG / JPEG / WebP input. But shipping
+ * it as a hard `core` dep would balloon the published bundle for
+ * every consumer. So we resolve it dynamically: hosts that want
+ * automatic compression just `npm install jimp`; everyone else gets
+ * the existing "image too large" refusal.
+ *
+ * Hosts can also inject a custom {@link ImageCompressor} via
+ * {@link setEngineImageCompressor} — useful for tests, future
+ * sharp-based compressors, or arena agents with different size
+ * targets.
+ *
+ * The defaults must stay pure-JS so this module is safe to bundle for
+ * Electron preload / browser worker contexts. Anything that needs
+ * native code (e.g. sharp) should be injected explicitly.
+ */
+import { IMAGE_LIMITS, IMAGE_TARGETS, byteLengthFromBase64 } from "./image-policy.js";
+/**
+ * No-op compressor: returns the input unchanged. Used when the host
+ * didn't install jimp and didn't inject anything else, so behavior
+ * stays the same as before this module existed.
+ */
+const NOOP_COMPRESSOR = {
+    async compress(image, _maxBytes) {
+        const bytes = byteLengthFromBase64(image.base64);
+        return {
+            image,
+            compressed: false,
+            originalBytes: bytes,
+            finalBytes: bytes,
+        };
+    },
+};
+let activeCompressor = null;
+/**
+ * Override the engine's active compressor. Pass `null` to clear the
+ * override and fall back to lazy jimp resolution. Hosts that want
+ * deterministic behavior in tests typically call this with a stub.
+ */
+export function setEngineImageCompressor(c) {
+    activeCompressor = c;
+}
+/** Reset state — for tests. */
+export function resetEngineImageCompressor() {
+    activeCompressor = null;
+    cachedJimpCompressor = null;
+}
+let cachedJimpCompressor = null;
+/**
+ * Resolve a jimp-backed compressor on first call. If jimp isn't
+ * installed, cache the no-op and stop retrying.
+ *
+ * jimp's API: `await Jimp.read(buffer)` → resize / quality / getBuffer.
+ * v0.x used CamelCase constants (e.g. `Jimp.MIME_JPEG`); v1 moved to
+ * an explicit string mime arg. We accept both by feature-testing.
+ */
+async function resolveJimpCompressor() {
+    if (cachedJimpCompressor)
+        return cachedJimpCompressor;
+    try {
+        // Dynamic import so consumers without jimp installed don't pay
+        // the bundle cost. The default export shape differs across v0/v1,
+        // hence the `any` cast. The literal module specifier is a string
+        // we resolve at runtime — TS sees no type info for it and would
+        // otherwise error TS2307 when jimp isn't on the host's path.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const dynImport = (s) => 
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval
+        Function("s", "return import(s)")(s);
+        const mod = (await dynImport("jimp"));
+        const Jimp = (mod.default ?? mod.Jimp ?? mod);
+        cachedJimpCompressor = {
+            async compress(image, maxBytes) {
+                const original = Buffer.from(image.base64, "base64");
+                const originalBytes = original.byteLength;
+                if (originalBytes <= maxBytes) {
+                    return { image, compressed: false, originalBytes, finalBytes: originalBytes };
+                }
+                let pic;
+                try {
+                    pic = await Jimp.read(original);
+                }
+                catch {
+                    // Unknown / corrupt format. Leave it alone; the policy gate
+                    // will refuse and surface a meaningful message to the user.
+                    return { image, compressed: false, originalBytes, finalBytes: originalBytes };
+                }
+                // Scale longest edge down to the target. We may still be over
+                // after one pass for very large source images, so loop with
+                // decreasing quality / dimension until under cap or we hit the
+                // floor.
+                const targets = [
+                    { dim: IMAGE_TARGETS.targetMaxDimension, q: Math.round(IMAGE_TARGETS.jpegQuality * 100) },
+                    { dim: 1280, q: 75 },
+                    { dim: 1024, q: 65 },
+                    { dim: 800, q: 55 },
+                ];
+                const mime = Jimp.MIME_JPEG ?? "image/jpeg";
+                let bestBuf = null;
+                for (const t of targets) {
+                    const w = pic.bitmap?.width ?? t.dim;
+                    const h = pic.bitmap?.height ?? t.dim;
+                    const longest = Math.max(w, h);
+                    // Only scale down — never up an already-small image.
+                    if (longest > t.dim) {
+                        if (w >= h) {
+                            pic.resize(t.dim, Math.round((h / w) * t.dim));
+                        }
+                        else {
+                            pic.resize(Math.round((w / h) * t.dim), t.dim);
+                        }
+                    }
+                    pic.quality(t.q);
+                    const buf = await pic.getBufferAsync(mime);
+                    if (buf.byteLength <= maxBytes) {
+                        bestBuf = buf;
+                        break;
+                    }
+                    bestBuf = buf;
+                }
+                if (!bestBuf) {
+                    return { image, compressed: false, originalBytes, finalBytes: originalBytes };
+                }
+                const finalBytes = bestBuf.byteLength;
+                const out = {
+                    ...image,
+                    base64: bestBuf.toString("base64"),
+                    mime: "image/jpeg",
+                };
+                return {
+                    image: out,
+                    compressed: true,
+                    originalBytes,
+                    finalBytes,
+                };
+            },
+        };
+    }
+    catch {
+        cachedJimpCompressor = NOOP_COMPRESSOR;
+    }
+    return cachedJimpCompressor;
+}
+/**
+ * Try compressing every image in the batch so it fits under the
+ * single-image cap. Returns the (possibly transformed) batch plus a
+ * summary of what changed. Callers should hand the returned images
+ * back into {@link enforceImagePolicy} to confirm; this function
+ * doesn't itself decide whether the result is acceptable.
+ */
+export async function tryCompressImages(images) {
+    if (images.length === 0)
+        return { images: [], anyCompressed: false };
+    const compressor = activeCompressor ?? (await resolveJimpCompressor());
+    if (compressor === NOOP_COMPRESSOR) {
+        return { images: images.slice(), anyCompressed: false };
+    }
+    const out = [];
+    let anyCompressed = false;
+    for (const img of images) {
+        const bytes = byteLengthFromBase64(img.base64);
+        if (bytes <= IMAGE_LIMITS.maxBytesPerImage) {
+            out.push(img);
+            continue;
+        }
+        const result = await compressor.compress(img, IMAGE_LIMITS.maxBytesPerImage);
+        out.push(result.image);
+        if (result.compressed)
+            anyCompressed = true;
+    }
+    return { images: out, anyCompressed };
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Engine-side image policy: a single source of truth for what counts as
+ * an "OK to ship to the model" attachment.
+ *
+ * Why this exists
+ * ---------------
+ * The desktop renderer happily takes a 4 MB screenshot, base64-encodes it,
+ * and ships it to the LLM. OpenAI-compatible providers stream the request
+ * body; a payload that fat plus a flaky link manifests as
+ * `OpenAI API error: Connection error.` with no useful classification,
+ * three retries deep. That bug is in our session log
+ * `s-mppk3ot5-02d35ca4`: textLen=4,364,933, promptTokens=1,091,232.
+ *
+ * The right fix is to keep the bytes small *before* they leave the host.
+ * But not every entry point has the same compressor available:
+ *   - desktop renderer has <canvas> + Blob, no native deps
+ *   - TUI runs in plain Node and has neither
+ *   - MCP tools / future arena agents will need it too
+ *
+ * So this module owns:
+ *   1. The shared *thresholds* every host honors before sending to the LLM
+ *      (`IMAGE_LIMITS`).
+ *   2. A `byteLengthFromBase64()` helper everyone uses to measure decoded
+ *      payload size without actually decoding it.
+ *   3. An `enforceImagePolicy()` engine gate that runs *after* parse-task
+ *      and *before* the message hits the provider. When a single image
+ *      blows the limit, the gate refuses the turn with a friendly error
+ *      and a hint telling the user what to do. The engine is the last
+ *      place we can refuse cheaply — the next step is a $0.10 vision call
+ *      over a flaky socket.
+ *
+ * Hosts (desktop, TUI) are encouraged to compress upstream so this gate
+ * never fires in practice. When it does fire, the user gets a clear
+ * message instead of "Connection error. Connection error. Connection
+ * error.".
+ *
+ * Pure + no I/O — safe to use from any caller.
+ */
+import type { ParsedImage } from "./parse-task.js";
+/**
+ * Hard limits the engine enforces. Soft hints (target sizes) live in
+ * `IMAGE_TARGETS` so hosts know what to aim for when they pre-compress.
+ *
+ * Rationale for each number:
+ *   - `maxBytesPerImage`: 2 MB decoded. OpenAI's `gpt-4o` accepts up to
+ *     20 MB but charges by tile count; 2 MB ≈ a 2048×2048 PNG which is
+ *     plenty for every UI screenshot. Above this we've measured the
+ *     "Connection error" failure mode in practice.
+ *   - `maxBytesPerTurn`: 6 MB total, regardless of count. The four-image
+ *     attach is the typical worst case from the desktop UI, and 4× the
+ *     per-image cap would blow past most providers' rate-limited request
+ *     body sizes.
+ *   - `maxImagesPerTurn`: 6 (matches the desktop renderer's UI limit, so
+ *     a wider engine gate is just dead defense).
+ */
+export declare const IMAGE_LIMITS: {
+    readonly maxBytesPerImage: number;
+    readonly maxBytesPerTurn: number;
+    readonly maxImagesPerTurn: 6;
+};
+/**
+ * Soft targets hosts use when pre-compressing. `targetMaxDimension` is
+ * the longest-edge pixel cap that *almost always* keeps a JPEG under
+ * `maxBytesPerImage`. Hosts re-encode at `jpegQuality` and only escalate
+ * the compression if the result is still over.
+ */
+export declare const IMAGE_TARGETS: {
+    readonly targetMaxDimension: 2048;
+    readonly jpegQuality: 0.82;
+};
+/**
+ * Decode-free size estimate of a base64 string.
+ *
+ * Returns the count of bytes the base64 string would produce *after*
+ * decoding. Used everywhere we need to "weigh" an image without paying
+ * the cost of `Buffer.from(s, "base64")` allocation.
+ *
+ *   - 4 base64 chars → 3 decoded bytes.
+ *   - Trailing `=` padding subtracts from the byte count.
+ *   - Tolerates whitespace and missing padding by working off `length`
+ *     modulo 4 — the wire format strips whitespace via parse-task, so
+ *     this only matters when an exotic caller hands us raw textarea text.
+ */
+export declare function byteLengthFromBase64(b64: string): number;
+/**
+ * Verdict returned by {@link enforceImagePolicy}. `ok: true` means the
+ * caller can proceed with the original images unchanged. `ok: false`
+ * carries a user-facing message + machine-readable reason so callers can
+ * decide whether to render an error card or refuse the turn outright.
+ */
+export type ImagePolicyVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    /**
+     * Stable string the engine surfaces as the run's terminal reason.
+     * Distinct values so a future UI could pick different icons.
+     */
+    code: "image_too_large" | "images_total_too_large" | "too_many_images";
+    /** User-facing message — Chinese-friendly because both UIs are zh. */
+    message: string;
+    /** Optional fields the UI may use for finer-grained reporting. */
+    offender?: {
+        name: string;
+        mime: string;
+        bytes: number;
+    };
+    totals: {
+        imageCount: number;
+        totalBytes: number;
+    };
+};
+/**
+ * Run the per-turn image policy.
+ *
+ * Three failure modes, all surfaced with a Chinese-language hint that
+ * tells the user *what to do next*:
+ *
+ *   1. Per-image cap exceeded → name the file + the cap, suggest
+ *      re-saving / cropping. (`code: "image_too_large"`)
+ *   2. Per-turn cumulative cap exceeded → total bytes + cap. The user
+ *      likely attached too many screenshots; suggest removing some.
+ *      (`code: "images_total_too_large"`)
+ *   3. Count cap exceeded → the desktop UI already caps at 6, so this
+ *      mostly catches future-MCP / TUI batch paths. (`code: "too_many_images"`)
+ *
+ * The gate is **strict** — no silent truncation. The "Connection error"
+ * failure mode this exists to prevent was effectively a silent truncate
+ * (bytes lost mid-stream); a friendly refusal is strictly better.
+ */
+/**
+ * Drop the images that exceed {@link IMAGE_LIMITS.maxBytesPerImage}
+ * and return a textual placeholder describing what was removed. The
+ * engine uses this to keep a poisoned image out of conversation
+ * history while still letting the rest of the turn proceed — Claude
+ * Code's "5MB brick session" failure mode is exactly the bug where
+ * a too-large image enters history and every subsequent request
+ * re-sends it (see docs/research-cc-vs-codex-image-handling.md §A).
+ *
+ * Returns the filtered image list and, when anything was dropped, a
+ * Chinese-language note suitable for prepending to the user text.
+ */
+export interface DropOversizedResult {
+    /** Images that fit under the per-image cap (in original order). */
+    kept: ParsedImage[];
+    /** A human-readable note about what was removed, or "" if nothing was. */
+    placeholder: string;
+    /** Number of images removed. */
+    droppedCount: number;
+}
+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

@@ -0,0 +1,189 @@
+/**
+ * Engine-side image policy: a single source of truth for what counts as
+ * an "OK to ship to the model" attachment.
+ *
+ * Why this exists
+ * ---------------
+ * The desktop renderer happily takes a 4 MB screenshot, base64-encodes it,
+ * and ships it to the LLM. OpenAI-compatible providers stream the request
+ * body; a payload that fat plus a flaky link manifests as
+ * `OpenAI API error: Connection error.` with no useful classification,
+ * three retries deep. That bug is in our session log
+ * `s-mppk3ot5-02d35ca4`: textLen=4,364,933, promptTokens=1,091,232.
+ *
+ * The right fix is to keep the bytes small *before* they leave the host.
+ * But not every entry point has the same compressor available:
+ *   - desktop renderer has <canvas> + Blob, no native deps
+ *   - TUI runs in plain Node and has neither
+ *   - MCP tools / future arena agents will need it too
+ *
+ * So this module owns:
+ *   1. The shared *thresholds* every host honors before sending to the LLM
+ *      (`IMAGE_LIMITS`).
+ *   2. A `byteLengthFromBase64()` helper everyone uses to measure decoded
+ *      payload size without actually decoding it.
+ *   3. An `enforceImagePolicy()` engine gate that runs *after* parse-task
+ *      and *before* the message hits the provider. When a single image
+ *      blows the limit, the gate refuses the turn with a friendly error
+ *      and a hint telling the user what to do. The engine is the last
+ *      place we can refuse cheaply — the next step is a $0.10 vision call
+ *      over a flaky socket.
+ *
+ * Hosts (desktop, TUI) are encouraged to compress upstream so this gate
+ * never fires in practice. When it does fire, the user gets a clear
+ * message instead of "Connection error. Connection error. Connection
+ * error.".
+ *
+ * Pure + no I/O — safe to use from any caller.
+ */
+/**
+ * Hard limits the engine enforces. Soft hints (target sizes) live in
+ * `IMAGE_TARGETS` so hosts know what to aim for when they pre-compress.
+ *
+ * Rationale for each number:
+ *   - `maxBytesPerImage`: 2 MB decoded. OpenAI's `gpt-4o` accepts up to
+ *     20 MB but charges by tile count; 2 MB ≈ a 2048×2048 PNG which is
+ *     plenty for every UI screenshot. Above this we've measured the
+ *     "Connection error" failure mode in practice.
+ *   - `maxBytesPerTurn`: 6 MB total, regardless of count. The four-image
+ *     attach is the typical worst case from the desktop UI, and 4× the
+ *     per-image cap would blow past most providers' rate-limited request
+ *     body sizes.
+ *   - `maxImagesPerTurn`: 6 (matches the desktop renderer's UI limit, so
+ *     a wider engine gate is just dead defense).
+ */
+export const IMAGE_LIMITS = {
+    maxBytesPerImage: 2 * 1024 * 1024,
+    maxBytesPerTurn: 6 * 1024 * 1024,
+    maxImagesPerTurn: 6,
+};
+/**
+ * Soft targets hosts use when pre-compressing. `targetMaxDimension` is
+ * the longest-edge pixel cap that *almost always* keeps a JPEG under
+ * `maxBytesPerImage`. Hosts re-encode at `jpegQuality` and only escalate
+ * the compression if the result is still over.
+ */
+export const IMAGE_TARGETS = {
+    targetMaxDimension: 2048,
+    jpegQuality: 0.82,
+};
+/**
+ * Decode-free size estimate of a base64 string.
+ *
+ * Returns the count of bytes the base64 string would produce *after*
+ * decoding. Used everywhere we need to "weigh" an image without paying
+ * the cost of `Buffer.from(s, "base64")` allocation.
+ *
+ *   - 4 base64 chars → 3 decoded bytes.
+ *   - Trailing `=` padding subtracts from the byte count.
+ *   - Tolerates whitespace and missing padding by working off `length`
+ *     modulo 4 — the wire format strips whitespace via parse-task, so
+ *     this only matters when an exotic caller hands us raw textarea text.
+ */
+export function byteLengthFromBase64(b64) {
+    if (!b64)
+        return 0;
+    // Strip whitespace defensively; the parser already does this, but other
+    // callers (logging stubs, MCP image blocks) might not.
+    const clean = b64.replace(/\s+/g, "");
+    const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+    return Math.floor((clean.length * 3) / 4) - padding;
+}
+function fmtMB(bytes) {
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+export function dropOversizedImages(images) {
+    const kept = [];
+    const dropped = [];
+    for (const img of images) {
+        const bytes = byteLengthFromBase64(img.base64);
+        if (bytes > IMAGE_LIMITS.maxBytesPerImage) {
+            dropped.push({ name: img.name || "(未命名)", bytes });
+        }
+        else {
+            kept.push(img);
+        }
+    }
+    if (dropped.length === 0) {
+        return { kept, placeholder: "", droppedCount: 0 };
+    }
+    const list = dropped
+        .map((d) => `「${d.name}」(~${fmtMB(d.bytes)})`)
+        .join("、");
+    const placeholder = `[已自动跳过 ${dropped.length} 张超大图片:${list};` +
+        `单图上限 ${fmtMB(IMAGE_LIMITS.maxBytesPerImage)}。` +
+        `图片未进入对话历史,本轮其余内容继续。]`;
+    return { kept, placeholder, droppedCount: dropped.length };
+}
+export function enforceImagePolicy(images) {
+    if (images.length === 0)
+        return { ok: true };
+    if (images.length > IMAGE_LIMITS.maxImagesPerTurn) {
+        return {
+            ok: false,
+            code: "too_many_images",
+            message: `一次最多附 ${IMAGE_LIMITS.maxImagesPerTurn} 张图片，` +
+                `本次有 ${images.length} 张。请删掉一些再发。`,
+            totals: {
+                imageCount: images.length,
+                totalBytes: images.reduce((s, i) => s + byteLengthFromBase64(i.base64), 0),
+            },
+        };
+    }
+    let totalBytes = 0;
+    for (const img of images) {
+        const bytes = byteLengthFromBase64(img.base64);
+        if (bytes > IMAGE_LIMITS.maxBytesPerImage) {
+            return {
+                ok: false,
+                code: "image_too_large",
+                message: `图片「${img.name || "(未命名)"}」解码后约 ${fmtMB(bytes)}，` +
+                    `超过单图上限 ${fmtMB(IMAGE_LIMITS.maxBytesPerImage)}。` +
+                    `请先截图压缩或保存为 JPEG（最长边 ≤ ${IMAGE_TARGETS.targetMaxDimension}px）再发。`,
+                offender: { name: img.name, mime: img.mime, bytes },
+                totals: {
+                    imageCount: images.length,
+                    totalBytes: totalBytes + bytes,
+                },
+            };
+        }
+        totalBytes += bytes;
+    }
+    if (totalBytes > IMAGE_LIMITS.maxBytesPerTurn) {
+        return {
+            ok: false,
+            code: "images_total_too_large",
+            message: `本次附图合计约 ${fmtMB(totalBytes)}，超过每轮上限 ${fmtMB(IMAGE_LIMITS.maxBytesPerTurn)}。` +
+                `请删掉一些图片，或先把图片压缩后再发。`,
+            totals: {
+                imageCount: images.length,
+                totalBytes,
+            },
+        };
+    }
+    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;