mu-agent 0.1.0

package/docs/development.md

@@ -0,0 +1,90 @@
+# Development
+
+See [AGENTS.md](https://github.com/earendil-works/pi/blob/main/AGENTS.md) for additional guidelines.
+
+## Setup
+
+```bash
+git clone https://github.com/earendil-works/pi
+cd pi
+npm install
+npm run build
+```
+
+Run from source:
+
+```bash
+/path/to/pi/pi-test.sh
+```
+
+The script can be run from any directory. Pi keeps the caller's current working directory.
+
+### Experimental remote harness
+
+The remote harness server/client integration is development-only. Run it from the repository with:
+
+```bash
+PI_EXPERIMENTAL=1 ./pi-test.sh server
+PI_EXPERIMENTAL=1 ./pi-test.sh client
+```
+
+`PI_SERVER_DIR` overrides the server profile and socket directory (default: `~/.pi/server`). `PI_SERVER_ID` selects the logical server ID when `--server-id` is omitted.
+
+The `client` and `experimental/plugin` package subpaths resolve only under the `source` condition in a checkout. Their implementations and the server/client commands are excluded from npm packages and standalone binaries. `pi-client`, `pi-protocol`, and `pi-server` are development dependencies of coding-agent, not runtime dependencies. The local SDK and stdio RPC API are unchanged.
+
+## Forking / Rebranding
+
+Configure via `package.json`:
+
+```json
+{
+  "piConfig": {
+    "name": "pi",
+    "configDir": ".pi"
+  }
+}
+```
+
+Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
+
+## Path Resolution
+
+Three execution modes: npm install, standalone binary, tsx from source.
+
+**Always use `src/config.ts`** for package assets:
+
+```typescript
+import { getPackageDir, getThemeDir } from "./config.js";
+```
+
+Never use `__dirname` directly for package assets.
+
+## Debug Command
+
+`/debug` (hidden) writes to `~/.pi/agent/pi-debug.log`:
+- Rendered TUI lines with ANSI codes
+- Last messages sent to the LLM
+
+## Testing
+
+```bash
+./test.sh                         # Run non-LLM tests (no API keys needed)
+npm test                          # Run all tests
+npm test -- test/specific.test.ts # Run specific test
+```
+
+### Published package smoke test
+
+After building, run `npm run check:package-install`. It packs the public packages and installs only coding-agent as a direct dependency in a temporary directory outside the repository. Local tarball overrides select declared transitive dependencies without installing development-only packages. The check verifies SDK imports and CLI startup without credentials or model requests.
+
+`npm run check` also checks runtime dependency declarations and rejects excluded development sources pulled into a package's build through imports.
+
+## Project Structure
+
+```
+packages/
+  ai/           # LLM provider abstraction
+  agent/        # Agent loop and message types  
+  tui/          # Terminal UI components
+  coding-agent/ # CLI and interactive mode
+```

package/docs/docs.json

@@ -0,0 +1,160 @@
+{
+  "navigation": [
+    {
+      "title": "Start here",
+      "items": [
+        {
+          "title": "Overview",
+          "path": "index.md"
+        },
+        {
+          "title": "Quickstart",
+          "path": "quickstart.md"
+        },
+        {
+          "title": "Using Pi",
+          "path": "usage.md"
+        },
+        {
+          "title": "Providers",
+          "path": "providers.md"
+        },
+        {
+          "title": "Security",
+          "path": "security.md"
+        },
+        {
+          "title": "Containerization",
+          "path": "containerization.md"
+        },
+        {
+          "title": "Settings",
+          "path": "settings.md"
+        },
+        {
+          "title": "Keybindings",
+          "path": "keybindings.md"
+        },
+        {
+          "title": "Sessions",
+          "path": "sessions.md"
+        },
+        {
+          "title": "Compaction",
+          "path": "compaction.md"
+        }
+      ]
+    },
+    {
+      "title": "Customization",
+      "items": [
+        {
+          "title": "Extensions",
+          "path": "extensions.md"
+        },
+        {
+          "title": "Skills",
+          "path": "skills.md"
+        },
+        {
+          "title": "Prompt Templates",
+          "path": "prompt-templates.md"
+        },
+        {
+          "title": "Themes",
+          "path": "themes.md"
+        },
+        {
+          "title": "Pi Packages",
+          "path": "packages.md"
+        },
+        {
+          "title": "Custom Models",
+          "path": "models.md"
+        },
+        {
+          "title": "Custom Providers",
+          "path": "custom-provider.md"
+        }
+      ]
+    },
+    {
+      "title": "Reference",
+      "items": [
+        {
+          "title": "Environment Variables",
+          "path": "environment-variables.md"
+        },
+        {
+          "title": "Session Format",
+          "path": "session-format.md"
+        }
+      ]
+    },
+    {
+      "title": "Programmatic Usage",
+      "items": [
+        {
+          "title": "SDK",
+          "path": "sdk.md"
+        },
+        {
+          "title": "RPC Mode",
+          "path": "rpc.md"
+        },
+        {
+          "title": "JSON Event Stream Mode",
+          "path": "json.md"
+        },
+        {
+          "title": "TUI Components",
+          "path": "tui.md"
+        }
+      ]
+    },
+    {
+      "title": "Platform Setup",
+      "items": [
+        {
+          "title": "Windows",
+          "path": "windows.md"
+        },
+        {
+          "title": "Termux on Android",
+          "path": "termux.md"
+        },
+        {
+          "title": "tmux",
+          "path": "tmux.md"
+        },
+        {
+          "title": "Terminal Setup",
+          "path": "terminal-setup.md"
+        },
+        {
+          "title": "Shell Aliases",
+          "path": "shell-aliases.md"
+        }
+      ]
+    },
+    {
+      "title": "Development",
+      "items": [
+        {
+          "title": "Development",
+          "path": "development.md"
+        }
+      ]
+    }
+  ],
+  "redirects": [
+    {
+      "from": "session.md",
+      "to": "session-format.md"
+    },
+    {
+      "from": "tree.md",
+      "to": "sessions.md"
+    }
+  ]
+}

package/docs/environment-variables.md

@@ -0,0 +1,100 @@
+# Environment Variables
+
+Pi uses environment variables in three ways:
+
+- Variables such as `PI_OFFLINE` configure the Pi process.
+- Pi sets process markers so child processes can identify Pi as the launching agent.
+- Commands run by the LLM-callable shell tools receive `PI_*` variables describing the current session.
+
+Provider API-key variables are documented separately in [Providers](providers.md#environment-variables-or-auth-file).
+
+## Process Marker
+
+The CLI and RPC entry points set two process markers:
+
+- `AI_AGENT=pi` is a generic marker that lets tooling identify Pi as the agent that launched the process.
+- `PI_CODING_AGENT=true` is Pi-specific and lets child processes detect that they run inside Pi.
+
+Child processes inherit both markers. They are not session-specific and are not set automatically when Pi is embedded through the SDK.
+
+## Shell Tool Session Environment
+
+Commands run by the `bash` and `powershell` tools receive the current Pi session state:
+
+| Variable | Description |
+|----------|-------------|
+| `PI_SESSION_ID` | Current session ID |
+| `PI_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
+| `PI_PROVIDER` | Currently selected model provider |
+| `PI_MODEL` | Currently selected model ID |
+| `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
+
+The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next shell command without restarting Pi. `PI_PROVIDER` and `PI_MODEL` identify the selected Pi model, not a different upstream model that a router may choose internally.
+
+When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
+
+```bash
+printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
+printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"
+```
+
+The session file can be inspected directly when the session is persistent:
+
+```bash
+if [ -n "$PI_SESSION_FILE" ]; then
+  tail -n 1 "$PI_SESSION_FILE"
+fi
+```
+
+These variables are injected into the LLM-callable `bash` and `powershell` tools. They are not injected into user-entered `!` or `!!` commands.
+
+### Custom Shell Tools
+
+Tools created with `createBashTool()` or `createPowerShellTool()` expose the session environment by default when registered with Pi. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
+
+```typescript
+const bashTool = createBashTool(cwd, {
+  spawnHook: (ctx) => ({
+    ...ctx,
+    env: { ...ctx.env, CI: "1" },
+  }),
+});
+```
+
+Disable session metadata independently of the spawn hook:
+
+```typescript
+const powershellTool = createPowerShellTool(cwd, {
+  exposeSessionEnvironment: false,
+  spawnHook: (ctx) => ctx,
+});
+```
+
+When disabled, Pi removes inherited values for these variables so nested Pi processes do not expose stale parent-session metadata.
+
+## Pi Process Configuration
+
+These variables are read by Pi itself:
+
+| Variable | Description |
+|----------|-------------|
+| `PI_CODING_AGENT_DIR` | Override the config directory; default is `~/.pi/agent` |
+| `PI_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
+| `PI_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
+| `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
+| `PI_SKIP_VERSION_CHECK` | Disable the `pi.dev` latest-version request |
+| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
+| `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
+| `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
+| `PI_RADIUS_GATEWAY` | Override the Radius gateway origin used by `/bug` uploads and Radius relay connections |
+| `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
+| `PI_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
+| `PI_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
+| `PI_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
+| `PI_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
+| `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
+| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
+
+Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](providers.md#environment-variables-or-auth-file).
+
+`PI_SERVER_DIR` and `PI_SERVER_ID` apply only to the source-only [experimental remote harness](development.md#experimental-remote-harness), not distributed builds.