pi-famulus 0.1.0

package/src/notify.ts

@@ -0,0 +1,231 @@
+/**
+ * NotifyCenter (design doc §4.5): the single injection point for all
+ * asynchronous events into the pi session.
+ *
+ * - idle  -> pi.sendMessage(msg, { triggerTurn: true })
+ * - busy  -> pi.sendMessage(msg, { deliverAs: "steer" })
+ * - passive -> held until the agent settles, then
+ *   pi.sendMessage(msg, { triggerTurn: false }): appended, starting no turn.
+ *   Sent at once while the model was writing, pi appended it at that turn's
+ *   end, while a wake steered in at the same moment waits for the next turn's
+ *   start: a monitor's exit landed before its own event (eval batches 2–4).
+ * - task exit notifications are coalesced over a 200ms window into one
+ *   <pi-famulus-wake kind="task"> payload, and the same task/event pair is only
+ *   ever delivered once.
+ */
+import { formatMonitorEvent, formatTaskNotification, type TaskExitInfo } from "./format";
+import { FAMULUS_WAKE_CUSTOM_TYPE, type WakeItem } from "./wake";
+import { realClock, type Clock, type ClockTimer } from "./clock";
+
+
+export interface NotifyMessage {
+  customType: string;
+  content: string;
+  details?: unknown;
+}
+
+export interface NotifyCenterDeps {
+  sendMessage: (
+    message: { customType: string; content: string; display: boolean; details?: unknown },
+    options: { triggerTurn?: boolean; deliverAs?: "steer" },
+  ) => void;
+  isIdle: () => boolean;
+  /** Batching window for task exit notifications (ms). Default 200. */
+  batchMs?: number;
+  /**
+   * Background tasks still awaiting their own exit wake.
+   * Read at flush time so siblings that exit in the same window are not listed.
+   */
+  listStillRunning?: () => WakeItem[];
+  clock?: Clock;
+  logEvent?: (type: string, fields?: Record<string, unknown>) => void;
+}
+
+
+export class NotifyCenter {
+  private readonly deps: NotifyCenterDeps;
+  private readonly batchMs: number;
+  private readonly clock: Clock;
+  private pendingExits: TaskExitInfo[] = [];
+  private readonly pendingMonitors = new Map<
+    string,
+    { description: string; eventCount: number; lastEvent: string; droppedLines: number; quiet: boolean }
+  >();
+  private readonly seen = new Set<string>();
+  private timer: ClockTimer | null = null;
+  private disposed = false;
+  /** A wake started or steered a run that has not settled yet. */
+  private runPending = false;
+  private held: NotifyMessage[] = [];
+
+  constructor(deps: NotifyCenterDeps) {
+    this.deps = deps;
+    this.batchMs = deps.batchMs ?? 200;
+    this.clock = deps.clock ?? realClock;
+  }
+
+  /**
+   * Queue a task exit notification. Deduplicated by task id; merged with
+   * other exits inside the batching window.
+   */
+  notifyTaskExit(info: TaskExitInfo): void {
+    if (this.disposed) return;
+    const key = `exit:${info.taskId}`;
+    if (this.seen.has(key)) {
+      this.deps.logEvent?.("wake.dedupe", { id: info.taskId });
+      return;
+    }
+    this.seen.add(key);
+    this.pendingExits.push(info);
+    this.scheduleFlush();
+  }
+
+  /**
+   * Send a notification immediately, routed by idle/busy state. A monitor's
+   * own notice (exit, timeout, stop) first delivers that monitor's coalesced
+   * events: they happened before it, and the model must not hear "exited"
+   * ahead of the lines the command printed.
+   */
+  notify(message: NotifyMessage, opts: { passive?: boolean; quietEvents?: boolean } = {}): void {
+    if (this.disposed) return;
+    const wake = message.details as { kind?: string; id?: string } | undefined;
+    if (wake?.kind === "monitor" && typeof wake.id === "string") this.flushMonitor(wake.id, opts.quietEvents);
+    if (!opts.passive) {
+      this.deliver(message);
+    } else if (this.runPending || !this.deps.isIdle()) {
+      this.held.push(message);
+    } else {
+      this.deliver(message, true);
+    }
+  }
+
+  /**
+   * The agent settled: the run any earlier wake started is over. Flush
+   * coalesced monitor output, then, unless that started another run, the
+   * held passive notices.
+   */
+  settled(): void {
+    if (this.disposed) return;
+    this.runPending = false;
+    this.flushMonitorEvents();
+    if (this.runPending) return;
+    for (const message of this.held.splice(0)) this.deliver(message, true);
+  }
+
+  /**
+   * Deliver monitor output immediately when idle, otherwise coalesce per
+   * monitor. `quiet`: output of a monitor the model stopped; it is only
+   * coalesced, and its summary is delivered without a turn (with the exit
+   * notice, or at settle), pending events of that monitor included.
+   */
+  notifyMonitorEvent(description: string, taskId: string, event: string, droppedLines = 0, opts: { quiet?: boolean } = {}): void {
+    if (this.disposed) return;
+    const pending = this.pendingMonitors.get(taskId);
+    if (this.deps.isIdle() && !pending && !opts.quiet) {
+      const wake = formatMonitorEvent(description, taskId, event, undefined, { droppedLines });
+      this.deliver({ customType: wake.customType, content: wake.content, details: wake.details });
+      return;
+    }
+    this.pendingMonitors.set(taskId, {
+      description,
+      eventCount: (pending?.eventCount ?? 0) + 1,
+      lastEvent: event,
+      droppedLines: (pending?.droppedLines ?? 0) + droppedLines,
+      quiet: (pending?.quiet ?? false) || opts.quiet === true,
+    });
+    if (this.deps.isIdle() && !opts.quiet) this.flushMonitorEvents();
+  }
+
+  /** Flush coalesced monitor output when the parent agent settles. */
+  flushMonitorEvents(): void {
+    if (this.disposed || !this.deps.isIdle() || this.pendingMonitors.size === 0) return;
+    for (const taskId of [...this.pendingMonitors.keys()]) this.flushMonitor(taskId);
+  }
+
+  /** Deliver one monitor's coalesced events, if any, in the current mode. */
+  private flushMonitor(taskId: string, quiet = false): void {
+    const item = this.pendingMonitors.get(taskId);
+    if (!item) return;
+    this.pendingMonitors.delete(taskId);
+    const summary = item.eventCount > 1
+      ? `${item.eventCount} events · last: ${item.lastEvent}`
+      : item.lastEvent;
+    const wake = formatMonitorEvent(item.description, taskId, summary, undefined, {
+      eventCount: item.eventCount,
+      droppedLines: item.droppedLines,
+    });
+    const message = { customType: wake.customType, content: wake.content, details: wake.details };
+    if (quiet || item.quiet) this.notify(message, { passive: true });
+    else this.deliver(message);
+  }
+
+  /** Flush any pending task exit notifications now. */
+  flush(): void {
+    this.clearTimer();
+    this.flushExits();
+    this.flushMonitorEvents();
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.clearTimer();
+    this.pendingExits = [];
+    this.pendingMonitors.clear();
+    this.held = [];
+  }
+
+  private scheduleFlush(): void {
+    if (this.timer !== null) return;
+    this.timer = this.clock.setTimeout(() => {
+      this.timer = null;
+      this.flushExits();
+    }, this.batchMs);
+    this.clock.unref?.(this.timer);
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      this.clock.clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private flushExits(): void {
+    if (this.disposed || this.pendingExits.length === 0) return;
+    const events = this.pendingExits;
+    this.pendingExits = [];
+    const wake = formatTaskNotification(events, this.deps.listStillRunning?.() ?? []);
+    this.deliver({
+      customType: FAMULUS_WAKE_CUSTOM_TYPE,
+      content: wake.content,
+      details: wake.details,
+    });
+  }
+
+  private deliver(message: NotifyMessage, passive = false): void {
+    const msg = { ...message, display: true };
+    const details = message.details as { kind?: string; id?: string; taskId?: string; tasks?: { id: string }[]; children?: { childId: string }[]; childId?: string; from?: string; eventCount?: number } | undefined;
+    if (details?.kind) {
+      const ids = details.kind === "task"
+        ? (details.tasks ?? []).map((task) => task.id)
+        : details.kind === "subagent-done"
+          ? (details.children ?? []).map((child) => child.childId)
+          : [details.id ?? details.taskId ?? details.childId ?? details.from].filter((id): id is string => Boolean(id));
+      this.deps.logEvent?.("wake.emit", {
+        kind: details.kind,
+        ids,
+        batch: ids.length > 1 || (details.kind === "monitor" && (details.eventCount ?? 0) > 1),
+      });
+    }
+    const mode = passive ? "passive" : this.deps.isIdle() ? "trigger" : "steer";
+    this.deps.logEvent?.("wake.deliver", { kind: details?.kind ?? "unknown", mode });
+    if (mode !== "passive") this.runPending = true;
+    if (mode === "passive") {
+      this.deps.sendMessage(msg, { triggerTurn: false });
+    } else if (mode === "trigger") {
+      this.deps.sendMessage(msg, { triggerTurn: true });
+    } else {
+      this.deps.sendMessage(msg, { deliverAs: "steer" });
+    }
+  }
+}

package/src/shell-exec.ts

@@ -0,0 +1,145 @@
+/**
+ * Shared bash helpers used by the parent override and the child-session bash.
+ * Previously copied in both files.
+ */
+import type { BashToolDetails } from "@earendil-works/pi-coding-agent";
+import { truncateTail } from "./format";
+import type { ManagerClient } from "./manager-client";
+
+export const SHELL_MAX_LINES = 2000;
+export const SHELL_MAX_BYTES = 51200;
+export const SHELL_OUTPUT_WINDOW_BYTES = 512 * 1024;
+
+export const BARE_SLEEP_PATTERNS: RegExp[] = [
+  /^\s*sleep\s+\d/,
+  /^\s*while\s+true\b/,
+  /^\s*while\s+sleep\b/,
+  /^\s*until\s+/,
+];
+
+export function bareSleepError(command: string, guidance: string): string | null {
+  if (!BARE_SLEEP_PATTERNS.some((re) => re.test(command))) return null;
+  return `Refusing to run a bare sleep/idle-loop command: ${JSON.stringify(command)}. ${guidance}`;
+}
+
+export function withAbort<T>(
+  promise: Promise<T>,
+  signal: AbortSignal | undefined,
+  onAbort: () => void,
+): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) {
+    onAbort();
+    return Promise.reject(new Error("aborted"));
+  }
+  return new Promise<T>((resolve, reject) => {
+    const handler = () => {
+      onAbort();
+      reject(new Error("aborted"));
+    };
+    signal.addEventListener("abort", handler, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", handler);
+        resolve(value);
+      },
+      (err) => {
+        signal.removeEventListener("abort", handler);
+        reject(err);
+      },
+    );
+  });
+}
+
+export interface CollectedOutput {
+  text: string;
+  totalSize: number;
+  windowed: boolean;
+  /** The task's status as the manager reported it with the output. */
+  status: string;
+}
+
+export async function collectOutput(client: ManagerClient, taskId: string): Promise<CollectedOutput> {
+  const probe = await client.output(taskId, 0, 1);
+  const totalSize = probe.total_size;
+  const start = Math.max(0, totalSize - SHELL_OUTPUT_WINDOW_BYTES);
+  let cursor = start;
+  let text = "";
+  for (;;) {
+    const res = await client.output(taskId, cursor, SHELL_OUTPUT_WINDOW_BYTES);
+    text += res.chunk;
+    if (res.next_cursor <= cursor || res.next_cursor >= res.total_size) break;
+    cursor = res.next_cursor;
+  }
+  return { text, totalSize, windowed: start > 0, status: probe.status };
+}
+
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export interface FormattedShellOutput {
+  text: string;
+  details: BashToolDetails | undefined;
+}
+
+export function formatFinishedOutput(raw: CollectedOutput, outputPath: string): FormattedShellOutput {
+  const t = truncateTail(raw.text, SHELL_MAX_LINES, SHELL_MAX_BYTES);
+  const truncated = t.truncated || raw.windowed;
+  let text = t.text || "(no output)";
+  if (!truncated) return { text, details: undefined };
+
+  const outputLines = t.text.length === 0 ? 0 : t.text.split("\n").length;
+  const outputBytes = Buffer.byteLength(t.text, "utf8");
+  const truncatedBy = t.totalLines > SHELL_MAX_LINES ? "lines" : "bytes";
+  const details: BashToolDetails = {
+    truncation: {
+      content: t.text,
+      truncated: true,
+      truncatedBy,
+      totalLines: t.totalLines,
+      totalBytes: raw.totalSize,
+      outputLines,
+      outputBytes,
+      lastLinePartial: false,
+      firstLineExceedsLimit: false,
+      maxLines: SHELL_MAX_LINES,
+      maxBytes: SHELL_MAX_BYTES,
+    },
+    fullOutputPath: outputPath,
+  };
+  const startLine = t.totalLines - outputLines + 1;
+  const endLine = t.totalLines;
+  if (truncatedBy === "lines") {
+    text += `\n\n[Showing lines ${startLine}-${endLine} of ${t.totalLines}. Full output: ${outputPath}]`;
+  } else {
+    text += `\n\n[Showing lines ${startLine}-${endLine} of ${t.totalLines} (${formatSize(SHELL_MAX_BYTES)} limit). Full output: ${outputPath}]`;
+  }
+  return { text, details };
+}
+
+export function appendStatus(text: string, status: string): string {
+  return text ? `${text}\n\n${status}` : status;
+}
+
+/**
+ * Status line for a finished task with no exit code: it was killed (its
+ * timeout, a stop, a crash). Reported as success, a model took a 1s timeout
+ * kill for a command still running (eval batch 4).
+ */
+export async function killedStatus(client: ManagerClient, taskId: string, timeoutSeconds: number | undefined): Promise<string> {
+  const record = (await client.list(true).catch(() => [])).find((t) => t.task_id === taskId);
+  if (record?.end_reason === "timeout" && timeoutSeconds !== undefined) return timedOutStatus(timeoutSeconds);
+  return killedBy(record?.signal);
+}
+
+/** The one wording of a timeout kill, on every bash path. */
+export function timedOutStatus(timeoutSeconds: number): string {
+  return `Command timed out after ${timeoutSeconds} seconds`;
+}
+
+export function killedBy(signal: string | null | undefined): string {
+  return `Command was killed${signal ? ` (${signal})` : ""}`;
+}

package/src/subagent/agent-records.ts

@@ -0,0 +1,168 @@
+/**
+ * On-disk agent child records so `pi-famulus ls` can see in-process subagents
+ * (design doc §4.3: task_list merges manager tasks with subagent runs).
+ *
+ * Layout: <home>/sessions/<session_id>/agents/<child_id>.json
+ */
+import { mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface AgentChildRecord {
+  v: 1;
+  kind: "agent";
+  child_id: string;
+  run_id: string;
+  session_id: string;
+  name: string;
+  agent: string;
+  /** Resolved model id when known (param override or agent definition). */
+  model?: string;
+  status: "pending" | "running" | "completed" | "failed" | "interrupted";
+  /** Total generations run (1 + resumes + stall retries); omitted when 1. */
+  attempts?: number;
+  /** Stall detections in the final user turn. */
+  stalls?: number;
+  started_at: number;
+  ended_at?: number;
+  error?: string;
+  /** Why the child ended (terminal statuses only). */
+  end_reason?: AgentEndReason;
+  /** Task prompt without the agent preamble, capped. */
+  prompt_head?: string;
+  /** Tail of the final result text, capped. */
+  result_tail?: string;
+  /** Tool results seen in the transcript so far. */
+  tool_calls?: number;
+  /** Absolute path of the live `<child_id>.jsonl` transcript. */
+  transcript?: string;
+}
+
+export type AgentEndReason =
+  | "completed"
+  | "failed"
+  | "model-error"
+  | "stalled"
+  | "timeout"
+  | "interrupted"
+  | "disposed";
+
+/** Map a terminal child status + result to the end_reason recorded on disk. */
+export function agentEndReason(
+  status: AgentChildRecord["status"],
+  result: { error?: string; endReason?: "model-error" } | undefined,
+): AgentEndReason | undefined {
+  if (status === "completed") return "completed";
+  if (status === "failed") {
+    if (result?.endReason === "model-error") return "model-error";
+    return result?.error === "stalled" ? "stalled" : "failed";
+  }
+  if (status === "interrupted") {
+    if (result?.error === "timeout") return "timeout";
+    if (result?.error === "disposed") return "disposed";
+    return "interrupted";
+  }
+  return undefined;
+}
+
+const HEAD_TAIL_CHARS = 2000;
+
+export function headOf(text: string): string {
+  return text.length <= HEAD_TAIL_CHARS ? text : `${text.slice(0, HEAD_TAIL_CHARS)}…`;
+}
+
+export function tailOf(text: string): string {
+  return text.length <= HEAD_TAIL_CHARS ? text : `…${text.slice(-HEAD_TAIL_CHARS)}`;
+}
+
+export function agentRecordsDir(home: string, sessionId: string): string {
+  return join(home, "sessions", sessionId, "agents");
+}
+
+export function agentRecordPath(home: string, sessionId: string, childId: string): string {
+  return join(agentRecordsDir(home, sessionId), `${childId}.json`);
+}
+
+/** Write one child record (mkdir + overwrite). */
+export function writeAgentChildRecord(home: string, record: AgentChildRecord): void {
+  const dir = agentRecordsDir(home, record.session_id);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(agentRecordPath(home, record.session_id, record.child_id), JSON.stringify(record));
+}
+
+export function removeAgentChildRecord(home: string, sessionId: string, childId: string): void {
+  try {
+    unlinkSync(agentRecordPath(home, sessionId, childId));
+  } catch {
+    // already gone
+  }
+}
+
+function parseRecord(raw: string): AgentChildRecord | null {
+  try {
+    const v = JSON.parse(raw) as Partial<AgentChildRecord>;
+    if (v.v !== 1 || v.kind !== "agent") return null;
+    if (typeof v.child_id !== "string" || typeof v.session_id !== "string") return null;
+    if (typeof v.name !== "string" || typeof v.agent !== "string") return null;
+    if (typeof v.status !== "string" || typeof v.started_at !== "number") return null;
+    return v as AgentChildRecord;
+  } catch {
+    return null;
+  }
+}
+
+/** Load agent child records from disk (all sessions under home). */
+export function loadAgentChildRecords(
+  home: string,
+  opts: { sessionId?: string; includeTerminal?: boolean; connectedSessionIds?: ReadonlySet<string> } = {},
+): AgentChildRecord[] {
+  const sessionsRoot = join(home, "sessions");
+  let sessionIds: string[];
+  try {
+    sessionIds = opts.sessionId
+      ? [opts.sessionId]
+      : readdirSync(sessionsRoot, { withFileTypes: true })
+          .filter((d) => d.isDirectory())
+          .map((d) => d.name);
+  } catch {
+    return [];
+  }
+  const out: AgentChildRecord[] = [];
+  for (const sid of sessionIds) {
+    const dir = agentRecordsDir(home, sid);
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      try {
+        const rec = parseRecord(readFileSync(join(dir, file), "utf8"));
+        if (!rec) continue;
+        const disconnected =
+          opts.connectedSessionIds !== undefined && !opts.connectedSessionIds.has(rec.session_id);
+        const shown: AgentChildRecord =
+          disconnected && (rec.status === "pending" || rec.status === "running")
+            ? { ...rec, status: "interrupted" }
+            : rec;
+        const terminal =
+          shown.status === "completed" || shown.status === "failed" || shown.status === "interrupted";
+        if (!opts.includeTerminal && terminal) continue;
+        out.push(shown);
+      } catch {
+        // skip bad files
+      }
+    }
+  }
+  return out;
+}
+
+export function isAgentStatusActive(status: AgentChildRecord["status"]): boolean {
+  return status === "pending" || status === "running";
+}
+
+/** Display command column for CLI / task_list. */
+export function formatAgentCommand(rec: AgentChildRecord): string {
+  const model = rec.model ? ` ${rec.model}` : "";
+  return `agent:${rec.name} (${rec.agent})${model}`;
+}