durable-chat 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,780 @@
1
- # Temporary Holding Version
1
+ # durable-chat
2
2
 
3
- 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.
3
+ A small terminal coordinator for durable pi agents.
4
+
5
+ One main conversation stays available to you. It delegates longer work to **background jobs**: separate
6
+ persisted agent conversations with a minimal covering tool set and the Substrate MCP gateway. Jobs keep
7
+ running while you keep chatting, survive process restarts, and can be inspected, continued, compacted,
8
+ reset, or cancelled. A job can hand its remaining work to a successor job or back to the coordinator.
9
+
10
+ Built on `@earendil-works/pi-durable` 1.5.0 (SQLite storage), `pi-ai`, `pi-schema`, and `pi-mcp`.
11
+
12
+ Maintainer overview: [docs/HANDOFF.md](docs/HANDOFF.md).
13
+ Release process: [docs/RELEASING.md](docs/RELEASING.md).
14
+
15
+ ## Install and run
16
+
17
+ Requires Node >= 22.19 (developed on Node 26).
18
+
19
+ Install the reviewed package from the [GitHub release](https://github.com/thorinside/durable-chat/releases):
20
+
21
+ ```sh
22
+ npm install --global https://github.com/thorinside/durable-chat/releases/download/v1.0.0/durable-chat-1.0.0.tgz
23
+ dchat help
24
+ dchat --provider faux --no-mcp ask "hello" # offline; no model account required
25
+ ```
26
+
27
+ The intended npm name is `durable-chat`; registry publication is separate from GitHub releases.
28
+ Until it is published, use the release archive above rather than assuming `npm install -g durable-chat` works.
29
+
30
+ For a source checkout:
31
+
32
+ ```sh
33
+ git clone https://github.com/thorinside/durable-chat.git
34
+ cd durable-chat
35
+ npm ci --ignore-scripts
36
+ npm run build
37
+ npm link --ignore-scripts
38
+ ```
39
+
40
+ Then configure a provider before interactive use:
41
+
42
+ ```sh
43
+ dchat config init # only if ~/.config/durable-chat/config.yaml is missing
44
+ dchat config set baseUrl http://127.0.0.1:1234/v1 # your local inference server
45
+ dchat # full-screen TUI
46
+ dchat --plain # line-oriented chat
47
+ ```
48
+
49
+ Published packages contain built JavaScript, not TypeScript entrypoints. Node refuses native
50
+ TypeScript stripping inside `node_modules`, so a working source checkout or `npm link` alone does
51
+ not verify an npm release. No compiler is required to run an installed release.
52
+ Git is required for managed worktrees; a compatible terminal is required for the interactive TUI.
53
+
54
+ Defaults live in `~/.config/durable-chat/config.yaml` (or `$XDG_CONFIG_HOME/durable-chat/config.yaml`).
55
+ The generated file points the store at `~/.local/share/durable-chat/store.sqlite` and selects local
56
+ inference. One process owns a store; a lock file (`<store>.lock`) enforces that and reclaims a lock left
57
+ by a dead pid.
58
+
59
+ On macOS in Ghostty, an interactive `dchat`, `dchat tui`, or `dchat chat` launch for an already-open
60
+ store focuses its existing terminal (including its tab/split) and exits successfully. The owner is
61
+ matched by PID or TTY; the single-writer lock stays in place. Batch commands and SSH sessions retain
62
+ the normal lock error. If Ghostty cannot focus the terminal, or Automation permission is denied,
63
+ the original error is shown. This uses Ghostty's `macos-applescript` support (enabled by default);
64
+ macOS may ask for Automation permission on the first use.
65
+
66
+ ## Future wake-ups
67
+
68
+ Main can use its `reminder` tool to schedule a one-shot check of a long-running process,
69
+ then reply immediately instead of waiting or polling:
70
+
71
+ ```json
72
+ {"action":"schedule","at":"2030-06-15T14:30:00Z","message":"Check the deployment status and report the next step."}
73
+ ```
74
+
75
+ `at` must be in the future, within 365 days, with seconds and an explicit timezone.
76
+ Messages are limited to 4000 characters; at most 100 reminders may be pending.
77
+ `{"action":"list"}` lists pending IDs; `{"action":"cancel","id":"123"}` suppresses an
78
+ undelivered reminder. Cancellation cannot retract an input already admitted to Main's inbox.
79
+
80
+ Deadlines and delivery receipts persist in SQLite. While the session is running, the
81
+ Harness wakes a sleeping task at its deadline and queues a normal Main input, behind any
82
+ active turn. Restarting recovers pending reminders, including overdue ones, without
83
+ re-admitting already delivered reminders. This does **not** launch dchat or wake a sleeping
84
+ computer: keep an interactive session running, or overdue reminders run when scheduling
85
+ next resumes (for example, opening the TUI). Batch/read-only status commands do not keep a
86
+ reminder service running. Cancellation is durable immediately; its now-inert sleeping task
87
+ settles at the original deadline. Reminders do not check a process themselves or imply it
88
+ has completed; Main decides what to do when the reminder arrives.
89
+
90
+ ## Configuration
91
+
92
+ Configuration is YAML, loaded on every run. Global defaults come from
93
+ `$XDG_CONFIG_HOME/durable-chat/config.yaml`, or `~/.config/durable-chat/config.yaml` when XDG is unset.
94
+ If the launch folder contains `.durable-chat/config.yaml`, its values override the global file.
95
+ Both locations accept `config.yml` as a fallback; `config.yaml` wins when both exist.
96
+ Only the launch folder is checked, not its parents.
97
+
98
+ Precedence is **CLI flag > environment variable > folder-local config > global config > built-in**.
99
+ Local files can contain just the keys you want to change. Nested `mcp` settings merge by key;
100
+ lists replace inherited lists (use `[]` to clear one). Relative paths still resolve against the launch
101
+ folder, not the config file's directory.
102
+
103
+ `--config <path>` or `DURABLE_CHAT_CONFIG` selects a **standalone** file instead of automatic global/local
104
+ layering; CLI `--config` wins over the environment selector. Missing explicit files are errors.
105
+ There is no implicit `.env` loading; `.env.example` lists equivalent environment overrides.
106
+
107
+ ```sh
108
+ durable-chat config path
109
+ durable-chat config show
110
+ durable-chat config keys
111
+ durable-chat config set maxTurns 20
112
+ durable-chat config set mcp.servers '["substrate", "nt_helper"]'
113
+ durable-chat config unset jobMaxTurns
114
+ durable-chat config edit # $VISUAL/$EDITOR
115
+ durable-chat config init --force # rewrite the template
116
+ ```
117
+
118
+ `set`/`unset` edit the YAML document in place, preserving comments and key order, and type-check the whole
119
+ file before writing. Secrets are not accepted in the file; `apiKeyEnv` names an environment variable.
120
+ `config show` prints effective values and loaded layers, never the secret itself.
121
+ `path`, `set`, `unset`, `init`, and `edit` target an existing folder-local file, otherwise the global
122
+ file. Use `--local` to target the folder even before a local file exists.
123
+ Unsetting a local key restores the inherited value. Use `--config <path>` to explicitly edit another
124
+ file. `--local` cannot be combined with `--config` or `DURABLE_CHAT_CONFIG`.
125
+
126
+ ### Folder-local overrides
127
+
128
+ ```sh
129
+ dchat config init --local # creates an empty override file, preserving global defaults
130
+ dchat config set maxTurns 30 # edits .durable-chat/config.yaml now that it exists
131
+ dchat config set store .durable-chat/store.sqlite
132
+ dchat config show # shows the merged settings
133
+ ```
134
+
135
+ For example, a project's `.durable-chat/config.yaml` could contain only:
136
+
137
+ ```yaml
138
+ maxTurns: 30
139
+ store: .durable-chat/store.sqlite
140
+ mcp:
141
+ servers: [substrate, nt_helper]
142
+ ```
143
+
144
+ Model and other unspecified settings still come from the global file. A local config does **not**
145
+ automatically switch databases; set `store` explicitly for folder-local state. Existing database contents
146
+ are not migrated. Ignore `.durable-chat/` in Git when it contains local state, and only load project
147
+ configs you trust. Without a local config, existing shared-store behavior is unchanged.
148
+
149
+ ### Fork the current state into a folder
150
+
151
+ ```sh
152
+ cd /path/to/project
153
+ dchat state fork
154
+ dchat
155
+ ```
156
+
157
+ `state fork` snapshots the currently selected database (normally the global store) into
158
+ `.durable-chat/store.sqlite` and sets `store` in the folder's local config, creating that config if
159
+ needed. Other local overrides and comments are preserved; global configuration and source state are
160
+ unchanged. To choose a different source explicitly:
161
+
162
+ ```sh
163
+ dchat state fork --store ~/.local/share/durable-chat/store.sqlite
164
+ ```
165
+
166
+ This is a consistent SQLite snapshot, including committed WAL data, not a raw file copy. It can read
167
+ a running source, but does not open a Harness, connect MCP, call a model, or resume work while copying.
168
+ Existing local databases or SQLite sidecars are never overwritten, even with `--force`.
169
+ `config show` shows the selected database; persistent `DURABLE_STORE` or `DURABLE_CHAT_CONFIG` overrides
170
+ must be unset to let the new local config take effect.
171
+
172
+ The fork retains conversations, task identities, and pending work. Subsequent changes are independent.
173
+ **Both copies can resume the same unfinished work and repeat external actions**; leave the original
174
+ stopped if you want only the fork to continue. Existing jobs retain their saved working directories:
175
+ forking storage does not move files or rewrite those job locations. Saved worktree assignments are
176
+ copied as-is; main's context-fork tool can create new worktrees for independent code variants.
177
+
178
+ The generated global defaults:
179
+
180
+ ```yaml
181
+ provider: local
182
+ model: nemotron-bolt
183
+ baseUrl: http://dev.local:1234/v1
184
+ contextWindow: 262144
185
+ maxTokens: 32768
186
+ streamTimeoutMs: 600000 # cold local start
187
+ retries: 1
188
+ thinkingLevel: "off"
189
+ maxTurns: 60
190
+ jobMaxTurns: 120
191
+ autoContinue: true
192
+ codemode: true # scripts that call the conversation's tools
193
+ # More than one provider can be configured; provider selects the active entry by name.
194
+ # providers:
195
+ # codex: { kind: openai-codex, model: gpt-6.1-sol }
196
+ # local: { kind: local, model: nemotron-bolt, baseUrl: http://127.0.0.1:1234/v1, contextWindow: 131072 }
197
+ store: ~/.local/share/durable-chat/store.sqlite
198
+ mcp:
199
+ enabled: true
200
+ servers: [substrate]
201
+ tools: []
202
+ config: ~/.pi/agent/mcp.json
203
+ ```
204
+
205
+ ### ChatGPT / Codex subscription
206
+
207
+ Use your ChatGPT/Codex subscription (OAuth) rather than an API key:
208
+
209
+ ```sh
210
+ durable-chat config set provider openai-codex
211
+ durable-chat config set model gpt-6.1-sol
212
+ durable-chat config set thinkingLevel medium
213
+ durable-chat config set contextWindow 500000
214
+ durable-chat config set maxTokens 128000
215
+ # An entry can hold its own settings, as providers.codex.model or providers.local.baseUrl.
216
+ ```
217
+
218
+ It reads the OAuth credential already stored by pi at `~/.pi/agent/auth.json` (override with
219
+ `DURABLE_AUTH_FILE`) and refreshes it in place. If that file has no `openai-codex` credential, sign in
220
+ with `pi` first. This is a subscription quota path, not `OPENAI_API_KEY`; never copy the token into this
221
+ repository.
222
+
223
+ ### OpenAI API key and local servers
224
+
225
+ Switch to the OpenAI API by setting `provider: openai`, `model: <listed id>`, and exporting
226
+ `OPENAI_API_KEY`. Set `provider: faux` for the offline scripted model.
227
+
228
+ The local provider declares `supportsDeveloperRole: false` and a chat-template thinking toggle because
229
+ llama.cpp-compatible servers commonly reject the OpenAI `developer` role. Agents run with
230
+ `thinkingLevel: "off"` to keep coordinator turns fast; change it in the config for reasoning models.
231
+
232
+ The file is read when a process starts; edits apply after restarting the process. Main and every job
233
+ use one session-wide model, initially selected at startup and changeable with `/model`. This includes
234
+ existing conversations, context forks, and handoff successors; there are no per-job model overrides.
235
+ An unfinished request retains its prepared model; it never blocks model selection. `/thinking [level]`
236
+ changes the thinking level for the run — main, existing jobs, and jobs created afterwards — without
237
+ writing the config file, so the next process starts from `thinkingLevel` again. `jobMaxTurns` remains a
238
+ creation-time job setting. Changing `store` selects another database; it does not migrate the old one.
239
+
240
+ ## Repository instructions (AGENTS.md)
241
+
242
+ Main, background jobs, forks and handoff successors automatically receive applicable `AGENTS.md`
243
+ files, from filesystem ancestors through their configured working directory. Files apply only to
244
+ that directory's subtree; more-specific files override ancestor rules within their own scope.
245
+ Sibling directories are not scanned. Paths are canonicalized, including symlinks and new write paths.
246
+ Managed worktrees use their own checked-out instructions, not changes in the source checkout.
247
+
248
+ Repository text is supplied as scoped **user context**, never trusted system policy. Each model
249
+ request gets one fresh, deduplicated snapshot, without appending instruction copies to durable
250
+ history. Forks rediscover instructions for their assigned directory rather than inheriting the
251
+ source's active scopes. Existing jobs are upgraded on startup.
252
+
253
+ When `read`, `write` or `edit` targets another scope, new or changed instructions automatically
254
+ pause the operation **before it executes**. The next model request loads them; the agent can then
255
+ review and retry. This also applies to coding tools called through codemode. Up to 16 recently
256
+ discovered target directories are retained per conversation for the current runtime; changing the
257
+ conversation cwd clears them. Files are refreshed on each request and checked again before coding
258
+ operations. Unreadable, invalid or oversized instruction files fail visibly (128 KiB per file).
259
+
260
+ `bash` accepts an optional `cwd` argument for directory-aware shell work, with the same instruction
261
+ check. It affects that command only. A `cd` inside a shell command does not change the conversation's
262
+ working directory. Arbitrary shell scripts, paths embedded in commands and external/MCP tools cannot
263
+ be statically inspected: agents should use explicit `bash` cwd or a coding-tool path to discover the
264
+ scope first. Instructions are guidance, not a filesystem sandbox. Files may change concurrently;
265
+ this is not a transactional security boundary.
266
+
267
+ ## Context and compaction
268
+
269
+ The context pane and `info`/`task show` show two different numbers:
270
+
271
+ - **context** — estimated size of the model request, using the same estimator Pi Durable uses
272
+ for compaction. It counts the newest assistant usage plus estimated messages after it.
273
+ - **spent** — cumulative recorded usage (`pi.usage`), not the current context.
274
+
275
+ For `gpt-6.1-sol` the window is 500k. Pi Durable’s default compaction policy reserves 16,384 tokens,
276
+ so blocking automatic compaction starts above **~483,616** tokens; background compaction starts
277
+ 32,768 tokens earlier (~450,848) when a selectable old prefix exists. It keeps about 20,000 recent
278
+ tokens, summarizes the older prefix, and places a `pi.compaction` head entry. A summary only counts
279
+ after its placement is stored.
280
+
281
+ Manual compaction: `m` on the selected target in the TUI, or `durable-chat compact [focus]` /
282
+ `durable-chat task compact <id> [focus]`. It runs a compaction task and waits for both the task and
283
+ the summary placement. A short conversation, or one with no selectable old prefix, is a no-op.
284
+
285
+ ## TUI
286
+
287
+ The default interface is a three-pane dashboard: jobs on the left, the selected conversation in the
288
+ middle, and live context on the right. The composer sends to `main` by default; open a job to target it.
289
+
290
+ The mouse wheel, Magic Mouse and trackpad scroll the pane under the pointer, keeping keyboard focus,
291
+ the composer draft and the selected job unchanged. Pane headings stay fixed; keyboard job navigation
292
+ brings the selection back into view. Alt+wheel scrolls faster.
293
+
294
+ Command-click transcript URLs on macOS (Ctrl-click in terminals that use that modifier) to open them
295
+ in the default browser. Markdown links and bare URLs keep their complete destinations when wrapped.
296
+ Clicks routed to the app also open web links; dragging across a link still selects text.
297
+
298
+ The terminal title includes the launch folder, for example `durable-chat — ~/projects/example`.
299
+ The previous title is restored on startup failure or exit using the terminal's title stack.
300
+ Folders outside home remain absolute. Allow program-controlled titles in your terminal; Ghostty's
301
+ `--title` option or a fixed `title` setting overrides title updates from apps.
302
+
303
+ ```text
304
+ ┌ durable-chat ─ local/nemotron-bolt ─ substrate ─ 2 live ─────────────────────┐
305
+ │ JOBS 2 live │ TRANSCRIPT main ● live │ CONTEXT │
306
+ │ ▸ #13 running 12s │ you Read src/ … │ target: main │
307
+ │ #14 sleeping 3s │ ai Started job #13. │ status: busy │
308
+ │ #11 completed │ ↳ ✓ bash · 18ms src/… │ turns: 3 │
309
+ │ #10 failed │ │ tokens: 18.2k │
310
+ ├──────────────────────┴───────────────────────────────┴──────────────────────┤
311
+ │ to main › _ │
312
+ │ ENTER send · CTRL-C ×2 quit · TAB jobs · CTRL-T target · CTRL-N new job │
313
+ └──────────────────────────────────────────────────────────────────────────────┘
314
+ ```
315
+
316
+ | Key | Action |
317
+ | --- | --- |
318
+ | `Tab` / `Shift-Tab` | cycle composer → jobs → transcript |
319
+ | `Ctrl-T` | switch composer target main ↔ selected job |
320
+ | `Ctrl-N` | new job brief |
321
+ | `Alt-S` | steer vs follow-up for the current target (main or job) |
322
+ | `Ctrl-V` | paste an image into the composer (main only) |
323
+ | `Enter` | send, open the selected job, or confirm |
324
+ | `j/k`, `g/G`, `PgUp/PgDn` | move selection or scroll |
325
+ | Mouse wheel / trackpad | scroll the pane under the pointer without moving keyboard focus |
326
+ | Cmd-click / Ctrl-click | open transcript links using the terminal's link modifier |
327
+ | `n / c / m / R` | new job · cancel · compact · reset (selected target) |
328
+ | `s / t / f / y` | send-to · expand tools · show finished · copy |
329
+ | `/` | start a slash command in the composer; filter jobs when focus is on jobs/transcript |
330
+ | `[` / `]` | shrink / grow the jobs pane |
331
+ | `{` / `}` | shrink / grow the context pane (shows it on narrow terminals) |
332
+ | `0` | reset pane widths |
333
+ | `i` | inspector (config, MCP notes, usage); `e` edits the config |
334
+ | `a` | abort the main run (jobs survive) |
335
+ | `?` | help |
336
+ | `Ctrl-C` | stop waiting / clear the prompt / close an overlay; arms quitting for 1.5 seconds |
337
+ | `Ctrl-C` twice | quit; small floating confirmation over the dashboard while live work exists |
338
+
339
+ `Ctrl-V` attaches an image to the next message to main. It reads the native clipboard (macOS and
340
+ Windows prebuilds, Linux with X11); `/image <path>` is the fallback where that helper is unavailable.
341
+ Images are prepared with Photon on a worker thread to the model's image limits, and paste is refused
342
+ when the model declares text-only input, because providers drop image blocks for those models.
343
+ Attachments go to main only; jobs keep text input.
344
+
345
+ Transcript prose supports lightweight Markdown: headings, emphasis, lists, links, quotes, tables, and code
346
+ blocks, including streaming replies. Tool output stays literal; code blocks use plain styling without
347
+ syntax highlighting. The plain-chat interface is unchanged.
348
+
349
+ The composer has a dark-grey three-row background with blank padding above and below the input.
350
+ Pane headings, the target/status line, and individual jobs have spacer rows; the transcript has a solid
351
+ black background. While targeting `main`, newly arriving jobs are highlighted automatically. Returning
352
+ to `main` selects the newest visible job; manual browsing between arrivals and pinned job targets are
353
+ preserved. A single `Ctrl-C` clears the input or stops waiting as before; a second consecutive press
354
+ within 1.5 seconds requests quit. Typing, navigation, or expiry resets that sequence. Live work still
355
+ gets the floating confirmation; `Ctrl-Q` is no longer a quit shortcut.
356
+
357
+ The status line always shows `ctx ~tokens/window`; wide layouts add `context` (estimated active request),
358
+ `compact` (the default automatic-compaction threshold) and `spent` (cumulative recorded usage). Pane
359
+ widths are adjustable from the jobs or transcript focus with `[`/`]`, `{`/`}`, and `0`; resizing is
360
+ per-run.
361
+
362
+ Jobs run in the background and main stays usable. The TUI is the single store writer; closing it pauses
363
+ jobs, and the next run resumes them. `durable-chat --plain` or `durable-chat chat` is the old
364
+ line-oriented interface over the same runtime.
365
+
366
+ Steering applies to both targets: `Alt-S` selects whether the next message joins the current run
367
+ (`steer`) or queues behind it (`followUp`). The CLI equivalent is `task send <id> "<message>" --steer`
368
+ or `/steer <id> <message>` in the chat or TUI composer.
369
+
370
+ Starting a job from the TUI or `task add` writes a native, model-visible `[host]` start notice into
371
+ main's conversation. Every job reports completion, failure, or abort as a native follow-up input by
372
+ default, including jobs started by main's `task` tool (whose tool result already covers the start).
373
+ That means **main automatically continues**: it runs, reviews the result, and tells the user what
374
+ changed. A handoff to main is also an input and starts a run. Main is event-driven: it is told not to
375
+ poll, and `task list`/`task show` are for an explicit status request or a specific detail, not for
376
+ checking whether work is done.
377
+
378
+ Set `autoContinue: false` in the config for passive notices (a write that main sees on its next turn
379
+ without spending tokens immediately). The default is `true`. The setting is captured when a job is
380
+ created, so changing it affects new jobs and their handoff successors.
381
+
382
+ Turn limits are tool rounds per run: `maxTurns: 60` for main and `jobMaxTurns: 120` for jobs. Main’s
383
+ `task` tool also enforces a host-side anti-poll guard: the first `show` on a live job is allowed, but a
384
+ second within 30 seconds returns a “do not poll” result and ends the run; a repeated `list` within 10
385
+ seconds does the same. This protects a model that ignores the prompt.
386
+
387
+ All durable state goes through Pi Durable — `Harness`, `Conversation`, `Task`, `Submission`, native
388
+ documents, `watchTaskGraph`, `conversation.watch`, `entries`, `compact`, `reset`, `abortTask`, and
389
+ native `control.terminate` handoffs. The only host files are configuration, the MCP server config, and
390
+ the store lock.
391
+
392
+ ## Commands
393
+
394
+ | Command | Meaning |
395
+ | --- | --- |
396
+ | `durable-chat` | full-screen TUI dashboard (`--plain` for the line chat) |
397
+ | `durable-chat tui` | force the TUI |
398
+ | `durable-chat chat` | line-oriented chat |
399
+ | `durable-chat ask "<text>" [--wait]` | one-shot main-agent turn; `--wait` joins live jobs afterwards |
400
+ | `durable-chat task add "<brief>" [--detach]` | start a background job agent (waits unless `--detach`) |
401
+ | `durable-chat tasks` | list live and finished jobs |
402
+ | `durable-chat task <id>` | job status, answer, and recent job transcript |
403
+ | `durable-chat task log <id>` | recent job transcript |
404
+ | `durable-chat task send <id> "<message>" [--steer]` | continue the job conversation, or steer its current run |
405
+ | `durable-chat task cancel <id>` | abort the job and its active job conversation |
406
+ | `durable-chat task compact <id> [focus]` | compact the job conversation |
407
+ | `durable-chat task reset <id> [handoff]` | reset the job context |
408
+ | `durable-chat watch [--follow]` | live job board until jobs settle (or until Ctrl-C with `--follow`) |
409
+ | `durable-chat compact [focus]` | compact the main conversation |
410
+ | `durable-chat reset [handoff]` | reset the main context |
411
+ | `durable-chat info` | config, store, model, limits, tools, and MCP status |
412
+ | `durable-chat config ...` | `path`, `show`, `keys`, `init`, `edit`, `get`, `set`, `unset` |
413
+ | `durable-chat state fork [--store <source>]` | snapshot the selected state into this folder and configure the fork |
414
+
415
+ Global flags: `--config <path>`, `--store <path>`, `--provider faux|openai|local`, `--model <id>`,
416
+ `--verbose`, `--plain`, `--no-mcp`, `--force` (for `config init`).
417
+
418
+ Inside the plain chat or TUI composer:
419
+
420
+ ```text
421
+ /tasks list jobs
422
+ /task <id> show a job
423
+ /log <id> recent job transcript
424
+ /new <brief> start a job and let it run
425
+ /send <id> <message> continue a job (follow-up)
426
+ /steer <id> <message> steer the job's current run
427
+ /cancel <id> abort a job
428
+ /compact [focus] compact the main conversation
429
+ /reset [handoff] reset the main context
430
+ /model [id] pick the session-wide model, across configured providers
431
+ /provider [name] list configured providers, or make one active for this session
432
+ /thinking [level] session thinking level for main and jobs; the config file decides the next run
433
+ /image <path> attach an image to the next message to main
434
+ /reboot archive all app state and start a fresh database (confirmation required)
435
+ /rollback [path] select saved state, archive current state, restore a copy, and relaunch
436
+ /wait join live jobs (Ctrl-C stops waiting only)
437
+ /info
438
+ /quit
439
+ ```
440
+
441
+ In the TUI, these are local actions, not model messages: `/help` opens help, `/info` opens the inspector,
442
+ `/tasks` focuses the jobs pane, and `/task`/`/log` open the job transcript. `/new` without a brief opens
443
+ the brief prompt. `/compact` and `/reset` apply to the current target; reset, cancel, and quitting with
444
+ live work retain their confirmations. `/send` and `/steer` address the specified job without changing
445
+ the current target. `/wait` joins a snapshot of current jobs, and Ctrl-C cancels only the wait.
446
+ Use `/filter [query]` in the TUI composer to filter jobs, or press `/` while focused on jobs/transcript.
447
+ Unknown or malformed commands report a local error rather than being sent to the model.
448
+
449
+ The main agent is never blocked by a job: jobs are background tasks in the main conversation and run in
450
+ their own conversations. Closing the process does not delete work; unfinished task phases resume on the
451
+ next open.
452
+
453
+ ### Model picker
454
+
455
+ Use `/model` to browse the models of **every configured provider**, the active entry first. In the
456
+ TUI, type to filter, use Up/Down to select, and press Enter to apply; Esc cancels. Plain chat offers a
457
+ numbered list and accepts a number, exact ID, or `provider/id`. `/model <exact-id>` selects directly.
458
+ When two entries list the same ID, the picker shows the provider-qualified `provider/id` so the choice
459
+ cannot be ambiguous.
460
+
461
+ OpenAI/Codex use their installed chat-model catalog. Local servers are queried at the configured
462
+ OpenAI-compatible `/models` endpoint, using the configured API key when present, with a five-second
463
+ timeout. If discovery fails, the configured model remains available. Browsing sends no generation
464
+ requests or OAuth refreshes.
465
+
466
+ Selection applies to main, existing jobs, future jobs/forks, and handoff successors. It keeps the
467
+ database, conversations, and tags, and restarts the runtime under the continuously held store lock.
468
+ Configured context/output ceilings are retained and capped to the selected model's catalog limits.
469
+ Compact large conversations before moving to a smaller context window.
470
+
471
+ Switching closes the current runtime and leaves prepared requests intact. Resumed requests and deferred
472
+ polls use their checkpoint model; ordinary retries prepare again using the current selection. If a pinned
473
+ model is unavailable, that turn ends with `no_model`; subsequent inputs use the selected model. Built-in
474
+ provider IDs remain available for checkpoints saved before named entries were configured. A failed restart
475
+ recovers the previous runtime.
476
+
477
+ Named OpenAI/Codex entries use the existing Pi credentials for their provider kind. Renaming an entry
478
+ keeps the same login, and refreshed tokens are saved back under the original Pi credential key.
479
+
480
+ Selection is **session-only**: it survives `/reboot` and `/rollback` in the same process, while a normal
481
+ process restart uses your configured default. To resume unfinished work on the selected model after
482
+ quitting, start with `dchat --model <id>`. Use `dchat config set model <id>` to explicitly change the
483
+ configured default.
484
+
485
+ `/provider [name]` lists the configured entries and makes one active, applying that entry's model,
486
+ endpoint, ceilings, timeout, and thinking level through the same reopen path as `/model`. Only the
487
+ active entry is contacted for a dynamic list; the others show their configured model. Like `/model`,
488
+ the switch is session-only: the config file still decides the next run.
489
+
490
+ ### Safe reboot
491
+
492
+ Use `/reboot` in the TUI or plain chat to start fresh at the **same database path**. It always asks for
493
+ confirmation: **Y reboots; Enter, N, or Esc cancels** in the TUI (`y` at the plain-chat prompt).
494
+ This applies to the entire store, even when a job is selected.
495
+
496
+ Reboot stops UI observers, closes the runtime and MCP connections, checkpoints SQLite's committed WAL,
497
+ and moves the database into a private, uniquely named archive directory beside the original:
498
+
499
+ ```text
500
+ <store>.reboot-<UTC timestamp>-<unique suffix>/<database filename>
501
+ ```
502
+
503
+ A fresh database then opens at the original path, with empty conversations, jobs, and tags. The active
504
+ session settings and model remain in use; restart the process to apply config-file edits.
505
+ Project files and Git worktrees stay in place. The archive retains old conversations and unfinished jobs,
506
+ which resume only when that archive is reopened.
507
+
508
+ The archive path appears in the TUI inspector, plain-chat banner, and `dchat info`, and survives
509
+ subsequent restarts. Archives stay available until you explicitly remove them. Use `/rollback` below
510
+ to restore a copy while preserving the archive.
511
+
512
+ The store lock stays held throughout rotation and reopening. Close other SQLite clients before
513
+ rebooting; aliased database files (symlinks or additional hard links) are refused. If fresh startup
514
+ fails, recovery preserves the partial replacement and restores the original when its journals can be
515
+ closed safely. Otherwise the error identifies the preserved archive and replacement for recovery.
516
+
517
+ ### Rollback
518
+
519
+ Use `/rollback` in the TUI or plain chat to select a saved database. It lists up to five recent archives,
520
+ with the last backup first. Enter a number or a file path; an explicit path also works directly:
521
+
522
+ ```text
523
+ /rollback
524
+ /rollback "/path/to/saved state/store.sqlite"
525
+ ```
526
+
527
+ After selecting a file, **Y confirms; Enter cancels**. The current runtime closes, its database is
528
+ archived under another unique name, and a consistent SQLite snapshot of the selected file is restored
529
+ at the **original active database path**. The runtime then relaunches with the active session settings.
530
+ The selected file stays unchanged, including when committed data must be read from its WAL.
531
+
532
+ The inspector and `dchat info` show both the selected source and the newly archived previous state.
533
+ Another `/rollback` can select that previous state to undo the restore. The source must be closed and
534
+ lockable; selecting the active database is refused. Failed replacement/reopening uses the same
535
+ preserving recovery as reboot.
536
+
537
+ Restored unfinished jobs resume automatically. Their saved workspaces, and all project files, retain
538
+ their current filesystem contents; rollback restores app state. Reopening another copy of the same
539
+ pending work can repeat external actions.
540
+
541
+ For advanced use, `dchat --store "/path/to/archive/store.sqlite"` opens an archive **in place** rather
542
+ than copying it to the active path.
543
+
544
+ The TUI design and its implementation notes are in [docs/tui-design.md](docs/tui-design.md).
545
+
546
+ ## What each agent can do
547
+
548
+ **Main agent** — `task` (`create`, `list`, `show`, `tag`, `steer`) and `fork`. It primes context through scouting jobs,
549
+ creates fresh jobs or context-forked variants, redirects running jobs, and waits for native notices instead of polling.
550
+
551
+ ```javascript
552
+ task({ action: "steer", id: "13", message: "Focus on the regression fix; preserve the existing API." })
553
+ ```
554
+
555
+ Steering returns as soon as the message is durably queued. The worker receives it at its next native
556
+ boundary; an executing tool continues until that boundary. The job stays live through the steering
557
+ response and reports the updated result, including when steering arrives during a final answer.
558
+ Queued steering survives a restart. Idle and completed jobs reject steering; create or fork a job for new work.
559
+
560
+ **Job agents** — a minimal covering set:
561
+
562
+ - `read`, `write`, `edit`, `bash` from pi-durable's coding tools
563
+ - `substrate_search`, `substrate_describe`, `substrate_call` when Substrate MCP is connected
564
+ - `handoff` — return the work to main or create a successor job
565
+ - `codemode` — a QuickJS script that calls this conversation's tools; only the script's output comes back
566
+
567
+ `substrate_call` is deliberately a gateway rather than 249 separate tool schemas: search the catalog,
568
+ describe the exact tool, then invoke it with a JSON args object. Jobs cannot start arbitrary jobs; a handoff creates at most one successor.
569
+
570
+ ### Codemode scripts
571
+
572
+ `codemode: true` (default, `DURABLE_CODEMODE`) gives main and every job the `codemode` tool. A script
573
+ runs in QuickJS on a worker thread and reaches only the tools of its own conversation, so main's
574
+ scripts can call `task` and `fork` while job scripts keep the coding tools and the MCP gateway.
575
+
576
+ - Only the script's output reaches the model, so a script can batch calls with `Promise.allSettled()`
577
+ and filter large output first.
578
+ - A script survives a restart: its calls are journaled, and a rerun replays them without running
579
+ finished calls again. Tools marked unsafe on replay (`task`, `fork`, `handoff`, `substrate_call`)
580
+ are not rerun, so scripts should not create jobs.
581
+ - The prompt section lists tool declarations up to a token budget; scripts find the rest with
582
+ `searchTools()`, `describeTool()`, and `describeNamespace()`.
583
+ - `store()`/`load()` keep small JSON per conversation, and a fork sees them as of its fork point.
584
+ - Tool `control` applies only to model-issued calls, so the anti-poll guard in the task tool returns
585
+ its text to a script but cannot end a run started by one.
586
+
587
+ ## Context forks (main-only)
588
+
589
+ Ask main to investigate once, then fork the prepared scout into independently briefed variants. Main's
590
+ tool calls look like:
591
+
592
+ ```text
593
+ fork({ source: "13", brief: "Implement the minimal fix", workspace: "worktree" })
594
+ fork({ source: "13", brief: "Try the alternative design", workspace: "worktree" })
595
+ fork({ source: "13", brief: "Review the risks without editing", workspace: "shared" })
596
+ fork({ source: "main", brief: "Explore another direction", workspace: "shared" })
597
+ ```
598
+
599
+ - `source` is `main`, a job ID as a string, or `tag:reviewer` for a uniquely tagged job. The cutoff is the latest completed assistant turn in
600
+ the source's active context. Prime a source before forking it; an in-flight tool round is excluded.
601
+ - Each fork is a new durable job and a native conversation fork. It inherits visible history and tool
602
+ evidence through the cutoff, with a fresh provider identity and independent subsequent entries.
603
+ Existing running tasks are left with the source. All new jobs report to main.
604
+ - The worker gets the job toolset and current brief, rather than main's coordinator tools. Only main
605
+ is offered `fork`, and the tool also checks the calling conversation. Jobs retain `handoff`.
606
+ - The Jobs pane shows `↳ #13` or `↳ main`. The context pane and `task <id>` details show the source
607
+ entry and assigned workspace/branch. Lineage and workspace plans survive restart.
608
+ - Inherited context is still model input; provider caching determines any processing-cost savings.
609
+
610
+ ### Reusable context tags
611
+
612
+ Main can name prepared contexts by purpose rather than remembering task numbers:
613
+
614
+ ```text
615
+ task({ action: "create", brief: "Learn the review conventions and inspect the architecture", tags: ["reviewer"] })
616
+ task({ action: "tag", id: "13", tags: ["reviewer", "primed"] })
617
+ fork({ source: "tag:reviewer", brief: "Review the new variant; recheck the changed files", tags: ["review-a"] })
618
+ ```
619
+
620
+ Tags are persisted independently of a job's lifecycle and can be changed after it completes.
621
+ `task tag` replaces the tag set; `tags: []` clears it. Tags normalize to lowercase, support letters,
622
+ digits, dots, hyphens and underscores, and are limited to eight tags of at most 48 characters per job.
623
+ Task lists/details and the Jobs pane show tags; the job filter matches them.
624
+
625
+ A tagged fork source must resolve to exactly one job with a completed turn. Missing or ambiguous
626
+ matches return a local tool error with candidate IDs; the app never silently chooses a different
627
+ context. Forks receive only their explicitly supplied tags, keeping the prepared source's label stable.
628
+ A tag identifies reusable context, not proof that its findings are still current.
629
+
630
+ ### Fork workspaces
631
+
632
+ `shared` (the default) uses the source conversation's directory recorded at the cutoff. `worktree` requires Git and a clean
633
+ source checkout, including untracked files, and records an exact base commit. The host creates a unique
634
+ `dchat/<uuid>` branch and worktree under the repository's Git common directory
635
+ (`dchat-worktrees/<uuid>`), preserving a source subdirectory as the worker's `cwd`.
636
+
637
+ The plan is committed with the job before filesystem setup. Setup finishes before the first worker
638
+ request; restart reconciles the same branch/path and reacquires the same brief submission. Setup
639
+ errors become job failures reported to main. Existing dirty worktrees and later variant commits are
640
+ retained; incomplete, locked, or mismatched workspaces are preserved and reported for inspection. Saved
641
+ workspace assignments also guard later tool environments after the job task finishes. A handoff
642
+ successor continues in its predecessor's assigned workspace.
643
+
644
+ Worktrees contain the recorded Git tree: ignored files, dependencies, credentials, and dirty edits are
645
+ not copied. The host runs no project setup hooks or dependency installation. Worktrees and branches
646
+ remain after completion, cancellation, and failure for explicit review/integration/cleanup. Main
647
+ decides which results to combine; the app performs no automatic merge. Worktrees provide separate edit
648
+ directories; jobs still share the host and retain their normal tool access.
649
+
650
+ This context-fork tool is distinct from `dchat state fork`, which copies the entire SQLite store.
651
+ Filesystem snapshots of dirty workspaces remain a separate future option.
652
+
653
+ ## Handoffs
654
+
655
+ A job can call the `handoff` tool instead of finishing:
656
+
657
+ ```text
658
+ handoff({ target: "main", brief: "Finish the release notes", summary: "Tests pass; changelog drafted." })
659
+ handoff({ target: "job", brief: "Publish the release", summary: "Notes reviewed; tag prepared." })
660
+ ```
661
+
662
+ - **Job → main**: the coordinator receives a native input (`[job #N handoff] …`) and starts a run.
663
+ The current job ends `handed_off`; main can inspect it with the task tool.
664
+ - **Job → job**: a successor job is created in main's conversation with the same model, cwd, turn limit,
665
+ and selected extensions. Its brief carries the summary and continuation. The current job ends
666
+ `handed_off`; the successor runs independently. Chains are capped at 8 handoffs.
667
+ - **Awareness**: user-started job chains keep writing `[host]` notices to main. A handoff to main is
668
+ itself the message; no extra completion notice is written.
669
+ - Both directions are native: a conversation document records the intent, the task creates the
670
+ successor or admits the main input, and terminal state is committed through `runtime.commit()`.
671
+
672
+ ## Substrate MCP
673
+
674
+ Job agents read MCP servers from `~/.pi/agent/mcp.json` (and `.pi/mcp.json` for project overrides), the
675
+ same format pi uses. The config keys are:
676
+
677
+ - `mcp.enabled` — `true` by default
678
+ - `mcp.servers` — default `[substrate]`
679
+ - `mcp.tools` — optional extra direct tools to expose (server tool names)
680
+ - `mcp.config` — default `~/.pi/agent/mcp.json`
681
+
682
+ Environment equivalents: `DURABLE_MCP_ENABLED`, `DURABLE_MCP_SERVERS`, `DURABLE_MCP_TOOLS`,
683
+ `DURABLE_MCP_CONFIG`. `--no-mcp` disables MCP for one run.
684
+
685
+ The `substrate` server gets the three-tool gateway. Other servers expose selected tools directly (all
686
+ tools up to 20 if no filter is set). If the server is missing, disabled, or unreachable, job agents get a
687
+ `mcp_substrate_unavailable` tool that explains why; jobs still have the coding tools. `durable-chat info`
688
+ shows the connection state and notes. Tokens are read from the config and never printed.
689
+
690
+ ## Durability notes
691
+
692
+ - Every job is a durable `durable-chat.job` task plus its own conversation. The task submits the brief,
693
+ joins the answer, and records the receipt (answer entry, capped answer text) on the task.
694
+ - Inputs use stable request IDs (`job:<taskId>:run`), so a restart reacquires the admission instead of
695
+ duplicating the brief. A generation cut off mid-request retries; an aborted partial answer is retained
696
+ as an aborted entry next to the retried answer.
697
+ - Cancelling a job marks its task, aborts the job conversation with a bounded cleanup wait, then commits
698
+ an `aborted` terminal outcome.
699
+ - Compaction is joined through the compaction task **and** its summary placement. A no-op (no selectable
700
+ old prefix, declined summary) is reported as a no-op, not as success.
701
+ - Reset is admitted immediately; while the conversation is busy it lands at the next boundary. Raw history
702
+ is retained.
703
+ - Jobs are background tasks, so `Conversation.abort()` on the main conversation does not cancel them;
704
+ `task cancel` targets one job.
705
+ - External effects are not exactly-once. Model/tool retries and process cuts can repeat a bash command;
706
+ `read`/`write`/`edit`/MCP calls are marked replay-unsafe where appropriate. Check the job transcript
707
+ before re-running a job with side effects.
708
+
709
+ ## Limits
710
+
711
+ - The config file selects a user-level store; everything is still one SQLite file.
712
+ - One writer per store. Do not run two `durable-chat` processes on one store (chat + watch included).
713
+ - Jobs only run while some process has the store open and scheduling enabled. Closing the process pauses
714
+ them; the next command resumes them.
715
+ - `task add --detach` admits the job and exits without starting it. Use `watch` (or another command that
716
+ resumes scheduling) to run it.
717
+ - The answer stored on a task is capped at 6000 characters; the full answer remains in the job
718
+ conversation (`task log <id>`).
719
+ - Automatic compaction uses pi-durable defaults. Manual compaction of a short conversation is a no-op by
720
+ design.
721
+
722
+ ## Development
723
+
724
+ ```sh
725
+ npm run check # tsc --noEmit
726
+ npm test # source regression tests
727
+ npm run build # clean dist/ build, rewriting relative .ts imports to .js
728
+ npm run test:package # pack, inspect and install into a temporary node_modules, then offline smoke
729
+ ```
730
+
731
+ `tsconfig.json` sets `skipLibCheck: true` deliberately: `@google/genai`'s published declarations import
732
+ an optional `@modelcontextprotocol/sdk` path that is not installed here. Our own sources are checked with
733
+ `strict`; the limitation is the third-party declaration, not a weakened check of this project.
734
+
735
+ ## Layout
736
+
737
+ ```text
738
+ src/cli.ts argument parsing, interactive REPL, slash commands
739
+ src/models.ts provider model discovery and picker selection
740
+ src/reboot.ts closed-database checkpoint, unique archival, and failed-startup recovery
741
+ src/rollback.ts saved-state discovery, source selection, and read-only SQLite snapshot installation
742
+ src/config.ts YAML defaults, precedence, path resolution, typed editing
743
+ src/config-commands.ts config path/show/keys/init/edit/get/set/unset
744
+ src/harness.ts store lock, providers, registry, root configuration, lifecycle
745
+ src/tasks.ts durable job task (workspace/run/report/abort), job links and handoffs
746
+ src/forks.ts completed-turn source selection for main-only context forks
747
+ src/tags.ts durable job tags and unambiguous prepared-context lookup
748
+ src/workspaces.ts Git worktree planning, persisted assignment, and restart-safe setup
749
+ src/jobs.ts job creation, scanning, answers, logs, compaction, messaging
750
+ src/tool.ts the main agent's `task` tool
751
+ src/mcp.ts MCP config, connections, Substrate gateway
752
+ src/chat.ts streaming and one-shot main turns
753
+ src/watch.ts live job board over the task graph
754
+ src/format.ts job views and text formatting
755
+ src/faux.ts offline scripted model for demos and tests
756
+ src/tui/main.ts run the alt-screen dashboard
757
+ src/tui/app.ts panes, keymap, actions, live updates
758
+ src/tui/state.ts pure job list/selection/target helpers
759
+ src/tui/transcript.ts windowed conversation history + live state
760
+ src/tui/format.ts terminal-friendly entry and tool formatting
761
+ ```
762
+
763
+ ## Safety and privacy
764
+
765
+ Agents can run shell commands and read/write files as your user; repository instructions and
766
+ QuickJS codemode are not an operating-system sandbox for the exposed tools. Use a trusted
767
+ working directory and review model/tool actions. Real providers can send prompts, source files
768
+ and tool output to their services and consume paid quota. MCP servers have their own access
769
+ and credential requirements; Substrate is optional (`--no-mcp`).
770
+
771
+ SQLite stores, archives, transcripts, credentials and project-local configuration can contain
772
+ private data. Keep `.durable-chat/`, `.pi/`, `.env`, auth files and database/log artifacts out of
773
+ Git and release archives. Do not upload a live store when reporting a bug.
774
+
775
+ ## License
776
+
777
+ Original durable-chat code is [MIT licensed](LICENSE). The actual upstream dependency is
778
+ `@earendil-works/pi-durable`, part of [earendil-works/pi](https://github.com/earendil-works/pi),
779
+ not a package named “PyDurable”. Its MIT license and relevant third-party notices are preserved
780
+ in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and `LICENSES/`. Dependencies retain their own licenses.