atom-agent 1.3.0 → 1.5.0

package/dist/zen.js

@@ -5,7 +5,7 @@
 // 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";
@@ -86,6 +86,7 @@ export function reasoningEffortParam(effort, _model) {
         return undefined;
     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) {
@@ -782,6 +783,9 @@ 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++) {
         try {
             throwIfCancelled(signal);
@@ -795,13 +799,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 +828,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" &&
@@ -871,6 +895,25 @@ 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);
+                    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
@@ -1007,6 +1050,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 +1074,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 +1126,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 +1141,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 +1194,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 +1295,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 +1310,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 +1363,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 &&
@@ -1430,9 +1532,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
@@ -1486,6 +1596,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

package/documentation/cli.md

@@ -10,9 +10,11 @@ atom             # run the installed binary (runs dist/cli.js)
 atom --help      # usage, env vars, commands, providers (exits, no TUI)
 atom --dashboard # write ~/.atom/telemetry/dashboard.html and exit (no TUI)
 atom --serve [--port <n>]  # serve the live observability webUI on loopback (no TUI, Ctrl+C stops)
+atom --web [--port <n>]    # serve the local agentic Web UI on loopback (no TUI, Ctrl+C stops)
+atom --no-extensions        # boot with zero third-party extensions (alias: --lockdown)
 ```
 
-`--help` (or `-h`) prints usage and exits. `--dashboard` and `--serve` handle local observability without starting the TUI (see [Observability](observability.md)). Any other invocation starts the TUI, even without a key.
+`--help` (or `-h`) prints usage and exits. `--dashboard` and `--serve` handle local observability without starting the TUI (see [Observability](observability.md)). `--web` starts the agentic Web UI over the same runtime as the TUI (loopback-only; JSON API at `/api/health`, `/api/providers`, `/api/sessions`). Extension flags (`--no-extensions` / `--lockdown`, repeatable `--enable-extension <glob>` / `--disable-extension <glob>`) control third-party extension loading and win over `atom.json` (see [Extensions](extensions.md) and [Configuration](configuration.md)). Any other invocation starts the TUI, even without a key.
 
 ## Slash commands
 
@@ -20,16 +22,14 @@ Type `/` to autocomplete as you type. Full registry (`src/App.tsx`):
 
 | Command | What it does |
 |---|---|
-| `/model` | Unified model picker: active provider first, then other keyed providers plus the always-visible keyless Kilo list (free models badged `(free)`, `free` filters them). Cross-provider pick switches provider |
-| `/models [refresh]` | Local discovery status; `refresh` re-probes local servers (or the Kilo gateway catalog while Kilo is active) |
+| `/model [filter\|refresh]` | Unified model picker: active provider first, then other keyed providers plus the always-visible keyless Kilo list (free models badged `(free)`, `free` filters them). Cross-provider pick switches provider. `refresh` re-probes local servers (or the Kilo gateway catalog while Kilo is active); plain text pre-filters the picker |
 | `/provider` | Provider plus key picker; validates and stores in `~/.atom/auth.json` (Kilo key optional — empty Enter continues anonymously) |
   | `/new` | Start a brand-new session (conversation plus counters reset, previous kept for `/resume`) |
   | `/rename <name>` | Rename the current session (id and history untouched; quotes optional) |
 | `/plan`, `/yolo` | Retired as typed commands — `Tab` is the only mode switcher (normal → yolo → plan → normal); typing them explains this instead of switching |
 | `/effort` | Reasoning-effort picker (`Auto`/`Low`/`Medium`/`High`/`Max`; sent for every model on every provider — `reasoning_effort` on OpenAI-chat, thinking budget on Anthropic, thinking level on Gemini; `Auto` omits it) |
 | `/tools` | List tools with one-line descriptions |
-| `/skills` | List installed skills (project plus global) |
-| `/skill` | Invoke a skill by name (`/skill:name`; skills also complete in the `/` menu) |
+| `/skill [name]` | Skill picker (list, filter, invoke); `/skill:name` invokes directly (skills also complete in the `/` menu) |
 | `/context` | Show context usage by source (system, tools, history, skills, config, prefix-cache) |
 | `/queue` | List queued follow-ups (`/queue clear` wipes; cap 10, in-memory only) |
 | `/steer` | Steer the running turn, or send when idle (`/steer <text>`) |

package/documentation/configuration.md

@@ -24,9 +24,12 @@ Template lives in `.env.example`. Never commit a real key.
 | `ATOM_TELEMETRY` | Local observability recording (`0`/`false`/`no`/`off` disables; `1`/`true`/`yes`/`on` forces on) | on (wins over `atom.json`) |
 | `ATOM_TELEMETRY_PORT` | Pinned port for the observability webUI (`atom --serve`; `--port` wins over this) | ephemeral (OS-assigned, printed on start) |
 | `ATOM_EXTENSIONS` | Extra extension directory for discovery (project, global, then this; see [Extensions](extensions.md)) | none |
-| `ATOM_OLLAMA_URL` | Ollama base URL override for local discovery | `http://localhost:11434` |
-| `ATOM_LMSTUDIO_URL` | LM Studio base URL override for local discovery | `http://localhost:1234` |
-| `ATOM_LLAMACPP_URL` | llama.cpp base URL override for local discovery | `http://localhost:8080` |
+| `ATOM_OLLAMA_URL` | Ollama base URL override for local discovery | `http://127.0.0.1:11434` |
+| `ATOM_LMSTUDIO_URL` | LM Studio base URL override for local discovery | `http://127.0.0.1:1234` |
+| `ATOM_LLAMACPP_URL` | llama.cpp base URL override for local discovery | `http://127.0.0.1:8080` |
+| `ATOM_STALL_TIMEOUT_MS` | Silent-stream stall guard for streaming readers | `60000` (60s; fails fast instead of hanging a silent 200-OK stream) |
+| `ATOM_FAST_LIST` | File-listing fast path (`0` forces the legacy walker) | fast path on |
+| `ATOM_INCREMENTAL` | Incremental Ink rendering (`0` restores full-frame rendering) | incremental on |
 
 `openai-compatible` uses stored key plus baseURL only. No env vars.
 
@@ -44,8 +47,10 @@ Precedence overall: env vars > saved session picks (`/model`, `/provider`, `/eff
 | `provider` | First-run default provider (needs its key, except keyless Kilo/local) | known provider id |
 | `model` | Default model id | non-empty string |
 | `reasoningEffort` | Default reasoning effort | `auto`/`low`/`medium`/`high`/`max` (`default` still accepted as an alias for `auto`) |
-| `maxToolSteps` | Tool rounds per turn | 5-100 (default 30) |
+| `maxToolSteps` | Optional cap on tool rounds per turn (`ATOM_MAX_TOOL_STEPS` wins over this) | 5-100 (default uncapped; the shipped `atom.example.json` sets `30` as a starting point) |
 | `compactPct` | Auto-compact percent of verified window | 50-95 (default 83) |
+| `compactAuto` | Master switch for automatic compaction (manual `/compact` always works) | boolean (default on) |
+| `compactReserve` | Reserved output buffer in tokens for the usable-limit calculation | 4096-100000 (tokens) |
 | `network` | Webfetch SSRF policy: which network zones the model may retrieve | object with boolean `allowPublic` (default true), `allowLocalhost` (default true), `allowPrivate` (default false), `allowLinkLocal` (default false) |
 | `telemetry` | Local observability recording (see [Observability](observability.md)) | `{enabled?: boolean}` (default on; `ATOM_TELEMETRY=0` wins) |
 | `extensions` | Extension enable/disable patterns by name (see [Extensions](extensions.md); CLI `--enable-extension`/`--disable-extension` win over this) | `{enabled?: string[], disabled?: string[]}` (default load all; `disabled` wins over `enabled`) |
@@ -90,7 +95,7 @@ The allowance is informational only: history is never truncated — there are no
 
 ## Session file
 
-`~/.atom/session.json`, version 1, atomic temp-plus-rename saves, `0600` POSIX. See [Sessions](sessions.md).
+Single-turn save: `~/.atom/session.json`, version 1, atomic temp-plus-rename saves, `0600` POSIX. Durable multi-session records live under `~/.atom/sessions/<id>.json` plus a plaintext `active` pointer. See [Sessions](sessions.md).
 
 ## AGENTS.md and system prompt
 
@@ -104,7 +109,7 @@ Final system prompt is two layers (`src/system.ts`, `src/zen.ts`):
 - Repo overlay: `AGENTS.md` in cwd, or `OPENCODE_AGENTS_PATH` override. Capped at 12KB
 - To change bot identity, edit the one-liner. To add project instructions, edit `AGENTS.md`
 
-ATOM loads the project `AGENTS.md` at startup so it knows tools, rules, and permission model. This repo own instructions live in `AGENTS.md` at the root.
+ATOM loads the project `AGENTS.md` at startup when present, so it picks up repo tools, rules, and permission model. This checkout ships no `AGENTS.md` (per-project overlay only).
 
 ## Context windows
 

package/documentation/development.md

@@ -17,7 +17,8 @@ Build output goes to `dist/` (`atom` runs `dist/cli.js`). `dist/` is gitignored
 npm start        # tsx src/cli.tsx
 npm test         # vitest run (fully mocked, never hits live APIs)
 npm run typecheck  # tsc --noEmit
-npm run build    # tsc -p tsconfig.build.json (src -> dist)
+npm run build    # tsc -p tsconfig.build.json (src -> dist) plus copy-web-ui (web UI assets into dist/)
+npm run bench    # node scripts/bench-render.mjs (render-throughput benchmark)
 ```
 
 Tests use `"test-key"` placeholders. Never paste a real key into fixtures, logs, or commits.
@@ -27,7 +28,7 @@ Tests use `"test-key"` placeholders. Never paste a real key into fixtures, logs,
 ```text
 .
 ├── src/
-│   ├── cli.tsx    # entry: --help/--dashboard/--serve, always starts TUI (missing key guides to /provider)
+│   ├── cli.tsx    # entry: --help/--dashboard/--serve/--web, extension flags; always starts TUI otherwise (missing key guides to /provider)
 │   ├── App.tsx    # Ink TUI: transcript, pickers (/model /provider /effort), modes, status line
 │   ├── context-windows.ts # curated per-model context windows + `token: (P%) NK` format
 │   ├── compact.ts # context compaction: load/trigger math, split, summary POST (tools off, 4096 cap)
@@ -59,4 +60,4 @@ Add or update tests for behavior changes. A fix without a test that would have c
 
 ## Agent workflow in this repo
 
-The repo `AGENTS.md` defines the loop the agent follows: read before edit, 30 tool rounds per turn by default, todowrite list for 3 or more steps with exactly one `in_progress`, verify every change with the suite. Issues live as local markdown under `.scratch/` (see [Issue tracker](agents/issue-tracker.md)).
+The repo `AGENTS.md` defines the loop the agent follows: read before edit, uncapped tool rounds per turn by default (optional cap via `ATOM_MAX_TOOL_STEPS` / `maxToolSteps`, clamped 5-100), todowrite list for 3 or more steps with exactly one `in_progress`, verify every change with the suite. Issues live as local markdown under `.scratch/` (see [Issue tracker](../docs/agents/issue-tracker.md)).

package/documentation/extensions.md

@@ -146,7 +146,7 @@ Exact `ExtensionAPI` methods — nothing else exists:
 | `isProjectTrusted()` | Whether this load is trusted (degrade gracefully when false) |
 | `setStatusSegment(text)` | One status-bar slot per extension (upsert by owner) |
 | `setWidget(def)` | Panel widget (`placement: "panel"`, keyed by owner + id) |
-| `notify(message)` | Transient `(name) message` transcript line |
+| `notify(message)` | Transient `(name) message` transcript line (staged queue caps at 100, drop-oldest) |
 | `promptUser(question, options?, allowCustom?)` | Modal dialog; rejects headless, during activation, or while one is open |
 
 Stores behind the API: `src/tools/custom.ts`, `intercept.ts`, `overrides.ts`, `provider-hooks.ts`, `compaction-hooks.ts`, `src/extension-commands.ts`, `src/extension-ui.ts`, `src/project-trust.ts`.

package/documentation/goals.md

@@ -30,7 +30,7 @@ One pinned session goal that keeps the agent working turn-to-turn until it is do
 
 ## Known limits
 
-- The `update_goal` schema is not in the chat-payload `tools` list — the model discovers it through the continuation message prose, not a tool definition.
+- The `update_goal` schema rides the chat-payload `tools` list only while a goal turn is live (hidden on non-goal turns so it cannot be misused); the model discovers it through the continuation message prose plus the live tool definition.
 - Multi-turn goal behavior against live models is unproven; the loop, judge, and gate paths are covered by mocked suites.
 
 ## Code

package/documentation/index.md

@@ -35,7 +35,7 @@ This index is the entry point. The README stays focused on evaluate, install, an
 
 Project conventions the agent itself loads at runtime:
 
-- [AGENTS.md](../AGENTS.md) - agent instructions loaded into the system prompt
-- [Issue tracker](agents/issue-tracker.md) - local markdown issues under `.scratch/`
-- [Triage labels](agents/triage-labels.md) - canonical triage roles
-- [Domain docs](agents/domain.md) - CONTEXT.md plus ADR conventions
+- `AGENTS.md` (per-project, when present) - agent instructions loaded into the system prompt
+- [Issue tracker](../docs/agents/issue-tracker.md) - local markdown issues under `.scratch/`
+- [Triage labels](../docs/agents/triage-labels.md) - canonical triage roles
+- [Domain docs](../docs/agents/domain.md) - CONTEXT.md plus ADR conventions

package/documentation/providers.md

@@ -20,7 +20,7 @@ Keys are never printed full (masked as last4), never logged, never in fixtures (
 ## Kilo Gateway (default)
 
 - Kilo is ATOM's default provider: fresh installs start on Kilo with no key required
-- The model catalog is discovered live via `GET https://api.kilo.ai/api/gateway/models` (cached for 5 minutes; `/models refresh` re-fetches while Kilo is active). Nothing is hardcoded — the catalog is authoritative, and free-model availability can change as Kilo updates it
+- The model catalog is discovered live via `GET https://api.kilo.ai/api/gateway/models` (cached for 5 minutes; `/model refresh` re-fetches while Kilo is active). Nothing is hardcoded — the catalog is authoritative, and free-model availability can change as Kilo updates it
 - Anonymous access covers eligible free models (ids ending in `:free`, including the `kilo-auto/free` dynamic routing model, which Kilo resolves server-side). Without a key ATOM prefers `kilo-auto/free` when exposed, else the first free model, else the first live id
 - Configure a key with `/provider` (validated, stored in `~/.atom/auth.json`) or `KILO_API_KEY` to unlock the full catalog; authenticated requests send `Authorization: Bearer <key>`, anonymous requests send no auth header at all
 - Free models show a `(free)` badge in `/model` and match the `free` filter
@@ -59,8 +59,7 @@ File lives at `~/.atom/auth.json` (`ATOM_HOME` overrides the home dir). `0600` o
 ## Switching
 
 - `/provider`: pick provider, paste key once (validated, stored), chat. Kilo's key is optional — without one the prompt offers anonymous free-model use. Switching provider keeps session history text. System prompt stays
-- `/model`: unified picker — active provider's live models first (fallback on any failure), then every other keyed provider's models plus the always-visible keyless Kilo and local lists (cached live list when warm, else fallback). `openai-compatible` joins only with both a key and a stored baseURL. Type to filter (`free` matches free Kilo models), list windows to 10 rows, picking another provider's model switches provider too
-- `/models refresh`: re-probes local servers; while Kilo is active it refreshes the Kilo gateway catalog instead
+- `/model`: unified picker — active provider's live models first (fallback on any failure), then every other keyed provider's models plus the always-visible keyless Kilo and local lists (cached live list when warm, else fallback). `openai-compatible` joins only with both a key and a stored baseURL. Type to filter (`free` matches free Kilo models), list windows to 10 rows, picking another provider's model switches provider too. `/model <text>` opens pre-filtered; `/model refresh` re-probes local servers (Kilo gateway catalog while Kilo is active)
 - `/effort`: reasoning-effort picker (`Auto`/`Low`/`Medium`/`High`/`Max`). Sent for every model on every provider: `reasoning_effort` on OpenAI-chat kinds (zen, OpenAI, DeepSeek, Mistral, Kilo, openai-compatible, locals), a `thinking` budget on Anthropic, a `thinkingConfig.thinkingLevel` on Gemini. `Auto` omits the knob. A model that truly lacks the knob fails the POST with a 400 naming it — the turn warns and retries once without it, so `(unsupported)` only ever reflects an actual server rejection
 
 Custom server: pick `openai-compatible`, paste the baseURL (validated as http/https, trailing slashes trimmed) and key. Endpoint helper appends `/chat/completions` when missing.

package/documentation/skills.md

@@ -34,7 +34,7 @@ Support files: `references/<...>` and `scripts/<...>` mentions inside the body a
 
 ## Listing and precedence
 
-`/skills` opens the searchable picker (names only, type to filter, arrows to browse, `Enter` stages for confirm). `skillsListText` (headless use) prints `Skills (N):` with one runnable `/skill:name` plus source per line — no descriptions in either surface. Model-only skills show `[auto-only]` instead of hiding. Notes and warnings ride along visibly. Empty with no warnings prints the install hint (`add SKILL.md skills under .claude/skills/, .agents/skills/, or the ~/. counterparts`).
+`/skill` opens the searchable picker (names only, type to filter, arrows to browse, `Enter` stages for confirm). `skillsListText` (headless use) prints `Skills (N):` with one runnable `/skill:name` plus source per line — no descriptions in either surface. Model-only skills show `[auto-only]` instead of hiding. Notes and warnings ride along visibly. Empty with no warnings prints the install hint (`add SKILL.md skills under .claude/skills/, .agents/skills/, or the ~/. counterparts`).
 
 Name clashes: global (personal) wins over project on exact-name matches, with a visible note. Same-level duplicates keep the first with a note. Pure function `resolveSkills`, covered by `tests/skills.test.ts`.
 
@@ -42,7 +42,7 @@ Name clashes: global (personal) wins over project on exact-name matches, with a
 
 Three tiers: (1) name plus description of every skill is known to the matcher at all times; (2) the `SKILL.md` body loads only on activation; (3) `references/` and `scripts/` files load on demand (inlined for explicit manual loads; the model reads them via `read` for auto loads). The transcript always shows one plain line per load (`deploy loaded`), never the body.
 
-- Manual: `/skill:name` (canonical; legacy `/skill-name` still works) loads the full body plus inlined references into context for that turn. Discovery without dispatch: the `/skills` picker (type to filter, arrows to browse, `Enter` stages `/skill:name` into the input — nothing is sent) and the `/` slash menu (skill rows complete on first `Enter`, run on the second) both confirm before loading; a fully typed `/skill:name` or `/skill-name` runs on first `Enter`. `allowed-tools` in frontmatter become turn-scoped auto-approvals. User-invocable `false` entries reject manual invocation
+- Manual: `/skill:name` or `/skill <name>` (canonical; legacy `/skill-name` still works) loads the full body plus inlined references into context for that turn. Discovery without dispatch: the `/skill` picker (type to filter, arrows to browse, `Enter` stages `/skill:name` into the input — nothing is sent) and the `/` slash menu (skill rows complete on first `Enter`, run on the second) both confirm before loading; a fully typed `/skill:name`, `/skill <name>`, or `/skill-name` runs on first `Enter`. `allowed-tools` in frontmatter become turn-scoped auto-approvals. User-invocable `false` entries reject manual invocation
 - Auto: deterministic whole-word description match with a high bar — distinct `name` plus `description` words (length 3 or more, stopwords dropped) appearing as whole message words, at least 3 hits, best score first, at most 1 skill per turn. Auto loads Tier 2 only (body without inlined references, truncated at 12KB with a read pointer). `disable-model-invocation` skills never match. See `matchSkills` in `src/skills.ts`
 - Deny rules still win over skill grants. See [Permissions](permissions.md)
 
@@ -54,4 +54,4 @@ Grant trust (`skillGrantsFor` in `src/policy.ts`, covered by `tests/policy.test.
 2. Keep the body self-contained; reference large helpers via `references/...` so they inline only when needed
 3. Declare least-privilege `allowed-tools`
 4. Set `user-invocable: false` for auto-only helpers, `disable-model-invocation: true` for manual-only helpers
-5. Verify with `/skills` listing plus `tests/skills*.test.ts` patterns
+5. Verify with `/skill` listing plus `tests/skills*.test.ts` patterns

package/documentation/tools.md

@@ -12,11 +12,11 @@ Extensions can register brand-new model-callable tools via `api.registerTool({ n
 
 | Tool | What it does | Permission in normal mode |
 |---|---|---|
-| `read` | Read files, list directories. Args: `path`, optional 1-based `offset`/`limit` | auto |
+| `read` | Read files (UTF-8 text, or PNG/JPEG/GIF/WebP as vision input), list directories. Args: `path`, optional 1-based `offset`/`limit` (text only) | auto |
 | `write` | Create or overwrite files (creates parent dirs). Silent pre-mutation snapshot for rewind | asks |
 | `edit` | Exact-match patch. Fails on no match, on multiple matches without `replaceAll`, on stale read | asks |
-| `grep` | Line-regex search under `dir`. `include` glob, `outputMode`: `content`, `files_with_matches`, `count` | auto |
-| `glob` | List paths matching pattern under `dir`, newest-first | auto |
+| `grep` | Line-regex search under `dir` (a directory, or a single file to search just it). Case-sensitive; `(?i)` prefix = case-insensitive. `include` glob with `{a,b}` (e.g. `*.{ts,tsx}`), `outputMode`: `content`, `files_with_matches`, `count` | auto |
+| `glob` | List paths matching pattern (`*`, `?`, `**`, `{a,b}`) under `dir` (a directory, or a single file to test just it), newest-first | auto |
 | `bash` | Shell command. JSON result with `exitCode`, `stdout`, `stderr`. Optional `runInBackground` | asks |
 | `bash_output` | Poll a background shell task by `taskId` | auto |
 | `webfetch` | Fetch a page as `markdown`, `text`, or `html`. http upgrades to https. Gated by the network SSRF policy (see below) | auto |
@@ -33,6 +33,7 @@ Read-only set: `read`, `grep`, `glob`, `webfetch`, `websearch`, `bash_output`, `
 | Path | Cap | Behavior |
 |---|---|---|
 | `read` output | ~64KB | Head plus truncation note. Full text spills to `<tmpdir>/atom-overflow/` with a `read` pointer |
+| `read` image | 8 MiB per image | PNG/JPEG/GIF/WebP attach as vision input (see below); larger images refused with downscale guidance |
 | `bash` stdout/stderr | ~8KB each | Each stream capped independently, JSON flags `stdoutTruncated`/`stderrTruncated`, overflow pointer on spill |
 | `bash_output` streams | ~8KB each | Same spill behavior for background stdout/stderr |
 | `webfetch` download | ~1MB | Noted as `[truncated: download exceeded ~1MB]` |
@@ -53,6 +54,10 @@ Count-cap notes (`grep`/`glob` over-cap) and prompt-assembly caps (skills, compa
 
 No path sandbox. Relative paths resolve against cwd. Absolute paths and `..` escapes are allowed anywhere on the machine, including sensitive locations like `~/.ssh/`. Treat those contents as untrusted. Never exfiltrate or commit secrets. The permission mode is the control plane. See [Permissions](permissions.md).
 
+## Image input (vision)
+
+`read` on a PNG, JPEG, GIF, or WebP file (detected by magic bytes, up to 8 MiB) attaches it as vision input: the result reads `Image read successfully: <path> (<mime>, <bytes> bytes, attached as vision input)` plus a `[media:<id> ...]` token. History, transcript, and `session.json` carry only that short token (images live under `~/.atom/media/`, pruned after 7 days); at POST time the token expands to provider-native image blocks (OpenAI `image_url`, Anthropic base64 `image` blocks, Gemini `inline_data`). Context accounting charges the deterministic base64 wire cost per token, so the load stays honest. Compaction summaries and the goal judge always strip images to `[image omitted: ...]` markers (text-only, cheap). A model that rejects image input (400 naming images) retries once automatically with images stripped. Anything else binary — PDF, AVIF, BMP, audio, video — is refused with convert-first guidance (e.g. `pdftoppm`/`pdftotext`); oversize images are refused with downscale guidance. Covered by `tests/media.test.ts`.
+
 ## Network policy (`webfetch` SSRF gate)
 
 Every URL — the initial one and every redirect hop — classifies into a zone (`public`, `localhost`, `private` RFC1918/CGNAT/TEST-NET, `link-local` incl. cloud metadata `169.254.169.254`, `blocked` for unparseable/unresolvable) and is checked against the `network` policy from `atom.json` (defaults: public + localhost allowed). Redirects are followed manually (cap 5, loop-detected, credentialed/scheme-changing targets refused) so a public URL can never bounce to metadata or the LAN unseen; each hop re-resolves DNS and the worst zone wins for multi-address hosts. IP-literal tricks (octal/hex forms, IPv4-mapped IPv6) classify by their real address. Known limitation: DNS rebind between check and fetch (TOCTOU) would need connection-level IP pinning, which global fetch does not offer. See [Configuration](configuration.md). Covered by `tests/policy.test.ts`.

package/documentation/troubleshooting.md

@@ -15,7 +15,7 @@ Never print full keys, never commit them, never put them in fixtures.
 
 ## Model list fails
 
-`/model` falls back to the offline list when the live `/models` call fails (Kilo falls back to the `kilo-auto/free` routing placeholder). That is expected offline. Check endpoint override (`OPENCODE_ZEN_ENDPOINT`), network, and key validity before assuming a bug. While Kilo is active, `/models refresh` re-fetches the gateway catalog.
+`/model` falls back to the offline list when the live `/models` call fails (Kilo falls back to the `kilo-auto/free` routing placeholder). That is expected offline. Check endpoint override (`OPENCODE_ZEN_ENDPOINT`), network, and key validity before assuming a bug. While Kilo is active, `/model refresh` re-fetches the gateway catalog.
 
 Effort (`/effort`: `Auto`/`Low`/`Medium`/`High`/`Max`) is sent for every model on every provider. If a turn warns that an effort level "is not supported by" a model, the server rejected the knob with a 400 and the turn continued without it — the setting is kept, so switching back to a supporting model re-applies it.
 

package/examples/extensions/01-audit-gate.js

@@ -4,8 +4,8 @@
 // as the normal model-visible result (approval is skipped, the turn
 // continues); anything this hook does not block runs untouched.
 //
-// Gallery sample for documentation/extensions.md — that guide references
-// this file by name and never duplicates it. Covered by
+// Gallery sample for documentation/extensions.md — that guide excerpts
+// this file and references it by name. Covered by
 // tests/extension-gallery.test.ts, which loads this exact file through the
 // real loadExtensions path.
 module.exports = function auditGate(api) {

package/examples/extensions/02-notes-tool.js

@@ -5,8 +5,8 @@
 // `Error: invalid call: ...` result and the implementation never runs), and
 // dispatches through the shared loop.
 //
-// Gallery sample for documentation/extensions.md — that guide references
-// this file by name and never duplicates it. Covered by
+// Gallery sample for documentation/extensions.md — that guide excerpts
+// this file and references it by name. Covered by
 // tests/extension-gallery.test.ts, which loads this exact file through the
 // real loadExtensions path.
 const notes = [];

package/examples/extensions/03-custom-command.js

@@ -6,8 +6,8 @@
 // transcript) so the dialog flow is testable headless — tests drive the
 // command with a stub askUser and unit-test the helper directly.
 //
-// Gallery sample for documentation/extensions.md — that guide references
-// this file by name and never duplicates it. Covered by
+// Gallery sample for documentation/extensions.md — that guide excerpts
+// this file and references it by name. Covered by
 // tests/extension-gallery.test.ts, which loads this exact file through the
 // real loadExtensions path.
 function summarizeChoice(choice, extra) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atom-agent",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Agentic terminal coding assistant: multi-provider LLM loop with local file/shell/web tools in an Ink (React) TUI.",
   "type": "module",
   "license": "MIT",
@@ -38,8 +38,9 @@
   "scripts": {
     "start": "tsx src/cli.tsx",
     "test": "vitest run",
+    "bench": "node scripts/bench-render.mjs",
     "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-web-ui.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {