@cjhyy/code-shell-core 0.6.0-rc.8 → 0.7.0-beta.1

package/dist/cc-orchestrator/external-agent-bindings.js

@@ -0,0 +1,150 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { codeShellHome, SessionManager } from "../session/session-manager.js";
+export function externalAgentBindingsPath(home = codeShellHome()) {
+    return join(home, "external-agents", "bindings.json");
+}
+export class ExternalAgentBindingStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    get(externalSessionId) {
+        return this.read({ failOnCorrupt: true }).bindings[externalSessionId];
+    }
+    upsert(next) {
+        const data = this.read({ failOnCorrupt: false });
+        const existing = data.bindings[next.externalSessionId];
+        const now = Date.now();
+        const binding = {
+            ...next,
+            codeShellSessionId: next.codeShellSessionId || existing?.codeShellSessionId || "",
+            createdAt: existing?.createdAt ?? now,
+            lastUsedAt: now,
+        };
+        data.bindings[next.externalSessionId] = binding;
+        this.write(data);
+        return binding;
+    }
+    read(opts) {
+        const file = this.file();
+        if (!existsSync(file))
+            return { bindings: {} };
+        try {
+            const parsed = JSON.parse(readFileSync(file, "utf-8"));
+            if (parsed && typeof parsed.bindings === "object" && parsed.bindings) {
+                return { bindings: parsed.bindings };
+            }
+            if (opts.failOnCorrupt) {
+                throw new Error(`external agent bindings file is corrupt: expected object with bindings`);
+            }
+            return { bindings: {} };
+        }
+        catch (err) {
+            if (opts.failOnCorrupt) {
+                throw new Error(`external agent bindings file is corrupt or unreadable: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            return { bindings: {} };
+        }
+    }
+    write(data) {
+        const file = this.file();
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+        renameSync(tmp, file);
+    }
+    file() {
+        return this.filePath ?? externalAgentBindingsPath();
+    }
+}
+export function detectExternalAgentWorktree(cwd) {
+    if (!existsSync(cwd))
+        return {};
+    try {
+        const root = git(cwd, ["rev-parse", "--show-toplevel"]);
+        const branch = git(root, ["branch", "--show-current"]);
+        const entries = parseWorktreeList(git(root, ["worktree", "list", "--porcelain"]));
+        const current = entries.find((entry) => resolve(entry.path) === resolve(root));
+        const main = entries[0];
+        if (!current || !branch || !main || resolve(current.path) === resolve(main.path))
+            return {};
+        return { worktreePath: root, worktreeBranch: branch };
+    }
+    catch {
+        return {};
+    }
+}
+export function externalAgentResumeCwdError(binding) {
+    if (existsSync(binding.cwd))
+        return undefined;
+    const branch = binding.worktreeBranch;
+    if (branch && branchExistsForBinding(binding)) {
+        return (`Error: external ${binding.cli} session ${binding.externalSessionId} is bound to cwd ` +
+            `${binding.cwd}, but that directory no longer exists. Worktree branch ${branch} still ` +
+            `exists; recreate the worktree at ${binding.worktreePath ?? binding.cwd} before resuming.`);
+    }
+    return (`Error: external ${binding.cli} session ${binding.externalSessionId} is bound to cwd ` +
+        `${binding.cwd}, but the workspace deleted${branch ? ` and branch ${branch} is gone` : ""}. ` +
+        `Start a new external session.`);
+}
+function branchExistsForBinding(binding) {
+    if (!binding.worktreeBranch)
+        return false;
+    for (const cwd of candidateGitCwds(binding)) {
+        if (!cwd || !existsSync(cwd))
+            continue;
+        try {
+            const out = git(cwd, ["branch", "--list", binding.worktreeBranch]);
+            if (out.length > 0)
+                return true;
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return false;
+}
+function candidateGitCwds(binding) {
+    const candidates = new Set();
+    if (existsSync(binding.cwd))
+        candidates.add(binding.cwd);
+    if (binding.codeShellSessionId) {
+        const sessionCwd = new SessionManager().readCwd(binding.codeShellSessionId);
+        if (sessionCwd)
+            candidates.add(sessionCwd);
+    }
+    candidates.add(process.cwd());
+    candidates.add(dirname(binding.cwd));
+    candidates.add(dirname(dirname(binding.cwd)));
+    return [...candidates];
+}
+function parseWorktreeList(raw) {
+    if (!raw.trim())
+        return [];
+    const entries = [];
+    let current = { path: "", branch: "" };
+    for (const line of raw.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            if (current.path)
+                entries.push(current);
+            current = { path: line.slice(9), branch: "" };
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = line.slice(7).replace("refs/heads/", "");
+        }
+    }
+    if (current.path)
+        entries.push(current);
+    return entries;
+}
+function git(cwd, args) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf-8",
+        timeout: 10000,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+export const externalAgentBindingStore = new ExternalAgentBindingStore();

package/dist/cc-orchestrator/external-agent-driver.d.ts

@@ -11,6 +11,7 @@ export declare function runWithLines(adapter: AgentAdapter, lines: string[], exi
 export interface DriverRunOpts extends Omit<BuildArgsOpts, "permissionMode"> {
     permissionMode?: PermissionMode;
 }
+export declare function detectCodexImageInput(command: string, cwd: string): Promise<boolean>;
 /** Spawn ONE headless agent run, collect stream-json to exit, return result.
  *  No time concept — a single turn. Honors AbortSignal (kills the child). */
 export declare function runAgentOnce(adapter: AgentAdapter, opts: DriverRunOpts & {

package/dist/cc-orchestrator/external-agent-driver.js

@@ -6,64 +6,115 @@ export function runWithLines(adapter, lines, exitCode) {
     const parsed = adapter.parseResult(lines);
     return { ...parsed, exitCode, lines };
 }
-/** Spawn ONE headless agent run, collect stream-json to exit, return result.
- *  No time concept — a single turn. Honors AbortSignal (kills the child). */
-export function runAgentOnce(adapter, opts, signal) {
-    return new Promise((resolve, reject) => {
-        const args = adapter.buildArgs({
-            prompt: opts.prompt,
-            resumeSessionId: opts.resumeSessionId,
-            permissionMode: opts.permissionMode ?? "default",
-            cwd: opts.cwd,
-        });
-        // claude takes the prompt in argv (`-p <prompt>`) and wants stdin closed
-        // (verified: avoids a 3s wait). codex `exec` reads the prompt from stdin
-        // (argv ends with `-`), so adapters that set promptViaStdin get a piped
-        // stdin we write the prompt to.
-        const viaStdin = adapter.promptViaStdin === true;
-        const child = spawn(opts.command, args, {
-            cwd: opts.cwd,
+const codexImageFlagCache = new Map();
+export function detectCodexImageInput(command, cwd) {
+    const cached = codexImageFlagCache.get(command);
+    if (cached)
+        return cached;
+    const probe = new Promise((resolve) => {
+        const child = spawn(command, ["exec", "--help"], {
+            cwd,
             env: { ...process.env, PATH: pathWithCommonBins() },
-            // NOT detached: this child is owned by the (long-lived) worker that reads
-            // its stdout. Detaching orphaned it across a worker/app restart — the
-            // reader promise then never resolved and the completion notification never
-            // fired (the "后台任务没返回" bug). Bound to the worker, it lives or dies
-            // with the process that's actually listening for its result.
-            detached: false,
-            stdio: [viaStdin ? "pipe" : "ignore", "pipe", "pipe"],
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
         });
-        if (viaStdin && child.stdin) {
-            child.stdin.end(opts.prompt);
-        }
-        const lines = [];
-        if (child.stdout) {
-            const rl = createInterface({ input: child.stdout });
-            rl.on("line", (line) => lines.push(line));
-        }
-        // Not detached → no own process group, so kill the child directly (a
-        // negative-pid group kill would target the worker's group). claude has no
-        // long-lived child tree of its own here, so a direct SIGTERM is sufficient.
-        const onAbort = () => {
+        let out = "";
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(() => {
             try {
                 child.kill("SIGTERM");
             }
-            catch { /* already gone */ }
-        };
-        signal?.addEventListener("abort", onAbort, { once: true });
-        child.on("error", (err) => {
-            signal?.removeEventListener("abort", onAbort);
-            // A missing binary is the most common failure (user hasn't installed the
-            // CLI, or GUI-launched Electron's PATH misses it). Turn the cryptic
-            // "spawn codex ENOENT" into something actionable that names the command.
-            if (err.code === "ENOENT") {
-                reject(new Error(`未找到命令 "${opts.command}"。请先安装该 CLI 并确保它在 PATH 中（${adapter.kind === "codex" ? "Codex CLI" : "Claude Code CLI"}）。`));
-                return;
+            catch {
+                // already gone
             }
-            reject(err);
+            done(false);
+        }, 2_000);
+        child.stdout?.on("data", (chunk) => {
+            out += chunk.toString("utf8");
         });
-        child.on("exit", (code) => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve(runWithLines(adapter, lines, code));
+        child.stderr?.on("data", (chunk) => {
+            out += chunk.toString("utf8");
         });
+        child.on("error", () => done(false));
+        child.on("exit", () => done(/(?:^|\s)-i(?:,|\s)|--image\b/.test(out)));
+    });
+    codexImageFlagCache.set(command, probe);
+    return probe;
+}
+/** Spawn ONE headless agent run, collect stream-json to exit, return result.
+ *  No time concept — a single turn. Honors AbortSignal (kills the child). */
+export function runAgentOnce(adapter, opts, signal) {
+    return new Promise((resolve, reject) => {
+        void (async () => {
+            const codexImageInputSupported = adapter.kind === "codex" && (opts.imagePaths?.length ?? 0) > 0
+                ? await detectCodexImageInput(opts.command, opts.cwd).catch(() => false)
+                : false;
+            const args = adapter.buildArgs({
+                prompt: opts.prompt,
+                resumeSessionId: opts.resumeSessionId,
+                permissionMode: opts.permissionMode ?? "default",
+                cwd: opts.cwd,
+                imagePaths: opts.imagePaths,
+                codexImageInputSupported,
+            });
+            // claude takes the prompt in argv (`-p <prompt>`) and wants stdin closed
+            // (verified: avoids a 3s wait). codex `exec` reads the prompt from stdin
+            // (argv ends with `-`), so adapters that set promptViaStdin get a piped
+            // stdin we write the prompt to.
+            const viaStdin = adapter.promptViaStdin === true;
+            const child = spawn(opts.command, args, {
+                cwd: opts.cwd,
+                env: { ...process.env, PATH: pathWithCommonBins() },
+                // NOT detached: this child is owned by the (long-lived) worker that reads
+                // its stdout. Detaching orphaned it across a worker/app restart — the
+                // reader promise then never resolved and the completion notification never
+                // fired (the "后台任务没返回" bug). Bound to the worker, it lives or dies
+                // with the process that's actually listening for its result.
+                detached: false,
+                stdio: [viaStdin ? "pipe" : "ignore", "pipe", "pipe"],
+            });
+            if (viaStdin && child.stdin) {
+                child.stdin.end(opts.prompt);
+            }
+            const lines = [];
+            if (child.stdout) {
+                const rl = createInterface({ input: child.stdout });
+                rl.on("line", (line) => lines.push(line));
+            }
+            // Not detached → no own process group, so kill the child directly (a
+            // negative-pid group kill would target the worker's group). claude has no
+            // long-lived child tree of its own here, so a direct SIGTERM is sufficient.
+            const onAbort = () => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* already gone */
+                }
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            child.on("error", (err) => {
+                signal?.removeEventListener("abort", onAbort);
+                // A missing binary is the most common failure (user hasn't installed the
+                // CLI, or GUI-launched Electron's PATH misses it). Turn the cryptic
+                // "spawn codex ENOENT" into something actionable that names the command.
+                if (err.code === "ENOENT") {
+                    reject(new Error(`未找到命令 "${opts.command}"。请先安装该 CLI 并确保它在 PATH 中（${adapter.kind === "codex" ? "Codex CLI" : "Claude Code CLI"}）。`));
+                    return;
+                }
+                reject(err);
+            });
+            child.on("exit", (code) => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve(runWithLines(adapter, lines, code));
+            });
+        })().catch(reject);
     });
 }

package/dist/cc-orchestrator/external-agent-session-store.d.ts

@@ -0,0 +1,23 @@
+export type ExternalAgentCli = "claude" | "codex";
+export interface ExternalAgentSessionBinding {
+    cli: ExternalAgentCli;
+    sessionId: string;
+    cwd: string;
+    worktreePath?: string;
+    worktreeBranch?: string;
+    updatedAt: number;
+}
+export type ExternalAgentSessionRecord = Omit<ExternalAgentSessionBinding, "updatedAt"> & {
+    updatedAt?: number;
+};
+export declare function defaultExternalAgentSessionStorePath(): string;
+export declare class ExternalAgentSessionStore {
+    private readonly file;
+    constructor(file?: string);
+    get(cli: ExternalAgentCli, sessionId: string): ExternalAgentSessionBinding | undefined;
+    record(binding: ExternalAgentSessionRecord): void;
+    private load;
+    private save;
+    private withLock;
+}
+export declare const externalAgentSessionStore: ExternalAgentSessionStore;

package/dist/cc-orchestrator/external-agent-session-store.js

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { codeShellHome } from "../session/session-manager.js";
+import { logger } from "../logging/logger.js";
+import { normalizeCwdPath } from "./cwd-normalize.js";
+const LOCK_WAIT_MS = 5_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_POLL_MS = 10;
+export function defaultExternalAgentSessionStorePath() {
+    return join(codeShellHome(), "external-agent-sessions.json");
+}
+export class ExternalAgentSessionStore {
+    file;
+    constructor(file = defaultExternalAgentSessionStorePath()) {
+        this.file = file;
+    }
+    get(cli, sessionId) {
+        if (!sessionId)
+            return undefined;
+        return this.load().find((s) => s.cli === cli && s.sessionId === sessionId);
+    }
+    record(binding) {
+        if (!binding.sessionId || !binding.cwd)
+            return;
+        const next = {
+            cli: binding.cli,
+            sessionId: binding.sessionId,
+            cwd: normalizeCwdPath(binding.cwd),
+            ...(binding.worktreePath ? { worktreePath: binding.worktreePath } : {}),
+            ...(binding.worktreeBranch ? { worktreeBranch: binding.worktreeBranch } : {}),
+            updatedAt: binding.updatedAt ?? Date.now(),
+        };
+        this.withLock(() => {
+            const sessions = this.load().filter((s) => !(s.cli === binding.cli && s.sessionId === binding.sessionId));
+            sessions.push(next);
+            this.save(sessions);
+        });
+    }
+    load() {
+        if (!existsSync(this.file))
+            return [];
+        try {
+            const raw = readFileSync(this.file, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (!parsed || !Array.isArray(parsed.sessions))
+                return [];
+            return parsed.sessions.filter(isBinding).map(normalizeBinding);
+        }
+        catch (err) {
+            logger.warn("external_agent_session_store.load_failed", {
+                cat: "cc",
+                file: this.file,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return [];
+        }
+    }
+    save(sessions) {
+        const dir = dirname(this.file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const snapshot = { version: 1, sessions };
+        const tmp = `${this.file}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            writeFileSync(tmp, JSON.stringify(snapshot, null, 2) + "\n", "utf-8");
+            renameSync(tmp, this.file);
+        }
+        catch (err) {
+            rmSync(tmp, { force: true });
+            throw err;
+        }
+    }
+    withLock(fn) {
+        const dir = dirname(this.file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        // TODO: move this sync polling lock to an async write queue; callers can
+        // otherwise block the event loop for up to LOCK_WAIT_MS under contention.
+        const lockDir = `${this.file}.lock`;
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        while (true) {
+            try {
+                mkdirSync(lockDir);
+                break;
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "EEXIST")
+                    throw err;
+                if (removeStaleLock(lockDir))
+                    continue;
+                if (Date.now() >= deadline) {
+                    throw new Error(`timed out waiting for external agent session store lock: ${lockDir}`, {
+                        cause: err,
+                    });
+                }
+                sleepSync(LOCK_POLL_MS);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            rmSync(lockDir, { recursive: true, force: true });
+        }
+    }
+}
+function normalizeBinding(binding) {
+    return { ...binding, cwd: normalizeCwdPath(binding.cwd) };
+}
+function removeStaleLock(lockDir) {
+    try {
+        if (Date.now() - statSync(lockDir).mtimeMs <= LOCK_STALE_MS)
+            return false;
+        rmSync(lockDir, { recursive: true, force: true });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return true;
+        return false;
+    }
+}
+function sleepSync(ms) {
+    try {
+        const view = new Int32Array(new SharedArrayBuffer(4));
+        Atomics.wait(view, 0, 0, ms);
+    }
+    catch {
+        const until = Date.now() + ms;
+        while (Date.now() < until) {
+            // fallback for runtimes where Atomics.wait is unavailable
+        }
+    }
+}
+function isBinding(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return ((v.cli === "claude" || v.cli === "codex") &&
+        typeof v.sessionId === "string" &&
+        v.sessionId.length > 0 &&
+        typeof v.cwd === "string" &&
+        v.cwd.length > 0);
+}
+export const externalAgentSessionStore = new ExternalAgentSessionStore();

package/dist/cc-orchestrator/session-history.js

@@ -51,14 +51,14 @@ export function readRecentHistory(cwd, sessionId, limit, claudeHome = join(homed
             const t = textOf(d.message?.content).trim();
             if (!t || NOISE.some((n) => t.startsWith(n)))
                 continue;
-            all.push({ role: "user", text: t.slice(0, 4000) });
+            all.push({ role: "user", text: t });
         }
         else if (d.type === "assistant") {
             const t = textOf(d.message?.content).trim();
             const tools = toolsOf(d.message?.content);
             if (!t && tools.length === 0)
                 continue;
-            all.push({ role: "assistant", text: t.slice(0, 4000), tools: tools.length ? tools : undefined });
+            all.push({ role: "assistant", text: t, tools: tools.length ? tools : undefined });
         }
     }
     const lim = limit > 0 ? limit : 20;

package/dist/cli/agent-server-stdio.js

@@ -50,6 +50,7 @@ import { logger } from "../logging/logger.js";
 import { cronScheduler } from "../automation/scheduler.js";
 import { CronStore, defaultCronStorePath } from "../automation/store.js";
 import { resolveLLMConfigForTag } from "../engine/resolve-llm-config.js";
+import { createIpcCredentialAccess, setDefaultCredentialAccess } from "../credentials/access.js";
 /**
  * Resolve per-session agent config: protocol slice overrides win, else fall
  * back to disk settings.agent.*. Fixes the bug where settings.agent.* never
@@ -106,8 +107,7 @@ catch (err) {
 // knob; imageDetail from settings.images.detail).
 const seedLlm = resolveLLMConfigForTag(settings, "text", settings.defaults?.text);
 if (!seedLlm) {
-    console.error(`[agent-server] 没有可用的文本模型连接(defaults.text=${settings.defaults?.text ?? "未设置"})。` +
-        `请在「连接」页添加并填写凭证。`);
+    console.error(`[agent-server] 没有可用的文本模型连接(defaults.text=${settings.defaults?.text ?? "未设置"})。` + `请在「连接」页添加并填写凭证。`);
     process.exit(1);
 }
 const llmConfig = seedLlm;
@@ -115,6 +115,10 @@ const llmConfig = seedLlm;
 const seedEngine = new Engine({
     llm: llmConfig,
     cwd,
+    preset: settings.agent.preset,
+    enabledBuiltinTools: settings.agent.enabledBuiltinTools,
+    disabledBuiltinTools: settings.agent.disabledBuiltinTools,
+    builtinToolHost: "desktop",
     settingsScope: "full",
     // No runtime — Engine.populateModelPoolFromSettings() runs in ctor.
 });
@@ -217,6 +221,7 @@ const chatManager = new ChatSessionManager({
             // This stdio worker exists only to serve the desktop app, so every
             // session it creates is a desktop-origin session.
             origin: "desktop",
+            builtinToolHost: "desktop",
             // Inherit full scope so spawned subagents read user config too.
             settingsScope: "full",
             // MCP servers from settings — the worker reads the full disk
@@ -270,6 +275,7 @@ cronScheduler.setExecutionEnabled(false);
 cronScheduler.loadJobs();
 // ─── Step 5: AgentServer over stdio ──────────────────────────────
 const stdioTransport = new StdioTransport(process.stdin, process.stdout);
+setDefaultCredentialAccess(createIpcCredentialAccess(stdioTransport));
 // Cron jobs are persisted by this worker but only main arms/executes their
 // timers (this worker keeps setExecutionEnabled(false) above). When an AI tool
 // creates/deletes a cron job here, notify main over stdio so it reloads the
@@ -286,6 +292,7 @@ const goalDiskReader = new SessionManager();
 const agentServer = new AgentServer({
     chatManager,
     transport: stdioTransport,
+    workspaceBridge: true,
     // Config hot-reload (layer 2) reads disk through the SAME closure the
     // engineFactory uses for new sessions, so a reloaded running session and a
     // newly-created session converge on identical disk config (no divergence).

package/dist/context/compaction.d.ts

@@ -10,12 +10,48 @@
  * All slicing functions use adjustIndexToPreserveAPIInvariants()
  * to prevent splitting tool_use / tool_result pairs.
  */
-import type { Message } from "../types.js";
+import type { ContentBlock, Message } from "../types.js";
 /**
  * Estimate token count from messages.
  * Uses per-block-type estimation with 33% overhead padding.
  */
 export declare function estimateTokens(messages: Message[]): number;
+export declare const IMAGE_HISTORY_PLACEHOLDER_PREFIX = "[image #";
+export declare const IMAGE_HISTORY_PLACEHOLDER_SUFFIX = ", \u5DF2\u5904\u7406 / already provided earlier]";
+interface ImagePreserveSet {
+    has(message: Message): boolean;
+}
+export interface DowngradeImageHistoryOptions {
+    /**
+     * Messages whose image payloads are being sent for their first model
+     * consumption in this request. They still count toward image numbering but
+     * keep their base64 until the caller clears the preserve set after a
+     * successful model response.
+     */
+    preserveMessages?: ImagePreserveSet;
+}
+export interface DowngradeImageHistoryResult {
+    messages: Message[];
+    replacedCount: number;
+}
+export interface Base64ImageHistoryEntry {
+    imageNumber: number;
+    block: ContentBlock;
+}
+export declare function collectBase64Images(messages: Message[]): Base64ImageHistoryEntry[];
+export declare function findImageByNumber(messages: Message[], imageNumber: number): Base64ImageHistoryEntry | undefined;
+/**
+ * Replace already-consumed image payload blocks with compact text markers.
+ *
+ * The transcript may retain the full image bytes for rendering/resume, but the
+ * working message history sent to the model should not re-send base64 after the
+ * model has seen it once. This handles both our internal Anthropic-style image
+ * blocks and OpenAI-style data-url image blocks defensively, including images
+ * nested inside tool_result.content arrays (view_image / browser screenshots).
+ */
+export declare function downgradeImagePayloadsInHistory(messages: Message[], options?: DowngradeImageHistoryOptions): DowngradeImageHistoryResult;
+export declare function messageHasBase64ImagePayload(message: Message): boolean;
+export declare function isBase64ImageBlock(block: ContentBlock): boolean;
 /**
  * Reconcile user-supplied compaction ratios into a safe ordering.
  *
@@ -170,3 +206,4 @@ export declare function dropOldestRounds(messages: Message[], roundsToDrop: numb
  * messages. Returns paths only — the model uses Read tool on demand.
  */
 export declare function extractReferencedFilePaths(messages: Message[]): string[];
+export {};