@ocis/myagent-cli 0.2.0

package/README.md

@@ -0,0 +1,357 @@
+# myagent CLI
+
+A coding agent for **your local repository**, powered by a remote MyAgent.
+The CLI is the hands and eyes; the agent's brain — model, conversation,
+compaction, cost accounting — stays on your MyAgent server.
+Not everything is code: **COWORK** mode turns the same agent into a general assistant
+(questions, lookups, summarizing, organizing) with the full tool set still available —
+see [Plan / Coding / Cowork modes](#plan--coding--cowork-modes).
+
+```
+local repo (cwd)                                  remote myagent
+┌───────────────────────────────┐                ┌────────────────────────────────┐
+│ myagent CLI                    │                │ agent loop (pi-agent-core)      │
+│  TUI: transcript · sidebar     │  SSE / REST    │ model / prompt cache / retry    │
+│  context: AGENTS.md/CLAUDE.md  │◄──────────────►│ history / auto-compact / guard  │
+│  client tools ─────────────────┼─ AG-UI run line│ steering / stop / usage         │
+│  session index (local)         │  + tool results│ (optional) server web_fetch     │
+└───────────────────────────────┘                └────────────────────────────────┘
+```
+
+- **No provider keys on the client.** Models are configured on the MyAgent Models page;
+  the CLI only holds an integration key (`iak_…`). When the integration is set to *Client
+  choice*, `/model` selects among the server's models per new session.
+- **Every coding tool runs on your machine.** The CLI advertises `local_*` tools to the
+  remote agent; when the agent calls one, it executes locally and submits the result.
+- **Agent management stays remote.** Sessions, history, auto-compaction, prompt caching and
+  usage/cost accounting all live on MyAgent and are surfaced in the TUI through the
+  integration API.
+- **One protocol: the AG-UI run line.** Each turn is a single `POST /v1/runs` stream that
+  stays open through tool waits — client tool calls (`CUSTOM_TOOL_CALL`), the agent's
+  continuation, and release signals all arrive on it. Tool results go back as protocol-native
+  `role: "tool"` messages to `POST /v1/runs/:threadId/messages` (single-frame
+  `INPUT_ACCEPTED`/`INPUT_REJECTED` ack). The CLI and the server deploy in lockstep — the
+  CLI assumes the AG-UI line exists.
+
+## Install
+
+```bash
+npm install -g @ocis/myagent-cli   # global (Node ≥22.19)
+bunx @ocis/myagent-cli             # one-off, no install (Bun)
+```
+
+The CLI runs on **Node.js ≥22.19** or **Bun ≥1.0** — it detects the runtime it was
+launched with. The published bin uses a Node shebang, so `bun install -g` also runs
+it under Node; use `bunx` (or `bun <path-to-bin>`) to run it on Bun. Configure
+credentials with `myagent config`, or set `MYAGENT_BASE_URL` /
+`MYAGENT_INTEGRATION_ID` / `MYAGENT_API_KEY`.
+
+## Plan / Coding / Cowork modes
+
+| Mode | Behavior |
+|------|----------|
+| **PLAN** (orange) | Investigate and propose. The mutating tools (`local_write`, `local_edit`, `local_shell`) refuse at execution time with a model-readable error; everything else (including `local_update_todo`) keeps working. |
+| **CODING** (green, default) | Software work: implement, verify, report. |
+| **COWORK** (purple) | General tasks — questions, lookups, summarizing, organizing, drafting. The full tool set stays available (including `local_write`/`local_edit`/`local_shell`); the mode only changes the framing, not the permissions. |
+
+Switch with `Tab` (plan → coding → cowork → plan), `/plan`, `/coding`, `/cowork`, or start
+with `--plan` / `--coding` / `--cowork`.
+
+Modes are designed to be prompt-cache-friendly:
+
+- **The advertised tool set never changes** — all tools are always in the schema, so the
+  cached tool block survives a switch.
+- **The system prompt never changes with the mode** — it statically defines all modes'
+  behavior and the announcement protocol.
+- **The mode is announced per user message** — when it changes (or on the first message of
+  a session), the CLI prepends `[mode: plan]` / `[mode: coding]` / `[mode: cowork]` to that
+  message. It never enters the system prompt, so the cached conversation prefix stays intact.
+
+## Tools (all client-side)
+
+| Tool | Purpose |
+|------|---------|
+| `local_read` | Read a text file with line numbers (`offset`/`limit`, binary/size guards) |
+| `local_write` | Create/overwrite (or append) a file, creating parent directories |
+| `local_edit` | Exact-string replacement (unique or `replace_all`; batch `edits`), returns a unified diff. Literal replacement — `$&` in the new text is safe. |
+| `local_shell` | Shell command on your machine, rooted at the workspace; 120s default timeout; process-group kill; 50KB UTF-8-safe output cap |
+| `local_grep` | Regex search (ripgrep when installed, pure-JS fallback), 100-match cap, skips build/VCS dirs |
+| `local_find` | Glob file discovery (`*`, `?`, `**`, `{a,b}`), 500-result cap |
+| `local_ls` | Directory listing (optional recursive + glob filter) |
+| `load_local_skill` | Load a `SKILL.md` playbook from the machine |
+| `local_update_todo` | Maintain the session TODO list (rendered in the right sidebar). Batched into the same assistant turn as other tool calls to avoid an extra model round-trip. |
+| `local_transfer_files` | Move single files between your machine and the myagent workspace (`direction: get`/`put`, plus `list`). Uses the workspace API; `get` writes locally (ASK/plan-mode rules apply), `put` does not touch your machine. Content never enters the model transcript. |
+
+Side-effecting tools honor the approval mode: **AUTO** (default) runs in-workspace work
+unattended but still asks before touching paths outside the workspace, while **ASK**
+confirms every mutation (and outside reads). `Shift+Tab` or `/edit` toggles it per session
+(changeable mid-run, it takes effect immediately); the current approval state is always
+visible in the status bar (AUTO is amber), and the active mode in the prompt's bottom
+edge. `--ask` starts in ASK, `--auto` (or the config default) starts in AUTO;
+`--allow-outside` pre-approves outside paths so they never prompt.
+
+**Workspace transfers.** `local_transfer_files` moves single files between your machine and
+the myagent server's shared workspace (the same files the web file browser/WebDAV expose):
+`{"direction":"put","from":"notes.txt"}` uploads, `{"direction":"get","from":"reports/q3.md"}`
+downloads, `{"direction":"list","path":"/"}` browses. Uploads are capped at ~37 MB (the
+server's 50 MB body limit after base64); both directions overwrite. Chat attachments made in
+the web UI are stored outside the workspace and are not reachable this way.
+
+### Approval prompts
+
+An approval floats directly above the prompt input (the editor keeps focus —
+you can keep typing) and is answered with **ctrl+y** (approve) or **ctrl+n**
+(deny). The wait is bounded: after **10 minutes** the approval times out and
+the agent receives an error result telling it to stop and wait for you — a
+run never hangs on an unanswered prompt.
+
+Approvals **serialize**: one card is shown at a time and the rest queue in
+arrival order (a round's parallel calls, or a second tool round starting while
+you decide, can each need one). Each waiting approval keeps its own deadline
+and its own cancellation, so a release of one call never cancels another and
+`/stop` cancels every one of them.
+
+While you decide, the CLI watches the session's event channel (when the server
+advertises `sessionEvents`) and reports when the channel itself drops and is
+being reconnected. If the server releases the call while you decide (the
+30-minute lease expired, the sandbox restarted, or the run ended), the
+approval is **cancelled** — the tool never runs, and the tool card in the
+transcript says so. Stopping the run (Esc, Ctrl+C, `/stop`) cancels a pending
+approval the same way. If the sandbox was paused while you were away, the next
+request wakes it automatically.
+
+## Context files
+
+Every turn ships a stable system block containing:
+
+- **`AGENTS.override.md` → `AGENTS.md` → `CLAUDE.md`** discovered per directory from the
+  filesystem root down to the workspace (outermost first), plus the global
+  `~/.config/myagent/AGENTS.md` and `.myagent/AGENTS.md`. Disable with `--no-context-files`.
+- Environment facts (workspace, OS + release + arch). Date and git branch are deliberately
+  omitted — the agent can query them with `local_shell` when needed.
+- The local `<available_skills>` catalog.
+- Both modes' instructions and the `[mode: x]` announcement protocol (static — the active
+  mode never changes this block). The TODO list lives in the `local_update_todo` tool
+  calls, not here.
+
+The block is re-sent each turn because the integration API treats system messages as
+per-request instructions — it is kept byte-stable across turns (no mode, todos, date or
+branch) so the provider prompt cache survives.
+
+## TUI
+
+```
+┌──────────────────────────────────────────────┬──────────────────────┐
+│ transcript                                   │ session title        │
+│  messages · tool calls · thinking · diffs    │ CONTEXT              │
+│                                              │  84k/200k (42% used) │
+│                                              │  ~$0.42 (27% cached) │
+│                                              │ TODO (2/5)           │
+│                                              │ CHANGES (12)         │
+│   ╭──────────────────────────────────────╮   │  M src/a.ts +18 -4   │
+│   │  > editor (multi-line, / commands…)  │   │                      │
+│   ╰─ CODING · sonnet-4-6 · high ─────────╯   │                      │
+│     AUTO · working · ↑ ↓ $       ~/repo:main │                      │
+└──────────────────────────────────────────────┴──────────────────────┘
+```
+
+The layout splits left/right first: the transcript, prompt and status bar live in the
+left column, so they never affect the right panel, which runs the full height of the
+terminal.
+
+- **Sidebar** (Ctrl+P toggles; hidden below 100 columns; ~25% of the terminal width):
+  the session title, a `CONTEXT` section (shown once usage is reported: `used / window
+  (% used)` on the first content line, cost with the cached-token share below), a `TODO`
+  section (only once the todo tool has been used), and `CHANGES` from `git`. Each section
+  title is prefixed with a hue-colored accent bar (`▌`) and sections have breathing room
+  above and below; the panel has a slightly lighter background (from the terminal's OSC 11
+  reply). Scroll with the mouse wheel or `Alt+↑/↓`; click `… N more` / press `Ctrl+E` to
+  expand the file list (collapsed shows 10, expanded shows every changed file).
+- **Diff viewer**: click a changed file in the sidebar. The viewer fills the screen — a
+  gray rounded frame inset from the edges (nothing behind it leaks through), with the file
+  title, position and view mode centered in the top edge. Only the diff content is shown
+  (`diff --git`, `index`, `---`/`+++` and `@@` headers are hidden); changed lines carry
+  pre/post line numbers, `↑/↓ PgUp/PgDn` or the mouse wheel scrolls, `t` toggles
+  inline/side-by-side (`i`/`p` pick a view), `Esc` closes, and opening another file
+  replaces the popup. The card refits the screen on terminal resize/zoom (the scroll
+  position is clamped to the new height).
+- **Prompt**: the editor sits in a rounded, inset frame (no background of its own); its
+  bottom edge carries the active mode (`PLAN` orange / `CODING` green / `COWORK` purple — `Tab`
+  cycles, click the label for the mode picker) followed by the model and thinking level in
+  gray (`·`-separated, both clickable to open their pickers), and a `↓ N more`
+  indicator while the input is scrolled.
+- **Status bar**: gray text on the terminal's own background, separated from the prompt by a
+  blank row; approval (`AUTO`/`ASK`, switchable mid-run with Shift+Tab or by clicking the
+  badge), run state, the current/last run's token totals and cost sit on the left, and
+  `path:branch` is flush right.
+- **Transcript**: assistant markdown (gray prose, indented `•` bullets and tables), a
+  collapsed thinking block (Ctrl+T), and tool calls collapsed to their header — e.g.
+  `▸ ✓ read src/app.ts · lines 1–4` (click one, or Ctrl+O for all, to expand). Expanded
+  results render by kind: syntax-highlighted file reads, side-by-side diffs with line
+  numbers for edits, `$ command` plus the last 30 output lines for bash (older lines
+  collapse to `... skipped`, failures are red). Server-tool activity and notices follow.
+- **Approvals** appear as an overlay (`y`/`n`).
+- **Editor**: `/` slash-command autocomplete, `@` file references, Shift+Enter or
+  Alt+Enter for a newline. (`Tab` is reserved for the mode cycle.)
+
+### Keys
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Cycle PLAN/CODING/COWORK |
+| `Shift+Tab` | Toggle AUTO/ASK approval |
+| `Enter` | Send; while running: **steer** the message into the in-flight turn |
+| `Ctrl+Y` / `Ctrl+N` | Answer a pending approval (approve / deny) |
+| `Esc` | Force-stop the run (`POST /stop`) |
+| `Ctrl+C` | Stop while running; while idle, press twice within 2s to quit (`/quit` exits directly) |
+| `Ctrl+P` | Toggle sidebar |
+| `Ctrl+E` | Expand/collapse the changed-files list |
+| `Alt+↑` / `Alt+↓` | Scroll the sidebar (mouse wheel works too) |
+| Click a file | Open its diff in a popup |
+| `t` / `i` / `p` | In the diff popup: toggle / inline / side-by-side pair |
+| `Ctrl+O` | Expand/collapse all tool output (a single tool call toggles on click) |
+| `Ctrl+T` | Expand/collapse thinking |
+| `Shift+Enter` / `Alt+Enter` | Newline |
+
+### Commands
+
+`/help` `/new` `/session [all]` (`/sessions`, `/resume` — aliases) `/plan` `/coding` `/cowork` `/mode` `/edit` `/thinking` `/model` `/compact`
+`/stop` `/reload` `/export` `/config` `/quit`
+
+## Sessions
+
+The remote session is the source of truth. The CLI keeps a small local index
+(`~/.config/myagent/sessions.json`) mapping working directories to thread ids and TODO
+lists so `-c` continues the right conversation.
+
+- `/new` — start a fresh session (the remote thread is created on the next prompt).
+- `/session` — list **this folder's** sessions and switch. The remote API has no working-
+  directory concept, so the filter comes from the local index; a "Show all folders…" entry
+  (or `/session all`) reveals every session on the integration, annotated with its source
+  folder. Switching to a session from another folder warns that tools still run in the
+  current workspace.
+- `/export` writes a markdown transcript; `/sessions` and `/resume` are aliases of `/session`.
+
+- **Steering**: typing while a run is active queues the message into the server-side run. It
+  floats above the prompt until the agent actually injects it (`QUEUED_MESSAGE_DELIVERED`),
+  then moves into the transcript as a user message.
+- **Stop**: `Esc` or `/stop` aborts the stream and calls the stop endpoint.
+- **Recovery**: if the stream drops, the CLI reconciles against the session detail
+  endpoint. Pending **read-only** tool calls are re-executed safely; pending **mutating**
+  calls are failed with an explanatory result instead of silently re-applied.
+- **Usage**: live `RUN_USAGE` events update the sidebar; on resume, persisted
+  `usage_stats` seed the panel.
+
+## Model selection
+
+The model runs server-side and is shown on the prompt's bottom edge. The integration's Model
+policy decides who picks it:
+
+- **Client choice** (the default): the CLI fetches the selectable models from
+  `GET /v1/models` and `/model` offers them in a picker. The server default (the first entry)
+  is marked **default**; the model in use is marked **current** (current wins when it is also
+  the default). `--model <id>` preselects one for new sessions.
+- **A forced model**: the endpoint returns exactly one entry, so there is nothing to choose.
+
+A thread pins its model on its first run, so `/model` applies to the **next** new session
+(`/new`); the running thread keeps its model. Once a session has run, `/thinking` offers the
+levels reported for that session's model.
+
+## Thinking level
+
+The thinking level is selectable per request — the same behavior as the web UI's per-message
+selector: `/thinking` offers the levels detected for the model plus **Default** (provider
+decides). `--thinking <level>` sets it for a run.
+
+## Credentials & config
+
+Resolved in order — flags > env > config file:
+
+- Flags: `--base-url`, `--integration-id`, `--api-key`
+- Env: `MYAGENT_BASE_URL`, `MYAGENT_INTEGRATION_ID`, `MYAGENT_API_KEY`, `MYAGENT_APPROVAL`
+- File: `$XDG_CONFIG_HOME/myagent/config.json` (0600), written by `myagent config`
+
+`--base-url` / `MYAGENT_BASE_URL` also accept the combined **API Base URL** shown on the
+Integrations page (`https://host/integrations/<id>`) — the integration id is derived from it.
+
+Create an integration + API key on the MyAgent **Integrations** page. Recommended settings
+for the CLI:
+
+- **Tools**: leave empty (all coding tools are supplied by the CLI) or enable `web_fetch` for
+  server-side fetching.
+- **Model**: any tool-capable model with a reasonable context window.
+
+The CLI and the server deploy in lockstep — every documented integration-API feature is
+assumed to exist (there is no capability handshake).
+
+## Non-interactive use
+
+```bash
+myagent -p "summarise the failing tests"       # text to stdout, tools to stderr
+cat README.md | myagent run "explain this"     # prompt from stdin
+myagent -p --output-format json "..."          # one JSON object: thread_id/text/usage
+myagent -p --output-format stream-json "..."   # JSONL events as they happen
+```
+
+### Prompt mode (CI)
+
+`--prompt` is the unattended one-shot entry point for CI and scripts:
+
+```bash
+myagent --prompt "fix the failing tests"                    # final answer to stdout
+cat prompt.md | myagent --prompt -                          # prompt from stdin
+myagent --prompt "..." --session <thread-id>                # continue a previous session
+myagent --prompt "..." --output-format json --timeout 600   # machine-readable, bounded
+```
+
+- **Non-TUI** — `--prompt` always runs headless, even on a TTY.
+- **AUTO accept all** — every tool runs unattended, *including paths outside the
+  workspace* (no one is present to answer an approval prompt). `--ask` cannot be
+  honored here and is ignored — passing both prints a warning on stderr rather
+  than silently dropping the safer setting. `--plan` still works (read-only).
+- **stdout is only the final assistant message** (tool progress goes to stderr).
+  `--output-format json` emits one JSON object — `thread_id`, `model`, `text`,
+  `usage`, `error`, `error_code` — and it is emitted for pre-run failures too, so
+  a parser never sees an empty stdout.
+- **`--timeout <sec>`** aborts the run (and stops it server-side) after N seconds.
+- **SIGINT/SIGTERM** stop the remote run gracefully (exit 130/143); a second
+  signal exits immediately.
+- **Continuation**: the JSON `thread_id` is the session id — pass it back as
+  `--session <thread-id>` to continue the same context on the next run. `-c`
+  continues the most recent session for the working directory (local index).
+
+Exit codes: `0` success · `1` run failed (including timeout) · `2` usage,
+configuration, or connection error · `130`/`143` interrupted.
+
+For CI, configure credentials via env (`MYAGENT_BASE_URL` — the combined
+`https://host/integrations/<id>` URL works — `MYAGENT_INTEGRATION_ID`,
+`MYAGENT_API_KEY`). `--prompt` sends its own final-answer instruction, so the
+agent returns only the final answer without any integration-side configuration.
+
+`-p`/`run` remain the general headless mode: they respect the configured
+approval default (and `--ask` denies mutating tools), and stream all assistant
+text. `--prompt` is the opinionated CI mode on top of the same runner.
+
+## Local skills
+
+A skill is a directory with `SKILL.md` (frontmatter `name`/`description` + instructions).
+Search paths, earlier wins: `--skills-dir`, `<workspace>/.myagent/skills`,
+`~/.config/myagent/skills`. The catalog is injected into the system block; the agent loads
+one with `load_local_skill`.
+
+## Development
+
+```bash
+bun install
+bun run dev            # run from source
+bun test               # unit + e2e (fake integration server) tests
+bun run typecheck
+bun run build          # npm package → dist/ (tsc + fix-esm; prepack runs this)
+bun run build:binary   # standalone binary → dist/myagent
+bun run build:all      # cross-compile linux/macos/windows (x64 + arm64)
+```
+
+`bun run build` emits the publishable ESM package to `dist/` (`prepack` runs it
+automatically on `npm publish`). The compiled binary has no runtime dependencies.
+`@earendil-works/pi-tui` provides the rendering layer (the same library the pi
+coding agent ships with).

package/dist/agent/context.d.ts

@@ -0,0 +1,33 @@
+export interface ContextFile {
+    path: string;
+    content: string;
+}
+/**
+ * Discover context files: the global file first, then per-directory files
+ * from the trust boundary down to cwd (outermost first), so the most local
+ * instructions come last. One file per directory; AGENTS.override.md wins.
+ *
+ * The walk is bounded (see contextBoundary): an unbounded walk to `/` would
+ * let anyone who can write to a shared ancestor (e.g. /tmp/AGENTS.md) inject
+ * instructions into every turn's system prompt — and in auto-approval mode
+ * drive unsupervised tool calls.
+ */
+export declare function findContextFiles(cwd: string, globalContextPath?: string): Promise<ContextFile[]>;
+export interface EnvironmentInfo {
+    workspace: string;
+    /** OS descriptor, e.g. "linux 6.8.0 (x64)". */
+    os: string;
+}
+/** Stable OS descriptor for the environment block (no volatile values). */
+export declare function osDescription(): string;
+export declare function buildEnvironmentBlock(info: EnvironmentInfo): string;
+export interface SystemPromptInput {
+    workspace: string;
+    contextFiles: ContextFile[];
+    environment: EnvironmentInfo;
+    skillsCatalog?: string;
+    /** Additional instructions (e.g. per-session user config). */
+    extraInstructions?: string;
+}
+/** Compose the per-request system block. Must be byte-stable across turns. */
+export declare function composeSystemPrompt(input: SystemPromptInput): string;

package/dist/agent/context.js

@@ -0,0 +1,169 @@
+// ---------------------------------------------------------------------------
+// Local context assembly for the remote agent.
+//
+// The agent's brain runs on MyAgent; the CLI is the only party that can see
+// the user's repository. Every turn therefore ships a system block carrying:
+//   - context files (AGENTS.md / CLAUDE.md) discovered from cwd upward
+//   - environment facts (workspace, OS) — deliberately NOT date/git branch,
+//     which change during a session and would invalidate the provider prompt
+//     cache (the agent can query them with local_shell when needed)
+//   - the local skills catalog
+//   - every mode's instructions and the mode-announcement protocol
+//
+// The block is re-sent each turn because the integration API treats `system`
+// messages as per-request instructions (replace semantics); it is therefore
+// kept byte-stable across turns so the cached prefix survives. The current
+// mode/todos never enter this block — the mode arrives as a `[mode: x]` marker
+// in the user message, and todos live in the local_update_todo tool calls.
+// ---------------------------------------------------------------------------
+import { homedir, release } from "node:os";
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { DEFAULT_MODE, MODES } from "./modes.js";
+const PER_DIR_CANDIDATES = [
+    "AGENTS.override.md",
+    "AGENTS.md",
+    "AGENTS.MD",
+    "CLAUDE.md",
+    "CLAUDE.MD",
+    ".myagent/AGENTS.md",
+];
+async function readIfExists(path) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            return null;
+        const text = await readFile(path, "utf-8");
+        return text.trim() ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The outermost directory whose context files are trusted: the git repository
+ * root when cwd is inside one, else $HOME when cwd is under it, else cwd.
+ */
+async function contextBoundary(start) {
+    for (let dir = start;;) {
+        if (await pathExists(join(dir, ".git")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const home = homedir();
+    return start === home || start.startsWith(home + sep) ? home : start;
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Discover context files: the global file first, then per-directory files
+ * from the trust boundary down to cwd (outermost first), so the most local
+ * instructions come last. One file per directory; AGENTS.override.md wins.
+ *
+ * The walk is bounded (see contextBoundary): an unbounded walk to `/` would
+ * let anyone who can write to a shared ancestor (e.g. /tmp/AGENTS.md) inject
+ * instructions into every turn's system prompt — and in auto-approval mode
+ * drive unsupervised tool calls.
+ */
+export async function findContextFiles(cwd, globalContextPath) {
+    const files = [];
+    if (globalContextPath) {
+        const content = await readIfExists(globalContextPath);
+        if (content)
+            files.push({ path: globalContextPath, content });
+    }
+    const start = resolve(cwd);
+    const boundary = await contextBoundary(start);
+    const ancestors = [];
+    for (let dir = start;;) {
+        ancestors.push(dir);
+        if (dir === boundary)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // defensive: the boundary is always an ancestor
+        dir = parent;
+    }
+    // boundary → cwd
+    ancestors.reverse();
+    for (const dir of ancestors) {
+        for (const candidate of PER_DIR_CANDIDATES) {
+            const full = join(dir, candidate);
+            const content = await readIfExists(full);
+            if (content) {
+                files.push({ path: full, content });
+                break;
+            }
+        }
+    }
+    return files;
+}
+/** Stable OS descriptor for the environment block (no volatile values). */
+export function osDescription() {
+    return `${process.platform} ${release()} (${process.arch})`;
+}
+export function buildEnvironmentBlock(info) {
+    return [
+        `<environment>`,
+        `workspace: ${info.workspace}`,
+        `os: ${info.os}`,
+        `</environment>`,
+    ].join("\n");
+}
+/**
+ * Static description of ALL modes plus the announcement protocol. Never
+ * changes with the active mode — the current mode is announced per user
+ * message as `[mode: plan]` / `[mode: coding]` / `[mode: cowork]`.
+ */
+function buildModesBlock() {
+    const modes = Object.keys(MODES);
+    const markers = modes.map((mode) => `[mode: ${mode}]`);
+    const markerList = `${markers.slice(0, -1).join(", ")} or ${markers.at(-1)}`;
+    const sections = modes.map((mode) => [`<${mode}_mode>`, MODES[mode].instructions, `</${mode}_mode>`].join("\n"));
+    return [
+        "<modes>",
+        "You operate in one of the modes below. Each user message may start with a mode marker —",
+        `${markerList} — announcing which mode you must follow; the`,
+        "latest marker wins. If no marker is present, keep following the last announced mode",
+        `(${DEFAULT_MODE} initially). All modes share the same tools: in plan mode the mutating tools refuse`,
+        "with an error instead of executing, so do not call them.",
+        "",
+        sections.join("\n\n"),
+        "</modes>",
+    ].join("\n");
+}
+/** Compose the per-request system block. Must be byte-stable across turns. */
+export function composeSystemPrompt(input) {
+    const parts = [];
+    parts.push([
+        "<cli_role>",
+        "You are MyAgent CLI, an assistant running on the user's machine.",
+        `All tools you are given execute locally inside the workspace: ${input.workspace}`,
+        "Always use those tools for file and shell work; there is no server-side copy of the files.",
+        "Paths are workspace-relative. The announced mode defines whether the task is software work",
+        "or general assistance — follow it.",
+        "</cli_role>",
+    ].join("\n"));
+    parts.push(buildModesBlock());
+    if (input.contextFiles.length > 0) {
+        const blocks = input.contextFiles.map((file) => `--- ${file.path} ---\n${file.content.trimEnd()}`);
+        parts.push(`<project_context>\n${blocks.join("\n\n")}\n</project_context>`);
+    }
+    parts.push(buildEnvironmentBlock(input.environment));
+    if (input.skillsCatalog)
+        parts.push(input.skillsCatalog);
+    if (input.extraInstructions?.trim()) {
+        parts.push(`<user_instructions>\n${input.extraInstructions.trim()}\n</user_instructions>`);
+    }
+    return parts.join("\n\n");
+}

package/dist/agent/modes.d.ts

@@ -0,0 +1,21 @@
+export type AgentMode = "plan" | "coding" | "cowork";
+/** The mode a fresh session starts in. */
+export declare const DEFAULT_MODE: AgentMode;
+export interface ModeSpec {
+    name: AgentMode;
+    /** Uppercase badge for the prompt frame / footer. */
+    label: string;
+    /** One-line UI blurb (mode picker rows). */
+    description: string;
+    /** Instructions for this mode, rendered into the static <modes> prompt block. */
+    instructions: string;
+    /** Mode accent color for badge + editor border. */
+    color: (s: string) => string;
+}
+export declare const MODES: Record<AgentMode, ModeSpec>;
+/** `[mode: plan]` / `[mode: coding]` / `[mode: cowork]` marker at the start of a user message. */
+export declare function modeMarker(mode: AgentMode): string;
+export declare function stripModeMarker(text: string): string;
+/** Tab / `/mode` cycle: plan → coding → cowork → plan. */
+export declare function nextMode(mode: AgentMode): AgentMode;
+export declare function isReadOnlyTool(name: string): boolean;

package/dist/agent/modes.js

@@ -0,0 +1,84 @@
+// ---------------------------------------------------------------------------
+// Plan / Coding / Cowork modes.
+//
+// IMPORTANT: the advertised tool set is mode-independent (a stable tool schema
+// block keeps the provider prompt cache warm across mode switches). A mode is
+// enforced at EXECUTION time: in plan mode mutating tools refuse with an error,
+// and the mode is announced to the model per user message via a `[mode: x]`
+// marker (see `modeMarker`). The system prompt statically defines all modes'
+// behavior — it never changes with the mode.
+// ---------------------------------------------------------------------------
+import { CODING_COLOR, COWORK_COLOR, PLAN_COLOR } from "../ui/colors.js";
+/** The mode a fresh session starts in. */
+export const DEFAULT_MODE = "coding";
+/** Tools whose execution never changes the user's machine. */
+const READ_ONLY_TOOLS = ["local_read", "local_grep", "local_find", "local_ls", "load_local_skill"];
+export const MODES = {
+    plan: {
+        name: "plan",
+        label: "PLAN",
+        color: PLAN_COLOR,
+        description: "read-only — investigate and propose",
+        instructions: [
+            "# Mode: PLAN (read-only)",
+            "You are in planning mode. Investigate and propose; do not change anything.",
+            "- Use the read-only tools to explore the codebase and gather evidence.",
+            "- Mutating tools (local_write, local_edit, local_shell) are advertised but REFUSE with an error in this mode — do not call them.",
+            "- local_update_todo is bookkeeping only and remains available if you want to lay out a plan checklist; batch it into the same turn as your other tool calls (parallel tool calling), never a turn of its own.",
+            "- Produce a concrete plan: files to change, the approach, risks, verification steps.",
+            "- Ask clarifying questions when the request is ambiguous instead of guessing.",
+            "- Keep the final plan concise and directly actionable — the user will switch to Coding mode to execute it.",
+        ].join("\n"),
+    },
+    coding: {
+        name: "coding",
+        label: "CODING",
+        color: CODING_COLOR,
+        description: "software work, end to end",
+        instructions: [
+            "# Mode: CODING (software engineering)",
+            "You are in coding mode. Carry out the software task end-to-end.",
+            "- Read before you write; prefer editing existing files over creating new ones.",
+            "- Keep changes minimal and consistent with the existing code.",
+            "- Use local_update_todo to track multi-step work (send the entire list each time). Batch it into the same turn as the tool calls it describes (parallel tool calling) — a todo-only turn wastes a model round-trip.",
+            "- Verify your changes (run tests/typecheck/build with local_shell where available).",
+            "- Keep the user informed with brief progress notes, then finish with a short summary.",
+        ].join("\n"),
+    },
+    cowork: {
+        name: "cowork",
+        label: "COWORK",
+        color: COWORK_COLOR,
+        description: "general tasks and everyday work",
+        instructions: [
+            "# Mode: COWORK (general tasks)",
+            "You are in cowork mode: a general-purpose assistant, not primarily a coding agent.",
+            "- Help with everyday work — answering questions, looking things up, summarizing, organizing information, drafting text, lightweight analysis.",
+            "- Do not assume the task involves a repository or code; ask when the goal is unclear.",
+            "- Answer directly and concisely first; expand only when it adds value.",
+            "- The full tool set is available (local_read, local_grep, local_find, local_ls, local_shell, local_write, local_edit, local_update_todo, local_transfer_files): use the tools when they genuinely help (inspect local files, run a command, verify a fact, move files to/from the myagent workspace). Do not refuse a tool just because the mode is cowork.",
+            "- local_update_todo remains available for multi-step work; batch it into the same turn as your other tool calls (parallel tool calling).",
+            "- Reply in the user's language.",
+        ].join("\n"),
+    },
+};
+/** `[mode: plan]` / `[mode: coding]` / `[mode: cowork]` marker at the start of a user message. */
+export function modeMarker(mode) {
+    return `[mode: ${mode}]`;
+}
+/**
+ * Remove a leading mode marker (used when rendering server-side history).
+ * `build`/`chat` are the pre-rename ids — old sessions still carry them.
+ */
+const MODE_MARKER_PATTERN = new RegExp(`^\\[mode: (?:${[...Object.keys(MODES), "build", "chat"].join("|")})\\]\\s*\\n*`);
+export function stripModeMarker(text) {
+    return text.replace(MODE_MARKER_PATTERN, "");
+}
+/** Tab / `/mode` cycle: plan → coding → cowork → plan. */
+export function nextMode(mode) {
+    const order = Object.keys(MODES);
+    return order[(order.indexOf(mode) + 1) % order.length];
+}
+export function isReadOnlyTool(name) {
+    return READ_ONLY_TOOLS.includes(name);
+}