@narumitw/pi-subagents 2.1.3 → 3.0.0

package/docs/design-principles.md

@@ -0,0 +1,31 @@
+# Design principles
+
+These principles define Pi Subagents rather than requirements for every Pi subagent implementation.
+
+## Context isolation is the purpose
+
+A subagent starts as a fresh Pi process.
+
+It does not inherit the main agent's conversation history.
+
+That isolation is not a limitation—it is the point.
+
+Fresh does not mean empty.
+
+The subagent still receives Pi's standard system prompt, the main agent's effective model, applicable project context, its selected tools, and one explicit task.
+
+The task defines the child's specialization, while the selected tools define its authority.
+
+Give each subagent a self-contained task containing only the context needed to complete that task.
+
+If work depends on substantial history from the current conversation, continue in the current thread instead of copying that history into a new subagent.
+
+## Simplicity over feature breadth
+
+Keep the architecture explicit, minimal, and easy to understand.
+
+Feature breadth alone does not justify more machinery.
+
+Prefer a small system whose behavior can be understood end to end over a feature-complete system whose behavior is obscured by layers of abstraction and orchestration.
+
+Every capability must earn its place: its value must outweigh both the complexity it introduces and the maintenance burden it leaves behind.

package/docs/ipc-transport-idea.md

@@ -0,0 +1,103 @@
+# Per-child IPC transport idea
+
+## Status
+
+This document records an unverified implementation idea for later evaluation.
+
+The current loopback TCP broker with private inherited-pipe credential bootstrap remains the implemented and authoritative transport.
+
+Do not treat this document as an approved migration plan or compatibility guarantee.
+
+## Motivation
+
+The TCP broker provides authenticated cross-process messaging but requires a server, ephemeral port, per-job tokens, private credential bootstrap, socket lifecycle management, NDJSON framing, connection deadlines, and long-poll handling.
+
+A private communication channel created with each child process may preserve the messaging contract with fewer transport concepts and less lifecycle code.
+
+## Proposed direction
+
+Spawn each child with a private Node.js child-process IPC channel:
+
+```ts
+spawn(command, args, {
+	stdio: ["ignore", "pipe", "pipe", "ipc"],
+});
+```
+
+Bind the channel to the job represented by that child process rather than accepting a job identifier or authentication token from the child.
+
+Send request and response events in either direction over the same persistent channel.
+
+Keep request state in a small session-owned registry in the parent and keep child wait promises in the child bridge.
+
+A possible exchange is:
+
+```text
+sender -> parent: send(recipient, message)
+parent -> sender: accepted(requestId)
+responder -> parent: send(requestId, message)
+parent -> requester: response(requestId, message)
+child requester -> parent: wait(requestId)
+```
+
+The exact wire messages and ownership boundaries remain undecided.
+
+## Complexity that may be removed
+
+A successful IPC design may remove:
+
+- The loopback TCP server and ephemeral port.
+- Per-job broker tokens and their private bootstrap pipe.
+- Socket connection and connection-limit management.
+- Custom NDJSON request and response framing.
+- Connection and frame deadlines.
+- Long-poll socket ownership.
+- Cross-job token validation.
+
+## Behavior that must remain
+
+Any replacement must preserve:
+
+- A fresh child Pi process with no inherited main-agent conversation history.
+- Context-specific provider-visible `subagent_send` definitions for main and child processes.
+- The child `subagent_wait` tool for child-originated requests.
+- Plain-text requests and responses in either direction.
+- At most four unresolved requests per job across both directions.
+- The 48 KiB and 1,992-line message limits that reserve space for protocol envelopes.
+- First-response-wins semantics.
+- Retryable waits after timeout.
+- Caller cancellation that stops only the current wait.
+- One-shot replay of a child response that arrives immediately before a main-agent job wait.
+- Interruption of active child response waits after a main-agent request is accepted, without consuming the original child requests.
+- Immediate rejection of pending waits after job cancellation, child exit, session replacement, reload, or shutdown.
+- Retention-limited state and terminal-safe cleanup.
+- Untrusted-content handling and terminal sanitization.
+- No peer messaging, retained child conversations, or nested subagents.
+
+## Compatibility spike
+
+Before selecting IPC, build the smallest possible spike that proves bidirectional messages, cancellation, child exit, and repeated cleanup through the actual Pi launch path.
+
+Exercise the spike with npm-installed Node.js Pi, Bun execution, and the Pi standalone executable where available.
+
+Include Linux and macOS, and include Windows before claiming Windows compatibility.
+
+Verify that the IPC channel does not interfere with Pi RPC framing, subprocess termination, detached process-group cleanup, or extension loading.
+
+Reject the IPC design if any supported runtime cannot expose a reliable private channel without runtime-specific branches or substantial fallback code.
+
+## Fallback
+
+If child-process IPC is not portable enough, evaluate dedicated inherited file descriptors such as fd 3 and fd 4.
+
+Inherited pipes can still remove TCP addressing and authentication, but they require explicit frame-size limits and stream lifecycle handling.
+
+HTTP loopback may simplify framing incrementally, but it retains the server, port, token, and network lifecycle and therefore offers a smaller reduction.
+
+Do not use filesystem polling or add an ad hoc messaging protocol to Pi's RPC stdin and stdout unless evidence shows that its additional coupling and cleanup remain simpler than the current transport.
+
+## Decision criteria
+
+Adopt a replacement only if it measurably reduces implementation and lifecycle complexity while preserving current behavior and supported runtime compatibility.
+
+Prefer the current TCP broker if the replacement requires runtime-specific branches, multiple transport fallbacks, or weaker isolation.

package/docs/tools.md

@@ -0,0 +1,109 @@
+# Pi Subagents tools
+
+## `subagent_spawn`
+
+| Parameter | Type | Required | Constraint / default |
+| --- | --- | --- | --- |
+| `task` | `string` | Yes | Self-contained task, up to 50 KiB of UTF-8 text. |
+| `tools` | `string[]` | No | Up to 64 names from `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, and `ls`; defaults to `read`, `grep`, `find`, and `ls`. |
+| `thinkingLevel` | `string` | No | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; defaults to the main agent's effective thinking level. |
+| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default timeout. |
+
+Starts one task-specialized subagent job with the selected tool capabilities and returns its job ID immediately.
+
+The runtime always adds `subagent_send` and `subagent_wait` to the selected tools.
+
+The child inherits the main agent's effective provider and model at spawn time.
+
+Providers registered by a parent extension throw before the job is queued because children disable unrelated extensions.
+
+A process-local runtime API key, including a parent-only `--api-key` value, also throws before queuing.
+
+Use Pi's stored credentials or environment credentials that the child process can read.
+
+Unavailable or extension-only tool names throw before the job is queued.
+
+Throws without launching a child when the session broker is unavailable.
+
+## `subagent_inspect`
+
+No parameters.
+
+## `subagent_cancel`
+
+| Parameter | Type | Required | Constraint / default |
+| --- | --- | --- | --- |
+| `jobId` | `string` | Yes | Job ID returned by `subagent_spawn`. |
+
+## `subagent_wait`
+
+### Main agent
+
+| Parameter | Type | Required | Constraint / default |
+| --- | --- | --- | --- |
+| `jobId` | `string` | Yes | Job ID to wait for. |
+| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default and does not cancel the job. |
+
+Returns `{ jobId, state, timedOut: false, interrupted: true, reason: "subagent_message" }` without cancelling the job when a child request or response arrives.
+
+### Subagent
+
+| Parameter | Type | Required | Constraint / default |
+| --- | --- | --- | --- |
+| `requestId` | `string` | Yes | Request ID returned by a child-originated `subagent_send`. |
+| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default and does not cancel the request. |
+
+Returns the main agent's response as plain text.
+
+A timeout, caller cancellation, or incoming main-agent request throws and stops only that wait, so the child may wait for the same request again.
+
+The runtime interrupts an active child wait only after Pi RPC accepts the incoming main request for steering.
+
+## `subagent_send`
+
+Main and child processes receive separate provider-visible definitions for their own context.
+
+### Main agent
+
+| Parameter | Type | Required | Constraint / default |
+| --- | --- | --- | --- |
+| `recipient` | `string` | Conditional | Active job ID for a new request. |
+| `requestId` | `string` | Conditional | Pending child request to answer. |
+| `message` | `string` | Yes | Plain-text request or response, up to 48 KiB of UTF-8 text and 1,992 lines. |
+
+Provide exactly one of `recipient` or `requestId`.
+
+A new request provides an active queued or running job ID as `recipient` and omits `requestId`.
+
+A response provides `requestId` and omits `recipient`.
+
+### Subagent
+
+| Parameter | Type | Required | Constraint / default |
+| --- | --- | --- | --- |
+| `requestId` | `string` | No | Pending main-agent request to answer; omit to start a new request to main. |
+| `message` | `string` | Yes | Plain-text request or response, up to 48 KiB of UTF-8 text and 1,992 lines. |
+
+A new request omits `requestId` and returns a request ID immediately for an optional `subagent_wait` call.
+
+A response provides the pending main-agent `requestId`.
+
+A main-originated request waits for the child RPC prompt to be accepted and then uses Pi steering to reach the running child.
+
+After steering is queued, the runtime interrupts active child response waits without consuming their original requests.
+
+Caller cancellation before RPC delivery starts rolls the request back.
+
+Once RPC delivery starts, cancellation stops only the caller's wait; the request may still arrive and remains answerable until delivery fails or the job terminates.
+
+A child response arrives asynchronously in the main session and interrupts the next active main-agent `subagent_wait`, including when the response arrived immediately before the wait started.
+
+The first accepted response wins, and repeated responses acknowledge the existing response without replacing it.
+
+Each job may have up to four unresolved or answered-but-not-consumed requests across both directions.
+
+Requests and responses are limited to 1,992 lines so their protocol envelopes fit Pi's 2,000-line model-text bound.
+
+Terminal jobs, unknown requests, cross-job responses, responses from the request originator, and stale session credentials throw.
+
+A successful call returns `{ requestId, accepted, duplicate }`.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "2.1.3",
-	"description": "Pi extension for delegating work to specialized isolated subagents.",
+	"version": "3.0.0",
+	"description": "Subagent jobs with asynchronous main-agent messaging for Pi.",
 	"type": "module",
 	"license": "MIT",
 	"private": false,
@@ -11,7 +11,7 @@
 		"pi",
 		"subagents",
 		"agents",
-		"automation"
+		"delegation"
 	],
 	"files": [
 		"src",
@@ -25,37 +25,29 @@
 			"./dist/index.ts"
 		]
 	},
-	"piExtension": {
-		"lifecycle": "stable"
-	},
 	"scripts": {
 		"build": "node scripts/build-runtime.mjs",
 		"check": "npm run build && biome check . && npm run typecheck",
 		"format": "biome check --write .",
-		"prepack": "npm run build",
-		"typecheck": "tsc --noEmit"
+		"typecheck": "tsc --noEmit",
+		"prepack": "npm run build"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-agent-core": "*",
 		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*",
 		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.10",
-		"@earendil-works/pi-agent-core": "0.84.3",
-		"@earendil-works/pi-ai": "0.84.3",
-		"@earendil-works/pi-coding-agent": "0.84.3",
-		"@earendil-works/pi-tui": "0.84.3",
+		"@biomejs/biome": "2.5.11",
+		"@earendil-works/pi-ai": "0.84.4",
+		"@earendil-works/pi-coding-agent": "0.84.4",
+		"@earendil-works/pi-tui": "0.84.4",
+		"@types/node": "26.4.0",
 		"esbuild": "0.28.2",
-		"typebox": "1.3.18",
+		"typebox": "1.3.20",
 		"typescript": "7.0.2"
 	},
-	"dependencies": {
-		"@narumitw/pi-tui-kit": "^0.59.0",
-		"proper-lockfile": "^4.1.2"
-	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",

package/src/broker-credentials.ts

@@ -0,0 +1,71 @@
+import * as fs from "node:fs";
+import type { BrokerCredentials } from "./types.js";
+
+export const BROKER_CREDENTIAL_FD = 3;
+export const BROKER_CREDENTIAL_FD_ENV = "PI_SUBAGENT_BROKER_FD";
+
+const MAX_CREDENTIAL_BYTES = 1_024;
+
+export function brokerCredentialEnvironment(): NodeJS.ProcessEnv {
+	return { [BROKER_CREDENTIAL_FD_ENV]: String(BROKER_CREDENTIAL_FD) };
+}
+
+export function serializeBrokerCredentials(credentials: BrokerCredentials): string {
+	return JSON.stringify(credentials);
+}
+
+export function captureBrokerCredentials(
+	readCredentials: () => string = readCredentialPipe,
+): BrokerCredentials | undefined {
+	const descriptor = process.env[BROKER_CREDENTIAL_FD_ENV];
+	delete process.env[BROKER_CREDENTIAL_FD_ENV];
+	if (descriptor === undefined) return undefined;
+	if (descriptor !== String(BROKER_CREDENTIAL_FD)) {
+		throw new Error("Invalid pi-subagents broker credential descriptor.");
+	}
+	let serialized: string;
+	try {
+		serialized = readCredentials();
+	} catch {
+		throw new Error("Unable to read pi-subagents broker credentials.");
+	}
+	if (Buffer.byteLength(serialized, "utf8") > MAX_CREDENTIAL_BYTES) {
+		throw new Error("Invalid pi-subagents broker credentials.");
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(serialized);
+	} catch {
+		throw new Error("Invalid pi-subagents broker credentials.");
+	}
+	if (!isBrokerCredentials(value)) {
+		throw new Error("Invalid pi-subagents broker credentials.");
+	}
+	return value;
+}
+
+function readCredentialPipe(): string {
+	try {
+		return fs.readFileSync(BROKER_CREDENTIAL_FD, "utf8");
+	} finally {
+		try {
+			fs.closeSync(BROKER_CREDENTIAL_FD);
+		} catch {
+			// The descriptor may already be closed after a failed read.
+		}
+	}
+}
+
+function isBrokerCredentials(value: unknown): value is BrokerCredentials {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const candidate = value as Record<string, unknown>;
+	return (
+		Object.keys(candidate).length === 3 &&
+		candidate.host === "127.0.0.1" &&
+		Number.isSafeInteger(candidate.port) &&
+		(candidate.port as number) >= 1 &&
+		(candidate.port as number) <= 65_535 &&
+		typeof candidate.token === "string" &&
+		/^[a-f0-9]{64}$/u.test(candidate.token)
+	);
+}

package/src/child-communication-bridge.ts

@@ -0,0 +1,153 @@
+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 { 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 childCommunicationBridge: ExtensionFactory = captured
+	? createChildCommunicationExtension(createBrokerClient(captured))
+	: () => 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;
+		},
+	};
+}
+
+function requestBroker(
+	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."));
+		});
+	});
+}
+
+function brokerError(response: Record<string, unknown>): Error {
+	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;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/child-communication-tools.ts

@@ -0,0 +1,147 @@
+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,
+} from "./message-broker.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 },
+);
+
+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 },
+);
+
+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>;
+}
+
+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 },
+				};
+			},
+		});
+	};
+}
+
+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;
+}
+
+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;
+}
+
+function optionalIdentifier(value: unknown, field: string): string | undefined {
+	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;
+}