pi-claude-supervisor 0.2.0

package/src/types.ts

@@ -0,0 +1,122 @@
+export type SupervisorState =
+  | "idle"
+  | "starting"
+  | "running"
+  | "waiting"
+  | "paused"
+  | "verifying"
+  | "completed"
+  | "failed"
+  | "stopped";
+
+export type WorkerExitReason = "completed" | "failed" | "stopped" | "crashed" | "unknown";
+
+export interface WorkerPermissionRequest {
+  requestId: string;
+  toolUseId: string;
+  toolName: string;
+  input: unknown;
+  raw: Record<string, unknown>;
+}
+
+export type WorkerEvent =
+  | { type: "output"; handle: WorkerHandle; chunk: WorkerOutputChunk }
+  | { type: "jsonl"; handle: WorkerHandle; record: Record<string, unknown> }
+  | { type: "turn_completed"; handle: WorkerHandle; result: Record<string, unknown>; sequence: number }
+  | { type: "permission_request"; handle: WorkerHandle; request: WorkerPermissionRequest }
+  | { type: "exited"; handle: WorkerHandle; exitCode?: number | null; signal?: NodeJS.Signals };
+
+export type WorkerEventListener = (event: WorkerEvent) => void | Promise<void>;
+
+export interface WorkerStartInput {
+  task: string;
+  cwd: string;
+  command: string;
+  args?: string[];
+  env?: NodeJS.ProcessEnv;
+  approval?: { actor: "human"; reason: string };
+  eventListener?: WorkerEventListener;
+}
+
+export interface WorkerHandle {
+  id: string;
+  pid?: number;
+  startedAt: string;
+  cwd: string;
+  sessionId?: string;
+}
+
+export interface WorkerStatus {
+  handle: WorkerHandle;
+  running: boolean;
+  exitCode?: number | null;
+  signal?: NodeJS.Signals;
+  lastOutputAt?: string;
+  lastInputAt?: string;
+  activeRequests?: number;
+  exitReason?: WorkerExitReason;
+  /** Whether the detached process group or cgroup has been confirmed gone. */
+  processGroupCleaned?: boolean;
+  /** Whether a Linux cgroup provided descendant cleanup for this worker. */
+  cgroupCleaned?: boolean;
+  /** cgroup attachment was unavailable and a fallback may have been used. */
+  cgroupError?: string;
+  /** Cleanup failure is diagnostic and must be treated as a safety failure. */
+  cleanupError?: string;
+  runtimeError?: string;
+  outputTruncated?: boolean;
+}
+
+export interface PermissionDecision {
+  behavior: "allow" | "deny";
+  message?: string;
+}
+
+export interface WorkerAdapter {
+  capabilities(): WorkerCapabilities;
+  start(input: WorkerStartInput): Promise<WorkerHandle>;
+  getStatus(handle: WorkerHandle): Promise<WorkerStatus>;
+  readOutput(handle: WorkerHandle): Promise<WorkerOutputChunk[]>;
+  /** Restore chunks when diagnostic event persistence fails before acknowledgement. */
+  restoreOutput?(handle: WorkerHandle, chunks: WorkerOutputChunk[]): Promise<void>;
+  /** Subscribe to transport and process lifecycle events without polling. */
+  subscribe?(handle: WorkerHandle, listener: WorkerEventListener): () => void;
+  /** Respond to Claude Code's stdio permission request. */
+  respondPermission?(handle: WorkerHandle, requestId: string, toolUseId: string, decision: PermissionDecision, updatedInput?: unknown): Promise<void>;
+  send(handle: WorkerHandle, message: string, idempotencyKey: string): Promise<void>;
+  pause(handle: WorkerHandle): Promise<void>;
+  resume(handle: WorkerHandle): Promise<void>;
+  stop(handle: WorkerHandle, reason: string): Promise<void>;
+  killProcessGroup(handle: WorkerHandle, reason: string): Promise<void>;
+  resumeSession(sessionId: string): Promise<WorkerHandle>;
+}
+
+export interface WorkerOutputChunk {
+  stream: "stdout" | "stderr";
+  text: string;
+  at: string;
+}
+
+export interface WorkerCapabilities {
+  transport: "process-pipe" | "pty" | "jsonl";
+  interactiveInput: boolean;
+  pause: boolean;
+  resumeSession: boolean;
+  processGroupControl: boolean;
+}
+
+export interface TaskContext {
+  taskId: string;
+  task: string;
+  cwd: string;
+  maxTurns: number;
+  startedAt: string;
+}
+
+export interface VerificationResult {
+  ok: boolean;
+  command: string;
+  exitCode: number;
+  output: string;
+  checkedAt: string;
+}

package/src/verifier.ts

@@ -0,0 +1,40 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { VerificationResult } from "./types.ts";
+import { assertSafeWorkerCommand } from "./policy.ts";
+import { workerEnvironment } from "./worker/environment.ts";
+
+const execFileAsync = promisify(execFile);
+
+export interface VerificationCommand {
+  command: string;
+  args?: string[];
+}
+
+export async function verify(
+  cwd: string,
+  command: VerificationCommand = { command: "git", args: ["diff", "--check"] },
+  timeoutMs = 120_000,
+): Promise<VerificationResult> {
+  assertSafeWorkerCommand(command.command, command.args);
+  const rendered = [command.command, ...(command.args ?? [])].join(" ");
+  try {
+    const result = await execFileAsync(command.command, command.args ?? [], {
+      cwd,
+      timeout: timeoutMs,
+      maxBuffer: 256 * 1024,
+      env: workerEnvironment(process.env, { GIT_TERMINAL_PROMPT: "0" }),
+    });
+    return { ok: true, command: rendered, exitCode: 0, output: `${result.stdout}${result.stderr}`, checkedAt: new Date().toISOString() };
+  } catch (error) {
+    const failure = error as { code?: number | string; stdout?: string; stderr?: string; message?: string };
+    const exitCode = typeof failure.code === "number" ? failure.code : 1;
+    return {
+      ok: false,
+      command: rendered,
+      exitCode,
+      output: `${failure.stdout ?? ""}${failure.stderr ?? ""}${failure.message ?? ""}`.slice(-256 * 1024),
+      checkedAt: new Date().toISOString(),
+    };
+  }
+}

package/src/worker/environment.ts

@@ -0,0 +1,31 @@
+const inheritedNames = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TMPDIR",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TERM",
+  "COLORTERM",
+] as const;
+
+/**
+ * Build a least-privilege worker environment. Credentials and arbitrary host
+ * variables are not inherited unless the caller explicitly supplies them.
+ */
+export function workerEnvironment(
+  inherited: NodeJS.ProcessEnv = process.env,
+  explicit: NodeJS.ProcessEnv = {},
+): NodeJS.ProcessEnv {
+  const result: NodeJS.ProcessEnv = {};
+  for (const name of inheritedNames) {
+    if (inherited[name] !== undefined) result[name] = inherited[name];
+  }
+  for (const [name, value] of Object.entries(explicit)) {
+    if (value !== undefined) result[name] = value;
+  }
+  return result;
+}