pi-famulus 0.2.0 → 0.2.2-beta.0

package/src/intercom/widgets.ts

@@ -0,0 +1,130 @@
+/**
+ * TUI widgets for intercom message cards.
+ *
+ * Upstream baseline: agent-intercom @ 98183fb, plugin/pi — verbatim port of
+ * the plugin's ChatText/ChatCard renderers and text-measurement helpers.
+ */
+
+/** Rough display width: CJK ideographs and wide chars count as 2. */
+export function stringWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) {
+    const cp = ch.codePointAt(0) ?? 0;
+    w += cp >= 0x2e80 ? 2 : 1;
+  }
+  return w;
+}
+
+/** Word-wrap one line, treating ANSI SGR sequences as zero-width. */
+export function wrapAnsiLine(line: string, width: number): string[] {
+  if (stringWidth(line.replace(/\x1b\[[0-9;]*m/g, "")) <= width) return [line];
+  const tokens = line.match(/(\x1b\[[0-9;]*m|\s+|[^\s\x1b]+)/g) ?? [line];
+  const lines: string[] = [];
+  let cur = "";
+  let curWidth = 0;
+  const push = () => {
+    lines.push(cur.trimEnd());
+    cur = "";
+    curWidth = 0;
+  };
+  for (const token of tokens) {
+    if (token.startsWith("\x1b")) {
+      cur += token;
+      continue;
+    }
+    if (/^\s+$/.test(token)) {
+      if (cur && curWidth + 1 <= width) {
+        cur += " ";
+        curWidth += 1;
+      }
+      continue;
+    }
+    let piece = token;
+    let pieceWidth = stringWidth(piece);
+    if (curWidth > 0 && curWidth + pieceWidth > width) push();
+    while (pieceWidth > width) {
+      let cut = 0;
+      let cutWidth = 0;
+      for (const ch of piece) {
+        const w = stringWidth(ch);
+        if (cutWidth + w > width) break;
+        cutWidth += w;
+        cut += ch.length;
+      }
+      cur += piece.slice(0, cut);
+      push();
+      piece = piece.slice(cut);
+      pieceWidth = stringWidth(piece);
+    }
+    cur += piece;
+    curWidth += pieceWidth;
+  }
+  if (cur.trimEnd()) push();
+  return lines.length ? lines : [""];
+}
+
+/** Local wall-clock `YYYY-mm-dd HH:ss`. */
+export function formatTimestamp(d: Date): string {
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** Minimal Text component satisfying pi's Component contract; no pi-tui dependency. */
+export class ChatText {
+  private text: string;
+  private paddingX: number;
+
+  constructor(text: string, paddingX = 1) {
+    this.text = text;
+    this.paddingX = paddingX;
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const padding = Math.min(this.paddingX, Math.max(0, Math.floor((width - 1) / 2)));
+    const pad = " ".repeat(padding);
+    const contentWidth = Math.max(1, width - padding * 2);
+    const out: string[] = [];
+    for (const line of this.text.split("\n")) {
+      for (const wrapped of wrapAnsiLine(line, contentWidth)) {
+        out.push(pad + wrapped);
+      }
+    }
+    return out;
+  }
+}
+
+/** Boxed card with a full-width background, matching pi's custom message look. */
+export class ChatCard {
+  private header: string;
+  private body: string;
+  private bg: (text: string) => string;
+
+  constructor(header: string, body: string, bg: (text: string) => string) {
+    this.header = header;
+    this.body = body;
+    this.bg = bg;
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const px = 1;
+    const contentWidth = Math.max(1, width - px * 2);
+    const out: string[] = [this.bg(" ".repeat(width))];
+    const padLine = (s: string) => {
+      const visible = stringWidth(s.replace(/\x1b\[[0-9;]*m/g, ""));
+      return this.bg(" ".repeat(px) + s + " ".repeat(Math.max(0, width - px - visible)));
+    };
+    for (const line of `${this.header}\n${this.body}`.split("\n")) {
+      for (const wrapped of wrapAnsiLine(line, contentWidth)) {
+        out.push(padLine(wrapped));
+      }
+    }
+    out.push(this.bg(" ".repeat(width)));
+    // One transparent line below the card as extra bottom margin.
+    out.push("");
+    return out;
+  }
+}

package/src/manager-client.ts

@@ -18,10 +18,11 @@ 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.2.0";
+const EXTENSION_VERSION = "0.2.2-beta.0";
 export { EXTENSION_VERSION };
-// 5: speaks per-kind agent admission and queued acquire.
-const PROTOCOL = 6;
+// 6: hosted subagents. 7: the extension's messaging bridge (`intercom`
+// request plus `intercom`/`intercom_reset` events).
+const PROTOCOL = 7;
 const HELLO_TIMEOUT_MS = 5000;
 const RECONNECT_HELLO_TIMEOUT_MS = 25_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
@@ -108,7 +109,14 @@ export interface MonitorOutputRecord {
 
 /** Server-pushed event (§3.3). Fields beyond `event` depend on the event kind. */
 export interface ManagerEvent {
-  event: "task_started" | "output" | "task_exited" | "session_rebound" | string;
+  event:
+    | "task_started"
+    | "output"
+    | "task_exited"
+    | "session_rebound"
+    | "intercom"
+    | "intercom_reset"
+    | string;
   task_id?: string;
   kind?: string;
   command?: string;
@@ -126,6 +134,8 @@ export interface ManagerEvent {
   ts?: number;
   /** Set on task_started when the daemon recorded who asked for the task. */
   origin?: { via: string; child_id?: string; run_id?: string };
+  /** An intercom bridge frame (deliver/receipt/idle_notice) for this session. */
+  frame?: Record<string, unknown>;
 }
 
 export class ManagerError extends Error {
@@ -608,6 +618,19 @@ export class ManagerClient {
     });
   }
 
+  /** The extension's messaging bridge: one intercom client-protocol op
+   * (register/send/list/receipt/…). Protocol 7+; rejected by older managers. */
+  async intercom(op: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (this.protocolLevel_ < 7) {
+      throw new ManagerError(
+        "E_VERSION",
+        "this pi-famulus daemon does not serve cross-session messaging (protocol " +
+          `${this.protocolLevel_}; need 7). Restart pi so it starts the current daemon.`,
+      );
+    }
+    return this.request({ type: "intercom", op });
+  }
+
   /** Daemon status, including optional in-place upgrade metadata. */
   async status(): Promise<ManagerStatusResponse> {
     const res = await this.request({ type: "status" });
@@ -637,6 +660,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;

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/prompts.generated.ts

@@ -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.",

package/src/reload-handoff.ts

@@ -29,6 +29,7 @@ const REGISTRATIONS = new Set<PropertyKey>([
   "registerShortcut",
   "registerFlag",
   "registerMessageRenderer",
+  "registerEntryRenderer",
   "registerProvider",
 ]);
 
@@ -51,8 +52,13 @@ export function createPiBinding(): PiBinding {
   let current: ExtensionAPI | null = null;
   let live = false;
 
-  const call = (pi: ExtensionAPI, method: PropertyKey, args: unknown[]): unknown =>
-    (Reflect.get(pi, method) as (...a: unknown[]) => unknown).apply(pi, args);
+  const call = (pi: ExtensionAPI, method: PropertyKey, args: unknown[]): unknown => {
+    const fn = Reflect.get(pi, method) as unknown;
+    // A host surface may not implement every registration kind (hosted
+    // child fakes, older pi); skipping beats crashing the replay.
+    if (typeof fn !== "function") return undefined;
+    return (fn as (...a: unknown[]) => unknown).apply(pi, args);
+  };
 
   const api = new Proxy({} as ExtensionAPI, {
     get(_target, key) {

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";
 }

package/src/subagent/hosted-session.ts

@@ -66,10 +66,10 @@ export function createHostedSessionFn(deps: HostedSessionDeps): CreateSessionFn
       "--thinking", String(thinking),
       "--append-system-prompt", promptFile,
       ...(trustInherited ? [] : [deps.getProjectTrusted?.() ? "-a" : "-na"]),
-      ...(req.agent.tools ? ["--tools", req.agent.tools.join(",")] : []),
+      ...(req.agent.tools ? ["--tools", hostedChildTools(req.agent.tools).join(",")] : []),
     ];
     const env = { ...process.env } as Record<string, string>;
-    if (req.agent.tools) env.PI_FAMULUS_CHILD_TOOLS = req.agent.tools.join(",");
+    if (req.agent.tools) env.PI_FAMULUS_CHILD_TOOLS = hostedChildTools(req.agent.tools).join(",");
     env.PI_FAMULUS_CHILD_RUN = req.runId;
     env.PI_FAMULUS_CHILD_NAME = req.name;
     const spawned = await client.agentSpawn({
@@ -80,14 +80,7 @@ export function createHostedSessionFn(deps: HostedSessionDeps): CreateSessionFn
       cwd,
       env,
     });
-    let warning = model.warning;
-    try {
-      await client.agentInput(req.childId, "set_steering_mode", "all", "parent");
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const note = `Steering mode was not set (${message}); queued input may wait until the current turn ends.`;
-      warning = warning ? `${warning} ${note}` : note;
-    }
+    const warning = model.warning;
     await client.agentWatch(req.childId);
     const session = new HostedRpcSession(client, req.childId, {
       warning,
@@ -108,6 +101,7 @@ class HostedRpcSession implements ChildSessionAdapter {
   private readonly unsubscribe: () => void;
   private streaming = false;
   private lastText = "";
+  private lastFailure: { stopReason: "error" | "aborted"; errorMessage?: string } | undefined;
   private turns: { role: string; text: string }[] = [];
   private usage: ChildTokenUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
   private settle: (() => void) | null = null;
@@ -172,6 +166,10 @@ class HostedRpcSession implements ChildSessionAdapter {
     return this.lastText || undefined;
   }
 
+  getLastAssistantFailure(): { stopReason: "error" | "aborted"; errorMessage?: string } | undefined {
+    return this.lastFailure;
+  }
+
   getConversation() {
     return this.turns.map((turn) => ({ ...turn }));
   }
@@ -216,6 +214,9 @@ class HostedRpcSession implements ChildSessionAdapter {
       };
       if (event.activity === "running") this.streaming = true;
       if (event.activity === "idle" || event.activity === "failed") {
+        if (event.activity === "failed" && !this.lastFailure) {
+          this.lastFailure = { stopReason: "error", errorMessage: "hosted child process failed" };
+        }
         this.streaming = false;
         this.settle?.();
         this.settle = null;
@@ -223,7 +224,20 @@ class HostedRpcSession implements ChildSessionAdapter {
       return;
     }
     if (event.event !== "agent_rpc" || !event.record || typeof event.record !== "object") return;
-    const record = event.record as { type?: string; message?: { role?: string; content?: { type?: string; text?: string }[]; usage?: Record<string, unknown> }; toolCallId?: string };
+    const record = event.record as {
+      type?: string;
+      message?: {
+        role?: string;
+        content?: { type?: string; text?: string }[];
+        usage?: Record<string, unknown>;
+        stopReason?: string;
+        errorMessage?: string;
+      };
+      toolCallId?: string;
+      toolName?: string;
+      args?: unknown;
+      isError?: boolean;
+    };
     const type = record.type ?? "";
     if (type === "agent_start") this.streaming = true;
     if (type === "agent_settled") {
@@ -237,6 +251,18 @@ class HostedRpcSession implements ChildSessionAdapter {
         this.lastText = text;
         this.turns.push({ role: "assistant", text });
       }
+      const stopReason = record.message.stopReason;
+      if (stopReason === "error" || stopReason === "aborted") {
+        this.lastFailure = {
+          stopReason,
+          ...(record.message.errorMessage ? { errorMessage: record.message.errorMessage } : {}),
+        };
+        if (record.message.errorMessage) {
+          this.turns.push({ role: "assistant error", text: record.message.errorMessage });
+        }
+      } else {
+        this.lastFailure = undefined;
+      }
       const usage = record.message.usage;
       if (usage) {
         this.usage.input += num(usage.input);
@@ -249,10 +275,21 @@ class HostedRpcSession implements ChildSessionAdapter {
       const text = (record.message.content ?? []).map((part) => part.text ?? "").join("");
       if (text) this.turns.push({ role: "user", text });
     }
+    if (type === "tool_execution_end") {
+      const name = record.toolName ?? "tool";
+      const text = record.args === undefined ? name : `${name} ${JSON.stringify(record.args)}`;
+      this.turns.push({
+        role: record.isError ? `tool ${name} error` : `tool ${name}`,
+        text,
+      });
+    }
     const adapted: ChildSessionEvent = {
       type,
       ...(record.message?.role ? { role: record.message.role } : {}),
       ...(record.toolCallId ? { toolCallId: record.toolCallId } : {}),
+      ...(record.toolName ? { toolName: record.toolName } : {}),
+      ...(record.args !== undefined ? { args: record.args } : {}),
+      ...(record.isError !== undefined ? { isError: record.isError } : {}),
     };
     for (const listener of this.listeners) listener(adapted);
   }
@@ -262,6 +299,15 @@ function num(value: unknown): number {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+const SUPERVISOR_TOOLS = ["contact_supervisor", "agent_message"];
+
+/** Agent allowlists still keep the two supervisor tools. */
+export function hostedChildTools(tools: string[]): string[] {
+  const kept = new Set(tools);
+  for (const name of SUPERVISOR_TOOLS) kept.add(name);
+  return [...kept];
+}
+
 /** Request id for a child→parent decision. */
 export function newCommsRequestId(): string {
   return `rq_${randomUUID().slice(0, 8)}`;

package/src/subagent/registry.ts

@@ -342,6 +342,84 @@ export class SubagentRegistry implements RunRegistry {
   // M3 extensions beyond Appendix B
   // -------------------------------------------------------------------------
 
+  /**
+   * Reconstruct a run/child the previous parent process wrote to disk
+   * so resume can reattach by child_id.
+   */
+  adoptExisting(info: {
+    runId: string;
+    childId: string;
+    name: string;
+    agent: string;
+    workKind?: string;
+    startedAt?: number;
+    prompt?: string;
+  }): void {
+    if (this.children.has(info.childId)) return;
+    let run = this.runs.get(info.runId);
+    if (!run) {
+      run = {
+        runId: info.runId,
+        kind: "tasks",
+        status: "interrupted",
+        createdAt: info.startedAt ?? this.now(),
+        children: [],
+      };
+      this.runs.set(info.runId, run);
+    }
+    const child: InternalChild = {
+      childId: info.childId,
+      runId: info.runId,
+      name: info.name,
+      agent: info.agent,
+      workKind: info.workKind ?? "other",
+      status: "interrupted",
+      startedAt: info.startedAt ?? this.now(),
+      endedAt: this.now(),
+      turn: 1,
+      queueMs: 0,
+      prompt: info.prompt,
+    };
+    run.children.push(child);
+    this.children.set(child.childId, child);
+    this.emit(run);
+  }
+
+  /** Bind a live hosted session to an adopted child without sending its first prompt. */
+  async attachChild(req: ChildRunRequest): Promise<ChildHandle> {
+    const child = this.children.get(req.childId);
+    if (!child) throw new Error(`unknown child ${req.childId} (adoptExisting first)`);
+    const runner = this.runner;
+    if (!runner?.attach) {
+      throw new Error(`subagent ${req.childId} has no live session to resume`);
+    }
+    child.prompt = req.taskPrompt ?? req.prompt;
+    child.preamble = req.agent.systemPrompt || undefined;
+    child.model = req.model ?? req.agent.model;
+    let handle: ChildHandle;
+    try {
+      handle = await runner.attach(req, (startingHandle) => {
+        child.handle = startingHandle;
+      });
+    } catch (error) {
+      const failed = child.handle as DisposableChildHandle | undefined;
+      child.handle = undefined;
+      await failed?.dispose?.();
+      throw error;
+    }
+    if (!this.children.has(child.childId)) return handle;
+    child.handle = handle;
+    handle.result.then((result) => this.settleChild(child.childId, result));
+    const resolved = handle.resolvedModel();
+    if (resolved) {
+      const thinking = handle.effectiveThinkingLevel?.();
+      child.model = `${resolved}${thinking ? `:${thinking}` : ""}`;
+    }
+    const run = this.runs.get(child.runId);
+    if (run) this.emit(run);
+    return handle;
+  }
+
   /** Allocate a pending child inside a run. Returns the child id. */
   addChild(runId: string, info: { name: string; agent: string; workKind?: string }): string {
     const run = this.runs.get(runId);