pi-famulus 0.1.0

package/src/events.ts

@@ -0,0 +1,61 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Clock } from "./clock";
+
+export type ExtensionEventFields = Record<string, unknown>;
+
+/** Append extension observability events to the session's shared events.jsonl. */
+export class ExtensionEventLog {
+  constructor(
+    private readonly home: string,
+    private readonly sessionId: () => string,
+    private readonly now: () => number,
+  ) {}
+
+  write(type: string, fields: ExtensionEventFields = {}): void {
+    const sid = this.sessionId();
+    if (!sid) return;
+    try {
+      const file = join(this.home, "sessions", sid, "events.jsonl");
+      mkdirSync(dirname(file), { recursive: true });
+      appendFileSync(file, `${formatExtensionEventLine({ ...fields, ts: this.now(), src: "extension", type })}\n`, {
+        encoding: "utf8",
+        flag: "a",
+      });
+    } catch {
+      // Observability must never break extension behavior.
+    }
+  }
+}
+
+export function formatExtensionEventLine(event: ExtensionEventFields): string {
+  const bounded: ExtensionEventFields = { ...event };
+  let truncated = false;
+  for (const [key, value] of Object.entries(bounded)) {
+    if (typeof value === "string" && value.length > 700) {
+      bounded[key] = `${value.slice(0, 699)}…`;
+      truncated = true;
+    } else if (Array.isArray(value) && value.length > 32) {
+      bounded[key] = value.slice(0, 32);
+      truncated = true;
+    }
+  }
+  if (truncated) bounded.truncated = true;
+  let line = JSON.stringify(bounded);
+  while (Buffer.byteLength(line, "utf8") + 1 >= 4096) {
+    const candidate = Object.entries(bounded).find(([, value]) => typeof value === "string" && value.length > 64);
+    if (!candidate) {
+      line = JSON.stringify({ ts: event.ts, src: "extension", type: event.type, truncated: true });
+      break;
+    }
+    const [key, value] = candidate;
+    bounded[key] = `${(value as string).slice(0, Math.max(0, Math.floor((value as string).length / 2) - 1))}…`;
+    bounded.truncated = true;
+    line = JSON.stringify(bounded);
+  }
+  return line;
+}
+
+export function createExtensionEventLog(home: string, sessionId: () => string, clock: Clock): ExtensionEventLog {
+  return new ExtensionEventLog(home, sessionId, () => clock.now());
+}

package/src/exit-notify-gate.ts

@@ -0,0 +1,69 @@
+/**
+ * A task can exit in the same socket read as a wait reply of done:false.
+ * The exit event is dispatched before markNotifyOnExit runs, so the wake is
+ * dropped. Stash that exit and fire it when the mark arrives late.
+ */
+import { realClock, type Clock } from "./clock";
+
+export interface StashedExit<T> {
+  taskId: string;
+  event: T;
+}
+
+export class ExitNotifyGate<T> {
+  private readonly notify = new Set<string>();
+  private readonly recent = new Map<string, T>();
+  private readonly ttlMs: number;
+  private readonly clock: Clock;
+  private readonly stamped = new Map<string, number>();
+
+  constructor(opts: { ttlMs?: number; clock?: Clock } = {}) {
+    this.ttlMs = opts.ttlMs ?? 30_000;
+    this.clock = opts.clock ?? realClock;
+  }
+
+  private now(): number {
+    return this.clock.now();
+  }
+
+  /**
+   * Record that this task should wake the parent when it exits.
+   * If the exit already arrived, return it so the caller can notify now.
+   */
+  mark(taskId: string): T | undefined {
+    this.prune();
+    this.notify.add(taskId);
+    const prior = this.recent.get(taskId);
+    if (prior === undefined) return undefined;
+    this.recent.delete(taskId);
+    this.stamped.delete(taskId);
+    this.notify.delete(taskId);
+    return prior;
+  }
+
+  /**
+   * An exit event arrived. "notify" if it was already marked, "stash" if the
+   * mark may still be coming, "ignore" for monitors (they have their own path).
+   */
+  onExit(taskId: string, event: T, isMonitor: boolean): "notify" | "stash" | "ignore" {
+    if (isMonitor) return "ignore";
+    this.prune();
+    if (this.notify.has(taskId)) {
+      this.notify.delete(taskId);
+      return "notify";
+    }
+    this.recent.set(taskId, event);
+    this.stamped.set(taskId, this.now());
+    return "stash";
+  }
+
+  private prune(): void {
+    const cutoff = this.now() - this.ttlMs;
+    for (const [id, at] of this.stamped) {
+      if (at < cutoff) {
+        this.stamped.delete(id);
+        this.recent.delete(id);
+      }
+    }
+  }
+}

package/src/exit-watchdog.ts

@@ -0,0 +1,60 @@
+/**
+ * Keeps backgrounded commands' wakes alive without the model's help.
+ *
+ * The prompt tells the agent to end its turn after backgrounding a command.
+ * Its wake normally comes from task_exited; a lost event is recovered by
+ * syncWithManager, which otherwise runs only when someone looks (task_list,
+ * /tasks, task_stop) or on reconnect. After reconnect gives up nothing looks,
+ * so an agent that obeyed would never be woken. While any wake is pending,
+ * this ticks on its own.
+ */
+import type { Clock, ClockTimer } from "./clock";
+
+export const EXIT_WATCHDOG_INTERVAL_MS = 30_000;
+
+export interface ExitWatchdogOptions {
+  clock: Clock;
+  intervalMs?: number;
+  hasPending: () => boolean;
+  /** Reconnect if needed and settle ended tasks (delivering their wakes). */
+  tick: () => Promise<unknown>;
+}
+
+export class ExitWatchdog {
+  private timer: ClockTimer;
+  private armed = false;
+  private inFlight = false;
+
+  constructor(private readonly opts: ExitWatchdogOptions) {}
+
+  /** Start ticking if not already; call whenever a task starts awaiting its wake. */
+  arm(): void {
+    if (this.armed) return;
+    this.armed = true;
+    this.timer = this.opts.clock.setInterval(
+      () => this.onTick(),
+      this.opts.intervalMs ?? EXIT_WATCHDOG_INTERVAL_MS,
+    );
+  }
+
+  dispose(): void {
+    if (!this.armed) return;
+    this.armed = false;
+    this.opts.clock.clearInterval(this.timer);
+  }
+
+  private onTick(): void {
+    if (!this.opts.hasPending()) {
+      this.dispose();
+      return;
+    }
+    if (this.inFlight) return;
+    this.inFlight = true;
+    void this.opts
+      .tick()
+      .catch(() => {})
+      .finally(() => {
+        this.inFlight = false;
+      });
+  }
+}

package/src/file-tail.ts

@@ -0,0 +1,48 @@
+/**
+ * Read only the tail of a file (fd + position). Never slurps the whole file.
+ */
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+
+export interface FileTail {
+  text: string;
+  size: number;
+}
+
+/** Last `maxBytes` bytes, cut on a UTF-8 boundary. Returns null if the file cannot be opened. */
+export function readFileTail(path: string, maxBytes: number): FileTail | null {
+  const cap = Math.max(0, Math.floor(maxBytes));
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, "r");
+    const size = fstatSync(fd).size;
+    if (size === 0 || cap === 0) return { text: "", size };
+    const start = Math.max(0, size - cap);
+    const len = size - start;
+    const buf = Buffer.alloc(len);
+    let off = 0;
+    while (off < len) {
+      const n = readSync(fd, buf, off, len - off, start + off);
+      if (n <= 0) break;
+      off += n;
+    }
+    const raw = buf.subarray(0, off);
+    const text = (start > 0 ? skipPartialUtf8(raw) : raw).toString("utf8");
+    return { text, size };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+function skipPartialUtf8(buf: Buffer): Buffer {
+  let i = 0;
+  while (i < buf.length && (buf[i] & 0b1100_0000) === 0b1000_0000) i++;
+  return buf.subarray(i);
+}

package/src/format.ts

@@ -0,0 +1,276 @@
+/**
+ * Pure formatting helpers (design doc Appendix A).
+ *
+ * These functions are the shared contract between implementation and tests.
+ * Signatures must match Appendix A exactly.
+ */
+import { formatFamulusWake, shellWakeTitle, type FormattedWake, type WakeItem } from "./wake";
+
+export { FAMULUS_WAKE_LEAD_IN } from "./wake";
+export type { FormattedWake, WakeItem } from "./wake";
+
+export interface TruncationInfo {
+  truncated: boolean;
+  totalLines: number;
+  totalBytes: number;
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+/**
+ * Keep the tail of `text`, bounded by both maxLines and maxBytes
+ * (defaults match the built-in bash tool: 2000 lines / 50KB).
+ * Never splits a line, except when the final line alone exceeds maxBytes,
+ * in which case its byte-tail is kept (UTF-8 lossy).
+ */
+export function truncateTail(
+  text: string,
+  maxLines: number = 2000,
+  maxBytes: number = 51200,
+): { text: string } & TruncationInfo {
+  const totalBytes = byteLength(text);
+  const lines = text.split("\n");
+  const totalLines = lines.length;
+  if (totalLines <= maxLines && totalBytes <= maxBytes) {
+    return { text, truncated: false, totalLines, totalBytes };
+  }
+  const kept: string[] = [];
+  let bytes = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const lineBytes = byteLength(lines[i]) + (kept.length > 0 ? 1 : 0); // +1 for the joining newline
+    if (kept.length >= maxLines || bytes + lineBytes > maxBytes) break;
+    kept.unshift(lines[i]);
+    bytes += lineBytes;
+  }
+  if (kept.length === 0 && lines.length > 0) {
+    // The final line alone exceeds maxBytes: keep its byte tail, aligned to a
+    // UTF-8 code point boundary so no replacement character is surfaced.
+    kept.push(byteTail(lines[lines.length - 1], maxBytes));
+  }
+  return { text: kept.join("\n"), truncated: true, totalLines, totalBytes };
+}
+
+/** Last `maxBytes` bytes of `text`, cut at a UTF-8 boundary (never mid-character). */
+function byteTail(text: string, maxBytes: number): string {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= maxBytes) return text;
+  let start = buf.length - maxBytes;
+  // Skip continuation bytes (0b10xxxxxx) to land on a character boundary.
+  while (start < buf.length && (buf[start] & 0b1100_0000) === 0b1000_0000) start++;
+  return buf.subarray(start).toString("utf8");
+}
+
+export interface TaskExitInfo {
+  taskId: string;
+  kind: string;
+  command: string;
+  status: "completed" | "failed" | "killed" | "orphaned";
+  exitCode: number | null;
+  durationMs: number;
+  outputPath: string;
+  /** Pre-truncated by the caller to 4000 chars. */
+  preview: string;
+  /** Signal name from the manager, when the exit was a signal. */
+  signal?: string;
+}
+
+/** Shorten a command for one-line display inside notifications. */
+function displayCommand(command: string): string {
+  return shellWakeTitle(command);
+}
+
+function statusPhrase(info: TaskExitInfo): string {
+  const code = info.exitCode === null ? null : `exit code ${info.exitCode}`;
+  switch (info.status) {
+    case "completed":
+      return code ? `completed (${code})` : "completed";
+    case "failed":
+      return code ? `failed (${code})` : "failed";
+    case "killed":
+      return "was killed";
+    case "orphaned":
+      return "ended when pi-famulus crashed";
+  }
+}
+
+const TASK_COMMAND_CHARS = 2000;
+
+function capCommand(command: string): string {
+  return command.length > TASK_COMMAND_CHARS ? `${command.slice(0, TASK_COMMAND_CHARS)}…` : command;
+}
+
+function taskSummary(info: TaskExitInfo): string {
+  return `Background command "${displayCommand(info.command)}" ${statusPhrase(info)}`;
+}
+
+/**
+ * One <pi-famulus-wake kind="task"> for a batch of exits (§4.5).
+ * `leadIn` is the ablation seam: "" leaves a parseable envelope.
+ */
+export function formatTaskNotification(
+  events: TaskExitInfo[],
+  stillRunning: WakeItem[] = [],
+  leadIn?: string,
+): FormattedWake {
+  return formatFamulusWake(
+    {
+      kind: "task",
+      stillRunning,
+      tasks: events.map((info) => ({
+        id: info.taskId,
+        taskKind: info.kind,
+        status: info.status,
+        summary: taskSummary(info),
+        command: capCommand(info.command),
+        outputPath: info.outputPath,
+        preview: info.preview,
+        durationMs: info.durationMs,
+        exitCode: info.exitCode,
+        ...(info.signal ? { signal: info.signal } : {}),
+      })),
+    },
+    leadIn,
+  );
+}
+
+/** Tool-result text returned when a foreground command is moved to the background (§4.2). */
+export function formatBackgroundNotice(
+  taskId: string,
+  command: string,
+  outputPath: string,
+): string {
+  // Model-facing. The transcript row is drawn by the bash tool's renderResult.
+  return [
+    `Command "${displayCommand(command)}" moved to background (task_id: ${taskId}). Output: ${outputPath}.`,
+    'You will be notified when it completes, even if other commands are still running. Do not poll or sleep: reply to the user now with no tool call, and continue from the <pi-famulus-wake kind="task"> when it arrives.',
+  ].join("\n");
+}
+
+/** Transcript row for a backgrounded command (UI only; never sent to the model). */
+export function backgroundRowText(
+  taskId: string,
+  item: { status: string; exitCode?: number | null; startedAt: number; endedAt?: number } | undefined,
+  now: number,
+): { glyph: string; color: string; text: string } {
+  if (!item || item.status === "running" || item.status === "pending") {
+    return { glyph: "⏵", color: "accent", text: `${taskId} running in background · /tasks` };
+  }
+  const secs = ((item.endedAt ?? now) - item.startedAt) / 1000;
+  const dur = secs < 60 ? `${secs.toFixed(1)}s` : `${Math.floor(secs / 60)}m${Math.round(secs % 60)}s`;
+  const exit = item.exitCode === null || item.exitCode === undefined ? "" : ` · exit ${item.exitCode}`;
+  const ok = item.status === "completed" && (item.exitCode === 0 || item.exitCode === null || item.exitCode === undefined);
+  return ok
+    ? { glyph: "✓", color: "success", text: `${taskId} finished${exit} · ${dur}` }
+    : { glyph: "✗", color: "error", text: `${taskId} ${item.status}${exit} · ${dur} · /tasks` };
+}
+
+/** Injected payload for a batch of monitor output lines (§4.4 / §4.5). */
+export function formatMonitorEvent(
+  description: string,
+  taskId: string,
+  batchText: string,
+  status?: string,
+  extras: { eventCount?: number; droppedLines?: number } = {},
+): FormattedWake {
+  return formatFamulusWake({
+    kind: "monitor",
+    id: taskId,
+    description,
+    ...(status ? { status } : {}),
+    event: batchText,
+    ...(extras.eventCount !== undefined ? { eventCount: extras.eventCount } : {}),
+    ...(extras.droppedLines !== undefined ? { droppedLines: extras.droppedLines } : {}),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// M3: subagent run completion notification (design doc §4.6)
+// ---------------------------------------------------------------------------
+
+export interface SubagentChildInfo {
+  childId: string;
+  name: string;
+  status: "pending" | "running" | "completed" | "failed" | "interrupted";
+  text: string;
+  error?: string;
+  /** Task prompt that was sent to this child. */
+  prompt?: string;
+}
+
+export interface SubagentNotificationInfo {
+  runId: string;
+  status: "completed" | "partial" | "failed" | "interrupted";
+  durationMs: number;
+  children: SubagentChildInfo[];
+}
+
+/** Per-child result text is capped to its tail inside notifications (§4.6). */
+const SUBAGENT_NOTIFICATION_CHILD_CHARS = 2000;
+
+function capTail(text: string): string {
+  return text.length > SUBAGENT_NOTIFICATION_CHILD_CHARS
+    ? text.slice(-SUBAGENT_NOTIFICATION_CHILD_CHARS)
+    : text;
+}
+
+/** Keep the start of a task prompt; the assignment is at the beginning. */
+function capPrompt(text: string): string {
+  return text.length > SUBAGENT_NOTIFICATION_CHILD_CHARS
+    ? `${text.slice(0, SUBAGENT_NOTIFICATION_CHILD_CHARS)}…`
+    : text;
+}
+
+export interface SubagentHandoverInfo {
+  runId: string;
+  childId: string;
+  name: string;
+  status: "completed" | "failed" | "interrupted";
+  prompt: string;
+  text: string;
+  error?: string;
+  /** Children that are still pending or running. Title is the agent name. */
+  stillRunning: WakeItem[];
+}
+
+/** Finished run: one <child> per child inside <pi-famulus-wake kind="subagent-done">. */
+export function formatSubagentNotification(info: SubagentNotificationInfo): FormattedWake {
+  const completed = info.children.filter((c) => c.status === "completed").length;
+  const summary = `${completed}/${info.children.length} subagents completed in ${Math.round(info.durationMs)}ms`;
+  return formatFamulusWake({
+    kind: "subagent-done",
+    runId: info.runId,
+    status: info.status,
+    durationMs: info.durationMs,
+    summary,
+    children: info.children.map((child) => ({
+      childId: child.childId,
+      name: child.name,
+      status: child.status,
+      prompt: capPrompt(child.prompt ?? ""),
+      result: capTail(child.text),
+      ...(child.error ? { error: child.error } : {}),
+    })),
+  });
+}
+
+/**
+ * One child finished while others in the same run are still going.
+ * The parent must see the original prompt and the result, then keep working.
+ */
+export function formatSubagentHandover(info: SubagentHandoverInfo): FormattedWake {
+  const summary = `${info.name} ${info.status}; ${info.stillRunning.length} still running`;
+  return formatFamulusWake({
+    kind: "subagent-handover",
+    runId: info.runId,
+    childId: info.childId,
+    name: info.name,
+    status: info.status,
+    stillRunning: info.stillRunning,
+    summary,
+    prompt: capPrompt(info.prompt),
+    result: capTail(info.text),
+    ...(info.error ? { error: info.error } : {}),
+  });
+}