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.
- package/LICENSE +21 -0
- package/README.md +281 -2
- package/agents/explore.toml +40 -0
- package/dist/agents/agent-assets.js +261 -0
- package/dist/agents/agent-cleanup.js +284 -0
- package/dist/agents/agent-discovery.js +108 -0
- package/dist/agents/agent-host.js +10 -0
- package/dist/agents/agent-manager.js +367 -0
- package/dist/agents/agent-reviver.js +64 -0
- package/dist/agents/agent-runner.js +288 -0
- package/dist/agents/agent-spawn-store.js +57 -0
- package/dist/agents/agent-template.js +46 -0
- package/dist/agents/agent-types.js +144 -0
- package/dist/agents/batch.js +92 -0
- package/dist/agents/cleanup-policy.js +194 -0
- package/dist/agents/cleanup-report.js +128 -0
- package/dist/agents/default-agents.js +19 -0
- package/dist/agents/harness/pi-bolt.js +15 -0
- package/dist/agents/harness/pi-compatible.js +68 -0
- package/dist/agents/harness/pig.js +16 -0
- package/dist/agents/harness/registry.js +27 -0
- package/dist/agents/harness.js +32 -0
- package/dist/agents/result-file-permissions.js +29 -0
- package/dist/agents/run-state.js +270 -0
- package/dist/agents/schemas/cleanup-batch.schema.js +19 -0
- package/dist/agents/schemas/cowboy-agents.schema.js +39 -0
- package/dist/agents/schemas/merge-batch.schema.js +25 -0
- package/dist/agents/schemas/steer-batch.schema.js +22 -0
- package/dist/agents/schemas/stop-batch.schema.js +18 -0
- package/dist/agents/spawn-defaults.js +70 -0
- package/dist/agents/subagent-session.js +601 -0
- package/dist/agents/tool-cleanup.js +57 -0
- package/dist/agents/tool-execution.js +125 -0
- package/dist/agents/tool-merge.js +190 -0
- package/dist/agents/tool-result.js +17 -0
- package/dist/agents/tool-steer.js +89 -0
- package/dist/agents/types.js +1 -0
- package/dist/availability.js +38 -0
- package/dist/config/config-io.js +261 -0
- package/dist/config/config-store.js +321 -0
- package/dist/config/config-validation.js +173 -0
- package/dist/config/layered-config.js +117 -0
- package/dist/config/types.js +23 -0
- package/dist/cow-support-launch.js +43 -0
- package/dist/events.js +146 -0
- package/dist/extension-toggle.js +28 -0
- package/dist/harness-availability-launch.js +23 -0
- package/dist/index.js +52 -0
- package/dist/infrastructure/exec-path.js +35 -0
- package/dist/infrastructure/git/cow-clone.js +398 -0
- package/dist/infrastructure/git/git-materializer.js +342 -0
- package/dist/infrastructure/git/git-merger.js +234 -0
- package/dist/infrastructure/git/git-retention.js +43 -0
- package/dist/infrastructure/git/git-runner.js +145 -0
- package/dist/infrastructure/git/git-worktree.js +143 -0
- package/dist/infrastructure/git/index.js +11 -0
- package/dist/infrastructure/git-client.js +11 -0
- package/dist/infrastructure/herdr/agent-stopper.js +60 -0
- package/dist/infrastructure/herdr/agents.js +329 -0
- package/dist/infrastructure/herdr/herdr-client.js +36 -0
- package/dist/infrastructure/herdr/herdr-transport.js +158 -0
- package/dist/infrastructure/herdr/index.js +15 -0
- package/dist/infrastructure/herdr/panes.js +174 -0
- package/dist/infrastructure/herdr/polling.js +44 -0
- package/dist/infrastructure/herdr/worktrees.js +76 -0
- package/dist/infrastructure/herdr-client.js +6 -0
- package/dist/infrastructure/herdr-host.js +163 -0
- package/dist/logger.js +79 -0
- package/dist/models/model-groups.js +72 -0
- package/dist/models/model-precedence.js +50 -0
- package/dist/models/model-request.js +108 -0
- package/dist/orchestrators/briefing-section.js +14 -0
- package/dist/orchestrators/context.js +116 -0
- package/dist/orchestrators/cues.js +90 -0
- package/dist/orchestrators/default-orchestrators.js +36 -0
- package/dist/orchestrators/orchestrator-discovery.js +68 -0
- package/dist/orchestrators/orchestrator-template.js +43 -0
- package/dist/orchestrators/orchestrator-types.js +78 -0
- package/dist/orchestrators/protocol.js +292 -0
- package/dist/orchestrators/types.js +7 -0
- package/dist/paths.js +66 -0
- package/dist/pi-settings.js +7 -0
- package/dist/predicates.js +25 -0
- package/dist/prompt/prompts.js +110 -0
- package/dist/prompt/skill-loader.js +153 -0
- package/dist/prompt/subagent-system-prompt.js +173 -0
- package/dist/registration.js +220 -0
- package/dist/shell.js +225 -0
- package/dist/spawn/cow-support.js +53 -0
- package/dist/spawn/herdr-launcher.js +80 -0
- package/dist/spawn/repo-lock.js +34 -0
- package/dist/spawn/sandbox.js +286 -0
- package/dist/spawn/spawn-coordinator.js +255 -0
- package/dist/spawn/spawn-id.js +39 -0
- package/dist/spawn/worktree-policy.js +137 -0
- package/dist/status-note.js +30 -0
- package/dist/subagent/ipc-protocol.js +68 -0
- package/dist/subagent/ipc.js +110 -0
- package/dist/subagent/pane-supervisor.js +24 -0
- package/dist/subagent/socket-ipc.js +240 -0
- package/dist/subagent/supervisor.js +315 -0
- package/dist/task-registry.js +258 -0
- package/dist/templates/template-files.js +84 -0
- package/dist/types.js +84 -0
- package/dist/ui/action-report.js +21 -0
- package/dist/ui/format.js +47 -0
- package/dist/ui/indicator.js +480 -0
- package/dist/ui/menu/helpers.js +227 -0
- package/dist/ui/menu/menu-agent-settings.js +182 -0
- package/dist/ui/menu/menu-agent-status.js +444 -0
- package/dist/ui/menu/menu-concurrency.js +226 -0
- package/dist/ui/menu/menu-model-settings.js +244 -0
- package/dist/ui/menu/menu-spawn-defaults.js +71 -0
- package/dist/ui/menu/menu-spawn-wizard.js +367 -0
- package/dist/ui/menu/menu-spawn-worktree.js +107 -0
- package/dist/ui/menu/menu-system-prompt.js +104 -0
- package/dist/ui/menu/menu-worktree-command.js +150 -0
- package/dist/ui/menu/menus.js +187 -0
- package/dist/ui/menu/model-picker.js +160 -0
- package/dist/ui/menu/screen-host.js +87 -0
- package/dist/ui/menu/submenus/confirm.js +23 -0
- package/dist/ui/menu/submenus/model-select.js +42 -0
- package/dist/ui/menu/submenus/name-field.js +43 -0
- package/dist/ui/menu/submenus/numeric-input.js +61 -0
- package/dist/ui/menu/submenus/target-select.js +129 -0
- package/dist/ui/menu/submenus/text-editor.js +49 -0
- package/dist/ui/menu/submenus/worktree-command-name.js +73 -0
- package/dist/ui/menu/submenus/worktree-name.js +53 -0
- package/dist/ui/menu/wrappers/settings-list.js +101 -0
- package/dist/ui/searchable-select.js +147 -0
- package/dist/ui/types.js +1 -0
- package/dist/utils.js +70 -0
- package/docs/assets/grazing.png +0 -0
- package/docs/assets/herdr-containers.png +0 -0
- package/docs/assets/logo-transparent.png +0 -0
- package/orchestrators/with-code-review.toml +20 -0
- package/package.json +109 -3
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* agents.ts — Layer 2: herdr agent resources.
|
|
3
|
+
*
|
|
4
|
+
* Start an agent into a pane, read the registry, send it input. One non-obvious
|
|
5
|
+
* rule: herdr's start-CLI readiness gate is meaningless for a subagent launched
|
|
6
|
+
* with an input message, so a readiness timeout is success here and only a
|
|
7
|
+
* transient "not an available shell" rejection is retried (retries are Layer 1
|
|
8
|
+
* polling).
|
|
9
|
+
*/
|
|
10
|
+
import * as path from "node:path";
|
|
11
|
+
import { createLogger } from "../../logger.js";
|
|
12
|
+
// isTaskAgentName lives in src/predicates.ts (shared leaf) so this layer never
|
|
13
|
+
// imports across into spawn/.
|
|
14
|
+
import { isTaskAgentName } from "../../predicates.js";
|
|
15
|
+
import { errorMessage } from "../../utils.js";
|
|
16
|
+
import { HerdrError, HerdrTransport, herdrErrorCode, isAgentGoneError, objectField, strField, } from "./herdr-transport.js";
|
|
17
|
+
import { keepPolling, pollUntil, settled } from "./polling.js";
|
|
18
|
+
const log = createLogger("herdr.agents");
|
|
19
|
+
// --- Constants ---
|
|
20
|
+
/**
|
|
21
|
+
* `herdr agent start` timeout (ms), at herdr's minimum (the CLI requires >3000).
|
|
22
|
+
* The gate it waits for ("ready for interactive input" = `idle`) never arrives for
|
|
23
|
+
* a subagent launched with an input message — it goes straight to `working` — so
|
|
24
|
+
* a `cli:agent:start:timeout` means "spawn accepted, pi booting".
|
|
25
|
+
*/
|
|
26
|
+
export const AGENT_START_TIMEOUT_MS = 5_000;
|
|
27
|
+
/**
|
|
28
|
+
* Max `herdr agent start` attempts. Only transient pre-start rejections (a fresh
|
|
29
|
+
* tab's shell not yet at its prompt) are retried; readiness timeouts mean the
|
|
30
|
+
* spawn was accepted and are never retried.
|
|
31
|
+
*/
|
|
32
|
+
export const AGENT_START_MAX_ATTEMPTS = 5;
|
|
33
|
+
/** Agent-start retry base delay (ms); grows linearly (base * attempt). */
|
|
34
|
+
export const AGENT_START_RETRY_BASE_DELAY_MS = 500;
|
|
35
|
+
/** Extra budget for the start CLI call itself beyond the start timeout (ms). */
|
|
36
|
+
const AGENT_START_CALL_SLACK_MS = 30_000;
|
|
37
|
+
/** Agent command budget (ms). */
|
|
38
|
+
const AGENT_COMMAND_TIMEOUT_MS = 15_000;
|
|
39
|
+
/** Agent registry namespace. */
|
|
40
|
+
export class HerdrAgents {
|
|
41
|
+
transport;
|
|
42
|
+
constructor(transport) {
|
|
43
|
+
this.transport = transport;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Start pi in the pane as a herdr agent. Returns when herdr accepted the spawn —
|
|
47
|
+
* NOT when pi is ready. Readiness timeouts return normally (the name is
|
|
48
|
+
* registered and pi is booting; retrying would start a second agent); transient
|
|
49
|
+
* pre-start rejections are retried with backoff; permanent errors propagate.
|
|
50
|
+
*/
|
|
51
|
+
async startPiAgent(options) {
|
|
52
|
+
let lastError;
|
|
53
|
+
const started = await pollUntil(async () => {
|
|
54
|
+
try {
|
|
55
|
+
await this.transport.call([
|
|
56
|
+
"agent",
|
|
57
|
+
"start",
|
|
58
|
+
options.name,
|
|
59
|
+
"--kind",
|
|
60
|
+
"pi",
|
|
61
|
+
"--pane",
|
|
62
|
+
options.paneId,
|
|
63
|
+
"--timeout",
|
|
64
|
+
String(AGENT_START_TIMEOUT_MS),
|
|
65
|
+
"--",
|
|
66
|
+
...options.piArgs,
|
|
67
|
+
], { timeoutMs: AGENT_START_TIMEOUT_MS + AGENT_START_CALL_SLACK_MS });
|
|
68
|
+
return settled(true);
|
|
69
|
+
}
|
|
70
|
+
catch (err) {
|
|
71
|
+
// Spawn accepted but readiness never observed — never retry (a retry
|
|
72
|
+
// would start a second agent).
|
|
73
|
+
if (isNonFatalStartError(err))
|
|
74
|
+
return settled(true);
|
|
75
|
+
lastError = withHerdrCode(err);
|
|
76
|
+
if (!isTransientAgentStartError(err)) {
|
|
77
|
+
// A refusal reports herdr's name bookkeeping, not whether a launch
|
|
78
|
+
// happened: the agent may be running under a name herdr dropped, or a
|
|
79
|
+
// name this same launch now holds.
|
|
80
|
+
if (await this.paneHostsAgent(options.paneId))
|
|
81
|
+
return settled(true);
|
|
82
|
+
throw lastError;
|
|
83
|
+
}
|
|
84
|
+
return keepPolling();
|
|
85
|
+
}
|
|
86
|
+
}, {
|
|
87
|
+
intervalMs: (attempt) => AGENT_START_RETRY_BASE_DELAY_MS * attempt,
|
|
88
|
+
maxAttempts: AGENT_START_MAX_ATTEMPTS,
|
|
89
|
+
});
|
|
90
|
+
if (started)
|
|
91
|
+
return;
|
|
92
|
+
// Every attempt was refused as a pre-start rejection, but a pane that hosts an
|
|
93
|
+
// agent now is a launch that happened.
|
|
94
|
+
if (await this.paneHostsAgent(options.paneId))
|
|
95
|
+
return;
|
|
96
|
+
const msg = lastError instanceof Error ? lastError.message : String(lastError);
|
|
97
|
+
throw new HerdrError(`herdr agent start failed after ${AGENT_START_MAX_ATTEMPTS} attempts (the target pane never became an available shell): ${msg}`, lastError instanceof HerdrError ? lastError.code : undefined);
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Whether the pane hosts an agent, whatever a start call reported. An agent
|
|
101
|
+
* runs in a pane this extension owns for one spawn, while the name a start call
|
|
102
|
+
* speaks in is bookkeeping herdr drops (`agent_name_not_found`) or finds taken by
|
|
103
|
+
* that same agent (`agent_name_taken`).
|
|
104
|
+
*/
|
|
105
|
+
async paneHostsAgent(paneId) {
|
|
106
|
+
try {
|
|
107
|
+
const info = await this.getAgentInfo(paneId, {
|
|
108
|
+
timeoutMs: AGENT_COMMAND_TIMEOUT_MS,
|
|
109
|
+
});
|
|
110
|
+
return info !== undefined && info.paneId === paneId;
|
|
111
|
+
}
|
|
112
|
+
catch (err) {
|
|
113
|
+
// An unanswerable probe is not evidence that a launch happened.
|
|
114
|
+
log.debug("agent start probe failed", {
|
|
115
|
+
paneId,
|
|
116
|
+
code: herdrErrorCode(err),
|
|
117
|
+
});
|
|
118
|
+
return false;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Every live agent record, nameless ones included. Herdr 0.8.x drops the custom
|
|
123
|
+
* `agent start` name, so orphaned runs carry only address/state fields — the
|
|
124
|
+
* read recovery and cleanup associate with a run.
|
|
125
|
+
*/
|
|
126
|
+
async listAgentRecords() {
|
|
127
|
+
const result = await this.transport.call(["agent", "list"]);
|
|
128
|
+
// Herdr has shipped both envelope shapes; either is a complete answer.
|
|
129
|
+
const listed = Array.isArray(result)
|
|
130
|
+
? result
|
|
131
|
+
: objectField(result, "agents");
|
|
132
|
+
if (!Array.isArray(listed)) {
|
|
133
|
+
throw new HerdrError(`herdr agent list returned no agents array: ${JSON.stringify(result).slice(0, 300)}`, undefined);
|
|
134
|
+
}
|
|
135
|
+
const out = [];
|
|
136
|
+
for (const entry of listed) {
|
|
137
|
+
const info = parseAgentInfo(entry);
|
|
138
|
+
if (info)
|
|
139
|
+
out.push(info);
|
|
140
|
+
}
|
|
141
|
+
return out;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* Snapshot for one herdr agent target, or undefined when gone. Herdr 0.8.x does
|
|
145
|
+
* not retain the custom `agent start` name, so callers must pass the pane id.
|
|
146
|
+
*/
|
|
147
|
+
async getAgentInfo(target, opts) {
|
|
148
|
+
try {
|
|
149
|
+
const result = await this.transport.call(["agent", "get", target], opts);
|
|
150
|
+
const info = parseAgentInfo(objectField(result, "agent") ?? result);
|
|
151
|
+
if (!info) {
|
|
152
|
+
log.debug("herdr record rejected", {
|
|
153
|
+
target,
|
|
154
|
+
result,
|
|
155
|
+
});
|
|
156
|
+
return undefined;
|
|
157
|
+
}
|
|
158
|
+
return { ...info, name: info.name ?? target };
|
|
159
|
+
}
|
|
160
|
+
catch (err) {
|
|
161
|
+
// A missing target is normal during watcher shutdown; other failures stay
|
|
162
|
+
// errors so callers can distinguish unknown from gone.
|
|
163
|
+
if (isAgentGoneError(err)) {
|
|
164
|
+
log.debug("agent not found", {
|
|
165
|
+
target,
|
|
166
|
+
code: err.code,
|
|
167
|
+
});
|
|
168
|
+
return undefined;
|
|
169
|
+
}
|
|
170
|
+
throw err;
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Live herdr agents for a task slug — the idempotent-spawn probe. A hit means an
|
|
175
|
+
* attempt already exists. Herdr 0.8.x drops the custom `agent start` name, so a
|
|
176
|
+
* record without one is matched by its worktree directory: extension worktrees
|
|
177
|
+
* are `cow-<taskSlug>-<id>`, and the cwd outlives the name. A failed probe
|
|
178
|
+
* returns [] so the spawn still proceeds.
|
|
179
|
+
*/
|
|
180
|
+
async findTaskAttempts(taskSlug) {
|
|
181
|
+
let records;
|
|
182
|
+
try {
|
|
183
|
+
records = await this.listAgentRecords();
|
|
184
|
+
}
|
|
185
|
+
catch {
|
|
186
|
+
return [];
|
|
187
|
+
}
|
|
188
|
+
const attempts = [];
|
|
189
|
+
for (const info of records) {
|
|
190
|
+
if (info.name !== undefined && isTaskAgentName(info.name, taskSlug)) {
|
|
191
|
+
// Only the conflicting identity; state is deliberately unclassified (a live
|
|
192
|
+
// entry owns the task either way, and nothing downstream may end it).
|
|
193
|
+
attempts.push({ name: info.name });
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
// Nameless (or cosmetically renamed) record: the worktree directory
|
|
197
|
+
// carries the same `cow-<slug>-<id>` identity and becomes the name.
|
|
198
|
+
if (info.cwd === undefined)
|
|
199
|
+
continue;
|
|
200
|
+
const base = path.basename(info.cwd);
|
|
201
|
+
if (isTaskAgentName(base, taskSlug))
|
|
202
|
+
attempts.push({ name: base });
|
|
203
|
+
}
|
|
204
|
+
return attempts;
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* Send logical key presses to an agent. Herdr validates every key name before
|
|
208
|
+
* writing any bytes, so an unsupported key fails without partial input. Throws
|
|
209
|
+
* HerdrError.
|
|
210
|
+
*/
|
|
211
|
+
async sendKeys(target, keys) {
|
|
212
|
+
await this.transport.call(["agent", "send-keys", target, ...keys], {
|
|
213
|
+
timeoutMs: AGENT_COMMAND_TIMEOUT_MS,
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* Submit a prompt to an agent. herdr checks the target first — a pane hosting
|
|
218
|
+
* no agent is `agent_not_found`, an approval dialog is `agent_blocked` — and
|
|
219
|
+
* then writes the text and the encoded Enter as one ordered submission that
|
|
220
|
+
* honours the pane's bracketed-paste mode.
|
|
221
|
+
*
|
|
222
|
+
* No `--wait`: a steer to an agent that is already working is this call's whole
|
|
223
|
+
* reason, and the stall rule belongs to the waiting form. Throws HerdrError.
|
|
224
|
+
*/
|
|
225
|
+
async submitPrompt(target, text) {
|
|
226
|
+
await this.transport.call(["agent", "prompt", target, text], {
|
|
227
|
+
timeoutMs: AGENT_COMMAND_TIMEOUT_MS,
|
|
228
|
+
});
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* Send a ctrl+c interrupt to a herdr agent. Non-fatal by intent: the agent
|
|
232
|
+
* being gone already is the wanted outcome, while any other failure is logged
|
|
233
|
+
* because the stopper then waits out its confirmation window on an agent it
|
|
234
|
+
* never reached.
|
|
235
|
+
*/
|
|
236
|
+
async interruptAgent(name) {
|
|
237
|
+
try {
|
|
238
|
+
await this.transport.call(["agent", "send-keys", name, "ctrl+c"], {
|
|
239
|
+
timeoutMs: AGENT_COMMAND_TIMEOUT_MS,
|
|
240
|
+
});
|
|
241
|
+
}
|
|
242
|
+
catch (err) {
|
|
243
|
+
if (isAgentGoneError(err)) {
|
|
244
|
+
log.debug("interrupt skipped: agent already gone", { name });
|
|
245
|
+
return;
|
|
246
|
+
}
|
|
247
|
+
log.warn("agent interrupt failed", {
|
|
248
|
+
name,
|
|
249
|
+
code: herdrErrorCode(err),
|
|
250
|
+
detail: errorMessage(err),
|
|
251
|
+
});
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* Whether a start failure is a non-fatal readiness timeout (spawn accepted, pi
|
|
257
|
+
* booting; expected for subagents launched with an input message). Matches
|
|
258
|
+
* `cli:agent:start:timeout` / `agent_not_ready` and the human timeout message.
|
|
259
|
+
*/
|
|
260
|
+
function isNonFatalStartError(err) {
|
|
261
|
+
if (!(err instanceof HerdrError))
|
|
262
|
+
return false;
|
|
263
|
+
if (err.code === "cli:agent:start:timeout" ||
|
|
264
|
+
err.code === "agent_not_ready") {
|
|
265
|
+
return true;
|
|
266
|
+
}
|
|
267
|
+
return /timed out waiting for agent startup/i.test(err.message);
|
|
268
|
+
}
|
|
269
|
+
/** Whether a start failure is a transient not-ready shell worth retrying. */
|
|
270
|
+
function isTransientAgentStartError(err) {
|
|
271
|
+
if (!(err instanceof HerdrError))
|
|
272
|
+
return false;
|
|
273
|
+
if (err.code === "agent_pane_unavailable" || err.code === "agent_pane_busy") {
|
|
274
|
+
return true;
|
|
275
|
+
}
|
|
276
|
+
return /is not an available shell/i.test(err.message);
|
|
277
|
+
}
|
|
278
|
+
/**
|
|
279
|
+
* The failure with herdr's code folded into its message. The message alone does
|
|
280
|
+
* not name the failure — several codes share wording, so "no longer owns the
|
|
281
|
+
* target terminal" and "is not an available shell" are indistinguishable by text
|
|
282
|
+
* — and this message is the text a failed run reports to the orchestrator.
|
|
283
|
+
*/
|
|
284
|
+
function withHerdrCode(err) {
|
|
285
|
+
if (!(err instanceof HerdrError) || err.code === undefined)
|
|
286
|
+
return err;
|
|
287
|
+
return new HerdrError(`${err.message} (herdr code: ${err.code})`, err.code);
|
|
288
|
+
}
|
|
289
|
+
/** One herdr agent JSON record in the extension's shape. */
|
|
290
|
+
function parseAgentInfo(entry) {
|
|
291
|
+
if (!entry || typeof entry !== "object")
|
|
292
|
+
return undefined;
|
|
293
|
+
const record = entry;
|
|
294
|
+
const paneId = strField(record, "pane_id");
|
|
295
|
+
if (!paneId)
|
|
296
|
+
return undefined;
|
|
297
|
+
const state = strField(record, "agent_status");
|
|
298
|
+
return {
|
|
299
|
+
name: strField(record, "name") ?? strField(record, "agent_name"),
|
|
300
|
+
state: state ?? "unknown",
|
|
301
|
+
workspaceId: strField(record, "workspace_id"),
|
|
302
|
+
tabId: strField(record, "tab_id"),
|
|
303
|
+
cwd: strField(record, "cwd"),
|
|
304
|
+
paneId,
|
|
305
|
+
interactiveReady: record.interactive_ready === true,
|
|
306
|
+
};
|
|
307
|
+
}
|
|
308
|
+
/** Agent namespace for one pi instance. */
|
|
309
|
+
function agentNamespace(pi) {
|
|
310
|
+
return new HerdrAgents(new HerdrTransport(pi));
|
|
311
|
+
}
|
|
312
|
+
export async function startPiAgent(pi, options) {
|
|
313
|
+
return agentNamespace(pi).startPiAgent(options);
|
|
314
|
+
}
|
|
315
|
+
export async function listAgentRecords(pi) {
|
|
316
|
+
return agentNamespace(pi).listAgentRecords();
|
|
317
|
+
}
|
|
318
|
+
export async function getAgentInfo(pi, target) {
|
|
319
|
+
return agentNamespace(pi).getAgentInfo(target);
|
|
320
|
+
}
|
|
321
|
+
export async function findTaskAttempts(pi, taskSlug) {
|
|
322
|
+
return agentNamespace(pi).findTaskAttempts(taskSlug);
|
|
323
|
+
}
|
|
324
|
+
export async function sendAgentKeys(pi, target, keys) {
|
|
325
|
+
return agentNamespace(pi).sendKeys(target, keys);
|
|
326
|
+
}
|
|
327
|
+
export async function submitAgentPrompt(pi, target, text) {
|
|
328
|
+
return agentNamespace(pi).submitPrompt(target, text);
|
|
329
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* herdr-client.ts — Layer 2 facade: one pi-bound herdr client.
|
|
3
|
+
*
|
|
4
|
+
* Transport plus the `.panes`/`.agents`/`.worktrees` namespaces, and the one
|
|
5
|
+
* workspace-scoped query that fits no namespace. One client shares a single
|
|
6
|
+
* transport across its namespaces; the pi-bound function below builds a client
|
|
7
|
+
* per call, for callers that hold only the pi instance.
|
|
8
|
+
*/
|
|
9
|
+
import { HerdrAgents } from "./agents.js";
|
|
10
|
+
import { HerdrError, HerdrTransport, objectField, strField, } from "./herdr-transport.js";
|
|
11
|
+
import { HerdrPanes } from "./panes.js";
|
|
12
|
+
import { HerdrWorktrees } from "./worktrees.js";
|
|
13
|
+
/** One pi-bound herdr client: transport plus the pane/agent/worktree namespaces. */
|
|
14
|
+
export class HerdrClient {
|
|
15
|
+
panes;
|
|
16
|
+
agents;
|
|
17
|
+
worktrees;
|
|
18
|
+
transport;
|
|
19
|
+
constructor(pi) {
|
|
20
|
+
this.transport = new HerdrTransport(pi);
|
|
21
|
+
this.panes = new HerdrPanes(this.transport);
|
|
22
|
+
this.agents = new HerdrAgents(this.transport);
|
|
23
|
+
this.worktrees = new HerdrWorktrees(this.transport);
|
|
24
|
+
}
|
|
25
|
+
/** The calling pane's workspace. `--current` targets the caller, never the user's focus. */
|
|
26
|
+
async getCurrentWorkspaceId() {
|
|
27
|
+
const result = await this.transport.call(["pane", "current", "--current"]);
|
|
28
|
+
const ws = strField(objectField(result, "pane"), "workspace_id");
|
|
29
|
+
if (ws === undefined)
|
|
30
|
+
throw new HerdrError("could not determine the current herdr workspace (not inside herdr?)", undefined);
|
|
31
|
+
return ws;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
export async function getCurrentWorkspaceId(pi) {
|
|
35
|
+
return new HerdrClient(pi).getCurrentWorkspaceId();
|
|
36
|
+
}
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* herdr-transport.ts — Layer 1: the raw `herdr` CLI transport.
|
|
3
|
+
*
|
|
4
|
+
* The only module that runs `herdr` and the only one that knows the 0.8.x wire
|
|
5
|
+
* format: a `{ result }` JSON envelope on stdout, a JSON `{ error }` object on
|
|
6
|
+
* stderr at exit 1. Runs through pi.exec so the child inherits the pane's HERDR_*
|
|
7
|
+
* environment. `runHerdr` is the pi-bound entry for callers that hold only the
|
|
8
|
+
* pi instance; it runs one call over a transport it builds itself.
|
|
9
|
+
*/
|
|
10
|
+
/** Per-call timeout for herdr control commands (ms). */
|
|
11
|
+
const DEFAULT_TIMEOUT_MS = 60_000;
|
|
12
|
+
/** herdr error text is truncated to this length. */
|
|
13
|
+
const ERROR_TEXT_LIMIT = 500;
|
|
14
|
+
/** Non-zero herdr exit; carries herdr's code and message. */
|
|
15
|
+
export class HerdrError extends Error {
|
|
16
|
+
code;
|
|
17
|
+
constructor(message, code) {
|
|
18
|
+
super(message);
|
|
19
|
+
this.code = code;
|
|
20
|
+
this.name = "HerdrError";
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Herdr's "the addressed resource does not exist" codes. They are the expected
|
|
25
|
+
* answer to a best-effort teardown or naming (the pane, tab, or agent is already
|
|
26
|
+
* gone) and are the only failures those may treat as success.
|
|
27
|
+
*/
|
|
28
|
+
const PANE_GONE_CODES = ["pane_not_found"];
|
|
29
|
+
const TAB_GONE_CODES = ["tab_not_found"];
|
|
30
|
+
const AGENT_GONE_CODES = [
|
|
31
|
+
"agent_not_found",
|
|
32
|
+
"agent_name_not_found",
|
|
33
|
+
];
|
|
34
|
+
/** True when herdr reported that the pane does not exist. */
|
|
35
|
+
export function isPaneGoneError(err) {
|
|
36
|
+
return (err instanceof HerdrError &&
|
|
37
|
+
err.code !== undefined &&
|
|
38
|
+
PANE_GONE_CODES.includes(err.code));
|
|
39
|
+
}
|
|
40
|
+
/** True when herdr reported that the tab does not exist. */
|
|
41
|
+
export function isTabGoneError(err) {
|
|
42
|
+
return (err instanceof HerdrError &&
|
|
43
|
+
err.code !== undefined &&
|
|
44
|
+
TAB_GONE_CODES.includes(err.code));
|
|
45
|
+
}
|
|
46
|
+
/** True when herdr reported that the agent target does not exist. */
|
|
47
|
+
export function isAgentGoneError(err) {
|
|
48
|
+
return (err instanceof HerdrError &&
|
|
49
|
+
err.code !== undefined &&
|
|
50
|
+
AGENT_GONE_CODES.includes(err.code));
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The herdr code of a failure, or undefined when there is none: a killed or
|
|
54
|
+
* timed-out CLI call and an unparseable envelope carry no code, so an absent
|
|
55
|
+
* code marks a failure outside herdr's own error contract.
|
|
56
|
+
*/
|
|
57
|
+
export function herdrErrorCode(err) {
|
|
58
|
+
return err instanceof HerdrError ? err.code : undefined;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Runs `herdr` for one pi instance and decodes its envelopes. Every namespace
|
|
62
|
+
* and state machine in this folder composes over one transport.
|
|
63
|
+
*/
|
|
64
|
+
export class HerdrTransport {
|
|
65
|
+
pi;
|
|
66
|
+
constructor(pi) {
|
|
67
|
+
this.pi = pi;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Parsed `result` of a herdr command's envelope. A command that exits 0
|
|
71
|
+
* without printing the envelope is a contract violation, not a text result,
|
|
72
|
+
* so it throws instead of handing the caller the raw stdout as its value.
|
|
73
|
+
*/
|
|
74
|
+
async call(args, opts) {
|
|
75
|
+
const stdout = await this.exec(args, opts);
|
|
76
|
+
if (!stdout)
|
|
77
|
+
return undefined;
|
|
78
|
+
let parsed;
|
|
79
|
+
try {
|
|
80
|
+
parsed = JSON.parse(stdout);
|
|
81
|
+
}
|
|
82
|
+
catch {
|
|
83
|
+
throw new HerdrError(`herdr ${args.join(" ")} printed no JSON result envelope: ${stdout.slice(0, ERROR_TEXT_LIMIT)}`, undefined);
|
|
84
|
+
}
|
|
85
|
+
return parsed.result;
|
|
86
|
+
}
|
|
87
|
+
/** Run the CLI; a non-zero exit becomes a HerdrError. */
|
|
88
|
+
async exec(args, opts) {
|
|
89
|
+
const exec = await this.pi.exec("herdr", args, {
|
|
90
|
+
timeout: opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
|
|
91
|
+
});
|
|
92
|
+
const stdout = exec.stdout.trim();
|
|
93
|
+
const stderr = exec.stderr.trim();
|
|
94
|
+
if (exec.code !== 0) {
|
|
95
|
+
const envelope = parseFailure(stderr);
|
|
96
|
+
const message = envelope === undefined
|
|
97
|
+
? printedFailure(printedText(stderr, stdout), args.join(" "), exec.code)
|
|
98
|
+
: (envelope.message ??
|
|
99
|
+
`herdr reported ${envelope.code ?? "an error"}`);
|
|
100
|
+
throw new HerdrError(message.slice(0, ERROR_TEXT_LIMIT), envelope?.code);
|
|
101
|
+
}
|
|
102
|
+
return stdout;
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
/** Herdr's failure envelope, or undefined when stderr is not one — empty and unparseable included. */
|
|
106
|
+
function parseFailure(stderr) {
|
|
107
|
+
let parsed;
|
|
108
|
+
try {
|
|
109
|
+
parsed = JSON.parse(stderr);
|
|
110
|
+
}
|
|
111
|
+
catch {
|
|
112
|
+
return undefined;
|
|
113
|
+
}
|
|
114
|
+
const error = objectField(parsed, "error");
|
|
115
|
+
return error === undefined
|
|
116
|
+
? undefined
|
|
117
|
+
: { code: strField(error, "code"), message: strField(error, "message") };
|
|
118
|
+
}
|
|
119
|
+
/** What herdr printed at all: stderr when it carried something, else stdout; undefined when silent. */
|
|
120
|
+
function printedText(stderr, stdout) {
|
|
121
|
+
if (stderr !== "")
|
|
122
|
+
return stderr;
|
|
123
|
+
return stdout === "" ? undefined : stdout;
|
|
124
|
+
}
|
|
125
|
+
/** The message for a failure that sent no envelope: herdr's own text, or a statement of silence. */
|
|
126
|
+
function printedFailure(printed, invocation, exitCode) {
|
|
127
|
+
return printed === undefined
|
|
128
|
+
? `herdr ${invocation} exited ${exitCode} without printing anything`
|
|
129
|
+
: `herdr ${invocation} exited ${exitCode}: ${printed}`;
|
|
130
|
+
}
|
|
131
|
+
/** The object value at `key` of an unknown value, or undefined when it is not one. */
|
|
132
|
+
export function objectField(obj, key) {
|
|
133
|
+
if (!obj || typeof obj !== "object")
|
|
134
|
+
return undefined;
|
|
135
|
+
const value = obj[key];
|
|
136
|
+
return value && typeof value === "object"
|
|
137
|
+
? value
|
|
138
|
+
: undefined;
|
|
139
|
+
}
|
|
140
|
+
/** A non-empty string field of an unknown value, by key. */
|
|
141
|
+
export function strField(obj, key) {
|
|
142
|
+
if (!obj || typeof obj !== "object")
|
|
143
|
+
return undefined;
|
|
144
|
+
const value = obj[key];
|
|
145
|
+
return typeof value === "string" && value.length > 0 ? value : undefined;
|
|
146
|
+
}
|
|
147
|
+
/** A boolean field of an unknown value, by key; undefined when absent or not a boolean. */
|
|
148
|
+
export function boolField(obj, key) {
|
|
149
|
+
if (!obj || typeof obj !== "object")
|
|
150
|
+
return undefined;
|
|
151
|
+
const value = obj[key];
|
|
152
|
+
return typeof value === "boolean" ? value : undefined;
|
|
153
|
+
}
|
|
154
|
+
export async function runHerdr(pi, args, opts) {
|
|
155
|
+
const transport = new HerdrTransport(pi);
|
|
156
|
+
const callOpts = opts?.timeoutMs === undefined ? undefined : { timeoutMs: opts.timeoutMs };
|
|
157
|
+
return transport.call(args, callOpts);
|
|
158
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* index.ts — barrel for the herdr plane (see ../herdr-client.ts, the path the
|
|
3
|
+
* herdr test fixtures mock).
|
|
4
|
+
*
|
|
5
|
+
* Layer 1 herdr-transport.ts, polling.ts
|
|
6
|
+
* Layer 2 panes.ts, agents.ts, worktrees.ts, herdr-client.ts (facade)
|
|
7
|
+
* Layer 3 agent-stopper.ts (stop-and-confirm state machine)
|
|
8
|
+
*/
|
|
9
|
+
export * from "./herdr-transport.js";
|
|
10
|
+
export * from "./polling.js";
|
|
11
|
+
export * from "./panes.js";
|
|
12
|
+
export * from "./agents.js";
|
|
13
|
+
export * from "./worktrees.js";
|
|
14
|
+
export * from "./herdr-client.js";
|
|
15
|
+
export * from "./agent-stopper.js";
|