pi-famulus 0.1.0

package/src/subagent/child-bash.ts

@@ -0,0 +1,183 @@
+/**
+ * Child-session bash variant (design doc §4.2 tail / §4.6).
+ *
+ * Registered as a custom tool named "bash" inside subagent sessions (it
+ * overrides the built-in there). Differences from the main bash override:
+ * - no run_in_background: subagents must not background work — the schema
+ *   omits the flag entirely (lain waitUntilExit lesson);
+ * - execute waits for the whole timeout via manager start + wait; on expiry
+ *   the process is killed (SIGTERM->SIGKILL by the manager) and a timeout
+ *   error is returned instead of backgrounding;
+ * - bare sleep / idle-loop commands are rejected (same patterns as the main
+ *   bash override; the detection logic is copied, not imported, per the M3
+ *   file-ownership rules);
+ * - no local fallback: when the manager is unavailable the tool fails with a
+ *   clear error (subagent sessions are spawned by the extension where the
+ *   manager is expected to be up).
+ */
+import { Type } from "typebox";
+import type {
+  AgentToolResult,
+  BashToolDetails,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { taskOutputPath } from "../config";
+import { realClock, type Clock } from "../clock";
+import type { ManagerClient } from "../manager-client";
+import {
+  appendStatus,
+  bareSleepError,
+  collectOutput,
+  formatFinishedOutput,
+  killedStatus,
+  timedOutStatus,
+  SHELL_MAX_BYTES,
+  SHELL_MAX_LINES,
+  withAbort,
+} from "../shell-exec";
+
+const MAX_LINES = SHELL_MAX_LINES;
+const MAX_BYTES = SHELL_MAX_BYTES;
+/** Wait granularity when no explicit timeout is given (abort responsiveness). */
+const WAIT_SLICE_MS = 60_000;
+
+const childBashParameters = 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)" }),
+  ),
+});
+
+type ChildBashParams = { command: string; timeout?: number };
+
+export interface FamulusChildBashDetails extends BashToolDetails {
+  task_id?: string;
+}
+
+export interface ChildBashDeps {
+  getClient: () => ManagerClient | null;
+  home: string;
+  /** Parent session id — the manager namespace this connection owns. */
+  sessionId: () => string;
+  /** Precomputed PI_* env injection (from the parent session). */
+  sessionEnv: () => Record<string, string>;
+  trackTask: (taskId: string, meta: { kind: string; command: string; cwd?: string }) => void;
+  childId?: string;
+  runId?: string;
+  clock?: Clock;
+}
+
+const CHILD_SLEEP_GUIDANCE =
+  "Sleeping to wait for work is never useful: run the actual command directly, or report back to the supervisor if you are blocked.";
+
+function rejectBareSleep(command: string): string | null {
+  return bareSleepError(command, CHILD_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(deps: ChildBashDeps): 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());
+  return env;
+}
+
+export function createChildBashTool(
+  deps: ChildBashDeps,
+): ToolDefinition<typeof childBashParameters, FamulusChildBashDetails | 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). ` +
+      "The command runs to completion (or the optional timeout in seconds, after which it is killed). " +
+      "There is no background execution inside subagents.",
+    promptSnippet: "Execute bash commands (ls, grep, find, etc.)",
+    parameters: childBashParameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx: ExtensionContext) {
+      const input = params as ChildBashParams;
+
+      const sleepError = rejectBareSleep(input.command);
+      if (sleepError) throw new Error(sleepError);
+
+      const client = deps.getClient();
+      if (!client || !(await client.ensureAvailable())) {
+        throw new Error("pi-famulus is not available; bash is disabled inside this subagent");
+      }
+
+      const timeoutMs = resolveTimeoutMs(input.timeout);
+      const start = await client.start({
+        kind: "shell",
+        command: input.command,
+        cwd: ctx.cwd,
+        env: fullEnv(deps),
+        run_in_background: false,
+        timeout_ms: timeoutMs,
+        ...(deps.childId && deps.runId
+          ? { origin: { via: "child-bash" as const, child_id: deps.childId, run_id: deps.runId } }
+          : {}),
+      });
+      deps.trackTask(start.task_id, { kind: "shell", command: input.command, cwd: ctx.cwd });
+      const outputPath = taskOutputPath(deps.home, deps.sessionId(), start.task_id);
+
+      const clock = deps.clock ?? realClock;
+      const deadline = timeoutMs !== null ? clock.now() + timeoutMs : null;
+      let waitResult: { done: boolean; exit_code?: number | null } | null = null;
+      for (;;) {
+        const budget =
+          deadline === null
+            ? WAIT_SLICE_MS
+            : Math.min(WAIT_SLICE_MS, Math.max(1, deadline - clock.now()));
+        try {
+          waitResult = await withAbort(client.wait(start.task_id, budget), signal, () => {
+            client.stop(start.task_id, "tool").catch(() => {});
+          });
+        } catch (err) {
+          if ((err as Error).message === "aborted") {
+            throw new Error("Command aborted (task stopped)");
+          }
+          throw new Error(
+            `Lost contact with pi-famulus while waiting for task ${start.task_id}: ` +
+              `${(err as Error).message}. Output so far: ${outputPath}.`,
+          );
+        }
+        if (waitResult.done) break;
+        if (deadline !== null && clock.now() >= deadline) {
+          await client.stop(start.task_id, "timeout").catch(() => {});
+          const collected = await collectOutput(client, start.task_id).catch(() => null);
+          const text = collected ? formatFinishedOutput(collected, outputPath).text : "";
+          throw new Error(
+            appendStatus(text, timedOutStatus(input.timeout!)),
+          );
+        }
+      }
+
+      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)));
+      }
+      const finalDetails = details
+        ? { ...details, task_id: start.task_id }
+        : ({ task_id: start.task_id } as FamulusChildBashDetails);
+      return { content: [{ type: "text", text }], details: finalDetails };
+    },
+  };
+}

package/src/subagent/conversation.ts

@@ -0,0 +1,76 @@
+/**
+ * Flatten a child AgentSession message list into plain turns.
+ * Structural on purpose: this file does not import pi.
+ */
+import type { ConversationTurn } from "./types";
+
+interface LooseBlock {
+  type?: string;
+  text?: string;
+  name?: string;
+  arguments?: unknown;
+}
+
+interface LooseMessage {
+  role?: string;
+  content?: unknown;
+  toolName?: string;
+  isError?: boolean;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+function blockText(block: LooseBlock): string {
+  if (block.type === "text" || block.type === "thinking") return block.text ?? "";
+  if (block.type === "toolCall") {
+    const args = block.arguments === undefined ? "" : ` ${JSON.stringify(block.arguments)}`;
+    return `tool ${block.name ?? "?"}${args}`;
+  }
+  return "";
+}
+
+function visibleUserText(text: string): string {
+  let visible = text.replace(/^You are running as model [^\n]+\.\n\n/, "");
+  const separator = visible.indexOf("\n\n---\n\n");
+  if (separator >= 0) visible = visible.slice(separator + "\n\n---\n\n".length);
+  return visible.trim();
+}
+
+function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => (block && typeof block === "object" ? blockText(block as LooseBlock) : ""))
+    .filter((part) => part.length > 0)
+    .join("\n");
+}
+
+export function turnsFromMessages(messages: readonly LooseMessage[]): ConversationTurn[] {
+  const turns: ConversationTurn[] = [];
+  let firstUserTurn = true;
+  for (const message of messages) {
+    if (message.role === "system") continue;
+    const rawText = contentText(message.content);
+    const text = message.role === "user" && firstUserTurn ? visibleUserText(rawText) : rawText;
+    if (message.role === "user") firstUserTurn = false;
+    if (message.role === "assistant" && (message.stopReason === "error" || message.stopReason === "aborted")) {
+      // A failed model call often has no text; its error is the only record of what happened.
+      if (text) turns.push({ role: "assistant", text });
+      turns.push({ role: "assistant error", text: message.errorMessage?.trim() || `model stopped: ${message.stopReason}` });
+      continue;
+    }
+    if (!text) continue;
+    if (message.role === "toolResult") {
+      const name = message.toolName ?? "tool";
+      turns.push({ role: message.isError ? `tool ${name} error` : `tool ${name}`, text });
+      continue;
+    }
+    turns.push({ role: message.role ?? "message", text });
+  }
+  return turns;
+}
+
+export function formatConversation(turns: readonly ConversationTurn[]): string {
+  if (turns.length === 0) return "(no messages yet)";
+  return turns.map((turn) => `── ${turn.role} ──\n${turn.text}`).join("\n\n");
+}

package/src/subagent/fleet-widget.ts

@@ -0,0 +1,176 @@
+/**
+ * Passive fleet summary below the editor — counts only, no keyboard hooks.
+ *
+ * Format: `2 workers · 1 subagent · 1 monitor`
+ *   workers   = backgrounded shell tasks (not sync-waited)
+ *   subagents = in-process subagent children
+ *   monitors  = active monitors
+ *
+ * Driven by WorkIndex changes. Does not poll the manager.
+ */
+import { realClock, type Clock, type ClockTimer } from "../clock";
+import { formatAge, type WorkIndex, type WorkItem } from "../work-index";
+import { truncateToWidth } from "../tui/pi-tui-load";
+
+export const FLEET_WIDGET_KEY = "pi-famulus-fleet";
+
+function isActive(item: WorkItem): boolean {
+  return item.status === "pending" || item.status === "running";
+}
+
+export interface FleetTheme {
+  fg(color: string, text: string): string;
+}
+
+export interface FleetTui {
+  requestRender(): void;
+}
+
+export interface FleetWidgetComponent {
+  render(width: number): string[];
+  invalidate?(): void;
+  dispose?(): void;
+}
+
+export interface FleetUi {
+  setWidget(
+    key: string,
+    content:
+      | string[]
+      | undefined
+      | ((tui: FleetTui, theme: FleetTheme) => FleetWidgetComponent),
+    options?: { placement?: "aboveEditor" | "belowEditor" },
+  ): void;
+}
+
+export interface FleetStatusDeps {
+  index: WorkIndex;
+  getUi: () => FleetUi | null;
+  clock?: Clock;
+}
+
+function countLabel(n: number, singular: string, plural?: string): string {
+  return `${n} ${n === 1 ? singular : (plural ?? `${singular}s`)}`;
+}
+
+/** Counts part of the fleet line. "shell" = a backgrounded bash command. */
+export function summaryLabel(shells: number, subagents: number, monitors: number): string {
+  const parts: string[] = [];
+  if (shells > 0) parts.push(countLabel(shells, "shell"));
+  if (subagents > 0) parts.push(countLabel(subagents, "subagent"));
+  if (monitors > 0) parts.push(countLabel(monitors, "monitor"));
+  return parts.join(" · ");
+}
+
+/**
+ * Passive fleet status line (below editor). No setStatus, no keyboard capture, no poll.
+ */
+export class FleetWidget {
+  private readonly deps: FleetStatusDeps;
+  private started = false;
+  private widgetRegistered = false;
+  private tui: FleetTui | null = null;
+  private unsubscribe: (() => void) | null = null;
+  private ageTimer: ClockTimer | null = null;
+  private readonly clock: Clock;
+
+  constructor(deps: FleetStatusDeps) {
+    this.deps = deps;
+    this.clock = deps.clock ?? realClock;
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.unsubscribe = this.deps.index.onChange(() => this.refresh());
+    this.refresh();
+  }
+
+  refresh(): void {
+    const ui = this.deps.getUi();
+    if (!ui) return;
+    const items = this.deps.index.list(this.clock.now());
+    const counts = this.deps.index.counts();
+    const activeAgents = items.filter((item) => item.kind === "agent" && isActive(item));
+    const total = counts.workers + counts.subagents + counts.monitors;
+    if (activeAgents.length > 0 && !this.ageTimer) {
+      this.ageTimer = this.clock.setInterval(() => this.tui?.requestRender(), 5000);
+      this.clock.unref?.(this.ageTimer);
+    } else if (activeAgents.length === 0) {
+      this.clearAgeTimer();
+    }
+    if (total === 0) {
+      this.clearWidget(ui);
+      return;
+    }
+    if (!this.widgetRegistered) {
+      ui.setWidget(
+        FLEET_WIDGET_KEY,
+        (tui, theme) => {
+          this.tui = tui;
+          this.widgetRegistered = true;
+          return {
+            render: (width) => this.renderLine(width, theme),
+            invalidate: () => {},
+            dispose: () => {
+              if (this.tui === tui) {
+                this.tui = null;
+                this.widgetRegistered = false;
+              }
+            },
+          };
+        },
+        { placement: "belowEditor" },
+      );
+      return;
+    }
+    this.tui?.requestRender();
+  }
+
+  dispose(): void {
+    this.started = false;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    const ui = this.deps.getUi();
+    this.clearAgeTimer();
+    if (ui) this.clearWidget(ui);
+  }
+
+  private clearAgeTimer(): void {
+    if (!this.ageTimer) return;
+    this.clock.clearInterval(this.ageTimer);
+    this.ageTimer = null;
+  }
+
+  private clearWidget(ui: FleetUi): void {
+    if (this.widgetRegistered || this.tui) {
+      ui.setWidget(FLEET_WIDGET_KEY, undefined, { placement: "belowEditor" });
+      this.widgetRegistered = false;
+      this.tui = null;
+    }
+  }
+
+  /**
+   * One line: `● 2 shells · 1 monitor · alpha 12s · beta 8s   /tasks`.
+   * Live work only: anything that exited, failed, or was killed drops out (its
+   * wake pill and /tasks already report it), and the line clears when idle.
+   */
+  private renderLine(width: number, theme: FleetTheme): string[] {
+    const now = this.clock.now();
+    const items = this.deps.index.list(now);
+    const counts = this.deps.index.counts();
+    const parts: string[] = [];
+    const summary = summaryLabel(counts.workers, 0, counts.monitors);
+    if (summary) parts.push(theme.fg("muted", summary));
+    for (const item of items.filter((i) => i.kind === "agent" && isActive(i))) {
+      const name = item.name ?? item.title;
+      parts.push(`${name} ${theme.fg("dim", formatAge(item.startedAt, item.endedAt, now))}`);
+    }
+    if (parts.length === 0) return [];
+    const line = `  ${theme.fg("accent", "●")} ${parts.join(theme.fg("dim", " · "))}   ${theme.fg("dim", "/tasks")}`;
+    return [truncateToWidth(line, Math.max(1, width), "…")];
+  }
+}
+
+/** @deprecated Use FleetWidget — kept as alias for older imports. */
+export { FleetWidget as FleetStatus };

package/src/subagent/model-spec.ts

@@ -0,0 +1,108 @@
+/**
+ * Fuzzy model spec resolution (design doc §4.6 "model resolution", appendix B).
+ *
+ * Pure and pi-free: candidates are plain {provider, id, name} records so the
+ * resolver is testable without a ModelRegistry. The caller decides the
+ * candidate set (scopedModels whitelist when non-empty, else all available).
+ *
+ * Spec grammar: `[provider/|provider:]id[:thinking]`
+ *   - thinking suffix: minimal|low|medium|high|xhigh (unrecognized suffixes
+ *     are treated as part of the id, e.g. OpenRouter's ":exacto")
+ *   - provider prefix: "provider/id" or "provider:id" both accepted
+ *   - bare id: exact unique match, else case-insensitive substring on id/name
+ */
+
+export interface ModelCandidate {
+  provider: string;
+  id: string;
+  name?: string;
+}
+
+export type ModelResolution =
+  | { ok: true; provider: string; id: string; thinking?: string }
+  | { ok: false; error: "no-match" | "ambiguous"; candidates: string[]; thinking?: string };
+
+const THINKING_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh"]);
+
+function label(c: ModelCandidate): string {
+  return `${c.provider}/${c.id}`;
+}
+
+/** Strip a trailing ":<thinking>" when it is a valid level. */
+export function splitThinkingSuffix(spec: string): { base: string; thinking?: string } {
+  const idx = spec.lastIndexOf(":");
+  if (idx <= 0 || idx === spec.length - 1) return { base: spec };
+  const suffix = spec.slice(idx + 1).toLowerCase();
+  if (!THINKING_LEVELS.has(suffix)) return { base: spec };
+  return { base: spec.slice(0, idx), thinking: suffix };
+}
+
+function splitProviderPrefix(spec: string): { provider: string; id: string } | null {
+  // "provider/id" or "provider:id" — first separator wins; the remainder may
+  // itself contain separators (model ids with colons, e.g. ":exacto").
+  for (const sep of ["/", ":"]) {
+    const idx = spec.indexOf(sep);
+    if (idx > 0 && idx < spec.length - 1) {
+      return { provider: spec.slice(0, idx), id: spec.slice(idx + 1) };
+    }
+  }
+  return null;
+}
+
+export function resolveModelSpec(spec: string, candidates: ModelCandidate[]): ModelResolution {
+  const { base, thinking } = splitThinkingSuffix(spec.trim());
+  if (base.length === 0) {
+    return { ok: false, error: "no-match", candidates: candidates.map(label), thinking };
+  }
+
+  // 1) provider-qualified exact match
+  const qualified = splitProviderPrefix(base);
+  if (qualified) {
+    const hit = candidates.find(
+      (c) => c.provider === qualified.provider && c.id === qualified.id,
+    );
+    if (hit) return { ok: true, provider: hit.provider, id: hit.id, thinking };
+    // Fall through: maybe the whole thing is a bare id containing a separator.
+  }
+
+  // 2) bare-id exact match (must be unique across providers)
+  const exact = candidates.filter((c) => c.id === base);
+  if (exact.length === 1) {
+    return { ok: true, provider: exact[0].provider, id: exact[0].id, thinking };
+  }
+  if (exact.length > 1) {
+    return { ok: false, error: "ambiguous", candidates: exact.map(label), thinking };
+  }
+
+  // 3) case-insensitive substring on id or display name
+  const needle = base.toLowerCase();
+  const fuzzy = candidates.filter(
+    (c) =>
+      c.id.toLowerCase().includes(needle) ||
+      (c.name !== undefined && c.name.toLowerCase().includes(needle)),
+  );
+  if (fuzzy.length === 1) {
+    return { ok: true, provider: fuzzy[0].provider, id: fuzzy[0].id, thinking };
+  }
+  if (fuzzy.length > 1) {
+    return { ok: false, error: "ambiguous", candidates: fuzzy.map(label), thinking };
+  }
+  return { ok: false, error: "no-match", candidates: candidates.map(label), thinking };
+}
+
+/** Render a resolution failure as an actionable error message. */
+export function modelResolutionError(spec: string, res: ModelResolution & { ok: false }): string {
+  const list = res.candidates.slice(0, 20).join(", ");
+  const more = res.candidates.length > 20 ? `, … +${res.candidates.length - 20} more` : "";
+  if (res.error === "ambiguous") {
+    return (
+      `model spec "${spec}" is ambiguous (matches: ${list}${more}). ` +
+      `Qualify with "provider/<id>".`
+    );
+  }
+  return (
+    `model spec "${spec}" matched nothing. ` +
+    `Available: ${list || "none"}${more}. ` +
+    `Use subagent({action:"models"}) to list selectable models.`
+  );
+}