subrouter-cli 0.0.0-stage → 0.1.0

package/CLAUDE.md

@@ -0,0 +1,51 @@
+# subrouter-cli
+
+`sub` — a personal agentic coding CLI (Claude Code / pi style) backed by the subrouter
+AI router (https://router.eva.pink). TypeScript on Node 24+, run straight from source
+via Node's native type stripping — no build step, no runtime dependencies.
+
+## Running
+
+```bash
+npm install        # devDependencies only (typescript + @types/node, for typechecking)
+npm link           # puts `sub` on your PATH
+sub --check        # connectivity + catalog diagnostic
+node scripts/sse-harness.ts --model <id> --dialect openai|anthropic|auto [--tools] [--save test/fixtures/x.sse]
+```
+
+## Constraints
+
+- **Zero runtime dependencies.** Only Node built-ins in `src/` and `scripts/`.
+- **Never print, log, or commit an API key — not even a masked form of it.** Real keys
+  live in `~/.config/subrouter-cli/config.json` (chmod 600) or the `SUBROUTER_API_KEY`
+  env var. `config.example.json` is the safe, committed template.
+- **Never log message content** to stdout/stderr; session transcripts go only to
+  `~/.config/subrouter-cli/sessions/`.
+- **macOS only (v1).** Raw-mode TTY handling and ANSI output assume a macOS Terminal.
+- **Terminal authorization and absolute access.** The user explicitly requested
+  guarded auto and a separate absolute permissions mode with whole-drive access.
+  `run_command` uses fixed `/bin/zsh -f -c` via Node built-ins, an existing cwd,
+  bounded output/time, ignored stdin and process-group cancellation. Commands require
+  separate explicit yes, except recognized routine tasks in session-only guarded
+  auto (`--auto`, `/mode auto`) or arbitrary commands in acknowledged absolute mode
+  (`--absolute`, `/mode absolute`). Destructive, elevated, unknown or opaque commands
+  never qualify in guarded auto. Absolute requires an interactive warning and typed
+  `ABSOLUTE` before activation, is never persisted, and bypasses per-call approvals
+  and the command classifier. It also lifts file-tool project/.git/recovery path
+  guards and allows absolute, home, parent and external paths; other modes retain
+  confinement. This grants current-account access, not root or a macOS permission
+  bypass. Tool-format/size/collision/tree safeguards, recoverable removal, known-key
+  protection and cancellation remain. Absolute capabilities are host-only and scoped
+  per execution with live generation checks; queued grants cannot survive revocation.
+  File approve-all and legacy `--auto-approve` remain file-only. Command grants use
+  exact snapshots; guarded auto also revalidates policy at execution. Tests/builds
+  execute trusted project code: a classifier is not proof of safety. Commands are
+  **not sandboxed** and may access the
+  wider machine/network. Do not claim cwd confinement limits command effects or
+  guarantee cleanup of descendants that detach into another process group. Do not
+  expose persistent background jobs or interactive command input. Use a minimal
+  environment allowlist and sanitize/redact known router credentials before output
+  reaches model history, transcripts or UI. No raw command-output progress cards.
+- **Clipboard helper stays user-triggered.** Image paste uses
+  `execFile('/usr/bin/osascript', …)` with fixed AppKit/JXA code, no shell, and no
+  clipboard-derived code or arguments. No native builds or third-party dependencies.

package/README.md

@@ -1,3 +1,398 @@
-# Temporary Holding Version
+# sub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A personal agentic coding CLI — Claude Code / pi style — backed by the
+[subrouter](https://router.eva.pink) AI router. Streaming chat REPL plus an agent loop
+with **filesystem tools** for creating and organizing projects, reading/editing code,
+searching, copying assets, and recoverable removal, plus **guarded terminal commands**
+for builds, tests, and other requested work. Opt-in auto mode handles recognized routine
+tasks without prompts; destructive or unknown commands still ask in guarded auto.
+A separate warned **absolute mode** permits whole-drive file access and arbitrary
+commands without further approvals.
+
+TypeScript on Node ≥ 24, run straight from source via Node's native type stripping:
+**zero build step, zero runtime dependencies** (only `typescript` + `@types/node` as
+devDependencies for typechecking). macOS only.
+
+## Setup
+
+```bash
+npm install        # devDependencies only (typescript + @types/node)
+npm run typecheck  # tsc --noEmit
+npm test           # node --test — the full suite is offline
+
+# put `sub` on your PATH (no root needed):
+mkdir -p ~/.local/bin
+ln -s "$PWD/scripts/sub-wrapper.sh" ~/.local/bin/sub   # or copy it; chmod +x
+```
+
+The API key comes from `SUBROUTER_API_KEY` or `~/.config/subrouter-cli/config.json`
+(see `config.example.json`). The config file is written chmod 600; keys are never
+printed, logged, or committed — not even masked.
+
+```bash
+sub --check          # connectivity + model catalog diagnostic
+sub                  # the REPL
+sub -p "explain this repo"   # one-shot, non-interactive
+sub --absolute       # entire drive + arbitrary commands; warning and typed ABSOLUTE required
+sub --auto           # guarded auto for files + recognized project tasks
+sub --auto-approve   # file-only auto; every terminal command still asks
+sub --model <id> --debug
+```
+
+## The REPL
+
+- **Terminal UI:** chat scrolls above a bottom-anchored panel, with the selected model
+  on its top divider, the violet `❯` input between dividers, and permission/activity
+  status below. The pi/Claude Code-inspired layout uses Subrouter's periwinkle-blue
+  accent (#8fa7ff) for branding, models, menus, and availability, with violet (#a674ff)
+  for effort and headings. Green ready/success states and amber/red warnings remain,
+  instead of
+  dimming everything. Command menus and views open immediately **below the input**, outside
+  the scrolling conversation. While a command is open, the normal status/usage rows
+  are hidden so only its controls remain. Reasoning text is hidden; answers and
+  in-flow tool activity cards stay in chat. The compact header shows only the
+  working directory. Pipes and very small terminals keep a simple layout; `--no-color`
+  disables styling and animation. Restart `sub` after source changes — existing sessions
+  do not hot-reload.
+- **Panel usage:** the latest turn's input/output tokens and the selected provider's
+  available pool percentages, refreshed every 30s and after turns. Model changes switch
+  the provider filter immediately. A separate account row shows router-reported RPM,
+  daily token usage/limit, and weekly spend/limit. These are shared account quotas, not
+  guessed provider subscription caps. Missing values remain unknown; explicit null limits
+  show unlimited. Usage fetch failures never block chat.
+- **Dynamic slash commands:** type `/` to open a live filtered palette below the input.
+  ↑/↓ selects, Tab completes, Enter runs, and Esc dismisses. `/model` and `/models`
+  open the model picker; `/model <id>` still sets
+  directly and persists the default. `/usage` opens a compact selected-provider report:
+  each pool window appears once with availability/reset time, followed by shared account
+  limits. Large token totals use K/M/B abbreviations. ↑/↓ scrolls, `r` bypasses the 30s
+  cache to refresh, Enter/Esc closes. `/mode` picks `ask`, `files`, guarded `auto`,
+  or warned `absolute`; `/mode auto` switches directly, `/mode absolute` opens the
+  acknowledgement, and `/mode ask` returns to prompting. Modes are session-only.
+  `/clear` resets the visible conversation and starts
+  a fresh transcript; `/exit` quits. Command notices and controls stay below the
+  input; agent answers and tool cards stay in chat. The absolute warning disappears
+  after its acknowledgement closes. Pipes and tiny terminals use plain command output.
+- **Anchored scrolling:** mouse wheel and Page Up/Down scroll conversation history while
+  the input stays fixed, even during a streaming answer. New output does not pull you
+  away from the history you are reading. Scroll down to return live; submitting a new
+  turn also returns live. Open command panels/pickers receive these keys instead.
+  Display history retains the latest 10,000 logical lines; full transcripts stay on disk.
+  Mouse reporting is disabled on exit or when the terminal becomes too small.
+- **Effort:** `/effort` opens a picker for `auto`, `low`, `medium`, `high`, `xhigh`, `max`;
+  `/effort high` sets directly. The choice is shown in the bar and saved as
+  `reasoning_effort`. `sub --effort high` overrides it for this run, including `-p`.
+  `auto` omits an explicit API setting. Chat Completions uses `reasoning_effort`; Messages
+  uses thinking budgets (2,048 / 4,096 / 8,192 / 16,384 / 32,000 tokens), raising total
+  `max_tokens` when necessary to leave at least 4,096 tokens for the answer. Supported
+  levels depend on the model/router; a rejection is reported, not silently downgraded.
+  Signed thinking blocks are retained for tool continuations, never shown in chat.
+- **Live agent cards:** the thinking indicator updates in place in the chat area, above
+  the composer, not in the bottom status strip. It is transient (not transcript/history
+  content), disappears when the answer starts, and stays hidden while viewing older
+  chat. Hidden model reasoning remains hidden. Tool activity updates a card **in the
+  conversation**, rather than pinning it to the composer; file writes/edits show pending
+  code as arguments stream, then update that same card to success/denied/error. Added
+  and removed lines are green/red, without language syntax highlighting. Completed
+  cards remain in chat history, and later replies follow them. Previews do not execute
+  changes: writes follow the selected permission mode.
+- **Image attachments:** **Ctrl+V** reads an image from the macOS clipboard and queues
+  it for your next prompt; your typed draft stays intact. Copy an image, or capture a
+  screenshot directly to the clipboard with **Ctrl+Cmd+Shift+4**, then Ctrl+V in `sub`.
+  **Cmd+V** still handles ordinary terminal text paste. An empty/text-only clipboard
+  produces a notice, not a message to the agent. Clipboard access occurs only on this
+  explicit shortcut, never in the background or via agent tools.
+  Pending filenames appear in the footer. Type your question and Enter, or Enter alone
+  to send an image-only turn. **Ctrl+X** removes pending attachments; `/clear` removes
+  both queued attachments and images already in conversation history. Images stay in
+  history across tool rounds and follow-up questions. Failed requests restore pending
+  attachments for retry. Use an **image-capable model**: router/model support varies,
+  and unsupported images are reported rather than silently dropped.
+  - Up to 4 images per prompt, 10 MiB each, 20 MiB total. Clipboard PNG is preserved;
+    screenshot TIFF is converted to PNG using AppKit. No resizing or HEIC conversion.
+    TIFF input is bounded to 40 MiB / 40 million pixels before PNG conversion.
+  - `sub --image ./shot.png -p "Explain this screenshot"` works in one-shot mode;
+    repeat `--image` for multiple files. Without `-p`, images are queued in the REPL.
+    Local files support PNG, JPEG, WebP, GIF, quoted paths, `~/`, and absolute paths.
+  - No image slash commands or `/help`: type `/` for the remaining command palette.
+    Clipboard images are local snapshots; nothing is uploaded until you submit a prompt.
+    Remote image URLs and Finder file-copy clipboard references are not supported.
+  - Clipboard access uses macOS's built-in `/usr/bin/osascript` with fixed AppKit/JXA
+    code via `execFile` (no shell, packages, native compilation, or temporary image files).
+    Reads time out after 10 seconds and Ctrl+C cancels; failed/cancelled reads keep the
+    queue intact. Shortcuts are disabled during turns, permission prompts, model pickers
+    and usage panels.
+  - UI and Markdown transcripts show filenames/metadata only. Private JSONL transcripts
+    (mode 0600) retain the encoded image bytes, so they can be much larger and include
+    private image content. No clipboard payload is printed to the terminal.
+  - Context warnings use exact Messages token counting when available, otherwise a rough
+    2,048-token allowance per image; actual image tokens vary by model and resolution.
+- **Live typing and steering:** the composer stays editable while the AI streams or
+  runs tools. **Enter** queues your text as steering; muted grey message rows above
+  the composer show what's pending, with the count in the existing footer. The latest
+  three messages are visible (earlier ones are summarized); long rows use an ellipsis.
+  Smaller terminals reduce this preview to preserve chat and the anchored composer.
+  Messages are delivered in order at the next safe model boundary,
+  after all results from an in-flight tool batch. A queued message received during
+  a final answer starts another response in the same turn. It does not interrupt a
+  running request or undo tools already executing — **Ctrl+C** stops the turn.
+  Pending previews update in place and disappear when sent. Applied messages use the
+  ordinary user-message styling, with no “steer:” prefix, and are included in the same
+  active workflow/transcript. Delivering them does not stop or restart the agent or a
+  running terminal command. A provider request already in flight cannot accept new
+  input retroactively; the next continuation receives the messages after tool results.
+  Pending text is display-only.
+  Unsubmitted drafts survive turn completion and temporarily yield to permission
+  questions, then return afterward. Permission answers are not steering. Ctrl+C
+  during approval cancels rather than approving the write. Unapplied steering on
+  cancellation, error or the tool-round cap returns to the editor for an explicit
+  retry; multiple restored messages are joined in order. Slash commands work during
+  a turn: `/usage`, `/model`, `/models`, `/effort`, and `/mode` open their usual controls while
+  the AI continues. Model/effort changes apply to the **next turn**; current requests
+  and tool continuations retain their original settings, and usage/transcripts remain
+  attributed to the active turn's model.
+  Cancelling a command does not cancel the agent. Permission questions take priority
+  over open command controls. `/clear` cancels and awaits the active turn before
+  resetting history/queued steering; `/exit` stops both. Clipboard shortcuts remain
+  idle-only.
+- **Agent loop:** up to 25 tool rounds per turn (`max_tool_rounds` in config).
+  File and terminal approvals appear in a bordered panel above the composer with a
+  separate choice row, not as text in the normal input bar. File changes accept
+  `y` = once, `a` = all file changes (this session), `n` = deny.
+  `--auto-approve` or `"auto_approve": true` skips **file-write** prompts only.
+  `/mode auto` or `--auto` also authorizes recognized routine terminal tasks.
+  Outside acknowledged absolute mode, all other terminal commands show the full
+  command/cwd/timeout and require their own explicit `y`/`yes`; blank, `a`/`all`, EOF
+  and cancellation do not authorize them. Absolute mode skips file/command prompts
+  after its typed warning acknowledgement. `/mode ask` revokes automatic grants;
+  queued auto/absolute commands and absolute file mutations cannot start after
+  revocation. Already-running operations are not interrupted.
+- **Keys:** Enter submits, arrows walk history, Ctrl+C interrupts (aborts a streaming
+  turn), Ctrl+D exits. Multi-line bracketed pastes submit as one turn. The model picker
+  navigates with ↑/↓ (or `j`/`k`), confirms with Enter, cancels with Esc or Ctrl+C.
+- **Markdown:** answers render as markdown — `**bold**`, `` `code` ``, fenced code
+  blocks (periwinkle blue), `#` headings, list markers, and `[links](url)` (URL dropped). Italic is
+  intentionally unsupported (`*`/`_` collide with identifiers). Transcripts keep the raw
+  markdown; styling is display-only. Partial prose, bold/code spans, and code-block
+  content appear as chunks arrive, without waiting for a newline or Ctrl+C. Only
+  ambiguous Markdown prefixes/links use bounded lookahead. Streamed replies discard
+  oversized leading/trailing blank gaps and use one blank line between prose paragraphs;
+  code-block whitespace is preserved.
+- **Sessions:** every turn appends to `~/.config/subrouter-cli/sessions/` — a
+  markdown log plus a JSONL transcript (shaped for a future `--resume`).
+- Model IDs auto-route to the right wire dialect: `anthropic/*` speaks the Messages
+  API; everything else speaks Chat Completions. Bare `claude-*` and
+  `gpt-*`/`grok-*`/`deepseek-*` also work; other bare IDs ask for the full
+  provider-prefixed ID from `/models`.
+
+## Tool policy
+
+Tools are available in the interactive agent REPL. Launch `sub` from the folder you
+want it to work in. In `ask`, `files`, and guarded `auto`, **filesystem-tool paths**
+are relative to that folder and confined there: absolute paths, `~`, parent-directory
+escapes, and symlink escapes are refused. In acknowledged `absolute`, tools can use
+absolute paths, `~/`, parent paths and external symlink parents across the drive,
+wherever your current macOS account has permission. Terminal commands are separately
+authorized (explicitly, by guarded auto, or by acknowledged absolute mode) and are
+**not sandboxed**. Their starting directory is validated, but their effects can extend
+to other files on your PC and the network. One-shot `-p` is still chat-only.
+
+| Tool | What it does | Approval |
+| --- | --- | --- |
+| `read_file` | Read a text file, up to 256 KiB | No |
+| `read_files` | Read 1–20 text files with per-file errors and a shared 256 KiB content budget | No |
+| `file_info` | Inspect type, size, permissions and modification time; no file content | No |
+| `list_dir` | List up to 500 directory entries | No |
+| `find_files` | Find paths by literal substring, optionally files/directories only | No |
+| `grep` | Search text content by literal substring | No |
+| `write_file` | Create/overwrite text, including missing parents, up to 1 MiB | Yes |
+| `edit_file` | Replace a nonempty, unique exact match; resulting file up to 1 MiB | Yes |
+| `make_dir` | Create folders and missing parents | Yes |
+| `copy_path` | Copy a file (including binary assets) or directory tree | Yes |
+| `move_path` | Move/rename a file or directory | Yes |
+| `remove_path` | Move a file/directory into private project recovery storage | Yes |
+| `list_removed` | List recovery IDs, original paths and removal times | No |
+| `restore_file` | Restore by recovery ID, optionally to a new destination | Yes |
+| `run_command` | Noninteractive terminal command with bounded output/time | Explicit yes, guarded auto for recognized tasks, or acknowledged absolute |
+
+File mutations marked Yes ask in `ask` mode and run automatically in `files`/`auto`/`absolute`.
+Neither file approve-all nor `--auto-approve` grants terminal authorization.
+
+`copy_path`, `move_path`, and `restore_file` **never overwrite an existing destination**.
+Copy/move/remove/restore preflight trees with a 5,000-entry / 100 MiB limit. Tree
+operations reject symlinks and special files rather than silently omitting entries.
+Outside absolute mode they also reject `.git` internals and recovery storage;
+mutations reject symlink paths (even links staying inside the project), the working
+directory itself, and `.git` internals. Absolute lifts those project/protected-name
+path guards, but write/edit still refuse final symlinks and non-regular files, and
+tree operations still refuse symlink entries. Text tools reject NUL-containing binary
+files. Write/edit may overwrite according to the selected permission mode; read before
+changing an existing file.
+
+`find_files` caps at 500 results / 5,000 inspected entries; `grep` caps at 200 results /
+5,000 files. Both skip symlinks, `.git`, `.sub-recovery`, dependencies and common build
+directories during recursion. Find patterns are literal, not globs or regular expressions.
+Mutations from concurrent tool batches are serialized per project in this process.
+Confinement is a path guard, not an OS sandbox against another process changing the
+filesystem concurrently; avoid moving project folders or changing symlinks mid-operation.
+
+Removed items live in `.sub-recovery/` inside the working folder (directory mode 0700,
+metadata mode 0600), survive CLI restarts, and are **not automatically purged**. A local
+ignore-all `.gitignore` is created in the recovery folder to reduce accidental commits;
+other upload/backup tools may still include it. Recovery
+is project-local, not Finder Trash or a backup of overwritten files. Outside absolute
+mode the agent cannot read or modify that storage directly; it uses `list_removed`
+and `restore_file`. Absolute mode can access the storage directly and removed external
+items are kept here too; restoring their external original paths requires absolute
+mode. Treat the folder as private data: do not commit, upload, or delete it if recovery
+is needed.
+Recovery items remain until restored or you manually manage the storage. These file-tool
+protections are not an OS sandbox: an approved terminal command can access or delete
+recovery data too.
+
+### Terminal commands
+
+`run_command(command, cwd?, timeout_ms?)` uses macOS `/bin/zsh -f -c`, with ignored
+stdin and piped stdout/stderr, not an interactive terminal. `cwd` must be an existing
+project directory (default project root), except absolute mode also permits existing
+directories elsewhere on the drive. The default timeout is 60 seconds, maximum
+5 minutes; commands are limited to 16 KiB and captured output to a combined 64 KiB.
+Overflow terminates the command and reports truncation, not unlimited collection.
+Results include status, exit code/signal, stdout/stderr and truncation; failure is
+reported faithfully. The live card shows lifecycle only, not raw command output.
+
+In ask/file-only mode, every command gets a separate approval. Guarded auto skips this
+question only for recognized routine tasks; acknowledged absolute mode skips it for
+arbitrary commands. When a command needs approval, its full text,
+canonical cwd and effective timeout appear in chat before the anchored yes/no question;
+control/invisible characters and backslashes are escaped visibly rather than executed
+by the terminal. Known router-key-bearing commands are rejected before display.
+Commands use a minimal environment allowlist (standard path/home/user/temp/locale
+variables, `TERM=dumb`), not ambient credential variables. Known router credentials
+are redacted from captured output before model/history/transcript use. This is not
+comprehensive secret isolation: commands can still read local configuration or make
+network requests. Review what you approve. `/bin/zsh -f` disables ordinary user rc
+loading; it does not isolate system startup behavior.
+
+### Guarded auto
+
+Enable with `sub --auto`, `/mode auto`, or the `/mode` picker. It is opt-in for this
+session, never saved as a default. `files` mode and legacy `auto_approve` remain file-only;
+`--auto`, `--auto-approve`, and `--absolute` are mutually exclusive.
+
+Recognized examples include `pwd`, `node --test`,
+`node --test --test-concurrency=2 --test-reporter=dot`, `tsc --noEmit`, `tsc --build`,
+`vite build`, `eslint src --max-warnings=0`, and guarded Git inspection such as
+`git --no-pager status --short` or
+`git --no-pager diff --no-ext-diff --no-textconv --stat`.
+`npm test` and `npm run build|test|lint|typecheck|check` qualify only when the current
+folder's bounded, regular `package.json` contains recognized script bodies and pre/post
+lifecycle hooks. Nested tasks are checked with recursion/work limits; changed scripts
+are rechecked when queued execution begins. Missing or opaque scripts ask.
+
+The parser accepts a narrow literal/quoted-word syntax and `&&` only when every part
+qualifies. Unknown flags/commands, shell substitutions, redirections, pipes, wrappers,
+interpreters/eval, installs/downloads, `sudo`, shell deletion (including `rm -rf`), disk
+operations, and destructive Git operations **never run automatically in guarded auto**.
+They require explicit approval once outside absolute mode; the agent should prefer
+recoverable file tools for removal.
+This is intentionally more conservative than an “anything except rm” blacklist.
+
+**Auto assumes a trusted project and toolchain.** Tests, builds, plugins, executable
+resolution and tool configuration can execute arbitrary code, including code with
+side effects. Recognizing a command is not proof that it is harmless, and this is not
+an OS sandbox. Do not enable auto in an untrusted repository. There is still an external
+filesystem race between validation and execution; command text inspection cannot
+provide isolation. Turning auto off revokes queued auto grants, including after turning
+it on again, but does not interrupt work already running.
+
+### Absolute permissions
+
+Enable with `sub --absolute`, `/mode absolute`, or the `/mode` picker. A prominent
+warning explains the whole-drive scope and possibility of permanent deletion,
+overwrites, downloaded code and network access. Type **`ABSOLUTE`** to acknowledge;
+blank, any other answer, Esc, Ctrl+C or EOF cancels. Selecting the picker entry alone
+does not enable it. The warning and typed acknowledgement leave the visible chat
+once the prompt closes; the persistent mode badge remains. CLI startup stays in ask
+mode until acknowledged; a cancelled in-session request retains the previous mode. An interactive terminal is required;
+`--absolute` is rejected with `-p`, `--check`, or piped input/output.
+
+**After acknowledgement there are no file/command approval prompts or guarded-auto
+command filtering.** File tools can read/change paths across the drive, including
+absolute paths and `~/`, and commands may start outside the project. A persistent red
+`ABSOLUTE — NO APPROVALS` badge stays visible while the agent works and command controls
+are open. Use only when you trust the task and the files/code the agent will encounter.
+
+This is current-account access, **not automatic root/sudo or a bypass of macOS privacy
+permissions**. No interactive password entry is provided. Tool byte/tree limits,
+regular-file and symlink-tree rules, no-overwrite copy/move/restore, recoverable
+`remove_path`, bounded command output/time and cancellation remain. Commands can still
+perform permanent deletion. Known router credentials are rejected in commands and
+redacted from command output and absolute file-tool results/errors before history;
+this is not comprehensive secret isolation or a network sandbox.
+
+Absolute is session-only, never saved or enabled by `auto_approve`. `/mode ask` disables
+it; queued absolute commands/mutations recheck their mode generation before executing.
+Turning it back on cannot revive old grants. Work already running is not interrupted;
+use Ctrl+C to stop the active turn.
+
+### Command cancellation
+
+Ctrl+C, `/clear`, `/exit`, timeout and output overflow terminate the process group,
+with TERM→KILL escalation. Normal shell completion also cleans up ordinary background
+descendants. There is no persistent-background-job or interactive-input API; programs
+requiring a TTY or password entry may fail. Descendants that detach into another
+process group/session can escape cleanup; no sandbox guarantee is made. Commands
+serialize with project mutations in this process and recheck cancellation before
+queued execution starts. Tool results remain paired with calls after cancellation,
+so continuing the conversation does not send broken tool history.
+
+For example: “Create a small website in `site/`, copy my assets into it, and run its
+tests.” In ask mode, the agent creates the structure with approval and asks before
+running tests. In guarded auto, recognized tasks can proceed without those prompts.
+Package installs and downloads are now possible through approved commands, not
+silently performed through filesystem tools.
+
+## Development
+
+```
+src/index.ts       entry, flags, bootstrap      test/            node:test suites
+src/client.ts      RouterClient (HTTP, retry)   scripts/         SSE harness (live)
+src/adapters/      openai.ts, anthropic.ts
+src/tools.ts       file tools + confinement     src/loop.ts      agent round driver
+src/repl.ts        REPL shell                   src/lineinput.ts raw-mode editor
+src/sessions.ts    transcripts                  src/usage.ts     /usage render
+src/markdown.ts    terminal markdown renderer
+```
+
+Live wire-shape verification:
+
+```bash
+node scripts/sse-harness.ts --model <id> --dialect openai|anthropic|auto [--tools] [--save test/fixtures/x.sse]
+```
+
+## Manual E2E checklist
+
+- [ ] `sub --check` green; `npm test` green; `npm run typecheck` clean
+- [ ] `/model` → arrow-key picker → streamed chat answers (markdown-rendered)
+- [ ] multi-tool task (create → edit → grep) exercising y / a / n approvals
+- [ ] `/usage` shows compact provider/account limits without duplicate footer rows
+- [ ] mouse wheel / Page Up/Down scroll chat with input anchored, including mid-stream
+- [ ] Ctrl+V queues a clipboard screenshot without submitting; Ctrl+X clears pending images
+- [ ] text Cmd+V still works; `/` palette has no image commands or `/help`
+- [ ] `/clear` starts a fresh transcript; session files exist
+- [ ] type during streaming; Enter queues steering and leaves tool/result ordering valid
+- [ ] an unfinished draft survives a permission question and turn completion
+- [ ] Ctrl+C mid-stream prints `*[stopped]*` and restores any unapplied steering
+- [ ] `sub -p "hi"` one-shot; `echo "…" | sub` piped mode works
+- [ ] bad key exits with the 401 hint; `SUBROUTER_BASE_URL` pointing at a dead port
+      reports healthz FAILED
+- [ ] `sub --debug` shows raw SSE frames with credentials redacted
+
+## Notes
+
+- **Zero runtime deps** — `src/` and `scripts/` use Node built-ins only.
+- **Never print an API key** — not even masked. Real keys live in the config file or
+  the env var.
+- Message content is written only to session transcripts under `~/.config/…/sessions/`,
+  never to stdout/stderr (except `--debug`, which dumps raw SSE frames on request).

package/config.example.json

@@ -0,0 +1,9 @@
+{
+  "base_url": "https://router.eva.pink/v1",
+  "api_key": "sk-sub-your-key-here",
+  "default_model": null,
+  "reasoning_effort": "auto",
+  "max_output_tokens": 8192,
+  "max_tool_rounds": 25,
+  "auto_approve": false
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "subrouter-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "sub — a personal agentic coding CLI for the subrouter AI router",
+  "type": "module",
+  "bin": {
+    "sub": "src/index.ts"
+  },
+  "scripts": {
+    "start": "node src/index.ts",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "harness": "node scripts/sse-harness.ts"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5.8"
+  }
+}