@howaboua/pi-shepherdr 0.2.5 → 0.2.7
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 +20 -0
- package/README.md +14 -2
- package/index.ts +3 -1
- package/package.json +6 -6
- package/src/agents-answer.ts +108 -0
- package/src/agents-contract.ts +18 -1
- package/src/agents-discovery.ts +211 -0
- package/src/agents-spawn.ts +179 -0
- package/src/agents-tool.ts +24 -202
- package/src/agents-work.ts +194 -0
- package/src/ask-answer.ts +54 -2
- package/src/delivery.ts +14 -3
- package/src/fleet.ts +66 -10
- package/src/herdr-client.ts +17 -0
- package/src/launch.ts +19 -8
- package/src/messages.ts +39 -7
- package/src/monitor.ts +2 -1
- package/src/peer-inbox.ts +10 -0
- package/src/remote/shepherdr-context.mjs +260 -0
- package/src/remote/shepherdr-peer.mjs +1 -1
- package/src/remote/shepherdr-session.mjs +294 -0
- package/src/remote/shepherdr.mjs +98 -236
- package/src/remote-client.ts +126 -17
- package/src/session-reader.ts +58 -0
- package/src/settlement.ts +19 -1
- package/src/shared-context.ts +283 -0
- package/src/types.ts +6 -0
- package/src/agents-operations.ts +0 -413
package/src/agents-operations.ts
DELETED
|
@@ -1,413 +0,0 @@
|
|
|
1
|
-
import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
|
|
2
|
-
import { activityTask } from "./activity.js";
|
|
3
|
-
import type { AgentsParams, READ_SOURCES } from "./agents-contract.js";
|
|
4
|
-
import type { AgentFleet, ConnectedMachine } from "./fleet.js";
|
|
5
|
-
import { getSnapshot } from "./herdr.js";
|
|
6
|
-
import { isDispatchRejected } from "./herdr-client.js";
|
|
7
|
-
import { agentSource } from "./messages.js";
|
|
8
|
-
import type { WorkAttempt } from "./monitor-state.js";
|
|
9
|
-
import { loadAgentProfiles } from "./profiles.js";
|
|
10
|
-
import type { ClaimedSettlement } from "./settlement.js";
|
|
11
|
-
import type {
|
|
12
|
-
AgentStatus,
|
|
13
|
-
PaneInfo,
|
|
14
|
-
PeerDelivery,
|
|
15
|
-
SessionSnapshot,
|
|
16
|
-
} from "./types.js";
|
|
17
|
-
|
|
18
|
-
const MAX_LIST_ITEMS = 30;
|
|
19
|
-
const MAX_TERMINAL_READ_CHARS = 36_000;
|
|
20
|
-
|
|
21
|
-
export function toolResult(value: Record<string, unknown>, warning?: string) {
|
|
22
|
-
if (warning) value = { ...value, next: warning };
|
|
23
|
-
return {
|
|
24
|
-
content: [{ type: "text" as const, text: JSON.stringify(value) }],
|
|
25
|
-
details: value,
|
|
26
|
-
};
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
export function reportProgress(
|
|
30
|
-
onUpdate: AgentToolUpdateCallback<Record<string, unknown>>,
|
|
31
|
-
message: string,
|
|
32
|
-
details: Record<string, unknown>,
|
|
33
|
-
): void {
|
|
34
|
-
onUpdate({
|
|
35
|
-
content: [{ type: "text", text: message }],
|
|
36
|
-
details,
|
|
37
|
-
});
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
export async function agentsHelp(): Promise<Record<string, unknown>> {
|
|
41
|
-
const profiles = await loadAgentProfiles();
|
|
42
|
-
return {
|
|
43
|
-
actions: {
|
|
44
|
-
help: "",
|
|
45
|
-
list: "machine?",
|
|
46
|
-
find: "query? status? machine?",
|
|
47
|
-
spawn:
|
|
48
|
-
"agent_type label message name? machine? placement? workspace? pane? cwd? base? blocking?",
|
|
49
|
-
watch: "target machine?",
|
|
50
|
-
unwatch: "target machine?",
|
|
51
|
-
send: "target message machine?",
|
|
52
|
-
assign: "target message machine? blocking?",
|
|
53
|
-
read: "target machine? source? lines?",
|
|
54
|
-
answer: "target answers machine? blocking?",
|
|
55
|
-
},
|
|
56
|
-
rules: {
|
|
57
|
-
machine:
|
|
58
|
-
"Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
|
|
59
|
-
target: "Use spawn/find target exactly",
|
|
60
|
-
label: "2-3 words; tab/session",
|
|
61
|
-
answers: "[{selections?:string[],other?:string,comment?:string}]",
|
|
62
|
-
send: "Peer questions, updates, replies; submission only, no wait or watch",
|
|
63
|
-
assign: "Delegate a task to an existing agent",
|
|
64
|
-
blocking:
|
|
65
|
-
"spawn/assign/answer default true; false pushes task settlement; never poll. Reviewer spawns always block; await review before working its scope",
|
|
66
|
-
watch:
|
|
67
|
-
"Explicit watch persists until unwatch; automatic task watches end on finish/failure, not blockage",
|
|
68
|
-
prompt:
|
|
69
|
-
"Only task + inaccessible context; no method/evidence/reporting boilerplate",
|
|
70
|
-
slash:
|
|
71
|
-
"Leading / uses target Pi commands/skills/templates; extension commands are submission-only, even with assign/spawn; TUI-only commands unavailable",
|
|
72
|
-
reuse:
|
|
73
|
-
"Reuse only same investigation; reviews independent; new scope = new agent",
|
|
74
|
-
...(profiles.has("general")
|
|
75
|
-
? {
|
|
76
|
-
general: "Only when requested/orchestrating",
|
|
77
|
-
}
|
|
78
|
-
: {}),
|
|
79
|
-
},
|
|
80
|
-
profiles: Object.fromEntries(
|
|
81
|
-
[...profiles].map(([name, profile]) => [name, profile.description]),
|
|
82
|
-
),
|
|
83
|
-
advanced: "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
|
|
84
|
-
};
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
function labels(snapshot: SessionSnapshot) {
|
|
88
|
-
return {
|
|
89
|
-
panes: new Map(snapshot.panes.map((pane) => [pane.pane_id, pane.label])),
|
|
90
|
-
tabs: new Map(snapshot.tabs.map((tab) => [tab.tab_id, tab.label])),
|
|
91
|
-
workspaces: new Map(
|
|
92
|
-
snapshot.workspaces.map((workspace) => [
|
|
93
|
-
workspace.workspace_id,
|
|
94
|
-
workspace.label,
|
|
95
|
-
]),
|
|
96
|
-
),
|
|
97
|
-
};
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
function compactAgent(
|
|
101
|
-
agent: PaneInfo,
|
|
102
|
-
snapshot: SessionSnapshot,
|
|
103
|
-
machine: string,
|
|
104
|
-
monitored: boolean,
|
|
105
|
-
): Record<string, unknown> {
|
|
106
|
-
const names = labels(snapshot);
|
|
107
|
-
return {
|
|
108
|
-
machine,
|
|
109
|
-
target: agent.pane_id,
|
|
110
|
-
...(agent.name ? { name: agent.name } : {}),
|
|
111
|
-
...(agent.label || names.panes.get(agent.pane_id)
|
|
112
|
-
? { label: agent.label ?? names.panes.get(agent.pane_id) }
|
|
113
|
-
: {}),
|
|
114
|
-
status: agent.agent_status,
|
|
115
|
-
cwd: agent.foreground_cwd ?? agent.cwd ?? null,
|
|
116
|
-
workspace: names.workspaces.get(agent.workspace_id) ?? agent.workspace_id,
|
|
117
|
-
tab: names.tabs.get(agent.tab_id) ?? agent.tab_id,
|
|
118
|
-
monitored,
|
|
119
|
-
};
|
|
120
|
-
}
|
|
121
|
-
|
|
122
|
-
function matchesAgent(
|
|
123
|
-
agent: Record<string, unknown>,
|
|
124
|
-
query: string | undefined,
|
|
125
|
-
status: AgentStatus | undefined,
|
|
126
|
-
): boolean {
|
|
127
|
-
if (status && agent["status"] !== status) return false;
|
|
128
|
-
if (!query) return true;
|
|
129
|
-
const haystack = Object.values(agent)
|
|
130
|
-
.filter((value) => typeof value === "string")
|
|
131
|
-
.join("\n")
|
|
132
|
-
.toLowerCase();
|
|
133
|
-
return haystack.includes(query.toLowerCase());
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
export async function listFleetAgents(
|
|
137
|
-
fleet: AgentFleet,
|
|
138
|
-
params: Pick<AgentsParams, "machine" | "query" | "status">,
|
|
139
|
-
): Promise<Record<string, unknown>> {
|
|
140
|
-
const [profiles, machines] = await Promise.all([
|
|
141
|
-
loadAgentProfiles(),
|
|
142
|
-
fleet.snapshots(params.machine),
|
|
143
|
-
]);
|
|
144
|
-
const agents = machines.flatMap((machine) => {
|
|
145
|
-
if (!machine.snapshot) return [];
|
|
146
|
-
return machine.snapshot.agents
|
|
147
|
-
.filter(
|
|
148
|
-
(agent) =>
|
|
149
|
-
agent.agent === "pi" &&
|
|
150
|
-
(!machine.local || agent.pane_id !== process.env["HERDR_PANE_ID"]),
|
|
151
|
-
)
|
|
152
|
-
.map((agent) =>
|
|
153
|
-
compactAgent(
|
|
154
|
-
agent,
|
|
155
|
-
machine.snapshot!,
|
|
156
|
-
machine.id,
|
|
157
|
-
machine.monitoredPaneIds?.has(agent.pane_id) ?? false,
|
|
158
|
-
),
|
|
159
|
-
)
|
|
160
|
-
.filter((agent) => matchesAgent(agent, params.query, params.status));
|
|
161
|
-
});
|
|
162
|
-
const workspaces = machines.flatMap((machine) =>
|
|
163
|
-
(machine.snapshot?.workspaces ?? []).map((workspace) => ({
|
|
164
|
-
machine: machine.id,
|
|
165
|
-
id: workspace.workspace_id,
|
|
166
|
-
label: workspace.label,
|
|
167
|
-
})),
|
|
168
|
-
);
|
|
169
|
-
return {
|
|
170
|
-
profiles: Object.fromEntries(
|
|
171
|
-
[...profiles].map(([name, profile]) => [name, profile.description]),
|
|
172
|
-
),
|
|
173
|
-
machines: machines.map(
|
|
174
|
-
({
|
|
175
|
-
snapshot: _snapshot,
|
|
176
|
-
monitoredPaneIds: _monitoredPaneIds,
|
|
177
|
-
...machine
|
|
178
|
-
}) => machine,
|
|
179
|
-
),
|
|
180
|
-
agents: agents.slice(0, MAX_LIST_ITEMS),
|
|
181
|
-
workspaces: workspaces.slice(0, MAX_LIST_ITEMS),
|
|
182
|
-
...(agents.length > MAX_LIST_ITEMS
|
|
183
|
-
? { moreAgents: agents.length - MAX_LIST_ITEMS }
|
|
184
|
-
: {}),
|
|
185
|
-
...(workspaces.length > MAX_LIST_ITEMS
|
|
186
|
-
? { moreWorkspaces: workspaces.length - MAX_LIST_ITEMS }
|
|
187
|
-
: {}),
|
|
188
|
-
};
|
|
189
|
-
}
|
|
190
|
-
|
|
191
|
-
export async function findFleetAgents(
|
|
192
|
-
fleet: AgentFleet,
|
|
193
|
-
params: Pick<AgentsParams, "machine" | "query" | "status">,
|
|
194
|
-
): Promise<Record<string, unknown>> {
|
|
195
|
-
const listed = await listFleetAgents(fleet, params);
|
|
196
|
-
return {
|
|
197
|
-
agents: listed["agents"],
|
|
198
|
-
...(listed["moreAgents"] === undefined
|
|
199
|
-
? {}
|
|
200
|
-
: { moreAgents: listed["moreAgents"] }),
|
|
201
|
-
};
|
|
202
|
-
}
|
|
203
|
-
|
|
204
|
-
function slugify(value: string): string {
|
|
205
|
-
const slug = value
|
|
206
|
-
.normalize("NFKD")
|
|
207
|
-
.replace(/[\u0300-\u036f]/gu, "")
|
|
208
|
-
.toLowerCase()
|
|
209
|
-
.replace(/[^a-z0-9]+/gu, "-")
|
|
210
|
-
.replace(/^-+|-+$/gu, "");
|
|
211
|
-
const named = /^[a-z]/u.test(slug) ? slug : `agent-${slug}`;
|
|
212
|
-
return named.slice(0, 32).replace(/-+$/u, "") || "agent";
|
|
213
|
-
}
|
|
214
|
-
|
|
215
|
-
export async function allocateAgentName(
|
|
216
|
-
runtime: ConnectedMachine,
|
|
217
|
-
label: string,
|
|
218
|
-
): Promise<string> {
|
|
219
|
-
const snapshot = await getSnapshot(runtime.client);
|
|
220
|
-
const names = new Set(
|
|
221
|
-
snapshot.agents.map((agent) => agent.name).filter(Boolean),
|
|
222
|
-
);
|
|
223
|
-
const base = slugify(label);
|
|
224
|
-
if (!names.has(base)) return base;
|
|
225
|
-
for (let suffix = 2; suffix < 10_000; suffix += 1) {
|
|
226
|
-
const tail = `-${suffix}`;
|
|
227
|
-
const candidate = `${base.slice(0, 32 - tail.length).replace(/-+$/u, "")}${tail}`;
|
|
228
|
-
if (!names.has(candidate)) return candidate;
|
|
229
|
-
}
|
|
230
|
-
throw new Error(
|
|
231
|
-
`could not allocate an agent name for ${JSON.stringify(label)}`,
|
|
232
|
-
);
|
|
233
|
-
}
|
|
234
|
-
|
|
235
|
-
export function settlementResult(
|
|
236
|
-
machine: string,
|
|
237
|
-
settlement: ClaimedSettlement,
|
|
238
|
-
): Record<string, unknown> {
|
|
239
|
-
if (settlement.reply?.stopReason === "error") {
|
|
240
|
-
throw new Error(
|
|
241
|
-
settlement.reply.text ||
|
|
242
|
-
`${settlement.agent.pane_id} assistant stopped with an error`,
|
|
243
|
-
);
|
|
244
|
-
}
|
|
245
|
-
const { pane, name, ...source } = agentSource(
|
|
246
|
-
settlement.agent,
|
|
247
|
-
settlement.labels,
|
|
248
|
-
);
|
|
249
|
-
return {
|
|
250
|
-
machine,
|
|
251
|
-
target: pane,
|
|
252
|
-
...(name ? { name } : {}),
|
|
253
|
-
source,
|
|
254
|
-
status: settlement.status,
|
|
255
|
-
...(settlement.reply ? { reply: settlement.reply.text } : {}),
|
|
256
|
-
...(settlement.ask
|
|
257
|
-
? {
|
|
258
|
-
ask: {
|
|
259
|
-
handoff: settlement.ask.handoff,
|
|
260
|
-
prompts: settlement.ask.prompts.map((prompt) => ({
|
|
261
|
-
title: prompt.title,
|
|
262
|
-
multiple: prompt.multiple,
|
|
263
|
-
choices: prompt.choices,
|
|
264
|
-
...(prompt.body ? { body: prompt.body } : {}),
|
|
265
|
-
})),
|
|
266
|
-
},
|
|
267
|
-
}
|
|
268
|
-
: {}),
|
|
269
|
-
...(settlement.blockedMessage
|
|
270
|
-
? { blocked_on: settlement.blockedMessage }
|
|
271
|
-
: {}),
|
|
272
|
-
...(settlement.status === "done" && !settlement.reply && !settlement.ask
|
|
273
|
-
? { completed: true }
|
|
274
|
-
: {}),
|
|
275
|
-
};
|
|
276
|
-
}
|
|
277
|
-
|
|
278
|
-
export async function dispatchAgentWork(
|
|
279
|
-
runtime: ConnectedMachine,
|
|
280
|
-
panel: PaneInfo,
|
|
281
|
-
task: string,
|
|
282
|
-
blocking: boolean,
|
|
283
|
-
signal: AbortSignal,
|
|
284
|
-
onUpdate: AgentToolUpdateCallback<Record<string, unknown>>,
|
|
285
|
-
send: () => Promise<PeerDelivery | void>,
|
|
286
|
-
options: { expectUserMessage?: boolean } = {},
|
|
287
|
-
): Promise<{
|
|
288
|
-
settlement?: ClaimedSettlement;
|
|
289
|
-
command?: true;
|
|
290
|
-
warning?: string;
|
|
291
|
-
}> {
|
|
292
|
-
signal.throwIfAborted();
|
|
293
|
-
const addedWatch = !runtime.monitor
|
|
294
|
-
.list()
|
|
295
|
-
.some(
|
|
296
|
-
(record) =>
|
|
297
|
-
record.terminalId === panel.terminal_id ||
|
|
298
|
-
record.paneId === panel.pane_id,
|
|
299
|
-
);
|
|
300
|
-
let attempt: WorkAttempt | undefined;
|
|
301
|
-
let settlement: Promise<ClaimedSettlement> | undefined;
|
|
302
|
-
let receipt: PeerDelivery | void;
|
|
303
|
-
let sendStarted = false;
|
|
304
|
-
try {
|
|
305
|
-
await runtime.monitor.track(panel);
|
|
306
|
-
const baseline = options.expectUserMessage
|
|
307
|
-
? await runtime.monitor.view(panel)
|
|
308
|
-
: undefined;
|
|
309
|
-
attempt = runtime.monitor.beginWork(
|
|
310
|
-
panel.pane_id,
|
|
311
|
-
task,
|
|
312
|
-
options.expectUserMessage ? (baseline?.input?.id ?? null) : undefined,
|
|
313
|
-
);
|
|
314
|
-
if (!attempt) throw new Error(`${panel.pane_id} is not monitored`);
|
|
315
|
-
settlement = blocking
|
|
316
|
-
? runtime.monitor.claimWork(attempt, signal)
|
|
317
|
-
: undefined;
|
|
318
|
-
void settlement?.catch(() => undefined);
|
|
319
|
-
signal.throwIfAborted();
|
|
320
|
-
sendStarted = true;
|
|
321
|
-
receipt = await send();
|
|
322
|
-
} catch (error) {
|
|
323
|
-
runtime.monitor.releaseWorkClaim(attempt, error);
|
|
324
|
-
if (sendStarted) await runtime.monitor.handleWorkFailure(attempt, error);
|
|
325
|
-
else runtime.monitor.rejectWork(attempt);
|
|
326
|
-
if (addedWatch && (!sendStarted || isDispatchRejected(error))) {
|
|
327
|
-
const record = runtime.monitor
|
|
328
|
-
.list()
|
|
329
|
-
.find((record) => record.terminalId === panel.terminal_id);
|
|
330
|
-
try {
|
|
331
|
-
if (record?.scope === "task" && !activityTask(record.activity)) {
|
|
332
|
-
await runtime.monitor.unwatch(record.paneId);
|
|
333
|
-
}
|
|
334
|
-
} catch (cleanupError) {
|
|
335
|
-
throw new AggregateError(
|
|
336
|
-
[error, cleanupError],
|
|
337
|
-
"Delegation failed; temporary watch cleanup also failed",
|
|
338
|
-
);
|
|
339
|
-
}
|
|
340
|
-
}
|
|
341
|
-
throw error;
|
|
342
|
-
}
|
|
343
|
-
try {
|
|
344
|
-
if (receipt?.command) {
|
|
345
|
-
runtime.monitor.releaseWorkClaim(
|
|
346
|
-
attempt,
|
|
347
|
-
new Error("Command submitted without task waiting"),
|
|
348
|
-
);
|
|
349
|
-
runtime.monitor.rejectWork(attempt);
|
|
350
|
-
if (addedWatch) {
|
|
351
|
-
const record = runtime.monitor
|
|
352
|
-
.list()
|
|
353
|
-
.find((record) => record.terminalId === panel.terminal_id);
|
|
354
|
-
if (record?.scope === "task" && !activityTask(record.activity))
|
|
355
|
-
await runtime.monitor.unwatch(record.paneId);
|
|
356
|
-
}
|
|
357
|
-
} else runtime.monitor.acceptWork(attempt);
|
|
358
|
-
await runtime.monitor.reconcileNow();
|
|
359
|
-
} catch (error) {
|
|
360
|
-
runtime.monitor.releaseWorkClaim(attempt, error);
|
|
361
|
-
return {
|
|
362
|
-
...(receipt?.command ? { command: true } : {}),
|
|
363
|
-
warning: `Submitted, but monitoring refresh failed: ${error instanceof Error ? error.message : String(error)}. Inspect the target before resubmitting`,
|
|
364
|
-
};
|
|
365
|
-
}
|
|
366
|
-
if (receipt?.command) return { command: true };
|
|
367
|
-
if (!blocking) return {};
|
|
368
|
-
reportProgress(onUpdate, `Waiting for ${panel.name ?? panel.pane_id}`, {
|
|
369
|
-
machine: runtime.machine,
|
|
370
|
-
target: panel.pane_id,
|
|
371
|
-
status: "working",
|
|
372
|
-
});
|
|
373
|
-
return { settlement: await settlement! };
|
|
374
|
-
}
|
|
375
|
-
|
|
376
|
-
export async function readAgentTerminal(
|
|
377
|
-
runtime: ConnectedMachine,
|
|
378
|
-
panel: PaneInfo,
|
|
379
|
-
source: Exclude<(typeof READ_SOURCES)[number], "latest">,
|
|
380
|
-
lines: number,
|
|
381
|
-
): Promise<Record<string, unknown>> {
|
|
382
|
-
const value = await runtime.client.request<unknown>("agent.read", {
|
|
383
|
-
target: panel.pane_id,
|
|
384
|
-
source,
|
|
385
|
-
format: "text",
|
|
386
|
-
lines,
|
|
387
|
-
strip_ansi: true,
|
|
388
|
-
});
|
|
389
|
-
if (
|
|
390
|
-
typeof value !== "object" ||
|
|
391
|
-
value === null ||
|
|
392
|
-
!("read" in value) ||
|
|
393
|
-
typeof value.read !== "object" ||
|
|
394
|
-
value.read === null ||
|
|
395
|
-
!("text" in value.read) ||
|
|
396
|
-
typeof value.read.text !== "string"
|
|
397
|
-
) {
|
|
398
|
-
throw new Error("Herdr agent.read returned no text");
|
|
399
|
-
}
|
|
400
|
-
const truncated = value.read.text.length > MAX_TERMINAL_READ_CHARS;
|
|
401
|
-
return {
|
|
402
|
-
machine: runtime.machine,
|
|
403
|
-
target: panel.pane_id,
|
|
404
|
-
status: panel.agent_status,
|
|
405
|
-
text: truncated
|
|
406
|
-
? `${value.read.text.slice(0, MAX_TERMINAL_READ_CHARS)}\n…`
|
|
407
|
-
: value.read.text,
|
|
408
|
-
...(truncated ||
|
|
409
|
-
("truncated" in value.read && value.read.truncated === true)
|
|
410
|
-
? { truncated: true }
|
|
411
|
-
: {}),
|
|
412
|
-
};
|
|
413
|
-
}
|