@howaboua/pi-shepherdr 0.1.1 → 0.1.3
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 +34 -0
- package/README.md +57 -46
- package/biome.json +1 -1
- package/changelog.ts +337 -0
- package/index.ts +95 -8
- package/package.json +24 -12
- package/profiles/explorer/profile.json +8 -0
- package/profiles/explorer/prompt.md +1 -0
- package/profiles/general/profile.json +8 -0
- package/profiles/general/prompt.md +1 -0
- package/profiles/reviewer/prepare.mjs +170 -0
- package/profiles/reviewer/profile.json +9 -0
- package/profiles/reviewer/prompt.md +1 -0
- package/src/activity.ts +20 -1
- package/src/agents-contract.ts +142 -0
- package/src/agents-operations.ts +338 -0
- package/src/agents-tool.ts +440 -0
- package/src/ask-answer.ts +297 -0
- package/src/controller.ts +178 -0
- package/src/fleet.ts +556 -0
- package/src/herdr-client.ts +10 -1
- package/src/herdr.ts +19 -6
- package/src/launch.ts +74 -14
- package/src/machine-menu.ts +158 -0
- package/src/machines-config.ts +148 -0
- package/src/messages.ts +142 -10
- package/src/monitor-events.ts +7 -5
- package/src/monitor-record.ts +34 -1
- package/src/monitor-state.ts +40 -4
- package/src/monitor.ts +124 -56
- package/src/profiles.ts +291 -0
- package/src/remote/shepherdr.mjs +520 -0
- package/src/remote-client.ts +426 -0
- package/src/session-reader.ts +218 -71
- package/src/settlement.ts +246 -42
- package/src/types.ts +42 -1
- package/src/widget.ts +23 -8
- package/src/master-config.ts +0 -61
- package/src/master-mode.ts +0 -107
- package/src/tool.ts +0 -195
|
@@ -0,0 +1,426 @@
|
|
|
1
|
+
import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { readFile } from "node:fs/promises";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
import type { HerdrConnection } from "./herdr-client.js";
|
|
6
|
+
import type { RemoteMachineConfig } from "./machines-config.js";
|
|
7
|
+
import type { AssistantReader } from "./session-reader.js";
|
|
8
|
+
import type { HerdrEvent, LatestAssistant, SessionView } from "./types.js";
|
|
9
|
+
|
|
10
|
+
const BRIDGE_VERSION = 3;
|
|
11
|
+
const REMOTE_HELPER = "~/.pi/agent/shepherdr.mjs";
|
|
12
|
+
const MAX_FRAME_BYTES = 8 * 1024 * 1024;
|
|
13
|
+
const MAX_DIAGNOSTIC_BYTES = 8 * 1024;
|
|
14
|
+
const DEPLOY_TIMEOUT_MS = 20_000;
|
|
15
|
+
const READY_TIMEOUT_MS = 15_000;
|
|
16
|
+
|
|
17
|
+
const DEPLOY_SOURCE = String.raw`
|
|
18
|
+
const { randomUUID } = require("node:crypto");
|
|
19
|
+
const { mkdir, readFile, rename, unlink, writeFile } = require("node:fs/promises");
|
|
20
|
+
const { homedir } = require("node:os");
|
|
21
|
+
const { dirname, join } = require("node:path");
|
|
22
|
+
const targetValue = process.argv[1];
|
|
23
|
+
const marker = "// @howaboua/pi-shepherdr managed bridge";
|
|
24
|
+
const target = targetValue === "~" ? homedir() : targetValue.startsWith("~/") ? join(homedir(), targetValue.slice(2)) : targetValue;
|
|
25
|
+
const chunks = [];
|
|
26
|
+
let size = 0;
|
|
27
|
+
process.stdin.on("data", chunk => { size += chunk.length; if (size > 1024 * 1024) { process.stderr.write("bridge source is too large\n"); process.exit(1); } chunks.push(chunk); });
|
|
28
|
+
process.stdin.on("end", () => { void (async () => {
|
|
29
|
+
const source = Buffer.concat(chunks);
|
|
30
|
+
let existing;
|
|
31
|
+
try { existing = await readFile(target); } catch (error) { if (error.code !== "ENOENT") throw error; }
|
|
32
|
+
if (existing) {
|
|
33
|
+
if (existing.equals(source)) { process.stdout.write(JSON.stringify({ updated: false, path: target }) + "\n"); return; }
|
|
34
|
+
if (!existing.toString("utf8", 0, marker.length + 32).startsWith(marker)) throw new Error(target + " is not owned by Shepherdr");
|
|
35
|
+
}
|
|
36
|
+
await mkdir(dirname(target), { recursive: true, mode: 0o700 });
|
|
37
|
+
const temporary = target + "." + process.pid + "." + randomUUID() + ".tmp";
|
|
38
|
+
try {
|
|
39
|
+
await writeFile(temporary, source, { mode: 0o600, flag: "wx" });
|
|
40
|
+
await rename(temporary, target);
|
|
41
|
+
} catch (error) {
|
|
42
|
+
await unlink(temporary).catch(() => undefined);
|
|
43
|
+
throw error;
|
|
44
|
+
}
|
|
45
|
+
process.stdout.write(JSON.stringify({ updated: true, path: target }) + "\n");
|
|
46
|
+
})().catch(error => { process.stderr.write(error.message + "\n"); process.exit(1); }); });
|
|
47
|
+
`;
|
|
48
|
+
|
|
49
|
+
interface PendingCall {
|
|
50
|
+
reject: (error: Error) => void;
|
|
51
|
+
resolve: (value: unknown) => void;
|
|
52
|
+
timer: NodeJS.Timeout;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
interface SubscriptionCallbacks {
|
|
56
|
+
onDisconnect: (error?: Error) => void;
|
|
57
|
+
onEvent: (event: HerdrEvent) => void;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
interface BridgeError {
|
|
61
|
+
code?: string;
|
|
62
|
+
herdrResponse?: boolean;
|
|
63
|
+
message: string;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function shellQuote(value: string): string {
|
|
67
|
+
return `'${value.replaceAll("'", `'"'"'`)}'`;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function executablePath(path: string): string {
|
|
71
|
+
return path.startsWith("~/")
|
|
72
|
+
? `"$HOME"/${shellQuote(path.slice(2))}`
|
|
73
|
+
: shellQuote(path);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function remoteCommand(config: RemoteMachineConfig): string {
|
|
77
|
+
const args = [
|
|
78
|
+
"exec",
|
|
79
|
+
shellQuote(config.node),
|
|
80
|
+
executablePath(REMOTE_HELPER),
|
|
81
|
+
...(config.socket ? ["--socket", shellQuote(config.socket)] : []),
|
|
82
|
+
...(config.session ? ["--session", shellQuote(config.session)] : []),
|
|
83
|
+
];
|
|
84
|
+
return args.join(" ");
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function spawnConnector(
|
|
88
|
+
config: RemoteMachineConfig,
|
|
89
|
+
command: string,
|
|
90
|
+
): ChildProcessWithoutNullStreams {
|
|
91
|
+
const [program, ...args] = config.command;
|
|
92
|
+
if (!program) throw new Error("remote machine command is empty");
|
|
93
|
+
return spawn(program, [...args, command], {
|
|
94
|
+
stdio: ["pipe", "pipe", "pipe"],
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function appendBounded(current: string, chunk: Buffer): string {
|
|
99
|
+
const next = current + chunk.toString("utf8");
|
|
100
|
+
return next.length <= MAX_DIAGNOSTIC_BYTES
|
|
101
|
+
? next
|
|
102
|
+
: next.slice(next.length - MAX_DIAGNOSTIC_BYTES);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
async function deploy(
|
|
106
|
+
config: RemoteMachineConfig,
|
|
107
|
+
source: Buffer,
|
|
108
|
+
): Promise<void> {
|
|
109
|
+
const command = [
|
|
110
|
+
shellQuote(config.node),
|
|
111
|
+
"-e",
|
|
112
|
+
shellQuote(DEPLOY_SOURCE),
|
|
113
|
+
shellQuote(REMOTE_HELPER),
|
|
114
|
+
].join(" ");
|
|
115
|
+
const child = spawnConnector(config, command);
|
|
116
|
+
let stdout = "";
|
|
117
|
+
let stderr = "";
|
|
118
|
+
child.stdout.on("data", (chunk: Buffer) => {
|
|
119
|
+
stdout = appendBounded(stdout, chunk);
|
|
120
|
+
});
|
|
121
|
+
child.stderr.on("data", (chunk: Buffer) => {
|
|
122
|
+
stderr = appendBounded(stderr, chunk);
|
|
123
|
+
});
|
|
124
|
+
child.stdin.end(source);
|
|
125
|
+
await new Promise<void>((resolve, reject) => {
|
|
126
|
+
const timer = setTimeout(() => {
|
|
127
|
+
child.kill();
|
|
128
|
+
reject(new Error("remote bridge deployment timed out"));
|
|
129
|
+
}, DEPLOY_TIMEOUT_MS);
|
|
130
|
+
timer.unref();
|
|
131
|
+
child.on("error", (error) => {
|
|
132
|
+
clearTimeout(timer);
|
|
133
|
+
reject(error);
|
|
134
|
+
});
|
|
135
|
+
child.on("exit", (code) => {
|
|
136
|
+
clearTimeout(timer);
|
|
137
|
+
if (code === 0) resolve();
|
|
138
|
+
else
|
|
139
|
+
reject(
|
|
140
|
+
new Error(
|
|
141
|
+
stderr.trim() ||
|
|
142
|
+
stdout.trim() ||
|
|
143
|
+
`remote bridge deployment exited ${code ?? "without status"}`,
|
|
144
|
+
),
|
|
145
|
+
);
|
|
146
|
+
});
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
|
|
151
|
+
private readonly child: ChildProcessWithoutNullStreams;
|
|
152
|
+
private closed = false;
|
|
153
|
+
private diagnostics = "";
|
|
154
|
+
private input = "";
|
|
155
|
+
private readonly onClose: (error: Error) => void;
|
|
156
|
+
private readonly pending = new Map<string, PendingCall>();
|
|
157
|
+
private readonly subscriptions = new Map<string, SubscriptionCallbacks>();
|
|
158
|
+
|
|
159
|
+
private constructor(
|
|
160
|
+
child: ChildProcessWithoutNullStreams,
|
|
161
|
+
onClose: (error: Error) => void,
|
|
162
|
+
) {
|
|
163
|
+
this.child = child;
|
|
164
|
+
this.onClose = onClose;
|
|
165
|
+
child.stdout.setEncoding("utf8");
|
|
166
|
+
child.stdout.on("data", (chunk: string) => this.consume(chunk));
|
|
167
|
+
child.stderr.on("data", (chunk: Buffer) => {
|
|
168
|
+
this.diagnostics = appendBounded(this.diagnostics, chunk);
|
|
169
|
+
});
|
|
170
|
+
child.on("error", (error) => this.disconnected(error));
|
|
171
|
+
child.on("exit", (code) => {
|
|
172
|
+
this.disconnected(
|
|
173
|
+
new Error(
|
|
174
|
+
this.diagnostics.trim() ||
|
|
175
|
+
`remote Shepherdr bridge exited ${code ?? "without status"}`,
|
|
176
|
+
),
|
|
177
|
+
);
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
static async connect(
|
|
182
|
+
config: RemoteMachineConfig,
|
|
183
|
+
onClose: (error: Error) => void,
|
|
184
|
+
): Promise<RemoteHerdrClient> {
|
|
185
|
+
const source = await readFile(
|
|
186
|
+
fileURLToPath(new URL("./remote/shepherdr.mjs", import.meta.url)),
|
|
187
|
+
);
|
|
188
|
+
await deploy(config, source);
|
|
189
|
+
const child = spawnConnector(config, remoteCommand(config));
|
|
190
|
+
const client = new RemoteHerdrClient(child, onClose);
|
|
191
|
+
try {
|
|
192
|
+
await client.ready();
|
|
193
|
+
return client;
|
|
194
|
+
} catch (error) {
|
|
195
|
+
client.close();
|
|
196
|
+
throw error;
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
async request<T>(
|
|
201
|
+
method: string,
|
|
202
|
+
params: object = {},
|
|
203
|
+
timeoutMs = 10_000,
|
|
204
|
+
): Promise<T> {
|
|
205
|
+
return (await this.call(
|
|
206
|
+
{ op: "request", method, params, timeoutMs },
|
|
207
|
+
timeoutMs + 1_000,
|
|
208
|
+
)) as T;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
async subscribe(
|
|
212
|
+
subscriptions: object[],
|
|
213
|
+
onEvent: (event: HerdrEvent) => void,
|
|
214
|
+
onDisconnect: (error?: Error) => void,
|
|
215
|
+
): Promise<() => void> {
|
|
216
|
+
const id = randomUUID();
|
|
217
|
+
this.subscriptions.set(id, { onEvent, onDisconnect });
|
|
218
|
+
try {
|
|
219
|
+
await this.call({ id, op: "subscribe", subscriptions }, 11_000);
|
|
220
|
+
} catch (error) {
|
|
221
|
+
this.subscriptions.delete(id);
|
|
222
|
+
throw error;
|
|
223
|
+
}
|
|
224
|
+
return () => {
|
|
225
|
+
if (!this.subscriptions.delete(id) || this.closed) return;
|
|
226
|
+
void this.call({ op: "unsubscribe", subscription: id }).catch(
|
|
227
|
+
() => undefined,
|
|
228
|
+
);
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
async latest(path?: string): Promise<LatestAssistant | undefined> {
|
|
233
|
+
return (await this.view(path)).assistant;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
async view(path?: string): Promise<SessionView> {
|
|
237
|
+
return (await this.call({ op: "view", path })) as SessionView;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
async keybindings(): Promise<Record<string, unknown>> {
|
|
241
|
+
return (await this.call({ op: "keybindings" })) as Record<string, unknown>;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
async directory(
|
|
245
|
+
value: string | undefined,
|
|
246
|
+
fallback: string,
|
|
247
|
+
): Promise<string> {
|
|
248
|
+
return (await this.call({ op: "directory", value, fallback })) as string;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
close(): void {
|
|
252
|
+
if (this.closed) return;
|
|
253
|
+
this.closed = true;
|
|
254
|
+
this.child.kill();
|
|
255
|
+
this.failPending(new Error("remote Shepherdr bridge closed"), false);
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
private ready(): Promise<void> {
|
|
259
|
+
return new Promise((resolve, reject) => {
|
|
260
|
+
const timer = setTimeout(() => {
|
|
261
|
+
this.close();
|
|
262
|
+
reject(new Error("remote Shepherdr bridge did not become ready"));
|
|
263
|
+
}, READY_TIMEOUT_MS);
|
|
264
|
+
timer.unref();
|
|
265
|
+
this.pending.set("ready", {
|
|
266
|
+
timer,
|
|
267
|
+
resolve: (value) => {
|
|
268
|
+
const ready = value as { version?: unknown };
|
|
269
|
+
if (ready.version !== BRIDGE_VERSION) {
|
|
270
|
+
reject(new Error("remote Shepherdr bridge version mismatch"));
|
|
271
|
+
return;
|
|
272
|
+
}
|
|
273
|
+
resolve();
|
|
274
|
+
},
|
|
275
|
+
reject,
|
|
276
|
+
});
|
|
277
|
+
});
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
private call(
|
|
281
|
+
message: Record<string, unknown>,
|
|
282
|
+
timeoutMs = 10_000,
|
|
283
|
+
): Promise<unknown> {
|
|
284
|
+
if (this.closed)
|
|
285
|
+
return Promise.reject(
|
|
286
|
+
new Error("remote Shepherdr bridge is unavailable"),
|
|
287
|
+
);
|
|
288
|
+
const id = typeof message["id"] === "string" ? message["id"] : randomUUID();
|
|
289
|
+
return new Promise((resolve, reject) => {
|
|
290
|
+
const timer = setTimeout(() => {
|
|
291
|
+
this.disconnected(
|
|
292
|
+
new Error(`remote Shepherdr ${String(message["op"])} timed out`),
|
|
293
|
+
);
|
|
294
|
+
}, timeoutMs);
|
|
295
|
+
timer.unref();
|
|
296
|
+
this.pending.set(id, { resolve, reject, timer });
|
|
297
|
+
this.child.stdin.write(
|
|
298
|
+
`${JSON.stringify({ ...message, id })}\n`,
|
|
299
|
+
(error) => {
|
|
300
|
+
if (!error) return;
|
|
301
|
+
const pending = this.pending.get(id);
|
|
302
|
+
if (!pending) return;
|
|
303
|
+
this.pending.delete(id);
|
|
304
|
+
clearTimeout(pending.timer);
|
|
305
|
+
pending.reject(error);
|
|
306
|
+
},
|
|
307
|
+
);
|
|
308
|
+
});
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
private consume(chunk: string): void {
|
|
312
|
+
this.input += chunk;
|
|
313
|
+
if (Buffer.byteLength(this.input) > MAX_FRAME_BYTES) {
|
|
314
|
+
this.disconnected(
|
|
315
|
+
new Error("remote Shepherdr bridge frame is too large"),
|
|
316
|
+
);
|
|
317
|
+
return;
|
|
318
|
+
}
|
|
319
|
+
for (;;) {
|
|
320
|
+
const newline = this.input.indexOf("\n");
|
|
321
|
+
if (newline < 0) break;
|
|
322
|
+
const line = this.input.slice(0, newline);
|
|
323
|
+
this.input = this.input.slice(newline + 1);
|
|
324
|
+
if (!line) continue;
|
|
325
|
+
let value: Record<string, unknown>;
|
|
326
|
+
try {
|
|
327
|
+
value = JSON.parse(line) as Record<string, unknown>;
|
|
328
|
+
} catch (error) {
|
|
329
|
+
this.disconnected(
|
|
330
|
+
new Error(
|
|
331
|
+
`remote Shepherdr bridge returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
|
|
332
|
+
),
|
|
333
|
+
);
|
|
334
|
+
return;
|
|
335
|
+
}
|
|
336
|
+
if (value["type"] === "ready") {
|
|
337
|
+
this.resolvePending("ready", value);
|
|
338
|
+
continue;
|
|
339
|
+
}
|
|
340
|
+
const subscription = value["subscription"];
|
|
341
|
+
if (typeof subscription === "string") {
|
|
342
|
+
const callbacks = this.subscriptions.get(subscription);
|
|
343
|
+
const event = value["event"];
|
|
344
|
+
if (callbacks && event && typeof event === "object") {
|
|
345
|
+
try {
|
|
346
|
+
callbacks.onEvent(event as HerdrEvent);
|
|
347
|
+
} catch (error) {
|
|
348
|
+
this.disconnected(
|
|
349
|
+
new Error(
|
|
350
|
+
`Shepherdr event handling failed: ${error instanceof Error ? error.message : String(error)}`,
|
|
351
|
+
{ cause: error },
|
|
352
|
+
),
|
|
353
|
+
);
|
|
354
|
+
return;
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
continue;
|
|
358
|
+
}
|
|
359
|
+
const id = value["id"];
|
|
360
|
+
if (typeof id !== "string") continue;
|
|
361
|
+
if (value["ok"] === true) this.resolvePending(id, value["result"]);
|
|
362
|
+
else {
|
|
363
|
+
const detail = value["error"] as BridgeError | undefined;
|
|
364
|
+
const error = new Error(
|
|
365
|
+
detail?.message ?? "remote Shepherdr bridge request failed",
|
|
366
|
+
) as Error & {
|
|
367
|
+
code?: string;
|
|
368
|
+
herdrResponse?: true;
|
|
369
|
+
};
|
|
370
|
+
if (detail?.code) error.code = detail.code;
|
|
371
|
+
if (detail?.herdrResponse) error.herdrResponse = true;
|
|
372
|
+
this.rejectPending(id, error);
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
private resolvePending(id: string, value: unknown): void {
|
|
378
|
+
const pending = this.pending.get(id);
|
|
379
|
+
if (!pending) return;
|
|
380
|
+
this.pending.delete(id);
|
|
381
|
+
clearTimeout(pending.timer);
|
|
382
|
+
pending.resolve(value);
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
private rejectPending(id: string, error: Error): void {
|
|
386
|
+
const pending = this.pending.get(id);
|
|
387
|
+
if (!pending) return;
|
|
388
|
+
this.pending.delete(id);
|
|
389
|
+
clearTimeout(pending.timer);
|
|
390
|
+
pending.reject(error);
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
private disconnected(error: Error): void {
|
|
394
|
+
if (this.closed) return;
|
|
395
|
+
this.closed = true;
|
|
396
|
+
this.child.kill();
|
|
397
|
+
this.failPending(error, true);
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
private failPending(error: Error, notify: boolean): void {
|
|
401
|
+
for (const pending of this.pending.values()) {
|
|
402
|
+
clearTimeout(pending.timer);
|
|
403
|
+
pending.reject(error);
|
|
404
|
+
}
|
|
405
|
+
this.pending.clear();
|
|
406
|
+
let callbackFailure: unknown;
|
|
407
|
+
for (const callbacks of this.subscriptions.values()) {
|
|
408
|
+
try {
|
|
409
|
+
callbacks.onDisconnect(error);
|
|
410
|
+
} catch (failure) {
|
|
411
|
+
callbackFailure ??= failure;
|
|
412
|
+
}
|
|
413
|
+
}
|
|
414
|
+
this.subscriptions.clear();
|
|
415
|
+
if (notify) {
|
|
416
|
+
this.onClose(
|
|
417
|
+
callbackFailure === undefined
|
|
418
|
+
? error
|
|
419
|
+
: new Error(
|
|
420
|
+
`${error.message}; disconnect handler failed: ${callbackFailure instanceof Error ? callbackFailure.message : String(callbackFailure)}`,
|
|
421
|
+
{ cause: callbackFailure },
|
|
422
|
+
),
|
|
423
|
+
);
|
|
424
|
+
}
|
|
425
|
+
}
|
|
426
|
+
}
|