pi-famulus 0.1.0

package/src/bash-override.ts

@@ -0,0 +1,372 @@
+/**
+ * bash tool override (design doc §4.2).
+ *
+ * Routes bash commands through pi-famulus:
+ * - foreground commands wait up to `foregroundBudgetMs` (default 20000,
+ *   configurable) and are then moved to the background instead of blocking;
+ * - bare sleep / idle-loop commands are rejected with guidance;
+ * - when the manager is unavailable, execution falls back to a local
+ *   child_process implementation that mimics the built-in bash tool
+ *   (degraded but never broken).
+ *
+ * Result details stay compatible with BashToolDetails
+ * ({ truncation?, fullOutputPath? }); extension fields are added alongside.
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Type } from "typebox";
+import type {
+  AgentToolResult,
+  BashToolDetails,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { taskOutputPath, type FamulusConfig } from "./config";
+import { realClock, type Clock, type ClockTimer } from "./clock";
+import { backgroundRowText, formatBackgroundNotice, truncateTail } from "./format";
+import { toolComponent } from "./tui/tool-component";
+import type { WorkIndex } from "./work-index";
+import type { ManagerClient } from "./manager-client";
+import {
+  appendStatus,
+  bareSleepError,
+  collectOutput,
+  formatFinishedOutput,
+  killedBy,
+  killedStatus,
+  timedOutStatus,
+  SHELL_MAX_BYTES,
+  SHELL_MAX_LINES,
+  withAbort,
+} from "./shell-exec";
+
+/** Same limits as the built-in bash tool. */
+const MAX_LINES = SHELL_MAX_LINES;
+const MAX_BYTES = SHELL_MAX_BYTES;
+
+const bashParameters = Type.Object({
+  command: Type.String({ description: "The bash command to execute" }),
+  timeout: Type.Optional(
+    Type.Number({ description: "Hard kill timeout in seconds (optional, no default timeout)" }),
+  ),
+  run_in_background: Type.Optional(
+    Type.Boolean({
+      description:
+        "Start the command in the background and return immediately. You will be notified when it completes.",
+    }),
+  ),
+});
+
+type BashParams = { command: string; timeout?: number; run_in_background?: boolean };
+
+/** Details shape returned by this override; superset of BashToolDetails. */
+export interface FamulusBashDetails extends BashToolDetails {
+  backgrounded?: boolean;
+  task_id?: string;
+}
+
+export interface BashOverrideDeps {
+  getClient: () => ManagerClient | null;
+  config: FamulusConfig;
+  home: string;
+  sessionId: () => string;
+  /** Extra environment injected into managed child processes (PI_* vars). */
+  sessionEnv: (ctx: ExtensionContext) => Record<string, string>;
+  /** Register task metadata so exit notifications can describe the task. */
+  trackTask: (taskId: string, meta: { kind: string; command: string; cwd?: string }) => void;
+  /**
+   * Mark a task so its task_exited event becomes a parent <pi-famulus-wake kind="task">.
+   * Only backgrounded parent bash should call this — sync waits (foreground
+   * budget hit, child-bash) must not wake the parent session.
+   */
+  markNotifyOnExit: (taskId: string) => void;
+  clock?: Clock;
+  /** Live background work, so a backgrounded row can show its final status. */
+  getIndex?: () => WorkIndex | null;
+}
+
+/** Same collapsed preview as pi's default tool-result view. */
+const PREVIEW_LINES = 10;
+
+function isActiveStatus(status: string | undefined): boolean {
+  return status === undefined || status === "running" || status === "pending";
+}
+
+const BARE_SLEEP_GUIDANCE =
+  "Do not sleep to wait for background work; completion is delivered via notification. Use the monitor tool to watch for a condition, or run_in_background for long commands.";
+
+function rejectBareSleep(command: string): string | null {
+  return bareSleepError(command, BARE_SLEEP_GUIDANCE);
+}
+
+function resolveTimeoutMs(timeoutSeconds: number | undefined): number | null {
+  if (timeoutSeconds === undefined) return null;
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+    throw new Error("Invalid timeout: must be a finite number of seconds");
+  }
+  return Math.round(timeoutSeconds * 1000);
+}
+
+function fullEnv(ctx: ExtensionContext, deps: BashOverrideDeps): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) env[key] = value;
+  }
+  Object.assign(env, deps.sessionEnv(ctx));
+  return env;
+}
+
+// ---------------------------------------------------------------------------
+// Local fallback (manager unavailable): mimics the built-in bash tool.
+// ---------------------------------------------------------------------------
+
+async function executeLocal(
+  params: BashParams,
+  signal: AbortSignal | undefined,
+  ctx: ExtensionContext,
+  clock: Clock,
+): Promise<AgentToolResult<FamulusBashDetails | undefined>> {
+  const timeoutMs = resolveTimeoutMs(params.timeout);
+  const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
+
+  const output = await new Promise<{ text: string; exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
+    (resolve, reject) => {
+      const child = spawn(shell, ["-c", params.command], {
+        cwd: ctx.cwd,
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      const chunks: Buffer[] = [];
+      let settled = false;
+      let timedOut = false;
+      let aborted = false;
+      let timer: ClockTimer | null = null;
+      const finish = (exitCode: number | null, killSignal: string | null) => {
+        if (settled) return;
+        settled = true;
+        if (timer !== null) clock.clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve({ text: Buffer.concat(chunks).toString("utf8"), exitCode, signal: killSignal, timedOut, aborted });
+      };
+      const kill = () => {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+          // already dead
+        }
+      };
+      const onAbort = () => {
+        aborted = true;
+        kill();
+      };
+      timer =
+        timeoutMs !== null
+          ? clock.setTimeout(() => {
+              timedOut = true;
+              kill();
+            }, timeoutMs)
+          : null;
+      if (timer !== null) clock.unref?.(timer);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      child.stdout?.on("data", (d: Buffer) => chunks.push(d));
+      child.stderr?.on("data", (d: Buffer) => chunks.push(d));
+      child.on("error", (err) => {
+        if (timer !== null) clock.clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        if (!settled) {
+          settled = true;
+          reject(new Error(`Failed to start shell: ${err.message}`));
+        }
+      });
+      child.on("close", (code, killSignal) => finish(code, killSignal));
+    },
+  );
+
+  const t = truncateTail(output.text, MAX_LINES, MAX_BYTES);
+  let text = t.text || "(no output)";
+  let details: FamulusBashDetails | undefined;
+  if (t.truncated) {
+    const fullOutputPath = join(tmpdir(), `pi-famulus-bash-${randomUUID()}.log`);
+    writeFileSync(fullOutputPath, output.text, "utf8");
+    const outputLines = t.text.length === 0 ? 0 : t.text.split("\n").length;
+    const startLine = t.totalLines - outputLines + 1;
+    details = {
+      truncation: {
+        content: t.text,
+        truncated: true,
+        truncatedBy: t.totalLines > MAX_LINES ? "lines" : "bytes",
+        totalLines: t.totalLines,
+        totalBytes: t.totalBytes,
+        outputLines,
+        outputBytes: Buffer.byteLength(t.text, "utf8"),
+        lastLinePartial: false,
+        firstLineExceedsLimit: false,
+        maxLines: MAX_LINES,
+        maxBytes: MAX_BYTES,
+      },
+      fullOutputPath,
+    };
+    text += `\n\n[Showing lines ${startLine}-${t.totalLines} of ${t.totalLines}. Full output: ${fullOutputPath}]`;
+  }
+
+  if (output.aborted) throw new Error(appendStatus(text, "Command aborted"));
+  if (output.timedOut && params.timeout !== undefined) {
+    throw new Error(appendStatus(text, timedOutStatus(params.timeout)));
+  }
+  if (output.exitCode !== 0 && output.exitCode !== null) {
+    throw new Error(appendStatus(text, `Command exited with code ${output.exitCode}`));
+  }
+  if (output.exitCode === null) throw new Error(appendStatus(text, killedBy(output.signal)));
+  return { content: [{ type: "text", text }], details };
+}
+
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+
+export function createBashOverride(
+  deps: BashOverrideDeps,
+): ToolDefinition<typeof bashParameters, FamulusBashDetails | undefined> {
+  return {
+    name: "bash",
+    label: "Bash",
+    description:
+      "Execute a bash command in the current working directory. Returns stdout and stderr. " +
+      `Output is truncated to last ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB (whichever is hit first). ` +
+      "Foreground commands that exceed the foreground budget are automatically moved to the background; " +
+      "you will be notified when they complete. Optionally provide a timeout in seconds (hard kill limit), " +
+      "or run_in_background to background immediately.",
+    promptSnippet: "Execute bash commands (ls, grep, find, etc.)",
+    promptGuidelines: [
+      "You can inspect PI_* environment variables for current model and session details.",
+      "Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them. End your turn (a reply with no tool call) and resume from the task wake when it arrives.",
+    ],
+    parameters: bashParameters,
+    renderResult(result, { expanded }, theme, context) {
+      const details = result.details as FamulusBashDetails | undefined;
+      if (details?.backgrounded && details.task_id) {
+        const taskId = details.task_id;
+        const index = deps.getIndex?.() ?? null;
+        const state = context.state as { unsubscribe?: () => void };
+        const item = index?.get(taskId);
+        if (index && !state.unsubscribe && isActiveStatus(item?.status)) {
+          // Redraw this row when the task finishes, then stop listening.
+          state.unsubscribe = index.onChange(() => {
+            if (!isActiveStatus(index.get(taskId)?.status)) {
+              state.unsubscribe?.();
+              state.unsubscribe = () => {};
+            }
+            context.invalidate();
+          });
+        }
+        const row = backgroundRowText(taskId, item, (deps.clock ?? realClock).now());
+        return toolComponent([`${theme.fg(row.color as never, row.glyph)} ${theme.fg("muted", row.text)}`]) as never;
+      }
+      const text = result.content
+        .filter((c): c is { type: "text"; text: string } => c.type === "text")
+        .map((c) => c.text)
+        .join("\n");
+      const lines = text.split("\n");
+      const shown = expanded ? lines : lines.slice(0, PREVIEW_LINES);
+      const out = shown.map((l) => theme.fg("toolOutput", l));
+      if (shown.length < lines.length) {
+        out.push(theme.fg("muted", `... (${lines.length - shown.length} more lines, ctrl+o to expand)`));
+      }
+      return toolComponent(out) as never;
+    },
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const input = params as BashParams;
+
+      const sleepError = rejectBareSleep(input.command);
+      if (sleepError) throw new Error(sleepError);
+
+      const client = deps.getClient();
+      const managed = client !== null && (await client.ensureAvailable());
+      if (!managed || client === null) {
+        // Degraded mode: run locally like the built-in bash tool.
+        return executeLocal(input, signal, ctx, deps.clock ?? realClock);
+      }
+
+      const timeoutMs = resolveTimeoutMs(input.timeout);
+      let start;
+      try {
+        start = await client.start({
+          kind: "shell",
+          command: input.command,
+          cwd: ctx.cwd,
+          env: fullEnv(ctx, deps),
+          run_in_background: input.run_in_background === true,
+          timeout_ms: timeoutMs,
+          origin: { via: input.run_in_background === true ? "bash-bg" : "bash-fg" },
+        });
+      } catch {
+        // Manager request failed mid-session; degrade to local execution.
+        return executeLocal(input, signal, ctx, deps.clock ?? realClock);
+      }
+      deps.trackTask(start.task_id, { kind: "shell", command: input.command, cwd: ctx.cwd });
+      const outputPath = taskOutputPath(deps.home, deps.sessionId(), start.task_id);
+
+      if (input.run_in_background === true) {
+        deps.markNotifyOnExit(start.task_id);
+        return {
+          content: [
+            { type: "text", text: formatBackgroundNotice(start.task_id, input.command, outputPath) },
+          ],
+          details: { fullOutputPath: outputPath, backgrounded: true, task_id: start.task_id },
+        };
+      }
+
+      // Foreground: wait up to the budget, then move to background.
+      let waitResult;
+      try {
+        waitResult = await withAbort(client.wait(start.task_id, deps.config.foregroundBudgetMs), signal, () => {
+          client.stop(start.task_id, "tool").catch(() => {});
+        });
+      } catch (err) {
+        if ((err as Error).message === "aborted") {
+          throw new Error("Command aborted (background task stopped)");
+        }
+        // Lost contact with the manager while waiting; the task may still run.
+        deps.markNotifyOnExit(start.task_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `Lost contact with pi-famulus while waiting for task ${start.task_id}. ` +
+                `The command may still be running. Output: ${outputPath}. ` +
+                "Use task_list/task_output to check on it once the manager is back.",
+            },
+          ],
+          details: { fullOutputPath: outputPath, backgrounded: true, task_id: start.task_id },
+        };
+      }
+
+      if (!waitResult.done) {
+        deps.markNotifyOnExit(start.task_id);
+        return {
+          content: [
+            { type: "text", text: formatBackgroundNotice(start.task_id, input.command, outputPath) },
+          ],
+          details: { fullOutputPath: outputPath, backgrounded: true, task_id: start.task_id },
+        };
+      }
+
+      const collected = await collectOutput(client, start.task_id);
+      const { text, details } = formatFinishedOutput(collected, outputPath);
+      const exitCode = waitResult.exit_code ?? null;
+      if (exitCode !== 0 && exitCode !== null) {
+        throw new Error(appendStatus(text, `Command exited with code ${exitCode}`));
+      }
+      // No exit code: killed (timeout, stop, crash), unless the manager
+      // finished it as completed with its runner status unobservable.
+      if (exitCode === null && collected.status !== "completed") {
+        throw new Error(appendStatus(text, await killedStatus(client, start.task_id, input.timeout)));
+      }
+      return { content: [{ type: "text", text }], details };
+    },
+  };
+}

package/src/behavior-guidelines.ts

@@ -0,0 +1,42 @@
+/**
+ * Persistent system-prompt section for background-task behavior.
+ *
+ * Returning `systemPrompt` from before_agent_start forces the whole prompt for
+ * that user-prompt run only (and clobbers other extensions). Wake turns started
+ * by sendMessage({ triggerTurn: true }) do not call before_agent_start again.
+ * A named section is diffed into the transcript and stays visible on those turns.
+ */
+export const BEHAVIOR_GUIDELINES_SECTION = "pi-famulus";
+
+/** Child-only instructions injected through the contact_supervisor tool guideline. */
+export const CHILD_BEHAVIOR_GUIDELINES = `## Child agent behavior (pi-famulus)
+
+- Do not background work; bash runs to completion.
+- When blocked, use contact_supervisor with need_decision; use progress_update for status.
+- Use agent_message only to communicate with siblings in this same run.
+- Your final message is your result.`;
+
+export const BEHAVIOR_GUIDELINES = `## Background tasks and notifications (pi-famulus)
+
+- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind="task"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.
+- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. Do not wait for further user input when the next step is clear; do not merely acknowledge and stop.
+- Never fabricate or assume a background task's result before its notification arrives.
+- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind="subagent-handover"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:"resume", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind="subagent-done"> arrives — read each <child>, synthesize, and continue.
+- Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind="supervisor-request"> (action:"reply"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:"resume"}). Supervisor wakes are not user messages — still act on them.`;
+
+export interface GuidelinePromptOptions {
+  sections?: Record<string, string>;
+}
+
+/** Mutate prompt sections in place. Does not replace the whole system prompt. */
+export function applyBehaviorGuidelines(options: GuidelinePromptOptions): void {
+  if (!options.sections) options.sections = {};
+  options.sections[BEHAVIOR_GUIDELINES_SECTION] = BEHAVIOR_GUIDELINES;
+}
+
+/** What a later wake turn sees: persisted sections, no before_agent_start. */
+export function wakePromptFromSections(sections: Record<string, string>): string {
+  return Object.entries(sections)
+    .map(([name, content]) => `<${name}>\n${content}\n</${name}>`)
+    .join("\n");
+}

package/src/clock.ts

@@ -0,0 +1,169 @@
+export type ClockTimer = unknown;
+
+/** The timer/time source used by extension services. */
+export interface Clock {
+  now(): number;
+  setTimeout(callback: () => void, delayMs: number): ClockTimer;
+  clearTimeout(timer: ClockTimer): void;
+  setInterval(callback: () => void, intervalMs: number): ClockTimer;
+  clearInterval(timer: ClockTimer): void;
+  unref?(timer: ClockTimer): void;
+  sleep(delayMs: number): Promise<void>;
+}
+
+export const realClock: Clock = {
+  now: () => Date.now(),
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (timer) => globalThis.clearTimeout(timer as ReturnType<typeof setTimeout>),
+  setInterval: (callback, intervalMs) => globalThis.setInterval(callback, intervalMs),
+  clearInterval: (timer) => globalThis.clearInterval(timer as ReturnType<typeof setInterval>),
+  unref: (timer) => (timer as { unref?: () => void }).unref?.(),
+  sleep: (delayMs) => new Promise((resolve) => globalThis.setTimeout(resolve, delayMs)),
+};
+
+type ScheduledTimer = {
+  readonly id: number;
+  readonly order: number;
+  due: number;
+  readonly interval: number | null;
+  readonly callback: () => void;
+};
+
+/** Deterministic scheduler. Advancing runs every due callback before returning. */
+export class ManualClock implements Clock {
+  private currentTime: number;
+  private nextId = 1;
+  private readonly timers = new Map<number, ScheduledTimer>();
+
+  constructor(startAt = 0) {
+    this.currentTime = startAt;
+  }
+
+  now(): number {
+    return this.currentTime;
+  }
+
+  setTimeout(callback: () => void, delayMs: number): ClockTimer {
+    return this.schedule(callback, delayMs, null);
+  }
+
+  clearTimeout(timer: ClockTimer): void {
+    this.cancel(timer);
+  }
+
+  setInterval(callback: () => void, intervalMs: number): ClockTimer {
+    return this.schedule(callback, Math.max(1, intervalMs), Math.max(1, intervalMs));
+  }
+
+  clearInterval(timer: ClockTimer): void {
+    this.cancel(timer);
+  }
+
+  sleep(delayMs: number): Promise<void> {
+    return new Promise((resolve) => this.setTimeout(resolve, delayMs));
+  }
+
+  advanceBy(deltaMs: number): void {
+    if (!Number.isFinite(deltaMs) || deltaMs < 0) {
+      throw new RangeError("ManualClock.advanceBy requires a finite non-negative duration");
+    }
+    this.advanceTo(this.currentTime + deltaMs);
+  }
+
+  advanceTo(targetTime: number): void {
+    if (!Number.isFinite(targetTime) || targetTime < this.currentTime) {
+      throw new RangeError("ManualClock.advanceTo cannot move backwards or to a non-finite time");
+    }
+
+    while (true) {
+      const next = [...this.timers.values()]
+        .filter((timer) => timer.due <= targetTime)
+        .sort((a, b) => a.due - b.due || a.order - b.order)[0];
+      if (!next) break;
+
+      // It may have been cancelled by an earlier callback since selection.
+      if (!this.timers.has(next.id)) continue;
+      this.currentTime = next.due;
+      if (next.interval === null) this.timers.delete(next.id);
+      else next.due += next.interval;
+      next.callback();
+    }
+
+    this.currentTime = targetTime;
+  }
+
+  private schedule(callback: () => void, delayMs: number, interval: number | null): ClockTimer {
+    const delay = Number.isFinite(delayMs) ? Math.max(0, delayMs) : 0;
+    const id = this.nextId++;
+    this.timers.set(id, {
+      id,
+      order: id,
+      due: this.currentTime + delay,
+      interval,
+      callback,
+    });
+    return id;
+  }
+
+  private cancel(timer: ClockTimer): void {
+    if (typeof timer === "number") this.timers.delete(timer);
+  }
+}
+
+/** Owns timer handles for one lifecycle scope and cancels them together. */
+export class TimerScope {
+  private readonly owned = new Map<ClockTimer, () => void>();
+  private disposed = false;
+
+  constructor(private readonly clock: Clock) {}
+
+  get size(): number {
+    return this.owned.size;
+  }
+
+  setTimeout(callback: () => void, delayMs: number): ClockTimer {
+    this.assertActive();
+    let timer: ClockTimer;
+    timer = this.clock.setTimeout(() => {
+      this.owned.delete(timer);
+      if (!this.disposed) callback();
+    }, delayMs);
+    this.owned.set(timer, () => this.clock.clearTimeout(timer));
+    return timer;
+  }
+
+  clearTimeout(timer: ClockTimer): void {
+    this.clear(timer);
+  }
+
+  setInterval(callback: () => void, intervalMs: number): ClockTimer {
+    this.assertActive();
+    const timer = this.clock.setInterval(() => {
+      if (!this.disposed) callback();
+    }, intervalMs);
+    this.owned.set(timer, () => this.clock.clearInterval(timer));
+    return timer;
+  }
+
+  clearInterval(timer: ClockTimer): void {
+    this.clear(timer);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const clear of this.owned.values()) clear();
+    this.owned.clear();
+  }
+
+  private clear(timer: ClockTimer): void {
+    const cancel = this.owned.get(timer);
+    if (!cancel) return;
+    cancel();
+    this.owned.delete(timer);
+  }
+
+  private assertActive(): void {
+    if (this.disposed) throw new Error("TimerScope is disposed");
+  }
+}