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,459 @@
1
+ /**
2
+ * harness.ts — the harness contract: which process launches a subagent, and how.
3
+ *
4
+ * A harness owns five things: the multiplexer agent kind its process launches as
5
+ * (`agentMultiplexerKind`), bringing its host pane into the state it launches in
6
+ * (`prepare`), the argv the pane runs (`buildArgs`), undoing any state it
7
+ * left on the filesystem (`teardown`), and warming a slow model list at boot
8
+ * (`prefetchModels`). One `Harness<L>` contract serves a built-in and a plugin;
9
+ * `L` is the launch type the implementation reads. What every harness has in
10
+ * common lives here as `SubagentLaunchInputs`; what one built-in family alone
11
+ * uses (pi's CLI flags, opencode's variant, codex's project trust) lives beside
12
+ * it as that family's inputs, so a second family adds a request member — never
13
+ * an optional field, a passthrough schema, or a raw config record on a shared
14
+ * type. One request carries one launch, and both `buildArgs` and `prepare` read
15
+ * it, so a built-in is handed its family's request and a plugin is handed the
16
+ * shared inputs alone. The listing request below (`HarnessListModelsRequest`) is
17
+ * the one shared request that breaks that shape, because one call answers for
18
+ * every runnable harness at once: a family's own input rides it as a field
19
+ * named after that family, never as a member a caller has to pick. Each
20
+ * harness's implementation lives beside this module (harness/pig.ts,
21
+ * harness/pi-bolt.ts, harness/opencode/index.ts, harness/codex.ts,
22
+ * harness/claude/index.ts) and is selected through harness/harness-registry.ts.
23
+ *
24
+ * `HARNESS_IDS` is the built-in vocabulary, and it stays whole wherever a value
25
+ * is read or written: a template written for a built-in harness must still load
26
+ * on a machine that cannot launch it — only its launch falls back to pi. A value
27
+ * naming a plugin harness is a different case: it is legal because this
28
+ * session's registry has that id, so an id no harness registered is reported
29
+ * rather than downgraded (see agent-types.ts). Which harnesses a machine can
30
+ * launch only narrows what the setting offers and which harness a spawn ends up
31
+ * using.
32
+ *
33
+ * Model lists belong to the harness too (`listModels`): one interface method
34
+ * answers "what can this harness run" for the pi family's catalog and for a
35
+ * foreign CLI alike, so a settings menu enumerates harness rows instead of
36
+ * knowing each family's source.
37
+ *
38
+ * Evolution rule: a new *built-in* harness family is added by growing
39
+ * `HARNESS_IDS`, one harness implementation, and — where that family needs them
40
+ * — a member on `BuiltinLaunchRequest` and a strict `[harness.<family>]` table
41
+ * for its own slice of the template (never passthrough; parsed options are typed
42
+ * and merged per field like every other template field). That member is the
43
+ * whole of what the family's `buildArgs` and `prepare` read, so the fields
44
+ * arrive with their first reader, never before.
45
+ *
46
+ * A *plugin* harness grows none of that: it registers a `PluginHarness` under
47
+ * its own id (see harness/harness-registry.ts and plugin/contract.ts), so its id
48
+ * is not in `HARNESS_IDS` and its CLI is not a built-in family's. A
49
+ * `harness_type` may still name it — the session's registry is what makes the id
50
+ * real. It is the same `Harness` contract with `SubagentLaunchInputs` as its
51
+ * launch type — its own options live in its own code — so a plugin can never
52
+ * claim a built-in family's request member.
53
+ */
54
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
55
+ import type { AgentMultiplexerKind, PaneControl } from "./agent-host.js";
56
+ /**
57
+ * Every built-in harness. `HarnessId` derives from this; a `harness_type` may
58
+ * also name a plugin harness's id, which is not one.
59
+ *
60
+ * `opencode` runs a binary of its own rather than pi: it is probed like every
61
+ * other harness and shows up wherever its binary is on PATH, and its own
62
+ * implementation stages the agent definition its launch reads. `codex` is the
63
+ * same kind of harness: probed by its binary, with its launch reading the
64
+ * staged system prompt file through a config override. `claude` is the same
65
+ * shape with a staged config directory instead of a staged definition.
66
+ */
67
+ export declare const HARNESS_IDS: readonly ["pi", "pig", "pi-bolt", "opencode", "codex", "claude"];
68
+ export type HarnessId = (typeof HARNESS_IDS)[number];
69
+ /**
70
+ * A harness id a value names: one of the built-ins (`HarnessId`) or a plugin
71
+ * harness's own id. Every id that is read, written, or passed around is this
72
+ * type — `HarnessId` alone would say a plugin harness cannot be named, and a
73
+ * bare `string` would say nothing about the built-ins, which are the ids that
74
+ * autocomplete here. A closed vocabulary is still `HarnessId`: the ids a
75
+ * built-in implementation is keyed by, and the built-in set a menu offers.
76
+ */
77
+ export type AnyHarnessId = HarnessId | (string & {});
78
+ /** A template that omits `harness_type` launches under pi. */
79
+ export declare const DEFAULT_HARNESS: HarnessId;
80
+ /**
81
+ * The harnesses that run the pi binary behind the pane: one model catalog and
82
+ * one default model serve the whole family, so pig and pi-bolt are configured
83
+ * through pi's row rather than rows of their own.
84
+ */
85
+ export declare const PI_FAMILY_HARNESS_IDS: readonly ["pi", "pig", "pi-bolt"];
86
+ /** One of the pi family's ids (see PI_FAMILY_HARNESS_IDS). */
87
+ export type PiFamilyHarnessId = (typeof PI_FAMILY_HARNESS_IDS)[number];
88
+ /**
89
+ * Whether this harness runs the pi binary (see PI_FAMILY_HARNESS_IDS). Narrowing,
90
+ * so the branch that builds the pi family's launch request is typed against a
91
+ * pi-family harness; a plugin harness id is never one. "Foreign" is this
92
+ * predicate's complement and nothing more: the set of harness ids that are not
93
+ * pi-family is not a closed vocabulary, so it has no type of its own — the ids
94
+ * that carry one are plain `string` and this is the gate.
95
+ */
96
+ export declare function isPiFamilyHarness(id: string): id is PiFamilyHarnessId;
97
+ /**
98
+ * Narrow untrusted input (config, menu) to a canonical built-in harness; a
99
+ * plugin harness id is not in `HARNESS_IDS`, so it is not what this returns.
100
+ * Callers that must accept a plugin id use the registry's own parse.
101
+ */
102
+ export declare function parseHarnessId(value: unknown): HarnessId | undefined;
103
+ /** How the child's tool set is chosen; `default` leaves the binary's own discovery untouched. */
104
+ export type ToolSelection = {
105
+ kind: "default";
106
+ } | {
107
+ kind: "none";
108
+ } | {
109
+ kind: "include";
110
+ names: string[];
111
+ } | {
112
+ kind: "exclude";
113
+ names: string[];
114
+ };
115
+ /**
116
+ * How extensions reach the child process. `default` leaves the child's own
117
+ * discovery alone; an explicit list is resolved to sources and carried as
118
+ * `paths`, because the child cannot re-resolve names itself.
119
+ */
120
+ export type ExtensionLaunchMode = {
121
+ kind: "default";
122
+ } | {
123
+ kind: "none";
124
+ } | {
125
+ kind: "paths";
126
+ paths: string[];
127
+ };
128
+ /**
129
+ * How the child gets its skills. `default` leaves the child's own discovery
130
+ * alone; `none` suppresses it because the extension decided the agent's skills
131
+ * itself (an explicit or inlined list rendered into the system prompt).
132
+ */
133
+ export type SkillLaunchMode = {
134
+ kind: "default";
135
+ } | {
136
+ kind: "none";
137
+ };
138
+ /**
139
+ * Launch inputs every harness family shares. All fields are required;
140
+ * a value the run does not carry is a real state (`null` or a union member),
141
+ * never an absent field. The subagent token is not among them: it is a pure
142
+ * function of the subagent id (`subagentTokenFor`), so a harness derives it
143
+ * rather than receives it — two fields where one derives from the other can
144
+ * only be redundant or wrong.
145
+ */
146
+ export interface SubagentLaunchInputs {
147
+ readonly subagentId: string;
148
+ /** Absolute path of the staged system prompt (multi-line text never crosses herdr's single-line shell encoder). */
149
+ readonly systemPromptFile: string;
150
+ /** Absolute path of the staged task; the harness decides how it rides the argv. */
151
+ readonly taskFile: string;
152
+ /** Absolute path of the file the child reports through. */
153
+ readonly resultFile: string;
154
+ /** `null` = no model override was requested. */
155
+ readonly modelKey: string | null;
156
+ readonly toolSelection: ToolSelection;
157
+ }
158
+ /** pi CLI specifics; no other harness family reads these. */
159
+ export interface PiLaunchInputs {
160
+ /** `null` = no thinking override was requested. */
161
+ readonly thinkingLevel: string | null;
162
+ /** `null` = no fork — not requested, or requested with no parent session file (the orchestrator warns there). */
163
+ readonly forkSessionFile: string | null;
164
+ readonly skills: SkillLaunchMode;
165
+ readonly extensions: ExtensionLaunchMode;
166
+ readonly projectTrusted: boolean;
167
+ }
168
+ /** opencode CLI specifics; no other harness family reads these. */
169
+ export interface OpencodeLaunchInputs {
170
+ /**
171
+ * `null` = no variant was requested. A variant has no flag of its own: it
172
+ * rides the model reference on the argv, so one with no model to join names
173
+ * nothing.
174
+ */
175
+ readonly variant: string | null;
176
+ }
177
+ /** codex CLI specifics; no other harness family reads these. */
178
+ export interface CodexLaunchInputs {
179
+ /**
180
+ * Whether the project is trusted: where pi passes `--approve`, codex asks
181
+ * never; where pi passes `--no-approve`, codex asks on request. The sandbox
182
+ * is not here — the child's report file lives outside the workspace, so it
183
+ * stays `workspace-write` whatever the trust.
184
+ */
185
+ readonly projectTrusted: boolean;
186
+ }
187
+ /**
188
+ * The launch-request families: the pi family (pi, pig, pi-bolt), opencode, codex
189
+ * and claude. Filtered from the multiplexer's kinds rather than re-declared, so
190
+ * the two vocabularies cannot drift apart; each member of `BuiltinLaunchRequest`
191
+ * carries one as its `family` tag, and a template's family-keyed tables are keyed
192
+ * by them. A harness id is mapped to its family by the registry; a plugin
193
+ * harness's id is not one.
194
+ */
195
+ export type HarnessFamily = Extract<AgentMultiplexerKind, "pi" | "opencode" | "codex" | "claude">;
196
+ /** The family tag one launch request carries; the tag alone selects the member. */
197
+ interface HarnessFamilyTag<F extends HarnessFamily> {
198
+ readonly family: F;
199
+ }
200
+ /** pi's argv request: the shared launch inputs plus pi's own CLI flags. */
201
+ export type PiFamilyLaunchRequest = HarnessFamilyTag<"pi"> & SubagentLaunchInputs & PiLaunchInputs;
202
+ /**
203
+ * opencode's argv request: the shared launch inputs plus opencode's own CLI
204
+ * specifics.
205
+ */
206
+ export type OpencodeLaunchRequest = HarnessFamilyTag<"opencode"> & SubagentLaunchInputs & OpencodeLaunchInputs;
207
+ /**
208
+ * codex's argv request: the shared launch inputs plus codex's own CLI
209
+ * specifics.
210
+ */
211
+ export type CodexLaunchRequest = HarnessFamilyTag<"codex"> & SubagentLaunchInputs & CodexLaunchInputs;
212
+ /**
213
+ * claude's argv request: the shared launch inputs alone. claude reads no
214
+ * family-specific inputs — its model key and tool selection already ride the
215
+ * shared inputs, the system prompt rides a staged file the argv names, and the
216
+ * task rides the pane launcher — so the member is the tag plus the shared
217
+ * shape, with no third conjunct to grow stale.
218
+ */
219
+ export type ClaudeLaunchRequest = HarnessFamilyTag<"claude"> & SubagentLaunchInputs;
220
+ /**
221
+ * The launch request a built-in harness reads, keyed by family: pi's flags are
222
+ * what a `"pi"` request is, so they cannot ride to a harness that never mapped
223
+ * them. One is built per launch, and both `buildArgs` and `prepare` read that
224
+ * same object. A new family adds a member — never an optional field on an
225
+ * existing member.
226
+ */
227
+ export type BuiltinLaunchRequest = PiFamilyLaunchRequest | OpencodeLaunchRequest | CodexLaunchRequest | ClaudeLaunchRequest;
228
+ /**
229
+ * The launch request one harness id reads: the argv it builds and the pane
230
+ * state it prepares. Keyed by id, so a harness added to `HARNESS_IDS` without a
231
+ * request fails to compile; the pi family shares one member because they all
232
+ * run the pi binary.
233
+ */
234
+ export type LaunchRequestFor<K extends HarnessId> = {
235
+ pi: PiFamilyLaunchRequest;
236
+ pig: PiFamilyLaunchRequest;
237
+ "pi-bolt": PiFamilyLaunchRequest;
238
+ opencode: OpencodeLaunchRequest;
239
+ codex: CodexLaunchRequest;
240
+ claude: ClaudeLaunchRequest;
241
+ }[K];
242
+ /**
243
+ * Represents an incompatible value rejected during harness configuration
244
+ * validation. `keyPath` is relative to the harness's section (for example,
245
+ * `configInclude[0]`), and `layer` indicates whether the value originated from
246
+ * the global or project file.
247
+ */
248
+ export interface HarnessConfigIssue {
249
+ readonly layer: "global" | "project";
250
+ readonly keyPath: string;
251
+ readonly got: unknown;
252
+ readonly expected: string;
253
+ }
254
+ /** Callback a codec calls to report each value it rejected. */
255
+ export type HarnessConfigReport = (issue: HarnessConfigIssue) => void;
256
+ /**
257
+ * The configuration slices a codec validates, as the file loader kept them:
258
+ * absent when a file has no section for this harness, else a JSON object.
259
+ * `project` is absent unless the codec declared `scope: "project"`.
260
+ */
261
+ export interface HarnessConfigLayers {
262
+ readonly global?: Readonly<Record<string, unknown>>;
263
+ readonly project?: Readonly<Record<string, unknown>>;
264
+ }
265
+ /**
266
+ * Configuration codec for a harness. Defines the schema, validation rules, and
267
+ * defaults for a harness's configuration section. When `scope` is omitted,
268
+ * validation is global-only and ignores project configuration files. When set
269
+ * to `"project"`, `parse` receives both global and project layers. `parse`
270
+ * always returns a usable value, reporting each rejected value instead of
271
+ * failing the whole section.
272
+ */
273
+ export interface HarnessConfigCodec<T = unknown> {
274
+ readonly scope?: "global" | "project";
275
+ parse(layers: HarnessConfigLayers, report: HarnessConfigReport): T;
276
+ }
277
+ /** What a harness needs to bring its host pane into the state it launches in. */
278
+ export interface HarnessPrepareRequest<L extends SubagentLaunchInputs = HarnessLaunch, C = unknown> {
279
+ readonly pi: ExtensionAPI;
280
+ /** The validated config for this harness, as its codec produced it. */
281
+ readonly config: C;
282
+ /**
283
+ * The pane surface the session's multiplexer offers. A harness types into its
284
+ * pane through this, never through a multiplexer's own client, so one launch runs
285
+ * under any multiplexer that offers the surface.
286
+ */
287
+ readonly pane: PaneControl;
288
+ readonly paneId: string;
289
+ readonly cwd: string;
290
+ /**
291
+ * The launch this pane is prepared for: the task file the pane must read, the
292
+ * system prompt file, the subagent id a launcher names itself after — the same
293
+ * request `buildArgs` was given, so a built-in family's own inputs reach its
294
+ * own harness and no other's, and a plugin reads the shared inputs alone.
295
+ */
296
+ readonly launch: L;
297
+ }
298
+ /**
299
+ * The run identity and address half of a teardown request. `paneId` is
300
+ * `null` when the pane is already gone; `cwd` is `null` when no directory
301
+ * address is known to the caller (a recovered run with no worktree).
302
+ */
303
+ export interface HarnessTeardownContext {
304
+ readonly paneId: string | null;
305
+ readonly cwd: string | null;
306
+ readonly subagentId: string;
307
+ }
308
+ /** The full teardown request: the context plus the pi instance a harness shells out through. */
309
+ export interface HarnessTeardownRequest extends HarnessTeardownContext {
310
+ readonly pi: ExtensionAPI;
311
+ }
312
+ /**
313
+ * One model a harness can run. `key` is the bare `"provider/model"` every layer
314
+ * stores and every CLI flag carries; `label` is the optional display form a
315
+ * picker shows in place of the key.
316
+ */
317
+ export interface ModelEntry {
318
+ readonly key: string;
319
+ readonly label?: string;
320
+ }
321
+ /**
322
+ * The slice of pi's model registry a harness reads to list what it can run:
323
+ * which models are available, in the registry's own order. Structural, so the
324
+ * harness layer never imports pi's registry type — and it is deliberately the
325
+ * whole of what the pi family's list reads, nothing more.
326
+ */
327
+ export interface ModelCatalog {
328
+ getAvailable(): readonly {
329
+ readonly provider: string;
330
+ readonly id: string;
331
+ }[];
332
+ }
333
+ /**
334
+ * What a harness's on-demand model list needs. The registry lives on the
335
+ * extension context (`ctx.modelRegistry`) rather than on the `ExtensionAPI`, so
336
+ * it is injected here instead of read from the shell.
337
+ */
338
+ export interface HarnessListModelsRequest {
339
+ readonly pi: ExtensionAPI;
340
+ readonly modelCatalog: ModelCatalog;
341
+ }
342
+ /**
343
+ * Lists the models one harness can run. Never throws: a list that could not be
344
+ * produced is an empty one with a logged reason, so a menu always opens.
345
+ */
346
+ export type HarnessListModels = (request: HarnessListModelsRequest) => Promise<readonly ModelEntry[]>;
347
+ /**
348
+ * A harness's answer about this machine, with the line for the human riding the
349
+ * arm it explains.
350
+ *
351
+ * `unavailable` keeps the harness out of the setting's offer. The notice is
352
+ * present only where the machine has something surprising to report — a binary
353
+ * that is installed but speaks another major; a binary that is simply missing
354
+ * says nothing, because nothing about the machine is unexpected there.
355
+ */
356
+ export type HarnessAvailability = {
357
+ readonly status: "available";
358
+ } | {
359
+ readonly status: "unavailable";
360
+ readonly notice?: string;
361
+ };
362
+ /**
363
+ * One harness implementation, over the launch type it reads: a built-in's
364
+ * `LaunchRequestFor<K>` (its family's request), or `SubagentLaunchInputs` for a
365
+ * plugin. The type parameter is what keeps one family's options out of another
366
+ * implementation: a pi harness cannot name `variant`, and a plugin cannot name
367
+ * any built-in option at all.
368
+ */
369
+ export interface Harness<L extends SubagentLaunchInputs = HarnessLaunch, C = unknown> {
370
+ /**
371
+ * Configuration codec for this harness. Validated after plugins register; the
372
+ * parsed value is passed to `prepare` as `request.config`.
373
+ */
374
+ readonly config?: HarnessConfigCodec<C>;
375
+ /**
376
+ * The agent kind this harness launches as, in the multiplexer's vocabulary; the only
377
+ * place a kind appears as a literal. A harness whose binary is not pi's can
378
+ * only launch under its own kind, because the multiplexer matches the detected process
379
+ * against it.
380
+ */
381
+ readonly agentMultiplexerKind: AgentMultiplexerKind;
382
+ /**
383
+ * What this machine can do with the harness, read at probe time. `unavailable`
384
+ * keeps the harness out of the setting, and a template that still names it
385
+ * falls back to pi instead of opening a pane that could never run it. The
386
+ * notice, where there is one, is shown to the human once the UI exists.
387
+ */
388
+ availability(): HarnessAvailability;
389
+ /**
390
+ * Bring the pane into the state this harness launches in, for the launch this
391
+ * family's own request describes. Idempotent; throws when the state could not
392
+ * be established.
393
+ */
394
+ prepare(request: HarnessPrepareRequest<L, C>): Promise<void>;
395
+ /**
396
+ * The complete argv the pane runs, including how the task rides (the pi
397
+ * family ends with `@<taskFile>`). Pure: no shellouts, no filesystem writes.
398
+ * Typed to this harness's own launch, so one family's flags cannot reach
399
+ * another's buildArgs, and a plugin reads only the shared inputs.
400
+ */
401
+ buildArgs(launch: L): string[];
402
+ /**
403
+ * Undo filesystem state this harness's prepare left behind. Best-effort and
404
+ * idempotent: callers wrap it so a failure is logged and never masks the
405
+ * error that led to it, and it must succeed when there is nothing to remove
406
+ * (a launch that failed before prepare, or a run that never prepared).
407
+ * Owned by the async cleanup plane, ordered before any worktree dirty
408
+ * probe — never invoked from synchronous code.
409
+ */
410
+ teardown(request: HarnessTeardownRequest): Promise<void>;
411
+ /**
412
+ * The models this harness can run, listed on demand — when a menu opens, and
413
+ * when the spawn wizard opens. The pi family reads its catalog live on
414
+ * every call. opencode and codex answer from their memoized fetches, so the
415
+ * boot warm and every menu select share one CLI run; an empty answer is
416
+ * never retained, so a failed list retries on the next read instead of
417
+ * pinning an empty row.
418
+ */
419
+ listModels(request: HarnessListModelsRequest): Promise<readonly ModelEntry[]>;
420
+ /**
421
+ * Warm the model list in the background at boot. Required, with an explicit
422
+ * no-op for a harness whose list is cheap — a harness that needs warming
423
+ * but forgets this compiles loudly missing, never silently cold.
424
+ * Fire-and-forget, so a slow channel never blocks the launch.
425
+ */
426
+ prefetchModels(pi: ExtensionAPI): void;
427
+ }
428
+ /**
429
+ * A plugin harness's launch: the shared inputs plus the open arm's tag.
430
+ * `family` is the union's one discriminant; `"plugin"` is not a built-in
431
+ * family, so the tag can never be mistaken for one, and the plugin's own id
432
+ * stays where it belongs — in the plan, not in the request. Nothing else rides
433
+ * here: a plugin's own options live in its own code.
434
+ */
435
+ export interface PluginLaunchRequest extends SubagentLaunchInputs {
436
+ readonly family: "plugin";
437
+ }
438
+ /**
439
+ * What one launch carries: a built-in family's request or the plugin arm.
440
+ * `family` discriminates them: a built-in arm names its family, and the open
441
+ * arm names `"plugin"`, so a plugin request can never equal a built-in family
442
+ * and an exhaustive switch over the built-in arms still bottoms out at `never`.
443
+ */
444
+ export type HarnessLaunch = BuiltinLaunchRequest | PluginLaunchRequest;
445
+ /**
446
+ * One plugin harness: the same `Harness` contract a built-in implements, over
447
+ * the shared launch inputs, plus the identity a plugin supplies for itself
448
+ * because it is not keyed in this package's built-in table. The registry holds
449
+ * it as the same `RegisteredHarness` a built-in becomes (see
450
+ * harness/harness-registry.ts), so a caller never branches on where it came from.
451
+ * `C` is the value its codec parses, which types the prepare request's config.
452
+ */
453
+ export interface PluginHarness<C = unknown> extends Harness<SubagentLaunchInputs, C> {
454
+ /** The id config and `harness_type`-shaped values name this harness by. */
455
+ readonly id: AnyHarnessId;
456
+ /** The label its settings rows show. */
457
+ readonly displayName: string;
458
+ }
459
+ export {};
@@ -1,46 +1,59 @@
1
1
  /**
2
2
  * harness.ts — the harness contract: which process launches a subagent, and how.
3
3
  *
4
- * A harness owns five things: the mux agent kind its process launches as
5
- * (`agentMuxKind`), bringing its host pane into the state it launches in
4
+ * A harness owns five things: the multiplexer agent kind its process launches as
5
+ * (`agentMultiplexerKind`), bringing its host pane into the state it launches in
6
6
  * (`prepare`), the argv the pane runs (`buildArgs`), undoing any state it
7
7
  * left on the filesystem (`teardown`), and warming a slow model list at boot
8
- * (`prefetchModels`). What every harness family has in common
9
- * lives here as `SubagentLaunchInputs`; what one family alone uses (pi's CLI
10
- * flags, opencode's variant, codex's project trust) lives beside it as that
11
- * family's inputs, so a second family adds a request member — never an
12
- * optional field, a passthrough schema, or a raw config record on a shared
13
- * type. One request carries one family's launch, and both `buildArgs` and
14
- * `prepare` read it, so nothing a harness is handed belongs to a family it
15
- * does not launch. The listing request below (`HarnessListModelsRequest`) is
8
+ * (`prefetchModels`). One `Harness<L>` contract serves a built-in and a plugin;
9
+ * `L` is the launch type the implementation reads. What every harness has in
10
+ * common lives here as `SubagentLaunchInputs`; what one built-in family alone
11
+ * uses (pi's CLI flags, opencode's variant, codex's project trust) lives beside
12
+ * it as that family's inputs, so a second family adds a request member — never
13
+ * an optional field, a passthrough schema, or a raw config record on a shared
14
+ * type. One request carries one launch, and both `buildArgs` and `prepare` read
15
+ * it, so a built-in is handed its family's request and a plugin is handed the
16
+ * shared inputs alone. The listing request below (`HarnessListModelsRequest`) is
16
17
  * the one shared request that breaks that shape, because one call answers for
17
18
  * every runnable harness at once: a family's own input rides it as a field
18
19
  * named after that family, never as a member a caller has to pick. Each
19
20
  * harness's implementation lives beside this module (harness/pig.ts,
20
21
  * harness/pi-bolt.ts, harness/opencode/index.ts, harness/codex.ts,
21
- * harness/claude/index.ts) and is selected through harness/registry.ts.
22
+ * harness/claude/index.ts) and is selected through harness/harness-registry.ts.
22
23
  *
23
- * `HARNESS_IDS` stays the full vocabulary everywhere a value is read or written:
24
- * a template written where a harness exists must still load where it does not.
25
- * Which harnesses a machine can launch only narrows what the setting offers and
26
- * which harness a spawn ends up using.
24
+ * `HARNESS_IDS` is the built-in vocabulary, and it stays whole wherever a value
25
+ * is read or written: a template written for a built-in harness must still load
26
+ * on a machine that cannot launch it — only its launch falls back to pi. A value
27
+ * naming a plugin harness is a different case: it is legal because this
28
+ * session's registry has that id, so an id no harness registered is reported
29
+ * rather than downgraded (see agent-types.ts). Which harnesses a machine can
30
+ * launch only narrows what the setting offers and which harness a spawn ends up
31
+ * using.
27
32
  *
28
33
  * Model lists belong to the harness too (`listModels`): one interface method
29
34
  * answers "what can this harness run" for the pi family's catalog and for a
30
35
  * foreign CLI alike, so a settings menu enumerates harness rows instead of
31
36
  * knowing each family's source.
32
37
  *
33
- * Evolution rule: a new harness family is added by growing `HARNESS_IDS`, one
34
- * harness implementation, and — where that family needs them — a member on
35
- * `HarnessLaunchRequest` and a strict `[harness.<family>]` table for its own
36
- * slice of the template (never passthrough; parsed options are typed and merged
37
- * per field like every other template field). That member is the whole of what
38
- * the family's `buildArgs` and `prepare` read, so the fields arrive with their
39
- * first reader, never before.
38
+ * Evolution rule: a new *built-in* harness family is added by growing
39
+ * `HARNESS_IDS`, one harness implementation, and — where that family needs them
40
+ * — a member on `BuiltinLaunchRequest` and a strict `[harness.<family>]` table
41
+ * for its own slice of the template (never passthrough; parsed options are typed
42
+ * and merged per field like every other template field). That member is the
43
+ * whole of what the family's `buildArgs` and `prepare` read, so the fields
44
+ * arrive with their first reader, never before.
45
+ *
46
+ * A *plugin* harness grows none of that: it registers a `PluginHarness` under
47
+ * its own id (see harness/harness-registry.ts and plugin/contract.ts), so its id
48
+ * is not in `HARNESS_IDS` and its CLI is not a built-in family's. A
49
+ * `harness_type` may still name it — the session's registry is what makes the id
50
+ * real. It is the same `Harness` contract with `SubagentLaunchInputs` as its
51
+ * launch type — its own options live in its own code — so a plugin can never
52
+ * claim a built-in family's request member.
40
53
  */
41
- import { isAvailable, isProven } from "../availability.js";
42
54
  /**
43
- * Every selectable harness. The `harness_type` enum and `HarnessId` derive from this.
55
+ * Every built-in harness. `HarnessId` derives from this; a `harness_type` may
56
+ * also name a plugin harness's id, which is not one.
44
57
  *
45
58
  * `opencode` runs a binary of its own rather than pi: it is probed like every
46
59
  * other harness and shows up wherever its binary is on PATH, and its own
@@ -68,43 +81,19 @@ export const PI_FAMILY_HARNESS_IDS = ["pi", "pig", "pi-bolt"];
68
81
  /**
69
82
  * Whether this harness runs the pi binary (see PI_FAMILY_HARNESS_IDS). Narrowing,
70
83
  * so the branch that builds the pi family's launch request is typed against a
71
- * pi-family harness.
84
+ * pi-family harness; a plugin harness id is never one. "Foreign" is this
85
+ * predicate's complement and nothing more: the set of harness ids that are not
86
+ * pi-family is not a closed vocabulary, so it has no type of its own — the ids
87
+ * that carry one are plain `string` and this is the gate.
72
88
  */
73
89
  export function isPiFamilyHarness(id) {
74
90
  return PI_FAMILY_HARNESS_IDS.some((family) => family === id);
75
91
  }
76
- /** How a harness's own settings row is labeled. */
77
- const HARNESS_DISPLAY_NAMES = {
78
- pi: "Pi",
79
- pig: "PiG",
80
- "pi-bolt": "Pi-Bolt",
81
- opencode: "OpenCode",
82
- codex: "Codex",
83
- claude: "Claude",
84
- };
85
- /** The display form of one harness, for the rows that configure it. */
86
- export function harnessDisplayName(id) {
87
- return HARNESS_DISPLAY_NAMES[id];
88
- }
89
- /** Narrow untrusted input (config, menu) to a canonical harness; invalid values fall back at the config boundary. */
90
- export function parseHarnessId(value) {
91
- return HARNESS_IDS.find((id) => id === value);
92
- }
93
92
  /**
94
- * Which harness a spawn launches under. A harness this machine cannot launch
95
- * falls back to pi whatever the setting or the template says — the same answer
96
- * the setting itself is narrowed to, so the menu can never offer a harness a
97
- * spawn would not use, and an unavailable value never fails a spawn.
93
+ * Narrow untrusted input (config, menu) to a canonical built-in harness; a
94
+ * plugin harness id is not in `HARNESS_IDS`, so it is not what this returns.
95
+ * Callers that must accept a plugin id use the registry's own parse.
98
96
  */
99
- export function resolveHarness(configured, availability) {
100
- return isAvailable(configured, availability) ? configured : DEFAULT_HARNESS;
101
- }
102
- /**
103
- * The harnesses a spawn here can really use, in `HARNESS_IDS` order. pi runs the
104
- * pane it would launch in, so the family answers always; any other harness needs
105
- * the probe to have confirmed its binary, because only the binary itself can
106
- * list the models it runs.
107
- */
108
- export function runnableHarnessIds(availability) {
109
- return HARNESS_IDS.filter((id) => isPiFamilyHarness(id) || isProven(id, availability));
97
+ export function parseHarnessId(value) {
98
+ return HARNESS_IDS.find((id) => id === value);
110
99
  }