shadok-ai 0.1.148 → 0.1.149

package/README.md

@@ -3,7 +3,8 @@
 A **web cockpit that drives multiple real Claude Code sessions in parallel** —
 each channel is one `claude` process, on your Claude subscription (not the API).
 Pilot them from a browser **and** from **Telegram** (one topic = one agent),
-with git-worktree isolation, per-repo secrets, a diff panel, and quota gauges.
+with git-worktree isolation, agent profiles, a secret vault, a diff panel, and
+quota gauges.
 
 ## Quick start
 
@@ -15,25 +16,83 @@ Then open **http://localhost:3789**.
 
 **Prerequisites:** Node ≥ 20 and the [`claude`](https://claude.com/claude-code)
 CLI installed and signed in on the machine (shadok-ai drives your existing
-Claude Code, on your subscription).
+Claude Code, on your subscription). `tmux` is optional but recommended — with
+it, agents survive the server restarting.
 
-On the first run it asks once for an optional **Telegram bot token** (press Enter
-to skip; you can add it later). Flags: `--port <n>`, `--no-telegram`,
-`--version`.
+On the first run it asks once for an optional **Telegram bot token** (press
+Enter to skip; you can add it later from the web UI).
+
+| Flag | Effect |
+|---|---|
+| `--port, -p <n>` | HTTP/WS port (default 3789; falls back to the next free one) |
+| `--no-telegram` | web-only; don't prompt for or use a bot token |
+| `--password <p>` | require this password to open the GUI (stored in config) |
+| `--version, -v` · `--help, -h` | version / help |
+
+## What you get
+
+- **Channels** — one `claude` process each, running in parallel. Renaming,
+  grouping, and closing all sync live between the browser and Telegram: it's
+  one list, server-owned, not two copies.
+- **Worktree isolation** — spawned agents get their own git worktree and branch
+  by default, so parallel agents never collide. Work is never auto-discarded:
+  an empty worktree is reclaimed on close, anything with changes or commits
+  stays (and `Recover` reopens it).
+- **Interactive dialogs** — the TUI's permission prompts and multiple-choice
+  questions become clickable buttons in the chat, and an inline keyboard in
+  Telegram.
+- **Agent profiles** — a named bundle of role prompt, permission guardrails
+  (e.g. forbid `git commit`), model, and which secrets to inject. Applied at
+  spawn, remembered across resume.
+- **Secret vault** — stored under `~/.shadok-ai`, never in your repo, injected
+  as env vars into the agents that need them.
+- **Quota gauges + pace guard** — 5h and 7d subscription usage, with an
+  optional block when you're burning faster than the window elapses (any
+  message can force through).
+- **Engine room** — the raw TUI screen, live, with clickable keys, for anything
+  the chat can't express.
+- **Diff panel** — what an agent actually changed, against its base.
+- **Self-update** — polls npm and can update and reload itself in place.
 
 ### Telegram (optional)
 
 Add your bot to a group with **Topics** enabled, make it an admin with *Manage
-topics* (and *Delete messages* for `/secret` scrubbing), then in the group:
+topics* (and *Delete messages* so `/secret` can scrub values), then in the group:
 
-- `/setup` — bind this group as the board (one group per instance)
-- `/spawn <name>` — a new isolated agent in its own topic (also appears as a web tab)
-- `/secrets` · `/secret KEY value` · `/unsecret KEY` — per-repo env secrets
-- `/update` — fetch `@latest` and respawn (self-update)
-- `/list` · `/new` · `/end`
-
-Web tabs and Telegram topics are **one list** — spawn, rename, and close sync
-both ways, live.
+| Command | |
+|---|---|
+| `/setup` | bind this group as the board (one group per instance) |
+| `/spawn [profile] <name>` | new isolated agent in its own topic (also a web tab) |
+| `/stop` (alias `/esc`) | interrupt the current turn — does **not** end the session |
+| `/new` · `/end` | reset · kill the session |
+| `/restart` | respawn the agent in place (e.g. to pick up new secrets) |
+| `/profiles` · `/list` | list profiles · list bindings |
+| `/secrets` · `/secret KEY value` · `/unsecret KEY` | the secret vault |
+| `/update` | fetch `@latest` and respawn |
+
+Creating a topic by hand also spawns an agent. Anything that isn't a command is
+sent to that topic's agent as a prompt — including photos and files, which are
+downloaded and handed to Claude Code.
+
+### Configuration
+
+Config lives in `~/.shadok-ai/config.json` (mode 600) and is **authoritative
+over the environment once set** from the GUI. The Telegram token, allowed
+chats, and the bridge on/off switch are **per launch directory** — running the
+server from another repo gives you a different cockpit and a different bot.
+
+| Env var | |
+|---|---|
+| `PORT` | HTTP/WS port |
+| `SHADOK_GUI_PASSWORD` | require a password for the GUI |
+| `SHADOK_TMUX=0` | force the node-pty transport instead of tmux |
+| `SHADOK_IDLE_MIN` | minutes with no client before a session is reclaimed (60) |
+| `SHADOK_PERMISSION_MODE` | mode new agents start in (default `acceptEdits`) |
+| `SHADOK_AUTOUPDATE` | fallback only — the GUI setting wins once used |
+| `SHADOK_PILOT_PROMPT=0` | don't inject the cockpit system prompt |
+| `SHADOK_RESUME_SUMMARY=1` | don't auto-answer the resume-from-summary prompt |
+| `TELEGRAM_BOT_TOKEN` · `TELEGRAM_ALLOWED_CHATS` | override the stored config |
+| `CLAUDE_CODE_OAUTH_TOKEN` | only for the usage gauges; `claude` itself uses the keychain |
 
 ---
 
@@ -42,7 +101,8 @@ both ways, live.
 
 ## How it works
 
-Drives the **Claude Code TUI** (the interactive `claude` CLI) through a pseudo-terminal.
+Drives the **Claude Code TUI** (the interactive `claude` CLI) through a real
+terminal, and reads the answers from Claude Code's own transcript.
 
 > ⚠️ The Claude Code TUI is not a stable API: a CLI update can break the
 > detection heuristics (`❯`, `⏺`, `esc to interrupt` markers).
@@ -50,31 +110,50 @@ Drives the **Claude Code TUI** (the interactive `claude` CLI) through a pseudo-t
 > [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
 > or `claude -p --output-format stream-json`.
 
-- **node-pty** spawns `claude` inside a real pseudo-terminal (the TUI believes it talks to a human);
-- **@xterm/headless** replays the ANSI stream into a virtual screen: we read
-  the screen as it would be displayed instead of parsing escape sequences;
-- the **responses to terminal queries** (cursor position `\x1b[?6n`,
-  identification `\x1b[c`…) generated by xterm are forwarded back to the
-  PTY — without this, the TUI ignores every keystroke;
-- prompts are sent via **bracketed paste** (`\x1b[200~…\x1b[201~`) with
-  retries, because the TUI flushes stdin received during its initialization;
-- the "Claude is done" state is detected heuristically: no
-  `esc to interrupt` marker + screen stable for N ms.
+Two transports, same interface:
+
+- **tmux (default when installed)** — `claude` runs in a detached tmux session,
+  so it survives the server restarting or crashing and is reattached on the
+  next start. tmux answers terminal queries itself, which removes a whole class
+  of PTY hacks. It does not survive a machine reboot.
+- **node-pty** — `claude` runs as a child of the server inside a pseudo-terminal
+  (the TUI believes it talks to a human), with **@xterm/headless** replaying the
+  ANSI stream into a virtual screen we can read. Terminal query responses
+  (cursor position `\x1b[?6n`, identification `\x1b[c`…) must be forwarded back
+  to the PTY, or the TUI ignores every keystroke. Dies with the server.
+
+In both cases prompts are sent via **bracketed paste** with retries (the TUI
+flushes stdin received during initialization), and "Claude is done" is detected
+heuristically: no `esc to interrupt` marker + screen stable for N ms.
+
+**Responses are not scraped from the screen.** Claude Code writes every turn to
+a `.jsonl` transcript; that file is the source of truth for chat content, which
+is what makes long answers reliable. The screen is used only for control —
+submitting, detecting the end of a turn, reading dialogs, and mirroring the raw
+TUI in the engine room.
 
-## Install
+## Build & test
 
 ```bash
 npm install
-npm run build
+npm run build      # tsc → dist/
+npm test
+npm run web        # run the server directly (no supervisor, no auto-update)
 ```
 
 The `postinstall` script fixes the executable bit of node-pty's
 `spawn-helper` (a known npm prebuilds bug on macOS).
 
-## CLI
+Note that `npx shadok-ai` does **not** run your working tree: it runs a
+supervisor that manages an auto-updating npm-installed copy. To test a local
+build, see "Running YOUR build" in [`CLAUDE.md`](CLAUDE.md).
+
+## One-shot CLI
+
+Separate from the cockpit: run a single prompt and print the answer.
 
 ```bash
-node dist/cli.js [options] "<prompt>"
+shadok-ai-run [options] "<prompt>"      # or: node dist/cli.js …
 
   --cwd <dir>       working directory of the claude session
   --continue, -c    resume the latest session of this directory
@@ -84,94 +163,67 @@ node dist/cli.js [options] "<prompt>"
   --timeout <sec>   max wait for the response (default 600)
 ```
 
-Without `--continue`/`--resume`, every run starts a **new** session.
-The session id is printed at the end of the run (found in
+Without `--continue`/`--resume`, every run starts a **new** session. The
+session id is printed at the end of the run (found in
 `~/.claude/projects/<encoded cwd>/`, like any Claude Code session):
 
 ```bash
-node dist/cli.js --cwd ~/my-project "Explain this project's structure"
+shadok-ai-run --cwd ~/my-project "Explain this project's structure"
 # ▶ session: 5fe046dd-…
 
-node dist/cli.js --cwd ~/my-project --resume 5fe046dd-… "Now refactor it"
-node dist/cli.js --cwd ~/my-project -c "Continue on the latest session"
+shadok-ai-run --cwd ~/my-project --resume 5fe046dd-… "Now refactor it"
+shadok-ai-run --cwd ~/my-project -c "Continue on the latest session"
 ```
 
-## Web interface
-
-```bash
-npm run web        # http://localhost:3789  (PORT=… to change)
-```
-
-A chat in the browser driving persistent TUI sessions, in parallel through
-channels:
-
-- **channels** (left column): "＋ new channel" opens a new independent
-  claude session (one WebSocket connection each). Each channel's LED shows
-  its state (green: ready, amber: responding, red: ended); the × closes the
-  channel and detaches from its session; double-click a name to rename it
-  (the name is remembered by session id and reapplied on resume). The
-  header, composer and Terminal view follow the active channel. Channels
-  are remembered (localStorage): on the next page load each one is restored
-  automatically — session resumed via `--resume` and history replayed.
-  Closing a channel (×) removes it from the remembered list;
-- **interactive dialogs**: when the TUI shows a choice (multiple-choice
-  question, permission prompt…), the options appear as clickable buttons in
-  the chat. Single select: one click validates. Multi-select (`[ ]`
-  checkboxes in the TUI): clicks toggle (the displayed state is re-read
-  from the TUI screen), then "Submit selection" confirms (Tab → Submit page
-  → Enter). The composer is locked while a choice is pending. The
-  "Type something" option becomes a free-form text input inside the dialog
-  bubble;
-- **history on resume**: when resuming a session (`--continue` or
-  `--resume`), the transcript is re-read from the session's `.jsonl` and
-  replayed in the chat (last 100 turns, dimmed). The markdown of the
-  responses is rendered as HTML (tables, code, lists) via `marked`, served
-  locally;
-- **"engine room"** (Terminal button): the raw TUI screen live, with
-  clickable keys (Esc, Enter, arrows, 1/2/3, y/n…) to answer permission
-  dialogs, and "Resync chat" to resynchronize the chat after a manual
-  intervention.
-
-### WebSocket protocol (to replace the interface)
+## WebSocket protocol (to replace the interface)
 
 The interface is a plain static page: all the intelligence lives server-side.
-Any client (another front-end, a Slack bot, a script…) can replace it by
-speaking this JSON protocol on `ws://…/ws`.
+Any client (another front-end, a bot, a script…) can replace it by speaking
+this JSON protocol on `ws://…/ws`. The built-in Telegram bridge *is* such a
+client — it connects to the same server over loopback.
 
-**Shared sessions**: the server keeps a single claude process per session
-id. If several clients (tabs, browsers, interfaces) "start" the same id,
-they attach to the same process and all receive the same events — other
-clients' prompts (`prompt-echo`), answers, dialogs, screen. Closing a
-connection detaches the client; the process is only stopped when the last
-client detaches (session stays resumable) or on an explicit `stop` (ends it
-for everyone).
+**Shared sessions**: the server keeps a single claude process per session id.
+If several clients (tabs, browsers, interfaces) `start` the same id, they
+attach to the same process and all receive the same events — other clients'
+prompts (`prompt-echo`), answers, dialogs, screen. Closing a connection
+detaches the client; the session is reclaimed after `SHADOK_IDLE_MIN` with no
+client, or immediately on an explicit `stop` (which ends it for everyone).
 
 **client → server**
 
 | Message | Purpose |
 |---|---|
-| `{type:"start", cwd?, resume?, continue?}` | starts or attaches to the session (once per connection) |
-| `{type:"prompt", text}` | sends a prompt |
+| `{type:"start", cwd?, resume?, continue?, worktree?, branch?, repo?, profile?}` | starts or attaches to the session (once per connection) |
+| `{type:"prompt", text, force?}` | sends a prompt (`force` bypasses the pace guard) |
 | `{type:"choose", n}` | single-select dialog: picks and validates option n |
-| `{type:"toggle", n}` | multi-select dialog: toggles option n |
-| `{type:"confirm"}` | multi-select dialog: submits the selection |
+| `{type:"toggle", n}` / `{type:"confirm"}` | multi-select: toggles option n / submits |
 | `{type:"freetext", n, text}` | "Type something" option: sends a free-form answer |
 | `{type:"key", key}` | raw keystroke (`enter`, `escape`, `up`, `down`, `tab`, `ctrl-c`, or a single character) |
 | `{type:"settle"}` | after a manual intervention: waits for the turn to finish |
-| `{type:"stop"}` | closes the session cleanly (/exit) for all clients |
+| `{type:"restart"}` | respawns the agent in place (picks up new secrets/profile) |
+| `{type:"stop", sessionId?}` | ends the session for all clients; `sessionId` targets another channel (zombie cleanup) |
 
 **server → client**
 
 | Message | Purpose |
 |---|---|
 | `{type:"ready", sessionId, cwd}` | session started (or attached) |
-| `{type:"working"}` | turn in progress |
+| `{type:"working"}` / `{type:"turn-done", sessionId}` | turn started / finished |
+| `{type:"stream-text", text}` | a complete assistant text block, from the transcript |
+| `{type:"stream-tool", id, name, summary}` / `{type:"stream-result", …}` | tool call / tool result |
+| `{type:"tokens", tokens}` / `{type:"context", pct}` | token usage / context fill |
 | `{type:"prompt-echo", text}` | prompt sent by another client of the session |
-| `{type:"answer", text, sessionId}` | response extracted from the transcript |
 | `{type:"dialog", question, options:[{n,label,hint,checked?}], multi}` | choice pending |
-| `{type:"history", turns:[{role,text}]}` | transcript replayed when resuming/attaching |
+| `{type:"history", turns:[…]}` | transcript replayed when resuming/attaching |
 | `{type:"screen", text, working}` | rendered TUI screen (whenever it changes) |
-| `{type:"error", message}` / `{type:"exited", code}` / `{type:"stopped"}` | errors and termination |
+| `{type:"pace-blocked"}` / `{type:"pace-hold"}` / `{type:"pace-resumed"}` | quota guardrail |
+| `{type:"auto-retry"}` / `-cancelled` / `-gave-up` | transient API error being retried |
+| `{type:"version", …}` / `{type:"server-reload", version}` | update available / server updated, reload |
+| `{type:"gone"}` / `{type:"error", message}` / `{type:"exited", code}` / `{type:"stopped"}` | session lost, errors, termination |
+
+HTTP endpoints (same auth): `/usage`, `/live`, `/sessions`, `/recover`,
+`/diff`, `/channels`, `/groups`, `/profiles`, `/secrets`, `/telegram`,
+`/defaults`, `/version`, `/autoupdate`, `/permission-mode`.
 
 ## Library
 
@@ -205,13 +257,18 @@ Main API:
 | `isWorking()` | true while Claude is working |
 | `onData(cb)` / `onExit(cb)` | raw ANSI stream (mirror mode) / process exit |
 
-`examples/two-turns.mjs` shows a two-turn conversation;
+`TmuxPilot` exposes the same surface and additionally survives a server
+restart. `examples/two-turns.mjs` shows a two-turn conversation;
 `debug/probe.mjs` logs the terminal sequences exchanged (useful when a CLI
 update breaks the detection).
 
 ## Known limits
 
 - Every session launched consumes your Claude quota like a normal session.
+- Profile guardrails are **soft**: agents run as the same OS user. It prevents
+  misfires, it is not a sandbox.
+- Agent worktrees are branched at spawn and never rebased, so a long-running
+  agent drifts from a moving main branch.
 - Dialogs the chat cannot handle in one click are managed through the
   engine room (`waitFor()` + `press()` in library mode).
 - The TUI runs in the alternate screen: `fullBuffer()` ≈ visible screen;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadok-ai",
-  "version": "0.1.148",
+  "version": "0.1.149",
   "main": "dist/session.js",
   "scripts": {
     "test": "node --import tsx --test test/*.ts .claude/skills/shadok-ai-agents/test/*.test.mjs",