pi-cowboy 0.0.0 → 0.3.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 (137) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +281 -2
  3. package/agents/explore.toml +40 -0
  4. package/dist/agents/agent-assets.js +261 -0
  5. package/dist/agents/agent-cleanup.js +284 -0
  6. package/dist/agents/agent-discovery.js +108 -0
  7. package/dist/agents/agent-host.js +10 -0
  8. package/dist/agents/agent-manager.js +367 -0
  9. package/dist/agents/agent-reviver.js +64 -0
  10. package/dist/agents/agent-runner.js +288 -0
  11. package/dist/agents/agent-spawn-store.js +57 -0
  12. package/dist/agents/agent-template.js +46 -0
  13. package/dist/agents/agent-types.js +144 -0
  14. package/dist/agents/batch.js +92 -0
  15. package/dist/agents/cleanup-policy.js +194 -0
  16. package/dist/agents/cleanup-report.js +128 -0
  17. package/dist/agents/default-agents.js +19 -0
  18. package/dist/agents/harness/pi-bolt.js +15 -0
  19. package/dist/agents/harness/pi-compatible.js +68 -0
  20. package/dist/agents/harness/pig.js +16 -0
  21. package/dist/agents/harness/registry.js +27 -0
  22. package/dist/agents/harness.js +32 -0
  23. package/dist/agents/result-file-permissions.js +29 -0
  24. package/dist/agents/run-state.js +270 -0
  25. package/dist/agents/schemas/cleanup-batch.schema.js +19 -0
  26. package/dist/agents/schemas/cowboy-agents.schema.js +39 -0
  27. package/dist/agents/schemas/merge-batch.schema.js +25 -0
  28. package/dist/agents/schemas/steer-batch.schema.js +22 -0
  29. package/dist/agents/schemas/stop-batch.schema.js +18 -0
  30. package/dist/agents/spawn-defaults.js +70 -0
  31. package/dist/agents/subagent-session.js +601 -0
  32. package/dist/agents/tool-cleanup.js +57 -0
  33. package/dist/agents/tool-execution.js +125 -0
  34. package/dist/agents/tool-merge.js +190 -0
  35. package/dist/agents/tool-result.js +17 -0
  36. package/dist/agents/tool-steer.js +89 -0
  37. package/dist/agents/types.js +1 -0
  38. package/dist/availability.js +38 -0
  39. package/dist/config/config-io.js +261 -0
  40. package/dist/config/config-store.js +321 -0
  41. package/dist/config/config-validation.js +173 -0
  42. package/dist/config/layered-config.js +117 -0
  43. package/dist/config/types.js +23 -0
  44. package/dist/cow-support-launch.js +43 -0
  45. package/dist/events.js +146 -0
  46. package/dist/extension-toggle.js +28 -0
  47. package/dist/harness-availability-launch.js +23 -0
  48. package/dist/index.js +52 -0
  49. package/dist/infrastructure/exec-path.js +35 -0
  50. package/dist/infrastructure/git/cow-clone.js +398 -0
  51. package/dist/infrastructure/git/git-materializer.js +342 -0
  52. package/dist/infrastructure/git/git-merger.js +234 -0
  53. package/dist/infrastructure/git/git-retention.js +43 -0
  54. package/dist/infrastructure/git/git-runner.js +145 -0
  55. package/dist/infrastructure/git/git-worktree.js +143 -0
  56. package/dist/infrastructure/git/index.js +11 -0
  57. package/dist/infrastructure/git-client.js +11 -0
  58. package/dist/infrastructure/herdr/agent-stopper.js +60 -0
  59. package/dist/infrastructure/herdr/agents.js +329 -0
  60. package/dist/infrastructure/herdr/herdr-client.js +36 -0
  61. package/dist/infrastructure/herdr/herdr-transport.js +158 -0
  62. package/dist/infrastructure/herdr/index.js +15 -0
  63. package/dist/infrastructure/herdr/panes.js +174 -0
  64. package/dist/infrastructure/herdr/polling.js +44 -0
  65. package/dist/infrastructure/herdr/worktrees.js +76 -0
  66. package/dist/infrastructure/herdr-client.js +6 -0
  67. package/dist/infrastructure/herdr-host.js +163 -0
  68. package/dist/logger.js +79 -0
  69. package/dist/models/model-groups.js +72 -0
  70. package/dist/models/model-precedence.js +50 -0
  71. package/dist/models/model-request.js +108 -0
  72. package/dist/orchestrators/briefing-section.js +14 -0
  73. package/dist/orchestrators/context.js +116 -0
  74. package/dist/orchestrators/cues.js +90 -0
  75. package/dist/orchestrators/default-orchestrators.js +36 -0
  76. package/dist/orchestrators/orchestrator-discovery.js +68 -0
  77. package/dist/orchestrators/orchestrator-template.js +43 -0
  78. package/dist/orchestrators/orchestrator-types.js +78 -0
  79. package/dist/orchestrators/protocol.js +292 -0
  80. package/dist/orchestrators/types.js +7 -0
  81. package/dist/paths.js +66 -0
  82. package/dist/pi-settings.js +7 -0
  83. package/dist/predicates.js +25 -0
  84. package/dist/prompt/prompts.js +110 -0
  85. package/dist/prompt/skill-loader.js +153 -0
  86. package/dist/prompt/subagent-system-prompt.js +173 -0
  87. package/dist/registration.js +220 -0
  88. package/dist/shell.js +225 -0
  89. package/dist/spawn/cow-support.js +53 -0
  90. package/dist/spawn/herdr-launcher.js +80 -0
  91. package/dist/spawn/repo-lock.js +34 -0
  92. package/dist/spawn/sandbox.js +286 -0
  93. package/dist/spawn/spawn-coordinator.js +255 -0
  94. package/dist/spawn/spawn-id.js +39 -0
  95. package/dist/spawn/worktree-policy.js +137 -0
  96. package/dist/status-note.js +30 -0
  97. package/dist/subagent/ipc-protocol.js +68 -0
  98. package/dist/subagent/ipc.js +110 -0
  99. package/dist/subagent/pane-supervisor.js +24 -0
  100. package/dist/subagent/socket-ipc.js +240 -0
  101. package/dist/subagent/supervisor.js +315 -0
  102. package/dist/task-registry.js +258 -0
  103. package/dist/templates/template-files.js +84 -0
  104. package/dist/types.js +84 -0
  105. package/dist/ui/action-report.js +21 -0
  106. package/dist/ui/format.js +47 -0
  107. package/dist/ui/indicator.js +480 -0
  108. package/dist/ui/menu/helpers.js +227 -0
  109. package/dist/ui/menu/menu-agent-settings.js +182 -0
  110. package/dist/ui/menu/menu-agent-status.js +444 -0
  111. package/dist/ui/menu/menu-concurrency.js +226 -0
  112. package/dist/ui/menu/menu-model-settings.js +244 -0
  113. package/dist/ui/menu/menu-spawn-defaults.js +71 -0
  114. package/dist/ui/menu/menu-spawn-wizard.js +367 -0
  115. package/dist/ui/menu/menu-spawn-worktree.js +107 -0
  116. package/dist/ui/menu/menu-system-prompt.js +104 -0
  117. package/dist/ui/menu/menu-worktree-command.js +150 -0
  118. package/dist/ui/menu/menus.js +187 -0
  119. package/dist/ui/menu/model-picker.js +160 -0
  120. package/dist/ui/menu/screen-host.js +87 -0
  121. package/dist/ui/menu/submenus/confirm.js +23 -0
  122. package/dist/ui/menu/submenus/model-select.js +42 -0
  123. package/dist/ui/menu/submenus/name-field.js +43 -0
  124. package/dist/ui/menu/submenus/numeric-input.js +61 -0
  125. package/dist/ui/menu/submenus/target-select.js +129 -0
  126. package/dist/ui/menu/submenus/text-editor.js +49 -0
  127. package/dist/ui/menu/submenus/worktree-command-name.js +73 -0
  128. package/dist/ui/menu/submenus/worktree-name.js +53 -0
  129. package/dist/ui/menu/wrappers/settings-list.js +101 -0
  130. package/dist/ui/searchable-select.js +147 -0
  131. package/dist/ui/types.js +1 -0
  132. package/dist/utils.js +70 -0
  133. package/docs/assets/grazing.png +0 -0
  134. package/docs/assets/herdr-containers.png +0 -0
  135. package/docs/assets/logo-transparent.png +0 -0
  136. package/orchestrators/with-code-review.toml +20 -0
  137. package/package.json +109 -3
@@ -0,0 +1,270 @@
1
+ /**
2
+ * run-state.ts — One subagent run's state, and the spawn projections derived from it.
3
+ *
4
+ * The value holds two statuses with plain names. `process` is how far the
5
+ * subagent run itself got; `shell` is what the parent session still does for
6
+ * it. A run that has taken its terminal outcome carries it in `terminal`
7
+ * (the settlement: completed, stopped, or failed). Timestamps ride in as
8
+ * arguments, so this module does no I/O.
9
+ */
10
+ /** Exact projection for a queued session forgotten during parent disposal. */
11
+ export const DISPOSE_QUEUED_MESSAGE = "Agent manager disposed before the queued agent could start.";
12
+ /** A no-op transition returns its input, so callers can tell it did nothing. */
13
+ function unchanged(state) {
14
+ return state;
15
+ }
16
+ /** The initial state for a spawn queued at the given time. */
17
+ export function createRun(queuedAt) {
18
+ return {
19
+ process: { kind: "queued", queuedAt },
20
+ shell: "held",
21
+ };
22
+ }
23
+ /** queued -> launching. Anything else is already underway or over. */
24
+ export function startRun(state, startedAt) {
25
+ if (state.shell !== "held" || state.process.kind !== "queued")
26
+ return unchanged(state);
27
+ return {
28
+ process: {
29
+ kind: "launching",
30
+ queuedAt: state.process.queuedAt,
31
+ startedAt,
32
+ },
33
+ shell: state.shell,
34
+ };
35
+ }
36
+ /**
37
+ * launching -> active. A disposal in flight stays a disposal: the process
38
+ * moves but the gate stays open and the poll stays abandoned.
39
+ */
40
+ export function activateRun(state) {
41
+ if (state.shell === "dropped")
42
+ return unchanged(state);
43
+ if (state.process.kind !== "launching")
44
+ return unchanged(state);
45
+ return {
46
+ process: {
47
+ kind: "active",
48
+ queuedAt: state.process.queuedAt,
49
+ startedAt: state.process.startedAt,
50
+ },
51
+ shell: state.shell,
52
+ };
53
+ }
54
+ /** queued -> settled stopped, never started: the queue entry is cancelled. */
55
+ export function abortQueuedRun(state, initiator, completedAt) {
56
+ if (state.shell !== "held" || state.process.kind !== "queued")
57
+ return unchanged(state);
58
+ return {
59
+ process: {
60
+ kind: "settled",
61
+ queuedAt: state.process.queuedAt,
62
+ started: false,
63
+ terminal: { kind: "stopped", initiator },
64
+ completedAt,
65
+ },
66
+ shell: state.shell,
67
+ };
68
+ }
69
+ /**
70
+ * A start that never became a run. Queued stays never-started; launching keeps
71
+ * its start time, since the slot was taken and the launch was attempted.
72
+ */
73
+ export function failStart(state, error, completedAt) {
74
+ if (state.shell !== "held")
75
+ return unchanged(state);
76
+ if (state.process.kind === "queued")
77
+ return {
78
+ process: {
79
+ kind: "settled",
80
+ queuedAt: state.process.queuedAt,
81
+ started: false,
82
+ terminal: { kind: "failed", error },
83
+ completedAt,
84
+ },
85
+ shell: state.shell,
86
+ };
87
+ if (state.process.kind === "launching")
88
+ return {
89
+ process: {
90
+ kind: "settled",
91
+ queuedAt: state.process.queuedAt,
92
+ startedAt: state.process.startedAt,
93
+ started: true,
94
+ terminal: { kind: "failed", error },
95
+ completedAt,
96
+ },
97
+ shell: state.shell,
98
+ };
99
+ return unchanged(state);
100
+ }
101
+ /**
102
+ * A live process takes its terminal and enters the settle pass. The outcome
103
+ * ends a disposal: shell returns to held so the settlement reports normally.
104
+ */
105
+ export function enterSettling(state, terminal, completedAt) {
106
+ if (state.shell === "dropped")
107
+ return unchanged(state);
108
+ if (state.process.kind !== "launching" && state.process.kind !== "active")
109
+ return unchanged(state);
110
+ return {
111
+ process: {
112
+ kind: "settling",
113
+ queuedAt: state.process.queuedAt,
114
+ startedAt: state.process.startedAt,
115
+ terminal,
116
+ completedAt,
117
+ },
118
+ shell: "held",
119
+ };
120
+ }
121
+ /** The settle pass ran its effects; the terminal it carried is the outcome. */
122
+ export function finishSettling(state) {
123
+ if (state.shell !== "held" || state.process.kind !== "settling")
124
+ return unchanged(state);
125
+ return {
126
+ process: {
127
+ kind: "settled",
128
+ queuedAt: state.process.queuedAt,
129
+ startedAt: state.process.startedAt,
130
+ started: true,
131
+ terminal: state.process.terminal,
132
+ completedAt: state.process.completedAt,
133
+ },
134
+ shell: state.shell,
135
+ };
136
+ }
137
+ /**
138
+ * A delivered steer returns a settling or settled run to active with a fresh
139
+ * start time. The terminal — decided or carried — does not survive: the
140
+ * revived run settles again on its own report. Settling revives too, since a
141
+ * steer can land while the settle pass still awaits its probes.
142
+ */
143
+ export function reviveRun(state, startedAt) {
144
+ if (state.shell !== "held")
145
+ return unchanged(state);
146
+ if (state.process.kind !== "settling" && state.process.kind !== "settled")
147
+ return unchanged(state);
148
+ return {
149
+ process: {
150
+ kind: "active",
151
+ queuedAt: state.process.queuedAt,
152
+ startedAt,
153
+ },
154
+ shell: state.shell,
155
+ };
156
+ }
157
+ /** A queued run the parent discarded never started; its error says so. */
158
+ export function disposeQueuedRun(state, completedAt) {
159
+ if (state.shell !== "held" || state.process.kind !== "queued")
160
+ return unchanged(state);
161
+ return {
162
+ process: {
163
+ kind: "settled",
164
+ queuedAt: state.process.queuedAt,
165
+ started: false,
166
+ terminal: { kind: "failed", error: DISPOSE_QUEUED_MESSAGE },
167
+ completedAt,
168
+ },
169
+ shell: state.shell,
170
+ };
171
+ }
172
+ /**
173
+ * A live run the parent discarded keeps running under a disposal: the gate is
174
+ * open and the poll is abandoned, but the pane and process survive.
175
+ */
176
+ export function disposeLiveRun(state) {
177
+ if (state.shell !== "held")
178
+ return unchanged(state);
179
+ if (state.process.kind !== "launching" && state.process.kind !== "active")
180
+ return unchanged(state);
181
+ return {
182
+ process: state.process,
183
+ shell: "disposed",
184
+ };
185
+ }
186
+ /**
187
+ * A discarded session keeps the lifecycle it had: dropping snapshots the
188
+ * projection instead of deriving a new one.
189
+ */
190
+ export function dropRun(state, artifacts) {
191
+ if (state.shell === "dropped")
192
+ return unchanged(state);
193
+ return { shell: "dropped", lifecycle: projectLifecycle(state, artifacts) };
194
+ }
195
+ /** A launched run's settled projection: its terminal, plus what the launch and the settle pass left behind. */
196
+ function settledStartedOutcome(startedAt, terminal, completedAt, { launch, retention }) {
197
+ const shared = {
198
+ phase: "settled",
199
+ startedAt,
200
+ ...(launch === undefined ? {} : { launch }),
201
+ ...(retention === undefined ? {} : { worktreeRetentionReason: retention }),
202
+ };
203
+ switch (terminal.kind) {
204
+ case "completed":
205
+ return {
206
+ ...shared,
207
+ status: "completed",
208
+ result: terminal.result,
209
+ completedAt,
210
+ };
211
+ case "failed":
212
+ return { ...shared, status: "error", error: terminal.error, completedAt };
213
+ case "stopped":
214
+ return {
215
+ ...shared,
216
+ status: "stopped",
217
+ completedAt,
218
+ stop: { initiator: terminal.initiator },
219
+ };
220
+ }
221
+ }
222
+ /** A run that ended before launching: its terminal, and the queue time it never left. A never-launched run holds no launch. */
223
+ function settledNeverStartedOutcome(queuedAt, terminal, completedAt, { retention }) {
224
+ const shared = {
225
+ phase: "never-started",
226
+ queuedAt,
227
+ ...(retention === undefined ? {} : { worktreeRetentionReason: retention }),
228
+ };
229
+ switch (terminal.kind) {
230
+ case "failed":
231
+ return { ...shared, status: "error", error: terminal.error, completedAt };
232
+ case "stopped":
233
+ return {
234
+ ...shared,
235
+ status: "stopped",
236
+ completedAt,
237
+ stop: { initiator: terminal.initiator },
238
+ };
239
+ }
240
+ }
241
+ function projectProcess(process, artifacts) {
242
+ switch (process.kind) {
243
+ case "queued":
244
+ return { phase: "queued", queuedAt: process.queuedAt };
245
+ case "launching":
246
+ case "active":
247
+ return {
248
+ phase: "spawned",
249
+ startedAt: process.startedAt,
250
+ ...(artifacts.launch === undefined ? {} : { launch: artifacts.launch }),
251
+ };
252
+ case "settling":
253
+ return settledStartedOutcome(process.startedAt, process.terminal, process.completedAt, artifacts);
254
+ case "settled":
255
+ return process.started
256
+ ? settledStartedOutcome(process.startedAt, process.terminal, process.completedAt, artifacts)
257
+ : settledNeverStartedOutcome(process.queuedAt, process.terminal, process.completedAt, artifacts);
258
+ }
259
+ }
260
+ /**
261
+ * The one derivation of the spawn's lifecycle from the run. A settling process
262
+ * already projects settled — the run is not settled until the pass ends, but
263
+ * its outcome is decided. A disposal projects its live process; a drop returns
264
+ * the frozen lifecycle it stored.
265
+ */
266
+ export function projectLifecycle(state, artifacts) {
267
+ if (state.shell === "dropped")
268
+ return state.lifecycle;
269
+ return projectProcess(state.process, artifacts);
270
+ }
@@ -0,0 +1,19 @@
1
+ /**
2
+ * cleanup-batch.schema.ts — TypeBox schema and derived type for the
3
+ * cleanup_cowboy_agent tool's parameters.
4
+ *
5
+ * One call cleans up one or more agents: every id in `agent_ids` runs the
6
+ * tracked-or-locate flow independently (best effort) and keeps its own
7
+ * structured `CleanupReport`, so a batch can partially succeed. The TS type
8
+ * derives from the schema via `Static<>` — there is no parallel hand-written
9
+ * interface.
10
+ */
11
+ import { Type } from "typebox";
12
+ const AGENT_IDS_DESCRIPTION = "REQUIRED. One or more agent ids to clean up (as printed by the cowboy_agent spawn result or a completion message). Every id is handled independently in input order — located (the locator runs for ids the store no longer tracks), cleaned up, and reported with its own agent status / pane / worktree / branch block — one id's outcome never blocks the rest. A repeated id is rejected before anything is removed — pass each id once. An agent that is still active is refused for its item only (stop it with stop_cowboy_agent, then clean up once it has settled).";
13
+ /** The call shape: one or more agent ids. No call-level flags. */
14
+ export const CleanupBatchSchema = Type.Object({
15
+ agent_ids: Type.Array(Type.String({ minLength: 1 }), {
16
+ minItems: 1,
17
+ description: AGENT_IDS_DESCRIPTION,
18
+ }),
19
+ }, { additionalProperties: false, required: ["agent_ids"] });
@@ -0,0 +1,39 @@
1
+ /**
2
+ * cowboy-agents.schema.ts — TypeBox schemas and derived types for the
3
+ * cowboy_agent tool's parameters.
4
+ *
5
+ * One schema describes one spawn (per-item params), the other describes the
6
+ * call shape (one or more spawns plus an optional call-level blocking flag).
7
+ * The TS types are derived from the schemas via `Static<>` — there is no
8
+ * parallel hand-written interface, so a schema change cannot leave the
9
+ * types behind.
10
+ *
11
+ * The cross-field rule (a non-background call requires exactly one agent)
12
+ * is not expressible in JSON Schema. It lives as a one-line guard at the
13
+ * top of `parseDelegationBatch` in `protocol.ts` — the schema file stays
14
+ * a single source of truth for the per-field shape.
15
+ */
16
+ import { Type } from "typebox";
17
+ const PROMPT_DESCRIPTION = "Task instructions for the agent. If the task requires code changes, the agent works in an isolated branch and will review and commit its changes upon approval. Do not instruct the agent to avoid committing when code modifications are needed.";
18
+ const TASK_NAME_DESCRIPTION = 'REQUIRED. Short 2-3 word task name (e.g. "fix login flow"). This single value names the agent\'s branch/tab/worktree/agent so you can recognize it at a glance, and the extension appends a unique spawn id so parallel spawns — and every entry in a batch — are always distinct. Limits: 3 words, 19 characters when slugged (lowercase, dashes). A longer name throws with the exact overshoot — retry with a shorter name. Missing name throws too. The same name twice in one call is rejected before anything spawns.';
19
+ const AGENT_TYPE_DESCRIPTION = 'Optional agent type; when omitted the configured default agent type is used ("general-purpose" unless changed in settings). An unknown or ambiguous name is rejected before any agent in the batch spawns. Available: general-purpose,Explore';
20
+ const MODEL_DESCRIPTION = 'Optional model for THIS agent as "provider/model-id". Leave it unset (the default) to use the configured default for this session and agent type — the usual case. Pass it when the user asked for a specific model for this task. When a previous attempt failed with a provider/model error, pass a different model here and instruct the agent in plain text to continue where the failed attempt left off. A model that is not in this session\'s registry fails the call before anything is spawned — leave it unset to use the configured default instead.';
21
+ /** One spawn's parameters: prompt + task_name required, agent_type/model optional. */
22
+ const CowboyAgentParamsSchema = Type.Object({
23
+ prompt: Type.String({ description: PROMPT_DESCRIPTION }),
24
+ task_name: Type.String({ description: TASK_NAME_DESCRIPTION }),
25
+ agent_type: Type.Optional(Type.String({ description: AGENT_TYPE_DESCRIPTION })),
26
+ model: Type.Optional(Type.String({ description: MODEL_DESCRIPTION })),
27
+ }, { additionalProperties: false, required: ["prompt", "task_name"] });
28
+ /**
29
+ * The call shape: one or more spawns in `agents`, and an optional
30
+ * `run_in_background` flag that applies to every item.
31
+ *
32
+ * The single-item blocking check (`run_in_background: false` requires
33
+ * exactly one item in `agents`) is enforced at the parse layer, not in
34
+ * the schema — see `protocol.ts`.
35
+ */
36
+ export const CowboyAgentsSchema = Type.Object({
37
+ agents: Type.Array(CowboyAgentParamsSchema, { minItems: 1 }),
38
+ run_in_background: Type.Optional(Type.Boolean()),
39
+ }, { additionalProperties: false, required: ["agents"] });
@@ -0,0 +1,25 @@
1
+ /**
2
+ * merge-batch.schema.ts — TypeBox schema and derived type for the
3
+ * merge_cowboy_branch tool's parameters.
4
+ *
5
+ * One call merges one or more settled agent branches into the same target:
6
+ * every branch in `branches` merges sequentially in input order (merges share
7
+ * one checkout, so parallel merging is impossible). A conflict halts the
8
+ * batch — the conflicted merge stays in progress for the orchestrator to
9
+ * resolve, and the remaining branches report as not attempted. The TS type
10
+ * derives from the schema via `Static<>` — there is no parallel hand-written
11
+ * interface.
12
+ */
13
+ import { Type } from "typebox";
14
+ const BRANCHES_DESCRIPTION = "REQUIRED. One or more settled agent branches to merge (the `cow-<task>-<id>` branches from the cowboy_agent result notes). Every branch merges sequentially in input order into the same `target`: merged, reported as already merged, or reported per item on failure — a non-conflict failure never blocks the rest. A repeated branch is rejected before anything merges — pass each branch once. A conflict halts the batch: the conflicted merge is left in progress (never auto-resolved) and the remaining branches are reported as not attempted.";
15
+ const TARGET_DESCRIPTION = "Merge target branch (default: main). Applies to every branch in `branches`: the repo's main checkout must be on the target before anything merges.";
16
+ const REPO_DESCRIPTION = "Any path inside the repo (default: the parent session's cwd). Applies to the whole call: the merge always runs in the repo's main checkout.";
17
+ /** The call shape: one or more branches plus call-level `target`/`repo`. */
18
+ export const MergeBatchSchema = Type.Object({
19
+ branches: Type.Array(Type.String({ minLength: 1 }), {
20
+ minItems: 1,
21
+ description: BRANCHES_DESCRIPTION,
22
+ }),
23
+ target: Type.Optional(Type.String({ description: TARGET_DESCRIPTION })),
24
+ repo: Type.Optional(Type.String({ description: REPO_DESCRIPTION })),
25
+ }, { additionalProperties: false, required: ["branches"] });
@@ -0,0 +1,22 @@
1
+ /**
2
+ * steer-batch.schema.ts — TypeBox schema and derived type for the
3
+ * steer_cowboy_agent tool's parameters.
4
+ *
5
+ * One call steers one or more agents with a single message: every id in
6
+ * `agent_ids` receives the same `message` independently (best effort) in
7
+ * input order, so a batch can partially succeed. A settled agent is revived
8
+ * by the delivery; a queued agent (no pane yet) and a cleaned-up agent
9
+ * (pane gone) are refused per item. The TS type derives from the schema via
10
+ * `Static<>` — there is no parallel hand-written interface.
11
+ */
12
+ import { Type } from "typebox";
13
+ const AGENT_IDS_DESCRIPTION = "REQUIRED. One or more agent ids to steer (as printed by the cowboy_agent spawn result or a completion message). Every id is handled independently in input order — delivered, or refused with its reason — and one id's refusal never blocks the rest. A settled agent is revived by the delivery. A repeated id is rejected before anything is delivered — pass each id once.";
14
+ const MESSAGE_DESCRIPTION = "REQUIRED. The single message delivered verbatim to every id in `agent_ids`. Plain instructions work best (e.g. \"stop refactoring; just fix the failing test and report\"). Delivery is fire-and-forget: nothing here waits for an agent to act on it. Because the text is entered into the agent's pi session, a command prefixed with `!` runs and adds its output to that agent's context, while `!!` runs it without adding the output to its context.";
15
+ /** The call shape: one or more agent ids plus the one message they all receive. No call-level flags. */
16
+ export const SteerBatchSchema = Type.Object({
17
+ agent_ids: Type.Array(Type.String({ minLength: 1 }), {
18
+ minItems: 1,
19
+ description: AGENT_IDS_DESCRIPTION,
20
+ }),
21
+ message: Type.String({ description: MESSAGE_DESCRIPTION }),
22
+ }, { additionalProperties: false, required: ["agent_ids", "message"] });
@@ -0,0 +1,18 @@
1
+ /**
2
+ * stop-batch.schema.ts — TypeBox schema and derived type for the
3
+ * stop_cowboy_agent tool's parameters.
4
+ *
5
+ * One call stops one or more agents: every id in `agent_ids` is handled
6
+ * independently (best effort) and reported with its own result line, so a
7
+ * batch can partially succeed. The TS type derives from the schema via
8
+ * `Static<>` — there is no parallel hand-written interface.
9
+ */
10
+ import { Type } from "typebox";
11
+ const AGENT_IDS_DESCRIPTION = "REQUIRED. One or more agent ids to stop (as printed by the cowboy_agent spawn result or a completion message). Every id is handled independently in input order: stopped, reported as already settled, or reported unknown — one id's outcome never blocks the rest. A repeated id is rejected before anything is stopped — pass each id once. Nothing is removed — the worktree and branch are preserved for inspection, merging (merge_cowboy_branch), or later cleanup (cleanup_cowboy_agent).";
12
+ /** The call shape: one or more agent ids. No call-level flags — stopping never blocks, so there is no background/foreground split. */
13
+ export const StopBatchSchema = Type.Object({
14
+ agent_ids: Type.Array(Type.String({ minLength: 1 }), {
15
+ minItems: 1,
16
+ description: AGENT_IDS_DESCRIPTION,
17
+ }),
18
+ }, { additionalProperties: false, required: ["agent_ids"] });
@@ -0,0 +1,70 @@
1
+ /**
2
+ * spawn-defaults.ts — what an omitted cowboy_agent param resolves to, read at
3
+ * call time over the live config store.
4
+ *
5
+ * - agent type: explicit `agent_type` → configured `defaultAgentType` →
6
+ * built-in `general-purpose`;
7
+ * - orchestrator: configured `defaultOrchestrator` → built-in `default`,
8
+ * resolved at spawn time by every spawn path;
9
+ * - worktree dirty-checkout policy: the agent template's key → the config
10
+ * setting;
11
+ * - harness: the agent template's `harness_type` → the config setting, then
12
+ * narrowed to the harnesses this machine can launch.
13
+ *
14
+ * A configured value that no longer resolves degrades to the built-in
15
+ * fallback instead of failing the spawn.
16
+ */
17
+ import { DEFAULT_AGENT_TYPE, DEFAULT_ORCHESTRATOR_NAME } from "../types.js";
18
+ import { getHarnessAvailability, getStore } from "../shell.js";
19
+ import { DEFAULT_ORCHESTRATORS } from "../orchestrators/default-orchestrators.js";
20
+ import { resolveOrchestrator } from "../orchestrators/orchestrator-types.js";
21
+ import { resolveHarness } from "./harness.js";
22
+ import { getAgentConfig, resolveType } from "./agent-types.js";
23
+ /** Unset/blank configured string. `""` is the only blank form the store writes. */
24
+ function configuredString(value) {
25
+ return typeof value === "string" && value !== "" ? value : undefined;
26
+ }
27
+ /** Configured `defaultAgentType` → built-in fallback. Returns the canonical registered key. */
28
+ export function resolveDefaultAgentType() {
29
+ const configured = configuredString(getStore().agent.defaultAgentType);
30
+ if (configured === undefined)
31
+ return DEFAULT_AGENT_TYPE;
32
+ const resolution = resolveType(configured);
33
+ return resolution.kind === "resolved" ? resolution.key : DEFAULT_AGENT_TYPE;
34
+ }
35
+ /** Configured `defaultOrchestrator` → built-in `default`, returned as written. */
36
+ export function resolveDefaultOrchestratorName() {
37
+ const configured = configuredString(getStore().agent.defaultOrchestrator);
38
+ if (configured === undefined)
39
+ return DEFAULT_ORCHESTRATOR_NAME;
40
+ if (configured === DEFAULT_ORCHESTRATOR_NAME)
41
+ return configured;
42
+ return resolveOrchestrator(configured)
43
+ ? configured
44
+ : DEFAULT_ORCHESTRATOR_NAME;
45
+ }
46
+ /** Explicit non-empty `agent_type` wins verbatim; anything else falls back to the configured default. Shared with the `tool_call` listener so both halves see the same type. */
47
+ export function resolveAgentTypeParam(raw) {
48
+ return typeof raw === "string" && raw !== ""
49
+ ? raw
50
+ : resolveDefaultAgentType();
51
+ }
52
+ /** Configured default → code `default`. Pure registry lookup — call before any worktree resolution. Returns the canonical config. */
53
+ export function resolveDefaultOrchestrator() {
54
+ const requested = resolveDefaultOrchestratorName();
55
+ const resolved = resolveOrchestrator(requested) ??
56
+ (requested === DEFAULT_ORCHESTRATOR_NAME
57
+ ? DEFAULT_ORCHESTRATORS[DEFAULT_ORCHESTRATOR_NAME]
58
+ : undefined);
59
+ return resolved ?? DEFAULT_ORCHESTRATORS[DEFAULT_ORCHESTRATOR_NAME];
60
+ }
61
+ /** Whether a dirty parent's WIP starts in this agent's worktree: the agent template's key wins over the config setting, read at call time like the other spawn defaults. */
62
+ export function resolveWorktreeCheckoutType(agentType) {
63
+ return (getAgentConfig(agentType)?.worktreeCheckoutType ??
64
+ getStore().agent.worktreeCheckoutType);
65
+ }
66
+ /** Which harness launches this agent: the agent template's `harness_type` wins over the config setting, read at call time like the other spawn defaults, and a harness this machine cannot launch falls back to pi. */
67
+ export function resolveHarnessType(agentType) {
68
+ const configured = getAgentConfig(agentType)?.harnessType ?? getStore().agent.harnessType;
69
+ return resolveHarness(configured, getHarnessAvailability());
70
+ }