pi-famulus 0.1.9 → 0.2.1

package/src/subagent/tool.ts

@@ -140,6 +140,10 @@ export interface SubagentToolDeps {
   /** Agent definition resolver (M5 wires the real loader; default: worker). */
   resolveAgent?: (name: string | undefined) => AgentDefinition;
   /** Selectable models for action:"models" (§4.6); absent → action errors. */
+  /** Receives the watcher for turns started by agent_message send. */
+  registerResumeWatch?: (watch: (childId: string) => void) => void;
+  /** Rebuild a child this session no longer holds so resume can use child_id. */
+  recoverChild?: (childId: string) => Promise<RunRecord | undefined>;
   listModels?: () => {
     provider: string;
     id: string;
@@ -226,6 +230,8 @@ function toNotificationInfo(record: RunRecord, now: number) {
       status: c.status,
       text: c.result?.text ?? "",
       error: c.result?.error,
+      ...(c.result?.endReason !== undefined ? { endReason: c.result.endReason } : {}),
+      ...(c.result?.retryAfter !== undefined ? { retryAfter: c.result.retryAfter } : {}),
       ...(c.result?.warning !== undefined ? { warning: c.result.warning } : {}),
       ...(c.prompt !== undefined ? { prompt: c.prompt } : {}),
     })),
@@ -346,6 +352,20 @@ export function createSubagentTool(
     return true;
   };
 
+  const armResumeWake = (childId: string): void => {
+    const registry = deps.getRegistry();
+    if (!registry) return;
+    const record = registry.list().find((run) => run.children.some((c) => c.childId === childId));
+    if (!record) return;
+    const handedOver = new Set<string>();
+    void registry.getResult(childId)?.then(() => {
+      if (!notifyChildHandover(registry, record.runId, childId, handedOver)) {
+        notifyRunCompleted(registry, record.runId);
+      }
+    });
+  };
+  deps.registerResumeWatch?.(armResumeWake);
+
   const startRun = async (
     params: SubagentParams,
     signal: AbortSignal | undefined,
@@ -547,7 +567,23 @@ export function createSubagentTool(
       };
     }
 
-    const record = requireRun(registry, params.run_id);
+    let record = params.run_id
+      ? requireRun(registry, params.run_id)
+      : params.child_id
+        ? resolveRunByChild(registry, params.child_id)
+        : undefined;
+    if (params.child_id && !params.run_id && action === "resume" && deps.recoverChild &&
+      (!record || !registry.findChild(record.runId, params.child_id))) {
+      record =
+        await deps.recoverChild(params.child_id);
+    }
+    if (!record) {
+      if (params.child_id && !params.run_id) {
+        throw new Error(`unknown child "${params.child_id}" (no run in this session holds it)`);
+      }
+      requireRun(registry, params.run_id);
+      throw new Error("run_id is required for this action");
+    }
 
     if (action === "get") {
       return {
@@ -585,18 +621,45 @@ export function createSubagentTool(
         const known = record.children.map((c) => `${c.name} (${c.childId})`).join(", ");
         throw new Error(`no child "${params.child_id}" in run ${record.runId} (children: ${known})`);
       }
+      const idle = record.children.filter((c) => {
+        if (params.child_id && c.childId !== params.child_id && c.name !== params.child_id) return false;
+        return c.status === "completed" || c.status === "failed" || c.status === "interrupted";
+      });
       for (const child of targets) {
         await registry.handle(child.childId)?.interrupt();
       }
-      const scope = params.child_id ? `subagent ${params.child_id}` : `${targets.length} subagent(s)`;
+      for (const child of idle) {
+        await registry.handle(child.childId)?.interrupt();
+      }
+      const interrupted = [...targets, ...idle].map((c) => c.childId);
+      const scope = params.child_id ? `subagent ${params.child_id}` : `${interrupted.length} subagent(s)`;
       return {
         content: [{ type: "text", text: `Interrupted ${scope} in run ${record.runId}.` }],
-        details: { run_id: record.runId, interrupted: targets.map((c) => c.childId) },
+        details: { run_id: record.runId, interrupted },
       };
     }
 
     if (action === "steer") {
       if (!params.message) throw new Error("message is required for steer");
+      const named = params.child_id
+        ? record.children.find((c) => c.childId === params.child_id || c.name === params.child_id)
+        : record.children.length === 1 ? record.children[0] : undefined;
+      if (named && named.status !== "running" && named.status !== "pending") {
+        const { queuedBehind } = await registry.resumeChild(named.childId, params.message);
+        armResumeWake(named.childId);
+        return {
+          content: [{
+            type: "text",
+            text: fill("tools.subagent.result.resumed", {
+              name: named.name,
+              childId: named.childId,
+              runId: record.runId,
+              queued: queuedText(queuedBehind),
+            }),
+          }],
+          details: { run_id: record.runId, child_id: named.childId, queued_behind: queuedBehind },
+        };
+      }
       const handle = resolveSingleActiveChild(registry, record, params.child_id, "steer");
       await handle.steer(params.message);
       return {
@@ -645,12 +708,7 @@ export function createSubagentTool(
     );
     // Resume is asynchronous. If siblings are still running, hand this child
     // back as soon as it finishes; otherwise the run-complete wake covers it.
-    const handedOver = new Set<string>();
-    void registry.getResult(child.childId)?.then(() => {
-      if (!notifyChildHandover(registry, record.runId, child.childId, handedOver)) {
-        notifyRunCompleted(registry, record.runId);
-      }
-    });
+    armResumeWake(child.childId);
     return {
       content: [
         {
@@ -733,6 +791,18 @@ export function createSubagentTool(
   };
 }
 
+function resolveRunByChild(registry: SubagentRegistry, childIdOrName: string) {
+  const runs = registry.list();
+  const byId = runs.filter((run) => run.children.some((c) => c.childId === childIdOrName));
+  if (byId.length === 1) return byId[0];
+  const byName = runs.filter((run) => run.children.some((c) => c.name === childIdOrName));
+  if (byName.length > 1) {
+    const ids = byName.map((run) => run.runId).join(", ");
+    throw new Error(`child name "${childIdOrName}" is in more than one run (${ids}); pass run_id`);
+  }
+  return byName[0];
+}
+
 /** Resume result clause for a turn waiting for an admission slot ("" when it started at once). */
 function queuedText(queuedBehind: number | null): string {
   if (queuedBehind === null) return "";

package/src/subagent/types.ts

@@ -46,7 +46,9 @@ export interface ChildResult {
   /** 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";
+  endReason?: "model-error" | "rate-limit";
+  /** Seconds until a rate-limited provider may be retried, when known. */
+  retryAfter?: number;
   /**
    * Total generations run (1 + resumes + stall retries). Omitted when 1.
    * Note: a user resume() also increments this; use `stalls` to count
@@ -102,6 +104,9 @@ export interface ChildSessionEvent {
   role?: string;
   /** Pi's stable tool-call id, used to pair execution start/end events. */
   toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  isError?: boolean;
   usage?: ChildTokenUsage;
 }
 
@@ -135,6 +140,8 @@ export interface ChildHandle {
   tokenUsage(): ChildTokenUsage;
   /** Cumulative observed LLM, tool, admission-queue and approximate wall time. */
   wallUsage(): ChildWallUsage;
+  /** Hosted-process view, when this child runs as `pi --mode rpc`. */
+  hosting?(): { residency?: string; driver?: string; cacheExpiresAt?: number; sessionFile?: string; sessionId?: string } | undefined;
 }
 
 /**
@@ -176,6 +183,8 @@ export type CreateSessionFn = (req: ChildRunRequest) => Promise<ChildSessionAdap
 
 export interface ChildRunner {
   start(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<ChildHandle>;
+  /** Reattach a child the daemon still hosts, without sending its first prompt. */
+  attach?(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<ChildHandle>;
 }
 
 /**

package/src/tui/attach-command.ts

@@ -0,0 +1,164 @@
+/**
+ * `/attach <child>`: talk to a hosted subagent through the daemon, in the pi TUI.
+ * Lines are the child's transcript; Enter sends a prompt (steered while it runs).
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ManagerClient } from "../manager-client";
+import type { SubagentRegistry } from "../subagent/registry";
+import { fitLines, loadPiTui } from "./pi-tui-load";
+
+export interface AttachCommandDeps {
+  getClient: () => ManagerClient | null;
+  getRegistry: () => SubagentRegistry | null;
+}
+
+export function registerAttachCommand(pi: ExtensionAPI, deps: AttachCommandDeps): void {
+  pi.registerCommand("attach", {
+    description: "Talk to a hosted subagent (child id)",
+    getArgumentCompletions: () => {
+      const children = deps.getRegistry()?.list().flatMap((run) => run.children.map((child) => child.childId)) ?? [];
+      return children.map((id) => ({ value: id, label: id }));
+    },
+    handler: async (args, ctx) => {
+      const childId = args.trim();
+      if (!childId) {
+        ctx.ui.notify("Usage: /attach <child id>", "warning");
+        return;
+      }
+      const client = deps.getClient();
+      if (!client?.isAvailable() || client.protocolLevel() < 6) {
+        ctx.ui.notify("Hosted subagents need a connected pi-famulus daemon (protocol 6).", "error");
+        return;
+      }
+      if (!ctx.hasUI || ctx.mode !== "tui") {
+        ctx.ui.notify(`Attach from a terminal with: pi-famulus attach ${childId}`, "info");
+        return;
+      }
+      await openAttachView(ctx, client, childId);
+    },
+  });
+}
+
+interface EntryMessage {
+  role?: string;
+  content?: string | { text?: string }[];
+  message?: EntryMessage;
+}
+
+function textOf(message: EntryMessage | undefined): string {
+  const content = message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => (typeof part === "string" ? part : part?.text ?? "")).join("");
+}
+
+function linesFromEntries(entries: unknown): string[] {
+  if (!Array.isArray(entries)) return [];
+  const out: string[] = [];
+  for (const entry of entries as EntryMessage[]) {
+    const message = entry.message ?? entry;
+    const text = textOf(message);
+    if (!text) continue;
+    if (message.role === "user") out.push(`you: ${text}`);
+    else if (message.role === "assistant") out.push(text);
+  }
+  return out;
+}
+
+/** Live transcript for one hosted child. Closing does not respawn a parked child. */
+export async function openAttachView(ctx: ExtensionContext, client: ManagerClient, childId: string): Promise<void> {
+  const piTui = loadPiTui();
+  if (!piTui) {
+    ctx.ui.notify(`pi-famulus attach ${childId}`, "info");
+    return;
+  }
+  await client.agentWatch(childId).catch((err: unknown) => {
+    throw new Error(err instanceof Error ? err.message : String(err));
+  });
+  const seeded = await client.agentInput(childId, "get_entries", "", "parent").catch(() => null);
+  const state = await client.agentInput(childId, "get_state", "", "parent").catch(() => null);
+  const lines: string[] = [`attached to ${childId}`, ""];
+  lines.push(...linesFromEntries(seeded?.entries));
+  let input = "";
+  let activity = state?.isStreaming === true ? "running" : "idle";
+  let status = activity;
+  let requestRender: (() => void) | null = null;
+  const unsub = client.onEvent((event) => {
+    const hosted = event as {
+      event?: string;
+      child_id?: string;
+      record?: { type?: string; message?: { role?: string; content?: { text?: string }[] } };
+      activity?: string;
+      residency?: string;
+      driver?: string;
+    };
+    if (hosted.child_id !== childId) return;
+    if (hosted.event === "agent_state") {
+      activity = hosted.activity ?? activity;
+      status = `${hosted.activity ?? "?"} · ${hosted.residency ?? "?"} · ${hosted.driver ?? "parent"}`;
+      requestRender?.();
+      return;
+    }
+    if (hosted.event !== "agent_rpc" || !hosted.record) return;
+    const record = hosted.record;
+    if (record.type === "message_end" && record.message?.role === "assistant") {
+      const text = textOf(record.message);
+      if (text) lines.push(text);
+    } else if (record.type === "agent_start") {
+      activity = "running";
+      lines.push("…");
+    }
+    requestRender?.();
+  });
+  try {
+    await ctx.ui.custom<void>((tui, _theme, _kb, done) => {
+      requestRender = () => tui.requestRender();
+      return {
+        render(width: number) {
+          const limit = Math.max(1, width);
+          const rows = Math.max(4, (tui.terminal?.rows ?? 24) - 6);
+          const body = lines.flatMap((line) => fitLines(line, limit)).slice(-rows);
+          return [
+            `◆ ${childId}  ${status}`,
+            ...body,
+            "",
+            `› ${input}`,
+            "enter send   esc close",
+          ];
+        },
+        invalidate() {},
+        handleInput(data: string) {
+          if (data === "\u001b") {
+            done();
+            return;
+          }
+          if (data === "\r" || data === "\n") {
+            const text = input;
+            input = "";
+            if (!text.trim()) return;
+            lines.push(`you: ${text}`);
+            const op = activity === "running" ? "prompt_steer" : "prompt";
+            void client.agentInput(childId, op, text, "user").catch((err: unknown) => {
+              lines.push(err instanceof Error ? err.message : String(err));
+              requestRender?.();
+            });
+            tui.requestRender();
+            return;
+          }
+          if (data === "\u007f" || data === "\b") {
+            input = input.slice(0, -1);
+            tui.requestRender();
+            return;
+          }
+          if (data.length === 1 && data >= " ") {
+            input += data;
+            tui.requestRender();
+          }
+        },
+      };
+    });
+  } finally {
+    unsub();
+    await client.agentUnwatch(childId).catch(() => {});
+  }
+}

package/src/work-index.ts

@@ -11,6 +11,12 @@ export type WorkKind = "shell" | "monitor" | "agent";
 export const WORK_RETAIN_MS = 10 * 60 * 1000;
 export const WORK_FINISHED_CAP = 50;
 
+/** stderr line when print mode drops live work and still exits 0. */
+export function printModeDropWarning(ids: string[]): string | null {
+  if (ids.length === 0) return null;
+  return `pi-famulus: print mode is ending; stopping ${ids.length} background item(s) (${ids.join(", ")}). The process still exits 0.\n`;
+}
+
 export interface WorkItem {
   id: string;
   kind: WorkKind;