pi-agent-replicate 0.0.0-stage → 1.4.1

package/pi-extension/subagents/delivery-log.ts

@@ -0,0 +1,51 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+const ALLOWED_FIELDS = [
+  "childId",
+  "deliveryId",
+  "status",
+  "resultPath",
+  "phase",
+  "error",
+  "waitedSince",
+  "waitedMs",
+  "attempt",
+  "cause",
+  "reason",
+  "surface",
+] as const;
+
+function normalizeError(value: unknown): string | undefined {
+  if (value == null) return undefined;
+  return value instanceof Error ? value.message : String(value);
+}
+
+/** Create a contained append-only JSON-lines delivery recorder. */
+export function createDeliveryLog(options: {
+  logPath: string;
+  now?: () => number;
+  onFailure?: (error: unknown) => void;
+}): { record(event: string, fields?: Record<string, unknown>): void } {
+  const now = options.now ?? Date.now;
+  return {
+    record(event, fields = {}) {
+      try {
+        mkdirSync(dirname(options.logPath), { recursive: true });
+        const record: Record<string, unknown> = {
+          version: 1,
+          time: new Date(now()).toISOString(),
+          event,
+        };
+        for (const key of ALLOWED_FIELDS) {
+          if (!(key in fields)) continue;
+          const value = key === "error" ? normalizeError(fields[key]) : fields[key];
+          if (value !== undefined) record[key] = value;
+        }
+        appendFileSync(options.logPath, `${JSON.stringify(record)}\n`, "utf8");
+      } catch (error) {
+        try { options.onFailure?.(error); } catch { /* containment sink is best effort */ }
+      }
+    },
+  };
+}

package/pi-extension/subagents/delivery-payload.ts

@@ -0,0 +1,55 @@
+/** Fixed statuses used for durable subagent result delivery. */
+export const DELIVERY_STATUSES = [
+  "completed",
+  "settled",
+  "help-request",
+  "closed",
+  "crashed",
+  "recovery-failed",
+  "cancelled",
+  "error",
+  "empty",
+] as const;
+
+/** Status stored in result files, inbox entries, and model-visible payloads. */
+export type DeliveryStatus = (typeof DELIVERY_STATUSES)[number];
+
+export interface DeliveryPayloadInput {
+  subject?: "Replica";
+  status: DeliveryStatus;
+  agentName: string;
+  childSessionId: string;
+  childSessionFile?: string;
+  answer?: string;
+  resultPath?: string;
+  deliveryId?: string;
+  elapsed?: number;
+  exitCode?: number;
+}
+
+/** Build one complete direct-child payload without truncating the answer or references. */
+export function frameDeliveryPayload(input: DeliveryPayloadInput): string {
+  if (!(DELIVERY_STATUSES as readonly string[]).includes(input.status)) {
+    throw new Error(`Unsupported delivery status: ${String(input.status)}`);
+  }
+
+  const lines = [
+    `${input.subject ?? "Subagent"} ${input.agentName} ${input.status}.`,
+    "",
+    input.answer ?? "No answer was captured.",
+  ];
+  // Replica results disclose only the work outcome; host references stay in metadata.
+  if (input.subject === "Replica") return lines.join("\n");
+  if (input.resultPath) lines.push("", `Result file: ${input.resultPath}`);
+  if (input.childSessionFile) {
+    lines.push(
+      "",
+      `Session: ${input.childSessionFile}`,
+      `Resume: pi --session ${input.childSessionFile}`,
+    );
+  } else {
+    lines.push("", `Child session: ${input.childSessionId}`);
+  }
+  if (input.deliveryId) lines.push(`Delivery: ${input.deliveryId}`);
+  return lines.join("\n");
+}

package/pi-extension/subagents/delivery.ts

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { interpretExitSidecar, readExitSidecar } from "./completion.ts";
+import { materializeResultFile, type ResultFileHandle, type ResultFileInput } from "./delivery-files.ts";
+import { frameDeliveryPayload, type DeliveryStatus } from "./delivery-payload.ts";
+import {
+  claimLineageInboxMaterialization,
+  completeLineageInboxMaterialization,
+  discoverLineageRoots,
+  pendingLineageInboxes,
+  releaseLineageInboxMaterialization,
+} from "./lineage.ts";
+
+export type DeliveryState = "none" | "delivery-pending" | "delivery-failed" | "delivered";
+export interface DeliveryProjection { state: DeliveryState; error?: string; resultPath?: string }
+
+/** Project model-visible delivery truth from durable inbox and acknowledgement facts. */
+export function projectDeliveryState(facts: {
+  hasInbox?: boolean;
+  materialized?: boolean;
+  failure?: string;
+  resultPath?: string;
+}): DeliveryProjection {
+  if (facts.failure) return { state: "delivery-failed", error: facts.failure, ...(facts.resultPath ? { resultPath: facts.resultPath } : {}) };
+  if (facts.materialized) return { state: "delivered", ...(facts.resultPath ? { resultPath: facts.resultPath } : {}) };
+  if (facts.hasInbox) return { state: "delivery-pending", ...(facts.resultPath ? { resultPath: facts.resultPath } : {}) };
+  return { state: "none" };
+}
+
+interface ParentDestination { sessionId: string; sessionFile: string; active: boolean }
+interface DeliverySinks {
+  materializeResultFile?: (input: ResultFileInput) => ResultFileHandle;
+  publishInbox?: (payload: Record<string, unknown>) => boolean;
+  acknowledgeSidecar?: (path: string) => void;
+  claimMaterialization?: (parent: Omit<ParentDestination, "active">) => { status: "acquired" | "materialized" | "busy"; token?: string };
+  completeMaterialization?: (token: string) => boolean;
+  releaseMaterialization?: (token: string) => void;
+  sendSteer?: (parent: Omit<ParentDestination, "active">, payload: string) => void | Promise<void>;
+  log?: (event: string, fields?: Record<string, unknown>) => void;
+  projectWidget?: (projection: DeliveryProjection) => void;
+  onFailure?: (error: unknown, fields?: Record<string, unknown>) => void;
+}
+
+export interface DeliveryTransactionInput {
+  sessionsDir: string;
+  childSessionId: string;
+  childSessionFile?: string;
+  deliveryId: string;
+  status: DeliveryStatus;
+  agentName: string;
+  answer?: string;
+  parent: ParentDestination;
+  sidecarPath?: string;
+  now?: () => number;
+  sinks?: DeliverySinks;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function containedFailure(sinks: DeliverySinks, error: unknown, fields: Record<string, unknown>): void {
+  const projection = projectDeliveryState({ hasInbox: true, failure: errorText(error), resultPath: typeof fields.resultPath === "string" ? fields.resultPath : undefined });
+  try { sinks.log?.("delivery-failed", { ...fields, error: errorText(error) }); }
+  catch (logError) { try { sinks.onFailure?.(logError, { ...fields, phase: "log" }); } catch { /* contained */ } }
+  try { sinks.projectWidget?.(projection); }
+  catch (widgetError) { try { sinks.onFailure?.(widgetError, { ...fields, phase: "widget" }); } catch { /* contained */ } }
+}
+
+/** Execute the one ordered durable result transaction. Failures stay retryable. */
+export async function runDeliveryTransaction(input: DeliveryTransactionInput): Promise<{ projection: DeliveryProjection; resultPath?: string }> {
+  const sinks = input.sinks ?? {};
+  const destination = { sessionId: input.parent.sessionId, sessionFile: input.parent.sessionFile };
+  if (input.sidecarPath && !existsSync(input.sidecarPath)) {
+    if (!sinks.claimMaterialization) return { projection: { state: "delivered" } };
+    const existing = sinks.claimMaterialization(destination);
+    if (existing.status === "materialized") return { projection: { state: "delivered" } };
+    if (existing.status === "busy") return { projection: { state: "delivery-pending" } };
+    if (existing.token) sinks.releaseMaterialization?.(existing.token);
+  }
+  let handle: ResultFileHandle | undefined;
+  let claimToken: string | undefined;
+  let phase = "materialize-result-file";
+  try {
+    handle = (sinks.materializeResultFile ?? materializeResultFile)({
+      sessionsDir: input.sessionsDir,
+      childSessionId: input.childSessionId,
+      deliveryId: input.deliveryId,
+      status: input.status,
+      agentName: input.agentName,
+      answer: input.answer,
+      now: (input.now ?? Date.now)(),
+    });
+    const payload = frameDeliveryPayload({
+      status: input.status,
+      agentName: input.agentName,
+      childSessionId: input.childSessionId,
+      childSessionFile: input.childSessionFile,
+      answer: input.answer,
+      resultPath: handle.path,
+      deliveryId: input.deliveryId,
+    });
+    phase = "publish-inbox";
+    if (!sinks.publishInbox || sinks.publishInbox({
+      kind: input.status === "settled" ? "settled" : "terminal",
+      status: input.status,
+      resultContent: payload,
+      answer: input.answer,
+      resultPath: handle.path,
+      childSessionFile: input.childSessionFile,
+      deliveryId: input.deliveryId,
+    }) !== true) throw new Error("Inbox publication failed");
+
+    phase = "acknowledge-sidecar";
+    if (input.sidecarPath) (sinks.acknowledgeSidecar ?? ((path: string) => rmSync(path, { force: true })))(input.sidecarPath);
+    if (!input.parent.active) {
+      const projection = projectDeliveryState({ hasInbox: true, resultPath: handle.path });
+      try { sinks.projectWidget?.(projection); } catch (error) { try { sinks.onFailure?.(error, { deliveryId: input.deliveryId, phase: "widget" }); } catch { /* contained */ } }
+      return { projection, resultPath: handle.path };
+    }
+
+    phase = "claim-materialization";
+    if (!sinks.claimMaterialization) throw new Error("Materialization claim sink is unavailable");
+    const claim = sinks.claimMaterialization(destination);
+    if (claim.status === "materialized") return { projection: projectDeliveryState({ hasInbox: true, materialized: true, resultPath: handle.path }), resultPath: handle.path };
+    if (claim.status !== "acquired" || !claim.token) throw new Error("Materialization claim is busy");
+    claimToken = claim.token;
+
+    phase = "send-steer";
+    if (!sinks.sendSteer) throw new Error("Exact-parent steer sink is unavailable");
+    await sinks.sendSteer(destination, payload);
+    phase = "complete-materialization";
+    if (!sinks.completeMaterialization?.(claimToken)) throw new Error("Unable to publish materialization acknowledgement");
+    claimToken = undefined;
+    const projection = projectDeliveryState({ hasInbox: true, materialized: true, resultPath: handle.path });
+    try { sinks.log?.("delivery-sent", { childId: input.childSessionId, deliveryId: input.deliveryId, status: input.status, resultPath: handle.path, phase }); } catch (error) { try { sinks.onFailure?.(error, { deliveryId: input.deliveryId, phase: "log" }); } catch { /* contained */ } }
+    try { sinks.projectWidget?.(projection); } catch (error) { try { sinks.onFailure?.(error, { deliveryId: input.deliveryId, phase: "widget" }); } catch { /* contained */ } }
+    return { projection, resultPath: handle.path };
+  } catch (error) {
+    if (claimToken) {
+      try { sinks.releaseMaterialization?.(claimToken); } catch { /* later recovery reclaims stale ownership */ }
+    }
+    const fields = { childId: input.childSessionId, deliveryId: input.deliveryId, status: input.status, resultPath: handle?.path, phase };
+    containedFailure(sinks, error, fields);
+    return { projection: projectDeliveryState({ hasInbox: Boolean(handle), failure: errorText(error), resultPath: handle?.path }), ...(handle ? { resultPath: handle.path } : {}) };
+  }
+}
+
+/** Read a retained completion sidecar and route it through the durable transaction. */
+export async function processCompletionSidecarDelivery(input: {
+  sessionFile: string;
+  delivery: Omit<DeliveryTransactionInput, "answer" | "sidecarPath"> & { answer?: string };
+}): Promise<{ projection: DeliveryProjection; resultPath?: string }> {
+  const sidecarPath = `${input.sessionFile}.exit`;
+  const sidecar = readExitSidecar(input.sessionFile);
+  if (!sidecar) return { projection: { state: "delivered" } };
+  const result = interpretExitSidecar(sidecar);
+  const answer = input.delivery.answer ?? result.summary ?? result.errorMessage ?? result.ping?.message;
+  return runDeliveryTransaction({ ...input.delivery, answer, sidecarPath });
+}
+
+function findLineageRoots(root: string): string[] {
+  const found = new Set(discoverLineageRoots(root));
+  const visit = (dir: string, depth: number) => {
+    if (depth > 4) return;
+    let entries: ReturnType<typeof readdirSync>;
+    try { entries = readdirSync(dir, { withFileTypes: true }) as any; } catch { return; }
+    const names = new Set((entries as any[]).map((entry) => entry.name));
+    if (names.has("events") && names.has("materialization-claims")) found.add(dir);
+    for (const entry of entries as any[]) if (entry.isDirectory()) visit(join(dir, entry.name), depth + 1);
+  };
+  visit(root, 0);
+  return [...found].sort();
+}
+
+/** Recover pending inboxes for one exact parent session, preserving retry ordering. */
+export async function recoverPendingInboxDeliveries(input: {
+  sessionDir: string;
+  parentSessionId: string;
+  parentSessionFile: string;
+  now?: () => number;
+  deliver: (record: { deliveryId: string; nodeId: string; content: string; resultPath?: string }) => void | Promise<void>;
+  log?: (event: string, fields?: Record<string, unknown>) => void;
+}): Promise<{ materialized: string[]; skipped: string[]; failed: string[] }> {
+  const materialized: string[] = [];
+  const skipped: string[] = [];
+  const failed: string[] = [];
+  for (const rootDir of findLineageRoots(input.sessionDir)) {
+    for (const record of pendingLineageInboxes(rootDir, input.parentSessionId, input.parentSessionFile)) {
+      const claim = claimLineageInboxMaterialization({
+        rootDir,
+        deliveryId: record.deliveryId,
+        nodeId: record.nodeId,
+        hasExactSessionEvidence: () => {
+          try { return existsSync(input.parentSessionFile) && readFileSync(input.parentSessionFile, "utf8").includes(record.deliveryId); }
+          catch { return false; }
+        },
+      });
+      if (claim.status !== "acquired") { skipped.push(record.deliveryId); continue; }
+      try {
+        const content = typeof record.payload.resultContent === "string" ? record.payload.resultContent : "";
+        await input.deliver({ deliveryId: record.deliveryId, nodeId: record.nodeId, content, resultPath: typeof record.payload.resultPath === "string" ? record.payload.resultPath : undefined });
+        if (!completeLineageInboxMaterialization(rootDir, record.deliveryId, record.nodeId, claim.token)) throw new Error("Unable to publish materialization acknowledgement");
+        materialized.push(record.deliveryId);
+      } catch (error) {
+        releaseLineageInboxMaterialization({
+          rootDir,
+          deliveryId: record.deliveryId,
+          nodeId: record.nodeId,
+          token: claim.token,
+          hasExactSessionEvidence: () => false,
+        });
+        failed.push(record.deliveryId);
+        try { input.log?.("delivery-recovery-failed", { deliveryId: record.deliveryId, childId: record.nodeId, phase: "deliver", error: errorText(error) }); } catch { /* contained */ }
+      }
+    }
+  }
+  return { materialized, skipped, failed };
+}

package/pi-extension/subagents/execution-owner.js

@@ -0,0 +1,30 @@
+/** Validate persisted ownership without manufacturing a root for legacy records. */
+export function readExecutionOwner(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const owner = value;
+    return typeof owner.toolCallId === "string" && !!owner.toolCallId &&
+        typeof owner.parentToolCallId === "string" && !!owner.parentToolCallId
+        ? { toolCallId: owner.toolCallId, parentToolCallId: owner.parentToolCallId }
+        : undefined;
+}
+/** Capture only Pi's execution edges; callers snapshot ownership before awaiting launch. */
+export function trackExecutionOwners(pi) {
+    const active = new Map();
+    pi.on("tool_execution_start", (event) => {
+        const parent = event.parentToolCallId;
+        const root = parent
+            ? active.get(parent)?.parentToolCallId
+            : event.toolCallId;
+        if (root)
+            active.set(event.toolCallId, { toolCallId: event.toolCallId, parentToolCallId: root });
+    });
+    pi.on("tool_execution_end", (event) => { active.delete(event.toolCallId); });
+    pi.on("session_start", () => { active.clear(); });
+    pi.on("session_shutdown", () => { active.clear(); });
+    return (id) => active.get(id);
+}
+/** Stereo consumes the visible root; retain the leaf independently for provenance. */
+export function linkedOutputDetails(owner) {
+    return owner ? { originatingToolCallId: owner.toolCallId, parentToolCallId: owner.parentToolCallId } : {};
+}

package/pi-extension/subagents/execution-owner.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** Actual attempt execution and its visible outer tool call, never inferred from IDs. */
+export interface ExecutionOwner {
+	toolCallId: string;
+	parentToolCallId: string;
+}
+
+/** Validate persisted ownership without manufacturing a root for legacy records. */
+export function readExecutionOwner(value: unknown): ExecutionOwner | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const owner = value as Partial<ExecutionOwner>;
+	return typeof owner.toolCallId === "string" && !!owner.toolCallId &&
+		typeof owner.parentToolCallId === "string" && !!owner.parentToolCallId
+		? { toolCallId: owner.toolCallId, parentToolCallId: owner.parentToolCallId }
+		: undefined;
+}
+
+/** Capture only Pi's execution edges; callers snapshot ownership before awaiting launch. */
+export function trackExecutionOwners(pi: ExtensionAPI): (id: string) => ExecutionOwner | undefined {
+	const active = new Map<string, ExecutionOwner>();
+	pi.on("tool_execution_start", (event) => {
+		const parent = (event as typeof event & { parentToolCallId?: string }).parentToolCallId;
+		const root = parent
+			? active.get(parent)?.parentToolCallId
+			: event.toolCallId;
+		if (root) active.set(event.toolCallId, { toolCallId: event.toolCallId, parentToolCallId: root });
+	});
+	pi.on("tool_execution_end", (event) => { active.delete(event.toolCallId); });
+	pi.on("session_start", () => { active.clear(); });
+	pi.on("session_shutdown", () => { active.clear(); });
+	return (id) => active.get(id);
+}
+
+/** Stereo consumes the visible root; retain the leaf independently for provenance. */
+export function linkedOutputDetails(owner: ExecutionOwner | undefined): Record<string, string> {
+	return owner ? { originatingToolCallId: owner.toolCallId, parentToolCallId: owner.parentToolCallId } : {};
+}