pi-subagents 0.80.0 → 0.81.0

package/bundle/chunk-5LFLVSTM.js

@@ -0,0 +1,260 @@
+// src/shared/types.ts
+import * as os from "node:os";
+import * as path from "node:path";
+var SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 3;
+var INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
+var INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
+var INTERCOM_SESSION_IDENTITY_EVENT = "intercom:session-identity";
+var SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
+var RUNNER_LAUNCHER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+var RUNNER_LAUNCHER_NAME_RULE = "must start with a letter or digit and use only letters, digits, '.', '_' or '-' (at most 128 characters)";
+var SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
+var SUBAGENT_PROCESS_TERMINAL_EVENT = "subagent:process-terminal";
+var SUBAGENT_FOREGROUND_COMPLETE_EVENT = "subagent:foreground-complete";
+var SUBAGENT_CONTROL_EVENT = "subagent:control-event";
+var SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
+var SUBAGENT_STEERING_NOTICE_EVENT = "subagent:steering-notice";
+var SUBAGENT_CHILD_STATUS_EVENT = "subagent:child-status";
+var SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
+var SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
+var FLEET_KEYBINDING_ACTIONS = [
+  "close",
+  "scrollUp",
+  "scrollDown",
+  "selectUp",
+  "selectDown",
+  "selectFirst",
+  "selectLast",
+  "pageUp",
+  "pageDown",
+  "refresh",
+  "steer",
+  "inspect",
+  "stop",
+  "toggleTools"
+];
+var DEFAULT_MAX_OUTPUT = {
+  bytes: 200 * 1024,
+  lines: 5e3
+};
+var DEFAULT_ARTIFACT_CONFIG = {
+  enabled: true,
+  dir: "session",
+  includeInput: true,
+  includeOutput: true,
+  includeJsonl: false,
+  includeTranscript: true,
+  includeMetadata: true,
+  cleanupDays: 7
+};
+function sanitizeTempScopeSegment(value) {
+  const sanitized = value.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized || "unknown";
+}
+function resolveTempScopeId(options) {
+  const env = options?.env ?? process.env;
+  const getuid = options && Object.hasOwn(options, "getuid") ? options.getuid : process.getuid?.bind(process);
+  if (typeof getuid === "function") {
+    return `uid-${getuid()}`;
+  }
+  for (const key of ["USERNAME", "USER", "LOGNAME"]) {
+    const value = env[key];
+    if (value) return `user-${sanitizeTempScopeSegment(value)}`;
+  }
+  const userInfo2 = options && Object.hasOwn(options, "userInfo") ? options.userInfo : os.userInfo;
+  try {
+    const username = userInfo2?.().username;
+    if (username) return `user-${sanitizeTempScopeSegment(username)}`;
+  } catch {
+  }
+  const homedir2 = env.USERPROFILE ?? env.HOME;
+  if (homedir2) return `home-${sanitizeTempScopeSegment(homedir2)}`;
+  const resolveHomedir = options && Object.hasOwn(options, "homedir") ? options.homedir : os.homedir;
+  try {
+    const fallbackHomedir = resolveHomedir?.();
+    if (fallbackHomedir) return `home-${sanitizeTempScopeSegment(fallbackHomedir)}`;
+  } catch {
+  }
+  return "shared";
+}
+var configuredTempRoot = process.env.PI_SUBAGENTS_TEMP_ROOT?.trim();
+var TEMP_ROOT_DIR = configuredTempRoot ? path.resolve(configuredTempRoot) : path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
+var RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
+var ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
+var CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
+var TEMP_ARTIFACTS_DIR = path.join(TEMP_ROOT_DIR, "artifacts");
+var DIRS = {
+  results: RESULTS_DIR,
+  async: ASYNC_DIR,
+  chain: CHAIN_RUNS_DIR,
+  artifacts: TEMP_ARTIFACTS_DIR
+};
+var WIDGET_KEY = "subagent-async";
+var SLASH_RESULT_TYPE = "subagent-slash-result";
+var SLASH_TEXT_RESULT_TYPE = "subagent-slash-text-result";
+var SLASH_TEXT_VIEW_ONLY_DETAILS = { viewOnly: true };
+var SLASH_SUBAGENT_REQUEST_EVENT = "subagent:slash:request";
+var SLASH_SUBAGENT_STARTED_EVENT = "subagent:slash:started";
+var SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
+var SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
+var SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
+var POLL_INTERVAL_MS = 250;
+var WIDGET_ANIMATION_INTERVAL_MS = 1e3;
+var MAX_WIDGET_JOBS = 4;
+var DEFAULT_SUBAGENT_MAX_DEPTH = 2;
+var SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "validate", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "worktree.cleanup", "lane.status", "lane.recordMerge", "lane.recordSupersession", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.command", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "command.status", "command.yield", "command.cancel", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"];
+var DEFAULT_FORK_PREAMBLE = "You are a delegated subagent running from a fork of the parent session. Treat the inherited conversation as reference-only context, not a live thread to continue. Do not continue or answer prior messages as if they are waiting for a reply. Your sole job is to execute the task below and return a focused result for that task using your tools.";
+function getAsyncConfigPath(suffix) {
+  return path.join(TEMP_ROOT_DIR, `async-cfg-${suffix}.json`);
+}
+function wrapForkTask(task, preamble) {
+  if (preamble === false) return task;
+  const effectivePreamble = preamble ?? DEFAULT_FORK_PREAMBLE;
+  const wrappedPrefix = `${effectivePreamble}
+
+Task:
+`;
+  if (task.startsWith(wrappedPrefix)) return task;
+  return `${wrappedPrefix}${task}`;
+}
+function normalizeNonNegativeInteger(value) {
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  if (!Number.isInteger(parsed) || parsed < 0) return void 0;
+  return parsed;
+}
+function normalizeMaxSubagentDepth(value) {
+  return normalizeNonNegativeInteger(value);
+}
+var SUBAGENT_MAX_DEPTH_ENV = "PI_SUBAGENT_MAX_DEPTH";
+function resolveCurrentMaxSubagentDepth(configMaxDepth, runtime) {
+  return normalizeMaxSubagentDepth(runtime ? runtime.maxDepth : process.env[SUBAGENT_MAX_DEPTH_ENV]) ?? normalizeMaxSubagentDepth(configMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
+}
+function resolveChildMaxSubagentDepth(parentMaxDepth, agentMaxDepth) {
+  const normalizedParent = normalizeMaxSubagentDepth(parentMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
+  const normalizedAgent = normalizeMaxSubagentDepth(agentMaxDepth);
+  return normalizedAgent === void 0 ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
+}
+function resolveCurrentSubagentDepth(runtime) {
+  const depth = runtime ? runtime.depth : 0;
+  return Number.isFinite(depth) ? depth : 0;
+}
+function checkSubagentDepth(configMaxDepth, runtime) {
+  const depth = resolveCurrentSubagentDepth(runtime);
+  const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth, runtime);
+  const blocked = depth >= maxDepth;
+  return { blocked, depth, maxDepth };
+}
+function resolveChildDepth(maxDepth, runtime) {
+  return {
+    depth: resolveCurrentSubagentDepth(runtime) + 1,
+    maxDepth: normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth(void 0, runtime)
+  };
+}
+function normalizeMaxSubagentSpawnsPerSession(value) {
+  return normalizeNonNegativeInteger(value);
+}
+function resolveMaxSubagentSpawnsPerSession(configMaxSpawns) {
+  const envMaxSpawns = normalizeMaxSubagentSpawnsPerSession(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_SESSION);
+  if (envMaxSpawns !== void 0) return envMaxSpawns === 0 ? void 0 : envMaxSpawns;
+  const configuredMaxSpawns = normalizeMaxSubagentSpawnsPerSession(configMaxSpawns);
+  return configuredMaxSpawns === 0 ? void 0 : configuredMaxSpawns;
+}
+var DEFAULT_MAX_SUBAGENT_SPAWNS_PER_RUN = 64;
+function normalizeMaxSubagentSpawnsPerRun(value) {
+  const normalized = normalizeNonNegativeInteger(value);
+  return normalized !== void 0 && normalized > 0 ? normalized : void 0;
+}
+function resolveMaxSubagentSpawnsPerRun(configMaxSpawns) {
+  return normalizeMaxSubagentSpawnsPerRun(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_RUN) ?? normalizeMaxSubagentSpawnsPerRun(configMaxSpawns) ?? DEFAULT_MAX_SUBAGENT_SPAWNS_PER_RUN;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function truncateOutput(output, config, artifactPath) {
+  const lines = output.split("\n");
+  const bytes = Buffer.byteLength(output, "utf-8");
+  if (bytes <= config.bytes && lines.length <= config.lines) {
+    return { text: output, truncated: false };
+  }
+  let truncatedLines = lines;
+  if (lines.length > config.lines) {
+    truncatedLines = lines.slice(0, config.lines);
+  }
+  let result = truncatedLines.join("\n");
+  if (Buffer.byteLength(result, "utf-8") > config.bytes) {
+    let low = 0;
+    let high = result.length;
+    while (low < high) {
+      const mid = Math.floor((low + high + 1) / 2);
+      if (Buffer.byteLength(result.slice(0, mid), "utf-8") <= config.bytes) {
+        low = mid;
+      } else {
+        high = mid - 1;
+      }
+    }
+    result = result.slice(0, low);
+  }
+  const keptLines = result.split("\n").length;
+  const marker = `[TRUNCATED: showing first ${keptLines} of ${lines.length} lines, ${formatBytes(Buffer.byteLength(result))} of ${formatBytes(bytes)}${artifactPath ? ` - full output at ${artifactPath}` : ""}]
+`;
+  return {
+    text: marker + result,
+    truncated: true,
+    originalBytes: bytes,
+    originalLines: lines.length,
+    artifactPath
+  };
+}
+
+export {
+  SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+  INTERCOM_DETACH_REQUEST_EVENT,
+  INTERCOM_DETACH_RESPONSE_EVENT,
+  INTERCOM_SESSION_IDENTITY_EVENT,
+  SUBAGENT_ASYNC_STARTED_EVENT,
+  RUNNER_LAUNCHER_NAME_PATTERN,
+  RUNNER_LAUNCHER_NAME_RULE,
+  SUBAGENT_ASYNC_COMPLETE_EVENT,
+  SUBAGENT_PROCESS_TERMINAL_EVENT,
+  SUBAGENT_FOREGROUND_COMPLETE_EVENT,
+  SUBAGENT_CONTROL_EVENT,
+  SUBAGENT_CONTROL_INTERCOM_EVENT,
+  SUBAGENT_STEERING_NOTICE_EVENT,
+  SUBAGENT_CHILD_STATUS_EVENT,
+  SUBAGENT_RESULT_INTERCOM_EVENT,
+  SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT,
+  FLEET_KEYBINDING_ACTIONS,
+  DEFAULT_MAX_OUTPUT,
+  DEFAULT_ARTIFACT_CONFIG,
+  TEMP_ROOT_DIR,
+  ASYNC_DIR,
+  CHAIN_RUNS_DIR,
+  TEMP_ARTIFACTS_DIR,
+  DIRS,
+  WIDGET_KEY,
+  SLASH_RESULT_TYPE,
+  SLASH_TEXT_RESULT_TYPE,
+  SLASH_TEXT_VIEW_ONLY_DETAILS,
+  SLASH_SUBAGENT_REQUEST_EVENT,
+  SLASH_SUBAGENT_STARTED_EVENT,
+  SLASH_SUBAGENT_RESPONSE_EVENT,
+  SLASH_SUBAGENT_UPDATE_EVENT,
+  SLASH_SUBAGENT_CANCEL_EVENT,
+  POLL_INTERVAL_MS,
+  WIDGET_ANIMATION_INTERVAL_MS,
+  MAX_WIDGET_JOBS,
+  SUBAGENT_ACTIONS,
+  DEFAULT_FORK_PREAMBLE,
+  getAsyncConfigPath,
+  wrapForkTask,
+  resolveCurrentMaxSubagentDepth,
+  resolveChildMaxSubagentDepth,
+  checkSubagentDepth,
+  resolveChildDepth,
+  resolveMaxSubagentSpawnsPerSession,
+  normalizeMaxSubagentSpawnsPerRun,
+  resolveMaxSubagentSpawnsPerRun,
+  truncateOutput
+};

package/bundle/chunk-62OCY2S4.js

@@ -0,0 +1,14 @@
+// src/api/inspectors.ts
+var INSPECTOR_REGISTER_EVENT = "pi-subagents:inspector-register:v1";
+function registerInspector(pi, plugin) {
+  const request = { version: 1, plugin };
+  pi.events.emit(INSPECTOR_REGISTER_EVENT, request);
+  if (!request.result) throw new Error("pi-subagents is not installed, not ready, or does not support inspector registration.");
+  if (!request.result.ok) throw request.result.error;
+  return request.result.registration;
+}
+
+export {
+  INSPECTOR_REGISTER_EVENT,
+  registerInspector
+};

package/bundle/chunk-74RT5YQE.js

@@ -0,0 +1,326 @@
+// src/runs/shared/herdr-connection.ts
+import { spawn, spawnSync } 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";
+var MAX_DISCOVERY_BYTES = 256 * 1024;
+var MAX_RPC_BYTES = 4 * 1024 * 1024;
+var SUBSCRIPTION_ACK_TIMEOUT_MS = 15e3;
+var HERDR_REMOTE_PATH = "$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+var 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="];
+function hardenedSshEnv(source = process.env) {
+  return { PATH: process.platform === "win32" ? source.PATH : "/usr/bin:/bin:/usr/sbin:/sbin", ...source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}, ...source.WINDIR ? { WINDIR: source.WINDIR } : {} };
+}
+function herdrSshArgs(source = process.env) {
+  return [...HERDR_SSH_BASE, ...source.SSH_AUTH_SOCK ? ["-o", `IdentityAgent=${source.SSH_AUTH_SOCK}`] : []];
+}
+var HerdrRpcError = class extends Error {
+  code;
+  requestId;
+  constructor(message, requestId, code) {
+    super(message);
+    this.name = "HerdrRpcError";
+    this.requestId = requestId;
+    this.code = code;
+  }
+};
+var HerdrTransportError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "HerdrTransportError";
+  }
+};
+function decodeHerdrJsonLine(line) {
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+  } catch {
+    throw new Error("Herdr emitted malformed JSON or UTF-8.");
+  }
+}
+function shellQuoteRemote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function remoteShellCommand(script, args = []) {
+  return `sh -c ${shellQuoteRemote(`PATH="${HERDR_REMOTE_PATH}"; export PATH; ${script}`)} sh${args.map((arg) => ` ${shellQuoteRemote(arg)}`).join("")}`;
+}
+function canonicalHerdrSession(session) {
+  return session && session !== "default" ? session : null;
+}
+function sshEnvCommand(session, command) {
+  const selected = canonicalHerdrSession(session), assignment = selected ? ` HERDR_SESSION=${shellQuoteRemote(selected)}` : "";
+  return `/usr/bin/env -u HERDR_SOCKET_PATH -u HERDR_SESSION${assignment} ${remoteShellCommand(command)}`;
+}
+function runHerdrRemoteCommand(machine, command, options = {}) {
+  return spawnSync(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { encoding: "utf8", env: hardenedSshEnv(options.env), timeout: options.timeout ?? 15e3, maxBuffer: options.maxBuffer ?? MAX_DISCOVERY_BYTES, windowsHide: true });
+}
+function runHerdrRemoteCommandAsync(machine, command, options = {}) {
+  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 = [], stderr = [], maxBuffer = options.maxBuffer ?? MAX_DISCOVERY_BYTES;
+    let stdoutBytes = 0, stderrBytes = 0, error, settled = false, escalation;
+    const finish = (status, 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);
+        }
+      }, 1e3);
+      escalation.unref?.();
+    };
+    const collect = (target, stream) => (chunk) => {
+      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 ?? 15e3);
+    timer.unref?.();
+  });
+}
+function parseHerdrEndpoint(value, expectedSession) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } 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;
+  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 };
+}
+async function discoverHerdrEndpoint(machine, options = {}) {
+  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: 15e3, 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);
+}
+var SocketRpcClient = class {
+  #socketPath;
+  #subscriptionAckTimeoutMs;
+  #next = 0;
+  constructor(socketPath, subscriptionAckTimeoutMs = SUBSCRIPTION_ACK_TIMEOUT_MS) {
+    this.#socketPath = socketPath;
+    this.#subscriptionAckTimeoutMs = subscriptionAckTimeoutMs;
+  }
+  call(method, params = {}, timeoutMs = 15e3) {
+    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, value) => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        socket.destroy();
+        error ? reject(error) : resolve(value);
+      };
+      socket.on("connect", () => socket.write(`${JSON.stringify({ id, method, params })}
+`));
+      socket.on("data", (chunk) => {
+        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;
+        try {
+          frame = decodeHerdrJsonLine(data.subarray(0, newline));
+        } catch {
+          finish(new Error("Herdr RPC returned malformed JSON or UTF-8."));
+          return;
+        }
+        const record = frame;
+        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 : void 0));
+        else finish(void 0, 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, listener, onDisconnect) {
+    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, rejectAck;
+    const acknowledgement = new Promise((resolve, reject) => {
+      resolveAck = resolve;
+      rejectAck = reject;
+    });
+    const failHandshake = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      rejectAck(error);
+    };
+    const disconnect = (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) => {
+      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;
+        try {
+          value = decodeHerdrJsonLine(line);
+        } catch {
+          disconnect(new Error("Herdr subscription emitted malformed JSON or UTF-8."));
+          socket.destroy();
+          return;
+        }
+        const record = value;
+        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 : void 0));
+              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 : void 0));
+          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 } })}
+`));
+    await acknowledgement;
+    return () => {
+      intentional = true;
+      clearTimeout(timer);
+      socket.destroy();
+    };
+  }
+};
+async function waitForSocket(socketPath, child) {
+  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, 384);
+        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) {
+  const wait = (ms) => child.exitCode !== null || child.signalCode !== null ? Promise.resolve() : Promise.race([new Promise((resolve) => child.once("exit", () => resolve())), new Promise((resolve) => setTimeout(resolve, ms))]);
+  if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+  await wait(1e3);
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill("SIGKILL");
+    await wait(1e3);
+  }
+}
+async function connectHerdrMachine(machine, options = {}) {
+  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, 448);
+  const children = /* @__PURE__ */ new Set();
+  const forward = async (remotePath, name) => {
+    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 });
+  } };
+}
+
+export {
+  remoteShellCommand,
+  runHerdrRemoteCommand,
+  runHerdrRemoteCommandAsync,
+  connectHerdrMachine
+};