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.
@@ -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: `[Cowboy agent "${spawn.display.type}" ${spawn.id} ${lifecycleStatus(spawn.lifecycle)}]\n\n${formatResultContent(spawn)}`,
227
+ content: `${settledHeadline(spawn)}\n\n${formatResultContent(spawn)}`,
228
228
  details,
229
229
  display: true,
230
230
  }, {
@@ -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: a SubagentIPC whose
5
- * onFrame carries the child's frames, wrapped in a ProcessSupervisorEngine (a
6
- * constructor that takes exactly that IPC). This module builds that pair and
7
- * nothing else —
8
- * launching the process (start), binding a live one (adopt), and beginning the
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 IPC and the engine over it. Starts, adopts, watches, and binds nothing. */
11
+ /** Wire the deliverable and the engine over it. Starts, adopts, and watches nothing. */
14
12
  export function createPaneSupervisor(input) {
15
- const ipc = input.transport.createIpc({
16
- agentId: input.agentId,
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
- ipc;
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, ipc, options = {}) {
62
+ constructor(host, deliverable, options = {}) {
63
63
  this.host = host;
64
- this.ipc = ipc;
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.ipc.readDeliverable();
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.5",
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.86.0",
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
- }
@@ -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
- }