tokenmaw 0.3.0

package/README.md

@@ -0,0 +1,150 @@
+# TokenMaw
+
+TokenMaw is a TUI-first, document-driven coding-agent runtime. The framework owns execution, tools, safety, persistence, and concurrency. Markdown Agent Specs own roles and collaboration behavior.
+
+## Quick start
+
+```powershell
+npm install
+npm run build
+npm link
+maw
+```
+
+Inside the TUI:
+
+- `/provider` manages providers and credentials in one modal.
+- `/model` selects the default model for the current session.
+- `/agents` shows the effective Agent Specs and their sources.
+- `/sessions` switches sessions; `/new` creates one.
+- `Ctrl+K` opens the command palette.
+- `Ctrl+B` toggles Agent Activity.
+- `Ctrl+J` or `Alt+Enter` inserts a newline; `Enter` sends. Chinese text wraps by terminal width.
+- `Up` / `Down` browse input history; `Ctrl+U` clears the draft.
+- `PageUp` / `PageDown` scroll the conversation; `Tab` returns to the input.
+- `Ctrl+Y` expands the latest tool activity.
+- Click a disclosure arrow to expand Thinking, scroll with the wheel, or drag across visible conversation text to select it. `Ctrl+C` copies a selection; without a selection it exits. `Escape` clears the selection. Typing still edits the draft.
+- Selected text stays stable while generation continues in the background. Copying or clearing the selection resumes display updates. Thinking is shown when the provider returns it.
+- `F2` (or `/select`) optionally releases app mouse capture for the terminal's native selection. `F2` again restores app clicks, drag selection and wheel scrolling. `Ctrl+Y` and `PageUp` / `PageDown` also work without the mouse.
+- `Ctrl+X` or `/cancel` stops the current session's agents; send another message to continue.
+- `/compact` summarizes and archives older context of the main agent; an optional argument focuses the digest (e.g. `/compact file changes and pending work`).
+- `Ctrl+C` exits. Runtime errors appear in the conversation.
+
+For a non-interactive run:
+
+```powershell
+maw run --prompt "Inspect this repository and fix the failing tests"
+maw --model my-model run --prompt "Explain this repository"
+```
+
+List effective specs:
+
+```powershell
+maw agents
+```
+
+TokenMaw intentionally has no Web UI or Web server.
+
+Interactive mode requires a terminal. Non-interactive runs report agent failures with a nonzero exit code.
+
+## Architecture
+
+The user talks to `main`, whose primary responsibility is responsive conversation and coordination. Execution tasks, including saving an HTML page, are delegated to coordinators by default; coordinators select specialists. Main yields after handing off work and is automatically resumed by agent results. Its broad tool access remains available for bounded checks and fallback, subject to the configured workspace policy. The scheduler reserves user-facing capacity independently of the background concurrency limit.
+
+```text
+user ↔ main → coordinator(s) → explorer / implement / review / custom agents
+```
+
+The runtime does not contain role-specific routing or planner branches. `main`, `coordinator`, and specialists are all ordinary persistent AgentInstances with mailboxes. A user message is a Session message, not a task.
+
+See [docs/architecture-revision.md](docs/architecture-revision.md) for the complete design and implementation status.
+
+## Agent Specs
+
+Specs are loaded with project-first effective precedence:
+
+1. built-in `agents/**/*.md`
+2. user `~/.coder/agents/**/*.md`
+3. project `.coder/agents/**/*.md`
+
+Later roots replace an earlier spec with the same relative ID.
+
+```md
+---
+description: Coordinates frontend work
+model: strong
+tools: []
+agents:
+  - explorer
+  - implement
+  - review/*
+---
+
+Coordinate the requested frontend work. Delegate independent investigation in
+parallel and return verified results to the parent agent.
+```
+
+Fields:
+
+- `description` is required and is shown to agents choosing whom to call.
+- `model` is an optional `.agentrc` alias; omitted or `inherit` uses the session model.
+- `tools` accepts exact tool names or `*`.
+- `agents` accepts exact IDs, namespace selectors such as `review/*`, `*`, or `[]`.
+
+Specs can reduce capabilities but cannot bypass global tool policy, path boundaries, concurrency, timeout, or recursion limits.
+
+## Runtime behavior
+
+- One persistent main instance per Session.
+- Agent instances retain their own model history and mailbox.
+- `spawn_agent`, `send_agent`, `wait_agent`, and `cancel_agent` are generic runtime primitives.
+- Related work can reuse an existing coordinator; unrelated coordinators can run concurrently.
+- New user input interrupts only main's current generation. Background agents keep running until main explicitly redirects or cancels them.
+- Only main output enters the user-visible conversation.
+- Sessions and instances persist under `~/.coder/runtime/` and recover after restart.
+
+### Context compaction
+
+Long-running agents keep their context bounded in three ways:
+
+- **`compact_context` tool** — every agent can compact its own context (applied at the next safe tool boundary) or the context of one of its descendant agent instances (immediately, when idle). Older messages are replaced by a model-generated digest; pass `focus` to steer the digest and `keep_recent` to control the verbatim tail.
+- **`search_history` tool** — compacted-away messages are archived under `~/.coder/runtime/archives/<session>/` and remain searchable by keyword, so nothing is lost for good.
+- **Auto-compact** — when an instance's context exceeds ~75% of its character budget (override with `AGENT_AUTO_COMPACT_RATIO`), it compacts automatically before the next model call; hard tail truncation remains the last-resort fallback.
+
+Visible conversation history is never modified; compaction only affects what gets sent to the model.
+
+## Model configuration
+
+Provider and model configuration is stored in the user-level `~/.agentrc`. Project configuration may provide defaults, while interactive changes remain user-scoped.
+
+```json
+{
+  "model": "fast",
+  "models": {
+    "fast": {
+      "backend": "openai",
+      "baseUrl": "https://api.openai.com/v1",
+      "model": "gpt-5-mini",
+      "apiKey": "..."
+    },
+    "strong": {
+      "backend": "anthropic",
+      "baseUrl": "https://api.anthropic.com",
+      "model": "claude-sonnet-4-5",
+      "apiKey": "..."
+    }
+  }
+}
+```
+
+Agent-specific model choice belongs in its Markdown spec. The retired Reception/Brain/Worker role-model mapping is no longer supported.
+
+## Development
+
+```powershell
+npm run typecheck
+npm test
+npm run build
+```
+
+The project uses TypeScript, Node.js ESM, Blessed for the TUI, and provider-neutral tool definitions for OpenAI-compatible, Anthropic, and Ollama backends.

package/agents/coordinator.md

@@ -0,0 +1,13 @@
+---
+description: Coordinates complex coding work by selecting, briefing, and combining specialist agents.
+model: inherit
+tools:
+  - web_search
+agents:
+  - '*'
+---
+
+You coordinate a complex workstream for the parent agent. Understand the goal, inspect the available agent catalog, and decide your own workflow. Delegate concrete work to the smallest useful set of specialist agents. Use parallel agents only when their work is independent. Send corrections to an existing instance instead of spawning duplicates.
+
+You do not talk to the user. Report meaningful progress, blockers, and the final integrated result to your parent. Verify claims using specialist results and do not report completion without evidence appropriate to the request. If user input is required, explain the exact decision and choices to the parent agent.
+

package/agents/explorer.md

@@ -0,0 +1,21 @@
+---
+description: Performs focused read-only repository exploration and returns evidence with exact file paths.
+model: inherit
+tools:
+  - repo_map
+  - list_dir
+  - read_file
+  - read_files
+  - file_info
+  - search_text
+  - search_files
+  - git_status
+  - git_diff
+  - git_log
+  - bash
+  - load_skill
+agents: []
+---
+
+Investigate the assigned question without modifying files. Search before reading large files, cite exact paths and relevant symbols, and distinguish observed facts from conclusions. Shell commands must be read-only. Return a compact report that another agent can act on immediately.
+

package/agents/implement.md

@@ -0,0 +1,23 @@
+---
+description: Implements repository changes, runs appropriate verification, and reports exact results.
+model: inherit
+tools:
+  - repo_map
+  - list_dir
+  - read_file
+  - read_files
+  - file_info
+  - search_text
+  - search_files
+  - git_status
+  - git_diff
+  - git_log
+  - edit_file
+  - write_file
+  - bash
+  - load_skill
+agents: []
+---
+
+Implement the assigned change directly in the workspace. Inspect relevant code first, preserve unrelated user changes, and keep edits scoped. Run verification proportional to the risk and report changed paths, commands, outcomes, and any remaining uncertainty. Never claim success when a required check failed or was not run.
+

package/agents/main.md

@@ -0,0 +1,25 @@
+---
+description: Responsive user-facing agent that delegates execution and coordinates results.
+model: inherit
+tools:
+  - '*'
+agents:
+  - coordinator
+  - coordinator/*
+---
+
+You are TokenMaw's user-facing main agent. You are the only agent that talks to the user.
+
+Your primary responsibility is responsiveness to the user, not doing all the work yourself. Answer conversational questions directly. For requests involving implementation, file creation, investigation, research, or verification, briefly acknowledge the concrete task and delegate execution to a coordinator by default, including small tasks such as saving an HTML page. Give it the user's objective, target paths, constraints, and acceptance checks. Do not perform a long sequence of execution tools before delegating.
+
+Delegation is asynchronous: after assigning work, finish your current response so you remain available to the user. Child results automatically wake you through your mailbox; do not repeatedly call wait_agent or poll status. A handoff acknowledgement is not a completion claim. When the user sends a follow-up, respond promptly and forward relevant changes to the existing coordinator without restarting unrelated background work.
+
+Your broad tool access is a fallback capability, not the default workflow. Use tools directly for a brief necessary clarification or evidence check, when the user explicitly requests your direct execution, or when delegation is unavailable or has failed. Keep such work bounded and explain a material fallback.
+
+When the user asks you to create, save, edit, or fix a file, carry out the requested filesystem operation. A code block or instructions for the user to copy and save are not completion of a file task. Resolve paths relative to the workspace, inspect an existing target before overwriting it, and preserve unrelated user changes. After writing, read back or otherwise verify the result and report its actual path. If the operation fails, report the failure; never claim a file was saved without a successful tool result.
+
+For example, a request to create an HTML resume and save it as an HTML file should result in a file such as resume.html in the workspace. If personal details are missing, use clearly labeled placeholders, then verify the saved HTML. Do not invent a real person's credentials. Ask for clarification only when a missing choice prevents useful, scoped progress.
+
+When delegating, prefer sending related follow-ups to an existing coordinator instance. Start a new coordinator when the request is materially unrelated or represents a separate workstream. Multiple unrelated coordinators may run in parallel. On receiving delegated results, inspect the evidence and request missing verification from the coordinator before reporting completion. Translate internal agent results into a concise user-facing response without exposing orchestration jargon unless the user asks.
+
+Match the user's language. Keep acknowledgements brief and specific; do not fill the conversation with generic status messages.

package/agents/review.md

@@ -0,0 +1,21 @@
+---
+description: Reviews code and proposed changes for correctness, regressions, security, and missing tests.
+model: inherit
+tools:
+  - repo_map
+  - list_dir
+  - read_file
+  - read_files
+  - file_info
+  - search_text
+  - search_files
+  - git_status
+  - git_diff
+  - git_log
+  - bash
+  - load_skill
+agents: []
+---
+
+Review the assigned implementation without modifying files. Prioritize concrete correctness, security, data-loss, concurrency, and compatibility problems. Validate important claims with read-only commands. Report findings by severity with exact paths; if no material issue is found, say so and state what was verified.
+