tokenmaw 0.3.0 → 0.4.1

package/README.md

@@ -17,7 +17,10 @@ Inside the TUI:
 - `/model` selects the default model for the current session.
 - `/agents` shows the effective Agent Specs and their sources.
 - `/sessions` switches sessions; `/new` creates one.
+- `/cd <path>` switches the working directory (relative paths resolve against the current one). The status bar always shows the current directory; `/cd` with no argument or `/pwd` prints it. Switching reloads the project's `.coder/agents` specs and `AGENTS.md`, and tool path authorization follows the new root.
+- `!<command>` runs a shell command directly in the current workspace, outside the agent loop: the prompt turns into `$` and the command text is highlighted while typing, the command and its output stream inline into the conversation transcript (never sent to the model or fed back into context), long-running commands animate their ellipsis, and `Ctrl+C` stops a running command. `/`-commands stay reserved for the built-in slash commands.
 - `Ctrl+K` opens the command palette.
+- `/worktree <name>` creates (or reopens) an isolated git worktree under `.coder/worktrees/<name>` on branch `maw/<name>` and moves this session into it, so parallel sessions stop colliding on one working tree. `/worktree-list` shows status, `/worktree-exit` returns to the main checkout (the worktree stays on disk), `/worktree-remove <name>` drops a clean worktree (the branch is never deleted). A `.worktreeinclude` file copies gitignored files (e.g. `.env`) into new worktrees. Non-interactive equivalent: `maw --worktree [name]`.
 - `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.
@@ -28,7 +31,10 @@ Inside the TUI:
 - `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.
+- `/btw <question>` opens a side conversation forked from the current session (full context included) and sends your question there. `/back` or `Ctrl+C` returns to the main conversation; side sessions are marked `[side]` in the status bar and the `/sessions` list.
+- `/fork` copies the current conversation into a new saved session. `/sessions` lists both; the original stays untouched.
+- `/goal <text>` sets a standing goal for the session: it is injected into every agent's prompt until cleared, shows in the status bar, and survives across sessions. `/goal clear` removes it.
+- `Ctrl+C` copies a selection; without a selection it arms a quit confirmation — press again within 2 seconds to exit. Inside a side conversation, `Ctrl+C` returns to the parent session instead. Runtime errors appear in the conversation.
 
 For a non-interactive run:
 
@@ -49,7 +55,7 @@ Interactive mode requires a terminal. Non-interactive runs report agent failures
 
 ## 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.
+The user talks to `main`, whose primary responsibility is responsive conversation and forward progress. Main handles small, local, and well-scoped work directly. It delegates only genuinely multi-file, ambiguous, or independently parallel work; coordinators select specialists only when that extra coordination is useful. Main remains available while background work runs and is resumed by verified agent results. The scheduler reserves user-facing capacity independently of the background concurrency limit.
 
 ```text
 user ↔ main → coordinator(s) → explorer / implement / review / custom agents
@@ -102,6 +108,20 @@ Specs can reduce capabilities but cannot bypass global tool policy, path boundar
 - 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.
+- Each turn records requests, input/output tokens, provider-reported cached input, and first-token latency when the backend supplies them. The status bar shows the session aggregate.
+- `AGENT_MAX_CHILDREN_PER_TURN` limits fan-out (default `3`); `AGENT_MAX_CONCURRENT_TURNS` and `AGENT_MAX_DEPTH` provide additional scheduler guardrails.
+
+### Multi-process safety
+
+Multiple `maw` processes can run against the same project without silently destroying each other's work:
+
+- **Cross-process write locks** — every file write (`edit_file`, `write_file`) and every session is guarded by an O_EXCL lock file under `~/.coder/runtime/locks/`. Lock records carry the holder pid and process start time, so a lock left by a crashed process is detected and taken over automatically, while a live holder is reported by pid (`AGENT_SESSION_LOCK_TIMEOUT_MS` adjusts the session-lock wait, default 5s).
+- **Optimistic conflict detection** — `edit_file` re-verifies inside the lock that the file still matches what the edit was based on; `write_file` refuses to overwrite a file that changed after it was read in this session. Changes from external editors or other tooling surface as explicit errors instead of silent lost updates.
+- **Single writer per session** — opening a session another process is writing succeeds in read-only mode (the status bar shows `[read-only pid <n>]`); submissions, `/goal`, and `/clear` are refused with guidance. `/fork` continues from that point in a writable copy, and once the other writer exits, the session self-heals back to writable on the next message.
+- **Concurrent instance awareness** — live instances register under `~/.coder/runtime/instances/`; the status bar warns when other maw processes share the workspace.
+- **Managed worktrees** — for genuine parallelism, `/worktree <name>` (or `maw --worktree [name]`) isolates each session in its own checkout so conflicts become ordinary merges. Worktrees are `git worktree lock`ed while a session uses them; cleanup removes clean, unlocked ones and never touches dirty checkouts or branches.
+
+Provider prompt caching is used when the provider supports it: runtime system prefixes stay stable and live sibling state travels through mailboxes instead of being re-injected into every request. Cross-request response caching is intentionally avoided because coding answers depend on the current workspace and tool results.
 
 ### Context compaction
 

package/agents/coordinator.md

@@ -7,7 +7,6 @@ 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.
+You coordinate a complex workstream for the parent agent. Understand the goal and choose the smallest workflow that can finish it. Start with one focused explorer or implementer; add another agent only when its work is independent and necessary. As soon as the root cause and edit location are clear, stop exploration and implement. Reuse existing instances instead of spawning duplicates.
 
+You do not talk to the user. Report concise progress to your parent: conclusion, evidence, changed paths, and next action. Do not paste large tool outputs. Verify claims with focused checks and do not report completion without evidence. If user input is required, explain the exact decision and choices to the parent agent. Stop or cancel redundant agents once one result resolves the question.

package/agents/main.md

@@ -10,9 +10,9 @@ agents:
 
 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.
+Your primary responsibility is responsiveness and forward progress. Answer conversational questions directly. Handle small, local, or well-scoped fixes yourself with the available tools. Delegate only when the task is genuinely multi-file, ambiguous, or benefits from independent parallel work. Never create a coordinator merely to inspect one or two files. When delegating, give one concrete objective, target paths, constraints, and acceptance checks.
 
-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.
+Delegation is asynchronous: after assigning work, 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 evidence is sufficient, stop further exploration and implement or ask the existing worker to implement. Never restart an equivalent workstream for a follow-up.
 
 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.
 

package/dist/backend.js

@@ -89,7 +89,11 @@ async function* ollamaStream(config, systemPrompt, messages, tools, signal) {
                 yield { content: null, toolCalls: obj.message.tool_calls, done: false };
             }
             if (obj.done) {
-                yield { content: null, done: true };
+                const stats = obj;
+                yield { content: null, done: true, usage: (stats.prompt_eval_count !== undefined || stats.eval_count !== undefined) ? {
+                        inputTokens: stats.prompt_eval_count,
+                        outputTokens: stats.eval_count,
+                    } : undefined };
                 return;
             }
         }
@@ -200,6 +204,7 @@ async function* openaiStream(config, systemPrompt, messages, tools, signal) {
         model: config.model,
         stream: true,
         messages: convertToOpenAIMessages(systemPrompt, messages),
+        stream_options: { include_usage: true },
     };
     applyOpenAIRequestOptions(body, config);
     const openaiTools = convertToolsToOpenAI(tools);
@@ -245,6 +250,13 @@ async function* openaiStream(config, systemPrompt, messages, tools, signal) {
                 continue;
             try {
                 const parsed = JSON.parse(trimmed.slice(6));
+                if (parsed.usage)
+                    yield { content: null, done: false, usage: {
+                            inputTokens: parsed.usage.prompt_tokens,
+                            outputTokens: parsed.usage.completion_tokens,
+                            cachedInputTokens: parsed.usage.prompt_tokens_details?.cached_tokens,
+                            reasoningTokens: parsed.usage.completion_tokens_details?.reasoning_tokens,
+                        } };
                 const choice = parsed.choices?.[0];
                 if (!choice)
                     continue;
@@ -495,6 +507,24 @@ async function* anthropicStream(config, systemPrompt, messages, tools, signal) {
                     yield { content: null, toolCalls: [toolCall], done: false };
                     continue;
                 }
+                if (event === 'message_start' && (parsed.message?.usage?.input_tokens !== undefined)) {
+                    const usage = parsed.message.usage;
+                    yield { content: null, done: false, usage: {
+                            inputTokens: usage.input_tokens,
+                            cachedInputTokens: usage.cache_read_input_tokens,
+                            cacheCreationInputTokens: usage.cache_creation_input_tokens,
+                        } };
+                }
+                if (event === 'message_delta' && parsed.usage) {
+                    const usage = parsed.usage;
+                    if (usage.output_tokens !== undefined || usage.cache_read_input_tokens !== undefined || usage.cache_creation_input_tokens !== undefined) {
+                        yield { content: null, done: false, usage: {
+                                outputTokens: usage.output_tokens,
+                                cachedInputTokens: usage.cache_read_input_tokens,
+                                cacheCreationInputTokens: usage.cache_creation_input_tokens,
+                            } };
+                    }
+                }
                 if (event === 'message_stop') {
                     yield { content: null, done: true };
                     return;

package/dist/cli.js

@@ -6,13 +6,29 @@ import { resolveModelConfig } from './model-config.js';
 import { defaultPolicy } from './policy.js';
 import { AgentRegistry } from './runtime/agent-registry.js';
 import { AgentRuntime } from './runtime/agent-runtime.js';
+import { WorktreeManager } from './runtime/worktree.js';
+import { registerWorkspaceInstance } from './runtime/workspace-instances.js';
 import { runFullscreenTui } from './ui/fullscreen-tui.js';
+import { checkForUpdate, formatUpdateNotice, offerSelfUpdate } from './update-check.js';
 import { CODER_VERSION } from './version.js';
 async function main() {
     const program = new Command();
     program.name('maw').description('Document-driven coding agent runtime').version(CODER_VERSION);
     program.allowExcessArguments(false).showSuggestionAfterError();
     program.option('--model <name>', 'default model name or .agentrc alias');
+    program.option('--worktree [name]', 'start inside an isolated managed git worktree (.coder/worktrees/<name>)');
+    // Query npm for a newer release while the command runs; afterwards a y/N
+    // prompt offers a self-update (China mirror first) in interactive sessions.
+    const updateNotice = checkForUpdate().catch(() => null);
+    const showUpdateNotice = async () => {
+        const result = await updateNotice;
+        if (!result?.updateAvailable || !process.stderr.isTTY)
+            return;
+        process.stderr.write(`\n${formatUpdateNotice(result)}\n`);
+        const message = await offerSelfUpdate(result).catch(() => null);
+        if (message)
+            process.stderr.write(`\n${message}\n`);
+    };
     let config = await loadConfig();
     const selectedFromCli = () => program.opts().model;
     setToolPolicy(defaultPolicy(config.policyLevel ?? 'moderate', process.cwd()));
@@ -23,6 +39,19 @@ async function main() {
         defaultModel: selectedFromCli() ?? config.model,
         resolveModel: (alias) => resolveModelConfig(config, alias).config,
     });
+    // Announce this instance so concurrent maw processes in the same workspace
+    // can surface a warning (and users can see who else is editing).
+    const stopInstanceHeartbeat = await registerWorkspaceInstance(process.cwd());
+    // /cd moves the runtime to a new workspace root; the tool policy must follow
+    // so read/write authorization keeps covering the new tree.
+    runtime.subscribe((event) => {
+        if (event.type !== 'workspace_changed')
+            return;
+        setToolPolicy(defaultPolicy(config.policyLevel ?? 'moderate', event.workspaceRoot));
+        void registerWorkspaceInstance(event.workspaceRoot).then((stop) => {
+            void stopInstanceHeartbeat().then(stop);
+        });
+    });
     const configManager = {
         getConfig: () => config,
         saveConfig: async (next) => {
@@ -54,6 +83,7 @@ async function main() {
             const response = session.messages.slice(submitted + 1).reverse().find((message) => message.role === 'assistant');
             if (response)
                 process.stdout.write(`${response.content}\n`);
+            await showUpdateNotice();
         }
         finally {
             await runtime.shutdown();
@@ -67,12 +97,26 @@ async function main() {
         for (const spec of runtime.listAgentSpecs()) {
             process.stdout.write(`${spec.id}\t${spec.scope}\t${spec.model ?? 'inherit'}\t${spec.description}\n`);
         }
+        await showUpdateNotice();
         await runtime.shutdown();
     });
     program.action(async () => {
         if (!process.stdin.isTTY || !process.stdout.isTTY)
             throw new Error('Interactive mode requires a terminal. Use maw run --prompt "..." for non-interactive execution.');
         await runtime.whenReady();
+        const worktreeArg = program.opts().worktree;
+        if (worktreeArg !== undefined) {
+            const manager = new WorktreeManager(process.cwd());
+            if (!await manager.isGitRepository()) {
+                console.error('--worktree requires a git repository');
+                process.exitCode = 1;
+                return;
+            }
+            const name = typeof worktreeArg === 'string' && worktreeArg.trim() ? worktreeArg.trim() : `session-${Date.now()}`;
+            const info = await manager.create(name);
+            await runtime.changeWorkspace(info.path);
+            process.stdout.write(`worktree ready: ${info.path} (${info.branch})\n`);
+        }
         const requested = selectedFromCli();
         const selected = resolveModelConfig(config, requested);
         runtime.setDefaultModel(requested ?? config.model);
@@ -86,10 +130,12 @@ async function main() {
             },
             configManager,
         });
+        await showUpdateNotice();
         await runtime.shutdown();
     });
     const shutdown = async () => {
         await runtime.shutdown().catch(() => undefined);
+        await stopInstanceHeartbeat().catch(() => undefined);
         process.exit(0);
     };
     process.once('SIGTERM', () => { void shutdown(); });