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
@@ -0,0 +1,212 @@
1
+ /**
2
+ * agent-host.ts — execution-multiplexer contracts (types only).
3
+ * AgentHost: hostAt/start/observe/stop/release/isAttached/findAttempts/deliver.
4
+ * AgentView: placement presentation (focus).
5
+ * PaneControl: the pane-side surface a harness prepares through.
6
+ * PlacementCatalog: the multiplexer's own view of the placements it owns (discovery,
7
+ * observation, path spelling) — the multiplexer vocabulary cleanup and status read.
8
+ * HerdrHostRef/AgentHostRef: host address. CheckoutBinding/ViewRequest: placement input.
9
+ * DeliverOutcome: what a pane submit attempt did. HostObservation: live agent state.
10
+ * LiveAttempt: conflict identity for dedup. ExecutionRuntime: host + view + pane +
11
+ * placements for one parent session.
12
+ */
13
+ import type { HostMultiplexer } from "../host-multiplexer.js";
14
+ /**
15
+ * Which multiplexer an address belongs to. The host multiplexers (see host-multiplexer.ts)
16
+ * are the built-in ones and autocomplete; any other string names a multiplexer a
17
+ * plugin registered, so the vocabulary stays open.
18
+ */
19
+ export type AgentMultiplexer = HostMultiplexer | (string & {});
20
+ /** A host address as herdr models it: one pi process in one pane of one tab of one workspace. */
21
+ interface HerdrHostRef {
22
+ readonly multiplexer: AgentMultiplexer;
23
+ /** Stable agent identity (herdr: agent name). The tab title may differ. */
24
+ readonly name: string;
25
+ readonly paneId: string;
26
+ /** Hosting tab when known; absent on registry-reconstructed addresses (release/observe use pane + workspace). */
27
+ readonly tabId?: string;
28
+ readonly workspaceId: string;
29
+ /** False for adopted worktree placements: failed-launch cleanup must not close them. */
30
+ readonly paneCreated: boolean;
31
+ }
32
+ /** What the domain types against; only the herdr impl names the variant. */
33
+ export type AgentHostRef = HerdrHostRef;
34
+ /** What a submit to an agent did. `submitted` is the only state a steer acts on. */
35
+ export type DeliverOutcome =
36
+ /** The text and the submission keypress both reached the agent. */
37
+ {
38
+ kind: "submitted";
39
+ }
40
+ /**
41
+ * The agent did not take the message, and `detail` says why — the pane hosts
42
+ * no agent, the agent is waiting on an approval, herdr was unreachable. Nothing
43
+ * was submitted.
44
+ */
45
+ | {
46
+ kind: "not-submitted";
47
+ detail: string;
48
+ };
49
+ /** Only pane placement exists today. */
50
+ type PlacementUnit = "pane";
51
+ /** Checkout for a placement to attach to; the multiplexer registers it, git owns it. */
52
+ export interface CheckoutBinding {
53
+ /** Worktree checkout path (the placement's cwd). */
54
+ path: string;
55
+ /** Main checkout — herdr requires this for `worktree open`. */
56
+ repoCwd: string;
57
+ /** Branch the checkout is on (`cow-<task>-<id>`). */
58
+ branch: string;
59
+ }
60
+ export interface ViewRequest {
61
+ readonly unit: PlacementUnit;
62
+ readonly cwd: string;
63
+ /** Human-facing placement title; a herdr tab's label carries the spawn marker in front of it, and it names the agent when the request names none. */
64
+ readonly label: string;
65
+ /** Stable agent identity; defaults to label, diverges on the fresh-tab path (pretty tab title, branch-derived agent name). */
66
+ readonly name?: string;
67
+ readonly checkout?: CheckoutBinding;
68
+ }
69
+ /** Presentation of a live host. Unit-specific by nature (pane focus is neighbor-relative; tab focus is by id). */
70
+ export interface AgentView {
71
+ focus(ref: AgentHostRef): Promise<void>;
72
+ }
73
+ /**
74
+ * The pane-side surface a harness prepares through. A harness that must type
75
+ * into its pane — installing a launcher, proving staged state is live — reaches
76
+ * the pane here, never through the multiplexer's own client, so the same harness
77
+ * runs under any multiplexer that offers this surface.
78
+ */
79
+ export interface PaneControl {
80
+ /** How the pane is addressed; the multiplexer's own vocabulary (herdr for the built-in multiplexer). */
81
+ readonly kind: string;
82
+ /**
83
+ * Type one command into the pane. Fire-and-forget by contract: a multiplexer
84
+ * returns before the shell has evaluated the line, so a caller proves what it
85
+ * typed rather than trusting this call (see pane-launcher.ts).
86
+ */
87
+ run(paneId: string, command: string): Promise<void>;
88
+ /** Resolve once the pane's output comes to contain `output`, or reject when the budget elapses. */
89
+ waitForOutput(paneId: string, output: string, timeoutMs: number): Promise<void>;
90
+ }
91
+ export interface HostObservation {
92
+ /** herdr's own vocabulary. */
93
+ readonly state: "idle" | "working" | "blocked" | "done" | "unknown";
94
+ }
95
+ /**
96
+ * A checkout the multiplexer knows about, as the multiplexer reports it (herdr: one
97
+ * `worktree list` row). `path` is already canonicalized the way this multiplexer
98
+ * spells its placements, so a caller compares it through
99
+ * `PlacementCatalog.canonicalizePath`.
100
+ */
101
+ export interface PlacementWorktree {
102
+ readonly path: string;
103
+ /** The multiplexer's label for the checkout, when it reported one. */
104
+ readonly label?: string;
105
+ /** The branch the checkout carries, when the multiplexer reported it. */
106
+ readonly branch?: string;
107
+ /** Workspace hosting the checkout's tab; absent when the checkout is not open. */
108
+ readonly workspaceId?: string;
109
+ }
110
+ /**
111
+ * A placement the multiplexer started, as the multiplexer reports it (herdr: one `agent list`
112
+ * record). Nameless records are included: herdr 0.8.x usually drops the name,
113
+ * and `cwd` is then the durable link from a record back to its checkout.
114
+ */
115
+ export interface PlacementRecord {
116
+ readonly name?: string;
117
+ readonly state: HostObservation["state"];
118
+ readonly workspaceId?: string;
119
+ readonly tabId?: string;
120
+ /** The placement's working directory, when the multiplexer reports one. */
121
+ readonly cwd?: string;
122
+ readonly paneId: string;
123
+ }
124
+ /**
125
+ * The multiplexer's own view of the placements it owns: what exists, how one is read
126
+ * back by pane, and how this multiplexer spells a path. Every method here is multiplexer
127
+ * vocabulary — that is exactly why it belongs to the multiplexer and not to the
128
+ * git/filesystem plane, so a session's cleanup and status paths read the
129
+ * placements of the multiplexer it is actually running rather than a multiplexer the
130
+ * extension picked on their behalf.
131
+ */
132
+ export interface PlacementCatalog {
133
+ /** The multiplexer these placements belong to; the value a persisted address records. */
134
+ readonly multiplexer: AgentMultiplexer;
135
+ /**
136
+ * Canonicalize a path the way this multiplexer spells its placements, so a caller
137
+ * can compare a path it holds with one the catalog reported.
138
+ */
139
+ canonicalizePath(value: string): string;
140
+ /** Every checkout the multiplexer knows. A failed read throws — unreadable is not empty. */
141
+ listWorktrees(): Promise<readonly PlacementWorktree[]>;
142
+ /** Every placement the multiplexer started, nameless ones included. A failed read throws. */
143
+ listPlacements(): Promise<readonly PlacementRecord[]>;
144
+ /** One placement's raw state by pane id; undefined = gone, a throw = unreadable (never evidence either way). */
145
+ observePane(paneId: string): Promise<HostObservation | undefined>;
146
+ }
147
+ /** Live attempt naming a task conflict; carries no stop address by design, so dedup can never end another session's work. */
148
+ export interface LiveAttempt {
149
+ /** Stable agent identity (herdr: agent name). */
150
+ readonly name: string;
151
+ }
152
+ /**
153
+ * The agent kind a host starts its process as, in the multiplexer's own vocabulary. The
154
+ * multiplexer matches the process it detects in the pane against the requested kind —
155
+ * herdr does, at `agent start` — so the kind has to be the one the launched
156
+ * binary is detected as. The four built-in kinds autocomplete; any other string
157
+ * is a kind a plugin harness launches under, as long as the multiplexer starts it.
158
+ */
159
+ export type AgentMultiplexerKind = "pi" | "claude" | "codex" | "opencode" | (string & {});
160
+ export interface AgentHost {
161
+ /** Obtain a host address: adopts the checkout (`worktree open`) or creates a fresh placement in the current workspace. */
162
+ hostAt(request: ViewRequest): Promise<AgentHostRef>;
163
+ /**
164
+ * Launch the child process into the host. `piArgs` already carries
165
+ * `--system-prompt <file>` and the `@<task-file>` message; `agentMultiplexerKind` is the
166
+ * kind the multiplexer must detect the process as.
167
+ */
168
+ start(ref: AgentHostRef, options: {
169
+ name: string;
170
+ piArgs: string[];
171
+ agentMultiplexerKind: AgentMultiplexerKind;
172
+ }): Promise<void>;
173
+ /** Live snapshot, or undefined when the host is gone. */
174
+ observe(ref: AgentHostRef): Promise<HostObservation | undefined>;
175
+ /** Interrupt and wait; never closes the placement (worktree removal depends on it). */
176
+ stop(ref: AgentHostRef, options?: {
177
+ interruptGraceMs?: number;
178
+ confirmMs?: number;
179
+ }): Promise<boolean>;
180
+ /**
181
+ * Undo hostAt. Destroying a placement ends its process (kill of last
182
+ * resort; multiplexers that cannot end it must not offer release).
183
+ * `placement` closes a self-created placement; `worktree-association`
184
+ * drops a checkout registration (the placement dies with it).
185
+ */
186
+ release(ref: AgentHostRef, scope: "placement" | "worktree-association"): Promise<boolean>;
187
+ /** Whether any live host (possibly another session's) still has this checkout; guards branch deletion — a throw counts as attached. */
188
+ isAttached(worktreePath: string, opts?: {
189
+ repoCwd?: string;
190
+ }): Promise<boolean>;
191
+ /** Live attempts for a task slug (survives parent reload); a failed probe returns [] so availability never blocks spawning. */
192
+ findAttempts(taskSlug: string): Promise<LiveAttempt[]>;
193
+ /**
194
+ * Submit a message to the run's agent. A working agent queues it for its next
195
+ * model call; a settled one starts another turn. The agent surface refuses a
196
+ * target that hosts no agent, so there is one way in and no half-delivered
197
+ * state: `not-submitted` means the message was refused and `detail` says why.
198
+ */
199
+ deliver(ref: AgentHostRef, message: string): Promise<DeliverOutcome>;
200
+ }
201
+ /** One multiplexer's host + view + pane control + placement catalog, built once per parent session. */
202
+ export interface ExecutionRuntime {
203
+ readonly host: AgentHost;
204
+ readonly view: AgentView;
205
+ /** The pane surface every harness this session launches under prepares through. */
206
+ readonly pane: PaneControl;
207
+ /** The multiplexer's view of the placements it owns (discovery, observation, path spelling). */
208
+ readonly placements: PlacementCatalog;
209
+ /** The multiplexer id this runtime was built from; the value a persisted address records. */
210
+ readonly multiplexer: AgentMultiplexer;
211
+ }
212
+ export {};
@@ -1,10 +1,13 @@
1
1
  /**
2
- * agent-host.ts — execution-backend contracts (types only).
2
+ * agent-host.ts — execution-multiplexer contracts (types only).
3
3
  * AgentHost: hostAt/start/observe/stop/release/isAttached/findAttempts/deliver.
4
4
  * AgentView: placement presentation (focus).
5
+ * PaneControl: the pane-side surface a harness prepares through.
6
+ * PlacementCatalog: the multiplexer's own view of the placements it owns (discovery,
7
+ * observation, path spelling) — the multiplexer vocabulary cleanup and status read.
5
8
  * HerdrHostRef/AgentHostRef: host address. CheckoutBinding/ViewRequest: placement input.
6
9
  * DeliverOutcome: what a pane submit attempt did. HostObservation: live agent state.
7
- * LiveAttempt: conflict identity for dedup. ExecutionRuntime: host + view for one
8
- * parent session.
10
+ * LiveAttempt: conflict identity for dedup. ExecutionRuntime: host + view + pane +
11
+ * placements for one parent session.
9
12
  */
10
13
  export {};
@@ -0,0 +1,99 @@
1
+ /**
2
+ * agent-manager.ts — Fleet controller for independently running subagents.
3
+ * Exports AgentManager; re-exports spawn and steer types.
4
+ */
5
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
6
+ import { ConcurrencyPools, type ConcurrencyConfig } from "../concurrency-pools.js";
7
+ import { HerdrTaskRegistry } from "../task-registry.js";
8
+ import { type AgentPhase, type AgentSpawn, type StopInitiator } from "../types.js";
9
+ import type { SupervisorTransport } from "../subagent/pane-supervisor.js";
10
+ import type { ExecutionRuntime } from "./agent-host.js";
11
+ import { type LocateResult } from "./agent-assets.js";
12
+ import type { CleanupOptions, CleanupReport } from "./cleanup-policy.js";
13
+ import { DISPOSE_QUEUED_MESSAGE, type SpawnOptions, type SteerOutcome } from "./subagent-session.js";
14
+ import type { SubagentType } from "./types.js";
15
+ export type { SpawnOptions, SteerOutcome } from "./subagent-session.js";
16
+ /**
17
+ * The transport a session's manager runs on: the session's runtime, which
18
+ * `ExecutionRuntime` builds once per parent session (agent-host.ts). The runtime is
19
+ * bound once here, so every spawn, every cleanup and the registry's dedup check
20
+ * reuse the same host, placements and pane; a multiplexer that opens a connection
21
+ * or starts a service in its `create` would otherwise leak one per call.
22
+ */
23
+ export declare function createAgentManagerTransport(runtime: ExecutionRuntime): SupervisorTransport;
24
+ type OnAgentComplete = (spawn: AgentSpawn) => void;
25
+ /** A report from an agent that already settled: news beyond its recorded result. */
26
+ type OnAgentFollowUp = (spawn: AgentSpawn, deliverable: string) => void;
27
+ /** Fleet controller; each session owns exactly one lifecycle. */
28
+ export declare class AgentManager {
29
+ private readonly transport;
30
+ /** Live sessions by id; the spawn itself stays identity-stable. */
31
+ private readonly sessions;
32
+ private onComplete?;
33
+ private onFollowUp?;
34
+ /**
35
+ * Teardowns in flight, by agent id. One teardown owns an id's artifacts at a
36
+ * time: a cleanup that arrives while one runs waits for it instead of racing
37
+ * it for the same checkout.
38
+ */
39
+ private readonly teardowns;
40
+ /** The resource limiter the fleet drives directly; sessions charge their capacity to it. */
41
+ private readonly pools;
42
+ /** Task identity and admission serialization; pool accounting lives in `pools`. */
43
+ private readonly registry;
44
+ constructor(pools: ConcurrencyPools, transport: SupervisorTransport);
45
+ getRegistry(): HerdrTaskRegistry;
46
+ setConcurrency(config: ConcurrencyConfig): void;
47
+ setOnComplete(cb: OnAgentComplete): void;
48
+ setOnFollowUp(cb: OnAgentFollowUp): void;
49
+ /**
50
+ * Mint a spawn id unique across every retained spawn, settled ones included:
51
+ * a retained spawn still owns its id, branch, worktree, and herdr name.
52
+ */
53
+ mintSpawnId(): string;
54
+ spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions): string;
55
+ private startSession;
56
+ /**
57
+ * Route a message to the agent's session. Unknown ids are refused with the
58
+ * reason; settled agents revive in their session. See SubagentSession.
59
+ */
60
+ steer(id: string, message: string): Promise<SteerOutcome>;
61
+ /** One spawn by id, unfiltered, so cleanup reaches settled spawns too. */
62
+ getSpawn(id: string): AgentSpawn | undefined;
63
+ /** Assets seam, built per call so probes run against the current shell. */
64
+ private assets;
65
+ /**
66
+ * Locate one agent's artifacts. Read-only: nothing is stopped, removed, or
67
+ * released. Covers ids no session tracks (a `/reload` rebuilt the store).
68
+ */
69
+ locate(id: string): Promise<LocateResult>;
70
+ /**
71
+ * Retained spawns in the given phases (default: all), newest start first.
72
+ * Pass ACTIVE_AGENT_PHASES for in-flight work, ALL_AGENT_PHASES for status.
73
+ */
74
+ listAgents(phases?: readonly AgentPhase[]): AgentSpawn[];
75
+ abort(id: string, initiator?: StopInitiator): Promise<boolean>;
76
+ private notifyComplete;
77
+ private notifyFollowUp;
78
+ /**
79
+ * Record why a spawn's checkout survived. The caller reports the outcome and
80
+ * the reason rides the spawn, so status still states it after the menu leaves.
81
+ */
82
+ private recordRetention;
83
+ /**
84
+ * Drop runtime session and store entry for good, and with them the run's
85
+ * staging directory. The removal is keyed on the id, not the session: a
86
+ * disposal leaves a settled spawn tracked with no session at all, and only
87
+ * the canonical path can still name the directory that run wrote to.
88
+ */
89
+ dropSpawn(spawn: AgentSpawn): void;
90
+ cleanup(id: string, opts?: CleanupOptions): Promise<CleanupReport>;
91
+ /** Clean one agent up, after whatever teardown for its id is already running. */
92
+ private runCleanup;
93
+ /**
94
+ * Dispose every runtime session. The shell-owned spawn store stays: settled
95
+ * spawns must stay cleanable and untracked live ones stay visible.
96
+ */
97
+ dispose(): void;
98
+ }
99
+ export { DISPOSE_QUEUED_MESSAGE };
@@ -4,7 +4,6 @@
4
4
  */
5
5
  import { getAgentSpawns, getCoordinatorOrNull, getPiInstance, getSessionCtx, } from "../shell.js";
6
6
  import { subagentResultFileFor } from "../paths.js";
7
- import { createHerdrRuntime } from "../infrastructure/herdr-host.js";
8
7
  import { HerdrTaskRegistry } from "../task-registry.js";
9
8
  import { createLogger } from "../logger.js";
10
9
  import { errorMessage } from "../utils.js";
@@ -12,14 +11,24 @@ import { ACTIVE_AGENT_PHASES, ALL_AGENT_PHASES, hasOutcome, lifecycleStartTime,
12
11
  import { FileDeliverable } from "../subagent/deliverable.js";
13
12
  import { removeResultArtifacts } from "../subagent/result-artifacts.js";
14
13
  import { createCleanup } from "./agent-cleanup.js";
15
- import { createHerdrAgentAssets, } from "./agent-assets.js";
14
+ import { createMultiplexerAgentAssets, } from "./agent-assets.js";
16
15
  import { DISPOSE_QUEUED_MESSAGE, SubagentSession, } from "./subagent-session.js";
17
16
  import { resolveHarnessType } from "./spawn-defaults.js";
18
- /** The transport the manager wires its sessions with unless the caller supplies one. */
19
- export const defaultAgentManagerTransport = {
20
- createHost: (pi) => createHerdrRuntime(pi).host,
21
- createDeliverable: (resultFile) => new FileDeliverable(resultFile),
22
- };
17
+ /**
18
+ * The transport a session's manager runs on: the session's runtime, which
19
+ * `ExecutionRuntime` builds once per parent session (agent-host.ts). The runtime is
20
+ * bound once here, so every spawn, every cleanup and the registry's dedup check
21
+ * reuse the same host, placements and pane; a multiplexer that opens a connection
22
+ * or starts a service in its `create` would otherwise leak one per call.
23
+ */
24
+ export function createAgentManagerTransport(runtime) {
25
+ return {
26
+ createHost: () => runtime.host,
27
+ createPane: () => runtime.pane,
28
+ createPlacements: () => runtime.placements,
29
+ createDeliverable: (resultFile) => new FileDeliverable(resultFile),
30
+ };
31
+ }
23
32
  const log = createLogger("manager");
24
33
  /**
25
34
  * The keep reason a cleanup report carries for a spawn that stays listed. A
@@ -59,7 +68,7 @@ export class AgentManager {
59
68
  pools;
60
69
  /** Task identity and admission serialization; pool accounting lives in `pools`. */
61
70
  registry;
62
- constructor(pools, transport = defaultAgentManagerTransport) {
71
+ constructor(pools, transport) {
63
72
  this.transport = transport;
64
73
  this.pools = pools;
65
74
  this.registry = new HerdrTaskRegistry({
@@ -186,7 +195,10 @@ export class AgentManager {
186
195
  }
187
196
  /** Assets seam, built per call so probes run against the current shell. */
188
197
  assets() {
189
- return createHerdrAgentAssets(getPiInstance());
198
+ const pi = getPiInstance();
199
+ // The multiplexer's own host and placement catalog, from the session's transport:
200
+ // the manager never picks a multiplexer for the cleanup and status paths.
201
+ return createMultiplexerAgentAssets(pi, this.transport.createHost(pi), this.transport.createPlacements(pi));
190
202
  }
191
203
  /**
192
204
  * Locate one agent's artifacts. Read-only: nothing is stopped, removed, or
@@ -0,0 +1,38 @@
1
+ /**
2
+ * agent-reviver.ts — Return a settled run to active. Exports reviveSettledRun.
3
+ *
4
+ * The pane still holds a live pi process, so a delivered message starts a
5
+ * second turn. The result dir is recreated empty first: settlement deletes it
6
+ * (child writes would fail ENOENT) and a stale report would settle the
7
+ * revive with the first run's outcome. A fresh supervisor adopts the host
8
+ * (one run per instance). A revive is not an admission, so the run cannot wait
9
+ * for room: it charges its pools immediately and can pass a limit. The promise
10
+ * keeps the first run's gate: it opened with the first
11
+ * turn's result, so the revived turn is reported through its completion message
12
+ * alone.
13
+ */
14
+ import type { ProcessSupervisor, ProcessSupervisorOptions, SubagentExitOutcome } from "../subagent/supervisor.js";
15
+ import { type SupervisorTransport } from "../subagent/pane-supervisor.js";
16
+ import type { AgentLaunchState, AgentSpawn } from "../types.js";
17
+ import type { AgentHostRef } from "./agent-host.js";
18
+ interface AgentReviveRequest {
19
+ spawn: AgentSpawn;
20
+ hostRef: AgentHostRef;
21
+ transport: SupervisorTransport;
22
+ supervisorOptions: ProcessSupervisorOptions;
23
+ /** Attach the adopted supervisor, and the launch the revived turn resumes, as the session's live run. */
24
+ attachSupervisor(supervisor: ProcessSupervisor, launch: AgentLaunchState): void;
25
+ /** Re-bind the parent abort signal (settlement detached it). */
26
+ rebindParentSignal(): void;
27
+ /** Feed the revived run's terminal outcome back to the session. */
28
+ reportOutcome(supervisor: ProcessSupervisor, outcome: SubagentExitOutcome): void;
29
+ }
30
+ /**
31
+ * Reset settlement artifacts, adopt the host with a fresh supervisor, and arm
32
+ * the second-settlement watch. The spawn's state stays with the session: the
33
+ * attach seam returns the run to active, so this function writes none of it.
34
+ * Synchronous: the message is already delivered, so nothing here waits on
35
+ * the agent.
36
+ */
37
+ export declare function reviveSettledRun(request: AgentReviveRequest): void;
38
+ export {};
@@ -0,0 +1,51 @@
1
+ /**
2
+ * agent-runner.ts — Launch-plan building for herdr-pane subagents.
3
+ *
4
+ * Produces a `SubagentLaunchPlan`: staged prompt files and the launch
5
+ * context, with the argv owned by the resolved harness (prompt text compiled
6
+ * by `../prompt/subagent-system-prompt.js`). The child process owns extension
7
+ * discovery and tool validation.
8
+ */
9
+ import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
10
+ import { type AgentWorktree, type RunTunables } from "../types.js";
11
+ import { buildWorktreeBranchSection } from "../prompt/subagent-system-prompt.js";
12
+ import { type AnyHarnessId, type HarnessLaunch } from "./harness.js";
13
+ import type { SubagentType } from "./types.js";
14
+ export { buildWorktreeBranchSection };
15
+ export interface SubagentLaunchPlan {
16
+ /** Cosmetic herdr agent name. */
17
+ name?: string;
18
+ /** Working directory for the pane (resolved worktree path or parent cwd). */
19
+ cwd: string;
20
+ /**
21
+ * The system prompt text itself, as written to `launch.systemPromptFile`.
22
+ */
23
+ systemPrompt?: string;
24
+ /** Legacy name: the complete argv the harness built, whatever binary it launches — the supervisor and herdr seams both spell it `piArgs`. */
25
+ piArgs: string[];
26
+ /**
27
+ * The launch request `piArgs` was built from, and the same object a harness's
28
+ * `prepare` receives: one construction site, so a field the launch adds
29
+ * reaches both without a second copy to keep in step.
30
+ */
31
+ launch: HarnessLaunch;
32
+ taskSlug?: string;
33
+ /** The harness that owns the pane `piArgs` launches into. */
34
+ harness: AnyHarnessId;
35
+ }
36
+ interface LaunchTunables extends RunTunables {
37
+ agentId?: string;
38
+ cwd?: string;
39
+ projectTrusted?: boolean;
40
+ }
41
+ interface LaunchExtras {
42
+ description: string;
43
+ /** The harness the launch resolves, so the plan and the pool identity agree. */
44
+ harness: AnyHarnessId;
45
+ /** Worktree coordinates with ownership; absent for parent-cwd runs. */
46
+ worktree?: AgentWorktree;
47
+ /** The subagent-facing guidance the resolved orchestration template declares, rendered as the system prompt's final block. */
48
+ agentGuidance?: string;
49
+ }
50
+ /** The child pi owns extension discovery and tool validation; this only forwards configuration. */
51
+ export declare function buildLaunchPlan(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: LaunchTunables & LaunchExtras): Promise<SubagentLaunchPlan>;
@@ -11,10 +11,9 @@ import path from "node:path";
11
11
  import { SettingsManager, } from "@earendil-works/pi-coding-agent";
12
12
  import { errorMessage } from "../utils.js";
13
13
  import { agentDir, subagentResultDirFor, subagentResultFileFor, subagentSystemFileFor, subagentTaskFileFor, } from "../paths.js";
14
- import { getStore } from "../shell.js";
14
+ import { getHarnessRegistry, getStore } from "../shell.js";
15
15
  import { buildSubagentSystemPrompt, buildWorktreeBranchSection, } from "../prompt/subagent-system-prompt.js";
16
- import { harnessFor } from "./harness/registry.js";
17
- import { harnessFamilyOf } from "./harness-family.js";
16
+ import { harnessFamilyOf } from "./harness/harness-registry.js";
18
17
  import { getAgentConfig, getConfig, } from "./agent-types.js";
19
18
  import { ensureResultDir, writeResultFile } from "./result-file-permissions.js";
20
19
  // Re-exported for consumers importing it from this module.
@@ -136,9 +135,11 @@ function resolveToolCliEntries(entries, optionName) {
136
135
  return [...resolved];
137
136
  }
138
137
  /**
139
- * The launch request for one harness, by family. The switch is exhaustive over
140
- * `HarnessId`, so a kind added to `HARNESS_IDS` without a branch here fails to
141
- * compile instead of being handed another family's request.
138
+ * The launch request for one harness. A built-in id is one of the closed
139
+ * families below, so its own inputs are the only ones it can be handed; any
140
+ * other registered id is a plugin harness, whose request carries the shared
141
+ * inputs and the open arm's tag alone — its CLI-specific options live in its
142
+ * own code, so nothing built-in-family-specific can reach it.
142
143
  */
143
144
  function buildLaunchRequest(harnessType, sharedInputs, piInputs, opencodeInputs, codexInputs) {
144
145
  switch (harnessType) {
@@ -153,32 +154,21 @@ function buildLaunchRequest(harnessType, sharedInputs, piInputs, opencodeInputs,
153
154
  case "claude":
154
155
  return { ...sharedInputs, family: "claude" };
155
156
  default: {
156
- const unhandled = harnessType;
157
- throw new Error(`unhandled harness: ${String(unhandled)}`);
157
+ if (getHarnessRegistry().get(harnessType) === undefined) {
158
+ throw new Error(`no harness registered for "${harnessType}"`);
159
+ }
160
+ return { ...sharedInputs, family: "plugin" };
158
161
  }
159
162
  }
160
163
  }
161
164
  /**
162
- * The harness's argv, from the request this launch carries. The request's own
163
- * family tag selects the harness, so one family's argv cannot be built from
164
- * another family's inputs; the switch is exhaustive over the tag, so a family
165
- * added to `HarnessLaunchRequest` without a branch fails to compile.
165
+ * The harness's argv, from the id that owns the pane and the request this launch
166
+ * carries. The registry narrows a built-in's launch to its own family request and
167
+ * hands a plugin the shared inputs, so one family's argv cannot be built from
168
+ * another family's inputs and no caller branches on origin.
166
169
  */
167
- function buildHarnessArgs(request) {
168
- switch (request.family) {
169
- case "pi":
170
- return harnessFor("pi").buildArgs(request);
171
- case "opencode":
172
- return harnessFor("opencode").buildArgs(request);
173
- case "codex":
174
- return harnessFor("codex").buildArgs(request);
175
- case "claude":
176
- return harnessFor("claude").buildArgs(request);
177
- default: {
178
- const unhandled = request;
179
- throw new Error(`unhandled harness family: ${String(unhandled)}`);
180
- }
181
- }
170
+ function buildHarnessArgs(harnessId, launch) {
171
+ return getHarnessRegistry().require(harnessId).buildArgs(launch);
182
172
  }
183
173
  /** The child pi owns extension discovery and tool validation; this only forwards configuration. */
184
174
  export async function buildLaunchPlan(pi, ctx, type, prompt, options) {
@@ -221,9 +211,10 @@ export async function buildLaunchPlan(pi, ctx, type, prompt, options) {
221
211
  try {
222
212
  // Exactly one harness launches a spawn, so exactly one family's slice
223
213
  // decides: its names are already in that family's vocabulary. A family the
224
- // template does not name launches unfiltered — never with another
225
- // family's list, and never translated.
226
- const filter = agentConfig?.toolsByFamily?.[harnessFamilyOf(harnessType)];
214
+ // template does not name — a plugin's own family especially — launches
215
+ // unfiltered, never with another family's list, and never translated.
216
+ const family = harnessFamilyOf(harnessType);
217
+ const filter = family === undefined ? undefined : agentConfig?.toolsByFamily?.[family];
227
218
  if (filter?.tools === false) {
228
219
  toolSelection = { kind: "none" };
229
220
  }
@@ -315,7 +306,7 @@ export async function buildLaunchPlan(pi, ctx, type, prompt, options) {
315
306
  projectTrusted: options.projectTrusted !== false,
316
307
  };
317
308
  const launch = buildLaunchRequest(harnessType, sharedInputs, piInputs, opencodeInputs, codexInputs);
318
- const piArgs = buildHarnessArgs(launch);
309
+ const piArgs = buildHarnessArgs(harnessType, launch);
319
310
  for (const msg of warnings) {
320
311
  ctx.ui.notify(`[cowboy] ${msg}`, "warning");
321
312
  }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * agent-spawn-store.ts — Shell-owned canonical AgentSpawn store.
3
+ * Exports AgentSpawnStore, SpawnIdCollisionError.
4
+ *
5
+ * The manager is per-session, so spawns live here in the shell: a spawn
6
+ * outlives its session and stays visible and cleanable. A `/reload`
7
+ * re-imports the extension and rebuilds this store empty. No I/O or
8
+ * lifecycle logic; the only scoping is the lifecycle phase, on request.
9
+ */
10
+ import type { AgentPhase, AgentSpawn } from "../types.js";
11
+ /**
12
+ * Thrown when `add` gets an id the store already owns. Overwriting would
13
+ * destroy the live spawn and the stop/cleanup/steer execution it carries, so
14
+ * the original is left untouched.
15
+ */
16
+ export declare class SpawnIdCollisionError extends Error {
17
+ readonly spawnId: string;
18
+ constructor(spawnId: string);
19
+ }
20
+ /** Process-lifetime spawn retention by id; drops only on explicit drop. */
21
+ export declare class AgentSpawnStore {
22
+ private spawns;
23
+ /**
24
+ * Register a spawn at creation. A duplicate id throws and leaves the
25
+ * original untouched; callers mint through `mint()`, so a collision is a bug.
26
+ */
27
+ add(spawn: AgentSpawn): void;
28
+ /**
29
+ * Mint an id no registered spawn holds, settled ones included: a retained
30
+ * spawn still owns its id. `mint` is injectable so collisions are testable.
31
+ */
32
+ mint(mint?: () => string): string;
33
+ /** Look one spawn up by id, never phase-filtered. */
34
+ get(id: string): AgentSpawn | undefined;
35
+ /** Drop a spawn once its resources are gone (cleanup success, Clear). */
36
+ drop(id: string): void;
37
+ /** Spawns in the given phases (default: all), in insertion order. */
38
+ list(phases?: readonly AgentPhase[]): AgentSpawn[];
39
+ }