@narumitw/pi-subagents 3.0.1 → 3.1.0

package/src/child-communication-bridge.ts

@@ -1,153 +1,145 @@
 import net from "node:net";
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
-import { captureBrokerCredentials } from "./broker-credentials.js";
-import {
-	type ChildCommunicationClient,
-	createChildCommunicationExtension,
-} from "./child-communication-tools.js";
+import { captureChildBootstrap } from "./broker-credentials.js";
+import { type ChildCommunicationClient, createChildCommunicationExtension } from "./child-communication-tools.js";
 import { MAX_FRAME_BYTES, MAX_IDENTIFIER_LENGTH } from "./message-broker.js";
 import type { BrokerCredentials } from "./types.js";
 
 const CONNECT_TIMEOUT_MS = 2_000;
 const SEND_RESPONSE_TIMEOUT_MS = 5_000;
 
-const captured = captureBrokerCredentials();
+const captured = captureChildBootstrap();
 
 const childCommunicationBridge: ExtensionFactory = captured
-	? createChildCommunicationExtension(createBrokerClient(captured))
-	: () => undefined;
+  ? createChildCommunicationExtension(createBrokerClient(captured.communication))
+  : () => undefined;
 
 export default childCommunicationBridge;
 
 export function createBrokerClient(credentials: BrokerCredentials): ChildCommunicationClient {
-	return {
-		async send(params, signal) {
-			const response = await requestBroker(
-				credentials,
-				{ type: "send", token: credentials.token, ...params },
-				signal,
-				SEND_RESPONSE_TIMEOUT_MS,
-			);
-			if (response.ok !== true) throw brokerError(response);
-			if (
-				typeof response.requestId !== "string" ||
-				!response.requestId ||
-				response.requestId.length > MAX_IDENTIFIER_LENGTH ||
-				typeof response.accepted !== "boolean" ||
-				typeof response.duplicate !== "boolean"
-			) {
-				throw new Error("Subagent broker returned an invalid send acknowledgement.");
-			}
-			return {
-				requestId: response.requestId,
-				accepted: response.accepted,
-				duplicate: response.duplicate,
-			};
-		},
-		async wait(requestId, timeoutMs, signal) {
-			const response = await requestBroker(
-				credentials,
-				{
-					type: "wait",
-					token: credentials.token,
-					requestId,
-					...(timeoutMs !== undefined ? { timeoutMs } : {}),
-				},
-				signal,
-			);
-			if (response.ok !== true) throw brokerError(response);
-			if (typeof response.response !== "string") {
-				throw new Error("Subagent broker returned an invalid plain-text response.");
-			}
-			return response.response;
-		},
-	};
+  return {
+    async send(params, signal) {
+      const response = await requestBroker(
+        credentials,
+        { type: "send", token: credentials.token, ...params },
+        signal,
+        SEND_RESPONSE_TIMEOUT_MS,
+      );
+      if (response.ok !== true) throw brokerError(response);
+      if (
+        typeof response.requestId !== "string" ||
+        !response.requestId ||
+        response.requestId.length > MAX_IDENTIFIER_LENGTH ||
+        typeof response.accepted !== "boolean" ||
+        typeof response.duplicate !== "boolean"
+      ) {
+        throw new Error("Subagent broker returned an invalid send acknowledgement.");
+      }
+      return {
+        requestId: response.requestId,
+        accepted: response.accepted,
+        duplicate: response.duplicate,
+      };
+    },
+    async wait(requestId, timeoutMs, signal) {
+      const response = await requestBroker(
+        credentials,
+        {
+          type: "wait",
+          token: credentials.token,
+          requestId,
+          ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        },
+        signal,
+      );
+      if (response.ok !== true) throw brokerError(response);
+      if (typeof response.response !== "string") {
+        throw new Error("Subagent broker returned an invalid plain-text response.");
+      }
+      return response.response;
+    },
+  };
 }
 
 function requestBroker(
-	credentials: BrokerCredentials,
-	request: Record<string, unknown>,
-	signal?: AbortSignal,
-	responseTimeoutMs?: number,
+  credentials: BrokerCredentials,
+  request: Record<string, unknown>,
+  signal?: AbortSignal,
+  responseTimeoutMs?: number,
 ): Promise<Record<string, unknown>> {
-	if (signal?.aborted) return Promise.reject(abortError("Subagent broker request was cancelled."));
-	return new Promise((resolve, reject) => {
-		const socket = net.createConnection({ host: credentials.host, port: credentials.port });
-		let response = Buffer.alloc(0);
-		let settled = false;
-		let responseTimer: NodeJS.Timeout | undefined;
-		const connectTimer = setTimeout(
-			() => finish(new Error("Subagent broker connection timed out.")),
-			CONNECT_TIMEOUT_MS,
-		);
-		connectTimer.unref();
-		const onAbort = () => finish(abortError("Subagent broker request was cancelled."));
-		const finish = (error?: Error, value?: Record<string, unknown>) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(connectTimer);
-			if (responseTimer) clearTimeout(responseTimer);
-			signal?.removeEventListener("abort", onAbort);
-			socket.destroy();
-			if (error) reject(error);
-			else resolve(value ?? {});
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-		socket.once("connect", () => {
-			clearTimeout(connectTimer);
-			if (responseTimeoutMs !== undefined) {
-				responseTimer = setTimeout(
-					() => finish(new Error("Subagent broker response timed out.")),
-					responseTimeoutMs,
-				);
-				responseTimer.unref();
-			}
-			socket.write(`${JSON.stringify(request)}\n`);
-		});
-		socket.on("data", (chunk: Buffer) => {
-			if (settled) return;
-			response = Buffer.concat([response, chunk]);
-			if (response.byteLength > MAX_FRAME_BYTES) {
-				finish(new Error("Subagent broker response exceeded its size limit."));
-				return;
-			}
-			const newline = response.indexOf(0x0a);
-			if (newline < 0) return;
-			const trailing = response
-				.subarray(newline + 1)
-				.toString("utf8")
-				.trim();
-			if (trailing) {
-				finish(new Error("Subagent broker returned more than one response frame."));
-				return;
-			}
-			try {
-				const parsed = JSON.parse(response.subarray(0, newline).toString("utf8")) as unknown;
-				if (!isRecord(parsed)) throw new Error();
-				finish(undefined, parsed);
-			} catch {
-				finish(new Error("Subagent broker returned malformed JSON."));
-			}
-		});
-		socket.once("error", (error) => finish(error));
-		socket.once("close", () => {
-			if (!settled) finish(new Error("Subagent broker closed without a response."));
-		});
-	});
+  if (signal?.aborted) return Promise.reject(abortError("Subagent broker request was cancelled."));
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host: credentials.host, port: credentials.port });
+    let response = Buffer.alloc(0);
+    let settled = false;
+    let responseTimer: NodeJS.Timeout | undefined;
+    const connectTimer = setTimeout(
+      () => finish(new Error("Subagent broker connection timed out.")),
+      CONNECT_TIMEOUT_MS,
+    );
+    connectTimer.unref();
+    const onAbort = () => finish(abortError("Subagent broker request was cancelled."));
+    const finish = (error?: Error, value?: Record<string, unknown>) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      if (responseTimer) clearTimeout(responseTimer);
+      signal?.removeEventListener("abort", onAbort);
+      socket.destroy();
+      if (error) reject(error);
+      else resolve(value ?? {});
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    socket.once("connect", () => {
+      clearTimeout(connectTimer);
+      if (responseTimeoutMs !== undefined) {
+        responseTimer = setTimeout(() => finish(new Error("Subagent broker response timed out.")), responseTimeoutMs);
+        responseTimer.unref();
+      }
+      socket.write(`${JSON.stringify(request)}\n`);
+    });
+    socket.on("data", (chunk: Buffer) => {
+      if (settled) return;
+      response = Buffer.concat([response, chunk]);
+      if (response.byteLength > MAX_FRAME_BYTES) {
+        finish(new Error("Subagent broker response exceeded its size limit."));
+        return;
+      }
+      const newline = response.indexOf(0x0a);
+      if (newline < 0) return;
+      const trailing = response
+        .subarray(newline + 1)
+        .toString("utf8")
+        .trim();
+      if (trailing) {
+        finish(new Error("Subagent broker returned more than one response frame."));
+        return;
+      }
+      try {
+        const parsed = JSON.parse(response.subarray(0, newline).toString("utf8")) as unknown;
+        if (!isRecord(parsed)) throw new Error();
+        finish(undefined, parsed);
+      } catch {
+        finish(new Error("Subagent broker returned malformed JSON."));
+      }
+    });
+    socket.once("error", (error) => finish(error));
+    socket.once("close", () => {
+      if (!settled) finish(new Error("Subagent broker closed without a response."));
+    });
+  });
 }
 
 function brokerError(response: Record<string, unknown>): Error {
-	return new Error(
-		typeof response.error === "string" ? response.error : "Subagent broker rejected the request.",
-	);
+  return new Error(typeof response.error === "string" ? response.error : "Subagent broker rejected the request.");
 }
 
 function abortError(message: string): Error {
-	const error = new Error(message);
-	error.name = "AbortError";
-	return error;
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/child-communication-tools.ts

@@ -1,147 +1,119 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import {
-	type BrokerSendAcknowledgement,
-	MAX_IDENTIFIER_LENGTH,
-	MAX_MESSAGE_BYTES,
-	sanitizeTerminalText,
-	validateMessage,
+  type BrokerSendAcknowledgement,
+  MAX_IDENTIFIER_LENGTH,
+  MAX_MESSAGE_BYTES,
+  sanitizeTerminalText,
+  validateMessage,
 } from "./message-broker.js";
+import { prepareTimeoutArguments, resolveTimeoutMs } from "./timeout.js";
 
 export const CHILD_COMMUNICATION_TOOL_NAMES = ["subagent_send", "subagent_wait"] as const;
 
-const MAX_TIMEOUT_MS = 2_147_483_647;
-const MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;
-
 const SendParameters = Type.Object(
-	{
-		requestId: Type.Optional(
-			Type.String({
-				description: "Pending main-agent request to answer. Omit when starting a new request.",
-				minLength: 1,
-				maxLength: MAX_IDENTIFIER_LENGTH,
-			}),
-		),
-		message: Type.String({
-			description: "Plain-text request or response. Maximum 48 KiB of UTF-8 text and 1,992 lines.",
-			minLength: 1,
-			maxLength: MAX_MESSAGE_BYTES,
-		}),
-	},
-	{ additionalProperties: false },
+  {
+    requestId: Type.Optional(
+      Type.String({
+        description: "Pending main-agent request to answer. Omit when starting a new request.",
+        minLength: 1,
+        maxLength: MAX_IDENTIFIER_LENGTH,
+      }),
+    ),
+    message: Type.String({
+      description: "Plain-text request or response. Maximum 48 KiB of UTF-8 text and 1,992 lines.",
+      minLength: 1,
+      maxLength: MAX_MESSAGE_BYTES,
+    }),
+  },
+  { additionalProperties: false },
 );
 
 const WaitParameters = Type.Object(
-	{
-		requestId: Type.String({
-			description: "Request ID returned by subagent_send.",
-			minLength: 1,
-			maxLength: MAX_IDENTIFIER_LENGTH,
-		}),
-		timeout: Type.Optional(
-			Type.Number({ description: "Timeout in seconds (optional, no default timeout)" }),
-		),
-	},
-	{ additionalProperties: false },
+  {
+    requestId: Type.String({
+      description: "Request ID returned by subagent_send.",
+      minLength: 1,
+      maxLength: MAX_IDENTIFIER_LENGTH,
+    }),
+    timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
+  },
+  { additionalProperties: false },
 );
 
-type ChildBrokerSendArguments =
-	| { recipient: "main"; message: string }
-	| { requestId: string; message: string };
+type ChildBrokerSendArguments = { recipient: "main"; message: string } | { requestId: string; message: string };
 
 type WaitArguments = Static<typeof WaitParameters>;
 
 export interface ChildCommunicationClient {
-	send(params: ChildBrokerSendArguments, signal?: AbortSignal): Promise<BrokerSendAcknowledgement>;
-	wait(requestId: string, timeoutMs: number | undefined, signal?: AbortSignal): Promise<string>;
+  send(params: ChildBrokerSendArguments, signal?: AbortSignal): Promise<BrokerSendAcknowledgement>;
+  wait(requestId: string, timeoutMs: number | undefined, signal?: AbortSignal): Promise<string>;
 }
 
-export function createChildCommunicationExtension(
-	client: ChildCommunicationClient,
-): ExtensionFactory {
-	return (pi) => {
-		pi.registerTool({
-			name: "subagent_send",
-			label: "Subagent · Send to Main",
-			description:
-				"Use subagent_send to send one request to the main agent or answer one pending main-agent request. Omit requestId to start a request. Provide requestId to answer that request.",
-			promptSnippet: "Use subagent_send to send or answer one main-agent message",
-			parameters: SendParameters,
-			async execute(_toolCallId, params, signal) {
-				validateMessage(params.message, "Subagent message");
-				const requestId = optionalIdentifier(params.requestId, "requestId");
-				const acknowledgement = await client.send(
-					requestId === undefined
-						? { recipient: "main", message: params.message }
-						: { requestId, message: params.message },
-					signal,
-				);
-				return {
-					content: [{ type: "text" as const, text: JSON.stringify(acknowledgement) }],
-					details: acknowledgement,
-				};
-			},
-		});
-
-		pi.registerTool({
-			name: "subagent_wait",
-			label: "Subagent · Wait for Main Agent",
-			description:
-				"Use subagent_wait with a request ID from subagent_send to wait for the main agent's plain-text response. A timeout, caller cancellation, or incoming main-agent request stops only this wait and does not cancel the original request. Retry the wait when its response is still needed.",
-			promptSnippet: "Use subagent_wait to receive a requested main-agent response",
-			parameters: WaitParameters,
-			prepareArguments: prepareWaitArguments,
-			async execute(_toolCallId, params, signal) {
-				const requestId = requiredIdentifier(params.requestId, "requestId");
-				const response = await client.wait(requestId, resolveTimeoutMs(params.timeout), signal);
-				return {
-					content: [{ type: "text" as const, text: sanitizeTerminalText(response) }],
-					details: { requestId },
-				};
-			},
-		});
-	};
-}
+export function createChildCommunicationExtension(client: ChildCommunicationClient): ExtensionFactory {
+  return (pi) => {
+    pi.registerTool({
+      name: "subagent_send",
+      label: "Subagent · Send to Main",
+      description:
+        "Use subagent_send to send one request to the main agent or answer one pending main-agent request. Omit requestId to start a request. Provide requestId to answer that request.",
+      promptSnippet: "Use subagent_send to send or answer one main-agent message",
+      parameters: SendParameters,
+      async execute(_toolCallId, params, signal) {
+        validateMessage(params.message, "Subagent message");
+        const requestId = optionalIdentifier(params.requestId, "requestId");
+        const acknowledgement = await client.send(
+          requestId === undefined
+            ? { recipient: "main", message: params.message }
+            : { requestId, message: params.message },
+          signal,
+        );
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(acknowledgement) }],
+          details: acknowledgement,
+        };
+      },
+    });
 
-function resolveTimeoutMs(timeout: number | undefined): number | undefined {
-	if (timeout === undefined) return undefined;
-	if (!Number.isFinite(timeout) || timeout <= 0) {
-		throw new Error("Invalid timeout: must be a finite number of seconds");
-	}
-	const timeoutMs = timeout * 1000;
-	if (timeoutMs > MAX_TIMEOUT_MS) {
-		throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
-	}
-	return timeoutMs;
+    pi.registerTool({
+      name: "subagent_wait",
+      label: "Subagent · Wait for Main Agent",
+      description:
+        "Use subagent_wait with a request ID from subagent_send to wait for the main agent's plain-text response. A timeout, caller cancellation, or incoming main-agent request stops only this wait and does not cancel the original request. Retry the wait when its response is still needed.",
+      promptSnippet: "Use subagent_wait to receive a requested main-agent response",
+      parameters: WaitParameters,
+      prepareArguments: prepareWaitArguments,
+      async execute(_toolCallId, params, signal) {
+        const requestId = requiredIdentifier(params.requestId, "requestId");
+        const response = await client.wait(requestId, resolveTimeoutMs(params.timeout), signal);
+        return {
+          content: [{ type: "text" as const, text: sanitizeTerminalText(response) }],
+          details: { requestId },
+        };
+      },
+    });
+  };
 }
 
 function prepareWaitArguments(args: unknown): WaitArguments {
-	if (!args || typeof args !== "object") return args as WaitArguments;
-	if (!Object.hasOwn(args, "timeoutMs")) return args as WaitArguments;
-	const record = args as Record<string, unknown>;
-	if (typeof record.timeoutMs !== "number") return record as WaitArguments;
-	const { timeoutMs, ...prepared } = record;
-	if (prepared.timeout === undefined) {
-		return { ...prepared, timeout: timeoutMs / 1000 } as WaitArguments;
-	}
-	return prepared as WaitArguments;
+  return prepareTimeoutArguments(args) as WaitArguments;
 }
 
 function optionalIdentifier(value: unknown, field: string): string | undefined {
-	return value === undefined ? undefined : requiredIdentifier(value, field);
+  return value === undefined ? undefined : requiredIdentifier(value, field);
 }
 
 function requiredIdentifier(value: unknown, field: string): string {
-	if (typeof value !== "string" || !value.trim()) throw new Error(`Subagent ${field} is required.`);
-	const identifier = value.trim();
-	if (
-		identifier.length > MAX_IDENTIFIER_LENGTH ||
-		[...identifier].some((character) => {
-			const codePoint = character.codePointAt(0) ?? 0;
-			return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
-		})
-	) {
-		throw new Error(`Subagent ${field} is invalid.`);
-	}
-	return identifier;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`Subagent ${field} is required.`);
+  const identifier = value.trim();
+  if (
+    identifier.length > MAX_IDENTIFIER_LENGTH ||
+    [...identifier].some((character) => {
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+    })
+  ) {
+    throw new Error(`Subagent ${field} is invalid.`);
+  }
+  return identifier;
 }

package/src/child-readiness-probe.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { toolSourceId } from "./attachment-utils.js";
+import { MAX_READINESS_FRAME_BYTES, takeCapturedReadiness } from "./broker-credentials.js";
+
+export interface ChildReadinessState {
+  fd: number;
+  expectedTools: string[];
+}
+
+const captured = takeCapturedReadiness();
+
+const childReadinessProbe: ExtensionFactory = captured ? createChildReadinessProbe(captured) : () => undefined;
+
+export default childReadinessProbe;
+
+export function createChildReadinessProbe(
+  readiness: ChildReadinessState,
+  writeFrame: (fd: number, frame: string) => void = writeReadinessFrame,
+  close: (fd: number) => void = closeDescriptor,
+): ExtensionFactory {
+  return (pi) => {
+    let settled = false;
+    const publish = (value: { ok: true; sources: string[] } | { ok: false; error: string }) => {
+      if (settled) return;
+      settled = true;
+      const frame = `${JSON.stringify(value)}\n`;
+      if (Buffer.byteLength(frame, "utf8") > MAX_READINESS_FRAME_BYTES) {
+        close(readiness.fd);
+        throw new Error("Pi-subagents readiness frame exceeded its size limit.");
+      }
+      try {
+        writeFrame(readiness.fd, frame);
+      } finally {
+        close(readiness.fd);
+      }
+    };
+
+    pi.on("resources_discover", () => {
+      const active = new Set(pi.getActiveTools());
+      const missing = readiness.expectedTools.filter((tool) => !active.has(tool));
+      if (missing.length > 0) {
+        publish({ ok: false, error: `Unavailable subagent tools: ${missing.join(", ")}.` });
+        return;
+      }
+      const sources = new Map(pi.getAllTools().map((tool) => [tool.name, tool.sourceInfo.path]));
+      publish({
+        ok: true,
+        sources: readiness.expectedTools.map((tool) => {
+          const source = sources.get(tool);
+          return source ? toolSourceId(source) : "";
+        }),
+      });
+    });
+
+    pi.on("session_shutdown", () => {
+      publish({ ok: false, error: "Subagent child shut down before readiness completed." });
+    });
+  };
+}
+
+function writeReadinessFrame(fd: number, frame: string): void {
+  fs.writeFileSync(fd, frame, "utf8");
+}
+
+function closeDescriptor(fd: number): void {
+  try {
+    fs.closeSync(fd);
+  } catch {
+    // The descriptor may already be closed after a failed write.
+  }
+}