pi-daddy 0.28.0 → 0.32.0

package/src/run-herdr.ts

@@ -1,386 +0,0 @@
-/**
- * Run a governed child in a herdr pane — ADR-0016 point 6.
- *
- * The second executor for the same plan. `runChild` spawns `pi` directly and captures its stdout;
- * `runHerdrPane` asks herdr to launch it in a visible, attachable terminal pane. `planSpawn` produces the
- * argv either way, so the grant is identical and only the *place it runs* differs.
- *
- * **Why go through herdr's CLI rather than the third-party `pi-herdr` extension.** That extension exposes
- * `agentArgs` and `env` as MODEL-facing tool parameters (R-30), which hands a model an argv array and the
- * environment variable the grant travels on. Here the model chooses a definition and a task; this package
- * builds the argv. Measured facts this relies on (`docs/probes/g16-herdr`):
- *
- *  - `herdr agent start … -- <args>` delivers argv **verbatim**, echoed back in the reply.
- *  - `--tools` is enforced inside a pane exactly as it is for a direct spawn; `--no-tools` yields none.
- *  - `herdr agent start` has **no `--env`**, but `tab create` / `pane split` do, and a pane's environment
- *    reaches the shell that launches the agent — verified by reading `$PI_GRANTS_GRANT` back out of a
- *    pane created with it. That is how the grant, depth and ledger path propagate on this path.
- *
- * **What a pane is not: a boundary.** It is a terminal. `--tools` remains the enforcement point, ADR-0012's
- * `bash` escape is unchanged, and a pane is *attachable by design*, so a human can type into a governed
- * child. Humans are not this project's threat model, but nothing here should be read as containing one.
- */
-
-import { rm } from "node:fs/promises";
-import { runWithFinalizers } from "./finalization.ts";
-import type { ChildRunResult } from "./run-child.ts";
-import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS } from "./run-child.ts";
-import { MAX_OPEN_PANES, markPaneSettled, trackPane, trimOpenPanes, untrackPane } from "./pane-reaper.ts";
-import { defaultExec, parseReply, type HerdrExec } from "./herdr-cli.ts";
-import { FRESH_LIFECYCLE_TIMEOUT_MS, readPane, waitForLifecycleBaseline, waitForSettled, observeHerdrSession, type PollTarget } from "./herdr-poll.ts";
-import { stageSystemPrompt } from "./herdr-stage.ts";
-import { uniqueAgentName } from "./herdr-name.ts";
-import { bundledHerdrPiLifecycleExtension } from "./herdr-pi-lifecycle.ts";
-import { startHerdrAgent } from "./herdr-start.ts";
-
-/**
- * Re-exported so importers of the executor still reach the protocol at the name they always used.
- *
- * Deliberate rather than lazy: `test/run-herdr.test.ts` imports `HerdrExec` from here and must pass
- * **unmodified** across this extraction — that is the only available proof the move changed no behaviour.
- */
-export { type HerdrExec, parseReply } from "./herdr-cli.ts";
-/** Re-exported: `splitSystemPrompt` moved to `./herdr-stage.ts` under the ceiling, its tests import it here. */
-export { splitSystemPrompt, stageSystemPrompt } from "./herdr-stage.ts";
-/** Re-exported: the name rules moved to `./herdr-name.ts` under the ceiling; tests import them here. */
-export { uniqueAgentName } from "./herdr-name.ts";
-/** Re-exported after startup retry extraction; existing executor importers keep this public constant. */
-export { PANE_READY_POLL_MS } from "./herdr-start.ts";
-/**
- * Re-exported so `test/run-herdr.test.ts` and any importer keep reaching these where they always were.
- *
- * `POLL_INTERVAL_MS` and `newSuffix` moved to `./herdr-poll.ts` under the 400-line ceiling; the names are part
- * of this module's surface and moving a file should not move an export.
- */
-export { DEFAULT_SNAPSHOT_LINES, POLL_INTERVAL_MS, readPane, tailLines, waitForLifecycleBaseline, waitForSettled, type PollTarget } from "./herdr-poll.ts";
-
-export interface HerdrRunRequest {
-  /** `planSpawn` args **without** the prompt — see `prompt`. */
-  args: string[];
-  /**
-   * The task, delivered with `herdr agent prompt` rather than as an argv element.
-   *
-   * This is strictly safer than the direct-spawn path, which has to defend a model-authored string from
-   * pi's argv parser by prefixing a space (`neutralisePrompt`, `docs/probes/g1-argv`). Here the task never
-   * reaches argv at all, so there is no parser in front of it.
-   */
-  prompt: string;
-  /** Grant/depth/ledger variables. Set on the PANE, which the agent's shell inherits. */
-  env: Record<string, string>;
-  cwd: string;
-  /** Unique pane and agent name. */
-  name: string;
-  /** herdr workspace to create the tab in. Omitted lets herdr choose. */
-  workspace?: string;
-  signal?: AbortSignal;
-  timeoutMs?: number;
-  maxOutputBytes?: number;
-  /**
-   * Leave the pane open after the run so a human can read or resume it.
-   *
-   * Default **false**: a fan-out that leaks a pane per child fills the operator's workspace, and
-   * `docs/probes/g16-herdr` records that panes are not trivially closable once orphaned.
-   */
-  keepPane?: boolean;
-  exec?: HerdrExec;
-  /**
-   * The pane's last few lines, re-reported every poll — a SNAPSHOT the consumer REPLACES, not appends.
-   *
-   * **Display only**, exactly as in `runChild`: the child's answer is still the returned `text`. Unlike
-   * `runChild`'s `onOutput`, this is not a stream: `agent read` returns a snapshot of a bounded terminal, and
-   * the previous append-shaped design produced an 89,000× amplification once a pane scrolled or passed the
-   * output cap. See `tailLines` in `./herdr-poll.ts`.
-   *
-   * Exceptions are swallowed; a renderer must not be able to break a governed run.
-   */
-  onSnapshot?: (lines: string[]) => void;
-  /** Available pane snapshots only, not a structured session transcript. Never awaited. */
-  onObservation?: (bytes: Uint8Array) => void;
-  /** How many pane lines to report per poll. Defaults to `DEFAULT_SNAPSHOT_LINES`. */
-  snapshotLines?: number;
-  /**
-   * The pane id, reported as soon as `tab create` returns it.
-   *
-   * Separate from `onOutput` because it arrives once and arrives *early*: it is what lets the parent print a
-   * name a human can switch to **while the child is alive**, which is the whole point of the pane surviving.
-   */
-  onPane?: (paneId: string, agentName: string) => void;
-  /** Called only after agent start and prompt both succeed; pane creation alone is still `starting`. */
-  onRunning?: (paneId: string, agentName: string) => void;
-  /** Security hook for attaching a writer lease to the tab. Unlike display callbacks, errors fail the run. */
-  onTab?: (tabId: string) => void;
-  /** Optional observation, unlike the required lease hook above. */
-  onNativeTab?: (tabId: string) => void;
-  onSessionReference?: PollTarget["onSessionReference"];
-  /** Close even a settled pane before releasing a writer lease; no post-lease prompt may remain live. */
-  closeOnSettle?: boolean;
-  /** Poll cadence override. Exists so tests do not wait `POLL_INTERVAL_MS` per state transition. */
-  pollIntervalMs?: number;
-}
-
-
-export class HerdrWriterCloseError extends Error {
-  constructor(tabId: string) {
-    super(`herdr writer tab ${tabId} could not be closed; retaining its workspace lease`);
-    this.name = "HerdrWriterCloseError";
-  }
-}
-
-/**
- * Run one governed child in a pane and return its output.
- *
- * Deliberately returns `ChildRunResult` — the same shape as `runChild` — so the extension can choose an
- * executor without knowing which one it got.
- */
-export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunResult> {
-  const exec = request.exec ?? defaultExec;
-  const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
-  const deadline = Date.now() + timeoutMs;
-  const empty: ChildRunResult = { code: null, text: "", truncated: false, timedOut: false, aborted: false };
-
-  // A-R3's rule, kept on this path too: checked BEFORE anything is created. An `AbortSignal` does not
-  // replay, so a check after the first `await` cannot see an abort that already happened — and we would
-  // have left a pane behind for a run that was never wanted.
-  if (request.signal?.aborted) return { ...empty, aborted: true };
-
-  // `--print` makes pi process the prompt and exit, so it never reaches the interactive readiness that
-  // `herdr agent start` waits for — the agent is simply never detected. Found by the first end-to-end run,
-  // which failed inside herdr with an empty reply. Caught here instead, naming the flag, because a
-  // mismatch between a plan and its executor is a caller bug and should read like one.
-  if (request.args.includes("--print") || request.args.includes("-p")) {
-    return {
-      ...empty,
-      spawnError:
-        "herdr needs an INTERACTIVE agent, but the plan contains --print, which makes pi exit immediately " +
-        "and never be detected. Build the plan with `print: false` for this executor.",
-    };
-  }
-
-  // A multi-line system prompt becomes a file; see `stageSystemPrompt`. Removed on every path that does not
-  // end up tracking a pane, because only a tracked pane's dir is reachable by a sweep.
-  const staged = await stageSystemPrompt(request.args);
-  if (staged.error) return { ...empty, spawnError: staged.error };
-  const promptDir = staged.promptDir;
-  let lifecycleExtension: string;
-  try {
-    lifecycleExtension = bundledHerdrPiLifecycleExtension();
-  } catch (error) {
-    if (promptDir) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
-    return { ...empty, spawnError: String(error) };
-  }
-  // Pi's `--no-extensions` disables discovery, not this explicit, package-pinned lifecycle reporter. It
-  // registers no tools; pi's existing `--tools` allowlist remains the governed child surface.
-  const effectiveArgs = [...staged.args, "-e", lifecycleExtension];
-
-  const create = ["tab", "create", "--label", request.name, "--cwd", request.cwd];
-  if (request.workspace) create.push("--workspace", request.workspace);
-  for (const [key, value] of Object.entries(request.env)) create.push("--env", `${key}=${value}`);
-
-  // The name herdr will actually know this agent by. Every later command in this function uses `agentName`,
-  // never `request.name`, which is only a base.
-  const agentName = uniqueAgentName(request.name);
-  const created = parseReply(await exec(create));
-  if (created.error) {
-    // **The staged prompt is removed here too.** This path returned without touching it, and nothing tracked it,
-    // so neither sweep could ever reach it — a permanent `/tmp/grants-herdr-*` per failed `tab create`. Measured
-    // by a reviewer, who also found leftovers from earlier runs already sitting in `/tmp`. It is the most likely
-    // failure on a machine where herdr is not running, i.e. the common case.
-    if (promptDir) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
-    return { ...empty, spawnError: `herdr tab create failed: ${created.error}` };
-  }
-
-  const rootPane = (created.result?.root_pane ?? {}) as { pane_id?: string; tab_id?: string };
-  const paneId = rootPane.pane_id;
-  const tabId = rootPane.tab_id;
-  if (tabId) { try { request.onNativeTab?.(tabId); } catch { /* observation only */ } }
-  // **Tracked BEFORE the pane-id check, not after.** A tab can exist from the moment this reply is parsed,
-  // so registering later leaves a window — one herdr round-trip wide — in which a killed process orphans a
-  // tab nothing would reap. The normal path had no such window and the error path did, which is backwards:
-  // the error path is the one more likely to be taken while something is already going wrong.
-  if (tabId && request.keepPane && promptDir) {
-    // `keepPane` keeps the PANE, and the staged prompt with it — a human inspecting the pane may want to see
-    // what the child was told. Registered `settled` so the trim never touches it, but registered nonetheless so
-    // the `exit` sweep can remove the temp dir rather than leaving one per kept pane forever. Measured: this
-    // path leaked a `/tmp/grants-herdr-*` that neither sweep could reach.
-    trackPane({ tab: tabId, name: agentName, promptDir, settled: true, keepTab: true });
-  }
-  if (tabId && !request.keepPane) trackPane({ tab: tabId, name: agentName, promptDir });
-
-  // Attach before the first post-create await. If the parent dies after this point, the independent lock
-  // helper closes the tab before releasing the writer lease.
-  if (request.onTab) {
-    try {
-      if (!tabId) throw new Error("herdr returned no tab id for writer-lease attachment");
-      request.onTab(tabId);
-    } catch (error) {
-      if (tabId && !request.keepPane) {
-        const closed = await exec(["tab", "close", tabId]).catch(() => undefined);
-        if (closed === undefined || parseReply(closed).error) throw new HerdrWriterCloseError(tabId);
-      }
-      return { ...empty, spawnError: `workspace writer lease could not attach to herdr tab (${String(error)})` };
-    }
-  }
-
-  if (tabId && !request.keepPane) {
-    // ADR-0032: panes now live until `agent_settled`, so they accumulate across one agent run — and a plain
-    // blocking `delegate` spends nothing from the fan-out budget, so the count is otherwise unbounded. Trimmed
-    // here rather than at settle time so the bound holds DURING a long run, not only after it.
-    const dropped = await trimOpenPanes(exec);
-    if (dropped.length > 0 && request.onSnapshot) {
-      try {
-        request.onSnapshot([
-          `[grants] closed ${dropped.length} older pane(s) to stay within the ${MAX_OPEN_PANES}-pane limit: ` +
-            dropped.join(", "),
-        ]);
-      } catch {
-        /* display only */
-      }
-    }
-  }
-
-  if (!paneId) {
-    // The tab may exist even though the reply carried no pane id, and this return used to be BEFORE
-    // `cleanup` was defined — so the one path where herdr half-succeeded was the one that leaked a tab.
-    if (tabId && !request.keepPane) {
-      const reply = await exec(["tab", "close", tabId]).catch(() => undefined);
-      // Same rule as `cleanup`: untrack only what is provably gone, so a close herdr refused stays the
-      // reaper's problem rather than being dropped on the assumption that it worked.
-      if (reply === undefined || parseReply(reply).error) {
-        if (request.closeOnSettle) throw new HerdrWriterCloseError(tabId);
-      } else {
-        untrackPane(tabId);
-      }
-    }
-    // There is no agent in this pane to ask, so the staged prompt has no reader — remove it. Kept only under
-    // `keepPane`, where the operator asked to inspect whatever exists.
-    if (promptDir && !request.keepPane) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
-    return { ...empty, spawnError: "herdr tab create returned no pane id" };
-  }
-
-  /**
-   * End this call. **A child that did not settle has its tab closed, because that is the only way to stop it.**
-   *
-   * ADR-0032 keeps a pane alive past its tool call so a human can read it. The original version of that also
-   * called `herdr agent stop` and claimed *"the agent is still stopped here… what survives is a terminal, not a
-   * running descendant."* **`herdr agent stop` does not exist.** Measured against herdr 0.7.5: the `agent`
-   * subcommands are `list get read send-keys prompt rename focus wait attach start explain`, and `agent stop`
-   * prints the usage banner and exits 0 — which `defaultExec` reports as a success, so nothing ever noticed.
-   * `docs/probes/g16-herdr/README.md` asserted it worked, in a *How to rerun* block that was never run.
-   *
-   * So there is exactly one kill available: closing the tab. That forces the distinction below.
-   *
-   *  - **Settled cleanly** (`idle`/`done`/`blocked` with an advanced counter): the child has answered and is
-   *    sitting idle. Its pane stays, which is the whole feature, and the `agent_settled` sweep reaps it.
-   *  - **Anything else** — a timeout, an abort, a failed start, a failed prompt, an unreadable pane: the child
-   *    may still be **working, with its grant**, after its tool call has already returned a result. Leaving
-   *    that running is a governance failure, not an untidy workspace, so the tab is closed here and now.
-   *
-   * `keepPane` is the operator overriding the whole question, and it is honoured either way: nothing is tracked
-   * and nothing is closed, which is what "keep this pane for me to inspect" has to mean.
-   */
-  const cleanup = async (settledCleanly: boolean) => {
-    if (request.keepPane) return;
-    if (settledCleanly && !request.closeOnSettle) return;
-    if (!tabId) return;
-    const reply = await exec(["tab", "close", tabId]).catch(() => undefined);
-    // Untracked only if provably closed — R-62's rule. A writer close failure must retain the lease;
-    // otherwise a still-promptable pane can overlap the successor admitted by a clean release.
-    if (reply === undefined || parseReply(reply).error) {
-      if (request.closeOnSettle) throw new HerdrWriterCloseError(tabId);
-      return;
-    }
-    untrackPane(tabId);
-    if (promptDir) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
-  };
-
-  // ADR-0032: the pane exists and has a name, so tell the caller NOW. A pane id that arrives with the result is
-  // useless — the point is switching to a child while it is still working. Guarded because a renderer must not
-  // be able to strand a pane we have already created.
-  if (request.onPane) {
-    try {
-      request.onPane(paneId, agentName);
-    } catch {
-      /* display only */
-    }
-  }
-
-  // Set only on the one path where the child answered and stopped working. Everything else — including an
-  // early `return` from a failed start or prompt — leaves it false, so `cleanup` closes the tab.
-  let settledCleanly = false;
-
-  return runWithFinalizers(async () => {
-    const started = await startHerdrAgent(exec, agentName, paneId, effectiveArgs, deadline);
-    if (started.error) return { ...empty, spawnError: `herdr agent start failed: ${started.error}` };
-
-    // The bundled reporter queues its initial idle state asynchronously. Establish its native-authority
-    // baseline before prompting, otherwise that initial report could advance the counter after prompt and
-    // be mistaken for settlement.
-    const baseline = await waitForLifecycleBaseline(
-      exec,
-      { ...request, name: agentName, nativePaneId: paneId },
-      Math.min(deadline, Date.now() + FRESH_LIFECYCLE_TIMEOUT_MS),
-    );
-    if (baseline.aborted) return { ...empty, aborted: true };
-    if (baseline.spawnError || baseline.before === undefined) return { ...empty, spawnError: baseline.spawnError ?? "Herdr lifecycle baseline is unavailable" };
-    observeHerdrSession(started.result?.agent, paneId, request.onSessionReference);
-
-    const prompted = parseReply(await exec(["agent", "prompt", agentName, request.prompt]));
-    if (prompted.error) return { ...empty, spawnError: `herdr agent prompt failed: ${prompted.error}` };
-    if (request.onRunning) {
-      try {
-        request.onRunning(paneId, agentName);
-      } catch {
-        /* display/observation only */
-      }
-    }
-
-    const settled = await waitForSettled(exec, { ...request, name: agentName, nativePaneId: paneId }, baseline.before, deadline, maxOutputBytes);
-    if (settled.aborted || settled.timedOut) {
-      // Still read: a timed-out child usually produced something, and a partial answer labelled partial is
-      // more useful than none. R-03's rule — a missing result must never look like an empty one.
-      const partial = await readPane(exec, agentName, maxOutputBytes);
-      if (!partial.readFailed) { try { request.onObservation?.(Buffer.from(partial.text)); } catch { /* observation only */ } }
-      return { ...empty, ...settled, text: partial.readFailed ? "" : partial.text, truncated: partial.truncated };
-    }
-    if (settled.spawnError) return { ...empty, spawnError: settled.spawnError };
-
-    const out = await readPane(exec, agentName, maxOutputBytes);
-    // **A failed read is a failed spawn, not an empty answer.** This branch used to return `readPane`'s own
-    // diagnostic as `text` with `code: 0`, so the orchestrator received
-    // `[grants] could not read the agent pane: …` **as the sub-agent's report** — R-03 exactly, and measured.
-    // The child may well have done its work; what we cannot do is claim to know what it said.
-    if (out.readFailed) {
-      return {
-        ...empty,
-        spawnError:
-          `the child settled but its pane could not be read (${out.readFailed}), so its answer is unknown. ` +
-          `The work may have been done — check pane ${paneId} if it is still open.`,
-      };
-    }
-    try { request.onObservation?.(Buffer.from(out.text)); } catch { /* observation only */ }
-    settledCleanly = true;
-    // The trim may now reclaim this pane if the cap is exceeded. Until this point it must not: closing the tab
-    // kills the child, and the child was still working.
-    if (tabId) markPaneSettled(tabId);
-    return {
-      code: settled.status === "blocked" ? 1 : 0,
-      // `truncated` is returned in the result too, but it was never SAID on this path, so a model received a
-      // tail with no indication that a head existed. The direct executor has always flagged it; a delegation
-      // that silently drops the first megabyte of an answer is the same defect wearing the other executor.
-      text: [
-        out.truncated ? `[grants] this pane exceeded the output cap; only its most recent output is below.\n` : "",
-        out.text,
-        settled.status === "blocked"
-          ? `\n\n[grants] this agent is BLOCKED waiting for a human in pane ${paneId}.`
-          : "",
-      ].join(""),
-      truncated: out.truncated,
-      timedOut: false,
-      aborted: false,
-    };
-  }, [{
-    label: "herdr pane finalizer failed",
-    run: () => cleanup(settledCleanly),
-  }]);
-}