pi-cowboy 0.15.2 → 0.17.2

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.
Files changed (221) hide show
  1. package/README.md +12 -9
  2. package/dist/agents/agent-assets.d.ts +114 -0
  3. package/dist/agents/agent-assets.js +42 -29
  4. package/dist/agents/agent-cleanup.d.ts +82 -0
  5. package/dist/agents/agent-cleanup.js +6 -6
  6. package/dist/agents/agent-discovery.d.ts +22 -0
  7. package/dist/agents/agent-discovery.js +7 -3
  8. package/dist/agents/agent-host.d.ts +212 -0
  9. package/dist/agents/agent-host.js +6 -3
  10. package/dist/agents/agent-manager.d.ts +99 -0
  11. package/dist/agents/agent-manager.js +21 -9
  12. package/dist/agents/agent-reviver.d.ts +38 -0
  13. package/dist/agents/agent-runner.d.ts +51 -0
  14. package/dist/agents/agent-runner.js +22 -31
  15. package/dist/agents/agent-spawn-store.d.ts +39 -0
  16. package/dist/agents/agent-template.d.ts +118 -0
  17. package/dist/agents/agent-template.js +7 -3
  18. package/dist/agents/agent-types.d.ts +59 -0
  19. package/dist/agents/agent-types.js +22 -6
  20. package/dist/agents/batch.d.ts +63 -0
  21. package/dist/agents/cleanup-policy.d.ts +288 -0
  22. package/dist/agents/cleanup-policy.js +2 -2
  23. package/dist/agents/cleanup-report.d.ts +14 -0
  24. package/dist/agents/default-agents.d.ts +8 -0
  25. package/dist/agents/harness/claude/index.d.ts +41 -0
  26. package/dist/agents/harness/claude/index.js +49 -7
  27. package/dist/agents/harness/claude/staging.d.ts +46 -0
  28. package/dist/agents/harness/claude/staging.js +3 -2
  29. package/dist/agents/harness/codex.d.ts +42 -0
  30. package/dist/agents/harness/codex.js +3 -4
  31. package/dist/agents/harness/harness-registry.d.ts +126 -0
  32. package/dist/agents/harness/harness-registry.js +272 -0
  33. package/dist/agents/harness/opencode/config.d.ts +39 -0
  34. package/dist/agents/harness/opencode/config.js +85 -0
  35. package/dist/agents/harness/opencode/definition.d.ts +21 -0
  36. package/dist/agents/harness/opencode/index.d.ts +33 -0
  37. package/dist/agents/harness/opencode/index.js +22 -7
  38. package/dist/agents/harness/opencode/permissions.d.ts +27 -0
  39. package/dist/agents/harness/opencode/staging.d.ts +50 -0
  40. package/dist/agents/harness/opencode/staging.js +17 -3
  41. package/dist/agents/harness/opencode/user-config.d.ts +36 -0
  42. package/dist/agents/harness/opencode/user-config.js +172 -0
  43. package/dist/agents/harness/opencode/version.d.ts +36 -0
  44. package/dist/agents/harness/pane-launcher.d.ts +89 -0
  45. package/dist/agents/harness/pane-launcher.js +23 -22
  46. package/dist/agents/harness/pi-bolt.d.ts +9 -0
  47. package/dist/agents/harness/pi-bolt.js +0 -1
  48. package/dist/agents/harness/pi-compatible.d.ts +48 -0
  49. package/dist/agents/harness/pi-compatible.js +3 -4
  50. package/dist/agents/harness/pig.d.ts +10 -0
  51. package/dist/agents/harness/pig.js +0 -1
  52. package/dist/agents/harness.d.ts +459 -0
  53. package/dist/agents/harness.js +46 -57
  54. package/dist/agents/multiplexer-registry.d.ts +101 -0
  55. package/dist/agents/multiplexer-registry.js +125 -0
  56. package/dist/agents/result-file-permissions.d.ts +19 -0
  57. package/dist/agents/run-state.d.ts +144 -0
  58. package/dist/agents/schemas/cleanup-batch.schema.d.ts +17 -0
  59. package/dist/agents/schemas/cowboy-agents.schema.d.ts +51 -0
  60. package/dist/agents/schemas/cowboy-agents.schema.js +1 -1
  61. package/dist/agents/schemas/merge-batch.schema.d.ts +21 -0
  62. package/dist/agents/schemas/steer-batch.schema.d.ts +19 -0
  63. package/dist/agents/schemas/stop-batch.schema.d.ts +16 -0
  64. package/dist/agents/spawn-defaults.d.ts +48 -0
  65. package/dist/agents/spawn-defaults.js +22 -21
  66. package/dist/agents/subagent-session.d.ts +161 -0
  67. package/dist/agents/subagent-session.js +10 -5
  68. package/dist/agents/tool-cleanup.d.ts +43 -0
  69. package/dist/agents/tool-execution.d.ts +61 -0
  70. package/dist/agents/tool-merge.d.ts +64 -0
  71. package/dist/agents/tool-result.d.ts +21 -0
  72. package/dist/agents/tool-steer.d.ts +40 -0
  73. package/dist/agents/types.d.ts +94 -0
  74. package/dist/availability.d.ts +42 -0
  75. package/dist/concurrency-pools.d.ts +168 -0
  76. package/dist/concurrency-pools.js +11 -9
  77. package/dist/config/concurrency-limit.d.ts +12 -0
  78. package/dist/config/config-io.d.ts +59 -0
  79. package/dist/config/config-io.js +12 -20
  80. package/dist/config/config-store.d.ts +201 -0
  81. package/dist/config/config-store.js +89 -42
  82. package/dist/config/config-validation.d.ts +7 -0
  83. package/dist/config/config-validation.js +90 -63
  84. package/dist/config/layered-config.d.ts +47 -0
  85. package/dist/config/layered-config.js +4 -0
  86. package/dist/config/types.d.ts +8 -0
  87. package/dist/cow-support-launch.d.ts +18 -0
  88. package/dist/events.d.ts +9 -0
  89. package/dist/events.js +71 -19
  90. package/dist/extension-toggle.d.ts +13 -0
  91. package/dist/harness-availability-launch.d.ts +47 -0
  92. package/dist/harness-availability-launch.js +48 -33
  93. package/dist/host-multiplexer.d.ts +42 -0
  94. package/dist/host-multiplexer.js +62 -0
  95. package/dist/index.d.ts +10 -0
  96. package/dist/index.js +5 -16
  97. package/dist/infrastructure/exec-path.d.ts +13 -0
  98. package/dist/infrastructure/exec-sync.d.ts +18 -0
  99. package/dist/infrastructure/git/cow-clone.d.ts +111 -0
  100. package/dist/infrastructure/git/git-materializer.d.ts +146 -0
  101. package/dist/infrastructure/git/git-merger.d.ts +111 -0
  102. package/dist/infrastructure/git/git-merger.js +1 -1
  103. package/dist/infrastructure/git/git-retention.d.ts +21 -0
  104. package/dist/infrastructure/git/git-runner.d.ts +89 -0
  105. package/dist/infrastructure/git/git-worktree.d.ts +86 -0
  106. package/dist/infrastructure/git/index.d.ts +11 -0
  107. package/dist/infrastructure/git-client.d.ts +11 -0
  108. package/dist/infrastructure/herdr/agent-stopper.d.ts +33 -0
  109. package/dist/infrastructure/herdr/agents.d.ts +124 -0
  110. package/dist/infrastructure/herdr/agents.js +1 -1
  111. package/dist/infrastructure/herdr/herdr-client.d.ts +23 -0
  112. package/dist/infrastructure/herdr/herdr-transport.d.ts +57 -0
  113. package/dist/infrastructure/herdr/index.d.ts +15 -0
  114. package/dist/infrastructure/herdr/panes.d.ts +82 -0
  115. package/dist/infrastructure/herdr/polling.d.ts +41 -0
  116. package/dist/infrastructure/herdr/worktrees.d.ts +32 -0
  117. package/dist/infrastructure/herdr-client.d.ts +6 -0
  118. package/dist/infrastructure/herdr-host.d.ts +11 -0
  119. package/dist/infrastructure/herdr-host.js +55 -5
  120. package/dist/logger.d.ts +13 -0
  121. package/dist/models/foreign-model-resolver.d.ts +39 -0
  122. package/dist/models/model-groups.d.ts +56 -0
  123. package/dist/models/model-precedence.d.ts +135 -0
  124. package/dist/models/model-precedence.js +20 -7
  125. package/dist/models/model-request-types.d.ts +51 -0
  126. package/dist/models/model-request.d.ts +47 -0
  127. package/dist/models/pi-model-resolver.d.ts +35 -0
  128. package/dist/orchestrators/briefing-section.d.ts +9 -0
  129. package/dist/orchestrators/context.d.ts +143 -0
  130. package/dist/orchestrators/context.js +7 -1
  131. package/dist/orchestrators/cues.d.ts +31 -0
  132. package/dist/orchestrators/default-orchestrators.d.ts +10 -0
  133. package/dist/orchestrators/default-orchestrators.js +7 -2
  134. package/dist/orchestrators/orchestrator-discovery.d.ts +27 -0
  135. package/dist/orchestrators/orchestrator-template.d.ts +22 -0
  136. package/dist/orchestrators/orchestrator-types.d.ts +30 -0
  137. package/dist/orchestrators/protocol.d.ts +119 -0
  138. package/dist/orchestrators/protocol.js +7 -5
  139. package/dist/orchestrators/types.d.ts +18 -0
  140. package/dist/paths.d.ts +49 -0
  141. package/dist/paths.js +1 -1
  142. package/dist/pi-settings.d.ts +3 -0
  143. package/dist/plugin/contract.d.ts +56 -0
  144. package/dist/plugin/contract.js +17 -0
  145. package/dist/plugin/discovery.d.ts +59 -0
  146. package/dist/plugin/discovery.js +67 -0
  147. package/dist/plugin/index.d.ts +16 -0
  148. package/dist/plugin/index.js +14 -0
  149. package/dist/plugin/loader.d.ts +52 -0
  150. package/dist/plugin/loader.js +181 -0
  151. package/dist/plugin/manifest.d.ts +25 -0
  152. package/dist/plugin/manifest.js +47 -0
  153. package/dist/predicates.d.ts +18 -0
  154. package/dist/prompt/prompts.d.ts +40 -0
  155. package/dist/prompt/skill-loader.d.ts +28 -0
  156. package/dist/prompt/subagent-system-prompt.d.ts +50 -0
  157. package/dist/registration.d.ts +43 -0
  158. package/dist/registration.js +15 -3
  159. package/dist/session-runtime.d.ts +43 -0
  160. package/dist/session-runtime.js +92 -0
  161. package/dist/shell.d.ts +151 -0
  162. package/dist/shell.js +30 -5
  163. package/dist/spawn/cow-support.d.ts +26 -0
  164. package/dist/spawn/crockford-base32.d.ts +46 -0
  165. package/dist/spawn/crockford-base32.js +2 -2
  166. package/dist/spawn/herdr-launcher.d.ts +33 -0
  167. package/dist/spawn/repo-lock.d.ts +21 -0
  168. package/dist/spawn/sandbox.d.ts +130 -0
  169. package/dist/spawn/sandbox.js +3 -3
  170. package/dist/spawn/spawn-coordinator.d.ts +80 -0
  171. package/dist/spawn/spawn-coordinator.js +1 -1
  172. package/dist/spawn/spawn-id.d.ts +23 -0
  173. package/dist/spawn/worktree-policy.d.ts +68 -0
  174. package/dist/status-note.d.ts +7 -0
  175. package/dist/subagent/deliverable.d.ts +40 -0
  176. package/dist/subagent/pane-supervisor.d.ts +33 -0
  177. package/dist/subagent/pane-supervisor.js +1 -1
  178. package/dist/subagent/result-artifacts.d.ts +16 -0
  179. package/dist/subagent/supervisor.d.ts +157 -0
  180. package/dist/subagent/supervisor.js +4 -4
  181. package/dist/task-registry.d.ts +88 -0
  182. package/dist/task-registry.js +3 -3
  183. package/dist/templates/template-files.d.ts +35 -0
  184. package/dist/templates/template-files.js +8 -4
  185. package/dist/types.d.ts +268 -0
  186. package/dist/ui/action-report.d.ts +29 -0
  187. package/dist/ui/format.d.ts +17 -0
  188. package/dist/ui/indicator.d.ts +194 -0
  189. package/dist/ui/menu/helpers.d.ts +95 -0
  190. package/dist/ui/menu/menu-agent-settings.d.ts +8 -0
  191. package/dist/ui/menu/menu-agent-settings.js +18 -10
  192. package/dist/ui/menu/menu-agent-status-cleanup.d.ts +46 -0
  193. package/dist/ui/menu/menu-agent-status.d.ts +20 -0
  194. package/dist/ui/menu/menu-concurrency.d.ts +8 -0
  195. package/dist/ui/menu/menu-concurrency.js +11 -8
  196. package/dist/ui/menu/menu-model-settings.d.ts +30 -0
  197. package/dist/ui/menu/menu-model-settings.js +7 -5
  198. package/dist/ui/menu/menu-spawn-defaults.d.ts +20 -0
  199. package/dist/ui/menu/menu-spawn-wizard.d.ts +7 -0
  200. package/dist/ui/menu/menu-spawn-worktree.d.ts +46 -0
  201. package/dist/ui/menu/menu-system-prompt.d.ts +6 -0
  202. package/dist/ui/menu/menu-worktree-command.d.ts +17 -0
  203. package/dist/ui/menu/menus.d.ts +23 -0
  204. package/dist/ui/menu/model-picker.d.ts +19 -0
  205. package/dist/ui/menu/model-picker.js +2 -3
  206. package/dist/ui/menu/screen-host.d.ts +88 -0
  207. package/dist/ui/menu/submenus/confirm.d.ts +27 -0
  208. package/dist/ui/menu/submenus/model-select.d.ts +38 -0
  209. package/dist/ui/menu/submenus/name-field.d.ts +30 -0
  210. package/dist/ui/menu/submenus/numeric-input.d.ts +26 -0
  211. package/dist/ui/menu/submenus/target-select.d.ts +92 -0
  212. package/dist/ui/menu/submenus/text-editor.d.ts +42 -0
  213. package/dist/ui/menu/submenus/worktree-command-name.d.ts +40 -0
  214. package/dist/ui/menu/submenus/worktree-name.d.ts +39 -0
  215. package/dist/ui/menu/wrappers/settings-list.d.ts +41 -0
  216. package/dist/ui/searchable-select.d.ts +38 -0
  217. package/dist/ui/types.d.ts +7 -0
  218. package/dist/utils.d.ts +39 -0
  219. package/package.json +4 -2
  220. package/dist/agents/harness/registry.js +0 -76
  221. package/dist/agents/harness-family.js +0 -23
package/README.md CHANGED
@@ -12,6 +12,8 @@
12
12
 
13
13
  Each agent runs in its own terminal pane inside [Herdr](https://github.com/electric-dragon-80000v/herdr) and works in an isolated copy-on-write Git worktree. You can watch agents work in real time, jump into any pane to steer them, or mix and match harnesses like Pi, Claude Code, OpenCode, and Codex in the same session. When the work is finished, `pi-cowboy` cleans up the leftovers for you.
14
14
 
15
+ Check out the [demo](https://electric-dragon-80000v.github.io/pi-cowboy/).
16
+
15
17
  ## Why should I use it?
16
18
 
17
19
  ### Focused tasks produce better code
@@ -26,7 +28,7 @@ Give each agent a smaller, isolated subtask. A single task with clear instructio
26
28
 
27
29
  Multiple agents can edit, build, and run tests at the same time without interfering with each other. Copy-on-write worktrees make high parallelism practical by keeping disk usage small even when your repository is in the magnitude of gigabytes.
28
30
 
29
- The numbers below come from a Git repository with 153,607 files in total (479 MiB tracked, 27 GiB total including untracked files):
31
+ The numbers below come from a Git repository on macOS with 153,607 files in total (479 MiB tracked, 27 GiB total including untracked files):
30
32
 
31
33
  | Method | Including untracked | Size on disk |
32
34
  | ---------------------------------------------- | ------------------- | ------------ |
@@ -193,7 +195,7 @@ When `pi-cowboy` spawns an agent, it picks the model using the first match in th
193
195
  2. The session per-type model override (`/cowboy` > `Model overrides`)
194
196
  3. The config per-type override (`agent.<agent-type>`)
195
197
  4. The model set in the [agent template](docs/Agent%20Templates.md) for the launching harness family
196
- 5. The session default model (`/cowboy model`)
198
+ 5. The Pi-family session default model (`/cowboy model`, which picks from Pi's catalogue)
197
199
  6. The launching harness's configured default (`agent.default` for the Pi family, or `agent.defaultModelByHarness` for foreign harnesses)
198
200
  7. For Pi-family launches, the parent session's active model
199
201
 
@@ -228,13 +230,13 @@ Delegates one or more tasks to cowboy agents. By default, the call returns immed
228
230
 
229
231
  Each item in `agents[]` takes:
230
232
 
231
- | Field | Required | Description |
232
- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
233
- | `prompt` | yes | Task instructions for the cowboy agent. |
234
- | `task_name` | yes | Short 2-3-word name (e.g. `"fix login flow"`) used to name the agent's branch, worktree, and tab. |
235
- | `agent_type` | no | Agent template to use. Defaults to the type selected at `/cowboy` > `Agent`. |
236
- | `model` | no | Model for this agent as `"provider/model-id"`. Resolved according to [Model resolution](#model-resolution). |
237
- | `harness_type` | no | Harness that launches this agent: `pi`, `pig`, `pi-bolt`, `opencode`, `codex`, or `claude`. Overrides the agent template's `harness_type` and the `agent.harnessType` setting. If this machine cannot launch the requested harness, the call fails before spawning. |
233
+ | Field | Required | Description |
234
+ | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
235
+ | `prompt` | yes | Task instructions for the cowboy agent. |
236
+ | `task_name` | yes | Short 2-3-word name (e.g. `"fix login flow"`) used to name the agent's branch, worktree, and tab. |
237
+ | `agent_type` | no | Agent template to use. Defaults to the type selected at `/cowboy` > `Agent`. |
238
+ | `model` | no | Model for this agent as `"provider/model-id"`. Resolved according to [Model resolution](#model-resolution). |
239
+ | `harness_type` | no | Harness that launches this agent: `pi`, `pig`, `pi-bolt`, `opencode`, `codex`, `claude`, or a harness a plugin registered in this session. Overrides the agent template's `harness_type` and the `agent.harnessType` setting. If the harness is not registered here, or this machine cannot launch it, the call fails before spawning. |
238
240
 
239
241
  ### `steer_cowboy_agent`
240
242
 
@@ -301,3 +303,4 @@ Yes. You can disable both the cowboy indicator and the grazing cows in `/cowboy`
301
303
  - [Menu](docs/Menu.md)
302
304
  - [Agent Templates](docs/Agent%20Templates.md)
303
305
  - [Orchestrator Templates](docs/Orchestrator%20Templates.md)
306
+ - [Plugins](docs/Plugins.md)
@@ -0,0 +1,114 @@
1
+ /**
2
+ * agent-assets.ts — located-artifacts seam: locate a run's work, then act on it.
3
+ * AgentAssets: locate/observe/deliverable + actuators. AgentAssetsDeps: raw probes it composes.
4
+ * LocateResult: Located (tracked/recovered) | Ambiguous | NotFound.
5
+ * CleanupDeps: injected host/git actuators. PaneRef/LocatedCandidate: addresses.
6
+ * createAgentAssets: bind over probes. createMultiplexerAgentAssets: bind to a session's multiplexer.
7
+ * Authority is per-asset: provenance (worktreeManaged/paneCreated) is memory-only;
8
+ * addresses (workspace/pane/branch/path) are live probes (memory can be stale, not just absent).
9
+ * Unreadable registries degrade to memory's answer, never to absence.
10
+ */
11
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
12
+ import type { AgentSpawn } from "../types.js";
13
+ import type { BranchCleanupResult, DeleteBranchOptions } from "../infrastructure/git-client.js";
14
+ import type { AgentMultiplexer, AgentHost, AgentHostRef, HostObservation, PlacementCatalog, PlacementRecord, PlacementWorktree } from "./agent-host.js";
15
+ import type { AnyHarnessId, HarnessTeardownContext } from "./harness.js";
16
+ import type { CleanupSource, LocatedArtifacts, RecoveredDeliverable } from "./cleanup-policy.js";
17
+ /**
18
+ * Injected host/git actuators. Host ops take the run's address (bound to release/close, never stop); git ops stay path-based (the host never destroys filesystem state).
19
+ * Function-typed properties, not methods: these are bare injected functions, and callers hand them on as values (`deps.isWorktreeDirty`).
20
+ */
21
+ export interface CleanupDeps {
22
+ /** Dirty/unverifiable retention probe. */
23
+ isWorktreeDirty: (worktreePath: string) => Promise<boolean | undefined>;
24
+ /** Filesystem probe (injected; this module never touches the filesystem). */
25
+ worktreeExists: (worktreePath: string) => Promise<boolean>;
26
+ /** Drop the worktree association, returning true only when confirmed gone. */
27
+ removeWorktree: (ref: AgentHostRef) => Promise<boolean>;
28
+ /** Remove a checkout that was never adopted into herdr. */
29
+ removeGitWorktree: (worktreePath: string, repoCwd: string) => Promise<boolean>;
30
+ /** Delete the branch a removed worktree carried once it is merged and unattached. */
31
+ deleteBranch: (options: DeleteBranchOptions) => Promise<BranchCleanupResult>;
32
+ /** Close a self-created placement. */
33
+ closePane: (ref: AgentHostRef) => Promise<void>;
34
+ /**
35
+ * Teardown of the harness state one ended run's pane was prepared with —
36
+ * ordered before any worktree dirty probe, see Harness.teardown. The bound
37
+ * actuator resolves the recorded harness and supplies the pi instance.
38
+ */
39
+ harnessTeardown: (harness: AnyHarnessId, context: HarnessTeardownContext) => Promise<void>;
40
+ }
41
+ export interface PaneRef {
42
+ readonly paneId: string;
43
+ }
44
+ /** One artifact pair answering to a contested id (ambiguity payload). */
45
+ interface LocatedCandidate {
46
+ worktreePath: string;
47
+ branch: string;
48
+ workspaceId?: string;
49
+ }
50
+ /** The located artifacts plus where they came from. */
51
+ export interface Located extends LocatedArtifacts {
52
+ kind: "located";
53
+ /** `tracked` (spawn record named them) or `recovered` (discovery did). */
54
+ source: CleanupSource;
55
+ }
56
+ /** Two artifacts answer to one id. The caller arbitrates; cleanup refuses. */
57
+ export interface Ambiguous {
58
+ kind: "ambiguous";
59
+ id: string;
60
+ candidates: readonly LocatedCandidate[];
61
+ }
62
+ /** Nothing answers to this id (no record, worktree, or proven branch). */
63
+ interface NotFound {
64
+ kind: "not-found";
65
+ id: string;
66
+ }
67
+ export type LocateResult = Located | Ambiguous | NotFound;
68
+ /** The seam: locate an agent's artifacts, then act on them. Injected probes are function-typed properties (see CleanupDeps). */
69
+ export interface AgentAssets extends CleanupDeps {
70
+ /**
71
+ * The multiplexer every address this seam builds belongs to (see hostRefFor in
72
+ * agent-cleanup.ts). It rides here rather than on `CleanupDeps` because only
73
+ * the locator produces addresses; the allocation-failure path consumes them.
74
+ */
75
+ multiplexer: AgentMultiplexer;
76
+ /** Run's deliverable, derived from the id alone without probing the run; reported, never deleted. */
77
+ deliverable: (id: string) => RecoveredDeliverable;
78
+ /** Locate one agent's artifacts (hint, else discovery); never stops anything — the pane is an address, not a process. */
79
+ locate(id: string, hint?: AgentSpawn): Promise<LocateResult>;
80
+ /** Raw liveness read: undefined = gone, a throw = unreadable (never evidence the run is over); no settlement verdict. */
81
+ observe(pane: PaneRef): Promise<HostObservation | undefined>;
82
+ }
83
+ /** Raw single-plane probes; matching/authority/ambiguity stay in this module so tests fake the planes. Injected probes are function-typed properties (see CleanupDeps). */
84
+ export interface AgentAssetsDeps extends CleanupDeps {
85
+ /** The multiplexer every address this seam builds belongs to. */
86
+ multiplexer: AgentMultiplexer;
87
+ /** Canonicalize a path the way the multiplexer spells its placements (see PlacementCatalog). */
88
+ canonicalizePath: (value: string) => string;
89
+ /** Run's deliverable and whether it exists. */
90
+ deliverable: (id: string) => RecoveredDeliverable;
91
+ /** Raw multiplexer registry read (the multiplexer's `worktree list`); a throw degrades discovery. */
92
+ listWorktrees: () => Promise<readonly PlacementWorktree[]>;
93
+ /** Raw multiplexer placement records (the multiplexer's `agent list`), nameless ones included. */
94
+ listPlacements: () => Promise<readonly PlacementRecord[]>;
95
+ /** One pane's raw state; undefined = gone, a throw = unreadable. */
96
+ readPane(paneId: string): Promise<HostObservation | undefined>;
97
+ /** The worktree root extension worktrees live under; undefined = unresolvable. */
98
+ worktreeRoot(): Promise<string | undefined>;
99
+ /** Entry names directly under `root` (the filesystem fallback). */
100
+ listRootEntries(root: string): Promise<readonly string[]>;
101
+ /** Main-checkout cwd derived from a checkout; undefined = it could not be resolved. */
102
+ resolveRepoCwd(worktreePath: string): Promise<string | undefined>;
103
+ }
104
+ /** Bind the seam over injected probes. */
105
+ export declare function createAgentAssets(deps: AgentAssetsDeps): AgentAssets;
106
+ /**
107
+ * Bind the seam to a session's multiplexer: the multiplexer's own reads come from the
108
+ * runtime's `PlacementCatalog` and its actuators from the runtime's `AgentHost`,
109
+ * so this module names no multiplexer. The rest — git, the filesystem, the config —
110
+ * is multiplexer-neutral and bound here. Failed repo derivation is `undefined` (never
111
+ * a borrowed cwd); failed pane reads throw (unreadable is not gone).
112
+ */
113
+ export declare function createMultiplexerAgentAssets(pi: ExtensionAPI, host: AgentHost, catalog: PlacementCatalog): AgentAssets;
114
+ export {};
@@ -3,7 +3,7 @@
3
3
  * AgentAssets: locate/observe/deliverable + actuators. AgentAssetsDeps: raw probes it composes.
4
4
  * LocateResult: Located (tracked/recovered) | Ambiguous | NotFound.
5
5
  * CleanupDeps: injected host/git actuators. PaneRef/LocatedCandidate: addresses.
6
- * createAgentAssets: bind over probes. createHerdrAgentAssets: bind to the real planes.
6
+ * createAgentAssets: bind over probes. createMultiplexerAgentAssets: bind to a session's multiplexer.
7
7
  * Authority is per-asset: provenance (worktreeManaged/paneCreated) is memory-only;
8
8
  * addresses (workspace/pane/branch/path) are live probes (memory can be stale, not just absent).
9
9
  * Unreadable registries degrade to memory's answer, never to absence.
@@ -11,12 +11,9 @@
11
11
  import * as fs from "node:fs";
12
12
  import * as path from "node:path";
13
13
  import { deleteWorktreeBranch, isWorktreeDirty, removeGitWorktree, resolveMainCheckout, } from "../infrastructure/git-client.js";
14
- import { getAgentInfo, listAgentRecords, listWorktrees, normalizeHerdrPath, } from "../infrastructure/herdr-client.js";
15
- import { createHerdrHost } from "../infrastructure/herdr-host.js";
16
- import { getSessionCtx, getStore } from "../shell.js";
14
+ import { getHarnessRegistry, getSessionCtx, getStore } from "../shell.js";
17
15
  import { subagentResultFileFor } from "../paths.js";
18
16
  import { buildWorktreeBranch, isExtensionWorktree, isSpawnArtifactName, resolveWorktreeRoot, slugifyWorktreeType, } from "../spawn/worktree-policy.js";
19
- import { harnessFor } from "./harness/registry.js";
20
17
  async function probeList(read) {
21
18
  try {
22
19
  return { ok: true, entries: await read() };
@@ -26,9 +23,9 @@ async function probeList(read) {
26
23
  return { ok: false };
27
24
  }
28
25
  }
29
- function matchWorktree(entries, worktreePath) {
30
- const wanted = normalizeHerdrPath(worktreePath);
31
- return entries?.find((entry) => normalizeHerdrPath(entry.path) === wanted);
26
+ function matchWorktree(entries, worktreePath, canonicalize) {
27
+ const wanted = canonicalize(worktreePath);
28
+ return entries?.find((entry) => canonicalize(entry.path) === wanted);
32
29
  }
33
30
  function paneOf(record) {
34
31
  return {
@@ -37,9 +34,9 @@ function paneOf(record) {
37
34
  workspaceId: record.workspaceId,
38
35
  };
39
36
  }
40
- function paneInWorktree(records, worktreePath) {
41
- const wanted = normalizeHerdrPath(worktreePath);
42
- const record = records?.find((entry) => entry.cwd !== undefined && normalizeHerdrPath(entry.cwd) === wanted);
37
+ function paneInWorktree(records, worktreePath, canonicalize) {
38
+ const wanted = canonicalize(worktreePath);
39
+ const record = records?.find((entry) => entry.cwd !== undefined && canonicalize(entry.cwd) === wanted);
43
40
  return record === undefined ? undefined : paneOf(record);
44
41
  }
45
42
  function paneInWorkspace(records, workspaceId) {
@@ -69,7 +66,7 @@ export function createAgentAssets(deps) {
69
66
  const out = [];
70
67
  const seen = new Set();
71
68
  const push = (candidate) => {
72
- const key = normalizeHerdrPath(candidate.path);
69
+ const key = deps.canonicalizePath(candidate.path);
73
70
  if (seen.has(key))
74
71
  return;
75
72
  seen.add(key);
@@ -88,7 +85,7 @@ export function createAgentAssets(deps) {
88
85
  branch: entry.branch !== undefined && isSpawnArtifactName(entry.branch, id)
89
86
  ? entry.branch
90
87
  : base,
91
- workspaceId: entry.openWorkspaceId,
88
+ workspaceId: entry.workspaceId,
92
89
  });
93
90
  }
94
91
  // Scan only when the registry answered nothing: adopted checkouts are already listed.
@@ -126,13 +123,14 @@ export function createAgentAssets(deps) {
126
123
  let workspaceId = recorded?.workspaceId;
127
124
  if (worktreePath !== undefined) {
128
125
  // Prefer herdr's live workspace (restarts/re-adopts mint new ids; a dead recorded one fails removal); no open workspace means the git plane removes it.
129
- const entry = matchWorktree(entries, worktreePath);
126
+ const entry = matchWorktree(entries, worktreePath, deps.canonicalizePath);
130
127
  if (entry !== undefined)
131
- workspaceId = entry.openWorkspaceId;
128
+ workspaceId = entry.workspaceId;
132
129
  }
133
130
  const pane = worktreePath === undefined
134
131
  ? recordedPane
135
- : (paneInWorktree(records, worktreePath) ?? recordedPane);
132
+ : (paneInWorktree(records, worktreePath, deps.canonicalizePath) ??
133
+ recordedPane);
136
134
  const worktree = worktreePath === undefined
137
135
  ? null
138
136
  : {
@@ -166,7 +164,7 @@ export function createAgentAssets(deps) {
166
164
  };
167
165
  }
168
166
  const found = candidates[0];
169
- const pane = paneInWorktree(records, found.path) ??
167
+ const pane = paneInWorktree(records, found.path, deps.canonicalizePath) ??
170
168
  paneInWorkspace(records, found.workspaceId) ??
171
169
  null;
172
170
  return {
@@ -187,7 +185,7 @@ export function createAgentAssets(deps) {
187
185
  }
188
186
  async function locate(id, hint) {
189
187
  const worktrees = await probeList(deps.listWorktrees);
190
- const records = await probeList(deps.listAgentRecords);
188
+ const records = await probeList(deps.listPlacements);
191
189
  const entries = worktrees.ok ? worktrees.entries : undefined;
192
190
  const live = records.ok ? records.entries : undefined;
193
191
  return hint === undefined
@@ -195,6 +193,7 @@ export function createAgentAssets(deps) {
195
193
  : locateTracked(id, hint, entries, live);
196
194
  }
197
195
  return {
196
+ multiplexer: deps.multiplexer,
198
197
  locate,
199
198
  observe: (pane) => deps.readPane(pane.paneId),
200
199
  deliverable: deps.deliverable,
@@ -207,21 +206,25 @@ export function createAgentAssets(deps) {
207
206
  harnessTeardown: deps.harnessTeardown,
208
207
  };
209
208
  }
210
- /* ── The herdr composition ─────────────────────────────────────────────── */
211
- /** Bind the seam to the real planes: failed repo derivation is `undefined` (never a borrowed cwd); failed pane reads throw (unreadable is not gone). */
212
- export function createHerdrAgentAssets(pi) {
213
- const host = createHerdrHost(pi);
209
+ /* ── The multiplexer composition ────────────────────────────────────────────── */
210
+ /**
211
+ * Bind the seam to a session's multiplexer: the multiplexer's own reads come from the
212
+ * runtime's `PlacementCatalog` and its actuators from the runtime's `AgentHost`,
213
+ * so this module names no multiplexer. The rest — git, the filesystem, the config —
214
+ * is multiplexer-neutral and bound here. Failed repo derivation is `undefined` (never
215
+ * a borrowed cwd); failed pane reads throw (unreadable is not gone).
216
+ */
217
+ export function createMultiplexerAgentAssets(pi, host, catalog) {
214
218
  return createAgentAssets({
219
+ multiplexer: catalog.multiplexer,
220
+ canonicalizePath: (value) => catalog.canonicalizePath(value),
215
221
  deliverable: (id) => {
216
222
  const resultFile = subagentResultFileFor(id);
217
223
  return { path: resultFile, present: fs.existsSync(resultFile) };
218
224
  },
219
- listWorktrees: () => listWorktrees(pi),
220
- listAgentRecords: () => listAgentRecords(pi),
221
- readPane: async (paneId) => {
222
- const info = await getAgentInfo(pi, paneId);
223
- return info === undefined ? undefined : { state: info.state };
224
- },
225
+ listWorktrees: () => catalog.listWorktrees(),
226
+ listPlacements: () => catalog.listPlacements(),
227
+ readPane: (paneId) => catalog.observePane(paneId),
225
228
  worktreeRoot: async () => {
226
229
  const cwd = getSessionCtx().cwd;
227
230
  if (!cwd)
@@ -260,6 +263,16 @@ export function createHerdrAgentAssets(pi) {
260
263
  closePane: async (ref) => {
261
264
  await host.release(ref, "placement");
262
265
  },
263
- harnessTeardown: (harness, context) => harnessFor(harness).teardown({ pi, ...context }),
266
+ harnessTeardown: async (harness, context) => {
267
+ // The id is read back from a recorded spawn rather than resolved here, so
268
+ // a plugin load reset between the launch that recorded it and this
269
+ // teardown (a reload, a session replacement) can leave it registered by
270
+ // nothing. Such an id has no teardown to run — the plugin's code went with
271
+ // its registration — which is the same success as a harness that never
272
+ // prepared.
273
+ await getHarnessRegistry()
274
+ .get(harness)
275
+ ?.teardown({ pi, ...context });
276
+ },
264
277
  });
265
278
  }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * agent-cleanup.ts — state-changing cleanup orchestration (policy lives in cleanup-policy.ts).
3
+ * createWorktreeTeardown: worktree/branch/pane removal over injected actuators.
4
+ * createCleanup: settled-or-recovered run cleanup over the assets seam.
5
+ * WorktreeTeardown/Cleanup: the two planes. WorktreeTeardownOutcome: removal result.
6
+ * WorktreeRemovalTarget: the address a teardown removes through.
7
+ * AgentCleanupRegistry: spawn lookup/drop surface.
8
+ * Report-gated (only ended runs are cleaned up; live runs are refused, never stopped);
9
+ * ordered: gate before removal, workspace before pane, branch only after confirmed checkout removal.
10
+ */
11
+ import type { AgentSpawn, WorktreeRetentionReason } from "../types.js";
12
+ import type { BranchCleanupResult } from "../infrastructure/git-client.js";
13
+ import type { AgentHostRef } from "./agent-host.js";
14
+ import type { AgentAssets, CleanupDeps } from "./agent-assets.js";
15
+ import { type CleanupOptions, type CleanupReport, type PaneTarget, type WorktreeRemovalMechanism, type WorktreeTarget } from "./cleanup-policy.js";
16
+ export type { CleanupDeps } from "./agent-assets.js";
17
+ /** The agent-tracking surface cleanup needs — injected by the caller. */
18
+ export interface AgentCleanupRegistry {
19
+ getSpawn(id: string): AgentSpawn | undefined;
20
+ /** Drop a terminal spawn from tracking (after its resources are gone). */
21
+ dropSpawn(spawn: AgentSpawn): void;
22
+ }
23
+ export type WorktreeTeardownOutcome = {
24
+ kind: "removed";
25
+ path: string;
26
+ branchName: string;
27
+ via: WorktreeRemovalMechanism;
28
+ branch: BranchCleanupResult;
29
+ } | {
30
+ kind: "kept";
31
+ path: string;
32
+ reason: WorktreeRetentionReason;
33
+ } | {
34
+ kind: "absent";
35
+ path?: string;
36
+ } | {
37
+ kind: "removal-failed";
38
+ path: string;
39
+ detail: string;
40
+ };
41
+ /** A checkout the multiplexer adopted: removal rides the host address. */
42
+ export type AdoptedWorktreeTarget = WorktreeTarget & {
43
+ workspaceId: string;
44
+ };
45
+ /** A pane the extension created: the only pane cleanup may close. */
46
+ type SelfCreatedPaneTarget = PaneTarget & {
47
+ origin: "self-created";
48
+ };
49
+ /**
50
+ * Removal target: each legal case carries exactly the address it uses. A
51
+ * host-adopted tree removes through its ref; a git-only tree closes a
52
+ * self-created pane through its ref; a detached tree removes through git
53
+ * and carries no ref.
54
+ */
55
+ export type WorktreeRemovalTarget = {
56
+ kind: "adopted";
57
+ worktree: AdoptedWorktreeTarget;
58
+ pane: PaneTarget | null;
59
+ ref: AgentHostRef;
60
+ } | {
61
+ kind: "closing-pane";
62
+ worktree: WorktreeTarget;
63
+ pane: SelfCreatedPaneTarget;
64
+ ref: AgentHostRef;
65
+ } | {
66
+ kind: "detached";
67
+ worktree: WorktreeTarget;
68
+ pane: PaneTarget | null;
69
+ };
70
+ /** The state-changing teardown plane: worktree, then branch, then pane. */
71
+ interface WorktreeTeardown {
72
+ /** Tear down one worktree; a detached target runs only the git fallback; never stops an agent. */
73
+ removeWorktree(target: WorktreeRemovalTarget, opts?: CleanupOptions): Promise<WorktreeTeardownOutcome>;
74
+ }
75
+ interface Cleanup extends WorktreeTeardown {
76
+ /** Tear down one settled (or recovered) run's artifacts, then report. */
77
+ cleanupAgent(agentId: string, registry: AgentCleanupRegistry, opts?: CleanupOptions): Promise<CleanupReport>;
78
+ }
79
+ /** Bind the teardown plane over its actuators; an absent tree reports before any gate or removal runs. */
80
+ export declare function createWorktreeTeardown(deps: CleanupDeps): WorktreeTeardown;
81
+ /** Bind state-changing cleanup over the assets seam (the composition all callers use). */
82
+ export declare function createCleanup(assets: AgentAssets): Cleanup;
@@ -14,14 +14,14 @@ import { errorMessage } from "../utils.js";
14
14
  import { ambiguousReport, assembleReport, assessRemovability, forcedFields, keptReport, paneDispositionFor, planRecovered, recordedSettlement, recoveryGate, recoveryRefusalReason, removalMechanismOf, shouldDropSpawn, } from "./cleanup-policy.js";
15
15
  const log = createLogger("cleanup");
16
16
  /* ── Addresses ─────────────────────────────────────────────────────────── */
17
- /** Actuator address: memory's ref refreshed from herdr's live report; recovered runs rebuild it with `paneCreated` false; no pane address means no ref (git plane removes the checkout). */
18
- function hostRefFor(located) {
17
+ /** Actuator address: memory's ref refreshed from the multiplexer's live report; recovered runs rebuild it with `paneCreated` false; no pane address means no ref (git plane removes the checkout). `multiplexer` is the session's multiplexer, so the address a persisted spawn carries names the multiplexer that minted it. */
18
+ function hostRefFor(located, multiplexer) {
19
19
  const pane = located.pane;
20
20
  const workspaceId = pane?.workspaceId ?? located.worktree?.workspaceId;
21
21
  if (pane === null || workspaceId === undefined)
22
22
  return undefined;
23
23
  return {
24
- engine: "herdr",
24
+ multiplexer,
25
25
  name: located.branch,
26
26
  paneId: pane.paneId,
27
27
  tabId: pane.tabId,
@@ -127,7 +127,7 @@ export function createWorktreeTeardown(deps) {
127
127
  const pane = target.pane;
128
128
  const ref = target.kind === "detached" ? undefined : target.ref;
129
129
  try {
130
- // Applies to herdr and git targets alike: a rolled-back create has neither checkout nor workspace.
130
+ // Applies to multiplexer and git targets alike: a rolled-back create has neither checkout nor workspace.
131
131
  if (!(await deps.worktreeExists(worktree.worktreePath))) {
132
132
  return { kind: "absent", path: worktree.worktreePath };
133
133
  }
@@ -193,7 +193,7 @@ export function createCleanup(assets) {
193
193
  forceable: false,
194
194
  };
195
195
  }
196
- // No recorded end: force overrides without reading; otherwise herdr's live read decides (unreadable refuses — never evidence the run is over).
196
+ // No recorded end: force overrides without reading; otherwise the multiplexer's live read decides (unreadable refuses — never evidence the run is over).
197
197
  if (opts?.force !== undefined) {
198
198
  return {
199
199
  kind: "torn-down",
@@ -312,7 +312,7 @@ export function createCleanup(assets) {
312
312
  });
313
313
  }
314
314
  }
315
- const removal = await removeResources(assets, plan, hostRefFor(located));
315
+ const removal = await removeResources(assets, plan, hostRefFor(located, assets.multiplexer));
316
316
  const report = assembleReport(agentId, located.source, plan, verdict.settlement, removal, opts);
317
317
  // A recovered run has no record to forget; drop only tracked spawns.
318
318
  if (shouldDropSpawn(report) && hint !== undefined)
@@ -0,0 +1,22 @@
1
+ /**
2
+ * agent-discovery.ts — Agent file discovery, parsing, and config merging.
3
+ *
4
+ * Scans user, shared, and project `*.toml` dirs through
5
+ * AgentTemplateSchema into AgentConfigs. Per-field precedence:
6
+ * default < user < shared < project.
7
+ */
8
+ import { type TemplateNotify, type TemplateRefusal } from "../templates/template-files.js";
9
+ import { type AgentTemplate } from "./agent-template.js";
10
+ import type { AgentConfig } from "./types.js";
11
+ /** One parsed agent template. */
12
+ export type AgentTemplateFile = AgentTemplate;
13
+ /** Shape failures throw; the scanner turns that into a one-line skip warning. */
14
+ export declare function parseAgentFile(content: string): AgentTemplateFile;
15
+ /**
16
+ * Empty array when the directory doesn't exist. Stays shell-free: `notify` and
17
+ * `refuse` are injected, so the session's rules — which harness ids this
18
+ * session runs — are the caller's, not this module's.
19
+ */
20
+ export declare function scanAgentFilesInDir(dirPath: string, notify?: TemplateNotify, refuse?: TemplateRefusal<AgentTemplateFile>): Promise<AgentTemplateFile[]>;
21
+ /** Per-field precedence: project > shared > user > extension > defaults. A set field wins; undefined falls through. */
22
+ export declare function mergeAgents(defaults: Map<string, AgentConfig>, userAgents: AgentTemplateFile[], sharedAgents: AgentTemplateFile[], projectAgents: AgentTemplateFile[]): Map<string, AgentConfig>;
@@ -15,9 +15,13 @@ const AGENT_SCAN_WARNING = {
15
15
  label: "Agent",
16
16
  problem: "is not a valid agent template and was skipped",
17
17
  };
18
- /** Empty array when the directory doesn't exist. Stays shell-free: `notify` is the injected warning sink. */
19
- export async function scanAgentFilesInDir(dirPath, notify) {
20
- return scanTemplateFilesInDir(dirPath, parseAgentFile, (agent) => agent.name, notify, AGENT_SCAN_WARNING);
18
+ /**
19
+ * Empty array when the directory doesn't exist. Stays shell-free: `notify` and
20
+ * `refuse` are injected, so the session's rules — which harness ids this
21
+ * session runs — are the caller's, not this module's.
22
+ */
23
+ export async function scanAgentFilesInDir(dirPath, notify, refuse) {
24
+ return scanTemplateFilesInDir(dirPath, parseAgentFile, (agent) => agent.name, notify, AGENT_SCAN_WARNING, refuse);
21
25
  }
22
26
  /** Per-field precedence: project > shared > user > extension > defaults. A set field wins; undefined falls through. */
23
27
  export function mergeAgents(defaults, userAgents, sharedAgents, projectAgents) {