@mu-agent/mu 0.1.0 → 0.2.1

package/README.md

@@ -1,97 +1,125 @@
 # @mu-agent/mu
 
-The terminal and TypeScript SDK distribution of Mu, a general-purpose extensible AI
-agent platform. Coding is the default profile, not a constraint of the underlying kernel.
+The CLI and TypeScript SDK distribution of [Mu](https://github.com/Spandan7724/mu), an
+extensible AI agent with a built-in coding profile.
+
+The package provides:
+
+- the `mu` interactive terminal application;
+- headless and NDJSON RPC modes;
+- the public `Agent` and `createAgent` TypeScript APIs;
+- the coding profile, TUI, extensions, MCP support, and a platform-specific ripgrep
+  sidecar.
+
+This package requires Bun 1.3 or later at runtime.
+
+## Install the CLI
 
 ```sh
-# npm (requires Bun)
 npm install -g @mu-agent/mu
-
-# Bun
+# or
 bun install -g @mu-agent/mu
+
 mu
 ```
 
-Update a global npm or Bun installation:
+Run `/login` to configure a provider account or API key, then `/model` to select a model.
+Environment variables such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`
+also work.
 
 ```sh
-mu self update
+mu                                  # interactive TUI
+mu -p "fix the failing test"        # one-shot result
+mu -p "review this patch" --json    # JSON event stream
+mu --resume <session-id>            # resume a session
+mu --rpc                            # NDJSON operations in, events out
+mu agents                           # manage several sessions
 ```
 
-Install the package locally to embed Mu:
+Run `mu --help` for all flags. Global npm and Bun installs can update or remove themselves:
 
 ```sh
-npm install @mu-agent/mu
-# or: bun add @mu-agent/mu
+mu self update
+mu self uninstall
 ```
 
-```ts
-import { Agent, createAgent } from "@mu-agent/mu";
+Native, runtime-free installers and release archives are documented in the
+[project README](https://github.com/Spandan7724/mu#install).
 
-// A domain-neutral agent with a general prompt and no tools.
-const assistant = new Agent();
-console.log((await assistant.run("Explain how an AI agent loop works")).text);
+## Coding agent
 
-// Mu's built-in coding profile: file, search, shell, task, and checkpoint tools.
-const codingAgent = await createAgent({
-  profile: "coding",
-  profileOptions: { root: process.cwd() },
-});
-console.log((await codingAgent.run("Summarize this directory")).text);
-await codingAgent.shutdown();
-```
+The CLI loads the coding profile by default. It includes:
+
+- `read`, `ls`, `edit`, and `write` file tools;
+- foreground and PTY-backed background shell commands;
+- repository search with `rg` and `rg --files`;
+- read-before-write checks and diff previews for approvals;
+- shadow-git workspace checkpoints with `/undo`, `/redo`, `/fork`, and `/diff`;
+- durable sessions, automatic context compaction, and Markdown transcript export;
+- managed `task` delegation and coding-specific `search`, `counsel`, and `recall` subagents.
+
+Explicitly ask **“Ask Recall why we rejected SQLite”** to investigate retained project
+sessions, including compacted history and alternate branches. Recall has only read-only
+history tools, no workspace or network tools, and cites session/entry references. It uses
+Search's same-provider model routing with the current model as fallback. Explicit-only
+invocation is a parent-model instruction, not a classifier or runtime authorization gate.
+Separate project directories, including other clones/worktrees, are not automatically joined.
+
+The default permission mode allows inspection and asks before file changes or commands.
+Use `/permissions` or `--permission-mode` to choose `default`, `accept-edits`,
+`plan-readonly`, or `yolo`. These are permission rules, not an OS sandbox.
+
+CLI sessions are scoped to the current project and stored under `~/.mu/sessions`.
+Checkpoints are stored under `~/.mu/checkpoints` and do not add commits or refs to the
+user's repository.
+
+### Interactive commands
+
+| Command | Purpose |
+|---|---|
+| `/login`, `/logout` | Add or remove credentials stored by Mu |
+| `/model` | Select the active model |
+| `/permissions` | Change the current permission mode |
+| `/resume`, `/new`, `/rename` | Open, create, or name conversations |
+| `/compact [focus]` | Compact the active model context |
+| `/undo`, `/redo`, `/fork`, `/diff` | Navigate the session and workspace history |
+| `/export [path.md]` | Export the complete active branch |
+| `/btw [question]` | Open an ephemeral read-only side conversation |
+| `/instructions [reload]`, `/reload` | Inspect or reload repository instructions |
+| `/subagents` | List subagents, their roles, and how to invoke them |
+| `/cost` | Show session token and cost totals |
+| `/keybindings` | Show Mu-specific keyboard controls |
+
+During a run, Enter steers the current turn and Tab queues a follow-up. `Ctrl+O` opens
+transcript review, `Alt+T` collapses expanded tool activity, `Shift+Tab` cycles permission
+modes, and a leading `!` runs a command directly without a model call. Direct shell commands
+are still recorded as session context.
 
-The matching OS/CPU package supplies a pinned ripgrep binary for fast search; installs
-without it fall back to `rg` on `PATH` or mu's built-in search.
-
-Run `/login` to sign in with an account or API key and `/logout` to remove a credential
-saved that way. Environment variables are not changed by `/logout`. `/model` only lists
-providers authenticated through `/login`; `openai-codex/*` rows use the ChatGPT plan and
-`openai/*` rows use a saved API key. Both OpenAI routes default to GPT-5.6 Sol. See the
-project repository for configuration, SDK, and development documentation.
-
-Local `llama-server` models are available under `llama-cpp/<alias>` without a login. Mu
-uses `http://127.0.0.1:8000` by default and discovers the alias exposed by `/v1/models`;
-set `LLAMA_CPP_BASE_URL` for another address and `LLAMA_CPP_API_KEY` for a secured server.
-
-Interactive runs are saved by working-directory scope under `~/.mu/sessions`; use
-`/resume` to choose one or `mu --resume <session-id>` to continue it directly. Mu prints
-the direct resume command when an interactive session closes. Use `/rename [name]` to name
-the current conversation; named conversations use that name in `/resume`. Press Delete
-twice on a `/resume` row to permanently remove it. Use `/new` to clear the terminal and
-start a fresh chat without deleting the previous saved session. Use
-`/permissions` to choose `default`, `accept-edits`, `plan-readonly`, or full-access
-behavior, including while the agent is running. In the coding TUI, `/btw [question]`
-opens an ephemeral read-only side conversation with the current chat as reference. Press
-Ctrl+B to switch between conversations or Escape to close the side conversation.
-
-Run `mu agents` to manage several sessions whose worker processes survive closing the
-viewer. Managed sessions commit the initiating prompt before contacting the provider and
-commit every completed assistant/tool turn before starting the next one. If a supervisor,
-worker, or machine stops during an in-flight provider or tool call, Mu marks that runtime
-failed and resumes from the last committed boundary; it never automatically replays the
-interrupted operation or claims exact mid-turn continuation.
-
-Coding workers that share a workspace serialize shadow-checkpoint Git operations with a
-cross-process ownership lock, including stale-owner recovery. Their filesystem itself is
-still shared: simultaneous agents can observe one another's edits, so coordinate tasks
-that modify the same files.
-
-Managed workers support built-in and external profiles through `--profile`. Profile
-commands, scoped session storage, runtime lifecycle hooks, and TUI renderers are preserved
-in managed mode. Environment needed only by a custom profile can be forwarded with
-uppercase `MU_PROFILE_*` variables; process identity variables such as `HOME` are never
-accepted through the viewer-to-supervisor handoff.
-
-Mu loads coding instructions from `~/.mu/AGENTS.md` and from the active project, stopping
-at its Git root. `AGENTS.override.md` takes precedence over `AGENTS.md`; Claude-compatible
-fallback files, `.mu/rules/`, `.claude/rules/`, conditional `paths` frontmatter, and safe
-`@file` imports are supported. Run `/instructions` to see the exact loaded files and
-warnings, `/instructions reload` (or `/reload`) to rescan, or start with
-`--no-instructions` to disable loading for one invocation.
-
-Instruction settings can be placed in user or project `.mu/config.json`; project values
-override user values:
+## Providers
+
+Account sign-in is available for OpenAI Codex/ChatGPT, GitHub Copilot, Kimi Code,
+OpenRouter, and xAI. API-key routes include Anthropic, OpenAI, Google, Z.AI Coding Plan,
+Qwen Token Plan, and providers supported by Mu's shared OpenAI-compatible and
+Gemini-compatible transports. Anthropic subscription OAuth is not supported.
+
+OpenAI API-key models use the `openai/*` namespace. ChatGPT-plan models use
+`openai-codex/*`; the credentials are separate and may coexist. Both routes receive
+provider-hosted web search automatically. Other providers currently run without web
+search.
+
+A local `llama-server` is discovered at `http://127.0.0.1:8000` and exposed as
+`llama-cpp/<alias>`. Set `LLAMA_CPP_BASE_URL` or `LLAMA_CPP_API_KEY` when needed.
+
+## Project instructions and extensions
+
+The coding profile loads instructions from `~/.mu/AGENTS.md` and the active project,
+stopping at its configured root marker (`.git` by default). It supports
+`AGENTS.override.md`, `AGENTS.md`, configured fallback names such as `CLAUDE.md`,
+`.mu/rules/`, `.claude/rules/`, conditional `paths` frontmatter, and scoped `@file`
+imports.
+
+Instruction settings can be placed in `~/.mu/config.json` or `.mu/config.json`. Project
+values override user values.
 
 ```json
 {
@@ -104,3 +132,137 @@ override user values:
   }
 }
 ```
+
+The CLI also discovers:
+
+- TypeScript extensions in `~/.mu/extensions` and `.mu/extensions`;
+- Markdown slash commands in `~/.mu/commands` and `.mu/commands`;
+- skills in `~/.mu/skills` and `.mu/skills`;
+- MCP servers from user and project `.mu/config.json`.
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "command": "bunx",
+      "args": ["-y", "your-mcp-server"],
+      "env": { "SERVER_TOKEN": "..." }
+    }
+  }
+}
+```
+
+MCP tools are named `mcp_<server>_<tool>` and use the same permission, event, and abort
+paths as local tools.
+
+## TypeScript SDK
+
+Install the package in a Bun project:
+
+```sh
+bun add @mu-agent/mu
+```
+
+### Low-level agent
+
+`new Agent()` is domain-neutral. It uses an in-memory session store and has no tools or
+extensions unless they are supplied by the caller.
+
+```ts
+import { Agent } from "@mu-agent/mu";
+
+const agent = new Agent({
+  model: "anthropic/claude-sonnet-5",
+  budget: { maxTurns: 8, maxCostUsd: 1 },
+});
+
+const result = await agent.run("Summarize the design trade-offs");
+console.log(result.text);
+console.log(result.reason, result.usage);
+```
+
+### Coding agent
+
+`createAgent()` adds managed `task` delegation. With `profile: "coding"`, it also loads
+the shipped coding tools, project instructions, permissions, checkpoints, background
+runtime, and `search`/`counsel`/`recall` specialists. Recall can access only history in the
+configured session store; SDK agents use an in-memory store by default.
+
+```ts
+import { createAgent } from "@mu-agent/mu";
+
+const agent = await createAgent({
+  profile: "coding",
+  profileOptions: { root: process.cwd() },
+  budget: { maxCostUsd: 2 },
+});
+
+const result = await agent.run("Find and fix the failing test");
+console.log(result.text);
+await agent.shutdown();
+```
+
+### Browser agent
+
+`profile: "browser"` drives a real Chrome-family browser over the Chrome DevTools Protocol:
+mu's own persistent profile (`~/.mu/browser/profiles/<name>`, sign in once with
+`mu browser login`) or any endpoint via `cdpUrl`. Actions that send, buy, delete, publish
+or change account settings, typing into password fields, uploads and page scripts go
+through `onPermission`; page content is treated as untrusted data.
+
+```ts
+import { createAgent } from "@mu-agent/mu";
+
+const agent = await createAgent({
+  profile: "browser",
+  profileOptions: { browserProfile: "default", headless: false },
+  onPermission: async (request) => (request.permission === "browser:commit" ? "deny" : "allow"),
+});
+
+const result = await agent.run("Summarize my three most recent unread emails");
+console.log(result.text);
+await agent.shutdown(); // the browser window stays open unless keepOpen: false
+```
+
+Options: `browserProfile`, `connect` (`managed` | `cdp`), `cdpUrl`, `executable`,
+`channel`, `headless`, `vision` (`auto` | `on` | `off`), `viewport`, `keepOpen`,
+`downloadsDir`, `allowedHosts`, `blockedHosts`. The same keys are read from the `browser`
+section of `~/.mu/config.json`; explicit options win.
+
+### Custom tools
+
+Tools use Zod schemas. Arguments are validated before `execute`, and the schema is
+converted to JSON Schema for providers.
+
+```ts
+import { Agent, tool } from "@mu-agent/mu";
+import { z } from "zod";
+
+const add = tool({
+  name: "add",
+  description: "Add two numbers",
+  inputSchema: z.object({ a: z.number(), b: z.number() }),
+  execute: ({ a, b }) => String(a + b),
+});
+
+const agent = new Agent({ tools: [add] });
+const result = await agent.run("What is 17 + 25?");
+console.log(result.text);
+```
+
+`Agent` also supports:
+
+- `stream()` for the same serializable event stream used by the TUI and RPC;
+- Zod-validated structured output through `run(prompt, { output: schema })`;
+- permission callbacks and layered permission rules;
+- model, turn, token, and cost budgets;
+- custom providers and models;
+- `MemorySessionStore`, `FileSessionStore`, and caller-defined session stores;
+- extensions, shell hooks, skills, MCP, child agents, and transcript serialization.
+
+See the [project README](https://github.com/Spandan7724/mu#typescript-sdk) and
+[source](https://github.com/Spandan7724/mu) for the complete project overview.
+
+## License
+
+MIT