atom-agent 1.3.0 → 1.5.0

package/dist/agent/tool-pipeline.js

@@ -0,0 +1,398 @@
+// One per-call pipeline for the SERIAL tool path: every serial tool call runs
+// through hook → validate → approve → execute → post-hook → commit in this
+// order, speaking one decision vocabulary and emitting one receipt.
+//
+// Ordering (the serial driver in ./loop.js calls runSerialToolPipeline, then
+// its shared commit funnel, then reports telemetry from the receipt):
+//  1. unknown-name gate (registry toolNames() — the intercepted tools are
+//     members, so no exemption exists).
+//  2. before-hooks (fail CLOSED to blocked; rewrites flow downstream).
+//  3. validation of the effective (post-rewrite) args (fail → inline error).
+//  4. registry-intercepted stage (validated, never needs approval, resolved
+//     without an executor via runInterceptedTool — dispatched by roster
+//     lookup, never by name).
+//  5. approval via the existing hook as-is (ticket 04 owns the policy).
+//  6. execution with timeout + normalization (throw/cancel propagates —
+//     never a receipt, never retried).
+//  7. post-hooks + result hook inside the commit funnel (fail OPEN to the
+//     original result; veto skips the commit).
+//
+// Decision vocabulary — each shape documented once, here:
+// - BeforeOutcome { args, blocked }: pre-hook verdict. `blocked !== null`
+//   commits without executing (first block wins, approval skipped).
+// - string | null from validateToolArgs: non-null detail = invalid args,
+//   committed as an `Error: invalid call: …` result, never executes.
+// - ApprovalDecision | null ("once" | "always" | "no" | null): "no" (or a
+//   throwing approver) denies without executing; null = no approval applies.
+// - string execution result, or a THROWN error (cancel → LoopCancelledError,
+//   aborts the turn; anything else aborts the turn too — never a result).
+// - AfterOutcome { content, isError }: post-hook patch verdict.
+// - ToolResultHookDecision | string | null | void: `content` replaces the
+//   result, `isError` overrides the error flag, `veto: true` skips the
+//   commit; string replaces content; anything else (or a throw) passes the
+//   original through.
+// - PipelineDecisionKind: the serial path's terminal label per call.
+// - ToolCallReceipt: the single receipt telemetry, history, and the
+//   transcript all observe (see the truth choice below).
+//
+// Receipt truth choice: the receipt carries the EFFECTIVE post-before-hook
+// args (what validated, approved, and ran — pre-hook args never executed,
+// so measuring them would bill work that never happened) and the FINAL
+// post-after-hook result (what history/activity/the model see — measuring
+// the pre-patch result would split "what ran" from "what was recorded").
+// What the user sees is what got measured.
+//
+// Parallel batches keep their own pre-pass + ordered commit with pre-commit
+// telemetry (ticket 05): the pre-pass plans each member via planToolCall
+// above (serially, in call order) and members execute through
+// runPlannedToolCall — the same plan/run pair the serial path uses. The
+// batch planner, the serial approval pre-pass, and the ordered commit stay
+// in ./loop.js untouched, so this module never changes parallel behavior.
+//
+// Dependency direction: agent/tool-pipeline -> {config, goal, tools,
+// tools/intercept, agent/normalize, agent/types} and NOT agent/loop or zen
+// (loop.js imports this module; the graph stays acyclic — see
+// tests/architecture.test.ts).
+import { invalidCall, isInterceptedTool, needsApproval, runInterceptedTool, toolNames, validateToolArgs, } from "../tools.js";
+import { afterToolInterceptors, applyAfterInterceptors, applyBeforeInterceptors, beforeToolInterceptors, blockedToolResult, } from "../tools/intercept.js";
+import { normalizeToolResult } from "./normalize.js";
+// 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;
+}
+export function throwIfCancelled(signal) {
+    if (signal?.aborted)
+        throw new LoopCancelledError();
+}
+// Per-tool outer timeout (ms): undefined → default 60s (enabled); explicit
+// <=0/NaN → disabled (direct await, zero overhead). Clamped 1s–120s when
+// enabled so a stuck executor can never hang the turn past the bash ceiling.
+export const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
+export function resolveToolTimeoutMs(raw) {
+    if (raw === undefined)
+        return DEFAULT_TOOL_TIMEOUT_MS;
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return DEFAULT_TOOL_TIMEOUT_MS;
+    if (raw <= 0)
+        return null;
+    return Math.min(Math.max(Math.floor(raw), 1000), 120_000);
+}
+// Race one execution against the outer timeout. Timeout resolves to an
+// `Error:` result (the model adapts); the underlying promise is left to
+// settle — executors own their own cleanup.
+//
+// Cancellation is DELIBERATELY not raced here: the pinned contract is that
+// an in-flight tool runs to completion and its result IS recorded, with the
+// cancel stopping the turn before the next batch/POST (see the
+// throwIfCancelled checks between batches and before each POST). Racing
+// abort against the execution would drop the in-flight result and break
+// assistant/tool pairing guarantees the tests pin. A hung tool + cancel
+// therefore waits for the timeout (≤60s), commits the timeout error, then
+// the next boundary check throws LoopCancelledError.
+export async function executeWithTimeout(execute, name, parsed, timeoutMs, signal) {
+    // No new executions after a cancel: refuse to start when already aborted.
+    if (signal?.aborted)
+        throw new LoopCancelledError();
+    if (timeoutMs === null) {
+        return execute(name, parsed);
+    }
+    let timer = null;
+    try {
+        const execP = execute(name, parsed);
+        const timeoutP = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                const err = new Error(`timeout after ${timeoutMs}ms`);
+                err.code = "ToolTimeout";
+                reject(err);
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([execP, timeoutP]);
+        }
+        catch (e) {
+            if (isCancelError(e))
+                throw e;
+            if (e?.code === "ToolTimeout" || e?.message?.startsWith("timeout after ")) {
+                return `Error: ${name} timed out after ${timeoutMs}ms — retry with a narrower scope or smaller input.`;
+            }
+            throw e;
+        }
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+// Permission-gate resolution shared by the serial path and the parallel
+// pre-pass: returns the hook's decision, or null when no approval applies
+// (no hook, or a tool that never needs it). A "no" (or a throwing hook)
+// denies without executing; cancellation always propagates.
+export async function resolveApproval(name, parsed, opts) {
+    if (!opts?.approve || !needsApproval(name))
+        return null;
+    try {
+        const decision = await opts.approve(name, parsed);
+        // Abort that lands as a resolved denial still cancels the whole turn.
+        throwIfCancelled(opts?.signal);
+        return decision;
+    }
+    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();
+        return "no";
+    }
+}
+// Shared JSON-arguments parse for the serial driver: malformed arguments
+// never reach hooks or executors — the caller routes the null case through
+// the commit funnel as an invalid-call error. Returns the parsed record, or
+// null when the raw arguments are not a JSON object.
+export function parseToolArguments(raw) {
+    try {
+        const text = typeof raw === "string" ? raw : "{}";
+        const value = JSON.parse(text);
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            return value;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// Model-visible result for arguments that are not a JSON object (an
+// `Error: invalid call: …` result, committed normally — the turn continues).
+export function invalidJsonArgsResult(name) {
+    return (`Error: invalid call: invalid JSON arguments for tool "${name}" ` +
+        `(arguments must be valid JSON). Fix the arguments and retry.`);
+}
+// Extension tool-call interception: global pre/post hooks registered via
+// ExtensionAPI.onBeforeToolCall/onAfterToolCall. Both helpers snapshot the
+// live handler list and never throw — a throwing before handler fails
+// closed (blocked outcome), a throwing after handler fails open (original
+// content). Cancellation checks stay where they are; hooks are in-process
+// policy, not executions, so they run even when the signal is armed and the
+// existing boundaries still stop the turn.
+export async function runBeforeIntercept(name, parsed) {
+    try {
+        return await applyBeforeInterceptors(beforeToolInterceptors(), name, parsed);
+    }
+    catch {
+        return { args: parsed, blocked: blockedToolResult(name, "(unknown)", "interception failed") };
+    }
+}
+export async function runAfterIntercept(name, parsed, result, isError) {
+    try {
+        return await applyAfterInterceptors(afterToolInterceptors(), { name, args: parsed, result, isError });
+    }
+    catch {
+        return { content: result, isError };
+    }
+}
+// After-tool-call result hook (issue 06): the single rewrite seam between
+// execution and commit. Absent hook (or null/undefined/void/non-object
+// return) → the original result, byte-identical. A string return replaces
+// content (error flag kept); an object may replace content, override
+// isError, or veto the commit. Hook failures degrade to the original — the
+// turn never breaks. The committed receipt carries the rewrite, so
+// telemetry, history, and activity all observe it.
+export async function applyToolResultHook(hook, name, parsed, result, isError) {
+    if (!hook)
+        return { content: result, isError, veto: false };
+    try {
+        const decision = await hook({ name, args: parsed, result, isError });
+        if (decision === null || decision === undefined)
+            return { content: result, isError, veto: false };
+        if (typeof decision === "string")
+            return { content: decision, isError, veto: false };
+        if (typeof decision === "object") {
+            if (decision.veto === true)
+                return { content: result, isError, veto: true };
+            const content = typeof decision.content === "string" ? decision.content : result;
+            const nextIsError = typeof decision.isError === "boolean" ? decision.isError : isError;
+            return { content, isError: nextIsError, veto: false };
+        }
+        return { content: result, isError, veto: false };
+    }
+    catch {
+        return { content: result, isError, veto: false };
+    }
+}
+// The commit-funnel patch sequence (post-hooks, then the result hook),
+// shared by the serial and parallel commits: every committed result passes
+// through both, in commit order, so tool_call_id re-pairing and ordering
+// are untouched. Never throws (both stages fail open — see above).
+export async function applyCommitPatches(name, parsed, result, isError, hook) {
+    const after = await runAfterIntercept(name, parsed, result, isError);
+    return applyToolResultHook(hook, name, parsed, after.content, after.isError);
+}
+// Model-visible result for an unknown tool name (an `Error: unknown tool:
+// … Available: …` result, committed normally — the turn continues).
+export function unknownToolResult(name) {
+    return `Error: unknown tool "${name}". Available: ${toolNames().join(", ")}`;
+}
+export async function planToolCall(name, parsed, opts) {
+    // Unknown-name gate: the registry's toolNames() is the single source — it
+    // already includes the intercepted tools, so no exemption is needed.
+    if (!toolNames().includes(name)) {
+        return {
+            plan: { args: parsed, blocked: null, invalid: null, unknown: unknownToolResult(name) },
+            preDecision: null,
+        };
+    }
+    const pre = await runBeforeIntercept(name, parsed);
+    if (pre.blocked !== null) {
+        return {
+            plan: { args: pre.args, blocked: pre.blocked, invalid: null, unknown: null },
+            preDecision: null,
+        };
+    }
+    const invalid = validateToolArgs(name, pre.args);
+    if (invalid) {
+        return {
+            plan: { args: pre.args, blocked: null, invalid, unknown: null },
+            preDecision: null,
+        };
+    }
+    const preDecision = await resolveApproval(name, pre.args, opts);
+    return {
+        plan: { args: pre.args, blocked: null, invalid: null, unknown: null },
+        preDecision,
+    };
+}
+// The ONE per-call runner: a planned call either yields its inline result
+// (unknown/blocked/invalid — never executes; denial resolves inside the
+// shared stages via the pre-decision) or executes through the shared
+// validate → intercepted → approve-or-preDecision → execute stages. Serial
+// calls plan+run inline; parallel members plan serially in the pre-pass,
+// then run here concurrently.
+export async function runPlannedToolCall(call, plan, preDecision, opts, execute, onUpdateGoal) {
+    if (plan.unknown !== null) {
+        return { result: plan.unknown, args: plan.args, decision: "unknown-tool" };
+    }
+    if (plan.blocked !== null) {
+        return { result: plan.blocked, args: plan.args, decision: "blocked" };
+    }
+    if (plan.invalid !== null) {
+        return { result: invalidCall(plan.invalid), args: plan.args, decision: "invalid-args" };
+    }
+    return runStagesWithDecision(call, plan.args, opts, execute, preDecision, onUpdateGoal);
+}
+// Inner execution after pre-interception: validate (rewritten) args, then
+// the registry-intercepted stage, then permission, then the executor. Kept
+// for import compatibility; new code prefers planToolCall +
+// runPlannedToolCall.
+export async function runOneToolWithArgs(call, parsed, opts, execute, preDecision, onUpdateGoal) {
+    const outcome = await runStagesWithDecision(call, parsed, opts, execute, preDecision, onUpdateGoal);
+    return { result: outcome.result, args: outcome.args };
+}
+async function runStagesWithDecision(call, parsed, opts, execute, preDecision, onUpdateGoal) {
+    const name = call?.function?.name ?? "(unknown)";
+    // Argument validation BEFORE approval/execution: model mistake, never runs.
+    // Pre-hook rewrites arrive here already applied, so they re-validate on
+    // exactly what would execute — invalid rewrites never reach an executor.
+    const detail = validateToolArgs(name, parsed);
+    if (detail) {
+        return { result: invalidCall(detail), args: parsed, decision: "invalid-args" };
+    }
+    // Intercepted tools (ask_question/update_goal): validated above, never need
+    // approval, resolved without an executor. Dispatched by registry roster
+    // lookup — never by name — so visibility and executability stay one list.
+    if (isInterceptedTool(name)) {
+        throwIfCancelled(opts?.signal);
+        // If the signal aborts during the modal, the runner rethrows raw and the
+        // mapping below raises 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).
+        try {
+            const resolved = await runInterceptedTool(name, parsed, {
+                askUser: opts?.askUser,
+                signal: opts?.signal,
+                onUpdateGoal,
+            });
+            // Non-null by roster contract (isInterceptedTool just matched); the
+            // fallthrough keeps this total if the roster ever drifts — the call
+            // then flows into approval/execution like any other known tool.
+            if (resolved !== null) {
+                return { result: resolved.result, args: parsed, decision: resolved.decision };
+            }
+        }
+        catch (e) {
+            if (isCancelError(e) || opts?.signal?.aborted)
+                throw new LoopCancelledError();
+            throw e;
+        }
+    }
+    const decision = preDecision ?? (await resolveApproval(name, parsed, opts));
+    if (decision === "no") {
+        return { result: `Error: denied by user: ${name}`, args: parsed, decision: "denied" };
+    }
+    // "once"/"always" run this call (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);
+    const timeoutMs = resolveToolTimeoutMs(opts?.toolTimeoutMs);
+    const doNormalize = opts?.normalizeResults !== false;
+    try {
+        const raw = await executeWithTimeout(execute, name, parsed, timeoutMs, opts?.signal);
+        if (doNormalize)
+            return { result: normalizeToolResult(raw), args: parsed, decision: "executed" };
+        return { result: typeof raw === "string" ? raw : normalizeToolResult(raw), args: parsed, decision: "executed" };
+    }
+    catch (e) {
+        if (isCancelError(e) || opts?.signal?.aborted)
+            throw new LoopCancelledError();
+        throw e;
+    }
+}
+// The ONE serial per-call pipeline: unknown-name gate → before-hooks →
+// validate → approve → execute (stages 1–6 above), returning the execution
+// result with the effective args and the terminal decision. Post-hooks and
+// the commit run in the shared commit funnel (via applyCommitPatches), so
+// the serial and parallel commits patch identically; the serial driver
+// reports telemetry from the funnel's receipt, unifying all three observers.
+// Hook-vs-approval ordering: pre-hooks run BEFORE validation and approval.
+// The hook sees the call pre-approval and may rewrite args before the
+// approval prompt shows them; a block short-circuits approval entirely (no
+// prompt for a call that never runs). Rewrites always re-validate before
+// execution, so a hook can never smuggle unvalidated args into an executor.
+// Unknown names never reach hooks (model mistake — nothing would run).
+// Registry-intercepted tools (ask_question/update_goal) pass the gate like
+// any known tool: the stages below validate them and resolve them without
+// an executor (never needs approval). ask_question never needs approval;
+// without an askUser hook it resolves to "Error: ask_question has no UI
+// hook". update_goal never needs approval either; without the per-turn
+// recorder it resolves to the outside-turn error. Model mistakes (unknown
+// name, invalid args) return repair-oriented results WITHOUT executing;
+// cancellations propagate as LoopCancelledError (never a result, never
+// retried).
+export async function runSerialToolPipeline(call, parsed, opts, execute, onUpdateGoal) {
+    const name = call?.function?.name ?? "(unknown)";
+    const { plan, preDecision } = await planToolCall(name, parsed, opts);
+    return runPlannedToolCall(call, plan, preDecision, opts, execute, onUpdateGoal);
+}

package/dist/agent/turn-events.js

@@ -0,0 +1,12 @@
+// Guarded emission: runs emit against the sink, swallowing observer errors so
+// a throwing sink can never break the turn. No-op when the sink is absent.
+export function emitTurnEvent(sink, emit) {
+    if (!sink)
+        return;
+    try {
+        emit(sink);
+    }
+    catch {
+        // observer errors never break the loop
+    }
+}

package/dist/cli.js

@@ -22,7 +22,39 @@ if (args.includes("--dashboard")) {
     console.error("Dashboard failed to write — telemetry store unavailable.");
     process.exit(1);
 }
-if (args.includes("--serve")) {
+if (args.includes("--web")) {
+    // ATOM WebUI: local agentic frontend over the same runtime as the TUI
+    // (loopback-only, Ctrl+C stops). The TUI below never starts alongside it.
+    const flagValue = (name) => {
+        const eq = args.find((a) => a.startsWith(`${name}=`));
+        if (eq !== undefined)
+            return eq.slice(name.length + 1);
+        const i = args.indexOf(name);
+        if (i !== -1 && i + 1 < args.length) {
+            const next = args[i + 1];
+            if (!next.startsWith("-"))
+                return next;
+        }
+        return undefined;
+    };
+    (async () => {
+        const { resolveWebPort, startWebServer } = await import("./web/server.js");
+        const server = await startWebServer({ port: resolveWebPort(process.env, flagValue("--port")) });
+        console.log(`ATOM WebUI at ${server.url} (loopback-only — Ctrl+C to stop).`);
+        console.log(`JSON API: ${server.url}api/health · ${server.url}api/providers · ${server.url}api/sessions`);
+        const stop = () => {
+            server.close().then(() => process.exit(0), () => process.exit(0));
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        await new Promise(() => { });
+    })().catch((e) => {
+        const detail = e instanceof Error ? e.message : String(e);
+        console.error(`ATOM WebUI failed to start (${detail}). Is the port already in use? Try --port <n>.`);
+        process.exit(1);
+    });
+}
+else if (args.includes("--serve")) {
     // Local observability webUI: serve the live dashboard + read-only JSON API
     // on loopback (Ctrl+C stops). The static --dashboard file is untouched.
     const flagValue = (name) => {
@@ -58,7 +90,8 @@ else if (args.includes("--help") || args.includes("-h")) {
     console.log(`Atom chatbot (Ink TUI)
 Usage: npm start
 Flags: --dashboard (write ~/.atom/telemetry/dashboard.html and exit)
-       --serve [--port <n>] (serve the live dashboard webUI on loopback and keep running)
+        --serve [--port <n>] (serve the live dashboard webUI on loopback and keep running)
+        --web [--port <n>] (serve the agentic WebUI on loopback and keep running)
        --no-extensions (--lockdown alias: boot with zero third-party extensions; builtins unchanged)
        --enable-extension <glob> (repeatable; only matching extensions load)
        --disable-extension <glob> (repeatable; wins over --enable-extension)
@@ -68,7 +101,7 @@ Env:
   OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY / MISTRAL_API_KEY / GEMINI_API_KEY (GOOGLE_API_KEY alias)  optional per provider (env wins over stored)
   OPENCODE_ZEN_MODEL    optional (default: ${DEFAULT_MODEL}; when set, wins over the saved /model)
   OPENCODE_ZEN_ENDPOINT optional (default: ${DEFAULT_ENDPOINT})
- Commands: /model (model picker) | /models [refresh] (local discovery refresh; Kilo catalog refresh when Kilo is active) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /goal <objective> (pin one session objective; bare shows it, pause/resume/clear manage it) | /compact [focus] (summarize older turns) | /tools | /skills (list installed skills) | /skill:name (invoke) | /context (context usage) | /queue + /steer (follow-ups while busy) | /autoscroll (toggle follow new output) | /thinking (toggle reasoning visibility) | /mode | /trust | /allow | /deny | /rules | /clear | /new (fresh conversation, previous kept) | /rename <name> (rename current session) | /session (switch session picker) | /resume (restore last saved session) | /telemetry | /dashboard | /rewind | /help | /exit | /quit — Tab cycles the permission mode normal → yolo → plan → normal (extension slash commands appear in the / menu and palette, not in this static list)
+ Commands: /model [filter|refresh] (model picker; refresh re-probes local servers, Kilo catalog refresh when Kilo is active) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /goal <objective> (pin one session objective; bare shows it, pause/resume/clear manage it) | /compact [focus] (summarize older turns) | /tools | /skill (skill picker) | /skill:name (invoke) | /context (context usage) | /queue + /steer (follow-ups while busy) | /autoscroll (toggle follow new output) | /thinking (toggle reasoning visibility) | /mode | /trust | /allow | /deny | /rules | /clear | /new (fresh conversation, previous kept) | /rename <name> (rename current session) | /session (switch session picker) | /resume (restore last saved session) | /telemetry | /dashboard | /rewind | /help | /exit | /quit — Tab cycles the permission mode normal → yolo → plan → normal (extension slash commands appear in the / menu and palette, not in this static list)
 Providers: kilo (default; anonymous free models, key optional)/opencode-zen/openai/anthropic/deepseek/mistral/google-gemini/openai-compatible (keys in ~/.atom/auth.json, 0600 POSIX; use /provider to paste one) + local auto-discovery: ollama (:11434), lmstudio (:1234), llamacpp (:8080) — no keys needed, overrides via ATOM_OLLAMA_URL/ATOM_LMSTUDIO_URL/ATOM_LLAMACPP_URL.
 Effort (Auto/Low/Medium/High/Max) applies on every provider: reasoning_effort for OpenAI-chat kinds, thinking budgets for Anthropic, thinking levels for Gemini. Auto omits the knob.`);
     process.exit(0);
@@ -93,16 +126,32 @@ const envModel = process.env.OPENCODE_ZEN_MODEL?.trim() || undefined;
 // /provider pointer; nothing is POSTed.
 // --serve parks above (the server holds the event loop), so the TUI must
 // never start alongside it: serve is a standalone mode like --dashboard.
-if (!args.includes("--serve")) {
-    // Production frame policy (Ink 7.1.1):
+// Same for --web (the agentic WebUI server owns the process instead).
+if (!args.includes("--serve") && !args.includes("--web")) {
+    // Production frame policy (Ink 7.1.1), measured with
+    // scripts/bench-render.mjs (real render root, fake TTY, 100x30):
     // - incrementalRendering: only changed terminal lines rewrite per frame.
-    //   Streaming paints touch the live tail + status bar, not the scrollback,
-    //   so this cuts flicker and stdout bytes on every token flush.
+    //   Streaming paints touch the live tail + status bar, not the scrollback.
+    //   Measured ~3x fewer stdout bytes than full-frame on sustained
+    //   streaming (paced 300-token run: ~66KB vs ~195KB) with identical
+    //   frames — strictly less flicker, zero behavior change. Compatible
+    //   with the whole UI (no full-screen chrome depends on reprints).
     //   Escape hatch: ATOM_INCREMENTAL=0 restores full-frame rendering.
     // - maxFps: 30 keeps keystroke-to-paint latency low; token paints already
-    //   coalesce to ~15fps via DRAFT_THROTTLE_MS, so Ink never does extra work.
+    //   coalesce to ~15fps via the paint scheduler, so Ink never does extra
+    //   work. Measured 15fps: fewer total bytes but the same clears-per-frame
+    //   (clears are driven by frame HEIGHT on win32, not rate) — halving the
+    //   cap would trade responsiveness for no structural gain. FPS limiting
+    //   is deliberately NOT used as a flicker fix.
     // - concurrent: enables React concurrent features (useTransition /
     //   useDeferredValue) for future deferral of expensive subtrees.
+    //   Measured neutral vs sync mode (frames/bytes within noise), kept for
+    //   the deferral option, not for current gains.
+    // Not configurable here (and intentionally so): full-screen clears come
+    // from frame geometry (win32 clears whenever the frame fills the
+    // viewport), so they are fixed by keeping the live frame short
+    // (windowed thinking, capped approval preview, coalesced paints) —
+    // no render flag can substitute for that.
     // Tests are unaffected: they render via ink-testing-library, not here.
     render(_jsx(App, { apiKey: apiKey, endpoint: endpoint, initialModel: envModel, restorePrefs: true, extensionsLockdown: extFlags.lockdown, enableExtensions: extFlags.enable, disableExtensions: extFlags.disable }), {
         incrementalRendering: process.env.ATOM_INCREMENTAL !== "0",

package/dist/compact.js

@@ -20,12 +20,23 @@ import { chatCompletionForProvider, } from "./zen.js";
 // ContextManager module; compact.ts imports what its splitter needs and
 // re-exports the stable surface so existing importers keep working untouched.
 import { estimateTokensForChars, messageChars } from "./context-manager.js";
+import { usableLimitFor } from "./overflow.js";
 import { truncateHead } from "./tools/shared.js";
 export { COMPACT_PCT_DEFAULT, compactPct, computeContextLoad, estimateTokensForChars, historyChars, shouldAutoCompact, } from "./context-manager.js";
 // ---- Constants ----
 export const COMPACT_KEEP_TOKENS = 20000;
 export const COMPACT_SUMMARY_MAX_TOKENS = 4096;
 export const COMPACT_TOOL_OUTPUT_CAP = 2000;
+// Budgeted tail band (issue 04, opencode reference): the retained tail is
+// 25% of the model's usable limit (verified window minus reserve), clamped
+// to [MIN, MAX]. Models with no verified window never fabricate one — they
+// fall back to COMPACT_KEEP_TOKENS (the pre-existing fixed tail).
+export const COMPACT_TAIL_MIN_TOKENS = 2000;
+export const COMPACT_TAIL_MAX_TOKENS = 15000;
+// Cleared marker for pruned old tool outputs. Same `[truncated: ...]`
+// family as capToolOutputsInTail — never a second convention. Short by
+// design: the summary carries the story, not this placeholder.
+export const COMPACT_PRUNED_TOOL_OUTPUT = "[truncated: old tool output cleared]";
 // opencode's 4ch/token heuristic (V2 preflight estimate): chars/4 floors to
 // estimated tokens. Used for load fallback + tail split only, never for the
 // `token: n/a` honesty rule or the NK cumulative spend.
@@ -74,18 +85,53 @@ export function capToolOutputsInTail(tail) {
         return { ...m };
     });
 }
+// Tail budget for a model (issue 04): 25% of the usable limit from
+// overflow.ts (read-only — trigger semantics untouched), clamped to the
+// [MIN, MAX] band. Unknown/blank models fall back to COMPACT_KEEP_TOKENS.
+export function tailKeepTokensForModel(model) {
+    if (typeof model !== "string" || model.length === 0)
+        return COMPACT_KEEP_TOKENS;
+    const usable = usableLimitFor(model);
+    if (usable === undefined)
+        return COMPACT_KEEP_TOKENS;
+    const quarter = Math.floor(usable * 0.25);
+    return Math.min(COMPACT_TAIL_MAX_TOKENS, Math.max(COMPACT_TAIL_MIN_TOKENS, quarter));
+}
+// Prune pass for old tool outputs (issue 04): bulky tool results OUTSIDE the
+// protected newest window (i.e. in the head being summarized) collapse to the
+// short cleared marker so the summary POST stays small even when the session
+// holds huge dumps. Small outputs pass through verbatim so the summary keeps
+// fidelity; the retained tail is NEVER passed here — its outputs stay
+// intact, and the newest turn is never pruned. Idempotent (the marker itself
+// is far below the cap).
+export function pruneOldToolOutputs(head) {
+    return head.map((m) => {
+        if (m?.role === "tool" &&
+            typeof m.content === "string" &&
+            m.content.length > COMPACT_TOOL_OUTPUT_CAP) {
+            return { ...m, content: COMPACT_PRUNED_TOOL_OUTPUT };
+        }
+        return { ...m };
+    });
+}
 // Split history (after system) into head + retained newest tail of whole
-// user-turns up to KEEP_TOKENS estimated tokens (chars/4). Tool outputs in
-// the tail are capped at 2000 chars each. Never drops history[0]; always
-// keeps at least the newest turn; when everything fits but there is more
-// than one turn, keeps only the newest turn in the tail so manual /compact
-// still has an older turn to summarize.
-export function splitHistoryForCompaction(history, keepTokens = COMPACT_KEEP_TOKENS) {
+// user-turns up to a token budget estimated at chars/4. The budget is
+// keepTokens by default (COMPACT_KEEP_TOKENS fallback); pass a model id to
+// scale it with that model's usable limit via tailKeepTokensForModel (the
+// model wins when given — unknown models fall back to the same fixed tail).
+// Tool outputs in the tail are capped at 2000 chars each. Never drops
+// history[0]; always keeps at least the newest turn; when everything fits
+// but there is more than one turn, keeps only the newest turn in the tail
+// so manual /compact still has an older turn to summarize.
+export function splitHistoryForCompaction(history, keepTokens = COMPACT_KEEP_TOKENS, model) {
     if (history.length <= 1)
         return { head: [], tail: [], olderTurnCount: 0 };
     const starts = turnStarts(history);
     if (starts.length === 0)
         return { head: [], tail: [], olderTurnCount: 0 };
+    const budget = typeof model === "string" && model.length > 0
+        ? tailKeepTokensForModel(model)
+        : keepTokens;
     let totalChars = 0;
     let tailStart = starts[starts.length - 1];
     for (let s = starts.length - 1; s >= 0; s--) {
@@ -93,7 +139,7 @@ export function splitHistoryForCompaction(history, keepTokens = COMPACT_KEEP_TOK
         const end = turnEnd(history, start, starts);
         totalChars += turnChars(history, start, end);
         const est = estimateTokensForChars(totalChars);
-        if (est <= keepTokens) {
+        if (est <= budget) {
             tailStart = start;
         }
         else {
@@ -122,6 +168,11 @@ export function splitHistoryForCompaction(history, keepTokens = COMPACT_KEEP_TOK
 // and next steps inside its prose (the canonical `Goal:` block is appended
 // separately after the POST). Absent/blank reads exactly as before, so
 // non-goal compaction output stays byte-identical.
+// Chaining (ticket 03): on a second or later compaction the head opens with
+// a prior "[Compacted context ...]" summary message. The summarizer merges
+// it forward — Objective, key decisions, and Relevant Files survive every
+// link in the chain — and when the prior summary conflicts with newer
+// conversation, the newer conversation wins.
 export function buildCompactionInstruction(focusText, goalObjective) {
     const focus = typeof focusText === "string" && focusText.trim().length > 0
         ? `\nFocus for this summary: ${focusText.trim()}\n`
@@ -142,6 +193,12 @@ export function buildCompactionInstruction(focusText, goalObjective) {
         `### Blocked\n` +
         `## Next Move\n` +
         `## Relevant Files\n` +
+        `Chaining: the history may open with a prior compaction summary ("[Compacted context ...]"). ` +
+        `Merge it forward — carry its Objective, key decisions, and Relevant Files into this summary ` +
+        `so a chain of compactions never loses the original goal. ` +
+        `When the prior summary conflicts with newer conversation, the newer conversation wins; ` +
+        `discard the stale fact and keep only what the newer turns confirm or what is carried forward explicitly. ` +
+        `Preserve file paths and identifiers verbatim.\n` +
         `Rules: no tools are available for this request — answer with the summary text only, no tool calls, no preamble beyond the headings.`);
 }
 export function buildSummaryMessages(systemContent, head, focusText, goalObjective) {
@@ -203,12 +260,19 @@ export function truncateHeadForRetry(head) {
 // throw immediately with history untouched (caller must not swap).
 export async function requestCompactSummary(req) {
     const attempt = async (head) => {
-        const messages = buildSummaryMessages(req.systemContent, head, req.focusText, req.goalObjective);
+        // Issue 04: bulky tool outputs outside the protected tail collapse to
+        // the cleared marker before the POST, so a session full of huge dumps
+        // still summarizes in one cheap request. The tail never flows through
+        // here — only the head — so newest-turn outputs stay intact.
+        const messages = buildSummaryMessages(req.systemContent, pruneOldToolOutputs(head), req.focusText, req.goalObjective);
         const res = await chatCompletionForProvider(req.provider, req.apiKey, req.model, messages, {
             baseURL: req.baseURL,
             endpointOverride: req.endpointOverride,
             disableTools: true,
             maxOutputTokens: COMPACT_SUMMARY_MAX_TOKENS,
+            // The summarizer needs prose, not pixels: media descriptors stay
+            // as markers so the summary POST stays text-only and cheap.
+            stripMedia: true,
             ...(req.signal ? { signal: req.signal } : {}),
         });
         // Totals keep accumulating: forward real summary usage when present.