atom-agent 0.3.0 → 1.1.0

package/dist/zen.js

@@ -5,10 +5,13 @@
 // 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, TOOL_DEFINITIONS, describeToolCall, executeTool, getTodos, invalidCall, needsApproval, toolNames, validateAskQuestionArgs, validateToolArgs, } from "./tools.js";
-import { chatEndpointFor, getProvider, modelsUrlForProvider, providerLabel, } from "./providers.js";
-import { ANTHROPIC_VERSION, anthropicHeaders, buildAnthropicBody, buildGeminiBody, geminiChatUrl, geminiGenerateUrl, geminiHeaders, parseAnthropicJson, parseAnthropicModelsList, parseGeminiJson, parseGeminiModelsList, parseOpenAIModelsList, readAnthropicSSEMessage, readGeminiSSEMessage, } from "./adapters.js";
-import { primaryTarget } from "./permissions.js";
+import { MAX_TOOL_STEPS, TOOL_DEFINITIONS, } from "./tools.js";
+import { chatEndpointFor, getProvider, isLocalProviderId, modelsUrlForProvider, providerLabel, } from "./providers.js";
+import { discoverLocalProvider } from "./local-discovery.js";
+import { ANTHROPIC_VERSION, anthropicHeaders, buildAnthropicBody, buildGeminiBody, geminiChatUrl, geminiGenerateUrl, geminiHeaders, parseAnthropicJson, parseAnthropicModelsList, parseGeminiJson, parseGeminiModelsList, parseOpenAIModelsList, readAnthropicSSEMessage, readGeminiSSEMessage, isStallError, readWithStall, } from "./adapters.js";
+export { isStallError, readWithStall, sseStallTimeoutMs } from "./adapters.js";
+import { KILO_FALLBACK_MODELS, fetchKiloModelsWithStatus, normalizeKiloChatError, } from "./kilo.js";
+import { splitSystemHead } from "./prompt-cache.js";
 import { SYSTEM_PROMPT } from "./system.js";
 export { MAX_TOOL_STEPS };
 // Re-exported so existing `SYSTEM_PROMPT` imports keep working; the
@@ -26,36 +29,18 @@ export const AGENTS_CHAR_CAP = 12 * 1024;
 // ---- Conversation-history budget (deterministic, no extra model calls) ----
 // Long sessions can't bloat context, cost, and latency: the shared loop core
 // trims history to BOTH caps before every POST (uniform across providers).
-// Optional env overrides (invalid/unset → defaults):
+// The caps themselves live in the ContextManager module (re-exported here so
+// existing importers keep working); precedence per knob stays env override
+// (when valid) → project atom.json → global atom.json → compiled default:
 // - ATOM_MAX_HISTORY_MESSAGES, clamped to 10–1000 (default 100)
 // - ATOM_MAX_HISTORY_CHARS, clamped to 10_000–2_000_000 (default 200_000)
-export const MAX_HISTORY_MESSAGES = 100;
-export const MAX_HISTORY_CHARS = 200_000;
-function clampEnvInt(raw, min, max, fallback) {
-    if (raw === undefined)
-        return fallback;
-    const text = raw.trim();
-    if (!/^\d+$/.test(text))
-        return fallback;
-    const n = Number(text);
-    if (!Number.isFinite(n))
-        return fallback;
-    return Math.min(Math.max(Math.floor(n), min), max);
-}
-// Message-count cap for history (env override clamped 10–1000).
-export function historyMessageBudget() {
-    return clampEnvInt(process.env.ATOM_MAX_HISTORY_MESSAGES, 10, 1000, MAX_HISTORY_MESSAGES);
-}
-// Total-chars cap for history (env override clamped 10_000–2_000_000).
-export function historyCharBudget() {
-    return clampEnvInt(process.env.ATOM_MAX_HISTORY_CHARS, 10_000, 2_000_000, MAX_HISTORY_CHARS);
-}
-// Tool-round budget for one agentic turn (env override clamped 5–100).
-// A real explore → implement → verify task needs 15–30 tool rounds, so the
-// default is 30; an explicit `opts.maxSteps` still wins (tests inject it).
-export function toolStepBudget() {
-    return clampEnvInt(process.env.ATOM_MAX_TOOL_STEPS, 5, 100, MAX_TOOL_STEPS);
-}
+export { toolStepBudget } from "./agent/loop.js";
+// Reasoning effort (session state in the App, default "default").
+// Wire values are exactly default/low/medium/high/max. "default" never
+// sends a param. NOTE: the user asked for `xhigh`, but the only VERIFIED
+// valid values (OpenCode Zen docs/changelog: Thinking Effort
+// Default/Max/High/Medium/Low, sent as `reasoning_effort`) use `Max`, so
+// the top setting is `Max`, sent on the wire as `max`.
 export const EFFORT_OPTIONS = [
     "default",
     "low",
@@ -89,158 +74,9 @@ export function reasoningEffortParam(effort, model) {
     }
     return undefined;
 }
-// Deterministic size of one message: string content counts as-is, anything
-// else counts stringified; assistant tool_calls and tool ids count too (they
-// ride on every POST). History chars = the sum over all messages.
-export function messageChars(m) {
-    let n = 0;
-    const content = m.content;
-    if (typeof content === "string") {
-        n += content.length;
-    }
-    else if (content !== null && content !== undefined) {
-        n += JSON.stringify(content).length;
-    }
-    if (m.role === "assistant") {
-        if (m.tool_calls !== undefined)
-            n += JSON.stringify(m.tool_calls).length;
-    }
-    else if (m.role === "tool") {
-        n += m.tool_call_id.length;
-    }
-    return n;
-}
-export function historyChars(history) {
-    let total = 0;
-    for (const m of history)
-        total += messageChars(m);
-    return total;
-}
-// Current open todo texts (content + activeForm) via the shared getTodos
-// read path — no duplicated state. Completed items never pin (their echoes
-// are stale context). Never throws: on any failure there is simply nothing
-// todo-pinned and truncation falls back to task-prompt + latest-turn pinning.
-function openTodoNeedles() {
-    try {
-        const open = getTodos().filter((t) => t.status !== "completed");
-        const out = [];
-        for (const t of open) {
-            if (typeof t.content === "string" && t.content.length > 0)
-                out.push(t.content);
-            if (typeof t.activeForm === "string" && t.activeForm.length > 0)
-                out.push(t.activeForm);
-        }
-        return out;
-    }
-    catch {
-        return [];
-    }
-}
-// Searchable text for todo matching: message content plus the assistant's
-// tool_calls payload (todowrite CALLS carry the list, tool RESULTS echo it).
-// Tool call ids are NOT searched — they are pairing keys, not goal text, so
-// a todo that reads like an id can never false-pin a turn.
-function todoHaystack(m) {
-    let hay = "";
-    const content = m.content;
-    if (typeof content === "string")
-        hay += content;
-    if (m.role === "assistant" && m.tool_calls !== undefined) {
-        try {
-            hay += JSON.stringify(m.tool_calls);
-        }
-        catch {
-            // unstringifiable payload pins nothing
-        }
-    }
-    return hay;
-}
-function turnMentionsTodo(history, start, end, needles) {
-    for (let i = start; i < end; i++) {
-        const hay = todoHaystack(history[i]);
-        if (hay.length === 0)
-            continue;
-        for (const n of needles) {
-            if (n.length > 0 && hay.includes(n))
-                return true;
-        }
-    }
-    return false;
-}
-// Drop oldest user-turns until history fits BOTH budget caps (message count
-// AND total chars, each plus the caller's `reserve` headroom for a message
-// it is about to push). A user turn = the `user` message plus all following
-// messages up to (excluding) the next `user` message, so assistant
-// tool_calls always stay paired with their tool results across all three
-// wire formats. NEVER drops history[0] (system prompt), the first user turn
-// (the task prompt — the goal a long run must never forget), any turn that
-// still quotes a CURRENT open todo (via getTodos, so completed/stale items
-// don't pin), or the latest turn (the one being sent/built). Budget-aware
-// edge: when the pinned content alone (first turn + todo turns + latest)
-// already exceeds a cap, there is nothing left to drop — stop and still send
-// (same never-drop-the-live-turn principle). Mutates `history` in place via
-// splice (so caller indices captured after this call stay valid) and, when at
-// least one turn dropped, fires ONE `notify` (the caller surfaces it dim in
-// the TUI); silence otherwise. Returns what was dropped.
-export function truncateHistory(history, notify, reserve) {
-    const result = { droppedTurns: 0, droppedMessages: 0 };
-    if (history.length <= 1)
-        return result;
-    const maxMessages = historyMessageBudget();
-    const maxChars = historyCharBudget();
-    const roomMessages = reserve?.messages !== undefined && Number.isFinite(reserve.messages)
-        ? Math.max(0, Math.floor(reserve.messages))
-        : 0;
-    const roomChars = reserve?.chars !== undefined && Number.isFinite(reserve.chars)
-        ? Math.max(0, reserve.chars)
-        : 0;
-    const needles = openTodoNeedles();
-    for (;;) {
-        const over = history.length + roomMessages > maxMessages ||
-            historyChars(history) + roomChars > maxChars;
-        if (!over)
-            break;
-        // Turn boundaries over history[1..]: each turn starts at a `user`
-        // message (the oldest slice starts at 1 even when it isn't one, matching
-        // the pre-pin drop unit). Whole-turn drops keep assistant/tool pairing.
-        const starts = [1];
-        for (let i = 2; i < history.length; i++) {
-            if (history[i]?.role === "user")
-                starts.push(i);
-        }
-        // Oldest NON-pinned, non-latest turn goes first: the first turn (task
-        // prompt) and any turn still quoting a current open todo stay, and the
-        // latest turn is never dropped. No candidate means pinned content alone
-        // is over budget — stop and send it as-is (see edge above).
-        let drop = -1;
-        for (let t = 0; t < starts.length; t++) {
-            if (t === starts.length - 1)
-                continue; // latest turn
-            if (t === 0)
-                continue; // task prompt
-            const end = t + 1 < starts.length ? starts[t + 1] : history.length;
-            if (needles.length > 0 && turnMentionsTodo(history, starts[t], end, needles))
-                continue;
-            drop = t;
-            break;
-        }
-        if (drop === -1)
-            break;
-        const end = drop + 1 < starts.length ? starts[drop + 1] : history.length;
-        const removed = history.splice(starts[drop], end - starts[drop]);
-        result.droppedTurns += 1;
-        result.droppedMessages += removed.length;
-    }
-    if (result.droppedTurns > 0) {
-        try {
-            notify?.(`(history truncated: dropped ${result.droppedTurns} oldest turn(s))`);
-        }
-        catch {
-            // observer errors never break the loop
-        }
-    }
-    return result;
-}
+export { CHARS_PER_TOKEN, MAX_HISTORY_CHARS, MAX_HISTORY_MESSAGES, createContextManager, estimateTokensForChars, historyCharBudget, historyChars, historyMessageBudget, messageChars, truncateHistoryWithCaps, } from "./context-manager.js";
+export { openTodoNeedles } from "./agent/gates.js";
+export { truncateHistory } from "./agent/loop.js";
 function finiteCount(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0
         ? Math.floor(value)
@@ -262,6 +98,22 @@ export function parseUsage(value) {
     const total = finiteCount(o["total_tokens"]);
     if (total !== undefined)
         out.total_tokens = total;
+    // Provider-reported prefix-cache counters (present-only, like everything
+    // else here): OpenAI prompt_tokens_details.cached_tokens (+cache_write
+    // when sent) and DeepSeek prompt_cache_hit_tokens (official docs shapes).
+    const details = o["prompt_tokens_details"];
+    if (typeof details === "object" && details !== null) {
+        const d = details;
+        const cached = finiteCount(d["cached_tokens"]);
+        if (cached !== undefined)
+            out.cacheReadTokens = cached;
+        const written = finiteCount(d["cache_write_tokens"]);
+        if (written !== undefined)
+            out.cacheWriteTokens = written;
+    }
+    const hit = finiteCount(o["prompt_cache_hit_tokens"]);
+    if (hit !== undefined)
+        out.cacheReadTokens = hit;
     return out.prompt_tokens !== undefined ||
         out.completion_tokens !== undefined ||
         out.total_tokens !== undefined
@@ -298,43 +150,24 @@ export function parseReasoningLabel(value) {
         return "present";
     return undefined;
 }
-// Whole-turn cancellation: thrown when the user cancels (Ctrl+C) mid-loop.
-// The App catches it, rolls the partial turn back (same splice contract as
-// POST failure), renders one dim `(cancelled)` line, and returns to a clean
-// input state. Never retried, never a tool result.
-export class LoopCancelledError extends Error {
-    constructor() {
-        super("(cancelled)");
-        this.name = "LoopCancelledError";
-    }
-}
-export function isCancelError(e) {
-    if (e instanceof LoopCancelledError)
-        return true;
-    if (e instanceof Error && e.name === "LoopCancelledError")
-        return true;
-    // fetch abort surfaces as DOMException AbortError (or Error with that name
-    // in mocks). Treat any AbortError as a cancellation, never a retry.
-    if (e instanceof Error && e.name === "AbortError")
-        return true;
-    if (typeof DOMException !== "undefined" && e instanceof DOMException && e.name === "AbortError") {
-        return true;
-    }
-    return false;
-}
-function throwIfCancelled(signal) {
-    if (signal?.aborted)
-        throw new LoopCancelledError();
-}
-export const MAX_RETRIES = 2;
+// Live execution phases surfaced to the TUI via onPhase. `detail` carries
+// the tool name for "tool" and a retry summary (attempt/delay/status) for
+// "retry"; it is empty for the other phases.
+import { isCancelError, LoopCancelledError, throwIfCancelled } from "./agent/loop.js";
+export { isCancelError, LoopCancelledError } from "./agent/loop.js";
+// Ten retries (eleven total attempts): provider rate limits (429 with
+// 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.
+export const MAX_RETRIES = 10;
 const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
 const RETRY_AFTER_CAP_MS = 30_000;
 export function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-// Exponential backoff 1s -> 2s, honoring Retry-After (seconds or HTTP date)
-// capped at 30s. `attempt` is the 0-based index of the failure just seen
-// (0 => first failure => 1s).
+// Exponential backoff 1s → 2s → 4s …, honoring Retry-After (seconds or
+// HTTP date) capped at 30s. `attempt` is the 0-based index of the failure
+// just seen (0 => first failure => 1s).
 export function getRetryDelay(attempt, res) {
     try {
         const raw = res
@@ -357,7 +190,7 @@ export function getRetryDelay(attempt, res) {
     catch {
         // fall through to backoff
     }
-    return attempt === 0 ? 1000 : 2000;
+    return Math.min(1000 * 2 ** attempt, RETRY_AFTER_CAP_MS);
 }
 async function safeErrorText(res) {
     try {
@@ -504,6 +337,11 @@ export async function fetchModels(endpoint, apiKey) {
 // - Slots with an id but no name at [DONE] are dropped with an onWarning
 //   message and never returned (keeps assistant/tool pairing valid).
 // - A stream that ends without [DONE] throws a truncation error.
+// - A stream silent longer than the stall budget (env ATOM_STALL_TIMEOUT_MS,
+//   default 60s; the clock resets on every received chunk) throws a
+//   Truncated-stream stall error — permanent, never retried, same contract
+//   as a dead connection (verified live: free-tier routers can stall a
+//   200-OK stream mid-generation for minutes).
 // - A stream with zero "data:" lines is treated as a non-SSE JSON payload
 //   (tolerance for bodies that are really single-shot JSON) and parsed as
 //   choices[0].message like the non-streaming fallback.
@@ -681,9 +519,11 @@ export async function readSSEMessage(res, opts) {
                 for (;;) {
                     let chunk;
                     try {
-                        chunk = await reader.read();
+                        chunk = await readWithStall(() => reader.read());
                     }
                     catch (e) {
+                        if (isStallError(e))
+                            throw e;
                         throw new Error(`Truncated stream from model (connection aborted: ${e instanceof Error ? e.message : String(e)}).`);
                     }
                     if (chunk.done)
@@ -718,13 +558,28 @@ export async function readSSEMessage(res, opts) {
             }
         }
         else if (typeof body[Symbol.asyncIterator] === "function") {
-            for await (const v of body) {
-                const text = typeof v === "string" ? v : decoder.decode(v, { stream: true });
-                rawText += text;
-                buffer += text;
-                drainBuffer();
-                if (sawDone)
-                    break;
+            const it = body[Symbol.asyncIterator]();
+            try {
+                for (;;) {
+                    const step = await readWithStall(() => it.next());
+                    if (step.done)
+                        break;
+                    const v = step.value;
+                    const text = typeof v === "string" ? v : decoder.decode(v, { stream: true });
+                    rawText += text;
+                    buffer += text;
+                    drainBuffer();
+                    if (sawDone)
+                        break;
+                }
+            }
+            finally {
+                try {
+                    await it.return?.();
+                }
+                catch {
+                    // ignore — the stream is over either way
+                }
             }
             if (!sawDone && buffer.length > 0) {
                 processLine(buffer);
@@ -838,8 +693,9 @@ export async function readSSEMessage(res, opts) {
 // the response actually carried them (usage: top-level `usage` on JSON or
 // SSE final chunks; reasoning: message/delta reasoning metadata).
 // Throws on HTTP error, empty reply, or a truncated stream.
-// - Network throws and HTTP 429/500/502/503/504 are retried up to 2 times
-//   (3 attempts) with 1s->2s backoff, honoring Retry-After capped at 30s.
+// - Network throws and HTTP 429/500/502/503/504 are retried up to
+//   MAX_RETRIES (10) with 1s→2s→4s… backoff, honoring Retry-After capped
+//   at 30s.
 //   Each retry emits onPhase("retry", detail). Other 4xx fail fast with
 //   the existing `Zen HTTP {status}` message.
 // - Callers must roll back the user turn on failure (see App submit).
@@ -862,9 +718,16 @@ export async function chatCompletion(endpoint, apiKey, model, history, opts, err
             }
             const effortParam = reasoningEffortParam(opts?.reasoningEffort, model);
             const summaryOpts = opts;
+            // 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(history);
             const payload = {
                 model,
-                messages: history,
+                messages,
                 stream: true,
             };
             // Compaction path only: tools disabled means NO `tools` key at all
@@ -882,9 +745,13 @@ export async function chatCompletion(endpoint, apiKey, model, history, opts, err
                 payload["reasoning_effort"] = effortParam;
             const res = await fetch(endpoint, {
                 method: "POST",
+                // Anonymous-capable providers (Kilo free models) omit Authorization
+                // when no key is configured — never an empty `Bearer `. Keyed
+                // providers always pass a key (gated by providerNeedsKey), so their
+                // behavior is unchanged.
                 headers: {
                     "Content-Type": "application/json",
-                    Authorization: `Bearer ${apiKey}`,
+                    ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
                 },
                 body: JSON.stringify(payload),
                 ...(signal ? { signal } : {}),
@@ -1002,7 +869,8 @@ export async function chatCompletion(endpoint, apiKey, model, history, opts, err
 // ends the loop (graceful fallback for models without tool support). Tool
 // errors are results the model sees — NOTHING is rolled back here; only a
 // POST failure (HTTP/network/empty/truncated) throws (and the caller rolls
-// back the user turn, as before, including any streaming draft).
+// back the user turn, as before; the caller preserves any streamed partial
+// on display).
 export async function runAgenticLoop(endpoint, apiKey, model, history, opts) {
     return runLoopWithChat((h, o) => chatCompletion(endpoint, apiKey, model, h, {
         onToken: o?.onToken,
@@ -1015,94 +883,6 @@ export async function runAgenticLoop(endpoint, apiKey, model, history, opts) {
         signal: o?.signal,
     }), history, opts);
 }
-// Execute one parsed tool call through validation + permission +
-// ask_question gates. Model mistakes (unknown name, invalid args) return
-// repairs-oriented results WITHOUT executing; cancellations propagate as
-// LoopCancelledError (never a result, never retried). Everything else
-// returns a result string fed back to the model:
-// - ask_question never needs approval; without an askUser hook it resolves
-//   to "Error: ask_question has no UI hook".
-// - write/edit/bash consult the approve hook when one is provided; a "no"
-//   resolves to "Error: denied by user: <tool>" (final, no retry/rollback).
-//   Without a hook every tool executes immediately.
-async function runOneTool(call, parsed, opts, execute) {
-    const name = call?.function?.name ?? "(unknown)";
-    // Unknown tool: model mistake — list actual names, never execute.
-    if (!toolNames().includes(name)) {
-        return `Error: unknown tool "${name}". Available: ${toolNames().join(", ")}`;
-    }
-    // Argument validation BEFORE approval/execution: model mistake, never runs.
-    const detail = validateToolArgs(name, parsed);
-    if (detail) {
-        return invalidCall(detail);
-    }
-    if (name === "ask_question") {
-        throwIfCancelled(opts?.signal);
-        // If the signal aborts during the modal, runAskQuestion rejects with
-        // LoopCancelledError (no result). If it resolves just as the signal
-        // aborts, return the result — the loop records it, then stops before
-        // the next POST (no new POSTs, pairing stays valid until rollback).
-        return runAskQuestion(parsed, opts?.askUser, opts?.signal);
-    }
-    if (opts?.approve && needsApproval(name)) {
-        let decision;
-        try {
-            decision = await opts.approve(name, parsed);
-        }
-        catch (e) {
-            // Whole-turn cancellation must propagate (Ctrl+C cancels the turn,
-            // not just deny one call). Anything else is a denial.
-            if (isCancelError(e) || opts?.signal?.aborted)
-                throw new LoopCancelledError();
-            decision = "no";
-        }
-        // Abort that lands as a resolved denial still cancels the whole turn.
-        throwIfCancelled(opts?.signal);
-        if (decision === "no") {
-            return `Error: denied by user: ${name}`;
-        }
-        // "once" runs this call; "always" runs it too (the caller caches the
-        // always-allowed set session-wide so later calls skip the prompt).
-    }
-    // No new executions after a cancel: stop after the current tool finishes.
-    // The current tool (if already running) is awaited to completion and its
-    // result IS recorded — the loop then stops before the next tool/POST, so
-    // assistant/tool pairing stays valid until the caller rolls back.
-    throwIfCancelled(opts?.signal);
-    try {
-        return await execute(name, parsed);
-    }
-    catch (e) {
-        if (isCancelError(e) || opts?.signal?.aborted)
-            throw new LoopCancelledError();
-        throw e;
-    }
-}
-async function runAskQuestion(parsed, askUser, signal) {
-    const invalid = validateAskQuestionArgs(parsed);
-    if (invalid)
-        return invalid;
-    if (!askUser)
-        return "Error: ask_question has no UI hook";
-    const q = parsed;
-    const allowCustom = q.allowCustom === true;
-    try {
-        const answer = await askUser(q.question, q.options, allowCustom);
-        if (typeof answer === "string" && answer.startsWith("Error:"))
-            return answer;
-        return JSON.stringify({ answer });
-    }
-    catch (e) {
-        // Whole-turn cancellation (Ctrl+C) propagates — it is NOT the Esc
-        // question-cancel result below.
-        if (isCancelError(e) || signal?.aborted)
-            throw new LoopCancelledError();
-        const msg = e instanceof Error ? e.message : String(e);
-        if (/cancel/i.test(msg))
-            return "Error: question cancelled by user";
-        return `Error: ${msg}`;
-    }
-}
 // AGENTS.md loading: <cwd>/AGENTS.md (or $OPENCODE_AGENTS_PATH when set)
 // is appended to the system prompt at startup, capped at 12KB.
 export function agentsFilePath(cwd = process.cwd()) {
@@ -1357,7 +1137,7 @@ export async function chatCompletionForProvider(provider, apiKey, model, history
         ? (opts?.endpointOverride ?? chatEndpointFor(provider, opts?.baseURL))
         : chatEndpointFor(provider, opts?.baseURL);
     const effortOpts = provider === "opencode-zen" ? { reasoningEffort: opts?.reasoningEffort } : {};
-    return chatCompletion(endpoint, apiKey, model, history, {
+    const chatOpts = {
         onToken: opts?.onToken,
         onPhase: opts?.onPhase,
         onToolDelta: opts?.onToolDelta,
@@ -1371,363 +1151,46 @@ export async function chatCompletionForProvider(provider, apiKey, model, history
         ...(opts?.maxOutputTokens !== undefined
             ? { maxOutputTokens: opts.maxOutputTokens }
             : {}),
-    }, providerLabel(provider));
-}
-// Todo-completion guard: the turn may not end with final text while todos
-// are open. With budget left, record the attempt and feed back a guard
-// message as a user follow-up so the model must continue with tool calls or
-// explicitly resolve the todos. With the step budget spent, end with an
-// explicit blocked statement naming the unfinished items instead.
-export function todoCompletionGate(finalText, ctx) {
-    const open = getTodos().filter((t) => t.status !== "completed");
-    if (open.length === 0)
-        return { action: "pass" };
-    const items = open.map((t, i) => `${i + 1}. [${t.status}] ${t.content}`).join("\n");
-    if (ctx.step >= ctx.maxSteps) {
-        return {
-            action: "end",
-            finalText: `${finalText}${finalText ? "\n" : ""}(blocked: ${open.length} open todo(s) — resolve with todo_update/todowrite before ending the turn:\n${items})`,
-        };
-    }
-    return {
-        action: "continue",
-        assistantText: finalText,
-        followUp: `(todo guard: ${open.length} open todo(s) — do not end the turn with final text. Continue with tool calls, or resolve them with todo_update/todowrite:\n${items})`,
     };
-}
-// Task 7 verification gate: files were written but no test/typecheck/build
-// command ran after the last write. The turn still ends here (never block)
-// — the result is labeled unverified so a "done" claim can never pass
-// silently without evidence. Turns with no writes (questions, explanations,
-// read-only work) are unaffected.
-export function verificationGate(finalText, ctx) {
-    if (!ctx.filesWritten || ctx.verifiedAfterWrite)
-        return { action: "pass" };
-    return {
-        action: "end",
-        finalText: `${finalText}${finalText ? "\n" : ""}(unverified: files were written but no test/typecheck command ran after the last write — run \`npm test\` and \`npm run typecheck\` and report their pass/fail lines, or name the blocker explicitly.)`,
-    };
-}
-export const TURN_END_GATES = [todoCompletionGate, verificationGate];
-export function evaluateTurnEnd(finalText, ctx, gates = TURN_END_GATES) {
-    for (const gate of gates) {
-        const decision = gate(finalText, ctx);
-        if (decision.action === "pass")
-            continue;
-        if (decision.action === "continue") {
-            return { kind: "continue", assistantText: decision.assistantText, followUp: decision.followUp };
+    // Kilo rides the shared OpenAI-chat path (streaming, tool reconstruction,
+    // retry) with its registry endpoint + label; HTTP failures are reframed
+    // into concise actionable Kilo errors (see src/kilo.ts). reasoning_effort
+    // is never attached (zen-only gating above).
+    if (provider === "kilo") {
+        try {
+            return await chatCompletion(endpoint, apiKey, model, history, chatOpts, providerLabel(provider));
+        }
+        catch (e) {
+            throw normalizeKiloChatError(e, apiKey);
         }
-        return { kind: "end", finalText: decision.finalText };
     }
-    return { kind: "end", finalText };
+    return chatCompletion(endpoint, apiKey, model, history, chatOpts, providerLabel(provider));
 }
-// Task 7 verification gate: a bash command counts as a verification run
-// when it names a common test/typecheck/build entry point. This is a word
-// heuristic, not a parser — a miss only appends a non-blocking
-// informational flag (never stops the turn), and the list is pinned by
-// tests/loop-verification-gate.test.ts.
-function isVerificationCommand(command) {
-    return /\b(vitest|jest|mocha|pytest|typecheck|tsc|verify|check|build|tests?)\b/i.test(command);
-}
-// Parallel independent tool calls (ticket 05): read-only, non-overlapping
-// calls in one model turn execute concurrently (roughly one round-trip
-// instead of N) with results re-paired in call order. Batching re-pairs at
-// the commit point the turn-continuation seam defines (one transcript entry
-// per call, in order), so the seam's pairing guarantee is unaffected.
+export { evaluateTurnEnd, isCodePath, MAX_VERIFY_ROUNDS, todoCompletionGate, TURN_END_GATES, verificationGate, } from "./agent/gates.js";
+// Parallel independent tool calls: batch PLANNING lives in src/scheduler.ts
+// (effect metadata + conflict rules, no per-tool branches); this module only
+// plans via planToolBatches below and executes (serial singletons in program
+// order, read batches concurrently, results committed in call order).
 //
-// Parallel-safe = this explicit allowlist only (new tools default to
-// serial). Excluded on purpose:
-// - write/edit/bash need approval and mutate the world (bash can touch
-//   anything, so no footprint check could clear it);
+// Parallel-safe = batchable reads only (see TOOL_EFFECTS in scheduler.ts).
+// Excluded on purpose:
+// - write/edit/bash mutate or spawn with an unbounded footprint (bash can
+//   touch anything, so no footprint check could clear it) — always singletons;
 // - ask_question blocks on a UI modal (parallel prompts make no sense);
 // - todowrite/todo_update share module-global todo state (read-modify-write
 //   races); todo_get is pure but sub-millisecond, so batching it buys
-//   nothing and it stays serial too (empty footprint, see below).
-export const PARALLEL_SAFE_TOOLS = new Set([
-    "read",
-    "grep",
-    "glob",
-    "webfetch",
-    "websearch",
-    "bash_output",
-]);
-// Overlap key for two parallel-safe calls: same tool over the same primary
-// target (path/pattern/command/URL/query/taskId — the same primary
-// describeToolCall shows). Same-key calls serialize (conservative: e.g. two
-// reads of one path); different keys — including different tools naming the
-// same string — are disjoint read-only footprints and run together. Returns
-// null when the call must stay serial: unknown name, malformed JSON,
-// failed validation (all inline-error paths), or an empty primary (unknown
-// footprint — never batch what you cannot see).
-export function parallelKeyFor(name, parsed) {
-    if (!PARALLEL_SAFE_TOOLS.has(name))
-        return null;
-    if (!toolNames().includes(name))
-        return null;
-    if (validateToolArgs(name, parsed))
-        return null;
-    const primary = primaryTarget(name, parsed);
-    if (primary.length === 0)
-        return null;
-    return `${name}${primary}`;
-}
-// Partition one assistant message's tool_calls into commit batches,
-// preserving program order: consecutive batchable calls with pairwise
-// disjoint keys form one batch; any serial-only call — and any call whose
-// key already appears in the open batch — closes the batch and runs as a
-// strict serial singleton. A later batch never moves ahead of an earlier
-// serial call (read-after-write stays ordered), and batches never span the
-// block boundary.
+//   nothing and it stays serial too.
+import { planBatches } from "./scheduler.js";
+// Partition one assistant message's tool_calls into commit batches —
+// effect-aware (see planBatches), preserving program order and the commit
+// contract the turn-continuation seam defines (one transcript entry per
+// call, in order). Kept under this name/signature for callers and tests.
 export function planToolBatches(calls) {
-    const batches = [];
-    let open = [];
-    const keys = new Set();
-    const flush = () => {
-        if (open.length > 0) {
-            batches.push(open);
-            open = [];
-            keys.clear();
-        }
-    };
-    for (const call of calls) {
-        let parsed;
-        let malformed = false;
-        try {
-            const raw = call?.function?.arguments ?? "{}";
-            const v = JSON.parse(typeof raw === "string" ? raw : "{}");
-            parsed = typeof v === "object" && v !== null ? v : {};
-        }
-        catch {
-            parsed = {};
-            malformed = true;
-        }
-        const name = call?.function?.name ?? "(unknown)";
-        const key = malformed ? null : parallelKeyFor(name, parsed);
-        if (key === null || keys.has(key)) {
-            flush();
-            batches.push([{ call, parsed, parallelKey: null }]);
-        }
-        else {
-            keys.add(key);
-            open.push({ call, parsed, parallelKey: key });
-        }
-    }
-    flush();
-    return batches;
-}
-// Shared agentic-loop core: the SINGLE loop implementation backing both
-// runAgenticLoop and runAgenticLoopForProvider (same tool/rollback contract).
-// Sequencing: each assistant message's tool_calls block is partitioned by
-// planToolBatches — a batch of parallel-safe calls runs concurrently and its
-// results commit in call order (re-paired by index, one transcript entry per
-// call); everything else executes strictly serially in program order. A
-// failure in one call NEVER skips the remaining commits of its block when
-// the results are values (each result pairs with its tool_call_id in
-// order); malformed calls (bad JSON, unknown name, failed validation) yield
-// their error result inline and the block continues. Validation/unknown/
-// denial/cancel are never retried — only transient transport failures retry
-// (inside chatCompletion). A thrown execution error (or cancel) aborts the
-// turn exactly as the old serial loop did — the caller rolls the partial
-// turn back, so assistant/tool pairing stays valid.
-export async function runLoopWithChat(chatFn, history, opts) {
-    const execute = opts?.execute ?? executeTool;
-    const maxSteps = opts?.maxSteps ?? toolStepBudget();
-    const signal = opts?.signal ?? null;
-    // Task 7 verification gate: whether this turn wrote files and whether a
-    // test/typecheck/build command ran after the last write. Only evidence
-    // AFTER the last write counts, so each new write resets the flag.
-    let filesWritten = false;
-    let verifiedAfterWrite = false;
-    // At most one truncation notice per turn; silence when nothing dropped.
-    let truncationNoticed = false;
-    for (let step = 0;; step++) {
-        throwIfCancelled(signal);
-        // History budget (uniform for all providers — every POST flows through
-        // here): trim oldest user-turns first before each send.
-        const trimmed = truncateHistory(history, truncationNoticed
-            ? undefined
-            : (notice) => {
-                try {
-                    opts?.onWarning?.(notice);
-                }
-                catch {
-                    // ignore observer errors
-                }
-            });
-        if (trimmed.droppedTurns > 0)
-            truncationNoticed = true;
-        let msg;
-        try {
-            msg = await chatFn(history, {
-                onToken: opts?.onToken,
-                onPhase: opts?.onPhase,
-                onToolDelta: opts?.onToolDelta,
-                onWarning: opts?.onWarning,
-                onThinking: opts?.onThinking,
-                sleep: opts?.sleep,
-                reasoningEffort: opts?.reasoningEffort,
-                signal,
-            });
-        }
-        catch (e) {
-            if (isCancelError(e) || signal?.aborted)
-                throw new LoopCancelledError();
-            throw e;
-        }
-        throwIfCancelled(signal);
-        if (msg.usage !== undefined) {
-            // Spend accounting: EVERY POST that reports usage forwards it, and the
-            // caller accumulates each report as billed spend — tool-round POSTs,
-            // summary POSTs, and successful retries each count once. Attempts that
-            // fail (HTTP/network/truncation) report no usage, so there is nothing
-            // to dedupe: each attempt that reached the provider and reported counts
-            // exactly once. Usage is never synthesized or estimated here.
-            try {
-                opts?.onUsage?.(msg.usage);
-            }
-            catch {
-                // ignore
-            }
-        }
-        if (msg.reasoning !== undefined) {
-            try {
-                opts?.onReasoning?.(msg.reasoning);
-            }
-            catch {
-                // ignore
-            }
-        }
-        const calls = msg.tool_calls ?? [];
-        if (calls.length === 0) {
-            // Turn-continuation seam (ticket 03): the todo guard and verification
-            // gate run as entries in TURN_END_GATES — one chain, one commit point.
-            // Behavior is byte-identical to the two inline blocks this replaced.
-            const outcome = evaluateTurnEnd(msg.content ?? "", { step, maxSteps, filesWritten, verifiedAfterWrite });
-            if (outcome.kind === "continue") {
-                history.push({ role: "assistant", content: outcome.assistantText });
-                history.push({ role: "user", content: outcome.followUp });
-                continue;
-            }
-            history.push({ role: "assistant", content: outcome.finalText });
-            try {
-                opts?.onPhase?.("done");
-            }
-            catch {
-                // ignore
-            }
-            return outcome.finalText;
-        }
-        if (step >= maxSteps) {
-            const base = msg.content ?? "";
-            const notice = `${base}${base ? "\n" : ""}(stopped: too many tool steps) (limit is ${maxSteps}; raise with ATOM_MAX_TOOL_STEPS=<n>)`;
-            history.push({ role: "assistant", content: notice });
-            try {
-                opts?.onPhase?.("done");
-            }
-            catch {
-                // ignore
-            }
-            return notice;
-        }
-        history.push({ role: "assistant", content: msg.content ?? null, tool_calls: calls });
-        // Commit helper shared by the serial and parallel paths: Task 7
-        // bookkeeping + one ordered transcript entry per call. Only successful
-        // executions count — denials, validation errors, and unknown tools (all
-        // `Error:` results) never ran, so they neither arm nor clear the gate.
-        const commitToolResult = (name, parsed, call, result) => {
-            const isError = typeof result === "string" && result.startsWith("Error");
-            if (!isError && (name === "write" || name === "edit")) {
-                filesWritten = true;
-                verifiedAfterWrite = false;
-            }
-            else if (!isError && name === "bash") {
-                const command = parsed["command"];
-                if (typeof command === "string" && isVerificationCommand(command) && filesWritten) {
-                    verifiedAfterWrite = true;
-                }
-            }
-            history.push({ role: "tool", tool_call_id: call?.id ?? "", content: result });
-            try {
-                opts?.onToolActivity?.(describeToolCall(name, parsed), result, isError);
-            }
-            catch {
-                // ignore observer errors
-            }
-        };
-        for (const batch of planToolBatches(calls)) {
-            // No new executions after a cancel: the current tool (if any) already
-            // finished; stop before starting the next batch.
-            throwIfCancelled(signal);
-            if (batch.length === 1) {
-                // Serial path: byte-identical to the pre-05 loop body.
-                const call = batch[0].call;
-                const name = call?.function?.name ?? "(unknown)";
-                try {
-                    opts?.onPhase?.("tool", name);
-                }
-                catch {
-                    // ignore
-                }
-                let parsed;
-                try {
-                    const raw = call?.function?.arguments ?? "{}";
-                    const v = JSON.parse(typeof raw === "string" ? raw : "{}");
-                    parsed = typeof v === "object" && v !== null ? v : {};
-                }
-                catch {
-                    parsed = {};
-                    const result = `Error: invalid call: invalid JSON arguments for tool "${name}" (arguments must be valid JSON). Fix the arguments and retry.`;
-                    history.push({ role: "tool", tool_call_id: call?.id ?? "", content: result });
-                    try {
-                        opts?.onToolActivity?.(describeToolCall(name, {}), result, true);
-                    }
-                    catch {
-                        // ignore observer errors
-                    }
-                    continue;
-                }
-                let result;
-                try {
-                    result = await runOneTool(call, parsed, opts, execute);
-                }
-                catch (e) {
-                    if (isCancelError(e) || signal?.aborted)
-                        throw new LoopCancelledError();
-                    throw e;
-                }
-                commitToolResult(name, parsed, call, result);
-                continue;
-            }
-            // Parallel batch: every member is pre-validated parallel-safe (see
-            // planToolBatches), so runOneTool neither prompts nor blocks here.
-            // Phases fire upfront in call order; results commit in call order, so
-            // each call still shows separately and tool_call_ids re-pair by index.
-            // A throw (cancel or execution error) aborts the turn exactly like the
-            // serial path — the caller rolls the partial turn back.
-            for (const member of batch) {
-                try {
-                    opts?.onPhase?.("tool", member.call?.function?.name ?? "(unknown)");
-                }
-                catch {
-                    // ignore
-                }
-            }
-            let results;
-            try {
-                results = await Promise.all(batch.map((member) => runOneTool(member.call, member.parsed, opts, execute)));
-            }
-            catch (e) {
-                if (isCancelError(e) || signal?.aborted)
-                    throw new LoopCancelledError();
-                throw e;
-            }
-            for (let i = 0; i < batch.length; i++) {
-                const member = batch[i];
-                commitToolResult(member.call?.function?.name ?? "(unknown)", member.parsed, member.call, results[i]);
-            }
-        }
-    }
+    return planBatches(calls);
 }
+import { runLoopWithChat } from "./agent/loop.js";
+export { runLoopWithChat } from "./agent/loop.js";
+export { DEFAULT_MAX_TOTAL_TOOL_CALLS, DEFAULT_TOOL_TIMEOUT_MS, executeWithTimeout, resolveMaxTotalToolCalls, resolveToolTimeoutMs, } from "./agent/loop.js";
 export async function runAgenticLoopForProvider(provider, apiKey, model, history, opts) {
     return runLoopWithChat((h, o) => chatCompletionForProvider(provider, apiKey, model, h, {
         onToken: o?.onToken,
@@ -1790,6 +1253,22 @@ export async function fetchModelsForProviderWithStatus(provider, apiKey, baseURL
         return { models: [], ok: false };
     const fallback = [...def.fallbackModels];
     try {
+        // Local runtimes: probe the loopback server (short timeout, never
+        // throws) instead of a keyed /models fetch. Chat itself still flows
+        // through the normal openai-chat path below.
+        if (isLocalProviderId(provider)) {
+            const res = await discoverLocalProvider(provider, { baseURL });
+            return { models: res.models.map((m) => m.id), ok: res.ok };
+        }
+        if (provider === "kilo") {
+            // Dynamic catalog via the Kilo gateway (anonymous when apiKey is "",
+            // authenticated otherwise). TTL-cached inside src/kilo.ts; failures
+            // return the offline placeholder uncached, exactly like other kinds.
+            const res = await fetchKiloModelsWithStatus(apiKey);
+            if (!res.ok)
+                return { models: [...KILO_FALLBACK_MODELS], ok: false };
+            return { models: res.models, ok: true };
+        }
         if (provider === "opencode-zen") {
             // Byte-identical rule: reuse fetchModels (compatibility-filtered).
             const endpoint = zenEndpointOverride ?? chatEndpointFor(provider, baseURL);