@howaboua/pi-shepherdr 0.2.24 → 0.2.26

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 (85) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +20 -12
  3. package/index.ts +2 -2
  4. package/package.json +10 -11
  5. package/src/agent-identity.ts +75 -0
  6. package/src/agents-contract.ts +20 -12
  7. package/src/agents-discovery.ts +79 -34
  8. package/src/agents-focus.ts +15 -9
  9. package/src/agents-spawn.ts +25 -7
  10. package/src/agents-tool.ts +35 -7
  11. package/src/agents-work.ts +2 -2
  12. package/src/attachment-notes.ts +25 -24
  13. package/src/attachment-protocol.ts +35 -15
  14. package/src/attachment-routing.ts +28 -24
  15. package/src/attachment-target.ts +58 -19
  16. package/src/attachment.ts +13 -17
  17. package/src/board/host.ts +19 -20
  18. package/src/board/membership.ts +49 -30
  19. package/src/close-idle.ts +89 -0
  20. package/src/context-routing.ts +196 -0
  21. package/src/control-panel/index.ts +3 -1
  22. package/src/control-panel/items.ts +14 -2
  23. package/src/control-panel/view.ts +6 -2
  24. package/src/controller.ts +11 -2
  25. package/src/core/AGENTS.md +5 -0
  26. package/src/core/backend.ts +266 -0
  27. package/src/core/client.ts +249 -0
  28. package/src/core/context-relay.mjs +111 -0
  29. package/src/core/focus-channel-helper.mjs +165 -0
  30. package/src/core/focus-channel-stream.ts +140 -0
  31. package/src/core/focus-channel-wire.mjs +160 -0
  32. package/src/core/focus-channel.ts +213 -0
  33. package/src/core/focus-window.ts +192 -0
  34. package/src/core/pi-executable.mjs +34 -0
  35. package/src/core/protocol.ts +116 -0
  36. package/src/core/registration.ts +51 -0
  37. package/src/core/remote-endpoint.ts +119 -0
  38. package/src/core/remote-exec.ts +122 -0
  39. package/src/core/remote-helper.mjs +244 -0
  40. package/src/core/remote-reader.ts +67 -0
  41. package/src/core/remote-relay.ts +191 -0
  42. package/src/core/request.ts +124 -0
  43. package/src/core/spawn.ts +177 -0
  44. package/src/core/status.ts +68 -0
  45. package/src/core/terminal.ts +103 -0
  46. package/src/fleet/catalog.ts +83 -0
  47. package/src/fleet/connection.ts +111 -0
  48. package/src/fleet/index.ts +161 -122
  49. package/src/fleet/inspection.ts +19 -1
  50. package/src/fleet/machine.ts +3 -0
  51. package/src/fleet/monitor.ts +18 -4
  52. package/src/fleet/persistence.ts +26 -3
  53. package/src/fleet/setup.ts +54 -13
  54. package/src/herdr.ts +25 -5
  55. package/src/launch-contract.ts +48 -0
  56. package/src/launch-location.ts +151 -0
  57. package/src/launch.ts +30 -183
  58. package/src/messages/attribution.ts +15 -6
  59. package/src/messages/events.ts +10 -4
  60. package/src/messages/focus.ts +11 -2
  61. package/src/messages/guidance.ts +22 -16
  62. package/src/monitor-extension-messages.ts +9 -2
  63. package/src/monitor-record.ts +13 -6
  64. package/src/monitor-state.ts +18 -4
  65. package/src/monitor.ts +31 -0
  66. package/src/peer-commands.ts +11 -0
  67. package/src/peer-inbox-delivery.ts +171 -0
  68. package/src/peer-inbox-focus.ts +113 -0
  69. package/src/peer-inbox.ts +126 -208
  70. package/src/remote/deployment.ts +1 -1
  71. package/src/remote/shepherdr-checkpoints.mjs +20 -2
  72. package/src/remote/shepherdr-context.mjs +15 -3
  73. package/src/remote/shepherdr-peer.mjs +18 -5
  74. package/src/remote/shepherdr-session.mjs +9 -2
  75. package/src/remote/shepherdr.mjs +1 -1
  76. package/src/settlement/collector.ts +2 -2
  77. package/src/settlement/index.ts +12 -0
  78. package/src/shared-context-host.ts +7 -18
  79. package/src/shared-context.ts +139 -12
  80. package/src/spawn-context.ts +10 -5
  81. package/src/spawn-ownership.ts +91 -0
  82. package/src/types.ts +10 -5
  83. package/src/worker-ownership.ts +92 -0
  84. package/src/worker-service.ts +13 -82
  85. package/changelog.ts +0 -337
@@ -6,8 +6,9 @@ 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 { CoreConnection } from "./core/backend.js";
9
10
  import type { AgentFleet } from "./fleet/index.js";
10
- import { getSnapshot, sessionPath } from "./herdr.js";
11
+ import { sessionPath } from "./herdr.js";
11
12
  import {
12
13
  RolledBackAgentLaunchError,
13
14
  rollbackStartedAgent,
@@ -17,10 +18,9 @@ import {
17
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);
@@ -266,7 +192,7 @@ export function registerWorkerService(
266
192
  const sharing =
267
193
  worker || profile.shareContext === false
268
194
  ? undefined
269
- : await shared.spawns.prepare(ctx, runtime, name, args);
195
+ : await shared.spawns.prepare(ctx, runtime, args);
270
196
  const boardBinding = worker
271
197
  ? undefined
272
198
  : await board.prepare(ctx, runtime, name, args);
@@ -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,
package/changelog.ts DELETED
@@ -1,337 +0,0 @@
1
- // Generated extension packages copy this file during changelog:extensions.
2
-
3
- import { randomUUID } from "node:crypto";
4
- import { readFileSync } from "node:fs";
5
- import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
6
- import { dirname, join } from "node:path";
7
- import { fileURLToPath } from "node:url";
8
- import {
9
- DynamicBorder,
10
- type ExtensionAPI,
11
- getAgentDir,
12
- getMarkdownTheme,
13
- } from "@earendil-works/pi-coding-agent";
14
- import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
15
-
16
- const ENTRY_TYPE = "@howaboua/pi-stuff/changelog";
17
- const REGISTRATION_CHANNEL = "@howaboua/pi-stuff/changelog/register/v1";
18
- const STATE_FILENAME = "howaboua-pi-stuff-changelog.json";
19
- const SUPPRESS_KEY = "suppress";
20
- const LOCK_STALE_MS = 30_000;
21
- const LOCK_TIMEOUT_MS = 2_000;
22
-
23
- interface PackageMetadata {
24
- name: string;
25
- version: string;
26
- }
27
-
28
- interface PackageRegistration extends PackageMetadata {
29
- changelogPath: string;
30
- }
31
-
32
- interface RegistrationEvent {
33
- accept: () => void;
34
- registration: PackageRegistration;
35
- }
36
-
37
- interface ChangelogEntry {
38
- content: string;
39
- version: string;
40
- }
41
-
42
- interface ChangelogEntryData {
43
- markdown: string;
44
- }
45
-
46
- type ChangelogState = Record<string, boolean | string>;
47
-
48
- function packageRegistration(): PackageRegistration {
49
- const packageDirectory = fileURLToPath(new URL(".", import.meta.url));
50
- const metadata = JSON.parse(
51
- readFileSync(join(packageDirectory, "package.json"), "utf8"),
52
- ) as Partial<PackageMetadata>;
53
- if (typeof metadata.name !== "string" || typeof metadata.version !== "string")
54
- throw new Error(`Invalid package metadata in ${packageDirectory}`);
55
- return {
56
- name: metadata.name,
57
- version: metadata.version,
58
- changelogPath: join(packageDirectory, "CHANGELOG.md"),
59
- };
60
- }
61
-
62
- function isRegistrationEvent(value: unknown): value is RegistrationEvent {
63
- if (!value || typeof value !== "object") return false;
64
- const event = value as Partial<RegistrationEvent>;
65
- return (
66
- typeof event.accept === "function" &&
67
- typeof event.registration?.name === "string" &&
68
- typeof event.registration.version === "string" &&
69
- typeof event.registration.changelogPath === "string"
70
- );
71
- }
72
-
73
- function parseChangelog(markdown: string): ChangelogEntry[] {
74
- const entries: ChangelogEntry[] = [];
75
- let currentLines: string[] = [];
76
- let currentVersion: string | undefined;
77
-
78
- for (const line of markdown.split("\n")) {
79
- const version = line.match(/^##\s+\[?(\d+\.\d+\.\d+)\]?(?:\s.*)?$/)?.[1];
80
- if (version) {
81
- if (currentVersion)
82
- entries.push({
83
- content: currentLines.join("\n").trim(),
84
- version: currentVersion,
85
- });
86
- currentVersion = version;
87
- currentLines = [line];
88
- } else if (currentVersion) {
89
- currentLines.push(line);
90
- }
91
- }
92
-
93
- if (currentVersion)
94
- entries.push({
95
- content: currentLines.join("\n").trim(),
96
- version: currentVersion,
97
- });
98
- return entries;
99
- }
100
-
101
- function compareVersions(left: string, right: string): number {
102
- const leftParts = left.split(".").map(Number);
103
- const rightParts = right.split(".").map(Number);
104
- for (let index = 0; index < 3; index++) {
105
- const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
106
- if (difference !== 0) return difference;
107
- }
108
- return 0;
109
- }
110
-
111
- function isStableVersion(version: string): boolean {
112
- return /^\d+\.\d+\.\d+$/.test(version);
113
- }
114
-
115
- function statePath(): string {
116
- return join(getAgentDir(), STATE_FILENAME);
117
- }
118
-
119
- async function readState(path: string): Promise<ChangelogState> {
120
- let text: string;
121
- try {
122
- text = await readFile(path, "utf8");
123
- } catch (error) {
124
- if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
125
- throw error;
126
- }
127
- const parsed = JSON.parse(text) as unknown;
128
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
129
- throw new Error(`${path} must contain a JSON object`);
130
- for (const [name, value] of Object.entries(parsed)) {
131
- if (name === SUPPRESS_KEY) {
132
- if (typeof value !== "boolean")
133
- throw new Error(`${path} ${SUPPRESS_KEY} must be a boolean`);
134
- } else if (typeof value !== "string") {
135
- throw new Error(`${path} version for ${name} must be a string`);
136
- }
137
- }
138
- return parsed as ChangelogState;
139
- }
140
-
141
- async function acquireLock(path: string): Promise<() => Promise<void>> {
142
- const deadline = Date.now() + LOCK_TIMEOUT_MS;
143
- while (true) {
144
- try {
145
- await mkdir(path);
146
- return () => rm(path, { force: true, recursive: true });
147
- } catch (error) {
148
- if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
149
- const info = await stat(path).catch(() => undefined);
150
- if (info && Date.now() - info.mtimeMs > LOCK_STALE_MS) {
151
- await rm(path, { force: true, recursive: true });
152
- continue;
153
- }
154
- if (Date.now() >= deadline)
155
- throw new Error(`Timed out waiting for ${path}`);
156
- await new Promise((resolve) => setTimeout(resolve, 20));
157
- }
158
- }
159
- }
160
-
161
- async function writeState(path: string, state: ChangelogState): Promise<void> {
162
- await mkdir(dirname(path), { mode: 0o700, recursive: true });
163
- const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
164
- try {
165
- const ordered = Object.fromEntries(
166
- Object.entries(state).sort(([left], [right]) =>
167
- left.localeCompare(right),
168
- ),
169
- );
170
- await writeFile(temporaryPath, `${JSON.stringify(ordered, null, 2)}\n`, {
171
- encoding: "utf8",
172
- mode: 0o600,
173
- });
174
- await rename(temporaryPath, path);
175
- } catch (error) {
176
- await rm(temporaryPath, { force: true });
177
- throw error;
178
- }
179
- }
180
-
181
- function packageMarkdown(
182
- registration: PackageRegistration,
183
- entries: ChangelogEntry[],
184
- ): string {
185
- const body = (entry: ChangelogEntry) =>
186
- entry.content
187
- .replace(/^##[^\n]*\n*/, "")
188
- .replace(/^###\s+(?:Changes|Minor Changes|Patch Changes)\s*\n*/gim, "")
189
- .replace(/^###\s+(.+)$/gm, "**$1**");
190
- if (entries.length === 1) {
191
- const [entry] = entries;
192
- if (!entry) return "";
193
- return `## ${registration.name} ${entry.version}\n\n${body(entry)}`;
194
- }
195
- return [
196
- `## ${registration.name}`,
197
- ...entries.map((entry) => `**${entry.version}**\n\n${body(entry)}`),
198
- ].join("\n\n");
199
- }
200
-
201
- async function claimUpdates(
202
- registrations: Iterable<PackageRegistration>,
203
- ): Promise<{ errors: string[]; markdown?: string }> {
204
- const stableRegistrations = [...registrations]
205
- .filter((registration) => isStableVersion(registration.version))
206
- .sort((left, right) => left.name.localeCompare(right.name));
207
- if (stableRegistrations.length === 0) return { errors: [] };
208
- const path = statePath();
209
- await mkdir(dirname(path), { mode: 0o700, recursive: true });
210
- const release = await acquireLock(`${path}.lock`);
211
- try {
212
- const state = await readState(path);
213
- const errors: string[] = [];
214
- const sections: string[] = [];
215
- let changed = false;
216
- if (state[SUPPRESS_KEY] === true) {
217
- for (const registration of stableRegistrations) {
218
- const seenVersion = state[registration.name];
219
- if (
220
- typeof seenVersion !== "string" ||
221
- compareVersions(registration.version, seenVersion) > 0
222
- ) {
223
- state[registration.name] = registration.version;
224
- changed = true;
225
- }
226
- }
227
- if (changed) await writeState(path, state);
228
- return { errors };
229
- }
230
- for (const registration of stableRegistrations) {
231
- const seenVersion = state[registration.name];
232
- if (
233
- typeof seenVersion === "string" &&
234
- compareVersions(registration.version, seenVersion) <= 0
235
- )
236
- continue;
237
- try {
238
- const entries = parseChangelog(
239
- await readFile(registration.changelogPath, "utf8"),
240
- ).filter(
241
- (entry) =>
242
- compareVersions(entry.version, registration.version) <= 0 &&
243
- (typeof seenVersion === "string"
244
- ? compareVersions(entry.version, seenVersion) > 0
245
- : entry.version === registration.version),
246
- );
247
- if (entries.length === 0) {
248
- errors.push(
249
- `No ${registration.version} changelog entry found for ${registration.name}`,
250
- );
251
- continue;
252
- }
253
- sections.push(packageMarkdown(registration, entries));
254
- state[registration.name] = registration.version;
255
- changed = true;
256
- } catch (error) {
257
- errors.push(
258
- `Could not read the ${registration.name} changelog: ${error instanceof Error ? error.message : String(error)}`,
259
- );
260
- }
261
- }
262
- if (changed) await writeState(path, state);
263
- return {
264
- errors,
265
- ...(sections.length > 0 ? { markdown: sections.join("\n\n") } : {}),
266
- };
267
- } finally {
268
- await release();
269
- }
270
- }
271
-
272
- function registerCoordinator(
273
- pi: ExtensionAPI,
274
- registration: PackageRegistration,
275
- ): void {
276
- let accepted = false;
277
- pi.events.emit(REGISTRATION_CHANNEL, {
278
- registration,
279
- accept: () => {
280
- accepted = true;
281
- },
282
- } satisfies RegistrationEvent);
283
- if (accepted) return;
284
-
285
- const registrations = new Map([[registration.name, registration]]);
286
- pi.events.on(REGISTRATION_CHANNEL, (value) => {
287
- if (!isRegistrationEvent(value)) return;
288
- registrations.set(value.registration.name, value.registration);
289
- value.accept();
290
- });
291
- pi.registerEntryRenderer<ChangelogEntryData>(
292
- ENTRY_TYPE,
293
- (entry, _options, theme) => {
294
- if (!entry.data) return undefined;
295
- const container = new Container();
296
- container.addChild(new DynamicBorder());
297
- container.addChild(
298
- new Text(theme.bold(theme.fg("accent", "What's New")), 1, 0),
299
- );
300
- container.addChild(new Spacer(1));
301
- container.addChild(
302
- new Markdown(entry.data.markdown.trim(), 1, 0, getMarkdownTheme()),
303
- );
304
- container.addChild(new Spacer(1));
305
- container.addChild(new DynamicBorder());
306
- return container;
307
- },
308
- );
309
- pi.on("session_start", async (event, ctx) => {
310
- if (event.reason === "reload" || ctx.mode !== "tui") return;
311
- if (
312
- ctx.sessionManager
313
- .getEntries()
314
- .some((entry) =>
315
- ["branch_summary", "compaction", "message"].includes(entry.type),
316
- )
317
- )
318
- return;
319
- try {
320
- const update = await claimUpdates(registrations.values());
321
- if (update.markdown)
322
- pi.appendEntry<ChangelogEntryData>(ENTRY_TYPE, {
323
- markdown: update.markdown,
324
- });
325
- for (const error of update.errors) ctx.ui.notify(error, "warning");
326
- } catch (error) {
327
- ctx.ui.notify(
328
- `Could not update Howaboua changelog state: ${error instanceof Error ? error.message : String(error)}`,
329
- "warning",
330
- );
331
- }
332
- });
333
- }
334
-
335
- export default function howabouaPackageChangelog(pi: ExtensionAPI): void {
336
- registerCoordinator(pi, packageRegistration());
337
- }