atom-agent 1.4.0 → 1.5.1

package/dist/zen.js

@@ -5,11 +5,11 @@
 // different Zen request shapes and are out of scope.
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
-import { MAX_TOOL_STEPS, allToolDefinitions, getExtensionPromptHints, } from "./tools.js";
+import { MAX_TOOL_STEPS, allToolDefinitions, chatToolDefinitions, getExtensionPromptHints, } from "./tools.js";
 import { chatEndpointFor, getProvider, isLocalProviderId, modelsUrlForProvider, providerLabel, } from "./providers.js";
 import { discoverLocalProvider } from "./local-discovery.js";
-import { ANTHROPIC_MAX_TOKENS, ANTHROPIC_VERSION, anthropicHeaders, anthropicThinkingFor, buildAnthropicBody, buildGeminiBody, geminiChatUrl, geminiGenerateUrl, geminiHeaders, geminiThinkingLevelFor, isEffortRejection, parseAnthropicJson, parseAnthropicModelsList, parseGeminiJson, parseGeminiModelsList, parseOpenAIModelsList, readAnthropicSSEMessage, readGeminiSSEMessage, isStallError, readWithStall, sseStallTimeoutMs, } from "./adapters.js";
-export { isStallError, readWithStall, sseStallTimeoutMs } from "./adapters.js";
+import { ANTHROPIC_MAX_TOKENS, ANTHROPIC_VERSION, anthropicHeaders, anthropicThinkingFor, buildAnthropicBody, buildGeminiBody, geminiChatUrl, geminiGenerateUrl, geminiHeaders, geminiThinkingLevelFor, isEffortRejection, parseAnthropicJson, parseAnthropicModelsList, parseGeminiJson, parseGeminiModelsList, parseOpenAIModelsList, readAnthropicSSEMessage, readGeminiSSEMessage, buildResponsesBody, isResponsesEffortRejection, isStallError, parseResponsesObject, readResponsesSSEMessage, readWithStall, sseHeaderTimeoutMs, sseStallTimeoutMs, zenHeaders, zenRequestId, } from "./adapters.js";
+export { isStallError, readWithStall, sseHeaderTimeoutMs, sseStallTimeoutMs, ZEN_CLIENT_UA, zenHeaders, zenRequestId, zenSessionId } from "./adapters.js";
 import { KILO_FALLBACK_MODELS, fetchKiloModelsWithStatus, normalizeKiloChatError, } from "./kilo.js";
 import { splitSystemHead } from "./prompt-cache.js";
 import { SYSTEM_PROMPT } from "./system.js";
@@ -86,6 +86,19 @@ export function reasoningEffortParam(effort, _model) {
         return undefined;
     return normalized;
 }
+// Wire value for the Responses `reasoning.effort` knob, or undefined when
+// the param must be omitted (Auto, or an unknown effort string). Max maps
+// to high — the deepest widely-supported level (same precedent as the
+// Gemini thinkingLevel mapping in adapters.ts).
+export function responsesEffortParam(effort) {
+    const normalized = normalizeEffort(effort);
+    if (normalized === "auto")
+        return undefined;
+    if (normalized === "max")
+        return "high";
+    return normalized;
+}
+import { historyHasMedia, isImageRejection, lowerOpenAIContent, } from "./media.js";
 export { CHARS_PER_TOKEN, createContextManager, estimateTokensForChars, historyChars, messageChars, } from "./context-manager.js";
 export { openTodoNeedles } from "./agent/gates.js";
 function finiteCount(value) {
@@ -170,9 +183,25 @@ export { isCancelError, LoopCancelledError } from "./agent/loop.js";
 // Retry-After) and weak-network throws both ride this policy. Cancellation
 // never retries. Delays grow exponentially under a 30s cap, so a fully dead
 // endpoint costs ~3.5min worst case before the turn fails loudly.
+// 524/529 added for opencode parity (Cloudflare / overloaded gateways).
 export const MAX_RETRIES = 10;
-const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504, 524, 529]);
 const RETRY_AFTER_CAP_MS = 30_000;
+// Per-model-call deadline (opencode options.timeout parity): bounds a single
+// chat POST including streaming. Env ATOM_MODEL_TIMEOUT_MS, default 300s
+// (matches opencode header/chunk defaults), max-clamped to 10min. Caller
+// combines with the user-cancel signal per attempt via AbortSignal.any.
+export const DEFAULT_MODEL_TIMEOUT_MS = 300_000;
+export const MAX_MODEL_TIMEOUT_MS = 600_000;
+export function modelTimeoutMs() {
+    const raw = process.env.ATOM_MODEL_TIMEOUT_MS;
+    if (raw !== undefined) {
+        const n = Number(raw.trim());
+        if (Number.isFinite(n) && n > 0)
+            return Math.min(Math.floor(n), MAX_MODEL_TIMEOUT_MS);
+    }
+    return DEFAULT_MODEL_TIMEOUT_MS;
+}
 export function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -220,15 +249,23 @@ function hasStreamBody(res) {
         return false;
     }
 }
-// Curated chat/completions-compatible models, verified from
-// https://opencode.ai/docs/zen. Used when the live model list cannot be
-// fetched or cannot confirm compatibility (network/auth/429/shape issues).
+// Curated Zen models, verified from https://opencode.ai/docs/zen + the live
+// /models list. Used when the live list cannot be fetched or cannot confirm
+// compatibility (network/auth/429/shape issues). Covers both wire families:
+// chat/completions (default transport) and responses-family (muse-spark-*,
+// served from /responses — see isZenResponsesModel); the live filter below
+// accepts ids from either set, the dispatcher routes by family.
 export const FALLBACK_MODELS = [
     "big-pickle",
     "mimo-v2.5-free",
     "ling-3.0-flash-fin-free",
     "nemotron-3-ultra-free",
     "nemotron-3.5-lightning-free",
+    "deepseek-v4-flash-free",
+    "muse-spark-1.3-contributor-free",
+    "muse-spark-1.2-contributor-free",
+    "muse-spark-1.3",
+    "muse-spark-1.2",
     "deepseek-v4-pro",
     "deepseek-v4-flash",
     "deepseek-v4-flash-vision-exp",
@@ -244,6 +281,26 @@ export const FALLBACK_MODELS = [
     "minimax-m2.7",
     "minimax-m3",
 ];
+// Responses-family model prefixes: these ids are served from Zen's
+// /responses endpoint (OpenAI Responses API shape), not /chat/completions.
+// Verified from the endpoint column at https://opencode.ai/docs/zen.
+const ZEN_RESPONSES_MODEL_PREFIXES = ["muse-spark-"];
+/** True when a Zen model id must ride the Responses transport. */
+export function isZenResponsesModel(model) {
+    return ZEN_RESPONSES_MODEL_PREFIXES.some((p) => model.startsWith(p));
+}
+export const RESPONSES_ENDPOINT_DEFAULT = "https://opencode.ai/zen/v1/responses";
+// Derive the /responses endpoint from a chat/completions endpoint (mirrors
+// modelsUrl above); falls back to the default when the shape is unknown.
+export function responsesEndpointFor(chatEndpoint) {
+    const suffix = "/chat/completions";
+    if (chatEndpoint.endsWith(suffix)) {
+        return chatEndpoint.slice(0, -suffix.length) + "/responses";
+    }
+    if (chatEndpoint.endsWith("/responses"))
+        return chatEndpoint;
+    return RESPONSES_ENDPOINT_DEFAULT;
+}
 export function endpointConfig() {
     return {
         endpoint: process.env.OPENCODE_ZEN_ENDPOINT ?? DEFAULT_ENDPOINT,
@@ -292,7 +349,11 @@ function entryId(entry) {
 export async function fetchModelsWithStatus(endpoint, apiKey) {
     try {
         const res = await fetch(modelsUrl(endpoint), {
-            headers: { Authorization: `Bearer ${apiKey}` },
+            // Zen client identity: free `*-free` models are gated upstream on
+            // official-client headers (UA + `x-opencode-session`, else 429/400).
+            // Anonymous-safe: zenHeaders omits Authorization when no key instead
+            // of sending `Bearer `.
+            headers: zenHeaders(apiKey),
         });
         if (!res.ok)
             return { models: [...FALLBACK_MODELS], ok: false };
@@ -394,12 +455,14 @@ export async function readSSEMessage(res, opts) {
     // while a free-tier request sits queued).
     let lastDataAt = Date.now();
     // Fail fast when the stream flows (or idles) with no model output: same
-    // permanent Truncated contract as a dead connection (passes through every
-    // catch below untouched), same env knob as the per-read byte race. Checked
+    // Truncated contract as a dead connection (stalls are retryable upstream —
+    // one retry after data, backoff for header stalls), same env knobs as the
+    // per-read byte race. Header phase (no data yet) uses the generous header
+    // budget; established streams use the tighter chunk budget. Checked
     // after each drained chunk — legitimately slow generations keep emitting
     // `data:` lines, so only true silence trips it.
     function throwIfDataStalled() {
-        const budget = sseStallTimeoutMs();
+        const budget = sawData ? sseStallTimeoutMs() : sseHeaderTimeoutMs();
         if (Date.now() - lastDataAt > budget) {
             throw new Error(`Truncated stream from model (stall: no output for ${budget}ms — queued or stalled upstream; resend to retry).`);
         }
@@ -782,7 +845,17 @@ opts, errorLabel = "Zen") {
     // Server-authoritative unsupported: when a 400 names the effort knob, the
     // flag below drops it and the loop retries without it (once per call).
     let effortDropped = false;
+    // Same contract for vision input (see src/media.ts): a 400 naming image
+    // input retries once with descriptors stripped to prose markers.
+    let mediaStripped = false;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        // Per-attempt model deadline: bounds the whole POST+stream (opencode
+        // options.timeout parity). User cancel still wins; deadline aborts map
+        // to retryable stall errors below, never to LoopCancelledError.
+        const deadlineMs = modelTimeoutMs();
+        let timedOut = false;
+        let timeoutId = null;
+        const attemptController = new AbortController();
         try {
             throwIfCancelled(signal);
             try {
@@ -795,13 +868,27 @@ opts, errorLabel = "Zen") {
                 ? undefined
                 : reasoningEffortParam(opts?.reasoningEffort, model);
             const summaryOpts = opts;
+            const mediaMode = opts?.stripMedia === true || mediaStripped
+                ? "strip"
+                : "send";
             // Stable-prefix split (prompt-cache architecture): history[0]'s env
             // tail becomes its own system message so the stable head + tools stay
             // byte-identical across POSTs for implicit prefix caching. Consecutive
             // system messages concatenate on every OpenAI-protocol server, so this
             // is content-neutral. No env tail (tests, old saves) → history passes
             // through untouched, byte-identical to before.
-            const messages = splitSystemHead(outgoingHistory);
+            // Media lowering runs after the split: histories without descriptors
+            // lower byte-identically (lowerOpenAIContent returns the string as-is).
+            const messages = splitSystemHead(outgoingHistory).map((m) => {
+                const c = m.content;
+                if (typeof c !== "string")
+                    return m;
+                const lowered = lowerOpenAIContent(m.role, c, mediaMode);
+                // Identity means untouched (no descriptors): keep the original ref
+                // so media-free payloads stay byte-identical. Anything else
+                // (stripped string or parts array) replaces the content.
+                return lowered === c ? m : { ...m, content: lowered };
+            });
             const payload = {
                 model,
                 messages,
@@ -810,9 +897,15 @@ opts, errorLabel = "Zen") {
             // Compaction path only: tools disabled means NO `tools` key at all
             // (asserted in tests); the normal loop always sends the schema —
             // builtins plus extension-registered custom tools, so the model can
-            // discover and call them exactly like builtins.
+            // discover and call them exactly like builtins. update_goal rides
+            // along only for live goal turns (includeUpdateGoal, set per POST by
+            // the runAgenticLoop* entry points) — otherwise the model cannot
+            // misuse what it cannot see.
             if (!summaryOpts?.disableTools) {
-                payload["tools"] = allToolDefinitions();
+                payload["tools"] =
+                    opts?.includeUpdateGoal === false
+                        ? chatToolDefinitions(false)
+                        : allToolDefinitions();
             }
             // Compaction path only: cap output (openai-chat kind uses max_tokens).
             if (typeof summaryOpts?.maxOutputTokens === "number" &&
@@ -822,6 +915,20 @@ opts, errorLabel = "Zen") {
             }
             if (effortParam !== undefined)
                 payload["reasoning_effort"] = effortParam;
+            // Base headers per provider: Zen sends the official-client identity
+            // (`User-Agent: opencode/*` + `x-opencode-session`/`x-opencode-request`)
+            // so free `*-free` models get quota instead of 429 FreeUsageLimitError
+            // or 400 MissingSessionID. Session is stable per process, request is
+            // fresh per POST attempt. Other openai-chat providers keep the legacy
+            // shape byte-identical. Anonymous-safe everywhere: no key omits
+            // Authorization (never `Bearer `). Pre-request hooks below can still
+            // override/delete any key (string sets, null/undefined deletes).
+            const baseHeaders = hookProvider === "opencode-zen"
+                ? zenHeaders(apiKey, { requestId: zenRequestId() })
+                : {
+                    "Content-Type": "application/json",
+                    ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+                };
             // Pre-request hooks (ticket 08) run per POST attempt: payload
             // replacement must be a record (else ignored — downstream JSON/fetch
             // handling is never bypassed); header merge honors deletions.
@@ -833,18 +940,41 @@ opts, errorLabel = "Zen") {
                     model,
                     url: endpoint,
                     payload,
-                    headers: {
-                        "Content-Type": "application/json",
-                        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
-                    },
+                    headers: { ...baseHeaders },
                 })
                 : {
                     payload,
-                    headers: {
-                        "Content-Type": "application/json",
-                        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
-                    },
+                    headers: { ...baseHeaders },
                 };
+            // Forward user cancel into the per-attempt controller, then arm the
+            // model deadline on the same controller.
+            if (signal) {
+                if (signal.aborted)
+                    throw new LoopCancelledError();
+                signal.addEventListener("abort", () => {
+                    try {
+                        attemptController.abort();
+                    }
+                    catch {
+                        // ignore
+                    }
+                }, { once: true });
+            }
+            timeoutId = setTimeout(() => {
+                timedOut = true;
+                try {
+                    attemptController.abort();
+                }
+                catch {
+                    // ignore
+                }
+            }, deadlineMs);
+            try {
+                timeoutId.unref?.();
+            }
+            catch {
+                // ignore — environments without unref proceed regardless
+            }
             const res = await fetch(endpoint, {
                 method: "POST",
                 // Anonymous-capable providers (Kilo free models) omit Authorization
@@ -853,7 +983,7 @@ opts, errorLabel = "Zen") {
                 // behavior is unchanged.
                 headers: outgoing.headers,
                 body: JSON.stringify(outgoing.payload),
-                ...(signal ? { signal } : {}),
+                signal: attemptController.signal,
             });
             // Post-response observers (ticket 08): every resolved POST (ok and
             // HTTP-error alike), fail-open — never break the turn. Zero-cost when
@@ -871,6 +1001,27 @@ opts, errorLabel = "Zen") {
             }
             if (!res.ok) {
                 const errText = await safeErrorText(res);
+                // The server is the authority on vision support: a 400 naming
+                // image input means this model/deployment takes no images — warn,
+                // strip descriptors to markers, and retry without them (once per
+                // call). Checked before effort so a joint rejection still strips.
+                if (res.status === 400 &&
+                    !mediaStripped &&
+                    opts?.stripMedia !== true &&
+                    historyHasMedia(outgoingHistory) &&
+                    isImageRejection(errText)) {
+                    mediaStripped = true;
+                    try {
+                        opts?.onWarning?.(`image input is not supported by ${model} — continuing without images`);
+                    }
+                    catch {
+                        // ignore observer errors
+                    }
+                    throwIfCancelled(signal);
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    continue;
+                }
                 // The server is the authority on effort support: a 400 naming the
                 // knob means this model/deployment has no such control — warn,
                 // drop the knob, and retry without it (setting kept). Any other
@@ -887,11 +1038,16 @@ opts, errorLabel = "Zen") {
                         // ignore observer errors
                     }
                     throwIfCancelled(signal);
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
                     continue;
                 }
                 const err = new Error(`${errorLabel} HTTP ${res.status}: ${errText.slice(0, 300)}`);
-                if (!RETRYABLE_STATUS.has(res.status))
+                if (!RETRYABLE_STATUS.has(res.status)) {
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
                     throw err;
+                }
                 if (attempt < MAX_RETRIES) {
                     throwIfCancelled(signal);
                     const delay = getRetryDelay(attempt, res);
@@ -901,11 +1057,15 @@ opts, errorLabel = "Zen") {
                     catch {
                         // ignore
                     }
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
                     await sleep(delay);
                     throwIfCancelled(signal);
                     lastError = err;
                     continue;
                 }
+                if (timeoutId)
+                    clearTimeout(timeoutId);
                 throw err;
             }
             if (!hasStreamBody(res)) {
@@ -950,26 +1110,287 @@ opts, errorLabel = "Zen") {
                 const reasoning = parseReasoningLabel(msg);
                 if (reasoning !== undefined)
                     result.reasoning = reasoning;
+                if (timeoutId)
+                    clearTimeout(timeoutId);
                 return result;
             }
-            return await readSSEMessage(res, opts);
+            try {
+                const streamed = await readSSEMessage(res, { ...opts, signal: attemptController.signal });
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                return streamed;
+            }
+            catch (streamErr) {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                throw streamErr;
+            }
         }
         catch (e) {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            // User cancel wins over deadline: only the user's own signal maps to
+            // LoopCancelledError. A deadline abort surfaces as a retryable stall.
+            if (signal?.aborted)
+                throw new LoopCancelledError();
+            if (timedOut && !(e instanceof Error && e.message.startsWith(`${errorLabel} HTTP`))) {
+                const deadlineErr = new Error(`Truncated stream from model (stall: no output for ${deadlineMs}ms — model deadline; resend to retry).`);
+                if (attempt < MAX_RETRIES) {
+                    const delay = getRetryDelay(attempt, undefined);
+                    try {
+                        opts?.onPhase?.("retry", `attempt ${attempt + 1}/${MAX_RETRIES} after ${delay}ms (model deadline ${deadlineMs}ms)`);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        await sleep(delay);
+                    }
+                    catch {
+                        // a failing sleep must not mask the original error
+                    }
+                    lastError = deadlineErr;
+                    throwIfCancelled(signal);
+                    continue;
+                }
+                throw deadlineErr;
+            }
             // Cancellations (Ctrl+C / AbortSignal) are final: never retry, never
             // reframe — propagate so the caller can roll back + show (cancelled).
-            if (isCancelError(e) || signal?.aborted)
+            if (isCancelError(e))
                 throw new LoopCancelledError();
             // HTTP failures already handled above (retry or fail-fast): rethrow
             // without treating them as retryable network errors.
             if (e instanceof Error && e.message.startsWith(`${errorLabel} HTTP`))
                 throw e;
-            // Parsing/validation failures (empty reply, truncation) are permanent:
-            // never retry, surface immediately so the caller can roll back.
+            // Empty replies are permanent: never retry, surface immediately.
+            if (e instanceof Error && e.message.startsWith("Empty reply")) {
+                throw e;
+            }
+            // Truncated streams: stall timeouts ride the normal network backoff
+            // (opencode parity — SSE read timed out is retryable); an abort with
+            // zero data gets exactly one immediate retry, then fails loudly.
+            if (e instanceof Error && e.message.startsWith("Truncated stream")) {
+                if (!isStallError(e) && attempt >= 1)
+                    throw e;
+                if (attempt < MAX_RETRIES) {
+                    const delay = getRetryDelay(attempt, undefined);
+                    try {
+                        opts?.onPhase?.("retry", `attempt ${attempt + 1}/${MAX_RETRIES} after ${delay}ms (${e.message.slice(0, 120)})`);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        await sleep(delay);
+                    }
+                    catch {
+                        // a failing sleep must not mask the original error
+                    }
+                    lastError = e;
+                    throwIfCancelled(signal);
+                    continue;
+                }
+                throw e;
+            }
+            // Anything else is a network-level throw: retry when attempts remain.
+            if (attempt < MAX_RETRIES) {
+                const delay = getRetryDelay(attempt, undefined);
+                try {
+                    opts?.onPhase?.("retry", `attempt ${attempt + 1}/${MAX_RETRIES} after ${delay}ms (${e instanceof Error ? e.message : String(e)})`);
+                }
+                catch {
+                    // ignore
+                }
+                try {
+                    await sleep(delay);
+                }
+                catch {
+                    // a failing sleep must not mask the original error
+                }
+                lastError = e;
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+// Responses-family chat POST with tools attached (tool_choice omitted, so
+// the default auto applies). Sends {model, instructions?, input, stream:true}
+// plus `reasoning: {effort}` whenever opts.reasoningEffort is non-Auto (see
+// responsesEffortParam) — for every responses model on opencode-zen.
+// A 400 naming the knob means the model truly lacks it: warn once via
+// onWarning and retry without it. Parses the Responses SSE event stream
+// (see readResponsesSSEMessage in adapters.ts).
+// Retry/rollback/hook/error-label contract mirrors chatCompletion exactly:
+// network throws and HTTP 429/500/502/503/504 retry up to MAX_RETRIES with
+// the same backoff; other 4xx fail fast as `{errorLabel} HTTP {status}`;
+// empty replies and truncated streams (no response.completed) throw
+// permanently; status "incomplete" returns with `truncated: true`.
+// Callers must roll back the user turn on failure (see App submit).
+export async function chatCompletionResponses(endpoint, apiKey, model, history, 
+// providerId (ticket 08): hook attribution for the responses transport —
+// the dispatcher passes its provider id, direct callers omit it and
+// default to "opencode-zen". Optional, wire-compatible.
+opts, errorLabel = "Zen") {
+    const sleep = opts?.sleep ?? defaultSleep;
+    const signal = opts?.signal ?? null;
+    const hookProvider = opts?.providerId ?? "opencode-zen";
+    const contextHooks = contextTransformers();
+    const outgoingHistory = contextHooks.length > 0 ? await applyContextTransform(contextHooks, history) : history;
+    let lastError = null;
+    // Server-authoritative unsupported: when a 400 names the reasoning knob,
+    // the flag below drops it and the loop retries without it (once per call).
+    let effortDropped = false;
+    // Same contract for vision input: a 400 naming image input retries once
+    // with descriptors stripped to prose markers.
+    let mediaStripped = false;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            throwIfCancelled(signal);
+            try {
+                opts?.onPhase?.("thinking");
+            }
+            catch {
+                // ignore observer errors
+            }
+            const effortParam = effortDropped
+                ? undefined
+                : responsesEffortParam(opts?.reasoningEffort);
+            const summaryOpts = opts;
+            const mediaMode = opts?.stripMedia === true || mediaStripped
+                ? "strip"
+                : "send";
+            const converted = buildResponsesBody(outgoingHistory, model, {
+                // Compaction path only: tools disabled means NO `tools` key at all;
+                // the normal loop always sends the schema so the model can discover
+                // and call tools exactly like builtins. update_goal rides along only
+                // for live goal turns (includeUpdateGoal); otherwise hidden.
+                includeTools: summaryOpts?.disableTools === true ? false : undefined,
+                includeUpdateGoal: opts?.includeUpdateGoal,
+                stripMedia: mediaMode === "strip" ? true : undefined,
+            });
+            // mediaMode is recomputed per attempt, so the strip retry below
+            // rebuilds the body in strip mode on its next pass through the loop.
+            const payload = {
+                model: converted.model,
+                ...(converted.instructions !== undefined
+                    ? { instructions: converted.instructions }
+                    : {}),
+                input: converted.input,
+                stream: true,
+            };
+            if (converted.tools !== undefined)
+                payload["tools"] = converted.tools;
+            // Compaction path only: cap output (responses kind uses
+            // max_output_tokens, same name as the cap option).
+            if (typeof summaryOpts?.maxOutputTokens === "number" &&
+                Number.isFinite(summaryOpts.maxOutputTokens) &&
+                summaryOpts.maxOutputTokens > 0) {
+                payload["max_output_tokens"] = Math.floor(summaryOpts.maxOutputTokens);
+            }
+            if (effortParam !== undefined)
+                payload["reasoning"] = { effort: effortParam };
+            const preHooks = beforeRequestInterceptors();
+            const outgoing = preHooks.length > 0
+                ? await applyBeforeRequest(preHooks, {
+                    provider: hookProvider,
+                    model,
+                    url: endpoint,
+                    payload,
+                    headers: { ...zenHeaders(apiKey, { requestId: zenRequestId() }) },
+                })
+                : {
+                    payload,
+                    headers: { ...zenHeaders(apiKey, { requestId: zenRequestId() }) },
+                };
+            const res = await fetch(endpoint, {
+                method: "POST",
+                // Anonymous-capable: zenHeaders omits Authorization when no key —
+                // never an empty `Bearer `.
+                headers: outgoing.headers,
+                body: JSON.stringify(outgoing.payload),
+                ...(signal ? { signal } : {}),
+            });
+            const postHooks = afterResponseObservers();
+            if (postHooks.length > 0) {
+                await notifyAfterResponse(postHooks, {
+                    provider: hookProvider,
+                    model,
+                    url: endpoint,
+                    status: res.status,
+                    ok: res.ok,
+                    headers: snapshotResponseHeaders(res),
+                });
+            }
+            if (!res.ok) {
+                const errText = await safeErrorText(res);
+                if (res.status === 400 &&
+                    !mediaStripped &&
+                    opts?.stripMedia !== true &&
+                    historyHasMedia(outgoingHistory) &&
+                    isImageRejection(errText)) {
+                    mediaStripped = true;
+                    try {
+                        opts?.onWarning?.(`image input is not supported by ${model} — continuing without images`);
+                    }
+                    catch {
+                        // ignore observer errors
+                    }
+                    throwIfCancelled(signal);
+                    continue;
+                }
+                if (res.status === 400 &&
+                    effortParam !== undefined &&
+                    !effortDropped &&
+                    isResponsesEffortRejection(errText)) {
+                    effortDropped = true;
+                    try {
+                        opts?.onWarning?.(`reasoning effort "${effortParam}" is not supported by ${model} — continuing without it`);
+                    }
+                    catch {
+                        // ignore observer errors
+                    }
+                    throwIfCancelled(signal);
+                    continue;
+                }
+                const err = new Error(`${errorLabel} HTTP ${res.status}: ${errText.slice(0, 300)}`);
+                if (!RETRYABLE_STATUS.has(res.status))
+                    throw err;
+                if (attempt < MAX_RETRIES) {
+                    throwIfCancelled(signal);
+                    const delay = getRetryDelay(attempt, res);
+                    try {
+                        opts?.onPhase?.("retry", `attempt ${attempt + 1}/${MAX_RETRIES} after ${delay}ms (HTTP ${res.status})`);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    await sleep(delay);
+                    throwIfCancelled(signal);
+                    lastError = err;
+                    continue;
+                }
+                throw err;
+            }
+            if (!hasStreamBody(res)) {
+                // Non-streaming responses object (no chat `choices` shape here —
+                // parseResponsesObject reads the Responses `output` array).
+                const data = await res.json();
+                return parseResponsesObject(data);
+            }
+            return await readResponsesSSEMessage(res, opts);
+        }
+        catch (e) {
+            if (isCancelError(e) || signal?.aborted)
+                throw new LoopCancelledError();
+            if (e instanceof Error && e.message.startsWith(`${errorLabel} HTTP`))
+                throw e;
             if (e instanceof Error &&
                 (e.message.startsWith("Empty reply") || e.message.startsWith("Truncated stream"))) {
                 throw e;
             }
-            // Anything else is a network-level throw: retry when attempts remain.
             if (attempt < MAX_RETRIES) {
                 const delay = getRetryDelay(attempt, undefined);
                 try {
@@ -1007,6 +1428,20 @@ opts, errorLabel = "Zen") {
 // on display). A length-truncated response (`finish_reason: "length"`) does
 // not throw: the loop fails each carried tool call inline with a repair
 // error and continues to the next model round.
+// Per-POST goal-tool visibility: update_goal rides the schema only while a
+// live goal turn is engaged (guarded — a throwing accessor reads as no
+// goal, exactly like the loop's readLiveGoal). Evaluated per POST so a goal
+// set, paused, or cleared mid-turn reshapes the very next schema; callers
+// without a goal hook (compaction, web, tests) read as no-goal and send the
+// legacy full surface only when they leave includeUpdateGoal undefined.
+function isGoalTurnLive(opts) {
+    try {
+        return opts?.goal?.getGoal?.()?.active === true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function runAgenticLoop(endpoint, apiKey, model, history, opts) {
     return runLoopWithChat((h, o) => chatCompletion(endpoint, apiKey, model, h, {
         onToken: o?.onToken,
@@ -1017,6 +1452,7 @@ export async function runAgenticLoop(endpoint, apiKey, model, history, opts) {
         sleep: o?.sleep,
         reasoningEffort: o?.reasoningEffort,
         signal: o?.signal,
+        includeUpdateGoal: isGoalTurnLive(opts),
     }), history, opts);
 }
 // AGENTS.md loading: <cwd>/AGENTS.md (or $OPENCODE_AGENTS_PATH when set)
@@ -1068,6 +1504,9 @@ export async function chatCompletionAnthropic(apiKey, model, history, opts) {
     // Same server-authoritative unsupported contract as the openai-chat path:
     // a 400 naming the thinking knob drops it for the rest of the call.
     let anthropicEffortDropped = false;
+    // Vision fallback (see src/media.ts): a 400 naming image input retries
+    // once with descriptors stripped to markers.
+    let anthropicMediaStripped = false;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
             throwIfCancelled(signal);
@@ -1080,6 +1519,8 @@ export async function chatCompletionAnthropic(apiKey, model, history, opts) {
             const summaryOpts = opts;
             const base = buildAnthropicBody(outgoingHistory, model, {
                 includeTools: !summaryOpts?.disableTools,
+                includeUpdateGoal: opts?.includeUpdateGoal !== false,
+                stripMedia: opts?.stripMedia === true || anthropicMediaStripped,
             });
             const body = { ...base, stream: true };
             // Compaction cap (anthropic kind uses max_tokens; default is already
@@ -1131,6 +1572,23 @@ export async function chatCompletionAnthropic(apiKey, model, history, opts) {
             }
             if (!res.ok) {
                 const errText = await safeErrorText(res);
+                // Vision fallback (see src/media.ts): a 400 naming image input
+                // retries once with descriptors stripped to markers.
+                if (res.status === 400 &&
+                    !anthropicMediaStripped &&
+                    opts?.stripMedia !== true &&
+                    historyHasMedia(outgoingHistory) &&
+                    isImageRejection(errText)) {
+                    anthropicMediaStripped = true;
+                    try {
+                        opts?.onWarning?.(`image input is not supported by ${model} — continuing without images`);
+                    }
+                    catch {
+                        // ignore observer errors
+                    }
+                    throwIfCancelled(signal);
+                    continue;
+                }
                 if (res.status === 400 &&
                     anthropicBudget !== undefined &&
                     !anthropicEffortDropped &&
@@ -1215,6 +1673,9 @@ export async function chatCompletionGemini(apiKey, model, history, opts) {
     // Same server-authoritative unsupported contract as the other paths: a
     // 400 naming the thinking knob drops it for the rest of the call.
     let geminiEffortDropped = false;
+    // Vision fallback (see src/media.ts): a 400 naming image input retries
+    // once with descriptors stripped to markers.
+    let geminiMediaStripped = false;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
             throwIfCancelled(signal);
@@ -1227,11 +1688,13 @@ export async function chatCompletionGemini(apiKey, model, history, opts) {
             const summaryOpts = opts;
             const body = buildGeminiBody(outgoingHistory, model, {
                 includeTools: !summaryOpts?.disableTools,
+                includeUpdateGoal: opts?.includeUpdateGoal !== false,
                 ...(typeof summaryOpts?.maxOutputTokens === "number" &&
                     Number.isFinite(summaryOpts.maxOutputTokens) &&
                     summaryOpts.maxOutputTokens > 0
                     ? { maxOutputTokens: Math.floor(summaryOpts.maxOutputTokens) }
                     : {}),
+                stripMedia: opts?.stripMedia === true || geminiMediaStripped,
             });
             // /effort maps to the native thinkingLevel (Auto omits it; Max rides
             // high, the deepest level the API offers). Merged into
@@ -1278,6 +1741,23 @@ export async function chatCompletionGemini(apiKey, model, history, opts) {
             }
             if (!res.ok) {
                 const errText = await safeErrorText(res);
+                // Vision fallback (see src/media.ts): a 400 naming image input
+                // retries once with descriptors stripped to markers.
+                if (res.status === 400 &&
+                    !geminiMediaStripped &&
+                    opts?.stripMedia !== true &&
+                    historyHasMedia(outgoingHistory) &&
+                    isImageRejection(errText)) {
+                    geminiMediaStripped = true;
+                    try {
+                        opts?.onWarning?.(`image input is not supported by ${model} — continuing without images`);
+                    }
+                    catch {
+                        // ignore observer errors
+                    }
+                    throwIfCancelled(signal);
+                    continue;
+                }
                 if (res.status === 400 &&
                     geminiLevel !== undefined &&
                     !geminiEffortDropped &&
@@ -1387,11 +1867,13 @@ export async function chatCompletionGemini(apiKey, model, history, opts) {
     throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 // Provider dispatcher: openai-chat reuses chatCompletion with the provider's
-// error label; anthropic/gemini go through their adapters. Effort rides
-// every kind: reasoning_effort on openai-chat (all providers, all models),
-// thinking budgets on anthropic-messages, thinkingLevel on gemini-generate.
-// Auto omits the knob; a model that truly lacks it 400s and the transports
-// above retry once without it.
+// error label; anthropic/gemini go through their adapters; Zen
+// responses-family models (muse-spark-*) ride chatCompletionResponses.
+// Effort rides every kind: reasoning_effort on openai-chat (all providers,
+// all models), reasoning.effort on responses, thinking budgets on
+// anthropic-messages, thinkingLevel on gemini-generate. Auto omits the knob
+// everywhere; a model that truly lacks it 400s and the transports above
+// retry once without it.
 export async function chatCompletionForProvider(provider, apiKey, model, history, opts) {
     const def = getProvider(provider);
     if (!def)
@@ -1430,9 +1912,17 @@ export async function chatCompletionForProvider(provider, apiKey, model, history
         ...effortOpts,
         // Compaction path only (undefined for the normal loop → tools sent).
         ...(opts?.disableTools !== undefined ? { disableTools: opts.disableTools } : {}),
+        // Goal-tool visibility (undefined for compaction/summary callers →
+        // legacy full surface; the loop entry points always set it per POST).
+        ...(opts?.includeUpdateGoal !== undefined
+            ? { includeUpdateGoal: opts.includeUpdateGoal }
+            : {}),
         ...(opts?.maxOutputTokens !== undefined
             ? { maxOutputTokens: opts.maxOutputTokens }
             : {}),
+        // Media strip (compaction/summarization callers set it; the normal
+        // loop leaves it undefined → images expand natively).
+        ...(opts?.stripMedia !== undefined ? { stripMedia: opts.stripMedia } : {}),
     };
     // Kilo rides the shared OpenAI-chat path (streaming, tool reconstruction,
     // retry, effort with server-rejection fallback) with its registry
@@ -1446,6 +1936,13 @@ export async function chatCompletionForProvider(provider, apiKey, model, history
             throw normalizeKiloChatError(e, apiKey);
         }
     }
+    // Zen responses-family (muse-spark-*, free contributor tiers included):
+    // same chatOpts surface (effort/tools/compaction/media/hooks), Responses
+    // wire shape + /responses endpoint. Only opencode-zen serves this family;
+    // every other provider keeps the chat path below byte-identical.
+    if (provider === "opencode-zen" && isZenResponsesModel(model)) {
+        return chatCompletionResponses(responsesEndpointFor(endpoint), apiKey, model, history, chatOpts, providerLabel(provider));
+    }
     return chatCompletion(endpoint, apiKey, model, history, chatOpts, providerLabel(provider));
 }
 export { evaluateTurnEnd, isCodePath, MAX_TODO_ROUNDS, MAX_VERIFY_ROUNDS, todoCompletionGate, TURN_END_GATES, verificationGate, } from "./agent/gates.js";
@@ -1486,6 +1983,7 @@ export async function runAgenticLoopForProvider(provider, apiKey, model, history
         reasoningEffort: o?.reasoningEffort,
         baseURL: opts?.baseURL,
         endpointOverride: opts?.endpointOverride,
+        includeUpdateGoal: isGoalTurnLive(opts),
     }), history, opts);
 }
 // Per-provider model list: live list per kind with curated fallback on ANY