@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/workflows/src/intercom/intercom-bridge.ts

@@ -0,0 +1,93 @@
+/**
+ * pi-intercom cooperation: parent session naming + presence detection.
+ *
+ * Responsibilities:
+ *  1. Detect whether pi-intercom-like surfaces exist on the ExtensionAPI
+ *     (structural check — no hard import).
+ *  2. On session_start, register the parent session name as
+ *     `pi-workflows-parent-<short-cwd-hash>` so detached child processes
+ *     can `contact_supervisor` through the intercom channel.
+ *
+ * cross-ref: pi-subagents src/intercom/intercom-bridge.ts
+ * cross-ref: spec §5.10 Integration with pi-intercom, §8.1 Phase G
+ */
+
+import { createHash } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Minimal structural types — no hard imports from pi-intercom
+// ---------------------------------------------------------------------------
+
+/** Minimal ExtensionAPI surface expected by intercom integration. */
+export interface PiIntercomExtensionAPI {
+  /** Sets the session name that children can use as `contact_supervisor` target. */
+  setSessionName?: (name: string) => void;
+  /** Event subscription surface used by multiple integrations. */
+  events?: {
+    emit?: (event: string, payload: Record<string, unknown>) => void;
+    on?: (event: string, handler: (payload: unknown) => void) => void;
+  };
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Session name derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Derives a short (8-char) hex hash from the given string (typically cwd).
+ * Stable across restarts for the same directory, short enough for display.
+ */
+export function deriveCwdHash(cwd: string): string {
+  return createHash("sha256").update(cwd).digest("hex").slice(0, 8);
+}
+
+/**
+ * Returns the canonical parent session name for this workflow run.
+ * Format: `pi-workflows-parent-<8-char-hash>`
+ *
+ * Spec default: derive from cwd (§9 open question 7 → resolved as cwd hash).
+ */
+export function buildParentSessionName(cwd: string = process.cwd()): string {
+  return `pi-workflows-parent-${deriveCwdHash(cwd)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Presence detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when the pi runtime exposes an intercom-like `setSessionName`
+ * method. Purely structural — does not import pi-intercom.
+ */
+export function isIntercomPresent(pi: PiIntercomExtensionAPI): boolean {
+  return typeof pi.setSessionName === "function";
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Registers the workflow parent session name via `pi.setSessionName` so
+ * detached child processes can `contact_supervisor` back to this session.
+ *
+ * - No-op when `pi.setSessionName` is absent (pi-intercom not installed).
+ * - Called once during extension initialization (session_start equivalent).
+ *
+ * @param pi   The ExtensionAPI instance.
+ * @param cwd  Working directory used to derive a stable hash. Defaults to
+ *             `process.cwd()`.
+ * @returns    The session name that was set, or `null` if intercom absent.
+ */
+export function registerIntercomParentSession(
+  pi: PiIntercomExtensionAPI,
+  cwd: string = process.cwd(),
+): string | null {
+  if (!isIntercomPresent(pi)) return null;
+
+  const name = buildParentSessionName(cwd);
+  // Safe: isIntercomPresent guard above ensures setSessionName exists.
+  pi.setSessionName!(name);
+  return name;
+}

package/dist/builtin/workflows/src/intercom/intercom-routing.ts

@@ -0,0 +1,125 @@
+/**
+ * Intercom routing: builds IntercomControlCallbacks that wire store/ui/emit.
+ *
+ * `buildIntercomCallbacks` is the pure factory consumed by extension/index.ts.
+ * Keeping it separate makes unit testing trivial (no full pi surface needed).
+ *
+ * cross-ref: spec §5.10, RFC §8.1 Phase G
+ */
+
+import type { Store } from "../shared/store.js";
+import type { NoticeLevel } from "../shared/store-types.js";
+import type { IntercomControlCallbacks, IntercomControlPayload } from "./result-intercom.js";
+
+// ---------------------------------------------------------------------------
+// Dependency surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal deps injected by the extension factory.
+ * Separating them makes the logic independently testable.
+ */
+export interface IntercomRoutingDeps {
+  /** Workflow store — for recordNotice / ackNotice. */
+  store: Store;
+  /**
+   * Raw pi events emit — used to fire `subagent:control-intercom:response`.
+   * `undefined` when pi.events.emit is not available.
+   */
+  emit: ((event: string, payload: Record<string, unknown>) => void) | undefined;
+  /**
+   * Pi confirm dialog with separate title + message args.
+   * `undefined` when pi.ui.confirm is absent.
+   */
+  confirm: ((title: string, message: string) => Promise<boolean>) | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function toNoticeLevel(raw: unknown): NoticeLevel {
+  if (raw === "warning" || raw === "error") return raw;
+  return "info";
+}
+
+function makeId(): string {
+  // crypto.randomUUID() is available globally in Bun and Node ≥ 16.
+  return crypto.randomUUID();
+}
+
+// ---------------------------------------------------------------------------
+// Callback builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds `IntercomControlCallbacks` wired to the given deps.
+ *
+ * - `need_decision`:
+ *     1. Record a notice with `requiresAck: true` (level: "warning").
+ *     2. Surface `pi.ui.confirm("Subagent needs decision", payload.message)`.
+ *     3. Emit `subagent:control-intercom:response` with
+ *        `{ requestId, runId, stageId, accepted }`.
+ *     4. Ack the notice.
+ *
+ * - `notify`:
+ *     Record a notice at `payload.level` (info/warning/error, defaults to info).
+ *
+ * - unknown / malformed:
+ *     Record a warning notice. No ack, no emit.
+ */
+export function buildIntercomCallbacks(deps: IntercomRoutingDeps): IntercomControlCallbacks {
+  const { store, emit, confirm } = deps;
+
+  return {
+    async onNeedDecision(payload: IntercomControlPayload): Promise<void> {
+      const noticeId = makeId();
+
+      store.recordNotice({
+        id: noticeId,
+        runId: payload.runId,
+        stageId: payload.stageId,
+        level: "warning",
+        message: payload.message,
+        createdAt: Date.now(),
+        requiresAck: true,
+      });
+
+      const accepted: boolean =
+        typeof confirm === "function"
+          ? await confirm("Subagent needs decision", payload.message).catch(() => false)
+          : false;
+
+      emit?.("subagent:control-intercom:response", {
+        requestId: payload.requestId ?? "",
+        runId: payload.runId ?? "",
+        stageId: payload.stageId ?? "",
+        accepted,
+      });
+
+      store.ackNotice(noticeId);
+    },
+
+    onNotify(payload: IntercomControlPayload): void {
+      store.recordNotice({
+        id: makeId(),
+        runId: payload.runId,
+        stageId: payload.stageId,
+        level: toNoticeLevel(payload.level),
+        message: payload.message,
+        createdAt: Date.now(),
+      });
+    },
+
+    onUnknown(payload: IntercomControlPayload): void {
+      store.recordNotice({
+        id: makeId(),
+        runId: payload.runId,
+        stageId: payload.stageId,
+        level: "warning",
+        message: `Unknown intercom type "${payload.type}": ${payload.message}`,
+        createdAt: Date.now(),
+      });
+    },
+  };
+}

package/dist/builtin/workflows/src/intercom/result-intercom.ts

@@ -0,0 +1,240 @@
+/**
+ * pi-intercom result routing: subagent:control-intercom → UI/store callbacks.
+ *
+ * Responsibilities:
+ *  Subscribes to `pi.events.on("subagent:control-intercom", ...)` (the channel
+ *  pi-subagents uses when a child calls `contact_supervisor`).  When a child
+ *  sub-agent of a workflow stage escalates, this module routes the event to
+ *  the appropriate callback:
+ *    - `onNeedDecision` → surfaces a blocking confirm dialog (ctx.ui.confirm)
+ *    - `onNotify`       → surfaces a non-blocking notice in the workflow overlay
+ *
+ * No-op when the events bus or subscription method is absent.
+ *
+ * cross-ref: pi-subagents src/intercom/result-intercom.ts
+ * cross-ref: spec §5.10 Integration with pi-intercom, §8.1 Phase G
+ */
+
+import type { WorkflowDetails } from "../shared/types.js";
+
+// ---------------------------------------------------------------------------
+// Minimal structural types
+// ---------------------------------------------------------------------------
+
+/** Minimal pi events bus surface used by this module. */
+export interface PiEventBus {
+  on?: (event: string, handler: (payload: unknown) => void) => void | (() => void);
+  emit?: (event: string, payload: Record<string, unknown>) => void;
+}
+
+/** Minimal ExtensionAPI surface expected by result-intercom module. */
+export interface PiResultIntercomExtensionAPI {
+  events?: PiEventBus;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Intercom control event payload
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of the `subagent:control-intercom` event payload emitted by
+ * pi-subagents when a child calls `contact_supervisor`.
+ *
+ * Both `type` and `message` are required. Additional fields are forwarded
+ * opaquely to callbacks.
+ */
+export interface IntercomControlPayload {
+  /** Escalation kind: a blocking decision request or an informational notice. */
+  type: "need_decision" | "notify" | string;
+  /** Human-readable message from the child agent. */
+  message: string;
+  /** Originating run/stage context if the child is inside a workflow. */
+  runId?: string;
+  stageId?: string;
+  /** The child agent's identifier (pi-subagents populates this). */
+  agentId?: string;
+  /** Arbitrary extra fields forwarded from pi-subagents. */
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Callback types
+// ---------------------------------------------------------------------------
+
+/**
+ * Called when the child requests a blocking decision from the user.
+ * Implementors should display `ctx.ui.confirm`-style UI.
+ */
+export type OnNeedDecision = (payload: IntercomControlPayload) => void | Promise<void>;
+
+/**
+ * Called for non-blocking notifications (e.g. status updates from the child).
+ * Implementors should surface these in the workflow overlay.
+ */
+export type OnNotify = (payload: IntercomControlPayload) => void | Promise<void>;
+
+/** Callback bag passed to `subscribeIntercomControl`. */
+export interface IntercomControlCallbacks {
+  onNeedDecision?: OnNeedDecision;
+  onNotify?: OnNotify;
+  /**
+   * Fallback called for unknown `type` values — useful for forward
+   * compatibility as pi-subagents adds new escalation kinds.
+   */
+  onUnknown?: (payload: IntercomControlPayload) => void | Promise<void>;
+}
+
+export type WorkflowIntercomDelivery = "off" | "notify" | "result" | "control-and-result";
+
+export interface WorkflowResultIntercomPort {
+  emit?: (event: string, payload: Record<string, unknown>) => void;
+  parentSession?: string | (() => string | undefined);
+}
+
+export interface WorkflowIntercomEventOptions {
+  readonly delivery: Exclude<WorkflowIntercomDelivery, "off">;
+  readonly parentSession?: string;
+}
+
+export interface WorkflowControlIntercomPayload {
+  readonly type: "notify" | "needs_attention";
+  readonly runId: string;
+  readonly mode: WorkflowDetails["mode"];
+  readonly status: WorkflowDetails["status"];
+  readonly message: string;
+  readonly parentSession?: string;
+  readonly createdAt: number;
+}
+
+export interface WorkflowResultIntercomPayload {
+  readonly runId: string;
+  readonly mode: WorkflowDetails["mode"];
+  readonly status: WorkflowDetails["status"];
+  readonly details: WorkflowDetails;
+  readonly parentSession?: string;
+  readonly createdAt: number;
+}
+
+function parentSessionFromPort(port: WorkflowResultIntercomPort, override?: string): string | undefined {
+  if (override !== undefined) return override;
+  if (typeof port.parentSession === "function") return port.parentSession();
+  return port.parentSession;
+}
+
+function shouldEmitControl(delivery: WorkflowIntercomDelivery): boolean {
+  return delivery === "notify" || delivery === "control-and-result";
+}
+
+function shouldEmitResult(delivery: WorkflowIntercomDelivery): boolean {
+  return delivery === "result" || delivery === "control-and-result";
+}
+
+export function workflowIntercomAvailable(port: WorkflowResultIntercomPort | undefined): boolean {
+  return typeof port?.emit === "function";
+}
+
+export function emitWorkflowControlIntercom(
+  port: WorkflowResultIntercomPort | undefined,
+  details: WorkflowDetails,
+  message: string,
+  options: WorkflowIntercomEventOptions,
+): boolean {
+  if (!workflowIntercomAvailable(port) || !shouldEmitControl(options.delivery) || details.runId === undefined) {
+    return false;
+  }
+  const parentSession = parentSessionFromPort(port!, options.parentSession);
+  const payload: WorkflowControlIntercomPayload = {
+    type: "notify",
+    runId: details.runId,
+    mode: details.mode,
+    status: details.status,
+    message,
+    ...(parentSession !== undefined ? { parentSession } : {}),
+    createdAt: Date.now(),
+  };
+  port!.emit!("workflow:control-intercom", payload as unknown as Record<string, unknown>);
+  return true;
+}
+
+export function emitWorkflowResultIntercom(
+  port: WorkflowResultIntercomPort | undefined,
+  details: WorkflowDetails,
+  options: WorkflowIntercomEventOptions,
+): boolean {
+  if (!workflowIntercomAvailable(port) || !shouldEmitResult(options.delivery) || details.runId === undefined) {
+    return false;
+  }
+  const parentSession = parentSessionFromPort(port!, options.parentSession);
+  const payload: WorkflowResultIntercomPayload = {
+    runId: details.runId,
+    mode: details.mode,
+    status: details.status,
+    details,
+    ...(parentSession !== undefined ? { parentSession } : {}),
+    createdAt: Date.now(),
+  };
+  port!.emit!("workflow:result-intercom", payload as unknown as Record<string, unknown>);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Subscription
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribes to `subagent:control-intercom` events on `pi.events` and routes
+ * each incoming payload to the appropriate callback.
+ *
+ * - No-op when `pi.events?.on` is absent (events bus not supported).
+ * - Each individual callback error is caught and re-thrown asynchronously so
+ *   one bad callback cannot prevent others from running.
+ *
+ * @returns A cleanup / unsubscribe function. Call it to stop routing.
+ *          Returns `null` when the subscription could not be established.
+ */
+export function subscribeIntercomControl(
+  pi: PiResultIntercomExtensionAPI,
+  callbacks: IntercomControlCallbacks,
+): (() => void) | null {
+  if (typeof pi.events?.on !== "function") return null;
+
+  let active = true;
+
+  const handler = (rawPayload: unknown): void => {
+    if (!active) return;
+
+    // Coerce to typed payload — we trust pi-subagents' contract but guard
+    // defensively against malformed emissions.
+    const payload = rawPayload as IntercomControlPayload;
+
+    if (!payload || typeof payload !== "object" || typeof payload.type !== "string") return;
+
+    const dispatch = (): Promise<void> => {
+      switch (payload.type) {
+        case "need_decision":
+          return Promise.resolve(callbacks.onNeedDecision?.(payload));
+        case "notify":
+          return Promise.resolve(callbacks.onNotify?.(payload));
+        default:
+          return Promise.resolve(callbacks.onUnknown?.(payload));
+      }
+    };
+
+    dispatch().catch((err) => {
+      // Surface errors without breaking the event loop.
+      Promise.reject(
+        new Error(
+          `pi-workflows intercom callback error (type=${payload.type}): ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      );
+    });
+  };
+
+  const unsubscribe = pi.events!.on!("subagent:control-intercom", handler);
+
+  return () => {
+    active = false;
+    if (typeof unsubscribe === "function") unsubscribe();
+  };
+}

package/dist/builtin/workflows/src/runs/background/cancellation-registry.ts

@@ -0,0 +1,113 @@
+/**
+ * CancellationRegistry — tracks active run AbortControllers and children.
+ *
+ * Responsibilities:
+ *   - register(runId, controller)        — attach primary controller for a run
+ *   - registerChild(runId, controller)   — attach a subordinate controller
+ *   - abort(runId, reason)               — abort primary + all children, returns true if found
+ *   - abortAll(reason)                   — abort every registered run, returns count aborted
+ *   - unregister(runId)                  — remove run from registry (after run ends)
+ *   - isAborted(runId)                   — true if run's primary controller was aborted
+ *
+ * Does NOT kill processes; only signals abort to registered controllers.
+ * cross-ref: spec §8.1 Phase D (kill-runtime-wiring downstream)
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ActiveRunEntry {
+  readonly controller: AbortController;
+  readonly children: AbortController[];
+}
+
+export interface CancellationRegistry {
+  register(runId: string, controller: AbortController): void;
+  registerChild(runId: string, controller: AbortController): void;
+  abort(runId: string, reason?: unknown): boolean;
+  abortAll(reason?: unknown): number;
+  unregister(runId: string): void;
+  isAborted(runId: string): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+class CancellationRegistryImpl implements CancellationRegistry {
+  private readonly _runs = new Map<string, ActiveRunEntry>();
+
+  register(runId: string, controller: AbortController): void {
+    // If already registered, replace (unregister old entry first without aborting)
+    const existing = this._runs.get(runId);
+    if (existing) {
+      // Preserve children when re-registering same runId
+      this._runs.set(runId, { controller, children: existing.children });
+    } else {
+      this._runs.set(runId, { controller, children: [] });
+    }
+  }
+
+  registerChild(runId: string, controller: AbortController): void {
+    const entry = this._runs.get(runId);
+    if (!entry) {
+      // No primary controller yet — create a placeholder entry with no primary
+      // so children can still be tracked. Callers should call register() first.
+      // Strict: throw to surface misuse.
+      throw new Error(`CancellationRegistry: cannot registerChild for unknown runId "${runId}". Call register() first.`);
+    }
+    entry.children.push(controller);
+  }
+
+  abort(runId: string, reason?: unknown): boolean {
+    const entry = this._runs.get(runId);
+    if (!entry) return false;
+
+    // Abort children first, then primary
+    for (const child of entry.children) {
+      if (!child.signal.aborted) {
+        child.abort(reason);
+      }
+    }
+    if (!entry.controller.signal.aborted) {
+      entry.controller.abort(reason);
+    }
+    return true;
+  }
+
+  abortAll(reason?: unknown): number {
+    let count = 0;
+    for (const runId of this._runs.keys()) {
+      if (this.abort(runId, reason)) count++;
+    }
+    return count;
+  }
+
+  unregister(runId: string): void {
+    this._runs.delete(runId);
+  }
+
+  isAborted(runId: string): boolean {
+    const entry = this._runs.get(runId);
+    if (!entry) return false;
+    return entry.controller.signal.aborted;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory + singleton
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an isolated CancellationRegistry instance (useful for testing).
+ */
+export function createCancellationRegistry(): CancellationRegistry {
+  return new CancellationRegistryImpl();
+}
+
+/**
+ * Singleton registry for the default runtime. Consumers needing isolation
+ * should call createCancellationRegistry() instead.
+ */
+export const cancellationRegistry: CancellationRegistry = createCancellationRegistry();

package/dist/builtin/workflows/src/runs/background/job-tracker.ts

@@ -0,0 +1,81 @@
+/**
+ * JobTracker — in-memory registry of live background run promises and
+ * their AbortControllers.
+ *
+ * Source of truth for run snapshots/status remains the store.
+ * JobTracker only holds the live Promise and AbortController so callers
+ * can await completion or cancel without going through the store.
+ *
+ * cross-ref: spec detached-runner §job-tracker
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface JobEntry {
+  readonly runId: string;
+  readonly controller: AbortController;
+  /** Settles when the background run resolves or rejects. */
+  readonly promise: Promise<void>;
+}
+
+export interface JobTracker {
+  /**
+   * Register a background job. `promise` must be the background run promise
+   * (already void-cast; all rejections must be handled before registering).
+   */
+  register(entry: JobEntry): void;
+  /** Remove a job from the tracker (called on settle). */
+  unregister(runId: string): void;
+  /** True if a live job exists for this runId. */
+  has(runId: string): boolean;
+  /** Return entry or undefined. */
+  get(runId: string): JobEntry | undefined;
+  /** All currently tracked runIds. */
+  runIds(): string[];
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+class JobTrackerImpl implements JobTracker {
+  private readonly _jobs = new Map<string, JobEntry>();
+
+  register(entry: JobEntry): void {
+    this._jobs.set(entry.runId, entry);
+  }
+
+  unregister(runId: string): void {
+    this._jobs.delete(runId);
+  }
+
+  has(runId: string): boolean {
+    return this._jobs.has(runId);
+  }
+
+  get(runId: string): JobEntry | undefined {
+    return this._jobs.get(runId);
+  }
+
+  runIds(): string[] {
+    return Array.from(this._jobs.keys());
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory + singleton
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an isolated JobTracker instance (useful for testing).
+ */
+export function createJobTracker(): JobTracker {
+  return new JobTrackerImpl();
+}
+
+/**
+ * Singleton tracker for the default runtime.
+ */
+export const jobTracker: JobTracker = createJobTracker();