pi-cowboy 0.3.5 → 0.4.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.
- package/dist/agents/agent-assets.js +2 -1
- package/dist/agents/agent-manager.js +13 -5
- package/dist/agents/agent-reviver.js +4 -9
- package/dist/agents/agent-runner.js +2 -2
- package/dist/agents/subagent-session.js +6 -71
- package/dist/index.js +3 -5
- package/dist/logger.js +6 -8
- package/dist/orchestrators/protocol.js +13 -1
- package/dist/paths.js +44 -6
- package/dist/shell.js +5 -32
- package/dist/spawn/crockford-base32.js +252 -0
- package/dist/spawn/spawn-coordinator.js +2 -2
- package/dist/spawn/spawn-id.js +1 -1
- package/dist/subagent/deliverable.js +39 -0
- package/dist/subagent/pane-supervisor.js +8 -17
- package/dist/subagent/result-artifacts.js +25 -0
- package/dist/subagent/supervisor.js +5 -5
- package/dist/types.js +0 -7
- package/package.json +2 -4
- package/dist/subagent/ipc-protocol.js +0 -68
- package/dist/subagent/ipc.js +0 -110
- package/dist/subagent/socket-ipc.js +0 -240
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
import { Buffer } from "buffer";
|
|
2
|
+
const characters = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
|
|
3
|
+
const checksumCharacters = "*~$=U";
|
|
4
|
+
export class InvalidChecksumCharacterError extends Error {
|
|
5
|
+
constructor(message) {
|
|
6
|
+
super(message);
|
|
7
|
+
this.name = "InvalidChecksumCharacterError";
|
|
8
|
+
// oxlint-disable-next-line typescript/no-unnecessary-condition -- captureStackTrace is a V8 extension, absent on other engines
|
|
9
|
+
if (Error.captureStackTrace) {
|
|
10
|
+
Error.captureStackTrace(this, this.constructor);
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
export class InvalidChecksumError extends Error {
|
|
15
|
+
constructor(message) {
|
|
16
|
+
super(message);
|
|
17
|
+
this.name = "InvalidChecksumError";
|
|
18
|
+
// oxlint-disable-next-line typescript/no-unnecessary-condition -- captureStackTrace is a V8 extension, absent on other engines
|
|
19
|
+
if (Error.captureStackTrace) {
|
|
20
|
+
Error.captureStackTrace(this, this.constructor);
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* An implementation of the Crockford Base32 algorithm.
|
|
26
|
+
*
|
|
27
|
+
* Spec: https://www.crockford.com/base32.html
|
|
28
|
+
*/
|
|
29
|
+
export class CrockfordBase32 {
|
|
30
|
+
static encode(input, options) {
|
|
31
|
+
if (Buffer.isBuffer(input)) {
|
|
32
|
+
input = Buffer.from(input);
|
|
33
|
+
}
|
|
34
|
+
else {
|
|
35
|
+
input = this.createBuffer(input);
|
|
36
|
+
}
|
|
37
|
+
const variant = options?.variant ?? "crockford";
|
|
38
|
+
const checksum = options?.checksum ?? false;
|
|
39
|
+
if (variant === "ulid") {
|
|
40
|
+
if (checksum) {
|
|
41
|
+
throw new Error("Checksums are not supported with the ulid variant");
|
|
42
|
+
}
|
|
43
|
+
return this.encodeUlid(input);
|
|
44
|
+
}
|
|
45
|
+
const output = [];
|
|
46
|
+
let bitsRead = 0;
|
|
47
|
+
let buffer = 0;
|
|
48
|
+
for (const byte of input) {
|
|
49
|
+
// Add current byte to start of buffer
|
|
50
|
+
buffer = (buffer << 8) | byte;
|
|
51
|
+
bitsRead += 8;
|
|
52
|
+
while (bitsRead >= 5) {
|
|
53
|
+
output.push((buffer >>> (bitsRead - 5)) & 0x1f);
|
|
54
|
+
bitsRead -= 5;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
if (bitsRead > 0) {
|
|
58
|
+
output.push((buffer << (5 - bitsRead)) & 0x1f);
|
|
59
|
+
}
|
|
60
|
+
let result = output.map((byte) => characters.charAt(byte)).join("");
|
|
61
|
+
if (checksum) {
|
|
62
|
+
result += this.computeChecksum(input);
|
|
63
|
+
}
|
|
64
|
+
return result;
|
|
65
|
+
}
|
|
66
|
+
static computeChecksum(bytes) {
|
|
67
|
+
// Crockford's check symbol is value mod 37, where value is the number the
|
|
68
|
+
// symbols represent. Fold byte-by-byte to avoid materializing a bigint;
|
|
69
|
+
// acc stays < 37 so (acc * 256 + byte) fits comfortably in a JS number.
|
|
70
|
+
let acc = 0;
|
|
71
|
+
for (const byte of bytes) {
|
|
72
|
+
acc = (acc * 256 + byte) % 37;
|
|
73
|
+
}
|
|
74
|
+
return (characters + checksumCharacters).charAt(acc);
|
|
75
|
+
}
|
|
76
|
+
static decode(input, options) {
|
|
77
|
+
// 1. Translate input to all uppercase
|
|
78
|
+
// 2. Translate I, L, and O to valid base 32 characters
|
|
79
|
+
// 3. Remove all hyphens
|
|
80
|
+
input = input
|
|
81
|
+
.toUpperCase()
|
|
82
|
+
.replace(/O/g, "0")
|
|
83
|
+
.replace(/[IL]/g, "1")
|
|
84
|
+
.replace(/-+/g, "");
|
|
85
|
+
const variant = options?.variant ?? "crockford";
|
|
86
|
+
const checksum = options?.checksum ?? false;
|
|
87
|
+
if (variant === "ulid") {
|
|
88
|
+
if (checksum) {
|
|
89
|
+
throw new Error("Checksums are not supported with the ulid variant");
|
|
90
|
+
}
|
|
91
|
+
return this.decodeUlid(input, options);
|
|
92
|
+
}
|
|
93
|
+
let providedCheck = null;
|
|
94
|
+
if (checksum) {
|
|
95
|
+
if (input.length === 0) {
|
|
96
|
+
throw new InvalidChecksumCharacterError("Cannot validate checksum: input is empty");
|
|
97
|
+
}
|
|
98
|
+
const last = input.charAt(input.length - 1);
|
|
99
|
+
if ((characters + checksumCharacters).indexOf(last) === -1) {
|
|
100
|
+
throw new InvalidChecksumCharacterError(`Invalid checksum character: ${last}`);
|
|
101
|
+
}
|
|
102
|
+
providedCheck = last;
|
|
103
|
+
input = input.slice(0, -1);
|
|
104
|
+
}
|
|
105
|
+
const output = [];
|
|
106
|
+
let bitsRead = 0;
|
|
107
|
+
let buffer = 0;
|
|
108
|
+
for (const character of input) {
|
|
109
|
+
const byte = characters.indexOf(character);
|
|
110
|
+
if (byte === -1) {
|
|
111
|
+
throw new Error(`Invalid base 32 character found in string: ${character}`);
|
|
112
|
+
}
|
|
113
|
+
bitsRead += 5;
|
|
114
|
+
if (bitsRead >= 8) {
|
|
115
|
+
bitsRead -= 8;
|
|
116
|
+
output.push(buffer | (byte >> bitsRead));
|
|
117
|
+
buffer = (byte << (8 - bitsRead)) & 0xff;
|
|
118
|
+
}
|
|
119
|
+
else {
|
|
120
|
+
buffer |= byte << (8 - bitsRead);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
// Flush a trailing partial byte when it carries data: either bits are
|
|
124
|
+
// non-zero, or a whole character (>= 5 bits) went unpaired and so cannot
|
|
125
|
+
// be canonical zero padding.
|
|
126
|
+
if (buffer > 0 || bitsRead >= 5) {
|
|
127
|
+
output.push(buffer);
|
|
128
|
+
}
|
|
129
|
+
if (providedCheck !== null) {
|
|
130
|
+
const computedCheck = this.computeChecksum(output);
|
|
131
|
+
if (providedCheck !== computedCheck) {
|
|
132
|
+
throw new InvalidChecksumError(`Checksum mismatch: expected '${computedCheck}' but found '${providedCheck}'`);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
if (options?.asNumber === true) {
|
|
136
|
+
return this.asNumber(output);
|
|
137
|
+
}
|
|
138
|
+
return this.asBuffer(output);
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* Validates whether `input` is a Crockford Base32 string with a correct
|
|
142
|
+
* trailing check symbol. Returns false for any malformed input (invalid
|
|
143
|
+
* characters, mismatched checksum, empty string), never throws.
|
|
144
|
+
*
|
|
145
|
+
* Use {@link decode} with `{ checksum: true }` if you need typed errors.
|
|
146
|
+
*/
|
|
147
|
+
static verify(input) {
|
|
148
|
+
try {
|
|
149
|
+
this.decode(input, { checksum: true });
|
|
150
|
+
return true;
|
|
151
|
+
}
|
|
152
|
+
catch {
|
|
153
|
+
return false;
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
static encodeUlid(input) {
|
|
157
|
+
// Keep empty binary input empty so Buffer round-trips do not become 0x00.
|
|
158
|
+
if (input.length === 0) {
|
|
159
|
+
return "";
|
|
160
|
+
}
|
|
161
|
+
// ULID variant uses modulo-based encoding (right-to-left, padding left)
|
|
162
|
+
// Convert buffer to bigint
|
|
163
|
+
let value = 0n;
|
|
164
|
+
for (const byte of input) {
|
|
165
|
+
value = (value << 8n) | BigInt(byte);
|
|
166
|
+
}
|
|
167
|
+
// Use repeated division by 32 to extract base32 digits
|
|
168
|
+
const output = [];
|
|
169
|
+
while (value > 0n) {
|
|
170
|
+
const remainder = Number(value % 32n);
|
|
171
|
+
output.unshift(characters.charAt(remainder));
|
|
172
|
+
value /= 32n;
|
|
173
|
+
}
|
|
174
|
+
// Pad to the expected length based on input size
|
|
175
|
+
// Each base32 character encodes 5 bits, so n bytes = n*8 bits
|
|
176
|
+
// require ceil(n*8/5) characters
|
|
177
|
+
const expectedLength = Math.ceil((input.length * 8) / 5);
|
|
178
|
+
return output.join("").padStart(expectedLength, "0");
|
|
179
|
+
}
|
|
180
|
+
static decodeUlid(input, options) {
|
|
181
|
+
// Empty encoded data represents no bytes; asNumber has no empty numeric
|
|
182
|
+
// value, so return the same numeric zero used by other empty decodes.
|
|
183
|
+
if (input.length === 0) {
|
|
184
|
+
return options?.asNumber === true ? 0n : Buffer.from([]);
|
|
185
|
+
}
|
|
186
|
+
// ULID variant uses modulo-based decoding (reverse of encoding)
|
|
187
|
+
// Treat the base32 string as a number in base 32
|
|
188
|
+
let value = 0n;
|
|
189
|
+
for (const character of input) {
|
|
190
|
+
const digit = characters.indexOf(character);
|
|
191
|
+
if (digit === -1) {
|
|
192
|
+
throw new Error(`Invalid base 32 character found in string: ${character}`);
|
|
193
|
+
}
|
|
194
|
+
value = value * 32n + BigInt(digit);
|
|
195
|
+
}
|
|
196
|
+
// Calculate expected output length based on input string length
|
|
197
|
+
// Each base32 character represents 5 bits, so n characters = n*5 bits
|
|
198
|
+
// We use floor because the encoder may have added padding characters
|
|
199
|
+
// to reach the expected length, creating extra bits we should ignore
|
|
200
|
+
const expectedBytes = Math.floor((input.length * 5) / 8);
|
|
201
|
+
// Convert bigint to byte array
|
|
202
|
+
const output = [];
|
|
203
|
+
let temp = value;
|
|
204
|
+
while (temp > 0n) {
|
|
205
|
+
output.unshift(Number(temp & 0xffn));
|
|
206
|
+
temp >>= 8n;
|
|
207
|
+
}
|
|
208
|
+
// For all-zero input the bigint loop emits no bytes, so seed one zero
|
|
209
|
+
// byte. The padding loop below then extends to expectedBytes when needed
|
|
210
|
+
// (e.g. "0000" -> two bytes); single-character "0" decodes to one byte
|
|
211
|
+
// even though expectedBytes is 0.
|
|
212
|
+
if (value === 0n) {
|
|
213
|
+
output.push(0);
|
|
214
|
+
}
|
|
215
|
+
// Pad with leading zeros to match expected length
|
|
216
|
+
while (output.length < expectedBytes) {
|
|
217
|
+
output.unshift(0);
|
|
218
|
+
}
|
|
219
|
+
if (options?.asNumber === true) {
|
|
220
|
+
return this.asNumber(output);
|
|
221
|
+
}
|
|
222
|
+
return this.asBuffer(output);
|
|
223
|
+
}
|
|
224
|
+
static createBuffer(input) {
|
|
225
|
+
if (typeof input === "number") {
|
|
226
|
+
if (!Number.isSafeInteger(input)) {
|
|
227
|
+
throw new Error("Input must be a safe integer");
|
|
228
|
+
}
|
|
229
|
+
input = BigInt(input);
|
|
230
|
+
}
|
|
231
|
+
if (input < 0n) {
|
|
232
|
+
throw new Error("Input cannot be a negative number");
|
|
233
|
+
}
|
|
234
|
+
const bytes = [];
|
|
235
|
+
while (input > 0n) {
|
|
236
|
+
bytes.unshift(Number(input & 0xffn));
|
|
237
|
+
input >>= 8n;
|
|
238
|
+
}
|
|
239
|
+
return Buffer.from(bytes);
|
|
240
|
+
}
|
|
241
|
+
static asNumber(output) {
|
|
242
|
+
let outputNumber = 0n;
|
|
243
|
+
output.forEach((byte) => {
|
|
244
|
+
outputNumber <<= 8n;
|
|
245
|
+
outputNumber |= BigInt(byte);
|
|
246
|
+
});
|
|
247
|
+
return outputNumber;
|
|
248
|
+
}
|
|
249
|
+
static asBuffer(output) {
|
|
250
|
+
return Buffer.from(output.map((byte) => byte.toString(16).padStart(2, "0")).join(""), "hex");
|
|
251
|
+
}
|
|
252
|
+
}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { getPiInstance, getRuntime } from "../shell.js";
|
|
9
9
|
import { hasOutcome, lifecycleStatus, } from "../types.js";
|
|
10
|
-
import { buildAgentDetails, formatResultContent, } from "../orchestrators/protocol.js";
|
|
10
|
+
import { buildAgentDetails, formatResultContent, settledHeadline, } from "../orchestrators/protocol.js";
|
|
11
11
|
import { findTaskDedup, TaskAlreadyInFlightError, } from "../task-registry.js";
|
|
12
12
|
import { isExtensionEnabled } from "../extension-toggle.js";
|
|
13
13
|
import { actionReport } from "../ui/action-report.js";
|
|
@@ -224,7 +224,7 @@ export class SpawnCoordinator {
|
|
|
224
224
|
// so a completion never interrupts work the orchestrator already started.
|
|
225
225
|
pi.sendMessage({
|
|
226
226
|
customType: "subagent-result",
|
|
227
|
-
content:
|
|
227
|
+
content: `${settledHeadline(spawn)}\n\n${formatResultContent(spawn)}`,
|
|
228
228
|
details,
|
|
229
229
|
display: true,
|
|
230
230
|
}, {
|
package/dist/spawn/spawn-id.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* Uniqueness is the caller's business — see generateUniqueSpawnId.
|
|
6
6
|
*/
|
|
7
7
|
import { randomBytes } from "node:crypto";
|
|
8
|
-
import { CrockfordBase32 } from "crockford-base32";
|
|
8
|
+
import { CrockfordBase32 } from "./crockford-base32.js";
|
|
9
9
|
/** Spawn-id alphabet (lowercase Crockford base32); src/predicates.ts derives its pattern from this. */
|
|
10
10
|
export const SPAWN_ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
|
|
11
11
|
/** Exact length of every spawn id (40 bits ⇒ 8 base32 chars). */
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* deliverable.ts — the child's report: the file it writes, the parent's read of
|
|
3
|
+
* it.
|
|
4
|
+
*
|
|
5
|
+
* A run's deliverable is a file on disk, not a message. The child is told where
|
|
6
|
+
* to write it by its prompt, and the parent reads it here. No protocol carries
|
|
7
|
+
* it, and nothing here needs the child to run the extension.
|
|
8
|
+
*/
|
|
9
|
+
import fs from "node:fs";
|
|
10
|
+
/**
|
|
11
|
+
* The deliverable as the run's result file. Parent and child derive the path
|
|
12
|
+
* independently (`subagentResultFileFor`), so no path ever travels between them.
|
|
13
|
+
*/
|
|
14
|
+
export class FileDeliverable {
|
|
15
|
+
resultFile;
|
|
16
|
+
constructor(resultFile) {
|
|
17
|
+
this.resultFile = resultFile;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* The child's last report, or null when it is absent, unreadable, or blank —
|
|
21
|
+
* the run has not finished. The content rides with the file's modification
|
|
22
|
+
* time, because a rewritten report of the same words is still news. The stamp
|
|
23
|
+
* is sampled before the content: a write landing between the two calls leaves
|
|
24
|
+
* the pair understating the file rather than overstating it, and the next poll
|
|
25
|
+
* corrects it.
|
|
26
|
+
*/
|
|
27
|
+
async readDeliverable() {
|
|
28
|
+
try {
|
|
29
|
+
const mtime = fs.statSync(this.resultFile).mtimeMs;
|
|
30
|
+
const content = fs.readFileSync(this.resultFile, "utf-8").trim();
|
|
31
|
+
if (!content)
|
|
32
|
+
return null;
|
|
33
|
+
return { content, mtime };
|
|
34
|
+
}
|
|
35
|
+
catch {
|
|
36
|
+
return null;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
@@ -1,24 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* pane-supervisor.ts — Build the supervisor for one child process in a pane.
|
|
3
3
|
*
|
|
4
|
-
* Both attempt origins need the same construction:
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* watch all stay with the caller, which owns the placement and the checkpoint
|
|
10
|
-
* that may discard it, and which also drives the channel (IPC start/close).
|
|
4
|
+
* Both attempt origins need the same construction: the deliverable the
|
|
5
|
+
* supervisor polls, wrapped in a ProcessSupervisorEngine. This module builds
|
|
6
|
+
* that and nothing else — launching the process (start), binding a live one
|
|
7
|
+
* (adopt), and beginning the watch all stay with the caller, which owns the
|
|
8
|
+
* placement and the checkpoint that may discard it.
|
|
11
9
|
*/
|
|
12
10
|
import { ProcessSupervisorEngine, } from "./supervisor.js";
|
|
13
|
-
/** Wire the
|
|
11
|
+
/** Wire the deliverable and the engine over it. Starts, adopts, and watches nothing. */
|
|
14
12
|
export function createPaneSupervisor(input) {
|
|
15
|
-
const
|
|
16
|
-
|
|
17
|
-
resultFile: input.resultFile,
|
|
18
|
-
onFrame: input.onFrame,
|
|
19
|
-
});
|
|
20
|
-
return {
|
|
21
|
-
supervisor: new ProcessSupervisorEngine(input.host, ipc, input.supervisorOptions),
|
|
22
|
-
ipc,
|
|
23
|
-
};
|
|
13
|
+
const deliverable = input.transport.createDeliverable(input.resultFile);
|
|
14
|
+
return new ProcessSupervisorEngine(input.host, deliverable, input.supervisorOptions);
|
|
24
15
|
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* result-artifacts.ts — the staging directory a run's files live in.
|
|
3
|
+
*
|
|
4
|
+
* A spawn stages its briefing, prompt, and report under
|
|
5
|
+
* `<tmpdir>/pi-cowboy/<agentId>/` (see paths.ts). Those files are ephemeral, so
|
|
6
|
+
* the directory's whole lifecycle here is "remove it once nothing can report
|
|
7
|
+
* into it".
|
|
8
|
+
*/
|
|
9
|
+
import fs from "node:fs";
|
|
10
|
+
import * as path from "node:path";
|
|
11
|
+
/**
|
|
12
|
+
* Remove a run's result directory. Best effort, and safe when it is already
|
|
13
|
+
* gone — the files are ephemeral temp-dir artifacts.
|
|
14
|
+
*
|
|
15
|
+
* The artifacts outlive settlement: a settled run stays watched, so the child
|
|
16
|
+
* may keep writing reports to this same directory until the run is dropped.
|
|
17
|
+
*/
|
|
18
|
+
export function removeResultArtifacts(resultFile) {
|
|
19
|
+
try {
|
|
20
|
+
fs.rmSync(path.dirname(resultFile), { recursive: true, force: true });
|
|
21
|
+
}
|
|
22
|
+
catch {
|
|
23
|
+
// Best effort: the agent's files are ephemeral temp-dir artifacts.
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
* watch() never settles.
|
|
21
21
|
* - Artifacts are NOT this engine's to remove: a settled run stays watched, so
|
|
22
22
|
* its result directory survives settlement and is removed when the run is
|
|
23
|
-
* dropped (see removeResultArtifacts).
|
|
23
|
+
* dropped (see removeResultArtifacts in result-artifacts.ts).
|
|
24
24
|
* - One supervisor per run: re-delegation and revive each use a fresh instance.
|
|
25
25
|
*/
|
|
26
26
|
import { createLogger } from "../logger.js";
|
|
@@ -38,7 +38,7 @@ function deferred() {
|
|
|
38
38
|
}
|
|
39
39
|
export class ProcessSupervisorEngine {
|
|
40
40
|
host;
|
|
41
|
-
|
|
41
|
+
deliverable;
|
|
42
42
|
pollMs;
|
|
43
43
|
stopInitiator;
|
|
44
44
|
onFollowUp;
|
|
@@ -59,9 +59,9 @@ export class ProcessSupervisorEngine {
|
|
|
59
59
|
/** A report seen once; a report still being written is not final. */
|
|
60
60
|
held = null;
|
|
61
61
|
watchStartedAt = 0;
|
|
62
|
-
constructor(host,
|
|
62
|
+
constructor(host, deliverable, options = {}) {
|
|
63
63
|
this.host = host;
|
|
64
|
-
this.
|
|
64
|
+
this.deliverable = deliverable;
|
|
65
65
|
this.pollMs = options.pollMs ?? DEFAULT_POLL_MS;
|
|
66
66
|
this.stopInitiator = options.stopInitiator ?? "user";
|
|
67
67
|
this.onFollowUp = options.onFollowUp;
|
|
@@ -295,7 +295,7 @@ export class ProcessSupervisorEngine {
|
|
|
295
295
|
/** One artifact read; a failed read is a poll with nothing in it. */
|
|
296
296
|
async readDeliverable() {
|
|
297
297
|
try {
|
|
298
|
-
return await this.
|
|
298
|
+
return await this.deliverable.readDeliverable();
|
|
299
299
|
}
|
|
300
300
|
catch (err) {
|
|
301
301
|
log.debug("readDeliverable failed", {
|
package/dist/types.js
CHANGED
|
@@ -1,10 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* pi reads a file whenever `--system-prompt`'s value is an existing path, so
|
|
3
|
-
* multi-line instructions ride out of herdr's single-line argv.
|
|
4
|
-
*/
|
|
5
|
-
export const SUBAGENT_SYSTEM_FILE_NAME = "system.md";
|
|
6
|
-
/** The pane's `@<file>` initial message; holds the task text and nothing else. */
|
|
7
|
-
export const SUBAGENT_TASK_FILE_NAME = "prompt.md";
|
|
8
1
|
/**
|
|
9
2
|
* Built-in fallbacks for the configurable spawn defaults. A persisted setting
|
|
10
3
|
* that is unset or names a type/template that no longer resolves degrades to
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-cowboy",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"packageManager": "pnpm@12.9.1",
|
|
6
6
|
"description": "Agent orchestrator for pi: each subagent runs as its own pi process in a background Herdr pane, isolated by a copy-on-write git worktree.",
|
|
@@ -96,7 +96,7 @@
|
|
|
96
96
|
"eslint": "^10.12.0",
|
|
97
97
|
"eslint-plugin-import-x": "^4.17.1",
|
|
98
98
|
"husky": "^9.1.7",
|
|
99
|
-
"oxlint": "1.
|
|
99
|
+
"oxlint": "1.87.0",
|
|
100
100
|
"oxlint-tsgolint": "7.0.2003",
|
|
101
101
|
"prettier": "^3.9.9",
|
|
102
102
|
"semantic-release": "^25.0.9",
|
|
@@ -104,8 +104,6 @@
|
|
|
104
104
|
"vitest": "^5.0.3"
|
|
105
105
|
},
|
|
106
106
|
"dependencies": {
|
|
107
|
-
"caller-id": "^0.1.0",
|
|
108
|
-
"crockford-base32": "^2.1.0",
|
|
109
107
|
"mustache": "^4.2.0",
|
|
110
108
|
"smol-toml": "^1.9.0",
|
|
111
109
|
"zod": "^4.6.5"
|
|
@@ -1,68 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* ipc-protocol.ts — the readiness handshake both ends share.
|
|
3
|
-
*
|
|
4
|
-
* The parent binds a per-agent endpoint before launching a subagent; the child
|
|
5
|
-
* pi process connects at boot and sends one ready frame carrying its own pid.
|
|
6
|
-
* The frame shape, its validation, and the child's one call live together here
|
|
7
|
-
* so the two ends cannot drift.
|
|
8
|
-
*/
|
|
9
|
-
import { createLogger } from "../logger.js";
|
|
10
|
-
import { detectSubagentSpawn } from "../shell.js";
|
|
11
|
-
import { errorMessage } from "../utils.js";
|
|
12
|
-
import { createIpcClient, getIpcAddress, } from "./socket-ipc.js";
|
|
13
|
-
const log = createLogger("handshake");
|
|
14
|
-
/** The ready frame a child sends for itself; `pid` is a parameter so no test needs a child process. */
|
|
15
|
-
export function readyFrameFor(agentId, pid = process.pid) {
|
|
16
|
-
return { kind: "ready", agentId, pid };
|
|
17
|
-
}
|
|
18
|
-
/** Narrow an untrusted frame to the recognized union; null for anything unrecognized. */
|
|
19
|
-
export function parseSubagentFrame(value) {
|
|
20
|
-
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
21
|
-
return null;
|
|
22
|
-
}
|
|
23
|
-
const { kind, agentId, pid } = value;
|
|
24
|
-
if (kind !== "ready")
|
|
25
|
-
return null;
|
|
26
|
-
if (typeof agentId !== "string" || agentId === "")
|
|
27
|
-
return null;
|
|
28
|
-
if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
|
|
29
|
-
return null;
|
|
30
|
-
return { kind: "ready", agentId, pid };
|
|
31
|
-
}
|
|
32
|
-
/**
|
|
33
|
-
* Tell the parent this process booted. Fire-and-forget and never throwing: the
|
|
34
|
-
* parent may have no listener (extensions disabled, a listener that failed to
|
|
35
|
-
* bind), and a missing handshake must not disturb the subagent's own work.
|
|
36
|
-
*/
|
|
37
|
-
export function announceSubagentReady(agentId, deps = {}) {
|
|
38
|
-
const createClient = deps.createClient ?? createIpcClient;
|
|
39
|
-
void sendReady(agentId, createClient).catch((error) => {
|
|
40
|
-
log.warn("subagent readiness handshake failed", {
|
|
41
|
-
agentId,
|
|
42
|
-
errorMessage: errorMessage(error),
|
|
43
|
-
});
|
|
44
|
-
});
|
|
45
|
-
}
|
|
46
|
-
/**
|
|
47
|
-
* The delegated process's boot action. True when this argv carries a subagent
|
|
48
|
-
* token (the caller stays inert — and the parent was told); false for a root
|
|
49
|
-
* session, which announces nothing.
|
|
50
|
-
*/
|
|
51
|
-
export function announceReadyForSpawn(argv = process.argv, announce = announceSubagentReady) {
|
|
52
|
-
const agentId = detectSubagentSpawn(argv);
|
|
53
|
-
if (agentId === undefined)
|
|
54
|
-
return false;
|
|
55
|
-
announce(agentId);
|
|
56
|
-
return true;
|
|
57
|
-
}
|
|
58
|
-
async function sendReady(agentId, createClient) {
|
|
59
|
-
const client = await createClient(getIpcAddress(agentId));
|
|
60
|
-
try {
|
|
61
|
-
const frame = { ...readyFrameFor(agentId) };
|
|
62
|
-
client.send(frame);
|
|
63
|
-
}
|
|
64
|
-
finally {
|
|
65
|
-
// Flush the frame, then close; a disconnect failure cannot undo delivery.
|
|
66
|
-
await client.disconnect().catch(() => { });
|
|
67
|
-
}
|
|
68
|
-
}
|
package/dist/subagent/ipc.js
DELETED
|
@@ -1,110 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* subagent/ipc.ts — SubagentIPC: the parent↔subagent message plane.
|
|
3
|
-
*
|
|
4
|
-
* The parent half is the HerdrSubagentIPC: a result file the child writes and
|
|
5
|
-
* the readiness endpoint the child announces its boot on.
|
|
6
|
-
*/
|
|
7
|
-
import fs from "node:fs";
|
|
8
|
-
import * as path from "node:path";
|
|
9
|
-
import { createLogger } from "../logger.js";
|
|
10
|
-
import { errorMessage } from "../utils.js";
|
|
11
|
-
import { parseSubagentFrame } from "./ipc-protocol.js";
|
|
12
|
-
import { createIpcServer, getIpcAddress, } from "./socket-ipc.js";
|
|
13
|
-
const log = createLogger("ipc");
|
|
14
|
-
/** SubagentIPC for a subagent in a herdr pane: files, readiness channel, teardown. */
|
|
15
|
-
export class HerdrSubagentIPC {
|
|
16
|
-
agentId;
|
|
17
|
-
resultFile;
|
|
18
|
-
onFrame;
|
|
19
|
-
channel = null;
|
|
20
|
-
constructor(options) {
|
|
21
|
-
this.agentId = options.agentId;
|
|
22
|
-
this.resultFile = options.resultFile;
|
|
23
|
-
this.onFrame = options.onFrame;
|
|
24
|
-
}
|
|
25
|
-
/**
|
|
26
|
-
* Bind the run's endpoint. Resolves once listening, so the caller launches the
|
|
27
|
-
* child only when the parent is already reachable. One bind per run.
|
|
28
|
-
*/
|
|
29
|
-
async start() {
|
|
30
|
-
if (this.channel !== null)
|
|
31
|
-
return;
|
|
32
|
-
const address = getIpcAddress(this.agentId);
|
|
33
|
-
this.channel = await createIpcServer(address, {
|
|
34
|
-
onMessage: (message) => this.handleFrame(message),
|
|
35
|
-
onError: (error) => log.warn("readiness channel error", {
|
|
36
|
-
agentId: this.agentId,
|
|
37
|
-
errorMessage: errorMessage(error),
|
|
38
|
-
}),
|
|
39
|
-
});
|
|
40
|
-
log.debug("readiness channel bound", { agentId: this.agentId, address });
|
|
41
|
-
}
|
|
42
|
-
/** Idempotent: close the channel and unlink the endpoint. */
|
|
43
|
-
async close() {
|
|
44
|
-
const server = this.channel;
|
|
45
|
-
if (server === null)
|
|
46
|
-
return;
|
|
47
|
-
this.channel = null;
|
|
48
|
-
await server.close().catch((error) => {
|
|
49
|
-
log.warn("readiness channel close failed", {
|
|
50
|
-
agentId: this.agentId,
|
|
51
|
-
errorMessage: errorMessage(error),
|
|
52
|
-
});
|
|
53
|
-
});
|
|
54
|
-
}
|
|
55
|
-
/**
|
|
56
|
-
* One frame from the child. A frame this run cannot claim — unparseable, or
|
|
57
|
-
* naming another agent — is dropped; the channel stays up either way.
|
|
58
|
-
*/
|
|
59
|
-
handleFrame(message) {
|
|
60
|
-
const frame = parseSubagentFrame(message);
|
|
61
|
-
if (frame === null) {
|
|
62
|
-
log.debug("ignoring unrecognized frame", { agentId: this.agentId });
|
|
63
|
-
return;
|
|
64
|
-
}
|
|
65
|
-
if (frame.agentId !== this.agentId) {
|
|
66
|
-
log.warn("ignoring frame for another agent", {
|
|
67
|
-
agentId: this.agentId,
|
|
68
|
-
announcedAgentId: frame.agentId,
|
|
69
|
-
});
|
|
70
|
-
return;
|
|
71
|
-
}
|
|
72
|
-
log.debug("received frame", { agentId: this.agentId, kind: frame.kind });
|
|
73
|
-
this.onFrame?.(frame);
|
|
74
|
-
}
|
|
75
|
-
/**
|
|
76
|
-
* The child's last report, or null when it is absent, unreadable, or blank —
|
|
77
|
-
* the run has not finished. The content rides with the file's modification
|
|
78
|
-
* time, because a rewritten report of the same words is still news. The stamp
|
|
79
|
-
* is sampled before the content: a write landing between the two calls leaves
|
|
80
|
-
* the pair understating the file rather than overstating it, and the next poll
|
|
81
|
-
* corrects it.
|
|
82
|
-
*/
|
|
83
|
-
async readDeliverable() {
|
|
84
|
-
try {
|
|
85
|
-
const mtime = fs.statSync(this.resultFile).mtimeMs;
|
|
86
|
-
const content = fs.readFileSync(this.resultFile, "utf-8").trim();
|
|
87
|
-
if (!content)
|
|
88
|
-
return null;
|
|
89
|
-
return { content, mtime };
|
|
90
|
-
}
|
|
91
|
-
catch {
|
|
92
|
-
return null;
|
|
93
|
-
}
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
|
-
/**
|
|
97
|
-
* Remove a run's result directory. Best effort, and safe when it is already
|
|
98
|
-
* gone — the files are ephemeral temp-dir artifacts.
|
|
99
|
-
*
|
|
100
|
-
* The artifacts outlive settlement: a settled run stays watched, so the child
|
|
101
|
-
* may keep writing reports to this same directory until the run is dropped.
|
|
102
|
-
*/
|
|
103
|
-
export function removeResultArtifacts(resultFile) {
|
|
104
|
-
try {
|
|
105
|
-
fs.rmSync(path.dirname(resultFile), { recursive: true, force: true });
|
|
106
|
-
}
|
|
107
|
-
catch {
|
|
108
|
-
// Best effort: the agent's files are ephemeral temp-dir artifacts.
|
|
109
|
-
}
|
|
110
|
-
}
|