pi-amq 0.1.1

package/transport/runtime-status.ts

@@ -0,0 +1,112 @@
+export type PiRuntimeMode = "tui" | "rpc" | "json" | "print";
+
+import type { ReceiverLeaseAcquireResult } from "./receiver-lease.js";
+
+export interface InboxRuntimeStatus {
+  readonly receiver: "dormant" | "send-only" | "receiving";
+  readonly watch: "stopped" | "recovering" | "watching" | "backoff" | "disabled";
+  readonly receiverGeneration: string | null;
+  readonly backoffAttempt: number;
+  readonly nextBackoffMs: number | null;
+  readonly lastError: string | null;
+  readonly staged: {
+    readonly urgent: number;
+    readonly normal: number;
+    readonly low: number;
+  };
+}
+
+export type InboxStatusProjection =
+  | { readonly surface: "tui"; readonly text: string; readonly value: InboxRuntimeStatus }
+  | { readonly surface: "rpc"; readonly value: InboxRuntimeStatus }
+  | { readonly surface: "none" };
+
+export type ReceiverLeaseRuntimeDisposition =
+  | { readonly mode: "receiving"; readonly generation: string }
+  | { readonly mode: "send-only"; readonly diagnostic: string };
+
+export class InboxStatusStore {
+  #status: InboxRuntimeStatus = {
+    receiver: "dormant",
+    watch: "stopped",
+    receiverGeneration: null,
+    backoffAttempt: 0,
+    nextBackoffMs: null,
+    lastError: null,
+    staged: { urgent: 0, normal: 0, low: 0 },
+  };
+  readonly #listeners = new Set<(status: InboxRuntimeStatus) => void>();
+
+  snapshot(): InboxRuntimeStatus {
+    return cloneStatus(this.#status);
+  }
+
+  update(update: Partial<InboxRuntimeStatus>): void {
+    this.#status = cloneStatus({ ...this.#status, ...update });
+    for (const listener of this.#listeners) listener(this.snapshot());
+  }
+
+  subscribe(listener: (status: InboxRuntimeStatus) => void): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+}
+
+export function projectInboxStatus(
+  mode: PiRuntimeMode,
+  status: InboxRuntimeStatus,
+): InboxStatusProjection {
+  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)}` : "";
+  return {
+    surface: "tui",
+    text: `AMQ ${status.receiver}/${status.watch}${backoff} u=${counts.urgent} n=${counts.normal} l=${counts.low}${error}`,
+    value,
+  };
+}
+
+export async function runInboxForMode(
+  mode: PiRuntimeMode,
+  pump: { run(signal?: AbortSignal): Promise<void> },
+  status: InboxStatusStore,
+  signal?: AbortSignal,
+): Promise<{ readonly kind: "send-only" } | { readonly kind: "completed" }> {
+  if (mode === "print" || mode === "json") {
+    status.update({
+      receiver: "send-only",
+      watch: "disabled",
+      receiverGeneration: null,
+      nextBackoffMs: null,
+      lastError: null,
+    });
+    return { kind: "send-only" };
+  }
+  await pump.run(signal);
+  return { kind: "completed" };
+}
+
+export function receiverLeaseRuntimeDisposition(
+  result: ReceiverLeaseAcquireResult,
+): ReceiverLeaseRuntimeDisposition {
+  if (result.kind === "acquired") {
+    return { mode: "receiving", generation: result.owner.generation };
+  }
+  return {
+    mode: "send-only",
+    diagnostic: result.kind === "held"
+      ? `Receiver is held by pi session ${result.owner.piSessionId}`
+      : result.diagnostic,
+  };
+}
+
+function cloneStatus(status: InboxRuntimeStatus): InboxRuntimeStatus {
+  return { ...status, staged: { ...status.staged } };
+}
+
+function bounded(value: string): string {
+  return value.length <= 160 ? value : `${value.slice(0, 159)}…`;
+}

package/workflow/.gitkeep

@@ -0,0 +1 @@
+

package/workflow/atomic-storage.ts

@@ -0,0 +1,120 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, link, open, readFile, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export type WorkflowAtomicWritePoint =
+  | "after-file-sync"
+  | "before-commit"
+  | "after-commit"
+  | "after-directory-sync";
+
+export type WorkflowAtomicFaultInjector = (
+  point: WorkflowAtomicWritePoint,
+) => void | Promise<void>;
+
+export async function writeWorkflowJson(
+  path: string,
+  value: unknown,
+  options: {
+    readonly createOnly?: boolean;
+    readonly fault?: WorkflowAtomicFaultInjector;
+  } = {},
+): Promise<void> {
+  const parent = dirname(path);
+  const temporaryPath = join(parent, `.pi-amq-workflow-${randomUUID()}.tmp`);
+  const contents = `${JSON.stringify(value)}\n`;
+  let committed = false;
+
+  try {
+    const handle = await open(temporaryPath, "wx", 0o600);
+    try {
+      await handle.writeFile(contents, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await chmod(temporaryPath, 0o600);
+    await options.fault?.("after-file-sync");
+    await options.fault?.("before-commit");
+    if (options.createOnly) {
+      await link(temporaryPath, path);
+      committed = true;
+      await unlink(temporaryPath);
+    } else {
+      await rename(temporaryPath, path);
+      committed = true;
+    }
+    await options.fault?.("after-commit");
+    await syncWorkflowDirectory(parent);
+    await options.fault?.("after-directory-sync");
+  } catch (error) {
+    if (!committed) await removeFileIfPresent(temporaryPath);
+    throw error;
+  }
+}
+
+export async function readWorkflowJson(path: string): Promise<unknown | undefined> {
+  let contents: string;
+  try {
+    contents = await readFile(path, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+  return JSON.parse(contents) as unknown;
+}
+
+export async function syncWorkflowDirectory(path: string): Promise<void> {
+  let handle;
+  try {
+    handle = await open(path, "r");
+    await handle.sync();
+  } catch (error) {
+    if (!isUnsupportedDirectorySync(error)) throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function sha256(value: string): string {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalize(child)]),
+    );
+  }
+  if (value === undefined || typeof value === "function" || typeof value === "symbol") {
+    throw new TypeError("Workflow state must be JSON serializable");
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new TypeError("Workflow state numbers must be finite");
+  }
+  return value;
+}
+
+async function removeFileIfPresent(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+  }
+}
+
+function isUnsupportedDirectorySync(error: unknown): boolean {
+  return isNodeError(error)
+    && (error.code === "EINVAL" || error.code === "ENOTSUP" || error.code === "EISDIR");
+}
+
+export function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/workflow/budget.ts

@@ -0,0 +1,90 @@
+import type { BudgetLimit } from "./workflow-types.js";
+
+export const UNLIMITED: BudgetLimit = Object.freeze({ kind: "unlimited" });
+
+export function limited(value: number): BudgetLimit {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new TypeError("Budget limit must be positive and finite");
+  }
+  return { kind: "limited", value };
+}
+
+export function limitedInteger(value: number): BudgetLimit {
+  if (!Number.isSafeInteger(value)) throw new TypeError("Budget limit must be a safe integer");
+  return limited(value);
+}
+
+export function parseBudgetLimit(
+  value: unknown,
+  name: string,
+  options: { readonly integer: boolean; readonly allowLegacyNumber?: boolean } = { integer: false },
+): BudgetLimit {
+  if (options.allowLegacyNumber && typeof value === "number") {
+    return options.integer ? limitedInteger(value) : limited(value);
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${name} must be limited(value) or unlimited`);
+  }
+  const object = value as Record<string, unknown>;
+  const keys = Object.keys(object);
+  if (object["kind"] === "unlimited") {
+    if (keys.length !== 1) throw new TypeError(`${name} unlimited limit has unknown fields`);
+    return UNLIMITED;
+  }
+  if (object["kind"] !== "limited" || keys.some((key) => key !== "kind" && key !== "value")) {
+    throw new TypeError(`${name} must be limited(value) or unlimited`);
+  }
+  if (keys.length !== 2) throw new TypeError(`${name} limited limit requires value`);
+  const numeric = object["value"];
+  if (typeof numeric !== "number") throw new TypeError(`${name} value must be a number`);
+  return options.integer ? limitedInteger(numeric) : limited(numeric);
+}
+
+export function isUnlimited(limit: BudgetLimit): boolean {
+  return limit.kind === "unlimited";
+}
+
+export function budgetValue(limit: BudgetLimit): number | undefined {
+  return limit.kind === "limited" ? limit.value : undefined;
+}
+
+export function budgetExceeded(observed: number, limit: BudgetLimit): boolean {
+  return limit.kind === "limited" && observed > limit.value;
+}
+
+export function remainingBudget(limit: BudgetLimit, used: number | "unlimited"): BudgetLimit {
+  if (limit.kind === "unlimited") return UNLIMITED;
+  if (used === "unlimited") return { kind: "limited", value: 0 };
+  return { kind: "limited", value: Math.max(0, limit.value - used) };
+}
+
+export function reserveBudget(
+  current: number | "unlimited",
+  requested: BudgetLimit,
+): number | "unlimited" {
+  if (current === "unlimited" || requested.kind === "unlimited") return "unlimited";
+  return current + requested.value;
+}
+
+export function assertBudgetRequestFits(
+  available: BudgetLimit,
+  requested: BudgetLimit,
+  message: string,
+): void {
+  if (available.kind === "unlimited") return;
+  if (requested.kind === "unlimited" || requested.value > available.value) {
+    throw new Error(message);
+  }
+}
+
+export function budgetExhausted(observed: number, limit: BudgetLimit): boolean {
+  return limit.kind === "limited" && observed >= limit.value;
+}
+
+export function budgetAtLeast(limit: BudgetLimit, observed: number): boolean {
+  return limit.kind === "unlimited" || limit.value >= observed;
+}
+
+export function budgetLimitLabel(limit: BudgetLimit): string {
+  return limit.kind === "unlimited" ? "unlimited" : String(limit.value);
+}

package/workflow/index.ts

@@ -0,0 +1,16 @@
+export * from "./run-store.js";
+export * from "./run-cleanup.js";
+export * from "./run-artifacts.js";
+export * from "./workflow-doctor.js";
+export * from "./run-gate.js";
+export * from "./lifecycle-projection.js";
+export * from "./budget.js";
+export * from "./system-process-inspector.js";
+export * from "./worker-launch.js";
+export * from "./worker-gate.js";
+export * from "./worker-model-catalog.js";
+export * from "./worker-prompt-capsule.js";
+export * from "./worker-process-supervisor.js";
+export * from "./workflow-lease.js";
+export * from "./workflow-types.js";
+export * from "./workspace-paths.js";

package/workflow/lifecycle-projection.ts

@@ -0,0 +1,37 @@
+export interface WorkerLifecycleProjectionV1 {
+  readonly body: string;
+  readonly labels: readonly string[];
+  readonly context: {
+    readonly orchestrator: {
+      readonly version: 1;
+      readonly name: "pi-amq";
+      readonly transport: "extension";
+      readonly event: "worker_lifecycle";
+      readonly task: { readonly id: string; readonly state: string };
+    };
+  };
+}
+
+export function projectWorkerLifecycle(
+  workerId: string,
+  state: string,
+): WorkerLifecycleProjectionV1 {
+  const labels = ["orchestrator", "orchestrator:pi-amq", `task-state:${state}`];
+  if (state === "ready_for_review") labels.push("handoff");
+  if (state === "failed" || state === "interrupted" || state === "blocked") {
+    labels.push("blocking");
+  }
+  return {
+    body: JSON.stringify({ workerId, state }),
+    labels,
+    context: {
+      orchestrator: {
+        version: 1,
+        name: "pi-amq",
+        transport: "extension",
+        event: "worker_lifecycle",
+        task: { id: workerId, state },
+      },
+    },
+  };
+}

package/workflow/model-fallback.ts

@@ -0,0 +1,17 @@
+export function classifyProviderFallbackFailure(
+  stopReason: unknown,
+  errorMessage: unknown,
+): string | null {
+  if (stopReason !== "error" || typeof errorMessage !== "string") return null;
+  const diagnostic = errorMessage.trim();
+  if (diagnostic.length === 0) return null;
+  const normalized = diagnostic.toLowerCase();
+  const category = /auth|credential|api[ _-]?key|unauthori[sz]ed|forbidden/.test(normalized)
+    ? "provider-auth"
+    : /quota|rate[ _-]?limit|resource exhausted|billing limit/.test(normalized)
+      ? "provider-quota"
+      : /capacity|overloaded|temporarily unavailable|no available.*server/.test(normalized)
+        ? "provider-capacity"
+        : null;
+  return category ? `${category}: ${diagnostic}` : null;
+}

package/workflow/pi-session-fork.ts

@@ -0,0 +1,96 @@
+import { access, mkdir, readFile, rename, rm } from "node:fs/promises";
+import { isAbsolute, dirname, normalize } from "node:path";
+
+import { SessionManager, type SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import type { WorkerForkSource } from "./workflow-types.js";
+
+export interface PiSessionForkInput extends WorkerForkSource {
+  readonly targetSessionFile: string;
+}
+
+export interface PiSessionForker {
+  fork(input: PiSessionForkInput): Promise<string>;
+}
+
+export interface ForkSourceSession {
+  getSessionFile(): string | undefined;
+  getLeafId(): string | null;
+  getBranch(fromId?: string): SessionEntry[];
+}
+
+export function describeCurrentPiSessionFork(source: ForkSourceSession): WorkerForkSource {
+  const sourceSessionFile = source.getSessionFile();
+  if (!sourceSessionFile || !isAbsolute(sourceSessionFile)) {
+    throw new Error("Fork context requires a persisted absolute parent Pi session file");
+  }
+  const branchPointId = source.getLeafId();
+  if (!branchPointId) throw new Error("Fork context requires a current parent session leaf");
+  const branch = source.getBranch(branchPointId);
+  if (branch.length === 0 || !branch.some((entry) => entry.id === branchPointId)) {
+    throw new Error("Fork context branch point is absent from the parent session");
+  }
+  return {
+    sourceSessionFile: normalize(sourceSessionFile),
+    branchPointId,
+    inheritedEntries: branch.length,
+    inheritedBytes: branch.reduce(
+      (total, entry) => total + Buffer.byteLength(`${JSON.stringify(entry)}\n`, "utf8"),
+      0,
+    ),
+  };
+}
+
+export class NodePiSessionForker implements PiSessionForker {
+  async fork(input: PiSessionForkInput): Promise<string> {
+    const sourceSessionFile = absolute(input.sourceSessionFile, "fork source session file");
+    const targetSessionFile = absolute(input.targetSessionFile, "fork target session file");
+    if (sourceSessionFile === targetSessionFile) {
+      throw new Error("Fork target session file must differ from its parent");
+    }
+    await assertAbsent(targetSessionFile);
+    await mkdir(dirname(targetSessionFile), { recursive: true, mode: 0o700 });
+    const sourceBefore = await readFile(sourceSessionFile);
+    const manager = SessionManager.open(sourceSessionFile, dirname(targetSessionFile));
+    if (!manager.getEntry(input.branchPointId)) {
+      throw new Error(`Fork branch point ${input.branchPointId} is absent from the parent session`);
+    }
+    let generated: string | undefined;
+    try {
+      generated = manager.createBranchedSession(input.branchPointId);
+      if (!generated) throw new Error("Pi session fork did not produce a persisted child session");
+      await access(generated);
+      await rename(generated, targetSessionFile);
+      generated = undefined;
+    } finally {
+      if (generated) await rm(generated, { force: true }).catch(() => {});
+    }
+    const child = SessionManager.open(targetSessionFile, dirname(targetSessionFile));
+    if (child.getHeader()?.parentSession !== sourceSessionFile) {
+      throw new Error("Fork child session does not record the expected parent session");
+    }
+    if (!child.getEntry(input.branchPointId)) {
+      throw new Error("Fork child session does not contain the requested branch point");
+    }
+    const sourceAfter = await readFile(sourceSessionFile);
+    if (!sourceAfter.equals(sourceBefore)) {
+      throw new Error("Forking mutated the parent Pi session file");
+    }
+    return targetSessionFile;
+  }
+}
+
+function absolute(value: string, label: string): string {
+  if (!isAbsolute(value)) throw new TypeError(`${label} must be absolute`);
+  return normalize(value);
+}
+
+async function assertAbsent(path: string): Promise<void> {
+  try {
+    await access(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  throw new Error(`Fork target session file already exists: ${path}`);
+}

package/workflow/run-artifacts.ts

@@ -0,0 +1,36 @@
+import { mkdir } from "node:fs/promises";
+import { isAbsolute, join, normalize } from "node:path";
+
+import { runDirectoryForRequest } from "./run-store.js";
+import type { WorkerRequest } from "./workflow-types.js";
+
+export function runArtifactDirectory(namespaceDirectory: string, requestKey: string): string {
+  return join(runDirectoryForRequest(namespaceDirectory, requestKey), "artifacts");
+}
+
+export async function ensureRunArtifactDirectory(
+  namespaceDirectory: string,
+  requestKey: string,
+): Promise<string> {
+  const directory = runArtifactDirectory(namespaceDirectory, requestKey);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  return directory;
+}
+
+export function withRunArtifactContext(
+  request: WorkerRequest,
+  artifactDirectory: string,
+): WorkerRequest {
+  if (!isAbsolute(artifactDirectory)) {
+    throw new TypeError("Run artifact directory must be absolute");
+  }
+  const canonical = normalize(artifactDirectory);
+  return {
+    ...request,
+    contextRefs: [
+      { kind: "artifact", value: canonical },
+      ...request.contextRefs.filter((reference) =>
+        reference.kind !== "artifact" || normalize(reference.value) !== canonical),
+    ],
+  };
+}