@rahularya01/pi-essentials 0.1.0

package/src/security/ssrf.ts

@@ -0,0 +1,237 @@
+import { lookup } from "node:dns/promises";
+import net from "node:net";
+
+const BLOCKED_HOSTS = new Set(["localhost", "localhost.localdomain", "0.0.0.0", "::1", "ip6-localhost", "ip6-loopback"]);
+
+const BLOCKED_SUFFIXES = [".localhost", ".local", ".internal", ".home.arpa", ".lan"];
+
+export type SsrfIssue =
+  | "unsupported-protocol"
+  | "invalid-url"
+  | "blocked-host"
+  | "blocked-ip"
+  | "dns-failure";
+
+export class SsrfError extends Error {
+  readonly issue: SsrfIssue;
+  constructor(message: string, issue: SsrfIssue) {
+    super(message);
+    this.name = "SsrfError";
+    this.issue = issue;
+  }
+}
+
+export function parseHttpUrl(raw: string): URL {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new SsrfError(`Invalid URL: ${raw}`, "invalid-url");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new SsrfError(`Only http and https URLs are allowed (got ${url.protocol})`, "unsupported-protocol");
+  }
+  if (url.username || url.password) {
+    throw new SsrfError("URLs with embedded credentials are not allowed", "invalid-url");
+  }
+  return url;
+}
+
+/** Strip IPv6 brackets, a trailing FQDN dot, and case. */
+export function normalizeHostname(hostname: string): string {
+  return hostname.replace(/^\[|\]$/g, "").replace(/\.+$/, "").toLowerCase();
+}
+
+export function isBlockedHostname(hostname: string): boolean {
+  const host = normalizeHostname(hostname);
+  if (!host) return true;
+  if (BLOCKED_HOSTS.has(host)) return true;
+  if (BLOCKED_SUFFIXES.some((suffix) => host.endsWith(suffix))) return true;
+  if (host === "metadata.google.internal" || host === "metadata") return true;
+  return false;
+}
+
+function isBlockedIpv4(ip: string): boolean {
+  const parts = ip.split(".").map((p) => Number(p));
+  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  const [a, b, c] = parts;
+  if (a === 0 || a === 10 || a === 127) return true;
+  if (a === 169 && b === 254) return true; // link-local / cloud metadata
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
+  if (a === 192 && b === 0 && c === 0) return true; // IETF protocol assignments
+  if (a === 198 && (b === 18 || b === 19)) return true; // benchmarking
+  if (a >= 224) return true; // multicast / reserved / broadcast
+  return false;
+}
+
+export function isBlockedIp(ip: string): boolean {
+  const version = net.isIP(ip);
+  if (!version) return true;
+  if (version === 4) return isBlockedIpv4(ip);
+
+  const groups = expandIpv6(ip);
+  if (!groups) return true;
+
+  // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d) addresses.
+  const isZeroPrefix = groups.slice(0, 5).every((g) => g === 0);
+  if (isZeroPrefix && (groups[5] === 0xffff || groups[5] === 0)) {
+    const mapped = `${groups[6] >> 8}.${groups[6] & 0xff}.${groups[7] >> 8}.${groups[7] & 0xff}`;
+    if (groups[5] === 0 && groups[6] === 0 && groups[7] <= 1) return true; // :: and ::1
+    return isBlockedIpv4(mapped);
+  }
+
+  const [first] = groups;
+  if ((first & 0xffc0) === 0xfe80) return true; // fe80::/10 link-local
+  if ((first & 0xfe00) === 0xfc00) return true; // fc00::/7 unique local
+  if ((first & 0xff00) === 0xff00) return true; // ff00::/8 multicast
+  if (first === 0x0064 && groups[1] === 0xff9b) return true; // 64:ff9b::/96 NAT64
+  if (first === 0x0100 && groups[1] === 0 && groups[2] === 0 && groups[3] === 0) return true; // 100::/64 discard
+  if (first === 0x2001 && groups[1] === 0x0db8) return true; // documentation
+  return false;
+}
+
+/** Expand any valid IPv6 textual form into eight 16-bit groups. */
+export function expandIpv6(ip: string): number[] | undefined {
+  if (!net.isIPv6(ip)) return undefined;
+  let text = ip.toLowerCase().replace(/%.*$/, ""); // drop zone id
+
+  // Trailing dotted-quad form: ::ffff:127.0.0.1
+  const dotted = text.match(/(\d{1,3}(?:\.\d{1,3}){3})$/);
+  if (dotted) {
+    const octets = dotted[1].split(".").map(Number);
+    if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return undefined;
+    const hi = ((octets[0] << 8) | octets[1]).toString(16);
+    const lo = ((octets[2] << 8) | octets[3]).toString(16);
+    text = `${text.slice(0, dotted.index)}${hi}:${lo}`;
+  }
+
+  const [head, tail, extra] = text.split("::");
+  if (extra !== undefined) return undefined;
+  const parse = (part: string): number[] =>
+    part
+      .split(":")
+      .filter((chunk) => chunk.length > 0)
+      .map((chunk) => Number.parseInt(chunk, 16));
+
+  const left = parse(head ?? "");
+  const right = tail === undefined ? [] : parse(tail);
+  const fill = tail === undefined ? 0 : 8 - left.length - right.length;
+  if (fill < 0) return undefined;
+  const groups = [...left, ...new Array<number>(Math.max(0, fill)).fill(0), ...right];
+  if (groups.length !== 8 || groups.some((g) => !Number.isInteger(g) || g < 0 || g > 0xffff)) return undefined;
+  return groups;
+}
+
+export interface PinnedAddress {
+  address: string;
+  family: number;
+}
+
+export interface SafeUrl {
+  url: URL;
+  /**
+   * The exact addresses this URL was validated against. Connecting to these
+   * instead of re-resolving the hostname is what closes the DNS-rebinding window
+   * between validation and connect.
+   */
+  addresses: PinnedAddress[];
+}
+
+export interface SsrfPolicy {
+  /**
+   * Hosts explicitly trusted by the user, as `host` or `host:port` (a bare host
+   * matches any port). Used for deliberately local services such as a self-hosted
+   * SearXNG instance.
+   */
+  allowedHosts?: ReadonlySet<string>;
+}
+
+/** True when the user has explicitly allowed this host (optionally per port). */
+export function isAllowedHost(url: URL, policy?: SsrfPolicy): boolean {
+  const allowed = policy?.allowedHosts;
+  if (!allowed || allowed.size === 0) return false;
+  const host = normalizeHostname(url.hostname);
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  return allowed.has(host) || allowed.has(`${host}:${port}`);
+}
+
+function explicitPort(entry: string): string | undefined {
+  const withoutScheme = entry.includes("://") ? entry.slice(entry.indexOf("://") + 3) : entry;
+  const authority = withoutScheme.split(/[/?#]/, 1)[0].split("@").pop() ?? "";
+  const match = authority.startsWith("[") ? /^\[[^\]]+\]:(\d+)$/.exec(authority) : /:(\d+)$/.exec(authority);
+  return match?.[1];
+}
+
+/** Normalize an allowlist entry the same way `isAllowedHost` normalizes a URL. */
+export function normalizeAllowedHost(entry: string): string | undefined {
+  const trimmed = entry.trim();
+  if (!trimmed) return undefined;
+  try {
+    // URL.port intentionally erases explicit default ports. Extract the port
+    // from the original authority so `host:80` does not become a host-wide grant.
+    const port = explicitPort(trimmed);
+    const parsed = new URL(trimmed.includes("://") ? trimmed : `http://${trimmed}`);
+    const host = normalizeHostname(parsed.hostname);
+    if (!host) return undefined;
+    return port ? `${host}:${port}` : host;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Validate a URL and return the addresses it resolved to, so the caller can pin
+ * the connection to them.
+ */
+export async function resolveSafeUrl(raw: string, policy?: SsrfPolicy): Promise<SafeUrl> {
+  const url = parseHttpUrl(raw);
+  const hostname = normalizeHostname(url.hostname);
+  const exempt = isAllowedHost(url, policy);
+
+  if (!exempt && isBlockedHostname(url.hostname)) {
+    throw new SsrfError(`Blocked host: ${url.hostname}`, "blocked-host");
+  }
+
+  const literal = net.isIP(hostname);
+  if (literal) {
+    if (!exempt && isBlockedIp(hostname)) {
+      throw new SsrfError(`Blocked IP address: ${url.hostname}`, "blocked-ip");
+    }
+    return { url, addresses: [{ address: hostname, family: literal }] };
+  }
+
+  let results: Array<{ address: string; family: number }>;
+  try {
+    results = await lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    throw new SsrfError(`DNS lookup failed for ${url.hostname}`, "dns-failure");
+  }
+  if (results.length === 0) {
+    throw new SsrfError(`DNS lookup returned no addresses for ${url.hostname}`, "dns-failure");
+  }
+  if (!exempt) {
+    for (const result of results) {
+      if (isBlockedIp(result.address)) {
+        throw new SsrfError(`Host ${url.hostname} resolves to blocked address ${result.address}`, "blocked-ip");
+      }
+    }
+  }
+  return {
+    url,
+    addresses: results.map((result) => ({ address: result.address, family: result.family || net.isIP(result.address) })),
+  };
+}
+
+export async function assertSafeUrl(raw: string, policy?: SsrfPolicy): Promise<URL> {
+  return (await resolveSafeUrl(raw, policy)).url;
+}
+
+export function redirectUrl(current: URL, location: string): URL {
+  try {
+    return new URL(location, current);
+  } catch {
+    throw new SsrfError(`Invalid redirect location: ${location}`, "invalid-url");
+  }
+}

package/src/subagents/activity.ts

@@ -0,0 +1,132 @@
+import { GLYPH, oneLine } from "../ui/render.ts";
+
+const MAX_EVENTS = 48;
+const SECRET_KEY = /(?:api[_-]?key|token|secret|password|passwd|authorization|cookie|credential)/i;
+const ARG_KEYS = ["command", "path", "file", "file_path", "filePath", "query", "url", "pattern", "glob", "target", "name"];
+
+export type TraceEvent =
+  | { kind: "tool"; id?: string; name: string; args?: string; status: "running" | "ok" | "error" }
+  | { kind: "text"; text: string };
+
+export interface LiveTrace {
+  activity: string;
+  events: TraceEvent[];
+  textBuffer: string;
+}
+
+export function emptyTrace(): LiveTrace {
+  return { activity: "", events: [], textBuffer: "" };
+}
+
+function pushEvent(trace: LiveTrace, event: TraceEvent): void {
+  const last = trace.events.at(-1);
+  if (event.kind === "text" && last?.kind === "text" && last.text === event.text) return;
+  trace.events.push(event);
+  if (trace.events.length > MAX_EVENTS) trace.events.splice(0, trace.events.length - MAX_EVENTS);
+}
+
+function stringArg(value: unknown): string | undefined {
+  if (typeof value === "string" && value.trim()) return oneLine(value, 48);
+  return undefined;
+}
+
+export function summarizeToolArgs(args: unknown): string | undefined {
+  if (!args || typeof args !== "object") return undefined;
+  const rec = args as Record<string, unknown>;
+  for (const key of ARG_KEYS) {
+    if (SECRET_KEY.test(key)) continue;
+    const value = stringArg(rec[key]);
+    if (value) return value;
+  }
+  for (const [key, raw] of Object.entries(rec)) {
+    if (SECRET_KEY.test(key)) continue;
+    const value = stringArg(raw);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+export function summarizeTool(name: string, args: unknown): string {
+  const detail = summarizeToolArgs(args);
+  const label = name.trim() || "tool";
+  return detail ? `${label} ${GLYPH.sep} ${detail}` : label;
+}
+
+function recordActivity(trace: LiveTrace, activity: string): boolean {
+  const next = oneLine(activity, 64);
+  if (!next || next === trace.activity) return false;
+  trace.activity = next;
+  return true;
+}
+
+function findTool(trace: LiveTrace, id: string | undefined, name: string): Extract<TraceEvent, { kind: "tool" }> | undefined {
+  if (id) {
+    for (let i = trace.events.length - 1; i >= 0; i--) {
+      const event = trace.events[i];
+      if (event.kind === "tool" && event.id === id) return event;
+    }
+  }
+  for (let i = trace.events.length - 1; i >= 0; i--) {
+    const event = trace.events[i];
+    if (event.kind === "tool" && event.name === name && event.status === "running") return event;
+  }
+  return undefined;
+}
+
+/**
+ * Fold a child `pi --mode json` event into a live trace.
+ * Returns true when the fleet/inspector should redraw.
+ */
+export function applySessionEvent(trace: LiveTrace, event: unknown): boolean {
+  if (!event || typeof event !== "object") return false;
+  const rec = event as {
+    type?: string;
+    toolCallId?: string;
+    toolName?: string;
+    isError?: boolean;
+    args?: unknown;
+    assistantMessageEvent?: { type?: string; delta?: string };
+    message?: { role?: string; content?: unknown; errorMessage?: string };
+  };
+
+  if (rec.toolName === "subagent_result") return false;
+
+  if (rec.type === "tool_execution_start" && rec.toolName) {
+    const args = summarizeToolArgs(rec.args);
+    pushEvent(trace, { kind: "tool", id: rec.toolCallId, name: rec.toolName, args, status: "running" });
+    return recordActivity(trace, summarizeTool(rec.toolName, rec.args)) || true;
+  }
+
+  if (rec.type === "tool_execution_end" && rec.toolName) {
+    const tool = findTool(trace, rec.toolCallId, rec.toolName);
+    const status = rec.isError ? "error" : "ok";
+    if (tool) tool.status = status;
+    else pushEvent(trace, { kind: "tool", id: rec.toolCallId, name: rec.toolName, status });
+    return recordActivity(trace, rec.isError ? `${rec.toolName} failed` : summarizeTool(rec.toolName, rec.args)) || true;
+  }
+
+  if (rec.type === "message_update") {
+    const delta = rec.assistantMessageEvent;
+    if (delta?.type === "text_delta" && typeof delta.delta === "string" && delta.delta) {
+      trace.textBuffer += delta.delta;
+      return recordActivity(trace, trace.textBuffer);
+    }
+    return false;
+  }
+
+  if (rec.type === "message_end" && rec.message?.role === "assistant") {
+    if (rec.message.errorMessage) {
+      pushEvent(trace, { kind: "text", text: oneLine(rec.message.errorMessage, 120) });
+      return recordActivity(trace, rec.message.errorMessage) || true;
+    }
+    const text = trace.textBuffer.trim();
+    trace.textBuffer = "";
+    if (text) {
+      pushEvent(trace, { kind: "text", text: oneLine(text, 160) });
+      return recordActivity(trace, text) || true;
+    }
+    return false;
+  }
+
+  return false;
+}

package/src/subagents/builtins/oracle.md

@@ -0,0 +1,11 @@
+---
+name: oracle
+description: Second opinion before acting. Challenge assumptions. Do not edit files.
+tools: read, grep, find, ls
+---
+You are an oracle. Challenge the plan or diagnosis in the task.
+
+Rules:
+- Do not edit files.
+- Surface hidden assumptions, alternative explanations, and missing evidence.
+- Be terse. Lead with the verdict, then the strongest objections, then what would change your mind.

package/src/subagents/builtins/reviewer.md

@@ -0,0 +1,11 @@
+---
+name: reviewer
+description: Code review against the task. Check correctness, tests, edge cases, and simplicity. Read-only by default.
+tools: read, grep, find, ls, bash
+---
+You are a reviewer. Inspect the current change or described task.
+
+Rules:
+- Do not implement new features. Small obvious fixes may be described, not applied, unless the task explicitly asks you to edit.
+- Look for correctness bugs, missing tests, edge cases, and unnecessary complexity.
+- Return a concise review: findings first, then residual risks, then what looks solid.

package/src/subagents/builtins/scout.md

@@ -0,0 +1,12 @@
+---
+name: scout
+description: Fast local codebase recon. Find relevant files, entry points, data flow, and risks. Read-only.
+tools: read, grep, find, ls
+---
+You are a scout. Explore the repository to answer the task with evidence.
+
+Rules:
+- Prefer read, grep, find, and ls. Do not edit files.
+- Cite file paths and brief quotes.
+- Return a concise recon brief: relevant files, how data flows, and risks.
+- If something is unclear, say what you could not verify.

package/src/subagents/builtins/worker.md

@@ -0,0 +1,11 @@
+---
+name: worker
+description: Implementation agent. Edit files, run checks, and escalate unclear decisions instead of guessing.
+---
+You are a worker. Implement the assigned task in this repository.
+
+Rules:
+- Make focused changes. Do not expand scope.
+- Validate with tests or typechecks when they exist.
+- If a decision needs the user, stop and report the options instead of guessing.
+- Return what you changed, how you verified it, and anything left unfinished.

package/src/subagents/discover.ts

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, getProjectPiDir } from "../paths.ts";
+import { parseAgentMarkdown, type AgentDefinition, type AgentScope } from "./types.ts";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+function loadDir(dir: string, source: AgentDefinition["source"]): AgentDefinition[] {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out: AgentDefinition[] = [];
+  for (const entry of entries.sort()) {
+    if (!entry.toLowerCase().endsWith(".md")) continue;
+    const filePath = path.join(dir, entry);
+    try {
+      if (!fs.statSync(filePath).isFile()) continue;
+      const markdown = fs.readFileSync(filePath, "utf8");
+      const agent = parseAgentMarkdown(markdown, path.basename(entry, path.extname(entry)), source, filePath);
+      if (agent.name) out.push(agent);
+    } catch {
+      // Skip unreadable or malformed agent files rather than failing discovery.
+    }
+  }
+  return out;
+}
+
+function loadBuiltins(): AgentDefinition[] {
+  return loadDir(path.join(here, "builtins"), "builtin");
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDefinition[] {
+  const byName = new Map<string, AgentDefinition>();
+  for (const agent of loadBuiltins()) byName.set(agent.name, agent);
+  if (scope === "user" || scope === "both") {
+    for (const agent of loadDir(path.join(getAgentDir(), "agents"), "user")) byName.set(agent.name, agent);
+  }
+  if (scope === "project" || scope === "both") {
+    for (const agent of loadDir(path.join(getProjectPiDir(cwd), "agents"), "project")) byName.set(agent.name, agent);
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function formatAgentList(agents: AgentDefinition[]): string {
+  if (agents.length === 0) return "none";
+  const width = Math.max(...agents.map((a) => a.name.length));
+  return agents
+    .map((a) => `${a.name.padEnd(width)}  [${a.source}] ${a.description || "(no description)"}`)
+    .join("\n");
+}

package/src/subagents/herdr.ts

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process";
+
+export type HerdrErrorCode = "HERDR_UNAVAILABLE" | "INVALID_RESPONSE" | "TIMEOUT";
+
+export type HerdrResult<T> = { ok: true; data: T } | { ok: false; error: { code: HerdrErrorCode; message: string } };
+
+export type SpawnLike = typeof spawn;
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+function herdrBin(): string {
+  return process.env.HERDR_BIN?.trim() || "herdr";
+}
+
+function fail(code: HerdrErrorCode, message: string): HerdrResult<never> {
+  return { ok: false, error: { code, message } };
+}
+
+/** Herdr replies with `{ result: ... }` on success or a bare object on some commands; tolerate both. */
+function unwrap(stdout: string): unknown {
+  const trimmed = stdout.trim();
+  if (!trimmed) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "result" in (parsed as Record<string, unknown>)) {
+      return (parsed as Record<string, unknown>).result;
+    }
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Run one `herdr` subcommand and parse its JSON reply. Never throws. */
+export function runHerdr(args: string[], options: { timeoutMs?: number; spawnImpl?: SpawnLike } = {}): Promise<HerdrResult<unknown>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const spawnImpl = options.spawnImpl ?? spawn;
+  return new Promise((resolve) => {
+    let proc: ReturnType<typeof spawn>;
+    try {
+      proc = spawnImpl(herdrBin(), args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      resolve(fail("HERDR_UNAVAILABLE", `Could not start herdr: ${(error as Error).message}`));
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (result: HerdrResult<unknown>) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      finish(fail("TIMEOUT", `herdr ${args.join(" ")} timed out after ${timeoutMs}ms.`));
+    }, timeoutMs);
+    timer.unref?.();
+
+    proc.stdout?.setEncoding("utf8");
+    proc.stdout?.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    proc.stderr?.setEncoding("utf8");
+    proc.stderr?.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    proc.on("error", (error) => {
+      const code = (error as NodeJS.ErrnoException).code;
+      finish(
+        fail(
+          "HERDR_UNAVAILABLE",
+          code === "ENOENT"
+            ? "herdr is not installed or not on PATH. Install Herdr, or set HERDR_BIN."
+            : error.message,
+        ),
+      );
+    });
+    proc.on("close", (exitCode) => {
+      if (exitCode !== 0) {
+        finish(fail("INVALID_RESPONSE", stderr.trim() || `herdr ${args[0] ?? ""} exited with code ${exitCode}.`));
+        return;
+      }
+      finish({ ok: true, data: unwrap(stdout) });
+    });
+  });
+}
+
+function extractPaneId(data: unknown): string | undefined {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return undefined;
+  const record = data as Record<string, unknown>;
+  const pane =
+    record.pane && typeof record.pane === "object" && !Array.isArray(record.pane)
+      ? (record.pane as Record<string, unknown>)
+      : record;
+  for (const key of ["pane_id", "paneId", "id"]) {
+    const value = pane[key];
+    if (typeof value === "string" && value) return value;
+  }
+  return undefined;
+}
+
+function quoteArg(value: string, platform: NodeJS.Platform): string {
+  if (platform === "win32") return `"${value.replaceAll('"', '\\"')}"`;
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Build a single shell-quoted command string for `herdr pane run`, which executes it
+ * through the pane's own shell. Every argument must come from values we generate
+ * ourselves (paths, flags) -- never from model or user-controlled text -- so quoting
+ * mistakes cannot become a shell-injection path from an untrusted source.
+ */
+export function buildPaneCommand(exe: string, args: string[], platform: NodeJS.Platform = process.platform): string {
+  return [exe, ...args].map((part) => quoteArg(part, platform)).join(" ");
+}
+
+export interface OpenInspectorPaneResult {
+  ok: boolean;
+  paneId?: string;
+  message?: string;
+}
+
+/** Open a new Herdr pane beside the current one and run `command` in it. Best-effort; never throws. */
+export async function openInspectorPane(
+  options: { cwd: string; command: string; spawnImpl?: SpawnLike },
+): Promise<OpenInspectorPaneResult> {
+  const probe = await runHerdr(["--version"], { timeoutMs: 5_000, spawnImpl: options.spawnImpl });
+  if (!probe.ok) return { ok: false, message: `Herdr is not available: ${probe.error.message}` };
+
+  const split = await runHerdr(
+    ["pane", "split", "--current", "--direction", "right", "--cwd", options.cwd, "--no-focus"],
+    { spawnImpl: options.spawnImpl },
+  );
+  if (!split.ok) return { ok: false, message: `Could not open a Herdr pane: ${split.error.message}` };
+
+  const paneId = extractPaneId(split.data);
+  if (!paneId) return { ok: false, message: "Herdr did not return a pane id for the new pane." };
+
+  const started = await runHerdr(["pane", "run", paneId, options.command], { spawnImpl: options.spawnImpl });
+  if (!started.ok) {
+    await runHerdr(["pane", "close", paneId], { timeoutMs: 5_000, spawnImpl: options.spawnImpl });
+    return { ok: false, message: `Could not start the inspector in the Herdr pane: ${started.error.message}` };
+  }
+
+  return { ok: true, paneId };
+}