atom-agent 0.3.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 1.1.0 — 2026-09-10
+
+- Agentic loop hardening (`src/agent/loop.ts`, `types.ts`, `loop-guard.ts`,
+  `normalize.ts`; `src/zen.ts`, `adapters.ts`): tool-result and
+  model-response normalization, per-tool execution timeouts, total tool-call
+  budget per turn, error-streak recovery (holds final text for a fix-forward
+  attempt instead of ending on unaddressed failures), opt-in repetition guard
+  with background-poll exclusions, and a per-turn `LoopStats` rollup
+  (iterations, calls, failures, cache hits, guard hits, bottleneck, context
+  growth) reported via `AgenticOpts.onLoopStats`, even on failed turns.
+  SSE stall guard (`ATOM_STALL_TIMEOUT_MS`, default 60s) in every streaming
+  reader: a silent 200-OK stream fails fast on the permanent Truncated
+  contract instead of hanging the turn
+- LoopStats into observability (`src/telemetry.ts`,
+  `telemetry-dashboard.ts`, `src/App.tsx`): `recordLoopStats` attaches the
+  harness rollup to the open turn trace, aggregates total cache/guard hits,
+  dashboard renders per-turn loop fragments plus overview cards
+- Search speed (`src/tools/search.ts`, `dir-cache.ts`, `read-cache.ts`,
+  `filesystem.ts`, `shell.ts`): `git ls-files` enumeration (tracked plus
+  untracked-non-ignored, `node_modules`/`.git` still excluded), single-pass
+  grep (half the file reads), 32-wide bounded-parallel scan with identical
+  output order, mtime-checked listing cache with exact invalidation on
+  write/edit/bash (`ATOM_FAST_LIST=0` forces the legacy walker), and a
+  stat-validated read cache. Measured 3–7x on content search; batching nudge
+  added to the system prompt
+- TUI flow (`src/App.tsx`, `ui/transcript.tsx`, `live-tail.tsx`,
+  `status-bar.tsx`, `todo-panel.tsx`, `modals.tsx`, `palette.tsx`):
+  `/autoscroll on|off` (freezes a following view mid-turn instead of yanking
+  it), `/thinking` toggle with per-round model reasoning persisted to the
+  transcript (rendering-only; never model history), memoized status bar,
+  todo panel, approval/question modals, and palette plus memoized
+  palette/checkpoint derivations (timer-tick and picker-nav flicker fix)
+
+## 1.0.0 — 2026-09-09
+
+- Kilo Gateway is the default provider (`src/kilo.ts` + registry entry in
+  `src/providers.ts`): OpenAI-compatible `POST /chat/completions` on the
+  shared streaming/tool-call path, live `GET /models` catalog (5-minute
+  TTL, `/models refresh` while Kilo is active), `:free` detection with
+  `(free)` picker badges, anonymous free-model use (no auth header sent),
+  optional `KILO_API_KEY` via `/provider`, short actionable errors
+  (`Kilo: anonymous free-model rate limit reached.`, `Kilo: API key is
+  invalid.`, `Kilo: model is unavailable.`, `Kilo: gateway temporarily
+  unavailable.`). Fresh installs start on `kilo-auto/free` with no key;
+  saved Kilo sessions restore keyless. All other providers unchanged
+  (existing zen-path suites pinned via `initialProvider="opencode-zen"`)
+- Observability: local per-turn telemetry (iterations, model calls with
+  API-reported tokens only, per-tool durations and ok/fail, retries,
+  outcomes) under `~/.atom/telemetry/` plus a self-contained drill-down
+  dashboard (`/dashboard`, `atom --dashboard`) and `/telemetry` summary.
+  Local-only, truncated + secret-scrubbed, off via `ATOM_TELEMETRY=0` or
+  `telemetry.enabled=false`. Unavailable values render as n/a (never
+  estimated); cost stays n/a until a provider reports it
+- Observability webUI: `atom --serve [--port <n>]` serves the live dashboard
+  (auto-refreshing) plus a read-only JSON API (`/api/health`,
+  `/api/aggregates`, `/api/sessions`) on loopback only. No new dependencies;
+  the static `--dashboard` file output is unchanged
+- Security hardening: explicit Policy layer (`src/policy.ts` — approval
+  order, skill-grant trust, network zones, secret scrubbing); project-local
+  skills never silently arm shell/filesystem grants; webfetch SSRF gate
+  (configurable `atom.json` network zones, per-hop redirect checks);
+  shell-output secret redaction; symlink targets in activity lines
+- Rollback semantics: explicit conversation (automatic) vs filesystem
+  (explicit `/rewind` only) vs process (never) contract (`src/rollback.ts`);
+  cancel line states no-revert truth; checkpoints drop on history lineage
+  resets; hash pre-verified restores; stale snapshot-temp pruning
+- Scheduler: effect metadata per tool (`src/scheduler.ts`) driving parallel
+  read batches; writes/spawns stay serial, order/cancel/approval preserved
+- Prompt cleanup: tool descriptions trimmed of runtime-guaranteed prose
+  (~17% smaller system prompt); harness contract in one system line
+- Code organization: `agent/` (loop, gates, types), `tools/` (9 modules),
+  `ui/` (transcript, input, todo-panel) extracted with compat re-exports;
+  boundary rules enforced by `tests/architecture.test.ts`
+- TUI scrolling: PgUp/Home hold the view mid-turn (frozen window plus a
+  static live-tail line, so streaming stops yanking the terminal);
+  End/PgDn re-follows; `/clear`, `/resume`, `/new`, rewind-truncate reset
+- Modes: `/plan` and `/yolo` retired — Tab is the only switcher
+  (normal → yolo → plan → normal); busy status line keeps the mode segment
+- Input cursor renders in inverse video (no letter shifting); pending
+  todos use ○ (never ❌); observability dashboard redesigned (hero, sticky
+  section nav, refined dark system, responsive)
+
 ## 0.3.0 — 2026-09-08
 
 - Agentic loop: 30-step budget (`ATOM_MAX_TOOL_STEPS`), todo-completion

package/README.md

@@ -15,8 +15,8 @@
 Atom is a small, fast, **agentic** terminal chatbot: it doesn't just answer —
 it runs an **observe → act → inspect → adjust** loop with **13 real,
 locally-executed tools** (files, shell, web), streaming output, and an
-interactive Ink TUI. Powered by [OpenCode Zen](https://opencode.ai/docs/zen)
-as the model provider. Zero ceremony: one key, one command, you're chatting
+interactive Ink TUI. Powered by [Kilo Gateway](https://kilo.ai)
+as the default model provider. Zero ceremony: no key, one command, you're chatting
 with an agent that can read your code, edit it, run it, and search the web.
 
 ## Documentation
@@ -26,10 +26,11 @@ Full docs live in [`documentation/`](documentation/index.md), same layout as ope
 - [Getting Started](documentation/getting-started.md) — install, key setup, first run
 - [CLI and TUI](documentation/cli.md) — slash commands, keyboard, status line
 - [Tools](documentation/tools.md) — the 13 local executors, caps, background tasks
-- [Providers and Models](documentation/providers.md) — 7 providers, endpoints, key resolution
-- [Permissions and Modes](documentation/permissions.md) — normal/yolo, trust, allow/deny rules
+- [Providers and Models](documentation/providers.md) — 8 remote providers + 3 local runtimes, endpoints, key resolution (Kilo default, key-optional)
+- [Permissions and Modes](documentation/permissions.md) — normal/yolo/plan, trust, allow/deny rules
 - [Skills](documentation/skills.md) — discovery, frontmatter contract, auto-invoke
 - [Sessions](documentation/sessions.md) — persistence, resume, clear, rewind
+- [Observability](documentation/observability.md) — local telemetry, `/telemetry`, dashboard drill-down
 - [Compaction and Token Display](documentation/compaction.md) — auto-compact, manual compact, footer format
 - [Configuration](documentation/configuration.md) — env vars, auth file, AGENTS.md layering
 - [Development](documentation/development.md) — scripts, structure, tests, build
@@ -51,14 +52,39 @@ Or run from source:
 npm install
 ```
 
-Get a key at [opencode.ai/auth](https://opencode.ai/auth), then:
+No key needed — Kilo Gateway is the default provider and its free models
+work anonymously:
 
 ```powershell
-$env:OPENCODE_ZEN_API_KEY="sk-your-key"
 npm start
 ```
 
-That's it. Type `/` to see every command. Full command reference: [CLI and TUI](documentation/cli.md).
+That's it. ATOM discovers Kilo's live model catalog and starts on the free
+routing model (`kilo-auto/free`); open `/model` to pick another. A
+`KILO_API_KEY` (or any other provider key at
+[opencode.ai/auth](https://opencode.ai/auth) for Zen, etc.) is optional —
+paste one via `/provider` to unlock more. Type `/` to see every command.
+Full command reference: [CLI and TUI](documentation/cli.md).
+
+## Updating
+
+Check your installed version, then update to the latest release:
+
+```bash
+npm ls -g atom-agent   # installed version
+npm i -g atom-agent@latest
+```
+
+If the old version sticks around, clear the cache and reinstall:
+
+```bash
+npm cache clean --force
+npm i -g atom-agent@latest
+```
+
+Run-from-source users just `git pull` instead. Maintainers: bump `version`
+in `package.json`, add a `CHANGELOG.md` entry, commit, tag `vX.Y.Z`, push —
+`prepublishOnly` rebuilds `dist/` at `npm publish` time, so never commit it.
 
 ## What Atom can do
 
@@ -72,20 +98,23 @@ That's it. Type `/` to see every command. Full command reference: [CLI and TUI](
   `bash_output`, `websearch`, `webfetch`, `ask_question` (asks *you* things
   interactively), `todowrite` / `todo_get` / `todo_update` (session task
   checklist with a live TUI panel)
-- 🛡️ **Normal / YOLO modes** — `Tab` toggles. Normal auto-runs reads but
+- 🛡️ **Normal / YOLO modes** — `Tab` cycles normal → yolo → plan → normal. Normal auto-runs reads but
   asks before writes/shell (`y` once · `a` always · `t` trust all · `n` deny);
   `/trust` toggles a session trust tier (one approval covers the whole task,
   status shows `+trust`, never saved). YOLO never asks
-- 🗺️ **Plan mode** — `/plan` enters a read-only mode for risky work:
+- 🗺️ **Plan mode** — `Tab` from yolo enters a read-only mode for risky work:
   exploration (`read`/`grep`/`glob`/web/todos/`ask_question`) runs free while
   `write`/`edit`/`bash` are blocked pre-execution with a replan note (never a
-  prompt). `Tab` never enters/exits plan, `/yolo`·`/trust` can't punch through
-  it, `/deny` still wins. Exiting `/plan` approves the recorded todo checklist
+  prompt). `/yolo`·`/trust` can't punch through
+  it, `/deny` still wins. `Tab` out of plan approves the recorded todo checklist
   into implementation (lands in normal, never yolo)
-- ⌨️ **Slash commands** — `/model` (interactive model picker), `/provider`
-  (provider + key picker, keys in `~/.atom/auth.json`), `/effort`
-   (reasoning-effort picker), `/tools`, `/help`, `/mode`, `/yolo`, `/trust`, `/plan`, `/clear`,
-  `/exit` — plus `/`-autocomplete as you type
+- ⌨️ **Slash commands** — `/model` (unified picker across keyed providers,
+  type to filter), `/provider` (provider + key picker, keys in
+  `~/.atom/auth.json`), `/effort` (reasoning-effort picker), `/tools`,
+  `/skills`, `/skill:name` (invoke a skill; skills complete in `/`), `/context`
+  (context usage by source), `/queue` + `/steer <text>` (follow-ups while
+  busy: queue until the turn ends, or inject into the running turn), `/help`, `/mode`, `/trust`,
+  `/clear`, `/exit` — plus `/`-autocomplete as you type (`/yolo` and `/plan` are retired as typed commands — `Tab` switches modes)
 - 📊 **Status line** — provider · model · session token usage (`token:
   (P%) NK`: NK is the cumulative spend in K, P% is the current context load
   over the model's verified window — last `prompt_tokens`, else the
@@ -98,6 +127,13 @@ That's it. Type `/` to see every command. Full command reference: [CLI and TUI](
   (structured summary, tools disabled, newest tail kept, thrash guard).
 - 📖 **AGENTS.md-aware** — Atom loads your project's `AGENTS.md` into its
   system prompt, so it knows your tools, rules, and permission model
+- 📊 **Local observability** — every turn is traced (iterations, model calls
+  with reported-only tokens, per-tool durations and ok/fail, retries,
+  outcomes) into `~/.atom/telemetry/`; `/telemetry` summarizes, `/dashboard`
+  (or `atom --dashboard`) writes a self-contained drill-down page, and
+  `atom --serve` offers the same view live in the browser plus a read-only
+  JSON API. Local-only, secret-scrubbed, off via `ATOM_TELEMETRY=0`. See
+  [Observability](documentation/observability.md)
 - 🔓 **No path sandbox** — file tools read/write anywhere on the computer
   (absolute paths and `..` escapes allowed, including sensitive locations
   like `~/.ssh/` — treat contents as untrusted, never exfiltrate or commit
@@ -138,25 +174,37 @@ auto-approved call).
 
 Full reference: [Providers and Models](documentation/providers.md) plus [Configuration](documentation/configuration.md).
 
-Atom talks to 7 providers behind one UI (opencode `/connect` mirror,
-manual-key only — no OAuth). Pick with `/provider`, paste a key once
-(validated, stored in `~/.atom/auth.json`, `0600` on POSIX), chat.
-Switching provider keeps session history text; system prompt stays.
-`/model` lists the active provider's live models (curated fallback on any
-failure). `/effort` sends `reasoning_effort` only for opencode-zen
-supported models; elsewhere kept but never sent.
+Atom talks to 8 remote providers plus 3 local runtimes (Ollama, LM Studio, llama.cpp) behind one UI (opencode `/connect` mirror,
+manual-key only — no OAuth). Kilo Gateway is the default: its free models
+(`:free` ids, incl. the `kilo-auto/free` routing model) chat with no key;
+paste a key once with `/provider` (validated, stored in
+`~/.atom/auth.json`, `0600` on POSIX) to unlock the full catalog or another
+provider, chat. Switching provider keeps session history text; system prompt
+stays. `/model` is a unified picker: the active provider's live models first
+(fallback on any failure), then every other keyed provider's models plus the
+always-visible keyless Kilo list (free models carry a `(free)` badge) —
+picking one switches provider too. `/effort` sends `reasoning_effort` only
+for opencode-zen supported models; elsewhere kept but never sent. Your
+`/model` + `/provider` + `/effort` picks persist across restarts (fresh
+conversation each launch; `/resume` restores it). Project defaults live in
+`atom.json` — see [Configuration](documentation/configuration.md).
 
 ### Model-choice policy
 
-The zen default is `deepseek-v4-pro` — picked from the live `/models` list
-for reliable multi-step tool use (tool calls + reasoning effort supported).
-Free models (`big-pickle`, `mimo-v2.5-free`, …) stay selectable via `/model`
-for quick single-turn questions. Override any time with `/model` or
+The Kilo default is `kilo-auto/free` — the gateway's dynamic free routing
+model, preferred while no Kilo key is configured (no paid credentials for
+first run). The catalog is discovered live, so free-model availability can
+change; override any time with `/model`. The zen default is
+`deepseek-v4-pro` — picked from the live `/models` list for reliable
+multi-step tool use (tool calls + reasoning effort supported). Free models
+(`big-pickle`, `mimo-v2.5-free`, …) stay selectable via `/model` for quick
+single-turn questions. Override any time with `/model` or
 `OPENCODE_ZEN_MODEL`.
 
 | Provider | Key env (wins over stored) | Endpoint | Notes |
 |---|---|---|---|
-| opencode-zen | `OPENCODE_ZEN_API_KEY` | `https://opencode.ai/zen/v1/chat/completions` | OpenAI-compatible chat/completions default; key at https://opencode.ai/auth |
+| kilo | `KILO_API_KEY` (optional — free models work anonymously) | `https://api.kilo.ai/api/gateway/chat/completions` | Kilo Gateway default, OpenAI-compatible; live `/models` catalog is authoritative |
+| opencode-zen | `OPENCODE_ZEN_API_KEY` | `https://opencode.ai/zen/v1/chat/completions` | OpenAI-compatible chat/completions; key at https://opencode.ai/auth |
 | openai | `OPENAI_API_KEY` | `https://api.openai.com/v1/chat/completions` | OpenAI-compatible; key at https://platform.openai.com/api-keys |
 | anthropic | `ANTHROPIC_API_KEY` | `https://api.anthropic.com/v1/messages` | Messages API (`x-api-key` + `anthropic-version: 2023-06-01`, `max_tokens` 4096); key at https://console.anthropic.com/settings/keys |
 | deepseek | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/chat/completions` | OpenAI-compatible (no `/v1` prefix); key at https://platform.deepseek.com/api_keys |
@@ -177,7 +225,7 @@ npm run typecheck
 npm run build    # emit dist/ (the `atom` binary entry is dist/cli.js)
 ```
 
-Env knobs: `OPENCODE_ZEN_API_KEY` (or stored zen key via `/provider`), `OPENCODE_ZEN_MODEL`,
+Env knobs: `KILO_API_KEY` (optional; or stored Kilo key via `/provider`), `OPENCODE_ZEN_API_KEY` (or stored zen key via `/provider`), `OPENCODE_ZEN_MODEL`,
 `OPENCODE_ZEN_ENDPOINT`, `OPENCODE_AGENTS_PATH`, `ATOM_COMPACT_PCT` (auto-compact percent, 50–95),
 `ATOM_MAX_TOOL_STEPS` (tool rounds per turn, default 30, clamped 5–100),
 plus per-provider key env vars above.
@@ -186,15 +234,18 @@ plus per-provider key env vars above.
 ```
 .
 ├── src/
-│   ├── cli.tsx    # entry: --help, always starts TUI (missing key guides to /provider)
-│   ├── App.tsx    # Ink TUI: transcript, pickers, modes (/plan /trust), approvals, status line
-│   ├── zen.ts     # agentic loop (budgets, todo/verification guards) + provider dispatch + SSE
+│   ├── cli.tsx    # entry: --help/--dashboard/--serve, always starts TUI (missing key guides to /provider)
+│   ├── App.tsx    # Ink TUI: transcript, pickers, Tab modes, /trust, approvals, status line
+│   ├── telemetry.ts # local observability recorder + store (never throws, off via ATOM_TELEMETRY=0)
+│   ├── telemetry-dashboard.ts # self-contained local dashboard page (session → turn → iteration → call)
+│   ├── zen.ts     # provider dispatch + agentic-loop wrappers (shared core in src/agent/loop.ts) + SSE
 │   ├── tools.ts   # 13 local tool executors + function schemas (read/write/edit/grep/glob/bash/…)
 │   ├── permissions.ts # allow/deny rule matcher backing /allow /deny /rules
 │   ├── snapshots.ts   # pre-mutation file snapshots backing /rewind
 │   ├── skills.ts  # skill discovery backing /skills
 │   ├── env-block.ts   # per-turn cwd/git/node environment block
-│   ├── providers.ts # 7-provider registry (kind/endpoint/env/default + fallback models)
+│   ├── providers.ts # 8 remote providers + 3 local runtimes (kind/endpoint/env/default + fallback models; Kilo default)
+│   ├── kilo.ts      # Kilo Gateway: catalog parsing, free detection, TTL cache, error normalization
 │   ├── auth.ts    # ~/.atom/auth.json store (env wins, 0600 POSIX)
 │   ├── adapters.ts # anthropic/gemini translation + SSE + models-list parsing + key validation
 │   ├── compact.ts # context compaction: load/trigger math, split, summary POST (tools off)