@howaboua/pi-shepherdr 0.1.2 → 0.1.4
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/CHANGELOG.md +52 -0
- package/README.md +55 -50
- package/biome.json +1 -1
- package/changelog.ts +337 -0
- package/index.ts +95 -5
- package/package.json +24 -12
- package/profiles/explorer/profile.json +8 -0
- package/profiles/explorer/prompt.md +1 -0
- package/profiles/general/profile.json +8 -0
- package/profiles/general/prompt.md +1 -0
- package/profiles/reviewer/prepare.mjs +170 -0
- package/profiles/reviewer/profile.json +9 -0
- package/profiles/reviewer/prompt.md +1 -0
- package/src/activity.ts +20 -1
- package/src/agents-contract.ts +142 -0
- package/src/agents-operations.ts +338 -0
- package/src/agents-tool.ts +440 -0
- package/src/ask-answer.ts +297 -0
- package/src/controller.ts +180 -0
- package/src/delivery.ts +68 -0
- package/src/herdr.ts +13 -1
- package/src/launch.ts +62 -8
- package/src/machine-menu.ts +158 -0
- package/src/messages.ts +108 -5
- package/src/monitor-record.ts +34 -1
- package/src/monitor-state.ts +40 -4
- package/src/monitor.ts +63 -6
- package/src/profiles.ts +291 -0
- package/src/remote/shepherdr.mjs +148 -28
- package/src/remote-client.ts +11 -5
- package/src/session-reader.ts +178 -50
- package/src/settlement.ts +228 -33
- package/src/types.ts +31 -1
- package/src/master-config.ts +0 -61
- package/src/master-mode.ts +0 -295
- package/src/tool.ts +0 -234
|
@@ -0,0 +1,440 @@
|
|
|
1
|
+
import { defineTool, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
|
|
3
|
+
import {
|
|
4
|
+
AgentsParameters,
|
|
5
|
+
type AgentsParams,
|
|
6
|
+
type AgentsToolParams,
|
|
7
|
+
parseAgentsRequest,
|
|
8
|
+
} from "./agents-contract.js";
|
|
9
|
+
import {
|
|
10
|
+
agentsHelp,
|
|
11
|
+
allocateAgentName,
|
|
12
|
+
dispatchAgentWork,
|
|
13
|
+
findFleetAgents,
|
|
14
|
+
listFleetAgents,
|
|
15
|
+
readAgentTerminal,
|
|
16
|
+
reportProgress,
|
|
17
|
+
settlementResult,
|
|
18
|
+
toolResult,
|
|
19
|
+
} from "./agents-operations.js";
|
|
20
|
+
import { type AskAnswer, prepareAskAnswer } from "./ask-answer.js";
|
|
21
|
+
import type { AgentFleet } from "./fleet.js";
|
|
22
|
+
import { resolvePiAgent } from "./herdr.js";
|
|
23
|
+
import { isHerdrResponseError } from "./herdr-client.js";
|
|
24
|
+
import {
|
|
25
|
+
resolvePreparationDirectory,
|
|
26
|
+
rollbackStartedAgent,
|
|
27
|
+
startAgent,
|
|
28
|
+
} from "./launch.js";
|
|
29
|
+
import {
|
|
30
|
+
loadAgentProfiles,
|
|
31
|
+
prepareProfileMessage,
|
|
32
|
+
profileAgentArgs,
|
|
33
|
+
} from "./profiles.js";
|
|
34
|
+
|
|
35
|
+
function required(value: string | undefined, field: string): string {
|
|
36
|
+
if (!value?.trim()) throw new Error(`${field} is required for this action`);
|
|
37
|
+
return value.trim();
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function agentLabel(value: string | undefined): string {
|
|
41
|
+
const label = required(value, "label");
|
|
42
|
+
const words = label.split(/\s+/u);
|
|
43
|
+
if (words.length < 2 || words.length > 3) {
|
|
44
|
+
throw new Error("label must contain 2 or 3 words");
|
|
45
|
+
}
|
|
46
|
+
return label;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function createAgentsTool(fleet: AgentFleet) {
|
|
50
|
+
return defineTool({
|
|
51
|
+
name: "agents",
|
|
52
|
+
label: "Shepherdr",
|
|
53
|
+
description: "Persistent Pi agents across configured Herdr machines.",
|
|
54
|
+
parameters: AgentsParameters,
|
|
55
|
+
promptSnippet: "Load agents help before first use.",
|
|
56
|
+
promptGuidelines: [
|
|
57
|
+
"agents: Blocking is default; set blocking false only while continuing other work. Asynchronous settlement is pushed automatically, so never poll.",
|
|
58
|
+
"agents: Specialists know their job. Give only the concrete task and inaccessible context; never append generic method, evidence, or reporting instructions.",
|
|
59
|
+
"agents: Reuse specialists only for the same investigation. Keep reviews independent. New scope gets a new agent.",
|
|
60
|
+
"agents: For advanced Herdr workspace, pane, process or layout control, run herdr --skill.",
|
|
61
|
+
],
|
|
62
|
+
executionMode: "sequential",
|
|
63
|
+
async execute(
|
|
64
|
+
_toolCallId,
|
|
65
|
+
input: AgentsToolParams,
|
|
66
|
+
signal,
|
|
67
|
+
onUpdate,
|
|
68
|
+
_ctx,
|
|
69
|
+
) {
|
|
70
|
+
const params = parseAgentsRequest(input);
|
|
71
|
+
const executionSignal = signal ?? new AbortController().signal;
|
|
72
|
+
const update = onUpdate ?? (() => undefined);
|
|
73
|
+
if (params.action === "help") {
|
|
74
|
+
return toolResult(await agentsHelp());
|
|
75
|
+
}
|
|
76
|
+
if (params.action === "list") {
|
|
77
|
+
return toolResult(await listFleetAgents(fleet, params));
|
|
78
|
+
}
|
|
79
|
+
if (params.action === "find") {
|
|
80
|
+
return toolResult(await findFleetAgents(fleet, params));
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const runtime = fleet.connected(params.machine);
|
|
84
|
+
if (params.action === "spawn") {
|
|
85
|
+
const profiles = await loadAgentProfiles();
|
|
86
|
+
const profileName = required(params.agent_type, "agent_type");
|
|
87
|
+
const profile = profiles.get(profileName);
|
|
88
|
+
if (!profile) {
|
|
89
|
+
throw new Error(
|
|
90
|
+
`unknown agent_type ${JSON.stringify(profileName)}; available: ${[...profiles.keys()].join(", ")}`,
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
const label = agentLabel(params.label);
|
|
94
|
+
const name =
|
|
95
|
+
params.name?.trim() || (await allocateAgentName(runtime, label));
|
|
96
|
+
const placement =
|
|
97
|
+
params.placement ??
|
|
98
|
+
(runtime.local && process.env["HERDR_WORKSPACE_ID"]
|
|
99
|
+
? "new_tab"
|
|
100
|
+
: "new_workspace");
|
|
101
|
+
const workspace =
|
|
102
|
+
params.workspace ??
|
|
103
|
+
(placement === "new_tab" && runtime.local
|
|
104
|
+
? process.env["HERDR_WORKSPACE_ID"]
|
|
105
|
+
: undefined);
|
|
106
|
+
const startParams = {
|
|
107
|
+
name,
|
|
108
|
+
label,
|
|
109
|
+
placement,
|
|
110
|
+
...(workspace ? { workspace } : {}),
|
|
111
|
+
...(params.pane ? { pane: params.pane } : {}),
|
|
112
|
+
...(params.cwd ? { cwd: params.cwd } : {}),
|
|
113
|
+
};
|
|
114
|
+
const cwd = await resolvePreparationDirectory(
|
|
115
|
+
runtime.client,
|
|
116
|
+
startParams,
|
|
117
|
+
runtime.fallbackCwd,
|
|
118
|
+
runtime.resolveDirectory,
|
|
119
|
+
);
|
|
120
|
+
const message = await prepareProfileMessage(
|
|
121
|
+
profile,
|
|
122
|
+
{
|
|
123
|
+
cwd,
|
|
124
|
+
message: required(params.message, "message"),
|
|
125
|
+
...(params.base ? { base: params.base } : {}),
|
|
126
|
+
},
|
|
127
|
+
{ targetLocal: runtime.local },
|
|
128
|
+
);
|
|
129
|
+
reportProgress(update, `Spawning ${label}`, {
|
|
130
|
+
machine: runtime.machine,
|
|
131
|
+
name,
|
|
132
|
+
profile: profile.name,
|
|
133
|
+
status: "starting",
|
|
134
|
+
});
|
|
135
|
+
const started = await startAgent(
|
|
136
|
+
runtime.client,
|
|
137
|
+
runtime.monitor,
|
|
138
|
+
startParams,
|
|
139
|
+
runtime.fallbackCwd,
|
|
140
|
+
runtime.resolveDirectory,
|
|
141
|
+
{
|
|
142
|
+
agentArgs: profileAgentArgs(profile, {
|
|
143
|
+
targetLocal: runtime.local,
|
|
144
|
+
}),
|
|
145
|
+
},
|
|
146
|
+
);
|
|
147
|
+
let promptSubmissionStarted = false;
|
|
148
|
+
let promptAccepted = false;
|
|
149
|
+
let settlement;
|
|
150
|
+
try {
|
|
151
|
+
settlement = await dispatchAgentWork(
|
|
152
|
+
runtime,
|
|
153
|
+
started.agent,
|
|
154
|
+
message,
|
|
155
|
+
params.blocking !== false,
|
|
156
|
+
executionSignal,
|
|
157
|
+
update,
|
|
158
|
+
async () => {
|
|
159
|
+
promptSubmissionStarted = true;
|
|
160
|
+
await runtime.client.request("agent.prompt", {
|
|
161
|
+
target: started.id,
|
|
162
|
+
text: message,
|
|
163
|
+
});
|
|
164
|
+
promptAccepted = true;
|
|
165
|
+
},
|
|
166
|
+
{ expectUserMessage: true },
|
|
167
|
+
);
|
|
168
|
+
} catch (error) {
|
|
169
|
+
if (
|
|
170
|
+
!promptAccepted &&
|
|
171
|
+
(!promptSubmissionStarted || isHerdrResponseError(error))
|
|
172
|
+
) {
|
|
173
|
+
return rollbackStartedAgent(
|
|
174
|
+
runtime.client,
|
|
175
|
+
runtime.monitor,
|
|
176
|
+
started,
|
|
177
|
+
error,
|
|
178
|
+
);
|
|
179
|
+
}
|
|
180
|
+
throw error;
|
|
181
|
+
}
|
|
182
|
+
return toolResult(
|
|
183
|
+
settlement
|
|
184
|
+
? {
|
|
185
|
+
spawned: true,
|
|
186
|
+
...settlementResult(runtime.machine, settlement),
|
|
187
|
+
}
|
|
188
|
+
: {
|
|
189
|
+
spawned: true,
|
|
190
|
+
machine: runtime.machine,
|
|
191
|
+
target: started.id,
|
|
192
|
+
name,
|
|
193
|
+
status: "working",
|
|
194
|
+
next: "Completion or blockage will be delivered automatically; do not poll",
|
|
195
|
+
},
|
|
196
|
+
);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
const target = required(params.target, "target");
|
|
200
|
+
if (params.action === "unwatch") {
|
|
201
|
+
const record = runtime.monitor
|
|
202
|
+
.list()
|
|
203
|
+
.find((agent) => agent.paneId === target || agent.name === target);
|
|
204
|
+
if (!record) {
|
|
205
|
+
return toolResult({
|
|
206
|
+
unwatched: false,
|
|
207
|
+
machine: runtime.machine,
|
|
208
|
+
target,
|
|
209
|
+
});
|
|
210
|
+
}
|
|
211
|
+
await runtime.monitor.unwatch(record.paneId);
|
|
212
|
+
return toolResult({
|
|
213
|
+
unwatched: true,
|
|
214
|
+
machine: runtime.machine,
|
|
215
|
+
target: record.paneId,
|
|
216
|
+
});
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
const panel = await resolvePiAgent(
|
|
220
|
+
runtime.client,
|
|
221
|
+
target,
|
|
222
|
+
runtime.local ? process.env["HERDR_PANE_ID"] : "",
|
|
223
|
+
);
|
|
224
|
+
if (params.action === "watch") {
|
|
225
|
+
await runtime.monitor.watch(panel);
|
|
226
|
+
return toolResult({
|
|
227
|
+
watched: true,
|
|
228
|
+
machine: runtime.machine,
|
|
229
|
+
target: panel.pane_id,
|
|
230
|
+
next: "Completion or blockage will be delivered automatically; do not poll",
|
|
231
|
+
});
|
|
232
|
+
}
|
|
233
|
+
if (params.action === "read") {
|
|
234
|
+
const source = params.source ?? "latest";
|
|
235
|
+
if (source !== "latest") {
|
|
236
|
+
return toolResult(
|
|
237
|
+
await readAgentTerminal(runtime, panel, source, params.lines ?? 40),
|
|
238
|
+
);
|
|
239
|
+
}
|
|
240
|
+
const view = await runtime.monitor.view(panel);
|
|
241
|
+
return toolResult({
|
|
242
|
+
machine: runtime.machine,
|
|
243
|
+
target: panel.pane_id,
|
|
244
|
+
status: panel.agent_status,
|
|
245
|
+
...(view.assistant
|
|
246
|
+
? { reply: view.assistant.text }
|
|
247
|
+
: { reply: null }),
|
|
248
|
+
...(panel.agent_status === "blocked" && view.ask
|
|
249
|
+
? {
|
|
250
|
+
ask: {
|
|
251
|
+
handoff: view.ask.handoff,
|
|
252
|
+
prompts: view.ask.prompts,
|
|
253
|
+
},
|
|
254
|
+
}
|
|
255
|
+
: {}),
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
if (params.action === "send") {
|
|
259
|
+
if (panel.agent_status === "blocked") {
|
|
260
|
+
const view = await runtime.monitor.view(panel);
|
|
261
|
+
throw new Error(
|
|
262
|
+
`${panel.pane_id} is blocked${view.ask ? " on ask; use action=answer" : ""}`,
|
|
263
|
+
);
|
|
264
|
+
}
|
|
265
|
+
const message = required(params.message, "message");
|
|
266
|
+
if (!runtime.monitor.isMonitored(panel.pane_id)) {
|
|
267
|
+
await runtime.monitor.track(panel);
|
|
268
|
+
}
|
|
269
|
+
const settlement = await dispatchAgentWork(
|
|
270
|
+
runtime,
|
|
271
|
+
panel,
|
|
272
|
+
message,
|
|
273
|
+
params.blocking !== false,
|
|
274
|
+
executionSignal,
|
|
275
|
+
update,
|
|
276
|
+
() =>
|
|
277
|
+
runtime.client.request("agent.prompt", {
|
|
278
|
+
target: panel.pane_id,
|
|
279
|
+
text: message,
|
|
280
|
+
}),
|
|
281
|
+
{ expectUserMessage: true },
|
|
282
|
+
);
|
|
283
|
+
return toolResult(
|
|
284
|
+
settlement
|
|
285
|
+
? { sent: true, ...settlementResult(runtime.machine, settlement) }
|
|
286
|
+
: {
|
|
287
|
+
sent: true,
|
|
288
|
+
machine: runtime.machine,
|
|
289
|
+
target: panel.pane_id,
|
|
290
|
+
status: "working",
|
|
291
|
+
next: "Completion or blockage will be delivered automatically; do not poll",
|
|
292
|
+
},
|
|
293
|
+
);
|
|
294
|
+
}
|
|
295
|
+
if (params.action === "answer") {
|
|
296
|
+
if (!runtime.monitor.isMonitored(panel.pane_id)) {
|
|
297
|
+
await runtime.monitor.track(panel);
|
|
298
|
+
}
|
|
299
|
+
const prepared = await prepareAskAnswer(
|
|
300
|
+
runtime.client,
|
|
301
|
+
runtime.monitor,
|
|
302
|
+
panel,
|
|
303
|
+
(params.answers ?? []) as AskAnswer[],
|
|
304
|
+
executionSignal,
|
|
305
|
+
);
|
|
306
|
+
const task = `Answer: ${prepared.ask.prompts
|
|
307
|
+
.map((prompt) => prompt.title)
|
|
308
|
+
.join(", ")}`;
|
|
309
|
+
const settlement = await dispatchAgentWork(
|
|
310
|
+
runtime,
|
|
311
|
+
panel,
|
|
312
|
+
task,
|
|
313
|
+
params.blocking !== false,
|
|
314
|
+
executionSignal,
|
|
315
|
+
update,
|
|
316
|
+
prepared.submit,
|
|
317
|
+
);
|
|
318
|
+
return toolResult(
|
|
319
|
+
settlement
|
|
320
|
+
? {
|
|
321
|
+
answered: true,
|
|
322
|
+
...settlementResult(runtime.machine, settlement),
|
|
323
|
+
}
|
|
324
|
+
: {
|
|
325
|
+
answered: true,
|
|
326
|
+
machine: runtime.machine,
|
|
327
|
+
target: panel.pane_id,
|
|
328
|
+
status: "working",
|
|
329
|
+
next: "Completion or blockage will be delivered automatically; do not poll",
|
|
330
|
+
},
|
|
331
|
+
);
|
|
332
|
+
}
|
|
333
|
+
throw new Error(`unsupported action ${params.action}`);
|
|
334
|
+
},
|
|
335
|
+
renderCall(args, theme, context) {
|
|
336
|
+
let params: AgentsParams | undefined;
|
|
337
|
+
try {
|
|
338
|
+
params = parseAgentsRequest(args);
|
|
339
|
+
} catch {
|
|
340
|
+
params = undefined;
|
|
341
|
+
}
|
|
342
|
+
const identity =
|
|
343
|
+
params?.target ??
|
|
344
|
+
params?.label ??
|
|
345
|
+
params?.name ??
|
|
346
|
+
params?.agent_type ??
|
|
347
|
+
"";
|
|
348
|
+
return new Text(
|
|
349
|
+
theme.fg(
|
|
350
|
+
context && "isBlocked" in context && context.isBlocked === true
|
|
351
|
+
? "warning"
|
|
352
|
+
: "toolTitle",
|
|
353
|
+
theme.bold(`agents ${params?.action ?? "request"}`),
|
|
354
|
+
) + (identity ? theme.fg("muted", ` · ${identity}`) : ""),
|
|
355
|
+
0,
|
|
356
|
+
0,
|
|
357
|
+
);
|
|
358
|
+
},
|
|
359
|
+
renderResult(toolResult, options, theme) {
|
|
360
|
+
const details =
|
|
361
|
+
typeof toolResult.details === "object" && toolResult.details !== null
|
|
362
|
+
? (toolResult.details as Record<string, unknown>)
|
|
363
|
+
: {};
|
|
364
|
+
const state =
|
|
365
|
+
typeof details["status"] === "string"
|
|
366
|
+
? details["status"]
|
|
367
|
+
: details["sent"] === true
|
|
368
|
+
? "sent"
|
|
369
|
+
: details["spawned"] === true
|
|
370
|
+
? "spawned"
|
|
371
|
+
: "done";
|
|
372
|
+
const target =
|
|
373
|
+
typeof details["name"] === "string"
|
|
374
|
+
? details["name"]
|
|
375
|
+
: typeof details["target"] === "string"
|
|
376
|
+
? details["target"]
|
|
377
|
+
: "";
|
|
378
|
+
const title = new Text(
|
|
379
|
+
theme.fg(
|
|
380
|
+
state === "blocked"
|
|
381
|
+
? "warning"
|
|
382
|
+
: state === "working"
|
|
383
|
+
? "accent"
|
|
384
|
+
: "success",
|
|
385
|
+
[target, state].filter(Boolean).join(" · "),
|
|
386
|
+
),
|
|
387
|
+
0,
|
|
388
|
+
0,
|
|
389
|
+
);
|
|
390
|
+
if (!options.expanded) return title;
|
|
391
|
+
const reply =
|
|
392
|
+
typeof details["reply"] === "string" ? details["reply"] : undefined;
|
|
393
|
+
const ask =
|
|
394
|
+
typeof details["ask"] === "object" && details["ask"] !== null
|
|
395
|
+
? (details["ask"] as { prompts?: unknown })
|
|
396
|
+
: undefined;
|
|
397
|
+
const informational = Object.fromEntries(
|
|
398
|
+
Object.entries(details).filter(
|
|
399
|
+
([key]) => key !== "reply" && key !== "ask",
|
|
400
|
+
),
|
|
401
|
+
);
|
|
402
|
+
if (
|
|
403
|
+
!reply &&
|
|
404
|
+
!Array.isArray(ask?.prompts) &&
|
|
405
|
+
Object.keys(informational).length === 0
|
|
406
|
+
) {
|
|
407
|
+
return title;
|
|
408
|
+
}
|
|
409
|
+
const container = new Container();
|
|
410
|
+
container.addChild(title);
|
|
411
|
+
if (Object.keys(informational).length > 0) {
|
|
412
|
+
container.addChild(new Spacer(1));
|
|
413
|
+
container.addChild(
|
|
414
|
+
new Text(JSON.stringify(informational, null, 2), 0, 0),
|
|
415
|
+
);
|
|
416
|
+
}
|
|
417
|
+
if (reply) {
|
|
418
|
+
container.addChild(new Spacer(1));
|
|
419
|
+
container.addChild(new Markdown(reply, 0, 0, getMarkdownTheme()));
|
|
420
|
+
}
|
|
421
|
+
if (Array.isArray(ask?.prompts)) {
|
|
422
|
+
const titles = ask.prompts
|
|
423
|
+
.flatMap((prompt) =>
|
|
424
|
+
typeof prompt === "object" &&
|
|
425
|
+
prompt !== null &&
|
|
426
|
+
"title" in prompt &&
|
|
427
|
+
typeof prompt.title === "string"
|
|
428
|
+
? [prompt.title]
|
|
429
|
+
: [],
|
|
430
|
+
)
|
|
431
|
+
.join(", ");
|
|
432
|
+
if (titles) {
|
|
433
|
+
container.addChild(new Spacer(1));
|
|
434
|
+
container.addChild(new Text(theme.fg("warning", titles), 0, 0));
|
|
435
|
+
}
|
|
436
|
+
}
|
|
437
|
+
return container;
|
|
438
|
+
},
|
|
439
|
+
});
|
|
440
|
+
}
|