atom-lite 0.5.1 → 0.6.3

package/CHANGELOG.md

@@ -5,9 +5,41 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.3] - 2026-11-06
 
 ### Added
+- Interactive approval prompts (y/n/t) for read/write/edit/bash operations outside the workspace, in both plan and yolo modes.
+
+### Changed
+- Default mode is now yolo; legacy `ask`/`trusted` approvalMode values migrate to yolo.
+- Outside-workspace operations prompt regardless of mode; hard-blocked in non-interactive sessions.
+
+## [0.6.2] - 2026-11-05
+
+### Fixed
+- Direct publish (bypass staged registry conflict).
+
+## [0.6.1] - 2026-11-05
+
+### Fixed
+- Shell mode result rendering and @ mention fuzzy search (fd path).
+- npm publish (staged 0.6.0 could not be approved locally).
+
+## [0.6.0] - 2026-11-05
+
+### Added
+- Autonomy primitives: removed hard caps, added optional token budgets, plan/yolo modes with Tab toggle, higher scheduler parallelism, improved compaction fidelity.
+- Interactive `@` file/folder mentions (including hidden files via `fd`) and `!` shell mode.
+- Built-in skills: `atom-lite-extensions`, `code-review`, `caveman`, `optimization`.
+- Richer default system prompt.
+
+### Changed
+- Replaced ask/trusted/deny approval modes with plan/yolo modes.
+- Configuration: `approvalMode` -> `mode`; added `maxTokensPerSession`/`maxTokensPerTurn`.
+
+### Fixed
+- Shell command results now render (resolve on process exit).
+- Hidden files included in `glob`/`grep` tools.
 
 ## [0.5.0] - 2026-11-05
 

package/README.md

@@ -1,59 +1,43 @@
 # Atom-lite
 
+<p align="center">
+  <img src="./assets/atom-lite.png" alt="Atom-lite" width="900" />
+</p>
+
 [![npm](https://img.shields.io/npm/v/atom-lite?logo=npm)](https://www.npmjs.com/package/atom-lite)
 [![CI](https://github.com/beast-ofcourse/atom-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/beast-ofcourse/atom-lite/actions/workflows/ci.yml)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22.19-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-**Atom-lite** is a local-first, model-agnostic coding agent with an intentionally small harness: one agent loop, four core built-in tools (`read`, `write`, `edit`, `bash`) plus network tools (`webfetch`, `websearch`), a deterministic conflict-aware scheduler, durable JSONL sessions, and explicit safety boundaries. It runs against local or hosted model providers through interchangeable adapters — no cloud account, telemetry service, or hosted control plane required.
-
-> See [`docs/README.md`](./docs/README.md) for the documentation index and [`docs/adr/`](./docs/adr/) for architectural decisions.
-
----
-
-## Table of contents
+Atom-lite is a local-first, model-agnostic coding agent built on a deliberately small harness: one agent loop, nine built-in tools, a conflict-aware scheduler, durable JSONL sessions, and explicit safety boundaries. It runs against local or hosted providers through interchangeable adapters — no cloud account, telemetry, or control plane required.
 
-- [Why Atom-lite](#why-atom-lite)
-- [Features](#features)
-- [Install](#install)
-- [Quick start](#quick-start)
-- [Default provider](#default-provider)
-- [Configuration](#configuration)
-- [Usage](#usage)
-- [Tools](#tools)
-- [Providers](#providers)
-- [Safety & security](#safety--security)
-- [Sessions](#sessions)
-- [Context management](#context-management)
-- [Development](#development)
-- [Architecture](#architecture)
-- [Contributing](#contributing)
-- [License](#license)
+> Documentation index: [`docs/README.md`](./docs/README.md). Architectural decisions: [`docs/adr/`](./docs/adr/).
 
 ## Why Atom-lite
 
-Most coding agents accumulate tools, sub-agents, planning frameworks, retrieval pipelines, and orchestration layers until the harness itself becomes the product. Atom-lite takes the opposite stance:
+Most coding agents accumulate tools, sub-agents, and orchestration until the harness becomes the product. Atom-lite takes the opposite stance:
 
-- **Small core, strong primitives.** The core contains only a provider interface, a session model, a single agent loop, four core tools plus two network tools, a scheduler/executor, context-window management, configuration, and a CLI.
-- **The model decides; the runtime enforces.** The model chooses which tool to call and what to do next. The runtime validates arguments, enforces workspace boundaries, applies approval rules, schedules calls safely, and returns accurate results. There is no hard-coded "plan → inspect → edit → test" workflow.
-- **Thin harness, not weak engineering.** Provider-specific formats, streaming failures, concurrent file access, shell timeouts, large outputs, context exhaustion, and session recovery are all handled — they are the reliability layer that makes a small harness useful.
+- **Small core, strong primitives.** Provider interface, session model, one agent loop, nine tools, scheduler/executor, context management, config, and CLI.
+- **The model decides; the runtime enforces.** The model chooses tools and next steps; the runtime validates arguments, enforces workspace boundaries, applies approval rules, schedules calls safely, and returns accurate results. No hard-coded workflow.
+- **Thin harness, not weak engineering.** Streaming failures, concurrent file access, shell timeouts, large outputs, context exhaustion, and session recovery are handled as the reliability layer.
 
 ## Features
 
-- **Six built-in tools** — four core tools (`read`, `write`, `edit`, `bash`) plus `webfetch` and `websearch`. Everything else (search, tests, git, builds) goes through `bash`.
-- **Single agent loop** — one agent, one conversation, one tool registry, one control loop. Parallelism lives inside a tool-call batch.
-- **Conflict-aware scheduler** — per-file read/write locks and a global bash barrier. Parallelism is governed by resource conflicts, not applied blindly.
-- **Durable sessions** — append-only JSONL event logs, resumable across CLI restarts, grouped by workspace.
-- **Context management** — token estimation, compaction (summarization of older history) before the context budget is exceeded, while retaining the full transcript.
-- **Live context meter** — the status line shows context tokens used against the selected model's real window (e.g. `tokens: 4.5k/256k`), resolved from provider metadata with known-model fallbacks.
-- **Approval modes** — `ask` / `trusted` / `deny` for shell commands, with session-level trust.
-- **Hash guards** — `expected_hash` rejects stale `write`/`edit` operations when the file changed since it was read.
-- **Provider-agnostic** — Ollama, Gemini, and any OpenAI-compatible endpoint (LM Studio, llama.cpp, Kilo AI Gateway, OpenAI, Anthropic, OpenRouter, Groq, Mistral, xAI, …).
-- **Interactive provider/model pickers** — `/provider` adds a provider and stores its key securely; `/model` fuzzy-searches every configured provider's models.
-- **Command palette and themes** — `ctrl+p` fuzzy-searches commands, skills, providers, models, themes, and recent sessions. `/theme` switches between auto, dark, light, and no-colour modes.
-- **Local-first** — runs fully against local providers with no cloud account, telemetry, or hosted database.
-- **Safe path handling** — file tools resolve against the workspace and reject escapes; shell is an explicit, sandbox-aware boundary.
+- **Nine built-in tools** — `read`, `write`, `edit`, `bash`, `grep`, `glob`, `webfetch`, `websearch`, `task`. Background tasks run via `bash` with `background:true` and are managed through `task`. Everything else (tests, git, builds) runs through `bash`.
+- **Single agent loop** — one agent, one conversation, one registry, one control loop. Parallelism lives inside a tool-call batch.
+- **Conflict-aware scheduler** — per-file read/write locks and a global bash barrier.
+- **Durable sessions** — append-only JSONL event logs, resumable across restarts, grouped by workspace.
+- **Context management** — token estimation and compaction before the budget is exceeded, full transcript retained.
+- **Live context meter** — `tokens: 4.5k/256k` against the model's real window, resolved from provider metadata with fallbacks.
+- **Autonomy modes** — `plan` (read/web only) and `yolo` (all tools), toggled with Tab; default `yolo`.
+- **Hash guards** — `expected_hash` rejects stale `write`/`edit` when a file changed since read.
+- **Provider-agnostic** — Ollama, Gemini, and any OpenAI-compatible endpoint (LM Studio, llama.cpp, Kilo, OpenAI, Anthropic, OpenRouter, Groq, Mistral, xAI, …).
+- **Interactive pickers** — `/provider` adds a provider and stores its key securely; `/model` fuzzy-searches every configured provider's models.
+- **Command palette & themes** — `ctrl+p` fuzzy-searches commands, skills, providers, models, themes, sessions. `/theme` switches auto/dark/light/no-colour.
+- **Local-first** — runs fully against local providers; no telemetry or hosted database.
+- **Safe path handling** — file tools resolve against the workspace and reject escapes; shell is an explicit boundary.
+- **Recovery** — automatic Git-gated checkpoints before mutating turns, with `/undo` and `/diff` for review. See [ADR 0014](./docs/adr/0014-checkpoints-and-undo.md).
 
 ## Install
 
@@ -67,7 +51,7 @@ Or run without installing:
 npx atom-lite "fix the failing test"
 ```
 
-Requires **Node.js >= 22.19** (see `engines` in `package.json`).
+Requires **Node.js >= 22.19**.
 
 ## Quick start
 
@@ -87,60 +71,21 @@ echo "summarize this repo" | atom-lite
 
 ## Default provider
 
-Out of the box, Atom-lite uses the **Kilo AI Gateway** (`https://api.kilo.ai/api/gateway`) with the free `kilo-auto/free` model. No API key is required (rate-limited to 200 requests/hour per IP for anonymous use). Override via `--provider`/`--model` or config.
+Out of the box, Atom-lite uses the **Kilo AI Gateway** (`https://api.kilo.ai/api/gateway`) with the free `kilo-auto/free` model. No API key required (rate-limited to 200 requests/hour per IP for anonymous use). Override via `--provider`/`--model` or config.
 
 ## Configuration
 
-User config: `~/.config/atom-lite/config.json`
-Project config: `.atom-lite/config.json` (non-secrets only)
+- User config: `~/.config/atom-lite/config.json`
+- Project config: `.atom-lite/config.json` (non-secrets only)
 
-Precedence (low → high): defaults → user config → project config (non-secret) → environment → CLI overrides. Security-critical user settings (e.g. `approvalMode`) are **not** overridable by project config.
+Precedence (low → high): defaults → user config → project config (non-secret) → environment → CLI overrides. Security-critical user settings (e.g. `approvalMode`) are not overridable by project config.
 
-Secrets are stored in `~/.config/atom-lite/credentials.json` with owner-only permissions (`0600`). Environment variables named by a provider's `apiKeyEnv` take precedence over the stored key. Secrets are never written to project config or session files.
-
-Environment overrides:
+Secrets live in `~/.config/atom-lite/credentials.json` (`0600`). Environment variables named by a provider's `apiKeyEnv` take precedence over the stored key. Secrets are never written to project config or session files.
 
 | Variable | Effect |
 | --- | --- |
 | `ATOM_LITE_PROVIDER` | Default provider profile name |
-| `ATOM_LITE_APPROVAL_MODE` | `ask` / `trusted` / `deny` |
-
-Example `config.json`:
-
-```json
-{
-  "defaultProvider": "kilo",
-  "providers": {
-    "kilo": {
-      "type": "openai-compatible",
-      "baseUrl": "https://api.kilo.ai/api/gateway",
-      "model": "kilo-auto/free",
-      "apiKeyEnv": null
-    },
-    "ollama": {
-      "type": "ollama",
-      "baseUrl": "http://127.0.0.1:11434",
-      "model": "qwen2.5-coder:7b"
-    },
-    "gemini": {
-      "type": "gemini",
-      "model": "gemini-2.0-flash",
-      "apiKeyEnv": "GEMINI_API_KEY"
-    }
-  },
-  "runtime": {
-    "approvalMode": "ask",
-    "bashConcurrency": "serial",
-    "maxIterations": 40,
-    "maxToolCalls": 100
-  },
-  "context": {
-    "maxInputTokens": null,
-    "reserveOutputTokens": 4096,
-    "compactAtPercent": 85
-  }
-}
-```
+| `ATOM_LITE_MODE` | `plan` / `yolo` |
 
 See [`docs/configuration.md`](./docs/configuration.md) for every field, default, and precedence rule.
 
@@ -169,17 +114,11 @@ atom-lite [task] [--provider NAME] [--model MODEL] [--continue] [--session ID]
 | `--version` | Print version |
 | `--help` | Show help |
 
-In the TUI, type `/help` to see every command grouped by category, or press
-`ctrl+p` for the fuzzy command palette. `/theme` opens a live-preview picker and
-persists your choice to user config; `NO_COLOR` and `--no-color` always win.
-`/sessions` opens a searchable session picker scoped to the current workspace,
-with a toggle for all workspaces, and `/search <query>` prints matching sessions
-with content snippets. Mouse wheel scrolling and click-to-focus are enabled for
-interactive terminals and can be disabled with `ui.mouse: false`.
+In the TUI, type `/help` for every command grouped by category, or press `ctrl+p` for the fuzzy command palette. `/theme` opens a live-preview picker and persists your choice; `NO_COLOR` and `--no-color` always win. `/sessions` opens a searchable picker scoped to the current workspace; `/search <query>` prints matching sessions with snippets. Mouse wheel scrolling and click-to-focus are enabled for interactive terminals and can be disabled with `ui.mouse: false`.
 
 ## Tools
 
-Four core tools (see [ADR 0001](./docs/adr/0001-four-built-in-tools-only.md)) plus the additive network tools from [ADR 0006](./docs/adr/0006-expanded-toolset.md):
+Nine built-in tools — the four core tools from [ADR 0001](./docs/adr/0001-four-built-in-tools-only.md), file search, network tools from [ADR 0006](./docs/adr/0006-expanded-toolset.md), plus `task` for background work from [ADR 0013](./docs/adr/0013-advanced-tool-features.md):
 
 | Tool | Purpose |
 | --- | --- |
@@ -187,16 +126,19 @@ Four core tools (see [ADR 0001](./docs/adr/0001-four-built-in-tools-only.md)) pl
 | `write` | Create or replace files safely (hash-guarded) |
 | `edit` | Precise find-and-replace edits (hash-guarded) |
 | `bash` | Execute shell commands (global exclusive barrier by default) |
+| `grep` | Search file contents by regex (ripgrep-backed, falls back to JS) |
+| `glob` | Find files matching a glob pattern |
 | `webfetch` | Fetch a URL and convert HTML to markdown |
 | `websearch` | Search the web and return ranked results |
+| `task` | Query or control a background bash task |
 
-File discovery, search, tests, Git, builds, formatters, and package managers are available through `bash`, not through additional built-in tools.
+Tests, Git, builds, formatters, and package managers are available through `bash`.
 
 ## Providers
 
 | Type | Adapter | Notes |
 | --- | --- | --- |
-| `openai-compatible` | `OpenAICompatibleAdapter` | LM Studio, llama.cpp/llama-server, Kilo AI Gateway, and other compatible endpoints |
+| `openai-compatible` | `OpenAICompatibleAdapter` | LM Studio, llama.cpp/llama-server, Kilo, and other compatible endpoints |
 | `ollama` | `OllamaAdapter` | Native Ollama chat API |
 | `gemini` | `GeminiAdapter` | Official Gemini API |
 
@@ -204,25 +146,24 @@ Provider profiles are named combinations of endpoint, model, auth source, and op
 
 ### Interactive setup
 
-- `/provider` opens a searchable list of built-in providers (Kilo, OpenAI, Anthropic, Google Gemini, OpenRouter, Groq, Mistral, xAI, Ollama, LM Studio, llama.cpp). Selecting a hosted provider prompts for an API key with hidden input, validates it against the provider, and saves it to `~/.config/atom-lite/credentials.json` (`0600`).
-- `/model` opens a fuzzy-searchable picker containing models from **every configured provider** (plus providers whose key is present in the environment). Live model lists are fetched in the background while the picker stays responsive.
+- `/provider` opens a searchable list of built-in providers (Kilo, OpenAI, Anthropic, Google Gemini, OpenRouter, Groq, Mistral, xAI, Ollama, LM Studio, llama.cpp). Selecting a hosted provider prompts for an API key with hidden input, validates it, and saves it to `~/.config/atom-lite/credentials.json` (`0600`).
+- `/model` opens a fuzzy-searchable picker containing models from every configured provider (plus providers whose key is present in the environment). Live model lists are fetched in the background.
 - `/model <provider>/<model>` and `/provider <name>` are the non-interactive forms.
 
-The selected provider/model is persisted to the user config, so the next session starts where you left off.
+The selected provider/model is persisted to user config, so the next session starts where you left off.
 
 ## Safety & security
 
-- **Workspace boundary** — `read`/`write`/`edit` resolve paths against the workspace and reject escapes. Shell commands are not constrained by this boundary (their effects are unknown), so `bash` runs as a global exclusive barrier.
-- **Approval modes** — `ask` prompts before each shell command; `trusted` auto-approves; `deny` blocks. Session trust can be granted interactively (`t`).
+- **Workspace boundary** — `read`/`write`/`edit` resolve paths against the workspace and reject escapes. Shell commands are not constrained by this boundary, so `bash` runs as a global exclusive barrier.
+- **Autonomy modes** — `plan` allows read/web tools only; `yolo` allows all tools. Default `yolo`. Toggle with Tab or set `runtime.mode`.
 - **Hash guards** — prevent stale overwrites when a file changed since it was read.
 - **Sandboxing flags** — reported per command; see `src/security/`.
-- **No secrets in config** — interactive provider setup stores API keys in `~/.config/atom-lite/credentials.json` with `0600` permissions; environment variables still take precedence.
+- **No secrets in config** — interactive setup stores API keys in `~/.config/atom-lite/credentials.json` (`0600`); environment variables take precedence.
 - **Local-first** — no cloud account, telemetry, or remote control plane required (see [ADR 0004](./docs/adr/0004-local-first-no-cloud-dependency.md)).
 
 ## Commands
 
-Type `/help` for the grouped list, or press `ctrl+p` for the fuzzy command
-palette. Common commands:
+Type `/help` for the grouped list, or press `ctrl+p` for the fuzzy command palette. Common commands:
 
 | Command | Description |
 | --- | --- |
@@ -237,7 +178,9 @@ palette. Common commands:
 | `/extensions` | List discovered extensions and load status |
 | `/compact` | Compact older context |
 | `/clear` | Clear the transcript view |
-| `/approval` | Change approval mode |
+| `/undo` | Restore workspace to a checkpoint |
+| `/diff` | Show changes since the last checkpoint |
+| `/approval` | Show approval mode (legacy) |
 | `/doctor` | Run diagnostics |
 | `/thinking` | Toggle thinking display |
 | `/theme [auto\|dark\|light\|ansi]` | Switch theme |
@@ -246,9 +189,7 @@ palette. Common commands:
 
 ## Sessions
 
-Sessions are append-only JSONL event logs recording everything that happened in one conversation. They are resumable across CLI restarts and grouped by workspace. Stored under the session store (see `src/sessions/`). Compaction summarizes older history to stay within the context budget while retaining the full transcript.
-
-The session index derives a title from the first user message unless `/session rename <title>` overrides it, and records the provider, update time, and message count. `/sessions` resumes a session in place: retained messages are replayed into the transcript and a `session_resumed` event is appended. `/search <query>` matches titles, message content, and workspace paths, ranking title hits first. `--list-sessions` and `--search-sessions` print the same index as stable tab-separated rows for scripts.
+Sessions are append-only JSONL event logs recording everything in one conversation. They are resumable across CLI restarts and grouped by workspace. The session index derives a title from the first user message unless `/session rename <title>` overrides it, and records the provider, update time, and message count. `/sessions` resumes a session in place: retained messages are replayed into the transcript and a `session_resumed` event is appended. `/search <query>` matches titles, message content, and workspace paths, ranking title hits first. `--list-sessions` and `--search-sessions` print the same index as stable tab-separated rows for scripts. Compaction summarizes older history to stay within the context budget while retaining the full transcript.
 
 ## Context management
 
@@ -270,13 +211,14 @@ Tests live in `tests/` (agent, config, runtime, tools). The project is TypeScrip
 
 ### Releasing
 
-1. Update `version` in `package.json` and add a `CHANGELOG.md` entry.
-2. Run `npm run typecheck && npm test && npm run bench`.
-3. Commit, then tag and push: `git tag vX.Y.Z && git push origin master --tags`.
-4. The `Release` workflow stages the package on npm with provenance and opens a draft GitHub release. It requires an `NPM_TOKEN` repository secret with publish access.
-5. Approve the staged version on npm (Staged Packages tab, or `npm stage approve <stage-id>` with 2FA), then publish the draft release on GitHub.
+Follow the release workflow in [`AGENTS.md`](./AGENTS.md):
 
-npm requires a maintainer with 2FA to approve staged releases; CI cannot complete that step.
+1. Bump `version` in `package.json` and add a `CHANGELOG.md` entry.
+2. Run `npm run typecheck && npm test && npm run bench` (bench is non-gating).
+3. Commit, tag, push: `git commit ... && git tag vX.Y.Z && git push origin master --tags`.
+4. Publish to npm directly: `npm publish --access public` (do not use `npm stage approve`).
+5. Create GitHub release: `gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."`.
+6. Verify: `npm view atom-lite version` and the GitHub release page.
 
 ## Architecture
 
@@ -290,7 +232,7 @@ src/
   runtime/      # scheduler, approvals
   security/     # paths, process, redaction
   sessions/     # store, events, recovery
-  tools/        # read, write, edit, bash, webfetch, websearch, registry
+  tools/        # read, write, edit, bash, grep, glob, webfetch, websearch, registry
 ```
 
 Key design decisions are recorded as ADRs in [`docs/adr/`](./docs/adr/):
@@ -305,10 +247,12 @@ Key design decisions are recorded as ADRs in [`docs/adr/`](./docs/adr/):
 
 ## Contributing
 
-Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a pull request. Issues and specs live as markdown under `.scratch/` (see [`docs/agents/issue-tracker.md`](./docs/agents/issue-tracker.md)). Please keep changes consistent with the "small core" principle: new tools require strong justification against ADR 0001.
+Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a pull request. Issues and specs live as markdown under `.scratch/` (see [`docs/agents/issue-tracker.md`](./docs/agents/issue-tracker.md)). Keep changes consistent with the "small core" principle: new tools require strong justification against ADR 0001.
 
 Report vulnerabilities privately as described in [`SECURITY.md`](./SECURITY.md).
 
 ## License
 
 MIT
+
+<!-- appended -->

package/dist/agent/loop.d.ts

@@ -5,6 +5,10 @@ export declare class AgentRuntime {
     private model;
     private workspace;
     private approvals;
+    private mode;
+    private maxTokensPerSession;
+    private maxTokensPerTurn;
+    private totalTokensUsed;
     private contextManager;
     private onEvent;
     private tools;
@@ -17,13 +21,25 @@ export declare class AgentRuntime {
     private systemPrompt;
     private contextWindow;
     private contextUsed;
+    private supportsVision;
+    private backgroundTasks;
+    private checkpointingEnabled;
+    private checkpointStoreOverride;
+    private turnCheckpointed;
+    private turnCheckpointId;
+    private turnCheckpointStore;
+    private turnIndex;
     constructor(options: AgentRuntimeOptions);
     switchModel(provider: AgentRuntimeOptions["provider"], model?: string): void;
     /** Update the context window for the selected model (metadata may arrive late). */
     setContextWindow(window: number | undefined): void;
+    setSupportsVision(value: boolean | undefined): void;
+    private injectCompletedBackgroundTasks;
     getContextUsage(): ContextUsage;
     private emitContextUsage;
     setEffort(effort: string): void;
+    setMode(mode: "plan" | "yolo"): void;
+    getMode(): "plan" | "yolo";
     setSteeringQueue(queue: string[]): void;
     compactSession(session: {
         messages: Message[];