@oisin-ee/pi-dogsled 0.16.4 → 0.18.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 +106 -33
- package/package.json +1 -1
- package/pi/board.ts +14 -0
- package/pi/inbox.ts +6 -2
- package/pi/index.ts +55 -8
- package/pi/work-todo.ts +67 -0
- package/plugins/dogsled/skills/dogsled/SKILL.md +3 -4
package/README.md
CHANGED
|
@@ -11,13 +11,13 @@ Install the binary on each Herdr host. Use the same release tag in each command.
|
|
|
11
11
|
Binary:
|
|
12
12
|
|
|
13
13
|
```sh
|
|
14
|
-
mise use github:oisin-ee/dogsled@v0.
|
|
14
|
+
mise use github:oisin-ee/dogsled@v0.18.0
|
|
15
15
|
```
|
|
16
16
|
|
|
17
17
|
Pi (extension, tools, and skill), from npm or as part of `@oisin-ee/oisinpi`:
|
|
18
18
|
|
|
19
19
|
```sh
|
|
20
|
-
pi install npm:@oisin-ee/pi-dogsled@0.
|
|
20
|
+
pi install npm:@oisin-ee/pi-dogsled@0.18.0
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
At session start the extension compares its version with `dogsled --version` and warns when they differ.
|
|
@@ -25,24 +25,24 @@ At session start the extension compares its version with `dogsled --version` and
|
|
|
25
25
|
Claude Code (hooks, tools, and skill):
|
|
26
26
|
|
|
27
27
|
```sh
|
|
28
|
-
claude plugin marketplace add oisin-ee/dogsled#v0.
|
|
28
|
+
claude plugin marketplace add oisin-ee/dogsled#v0.18.0
|
|
29
29
|
claude plugin install dogsled@dogsled
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
Codex (hooks, tools, and skill):
|
|
33
33
|
|
|
34
34
|
```sh
|
|
35
|
-
codex plugin marketplace add oisin-ee/dogsled --ref v0.
|
|
35
|
+
codex plugin marketplace add oisin-ee/dogsled --ref v0.18.0
|
|
36
36
|
codex plugin add dogsled@dogsled
|
|
37
37
|
```
|
|
38
38
|
|
|
39
39
|
Codex requires review and trust before it runs plugin hooks. See the [Codex hooks documentation](https://developers.openai.com/codex/hooks#plugin-hooks).
|
|
40
40
|
The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#codex-plugin) describes plugin installation.
|
|
41
41
|
|
|
42
|
-
Herdr (
|
|
42
|
+
Herdr (right-side work board):
|
|
43
43
|
|
|
44
44
|
```sh
|
|
45
|
-
herdr plugin install oisin-ee/dogsled --ref v0.
|
|
45
|
+
herdr plugin install oisin-ee/dogsled --ref v0.18.0 --yes
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
Harness plugins use the binary on `PATH`. They do not install it or start host services.
|
|
@@ -108,7 +108,7 @@ The sidebar shows `working`, then `idle` for success or `blocked` for failure, w
|
|
|
108
108
|
|
|
109
109
|
`--max` sets one deadline from command startup, including discovery, placement, admission, and job completion. It defaults to 30 minutes.
|
|
110
110
|
Operations use the remaining command budget, capped at 30 seconds for routine calls and locks, or 10 minutes for setup.
|
|
111
|
-
Setup includes worktree creation and `setup` commands, repository clones, mise trust checks, and agent startup, locally and through SSH.
|
|
111
|
+
Setup includes worktree creation and removal, `setup` and `teardown` commands, repository clones, mise trust checks, and agent startup, locally and through SSH.
|
|
112
112
|
A non-waiting action reports the operation that exceeded its deadline.
|
|
113
113
|
`logs --follow` can continue indefinitely, but each remote read has a 30-second limit.
|
|
114
114
|
Run long waits through the harness's background-task facility.
|
|
@@ -129,6 +129,7 @@ Herdr refuses a start before it types into the pane, for example `agent_pane_bus
|
|
|
129
129
|
```
|
|
130
130
|
|
|
131
131
|
The child gets `--model`, `--thinking`, `--append-system-prompt <prompt>`, then `pi_args`. Unknown keys are ignored, so Shepherdr profiles load as they are.
|
|
132
|
+
`prompt` can also be a list, such as `["../_shared/lead.md", "prompt.md"]`. Each file becomes its own `--append-system-prompt`, in order, so profiles can share one prompt. A directory without `profile.json`, such as `_shared`, is not a profile. The profile panel edits the last file.
|
|
132
133
|
`role` is `reader` or `writer`. Without it, a child with `--branch` is a writer, and any other child a reader.
|
|
133
134
|
`dogsled profiles` lists them; a broken profile shows as `broken: <reason>`.
|
|
134
135
|
|
|
@@ -139,17 +140,17 @@ An item records its host, pane, owner pane, creation time, closure time, and for
|
|
|
139
140
|
`items --json` returns `{items,queue}`. `--owner` filters both collections.
|
|
140
141
|
The service closes a job item after job completion, and any item after pane removal.
|
|
141
142
|
|
|
142
|
-
|
|
143
|
+
`done` hands the task back to the owner. The child host captures the final reply, closes the pane and agent worktree, and keeps the branch. The owner receives the reply and lands the branch without a live child. The sweep remains a backstop.
|
|
143
144
|
|
|
144
|
-
|
|
145
|
-
2. puts the reply in the owner's inbox (see [Inbox](#inbox));
|
|
146
|
-
3. if the child called `done` during that turn, closes it when it is a reader whose worktree is clean with no commits outside the default branch, or when its branch has landed.
|
|
145
|
+
Call `done` during the final working turn, after committing changes. It refuses open children, queued tickets, dirty agent worktrees, and removal that loses content under the shared loss rule. Retaining the local branch protects unlanded commits.
|
|
147
146
|
|
|
148
|
-
|
|
149
|
-
A child that ends a turn without `done` stays open, and its reply tells the owner it waits for input.
|
|
147
|
+
Marks in `done.json` use the launch/item id, pane, and `agent_session.value`, not the terminal id. Legacy marks migrate without deletion. The first `idle` or `done` observation ends the marked turn, including after restore without a completion counter. Working, blocked, and unknown states never authorize closure.
|
|
150
148
|
|
|
151
|
-
|
|
152
|
-
|
|
149
|
+
New inbox work accepted during that same working turn cancels its mark. After that turn ends, the mark is terminal. Senders receive `<name> finished; start a new child for more work`.
|
|
150
|
+
|
|
151
|
+
A child without its own `done` stays open, including a child that asks a question or orchestrates other children. Automatic closure never closes the caller or a busy pane. Shared worktrees remain, and only the finished child pane closes. A last primary pane stays while closing it would close linked workspaces.
|
|
152
|
+
|
|
153
|
+
Closed children retain TO LAND rows: `<child>: branch <b> +N to land`. These rows come from durable items and branch observations, not live panes. Integration or branch deletion removes the row.
|
|
153
154
|
|
|
154
155
|
`dogsled board` groups an owner's children, jobs, and queued tickets by what the owner must do: TO LAND, ATTENTION, RUNNING, and WAITING. Each agent row names the harness and model; each job row names its command. `--json` is what the Pi widget draws.
|
|
155
156
|
`dogsled read TARGET [--host H]` shows a child's or job's newest output and the captured final reply.
|
|
@@ -165,7 +166,7 @@ dogsled done # as a child: my whole task is complete
|
|
|
165
166
|
For an interrupted launch with no final receipt, explicit `close` can retire its exact idle shell under the request and pane locks. This closes **only the pane**, retaining the checkout, preparation holds, and unknown launch evidence. It does not report that the task never started. Competing launch records, a changed terminal, any agent, or incomplete foreground evidence refuse recovery. Automatic cleanup never uses this recovery path; normal cleanup can assess the retained checkout after its holds are resolved.
|
|
166
167
|
In an agent worktree (locked `agent:worktree`, as dogsled makes them), it runs the repository's `teardown` commands in the worktree (see [Repository configuration](#repository-configuration)).
|
|
167
168
|
Then it closes every pane that uses the worktree and the Herdr workspace that shows it, unlocks the worktree, and runs `git worktree remove` without force.
|
|
168
|
-
Close uses the same loss rule as cleanup:
|
|
169
|
+
Close uses the same loss rule as cleanup: no unique checkout content and every commit held by the default branch or freshly fetched remote refs. It deletes the branch under that same rule. Local-only work refuses close, including an explicit owner close.
|
|
169
170
|
When `place` opened the main checkout's workspace as the anchor and no linked worktree is open in Herdr any more, close closes that anchor too. It does so only while the anchor is unfocused, is not the caller's, and has one pane with no agent.
|
|
170
171
|
A pane outside a worktree, or in an unlocked worktree (someone's own checkout), is closed alone; the checkout stays.
|
|
171
172
|
A child tab in the caller's own workspace is closed. Close refuses a missing pane, the caller's own pane, a worktree the caller works in or whose workspace is the caller's, a worktree outside the repository's worktree directory, a dirty or detached worktree, and any other lock.
|
|
@@ -241,8 +242,11 @@ Peer reads run in parallel through SSH and the configured `remote_command`.
|
|
|
241
242
|
A shared, locked cache permits at most one read per peer per ten seconds, including concurrent callers.
|
|
242
243
|
Status never probes peers itself.
|
|
243
244
|
|
|
244
|
-
|
|
245
|
-
|
|
245
|
+
`service: up` means a process holds the host's service lock. A free lock or unreachable peer means `service: down`.
|
|
246
|
+
Status shows snapshot age separately, including when the service runs. Peers without the liveness field retain the 30-second age fallback during upgrades.
|
|
247
|
+
Admission still requires a snapshot no older than 30 seconds. Finished-child cleanup can use an older snapshot from a running service.
|
|
248
|
+
Close rechecks the live pane, the child's `done` mark, and the loss guard before it acts.
|
|
249
|
+
Each tick observes a shared checkout once. Independent checkout and shell-pane reads use at most one worker per available CPU.
|
|
246
250
|
The last peer measurement remains visible when available. Every discovered host stays in the output.
|
|
247
251
|
The JSON output contains `hosts`, with service state, reachability, sample time, probe, headroom, errors, and `retry_ms` while a peer read backs off.
|
|
248
252
|
|
|
@@ -262,7 +266,7 @@ Example tab-row output:
|
|
|
262
266
|
local 11/12 ▲ · netcup 3/16 · momokaya-2 1/7
|
|
263
267
|
```
|
|
264
268
|
|
|
265
|
-
`▲` means not eligible. `?` means the
|
|
269
|
+
`▲` means not eligible, including a stale snapshot from a running service. `?` means the service is down or unavailable, or no snapshot exists.
|
|
266
270
|
A host without measurements prints `momokaya-2 ?`. A stale host keeps its last numbers, followed by ` ?`.
|
|
267
271
|
The numbers are busy cores over cores. A host without a CPU sample shows `load N/cores` instead.
|
|
268
272
|
`--brief` includes busy/cores, memory, disk, agent counts, and a hint to run `dogsled status`.
|
|
@@ -306,25 +310,30 @@ dogsled prune targets
|
|
|
306
310
|
Doctor changes no candidates. It reports `worktrees`, `branches`, `workspaces`, `panes`, `jobs`, `targets`, `disk`, `processes`, and `repositories`.
|
|
307
311
|
Doctor lists linked worktrees on a branch and detached ones.
|
|
308
312
|
One loss rule in `src/loss.rs` governs worktrees, detached HEADs, branches, close, and board facts.
|
|
309
|
-
A checkout must have no tracked or untracked
|
|
313
|
+
A checkout must have no unique tracked or untracked content. Ignored files do not count. A ref without a checkout skips this condition.
|
|
314
|
+
Deleted tracked files alone (` D` or `D `) lose nothing when the tip is held. Other changes still prevent removal.
|
|
315
|
+
Before removal, dogsled restores only those deleted paths from the held HEAD, including staged deletions. It then removes the checkout without force.
|
|
310
316
|
Every commit must be held by the default branch or remote-tracking refs. Each cleanup pass runs `git fetch --all --prune` before remote refs count.
|
|
311
317
|
A failed fetch produces a repository warning. Only the default branch counts for that repository. Deleted upstream branches receive no special treatment.
|
|
312
318
|
A branch is integrated when it is deleted, when it is an ancestor of Git's remote default branch (local `main` is the fallback), or when commits on that branch apply it.
|
|
313
|
-
The branch's commits split into consecutive runs, and each run needs one commit that applies it.
|
|
319
|
+
The branch's commits split into consecutive runs, and each run needs one commit that applies it. Each run uses its net diff, including paths and before/after objects, rather than the union of paths from its commits. Merges from main and reverted edits therefore do not enlarge the whole branch's required path set. A candidate must change every net path. The exact three-way merge into its parent must reproduce its content on those paths.
|
|
314
320
|
One run is a merge, squash, or cherry-pick of the whole branch. Several runs are a stack: the branch holds an earlier branch's commits, and each branch landed as its own squash. Git alone decides this.
|
|
315
321
|
Each path merges on its own. An addition, deletion, or mode change on a path the base also changed differently is a conflict, and renames are not followed, so a doubtful run is not applied.
|
|
322
|
+
A tip also counts as integrated when a local or remote-tracking ref contains it and that ref is integrated. This proof names the containing ref. The search considers only containing refs and checks each directly, without recursive alias loops.
|
|
316
323
|
Results use the remote-tracking branch, so `git fetch` keeps them current.
|
|
317
324
|
A local branch with no worktree is removable when it is integrated or every commit is on a remote branch. Other branches are report-only. The default branch is never a candidate. Prune deletes a branch with `git branch -D` after it rechecks the planned commit.
|
|
318
325
|
Prune and the sweep share the same holds: active panes or processes, the caller, an unreadable process table, and pending preparations or launches.
|
|
319
|
-
An unfinished launch holds its checkout
|
|
326
|
+
An unfinished launch holds its checkout before pane allocation completes, or while its attempted start has the matching agent. An empty shell from a final launch holds nothing.
|
|
320
327
|
An open agent item holds its checkout in prune and the sweep; `close` ends it and keeps the reply. Within `close`, a live owner holds the checkout until the default branch holds its work.
|
|
321
328
|
An idle or done agent that has not called `dogsled done` holds its checkout in prune, the sweep, and an automatic close; only an explicit `dogsled close` takes it. An idle shell, a done agent without an open item, and a workspace alone are not holds. The processes of an idle agent pane are not holds, but a background job that a shell started is. Foreign locks still prevent removal.
|
|
322
329
|
A dirty checkout whose commits are in the default branch gets a `landed_dirty` finding when no hold applies.
|
|
323
330
|
The finding includes the repository, checkout, branch or HEAD, dirty-path count, and up to ten paths. It is never removable.
|
|
324
331
|
A registered worktree whose directory is gone is a stale registration. Prune drops the record only.
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
A
|
|
332
|
+
Prune and the sweep use one pane rule. Both keep the caller's pane and focused panes.
|
|
333
|
+
An empty shell closes when its job ended, its directory disappeared, its launch is final, or its agent item closed.
|
|
334
|
+
A final launch was refused, never attempted, or has an unknown outcome with no agent in its terminal. Cleanup preserves launch receipts and checks terminal ownership under the launch locks.
|
|
335
|
+
A shell without a Dogsled record closes after 15 minutes continuously at an empty prompt, based on service observations and a fresh check. Herdr reports no activity time, so a command that starts and ends between samples does not count.
|
|
336
|
+
An agent pane still needs more than 24 hours continuously idle or done and a `done` mark. An agent with open children stays open.
|
|
328
337
|
A workspace whose every pane is idle is one `workspaces` entry, and prune closes it whole. The caller's workspace stays, and so does a workspace that a worktree removal closes.
|
|
329
338
|
Ended jobs expire after 24 hours, together with their logs. Disk usage above 90% lists the largest known dogsled-owned paths.
|
|
330
339
|
A `targets` entry is build output: a directory with a `CACHEDIR.TAG` that starts with the cache-directory signature, directly under a main checkout or a linked worktree, such as Rust's `target/`.
|
|
@@ -353,7 +362,7 @@ The socket is optional. A bind failure produces a warning, and pending requests
|
|
|
353
362
|
A Stop request failure produces a warning without preventing existing gate or inbox messages from reaching the agent.
|
|
354
363
|
Each requested pass builds the doctor plan in sweep scope. It applies only entries whose removal loses nothing:
|
|
355
364
|
|
|
356
|
-
- `panes` and `workspaces`:
|
|
365
|
+
- `panes` and `workspaces`: the shared pane rule above. A workspace closes whole only when every pane qualifies. Final launch panes close separately under their launch locks.
|
|
357
366
|
- `worktrees` and `branches`: the shared loss rule and holds described above, identical to prune.
|
|
358
367
|
- Orphaned children: a child that called `done`, whose owner is gone, and whose checkout passes the shared loss rule. Close runs teardown and removes its workspace, checkout, and item.
|
|
359
368
|
|
|
@@ -365,7 +374,7 @@ The report includes start and finish times, removals, failures, repository warni
|
|
|
365
374
|
The service also writes removals, failures, and repository warnings to stderr.
|
|
366
375
|
Child completion and orphan checks remain independent of requested doctor cleanup.
|
|
367
376
|
An orphan that is dirty, unpushed, `working`, `blocked`, or on an unreachable host stays open. Status shows `orphaned:` and the reason on its item line, the brief counts it, and every check-in on the host lists it.
|
|
368
|
-
Prune also handles
|
|
377
|
+
Prune also handles ended jobs, stale registrations, and `targets`. Disk, process, and repository findings are report-only.
|
|
369
378
|
|
|
370
379
|
## Placement
|
|
371
380
|
|
|
@@ -423,6 +432,57 @@ repositories = [] # for example "~/.config/mise"; `~/` is the home directory
|
|
|
423
432
|
|
|
424
433
|
Host policy has no worktree hooks. A `[hooks]` table is an unknown key, so it is an error. Worktree setup and teardown belong to each repository.
|
|
425
434
|
|
|
435
|
+
### Quota snapshots
|
|
436
|
+
|
|
437
|
+
```toml
|
|
438
|
+
[quota]
|
|
439
|
+
management_url = "https://cliproxy-admin.tail10e7b9.ts.net"
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
The URL is an HTTPS origin, without a path or credentials. No management key belongs in configuration.
|
|
443
|
+
Only macOS collects quota, and only when this Keychain lookup succeeds:
|
|
444
|
+
|
|
445
|
+
```sh
|
|
446
|
+
security find-generic-password -s dogsled -a cliproxy-management -w
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
This command prints the key. Dogsled captures it internally and never logs it.
|
|
450
|
+
Create the generic-password item through Keychain Access, with service `dogsled` and account `cliproxy-management`.
|
|
451
|
+
The collector passes the key to curl through stdin, never command arguments or a file.
|
|
452
|
+
Linux hosts never read the key. A missing URL or unreadable Keychain item makes quota commands use the local cache.
|
|
453
|
+
|
|
454
|
+
```sh
|
|
455
|
+
dogsled quota
|
|
456
|
+
dogsled quota --json
|
|
457
|
+
dogsled quota --json --cached
|
|
458
|
+
dogsled quota --refresh
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
`--cached` reads only `$DOGSLED_STATE/quota.json`, even when it is older than 15 minutes.
|
|
462
|
+
Without `--cached`, the collector refreshes snapshots older than five minutes. `--refresh` forces collection.
|
|
463
|
+
The service also refreshes every five minutes. A shared lock prevents concurrent collection, and failed collection backs off.
|
|
464
|
+
Each successful collection pushes the snapshot to enabled Herdr peers over SSH. Failed pushes retry with backoff.
|
|
465
|
+
Peers need a dogsled version that supports quota storage. No management credential leaves the collector.
|
|
466
|
+
|
|
467
|
+
The version-1 contract contains `version`, `fetched_ms`, `source`, and `pools`.
|
|
468
|
+
`source` identifies the collector by hostname. Each row contains these fields:
|
|
469
|
+
|
|
470
|
+
- `pool`: `claude`, `codex`, or `minimax`.
|
|
471
|
+
- `account` and `window`: the account label and provider window name.
|
|
472
|
+
- `used_pct`: a number from 0 to 100.
|
|
473
|
+
- `resets_ms`: Unix milliseconds, or `null` when unavailable.
|
|
474
|
+
- `error`: a safe error description, or `null`.
|
|
475
|
+
|
|
476
|
+
Claude windows are `five_hour`, `seven_day`, `seven_day_opus`, and `seven_day_sonnet`.
|
|
477
|
+
Codex windows are `primary` and `secondary`. MiniMax windows are `interval` and `weekly`.
|
|
478
|
+
MiniMax account labels use `minimax-N`, where N is the position in the configured API-key list.
|
|
479
|
+
A failed account has error rows with zero usage and no reset time. Consumers must treat these rows as unknown, not available quota.
|
|
480
|
+
A pool is exhausted when every account has a window at 100% with a reset time in the future.
|
|
481
|
+
Human output shows each window, reset time, and snapshot age. No snapshot produces an empty version-1 snapshot with `fetched_ms: 0`.
|
|
482
|
+
|
|
483
|
+
The hidden `quota --store` command accepts one validated snapshot on stdin and writes it atomically.
|
|
484
|
+
Older pushed snapshots cannot replace newer snapshots. The SSH transport uses the same writer through `host quota-store`.
|
|
485
|
+
|
|
426
486
|
### Repository configuration
|
|
427
487
|
|
|
428
488
|
An optional `dogsled.toml` at the root of the repository's main checkout configures its worktrees. Without the file, the defaults apply.
|
|
@@ -479,7 +539,7 @@ The CLI never reads stdin. Claude Code and Codex receive `hookSpecificOutput` JS
|
|
|
479
539
|
Pi receives plain text through its `before_agent_start` extension. All three use the same snapshot reader and formatter.
|
|
480
540
|
|
|
481
541
|
Before an orchestrator stops, the stop gate checks its own TO LAND children.
|
|
482
|
-
Pi calls `dogsled hook gate` from `agent_before_settle`
|
|
542
|
+
Pi calls `dogsled hook gate` from `agent_before_settle` on every completed stop, which also requests a cleanup pass. A reminder is added as a visible message that continues the run.
|
|
483
543
|
Claude Code and Codex include the reminder in their existing `Stop` inbox response.
|
|
484
544
|
The reminder requests a review, a commit from dirty children, integration, or an explicit blocker or deferral.
|
|
485
545
|
It never commits, merges, closes, or discards work itself. Clean readers and working children do not trigger it.
|
|
@@ -512,8 +572,8 @@ The caller is the harness's `HERDR_PANE_ID`. Pi registers the server from its ex
|
|
|
512
572
|
|
|
513
573
|
The extension adds host status before each prompt, registers the tools, and draws:
|
|
514
574
|
|
|
515
|
-
- **The board
|
|
516
|
-
- **Alt+W or `/work`** expands or collapses
|
|
575
|
+
- **The right-side board** shows cached quotas, agents, jobs, and todos when `HERDR_ENV=1` and `HERDR_SOCKET_PATH` accepts a connection. Pi opens or reuses the tab’s split and sets no above-editor widget. Without Herdr, the existing widget shows host meters, the current task, and work groups. Agent/job data refreshes every ten seconds. Compatible pi-todo snapshots update immediately in the widget.
|
|
576
|
+
- **Alt+W or `/work`** opens or reuses the Herdr split. Without Herdr, it expands or collapses the widget in place, without a popup or editor replacement. Alt+J/K moves selection, Alt+] changes views, and Alt+I shows inline details. Typing stays in the editor. Alt+S stops jobs, Alt+C cancels queued work, and Alt+M sends agent messages. Stop and cancel require confirmation. Completed job history starts collapsed.
|
|
517
577
|
- **`/dogsled`**, the control panel, with four tabs: Status (hosts with their retry state, then your rows; Enter on a host reads it again now), Hosts (reconnect, rename, enable, disable, add), Profiles (Enter edits `prompt.md`), and Inbox. The widget steps aside while the panel is open.
|
|
518
578
|
- **The inbox reader** and a renderer that shows each record's kind, sender, and text, folded past twelve lines.
|
|
519
579
|
|
|
@@ -523,13 +583,26 @@ Todos follow the active Pi session branch. Agents and jobs follow the calling He
|
|
|
523
583
|
|
|
524
584
|
The Jobs view joins retained records to the current owner's ledger by host and job ID. It does not show unrelated fleet jobs. Job inspection uses `dogsled read` for a bounded log tail and shows the `dogsled logs` command for full output. Expired records and unavailable hosts produce explicit errors. The panel never starts a new process manager, edits todos, or writes into an agent terminal.
|
|
525
585
|
|
|
526
|
-
The Herdr plugin
|
|
586
|
+
The Herdr plugin opens the right-side work board:
|
|
527
587
|
|
|
528
588
|
```sh
|
|
529
|
-
|
|
589
|
+
dogsled board --open # open or reuse the caller’s tab split
|
|
590
|
+
dogsled board --side --owner "$HERDR_PANE_ID" # print once
|
|
591
|
+
herdr plugin pane open --plugin dogsled --entrypoint board --direction right --no-focus
|
|
530
592
|
```
|
|
531
593
|
|
|
532
|
-
The
|
|
594
|
+
The split runs `dogsled board --side --watch` and refreshes every ten seconds. `--owner` defaults to the opening pane from Herdr’s plugin context.
|
|
595
|
+
Quotas come only from `quota.json`; the board never calls a provider or reads credentials. The heading shows cache age and `STALE` after fifteen minutes.
|
|
596
|
+
|
|
597
|
+
Pi renders each new todo revision through pi-todo’s `display.createView(host).render(width)`. Dogsled never reads or copies task state.
|
|
598
|
+
The board publishes its width in the ledger; before that, Pi uses 48 columns. Resizing republishes the same provider view at the new width.
|
|
599
|
+
Pi atomically writes `{session, branch, revision, current, pane, width, lines}` to `todo-lines/<pane-hash>.json` in Dogsled’s state directory.
|
|
600
|
+
The service reads files for live agent panes into `todos.json`. Peers expose this presentation through `dogsled host todos --json`.
|
|
601
|
+
The board shows each agent’s current line and prints the owner’s full provider-rendered lines unchanged, including ANSI styles. Missing presentations show as unavailable.
|
|
602
|
+
Session shutdown and provider release remove the pane’s publication. `/dogsled` remains the interactive control panel in both display modes.
|
|
603
|
+
|
|
604
|
+
Herdr 0.9.5 creates a new pane on every plugin open. Dogsled keeps a small `boards/<tab-hash>.json` registry keyed by Herdr tab ID.
|
|
605
|
+
It stores the board pane and terminal IDs, verifies them against live panes before reuse, and removes a stale entry before opening another split.
|
|
533
606
|
All three harness packages share `plugins/dogsled/skills/dogsled/SKILL.md`. It describes delegation, jobs, messages, and the queue.
|
|
534
607
|
|
|
535
608
|
## Build and development
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oisin-ee/pi-dogsled",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.18.0",
|
|
4
4
|
"description": "Pi extension for dogsled: the board, the /dogsled panel, the inbox reader, and the dogsled tools. Needs the dogsled binary of the same version.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
package/pi/board.ts
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
// from `dogsled board --json`; this file only lays it out for a terminal width.
|
|
3
3
|
import type { ThemeColor } from "@earendil-works/pi-coding-agent";
|
|
4
4
|
import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
|
|
5
|
+
import { createConnection } from "node:net";
|
|
6
|
+
|
|
7
|
+
/** A stale socket path is not a running Herdr session. Never probe outside Herdr. */
|
|
8
|
+
export async function herdrAvailable(env: NodeJS.ProcessEnv = process.env): Promise<boolean> {
|
|
9
|
+
const path = env["HERDR_SOCKET_PATH"];
|
|
10
|
+
if (env["HERDR_ENV"] !== "1" || !path) return false;
|
|
11
|
+
return new Promise(resolve => {
|
|
12
|
+
const socket = createConnection(path);
|
|
13
|
+
const finish = (available: boolean) => { socket.destroy(); resolve(available); };
|
|
14
|
+
socket.once("connect", () => finish(true));
|
|
15
|
+
socket.once("error", () => finish(false));
|
|
16
|
+
socket.setTimeout(1_000, () => finish(false));
|
|
17
|
+
});
|
|
18
|
+
}
|
|
5
19
|
|
|
6
20
|
export type Group = "to_land" | "attention" | "running" | "waiting";
|
|
7
21
|
|
package/pi/inbox.ts
CHANGED
|
@@ -26,6 +26,8 @@ interface Claimed extends Delivered {
|
|
|
26
26
|
}
|
|
27
27
|
|
|
28
28
|
type Exec = (args: string[]) => Promise<string>;
|
|
29
|
+
export type WatchDirectory = (dir: string, listener: (event: string, name: string | null) => void) => FSWatcher;
|
|
30
|
+
const watchDirectory: WatchDirectory = (dir, listener) => watch(dir, { persistent: false }, listener);
|
|
29
31
|
|
|
30
32
|
function parseClaimed(stdout: string): Claimed[] {
|
|
31
33
|
const value: unknown = JSON.parse(stdout);
|
|
@@ -58,10 +60,12 @@ export class InboxReader {
|
|
|
58
60
|
|
|
59
61
|
private readonly pi: Pick<ExtensionAPI, "sendMessage">;
|
|
60
62
|
private readonly exec: Exec;
|
|
63
|
+
private readonly watchDirectory: WatchDirectory;
|
|
61
64
|
|
|
62
|
-
constructor(pi: Pick<ExtensionAPI, "sendMessage">, exec: Exec) {
|
|
65
|
+
constructor(pi: Pick<ExtensionAPI, "sendMessage">, exec: Exec, watchInbox: WatchDirectory = watchDirectory) {
|
|
63
66
|
this.pi = pi;
|
|
64
67
|
this.exec = exec;
|
|
68
|
+
this.watchDirectory = watchInbox;
|
|
65
69
|
}
|
|
66
70
|
|
|
67
71
|
/** Register as this pane's reader, deliver what is waiting, and watch for more. */
|
|
@@ -74,7 +78,7 @@ export class InboxReader {
|
|
|
74
78
|
if (typeof where.dir !== "string" || typeof where.file !== "string") throw new Error("dogsled inbox path returned no dir or file");
|
|
75
79
|
const file = where.file;
|
|
76
80
|
// Each write replaces the file, so the directory is watched, not the file.
|
|
77
|
-
this.watcher =
|
|
81
|
+
this.watcher = this.watchDirectory(where.dir, (_event, name) => {
|
|
78
82
|
if (name === file) void this.drain(ctx);
|
|
79
83
|
});
|
|
80
84
|
this.watcher.on("error", () => { this.watcher?.close(); this.watcher = undefined; });
|
package/pi/index.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { readFileSync } from "node:fs";
|
|
2
2
|
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
3
3
|
import { Box, Text, Key } from "@earendil-works/pi-tui";
|
|
4
|
-
import { type Board, clean, parseBoard } from "./board.ts";
|
|
5
|
-
import { WorkTodo } from "./work-todo.ts";
|
|
4
|
+
import { type Board, clean, parseBoard, herdrAvailable } from "./board.ts";
|
|
5
|
+
import { WorkTodo, TodoPublisher } from "./work-todo.ts";
|
|
6
6
|
import { UnitBridge } from "./unit-bridge.ts";
|
|
7
7
|
import { workBoard, workText, type WorkState } from "./work.ts";
|
|
8
8
|
import { type Details, InboxReader, MESSAGE_TYPE } from "./inbox.ts";
|
|
@@ -74,10 +74,30 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
74
74
|
let workAbort: AbortController | undefined;
|
|
75
75
|
let context: ExtensionContext | undefined;
|
|
76
76
|
let requestWorkRender: (() => void) | undefined;
|
|
77
|
-
|
|
77
|
+
let sideDisplay = false;
|
|
78
|
+
let publicationFailure: string | undefined;
|
|
79
|
+
const publisher = new TodoPublisher(owner ?? "", error => context?.ui.notify(`Todo publication failed: ${String(error)}`, "error"));
|
|
80
|
+
const todos = new WorkTodo(pi.events, () => {
|
|
81
|
+
if (context) { publishTodos(context); draw(context); }
|
|
82
|
+
}, () => {
|
|
78
83
|
if (context) void openWork(context, "todos").catch(error => context?.ui.notify(String(error), "error"));
|
|
79
84
|
});
|
|
80
85
|
|
|
86
|
+
function publishTodos(ctx: ExtensionContext): void {
|
|
87
|
+
if (!owner) return;
|
|
88
|
+
try { publisher.publish(todos.current, ctx.ui.theme); }
|
|
89
|
+
catch (error) { ctx.ui.notify(`Todo publication failed: ${String(error)}`, "error"); }
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
async function publication(ctx: ExtensionContext): Promise<void> {
|
|
93
|
+
if (!owner) return;
|
|
94
|
+
const current = generation;
|
|
95
|
+
const location: unknown = JSON.parse(await exec(["board", "--todo-path", "--owner", owner, "--json"]));
|
|
96
|
+
if (current !== generation) return;
|
|
97
|
+
publisher.configure(location);
|
|
98
|
+
publishTodos(ctx);
|
|
99
|
+
}
|
|
100
|
+
|
|
81
101
|
function state(): WorkState {
|
|
82
102
|
return { board, todo: todos.current, error: failure ?? todos.error };
|
|
83
103
|
}
|
|
@@ -97,6 +117,7 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
97
117
|
}
|
|
98
118
|
|
|
99
119
|
async function openWork(ctx: ExtensionContext, tab: WorkTab): Promise<void> {
|
|
120
|
+
if (sideDisplay && owner) { await exec(["board", "--open", "--owner", owner, "--json"]); return; }
|
|
100
121
|
if (ctx.mode !== "tui") { ctx.ui.notify(workText(state()), "info"); return; }
|
|
101
122
|
if (panelOpen) return;
|
|
102
123
|
workOpen = true;
|
|
@@ -136,7 +157,7 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
136
157
|
}
|
|
137
158
|
|
|
138
159
|
function draw(ctx: ExtensionContext) {
|
|
139
|
-
if (ctx.mode !== "tui") return;
|
|
160
|
+
if (ctx.mode !== "tui" || sideDisplay) return;
|
|
140
161
|
workPanel?.update(workData());
|
|
141
162
|
const data = state();
|
|
142
163
|
if (panelOpen || (!workOpen && !data.board.rows.length && (!data.todo || data.todo.display.empty) && !data.error)) {
|
|
@@ -174,6 +195,13 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
174
195
|
await inbox.drain(ctx);
|
|
175
196
|
try { await units.ready(ctx); await units.drain(ctx); } catch (error) { ctx.ui.notify(`Dogsled settlement delivery pending: ${String(error)}`, "warning"); }
|
|
176
197
|
if (ctx.mode !== "tui") return;
|
|
198
|
+
try { await publication(ctx); publicationFailure = undefined; }
|
|
199
|
+
catch (error) {
|
|
200
|
+
const text = `Todo publication unavailable: ${String(error)}`;
|
|
201
|
+
if (text !== publicationFailure) ctx.ui.notify(text, "warning");
|
|
202
|
+
publicationFailure = text;
|
|
203
|
+
}
|
|
204
|
+
if (current !== generation || sideDisplay) return;
|
|
177
205
|
try {
|
|
178
206
|
const next = parseBoard(JSON.parse(await exec(["board", "--json"])));
|
|
179
207
|
if (current !== generation) return;
|
|
@@ -197,9 +225,24 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
197
225
|
return refresh;
|
|
198
226
|
}
|
|
199
227
|
|
|
228
|
+
/** Dogsled answers `skipped` for a pane it launched: a child keeps the widget path. */
|
|
229
|
+
async function openSide(ctx: ExtensionContext): Promise<boolean> {
|
|
230
|
+
if (!owner) return false;
|
|
231
|
+
try {
|
|
232
|
+
const opened: unknown = JSON.parse(await exec(["board", "--open", "--owner", owner, "--json"]));
|
|
233
|
+
return typeof opened === "object" && opened !== null && typeof (opened as Record<string, unknown>)["pane_id"] === "string";
|
|
234
|
+
} catch (error) {
|
|
235
|
+
ctx.ui.notify(`Dogsled side board unavailable: ${String(error)}`, "error");
|
|
236
|
+
return false;
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
|
|
200
240
|
pi.on("session_start", async (event, ctx) => {
|
|
201
241
|
units.start(event.reason);
|
|
202
|
-
|
|
242
|
+
const wasSide = sideDisplay;
|
|
243
|
+
sideDisplay = Boolean(owner) && ctx.mode === "tui" && await herdrAvailable() && await openSide(ctx);
|
|
244
|
+
if (ctx.mode === "tui" && (!sideDisplay || (!wasSide && requestWorkRender))) ctx.ui.setWidget("dogsled", undefined);
|
|
245
|
+
await publisher.clear();
|
|
203
246
|
requestWorkRender = undefined;
|
|
204
247
|
workPanel?.dispose();
|
|
205
248
|
if (timer) clearInterval(timer);
|
|
@@ -227,7 +270,7 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
227
270
|
}
|
|
228
271
|
await update(ctx);
|
|
229
272
|
});
|
|
230
|
-
pi.on("session_shutdown", (_event, ctx) => {
|
|
273
|
+
pi.on("session_shutdown", async (_event, ctx) => {
|
|
231
274
|
units.stop();
|
|
232
275
|
workPanel?.dispose();
|
|
233
276
|
generation++;
|
|
@@ -241,8 +284,9 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
241
284
|
timer = undefined;
|
|
242
285
|
inbox.stop();
|
|
243
286
|
todos.stop();
|
|
287
|
+
await publisher.clear();
|
|
244
288
|
context = undefined;
|
|
245
|
-
if (ctx.mode === "tui") ctx.ui.setWidget("dogsled", undefined);
|
|
289
|
+
if (ctx.mode === "tui" && !sideDisplay) ctx.ui.setWidget("dogsled", undefined);
|
|
246
290
|
});
|
|
247
291
|
// A delivered message is in the transcript once Pi ends it: only then is it acknowledged.
|
|
248
292
|
pi.on("message_end", async event => { await inbox.ended(event.message); });
|
|
@@ -251,7 +295,10 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
251
295
|
try { await units.settled(ctx); } catch (error) { ctx.ui.notify(`Dogsled unit acknowledgement pending: ${String(error)}`, "warning"); }
|
|
252
296
|
});
|
|
253
297
|
pi.on("agent_before_settle", async event => {
|
|
254
|
-
|
|
298
|
+
// `context.canContinue` describes the transcript before this handler's entries. A normal stop
|
|
299
|
+
// ends on the assistant, so it is false; the appended reminder is user context and makes the
|
|
300
|
+
// continuation valid. The gate must run on every completed stop: it also requests the sweep.
|
|
301
|
+
if (!owner || event.outcome !== "completed" || event.continue) return;
|
|
255
302
|
// The Rust gate owns selection and durable deduplication across all harnesses.
|
|
256
303
|
const result = await pi.exec(binary, ["hook", "gate"], { timeout: 6_000 });
|
|
257
304
|
if (result.code !== 0) throw new Error(`dogsled stop gate failed: ${result.stderr.trim() || `exit ${result.code}`}`);
|
package/pi/work-todo.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { rename, rm, writeFile } from "node:fs/promises";
|
|
3
4
|
|
|
4
5
|
/** The provider owns rendering and state interpretation; this is an in-process capability. */
|
|
5
6
|
export interface TodoViewHost {
|
|
@@ -33,6 +34,72 @@ export interface TodoSnapshot {
|
|
|
33
34
|
display: TodoDisplay;
|
|
34
35
|
}
|
|
35
36
|
|
|
37
|
+
export interface TodoLines {
|
|
38
|
+
session: string;
|
|
39
|
+
branch: string | null;
|
|
40
|
+
revision: number;
|
|
41
|
+
current: string;
|
|
42
|
+
pane: string;
|
|
43
|
+
width: number;
|
|
44
|
+
lines: string[];
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Serialize only the provider's presentation. Never inspect its opaque state. */
|
|
48
|
+
export function renderTodoLines(next: TodoSnapshot, pane: string, host: TodoViewHost, width = 48): TodoLines {
|
|
49
|
+
const view = next.display.createView(host);
|
|
50
|
+
try {
|
|
51
|
+
const lines = view.render(width);
|
|
52
|
+
if (!Array.isArray(lines) || !lines.every(line => typeof line === "string")) throw new Error("Invalid todo render output");
|
|
53
|
+
return { session: next.session, branch: next.branch, revision: next.revision, current: next.display.current, pane, width, lines };
|
|
54
|
+
} finally { view.dispose(); }
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Atomic per-pane publication into Dogsled's ledger. One ordered writer per Pi session. */
|
|
58
|
+
export class TodoPublisher {
|
|
59
|
+
private path: string | undefined;
|
|
60
|
+
private width = 48;
|
|
61
|
+
private height = 10_000;
|
|
62
|
+
private published: TodoSnapshot | undefined;
|
|
63
|
+
private queue = Promise.resolve();
|
|
64
|
+
private readonly pane: string;
|
|
65
|
+
private readonly failed: (error: unknown) => void;
|
|
66
|
+
constructor(pane: string, failed: (error: unknown) => void) { this.pane = pane; this.failed = failed; }
|
|
67
|
+
|
|
68
|
+
configure(value: unknown): void {
|
|
69
|
+
if (!record(value) || typeof value["path"] !== "string"
|
|
70
|
+
|| !Number.isInteger(value["width"]) || Number(value["width"]) < 1 || Number(value["width"]) > 65535
|
|
71
|
+
|| !Number.isInteger(value["height"]) || Number(value["height"]) < 1 || Number(value["height"]) > 10_000) throw new Error("Invalid todo publication path");
|
|
72
|
+
if (this.path !== value["path"] || this.width !== value["width"] || this.height !== value["height"]) this.published = undefined;
|
|
73
|
+
this.path = value["path"];
|
|
74
|
+
this.width = Number(value["width"]);
|
|
75
|
+
this.height = Number(value["height"]);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
publish(next: TodoSnapshot | undefined, theme: TodoViewHost["theme"]): void {
|
|
79
|
+
const path = this.path;
|
|
80
|
+
if (!path || (next && next === this.published)) return;
|
|
81
|
+
// Render now, while this revision still owns the provider capability.
|
|
82
|
+
const payload = next ? renderTodoLines(next, this.pane, { theme, height: () => this.height, requestRender() {} }, this.width) : undefined;
|
|
83
|
+
this.published = next;
|
|
84
|
+
this.queue = this.queue.then(async () => {
|
|
85
|
+
if (!payload) { await rm(path, { force: true }); return; }
|
|
86
|
+
const temporary = `${path}.${randomUUID()}.tmp`;
|
|
87
|
+
try {
|
|
88
|
+
await writeFile(temporary, JSON.stringify(payload), { flag: "wx", mode: 0o600 });
|
|
89
|
+
await rename(temporary, path);
|
|
90
|
+
} finally { await rm(temporary, { force: true }); }
|
|
91
|
+
}).catch(error => { this.published = undefined; this.failed(error); });
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
async clear(): Promise<void> {
|
|
95
|
+
const path = this.path;
|
|
96
|
+
this.published = undefined;
|
|
97
|
+
this.queue = this.queue.then(async () => { if (path) await rm(path, { force: true }); }).catch(this.failed);
|
|
98
|
+
await this.queue;
|
|
99
|
+
}
|
|
100
|
+
async flushed(): Promise<void> { await this.queue; }
|
|
101
|
+
}
|
|
102
|
+
|
|
36
103
|
type Bus = ExtensionAPI["events"];
|
|
37
104
|
function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null; }
|
|
38
105
|
function isDisplay(value: unknown): boolean {
|
|
@@ -52,12 +52,11 @@ dogsled inbox list
|
|
|
52
52
|
|
|
53
53
|
## Closing
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
`done` means your work is finished: hand it back, release your resources, and end your agent. Call it during the final working turn, after committing changes. The child host captures your reply and closes your pane and agent worktree when the turn ends. Your branch stays for the owner to land. Closed children remain under TO LAND until integration or branch deletion.
|
|
56
56
|
|
|
57
|
-
|
|
58
|
-
- a writer closes once its branch has landed. Until then it shows under TO LAND: merge or drop the branch.
|
|
57
|
+
`done` refuses open children, queued tickets, dirty agent worktrees, and removal that loses content with the branch kept. New inbox work during the same working turn cancels the mark. After the turn ends, messages fail with `<name> finished; start a new child for more work`.
|
|
59
58
|
|
|
60
|
-
|
|
59
|
+
Without its own `done`, a child stays open. Questions and orchestration do not authorize closure. Busy panes and the caller never close automatically. Shared worktrees stay. A primary pane stays if its closure would close linked workspaces.
|
|
61
60
|
|
|
62
61
|
When you are a child, call `done` once, in the turn that completes your whole task, then end the turn with your final reply. Do not call it when you ask a question or wait for your own children; `done` is refused while you own open children or queued work. To end a child now:
|
|
63
62
|
|