@testchimp/cli 0.1.65 → 0.1.67

package/dist/chimphands/llmRetryProxy.d.ts

@@ -0,0 +1,24 @@
+export type LlmRetryConfig = {
+    delayMs: number;
+    maxMs: number;
+};
+export type LlmRetryDeps = {
+    delayMs?: number;
+    maxMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    fetchFn?: typeof fetch;
+    log?: (msg: string) => void;
+};
+export declare function resolveLlmRetryConfig(): LlmRetryConfig;
+export declare function isChimphandsLlmRetryEnabled(): boolean;
+export declare function isRetryableLlmFailure(status: number): boolean;
+export declare function isRetryableLlmNetworkError(err: unknown): boolean;
+/** Retry upstream fetch until success, non-retryable status, or deadline. */
+export declare function fetchUpstreamWithRetry(url: string, init: RequestInit, deps?: LlmRetryDeps): Promise<Response>;
+export type LlmRetryProxyHandle = {
+    baseUrl: string;
+    stop: () => Promise<void>;
+};
+/** Start a localhost proxy that forwards to FeatureService /v1 with retry. */
+export declare function startLlmRetryProxy(upstreamLlmBase: string, deps?: LlmRetryDeps): Promise<LlmRetryProxyHandle>;

package/dist/chimphands/llmRetryProxy.js

@@ -0,0 +1,177 @@
+/**
+ * Localhost LLM retry proxy for ChimpHands: forwards OpenCode /v1 calls to FeatureService
+ * and retries transient 502/503/504 + network failures (30s delay, up to 5 min).
+ */
+import http from "node:http";
+import { URL } from "node:url";
+const DEFAULT_DELAY_MS = 30_000;
+const DEFAULT_MAX_MS = 300_000;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function resolveLlmRetryConfig() {
+    const delayRaw = Number(process.env.CHIMPHANDS_LLM_RETRY_DELAY_MS ?? DEFAULT_DELAY_MS);
+    const maxRaw = Number(process.env.CHIMPHANDS_LLM_RETRY_MAX_MS ?? DEFAULT_MAX_MS);
+    return {
+        delayMs: Number.isFinite(delayRaw) && delayRaw > 0 ? delayRaw : DEFAULT_DELAY_MS,
+        maxMs: Number.isFinite(maxRaw) && maxRaw > 0 ? maxRaw : DEFAULT_MAX_MS,
+    };
+}
+export function isChimphandsLlmRetryEnabled() {
+    const v = (process.env.CHIMPHANDS_LLM_RETRY ?? "1").trim().toLowerCase();
+    return v !== "0" && v !== "false" && v !== "off" && v !== "no";
+}
+export function isRetryableLlmFailure(status) {
+    return status === 502 || status === 503 || status === 504;
+}
+export function isRetryableLlmNetworkError(err) {
+    if (!(err instanceof Error)) {
+        return /fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|socket hang up|EAI_AGAIN/i.test(String(err));
+    }
+    const code = err.code;
+    if (code && ["ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT", "ECONNRESET", "EAI_AGAIN"].includes(code)) {
+        return true;
+    }
+    return /fetch failed|socket hang up|network|timed out|timeout/i.test(err.message);
+}
+function formatRemainingMs(ms) {
+    return `${Math.max(0, Math.ceil(ms / 1000))}s`;
+}
+/** Retry upstream fetch until success, non-retryable status, or deadline. */
+export async function fetchUpstreamWithRetry(url, init, deps = {}) {
+    const cfg = resolveLlmRetryConfig();
+    const delayMs = deps.delayMs ?? cfg.delayMs;
+    const maxMs = deps.maxMs ?? cfg.maxMs;
+    const sleepFn = deps.sleep ?? defaultSleep;
+    const nowFn = deps.now ?? Date.now;
+    const fetchFn = deps.fetchFn ?? fetch;
+    const log = deps.log ?? ((msg) => console.error(msg));
+    let attempt = 0;
+    let deadline;
+    while (true) {
+        attempt += 1;
+        try {
+            const res = await fetchFn(url, init);
+            if (!isRetryableLlmFailure(res.status)) {
+                return res;
+            }
+            if (deadline === undefined) {
+                deadline = nowFn() + maxMs;
+            }
+            const remaining = deadline - nowFn();
+            if (remaining <= 0) {
+                return res;
+            }
+            const waitMs = Math.min(delayMs, remaining);
+            log(`ChimpHands LLM proxy: upstream ${res.status}, retry in ${Math.round(waitMs / 1000)}s (attempt ${attempt}, ~${formatRemainingMs(remaining)} remaining)`);
+            try {
+                await res.arrayBuffer();
+            }
+            catch {
+                /* ignore body drain errors */
+            }
+            await sleepFn(waitMs);
+            continue;
+        }
+        catch (err) {
+            if (!isRetryableLlmNetworkError(err)) {
+                throw err;
+            }
+            if (deadline === undefined) {
+                deadline = nowFn() + maxMs;
+            }
+            const remaining = deadline - nowFn();
+            if (remaining <= 0) {
+                throw err;
+            }
+            const waitMs = Math.min(delayMs, remaining);
+            const detail = err instanceof Error ? err.message : String(err);
+            log(`ChimpHands LLM proxy: upstream network error (${detail}), retry in ${Math.round(waitMs / 1000)}s (attempt ${attempt}, ~${formatRemainingMs(remaining)} remaining)`);
+            await sleepFn(waitMs);
+        }
+    }
+}
+function stripHopByHopHeaders(raw) {
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined)
+            continue;
+        const lower = key.toLowerCase();
+        if (lower === "host" || lower === "connection" || lower === "keep-alive" || lower === "transfer-encoding") {
+            continue;
+        }
+        out[key] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return out;
+}
+async function readRequestBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return chunks.length ? Buffer.concat(chunks) : undefined;
+}
+/** Start a localhost proxy that forwards to FeatureService /v1 with retry. */
+export async function startLlmRetryProxy(upstreamLlmBase, deps = {}) {
+    const upstream = new URL(upstreamLlmBase.replace(/\/$/, "") + "/");
+    const upstreamOrigin = upstream.origin;
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            try {
+                const pathWithQuery = req.url || "/";
+                const targetUrl = new URL(pathWithQuery, upstreamOrigin).toString();
+                const method = req.method || "GET";
+                const body = await readRequestBody(req);
+                const headers = stripHopByHopHeaders(req.headers);
+                const init = {
+                    method,
+                    headers,
+                    body: body && method !== "GET" && method !== "HEAD" ? new Uint8Array(body) : undefined,
+                };
+                const upstreamRes = await fetchUpstreamWithRetry(targetUrl, init, deps);
+                const responseHeaders = {};
+                upstreamRes.headers.forEach((value, key) => {
+                    if (key.toLowerCase() === "transfer-encoding")
+                        return;
+                    responseHeaders[key] = value;
+                });
+                res.writeHead(upstreamRes.status, responseHeaders);
+                if (upstreamRes.body) {
+                    const reader = upstreamRes.body.getReader();
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        if (value?.length) {
+                            res.write(Buffer.from(value));
+                        }
+                    }
+                }
+                res.end();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (!res.headersSent) {
+                    res.writeHead(502, { "Content-Type": "text/plain; charset=utf-8" });
+                }
+                res.end(msg);
+            }
+        })();
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === "string") {
+        server.close();
+        throw new Error("ChimpHands LLM retry proxy failed to bind");
+    }
+    const baseUrl = `http://127.0.0.1:${addr.port}/v1`;
+    return {
+        baseUrl,
+        stop: () => new Promise((resolve, reject) => {
+            server.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}

package/dist/chimphands/llmRetryProxy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/chimphands/llmRetryProxy.test.js

@@ -0,0 +1,156 @@
+import assert from "node:assert/strict";
+import http from "node:http";
+import { describe, it } from "node:test";
+import { fetchUpstreamWithRetry, isChimphandsLlmRetryEnabled, isRetryableLlmFailure, isRetryableLlmNetworkError, startLlmRetryProxy, } from "./llmRetryProxy.js";
+describe("isRetryableLlmFailure", () => {
+    it("retries 502/503/504 only", () => {
+        assert.equal(isRetryableLlmFailure(503), true);
+        assert.equal(isRetryableLlmFailure(502), true);
+        assert.equal(isRetryableLlmFailure(504), true);
+        assert.equal(isRetryableLlmFailure(500), false);
+        assert.equal(isRetryableLlmFailure(429), false);
+        assert.equal(isRetryableLlmFailure(401), false);
+    });
+});
+describe("isRetryableLlmNetworkError", () => {
+    it("detects common network failures", () => {
+        assert.equal(isRetryableLlmNetworkError(Object.assign(new Error("fetch failed"), { cause: "x" })), true);
+        assert.equal(isRetryableLlmNetworkError(Object.assign(new Error("x"), { code: "ECONNREFUSED" })), true);
+        assert.equal(isRetryableLlmNetworkError(new Error("401 Unauthorized")), false);
+    });
+});
+describe("isChimphandsLlmRetryEnabled", () => {
+    it("defaults to enabled", () => {
+        const prev = process.env.CHIMPHANDS_LLM_RETRY;
+        delete process.env.CHIMPHANDS_LLM_RETRY;
+        assert.equal(isChimphandsLlmRetryEnabled(), true);
+        process.env.CHIMPHANDS_LLM_RETRY = "0";
+        assert.equal(isChimphandsLlmRetryEnabled(), false);
+        if (prev === undefined)
+            delete process.env.CHIMPHANDS_LLM_RETRY;
+        else
+            process.env.CHIMPHANDS_LLM_RETRY = prev;
+    });
+});
+describe("fetchUpstreamWithRetry", () => {
+    it("503 twice then 200 succeeds after two waits", async () => {
+        let calls = 0;
+        const sleeps = [];
+        const res = await fetchUpstreamWithRetry("http://example.test/v1/responses", { method: "POST" }, {
+            delayMs: 30,
+            maxMs: 300,
+            sleep: async (ms) => {
+                sleeps.push(ms);
+            },
+            fetchFn: async () => {
+                calls += 1;
+                if (calls <= 2) {
+                    return new Response("unavailable", { status: 503 });
+                }
+                return new Response('{"ok":true}', { status: 200, headers: { "Content-Type": "application/json" } });
+            },
+        });
+        assert.equal(res.status, 200);
+        assert.equal(calls, 3);
+        assert.deepEqual(sleeps, [30, 30]);
+    });
+    it("503 until deadline returns last 503", async () => {
+        let calls = 0;
+        let now = 0;
+        const res = await fetchUpstreamWithRetry("http://example.test/v1/responses", { method: "POST" }, {
+            delayMs: 100,
+            maxMs: 250,
+            now: () => now,
+            sleep: async (ms) => {
+                now += ms;
+            },
+            fetchFn: async () => {
+                calls += 1;
+                return new Response("unavailable", { status: 503 });
+            },
+        });
+        assert.equal(res.status, 503);
+        assert.equal(calls, 4);
+    });
+    it("network error then success", async () => {
+        let calls = 0;
+        const res = await fetchUpstreamWithRetry("http://example.test/v1/responses", { method: "POST" }, {
+            delayMs: 10,
+            maxMs: 100,
+            sleep: async () => { },
+            fetchFn: async () => {
+                calls += 1;
+                if (calls === 1) {
+                    throw Object.assign(new Error("connect ECONNREFUSED"), { code: "ECONNREFUSED" });
+                }
+                return new Response("ok", { status: 200 });
+            },
+        });
+        assert.equal(res.status, 200);
+        assert.equal(calls, 2);
+    });
+});
+describe("startLlmRetryProxy", () => {
+    it("503 twice then 200 via proxy", async () => {
+        let upstreamCalls = 0;
+        const upstream = http.createServer((_req, res) => {
+            upstreamCalls += 1;
+            if (upstreamCalls <= 2) {
+                res.writeHead(503, { "Content-Type": "text/plain" });
+                res.end("down");
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end('{"ok":true}');
+        });
+        await new Promise((resolve) => upstream.listen(0, "127.0.0.1", () => resolve()));
+        const upstreamPort = upstream.address().port;
+        const proxy = await startLlmRetryProxy(`http://127.0.0.1:${upstreamPort}/v1`, {
+            delayMs: 20,
+            maxMs: 200,
+            sleep: async () => { },
+        });
+        try {
+            const res = await fetch(`${proxy.baseUrl}/responses`, { method: "POST", body: "{}" });
+            assert.equal(res.status, 200);
+            assert.equal(await res.text(), '{"ok":true}');
+            assert.equal(upstreamCalls, 3);
+        }
+        finally {
+            await proxy.stop();
+            await new Promise((resolve) => upstream.close(() => resolve()));
+        }
+    });
+    it("streams chunked success without duplication after 503", async () => {
+        let upstreamCalls = 0;
+        const upstream = http.createServer((_req, res) => {
+            upstreamCalls += 1;
+            if (upstreamCalls === 1) {
+                res.writeHead(503);
+                res.end("down");
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/event-stream" });
+            res.write("data: one\n\n");
+            res.write("data: two\n\n");
+            res.end();
+        });
+        await new Promise((resolve) => upstream.listen(0, "127.0.0.1", () => resolve()));
+        const upstreamPort = upstream.address().port;
+        const proxy = await startLlmRetryProxy(`http://127.0.0.1:${upstreamPort}/v1`, {
+            delayMs: 10,
+            maxMs: 100,
+            sleep: async () => { },
+        });
+        try {
+            const res = await fetch(`${proxy.baseUrl}/chat/completions`, { method: "POST", body: "{}" });
+            assert.equal(res.status, 200);
+            assert.equal(await res.text(), "data: one\n\ndata: two\n\n");
+            assert.equal(upstreamCalls, 2);
+        }
+        finally {
+            await proxy.stop();
+            await new Promise((resolve) => upstream.close(() => resolve()));
+        }
+    });
+});

package/dist/chimphands/run.js

@@ -11,6 +11,7 @@ import http from "node:http";
 import https from "node:https";
 import { URL } from "node:url";
 import { getBackendUrl, requireApiKey } from "../core/client.js";
+import { isChimphandsLlmRetryEnabled, startLlmRetryProxy } from "./llmRetryProxy.js";
 const ROLE_ASSISTANT = "CHIMPHANDS_MESSAGE_ROLE_ASSISTANT";
 const ROLE_TOOL = "CHIMPHANDS_MESSAGE_ROLE_TOOL";
 const ROLE_REASONING = "CHIMPHANDS_MESSAGE_ROLE_REASONING";
@@ -960,8 +961,10 @@ function detectWorkingBranchFromToolOutput(output) {
         pullRequestUrl: prMatch?.[0],
     };
 }
-function writeOpencodeConfig(backend, apiKey, boot) {
-    const llmBase = (bootStr(boot, "llm_base_url", "llmBaseUrl") || `${backend}/v1`).replace(/\/$/, "");
+function writeOpencodeConfig(backend, apiKey, boot, llmBaseOverride) {
+    const llmBase = (llmBaseOverride ||
+        bootStr(boot, "llm_base_url", "llmBaseUrl") ||
+        `${backend}/v1`).replace(/\/$/, "");
     const llmKey = apiKey || bootStr(boot, "llm_api_key", "llmApiKey");
     const modelId = resolveOpencodeModelId(boot);
     const model = `${TESTCHIMP_PROVIDER_ID}/${modelId}`;
@@ -980,6 +983,8 @@ function writeOpencodeConfig(backend, apiKey, boot) {
     const providerOptions = {
         apiKey: llmKey,
         baseURL: llmBase,
+        // Retry proxy may wait up to 5 min; allow long completions after upstream is healthy.
+        timeout: 900_000,
     };
     if (sessionId) {
         providerOptions.headers = {
@@ -1053,6 +1058,35 @@ async function abortOpencodeSession(attachUrl, opencodeSessionId) {
         console.error(`ChimpHands OpenCode session abort failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/** Deliver a user message into an active OpenCode turn without aborting it. */
+async function injectOpencodeUserMessage(attachUrl, opencodeSessionId, content) {
+    const base = attachUrl.replace(/\/$/, "");
+    const url = `${base}/session/${encodeURIComponent(opencodeSessionId)}/prompt_async`;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-opencode-directory": process.cwd(),
+            },
+            body: JSON.stringify({
+                parts: [{ type: "text", text: content }],
+            }),
+        });
+        if (res.status === 204 || res.ok) {
+            const preview = content.length > 120 ? `${content.slice(0, 117)}...` : content;
+            console.error(`ChimpHands injected mid-turn user message into OpenCode session ${opencodeSessionId}: ${JSON.stringify(preview)}`);
+            return true;
+        }
+        console.error(`ChimpHands mid-turn inject HTTP ${res.status} for session ${opencodeSessionId}`);
+        return false;
+    }
+    catch (err) {
+        console.error(`ChimpHands mid-turn inject failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
 function parseInboundUserMessage(data) {
     if (!data || typeof data !== "object")
         return null;
@@ -1732,7 +1766,16 @@ export async function runChimphands(opts) {
         process.env.TESTCHIMP_USER_ID = userId;
     }
     mkdirSync(".opencode", { recursive: true });
-    const opencodeModel = writeOpencodeConfig(backend, apiKey, boot);
+    const upstreamLlmBase = (bootStr(boot, "llm_base_url", "llmBaseUrl") || `${backend}/v1`).replace(/\/$/, "");
+    let llmBaseForOpencode = upstreamLlmBase;
+    let stopLlmProxy = null;
+    if (isChimphandsLlmRetryEnabled()) {
+        const proxy = await startLlmRetryProxy(upstreamLlmBase);
+        llmBaseForOpencode = proxy.baseUrl;
+        stopLlmProxy = proxy.stop;
+        console.error(`ChimpHands LLM retry proxy: ${llmBaseForOpencode} -> ${upstreamLlmBase}`);
+    }
+    const opencodeModel = writeOpencodeConfig(backend, apiKey, boot, llmBaseForOpencode);
     console.error(`ChimpHands OpenCode model: ${opencodeModel}`);
     if (attachUrl) {
         console.error(`ChimpHands OpenCode attach: ${attachUrl}`);
@@ -1775,6 +1818,8 @@ export async function runChimphands(opts) {
     let cancelTurnRequested = false;
     let activeOpencodeChild = null;
     let agentTurnInProgress = false;
+    /** Mid-turn messages waiting for an OpenCode session id before prompt_async inject. */
+    const pendingMidTurnInject = [];
     /** Wakes waitForNextPrompt when idle is signaled (SSE) or a user message arrives. */
     let wakeWaitForPrompt = null;
     const wakePromptWaiter = () => {
@@ -1788,6 +1833,48 @@ export async function runChimphands(opts) {
             activeOpencodeChild = child;
         },
     };
+    /** Abort in-flight OpenCode turn (session HTTP abort + kill `opencode run` child). */
+    const abortActiveTurn = () => {
+        cancelTurnRequested = true;
+        const sessionToAbort = opencodeSessionId?.trim();
+        if (attachUrl && sessionToAbort) {
+            void abortOpencodeSession(attachUrl, sessionToAbort);
+        }
+        const ch = activeOpencodeChild;
+        if (ch && !ch.killed) {
+            try {
+                ch.kill("SIGTERM");
+                setTimeout(() => {
+                    try {
+                        if (!ch.killed)
+                            ch.kill("SIGKILL");
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }, 2000);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    };
+    const flushPendingMidTurnInject = () => {
+        if (!attachUrl || !agentTurnInProgress)
+            return;
+        const sessionToInject = opencodeSessionId?.trim();
+        if (!sessionToInject)
+            return;
+        while (pendingMidTurnInject.length) {
+            const content = pendingMidTurnInject.shift();
+            void injectOpencodeUserMessage(attachUrl, sessionToInject, content).then((ok) => {
+                if (!ok) {
+                    queue.push(content);
+                    wakePromptWaiter();
+                }
+            });
+        }
+    };
     const enqueueUserMessage = (msg) => {
         const id = msg.id?.trim();
         if (id) {
@@ -1798,12 +1885,30 @@ export async function runChimphands(opts) {
         const content = normalizeUserMessage(msg.content || "");
         if (!content)
             return;
-        queue.push(content);
         lastUserActivity = Date.now();
         idle = false;
-        wakePromptWaiter();
         const preview = content.length > 120 ? `${content.slice(0, 117)}...` : content;
+        if (agentTurnInProgress && attachUrl) {
+            const sessionToInject = opencodeSessionId?.trim();
+            if (sessionToInject) {
+                console.error(`ChimpHands delivering mid-turn user message via OpenCode prompt_async (turnActive=true): ${JSON.stringify(preview)}`);
+                void injectOpencodeUserMessage(attachUrl, sessionToInject, content).then((ok) => {
+                    if (!ok) {
+                        queue.push(content);
+                        wakePromptWaiter();
+                        return;
+                    }
+                    postEvent(ROLE_STATUS, "Message sent to agent…", { status: STATUS_RUNNING });
+                });
+                return;
+            }
+            pendingMidTurnInject.push(content);
+            console.error(`ChimpHands holding mid-turn user message until OpenCode session id is available: ${JSON.stringify(preview)}`);
+            return;
+        }
+        queue.push(content);
         console.error(`ChimpHands queued user message (turnActive=${agentTurnInProgress}, depth=${queue.length}): ${JSON.stringify(preview)}`);
+        wakePromptWaiter();
     };
     const pollPendingUserMessages = async () => {
         try {
@@ -1869,29 +1974,7 @@ export async function runChimphands(opts) {
         childEnv.TESTCHIMP_USER_ID = userId;
     const handleCancelTurn = () => {
         console.error(`ChimpHands cancel_turn received for session ${sessionId}`);
-        cancelTurnRequested = true;
-        const sessionToAbort = opencodeSessionId?.trim();
-        if (attachUrl && sessionToAbort) {
-            void abortOpencodeSession(attachUrl, sessionToAbort);
-        }
-        const ch = activeOpencodeChild;
-        if (ch && !ch.killed) {
-            try {
-                ch.kill("SIGTERM");
-                setTimeout(() => {
-                    try {
-                        if (!ch.killed)
-                            ch.kill("SIGKILL");
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                }, 2000);
-            }
-            catch {
-                /* ignore */
-            }
-        }
+        abortActiveTurn();
     };
     const stopInbound = connectInboundStream(backend, apiKey, sessionId, {
         onUserMessage: enqueueUserMessage,
@@ -1928,6 +2011,12 @@ export async function runChimphands(opts) {
         wakePromptWaiter();
         await commitAndPushDirtyWorktree("chimphands: commit before session idle/shutdown");
         await poster.flush();
+        if (stopLlmProxy) {
+            await stopLlmProxy().catch((err) => {
+                console.error(`ChimpHands LLM retry proxy stop failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+            stopLlmProxy = null;
+        }
         if (runtimeId) {
             await postJson(backend, apiKey, "/api/chimphands/complete_runtime", {
                 runtimeId,
@@ -2007,6 +2096,7 @@ export async function runChimphands(opts) {
         while (prompt) {
             cancelTurnRequested = false;
             agentTurnInProgress = true;
+            flushPendingMidTurnInject();
             let useOpencodeSessionId = opencodeSessionId;
             let isNewOpencodeSession = !useOpencodeSessionId;
             let effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, isNewOpencodeSession, workingBranch, pullRequestUrl);
@@ -2021,6 +2111,7 @@ export async function runChimphands(opts) {
                         sessionId,
                         opencodeSessionId: id,
                     }).catch(() => { });
+                    flushPendingMidTurnInject();
                 },
                 onWorkingBranch: noteWorkingBranch,
                 postEvent: turnPostEvent,
@@ -2040,6 +2131,7 @@ export async function runChimphands(opts) {
                             sessionId,
                             opencodeSessionId: id,
                         }).catch(() => { });
+                        flushPendingMidTurnInject();
                     },
                     onWorkingBranch: noteWorkingBranch,
                     postEvent: turnPostEvent,
@@ -2047,6 +2139,9 @@ export async function runChimphands(opts) {
                 }, attachUrl);
             }
             agentTurnInProgress = false;
+            while (pendingMidTurnInject.length) {
+                queue.push(pendingMidTurnInject.shift());
+            }
             await poster.flush();
             if (result.opencodeSessionId) {
                 opencodeSessionId = result.opencodeSessionId;

package/dist/cli/program.js

@@ -292,6 +292,48 @@ export function buildCliProgram() {
         const out = await runTool("fetch-execution-report", merged, { postMcp });
         console.log(out);
     });
+    program
+        .command("upload-attachment")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "upload-attachment").description)
+        .addOption(jsonInputOption())
+        .option("--file <path>", "Path to file to upload (e.g. screenshot PNG)")
+        .option("--filename <name>", "Original filename for extension inference")
+        .option("--content-type <type>", "MIME type (default application/octet-stream)")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.file)
+            body.file = String(opts.file);
+        if (opts.filename)
+            body.filename = String(opts.filename);
+        if (opts.contentType)
+            body.contentType = String(opts.contentType);
+        const merged = mergeBodies(body, opts.jsonInput);
+        if (!merged.file || String(merged.file).trim() === "") {
+            throw new Error("file is required (--file)");
+        }
+        const out = await runTool("upload-attachment", {
+            file: String(merged.file).trim(),
+            ...(merged.filename ? { filename: String(merged.filename) } : {}),
+            ...(merged.contentType ? { contentType: String(merged.contentType) } : {}),
+        }, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-batch-view-url")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-batch-view-url").description)
+        .addOption(jsonInputOption())
+        .option("--batch-invocation-id <id>", "Batch invocation id")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.batchInvocationId)
+            body.batchInvocationId = String(opts.batchInvocationId);
+        const merged = mergeBodies(body, opts.jsonInput);
+        if (!merged.batchInvocationId || String(merged.batchInvocationId).trim() === "") {
+            throw new Error("batchInvocationId is required (--batch-invocation-id)");
+        }
+        const out = await runTool("get-batch-view-url", { batchInvocationId: String(merged.batchInvocationId).trim() }, { postMcp });
+        console.log(out);
+    });
     addAgentTraceabilityOptions(program
         .command("create-user-story")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-user-story").description)

package/dist/core/schemas.d.ts

@@ -1972,3 +1972,13 @@ export declare const listApiOperationInteractionsInput: z.ZodObject<{
     }>>;
     limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
+/** Max decoded upload size for agent evidence (matches backend ExploreSnapsPathUtil). */
+export declare const MAX_AGENT_ATTACHMENT_BYTES: number;
+export declare const uploadAttachmentInput: z.ZodObject<{
+    file: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const getBatchViewUrlInput: z.ZodObject<{
+    batchInvocationId: z.ZodString;
+}, z.core.$strip>;

package/dist/core/schemas.js

@@ -990,3 +990,13 @@ export const listApiOperationInteractionsInput = z
         });
     }
 });
+/** Max decoded upload size for agent evidence (matches backend ExploreSnapsPathUtil). */
+export const MAX_AGENT_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export const uploadAttachmentInput = z.object({
+    file: z.string().min(1),
+    filename: z.string().min(1).optional(),
+    contentType: z.string().min(1).optional(),
+});
+export const getBatchViewUrlInput = z.object({
+    batchInvocationId: z.string().min(1),
+});

package/dist/core/tools.js

@@ -1467,6 +1467,43 @@ export const TOOL_DEFINITIONS = [
             return postMcp("/api/mcp/list_api_operation_interactions", body);
         },
     },
+    {
+        kebab: "upload-attachment",
+        description: "Upload a file (e.g. agent screenshot evidence) to explore-snaps and return a stable view URL. " +
+            "Pass --file <path>; optional --filename and --content-type. Response includes viewUrl to paste in chat.",
+        inputSchema: S.uploadAttachmentInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const { readFile, stat } = await import("node:fs/promises");
+            const { basename } = await import("node:path");
+            const fileStat = await stat(a.file);
+            if (fileStat.size > S.MAX_AGENT_ATTACHMENT_BYTES) {
+                throw new Error(`File exceeds maximum size of ${S.MAX_AGENT_ATTACHMENT_BYTES} bytes (${fileStat.size} bytes)`);
+            }
+            const bytes = await readFile(a.file);
+            const body = {
+                fileBase64: bytes.toString("base64"),
+            };
+            const filename = a.filename?.trim() || basename(a.file);
+            if (filename)
+                body.filename = filename;
+            if (a.contentType?.trim())
+                body.contentType = a.contentType.trim();
+            return postMcp("/api/mcp/upload_attachment", body);
+        },
+    },
+    {
+        kebab: "get-batch-view-url",
+        description: "Resolve the TestChimp batch execution viewer deeplink for the authenticated project. " +
+            "Pass --batch-invocation-id. Returns batchViewUrl for messaging back to the user.",
+        inputSchema: S.getBatchViewUrlInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/get_batch_view_url", {
+                batchInvocationId: a.batchInvocationId.trim(),
+            });
+        },
+    },
 ];
 const TOOL_BY_KEBAB = new Map(TOOL_DEFINITIONS.map((t) => [t.kebab, t]));
 export function getToolDefinition(kebab) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage, API operations (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",
@@ -13,6 +13,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test dist/chimphands/llmRetryProxy.test.js",
     "watch": "tsc --watch",
     "start": "node dist/bin/testchimp.js",
     "prepublishOnly": "npm run build"