@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/src/agent/index.ts

@@ -1,7 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { setTimeout as delay } from "node:timers/promises";
 import type {
   ExtensionAPI,
   ExtensionContext,
@@ -12,23 +11,22 @@ import {
   alive,
   ensureActor,
   ownIdentity,
+  requestStop,
   signalProcess,
-  verifyProcess,
-  shells,
+  stopChildren,
 } from "./process.ts";
 import { isChild, errorText } from "./host.ts";
 import {
-  delegateSchema,
-  runsSchema,
   resultSchema,
   attachmentSchema,
   admissionSchema,
   commandSchema,
+  type Attachment,
   type Launch,
+  type ProcessIdentity,
   type Result,
-  type DelegateInput,
-  type RunsInput,
 } from "./contracts.ts";
+import { delegateSchema, runsSchema, type DelegateInput, type RunsInput } from "./tool-schemas.ts";
 import {
   enqueue,
   latest,
@@ -40,21 +38,65 @@ import {
   conversation,
   write,
 } from "./storage.ts";
-import { hold, notify, settle, release } from "./notifications.ts";
+import { notifications, deliver, settle } from "./notifications.ts";
 import { prepareLaunch } from "./launch.ts";
-import { toolResult, projection, render, summaries } from "./view.ts";
-import { registerUsage } from "./usage.ts";
-import { notifyLegacy } from "./legacy.ts";
+import { renderReceipt, renderInventory, renderInspection } from "./view.ts";
+import { legacyDirectory, legacyNotifications } from "./legacy.ts";
+import { DirectoryWatch, pathStamp, type WatchState } from "./wake.ts";
 import { savedContinuation } from "./saved.ts";
 import { executionCwd } from "./cwd.ts";
 import { getPiAgentDir } from "../pi-intercom/agent-dir.ts";
+import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.ts";
 
+/** Native fork lifetime owner (`ctx.managedHost`); read structurally so official Pi stays supported. */
+interface ManagedHost {
+  readonly owner: { readonly pid: number };
+  readonly ready: Promise<boolean>;
+}
+/** `handoff` and `provisional` mean another worker under the same launcher may still own these children. */
+function retainsChildren(event: object): boolean {
+  const disposition: unknown = Reflect.get(event, "disposition");
+  return disposition === "handoff" || disposition === "provisional";
+}
+function managedHost(context: ExtensionContext): ManagedHost | undefined {
+  const host: unknown = Reflect.get(context, "managedHost");
+  if (typeof host !== "object" || host === null) {
+    return undefined;
+  }
+  const owner: unknown = Reflect.get(host, "owner");
+  const pid: unknown =
+    typeof owner === "object" && owner !== null ? Reflect.get(owner, "pid") : undefined;
+  const ready: unknown = Reflect.get(host, "ready");
+  return typeof pid === "number" && Number.isSafeInteger(pid) && ready instanceof Promise
+    ? { owner: { pid }, ready: ready.then((accepted) => accepted === true) }
+    : undefined;
+}
+
+/** Legacy results are optional; their reconciliation reports an invalid configured root. */
+function legacyInput(): string[] {
+  try {
+    return [legacyDirectory()];
+  } catch {
+    return [];
+  }
+}
 class AgentRuntime {
   private ctx?: ExtensionContext;
+  // A managed launcher owns children across worker replacement; otherwise this process does.
+  private host?: ManagedHost;
+  private accepted = false;
   private base = "";
   private owner = "";
   private generation = "";
+  // Polling remains only while change hints are unavailable or a reconciliation failed.
   private timer?: NodeJS.Timeout;
+  private woken?: NodeJS.Immediate;
+  // Change hints for the owner directory, legacy results and every awaited canonical file.
+  private readonly watches = new Map<string, DirectoryWatch>();
+  private awaited: ReadonlySet<string> = new Set();
+  // Input stamps the last reconciliation saw; a one-second probe recovers dropped hints.
+  private observed = new Map<string, string>();
+  private probe?: NodeJS.Timeout;
   private closing = false;
   private reset: Promise<void> = Promise.resolve();
   private readonly shutdown = new AbortController();
@@ -72,23 +114,121 @@ class AgentRuntime {
       throw new Error("Agent runtime is not attached.");
     }
   }
+  private readonly wake = (): void => {
+    this.woken ??= setImmediate(() => {
+      this.woken = undefined;
+      this.scan();
+    }).unref();
+  };
+  private readonly recover = (): void => {
+    for (const [file, seen] of this.observed) {
+      if (pathStamp(file) !== seen) {
+        this.wake();
+        return;
+      }
+    }
+  };
   private readonly scan = (): void => {
+    clearTimeout(this.timer);
     if (this.closing || !this.ctx || this.child) {
       return;
     }
+    const inputs = () => [this.base, ...legacyInput(), ...this.awaited];
+    const before = new Map(inputs().map((file) => [file, pathStamp(file)]));
+    let reconciled = true;
     try {
-      notify(this.pi, this.ctx, this.base, this.owner);
-      notifyLegacy(this.pi, this.ctx);
+      const { notices, awaited } = notifications(this.ctx, this.base, this.owner);
+      this.awaited = awaited;
+      try {
+        notices.unshift(...legacyNotifications(this.ctx));
+      } catch (error) {
+        console.error(`Legacy completion reconciliation: ${errorText(error)}`);
+      }
+      deliver(this.pi, this.ctx, notices);
     } catch (error) {
+      reconciled = false;
       console.error(`Agent completion reconciliation: ${errorText(error)}`);
     }
+    // Newly awaited files were absent when read, or are rechecked once by the probe.
+    this.observed = new Map(inputs().map((file) => [file, before.get(file) ?? ""]));
+    const next = this.watch();
+    if (!reconciled || next === "poll") {
+      this.timer = setTimeout(this.scan, 200).unref();
+    } else if (next === "rescan") {
+      // Publications before arming had no hint; reconcile once more after it.
+      this.wake();
+    }
   };
-  private start(context: ExtensionContext): Promise<void> {
-    this.reset = this.reset.then(() => this.attach(context));
-    return this.reset;
+  /** Watches every directory that can publish an awaited input; legacy results may never exist. */
+  private watch(): "poll" | "rescan" | "hints" {
+    const legacy = legacyInput();
+    const directories = [
+      ...new Set([this.base, ...legacy, ...[...this.awaited].map((file) => path.dirname(file))]),
+    ];
+    for (const [directory, watch] of this.watches) {
+      if (!directories.includes(directory)) {
+        watch.close();
+        this.watches.delete(directory);
+      }
+    }
+    const states = directories.map((directory): [string, WatchState] => {
+      let watch = this.watches.get(directory);
+      if (watch === undefined) {
+        const every = directory === this.base || legacy.includes(directory);
+        watch = new DirectoryWatch(
+          directory,
+          (file) => every || file === null || this.awaited.has(path.join(directory, file)),
+          this.wake,
+        );
+        this.watches.set(directory, watch);
+      }
+      return [directory, watch.ensure()];
+    });
+    if (states.some(([directory, state]) => state === "unwatched" && !legacy.includes(directory))) {
+      return "poll";
+    }
+    return states.some(([, state]) => state === "armed") ? "rescan" : "hints";
+  }
+  private unwatch(): void {
+    clearTimeout(this.timer);
+    clearInterval(this.probe);
+    this.observed.clear();
+    clearImmediate(this.woken);
+    this.woken = undefined;
+    for (const watch of this.watches.values()) {
+      watch.close();
+    }
+    this.watches.clear();
+    this.awaited = new Set();
+  }
+  private start(context: ExtensionContext): Promise<void> | undefined {
+    this.host = managedHost(context);
+    if (this.host === undefined || this.accepted || this.child) {
+      this.reset = this.reset.then(() => this.attach(context));
+      return this.reset;
+    }
+    // Attach and publish only after the launcher retires rollback: an unready replacement
+    // must neither adopt children nor append completions to a journal it may abandon.
+    // Readiness follows session_start, so never await it here.
+    this.owner = context.sessionManager.getSessionId();
+    this.base = ownerDirectory(this.agentDir, this.owner);
+    this.host.ready
+      .then(async (accepted) => {
+        if (accepted && !this.closing) {
+          this.accepted = true;
+          await this.start(context);
+        }
+      })
+      .catch((error: unknown) => {
+        console.error(`Agent runtime attachment: ${errorText(error)}`);
+      });
+    return undefined;
+  }
+  private ownerIdentity(): Omit<ProcessIdentity, "token"> {
+    return ownIdentity(this.host?.owner.pid);
   }
   private async attach(context: ExtensionContext): Promise<void> {
-    clearInterval(this.timer);
+    this.unwatch();
     this.ctx = context;
     if (this.child) {
       return;
@@ -98,55 +238,54 @@ class AgentRuntime {
     this.generation = randomUUID();
     await fs.promises.mkdir(this.base, { recursive: true, mode: 0o700 });
     write(path.join(this.base, "attachment.json"), {
-      ...ownIdentity(),
+      ...this.ownerIdentity(),
       generation: this.generation,
       attached: true,
     });
     if (this.closing) {
       return;
     }
-    this.timer = setInterval(this.scan, 200);
-    this.timer.unref();
-    this.scan();
+    // Recovery and watch setup stay off the awaited startup path.
+    this.timer = setTimeout(this.scan, 200).unref();
+    this.probe = setInterval(this.recover, 1000).unref();
   }
-  private async dispose(): Promise<void> {
+  private async dispose(retain: boolean): Promise<void> {
     this.closing = true;
-    clearInterval(this.timer);
+    this.unwatch();
     this.shutdown.abort();
     await this.reset;
-    if (this.base.length > 0) {
+    if (!retain && this.base.length > 0) {
       const file = path.join(this.base, "attachment.json");
-      if (read(file, attachmentSchema)?.generation === this.generation) {
-        write(file, { ...ownIdentity(), generation: this.generation, attached: false });
+      const attachment = read(file, attachmentSchema);
+      if (attachment !== undefined && this.releases(attachment)) {
+        write(file, {
+          ...this.ownerIdentity(),
+          generation: attachment.generation,
+          attached: false,
+        });
+        await stopChildren(this.base, this.owner);
       }
     }
     this.ctx = undefined;
   }
+  private releases(attachment: Attachment): boolean {
+    if (attachment.generation === this.generation) {
+      return true;
+    }
+    // An unready replacement never attached, but exiting still releases the launcher-owned children.
+    return (
+      this.generation.length === 0 && attachment.attached && attachment.pid === this.host?.owner.pid
+    );
+  }
   private stop(launch: Launch) {
     const base = this.base;
-    const identity = actor(base, launch);
-    const targets = identity ? [identity, ...shells(base, launch, identity.token)] : [];
-    // Verify all targets before admitting a request or signaling any process.
-    const live = targets.filter(verifyProcess);
+    const { targets: live, command: id } = requestStop(base, launch);
     if (live.length === 0) {
-      return {
-        ...projection(base, launch, this.ctx),
+      return renderReceipt(base, launch, this.ctx, {
         stopAcknowledged: false,
         note: "No matching live actor or owned shell; process exit code remains unknown.",
-      };
-    }
-    const id =
-      identity && verifyProcess(identity)
-        ? enqueue(base, launch, "stop", { actorToken: identity.token })
-        : undefined;
-    if (identity) {
-      write(path.join(conversation(base, launch), `stopping-${identity.token}.json`), {
-        at: Date.now(),
       });
     }
-    live.forEach((target) => {
-      signalProcess(target, "SIGTERM");
-    });
     const escalation = setTimeout(() => {
       try {
         live.forEach((target) => {
@@ -157,65 +296,11 @@ class AgentRuntime {
       }
     }, 3000);
     escalation.unref();
-    return {
-      ...projection(base, launch, this.ctx),
+    return renderReceipt(base, launch, this.ctx, {
       stopRequest: id,
       stopAcknowledged: false,
       note: "Stop requested; neither native admission nor process exit is implied.",
-    };
-  }
-  private interrupted(launch: Launch, signal: AbortSignal | undefined, owned: boolean) {
-    if (this.shutdown.signal.aborted) {
-      return toolResult({
-        ...projection(this.base, launch, this.ctx),
-        wait: "detached",
-        note: "Parent runtime disposed; producer was not stopped.",
-      });
-    }
-    if (signal?.aborted === true) {
-      if (owned) {
-        this.stop(launch);
-      }
-      return toolResult({
-        ...projection(this.base, launch, this.ctx),
-        wait: "cancelled",
-        note: owned
-          ? "Owned foreground work was asked to stop; exit is unconfirmed."
-          : "Only the wait was cancelled; producer was not stopped.",
-      });
-    }
-    const identity = actor(this.base, launch);
-    if (identity && !alive(identity)) {
-      return toolResult({
-        ...projection(this.base, launch, this.ctx),
-        wait: "interrupted",
-        note: "Actor is not live; no completion or exit code was invented.",
-      });
-    }
-    return;
-  }
-  private async wait(launch: Launch, signal: AbortSignal | undefined, owned: boolean) {
-    const held = hold(this.owner, launch.id);
-    for (;;) {
-      const result = read(
-        path.join(runDirectory(this.base, launch.id), "result.json"),
-        resultSchema,
-      );
-      if (result) {
-        hold(this.owner, launch.id);
-        return render(this.base, launch, this.ctx, { receivedResult: true });
-      }
-      const interruption = this.interrupted(launch, signal, owned);
-      if (interruption) {
-        if (held) {
-          release(this.owner, launch.id);
-        }
-        return interruption;
-      }
-      // Cancellation of an observer never removes canonical producer state.
-      // oxlint-disable-next-line no-await-in-loop
-      await delay(50);
-    }
+    });
   }
   private async delegate(
     input: DelegateInput,
@@ -238,28 +323,17 @@ class AgentRuntime {
     });
     this.checkMain();
     enqueue(this.base, launch, "run");
-    await ensureActor(this.base, launch);
-    if (input.async === false) {
-      return this.wait(launch, signal, true);
-    }
-    return toolResult({
-      ...projection(this.base, launch, this.ctx),
+    await ensureActor(this.base, launch, this.shutdown.signal);
+    return renderReceipt(this.base, launch, this.ctx, {
       receipt: "launch",
-      note: "Launch accepted, not actual completion or native receipt publication.",
+      note: "Launch accepted, not completion or native receipt publication. Completion arrives as a notification; do other work or end the turn instead of polling.",
     });
   }
   private list(input: RunsInput) {
     const all = list(this.base)
       .map((id) => launchAt(this.base, id, this.owner))
       .sort((a, b) => a.createdAt - b.createdAt);
-    const offset = input.offset ?? 0;
-    const page = summaries(this.base, all.slice(offset, offset + 50), this.ctx);
-    return toolResult({
-      runs: page,
-      offset,
-      nextOffset: offset + page.length < all.length ? offset + page.length : undefined,
-      total: all.length,
-    });
+    return renderInventory(this.base, all, this.ctx, input);
   }
   private successor(launch: Launch, prompt: string): Launch | undefined {
     const id = randomUUID();
@@ -291,11 +365,7 @@ class AgentRuntime {
     }
     return;
   }
-  private async retryContinuation(
-    launch: Launch,
-    input: RunsInput,
-    signal: AbortSignal | undefined,
-  ) {
+  private async retryContinuation(launch: Launch, input: RunsInput) {
     const identity = actor(this.base, launch);
     const command = read(
       path.join(conversation(this.base, launch), "commands", `${launch.id}.json`),
@@ -309,17 +379,14 @@ class AgentRuntime {
       command.action !== "run"
     ) {
       throw new Error(
-        `Run ${launch.id} is awaiting native admission. Retry requires the exact saved prompt, its existing queued Run command, and no live actor. Missing commands or ambiguous process claims require inspection; wait for admission or a canonical result before sending another prompt. No new continuation was launched.`,
+        `Run ${launch.id} is awaiting native admission. Retry requires the exact saved prompt, its existing queued Run command, and no live actor. Missing commands or ambiguous process claims require inspection. Admission or a canonical result arrives without polling: end the turn or do other work until the completion notification, then inspect once before sending another prompt. No new continuation was launched.`,
       );
     }
     // Only an unadmitted durable command is retryable; keep all process/shell claim guards.
-    await ensureActor(this.base, launch);
-    if (input.async === false) {
-      return this.wait(launch, signal, true);
-    }
-    return toolResult({ ...projection(this.base, launch, this.ctx), receipt: "continuation" });
+    await ensureActor(this.base, launch, this.shutdown.signal);
+    return renderReceipt(this.base, launch, this.ctx, { receipt: "continuation" });
   }
-  private async continue(launch: Launch, input: RunsInput, signal: AbortSignal | undefined) {
+  private async continue(launch: Launch, input: RunsInput) {
     if (input.prompt === undefined) {
       throw new Error("continue requires the entire new prompt.");
     }
@@ -328,16 +395,12 @@ class AgentRuntime {
     }
     const completed = this.continuationResult(launch);
     if (completed === "pending") {
-      return this.retryContinuation(launch, input, signal);
+      return this.retryContinuation(launch, input);
     }
     const identity = actor(this.base, launch);
     if (!completed && identity && alive(identity)) {
       const command = enqueue(this.base, launch, "steer", { prompt: input.prompt });
-      if (input.async === false) {
-        return this.guidance(launch, command, signal);
-      }
-      return toolResult({
-        ...projection(this.base, launch, this.ctx),
+      return renderReceipt(this.base, launch, this.ctx, {
         receipt: "guidance",
         command,
         note: "Guidance queued, not actual completion or model consumption.",
@@ -345,48 +408,16 @@ class AgentRuntime {
     }
     const next = this.successor(launch, input.prompt);
     if (!next) {
-      return toolResult({
-        ...projection(this.base, latest(this.base, launch), this.ctx),
+      return renderReceipt(this.base, latest(this.base, launch), this.ctx, {
         receipt: "existing-successor",
       });
     }
     // Retain successor claims on ambiguous after-launch failures: no replay.
     enqueue(this.base, next, "run");
-    await ensureActor(this.base, next);
-    if (input.async === false) {
-      return this.wait(next, signal, true);
-    }
-    return toolResult({ ...projection(this.base, next, this.ctx), receipt: "continuation" });
-  }
-  private async guidance(launch: Launch, command: string, signal: AbortSignal | undefined) {
-    const file = path.join(conversation(this.base, launch), "admissions", `${command}.json`);
-    for (;;) {
-      const admission = read(file, admissionSchema);
-      if (admission) {
-        if (admission.state === "stale") {
-          return toolResult({
-            ...projection(this.base, launch, this.ctx),
-            command,
-            guidance: "stale",
-            note: "The native turn settled before guidance admission. Retry the entire prompt as a continuation; no new work was started.",
-          });
-        }
-        return this.wait(launch, signal, false);
-      }
-      const interruption = this.interrupted(launch, signal, false);
-      if (interruption) {
-        return interruption;
-      }
-      // Observe the actor's actual admission, not a timer-based model-consumption claim.
-      // oxlint-disable-next-line no-await-in-loop
-      await delay(50);
-    }
+    await ensureActor(this.base, next, this.shutdown.signal);
+    return renderReceipt(this.base, next, this.ctx, { receipt: "continuation" });
   }
-  private async continueSaved(
-    input: RunsInput & { id: string },
-    signal: AbortSignal | undefined,
-    context: ExtensionContext,
-  ) {
+  private async continueSaved(input: RunsInput & { id: string }, context: ExtensionContext) {
     if (input.prompt === undefined) {
       throw new Error("continue requires the entire new prompt.");
     }
@@ -400,17 +431,13 @@ class AgentRuntime {
     if (created) {
       // The durable adoption claim survives ambiguous after-launch failures.
       enqueue(this.base, launch, "run");
-      await ensureActor(this.base, launch);
+      await ensureActor(this.base, launch, this.shutdown.signal);
     }
-    if (input.async === false) {
-      return this.wait(launch, signal, created);
-    }
-    return toolResult({
-      ...projection(this.base, launch, this.ctx),
+    return renderReceipt(this.base, launch, this.ctx, {
       receipt: created ? "continuation" : "existing-successor",
     });
   }
-  private async runs(input: RunsInput, signal: AbortSignal | undefined, context: ExtensionContext) {
+  private async runs(input: RunsInput, context: ExtensionContext) {
     this.checkMain();
     await this.reset;
     if (input.action === "list") {
@@ -424,31 +451,36 @@ class AgentRuntime {
       input.action === "continue" &&
       !fs.existsSync(path.join(runDirectory(this.base, input.id), "launch.json"))
     ) {
-      return this.continueSaved({ ...input, id: input.id }, signal, context);
+      return this.continueSaved({ ...input, id: input.id }, context);
     }
     const original = launchAt(this.base, input.id, this.owner);
     if (input.action === "inspect") {
-      return render(this.base, original, this.ctx, input);
+      return renderInspection(this.base, original, this.ctx, input);
     }
     const launch = latest(this.base, original);
     if (input.action === "stop") {
-      return toolResult(this.stop(launch));
-    }
-    if (input.action === "wait") {
-      return this.wait(launch, signal, false);
+      return this.stop(launch);
     }
-    return this.continue(launch, input, signal);
+    return this.continue(launch, input);
   }
   register(): void {
-    registerUsage(this.pi);
+    registerCompactMessages(this.pi, ["agent-completion", "subagent-notify"]);
     this.pi.on("session_start", (_event, context) => this.start(context));
-    this.pi.on("turn_end", (event) => {
-      settle(this.owner, event.context.pendingMessages.length > 0);
+    this.pi.on("turn_end", (event, context) => {
+      // The public pending flag covers user input; the preview also includes custom messages.
+      if (
+        settle(this.owner, context.hasPendingMessages() || event.context.pendingMessages.length > 0)
+      ) {
+        // Released admissions may have been dropped from the queue rather than published.
+        this.wake();
+      }
     });
     this.pi.on("agent_settled", () => {
       this.scan();
     });
-    this.pi.on("session_shutdown", () => this.dispose());
+    this.pi.on("session_shutdown", (event) =>
+      this.dispose(event.reason === "reload" || retainsChildren(event)),
+    );
     if (this.child) {
       this.pi.on("tool_call", (event) => {
         if (event.toolName === "delegate" || event.toolName === "agent_runs") {
@@ -463,20 +495,22 @@ class AgentRuntime {
       name: "delegate",
       label: "Delegate",
       description:
-        "Launch one child with exactly the supplied prompt. Fresh context by default; fork preserves the full native conversation. Main sessions only. Returns an asynchronous launch receipt unless async:false.",
+        "Run a child on exactly this prompt; main sessions only. Fork copies the full conversation; default is fresh. Returns a receipt; completion is notified later: do other work or end the turn, don't poll.",
       parameters: delegateSchema,
       exposure: this.child ? "hidden" : "direct",
+      renderResult: renderCompactResult,
       execute,
     });
     const runs: ToolDefinition<typeof runsSchema>["execute"] = (...args) =>
-      this.runs(args[1], args[2], args[4]);
+      this.runs(args[1], args[4]);
     this.pi.registerTool({
       name: "agent_runs",
       label: "Agent runs",
       description:
-        "List, inspect, continue, wait for, or stop this native main session's durable child runs. Inspect is paged with byte offsets; full outputs and native journals remain available. Wait cancellation does not stop existing work. Continue requires the complete new prompt and reuses the saved conversation.",
+        "Manage your child runs without waiting; completions are notified. Inspect pages by byte offset, never interrupting. Continue takes the complete new prompt: it steers a live child or resumes the saved conversation.",
       parameters: runsSchema,
       exposure: this.child ? "hidden" : "direct",
+      renderResult: renderCompactResult,
       execute: runs,
     });
   }