pi-agent-replicate 0.0.0-stage → 1.4.1

package/pi-extension/subagents/terminal.js

@@ -0,0 +1,111 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { closeHerdrSurface, createHerdrSurface, createHerdrSurfaceInWorkspace, createHerdrSurfaceSplit, createHerdrWorktree, getHerdrPaneProcessInfo, getHerdrSurfaceTabId, rememberHerdrSurfaceTab, waitForHerdrPiReady, waitForHerdrShellReady, isHerdrAvailable, isProcessAlive, readHerdrScreen, readHerdrScreenAsync, inspectHerdrPane, renameHerdrTab, renameHerdrWorkspace, sendHerdrCommand, sendHerdrEscape, waitForHerdrPaneAbsence, waitForProcessesExit, } from "./herdr.js";
+const SETUP_HINT = "Start pi inside herdr (`herdr`, then run `pi`).";
+export function isTerminalAvailable() {
+    return isHerdrAvailable();
+}
+export function terminalSetupHint() {
+    return SETUP_HINT;
+}
+function assertTerminalAvailable() {
+    if (!isTerminalAvailable())
+        throw new Error(`herdr is not available. ${SETUP_HINT}`);
+}
+export function shellQuote(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+/** Create a new herdr tab and return its root pane ID. */
+export function createSubagentPane(name) {
+    assertTerminalAvailable();
+    return createHerdrSurface(name);
+}
+/** Create a subagent tab in an exact existing Herdr workspace. */
+export function createSubagentPaneInWorkspace(name, cwd, workspaceId) {
+    assertTerminalAvailable();
+    return createHerdrSurfaceInWorkspace(name, cwd, workspaceId);
+}
+/** Return the owning Herdr tab remembered for a package-created pane. */
+export function getPaneTabId(paneId) {
+    return getHerdrSurfaceTabId(paneId);
+}
+/** Restore a pane-to-tab association from durable launch metadata. */
+export function rememberPaneTab(paneId, tabId) {
+    rememberHerdrSurfaceTab(paneId, tabId);
+}
+/** Create a Git worktree in its own herdr workspace and return its root surface. */
+export function createSubagentWorktree(name, cwd, branch, base) {
+    assertTerminalAvailable();
+    return createHerdrWorktree(name, cwd, branch, base);
+}
+/** Split the current herdr pane and return the child pane ID. */
+export function splitCurrentPane(name, direction) {
+    assertTerminalAvailable();
+    return createHerdrSurfaceSplit(name, direction);
+}
+export function renameCurrentTab(title) {
+    assertTerminalAvailable();
+    renameHerdrTab(title);
+}
+export function renameCurrentWorkspace(title) {
+    assertTerminalAvailable();
+    renameHerdrWorkspace(title);
+}
+export function runInPane(paneId, command) {
+    assertTerminalAvailable();
+    sendHerdrCommand(paneId, command);
+}
+export function interruptPane(paneId) {
+    assertTerminalAvailable();
+    sendHerdrEscape(paneId);
+}
+export function runScriptInPane(paneId, command, options) {
+    const scriptPath = options?.scriptPath ??
+        join(tmpdir(), "pi-herdr-subagent-scripts", `cmd-${Date.now()}-${Math.random().toString(16).slice(2, 8)}.sh`);
+    mkdirSync(dirname(scriptPath), { recursive: true });
+    const scriptLines = ["#!/bin/bash"];
+    if (options?.scriptPreamble)
+        scriptLines.push(options.scriptPreamble.trimEnd());
+    scriptLines.push(command);
+    writeFileSync(scriptPath, `${scriptLines.join("\n")}\n`, { mode: 0o755 });
+    runInPane(paneId, `bash ${shellQuote(scriptPath)}`);
+    return scriptPath;
+}
+export function readPane(paneId, lines = 50) {
+    assertTerminalAvailable();
+    return readHerdrScreen(paneId, lines);
+}
+export async function readPaneAsync(paneId, lines = 50) {
+    assertTerminalAvailable();
+    return readHerdrScreenAsync(paneId, lines);
+}
+export async function inspectPane(paneId) {
+    assertTerminalAvailable();
+    const result = await inspectHerdrPane(paneId);
+    if (result.kind === "present") {
+        return { ...result, observedAt: Date.now() };
+    }
+    return result;
+}
+export function closePane(paneId) {
+    assertTerminalAvailable();
+    closeHerdrSurface(paneId);
+}
+export function getPaneProcessInfo(paneId) {
+    assertTerminalAvailable();
+    return getHerdrPaneProcessInfo(paneId);
+}
+export async function waitForShellReady(paneId, options) {
+    assertTerminalAvailable();
+    return waitForHerdrShellReady(paneId, options);
+}
+export async function waitForPiReady(paneId, sessionFile, cwd) {
+    assertTerminalAvailable();
+    return waitForHerdrPiReady(paneId, sessionFile, cwd);
+}
+export async function waitForPaneAbsence(paneId, options) {
+    assertTerminalAvailable();
+    return waitForHerdrPaneAbsence(paneId, options);
+}
+export { isProcessAlive, waitForProcessesExit };

package/pi-extension/subagents/terminal.ts

@@ -0,0 +1,208 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+	closeHerdrSurface,
+	createHerdrSurface,
+
+	createHerdrSurfaceInWorkspace,
+	createHerdrSurfaceSplit,
+	createHerdrWorktree,
+	getHerdrPaneProcessInfo,
+	getHerdrSurfaceTabId,
+	rememberHerdrSurfaceTab,
+	waitForHerdrPiReady,
+	waitForHerdrShellReady,
+	isHerdrAvailable,
+	isProcessAlive,
+	readHerdrScreen,
+	readHerdrScreenAsync,
+	inspectHerdrPane,
+	renameHerdrTab,
+	renameHerdrWorkspace,
+	sendHerdrCommand,
+	sendHerdrEscape,
+	waitForHerdrPaneAbsence,
+	waitForProcessesExit,
+	type HerdrPaneProcessInfo,
+} from "./herdr.ts";
+
+export type PaneId = string;
+export type SplitDirection = "right" | "down";
+export type { HerdrWorktreeSurface } from "./herdr.ts";
+
+const SETUP_HINT = "Start pi inside herdr (`herdr`, then run `pi`).";
+
+export function isTerminalAvailable(): boolean {
+	return isHerdrAvailable();
+}
+
+export function terminalSetupHint(): string {
+	return SETUP_HINT;
+}
+
+function assertTerminalAvailable(): void {
+	if (!isTerminalAvailable())
+		throw new Error(`herdr is not available. ${SETUP_HINT}`);
+}
+
+export function shellQuote(value: string): string {
+	return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
+/** Create a new herdr tab and return its root pane ID. */
+export function createSubagentPane(name: string): PaneId {
+	assertTerminalAvailable();
+	return createHerdrSurface(name);
+}
+
+
+/** Create a subagent tab in an exact existing Herdr workspace. */
+export function createSubagentPaneInWorkspace(
+	name: string,
+	cwd: string,
+	workspaceId: string,
+): PaneId {
+	assertTerminalAvailable();
+	return createHerdrSurfaceInWorkspace(name, cwd, workspaceId);
+}
+
+
+/** Return the owning Herdr tab remembered for a package-created pane. */
+export function getPaneTabId(paneId: PaneId): string | undefined {
+	return getHerdrSurfaceTabId(paneId);
+}
+
+/** Restore a pane-to-tab association from durable launch metadata. */
+export function rememberPaneTab(paneId: PaneId, tabId: string): void {
+	rememberHerdrSurfaceTab(paneId, tabId);
+}
+/** Create a Git worktree in its own herdr workspace and return its root surface. */
+export function createSubagentWorktree(
+	name: string,
+	cwd: string,
+	branch: string,
+	base: string,
+): import("./herdr.ts").HerdrWorktreeSurface {
+	assertTerminalAvailable();
+	return createHerdrWorktree(name, cwd, branch, base);
+}
+
+/** Split the current herdr pane and return the child pane ID. */
+export function splitCurrentPane(
+	name: string,
+	direction: SplitDirection,
+): PaneId {
+	assertTerminalAvailable();
+	return createHerdrSurfaceSplit(name, direction);
+}
+
+export function renameCurrentTab(title: string): void {
+	assertTerminalAvailable();
+	renameHerdrTab(title);
+}
+
+export function renameCurrentWorkspace(title: string): void {
+	assertTerminalAvailable();
+	renameHerdrWorkspace(title);
+}
+
+
+export function runInPane(paneId: PaneId, command: string): void {
+	assertTerminalAvailable();
+	sendHerdrCommand(paneId, command);
+}
+
+export function interruptPane(paneId: PaneId): void {
+	assertTerminalAvailable();
+	sendHerdrEscape(paneId);
+}
+
+export function runScriptInPane(
+	paneId: PaneId,
+	command: string,
+	options?: { scriptPath?: string; scriptPreamble?: string },
+): string {
+	const scriptPath =
+		options?.scriptPath ??
+		join(
+			tmpdir(),
+			"pi-herdr-subagent-scripts",
+			`cmd-${Date.now()}-${Math.random().toString(16).slice(2, 8)}.sh`,
+		);
+	mkdirSync(dirname(scriptPath), { recursive: true });
+
+	const scriptLines = ["#!/bin/bash"];
+	if (options?.scriptPreamble)
+		scriptLines.push(options.scriptPreamble.trimEnd());
+	scriptLines.push(command);
+	writeFileSync(scriptPath, `${scriptLines.join("\n")}\n`, { mode: 0o755 });
+
+	runInPane(paneId, `bash ${shellQuote(scriptPath)}`);
+	return scriptPath;
+}
+
+export function readPane(paneId: PaneId, lines = 50): string {
+	assertTerminalAvailable();
+	return readHerdrScreen(paneId, lines);
+}
+
+export async function readPaneAsync(
+	paneId: PaneId,
+	lines = 50,
+): Promise<string> {
+	assertTerminalAvailable();
+	return readHerdrScreenAsync(paneId, lines);
+}
+
+export type { PaneInspection, HerdrAgentStatus } from "./lifecycle.ts";
+
+export async function inspectPane(
+	paneId: PaneId,
+): Promise<import("./lifecycle.ts").PaneInspection> {
+	assertTerminalAvailable();
+	const result = await inspectHerdrPane(paneId);
+	if (result.kind === "present") {
+		return { ...result, observedAt: Date.now() };
+	}
+	return result;
+}
+
+export function closePane(paneId: PaneId): void {
+	assertTerminalAvailable();
+	closeHerdrSurface(paneId);
+}
+
+export type { HerdrPaneProcessInfo };
+
+export function getPaneProcessInfo(paneId: PaneId): HerdrPaneProcessInfo {
+	assertTerminalAvailable();
+	return getHerdrPaneProcessInfo(paneId);
+}
+
+export async function waitForShellReady(
+	paneId: PaneId,
+	options?: { timeoutMs?: number; intervalMs?: number; signal?: AbortSignal },
+): Promise<void> {
+	assertTerminalAvailable();
+	return waitForHerdrShellReady(paneId, options);
+}
+
+export async function waitForPiReady(
+	paneId: PaneId,
+	sessionFile: string,
+	cwd: string,
+): Promise<void> {
+	assertTerminalAvailable();
+	return waitForHerdrPiReady(paneId, sessionFile, cwd);
+}
+
+export async function waitForPaneAbsence(
+	paneId: PaneId,
+	options?: { timeoutMs?: number; intervalMs?: number },
+): Promise<boolean> {
+	assertTerminalAvailable();
+	return waitForHerdrPaneAbsence(paneId, options);
+}
+
+export { isProcessAlive, waitForProcessesExit };

package/pi-extension/subagents/watchdog.js

@@ -0,0 +1,122 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync, } from "node:fs";
+import { dirname } from "node:path";
+export const DEFAULT_QUIET_THRESHOLD_MS = 120_000;
+export const MAX_RECOVERY_ATTEMPTS = 3;
+export const REPLICA_STOP_GRACE_MS = 10_000;
+/** A stopped replica gets a safety net, never an inactivity-based relaunch. */
+export function replicaStopDue(input) {
+    return input.idleSince !== undefined && input.idle && !input.pendingMessages &&
+        !input.moving && !input.descendants && input.now - input.idleSince >= REPLICA_STOP_GRACE_MS;
+}
+/** Resolve the watchdog threshold with environment precedence and strict validation. */
+export function resolveQuietThreshold(envValue, configuredValue) {
+    if (envValue !== undefined) {
+        const parsed = Number(envValue);
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            throw new Error("Invalid PI_SUBAGENT_QUIET_THRESHOLD_MS: expected a positive integer");
+        }
+        return parsed;
+    }
+    if (configuredValue !== undefined) {
+        if (!Number.isInteger(configuredValue) || configuredValue <= 0) {
+            throw new Error("Invalid status.quietThresholdMs: expected a positive integer");
+        }
+        return configuredValue;
+    }
+    return DEFAULT_QUIET_THRESHOLD_MS;
+}
+/** Classify observable inactivity without bounding tools, streams, or descendant drain. */
+export function classifyStaleness(input) {
+    if (!input.autonomous)
+        return "active";
+    if (input.waitingForDescendants)
+        return "waiting";
+    if (input.activity?.compactionActive)
+        return "active";
+    if (input.activity?.toolActive)
+        return "active";
+    if (input.descendantActivityAt !== undefined && input.activity?.providerActive)
+        return "active";
+    const lastEventAt = Math.max(input.activity?.updatedAt ?? input.startedAt, input.descendantActivityAt ?? 0);
+    return input.now - lastEventAt > input.quietThresholdMs ? "stale" : "active";
+}
+function records(logPath, childId) {
+    if (!existsSync(logPath))
+        return [];
+    return readFileSync(logPath, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line, index) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`Invalid recovery ledger record ${index + 1} in ${logPath}`, { cause: error });
+        }
+    })
+        .filter((record) => record.event === "recovery-attempt" && record.childId === childId);
+}
+function appendRecoveryRecord(logPath, record) {
+    mkdirSync(dirname(logPath), { recursive: true });
+    const descriptor = openSync(logPath, "a");
+    try {
+        writeSync(descriptor, `${JSON.stringify(record)}\n`, undefined, "utf8");
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/**
+ * Decide whether the parent watchdog may supervise one child as stale.
+ *
+ * An exhausted recovery budget is final: the child cannot be resumed again, so
+ * another stale pass would only repeat the same kill attempt forever.
+ */
+export function shouldStartStaleRecovery(input) {
+    if (input.interactive)
+        return false;
+    if (input.pendingTerminalDelivery)
+        return false;
+    if (input.recoveryAttemptActive)
+        return false;
+    if (input.recoveryExhausted)
+        return false;
+    return true;
+}
+/** Consume one durable attempt from the shared crash-and-stale recovery budget. */
+export function consumeRecoveryAttempt(input) {
+    const previous = records(input.logPath, input.childId);
+    const attemptedCauses = previous
+        .map((record) => record.cause)
+        .filter((cause) => cause === "crash" || cause === "stale");
+    const reasonFor = (causes) => {
+        if (new Set(causes).size > 1)
+            return "Recovery failed after mixed crash and stale attempts.";
+        return causes[0] === "crash"
+            ? "Recovery failed after repeated child process crashes."
+            : "Recovery failed after repeated stale watchdog kills.";
+    };
+    if (previous.length >= MAX_RECOVERY_ATTEMPTS) {
+        return {
+            attempt: MAX_RECOVERY_ATTEMPTS,
+            exhausted: true,
+            reason: reasonFor(attemptedCauses),
+        };
+    }
+    const attempt = previous.length + 1;
+    const now = input.now ?? Date.now;
+    appendRecoveryRecord(input.logPath, {
+        version: 1,
+        time: new Date(now()).toISOString(),
+        event: "recovery-attempt",
+        childId: input.childId,
+        attempt,
+        cause: input.cause,
+    });
+    return {
+        attempt,
+        exhausted: false,
+        reason: reasonFor([...attemptedCauses, input.cause]),
+    };
+}

package/pi-extension/subagents/watchdog.ts

@@ -0,0 +1,171 @@
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import type { SubagentActivityState } from "./activity.ts";
+
+export const DEFAULT_QUIET_THRESHOLD_MS = 120_000;
+export const MAX_RECOVERY_ATTEMPTS = 3;
+
+export const REPLICA_STOP_GRACE_MS = 10_000;
+
+/** A stopped replica gets a safety net, never an inactivity-based relaunch. */
+export function replicaStopDue(input: {
+  now: number;
+  idleSince: number | undefined;
+  idle: boolean;
+  pendingMessages: boolean;
+  moving: boolean;
+  descendants: boolean;
+}): boolean {
+  return input.idleSince !== undefined && input.idle && !input.pendingMessages &&
+    !input.moving && !input.descendants && input.now - input.idleSince >= REPLICA_STOP_GRACE_MS;
+}
+
+export type RecoveryCause = "crash" | "stale";
+export type StaleVerdict = "active" | "waiting" | "stale";
+
+/** Resolve the watchdog threshold with environment precedence and strict validation. */
+export function resolveQuietThreshold(
+  envValue: string | undefined,
+  configuredValue: number | undefined,
+): number {
+  if (envValue !== undefined) {
+    const parsed = Number(envValue);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+      throw new Error("Invalid PI_SUBAGENT_QUIET_THRESHOLD_MS: expected a positive integer");
+    }
+    return parsed;
+  }
+  if (configuredValue !== undefined) {
+    if (!Number.isInteger(configuredValue) || configuredValue <= 0) {
+      throw new Error("Invalid status.quietThresholdMs: expected a positive integer");
+    }
+    return configuredValue;
+  }
+  return DEFAULT_QUIET_THRESHOLD_MS;
+}
+
+/** Classify observable inactivity without bounding tools, streams, or descendant drain. */
+export function classifyStaleness(input: {
+  autonomous: boolean;
+  activity?: SubagentActivityState;
+  startedAt: number;
+  now: number;
+  quietThresholdMs: number;
+  waitingForDescendants: boolean;
+  /** Latest result delivered by an owned descendant, which wakes the owner. */
+  descendantActivityAt?: number;
+}): StaleVerdict {
+  if (!input.autonomous) return "active";
+  if (input.waitingForDescendants) return "waiting";
+  if (input.activity?.compactionActive) return "active";
+  if (input.activity?.toolActive) return "active";
+
+  if (input.descendantActivityAt !== undefined && input.activity?.providerActive) return "active";
+  const lastEventAt = Math.max(
+    input.activity?.updatedAt ?? input.startedAt,
+    input.descendantActivityAt ?? 0,
+  );
+  return input.now - lastEventAt > input.quietThresholdMs ? "stale" : "active";
+}
+
+interface RecoveryRecord {
+  event?: unknown;
+  childId?: unknown;
+  attempt?: unknown;
+  cause?: unknown;
+}
+
+function records(logPath: string, childId: string): RecoveryRecord[] {
+  if (!existsSync(logPath)) return [];
+  return readFileSync(logPath, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line) as RecoveryRecord;
+      } catch (error) {
+        throw new Error(`Invalid recovery ledger record ${index + 1} in ${logPath}`, { cause: error });
+      }
+    })
+    .filter((record) => record.event === "recovery-attempt" && record.childId === childId);
+}
+
+function appendRecoveryRecord(logPath: string, record: Record<string, unknown>): void {
+  mkdirSync(dirname(logPath), { recursive: true });
+  const descriptor = openSync(logPath, "a");
+  try {
+    writeSync(descriptor, `${JSON.stringify(record)}\n`, undefined, "utf8");
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+/**
+ * Decide whether the parent watchdog may supervise one child as stale.
+ *
+ * An exhausted recovery budget is final: the child cannot be resumed again, so
+ * another stale pass would only repeat the same kill attempt forever.
+ */
+export function shouldStartStaleRecovery(input: {
+  interactive: boolean;
+  pendingTerminalDelivery: boolean;
+  recoveryAttemptActive: boolean;
+  recoveryExhausted: boolean;
+}): boolean {
+  if (input.interactive) return false;
+  if (input.pendingTerminalDelivery) return false;
+  if (input.recoveryAttemptActive) return false;
+  if (input.recoveryExhausted) return false;
+  return true;
+}
+
+/** Consume one durable attempt from the shared crash-and-stale recovery budget. */
+export function consumeRecoveryAttempt(input: {
+  logPath: string;
+  childId: string;
+  cause: RecoveryCause;
+  now?: () => number;
+}): { attempt: number; exhausted: boolean; reason: string } {
+  const previous = records(input.logPath, input.childId);
+  const attemptedCauses = previous
+    .map((record) => record.cause)
+    .filter((cause): cause is RecoveryCause => cause === "crash" || cause === "stale");
+  const reasonFor = (causes: RecoveryCause[]): string => {
+    if (new Set(causes).size > 1) return "Recovery failed after mixed crash and stale attempts.";
+    return causes[0] === "crash"
+      ? "Recovery failed after repeated child process crashes."
+      : "Recovery failed after repeated stale watchdog kills.";
+  };
+  if (previous.length >= MAX_RECOVERY_ATTEMPTS) {
+    return {
+      attempt: MAX_RECOVERY_ATTEMPTS,
+      exhausted: true,
+      reason: reasonFor(attemptedCauses),
+    };
+  }
+
+  const attempt = previous.length + 1;
+  const now = input.now ?? Date.now;
+  appendRecoveryRecord(input.logPath, {
+    version: 1,
+    time: new Date(now()).toISOString(),
+    event: "recovery-attempt",
+    childId: input.childId,
+    attempt,
+    cause: input.cause,
+  });
+  return {
+    attempt,
+    exhausted: false,
+    reason: reasonFor([...attemptedCauses, input.cause]),
+  };
+}