pi-famulus 0.1.9 → 0.2.1

package/src/manager-client.ts

@@ -18,10 +18,10 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.9";
+const EXTENSION_VERSION = "0.2.1";
 export { EXTENSION_VERSION };
 // 5: speaks per-kind agent admission and queued acquire.
-const PROTOCOL = 5;
+const PROTOCOL = 6;
 const HELLO_TIMEOUT_MS = 5000;
 const RECONNECT_HELLO_TIMEOUT_MS = 25_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
@@ -124,6 +124,8 @@ export interface ManagerEvent {
   output_size?: number;
   end_reason?: string;
   ts?: number;
+  /** Set on task_started when the daemon recorded who asked for the task. */
+  origin?: { via: string; child_id?: string; run_id?: string };
 }
 
 export class ManagerError extends Error {
@@ -142,6 +144,12 @@ export interface ManagerClientOptions {
   piPid?: number;
   /** Session working directory, sent on hello (optional; older managers ignore it). */
   cwd?: string;
+  /** `parent` for a pi session, `child` for pi-famulus inside a hosted subagent. */
+  role?: "parent" | "child";
+  childId?: string;
+  token?: string;
+  /** Pi session file this process has open. */
+  sessionFile?: string;
   log?: (message: string) => void;
   clock?: Clock;
 }
@@ -288,6 +296,10 @@ export class ManagerClient {
   private managerPath: string | null;
   private readonly piPid: number;
   private readonly cwd: string | undefined;
+  private readonly role: "parent" | "child";
+  private readonly childId: string | undefined;
+  private readonly token: string | undefined;
+  private readonly sessionFile: string | undefined;
   private readonly log: (message: string) => void;
   private readonly clock: Clock;
 
@@ -315,6 +327,10 @@ export class ManagerClient {
     this.managerPath = options.managerPath;
     this.piPid = options.piPid ?? process.pid;
     this.cwd = options.cwd;
+    this.role = options.role ?? "parent";
+    this.childId = options.childId;
+    this.token = options.token;
+    this.sessionFile = options.sessionFile;
     this.log = options.log ?? (() => {});
     this.clock = options.clock ?? realClock;
   }
@@ -458,20 +474,140 @@ export class ManagerClient {
     childId: string,
     workKind = "other",
     signal?: AbortSignal,
-  ): Promise<{ granted: boolean; rejection?: string }> {
+  ): Promise<{ granted: boolean; rejection?: string; queuedBehind?: number }> {
     if (signal?.aborted) throw new Error("subagent admission cancelled");
     const message: Record<string, unknown> = { type: "acquire_agent", child_id: childId };
     if (this.protocolLevel_ >= 5) message.work_kind = workKind;
     // Protocol 4 has no cancel frame. Keep its immediate acquire correlated so
     // admission can release a grant that arrives after the generation aborts.
     const res = await this.request(message, DEFAULT_REQUEST_TIMEOUT_MS, this.protocolLevel_ >= 5 ? signal : undefined, true);
-    return { granted: res.granted === true, ...(typeof res.rejection === "string" ? { rejection: res.rejection } : {}) };
+    return {
+      granted: res.granted === true,
+      ...(typeof res.rejection === "string" ? { rejection: res.rejection } : {}),
+      ...(typeof res.queued_behind === "number" ? { queuedBehind: res.queued_behind } : {}),
+    };
   }
 
   async releaseAgent(childId: string): Promise<void> {
     await this.request({ type: "release_agent", child_id: childId });
   }
 
+  requireHostedProtocol(): void {
+    if (this.protocolLevel_ < 6) {
+      throw new Error(
+        "this pi-famulus daemon does not host subagents (protocol " +
+          `${this.protocolLevel_}; need 6). Restart pi so it starts the current daemon.`,
+      );
+    }
+  }
+
+  async agentSpawn(input: {
+    childId: string;
+    runId: string;
+    name: string;
+    argv: string[];
+    cwd: string;
+    env: Record<string, string>;
+  }): Promise<Record<string, unknown>> {
+    this.requireHostedProtocol();
+    return this.request({
+      type: "agent_spawn",
+      child_id: input.childId,
+      run_id: input.runId,
+      name: input.name,
+      argv: input.argv,
+      cwd: input.cwd,
+      env: input.env,
+    }, 20_000);
+  }
+
+  async agentInput(childId: string, op: string, text: string, source = "parent", since?: string): Promise<Record<string, unknown>> {
+    this.requireHostedProtocol();
+    return this.request({
+      type: "agent_input",
+      child_id: childId,
+      op,
+      text,
+      source,
+      ...(since ? { since } : {}),
+    }, 20_000);
+  }
+
+  async agentWatch(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_watch", child_id: childId });
+  }
+
+  async agentUnwatch(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_unwatch", child_id: childId });
+  }
+
+  async agentPeers(): Promise<Array<{ childId: string; name: string; runId: string; activity: string; residency: string }>> {
+    this.requireHostedProtocol();
+    const res = await this.request({ type: "agent_peers" });
+    const peers = Array.isArray(res.peers) ? res.peers : [];
+    return peers.flatMap((peer) => {
+      if (!peer || typeof peer !== "object") return [];
+      const row = peer as Record<string, unknown>;
+      if (typeof row.child_id !== "string") return [];
+      return [{
+        childId: row.child_id,
+        name: typeof row.name === "string" ? row.name : row.child_id,
+        runId: typeof row.run_id === "string" ? row.run_id : "",
+        activity: typeof row.activity === "string" ? row.activity : "idle",
+        residency: typeof row.residency === "string" ? row.residency : "",
+      }];
+    });
+  }
+
+  async agentPark(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_park", child_id: childId });
+  }
+
+  async agentTakeover(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_takeover", child_id: childId });
+  }
+
+  async hostedLookup(query: { sessionId?: string; sessionFile?: string }): Promise<Record<string, unknown> | null> {
+    if (this.protocolLevel_ < 6) return null;
+    const res = await this.request({
+      type: "hosted_lookup",
+      ...(query.sessionId ? { session_id: query.sessionId } : {}),
+      ...(query.sessionFile ? { session_file: query.sessionFile } : {}),
+    });
+    const hosted = res.hosted;
+    return hosted && typeof hosted === "object" ? hosted as Record<string, unknown> : null;
+  }
+
+  async agentComms(requestId: string, reason: string, message: string): Promise<string> {
+    this.requireHostedProtocol();
+    const res = await this.request({ type: "agent_comms", request_id: requestId, reason, message }, 11 * 60 * 1000);
+    return typeof res.reply === "string" ? res.reply : "";
+  }
+
+  async agentCommsReply(requestId: string, childId: string, message: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_comms_reply", request_id: requestId, child_id: childId, message });
+  }
+
+  async agentUiResponse(childId: string, rpcId: string, value: Record<string, unknown>, cancelled: boolean): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_ui_response", child_id: childId, rpc_id: rpcId, value, cancelled });
+  }
+
+  async agentCache(expiresAt: number | null, tier: string | null, lifetimeMs: number | null): Promise<void> {
+    if (this.protocolLevel_ < 6) return;
+    await this.request({
+      type: "agent_cache",
+      ...(expiresAt !== null ? { expires_at: expiresAt } : {}),
+      ...(tier ? { tier } : {}),
+      ...(lifetimeMs !== null ? { lifetime_ms: lifetimeMs } : {}),
+    });
+  }
+
   /** Daemon status, including optional in-place upgrade metadata. */
   async status(): Promise<ManagerStatusResponse> {
     const res = await this.request({ type: "status" });
@@ -501,6 +637,8 @@ export class ManagerClient {
   async close(): Promise<void> {
     this.intentionalClose = true;
     this.state = "disconnected";
+    this.eventHandlers.clear();
+    this.reconnectHandlers.clear();
     this.failAllPending(new Error("manager client closed"));
     const socket = this.socket;
     this.socket = null;
@@ -774,6 +912,10 @@ export class ManagerClient {
           ...(this.cwd ? { cwd: this.cwd } : {}),
           extension_version: EXTENSION_VERSION,
           protocol: PROTOCOL,
+          role: this.role,
+          ...(this.sessionFile ? { session_file: this.sessionFile } : {}),
+          ...(this.childId ? { child_id: this.childId } : {}),
+          ...(this.token ? { token: this.token } : {}),
         }),
       );
     });
@@ -865,7 +1007,7 @@ export class ManagerClient {
     waitForAdmission = false,
   ): Promise<Record<string, unknown>> {
     const type = String(msg.type);
-    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start", "acquire_agent", "cancel_acquire_agent", "release_agent"].includes(type);
+    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start", "acquire_agent", "cancel_acquire_agent", "release_agent", "agent_spawn", "agent_watch", "agent_park", "agent_peers", "hosted_lookup"].includes(type);
     const effectiveTimeoutMs = retryable ? Math.max(timeoutMs, RECONNECT_WINDOW_MS + 1000) : timeoutMs;
     return new Promise((resolve, reject) => {
       if (signal?.aborted) {

package/src/notify.ts

@@ -311,4 +311,5 @@ export class NotifyCenter {
     }
     onDelivered?.(sourcePreview ?? (details?.kind === "monitor" ? (message.details as { event?: string }).event : undefined));
   }
+
 }

package/src/pi-command.ts

@@ -0,0 +1,123 @@
+/**
+ * Find the pi command a hosted subagent should be. The daemon never searches
+ * PATH; the extension resolves it where pi is already running.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename } from "node:path";
+export type PiCommand = { argv: string[] } | { error: string };
+
+export function resolvePiArgv(configured?: string | null, argv: readonly string[] = process.argv): PiCommand {
+  const raw = (configured && configured.trim()) || process.env.PI_FAMULUS_PI?.trim() || "";
+  if (raw) {
+    if (raw.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(raw) as unknown;
+        if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((part) => typeof part === "string" && part.length > 0)) {
+          return { argv: parsed as string[] };
+        }
+      } catch {
+        return { error: `PI_FAMULUS_PI / subagent.piCommand is not a JSON argv array: ${raw}` };
+      }
+      return { error: `PI_FAMULUS_PI / subagent.piCommand is not a JSON argv array: ${raw}` };
+    }
+    return { argv: raw.includes(" ") ? splitCommand(raw) : [raw] };
+  }
+  const fromProcess = runningPiArgv(argv);
+  if (fromProcess) return { argv: fromProcess };
+  const exec = process.execPath;
+  try {
+    const req = createRequire(import.meta.url);
+    const pkg = req.resolve("@earendil-works/pi-coding-agent/package.json");
+    const cli = pkg.replace(/package\.json$/, "dist/cli.js");
+    if (existsSync(cli)) return { argv: [exec, cli] };
+  } catch {
+    // The host did not load pi as a resolvable package.
+  }
+  return {
+    error:
+      "cannot find the pi executable that is running this session. Set subagent.piCommand in config.json or PI_FAMULUS_PI to the pi command.",
+  };
+}
+
+const PARENT_FLAGS = new Set([
+  "-ne",
+  "--no-extensions",
+  "-ns",
+  "--no-skills",
+  "-np",
+  "--no-prompt-templates",
+  "-nc",
+  "--no-context-files",
+  "--offline",
+  "--no-mcp",
+]);
+
+/**
+ * Flags from the pi process that is spawning the subagent. The child is a new
+ * process, so it only sees providers and tools that its own command line loads.
+ * Eval and SDK hosts pass those as `-e` on argv (`-ne` plus an explicit faux
+ * provider extension); forwarding them is what lets the child use the same model.
+ */
+export function parentResourceArgs(argv: readonly string[] = process.argv.slice(2)): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-e" || arg === "--extension") {
+      const value = argv[i + 1];
+      if (value && !value.startsWith("-")) {
+        out.push("-e", value);
+        i++;
+      }
+      continue;
+    }
+    if (PARENT_FLAGS.has(arg)) out.push(arg);
+  }
+  return out;
+}
+
+/**
+ * The pi process that loaded this extension. `node_modules/.bin/pi` is a
+ * symlink (eval and `npm exec`); its path does not contain `pi-coding-agent`,
+ * so matching only that substring misses the process that is actually running.
+ */
+function runningPiArgv(argv: readonly string[]): string[] | null {
+  const entry = argv[1] ?? "";
+  if (!entry || !existsSync(entry)) return null;
+  let real = entry;
+  try {
+    real = realpathSync(entry);
+  } catch {
+    // A broken symlink still has a path; keep the original.
+  }
+  const base = basename(entry).toLowerCase();
+  const namedPi = base === "pi" || base === "pi.cmd" || base === "pi.exe" || entry.includes("pi-coding-agent") || real.includes("pi-coding-agent");
+  if (!namedPi) return null;
+  if (/\.[cm]?js$/i.test(real)) return [process.execPath, real];
+  return [entry];
+}
+
+function splitCommand(raw: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  for (const ch of raw) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === " ") {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current) parts.push(current);
+  return parts;
+}

package/src/prompts.generated.ts

@@ -5,16 +5,16 @@ export const PROMPTS = {
   "agents.explorer.system-prompt": "You are an explorer agent. Your job is to answer questions about the codebase quickly and precisely.\n\nRules:\n- Return findings, never change code. You are strictly read-only: do not edit, write, or create files.\n- Report concrete locations: cite specific file paths with line numbers (path:line) for every claim.\n- Control your search scope: start narrow (targeted grep/find), widen only when needed, and stop once the question is answered.\n- Prefer a short, factual summary over exhaustive dumps. List what you found and where.",
   "agents.worker.description": "General-purpose executor — completes concrete coding tasks end to end",
   "agents.worker.system-prompt": "You are a worker agent. Your job is to complete the concrete task you were given, end to end.\n\nRules:\n- Do the task, don't just describe it. Make the actual edits and run the actual commands.\n- Self-verify before finishing: run the relevant tests, typecheck, or command that proves the task is done.\n- Stay within the task's scope; do not refactor unrelated code.\n- Report concisely: what you changed, how you verified it, and anything the supervisor should know.",
-  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- 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.\n- 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. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- 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.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- 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.",
+  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- 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.\n- 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. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- 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.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- Use agent_message to steer a running subagent or to continue an idle one (send starts a new turn), and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). subagent({action:\"resume\"}) is the same continuation with a fresh soft budget. Supervisor wakes are not user messages — still act on them.",
   "guidelines.monitor-idle": "After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield.",
   "guidelines.child": "## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result.",
-  "tools.agent_message.description": "Message your subagents. \"send\" steers or queues a running child. Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). \"reply\" answers a child's pending decision request; \"broadcast\" steers every running child of a run (to = run_id); \"list\" shows children, pending decision requests, and recent traffic.",
+  "tools.agent_message.description": "Message your subagents. \"send\" steers or queues a running child, and starts a new turn on an idle one. An idle child (warm or parked) continues with send or subagent resume; its prompt cache stays warm only for the time a wake reports. \"reply\" answers a child's pending decision request; \"broadcast\" steers every running child of a run (to = run_id); \"list\" shows children, pending decision requests, and recent traffic.",
   "tools.agent_message.snippet": "Send/reply/broadcast messages to subagents",
   "tools.agent_message.param.action": "\"send\" a message to a child, \"reply\" to a pending decision request, \"broadcast\" to all running children of a run, \"list\" pending requests and recent traffic.",
   "tools.agent_message.param.to": "Target child_id or name (\"send\"/\"reply\"). For \"broadcast\" from the parent session: run_id. Child sessions broadcast to their own run and must omit this.",
   "tools.agent_message.param.message": "Message text.",
-  "tools.agent_message.param.delivery": "\"steer\" (default) delivers to a running child after its current tool call/turn finishes; \"queue\" delivers after its current turn. Sending to a finished child is an error — resume with subagent({action:\"resume\"}).",
-  "tools.agent_message.error.finished-child": "Child {{childId}} ({{name}}) has finished ({{status}}). agent_message does not resume children. Use subagent({ action: \"resume\", run_id: \"{{runId}}\", child_id: \"{{childId}}\", message: \"...\" }).",
+  "tools.agent_message.param.delivery": "\"steer\" (default) delivers to a running child after its current tool call/turn finishes; \"queue\" delivers after its current turn. Sending to an idle child starts a new turn.",
+  "tools.agent_message.error.finished-child": "Child {{childId}} ({{name}}) has finished ({{status}}), and this host cannot start another turn. Use subagent({ action: \"resume\", run_id: \"{{runId}}\", child_id: \"{{childId}}\", message: \"...\" }).",
   "tools.bash.description": "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last {{maxLines}} lines or {{maxKb}}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.",
   "tools.bash.snippet": "Execute bash commands (ls, grep, find, etc.)",
   "tools.bash.rules": ["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."],
@@ -23,7 +23,7 @@ export const PROMPTS = {
   "tools.bash.param.run_in_background": "Start the command in the background and return immediately. You will be notified when it completes.",
   "tools.bash.result.backgrounded": "Command \"{{command}}\" moved to background (task_id: {{taskId}}). Output: {{outputPath}}.\nYou 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.",
   "tools.bash.error.bare-sleep": "Refusing to run a bare sleep/idle-loop command: {{command}}. 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.",
-  "tools.child.agent_message.description": "Message sibling subagents in your run, or list pending requests. \"send\" delivers to a running sibling. Sending to a finished sibling errors and does not resume it; resume with subagent({ action: \"resume\", run_id, child_id, message }). \"broadcast\" steers every running sibling in your run; \"list\" shows pending decision requests and recent traffic. Cross-run messaging is rejected.",
+  "tools.child.agent_message.description": "Message sibling subagents in your run, or list pending requests. \"send\" delivers to a running sibling and starts a new turn on an idle one. \"broadcast\" steers every running sibling in your run; \"list\" shows pending decision requests and recent traffic. Cross-run messaging is rejected.",
   "tools.child.agent_message.snippet": "Message sibling subagents in your run",
   "tools.child.bash.description": "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last {{maxLines}} lines or {{maxKb}}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.",
   "tools.child.bash.snippet": "Execute bash commands (ls, grep, find, etc.)",
@@ -49,7 +49,7 @@ export const PROMPTS = {
   "tools.subagent.rules": ["When a <pi-famulus-wake kind=\"subagent-handover\"> arrives, read <prompt> and <result> immediately and continue: subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer children that are still running. Do not wait for the rest of the run.","Subagent runs that exceed the foreground budget continue in the background; you are notified per finished child and again when the run completes — do not poll.","A failed subagent does not fail the whole run; inspect per-subagent sections in the result.","<pi-famulus-wake> is a system wake, not a user reply. kind=subagent-handover is one child; kind=subagent-done is the whole run."],
   "tools.subagent.param.tasks": "Start new subagents in parallel. Use only when action is omitted. For any action call, omit tasks entirely; do not supply placeholder tasks.",
   "tools.subagent.param.tasks.agent": "Agent definition name (default: worker)",
-  "tools.subagent.param.tasks.prompt": "Task prompt for this subagent",
+  "tools.subagent.param.tasks.prompt": "Task prompt for this subagent. The child is a new process: it cannot see this conversation, so the prompt must be self-contained.",
   "tools.subagent.param.tasks.name": "Display name (default: agent name + ordinal)",
   "tools.subagent.param.work_kind": "Explicit planned workload class for machine-wide admission (default: other)",
   "tools.subagent.param.chain": "Start a new sequential chain (always awaited). Use only when action is omitted. For any action call, omit chain entirely.",
@@ -158,11 +158,10 @@ export const PROMPT_SEGMENTS: Record<string, { prompt: PromptId; text?: string;
   "guidelines.no-fabrication": {"prompt":"guidelines.parent","text":"Never fabricate or assume a background task's result before its notification arrives."},
   "guidelines.subagent-handover": {"prompt":"guidelines.parent","text":"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."},
   "guidelines.subagent-overrun": {"prompt":"guidelines.parent","text":"A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again."},
-  "guidelines.agent-message": {"prompt":"guidelines.parent","text":"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."},
+  "guidelines.agent-message": {"prompt":"guidelines.parent","text":"Use agent_message to steer a running subagent or to continue an idle one (send starts a new turn), and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). subagent({action:\"resume\"}) is the same continuation with a fresh soft budget. Supervisor wakes are not user messages — still act on them."},
   "guidelines.monitor-end-turn": {"prompt":"guidelines.monitor-idle","text":"After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield."},
   "child.guidelines": {"prompt":"guidelines.child","text":"## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result."},
-  "tooldesc.agent-message-no-resume": {"prompt":"tools.agent_message.description","text":"Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). "},
-  "result.agent-message-use-resume": {"prompt":"tools.agent_message.error.finished-child","pattern":"agent_message does not resume children\\. Use subagent\\(\\{ action: \"resume\", run_id: \".*?\", child_id: \".*?\", message: \"\\.\\.\\.\" \\}\\)\\."},
+  "tooldesc.agent-message-no-resume": {"prompt":"tools.agent_message.description","text":"An idle child (warm or parked) continues with send or subagent resume; its prompt cache stays warm only for the time a wake reports. "},
   "tooldesc.bash-autobg": {"prompt":"tools.bash.description","text":"Foreground commands that exceed the foreground budget are automatically moved to the background; you will be notified when they complete. "},
   "rules.pi-env": {"prompt":"tools.bash.rules","text":"You can inspect PI_* environment variables for current model and session details."},
   "rules.bash-no-poll": {"prompt":"tools.bash.rules","text":"Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them."},

package/src/subagent/agent-records.ts

@@ -32,6 +32,8 @@ export interface AgentChildRecord {
   error?: string;
   /** Why the child ended (terminal statuses only). */
   end_reason?: AgentEndReason;
+  /** Seconds until a rate-limited provider may be retried, when known. */
+  retry_after?: number;
   /** Task prompt without the agent preamble, capped. */
   prompt_head?: string;
   /** Tail of the final result text, capped. */
@@ -58,6 +60,7 @@ export type AgentEndReason =
   | "completed"
   | "failed"
   | "model-error"
+  | "rate-limit"
   | "stalled"
   | "timeout"
   | "interrupted"
@@ -66,10 +69,11 @@ export type AgentEndReason =
 /** Map a terminal child status + result to the end_reason recorded on disk. */
 export function agentEndReason(
   status: AgentChildRecord["status"],
-  result: { error?: string; endReason?: "model-error" } | undefined,
+  result: { error?: string; endReason?: "model-error" | "rate-limit" } | undefined,
 ): AgentEndReason | undefined {
   if (status === "completed") return "completed";
   if (status === "failed") {
+    if (result?.endReason === "rate-limit") return "rate-limit";
     if (result?.endReason === "model-error") return "model-error";
     return result?.error === "stalled" ? "stalled" : "failed";
   }
@@ -174,6 +178,42 @@ function parseRecord(raw: string): AgentChildRecord | null {
 }
 
 /** Load agent child records from disk (all sessions under home). */
+/** Hosted children the daemon still has warm. They outlive a gone parent session. */
+export function warmHostedChildIds(home: string): Set<string> {
+  const out = new Set<string>();
+  try {
+    const { pid } = JSON.parse(readFileSync(join(home, "manager.pid"), "utf8")) as { pid?: unknown };
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return out;
+    try {
+      process.kill(pid, 0);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EPERM") return out;
+    }
+  } catch {
+    return out;
+  }
+  let files: string[];
+  try {
+    files = readdirSync(join(home, "agents")).filter((name) => name.endsWith(".json"));
+  } catch {
+    return out;
+  }
+  for (const file of files) {
+    try {
+      const value = JSON.parse(readFileSync(join(home, "agents", file), "utf8")) as {
+        residency?: string;
+        child_id?: string;
+      };
+      if (value.residency === "warm" && typeof value.child_id === "string") {
+        out.add(value.child_id);
+      }
+    } catch {
+      // skip bad hosted records
+    }
+  }
+  return out;
+}
+
 export function loadAgentChildRecords(
   home: string,
   opts: { sessionId?: string; includeTerminal?: boolean; connectedSessionIds?: ReadonlySet<string> } = {},
@@ -189,6 +229,7 @@ export function loadAgentChildRecords(
   } catch {
     return [];
   }
+  const warm = opts.connectedSessionIds === undefined ? new Set<string>() : warmHostedChildIds(home);
   const out: AgentChildRecord[] = [];
   for (const sid of sessionIds) {
     const dir = agentRecordsDir(home, sid);
@@ -205,7 +246,9 @@ export function loadAgentChildRecords(
         const disconnected =
           opts.connectedSessionIds !== undefined && !opts.connectedSessionIds.has(rec.session_id);
         const shown: AgentChildRecord =
-          disconnected && (rec.status === "pending" || rec.status === "running")
+          disconnected &&
+          (rec.status === "pending" || rec.status === "running") &&
+          !warm.has(rec.child_id)
             ? { ...rec, status: "interrupted" }
             : rec;
         const terminal =
@@ -220,6 +263,12 @@ export function loadAgentChildRecords(
   return out;
 }
 
+/** One child by id or name, across every session under home. */
+export function findAgentChildRecord(home: string, childIdOrName: string): AgentChildRecord | undefined {
+  const recs = loadAgentChildRecords(home, { includeTerminal: true });
+  return recs.find((rec) => rec.child_id === childIdOrName) ?? recs.find((rec) => rec.name === childIdOrName);
+}
+
 export function isAgentStatusActive(status: AgentChildRecord["status"]): boolean {
   return status === "pending" || status === "running";
 }