@howaboua/pi-shepherdr 0.2.4 → 0.2.6

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/src/settlement.ts CHANGED
@@ -45,6 +45,7 @@ export interface ClaimedSettlement extends CollectedSettlement {
45
45
  }
46
46
 
47
47
  interface SettlementClaim {
48
+ answeringAskId?: string;
48
49
  cleanup(): void;
49
50
  reject(error: Error): void;
50
51
  resolve(settlement: ClaimedSettlement): void;
@@ -225,7 +226,11 @@ export class SettlementReporter {
225
226
  this.retries.clear();
226
227
  }
227
228
 
228
- claim(attempt: WorkAttempt, signal: AbortSignal): Promise<ClaimedSettlement> {
229
+ claim(
230
+ attempt: WorkAttempt,
231
+ signal: AbortSignal,
232
+ answeringAskId?: string,
233
+ ): Promise<ClaimedSettlement> {
229
234
  signal.throwIfAborted();
230
235
  if (this.claims.has(attempt.attemptId)) {
231
236
  throw new Error(`work attempt ${attempt.attemptId} is already claimed`);
@@ -243,6 +248,7 @@ export class SettlementReporter {
243
248
  );
244
249
  };
245
250
  const claim: SettlementClaim = {
251
+ ...(answeringAskId ? { answeringAskId } : {}),
246
252
  cleanup: () => signal.removeEventListener("abort", abort),
247
253
  reject,
248
254
  resolve,
@@ -324,6 +330,18 @@ export class SettlementReporter {
324
330
  const retryRequest = task ? { ...request, task } : request;
325
331
  const expectedUser = activityExpectedUser(current.activity);
326
332
  const blocked = settlement.status === "blocked";
333
+ const answeringAskId = retryState.attemptId
334
+ ? this.claims.get(retryState.attemptId)?.answeringAskId
335
+ : undefined;
336
+ // The original Ask's blocked snapshot is not settlement of its answer.
337
+ if (
338
+ blocked &&
339
+ answeringAskId &&
340
+ settlement.ask?.toolCallId === answeringAskId &&
341
+ !settlement.session.askResults?.[answeringAskId]
342
+ ) {
343
+ return;
344
+ }
327
345
  // A blocked status is authoritative even when Pi has not persisted the turn.
328
346
  // Pi persists expanded skills/templates, not the submitted command text.
329
347
  if (
package/src/types.ts CHANGED
@@ -127,8 +127,14 @@ export interface PendingAsk {
127
127
  toolCallId: string;
128
128
  }
129
129
 
130
+ export interface AskResult {
131
+ responses?: Array<{ comment?: string; id: string; selections: string[] }>;
132
+ status: "accepted" | "rejected" | "unknown";
133
+ }
134
+
130
135
  export interface SessionView {
131
136
  ask?: PendingAsk;
137
+ askResults?: Record<string, AskResult>;
132
138
  assistant?: LatestAssistant;
133
139
  assistantAfterInput?: boolean;
134
140
  input?: LatestInput;
@@ -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
- }