@testchimp/cli 0.1.66 → 0.1.68

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/midTurnSteering.d.ts

@@ -0,0 +1,25 @@
+/** Helpers for mid-turn user steering via OpenCode prompt_async. */
+export type OpencodeSessionMessage = {
+    info?: {
+        id?: string;
+        role?: string;
+    };
+    parts?: Array<{
+        type?: string;
+        text?: string;
+        state?: {
+            status?: string;
+        };
+    }>;
+};
+export declare function normalizeSteeringContent(content: string): string;
+export declare function midTurnSteeringKey(id: string | undefined, content: string): string;
+export declare function extractUserMessageText(msg: OpencodeSessionMessage): string;
+/** True when an assistant message after the matching user text has substantive output. */
+export declare function userMessageHasAssistantReply(messages: OpencodeSessionMessage[], userContent: string): boolean;
+export declare function fetchOpencodeSessionMessages(attachUrl: string, opencodeSessionId: string, cwd?: string): Promise<OpencodeSessionMessage[]>;
+/**
+ * After a turn ends, re-queue mid-turn steering messages that prompt_async accepted
+ * but OpenCode never answered (e.g. blocked on long-running bash).
+ */
+export declare function releaseUnansweredMidTurnMessages(attachUrl: string, opencodeSessionId: string, midTurnInjected: Map<string, string>, queue: string[], wake: () => void, sidecarAnsweredKeys?: Set<string>): Promise<void>;

package/dist/chimphands/midTurnSteering.js

@@ -0,0 +1,93 @@
+/** Helpers for mid-turn user steering via OpenCode prompt_async. */
+export function normalizeSteeringContent(content) {
+    return content.trim();
+}
+export function midTurnSteeringKey(id, content) {
+    const norm = normalizeSteeringContent(content);
+    return id?.trim() || `content:${norm}`;
+}
+export function extractUserMessageText(msg) {
+    return (msg.parts || [])
+        .filter((p) => p.type === "text" && p.text?.trim())
+        .map((p) => p.text.trim())
+        .join("\n");
+}
+/** True when an assistant message after the matching user text has substantive output. */
+export function userMessageHasAssistantReply(messages, userContent) {
+    const normalizedTarget = normalizeSteeringContent(userContent);
+    if (!normalizedTarget)
+        return true;
+    let userIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const role = (messages[i]?.info?.role || "").toLowerCase();
+        if (role !== "user")
+            continue;
+        const text = normalizeSteeringContent(extractUserMessageText(messages[i]));
+        if (text === normalizedTarget) {
+            userIdx = i;
+            break;
+        }
+    }
+    if (userIdx < 0)
+        return false;
+    for (let i = userIdx + 1; i < messages.length; i++) {
+        const role = (messages[i]?.info?.role || "").toLowerCase();
+        if (role !== "assistant")
+            continue;
+        const hasText = (messages[i]?.parts || []).some((p) => (p.type === "text" || p.type === "reasoning") && p.text?.trim());
+        const hasCompletedTool = (messages[i]?.parts || []).some((p) => p.type === "tool" && p.state?.status === "completed");
+        if (hasText || hasCompletedTool)
+            return true;
+    }
+    return false;
+}
+export async function fetchOpencodeSessionMessages(attachUrl, opencodeSessionId, cwd = process.cwd()) {
+    const base = attachUrl.replace(/\/$/, "");
+    const url = `${base}/session/${encodeURIComponent(opencodeSessionId)}/message`;
+    const res = await fetch(url, {
+        headers: { Accept: "application/json", "x-opencode-directory": cwd },
+    });
+    if (!res.ok) {
+        throw new Error(`OpenCode session messages HTTP ${res.status}`);
+    }
+    const data = (await res.json());
+    return Array.isArray(data) ? data : [];
+}
+/**
+ * After a turn ends, re-queue mid-turn steering messages that prompt_async accepted
+ * but OpenCode never answered (e.g. blocked on long-running bash).
+ */
+export async function releaseUnansweredMidTurnMessages(attachUrl, opencodeSessionId, midTurnInjected, queue, wake, sidecarAnsweredKeys = new Set()) {
+    if (!midTurnInjected.size)
+        return;
+    let messages = [];
+    try {
+        messages = await fetchOpencodeSessionMessages(attachUrl, opencodeSessionId);
+    }
+    catch (err) {
+        console.error(`ChimpHands mid-turn steering check failed — queueing unanswered injected messages: ${err instanceof Error ? err.message : String(err)}`);
+        for (const [key, content] of midTurnInjected.entries()) {
+            if (sidecarAnsweredKeys.has(key))
+                continue;
+            queue.push(content);
+        }
+        midTurnInjected.clear();
+        wake();
+        return;
+    }
+    for (const [key, content] of midTurnInjected.entries()) {
+        if (sidecarAnsweredKeys.has(key)) {
+            console.error(`ChimpHands mid-turn steering message ${key} answered by sidecar — no re-queue`);
+            continue;
+        }
+        if (userMessageHasAssistantReply(messages, content)) {
+            console.error(`ChimpHands mid-turn steering message ${key} was answered in-session — no re-queue`);
+            continue;
+        }
+        console.error(`ChimpHands mid-turn steering message ${key} unanswered — queueing for next turn`);
+        queue.push(content);
+    }
+    midTurnInjected.clear();
+    if (queue.length)
+        wake();
+}

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

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

package/dist/chimphands/midTurnSteering.test.js

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { userMessageHasAssistantReply, } from "./midTurnSteering.js";
+function userMsg(text) {
+    return { info: { role: "user" }, parts: [{ type: "text", text }] };
+}
+function assistantText(text) {
+    return { info: { role: "assistant" }, parts: [{ type: "text", text }] };
+}
+function assistantTool(status) {
+    return {
+        info: { role: "assistant" },
+        parts: [{ type: "tool", state: { status } }],
+    };
+}
+describe("userMessageHasAssistantReply", () => {
+    it("returns false when user message has no assistant reply after it", () => {
+        const messages = [userMsg("why gcp_sa_json_path?")];
+        assert.equal(userMessageHasAssistantReply(messages, "why gcp_sa_json_path?"), false);
+    });
+    it("returns true when assistant text follows the matching user message", () => {
+        const messages = [
+            userMsg("first question"),
+            assistantText("first answer"),
+            userMsg("why gcp_sa_json_path?"),
+            assistantText("We should use WIF in CI."),
+        ];
+        assert.equal(userMessageHasAssistantReply(messages, "why gcp_sa_json_path?"), true);
+    });
+    it("matches the latest user message with the same content", () => {
+        const messages = [
+            userMsg("repeat"),
+            assistantText("old answer"),
+            userMsg("repeat"),
+        ];
+        assert.equal(userMessageHasAssistantReply(messages, "repeat"), false);
+    });
+    it("counts completed tool output as a reply", () => {
+        const messages = [userMsg("check auth"), assistantTool("completed")];
+        assert.equal(userMessageHasAssistantReply(messages, "check auth"), true);
+    });
+    it("ignores pending tool parts as a reply", () => {
+        const messages = [userMsg("run tests"), assistantTool("running")];
+        assert.equal(userMessageHasAssistantReply(messages, "run tests"), false);
+    });
+});

package/dist/chimphands/run.js

@@ -11,6 +11,9 @@ 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";
+import { midTurnSteeringKey, releaseUnansweredMidTurnMessages, } from "./midTurnSteering.js";
+import { runSteeringSidecarReply } from "./steeringSidecar.js";
 const ROLE_ASSISTANT = "CHIMPHANDS_MESSAGE_ROLE_ASSISTANT";
 const ROLE_TOOL = "CHIMPHANDS_MESSAGE_ROLE_TOOL";
 const ROLE_REASONING = "CHIMPHANDS_MESSAGE_ROLE_REASONING";
@@ -20,6 +23,7 @@ const STATUS_WAITING_USER = "CHIMPHANDS_SESSION_STATUS_WAITING_USER";
 const STATUS_IDLE = "CHIMPHANDS_SESSION_STATUS_IDLE";
 const STATUS_FAILED = "CHIMPHANDS_SESSION_STATUS_FAILED";
 const OPENCODE_AGENT_ID = "chimphands";
+const MID_TURN_DELIVERED_STATUS = "Answering your question while the current step continues…";
 /** Coalesce live token fanout (~6–10 posts/s/session) while UI is attached. */
 const STREAM_POST_MIN_INTERVAL_MS = 150;
 function isStreamFanoutRole(role) {
@@ -83,6 +87,11 @@ const CHIMPHANDS_AGENT_PROMPT = `You are ChimpHands, TestChimp's coding agent. Y
 - Follow plan → explicit user approval → execute (interactive default). Do not skip MCP calls or claim done without tool evidence.
 - Export \`TESTCHIMP_EXECUTION_SOURCE=CLOUD_AGENT\` before Playwright/Mobilewright runs.
 
+## CI runner hygiene (GitHub Actions)
+- On hosted runners: load skill \`references/chimphands-ci-runner.md\` before compile, Docker builds, or large installs.
+- Never \`git fetch origin\` (full fetch) — shallow single-branch fetch only; branch names are in \`.chimphands/remote-branch-names.txt\`.
+- Reclaim disk between heavy phases (\`docker builder prune -af\` after image builds, stop compile daemons, delete temp/test artifacts). One reclaim+retry on ENOSPC — no blind loops.
+
 ## Honesty
 - If MCP/tools fail, report the error. Never narrate success without tool output or a PR link when repo changes were needed.`;
 function normalizeUserMessage(content) {
@@ -179,7 +188,7 @@ class AgentEventPoster {
         if (opts?.pullRequestUrl)
             body.pullRequestUrl = opts.pullRequestUrl;
         if (opts?.toolExecution)
-            body.toolExecution = opts.toolExecution;
+            body.toolExecution = protoJsonToolExecution(opts.toolExecution);
         const streamRole = isStreamFanoutRole(role);
         this.chain = this.chain.then(async () => {
             const live = !!opts?.liveStream && !opts?.durable;
@@ -206,7 +215,7 @@ class AgentEventPoster {
                 if (opts?.opencodeSessionId)
                     eph.opencodeSessionId = opts.opencodeSessionId;
                 if (opts?.toolExecution)
-                    eph.toolExecution = opts.toolExecution;
+                    eph.toolExecution = protoJsonToolExecution(opts.toolExecution);
                 try {
                     await postJson(this.backend, this.apiKey, "/api/chimphands/post_ephemeral_agent_event", eph);
                     this.ephemeralFailCount = 0;
@@ -307,14 +316,44 @@ function normalizeEpochMillis(raw) {
     return raw < 1_000_000_000_000 ? Math.round(raw * 1000) : Math.round(raw);
 }
 function coerceTimeoutMillis(input) {
-    if (!input)
+    if (input == null)
+        return undefined;
+    let obj;
+    if (typeof input === "string") {
+        try {
+            const parsed = JSON.parse(input);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                obj = parsed;
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else {
+        obj = input;
+    }
+    if (!obj)
         return undefined;
-    const raw = input.timeout ?? input.timeoutMs ?? input.timeout_ms;
+    const raw = obj.timeout ?? obj.timeoutMs ?? obj.timeout_ms;
     const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN;
     if (!Number.isFinite(n) || n <= 0)
         return undefined;
     return Math.round(n);
 }
+/** Protobuf JSON encodes int64 as strings; numbers can fail JsonFormat.parse. */
+function protoJsonToolExecution(payload) {
+    const out = { status: payload.status };
+    if (payload.toolName)
+        out.toolName = payload.toolName;
+    if (payload.startedAtMillis != null)
+        out.startedAtMillis = String(payload.startedAtMillis);
+    if (payload.timeoutMillis != null)
+        out.timeoutMillis = String(payload.timeoutMillis);
+    if (payload.endedAtMillis != null)
+        out.endedAtMillis = String(payload.endedAtMillis);
+    return out;
+}
 function mapToolExecutionStatus(status) {
     const s = String(status || "").trim().toLowerCase();
     if (!s)
@@ -960,8 +999,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 +1021,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 +1096,37 @@ 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({
+                agent: OPENCODE_AGENT_ID,
+                noReply: false,
+                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 +1806,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}`);
@@ -1768,15 +1851,19 @@ export async function runChimphands(opts) {
     const idleMs = (bootNum(boot, "idle_timeout_seconds", "idleTimeoutSeconds") || 600) * 1000;
     const queue = [];
     const seenUserMessageIds = new Set();
+    /** Mid-turn prompt_async successes that may need a follow-up turn if OpenCode never answered. */
+    const midTurnInjectedById = new Map();
+    /** Steering keys answered by the parallel child-session sidecar. */
+    const midTurnSidecarAnswered = new Set();
     let idle = false;
     let sessionActive = true;
     let lastUserActivity = Date.now();
     let exitCode;
     let cancelTurnRequested = false;
-    /** True when cancel was triggered by a mid-turn user message (steer), not Stop. */
-    let steerAbortRequested = 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 = () => {
@@ -1791,11 +1878,8 @@ export async function runChimphands(opts) {
         },
     };
     /** Abort in-flight OpenCode turn (session HTTP abort + kill `opencode run` child). */
-    const abortActiveTurn = (reason) => {
+    const abortActiveTurn = () => {
         cancelTurnRequested = true;
-        if (reason === "steer") {
-            steerAbortRequested = true;
-        }
         const sessionToAbort = opencodeSessionId?.trim();
         if (attachUrl && sessionToAbort) {
             void abortOpencodeSession(attachUrl, sessionToAbort);
@@ -1819,6 +1903,60 @@ export async function runChimphands(opts) {
             }
         }
     };
+    const noteMidTurnInjectSuccess = (steeringKey, content) => {
+        midTurnInjectedById.set(steeringKey, normalizeUserMessage(content));
+    };
+    const deliverMidTurnSteeringSidecar = (steeringKey, content) => {
+        const parentSessionId = opencodeSessionId?.trim();
+        if (!attachUrl || !parentSessionId)
+            return;
+        void runSteeringSidecarReply({
+            attachUrl,
+            parentSessionId,
+            userQuestion: content,
+            conversationSummary,
+            model: opencodeModel,
+            agentId: OPENCODE_AGENT_ID,
+        })
+            .then((replyParts) => {
+            if (!replyParts.length) {
+                console.error(`ChimpHands steering sidecar returned no text for ${steeringKey}`);
+                return;
+            }
+            midTurnSidecarAnswered.add(steeringKey);
+            for (const text of replyParts) {
+                postEvent(ROLE_ASSISTANT, text, {
+                    durable: true,
+                    opencodeSessionId: parentSessionId,
+                    messageId: `ch_steering_${steeringKey}_${Date.now()}`,
+                });
+            }
+            console.error(`ChimpHands steering sidecar answered mid-turn message ${steeringKey} (${replyParts.length} part(s))`);
+        })
+            .catch((err) => {
+            console.error(`ChimpHands steering sidecar failed for ${steeringKey}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    const flushPendingMidTurnInject = () => {
+        if (!attachUrl || !agentTurnInProgress)
+            return;
+        const sessionToInject = opencodeSessionId?.trim();
+        if (!sessionToInject)
+            return;
+        while (pendingMidTurnInject.length) {
+            const content = pendingMidTurnInject.shift();
+            const steeringKey = midTurnSteeringKey(undefined, content);
+            void injectOpencodeUserMessage(attachUrl, sessionToInject, content).then((ok) => {
+                if (!ok) {
+                    queue.push(content);
+                    wakePromptWaiter();
+                    return;
+                }
+                noteMidTurnInjectSuccess(steeringKey, content);
+                deliverMidTurnSteeringSidecar(steeringKey, content);
+            });
+        }
+    };
     const enqueueUserMessage = (msg) => {
         const id = msg.id?.trim();
         if (id) {
@@ -1829,17 +1967,32 @@ export async function runChimphands(opts) {
         const content = normalizeUserMessage(msg.content || "");
         if (!content)
             return;
-        queue.push(content);
         lastUserActivity = Date.now();
         idle = false;
         const preview = content.length > 120 ? `${content.slice(0, 117)}...` : content;
-        console.error(`ChimpHands queued user message (turnActive=${agentTurnInProgress}, depth=${queue.length}): ${JSON.stringify(preview)}`);
-        // OpenCode has no mid-turn inject: abort the active turn so the queued
-        // message is consumed immediately as the next prompt (course-correct).
-        if (agentTurnInProgress && !cancelTurnRequested) {
-            console.error(`ChimpHands steering: aborting active turn so queued user message reaches OpenCode`);
-            abortActiveTurn("steer");
+        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)}`);
+                const steeringKey = midTurnSteeringKey(id, content);
+                void injectOpencodeUserMessage(attachUrl, sessionToInject, content).then((ok) => {
+                    if (!ok) {
+                        queue.push(content);
+                        wakePromptWaiter();
+                        return;
+                    }
+                    noteMidTurnInjectSuccess(steeringKey, content);
+                    postEvent(ROLE_STATUS, MID_TURN_DELIVERED_STATUS, { status: STATUS_RUNNING });
+                    deliverMidTurnSteeringSidecar(steeringKey, content);
+                });
+                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 () => {
@@ -1906,8 +2059,7 @@ export async function runChimphands(opts) {
         childEnv.TESTCHIMP_USER_ID = userId;
     const handleCancelTurn = () => {
         console.error(`ChimpHands cancel_turn received for session ${sessionId}`);
-        steerAbortRequested = false;
-        abortActiveTurn("cancel");
+        abortActiveTurn();
     };
     const stopInbound = connectInboundStream(backend, apiKey, sessionId, {
         onUserMessage: enqueueUserMessage,
@@ -1944,6 +2096,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,
@@ -2022,21 +2180,12 @@ export async function runChimphands(opts) {
         });
         while (prompt) {
             cancelTurnRequested = false;
-            const wasSteered = steerAbortRequested;
-            steerAbortRequested = false;
             agentTurnInProgress = true;
+            flushPendingMidTurnInject();
             let useOpencodeSessionId = opencodeSessionId;
             let isNewOpencodeSession = !useOpencodeSessionId;
-            const promptForOpencode = wasSteered
-                ? [
-                    "The previous agent turn was interrupted because the user sent a new message.",
-                    "Stop any long-running watch/poll that no longer applies. Course-correct using this guidance:",
-                    "",
-                    prompt,
-                ].join("\n")
-                : prompt;
-            let effectivePrompt = wrapPromptWithContext(conversationSummary, promptForOpencode, isNewOpencodeSession, workingBranch, pullRequestUrl);
-            const turnPostEvent = (role, content, opts) => postEventForTurn(promptForOpencode, effectivePrompt, role, content, opts);
+            let effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, isNewOpencodeSession, workingBranch, pullRequestUrl);
+            const turnPostEvent = (role, content, opts) => postEventForTurn(prompt, effectivePrompt, role, content, opts);
             // Visible in chat (not filtered as routine). OpenCode may not emit text until a
             // part completes — without this the UI looks empty while the turn is running.
             postEvent(ROLE_STATUS, "Agent is working…", { status: STATUS_RUNNING });
@@ -2047,6 +2196,7 @@ export async function runChimphands(opts) {
                         sessionId,
                         opencodeSessionId: id,
                     }).catch(() => { });
+                    flushPendingMidTurnInject();
                 },
                 onWorkingBranch: noteWorkingBranch,
                 postEvent: turnPostEvent,
@@ -2066,6 +2216,7 @@ export async function runChimphands(opts) {
                             sessionId,
                             opencodeSessionId: id,
                         }).catch(() => { });
+                        flushPendingMidTurnInject();
                     },
                     onWorkingBranch: noteWorkingBranch,
                     postEvent: turnPostEvent,
@@ -2073,6 +2224,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;
@@ -2100,6 +2254,14 @@ export async function runChimphands(opts) {
             if (!poster.uiAttached) {
                 await commitAndPushDirtyWorktree("chimphands: commit after turn (async / no UI attached)");
             }
+            if (attachUrl && opencodeSessionId && midTurnInjectedById.size) {
+                try {
+                    await releaseUnansweredMidTurnMessages(attachUrl, opencodeSessionId, midTurnInjectedById, queue, wakePromptWaiter, midTurnSidecarAnswered);
+                }
+                catch (err) {
+                    console.error(`ChimpHands mid-turn steering release failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             if (result.code !== 0 && !result.cancelled) {
                 const errMsg = (result.err || "opencode failed").trim() || "opencode failed";
                 console.error(`ChimpHands OpenCode failed: ${errMsg}`);
@@ -2124,11 +2286,7 @@ export async function runChimphands(opts) {
                 exitCode = result.code || 1;
                 break;
             }
-            if (result.cancelled && (steerAbortRequested || queue.length > 0)) {
-                // Mid-turn user message aborted this turn — run the queued prompt next.
-                postEvent(ROLE_STATUS, "Incorporating your message…", { status: STATUS_RUNNING });
-            }
-            else if (result.cancelled) {
+            if (result.cancelled) {
                 postEvent(ROLE_STATUS, "Turn stopped", { status: STATUS_WAITING_USER });
             }
             else {

package/dist/chimphands/steeringSidecar.d.ts

@@ -0,0 +1,40 @@
+/** Parallel OpenCode child-session turn for mid-turn steering Q&A. */
+export type OpencodeModelRef = {
+    providerID: string;
+    modelID: string;
+};
+export declare function parseOpencodeModelRef(model: string): OpencodeModelRef | undefined;
+export declare function buildSteeringSidecarPrompt(userQuestion: string, conversationSummary: string): string;
+type OpencodeMessagePart = {
+    type?: string;
+    text?: string;
+    state?: {
+        status?: string;
+        output?: string;
+    };
+};
+type OpencodeMessageResponse = {
+    info?: {
+        role?: string;
+        id?: string;
+    };
+    parts?: OpencodeMessagePart[];
+};
+export declare function extractAssistantReplyParts(response: OpencodeMessageResponse): string[];
+export type SteeringSidecarOptions = {
+    attachUrl: string;
+    parentSessionId: string;
+    userQuestion: string;
+    conversationSummary?: string;
+    model: string;
+    agentId: string;
+    cwd?: string;
+    /** Max wait for the child-session /message round-trip. */
+    timeoutMs?: number;
+};
+/**
+ * Run a parallel OpenCode turn on a child session so the user gets an immediate
+ * answer while the main session stays blocked on a long-running tool.
+ */
+export declare function runSteeringSidecarReply(opts: SteeringSidecarOptions): Promise<string[]>;
+export {};

package/dist/chimphands/steeringSidecar.js

@@ -0,0 +1,103 @@
+/** Parallel OpenCode child-session turn for mid-turn steering Q&A. */
+export function parseOpencodeModelRef(model) {
+    const trimmed = model.trim();
+    if (!trimmed)
+        return undefined;
+    const slash = trimmed.indexOf("/");
+    if (slash <= 0 || slash >= trimmed.length - 1)
+        return undefined;
+    return {
+        providerID: trimmed.slice(0, slash),
+        modelID: trimmed.slice(slash + 1),
+    };
+}
+export function buildSteeringSidecarPrompt(userQuestion, conversationSummary) {
+    const summary = conversationSummary.trim();
+    const parts = [
+        "Mid-turn steering reply — the main ChimpHands session is still running a long command in parallel.",
+        "Answer the user's question directly and concisely.",
+        "Do NOT run bash/shell, edit files, or kick off long tools. Read-only lookup is OK if needed.",
+        "Do not repeat the full plan; focus on the question.",
+    ];
+    if (summary) {
+        parts.push("", "Conversation so far:", summary);
+    }
+    parts.push("", "User question:", userQuestion.trim());
+    return parts.join("\n");
+}
+export function extractAssistantReplyParts(response) {
+    const role = (response.info?.role || "").toLowerCase();
+    if (role && role !== "assistant")
+        return [];
+    const out = [];
+    for (const part of response.parts || []) {
+        if (part.type === "text" && part.text?.trim()) {
+            out.push(part.text.trim());
+        }
+    }
+    return out;
+}
+async function opencodeFetch(attachUrl, path, init, cwd) {
+    const base = attachUrl.replace(/\/$/, "");
+    return fetch(`${base}${path}`, {
+        ...init,
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "x-opencode-directory": cwd,
+            ...init.headers,
+        },
+    });
+}
+async function createSteeringChildSession(attachUrl, parentSessionId, cwd) {
+    const res = await opencodeFetch(attachUrl, "/session", {
+        method: "POST",
+        body: JSON.stringify({
+            parentID: parentSessionId,
+            title: "ChimpHands steering",
+        }),
+    }, cwd);
+    if (!res.ok) {
+        throw new Error(`OpenCode create steering session HTTP ${res.status}`);
+    }
+    const data = (await res.json());
+    const childId = data.id?.trim();
+    if (!childId)
+        throw new Error("OpenCode create steering session returned no id");
+    return childId;
+}
+/**
+ * Run a parallel OpenCode turn on a child session so the user gets an immediate
+ * answer while the main session stays blocked on a long-running tool.
+ */
+export async function runSteeringSidecarReply(opts) {
+    const cwd = opts.cwd || process.cwd();
+    const childSessionId = await createSteeringChildSession(opts.attachUrl, opts.parentSessionId, cwd);
+    const modelRef = parseOpencodeModelRef(opts.model);
+    const prompt = buildSteeringSidecarPrompt(opts.userQuestion, opts.conversationSummary || "");
+    const timeoutMs = opts.timeoutMs ?? 120_000;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const body = {
+            agent: opts.agentId,
+            noReply: false,
+            parts: [{ type: "text", text: prompt }],
+        };
+        if (modelRef)
+            body.model = modelRef;
+        const res = await opencodeFetch(opts.attachUrl, `/session/${encodeURIComponent(childSessionId)}/message`, {
+            method: "POST",
+            body: JSON.stringify(body),
+            signal: ac.signal,
+        }, cwd);
+        if (!res.ok) {
+            throw new Error(`OpenCode steering /message HTTP ${res.status}`);
+        }
+        const data = (await res.json());
+        return extractAssistantReplyParts(data);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

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

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

package/dist/chimphands/steeringSidecar.test.js

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { buildSteeringSidecarPrompt, extractAssistantReplyParts, parseOpencodeModelRef, } from "./steeringSidecar.js";
+describe("parseOpencodeModelRef", () => {
+    it("splits provider/model", () => {
+        assert.deepEqual(parseOpencodeModelRef("testchimp/gpt-5.6-luna"), {
+            providerID: "testchimp",
+            modelID: "gpt-5.6-luna",
+        });
+    });
+});
+describe("buildSteeringSidecarPrompt", () => {
+    it("includes summary and user question", () => {
+        const prompt = buildSteeringSidecarPrompt("why WIF?", "Prior: discussed CI auth.");
+        assert.match(prompt, /why WIF\?/);
+        assert.match(prompt, /Prior: discussed CI auth\./);
+        assert.match(prompt, /Do NOT run bash/);
+    });
+});
+describe("extractAssistantReplyParts", () => {
+    it("returns text parts from assistant message", () => {
+        const parts = extractAssistantReplyParts({
+            info: { role: "assistant" },
+            parts: [{ type: "text", text: "Use WIF in CI." }],
+        });
+        assert.deepEqual(parts, ["Use WIF in CI."]);
+    });
+});

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.66",
+  "version": "0.1.68",
   "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 dist/chimphands/midTurnSteering.test.js dist/chimphands/steeringSidecar.test.js",
     "watch": "tsc --watch",
     "start": "node dist/bin/testchimp.js",
     "prepublishOnly": "npm run build"