pi-amq 0.1.1

package/workflow/spawn-confirmation.ts

@@ -0,0 +1,305 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { defaultPiStateDirectory } from "./workspace-paths.js";
+import type {
+  WorkerProposalEditableField,
+  WorkerProposalProvenance,
+  WorkerRequest,
+} from "./workflow-types.js";
+
+export type ConfirmSpawnsPolicy = WorkerProposalProvenance["confirmSpawns"];
+
+export interface SpawnConfirmationConfigOptions {
+  readonly projectDirectory: string;
+  readonly projectTrusted: boolean;
+  readonly userConfigPath?: string;
+  readonly projectConfigPath?: string;
+}
+
+export async function loadConfirmSpawnsPolicy(
+  options: SpawnConfirmationConfigOptions,
+): Promise<ConfirmSpawnsPolicy> {
+  let policy: ConfirmSpawnsPolicy = "multi-worker-only";
+  const user = await readOptionalConfig(
+    options.userConfigPath ?? join(defaultPiStateDirectory(), "pi-amq", "config.json"),
+  );
+  if (user !== undefined) policy = user;
+  if (options.projectTrusted) {
+    const project = await readOptionalConfig(
+      options.projectConfigPath ?? join(options.projectDirectory, ".pi", "pi-amq", "config.json"),
+    );
+    if (project !== undefined) policy = project;
+  }
+  return policy;
+}
+
+export interface EditedWorkerProposal {
+  readonly request: WorkerRequest;
+  readonly humanEditedFields: readonly WorkerProposalEditableField[];
+}
+
+export type LaunchPreviewDecision =
+  | { readonly kind: "accepted"; readonly proposals: readonly EditedWorkerProposal[] }
+  | { readonly kind: "cancelled" };
+
+export interface LaunchPreviewSubmission<T> {
+  readonly groupKey: string;
+  readonly policy: ConfirmSpawnsPolicy;
+  readonly tui: boolean;
+  readonly request: WorkerRequest;
+  readonly signal?: AbortSignal;
+  readonly preview: (requests: readonly WorkerRequest[]) => Promise<LaunchPreviewDecision>;
+  readonly launch: (accepted: WorkerRequest) => Promise<T>;
+}
+
+export type LaunchPreviewSubmissionResult<T> =
+  | { readonly kind: "launched"; readonly value: T }
+  | { readonly kind: "cancelled"; readonly reason: string };
+
+interface PendingSubmission {
+  readonly request: WorkerRequest;
+  readonly signal: AbortSignal | undefined;
+  readonly preview: LaunchPreviewSubmission<unknown>["preview"];
+  readonly launch: LaunchPreviewSubmission<unknown>["launch"];
+  readonly resolve: (result: LaunchPreviewSubmissionResult<unknown>) => void;
+  readonly reject: (error: Error) => void;
+  active: boolean;
+}
+
+interface PendingBatch {
+  readonly policy: ConfirmSpawnsPolicy;
+  readonly tui: boolean;
+  readonly submissions: PendingSubmission[];
+  readonly timer: ReturnType<typeof setTimeout>;
+}
+
+export interface LaunchPreviewCoordinatorOptions {
+  readonly batchWindowMs?: number;
+}
+
+export class LaunchPreviewCoordinator {
+  readonly #batchWindowMs: number;
+  readonly #batches = new Map<string, PendingBatch>();
+
+  constructor(options: LaunchPreviewCoordinatorOptions = {}) {
+    this.#batchWindowMs = options.batchWindowMs ?? 20;
+    if (!Number.isSafeInteger(this.#batchWindowMs) || this.#batchWindowMs < 0 || this.#batchWindowMs > 1_000) {
+      throw new TypeError("Launch preview batch window must be an integer between 0 and 1000 ms");
+    }
+  }
+
+  async submit<T>(submission: LaunchPreviewSubmission<T>): Promise<LaunchPreviewSubmissionResult<T>> {
+    if (submission.signal?.aborted) throw abortError(submission.signal);
+    if (submission.policy === "off") {
+      const accepted = withProvenance(submission.request, "off", "skipped-policy-off", []);
+      return { kind: "launched", value: await submission.launch(accepted) };
+    }
+    return new Promise<LaunchPreviewSubmissionResult<T>>((resolve, reject) => {
+      const key = `${submission.groupKey}\0${submission.policy}\0${submission.tui ? "tui" : "headless"}`;
+      let batch = this.#batches.get(key);
+      if (!batch) {
+        const timer = setTimeout(() => void this.#flush(key), this.#batchWindowMs);
+        batch = {
+          policy: submission.policy,
+          tui: submission.tui,
+          submissions: [],
+          timer,
+        };
+        this.#batches.set(key, batch);
+      }
+      const pending: PendingSubmission = {
+        request: submission.request,
+        signal: submission.signal,
+        preview: submission.preview,
+        launch: submission.launch as (accepted: WorkerRequest) => Promise<unknown>,
+        resolve: resolve as (result: LaunchPreviewSubmissionResult<unknown>) => void,
+        reject: (error) => reject(error),
+        active: true,
+      };
+      batch.submissions.push(pending);
+      submission.signal?.addEventListener("abort", () => {
+        if (!pending.active) return;
+        pending.active = false;
+        pending.reject(abortError(submission.signal!));
+      }, { once: true });
+    });
+  }
+
+  async #flush(key: string): Promise<void> {
+    const batch = this.#batches.get(key);
+    if (!batch) return;
+    clearTimeout(batch.timer);
+    this.#batches.delete(key);
+    const pending = batch.submissions.filter((submission) => submission.active);
+    if (pending.length === 0) return;
+
+    if (batch.policy === "multi-worker-only" && pending.length === 1) {
+      const only = pending[0]!;
+      only.active = false;
+      await settleLaunch(
+        only,
+        withProvenance(only.request, batch.policy, "skipped-single-worker", []),
+      );
+      return;
+    }
+    if (!batch.tui) {
+      const error = new Error(
+        `confirm_spawns=${batch.policy} requires an interactive TUI for this ${pending.length}-worker proposal; no worker was accepted`,
+      );
+      for (const submission of pending) {
+        submission.active = false;
+        submission.reject(error);
+      }
+      return;
+    }
+
+    let decision: LaunchPreviewDecision;
+    try {
+      decision = await pending[0]!.preview(pending.map((submission) => submission.request));
+    } catch (error) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      for (const submission of pending) {
+        if (!submission.active) continue;
+        submission.active = false;
+        submission.reject(normalized);
+      }
+      return;
+    }
+    if (pending.some((submission) => !submission.active)) {
+      for (const submission of pending) {
+        if (!submission.active) continue;
+        submission.active = false;
+        submission.resolve({
+          kind: "cancelled",
+          reason: "A launch-preview tool call was aborted; no worker contract was accepted or ledgered",
+        });
+      }
+      return;
+    }
+    if (decision.kind === "cancelled") {
+      for (const submission of pending) {
+        submission.active = false;
+        submission.resolve({
+          kind: "cancelled",
+          reason: "Launch preview cancelled; no worker contract was accepted or ledgered",
+        });
+      }
+      return;
+    }
+    if (decision.proposals.length !== pending.length) {
+      const error = new Error("Launch preview returned a different proposal count");
+      for (const submission of pending) {
+        submission.active = false;
+        submission.reject(error);
+      }
+      return;
+    }
+    const keys = new Set<string>();
+    for (const proposal of decision.proposals) {
+      if (keys.has(proposal.request.requestKey)) {
+        const error = new Error("Launch preview returned duplicate worker request keys");
+        for (const submission of pending) {
+          submission.active = false;
+          submission.reject(error);
+        }
+        return;
+      }
+      keys.add(proposal.request.requestKey);
+    }
+    if (pending.some((submission) => !keys.has(submission.request.requestKey))) {
+      const error = new Error("Launch preview changed or dropped a worker request key");
+      for (const submission of pending) {
+        submission.active = false;
+        submission.reject(error);
+      }
+      return;
+    }
+    for (const submission of pending) submission.active = false;
+    await Promise.all(pending.map(async (submission) => {
+      const proposal = decision.proposals.find(
+        (candidate) => candidate.request.requestKey === submission.request.requestKey,
+      );
+      if (!proposal) {
+        submission.reject(new Error(`Launch preview dropped ${submission.request.requestKey}`));
+        return;
+      }
+      const fields = uniqueFields(proposal.humanEditedFields);
+      await settleLaunch(
+        submission,
+        withProvenance(proposal.request, batch.policy, "accepted", fields),
+      );
+    }));
+  }
+}
+
+async function settleLaunch(submission: PendingSubmission, request: WorkerRequest): Promise<void> {
+  try {
+    submission.resolve({ kind: "launched", value: await submission.launch(request) });
+  } catch (error) {
+    submission.reject(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
+function withProvenance(
+  request: WorkerRequest,
+  policy: ConfirmSpawnsPolicy,
+  disposition: WorkerProposalProvenance["disposition"],
+  humanEditedFields: readonly WorkerProposalEditableField[],
+): WorkerRequest {
+  return {
+    ...request,
+    proposal: {
+      source: humanEditedFields.length === 0 ? "tool" : "human-edited",
+      confirmSpawns: policy,
+      disposition,
+      humanEditedFields,
+    },
+  };
+}
+
+function uniqueFields(
+  fields: readonly WorkerProposalEditableField[],
+): readonly WorkerProposalEditableField[] {
+  const supported = new Set<WorkerProposalEditableField>(["role", "task", "model", "difficulty", "budget"]);
+  const unique: WorkerProposalEditableField[] = [];
+  for (const field of fields) {
+    if (!supported.has(field)) throw new TypeError(`Unknown edited proposal field ${field}`);
+    if (!unique.includes(field)) unique.push(field);
+  }
+  return unique;
+}
+
+async function readOptionalConfig(path: string): Promise<ConfirmSpawnsPolicy | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return undefined;
+    throw error;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(raw) as unknown;
+  } catch (error) {
+    throw new TypeError(`${path}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${path}: pi-amq config must be an object`);
+  }
+  const policy = (value as Record<string, unknown>)["confirm_spawns"];
+  if (policy === undefined) return undefined;
+  if (policy !== "on" && policy !== "multi-worker-only" && policy !== "off") {
+    throw new TypeError(`${path}: confirm_spawns must be on, multi-worker-only, or off`);
+  }
+  return policy;
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error
+    && (error as { readonly code?: unknown }).code === "ENOENT";
+}
+
+function abortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error("Launch preview aborted");
+}

package/workflow/system-process-inspector.ts

@@ -0,0 +1,142 @@
+import { execFile } from "node:child_process";
+import { readFile, readlink } from "node:fs/promises";
+import { hostname } from "node:os";
+import { isAbsolute, normalize } from "node:path";
+import { promisify } from "node:util";
+
+import type {
+  ProcessIdentity,
+  ProcessIdentityInspector,
+  ProcessInspection,
+} from "./workflow-lease.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Reads PID-reuse-resistant identity evidence without treating age or timeout as death proof. */
+export class SystemProcessIdentityInspector implements ProcessIdentityInspector {
+  async current(): Promise<ProcessIdentity> {
+    const inspection = await this.inspect(process.pid);
+    if (inspection.kind !== "live") {
+      throw new Error(
+        inspection.kind === "unknown"
+          ? `Current process identity is unavailable: ${inspection.diagnostic}`
+          : "Current process disappeared during identity inspection",
+      );
+    }
+    return inspection.identity;
+  }
+
+  async inspect(pid: number): Promise<ProcessInspection> {
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+      return { kind: "unknown", diagnostic: "PID must be a positive integer" };
+    }
+    if (process.platform === "linux") return inspectLinux(pid);
+    if (process.platform === "darwin") return inspectDarwin(pid);
+    return {
+      kind: "unknown",
+      diagnostic: `Process start identity is unsupported on ${process.platform}`,
+    };
+  }
+}
+
+async function inspectLinux(pid: number): Promise<ProcessInspection> {
+  try {
+    const [stat, executable, bootIdentity] = await Promise.all([
+      readFile(`/proc/${pid}/stat`, "utf8"),
+      readlink(`/proc/${pid}/exe`),
+      readFile("/proc/sys/kernel/random/boot_id", "utf8"),
+    ]);
+    const closing = stat.lastIndexOf(")");
+    if (closing < 0) return { kind: "unknown", diagnostic: "Linux process stat is malformed" };
+    const fields = stat.slice(closing + 2).trim().split(/\s+/);
+    const startTicks = fields[19];
+    if (!startTicks) return { kind: "unknown", diagnostic: "Linux process start ticks are missing" };
+    return {
+      kind: "live",
+      identity: {
+        pid,
+        processStartIdentity: `linux-start-ticks:${startTicks}`,
+        bootIdentity: bootIdentity.trim() || null,
+        executable: normalize(executable),
+        hostname: hostname(),
+      },
+    };
+  } catch (error) {
+    return classifyInspectionFailure(error, pid);
+  }
+}
+
+async function inspectDarwin(pid: number): Promise<ProcessInspection> {
+  try {
+    const [{ stdout }, boot] = await Promise.all([
+      execFileAsync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "comm="], {
+        encoding: "utf8",
+        maxBuffer: 8_192,
+        timeout: 2_000,
+      }),
+      execFileAsync("sysctl", ["-n", "kern.boottime"], {
+        encoding: "utf8",
+        maxBuffer: 8_192,
+        timeout: 2_000,
+      }),
+    ]);
+    const line = stdout.trim();
+    if (line.length === 0) return { kind: "absent" };
+    const start = line.slice(0, 24).trim();
+    const psExecutable = line.slice(24).trim();
+    if (start.length === 0) {
+      return { kind: "unknown", diagnostic: "Darwin ps start identity is incomplete" };
+    }
+    const executable = selectDarwinExecutable(
+      psExecutable,
+      pid === process.pid ? process.execPath : null,
+    );
+    if (executable === null) {
+      return { kind: "unknown", diagnostic: "Darwin process executable is unavailable" };
+    }
+    return {
+      kind: "live",
+      identity: {
+        pid,
+        processStartIdentity: `darwin-lstart:${start}`,
+        bootIdentity: boot.stdout.trim() || null,
+        executable,
+        hostname: hostname(),
+      },
+    };
+  } catch (error) {
+    return classifyInspectionFailure(error, pid);
+  }
+}
+
+/** Uses current-process evidence only when ps reports a relative argv[0]. */
+export function selectDarwinExecutable(
+  psExecutable: string,
+  currentExecutable: string | null,
+): string | null {
+  const reported = psExecutable.trim();
+  if (isAbsolute(reported)) return normalize(reported);
+  if (currentExecutable !== null && isAbsolute(currentExecutable)) {
+    return normalize(currentExecutable);
+  }
+  return null;
+}
+
+function classifyInspectionFailure(error: unknown, pid: number): ProcessInspection {
+  if (isNodeError(error) && (error.code === "ENOENT" || error.code === "ESRCH")) {
+    return { kind: "absent" };
+  }
+  if (isExecFailure(error) && error.code === 1) return { kind: "absent" };
+  return {
+    kind: "unknown",
+    diagnostic: `Could not inspect PID ${pid}: ${error instanceof Error ? error.message : String(error)}`,
+  };
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}
+
+function isExecFailure(error: unknown): error is Error & { readonly code: number } {
+  return error instanceof Error && "code" in error && typeof error.code === "number";
+}

package/workflow/worker-child-extension.ts

@@ -0,0 +1,193 @@
+import { createReadStream, readFileSync } from "node:fs";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  parseWorkerLaunchContractV1,
+  validateWorkerChildContext,
+  type WorkerChildContext,
+} from "./worker-launch.js";
+import { classifyProviderFallbackFailure } from "./model-fallback.js";
+import type { WorkerLaunchContractV1 } from "./workflow-types.js";
+
+export default function workerChildExtension(pi: ExtensionAPI): void {
+  const loaded = loadLaunchContract();
+  if (!loaded.ok) {
+    pi.on("session_start", (_event, ctx) => refuse(loaded.error, ctx));
+    pi.on("before_agent_start", (_event, ctx) => refuse(loaded.error, ctx));
+    return;
+  }
+  const contract = loaded.contract;
+  let ready = false;
+
+  pi.registerTool({
+    name: "message_worker",
+    label: "Message Worker",
+    description: "Request one directionally granted peer message through the parent supervisor.",
+    parameters: Type.Object({
+      target: Type.String({ minLength: 1, maxLength: 256 }),
+      message: Type.String({ minLength: 1, maxLength: 32_768 }),
+      correlation: Type.String({ minLength: 1, maxLength: 256 }),
+    }),
+    async execute(_id, params) {
+      writeProtocolLine({
+        type: "pi_amq_worker_peer_message",
+        runId: contract.runId,
+        workerId: contract.workerId,
+        attemptId: contract.attemptId,
+        workerAttemptGeneration: contract.workerAttemptGeneration,
+        supervisorGeneration: contract.supervisorGeneration,
+        target: params.target,
+        message: params.message,
+        correlation: params.correlation,
+      });
+      const details = { status: "requested", target: params.target, correlation: params.correlation };
+      return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details };
+    },
+  });
+
+  pi.registerTool({
+    name: "wait_for_input",
+    label: "Wait for Input",
+    description: "Declare a typed correlated wait without inferring waiting from prose or silence.",
+    parameters: Type.Object({
+      reason: Type.String({ minLength: 1, maxLength: 2_048 }),
+      correlation: Type.String({ minLength: 1, maxLength: 256 }),
+    }),
+    async execute(_id, params) {
+      writeProtocolLine({
+        type: "pi_amq_worker_wait",
+        runId: contract.runId,
+        workerId: contract.workerId,
+        attemptId: contract.attemptId,
+        workerAttemptGeneration: contract.workerAttemptGeneration,
+        supervisorGeneration: contract.supervisorGeneration,
+        reason: params.reason,
+        correlation: params.correlation,
+      });
+      const details = {
+        status: "declared",
+        reason: params.reason,
+        correlation: params.correlation,
+      };
+      return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details };
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    try {
+      validateWorkerChildContext(contract, childContext(ctx));
+      attachParentLiveness(contract, ctx);
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      if (!sessionFile) throw new Error("Pi worker session file is unavailable");
+      writeProtocolLine({
+        type: "pi_amq_worker_ready",
+        runId: contract.runId,
+        workerId: contract.workerId,
+        attemptId: contract.attemptId,
+        workerAttemptGeneration: contract.workerAttemptGeneration,
+        supervisorGeneration: contract.supervisorGeneration,
+        sessionFile,
+      });
+      ready = true;
+    } catch (error) {
+      refuse(error, ctx);
+    }
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    try {
+      if (!ready) throw new Error("Worker launch parity was not established");
+      validateWorkerChildContext(contract, childContext(ctx, event.systemPromptOptions.selectedTools));
+    } catch (error) {
+      refuse(error, ctx);
+    }
+  });
+
+  pi.on("model_select", (_event, ctx) => revalidateOrRefuse(contract, ctx));
+  pi.on("thinking_level_select", (_event, ctx) => revalidateOrRefuse(contract, ctx));
+  pi.on("agent_settled", () => {
+    if (!ready) return;
+    writeProtocolLine({
+      type: "pi_amq_worker_settled",
+      runId: contract.runId,
+      workerId: contract.workerId,
+      attemptId: contract.attemptId,
+      workerAttemptGeneration: contract.workerAttemptGeneration,
+      supervisorGeneration: contract.supervisorGeneration,
+    });
+  });
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message;
+    if (message.role !== "assistant") return;
+    const reason = classifyProviderFallbackFailure(message.stopReason, message.errorMessage);
+    if (!reason) return;
+    writeProtocolLine({
+      type: "pi_amq_worker_provider_failure",
+      runId: contract.runId,
+      workerId: contract.workerId,
+      attemptId: contract.attemptId,
+      workerAttemptGeneration: contract.workerAttemptGeneration,
+      supervisorGeneration: contract.supervisorGeneration,
+      reason,
+    });
+    ctx.shutdown();
+  });
+}
+
+function loadLaunchContract():
+  | { readonly ok: true; readonly contract: WorkerLaunchContractV1 }
+  | { readonly ok: false; readonly error: Error } {
+  try {
+    const path = process.env["PI_AMQ_WORKER_LAUNCH_CONTRACT"];
+    if (!path) throw new Error("PI_AMQ_WORKER_LAUNCH_CONTRACT is required");
+    const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return { ok: true, contract: parseWorkerLaunchContractV1(value) };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+  }
+}
+
+function childContext(ctx: ExtensionContext, tools?: readonly string[]): WorkerChildContext {
+  return {
+    mode: ctx.mode,
+    cwd: ctx.cwd,
+    model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+    thinkingLevel: ctx.thinkingLevel,
+    projectTrusted: ctx.isProjectTrusted(),
+    ...(tools === undefined ? {} : { tools }),
+    environmentKeys: Object.keys(process.env),
+  };
+}
+
+function revalidateOrRefuse(contract: WorkerLaunchContractV1, ctx: ExtensionContext): void {
+  try {
+    validateWorkerChildContext(contract, childContext(ctx));
+  } catch (error) {
+    refuse(error, ctx);
+  }
+}
+
+function attachParentLiveness(contract: WorkerLaunchContractV1, ctx: ExtensionContext): void {
+  const configured = Number(process.env["PI_AMQ_PARENT_LIVENESS_FD"]);
+  if (configured !== contract.parentLivenessFd) {
+    throw new Error("Parent-liveness descriptor does not match the launch contract");
+  }
+  const stream = createReadStream("", { fd: configured, autoClose: false });
+  stream.on("end", () => ctx.shutdown());
+  stream.on("error", () => ctx.shutdown());
+  stream.resume();
+}
+
+function refuse(error: unknown, ctx: ExtensionContext): void {
+  writeProtocolLine({
+    type: "pi_amq_worker_refused",
+    error: error instanceof Error ? error.message : String(error),
+  });
+  ctx.shutdown();
+}
+
+function writeProtocolLine(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}