pi-amq 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-amq",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A daemonless AMQ bridge and governed worker runtime for pi",
   "type": "module",
   "license": "MIT",

package/transport/runtime-status.ts

@@ -59,12 +59,23 @@ export function projectInboxStatus(
   if (mode === "print" || mode === "json") return { surface: "none" };
   const value = cloneStatus(status);
   if (mode === "rpc") return { surface: "rpc", value };
-  const backoff = status.nextBackoffMs === null ? "" : ` ${status.nextBackoffMs}ms`;
-  const counts = status.staged;
-  const error = status.lastError ? ` error=${bounded(status.lastError)}` : "";
+  if (status.receiver === "dormant") return { surface: "none" };
+  const parts = ["AMQ"];
+  if (status.watch === "backoff" || status.watch === "recovering") {
+    parts.push(status.nextBackoffMs === null
+      ? "reconnecting"
+      : `reconnecting in ${status.nextBackoffMs}ms`);
+  } else {
+    parts.push(status.receiver);
+  }
+  const counts = Object.entries(status.staged)
+    .filter(([, count]) => count > 0)
+    .map(([priority, count]) => `${count} ${priority}`);
+  if (counts.length > 0) parts.push(counts.join(", "));
+  if (status.lastError) parts.push(bounded(status.lastError));
   return {
     surface: "tui",
-    text: `AMQ ${status.receiver}/${status.watch}${backoff} u=${counts.urgent} n=${counts.normal} l=${counts.low}${error}`,
+    text: parts.join(" · "),
     value,
   };
 }

package/workflow/run-store.ts

@@ -47,10 +47,11 @@ import type {
   WorkerProposalProvenance,
   WorkerRequest,
   WorkerRoleContract,
-  WorkerLaunchContractV1,
+  WorkerLaunchContract,
+  WorkerLaunchContractV2,
   WorkspaceGrant,
 } from "./workflow-types.js";
-import { parseWorkerLaunchContractV1 } from "./worker-launch.js";
+import { parseWorkerLaunchContract, parseWorkerLaunchContractV2 } from "./worker-launch.js";
 import {
   UNLIMITED,
   budgetExceeded,
@@ -472,7 +473,8 @@ export class WorkflowRunStore {
     readonly workerAttemptGeneration: string;
     readonly leaseGeneration: string;
     readonly processIdentity: ProcessIdentity;
-    readonly launchContract: WorkerLaunchContractV1;
+    /** Write side is schema 2 only; schema 1 stays readable history and never launches a child. */
+    readonly launchContract: WorkerLaunchContractV2;
   }): Promise<RunProjectionV2> {
     const requestKey = validateRequestKey(inputRequestKey);
     return this.#withRunMutation(requestKey, async (current, events) => {
@@ -496,7 +498,7 @@ export class WorkflowRunStore {
           workerAttemptGeneration: input.workerAttemptGeneration,
           leaseGeneration: requireNonEmpty(input.leaseGeneration, "lease generation"),
           processIdentity: parseProcessIdentity(input.processIdentity),
-          launchContract: parseWorkerLaunchContractV1(input.launchContract),
+          launchContract: parseWorkerLaunchContractV2(input.launchContract),
         }),
       };
     });
@@ -2186,7 +2188,7 @@ function parseAttemptStartPayload(value: unknown): {
   readonly workerAttemptGeneration: string;
   readonly leaseGeneration: string;
   readonly processIdentity: ProcessIdentity;
-  readonly launchContract: WorkerLaunchContractV1;
+  readonly launchContract: WorkerLaunchContract;
 } {
   const object = strictRecord(
     value,
@@ -2199,7 +2201,7 @@ function parseAttemptStartPayload(value: unknown): {
     workerAttemptGeneration: nonEmptyString(object, "workerAttemptGeneration"),
     leaseGeneration: nonEmptyString(object, "leaseGeneration"),
     processIdentity: parseProcessIdentity(object["processIdentity"]),
-    launchContract: parseWorkerLaunchContractV1(object["launchContract"]),
+    launchContract: parseWorkerLaunchContract(object["launchContract"]),
   };
 }
 
@@ -2590,7 +2592,7 @@ function parseWorkerAttempt(value: unknown): WorkerAttemptProjection {
     },
     launchContract: object["launchContract"] === null
       ? null
-      : parseWorkerLaunchContractV1(object["launchContract"]),
+      : parseWorkerLaunchContract(object["launchContract"]),
     ...(modelSelection ? {
       modelSelection: {
         model: parseModelSpec(modelSelection["model"]),

package/workflow/worker-child-extension.ts

@@ -1,25 +1,39 @@
-import { createReadStream, readFileSync } from "node:fs";
+import { createReadStream, readFileSync, writeSync } from "node:fs";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import {
-  parseWorkerLaunchContractV1,
+  parseWorkerLaunchContractV2,
   validateWorkerChildContext,
   type WorkerChildContext,
 } from "./worker-launch.js";
 import { classifyProviderFallbackFailure } from "./model-fallback.js";
-import type { WorkerLaunchContractV1 } from "./workflow-types.js";
+import type { WorkerLaunchContractV2 } from "./workflow-types.js";
+
+type ProtocolWriter = (value: unknown) => void;
 
 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));
+    pi.on("session_start", (_event, ctx) => refuseWithoutProtocol(loaded.error, ctx));
+    pi.on("before_agent_start", (_event, ctx) => refuseWithoutProtocol(loaded.error, ctx));
     return;
   }
   const contract = loaded.contract;
+  let writeProtocol: ProtocolWriter;
+  try {
+    writeProtocol = createProtocolWriter(contract);
+  } catch (error) {
+    pi.on("session_start", (_event, ctx) => refuseWithoutProtocol(error, ctx));
+    pi.on("before_agent_start", (_event, ctx) => refuseWithoutProtocol(error, ctx));
+    return;
+  }
   let ready = false;
+  // The inherited liveness descriptor is single-use for this process: releasing it closes fd 3,
+  // so a later re-attach could never succeed. Track the state explicitly instead of detaching
+  // and reopening, which would surface as a silent shutdown rather than a visible refusal.
+  const liveness = createParentLivenessGuard(contract);
 
   pi.registerTool({
     name: "message_worker",
@@ -31,7 +45,7 @@ export default function workerChildExtension(pi: ExtensionAPI): void {
       correlation: Type.String({ minLength: 1, maxLength: 256 }),
     }),
     async execute(_id, params) {
-      writeProtocolLine({
+      writeProtocol({
         type: "pi_amq_worker_peer_message",
         runId: contract.runId,
         workerId: contract.workerId,
@@ -56,7 +70,7 @@ export default function workerChildExtension(pi: ExtensionAPI): void {
       correlation: Type.String({ minLength: 1, maxLength: 256 }),
     }),
     async execute(_id, params) {
-      writeProtocolLine({
+      writeProtocol({
         type: "pi_amq_worker_wait",
         runId: contract.runId,
         workerId: contract.workerId,
@@ -78,10 +92,10 @@ export default function workerChildExtension(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
     try {
       validateWorkerChildContext(contract, childContext(ctx));
-      attachParentLiveness(contract, ctx);
+      liveness.attach(ctx);
       const sessionFile = ctx.sessionManager.getSessionFile();
       if (!sessionFile) throw new Error("Pi worker session file is unavailable");
-      writeProtocolLine({
+      writeProtocol({
         type: "pi_amq_worker_ready",
         runId: contract.runId,
         workerId: contract.workerId,
@@ -92,7 +106,7 @@ export default function workerChildExtension(pi: ExtensionAPI): void {
       });
       ready = true;
     } catch (error) {
-      refuse(error, ctx);
+      refuse(error, ctx, writeProtocol);
     }
   });
 
@@ -101,15 +115,16 @@ export default function workerChildExtension(pi: ExtensionAPI): void {
       if (!ready) throw new Error("Worker launch parity was not established");
       validateWorkerChildContext(contract, childContext(ctx, event.systemPromptOptions.selectedTools));
     } catch (error) {
-      refuse(error, ctx);
+      refuse(error, ctx, writeProtocol);
     }
   });
 
-  pi.on("model_select", (_event, ctx) => revalidateOrRefuse(contract, ctx));
-  pi.on("thinking_level_select", (_event, ctx) => revalidateOrRefuse(contract, ctx));
+  pi.on("model_select", (_event, ctx) => revalidateOrRefuse(contract, ctx, writeProtocol));
+  pi.on("thinking_level_select", (_event, ctx) => revalidateOrRefuse(contract, ctx, writeProtocol));
+  pi.on("session_shutdown", () => liveness.release());
   pi.on("agent_settled", () => {
     if (!ready) return;
-    writeProtocolLine({
+    writeProtocol({
       type: "pi_amq_worker_settled",
       runId: contract.runId,
       workerId: contract.workerId,
@@ -123,7 +138,7 @@ export default function workerChildExtension(pi: ExtensionAPI): void {
     if (message.role !== "assistant") return;
     const reason = classifyProviderFallbackFailure(message.stopReason, message.errorMessage);
     if (!reason) return;
-    writeProtocolLine({
+    writeProtocol({
       type: "pi_amq_worker_provider_failure",
       runId: contract.runId,
       workerId: contract.workerId,
@@ -137,13 +152,13 @@ export default function workerChildExtension(pi: ExtensionAPI): void {
 }
 
 function loadLaunchContract():
-  | { readonly ok: true; readonly contract: WorkerLaunchContractV1 }
+  | { readonly ok: true; readonly contract: WorkerLaunchContractV2 }
   | { 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) };
+    return { ok: true, contract: parseWorkerLaunchContractV2(value) };
   } catch (error) {
     return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
   }
@@ -161,33 +176,100 @@ function childContext(ctx: ExtensionContext, tools?: readonly string[]): WorkerC
   };
 }
 
-function revalidateOrRefuse(contract: WorkerLaunchContractV1, ctx: ExtensionContext): void {
+function revalidateOrRefuse(
+  contract: WorkerLaunchContractV2,
+  ctx: ExtensionContext,
+  writeProtocol: ProtocolWriter,
+): void {
   try {
     validateWorkerChildContext(contract, childContext(ctx));
   } catch (error) {
-    refuse(error, ctx);
+    refuse(error, ctx, writeProtocol);
   }
 }
 
-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");
+interface ParentLivenessGuard {
+  /** Idempotent: a repeated session_start keeps the existing stream instead of reopening fd 3. */
+  attach(ctx: ExtensionContext): void;
+  /** Closes the descriptor so a settled one-shot child can exit. The guard stays released. */
+  release(): void;
+}
+
+function createParentLivenessGuard(contract: WorkerLaunchContractV2): ParentLivenessGuard {
+  let state: "unattached" | "attached" | "released" = "unattached";
+  let detach = (): void => {};
+  return {
+    attach(ctx) {
+      if (state === "attached") return;
+      if (state === "released") {
+        throw new Error("Parent-liveness descriptor was already released and cannot be reattached");
+      }
+      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: true });
+      const requestShutdown = (): void => {
+        try {
+          ctx.shutdown();
+        } catch (error) {
+          console.error(`pi-amq parent-liveness shutdown failed: ${errorMessage(error)}`);
+        }
+      };
+      stream.on("end", requestShutdown);
+      stream.on("error", requestShutdown);
+      stream.resume();
+      detach = () => {
+        stream.off("end", requestShutdown);
+        stream.off("error", requestShutdown);
+        stream.destroy();
+      };
+      state = "attached";
+    },
+    release() {
+      if (state !== "attached") return;
+      detach();
+      detach = (): void => {};
+      state = "released";
+    },
+  };
+}
+
+function refuse(error: unknown, ctx: ExtensionContext, writeProtocol: ProtocolWriter): void {
+  try {
+    writeProtocol({
+      type: "pi_amq_worker_refused",
+      error: error instanceof Error ? error.message : String(error),
+    });
+  } catch (protocolError) {
+    console.error(`pi-amq worker protocol refusal failed: ${errorMessage(protocolError)}`);
   }
-  const stream = createReadStream("", { fd: configured, autoClose: false });
-  stream.on("end", () => ctx.shutdown());
-  stream.on("error", () => ctx.shutdown());
-  stream.resume();
+  ctx.shutdown();
 }
 
-function refuse(error: unknown, ctx: ExtensionContext): void {
-  writeProtocolLine({
-    type: "pi_amq_worker_refused",
-    error: error instanceof Error ? error.message : String(error),
-  });
+function refuseWithoutProtocol(error: unknown, ctx: ExtensionContext): void {
+  console.error(`pi-amq worker launch refused: ${errorMessage(error)}`);
   ctx.shutdown();
 }
 
-function writeProtocolLine(value: unknown): void {
-  process.stdout.write(`${JSON.stringify(value)}\n`);
+function createProtocolWriter(contract: WorkerLaunchContractV2): ProtocolWriter {
+  const configured = Number(process.env["PI_AMQ_PROTOCOL_FD"]);
+  if (configured !== contract.protocolFd) {
+    throw new Error("Worker protocol descriptor does not match the launch contract");
+  }
+  return (value) => writeProtocolLine(contract.protocolFd, value);
+}
+
+function writeProtocolLine(fd: number, value: unknown): void {
+  const line = Buffer.from(`${JSON.stringify(value)}\n`, "utf8");
+  let offset = 0;
+  while (offset < line.byteLength) {
+    const written = writeSync(fd, line, offset, line.byteLength - offset);
+    if (written <= 0) throw new Error("Worker protocol descriptor accepted no bytes");
+    offset += written;
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
 }

package/workflow/worker-launch.ts

@@ -4,7 +4,9 @@ import type {
   AttemptId,
   ModelSpec,
   WorkerContract,
+  WorkerLaunchContract,
   WorkerLaunchContractV1,
+  WorkerLaunchContractV2,
 } from "./workflow-types.js";
 import { parseBudgetLimit } from "./budget.js";
 
@@ -44,12 +46,13 @@ export interface PiProcessLaunchCommand {
   readonly cwd: string;
   readonly env: Readonly<Record<string, string>>;
   readonly parentLivenessFd: 3;
-  readonly launchContract: WorkerLaunchContractV1;
+  readonly protocolFd: 4;
+  readonly launchContract: WorkerLaunchContractV2;
   readonly launchContractPath: string;
 }
 
 export interface ResolvedWorkerLaunch {
-  readonly contract: WorkerLaunchContractV1;
+  readonly contract: WorkerLaunchContractV2;
   readonly command: PiProcessLaunchCommand;
 }
 
@@ -71,19 +74,50 @@ export class WorkerLaunchValidationError extends Error {
 }
 
 export function parseWorkerLaunchContractV1(value: unknown): WorkerLaunchContractV1 {
+  const parsed = parseWorkerLaunchContractVersion(value, 1);
+  if (parsed.schema !== 1) throw new WorkerLaunchValidationError("Worker launch schema must be 1");
+  return parsed;
+}
+
+export function parseWorkerLaunchContractV2(value: unknown): WorkerLaunchContractV2 {
+  const parsed = parseWorkerLaunchContractVersion(value, 2);
+  if (parsed.schema !== 2) throw new WorkerLaunchValidationError("Worker launch schema must be 2");
+  return parsed;
+}
+
+export function parseWorkerLaunchContract(value: unknown): WorkerLaunchContract {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new WorkerLaunchValidationError("worker launch contract must be an object");
+  }
+  const schema = (value as Record<string, unknown>)["schema"];
+  if (schema === 1) return parseWorkerLaunchContractV1(value);
+  if (schema === 2) return parseWorkerLaunchContractV2(value);
+  throw new WorkerLaunchValidationError("Worker launch schema must be 1 or 2");
+}
+
+function parseWorkerLaunchContractVersion(
+  value: unknown,
+  schema: 1 | 2,
+): WorkerLaunchContract {
   const object = strictObject(value, [
     "schema", "runId", "workerId", "attemptId", "workerAttemptGeneration",
     "supervisorGeneration", "transportMode", "channel", "depth", "model", "capabilities",
     "tools", "workspace", "sessionDirectory", "projectTrust", "parentLivenessFd", "budget",
     "sideEffectPolicy", "continuedSessionFile", "forkedSessionFile",
+    ...(schema === 2 ? ["protocolFd"] : []),
   ], "worker launch contract");
-  if (object["schema"] !== 1) throw new WorkerLaunchValidationError("Worker launch schema must be 1");
+  if (object["schema"] !== schema) {
+    throw new WorkerLaunchValidationError(`Worker launch schema must be ${schema}`);
+  }
   if (object["transportMode"] !== "send-only") {
     throw new WorkerLaunchValidationError("Worker launch transport mode must be send-only");
   }
   if (object["parentLivenessFd"] !== 3) {
     throw new WorkerLaunchValidationError("Worker parent-liveness descriptor must be 3");
   }
+  if (schema === 2 && object["protocolFd"] !== 4) {
+    throw new WorkerLaunchValidationError("Worker protocol descriptor must be 4");
+  }
   const model = strictObject(object["model"], ["provider", "id", "thinkingLevel"], "worker model");
   const workspace = strictObject(object["workspace"], ["path", "mode", "worktreePath"], "worker workspace");
   const budget = strictObject(
@@ -118,11 +152,10 @@ export function parseWorkerLaunchContractV1(value: unknown): WorkerLaunchContrac
   if (continuedSessionFile !== undefined && forkedSessionFile !== undefined) {
     throw new WorkerLaunchValidationError("Worker launch cannot continue and fork a session together");
   }
-  return {
-    schema: 1,
-    runId: prefixedString(object["runId"], "run", "run ID") as WorkerLaunchContractV1["runId"],
-    workerId: prefixedString(object["workerId"], "worker", "worker ID") as WorkerLaunchContractV1["workerId"],
-    attemptId: prefixedString(object["attemptId"], "attempt", "attempt ID") as WorkerLaunchContractV1["attemptId"],
+  const fields: Omit<WorkerLaunchContractV1, "schema"> = {
+    runId: prefixedString(object["runId"], "run", "run ID") as WorkerLaunchContract["runId"],
+    workerId: prefixedString(object["workerId"], "worker", "worker ID") as WorkerLaunchContract["workerId"],
+    attemptId: prefixedString(object["attemptId"], "attempt", "attempt ID") as WorkerLaunchContract["attemptId"],
     workerAttemptGeneration: requiredString(
       object["workerAttemptGeneration"],
       "worker attempt generation",
@@ -169,6 +202,9 @@ export function parseWorkerLaunchContractV1(value: unknown): WorkerLaunchContrac
       "worker side-effect policy",
     ),
   };
+  return schema === 1
+    ? { schema: 1, ...fields }
+    : { schema: 2, ...fields, protocolFd: 4 };
 }
 
 export function resolveWorkerLaunch(input: {
@@ -260,8 +296,8 @@ export function resolveWorkerLaunch(input: {
     ),
     ...(contract.channel === "rpc" ? ["wait_for_input"] : []),
   ])].sort();
-  const launchContract: WorkerLaunchContractV1 = {
-    schema: 1,
+  const launchContract: WorkerLaunchContractV2 = {
+    schema: 2,
     runId: contract.runId,
     workerId: contract.workerId,
     attemptId: attempt.attemptId,
@@ -286,6 +322,7 @@ export function resolveWorkerLaunch(input: {
     ...(forkedSessionFile ? { forkedSessionFile } : {}),
     projectTrust,
     parentLivenessFd: 3,
+    protocolFd: 4,
     budget: contract.budget,
     sideEffectPolicy: contract.sideEffectPolicy,
   };
@@ -303,6 +340,7 @@ export function resolveWorkerLaunch(input: {
       cwd: absolutePath(contract.workspace.worktreePath ?? contract.workspace.path, "worker cwd"),
       env: childEnvironment(authority.inheritedEnvironment, launchContractPath),
       parentLivenessFd: 3,
+      protocolFd: 4,
       launchContract,
       launchContractPath,
     },
@@ -310,7 +348,7 @@ export function resolveWorkerLaunch(input: {
 }
 
 export function validateWorkerChildContext(
-  contract: WorkerLaunchContractV1,
+  contract: WorkerLaunchContract,
   context: WorkerChildContext,
 ): void {
   const expectedMode = contract.channel === "json-result" ? "json" : "rpc";
@@ -352,7 +390,7 @@ export function isReceiverAuthorityEnvironmentKey(key: string): boolean {
 }
 
 function buildPiArguments(
-  contract: WorkerLaunchContractV1,
+  contract: WorkerLaunchContract,
   childExtensionPath: string,
   requiresProjectResources: boolean,
   prompt: string,
@@ -400,6 +438,7 @@ function childEnvironment(
   }
   env["PI_AMQ_WORKER_LAUNCH_CONTRACT"] = launchContractPath;
   env["PI_AMQ_PARENT_LIVENESS_FD"] = "3";
+  env["PI_AMQ_PROTOCOL_FD"] = "4";
   return env;
 }