pi-famulus 0.2.0 → 0.2.2-beta.0

package/src/subagent/runner.ts

@@ -87,6 +87,8 @@ export interface InProcessRunnerOptions {
   stallRetryDelayMs?: number;
   /** Called on every stall detection (before any retry), with the 1-based attempt. */
   onStall?: (childId: string, attempt: number) => void;
+  /** Same tool name and arguments three times in a row. */
+  onToolLoop?: (childId: string, toolName: string, args: unknown) => void;
   /** Overrun reminder interval (ms). Default 10 minutes. */
   overrunRepeatMs?: number;
   /** Abort ceiling per user turn (ms). 0/absent = off: the soft deadline never aborts. */
@@ -116,6 +118,20 @@ function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** 429 / rate-limit text is recorded separately from other model errors. */
+export function classifyModelFailure(message: string): {
+  endReason: "model-error" | "rate-limit";
+  retryAfter?: number;
+} {
+  const rateLimited = /\b429\b|rate[\s-]?limit|too many requests/i.test(message);
+  if (!rateLimited) return { endReason: "model-error" };
+  const retry = /retry[\s-]?after[:\s]+(\d+)/i.exec(message);
+  return {
+    endReason: "rate-limit",
+    ...(retry ? { retryAfter: Number(retry[1]) } : {}),
+  };
+}
+
 export class InProcessRunner implements ChildRunner {
   private readonly opts: InProcessRunnerOptions;
 
@@ -129,6 +145,13 @@ export class InProcessRunner implements ChildRunner {
     await handle.launch();
     return handle;
   }
+
+  async attach(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<DisposableChildHandle> {
+    const handle = new InProcessChildHandle(req, this.opts);
+    onHandle?.(handle);
+    await handle.attachIdle();
+    return handle;
+  }
 }
 
 class InProcessChildHandle implements DisposableChildHandle {
@@ -138,6 +161,9 @@ class InProcessChildHandle implements DisposableChildHandle {
   private readonly stallRetries: number;
   private readonly stallRetryDelayMs: number;
   private readonly onStall?: (childId: string, attempt: number) => void;
+  private readonly onToolLoop?: (childId: string, toolName: string, args: unknown) => void;
+  private lastToolKey: string | null = null;
+  private lastToolCount = 0;
   private readonly overrunRepeatMs: number;
   private readonly hardTimeoutMs: number;
   private readonly onOverrun?: (tick: OverrunTick) => void;
@@ -233,6 +259,7 @@ class InProcessChildHandle implements DisposableChildHandle {
       ? Math.max(0, Math.floor(rawDelay))
       : DEFAULT_STALL_RETRY_DELAY_MS;
     this.onStall = opts.onStall;
+    this.onToolLoop = opts.onToolLoop;
     const rawRepeat = opts.overrunRepeatMs ?? DEFAULT_OVERRUN_REPEAT_MS;
     this.overrunRepeatMs =
       Number.isFinite(rawRepeat) && rawRepeat > 0
@@ -331,6 +358,27 @@ class InProcessChildHandle implements DisposableChildHandle {
     await this.beginGeneration(this.req.prompt, true);
   }
 
+  /**
+   * Bind an already-hosted session so resume() can send the next turn.
+   * The previous parent died; this generation is interrupted, not prompted.
+   */
+  async attachIdle(): Promise<void> {
+    this.sessionCreation = this.createSession(this.req);
+    const created =
+      await this.sessionCreation;
+    this.sessionCreation = null;
+    if (this.disposed) return;
+    this.session = created;
+    this.resolvedModel_ = created.resolvedModel;
+    this.unsubscribe = this.session.subscribe((event) => this.handleSessionEvent(event));
+    this.settle(this.generation, {
+      status: "interrupted",
+      text: this.session.getLastAssistantText() ?? "",
+      error: "parent session ended",
+      durationMs: 0,
+    });
+  }
+
   async steer(message: string): Promise<void> {
     if (this.status_ !== "running" || !this.session) {
       throw new Error(`subagent ${this.req.childId} is not running (status: ${this.status_})`);
@@ -480,11 +528,10 @@ class InProcessChildHandle implements DisposableChildHandle {
       text: this.status_ === "pending" ? "" : this.partialText(),
       durationMs: this.now() - this.startedAt,
     });
-    try {
-      await this.session?.abort();
-    } catch {
-      // abort is best-effort; the result is already settled
-    }
+    // Resume may be accepted as soon as the interrupted result is visible.
+    // Drain this abort just like a timeout/stall abort before prompting again.
+    this.abortPromise = this.session ? this.session.abort().catch(() => {}) : null;
+    await this.abortPromise;
   }
 
   dispose(): void | Promise<void> {
@@ -690,11 +737,14 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (!this.isCurrent(gen)) return;
     const failure = session?.getLastAssistantFailure?.();
     if (failure) {
+      const error = failure.errorMessage?.trim() || `Model stopped with ${failure.stopReason}`;
+      const classified = classifyModelFailure(error);
       this.settle(gen, {
         status: "failed",
         text: this.partialText(),
-        error: failure.errorMessage?.trim() || `Model stopped with ${failure.stopReason}`,
-        endReason: "model-error",
+        error,
+        endReason: classified.endReason,
+        ...(classified.retryAfter !== undefined ? { retryAfter: classified.retryAfter } : {}),
         durationMs: this.now() - this.startedAt,
       });
       return;
@@ -871,7 +921,7 @@ class InProcessChildHandle implements DisposableChildHandle {
     this.toolStartedAt = null;
   }
 
-  private handleSessionEvent(event: { type: string; role?: string; toolCallId?: string; usage?: { input: number; output: number } }): void {
+  private handleSessionEvent(event: { type: string; role?: string; toolCallId?: string; toolName?: string; args?: unknown; usage?: { input: number; output: number } }): void {
     const now = this.now();
     const active = this.status_ === "running";
     let currentToolEvent = false;
@@ -915,6 +965,7 @@ class InProcessChildHandle implements DisposableChildHandle {
       if (currentToolEvent) {
         this.toolDepth++;
         this.clearStall();
+        this.noteToolCall(event.toolName, event.args);
       }
       return;
     }
@@ -931,6 +982,22 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (this.toolDepth === 0 && !this.decisionPaused) this.armStall(this.generation);
   }
 
+  private noteToolCall(toolName: string | undefined, args: unknown): void {
+    const name = toolName ?? "";
+    const key = `${name}\0${JSON.stringify(args ?? null)}`;
+    if (this.lastToolKey === key) this.lastToolCount += 1;
+    else {
+      this.lastToolKey = key;
+      this.lastToolCount = 1;
+    }
+    if (this.lastToolCount !== 3 || !name) return;
+    try {
+      this.onToolLoop?.(this.req.childId, name, args);
+    } catch {
+      // loop observers must not break the child
+    }
+  }
+
   private release(terminal = true): void {
     const release = this.releaseSlot;
     if (terminal) this.releaseSlot = null;

package/src/subagent/tool.ts

@@ -142,6 +142,8 @@ export interface SubagentToolDeps {
   /** 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;
@@ -228,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 } : {}),
     })),
@@ -563,11 +567,16 @@ export function createSubagentTool(
       };
     }
 
-    const record = 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)`);

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;
 }
 
@@ -178,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/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;