pi-famulus 0.1.0

package/src/subagent/transcript.ts

@@ -0,0 +1,71 @@
+/**
+ * Live child transcripts for the CLI (`pi-famulus agent ch_…`, `show ch_…`).
+ *
+ * Layout: <home>/sessions/<session_id>/agents/<child_id>.jsonl, one JSON object
+ * per conversation turn: { ts, role, text, tool?, isError? }. Lines are only
+ * ever appended; a turn already written is never rewritten.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Clock } from "../clock";
+import { agentRecordsDir } from "./agent-records";
+import type { ConversationTurn } from "./types";
+
+/** Per-line text cap; keeps every line well under the 4 KiB event-line budget used elsewhere. */
+const MAX_TEXT_CHARS = 3000;
+
+export function transcriptPath(home: string, sessionId: string, childId: string): string {
+  return `${agentRecordsDir(home, sessionId)}/${childId}.jsonl`;
+}
+
+function capText(text: string): string {
+  return text.length <= MAX_TEXT_CHARS ? text : `${text.slice(0, MAX_TEXT_CHARS)}… (${text.length} chars)`;
+}
+
+/** `tool read` / `tool bash error` → tool name + error flag. */
+function toolOf(role: string): { tool: string; isError: boolean } | undefined {
+  const m = /^tool (\S+)( error)?$/.exec(role);
+  return m ? { tool: m[1], isError: m[2] !== undefined } : undefined;
+}
+
+export function transcriptLine(turn: ConversationTurn, ts: number): string {
+  const tool = toolOf(turn.role);
+  const modelError = turn.role === "assistant error";
+  const line = tool
+    ? { ts, role: "tool", tool: tool.tool, text: capText(turn.text), ...(tool.isError ? { isError: true } : {}) }
+    : { ts, role: modelError ? "assistant" : turn.role, text: capText(turn.text), ...(modelError ? { isError: true } : {}) };
+  return `${JSON.stringify(line)}\n`;
+}
+
+export class TranscriptWriter {
+  private readonly written = new Map<string, number>();
+  private readonly toolCalls = new Map<string, number>();
+
+  constructor(
+    private readonly home: string,
+    private readonly clock: Clock,
+  ) {}
+
+  /** Append turns not yet written. Returns the transcript path. */
+  sync(sessionId: string, childId: string, turns: readonly ConversationTurn[]): string {
+    const path = transcriptPath(this.home, sessionId, childId);
+    const done = this.written.get(childId) ?? 0;
+    if (turns.length <= done) return path;
+    const fresh = turns.slice(done);
+    const ts = this.clock.now();
+    try {
+      mkdirSync(dirname(path), { recursive: true });
+      appendFileSync(path, fresh.map((t) => transcriptLine(t, ts)).join(""));
+    } catch {
+      return path; // best-effort: a later sync retries the same turns
+    }
+    this.written.set(childId, turns.length);
+    const tools = fresh.filter((t) => toolOf(t.role) !== undefined).length;
+    this.toolCalls.set(childId, (this.toolCalls.get(childId) ?? 0) + tools);
+    return path;
+  }
+
+  toolCallCount(childId: string): number {
+    return this.toolCalls.get(childId) ?? 0;
+  }
+}

package/src/subagent/types.ts

@@ -0,0 +1,125 @@
+/**
+ * M3 subagent core types (design doc Appendix B).
+ *
+ * This module is pi-free: no runtime dependency on
+ * `@earendil-works/pi-coding-agent` (and no type imports either), so every
+ * consumer stays testable with plain fakes.
+ */
+
+/**
+ * Mirror of the M5 `AgentDefinition` (design doc Appendix B, src/agents/).
+ * Structurally compatible with the M5 definition, so the real agent loader
+ * can be wired in at integration time without changes here.
+ */
+export interface AgentDefinition {
+  name: string; // ^[a-z][a-z0-9-]*$
+  description: string; // required, non-empty
+  tools: string[]; // default ["read","bash","edit","write"]
+  model?: string; // "provider:id" | bare id
+  thinking?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  systemPrompt: string; // frontmatter body, trimmed
+  source: "builtin" | "user" | "project";
+  path?: string; // builtins have no path
+}
+
+export type ChildStatus = "pending" | "running" | "completed" | "failed" | "interrupted";
+
+export interface ChildResult {
+  status: "completed" | "failed" | "interrupted";
+  text: string; // getLastAssistantText() or "(no output)"
+  error?: string;
+  /** Non-fatal caveat, e.g. agent-definition model fell back to parent model. */
+  warning?: string;
+  /** Set when the model itself stopped with an error (provider failure). */
+  endReason?: "model-error";
+  /**
+   * Total generations run (1 + resumes + stall retries). Omitted when 1.
+   * Note: a user resume() also increments this; use `stalls` to count
+   * stall retries specifically.
+   */
+  attempts?: number;
+  /** Stall detections in the user turn that produced this result. */
+  stalls?: number;
+  durationMs: number;
+}
+
+/** One turn of a child session, for the /tasks conversation view. */
+export interface ConversationTurn {
+  role: string;
+  text: string;
+}
+
+export interface ChildRunRequest {
+  childId: string; // assigned by the registry: "ch_" + 8
+  runId: string; // "run_" + 8
+  name: string; // display name (tasks[].name or agent name or ordinal)
+  prompt: string; // actual first prompt sent to the session, including agent preamble
+  /** User-authored task prompt without agent or model preamble. */
+  taskPrompt?: string;
+  agent: AgentDefinition; // already resolved
+  model?: string; // subagent() parameter-level override
+  timeoutMs: number;
+  depth: number; // main session = 0, child = 1
+}
+
+export interface ChildHandle {
+  readonly childId: string;
+  readonly result: Promise<ChildResult>; // resolves exactly once per generation;
+  // after resume() the new generation's promise is exposed via
+  // registry.getResult() (and via this getter, which always returns the
+  // current generation's promise).
+  steer(message: string): Promise<void>; // while running; terminal -> throw
+  followUp(message: string): Promise<void>; // same, queued delivery
+  resume(message: string): Promise<void>; // terminal -> continue running
+  interrupt(): Promise<void>; // abort; result resolves as interrupted
+  status(): ChildStatus;
+  lastEventAt(): number; // for the stall watchdog / status display
+  /** Resolved `provider/id` once the child session has been constructed. */
+  resolvedModel(): string | undefined;
+  /** Live child transcript. Empty when the session never started. */
+  conversation(): ConversationTurn[];
+}
+
+/**
+ * Child session adapter — the dynamic-import product of pi-runtime.ts is
+ * wrapped into this interface; tests use fakes.
+ */
+export interface ChildSessionAdapter {
+  /** Non-fatal setup caveat (e.g. model fallback); copied to ChildResult. */
+  readonly warning?: string;
+  /**
+   * Resolved model label (`provider/id`) after session construction.
+   * Used for fleet/ls persistence and so the child prompt can name its model.
+   */
+  readonly resolvedModel?: string;
+  prompt(text: string): Promise<void>;
+  steer(text: string): Promise<void>;
+  followUp(text: string): Promise<void>;
+  abort(): Promise<void>;
+  waitForIdle(): Promise<void>;
+  getLastAssistantText(): string | undefined;
+  /** Provider/model failure outcome of the last assistant turn, when any. */
+  getLastAssistantFailure?(): { stopReason: "error" | "aborted"; errorMessage?: string } | undefined;
+  getConversation(): ConversationTurn[];
+  /** Introspection for child-session orchestration and contract tests. */
+  getActiveToolNames?(): string[];
+  getSystemPrompt?(): string;
+  isStreaming(): boolean;
+  subscribe(listener: (event: { type: string }) => void): () => void;
+  dispose(): void;
+}
+
+export type CreateSessionFn = (req: ChildRunRequest) => Promise<ChildSessionAdapter>;
+
+export interface ChildRunner {
+  start(req: ChildRunRequest): Promise<ChildHandle>;
+}
+
+/**
+ * Extension beyond Appendix B: handles produced by InProcessRunner own a
+ * live session that must be disposed on run/session teardown. The registry
+ * duck-types this to release sessions in disposeRun().
+ */
+export interface DisposableChildHandle extends ChildHandle {
+  dispose(): void;
+}

package/src/task-exit-notify.ts

@@ -0,0 +1,21 @@
+/**
+ * Decide whether a manager task_exited should become a parent-session
+ * <pi-famulus-wake kind="task"> (design doc §4.2 / §4.5 / §4.6).
+ *
+ * - Monitors are handled by MonitorRegistry (not this path).
+ * - Parent bash only opts in via markNotifyOnExit when it actually
+ *   backgrounded the command (budget exceeded / run_in_background / lost contact).
+ * - Child-bash always sync-waits and must not wake the parent — otherwise every
+ *   subagent shell completion is mis-shown as a parent "Background command".
+ */
+
+export function shouldNotifyTaskExit(opts: {
+  taskId: string;
+  /** True when MonitorRegistry owns this task_id. */
+  isMonitor: boolean;
+  /** Task ids the parent bash marked for exit wake. */
+  notifyOnExit: ReadonlySet<string>;
+}): boolean {
+  if (opts.isMonitor) return false;
+  return opts.notifyOnExit.has(opts.taskId);
+}

package/src/task-tools.ts

@@ -0,0 +1,330 @@
+/**
+ * task_* tools (design doc §4.3): inspect and stop manager tasks.
+ */
+import { Type } from "typebox";
+import { realClock, type Clock } from "./clock";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ManagerClient, TaskRecord } from "./manager-client";
+import {
+  formatAgentCommand,
+  isAgentStatusActive,
+  loadAgentChildRecords,
+} from "./subagent/agent-records";
+import type { SubagentRegistry } from "./subagent/registry";
+import type { WorkIndex, WorkItem } from "./work-index";
+import { formatAge } from "./work-index";
+
+export interface TaskToolsDeps {
+  getClient: () => ManagerClient | null;
+  /** Optional: merge in-process subagent children into task_list (§4.3). */
+  getRegistry?: () => SubagentRegistry | null;
+  /** Fleet /tasks / task_list share this index when present. */
+  getIndex?: () => WorkIndex | null;
+  home?: string;
+  sessionId?: () => string;
+  clock?: Clock;
+  /** Settle work the manager reports as ended (lost exit events). */
+  syncWithManager?: () => Promise<unknown>;
+  /** task_stop on a monitor: its leftover lines and exit should not wake the model. */
+  noteStopRequested?: (taskId: string) => (() => void) | void;
+}
+
+function requireClient(deps: TaskToolsDeps): Promise<ManagerClient> {
+  const client = deps.getClient();
+  if (!client) {
+    return Promise.reject(
+      new Error("pi-famulus is not available in this session; task tools are disabled"),
+    );
+  }
+  return client.ensureAvailable().then((ok) => {
+    if (!ok) {
+      throw new Error("pi-famulus is not available in this session; task tools are disabled");
+    }
+    return client;
+  });
+}
+
+function agentTextFor(deps: TaskToolsDeps, id: string): string | undefined {
+  const indexed = deps.getIndex?.()?.get(id);
+  const isAgent = indexed?.kind === "agent" || id.startsWith("ch_");
+  if (!isAgent && !deps.getRegistry?.()?.handle(id)) return undefined;
+  const handle = deps.getRegistry?.()?.handle(id);
+  const convo = handle?.conversation?.();
+  if (convo && convo.length > 0) {
+    const text = convo.map((t) => `${t.role}: ${t.text}`).join("\n");
+    return indexed?.error ? `${text}\n\nError: ${indexed.error}` : text;
+  }
+  if (indexed?.text || indexed?.error) {
+    return [indexed.text, indexed.error ? `Error: ${indexed.error}` : undefined].filter(Boolean).join("\n\n");
+  }
+  if (isAgent) return "";
+  return undefined;
+}
+
+function formatDuration(startedAt: number, endedAt: number | null, 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 `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s`;
+}
+
+function formatTaskLine(task: TaskRecord, now: number): string {
+  const exit =
+    task.status === "running"
+      ? `pid=${task.pid}`
+      : task.exit_code !== null
+        ? `exit=${task.exit_code}`
+        : (task.signal ?? "done");
+  const command = task.command.replace(/\s+/g, " ").trim();
+  const shortCommand = command.length > 100 ? `${command.slice(0, 99)}…` : command;
+  return (
+    `${task.task_id} [${task.kind}] ${task.status} (${exit}, ${formatDuration(task.started_at, task.ended_at, now)})` +
+    ` "${shortCommand}"` +
+    `\n    output: ${task.output_path} (${task.output_size} bytes)`
+  );
+}
+
+const END_TURN_HINT =
+  'The task is still running. Reply to the user now with no tool call; a <pi-famulus-wake> arrives when it finishes.';
+const LIST_END_TURN_HINT =
+  "Running work wakes you with a <pi-famulus-wake> when it finishes. Reply to the user now with no tool call instead of checking again.";
+
+const taskListParameters = Type.Object({
+  all: Type.Optional(
+    Type.Boolean({ description: "Also include finished work (default: running only). Always limited to this session." }),
+  ),
+});
+
+export function createTaskListTool(
+  deps: TaskToolsDeps,
+): ToolDefinition<typeof taskListParameters, { tasks: TaskRecord[]; agents: string[] }> {
+  return {
+    name: "task_list",
+    label: "Task List",
+    description:
+      "List background work this session started: shell/monitor tasks and subagent children. " +
+      "Work from other pi sessions is never shown.",
+    promptSnippet: "List background shell/monitor tasks and subagents",
+    parameters: taskListParameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const client = await requireClient(deps);
+      await deps.syncWithManager?.();
+      const tasks = await client.list(params.all === true);
+      const index = deps.getIndex?.() ?? null;
+      const now = (deps.clock ?? realClock).now();
+      const lines: string[] = [];
+      const seen = new Set<string>();
+      let running = false;
+
+      const pushItem = (item: WorkItem) => {
+        if (seen.has(item.id)) return;
+        if (!params.all && item.status !== "running" && item.status !== "pending") return;
+        seen.add(item.id);
+        const age = formatAge(item.startedAt, item.endedAt, now);
+        running ||= item.status === "running" || item.status === "pending";
+        lines.push(`${item.id} [${item.kind}] ${item.status} (${age}) "${item.title}"`);
+      };
+
+      if (index) {
+        for (const item of index.list()) pushItem(item);
+      }
+      for (const task of tasks) {
+        if (seen.has(task.task_id)) continue;
+        if (!params.all && task.status !== "running") continue;
+        // Sync-waited shells are not in the index and must not be listed as workers.
+        if (task.kind === "shell" && !index?.get(task.task_id)) continue;
+        seen.add(task.task_id);
+        running ||= task.status === "running";
+        lines.push(formatTaskLine(task, now));
+      }
+
+      const agentLines: string[] = [];
+      const live = deps.getRegistry?.()?.activeChildren() ?? [];
+      const liveIds = new Set(live.map((c) => c.childId));
+      if (deps.home) {
+        const own = deps.sessionId?.();
+        // No session id means no scope to apply: show nothing rather than everyone's agents.
+        // Live children are listed from the registry above. A "running" record
+        // it does not hold was left by an earlier pi process of this session.
+        const disk = !own ? [] : loadAgentChildRecords(deps.home, {
+          sessionId: own,
+          includeTerminal: params.all === true,
+          connectedSessionIds: new Set<string>(),
+        });
+        for (const rec of disk) {
+          if (liveIds.has(rec.child_id) || seen.has(rec.child_id)) continue;
+          if (!params.all && !isAgentStatusActive(rec.status)) continue;
+          running ||= isAgentStatusActive(rec.status);
+          agentLines.push(
+            `${rec.child_id} [agent] ${rec.status} (run=${rec.run_id}) "${formatAgentCommand(rec).replace(/^agent:/, "")}"` +
+              (rec.error ? ` — error: ${rec.error}` : ""),
+          );
+        }
+      }
+
+      if (lines.length === 0 && agentLines.length === 0) {
+        return {
+          content: [{ type: "text", text: "No tasks." }],
+          details: { tasks: [], agents: [] },
+        };
+      }
+      const header = `${lines.length + agentLines.length} background item(s):`;
+      const body = [...lines, ...agentLines];
+      return {
+        content: [{ type: "text", text: [header, ...body, ...(running ? ["", LIST_END_TURN_HINT] : [])].join("\n") }],
+        details: { tasks, agents: agentLines },
+      };
+    },
+  };
+}
+
+const taskOutputParameters = Type.Object({
+  task_id: Type.String({ description: "Task id, e.g. sh_a1b2c3d4" }),
+  cursor: Type.Optional(
+    Type.Number({
+      description:
+        "Byte offset to read from (for incremental reads). Omit to read the tail of the output.",
+    }),
+  ),
+  max_bytes: Type.Optional(
+    Type.Number({ description: "Maximum bytes to return (default 65536)" }),
+  ),
+});
+
+export interface TaskOutputDetails {
+  task_id: string;
+  status: string;
+  exit_code: number | null;
+  cursor: number;
+  next_cursor: number;
+  total_size: number;
+}
+
+const DEFAULT_OUTPUT_BYTES = 65536;
+
+export function createTaskOutputTool(
+  deps: TaskToolsDeps,
+): ToolDefinition<typeof taskOutputParameters, TaskOutputDetails> {
+  // total_size at the last read of each running task. A repeat read that finds
+  // the same size is polling: the prompt forbids it, but models still loop.
+  const lastRunningSize = new Map<string, number>();
+  const guardPoll = (id: string, running: boolean, size: number) => {
+    if (running && lastRunningSize.get(id) === size) {
+      throw new Error(`No new output from ${id} since your last read. ${END_TURN_HINT}`);
+    }
+    if (running) lastRunningSize.set(id, size);
+    else lastRunningSize.delete(id);
+  };
+  return {
+    name: "task_output",
+    label: "Task Output",
+    description:
+      "Read output of a background task. Without a cursor, returns the tail of the output " +
+      "plus the current file pointer; pass the returned next_cursor as cursor for incremental reads. " +
+      "Not a way to wait: a running task wakes you when it finishes, so reply with no tool call instead of calling this again.",
+    promptSnippet: "Read background task output",
+    parameters: taskOutputParameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const agentText = agentTextFor(deps, params.task_id);
+      if (agentText !== undefined) {
+        const status = deps.getIndex?.()?.get(params.task_id)?.status ?? "unknown";
+        const running = status === "pending" || status === "running";
+        guardPoll(params.task_id, running, agentText.length);
+        const body = (agentText || "(no output yet)") + (running ? `\n\n${END_TURN_HINT}` : "");
+        return {
+          content: [{ type: "text", text: body }],
+          details: {
+            task_id: params.task_id,
+            status,
+            exit_code: null,
+            cursor: 0,
+            next_cursor: 0,
+            total_size: body.length,
+          },
+        };
+      }
+      const client = await requireClient(deps);
+      const maxBytes =
+        params.max_bytes !== undefined && params.max_bytes > 0
+          ? Math.floor(params.max_bytes)
+          : DEFAULT_OUTPUT_BYTES;
+
+      let cursor = params.cursor;
+      if (cursor === undefined) {
+        // Tail read: probe total size, then read the last max_bytes window.
+        const probe = await client.output(params.task_id, 0, 1);
+        cursor = Math.max(0, probe.total_size - maxBytes);
+      }
+
+      const res = await client.output(params.task_id, cursor, maxBytes);
+      const running = res.status === "running";
+      guardPoll(params.task_id, running, res.total_size);
+      const details: TaskOutputDetails = {
+        task_id: params.task_id,
+        status: res.status,
+        exit_code: res.exit_code,
+        cursor,
+        next_cursor: res.next_cursor,
+        total_size: res.total_size,
+      };
+      const body = res.chunk || "(no output yet)";
+      const footer =
+        `\n\n[task ${params.task_id} status=${res.status}` +
+        ` exit_code=${res.exit_code === null ? "null" : res.exit_code}` +
+        ` cursor=${cursor} next_cursor=${res.next_cursor} total_size=${res.total_size}]` +
+        (running ? `\n${END_TURN_HINT}` : "");
+      return { content: [{ type: "text", text: body + footer }], details };
+    },
+  };
+}
+
+const taskStopParameters = Type.Object({
+  task_id: Type.String({ description: "Task id to stop, e.g. sh_a1b2c3d4" }),
+});
+
+export function createTaskStopTool(
+  deps: TaskToolsDeps,
+): ToolDefinition<typeof taskStopParameters, { task_id: string; stopped: boolean }> {
+  return {
+    name: "task_stop",
+    label: "Task Stop",
+    description:
+      "Stop a running background task (SIGTERM to the process group, SIGKILL after a 2s grace).",
+    promptSnippet: "Stop a background task",
+    parameters: taskStopParameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx: ExtensionContext) {
+      const agent = deps.getRegistry?.()?.handle(params.task_id);
+      if (agent || params.task_id.startsWith("ch_") || deps.getIndex?.()?.get(params.task_id)?.kind === "agent") {
+        if (!agent) {
+          throw new Error(`no live subagent ${params.task_id}`);
+        }
+        await agent.interrupt();
+        return {
+          content: [{ type: "text", text: `Subagent ${params.task_id} interrupted.` }],
+          details: { task_id: params.task_id, stopped: true },
+        };
+      }
+      const client = await requireClient(deps);
+      const undoNote = deps.noteStopRequested?.(params.task_id);
+      try {
+        await client.stop(params.task_id, "tool");
+      } catch (err) {
+        undoNote?.();
+        throw err;
+      } finally {
+        // Stopping a task that already ended emits no new exit event.
+        await deps.syncWithManager?.();
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Task ${params.task_id} stopped (SIGTERM; SIGKILL after 2s grace if needed).`,
+          },
+        ],
+        details: { task_id: params.task_id, stopped: true },
+      };
+    },
+  };
+}