pi-subagents 0.69.0 → 0.70.0

package/src/runs/shared/external-job-runner.ts

@@ -1,389 +0,0 @@
-import { createHash } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { ExternalJobProviderError, type ExternalJobHandle, type ExternalJobResult, type ExternalJobState } from "../../api/external-job-provider.ts";
-import type { ExternalJobStatus } from "../../shared/types.ts";
-import { requestExternalJobOperation } from "./external-job-bridge.ts";
-
-const STATUS_POLL_INTERVAL_MS = 1_000;
-
-export interface ExternalJobRunResult {
-	output: string;
-	exitCode: number;
-	error?: string;
-	timedOut?: boolean;
-	stopped?: boolean;
-	externalJob: ExternalJobStatus;
-}
-
-export function externalJobPromptDigest(prompt: string): string {
-	return createHash("sha256").update(prompt).digest("hex");
-}
-
-export function externalJobStableJson(value: unknown): string {
-	if (value === null || typeof value !== "object") return JSON.stringify(value);
-	if (Array.isArray(value)) return `[${value.map(externalJobStableJson).join(",")}]`;
-	const record = value as Record<string, unknown>;
-	return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${externalJobStableJson(record[key])}`).join(",")}}`;
-}
-
-export function externalJobFollowUpRequestDigest(input: { provider: string; parentProviderJobId: string; promptDigest: string; options: Record<string, unknown> }): string {
-	return createHash("sha256")
-		.update(externalJobStableJson({ provider: input.provider, parentProviderJobId: input.parentProviderJobId, promptDigest: input.promptDigest, options: input.options }))
-		.digest("hex");
-}
-
-export function externalJobFollowUpRequestId(requestDigest: string): string {
-	return `follow-up-${requestDigest.slice(0, 48)}`;
-}
-
-export function externalJobFollowUpRunId(requestDigest: string): string {
-	const hex = requestDigest.padEnd(32, "0").slice(0, 32).split("");
-	hex[12] = "4";
-	hex[16] = ((Number.parseInt(hex[16]!, 16) & 0x3) | 0x8).toString(16);
-	const value = hex.join("");
-	return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20, 32)}`;
-}
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function terminal(state: ExternalJobState): boolean {
-	return state === "completed" || state === "failed" || state === "stopped" || state === "blocked";
-}
-
-function formatError(error: ExternalJobProviderError, provider: string): string {
-	const blocking = error.blockingJobId ? ` Blocking provider job: ${error.blockingJobId}.` : "";
-	return `External-job provider '${provider}' failed closed (${error.code}): ${error.message}.${blocking}`;
-}
-
-function isNotFound(error: unknown): boolean {
-	return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function malformedStatus(statusPath: string): ExternalJobProviderError {
-	return new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable" });
-}
-
-function parseExternalJobStatus(value: unknown, statusPath: string): ExternalJobStatus {
-	if (!isRecord(value)) throw malformedStatus(statusPath);
-	const provider = value.provider;
-	const promptDigest = value.promptDigest;
-	const state = value.state;
-	if (typeof provider !== "string" || provider.length === 0) throw malformedStatus(statusPath);
-	if (typeof promptDigest !== "string" || promptDigest.length === 0) throw malformedStatus(statusPath);
-	if (state !== "queued" && state !== "running" && state !== "completed" && state !== "failed" && state !== "stopped" && state !== "blocked") throw malformedStatus(statusPath);
-	if (value.options !== undefined && !isRecord(value.options)) throw malformedStatus(statusPath);
-	const providerJobId = value.providerJobId;
-	const handleUrl = value.handleUrl;
-	const conversationUrl = value.conversationUrl;
-	const resultArtifactPath = value.resultArtifactPath;
-	const failureCode = value.failureCode;
-	const failureMessage = value.failureMessage;
-	const blockingJobId = value.blockingJobId;
-	const startedAt = value.startedAt;
-	const updatedAt = value.updatedAt;
-	if (providerJobId !== undefined && (typeof providerJobId !== "string" || providerJobId.length === 0)) throw malformedStatus(statusPath);
-	if (handleUrl !== undefined && typeof handleUrl !== "string") throw malformedStatus(statusPath);
-	if (conversationUrl !== undefined && typeof conversationUrl !== "string") throw malformedStatus(statusPath);
-	if (resultArtifactPath !== undefined && typeof resultArtifactPath !== "string") throw malformedStatus(statusPath);
-	if (failureCode !== undefined && typeof failureCode !== "string") throw malformedStatus(statusPath);
-	if (failureMessage !== undefined && typeof failureMessage !== "string") throw malformedStatus(statusPath);
-	if (blockingJobId !== undefined && typeof blockingJobId !== "string") throw malformedStatus(statusPath);
-	const operation = value.operation;
-	const sourceRunId = value.sourceRunId;
-	const sourceStepIndex = value.sourceStepIndex;
-	const parentProviderJobId = value.parentProviderJobId;
-	const requestId = value.requestId;
-	const requestDigest = value.requestDigest;
-	if (operation !== undefined && operation !== "start" && operation !== "follow-up") throw malformedStatus(statusPath);
-	if (sourceRunId !== undefined && (typeof sourceRunId !== "string" || sourceRunId.length === 0)) throw malformedStatus(statusPath);
-	if (sourceStepIndex !== undefined && (typeof sourceStepIndex !== "number" || !Number.isInteger(sourceStepIndex) || sourceStepIndex < 0)) throw malformedStatus(statusPath);
-	if (parentProviderJobId !== undefined && (typeof parentProviderJobId !== "string" || parentProviderJobId.length === 0)) throw malformedStatus(statusPath);
-	if (requestId !== undefined && (typeof requestId !== "string" || requestId.length === 0)) throw malformedStatus(statusPath);
-	if (requestDigest !== undefined && (typeof requestDigest !== "string" || requestDigest.length === 0)) throw malformedStatus(statusPath);
-	if (startedAt !== undefined && typeof startedAt !== "number") throw malformedStatus(statusPath);
-	if (updatedAt !== undefined && typeof updatedAt !== "number") throw malformedStatus(statusPath);
-	return {
-		provider,
-		promptDigest,
-		...(operation ? { operation } : {}),
-		...(sourceRunId ? { sourceRunId } : {}),
-		...(sourceStepIndex !== undefined ? { sourceStepIndex } : {}),
-		...(parentProviderJobId ? { parentProviderJobId } : {}),
-		...(requestId ? { requestId } : {}),
-		...(requestDigest ? { requestDigest } : {}),
-		options: value.options ?? {},
-		state,
-		...(providerJobId ? { providerJobId } : {}),
-		...(handleUrl ? { handleUrl } : {}),
-		...(conversationUrl ? { conversationUrl } : {}),
-		...(resultArtifactPath ? { resultArtifactPath } : {}),
-		...(failureCode ? { failureCode } : {}),
-		...(failureMessage ? { failureMessage } : {}),
-		...(blockingJobId ? { blockingJobId } : {}),
-		...(startedAt !== undefined ? { startedAt } : {}),
-		...(updatedAt !== undefined ? { updatedAt } : {}),
-	};
-}
-
-function readExistingExternalJob(asyncDir: string, stepIndex: number): ExternalJobStatus | undefined {
-	const statusPath = path.join(asyncDir, "status.json");
-	let raw: string;
-	try {
-		raw = fs.readFileSync(statusPath, "utf-8");
-	} catch (error) {
-		if (isNotFound(error)) return undefined;
-		throw new ExternalJobProviderError(`Unreadable external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (error) {
-		throw new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
-	}
-	if (!isRecord(parsed) || !Array.isArray(parsed.steps)) throw malformedStatus(statusPath);
-	const step = parsed.steps[stepIndex];
-	if (step === undefined || !isRecord(step)) throw malformedStatus(statusPath);
-	if (step.externalJob === undefined) return undefined;
-	return parseExternalJobStatus(step.externalJob, statusPath);
-}
-
-function externalJobLineage(followUp: ExternalJobFollowUpDescriptor | undefined, previous: ExternalJobStatus | undefined) {
-	return {
-		operation: followUp ? "follow-up" as const : previous?.operation,
-		...(followUp ? {
-			sourceRunId: followUp.sourceRunId,
-			sourceStepIndex: followUp.sourceStepIndex,
-			parentProviderJobId: followUp.parentProviderJobId,
-			requestId: followUp.requestId,
-			requestDigest: followUp.requestDigest,
-		} : {
-			...(previous?.sourceRunId ? { sourceRunId: previous.sourceRunId } : {}),
-			...(previous?.sourceStepIndex !== undefined ? { sourceStepIndex: previous.sourceStepIndex } : {}),
-			...(previous?.parentProviderJobId ? { parentProviderJobId: previous.parentProviderJobId } : {}),
-			...(previous?.requestId ? { requestId: previous.requestId } : {}),
-			...(previous?.requestDigest ? { requestDigest: previous.requestDigest } : {}),
-		}),
-	};
-}
-
-function statusFromHandle(input: {
-	provider: string;
-	promptDigest: string;
-	options: Record<string, unknown>;
-	followUp?: ExternalJobFollowUpDescriptor;
-	startedAt?: number;
-	previous?: ExternalJobStatus;
-	handle: ExternalJobHandle;
-	resultArtifactPath?: string;
-}): ExternalJobStatus {
-	return {
-		provider: input.provider,
-		providerJobId: input.handle.providerJobId,
-		promptDigest: input.promptDigest,
-		...externalJobLineage(input.followUp, input.previous),
-		options: input.options,
-		handleUrl: input.handle.handleUrl ?? input.previous?.handleUrl,
-		conversationUrl: input.handle.conversationUrl ?? input.previous?.conversationUrl,
-		resultArtifactPath: input.resultArtifactPath ?? input.previous?.resultArtifactPath,
-		state: input.handle.state,
-		failureCode: input.handle.failureCode,
-		failureMessage: input.handle.failureMessage,
-		blockingJobId: input.handle.blockingJobId,
-		startedAt: input.previous?.startedAt ?? input.startedAt,
-		updatedAt: Date.now(),
-	};
-}
-
-function failureStatus(input: {
-	provider: string;
-	promptDigest: string;
-	options: Record<string, unknown>;
-	followUp?: ExternalJobFollowUpDescriptor;
-	previous?: ExternalJobStatus;
-	code: string;
-	message: string;
-	blockingJobId?: string;
-}): ExternalJobStatus {
-	return {
-		provider: input.provider,
-		providerJobId: input.previous?.providerJobId,
-		promptDigest: input.promptDigest,
-		...externalJobLineage(input.followUp, input.previous),
-		options: input.options,
-		handleUrl: input.previous?.handleUrl,
-		conversationUrl: input.previous?.conversationUrl,
-		resultArtifactPath: input.previous?.resultArtifactPath,
-		state: input.blockingJobId ? "blocked" : "failed",
-		failureCode: input.code,
-		failureMessage: input.message,
-		blockingJobId: input.blockingJobId,
-		startedAt: input.previous?.startedAt,
-		updatedAt: Date.now(),
-	};
-}
-
-function resultOutput(result: ExternalJobResult, artifactPath: string | undefined): string {
-	if (result.output?.trim()) return result.output.trim();
-	if (artifactPath) return `External job finished. Result artifact: ${artifactPath}`;
-	return "External job finished without text output.";
-}
-
-function blocksStartRedispatch(status: ExternalJobStatus, provider: string, promptDigest: string): boolean {
-	return status.provider === provider
-		&& status.promptDigest === promptDigest
-		&& !status.providerJobId
-		&& status.failureCode !== "provider-unavailable";
-}
-
-interface ExternalJobFollowUpDescriptor {
-	sourceRunId: string;
-	sourceStepIndex: number;
-	parentProviderJobId: string;
-	requestId: string;
-	requestDigest: string;
-}
-
-function sameFollowUpLineage(status: ExternalJobStatus, followUp: ExternalJobFollowUpDescriptor | undefined): boolean {
-	if (!followUp) return status.operation !== "follow-up";
-	return status.operation === "follow-up"
-		&& status.sourceRunId === followUp.sourceRunId
-		&& status.sourceStepIndex === followUp.sourceStepIndex
-		&& status.parentProviderJobId === followUp.parentProviderJobId
-		&& status.requestId === followUp.requestId
-		&& status.requestDigest === followUp.requestDigest;
-}
-
-export async function runExternalJob(input: {
-	provider: string;
-	options?: Record<string, unknown>;
-	cwd: string;
-	prompt: string;
-	asyncDir: string;
-	stepIndex: number;
-	runId: string;
-	agent: string;
-	sessionId?: string;
-	registerTimeout?: (stop: (() => void) | undefined) => void;
-	registerStop?: (stop: (() => void) | undefined) => void;
-	timeoutMessage?: string;
-	stopMessage?: string;
-	onExternalJob?: (status: ExternalJobStatus) => void;
-	followUp?: ExternalJobFollowUpDescriptor;
-}): Promise<ExternalJobRunResult> {
-	const provider = input.provider;
-	const options = input.options ?? {};
-	const promptDigest = externalJobPromptDigest(input.prompt);
-	const startedAt = Date.now();
-	let timedOut = false;
-	let stopped = false;
-	let current: ExternalJobStatus | undefined;
-	const timeout = () => { timedOut = true; };
-	const stop = () => { stopped = true; };
-	input.registerTimeout?.(timeout);
-	input.registerStop?.(stop);
-	const publish = (status: ExternalJobStatus) => {
-		current = status;
-		input.onExternalJob?.(status);
-	};
-	const localCancellation = () => {
-		if (!timedOut && !stopped) return undefined;
-		const message = stopped
-			? input.stopMessage ?? `Subagent stopped locally before external provider '${provider}' returned a job id. The provider start may still be running.`
-			: input.timeoutMessage ?? `Subagent timed out locally before external provider '${provider}' returned a job id. The provider start may still be running.`;
-		return new ExternalJobProviderError(message, { code: stopped ? "local-stop" : "local-timeout" });
-	};
-	try {
-		current = readExistingExternalJob(input.asyncDir, input.stepIndex);
-		let handle: ExternalJobHandle;
-		if (current?.providerJobId) {
-			if (current.provider !== provider || current.promptDigest !== promptDigest || !sameFollowUpLineage(current, input.followUp)) {
-				const message = `Existing external job '${current.providerJobId}' does not match provider, prompt digest, or follow-up lineage. Refusing to redispatch prompt.`;
-				const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: "recovery-mismatch", message });
-				publish(status);
-				return { output: message, exitCode: 1, error: message, externalJob: status };
-			}
-			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "reattach", provider, providerJobId: current.providerJobId });
-		} else {
-			if (current && blocksStartRedispatch(current, provider, promptDigest)) {
-				const message = `External-job ${input.followUp ? "follow-up" : "start"} for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
-				const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: input.followUp ? "dispatch-redispatch-blocked" : "start-redispatch-blocked", message });
-				publish(status);
-				return { output: message, exitCode: 1, error: message, externalJob: status };
-			}
-			publish({ provider, promptDigest, ...(input.followUp ? { operation: "follow-up" as const, ...input.followUp } : {}), options, state: "queued", startedAt, updatedAt: Date.now() });
-			if (input.followUp) {
-				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
-					operation: "follow-up",
-					provider,
-					followUp: {
-						prompt: input.prompt,
-						promptDigest,
-						cwd: input.cwd,
-						runId: input.runId,
-						stepIndex: input.stepIndex,
-						agent: input.agent,
-						options,
-						...(input.sessionId ? { sessionId: input.sessionId } : {}),
-						...input.followUp,
-					},
-				}, undefined, localCancellation);
-			} else {
-				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
-					operation: "start",
-					provider,
-					start: {
-						prompt: input.prompt,
-						promptDigest,
-						cwd: input.cwd,
-						runId: input.runId,
-						stepIndex: input.stepIndex,
-						agent: input.agent,
-						options,
-						...(input.sessionId ? { sessionId: input.sessionId } : {}),
-					},
-				}, undefined, localCancellation);
-			}
-		}
-		publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, startedAt, previous: current, handle }));
-		while (!terminal(handle.state)) {
-			if (timedOut || stopped) {
-				const message = stopped
-					? input.stopMessage ?? `Subagent stopped locally; external provider job '${handle.providerJobId}' may still be running.`
-					: input.timeoutMessage ?? `Subagent timed out locally; external provider job '${handle.providerJobId}' may still be running.`;
-				return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: current! };
-			}
-			await sleep(STATUS_POLL_INTERVAL_MS);
-			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "status", provider, providerJobId: handle.providerJobId });
-			publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle }));
-		}
-		const result = await requestExternalJobOperation<ExternalJobResult>(input.asyncDir, { operation: "result", provider, providerJobId: handle.providerJobId });
-		let artifactPath = result.artifactPath;
-		if (!artifactPath && result.output !== undefined) {
-			artifactPath = path.join(input.asyncDir, `external-job-${input.stepIndex}.result.md`);
-			fs.writeFileSync(artifactPath, result.output, "utf-8");
-		}
-		const finalStatus = statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle: result, resultArtifactPath: artifactPath });
-		publish(finalStatus);
-		const output = resultOutput(result, artifactPath);
-		const error = result.state === "completed" ? undefined : result.failureMessage ?? `External job ${result.state}.`;
-		return { output, exitCode: result.state === "completed" ? 0 : 1, ...(error ? { error } : {}), externalJob: finalStatus };
-	} catch (error) {
-		const providerError = error instanceof ExternalJobProviderError
-			? error
-			: new ExternalJobProviderError(error instanceof Error ? error.message : String(error), { code: "provider-error", cause: error });
-		const message = formatError(providerError, provider);
-		const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: providerError.code, message, ...(providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {}) });
-		publish(status);
-		return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: status };
-	} finally {
-		input.registerTimeout?.(undefined);
-		input.registerStop?.(undefined);
-	}
-}

package/src/runs/shared/fast-mode-extension.ts

@@ -1,10 +0,0 @@
-import type { BeforeProviderRequestEvent, ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-export function rewriteFastModeProviderRequest(event: BeforeProviderRequestEvent): unknown {
-	if (!event.payload || typeof event.payload !== "object" || Array.isArray(event.payload)) return event.payload;
-	return { ...event.payload, service_tier: "priority" };
-}
-
-export default function registerSubagentFastModeExtension(pi: ExtensionAPI): void {
-	pi.on("before_provider_request", rewriteFastModeProviderRequest);
-}

package/src/runs/shared/herdr-connection.ts

@@ -1,134 +0,0 @@
-import { spawn, spawnSync, type ChildProcess } from "node:child_process";
-import * as fs from "node:fs";
-import * as net from "node:net";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { HerdrMachineReference } from "../../shared/types.ts";
-
-const MAX_DISCOVERY_BYTES = 256 * 1024;
-const MAX_RPC_BYTES = 4 * 1024 * 1024;
-const SUBSCRIPTION_ACK_TIMEOUT_MS = 15_000;
-export const HERDR_REMOTE_PATH = "$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
-export const HERDR_SSH_BASE = ["-T", "-o", "BatchMode=yes", "-o", "NumberOfPasswordPrompts=0", "-o", "StrictHostKeyChecking=yes", "-o", "ConnectTimeout=10", "-o", "ConnectionAttempts=1", "-o", "ForwardAgent=no", "-o", "ExitOnForwardFailure=yes", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=4", "-o", "SendEnv=-*", "-o", "SetEnv=PI_SUBAGENTS_SSH_GUARD="] as const;
-export function hardenedSshEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv { return { PATH: process.platform === "win32" ? source.PATH : "/usr/bin:/bin:/usr/sbin:/sbin", ...(source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}), ...(source.WINDIR ? { WINDIR: source.WINDIR } : {}) }; }
-export function herdrSshArgs(source: NodeJS.ProcessEnv = process.env): string[] { return [...HERDR_SSH_BASE, ...(source.SSH_AUTH_SOCK ? ["-o", `IdentityAgent=${source.SSH_AUTH_SOCK}`] : [])]; }
-
-export interface HerdrEndpoint { socket: string; session: string | null; version: string; protocol: number; compatible: boolean; running: boolean }
-export interface HerdrRpcClient {
-	call<T>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
-	subscribe(subscriptions: unknown[], listener: (event: unknown) => void, onDisconnect?: (error: Error) => void): Promise<() => void>;
-}
-export class HerdrRpcError extends Error {
-	readonly code?: string; readonly requestId: string;
-	constructor(message: string, requestId: string, code?: string) { super(message); this.name = "HerdrRpcError"; this.requestId = requestId; this.code = code; }
-}
-export class HerdrTransportError extends Error { constructor(message: string, options?: ErrorOptions) { super(message, options); this.name = "HerdrTransportError"; } }
-export interface HerdrForwardedConnection { endpoint: HerdrEndpoint; socketPath: string; client: HerdrRpcClient; forwardRemoteSocket(remotePath: string, name: string): Promise<{ socketPath: string; close(): Promise<void> }>; close(): Promise<void> }
-export function decodeHerdrJsonLine(line: Buffer): unknown { try { return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line)) as unknown; } catch { throw new Error("Herdr emitted malformed JSON or UTF-8."); } }
-
-export function shellQuoteRemote(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
-export function remoteShellCommand(script: string, args: string[] = []): string { return `sh -c ${shellQuoteRemote(`PATH="${HERDR_REMOTE_PATH}"; export PATH; ${script}`)} sh${args.map((arg) => ` ${shellQuoteRemote(arg)}`).join("")}`; }
-function canonicalHerdrSession(session: string | null | undefined): string | null { return session && session !== "default" ? session : null; }
-function sshEnvCommand(session: string | undefined, command: string): string { const selected = canonicalHerdrSession(session), assignment = selected ? ` HERDR_SESSION=${shellQuoteRemote(selected)}` : ""; return `/usr/bin/env -u HERDR_SOCKET_PATH -u HERDR_SESSION${assignment} ${remoteShellCommand(command)}`; }
-
-export function runHerdrRemoteCommand(machine: HerdrMachineReference, command: string, options: { sshBin?: string; env?: NodeJS.ProcessEnv; timeout?: number; maxBuffer?: number } = {}) { return spawnSync(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { encoding: "utf8", env: hardenedSshEnv(options.env), timeout: options.timeout ?? 15_000, maxBuffer: options.maxBuffer ?? MAX_DISCOVERY_BYTES, windowsHide: true }); }
-
-export function runHerdrRemoteCommandAsync(machine: HerdrMachineReference, command: string, options: { sshBin?: string; env?: NodeJS.ProcessEnv; timeout?: number; maxBuffer?: number } = {}): Promise<{ status: number | null; stdout: string; stderr: string; error?: Error }> {
-	return new Promise((resolve) => {
-		const child = spawn(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { env: hardenedSshEnv(options.env), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
-		const stdout: Buffer[] = [], stderr: Buffer[] = [], maxBuffer = options.maxBuffer ?? MAX_DISCOVERY_BYTES; let stdoutBytes = 0, stderrBytes = 0, error: Error | undefined, settled = false, escalation: NodeJS.Timeout | undefined;
-		const finish = (status: number | null, spawnError = error) => { if (settled) return; settled = true; clearTimeout(timer); if (escalation) clearTimeout(escalation); resolve({ status, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), ...(spawnError ? { error: spawnError } : {}) }); };
-		const terminate = () => { child.kill("SIGTERM"); escalation ??= setTimeout(() => { if (!settled) { child.kill("SIGKILL"); finish(child.exitCode ?? null); } }, 1_000); escalation.unref?.(); };
-		const collect = (target: Buffer[], stream: "stdout" | "stderr") => (chunk: Buffer) => { const bytes = stream === "stdout" ? (stdoutBytes += chunk.byteLength) : (stderrBytes += chunk.byteLength); if (bytes > maxBuffer) { error ??= new Error(`${stream} maxBuffer length exceeded`); terminate(); } else target.push(chunk); };
-		child.stdout.on("data", collect(stdout, "stdout")); child.stderr.on("data", collect(stderr, "stderr"));
-		child.once("error", (spawnError) => finish(null, spawnError));
-		child.once("close", (status) => finish(status));
-		const timer = setTimeout(terminate, options.timeout ?? 15_000); timer.unref?.();
-	});
-}
-
-export function parseHerdrEndpoint(value: string, expectedSession?: string): HerdrEndpoint {
-	let parsed: unknown;
-	try { parsed = JSON.parse(value) as unknown; } catch { throw new Error("Remote Herdr endpoint discovery returned malformed JSON."); }
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Remote Herdr endpoint discovery returned no endpoint.");
-	const p = parsed as Record<string, unknown>;
-	if (typeof p.socket !== "string" || !path.posix.isAbsolute(p.socket) || typeof p.version !== "string" || typeof p.protocol !== "number") throw new Error("Remote Herdr endpoint discovery returned incomplete identity.");
-	const session = canonicalHerdrSession(typeof p.session === "string" ? p.session : null), expected = canonicalHerdrSession(expectedSession);
-	if (expected !== session) throw new Error(`Remote Herdr session identity mismatch: expected ${expected ?? "default"}, received ${session ?? "default"}.`);
-	if (p.running !== true || p.compatible !== true || p.endpoint_compatible === false) throw new Error("The selected remote Herdr session is stopped or incompatible.");
-	return { socket: p.socket, session, version: p.version, protocol: p.protocol, compatible: true, running: true };
-}
-
-export async function discoverHerdrEndpoint(machine: HerdrMachineReference, options: { sshBin?: string; env?: NodeJS.ProcessEnv } = {}): Promise<HerdrEndpoint> {
-	const discovery = 'herdr_path=$(command -v herdr) || exit 127; case "$herdr_path" in /*/herdr) ;; *) exit 126;; esac; exec "$herdr_path" status server --json';
-	const result = await runHerdrRemoteCommandAsync(machine, sshEnvCommand(machine.session, discovery), { ...options, timeout: 15_000, maxBuffer: MAX_DISCOVERY_BYTES });
-	if (result.error) throw new Error(`Remote Herdr discovery failed: ${result.error.message}`);
-	if (result.status !== 0) throw new Error(`Remote Herdr discovery failed with code ${result.status}: ${(result.stderr || result.stdout).trim()}`);
-	return parseHerdrEndpoint(result.stdout, machine.session);
-}
-
-export class SocketRpcClient implements HerdrRpcClient {
-	readonly #socketPath: string;
-	readonly #subscriptionAckTimeoutMs: number;
-	#next = 0;
-	constructor(socketPath: string, subscriptionAckTimeoutMs = SUBSCRIPTION_ACK_TIMEOUT_MS) { this.#socketPath = socketPath; this.#subscriptionAckTimeoutMs = subscriptionAckTimeoutMs; }
-	call<T>(method: string, params: Record<string, unknown> = {}, timeoutMs = 15_000): Promise<T> {
-		return new Promise((resolve, reject) => {
-			const socket = net.createConnection(this.#socketPath); let bytes = 0; let data = Buffer.alloc(0); let finished = false; const id = String(++this.#next);
-			const timer = setTimeout(() => finish(new HerdrTransportError(`Herdr RPC '${method}' timed out.`)), timeoutMs); timer.unref?.();
-			const finish = (error?: Error, value?: T) => { if (finished) return; finished = true; clearTimeout(timer); socket.destroy(); error ? reject(error) : resolve(value as T); };
-			socket.on("connect", () => socket.write(`${JSON.stringify({ id, method, params })}\n`));
-			socket.on("data", (chunk: Buffer) => {
-				bytes += chunk.byteLength; if (bytes > MAX_RPC_BYTES) { finish(new Error("Herdr RPC response exceeded its byte bound.")); return; }
-				data = Buffer.concat([data, chunk]); const newline = data.indexOf(10); if (newline < 0) return;
-				let frame: unknown; try { frame = decodeHerdrJsonLine(data.subarray(0, newline)); } catch { finish(new Error("Herdr RPC returned malformed JSON or UTF-8.")); return; }
-				const record = frame as { id?: unknown; result?: T; error?: { message?: unknown; code?: unknown } };
-				if (record.id !== id) { finish(new Error("Herdr RPC response identity mismatch.")); return; }
-				if (record.error) finish(new HerdrRpcError(String(record.error.message ?? "Herdr RPC failed."), id, typeof record.error.code === "string" ? record.error.code : undefined)); else finish(undefined, record.result);
-			});
-			socket.on("error", (error) => finish(new HerdrTransportError(error.message, { cause: error })));
-			socket.on("close", () => finish(new HerdrTransportError(`Herdr RPC '${method}' ended before a response.`)));
-		});
-	}
-	async subscribe(subscriptions: unknown[], listener: (event: unknown) => void, onDisconnect?: (error: Error) => void): Promise<() => void> {
-		const socket = net.createConnection(this.#socketPath); const id = String(++this.#next); let buffer = Buffer.alloc(0), bytes = 0, acknowledged = false, intentional = false, notified = false, settled = false;
-		let resolveAck!: () => void, rejectAck!: (error: Error) => void;
-		const acknowledgement = new Promise<void>((resolve, reject) => { resolveAck = resolve; rejectAck = reject; });
-		const failHandshake = (error: Error) => { if (settled) return; settled = true; clearTimeout(timer); socket.destroy(); rejectAck(error); };
-		const disconnect = (error: Error) => { if (intentional || notified) return; notified = true; if (!acknowledged) failHandshake(error); else onDisconnect?.(error); };
-		const timer = setTimeout(() => failHandshake(new Error("Herdr subscription acknowledgement timed out.")), this.#subscriptionAckTimeoutMs); timer.unref?.();
-		socket.on("data", (chunk: Buffer) => { bytes += chunk.byteLength; if (bytes > (acknowledged ? MAX_RPC_BYTES * 32 : MAX_RPC_BYTES)) { disconnect(new Error("Herdr subscription exceeded its byte bound.")); socket.destroy(); return; } buffer = Buffer.concat([buffer, chunk]); for (;;) { const i = buffer.indexOf(10); if (i < 0) break; const line = buffer.subarray(0, i); buffer = buffer.subarray(i + 1); let value: unknown; try { value = decodeHerdrJsonLine(line); } catch { disconnect(new Error("Herdr subscription emitted malformed JSON or UTF-8.")); socket.destroy(); return; } const record = value as { id?: unknown; result?: { type?: unknown }; error?: { message?: unknown; code?: unknown } }; if (!acknowledged) { if (record.id === id) { if (record.error) { failHandshake(new HerdrRpcError(String(record.error.message ?? "Herdr subscription failed."), id, typeof record.error.code === "string" ? record.error.code : undefined)); return; } if (record.result?.type !== "subscription_started") { failHandshake(new Error("Herdr subscription returned an invalid acknowledgement.")); return; } acknowledged = true; settled = true; clearTimeout(timer); resolveAck(); continue; } if (record.id === "" && record.error && record.error.code === "invalid_request") { failHandshake(new HerdrRpcError(String(record.error.message ?? "Herdr subscription request was invalid."), "", "invalid_request")); return; } failHandshake(new Error("Herdr subscription emitted an event before acknowledgement.")); return; } if (record.error) { disconnect(new HerdrRpcError(String(record.error.message ?? "Herdr subscription failed."), typeof record.id === "string" ? record.id : "", typeof record.error.code === "string" ? record.error.code : undefined)); socket.destroy(); return; } listener(value); } });
-		socket.on("error", (error) => disconnect(error));
-		socket.on("close", () => disconnect(new Error("Herdr subscription connection was lost.")));
-		socket.on("connect", () => socket.write(`${JSON.stringify({ id, method: "events.subscribe", params: { subscriptions } })}\n`));
-		await acknowledgement;
-		return () => { intentional = true; clearTimeout(timer); socket.destroy(); };
-	}
-}
-
-async function waitForSocket(socketPath: string, child: ChildProcess): Promise<void> {
-	for (let attempt = 0; attempt < 100; attempt++) {
-		if (child.exitCode !== null) throw new Error(`SSH StreamLocal forwarding exited with code ${child.exitCode}.`);
-		try { const stat = fs.lstatSync(socketPath); if (stat.isSocket()) { fs.chmodSync(socketPath, 0o600); return; } } catch {}
-		await new Promise((resolve) => setTimeout(resolve, 25));
-	}
-	throw new Error("SSH StreamLocal forwarding did not create its local socket.");
-}
-async function terminateChild(child: ChildProcess): Promise<void> { const wait = (ms: number) => child.exitCode !== null || child.signalCode !== null ? Promise.resolve() : Promise.race([new Promise<void>((resolve) => child.once("exit", () => resolve())), new Promise<void>((resolve) => setTimeout(resolve, ms))]); if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM"); await wait(1_000); if (child.exitCode === null && child.signalCode === null) { child.kill("SIGKILL"); await wait(1_000); } }
-
-export async function connectHerdrMachine(machine: HerdrMachineReference, options: { sshBin?: string; env?: NodeJS.ProcessEnv } = {}): Promise<HerdrForwardedConnection> {
-	if (process.platform === "win32") throw new Error("Pane-native Herdr placement requires OpenSSH StreamLocal forwarding and is not supported on Windows.");
-	const endpoint = await discoverHerdrEndpoint(machine, options);
-	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-herdr-")); fs.chmodSync(dir, 0o700);
-	const children = new Set<ChildProcess>();
-	const forward = async (remotePath: string, name: string) => {
-		if (!path.posix.isAbsolute(remotePath)) throw new Error("Remote socket path must be absolute.");
-		const local = path.join(dir, `${name}.sock`);
-		const child = spawn(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), "-N", "-o", "StreamLocalBindUnlink=yes", "-L", `${local}:${remotePath}`, machine.target], { env: hardenedSshEnv(options.env), stdio: "ignore", windowsHide: true }); children.add(child);
-		const stop = async () => { await terminateChild(child); children.delete(child); try { fs.rmSync(local, { force: true }); } catch {} };
-		try { await waitForSocket(local, child); } catch (error) { await stop(); throw error; }
-		return { socketPath: local, close: stop };
-	};
-	const primary = await forward(endpoint.socket, "herdr").catch((error) => { fs.rmSync(dir, { recursive: true, force: true }); throw error; });
-	return { endpoint, socketPath: primary.socketPath, client: new SocketRpcClient(primary.socketPath), forwardRemoteSocket: forward, close: async () => { await Promise.all([...children].map(terminateChild)); children.clear(); fs.rmSync(dir, { recursive: true, force: true }); } };
-}