@howaboua/pi-shepherdr 0.2.18 → 0.2.19

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 CHANGED
@@ -1,5 +1,11 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.2.19
4
+
5
+ - Added Codex parent-child metadata for workers when used with PCC, preserved on resume and independent of shared notes.
6
+
7
+ Agent-read help and invalid-source errors now list supported sources.
8
+
3
9
  ## 0.2.18
4
10
 
5
11
  - Replaced the Ask-specific `answer` action with `reply` for extension replies. Update and reload Ask and Shepherdr together on controllers and workers.
package/README.md CHANGED
@@ -194,6 +194,8 @@ Child board calls use the owning Pi sessions and existing SSH connections, not a
194
194
 
195
195
  ## Shared notes and history
196
196
 
197
+ With compatible Pi Codex Conversion on both ends, Shepherdr marks fresh spawned workers before their first task with their immediate parent's native Pi session ID and `subagentKind: "collab_spawn"`. Each worker keeps its own native session ID. This relationship works with shared notes disabled and does not grant notes access. Resume preserves it; forks and profiles selecting existing sessions do not acquire an inherited relationship. Older PCC versions without the optional capability retain ordinary delegation. The [extension API guide](../../docs/extension-apis.md#parent-and-worker-relationships) documents PCC's `bindRelationship` service contract for other orchestrators. Shepherdr owns transport, not a separate public relationship RPC API.
198
+
197
199
  With Pi Codex Conversion 3.0.40 or newer and notes-based continuity, enable **Share subagent context** under `/codex context` in the controller. It is off by default. Shared `spawn` gives each child a unique context identity before its first turn; `contextAgent` in the result identifies its notes and history. Shared nested spawns stay in the same family. Turning sharing off affects new spawns only; existing identity survives resume. `assign` and independently started agents remain unchanged. Older compatible Conversion versions keep ordinary delegation without sharing.
198
200
 
199
201
  Set `"share_context": false` in a profile to keep its new workers' notes and history independent even when controller sharing is enabled. Omission or `true` follows the controller setting, never turns sharing on itself. This separates context, not filesystem permissions or information included in the task.
package/biome.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
2
+ "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
3
3
  "vcs": {
4
4
  "enabled": true,
5
5
  "clientKind": "git",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.2.18",
3
+ "version": "0.2.19",
4
4
  "description": "Persistent blocking and asynchronous Pi agents through Herdr.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -43,7 +43,7 @@
43
43
  "pack:dry": "npm pack --dry-run"
44
44
  },
45
45
  "peerDependencies": {
46
- "@howaboua/pi-codex-conversion": ">=3.0.50",
46
+ "@howaboua/pi-codex-conversion": ">=3.0.51",
47
47
  "@earendil-works/pi-ai": ">=1.1.0",
48
48
  "@earendil-works/pi-coding-agent": ">=1.1.0",
49
49
  "@earendil-works/pi-tui": ">=1.1.0",
@@ -58,13 +58,13 @@
58
58
  "@howaboua/pi-agent-board": "0.0.1"
59
59
  },
60
60
  "devDependencies": {
61
- "@howaboua/pi-codex-conversion": "3.0.50",
62
- "@biomejs/biome": "^2.5.10",
61
+ "@howaboua/pi-codex-conversion": "3.0.51",
62
+ "@biomejs/biome": "^2.5.15",
63
63
  "@earendil-works/pi-ai": "1.1.0",
64
64
  "@earendil-works/pi-coding-agent": "1.1.0",
65
65
  "@earendil-works/pi-tui": "1.1.0",
66
- "@types/node": "^26.2.0",
67
- "typebox": "1.3.18",
66
+ "@types/node": "^26.6.5",
67
+ "typebox": "1.3.36",
68
68
  "typescript": "^7.0.2"
69
69
  },
70
70
  "pi": {
@@ -182,6 +182,13 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
182
182
  if (unknown.length > 0) {
183
183
  throw new Error(`unknown ${action} field(s): ${unknown.join(", ")}`);
184
184
  }
185
+ if (
186
+ action === "read" &&
187
+ "source" in request &&
188
+ !READ_SOURCES.some((source) => source === request["source"])
189
+ ) {
190
+ throw new Error(`read source must be one of: ${READ_SOURCES.join(", ")}`);
191
+ }
185
192
  if (!Check(AgentsRequest, request)) {
186
193
  throw new Error(
187
194
  `invalid ${action} request; call agents help for its contract`,
@@ -44,7 +44,7 @@ export async function agentsHelp(
44
44
  assign: "target message machine? blocking?",
45
45
  attach: "target context board machine?",
46
46
  detach: "target context board machine?",
47
- read: "target machine? source? lines?",
47
+ read: "target machine? source=latest|visible|recent? lines?",
48
48
  reply: "target extension id message machine?",
49
49
  },
50
50
  rules: {
@@ -123,6 +123,11 @@ export async function spawnAgent(
123
123
  status: "starting",
124
124
  });
125
125
  const agentArgs = profileAgentArgs(profile, { targetLocal: runtime.local });
126
+ const relationship = sharedContext.prepareRelationship(
127
+ ctx,
128
+ runtime,
129
+ agentArgs,
130
+ );
126
131
  const sharing =
127
132
  profile.shareContext === false
128
133
  ? undefined
@@ -140,8 +145,10 @@ export async function spawnAgent(
140
145
  let dispatch;
141
146
  let shared: { agentName?: string; warning?: string } | undefined;
142
147
  let boardAgent: string | undefined;
148
+ let relationshipWarning: string | undefined;
143
149
  const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
144
150
  try {
151
+ relationshipWarning = (await relationship?.accept(started.agent))?.warning;
145
152
  boardAgent = await boardBinding?.accept(started.agent);
146
153
  shared = await sharing?.accept(started.agent);
147
154
  dispatch = await dispatchAgentWork(
@@ -197,6 +204,8 @@ export async function spawnAgent(
197
204
  next: "Converse, do other work or reply now; completion/blockage arrives even after you reply. No polling or sleep waits",
198
205
  }),
199
206
  },
200
- [dispatch.warning, shared?.warning].filter(Boolean).join("\n") || undefined,
207
+ [dispatch.warning, shared?.warning, relationshipWarning]
208
+ .filter(Boolean)
209
+ .join("\n") || undefined,
201
210
  );
202
211
  }
@@ -160,6 +160,14 @@ export class SharedAgentContext {
160
160
  if (!service || !identity) return null;
161
161
  return service.bind(ctx, "binding" in value ? value.binding : undefined);
162
162
  }
163
+ if ("operation" in value && value.operation === "bind-relationship") {
164
+ return (
165
+ service?.bindRelationship?.(
166
+ ctx,
167
+ "relationship" in value ? value.relationship : undefined,
168
+ ) ?? null
169
+ );
170
+ }
163
171
  if (!identity || !service)
164
172
  throw new Error("Context sharing is unavailable in this session");
165
173
  const envelope = value as Partial<ContextEnvelope>;
@@ -290,6 +298,50 @@ export class SharedAgentContext {
290
298
  return matches[0]!;
291
299
  }
292
300
 
301
+ prepareRelationship(
302
+ ctx: ExtensionContext,
303
+ runtime: ConnectedMachine,
304
+ args: readonly string[],
305
+ ) {
306
+ if (!this.getService()?.bindRelationship) return undefined;
307
+ // Session-selection profiles resume existing identities rather than creating workers.
308
+ if (
309
+ args.some((arg) =>
310
+ /^(?:--(?:session(?:-id)?|continue|resume|no-session|fork)(?:=|$)|-[cr]$)/.test(
311
+ arg,
312
+ ),
313
+ )
314
+ )
315
+ return undefined;
316
+ const parentThreadId = ctx.sessionManager.getSessionId();
317
+ const relationship = { parentThreadId, subagentKind: "collab_spawn" };
318
+ return {
319
+ accept: async (agent: PaneInfo) => {
320
+ const file = sessionPath(agent);
321
+ if (!file) throw new Error("Spawned agent has no saved Pi session");
322
+ const value = await runtime.client.requestContext(
323
+ sessionContextPath(file),
324
+ {
325
+ operation: "bind-relationship",
326
+ relationship,
327
+ },
328
+ );
329
+ if (ctx.sessionManager.getSessionId() !== parentThreadId)
330
+ throw new Error("Controller session changed during spawn");
331
+ if (value === null)
332
+ return {
333
+ warning:
334
+ "Worker relationship marking requires Codex conversion on the target",
335
+ };
336
+ if (!isDeepStrictEqual(value, relationship))
337
+ throw new Error(
338
+ "Spawned agent did not adopt its parent relationship",
339
+ );
340
+ return undefined;
341
+ },
342
+ };
343
+ }
344
+
293
345
  async prepare(
294
346
  ctx: ExtensionContext,
295
347
  runtime: ConnectedMachine,