shadok-ai 0.1.201 → 0.1.202

package/README.md

@@ -3,8 +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, agent profiles, a secret vault, a diff panel, and
-quota gauges.
+with git-worktree isolation, agent profiles, a secret vault, a diff panel,
+scheduled prompts, and quota gauges.
 
 ## Quick start
 
@@ -46,11 +46,22 @@ Enter to skip; you can add it later from the web UI).
   spawn, remembered across resume.
 - **Secret vault** — stored under `~/.shadok-ai`, never in your repo, injected
   as env vars into the agents that need them.
+- **Scheduled prompts** — give a channel a recurring prompt (every N minutes, or
+  daily at HH:MM in a time zone you choose) for monitoring and reporting. Each
+  schedule can carry a **deterministic guard command** that runs *without the
+  model*: prints nothing → nothing to report, the agent is never woken and the
+  run costs **zero tokens**; prints something → that output is prepended to the
+  prompt and the agent runs. A watcher that is quiet most of the day costs
+  nothing most of the day.
 - **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).
+- **Notifications** — favicon, title badge and an optional sound when an agent
+  needs you. It only blinks when the tab is hidden *and* an unmuted channel is
+  actually waiting.
 - **Engine room** — the raw TUI screen, live, with clickable keys, for anything
-  the chat can't express.
+  the chat can't express. With tmux there is also an **experimental real
+  terminal** (xterm.js over the pane's byte stream) when a snapshot isn't enough.
 - **Diff panel** — what an agent actually changed, against its base.
 - **Self-update** — polls npm and can update and reload itself in place.
 
@@ -67,6 +78,8 @@ topics* (and *Delete messages* so `/secret` can scrub values), then in the group
 | `/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 |
+| `/cron every 30m <prompt>` · `/cron daily 09:00 <prompt>` | schedule a recurring prompt on this agent |
+| `/cron list` · `/cron on\|off\|del <id>` | manage them (`<id>` accepts the printed 8-char prefix) |
 | `/secrets` · `/secret KEY value` · `/unsecret KEY` | the secret vault |
 | `/update` | fetch `@latest` and respawn |
 
@@ -74,6 +87,12 @@ 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.
 
+**Direct messages belong to one person.** The first user to DM the bot claims it;
+everyone else is refused. On startup the owner is adopted from an existing DM or
+from the board group's creator, so an instance that already has an owner never
+hands itself to whoever messages next — a bot username is public, and a DM is a
+shell.
+
 ### Exposing it beyond this machine
 
 The cockpit runs arbitrary commands on the host by design, so it binds
@@ -99,7 +118,12 @@ origin in `SHADOK_ORIGINS`.
 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.
+server from another repo gives you a different cockpit and a different bot. So
+are the channel list and the scheduled prompts.
+
+`timezone` (an IANA name like `Europe/Paris`, settable via `/timezone`) is the
+default zone for reading a `daily` schedule. Without it the hour follows the
+machine, which silently shifts every daily prompt on a server running in UTC.
 
 | Env var | |
 |---|---|
@@ -121,6 +145,34 @@ server from another repo gives you a different cockpit and a different bot.
 > **Hacking on shadok-ai?** Read [`CLAUDE.md`](CLAUDE.md) (map, build/run,
 > invariants) and [`docs/architecture.md`](docs/architecture.md) first.
 
+### Keeping the docs honest
+
+Three documents, three jobs — and **they ship with the change that makes them
+wrong**, not in a catch-up pass afterwards:
+
+| Document | Holds | Update it when |
+|---|---|---|
+| `README.md` | what shadok-ai does and how to drive it | a user-visible feature, flag, command, endpoint or protocol message changes |
+| `CLAUDE.md` | the file→responsibility map, the build/run recipe, the invariants | you add a module, or you lose an afternoon to something the next person would lose it to as well |
+| `docs/architecture.md` | how a subsystem actually works and why it was built that way | you add or reshape a subsystem, or you make a design trade-off worth remembering |
+| `docs/superpowers/specs/` | one design per feature, dated | before building anything non-trivial |
+
+This is not bookkeeping. A doc that lags is worse than no doc: it is confidently
+wrong, and it is read as current. `docs/architecture.md` once went **48 commits**
+without an update, and by then it was missing entire subsystems while its line
+references pointed at code that had moved hundreds of lines — a reader in that
+window gets misled, not merely under-informed.
+
+Two habits that keep it cheap:
+
+- **Cite symbols, not just line numbers.** `finishTurn` survives a refactor;
+  `server.ts:781` does not. Where a line number helps, say which commit it was
+  read at.
+- **Write the *why*, not the *what*.** The what is in the diff. What the diff
+  cannot say is which alternative you rejected and what it cost you to find out —
+  that is the whole value of `architecture.md`, and the reason the invariants
+  list reads like a scar tissue map.
+
 ## How it works
 
 Drives the **Claude Code TUI** (the interactive `claude` CLI) through a real
@@ -215,7 +267,7 @@ client, or immediately on an explicit `stop` (which ends it for everyone).
 
 | Message | Purpose |
 |---|---|
-| `{type:"start", cwd?, resume?, continue?, worktree?, branch?, repo?, profile?}` | starts or attaches to the session (once per connection) |
+| `{type:"start", cwd?, resume?, continue?, worktree?, branch?, repo?, profile?, origin?}` | starts or attaches to the session (once per connection). `origin` (`"web"`, `"cron"`, `"telegram"`, `"cli"`…) travels with `prompt-echo` so other clients can say who spoke |
 | `{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}` / `{type:"confirm"}` | multi-select: toggles option n / submits |
@@ -223,6 +275,8 @@ client, or immediately on an explicit `stop` (which ends it for everyone).
 | `{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:"restart"}` | respawns the agent in place (picks up new secrets/profile) |
+| `{type:"term-attach"}` · `{type:"term-detach"}` | **experimental, tmux only** — open/close the pane's raw byte pipe |
+| `{type:"term-input", data}` · `{type:"term-resize", cols, rows}` | raw input (base64) / match the pane to the viewport |
 | `{type:"stop", sessionId?}` | ends the session for all clients; `sessionId` targets another channel (zombie cleanup) |
 
 **server → client**
@@ -231,7 +285,7 @@ client, or immediately on an explicit `stop` (which ends it for everyone).
 |---|---|
 | `{type:"ready", sessionId, cwd}` | session started (or attached) |
 | `{type:"working"}` / `{type:"turn-done", sessionId}` | turn started / finished |
-| `{type:"stream-text", text}` | a complete assistant text block, from the transcript |
+| `{type:"stream-text", text, at?}` | a complete assistant text block, from the transcript. `at` is when it was **written**, not when we read it |
 | `{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 |
@@ -241,11 +295,13 @@ client, or immediately on an explicit `stop` (which ends it for everyone).
 | `{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 |
+| `{type:"term-data", data}` | **experimental** — raw pane output (base64) for a client-side terminal emulator |
+| `{type:"gone"}` / `{type:"error", message, code?}` / `{type:"exited", code}` / `{type:"stopped"}` | session lost, errors, termination. `error.code` is `"busy"` for a prompt refused mid-turn, so a machine client needn't match on the message text |
 
 HTTP endpoints (same auth): `/usage`, `/live`, `/sessions`, `/recover`,
-`/diff`, `/channels`, `/groups`, `/profiles`, `/secrets`, `/telegram`,
-`/defaults`, `/version`, `/autoupdate`, `/permission-mode`.
+`/diff`, `/channels` (its GET adds a **derived** `crons` field — never stored),
+`/channel` (DELETE), `/groups`, `/crons`, `/timezone`, `/profiles`, `/secrets`,
+`/telegram`, `/defaults`, `/version`, `/autoupdate`, `/permission-mode`.
 
 ## Library
 
@@ -290,7 +346,12 @@ update breaks the detection).
 - 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.
+  agent drifts from a moving main branch. A design for this exists and was
+  deliberately deferred:
+  `docs/superpowers/specs/2026-07-28-worktree-rebase-drift-design.md`.
+- The interactive terminal (xterm.js over the raw pane stream) is
+  **experimental** and requires tmux; with node-pty the engine room is all there
+  is.
 - 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.201",
+  "version": "0.1.202",
   "main": "dist/session.js",
   "scripts": {
     "test": "node --import tsx --test test/*.ts .claude/skills/shadok-ai-agents/test/*.test.mjs",