pi-famulus 0.1.0

package/src/comms/comms.ts

@@ -0,0 +1,199 @@
+/**
+ * createComms (design doc §4.7): parent↔child messaging on top of a CommsHost.
+ *
+ * Supervisor notifications are self-contained here (wiring matrix: comms owns
+ * its XML formats; nothing is added to src/format.ts).
+ */
+import {
+  DECISION_TIMEOUT_MESSAGE,
+  Mailbox,
+  type MailboxOptions,
+} from "./mailbox";
+import type { Comms, CommsHost } from "./types";
+import { formatFamulusWake, type FormattedWake } from "../wake";
+import type { Clock } from "../clock";
+
+/** Ring bucket used when the host does not know the child (defensive fallback). */
+export const UNKNOWN_RUN_ID = "unknown";
+
+/** Fire-and-forget progress notification shown to the parent agent. */
+export function formatSupervisorUpdate(
+  from: { childId: string; name: string },
+  message: string,
+): FormattedWake {
+  return formatFamulusWake({
+    kind: "supervisor-update",
+    from: from.childId,
+    name: from.name,
+    message,
+  });
+}
+
+/** Blocking decision request; the reply recipe is a <reply-with> child, not message text. */
+export function formatSupervisorRequest(
+  from: { childId: string; name: string },
+  message: string,
+): FormattedWake {
+  return formatFamulusWake({
+    kind: "supervisor-request",
+    from: from.childId,
+    name: from.name,
+    message,
+  });
+}
+
+/**
+ * Appendix B `createComms(host)`. The returned object is a `Comms`; the
+ * widened `CommsWithOrigin` return type additionally lets callers attribute
+ * `send`/`reply` mailbox entries to a child origin (used by the agent_message
+ * tool for child senders). Structurally assignable to `Comms`.
+ */
+export interface CommsWithOrigin extends Comms {
+  reply(toChildId: string, message: string, from?: string): void;
+  send(
+    toChildId: string,
+    message: string,
+    delivery: "steer" | "queue",
+    from?: string,
+  ): Promise<void>;
+  /** Cancel pending decision waiters and timers (session shutdown). */
+  dispose(): void;
+}
+
+export interface CommsOptions {
+  /** Pre-built mailbox (tests); otherwise one is created from the options below. */
+  mailbox?: Mailbox;
+  decisionTimeoutMs?: MailboxOptions["decisionTimeoutMs"];
+  clock?: Clock;
+  logEvent?: (type: string, fields?: Record<string, unknown>) => void;
+}
+
+export function createComms(host: CommsHost, options: CommsOptions = {}): CommsWithOrigin {
+  const mailbox =
+    options.mailbox ??
+    new Mailbox({ decisionTimeoutMs: options.decisionTimeoutMs, clock: options.clock });
+
+  function runIdOf(childId: string): string {
+    return host.getChild(childId)?.runId ?? UNKNOWN_RUN_ID;
+  }
+
+  return {
+    async contactSupervisor(fromChildId, reason, message) {
+      const child = host.getChild(fromChildId);
+      const runId = child?.runId ?? UNKNOWN_RUN_ID;
+      const name = child?.name ?? fromChildId;
+      const entry = mailbox.append(runId, {
+        from: fromChildId,
+        to: "supervisor",
+        kind: reason,
+        message,
+      });
+
+      if (reason === "progress_update") {
+        host.notifySupervisor(formatSupervisorUpdate({ childId: fromChildId, name }, message));
+        return "ok";
+      }
+
+      // need_decision: register the per-child waiter BEFORE notifying, so a
+      // supervisor that replies synchronously still resolves correctly.
+      const wait = mailbox.beginDecision(fromChildId, name, message);
+      options.logEvent?.("decision.request", { child_id: fromChildId });
+      const stall = child?.handle as { pauseStall?: () => void; resumeStall?: () => void } | undefined;
+      stall?.pauseStall?.();
+      host.notifySupervisor(formatSupervisorRequest({ childId: fromChildId, name }, message));
+      try {
+        const replyText = await wait;
+        if (replyText === DECISION_TIMEOUT_MESSAGE) {
+          options.logEvent?.("decision.timeout", { child_id: fromChildId });
+        }
+        entry.reply = replyText;
+        return replyText;
+      } finally {
+        stall?.resumeStall?.();
+      }
+    },
+
+    reply(toChildId, message, from = "supervisor") {
+      if (!mailbox.resolveDecision(toChildId, message)) {
+        const pending = mailbox.pendingRequests();
+        const listing =
+          pending.length === 0
+            ? "none"
+            : pending.map((p) => `${p.childId} (${p.name})`).join(", ");
+        throw new Error(
+          `No pending decision request from ${toChildId}. Pending requests: ${listing}.`,
+        );
+      }
+      mailbox.append(runIdOf(toChildId), { from, to: toChildId, kind: "reply", message });
+      options.logEvent?.("decision.reply", { child_id: toChildId });
+    },
+
+    async send(toChildId, message, delivery, from = "supervisor") {
+      const child = host.getChild(toChildId);
+      if (!child) {
+        const known =
+          host.listChildren().map((c) => `${c.childId} (${c.name})`).join(", ") || "none";
+        throw new Error(`Unknown child "${toChildId}". Known children: ${known}.`);
+      }
+      if (child.status === "running") {
+        if (delivery === "steer") {
+          await child.handle.steer(message);
+        } else {
+          await child.handle.followUp(message);
+        }
+      } else if (
+        child.status === "completed" ||
+        child.status === "failed" ||
+        child.status === "interrupted"
+      ) {
+        // Lifecycle (resume) belongs to the subagent tool. Resuming here never
+        // wired a completion wake, so the parent hung.
+        throw new Error(
+          `Child ${toChildId} (${child.name}) has finished (${child.status}). ` +
+            `agent_message does not resume children. ` +
+            `Use subagent({ action: "resume", run_id: "${child.runId}", child_id: "${toChildId}", message: "..." }).`,
+        );
+      } else {
+        throw new Error(
+          `Child ${toChildId} (${child.name}) is ${child.status}; ` +
+            "messages can only be delivered to running or finished children.",
+        );
+      }
+      mailbox.append(child.runId, { from, to: toChildId, kind: "send", message });
+    },
+
+    async broadcast(runId, message, fromChildId) {
+      const from = fromChildId ?? "supervisor";
+      const targets = host
+        .listChildren()
+        .filter(
+          (c) => c.runId === runId && c.status === "running" && c.childId !== fromChildId,
+        );
+      const delivered: string[] = [];
+      for (const target of targets) {
+        const child = host.getChild(target.childId);
+        if (!child) continue;
+        try {
+          await child.handle.steer(message);
+        } catch {
+          continue; // best-effort: only successfully steered children are reported
+        }
+        delivered.push(target.childId);
+        mailbox.append(runId, { from, to: target.childId, kind: "broadcast", message });
+      }
+      return delivered;
+    },
+
+    pendingRequests() {
+      return mailbox.pendingRequests();
+    },
+
+    log(runId, limit) {
+      return mailbox.log(runId, limit);
+    },
+
+    dispose() {
+      mailbox.dispose();
+    },
+  };
+}

package/src/comms/mailbox.ts

@@ -0,0 +1,156 @@
+/**
+ * Mailbox (design doc §4.7): per-run ring log of all comms traffic plus
+ * per-child `need_decision` waiters.
+ *
+ * Anti-global-lock (pi-intercom lesson): every child gets its own waiter
+ * entry with its own promise and its own timeout timer — children never
+ * queue behind each other.
+ */
+import { realClock, type Clock, type ClockTimer } from "../clock";
+import type { MailboxEntry } from "./types";
+
+export const DEFAULT_MAILBOX_CAPACITY = 200;
+export const DEFAULT_LOG_LIMIT = 20;
+export const DEFAULT_DECISION_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
+
+/** Exact contract text (§4.7) returned to a child whose decision request times out. */
+export const DECISION_TIMEOUT_MESSAGE =
+  "Supervisor did not respond within 10 minutes; decide yourself and continue.";
+
+export interface PendingDecisionRequest {
+  childId: string;
+  name: string;
+  message: string;
+  sinceMs: number;
+}
+
+interface Waiter {
+  name: string;
+  message: string;
+  sinceMs: number;
+  resolve: (reply: string) => void;
+  timer: ClockTimer;
+}
+
+export interface MailboxOptions {
+  /** Ring capacity per run. Default 200. */
+  capacity?: number;
+  /** need_decision timeout. Default 600_000 (10 min). */
+  decisionTimeoutMs?: number;
+  clock?: Clock;
+}
+
+export class Mailbox {
+  private readonly capacity: number;
+  private readonly decisionTimeoutMs: number;
+  private readonly clock: Clock;
+  private readonly rings = new Map<string, MailboxEntry[]>();
+  private readonly waiters = new Map<string, Waiter>();
+
+  constructor(options: MailboxOptions = {}) {
+    this.capacity = options.capacity ?? DEFAULT_MAILBOX_CAPACITY;
+    this.decisionTimeoutMs = options.decisionTimeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
+    this.clock = options.clock ?? realClock;
+  }
+
+  /**
+   * Append an entry to a run's ring (oldest entries dropped past capacity).
+   * Returns the stored entry; callers may later set `entry.reply` — the ring
+   * holds the same object reference.
+   */
+  append(runId: string, entry: Omit<MailboxEntry, "ts"> & { ts?: number }): MailboxEntry {
+    const full: MailboxEntry = {
+      ts: entry.ts ?? this.clock.now(),
+      from: entry.from,
+      to: entry.to,
+      kind: entry.kind,
+      message: entry.message,
+    };
+    if (entry.reply !== undefined) full.reply = entry.reply;
+    let ring = this.rings.get(runId);
+    if (!ring) {
+      ring = [];
+      this.rings.set(runId, ring);
+    }
+    ring.push(full);
+    if (ring.length > this.capacity) {
+      ring.splice(0, ring.length - this.capacity);
+    }
+    return full;
+  }
+
+  /** Last `limit` entries of a run, chronological order. Default 20. */
+  log(runId: string, limit: number = DEFAULT_LOG_LIMIT): MailboxEntry[] {
+    const ring = this.rings.get(runId) ?? [];
+    if (limit <= 0) return [];
+    return ring.slice(Math.max(0, ring.length - limit));
+  }
+
+  hasPendingDecision(childId: string): boolean {
+    return this.waiters.has(childId);
+  }
+
+  /**
+   * Register this child's need_decision waiter and return the promise that
+   * resolves with the supervisor's reply (or DECISION_TIMEOUT_MESSAGE after
+   * the timeout). Independent per child — no global lock.
+   *
+   * Throws if the child already has a pending request (one at a time).
+   */
+  beginDecision(childId: string, name: string, message: string): Promise<string> {
+    if (this.waiters.has(childId)) {
+      throw new Error(
+        `Child ${childId} already has a pending decision request; ` +
+          "wait for the supervisor's reply before asking again.",
+      );
+    }
+    let resolveFn!: (reply: string) => void;
+    const promise = new Promise<string>((res) => {
+      resolveFn = res;
+    });
+    const timer = this.clock.setTimeout(() => {
+      if (this.waiters.delete(childId)) {
+        resolveFn(DECISION_TIMEOUT_MESSAGE);
+      }
+    }, this.decisionTimeoutMs);
+    this.waiters.set(childId, {
+      name,
+      message,
+      sinceMs: this.clock.now(),
+      resolve: resolveFn,
+      timer,
+    });
+    return promise;
+  }
+
+  /**
+   * Resolve a pending need_decision waiter with the supervisor's reply.
+   * Returns false when the child has no pending request.
+   */
+  resolveDecision(childId: string, reply: string): boolean {
+    const waiter = this.waiters.get(childId);
+    if (!waiter) return false;
+    this.waiters.delete(childId);
+    this.clock.clearTimeout(waiter.timer);
+    waiter.resolve(reply);
+    return true;
+  }
+
+  pendingRequests(): PendingDecisionRequest[] {
+    return [...this.waiters.entries()].map(([childId, w]) => ({
+      childId,
+      name: w.name,
+      message: w.message,
+      sinceMs: w.sinceMs,
+    }));
+  }
+
+  /** Cancel all timers; outstanding waiters resolve with the timeout message. */
+  dispose(): void {
+    for (const waiter of this.waiters.values()) {
+      this.clock.clearTimeout(waiter.timer);
+      waiter.resolve(DECISION_TIMEOUT_MESSAGE);
+    }
+    this.waiters.clear();
+  }
+}

package/src/comms/registry-host.ts

@@ -0,0 +1,73 @@
+/**
+ * CommsHost adapter over the subagent RunRegistry (integration wiring, §4.7).
+ *
+ * Lives in comms/ so the M4 module stays self-contained; the registry is
+ * accessed structurally (RunRegistry query surface from appendix B) plus the
+ * concrete SubagentRegistry.handle() lookup.
+ */
+import type { SubagentRegistry } from "../subagent/registry";
+import { FAMULUS_WAKE_CUSTOM_TYPE } from "../wake";
+
+import type { CommsHost } from "./types";
+
+export interface RegistryHostDeps {
+  getRegistry: () => SubagentRegistry | null;
+  /** NotifyCenter-compatible sink for supervisor-bound notifications. */
+  getNotifyCenter: () => {
+    notify(msg: { customType: string; content: string; details?: unknown }): void;
+  } | null;
+}
+
+
+export function createRegistryCommsHost(deps: RegistryHostDeps): CommsHost {
+  const locate = (childId: string) => {
+    const registry = deps.getRegistry();
+    if (!registry) return undefined;
+    for (const run of registry.list()) {
+      const child = run.children.find((c) => c.childId === childId || c.name === childId);
+      if (child) return { run, child };
+    }
+    return undefined;
+  };
+
+  return {
+    getChild(childId) {
+      const found = locate(childId);
+      const handle = deps.getRegistry()?.handle(found?.child.childId ?? childId);
+      if (!found || !handle) return undefined;
+      return {
+        handle,
+        runId: found.run.runId,
+        name: found.child.name,
+        status: found.child.status,
+      };
+    },
+
+    listChildren() {
+      const registry = deps.getRegistry();
+      if (!registry) return [];
+      return registry.list().flatMap((run) =>
+        run.children.map((c) => ({
+          childId: c.childId,
+          runId: run.runId,
+          name: c.name,
+          status: c.status,
+        })),
+      );
+    },
+
+    sameRun(childIdA, childIdB) {
+      const a = locate(childIdA);
+      const b = locate(childIdB);
+      return a !== undefined && b !== undefined && a.run.runId === b.run.runId;
+    },
+
+    notifySupervisor(wake) {
+      deps.getNotifyCenter()?.notify({
+        customType: FAMULUS_WAKE_CUSTOM_TYPE,
+        content: wake.content,
+        details: wake.details,
+      });
+    },
+  };
+}

package/src/comms/reply-command.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Comms } from "./types";
+
+export type ReplyCommandResolution =
+  | { childId: string; message: string }
+  | { error: string };
+
+export function resolveReplyCommand(
+  args: string,
+  pending: ReturnType<Comms["pendingRequests"]>,
+): ReplyCommandResolution {
+  const input = args.trim();
+  if (pending.length === 0) return { error: "No pending supervisor decisions." };
+  if (!input) {
+    return {
+      error: `Pending decisions: ${pending.map((item) => `${item.childId} (${item.name})`).join(", ")}`,
+    };
+  }
+
+  const [target, ...rest] = input.split(/\s+/);
+  const matched = pending.filter((item) => item.childId === target || item.name === target);
+  if (matched.length === 1) {
+    const message = rest.join(" ").trim();
+    return message
+      ? { childId: matched[0].childId, message }
+      : { error: `Usage: /reply ${target} <decision>` };
+  }
+  if (matched.length > 1) return { error: `Ambiguous pending decision "${target}"; use a child id.` };
+  if (pending.length === 1) return { childId: pending[0].childId, message: input };
+  return {
+    error: `Specify a pending child id or name. Pending: ${pending.map((item) => `${item.childId} (${item.name})`).join(", ")}`,
+  };
+}
+
+export function registerReplyCommand(pi: ExtensionAPI, comms: Comms): void {
+  pi.registerCommand("reply", {
+    description: "Reply to a pending subagent decision (/reply <child-id> <decision>)",
+    handler: async (args, ctx: ExtensionContext) => {
+      const resolved = resolveReplyCommand(args, comms.pendingRequests());
+      if ("error" in resolved) {
+        ctx.ui.notify(resolved.error, "info");
+        return;
+      }
+      try {
+        comms.reply(resolved.childId, resolved.message);
+        ctx.ui.notify(`Replied to ${resolved.childId}.`, "info");
+      } catch (err) {
+        ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      }
+    },
+  });
+}

package/src/comms/routing.ts

@@ -0,0 +1,23 @@
+/**
+ * Lineage checks (design doc §4.7): sibling messaging is only allowed inside
+ * the same run. Pure functions over the CommsHost interface.
+ */
+import type { CommsHost } from "./types";
+
+/**
+ * Assert that child `fromChildId` may message child `toChildId`.
+ * Throws Error("cross-run messaging not allowed") when the two children belong
+ * to different runs (v1 lineage = same runId), and a clear error for self-send.
+ */
+export function assertSiblingAllowed(
+  host: CommsHost,
+  fromChildId: string,
+  toChildId: string,
+): void {
+  if (fromChildId === toChildId) {
+    throw new Error(`Child ${fromChildId} cannot send a message to itself.`);
+  }
+  if (!host.sameRun(fromChildId, toChildId)) {
+    throw new Error("cross-run messaging not allowed");
+  }
+}