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/LICENSE +21 -0
- package/LICENSES/mcp-sdk-MIT.txt +21 -0
- package/LICENSES/pi-MIT.txt +21 -0
- package/LICENSES/typebox-MIT.txt +23 -0
- package/LICENSES/yaml-ISC.txt +13 -0
- package/README.md +779 -2
- package/THIRD_PARTY_NOTICES.md +46 -0
- package/dist/agent-instructions.js +176 -0
- package/dist/auth.js +91 -0
- package/dist/chat.js +121 -0
- package/dist/cli.js +519 -0
- package/dist/codemode.js +23 -0
- package/dist/commands.js +227 -0
- package/dist/config-commands.js +142 -0
- package/dist/config.js +567 -0
- package/dist/context-usage.js +48 -0
- package/dist/existing-session.js +52 -0
- package/dist/faux.js +89 -0
- package/dist/forks.js +33 -0
- package/dist/format.js +144 -0
- package/dist/handoff.js +56 -0
- package/dist/harness.js +446 -0
- package/dist/images.js +64 -0
- package/dist/jobs.js +274 -0
- package/dist/mcp.js +231 -0
- package/dist/models.js +64 -0
- package/dist/reboot.js +70 -0
- package/dist/reminders.js +120 -0
- package/dist/rollback.js +72 -0
- package/dist/state.js +64 -0
- package/dist/tags.js +44 -0
- package/dist/tasks.js +466 -0
- package/dist/tool.js +205 -0
- package/dist/tui/app.js +1695 -0
- package/dist/tui/browser.js +19 -0
- package/dist/tui/dialog.js +39 -0
- package/dist/tui/format.js +223 -0
- package/dist/tui/main.js +83 -0
- package/dist/tui/selection.js +161 -0
- package/dist/tui/state.js +98 -0
- package/dist/tui/transcript.js +151 -0
- package/dist/watch.js +134 -0
- package/dist/workspaces.js +106 -0
- package/package.json +57 -4
package/README.md
CHANGED
|
@@ -1,3 +1,780 @@
|
|
|
1
|
-
#
|
|
1
|
+
# durable-chat
|
|
2
2
|
|
|
3
|
-
|
|
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.
|