@howaboua/pi-shepherdr 0.2.28-core.12.1.gda85fa2e8a0f → 1.0.0

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.
Files changed (55) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +34 -5
  3. package/biome.json +1 -1
  4. package/index.ts +5 -2
  5. package/package.json +19 -14
  6. package/src/agents-contract.ts +80 -61
  7. package/src/agents-discovery.ts +14 -10
  8. package/src/agents-focus.ts +7 -0
  9. package/src/agents-reply.ts +3 -12
  10. package/src/agents-spawn.ts +26 -2
  11. package/src/agents-tool.ts +57 -21
  12. package/src/agents-work.ts +9 -4
  13. package/src/ancestry-record.ts +116 -0
  14. package/src/attachment-notes.ts +3 -2
  15. package/src/attachment-protocol.ts +124 -68
  16. package/src/attachment-target.ts +8 -7
  17. package/src/attachment.ts +3 -3
  18. package/src/board/records.ts +50 -36
  19. package/src/close-idle.ts +2 -2
  20. package/src/controller.ts +5 -4
  21. package/src/core/backend.ts +26 -3
  22. package/src/core/helper-bootstrap.mjs +1 -1
  23. package/src/core/helper-core.mjs +4 -3
  24. package/src/core/helper-lifetime.mjs +199 -0
  25. package/src/core/remote-endpoint.ts +10 -3
  26. package/src/core/remote-helper.ts +3 -0
  27. package/src/core/remote-service.mjs +9 -0
  28. package/src/core/remote-transport.ts +11 -1
  29. package/src/core/spawn.ts +1 -1
  30. package/src/core/terminal-peer.mjs +26 -5
  31. package/src/core/terminal.ts +2 -1
  32. package/src/fleet/connection.ts +4 -0
  33. package/src/fleet/index.ts +24 -3
  34. package/src/launch-contract.ts +1 -0
  35. package/src/launch.ts +40 -3
  36. package/src/messages/attribution.ts +14 -5
  37. package/src/messages/focus.ts +4 -3
  38. package/src/messages/peer-sharing.ts +34 -20
  39. package/src/monitor-events.ts +10 -10
  40. package/src/monitor-extension-messages.ts +1 -0
  41. package/src/monitor.ts +5 -5
  42. package/src/profiles.ts +1 -8
  43. package/src/remote/shepherdr-session.mjs +43 -0
  44. package/src/settlement/delivery.ts +32 -14
  45. package/src/settlement/index.ts +3 -0
  46. package/src/shared-context.ts +4 -100
  47. package/src/spawn-ancestry.ts +103 -0
  48. package/src/spawn-ownership.ts +93 -5
  49. package/src/types.ts +1 -0
  50. package/src/worker-ownership.ts +41 -32
  51. package/src/worker-resume.ts +231 -0
  52. package/src/worker-role.ts +9 -35
  53. package/src/worker-service.ts +95 -59
  54. package/worker-api.ts +38 -0
  55. package/src/profile-prompt.ts +0 -32
@@ -9,12 +9,11 @@ import type {
9
9
  SharedContextResult,
10
10
  } from "@howaboua/pi-agent-comms/context-sharing";
11
11
  import type { CodexAgentRelationshipService } from "@howaboua/pi-codex-conversion/agent-relationship";
12
- import { Check } from "typebox/value";
13
12
  import { AgentAttachment } from "./attachment.js";
14
13
  import {
15
14
  attachmentRoutes,
16
15
  canonicalContextIdentity,
17
- Identity,
16
+ checkIdentity,
18
17
  } from "./attachment-protocol.js";
19
18
  import type { AgentBoard } from "./board/host.js";
20
19
  import { children, isBoardEnvelope } from "./board/records.js";
@@ -23,7 +22,6 @@ import {
23
22
  countContextTargets,
24
23
  sendContextRoute,
25
24
  } from "./context-routing.js";
26
- import { sessionPath } from "./core/agents.js";
27
25
  import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
28
26
  import {
29
27
  describePeerSharing,
@@ -34,6 +32,7 @@ import {
34
32
  requestContext,
35
33
  sessionContextPath,
36
34
  } from "./remote/shepherdr-context.mjs";
35
+ import { resolveAncestryRoot } from "./spawn-ancestry.js";
37
36
  import { MEMBER_ENTRY, type Member, SpawnContext } from "./spawn-context.js";
38
37
  import type { PaneInfo } from "./types.js";
39
38
 
@@ -148,58 +147,6 @@ export class SharedAgentContext {
148
147
  value.operation === "peer-sharing"
149
148
  )
150
149
  return describePeerSharing(ctx, this.getService(), this.board);
151
- if (
152
- value &&
153
- typeof value === "object" &&
154
- "operation" in value &&
155
- value.operation === "agent-root"
156
- ) {
157
- const own = this.board.binding(ctx);
158
- const identity = this.getService()?.describe(ctx);
159
- if (
160
- !("scope" in value) ||
161
- (value.scope !== "board" && value.scope !== "context")
162
- )
163
- throw new Error("Invalid /root family");
164
- const family =
165
- value.scope === "board" ? own.rootSessionId : identity?.sessionId;
166
- if (
167
- !("family" in value) ||
168
- value.family !== family ||
169
- !("visited" in value) ||
170
- !Array.isArray(value.visited) ||
171
- value.visited.some((item) => typeof item !== "string") ||
172
- value.visited.length >= 64 ||
173
- value.visited.includes(ctx.sessionManager.getSessionId())
174
- )
175
- throw new Error("No live /root in this agent family");
176
- const routing = identity?.routing as Partial<Routing> | undefined;
177
- const upstream =
178
- value.scope === "board"
179
- ? own.upstream
180
- : identity?.threadId !== identity?.sessionId &&
181
- routing?.transport === "shepherdr"
182
- ? routing.parent
183
- : undefined;
184
- if (upstream)
185
- return requestContext(
186
- upstream,
187
- {
188
- ...value,
189
- visited: [...value.visited, ctx.sessionManager.getSessionId()],
190
- },
191
- signal,
192
- );
193
- if (
194
- (value.scope === "board" ? own.sessionId : identity?.threadId) !==
195
- family
196
- )
197
- throw new Error("No live /root in this agent family");
198
- return {
199
- ...(await this.fleet.connected().client.machineIdentity()),
200
- sessionFile: ctx.sessionManager.getSessionFile(),
201
- };
202
- }
203
150
  if (isBoardEnvelope(value)) return this.board.handle(ctx, value, signal);
204
151
  if (!value || typeof value !== "object")
205
152
  throw new Error("Invalid shared context request");
@@ -221,7 +168,7 @@ export class SharedAgentContext {
221
168
  if (
222
169
  !file ||
223
170
  !("identity" in value) ||
224
- !Check(Identity, value.identity) ||
171
+ !checkIdentity(value.identity) ||
225
172
  !isDeepStrictEqual(
226
173
  identity,
227
174
  canonicalContextIdentity(value.identity),
@@ -401,49 +348,6 @@ export class SharedAgentContext {
401
348
  machine?: string,
402
349
  signal?: AbortSignal,
403
350
  ) {
404
- const own = this.board.binding(ctx);
405
- const identity = this.getService()?.describe(ctx);
406
- const scope = own.upstream || !identity ? "board" : "context";
407
- const family = scope === "board" ? own.rootSessionId : identity?.sessionId;
408
- let result: unknown;
409
- try {
410
- result = await this.handle(
411
- ctx,
412
- { operation: "agent-root", scope, family, visited: [] },
413
- signal,
414
- );
415
- } catch (error) {
416
- signal?.throwIfAborted();
417
- throw new Error(
418
- "No live /root in this agent family; use find for an exact target",
419
- { cause: error },
420
- );
421
- }
422
- if (
423
- !result ||
424
- typeof result !== "object" ||
425
- !("host" in result) ||
426
- !("session" in result) ||
427
- !("sessionFile" in result) ||
428
- typeof result.sessionFile !== "string"
429
- )
430
- throw new Error("No live /root in this agent family");
431
- const matches = [];
432
- for (const entry of await this.fleet.snapshots(machine)) {
433
- if (!entry.snapshot) continue;
434
- const runtime = this.fleet.connected(entry.id);
435
- const identity = await runtime.client.machineIdentity();
436
- if (identity.host !== result.host || identity.session !== result.session)
437
- continue;
438
- for (const agent of entry.snapshot.agents) {
439
- if (agent.agent === "pi" && sessionPath(agent) === result.sessionFile)
440
- matches.push({ runtime, target: agent.pane_id });
441
- }
442
- }
443
- if (matches.length !== 1)
444
- throw new Error(
445
- "No unique live /root in this agent family; use find for an exact target",
446
- );
447
- return matches[0]!;
351
+ return resolveAncestryRoot(ctx, this.fleet, machine, signal);
448
352
  }
449
353
  }
@@ -0,0 +1,103 @@
1
+ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import { nativeAgentName } from "./agent-identity.js";
3
+ import {
4
+ type NativeSessionIdentity,
5
+ type SpawnAncestry,
6
+ savedSpawnAncestry,
7
+ } from "./ancestry-record.js";
8
+ import { sessionPath } from "./core/agents.js";
9
+ import type { AgentFleet } from "./fleet/index.js";
10
+ import { markedWorker } from "./worker-role.js";
11
+
12
+ export type { SpawnAncestry } from "./ancestry-record.js";
13
+
14
+ function rootIdentity(
15
+ ctx: ExtensionContext,
16
+ fleet: AgentFleet,
17
+ ): NativeSessionIdentity {
18
+ const ancestry = savedSpawnAncestry(ctx);
19
+ if (ancestry) return ancestry.root;
20
+ // Older workers have no machine-qualified root. Optional sharing is not proof.
21
+ const legacyParent = ctx.sessionManager.getEntries().some((entry) => {
22
+ if (
23
+ entry.type !== "custom" ||
24
+ entry.customType !== "codex-agent-relationship"
25
+ )
26
+ return false;
27
+ const value = entry.data;
28
+ return (
29
+ !!value &&
30
+ typeof value === "object" &&
31
+ "threadId" in value &&
32
+ value.threadId === ctx.sessionManager.getSessionId() &&
33
+ "parentThreadId" in value &&
34
+ typeof value.parentThreadId === "string" &&
35
+ !!value.parentThreadId
36
+ );
37
+ });
38
+ if (markedWorker(ctx.sessionManager) || legacyParent)
39
+ throw new Error(
40
+ "This worker has no saved ancestry; use an exact agent target or resume it from its parent",
41
+ );
42
+ const sessionFile = ctx.sessionManager.getSessionFile();
43
+ if (!sessionFile) throw new Error("Ancestry requires a saved Pi session");
44
+ return {
45
+ machine: fleet.localMachine(),
46
+ sessionId: ctx.sessionManager.getSessionId(),
47
+ sessionFile,
48
+ };
49
+ }
50
+
51
+ /** Prepare before launch; the child persists this only after optional bindings. */
52
+ export async function prepareLaunchAncestry(
53
+ ctx: ExtensionContext,
54
+ fleet: AgentFleet,
55
+ signal?: AbortSignal,
56
+ ): Promise<SpawnAncestry> {
57
+ signal?.throwIfAborted();
58
+ const sessionFile = ctx.sessionManager.getSessionFile();
59
+ if (!sessionFile)
60
+ throw new Error("Spawning requires a saved parent Pi session");
61
+ return {
62
+ parent: {
63
+ machine: fleet.localMachine(),
64
+ sessionId: ctx.sessionManager.getSessionId(),
65
+ sessionFile,
66
+ },
67
+ root: rootIdentity(ctx, fleet),
68
+ };
69
+ }
70
+
71
+ export async function resolveAncestryRoot(
72
+ ctx: ExtensionContext,
73
+ fleet: AgentFleet,
74
+ machine?: string,
75
+ signal?: AbortSignal,
76
+ ) {
77
+ const root = rootIdentity(ctx, fleet);
78
+ const matches = [];
79
+ for (const entry of await fleet.snapshots(machine ?? root.machine)) {
80
+ if (!entry.snapshot) continue;
81
+ const runtime = fleet.connected(entry.id);
82
+ const identity = await runtime.client.machineIdentity();
83
+ if (identity.session !== root.machine) continue;
84
+ for (const panel of entry.snapshot.agents) {
85
+ if (panel.agent !== "pi" || sessionPath(panel) !== root.sessionFile)
86
+ continue;
87
+ try {
88
+ if (
89
+ (await nativeAgentName(runtime.client, panel, signal)) ===
90
+ `/${root.sessionId}`
91
+ )
92
+ matches.push({ runtime, target: panel.pane_id });
93
+ } catch {
94
+ signal?.throwIfAborted();
95
+ }
96
+ }
97
+ }
98
+ if (matches.length !== 1)
99
+ throw new Error(
100
+ "No unique live /root in this spawn ancestry; use find for an exact target",
101
+ );
102
+ return matches[0]!;
103
+ }
@@ -2,12 +2,40 @@ import type {
2
2
  ExtensionAPI,
3
3
  ExtensionContext,
4
4
  } from "@earendil-works/pi-coding-agent";
5
+ import {
6
+ arr,
7
+ compile,
8
+ lit,
9
+ obj,
10
+ opt,
11
+ type Static,
12
+ str,
13
+ } from "@earendil-works/pi-schema";
5
14
  import { sessionPath } from "./core/agents.js";
6
15
  import type { ConnectedMachine } from "./fleet/index.js";
16
+ import type { StartAgentParams } from "./launch-contract.js";
7
17
  import type { PaneInfo } from "./types.js";
8
18
 
9
19
  const ENTRY = "herdr-spawn-ownership-v1";
10
-
20
+ const SavedLaunch = obj(
21
+ {
22
+ args: arr(str()),
23
+ params: obj(
24
+ {
25
+ name: str(),
26
+ cwd: str(),
27
+ label: opt(str()),
28
+ placement: {
29
+ ...lit("terminal"),
30
+ type: "string",
31
+ },
32
+ },
33
+ { open: true },
34
+ ),
35
+ },
36
+ { open: true },
37
+ );
38
+ const checkSavedLaunch = compile(SavedLaunch).check;
11
39
  export interface SpawnOwnership {
12
40
  parent: string;
13
41
  machine: string;
@@ -16,6 +44,9 @@ export interface SpawnOwnership {
16
44
  pane: string;
17
45
  terminal: string;
18
46
  sessionFile: string;
47
+ agent?: string;
48
+ launch?: Static<typeof SavedLaunch>;
49
+ aliases?: string[];
19
50
  }
20
51
 
21
52
  export function spawnedChildren(ctx: ExtensionContext): SpawnOwnership[] {
@@ -43,8 +74,23 @@ export function spawnedChildren(ctx: ExtensionContext): SpawnOwnership[] {
43
74
  pane: value.pane,
44
75
  terminal: value.terminal,
45
76
  sessionFile: value.sessionFile,
77
+ ...("agent" in value && typeof value.agent === "string"
78
+ ? { agent: value.agent }
79
+ : {}),
80
+ ...("aliases" in value &&
81
+ Array.isArray(value.aliases) &&
82
+ value.aliases.every((alias) => typeof alias === "string")
83
+ ? { aliases: value.aliases }
84
+ : {}),
46
85
  };
47
- children.set(JSON.stringify([child.machine, child.pane]), child);
86
+ if ("launch" in value) {
87
+ if (!checkSavedLaunch(value.launch))
88
+ throw new Error(
89
+ "Saved worker launch settings are invalid; open its saved session manually",
90
+ );
91
+ child.launch = value.launch;
92
+ }
93
+ children.set(JSON.stringify([child.session, child.sessionFile]), child);
48
94
  }
49
95
  return [...children.values()];
50
96
  }
@@ -54,10 +100,15 @@ export function prepareSpawnOwnership(
54
100
  pi: ExtensionAPI,
55
101
  ctx: ExtensionContext,
56
102
  runtime: ConnectedMachine,
57
- ): (panel: PaneInfo, args: readonly string[]) => Promise<void> {
103
+ ): (
104
+ panel: PaneInfo,
105
+ args: readonly string[],
106
+ agent?: string,
107
+ params?: StartAgentParams,
108
+ ) => Promise<void> {
58
109
  const parent = ctx.sessionManager.getSessionFile();
59
110
  const anchor = ctx.sessionManager.getLeafId();
60
- return async (panel, args) => {
111
+ return async (panel, args, agent, params) => {
61
112
  // Launching a resumed identity does not make that session our child.
62
113
  if (
63
114
  args.some((arg) =>
@@ -81,11 +132,48 @@ export function prepareSpawnOwnership(
81
132
  );
82
133
  pi.appendEntry(ENTRY, {
83
134
  parent,
84
- machine: runtime.machine,
135
+ machine: identity.session,
85
136
  ...identity,
86
137
  pane: panel.pane_id,
87
138
  terminal: panel.terminal_id,
88
139
  sessionFile: file,
140
+ ...(agent ? { agent } : {}),
141
+ ...(params?.name && panel.cwd
142
+ ? {
143
+ launch: {
144
+ args: [...args],
145
+ params: {
146
+ name: params.name,
147
+ ...(params.label ? { label: params.label } : {}),
148
+ cwd: panel.cwd,
149
+ placement: "terminal",
150
+ },
151
+ },
152
+ }
153
+ : {}),
89
154
  } satisfies SpawnOwnership);
90
155
  };
91
156
  }
157
+
158
+ export function recordResumedChild(
159
+ pi: ExtensionAPI,
160
+ child: SpawnOwnership,
161
+ panel: PaneInfo,
162
+ agent: string,
163
+ ): void {
164
+ pi.appendEntry(ENTRY, {
165
+ ...child,
166
+ machine: child.session,
167
+ agent,
168
+ pane: panel.pane_id,
169
+ terminal: panel.terminal_id,
170
+ aliases: [
171
+ ...new Set([
172
+ ...(child.aliases ?? []),
173
+ child.pane,
174
+ child.terminal,
175
+ ...(panel.name ? [panel.name] : []),
176
+ ]),
177
+ ],
178
+ } satisfies SpawnOwnership);
179
+ }
package/src/types.ts CHANGED
@@ -25,6 +25,7 @@ interface MachineIdentity {
25
25
 
26
26
  export interface FocusRequest {
27
27
  source: MachineIdentity & {
28
+ agent?: string;
28
29
  backend?: "core";
29
30
  pane?: string;
30
31
  terminal: string;
@@ -1,47 +1,56 @@
1
1
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import {
3
+ compile,
4
+ lit,
5
+ obj,
6
+ type Static,
7
+ str,
8
+ union,
9
+ } from "@earendil-works/pi-schema";
2
10
  import { getSnapshot, sessionPath } from "./core/agents.js";
3
11
  import type { AgentFleet } from "./fleet/index.js";
4
12
  import type { PaneInfo } from "./types.js";
5
13
 
6
- export const ENTRY = "herdr-owned-worker-v1";
7
-
8
- export interface OwnedWorker {
9
- workerId: string;
10
- pulseId: string;
11
- runId: string;
12
- parent: string;
13
- host: string;
14
- session: string;
15
- target: string;
16
- terminal: string;
17
- sessionPath: string;
18
- cwd: string;
19
- }
14
+ export const ENTRY = "herdr-owned-worker-v2";
15
+ const Ownership = obj(
16
+ {
17
+ workerId: str(),
18
+ scope: str(),
19
+ key: str(),
20
+ requestId: str(),
21
+ lifetime: union([
22
+ {
23
+ ...lit("parent"),
24
+ type: "string",
25
+ },
26
+ {
27
+ ...lit("detached"),
28
+ type: "string",
29
+ },
30
+ ]),
31
+ parent: str(),
32
+ host: str(),
33
+ session: str(),
34
+ target: str(),
35
+ terminal: str(),
36
+ sessionPath: str(),
37
+ cwd: str(),
38
+ },
39
+ { open: true },
40
+ );
41
+ const checkOwnership = compile(Ownership).check;
42
+ export type OwnedWorker = Static<typeof Ownership>;
20
43
 
21
44
  export function records(ctx: ExtensionContext): OwnedWorker[] {
22
45
  const workers = new Map<string, OwnedWorker>();
23
46
  for (const entry of ctx.sessionManager.getBranch()) {
24
47
  if (entry.type !== "custom" || entry.customType !== ENTRY) continue;
25
- const value = entry.data as Record<string, unknown> | undefined;
26
- if (
27
- !value ||
28
- ![
29
- "workerId",
30
- "pulseId",
31
- "runId",
32
- "parent",
33
- "host",
34
- "session",
35
- "target",
36
- "terminal",
37
- "sessionPath",
38
- "cwd",
39
- ].every((key) => typeof value[key] === "string")
40
- )
48
+ const value: unknown = entry.data;
49
+ if (!checkOwnership(value))
41
50
  throw new Error(
42
- "Saved pulse worker ownership is invalid; inspect the session before retrying",
51
+ "Saved worker ownership is invalid; inspect the session before retrying",
43
52
  );
44
- const worker = value as unknown as OwnedWorker;
53
+ const worker = value;
45
54
  if (worker.parent === ctx.sessionManager.getSessionFile())
46
55
  workers.set(worker.workerId, worker);
47
56
  }