@howaboua/pi-shepherdr 0.2.21 → 0.2.23

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/board/host.ts CHANGED
@@ -57,7 +57,8 @@ export class AgentBoard {
57
57
  discoverBoard(pi, (runtime) => {
58
58
  this.runtime = runtime;
59
59
  runtime.attach({
60
- briefing: boardBriefing,
60
+ briefing: (member, population) =>
61
+ boardBriefing(member, population, runtime.gptPromptMode),
61
62
  request: requestContext,
62
63
  commitDirectory: (own, directory, caller, request) =>
63
64
  this.membership.commitDirectory(own, directory, caller, request),
@@ -136,7 +137,7 @@ export class AgentBoard {
136
137
  args: readonly string[],
137
138
  ) {
138
139
  if (!this.enabled(ctx)) return undefined;
139
- const own = binding(ctx);
140
+ const own = { ...binding(ctx), enabled: true };
140
141
  if (
141
142
  args.some((arg) =>
142
143
  /^(?:--(?:session(?:-id)?|continue|resume|no-session|fork)(?:=|$)|-[cr]$)/.test(
package/src/launch.ts CHANGED
@@ -11,6 +11,7 @@ import {
11
11
  } from "./herdr.js";
12
12
  import { type HerdrConnection, isHerdrErrorCode } from "./herdr-client.js";
13
13
  import type { PaneInfo } from "./types.js";
14
+ import { WORKER_FLAG } from "./worker-role.js";
14
15
 
15
16
  export const START_PLACEMENTS = ["new_workspace", "new_tab", "pane"] as const;
16
17
  const AGENT_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
@@ -87,6 +88,18 @@ export interface StartedAgent {
87
88
  id: string;
88
89
  }
89
90
 
91
+ export class RolledBackAgentLaunchError extends Error {
92
+ constructor(cause: unknown) {
93
+ super(cause instanceof Error ? cause.message : String(cause), { cause });
94
+ }
95
+ }
96
+
97
+ export class UnstartedAgentLaunchError extends Error {
98
+ constructor(cause: unknown) {
99
+ super(cause instanceof Error ? cause.message : String(cause), { cause });
100
+ }
101
+ }
102
+
90
103
  async function createStartPane(
91
104
  client: HerdrConnection,
92
105
  params: StartAgentParams,
@@ -103,10 +116,13 @@ async function createStartPane(
103
116
  }
104
117
  if (placement === "new_tab") {
105
118
  const workspaceTarget = required(params.workspace, "workspace");
106
- const workspace = resolveWorkspace(
107
- await getSnapshot(client),
108
- workspaceTarget,
109
- );
119
+ let workspace;
120
+ try {
121
+ workspace = resolveWorkspace(await getSnapshot(client), workspaceTarget);
122
+ } catch (error) {
123
+ throw new UnstartedAgentLaunchError(error);
124
+ }
125
+ // A failed create response may still have created a location.
110
126
  const created = createdLocation(
111
127
  await client.request<unknown>("tab.create", {
112
128
  workspace_id: workspace.workspace_id,
@@ -207,11 +223,24 @@ export async function startAgent(
207
223
  ): Promise<StartedAgent> {
208
224
  const name = required(params.name, "name");
209
225
  if (!AGENT_NAME.test(name)) {
210
- throw new Error("name must match [a-z][a-z0-9_-]{0,31}");
226
+ throw new Error(
227
+ "name must be 1–32 characters, start with a lowercase letter, and contain only lowercase letters, digits, underscores or hyphens. Omit name to generate it from label; label can be longer.",
228
+ );
211
229
  }
212
230
  const label = params.label?.trim() || name;
213
- const args = ["--name", label, ...(options.agentArgs ?? [])];
214
- if (parseArgs(args).noSession) {
231
+ const args = [
232
+ `--${WORKER_FLAG}`,
233
+ "--name",
234
+ label,
235
+ ...(options.agentArgs ?? []),
236
+ ];
237
+ const parsed = parseArgs(args);
238
+ if (parsed.unknownFlags.get(WORKER_FLAG) !== true) {
239
+ throw new Error(
240
+ "spawn requires its worker role; remove --shepherdr-worker from profile pi_args",
241
+ );
242
+ }
243
+ if (parsed.noSession) {
215
244
  throw new Error(
216
245
  "spawn requires a persistent Pi session; remove --no-session from profile pi_args",
217
246
  );
@@ -221,11 +250,12 @@ export async function startAgent(
221
250
  "cwd cannot change an existing pane; prepare the pane through Herdr",
222
251
  );
223
252
  }
224
- const cwd = await resolveStartDirectory(
225
- params,
226
- fallbackCwd,
227
- resolveDirectory,
228
- );
253
+ let cwd: string;
254
+ try {
255
+ cwd = await resolveStartDirectory(params, fallbackCwd, resolveDirectory);
256
+ } catch (error) {
257
+ throw new UnstartedAgentLaunchError(error);
258
+ }
229
259
  const created = await createStartPane(client, params, cwd, label);
230
260
  let agent: PaneInfo;
231
261
  try {
@@ -270,7 +300,7 @@ async function rollbackCreatedLocation(
270
300
  { cause },
271
301
  );
272
302
  }
273
- throw cause;
303
+ throw new RolledBackAgentLaunchError(cause);
274
304
  }
275
305
 
276
306
  async function startWhenShellReady(
package/src/messages.ts CHANGED
@@ -72,8 +72,8 @@ export function orchestrationGuidance(enabled: boolean, general: boolean) {
72
72
  if (!enabled)
73
73
  return `Work normally. Delegate only when useful or requested. ${ownership}`;
74
74
  const guidance = general
75
- ? "Your main goal from now on is to orchestrate agents. Fan out suitable work to general agents, synthesize their results, and report the outcome. Work directly only when asked or for routine local tasks."
76
- : "Your main goal from now on is to orchestrate agents. Fan out suitable work, synthesize agent results, and report the outcome. Work directly only when asked or for routine local tasks.";
75
+ ? "Orchestrate general agents with separate scopes. Integrate their results, validate the combined outcome and report it. Work directly only when asked or for routine local tasks."
76
+ : "Orchestrate agents with separate scopes. Integrate their results, validate the combined outcome and report it. Work directly only when asked or for routine local tasks.";
77
77
  return `${guidance} ${ownership}`;
78
78
  }
79
79
  export function activeAgentsBriefing(
@@ -110,16 +110,34 @@ export function boardMigrationWarning() {
110
110
  export function boardBriefing(
111
111
  member: boolean,
112
112
  population: "empty" | "populated" | "unavailable",
113
+ gpt = false,
113
114
  ) {
114
115
  const state =
115
116
  population === "populated"
116
- ? "Read relevant board threads."
117
+ ? gpt
118
+ ? "Read relevantboardthreads."
119
+ : "Read relevant board threads."
117
120
  : population === "empty"
118
- ? "Shared board available; no posts yet."
119
- : "Shared board status unavailable. Check board help and retry reading when available.";
121
+ ? gpt
122
+ ? "Sharedboard available; posts=none."
123
+ : "Shared board available; no posts yet."
124
+ : gpt
125
+ ? "Sharedboard status unavailable; board help→retry read when available."
126
+ : "Shared board status unavailable. Check board help and retry reading when available.";
120
127
  const setup = member
121
- ? "The root agent owns setup; follow your assigned task."
128
+ ? gpt
129
+ ? "Root owns setup; follow assignedtask."
130
+ : "The root agent owns setup; follow your assigned task."
122
131
  : "";
132
+ if (gpt)
133
+ return [
134
+ state,
135
+ setup,
136
+ "Posts=work-changing ownership/decisions/findings/blockers only. Existingthread replies; link≠repeat. Personalcheckpoints→notes. No ack/statusspam/duplicate completionreports. Assignments/urgentmessages→agents.",
137
+ "Channels=workstreams; threads=topics. Reuse relevantchannels≠catchalls. Newchannel requires distinctcoordinationpurpose; never task/result announcement only.",
138
+ ]
139
+ .filter(Boolean)
140
+ .join(" ");
123
141
  return (
124
142
  [
125
143
  state,
@@ -9,6 +9,8 @@ import type { ExtensionMessage, MonitoredAgent, PaneInfo } from "./types.js";
9
9
 
10
10
  interface MonitorExtensionMessagesOptions {
11
11
  client: HerdrConnection;
12
+ machine: string;
13
+ machineLabel: () => string;
12
14
  reader: AssistantReader;
13
15
  state: MonitorState;
14
16
  notify: (
@@ -176,8 +178,19 @@ export class MonitorExtensionMessages {
176
178
  private warning(error: unknown): void {
177
179
  if (this.warned) return;
178
180
  this.warned = true;
181
+ const label = this.options.machineLabel();
182
+ const machine =
183
+ label === this.options.machine
184
+ ? label
185
+ : `${label} (${this.options.machine})`;
186
+ const detail =
187
+ error instanceof Error && "code" in error && error.code === "EPIPE"
188
+ ? "the connection closed"
189
+ : error instanceof Error
190
+ ? error.message
191
+ : String(error);
179
192
  this.context?.ui.notify(
180
- `Worker extension notifications unavailable: ${error instanceof Error ? error.message : String(error)}. Use agents read to inspect workers; reconnect through /herdr`,
193
+ `Worker notices unavailable on ${machine}: ${detail}. Open /herdr → Status to reconnect. Then use agents read to check worker messages.`,
181
194
  "warning",
182
195
  );
183
196
  }
package/src/monitor.ts CHANGED
@@ -61,6 +61,8 @@ export class AgentMonitor {
61
61
  const reader = options.reader ?? new SessionReader();
62
62
  this.extensionMessages = new MonitorExtensionMessages({
63
63
  client: this.client,
64
+ machine: this.machine,
65
+ machineLabel: options.machineLabel,
64
66
  reader,
65
67
  state: this.state,
66
68
  notify: (ctx, record, agent, message) => {
@@ -0,0 +1,32 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+
3
+ export const PROFILE_PROMPT_FLAG = "shepherdr-profile-prompt";
4
+ const SECTION = "shepherdr_profile";
5
+
6
+ export function registerProfilePrompt(pi: ExtensionAPI): void {
7
+ pi.registerFlag(PROFILE_PROMPT_FLAG, {
8
+ type: "string",
9
+ description: "JSON-encoded worker profile prompt",
10
+ });
11
+ pi.on("before_agent_start", async (event, ctx) => {
12
+ const encoded = pi.getFlag(PROFILE_PROMPT_FLAG);
13
+ if (encoded === undefined) return;
14
+ let prompt: unknown;
15
+ try {
16
+ prompt = JSON.parse(String(encoded));
17
+ if (typeof prompt !== "string") throw new Error("Expected a string");
18
+ } catch (cause) {
19
+ await ctx.abort();
20
+ throw new Error("Worker profile prompt is invalid; respawn the worker", {
21
+ cause,
22
+ });
23
+ }
24
+ // Custom sections follow shared project context. Never relocate foreign addenda.
25
+ const options = event.systemPromptOptions;
26
+ if (options.forceSystemPrompt !== undefined) {
27
+ options.forceSystemPrompt += `\n\n<${SECTION}>\n${prompt}\n</${SECTION}>`;
28
+ } else {
29
+ options.sections[SECTION] = prompt;
30
+ }
31
+ });
32
+ }
package/src/profiles.ts CHANGED
@@ -13,6 +13,7 @@ import {
13
13
  import { homedir } from "node:os";
14
14
  import { join, resolve } from "node:path";
15
15
  import { fileURLToPath, pathToFileURL } from "node:url";
16
+ import { PROFILE_PROMPT_FLAG } from "./profile-prompt.js";
16
17
 
17
18
  const PROFILE_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
18
19
  const AGENT_DIRECTORY =
@@ -33,7 +34,6 @@ export interface AgentProfile {
33
34
  piArgs: string[];
34
35
  prepare?: string;
35
36
  prompt?: string;
36
- promptPath?: string;
37
37
  shareContext?: boolean;
38
38
  thinking: string;
39
39
  }
@@ -165,7 +165,6 @@ async function readProfile(
165
165
  ...(resolvedPromptPath
166
166
  ? {
167
167
  prompt: await readFile(resolvedPromptPath, "utf8"),
168
- promptPath: resolvedPromptPath,
169
168
  }
170
169
  : {}),
171
170
  ...(prepare ? { prepare } : {}),
@@ -261,34 +260,18 @@ export async function loadAgentProfiles(): Promise<Map<string, AgentProfile>> {
261
260
  return profiles;
262
261
  }
263
262
 
264
- function promptArgument(
265
- profile: AgentProfile,
266
- targetLocal: boolean,
267
- ): string | undefined {
268
- if (
269
- targetLocal &&
270
- profile.promptPath &&
271
- ![...profile.promptPath].some((character) => /\p{Cc}/u.test(character))
272
- ) {
273
- return profile.promptPath;
274
- }
275
- return profile.prompt
276
- ?.replace(/\p{Cc}+/gu, " ")
277
- .replace(/\s+/gu, " ")
278
- .trim();
279
- }
280
-
281
263
  export function profileAgentArgs(
282
264
  profile: AgentProfile,
283
- options: { targetLocal?: boolean } = {},
265
+ options: { includePrompt?: boolean } = {},
284
266
  ): string[] {
285
- const prompt = promptArgument(profile, options.targetLocal !== false);
267
+ const prompt = options.includePrompt === false ? undefined : profile.prompt;
286
268
  return [
287
269
  "--model",
288
270
  profile.model,
289
271
  "--thinking",
290
272
  profile.thinking,
291
- ...(prompt ? ["--append-system-prompt", prompt] : []),
273
+ // JSON keeps newlines/control characters out of argv without altering role text.
274
+ ...(prompt ? [`--${PROFILE_PROMPT_FLAG}`, JSON.stringify(prompt)] : []),
292
275
  ...profile.piArgs,
293
276
  ];
294
277
  }
@@ -141,13 +141,17 @@ async function deploy(
141
141
  child.stderr.on("data", (chunk: Buffer) => {
142
142
  stderr = appendBounded(stderr, chunk);
143
143
  });
144
- child.stdin.end(source);
145
144
  await new Promise<void>((resolve, reject) => {
146
145
  const timer = setTimeout(() => {
147
146
  child.kill();
148
147
  reject(new Error("remote bridge deployment timed out"));
149
148
  }, DEPLOY_TIMEOUT_MS);
150
149
  timer.unref();
150
+ child.stdin.on("error", (error) => {
151
+ clearTimeout(timer);
152
+ child.kill();
153
+ reject(error);
154
+ });
151
155
  child.on("error", (error) => {
152
156
  clearTimeout(timer);
153
157
  reject(error);
@@ -164,6 +168,7 @@ async function deploy(
164
168
  ),
165
169
  );
166
170
  });
171
+ child.stdin.end(source);
167
172
  });
168
173
  }
169
174
 
@@ -196,6 +201,7 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
196
201
  child.stderr.on("data", (chunk: Buffer) => {
197
202
  this.diagnostics = appendBounded(this.diagnostics, chunk);
198
203
  });
204
+ child.stdin.on("error", (error) => this.disconnected(error));
199
205
  child.on("error", (error) => this.disconnected(error));
200
206
  child.on("exit", (code) => {
201
207
  this.disconnected(
@@ -572,7 +578,7 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
572
578
  `${JSON.stringify({ ...message, id })}\n`,
573
579
  (error) => {
574
580
  if (!error) return;
575
- this.rejectPending(id, error);
581
+ this.disconnected(error);
576
582
  },
577
583
  );
578
584
  });
@@ -712,6 +718,10 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
712
718
 
713
719
  private disconnected(error: Error): void {
714
720
  if (this.closed) return;
721
+ if ("code" in error && error.code === "EPIPE")
722
+ error = new Error("Connection to the remote machine closed", {
723
+ cause: error,
724
+ });
715
725
  this.closed = true;
716
726
  this.child.kill();
717
727
  this.failPending(error, true);
@@ -36,7 +36,8 @@ export class SpawnContext {
36
36
  runtime: ConnectedMachine,
37
37
  args: readonly string[],
38
38
  ) {
39
- if (!this.getService()?.bindRelationship) return undefined;
39
+ const service = this.getService();
40
+ if (!service?.bindRelationship) return undefined;
40
41
  // Session-selection profiles resume existing identities rather than creating workers.
41
42
  if (
42
43
  args.some((arg) =>
@@ -47,7 +48,12 @@ export class SpawnContext {
47
48
  )
48
49
  return undefined;
49
50
  const parentThreadId = ctx.sessionManager.getSessionId();
50
- const relationship = { parentThreadId, subagentKind: "collab_spawn" };
51
+ const cacheAffinityId = service.cacheAffinityId?.(ctx);
52
+ const linkage = { parentThreadId, subagentKind: "collab_spawn" };
53
+ const relationship = {
54
+ ...linkage,
55
+ ...(cacheAffinityId ? { cacheAffinityId } : {}),
56
+ };
51
57
  return {
52
58
  accept: async (agent: PaneInfo) => {
53
59
  const file = sessionPath(agent);
@@ -66,6 +72,12 @@ export class SpawnContext {
66
72
  warning:
67
73
  "Worker relationship marking requires Codex conversion on the target",
68
74
  };
75
+ // Older targets preserve linkage but do not recognise cache affinity.
76
+ if (cacheAffinityId && isDeepStrictEqual(value, linkage))
77
+ return {
78
+ warning:
79
+ "Worker started without shared cache routing; update Codex Conversion on the target to enable it",
80
+ };
69
81
  if (!isDeepStrictEqual(value, relationship))
70
82
  throw new Error(
71
83
  "Spawned agent did not adopt its parent relationship",
@@ -0,0 +1,83 @@
1
+ import type {
2
+ ExtensionAPI,
3
+ ExtensionContext,
4
+ } from "@earendil-works/pi-coding-agent";
5
+
6
+ export const WORKER_FLAG = "shepherdr-worker";
7
+ export const PULSE_WORKER_FLAG = "shepherdr-pulse-worker";
8
+ const WORKER_MARKER = "herdr-worker-v1";
9
+ const LEGACY_PULSE_MARKER = "herdr-pulse-worker-v1";
10
+ const WORKER_ROLE_CHANNEL = "shepherdr:worker-role:v1";
11
+
12
+ type SessionManager = ExtensionContext["sessionManager"];
13
+
14
+ /** Optional synchronous event request; consumers need no Shepherdr import. */
15
+ interface WorkerRoleRequest {
16
+ sessionManager: SessionManager;
17
+ reply: (worker: boolean) => void;
18
+ }
19
+
20
+ function markedWorker(manager: SessionManager, pulseOnly = false): boolean {
21
+ const sessionId = manager.getSessionId();
22
+ return manager.getEntries().some((entry) => {
23
+ if (
24
+ entry.type !== "custom" ||
25
+ (entry.customType !== WORKER_MARKER &&
26
+ entry.customType !== LEGACY_PULSE_MARKER)
27
+ )
28
+ return false;
29
+ const data = entry.data as
30
+ | { sessionId?: unknown; pulse?: unknown }
31
+ | undefined;
32
+ return (
33
+ data?.sessionId === sessionId &&
34
+ (!pulseOnly ||
35
+ entry.customType === LEGACY_PULSE_MARKER ||
36
+ data.pulse === true)
37
+ );
38
+ });
39
+ }
40
+
41
+ export function registerWorkerRole(pi: ExtensionAPI) {
42
+ pi.registerFlag(WORKER_FLAG, {
43
+ type: "boolean",
44
+ default: false,
45
+ description: "Run as a supervised Shepherdr worker",
46
+ });
47
+ pi.registerFlag(PULSE_WORKER_FLAG, {
48
+ type: "boolean",
49
+ default: false,
50
+ description: "Run as a detached pulse worker",
51
+ });
52
+ const isWorker = (manager: SessionManager) =>
53
+ pi.getFlag(WORKER_FLAG) === true ||
54
+ pi.getFlag(PULSE_WORKER_FLAG) === true ||
55
+ markedWorker(manager);
56
+ const isPulseWorker = (manager: SessionManager) =>
57
+ pi.getFlag(PULSE_WORKER_FLAG) === true || markedWorker(manager, true);
58
+ // Read the supplied native session directly, even before our session_start.
59
+ pi.events.on(WORKER_ROLE_CHANNEL, (request: unknown) => {
60
+ const value = request as Partial<WorkerRoleRequest> | undefined;
61
+ if (
62
+ typeof value?.reply === "function" &&
63
+ typeof value.sessionManager?.getSessionId === "function" &&
64
+ typeof value.sessionManager.getEntries === "function"
65
+ )
66
+ value.reply(isWorker(value.sessionManager));
67
+ });
68
+ pi.on("before_agent_start", (_event, ctx) => {
69
+ const pulse = pi.getFlag(PULSE_WORKER_FLAG) === true;
70
+ if (
71
+ (pi.getFlag(WORKER_FLAG) === true || pulse) &&
72
+ (!markedWorker(ctx.sessionManager) ||
73
+ (pulse && !markedWorker(ctx.sessionManager, true)))
74
+ ) {
75
+ // Startup entries would prevent fresh Notes family adoption before work.
76
+ pi.appendEntry(WORKER_MARKER, {
77
+ sessionId: ctx.sessionManager.getSessionId(),
78
+ ...(pulse ? { pulse: true } : {}),
79
+ });
80
+ }
81
+ });
82
+ return { isWorker, isPulseWorker };
83
+ }