@howaboua/pi-shepherdr 0.2.23 → 0.2.25

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 (96) hide show
  1. package/CHANGELOG.md +20 -18
  2. package/README.md +80 -69
  3. package/biome.json +1 -1
  4. package/index.ts +4 -2
  5. package/package.json +14 -9
  6. package/src/agents-contract.ts +9 -6
  7. package/src/agents-discovery.ts +78 -37
  8. package/src/agents-focus.ts +17 -11
  9. package/src/agents-reply.ts +1 -1
  10. package/src/agents-spawn.ts +24 -8
  11. package/src/agents-tool.ts +26 -8
  12. package/src/agents-work.ts +5 -5
  13. package/src/attachment-notes.ts +14 -2
  14. package/src/attachment-protocol.ts +21 -4
  15. package/src/attachment-routing.ts +1 -1
  16. package/src/attachment-target.ts +5 -2
  17. package/src/attachment.ts +4 -3
  18. package/src/board/host.ts +5 -3
  19. package/src/board/membership.ts +1 -1
  20. package/src/close-idle.ts +89 -0
  21. package/src/{control-panel-actions.ts → control-panel/actions.ts} +2 -2
  22. package/src/{control-panel.ts → control-panel/index.ts} +7 -5
  23. package/src/{control-panel-items.ts → control-panel/items.ts} +17 -5
  24. package/src/{control-panel-view.ts → control-panel/view.ts} +9 -5
  25. package/src/controller.ts +17 -5
  26. package/src/core/AGENTS.md +5 -0
  27. package/src/core/backend.ts +266 -0
  28. package/src/core/client.ts +249 -0
  29. package/src/core/context-relay.mjs +111 -0
  30. package/src/core/focus-channel-helper.mjs +165 -0
  31. package/src/core/focus-channel-stream.ts +140 -0
  32. package/src/core/focus-channel-wire.mjs +160 -0
  33. package/src/core/focus-channel.ts +213 -0
  34. package/src/core/focus-window.ts +192 -0
  35. package/src/core/pi-executable.mjs +34 -0
  36. package/src/core/protocol.ts +116 -0
  37. package/src/core/registration.ts +51 -0
  38. package/src/core/remote-endpoint.ts +119 -0
  39. package/src/core/remote-exec.ts +122 -0
  40. package/src/core/remote-helper.mjs +244 -0
  41. package/src/core/remote-reader.ts +67 -0
  42. package/src/core/remote-relay.ts +191 -0
  43. package/src/core/request.ts +124 -0
  44. package/src/core/spawn.ts +177 -0
  45. package/src/core/status.ts +68 -0
  46. package/src/core/terminal.ts +103 -0
  47. package/src/fleet/catalog.ts +83 -0
  48. package/src/fleet/connection.ts +111 -0
  49. package/src/fleet/index.ts +413 -0
  50. package/src/fleet/inspection.ts +159 -0
  51. package/src/fleet/machine.ts +55 -0
  52. package/src/fleet/monitor.ts +85 -0
  53. package/src/fleet/persistence.ts +65 -0
  54. package/src/fleet/reconnect.ts +75 -0
  55. package/src/fleet/setup.ts +133 -0
  56. package/src/herdr.ts +25 -5
  57. package/src/launch-contract.ts +48 -0
  58. package/src/launch-location.ts +151 -0
  59. package/src/launch.ts +30 -183
  60. package/src/messages/attachments.ts +39 -0
  61. package/src/messages/attribution.ts +84 -0
  62. package/src/messages/event-details.ts +69 -0
  63. package/src/messages/events.ts +195 -0
  64. package/src/messages/focus.ts +47 -0
  65. package/src/messages/guidance.ts +83 -0
  66. package/src/messages/render.ts +89 -0
  67. package/src/messages/voice-announcements.ts +79 -0
  68. package/src/monitor-record.ts +9 -6
  69. package/src/monitor.ts +33 -2
  70. package/src/peer-commands.ts +11 -0
  71. package/src/peer-inbox-delivery.ts +171 -0
  72. package/src/peer-inbox-focus.ts +113 -0
  73. package/src/peer-inbox.ts +127 -209
  74. package/src/remote/client.ts +127 -0
  75. package/src/remote/context-relay.ts +84 -0
  76. package/src/remote/deployment.ts +179 -0
  77. package/src/remote/focus-channels.ts +89 -0
  78. package/src/remote/shepherdr-context.mjs +1 -1
  79. package/src/remote/shepherdr-peer.mjs +18 -5
  80. package/src/remote/shepherdr-session.mjs +9 -2
  81. package/src/remote/shepherdr.mjs +1 -1
  82. package/src/remote/transport.ts +369 -0
  83. package/src/settlement/collector.ts +122 -0
  84. package/src/settlement/delivery.ts +144 -0
  85. package/src/{settlement.ts → settlement/index.ts} +35 -233
  86. package/src/shared-context-host.ts +40 -14
  87. package/src/shared-context.ts +44 -6
  88. package/src/spawn-context.ts +24 -17
  89. package/src/spawn-ownership.ts +91 -0
  90. package/src/types.ts +9 -5
  91. package/src/voice-handoff.ts +1 -1
  92. package/src/worker-ownership.ts +92 -0
  93. package/src/worker-service.ts +14 -83
  94. package/src/fleet.ts +0 -702
  95. package/src/messages.ts +0 -637
  96. package/src/remote-client.ts +0 -761
@@ -0,0 +1,91 @@
1
+ import type {
2
+ ExtensionAPI,
3
+ ExtensionContext,
4
+ } from "@earendil-works/pi-coding-agent";
5
+ import type { ConnectedMachine } from "./fleet/index.js";
6
+ import { sessionPath } from "./herdr.js";
7
+ import type { PaneInfo } from "./types.js";
8
+
9
+ const ENTRY = "herdr-spawn-ownership-v1";
10
+
11
+ export interface SpawnOwnership {
12
+ parent: string;
13
+ machine: string;
14
+ host: string;
15
+ session: string;
16
+ pane: string;
17
+ terminal: string;
18
+ sessionFile: string;
19
+ }
20
+
21
+ export function spawnedChildren(ctx: ExtensionContext): SpawnOwnership[] {
22
+ const children = new Map<string, SpawnOwnership>();
23
+ for (const entry of ctx.sessionManager.getBranch()) {
24
+ if (entry.type !== "custom" || entry.customType !== ENTRY) continue;
25
+ const value: unknown = entry.data;
26
+ if (!value || typeof value !== "object") continue;
27
+ if (
28
+ !("parent" in value && typeof value.parent === "string") ||
29
+ !("machine" in value && typeof value.machine === "string") ||
30
+ !("host" in value && typeof value.host === "string") ||
31
+ !("session" in value && typeof value.session === "string") ||
32
+ !("pane" in value && typeof value.pane === "string") ||
33
+ !("terminal" in value && typeof value.terminal === "string") ||
34
+ !("sessionFile" in value && typeof value.sessionFile === "string") ||
35
+ value.parent !== ctx.sessionManager.getSessionFile()
36
+ )
37
+ continue;
38
+ const child: SpawnOwnership = {
39
+ parent: value.parent,
40
+ machine: value.machine,
41
+ host: value.host,
42
+ session: value.session,
43
+ pane: value.pane,
44
+ terminal: value.terminal,
45
+ sessionFile: value.sessionFile,
46
+ };
47
+ children.set(JSON.stringify([child.machine, child.pane]), child);
48
+ }
49
+ return [...children.values()];
50
+ }
51
+
52
+ // Capture before launch. A context switch must never adopt a completed spawn.
53
+ export function prepareSpawnOwnership(
54
+ pi: ExtensionAPI,
55
+ ctx: ExtensionContext,
56
+ runtime: ConnectedMachine,
57
+ ): (panel: PaneInfo, args: readonly string[]) => Promise<void> {
58
+ const parent = ctx.sessionManager.getSessionFile();
59
+ const anchor = ctx.sessionManager.getLeafId();
60
+ return async (panel, args) => {
61
+ // Launching a resumed identity does not make that session our child.
62
+ if (
63
+ args.some((arg) =>
64
+ /^(?:--(?:session(?:-id)?|continue|resume|no-session|fork)(?:=|$)|-[cr]$)/.test(
65
+ arg,
66
+ ),
67
+ )
68
+ )
69
+ return;
70
+ const identity = await runtime.client.machineIdentity();
71
+ const file = sessionPath(panel);
72
+ if (
73
+ !parent ||
74
+ !file ||
75
+ parent !== ctx.sessionManager.getSessionFile() ||
76
+ (anchor &&
77
+ !ctx.sessionManager.getBranch().some((entry) => entry.id === anchor))
78
+ )
79
+ throw new Error(
80
+ "Parent context changed during spawn; retry from the intended session",
81
+ );
82
+ pi.appendEntry(ENTRY, {
83
+ parent,
84
+ machine: runtime.machine,
85
+ ...identity,
86
+ pane: panel.pane_id,
87
+ terminal: panel.terminal_id,
88
+ sessionFile: file,
89
+ } satisfies SpawnOwnership);
90
+ };
91
+ }
package/src/types.ts CHANGED
@@ -4,6 +4,7 @@ export interface PeerMessage {
4
4
  text: string;
5
5
  sender: string;
6
6
  context?: string;
7
+ closeIfIdle?: true;
7
8
  }
8
9
 
9
10
  export interface PeerDelivery {
@@ -24,7 +25,8 @@ export interface MachineIdentity {
24
25
 
25
26
  export interface FocusRequest {
26
27
  source: MachineIdentity & {
27
- pane: string;
28
+ backend?: "core";
29
+ pane?: string;
28
30
  terminal: string;
29
31
  sessionFile: string;
30
32
  };
@@ -69,6 +71,7 @@ interface AgentSessionInfo {
69
71
  }
70
72
 
71
73
  export interface PaneInfo {
74
+ backend?: "core";
72
75
  agent?: string | null;
73
76
  agent_session?: AgentSessionInfo | null;
74
77
  agent_status: AgentStatus;
@@ -80,9 +83,9 @@ export interface PaneInfo {
80
83
  name?: string | null;
81
84
  pane_id: string;
82
85
  title?: string | null;
83
- tab_id: string;
86
+ tab_id?: string;
84
87
  terminal_id: string;
85
- workspace_id: string;
88
+ workspace_id?: string;
86
89
  }
87
90
 
88
91
  interface TabInfo {
@@ -112,9 +115,9 @@ export interface MonitoredAgent {
112
115
  readonly notifiedExtensionMessages?: string[];
113
116
  readonly name?: string;
114
117
  readonly paneId: string;
115
- readonly tabId: string;
118
+ readonly tabId?: string;
116
119
  readonly terminalId: string;
117
- readonly workspaceId: string;
120
+ readonly workspaceId?: string;
118
121
  }
119
122
 
120
123
  type MachineConnectionStatus = "connected" | "connecting" | "unavailable";
@@ -167,6 +170,7 @@ export interface ExtensionReply {
167
170
  export interface SessionView {
168
171
  extensionMessages?: ExtensionMessage[];
169
172
  assistant?: LatestAssistant;
173
+ assistantPending?: boolean;
170
174
  assistantAfterInput?: boolean;
171
175
  input?: LatestInput;
172
176
  }
@@ -4,7 +4,7 @@ import type {
4
4
  ExtensionContext,
5
5
  } from "@earendil-works/pi-coding-agent";
6
6
  import { recordContextBriefing } from "@howaboua/pi-agent-board/integration";
7
- import { voiceFocusContinuity, voiceFocusReport } from "./messages.js";
7
+ import { voiceFocusContinuity, voiceFocusReport } from "./messages/focus.js";
8
8
  import { registerFocusChannelReceiver } from "./peer-channel.js";
9
9
  import type { FocusRequest, PaneInfo, PeerChannel } from "./types.js";
10
10
 
@@ -0,0 +1,92 @@
1
+ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import { CoreConnection } from "./core/backend.js";
3
+ import type { AgentFleet } from "./fleet/index.js";
4
+ import { getSnapshot, sessionPath } from "./herdr.js";
5
+ import type { PaneInfo } from "./types.js";
6
+
7
+ export const ENTRY = "herdr-owned-worker-v1";
8
+
9
+ export interface OwnedWorker {
10
+ workerId: string;
11
+ pulseId: string;
12
+ runId: string;
13
+ parent: string;
14
+ host: string;
15
+ session: string;
16
+ target: string;
17
+ terminal: string;
18
+ sessionPath: string;
19
+ cwd: string;
20
+ }
21
+
22
+ export function records(ctx: ExtensionContext): OwnedWorker[] {
23
+ const workers = new Map<string, OwnedWorker>();
24
+ for (const entry of ctx.sessionManager.getBranch()) {
25
+ if (entry.type !== "custom" || entry.customType !== ENTRY) continue;
26
+ const value = entry.data as Record<string, unknown> | undefined;
27
+ if (
28
+ !value ||
29
+ ![
30
+ "workerId",
31
+ "pulseId",
32
+ "runId",
33
+ "parent",
34
+ "host",
35
+ "session",
36
+ "target",
37
+ "terminal",
38
+ "sessionPath",
39
+ "cwd",
40
+ ].every((key) => typeof value[key] === "string")
41
+ )
42
+ throw new Error(
43
+ "Saved pulse worker ownership is invalid; inspect the session before retrying",
44
+ );
45
+ const worker = value as unknown as OwnedWorker;
46
+ if (worker.parent === ctx.sessionManager.getSessionFile())
47
+ workers.set(worker.workerId, worker);
48
+ }
49
+ return [...workers.values()];
50
+ }
51
+
52
+ export async function panelFor(
53
+ fleet: AgentFleet,
54
+ worker: OwnedWorker,
55
+ ): Promise<PaneInfo | undefined> {
56
+ const snapshot = await getSnapshot(fleet.connected().client);
57
+ if (
58
+ snapshot.agents.some(
59
+ (value) =>
60
+ value.pane_id !== worker.target &&
61
+ sessionPath(value) === worker.sessionPath,
62
+ )
63
+ )
64
+ throw new Error(
65
+ "Worker session is open in another pane; refusing to control it",
66
+ );
67
+ const panel = snapshot.agents.find(
68
+ (value) => value.pane_id === worker.target,
69
+ );
70
+ if (panel) {
71
+ if (
72
+ panel.pane_id ===
73
+ process.env[
74
+ fleet.connected().client instanceof CoreConnection
75
+ ? "HC_TERMINAL_ID"
76
+ : "HERDR_PANE_ID"
77
+ ] ||
78
+ panel.terminal_id !== worker.terminal ||
79
+ panel.agent !== "pi" ||
80
+ sessionPath(panel) !== worker.sessionPath
81
+ )
82
+ throw new Error("Worker pane identity changed; refusing to control it");
83
+ return panel;
84
+ }
85
+ if (
86
+ snapshot.agents.some((value) => sessionPath(value) === worker.sessionPath)
87
+ )
88
+ throw new Error(
89
+ "Worker session is open in another pane; refusing to control it",
90
+ );
91
+ return undefined;
92
+ }
@@ -6,21 +6,21 @@ import type {
6
6
  import { activityTask } from "./activity.js";
7
7
  import { dispatchAgentWork, reserveAgentName } from "./agents-work.js";
8
8
  import type { AgentBoard } from "./board/host.js";
9
- import type { AgentFleet } from "./fleet.js";
10
- import { getSnapshot, sessionPath } from "./herdr.js";
9
+ import { CoreConnection } from "./core/backend.js";
10
+ import type { AgentFleet } from "./fleet/index.js";
11
+ import { sessionPath } from "./herdr.js";
11
12
  import {
12
13
  RolledBackAgentLaunchError,
13
14
  rollbackStartedAgent,
14
15
  startAgent,
15
16
  UnstartedAgentLaunchError,
16
17
  } from "./launch.js";
17
- import { attributeAgentPrompt } from "./messages.js";
18
+ import { attributeAgentPrompt } from "./messages/attribution.js";
18
19
  import { loadAgentProfiles, profileAgentArgs } from "./profiles.js";
19
20
  import type { SharedAgentContext } from "./shared-context.js";
20
- import type { PaneInfo } from "./types.js";
21
+ import { ENTRY, panelFor, records } from "./worker-ownership.js";
21
22
  import { PULSE_WORKER_FLAG, type registerWorkerRole } from "./worker-role.js";
22
23
 
23
- const ENTRY = "herdr-owned-worker-v1";
24
24
  const RUNNER_PROTOCOL = "@howaboua/pi-pulses/runner/v1";
25
25
  // Structural implementation of Pulses' optional runner ABI, without a private-package dependency.
26
26
  interface PulseRun {
@@ -35,48 +35,6 @@ interface PulseWorker {
35
35
  workerId: string;
36
36
  state: "working" | "idle" | "closed";
37
37
  }
38
- interface OwnedWorker {
39
- workerId: string;
40
- pulseId: string;
41
- runId: string;
42
- parent: string;
43
- host: string;
44
- session: string;
45
- target: string;
46
- terminal: string;
47
- sessionPath: string;
48
- cwd: string;
49
- }
50
-
51
- function records(ctx: ExtensionContext): OwnedWorker[] {
52
- const workers = new Map<string, OwnedWorker>();
53
- for (const entry of ctx.sessionManager.getBranch()) {
54
- if (entry.type !== "custom" || entry.customType !== ENTRY) continue;
55
- const value = entry.data as Record<string, unknown> | undefined;
56
- if (
57
- !value ||
58
- ![
59
- "workerId",
60
- "pulseId",
61
- "runId",
62
- "parent",
63
- "host",
64
- "session",
65
- "target",
66
- "terminal",
67
- "sessionPath",
68
- "cwd",
69
- ].every((key) => typeof value[key] === "string")
70
- )
71
- throw new Error(
72
- "Saved pulse worker ownership is invalid; inspect the session before retrying",
73
- );
74
- const worker = value as unknown as OwnedWorker;
75
- if (worker.parent === ctx.sessionManager.getSessionFile())
76
- workers.set(worker.workerId, worker);
77
- }
78
- return [...workers.values()];
79
- }
80
38
 
81
39
  export function registerWorkerService(
82
40
  pi: ExtensionAPI,
@@ -111,45 +69,13 @@ export function registerWorkerService(
111
69
  throw new Error("Worker belongs to another host or Herdr session");
112
70
  return worker;
113
71
  }
114
- async function panelFor(worker: OwnedWorker): Promise<PaneInfo | undefined> {
115
- const snapshot = await getSnapshot(fleet.connected().client);
116
- if (
117
- snapshot.agents.some(
118
- (value) =>
119
- value.pane_id !== worker.target &&
120
- sessionPath(value) === worker.sessionPath,
121
- )
122
- )
123
- throw new Error(
124
- "Worker session is open in another pane; refusing to control it",
125
- );
126
- const panel = snapshot.agents.find(
127
- (value) => value.pane_id === worker.target,
128
- );
129
- if (panel) {
130
- if (
131
- panel.pane_id === process.env["HERDR_PANE_ID"] ||
132
- panel.terminal_id !== worker.terminal ||
133
- panel.agent !== "pi" ||
134
- sessionPath(panel) !== worker.sessionPath
135
- )
136
- throw new Error("Worker pane identity changed; refusing to control it");
137
- return panel;
138
- }
139
- if (
140
- snapshot.agents.some((value) => sessionPath(value) === worker.sessionPath)
141
- )
142
- throw new Error(
143
- "Worker session is open in another pane; refusing to control it",
144
- );
145
- return undefined;
146
- }
72
+
147
73
  async function inspect(
148
74
  ctx: ExtensionContext,
149
75
  workerId: string,
150
76
  ): Promise<PulseWorker> {
151
77
  const worker = await owned(ctx, workerId);
152
- const panel = await panelFor(worker);
78
+ const panel = await panelFor(fleet, worker);
153
79
  const record = fleet
154
80
  .connected()
155
81
  .monitor.list()
@@ -221,7 +147,7 @@ export function registerWorkerService(
221
147
  if (input.workerId && input.workerId !== worker?.workerId)
222
148
  throw new Error("Worker is not owned by this pulse in this branch");
223
149
  if (worker) await owned(ctx, worker.workerId);
224
- let panel = worker ? await panelFor(worker) : undefined;
150
+ let panel = worker ? await panelFor(fleet, worker) : undefined;
225
151
  if (worker?.runId === input.runId) {
226
152
  stage = "dispatch";
227
153
  return await inspect(ctx, worker.workerId);
@@ -280,7 +206,12 @@ export function registerWorkerService(
280
206
  name,
281
207
  label: input.title,
282
208
  cwd: input.cwd,
283
- placement: workspace ? "new_tab" : "new_workspace",
209
+ placement:
210
+ runtime.client instanceof CoreConnection
211
+ ? "terminal"
212
+ : workspace
213
+ ? "new_tab"
214
+ : "new_workspace",
284
215
  ...(workspace ? { workspace } : {}),
285
216
  },
286
217
  runtime.fallbackCwd,