pi-famulus 0.1.0

package/src/wake.ts

@@ -0,0 +1,219 @@
+/**
+ * Unified wake envelope (design doc §4.5).
+ *
+ * One customType, one lead-in, one <pi-famulus-wake> element. details.kind is the
+ * discriminator the renderer and the eval adapter both read.
+ */
+
+export const FAMULUS_WAKE_CUSTOM_TYPE = "pi-famulus-wake";
+
+export const FAMULUS_WAKE_LEAD_IN =
+  "System wake — not a new user message. Handle this <pi-famulus-wake> before other work.";
+
+export interface WakeItem {
+  id: string;
+  title: string;
+}
+
+export interface TaskWake {
+  id: string;
+  taskKind: string;
+  status: "completed" | "failed" | "killed" | "orphaned";
+  summary: string;
+  command: string;
+  outputPath: string;
+  preview: string;
+  durationMs: number;
+  exitCode: number | null;
+  /** Signal name ("SIGTERM" | "SIGKILL"). Omitted when the exit had no signal. */
+  signal?: string;
+}
+
+export interface SubagentDoneChild {
+  childId: string;
+  name: string;
+  status: "pending" | "running" | "completed" | "failed" | "interrupted";
+  prompt: string;
+  result: string;
+  error?: string;
+}
+
+export type FamulusWake =
+  | { kind: "task"; stillRunning: WakeItem[]; tasks: TaskWake[] }
+  | {
+      kind: "monitor";
+      id: string;
+      description: string;
+      status?: string;
+      event: string;
+      eventCount?: number;
+      droppedLines?: number;
+    }
+  | {
+      kind: "subagent-handover";
+      runId: string;
+      childId: string;
+      name: string;
+      status: "completed" | "failed" | "interrupted";
+      stillRunning: WakeItem[];
+      summary: string;
+      prompt: string;
+      result: string;
+      error?: string;
+    }
+  | {
+      kind: "subagent-done";
+      runId: string;
+      status: "completed" | "partial" | "failed" | "interrupted";
+      durationMs: number;
+      summary: string;
+      children: SubagentDoneChild[];
+    }
+  | { kind: "supervisor-request"; from: string; name: string; message: string }
+  | { kind: "supervisor-update"; from: string; name: string; message: string };
+
+export interface FormattedWake {
+  customType: typeof FAMULUS_WAKE_CUSTOM_TYPE;
+  content: string;
+  details: FamulusWake;
+}
+
+export function escapeXml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export function escapeXmlAttr(text: string): string {
+  return escapeXml(text).replace(/"/g, "&quot;");
+}
+
+/** Shell still-running title: one line, capped at 80 characters. */
+export function shellWakeTitle(command: string): string {
+  const one = command.replace(/\s+/g, " ").trim();
+  if (one.length <= 80) return one;
+  return `${one.slice(0, 79)}…`;
+}
+
+export function formatFamulusWake(details: FamulusWake, leadIn: string = FAMULUS_WAKE_LEAD_IN): FormattedWake {
+  const xml = renderWake(details);
+  const content = leadIn ? `${leadIn}\n\n${xml}` : xml;
+  return { customType: FAMULUS_WAKE_CUSTOM_TYPE, content, details };
+}
+
+function renderWake(details: FamulusWake): string {
+  switch (details.kind) {
+    case "task":
+      return renderTask(details);
+    case "monitor":
+      return renderMonitor(details);
+    case "subagent-handover":
+      return renderHandover(details);
+    case "subagent-done":
+      return renderDone(details);
+    case "supervisor-request":
+      return renderRequest(details);
+    case "supervisor-update":
+      return renderUpdate(details);
+  }
+}
+
+function stillRunningXml(items: WakeItem[]): string {
+  if (items.length === 0) return "";
+  const lines = items.map((item) => `    <item id="${escapeXmlAttr(item.id)}">${escapeXml(item.title)}</item>`);
+  return ["  <still-running>", ...lines, "  </still-running>"].join("\n");
+}
+
+function renderTask(details: Extract<FamulusWake, { kind: "task" }>): string {
+  const parts = ['<pi-famulus-wake kind="task">'];
+  const still = stillRunningXml(details.stillRunning);
+  if (still) parts.push(still);
+  for (const task of details.tasks) {
+    const attrs = [
+      `id="${escapeXmlAttr(task.id)}"`,
+      `kind="${escapeXmlAttr(task.taskKind)}"`,
+      `status="${escapeXmlAttr(task.status)}"`,
+      `duration-ms="${Math.round(task.durationMs)}"`,
+    ];
+    if (task.exitCode !== null) attrs.push(`exit-code="${task.exitCode}"`);
+    if (task.signal) attrs.push(`signal="${escapeXmlAttr(task.signal)}"`);
+    parts.push(`  <task ${attrs.join(" ")}>`);
+    parts.push(`    <summary>${escapeXml(task.summary)}</summary>`);
+    parts.push(`    <command>${escapeXml(task.command)}</command>`);
+    parts.push(`    <output-file>${escapeXml(task.outputPath)}</output-file>`);
+    parts.push(`    <preview>${escapeXml(task.preview)}</preview>`);
+    parts.push("  </task>");
+  }
+  parts.push("</pi-famulus-wake>");
+  return parts.join("\n");
+}
+
+function renderMonitor(details: Extract<FamulusWake, { kind: "monitor" }>): string {
+  const attrs = [
+    'kind="monitor"',
+    `id="${escapeXmlAttr(details.id)}"`,
+    `description="${escapeXmlAttr(details.description)}"`,
+  ];
+  if (details.status) attrs.push(`status="${escapeXmlAttr(details.status)}"`);
+  if (details.eventCount !== undefined && details.eventCount > 1) attrs.push(`event-count="${details.eventCount}"`);
+  if (details.droppedLines !== undefined && details.droppedLines > 0) {
+    attrs.push(`dropped-lines="${details.droppedLines}"`);
+  }
+  return [`<pi-famulus-wake ${attrs.join(" ")}>`, `  <event>${escapeXml(details.event)}</event>`, "</pi-famulus-wake>"].join("\n");
+}
+
+function renderHandover(details: Extract<FamulusWake, { kind: "subagent-handover" }>): string {
+  const attrs = [
+    'kind="subagent-handover"',
+    `run-id="${escapeXmlAttr(details.runId)}"`,
+    `child-id="${escapeXmlAttr(details.childId)}"`,
+    `name="${escapeXmlAttr(details.name)}"`,
+    `status="${escapeXmlAttr(details.status)}"`,
+  ];
+  const parts = [`<pi-famulus-wake ${attrs.join(" ")}>`];
+  const still = stillRunningXml(details.stillRunning);
+  if (still) parts.push(still);
+  parts.push(`  <summary>${escapeXml(details.summary)}</summary>`);
+  parts.push(`  <prompt>${escapeXml(details.prompt)}</prompt>`);
+  if (details.error) parts.push(`  <error>${escapeXml(details.error)}</error>`);
+  parts.push(`  <result>${escapeXml(details.result)}</result>`);
+  parts.push("</pi-famulus-wake>");
+  return parts.join("\n");
+}
+
+function renderDone(details: Extract<FamulusWake, { kind: "subagent-done" }>): string {
+  const attrs = [
+    'kind="subagent-done"',
+    `run-id="${escapeXmlAttr(details.runId)}"`,
+    `status="${escapeXmlAttr(details.status)}"`,
+    `duration-ms="${Math.round(details.durationMs)}"`,
+  ];
+  const parts = [`<pi-famulus-wake ${attrs.join(" ")}>`, `  <summary>${escapeXml(details.summary)}</summary>`];
+  for (const child of details.children) {
+    parts.push(
+      `  <child id="${escapeXmlAttr(child.childId)}" name="${escapeXmlAttr(child.name)}" status="${escapeXmlAttr(child.status)}">`,
+    );
+    parts.push(`    <prompt>${escapeXml(child.prompt)}</prompt>`);
+    if (child.error) parts.push(`    <error>${escapeXml(child.error)}</error>`);
+    parts.push(`    <result>${escapeXml(child.result)}</result>`);
+    parts.push("  </child>");
+  }
+  parts.push("</pi-famulus-wake>");
+  return parts.join("\n");
+}
+
+function renderRequest(details: Extract<FamulusWake, { kind: "supervisor-request" }>): string {
+  const recipe = `agent_message { action: "reply", to: "${details.from}", message: "<your decision>" }`;
+  return [
+    `<pi-famulus-wake kind="supervisor-request" from="${escapeXmlAttr(details.from)}" name="${escapeXmlAttr(details.name)}">`,
+    `  <message>${escapeXml(details.message)}</message>`,
+    `  <reply-with>${escapeXml(recipe)}</reply-with>`,
+    "</pi-famulus-wake>",
+  ].join("\n");
+}
+
+function renderUpdate(details: Extract<FamulusWake, { kind: "supervisor-update" }>): string {
+  return [
+    `<pi-famulus-wake kind="supervisor-update" from="${escapeXmlAttr(details.from)}" name="${escapeXmlAttr(details.name)}">`,
+    `  <message>${escapeXml(details.message)}</message>`,
+    "</pi-famulus-wake>",
+  ].join("\n");
+}

package/src/work-index.ts

@@ -0,0 +1,182 @@
+/**
+ * One index of background work for the fleet line, /tasks, and task_list.
+ *
+ * Finished items stay for 10 minutes (cap 50). Sync-waited shells are never
+ * inserted — only backgrounded shells count as workers.
+ */
+import { realClock, type Clock } from "./clock";
+
+export type WorkKind = "shell" | "monitor" | "agent";
+
+export const WORK_RETAIN_MS = 10 * 60 * 1000;
+export const WORK_FINISHED_CAP = 50;
+
+export interface WorkItem {
+  id: string;
+  kind: WorkKind;
+  status: string;
+  title: string;
+  command?: string;
+  cwd?: string;
+  startedAt: number;
+  endedAt?: number;
+  exitCode?: number | null;
+  signal?: string;
+  endReason?: string;
+  outputPath?: string;
+  stderrPath?: string;
+  /** Backgrounded parent shell. Ignored for monitor/agent. */
+  countsAsWorker: boolean;
+  runId?: string;
+  name?: string;
+  agent?: string;
+  model?: string;
+  /** User-authored prompt, excluding injected agent/model preamble. */
+  prompt?: string;
+  /** Agent-authored preamble, shown separately from the user task prompt. */
+  preamble?: string;
+  /** Last assistant text, for task_output on ch_ ids. */
+  text?: string;
+  /** Failure reason for failed agents (shown in /tasks and task_list). */
+  error?: string;
+}
+
+export interface WorkCounts {
+  workers: number;
+  subagents: number;
+  monitors: number;
+}
+
+export interface WorkIndexOptions {
+  retainMs?: number;
+  finishedCap?: number;
+  clock?: Clock;
+}
+
+function isActiveStatus(status: string): boolean {
+  return status === "pending" || status === "running";
+}
+
+export class WorkIndex {
+  private readonly items = new Map<string, WorkItem>();
+  private readonly listeners = new Set<() => void>();
+  private readonly retainMs: number;
+  private readonly finishedCap: number;
+  private readonly clock: Clock;
+
+  constructor(opts: WorkIndexOptions = {}) {
+    this.retainMs = opts.retainMs ?? WORK_RETAIN_MS;
+    this.finishedCap = opts.finishedCap ?? WORK_FINISHED_CAP;
+    this.clock = opts.clock ?? realClock;
+  }
+
+  private now(): number {
+    return this.clock.now();
+  }
+
+  onChange(cb: () => void): () => void {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+
+  get(id: string): WorkItem | undefined {
+    return this.items.get(id);
+  }
+
+  upsert(item: WorkItem): void {
+    this.items.set(item.id, item);
+    this.prune();
+    this.emit();
+  }
+
+  patch(id: string, patch: Partial<WorkItem>): WorkItem | undefined {
+    const cur = this.items.get(id);
+    if (!cur) return undefined;
+    const next = { ...cur, ...patch, id: cur.id, kind: cur.kind };
+    this.items.set(id, next);
+    this.prune();
+    this.emit();
+    return next;
+  }
+
+  /**
+   * Active items (oldest first) plus finished items still inside the retain
+   * window (newest first), capped.
+   */
+  list(now = this.now()): WorkItem[] {
+    this.prune(now);
+    const active: WorkItem[] = [];
+    const finished: WorkItem[] = [];
+    for (const item of this.items.values()) {
+      if (isActiveStatus(item.status)) active.push(item);
+      else finished.push(item);
+    }
+    active.sort((a, b) => a.startedAt - b.startedAt);
+    finished.sort((a, b) => (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt));
+    return [...active, ...finished.slice(0, this.finishedCap)];
+  }
+
+  /**
+   * Shell/monitor rows still shown as live although the manager reports the
+   * task ended: their exit event was lost (reconnect, a race, an older
+   * manager). The caller settles them; nothing else ever would.
+   */
+  staleLive<T extends { task_id: string; status: string }>(tasks: readonly T[]): T[] {
+    return tasks.filter((task) => {
+      if (task.status === "running") return false;
+      const row = this.items.get(task.task_id);
+      return row !== undefined && row.kind !== "agent" && isActiveStatus(row.status);
+    });
+  }
+
+  /** Running background shells, subagents, and monitors. No total. */
+  counts(now = this.now()): WorkCounts {
+    let workers = 0;
+    let subagents = 0;
+    let monitors = 0;
+    for (const item of this.list(now)) {
+      if (!isActiveStatus(item.status)) continue;
+      if (item.kind === "shell" && item.countsAsWorker && item.status === "running") workers++;
+      else if (item.kind === "agent") subagents++;
+      else if (item.kind === "monitor" && item.status === "running") monitors++;
+    }
+    return { workers, subagents, monitors };
+  }
+
+  private prune(now = this.now()): void {
+    const finished: WorkItem[] = [];
+    for (const item of this.items.values()) {
+      if (isActiveStatus(item.status)) continue;
+      const ended = item.endedAt ?? item.startedAt;
+      if (now - ended > this.retainMs) {
+        this.items.delete(item.id);
+        continue;
+      }
+      finished.push(item);
+    }
+    if (finished.length <= this.finishedCap) return;
+    finished.sort((a, b) => (a.endedAt ?? a.startedAt) - (b.endedAt ?? b.startedAt));
+    for (const item of finished.slice(0, finished.length - this.finishedCap)) {
+      this.items.delete(item.id);
+    }
+  }
+
+  private emit(): void {
+    for (const cb of [...this.listeners]) {
+      try {
+        cb();
+      } catch {
+        // ignore listener errors
+      }
+    }
+  }
+}
+
+export function formatAge(startedAt: number, endedAt: number | undefined, now: number): string {
+  const end = endedAt ?? now;
+  const ms = Math.max(0, end - startedAt);
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s`;
+  return `${Math.floor(ms / 3_600_000)}h${Math.floor((ms % 3_600_000) / 60_000)}m`;
+}