@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/dist/agent/index.js

@@ -1,25 +1,63 @@
 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 { actor, alive, ensureActor, ownIdentity, signalProcess, verifyProcess, shells, } from "./process.js";
+import { actor, alive, ensureActor, ownIdentity, requestStop, signalProcess, stopChildren, } from "./process.js";
 import { isChild, errorText } from "./host.js";
-import { delegateSchema, runsSchema, resultSchema, attachmentSchema, admissionSchema, commandSchema, } from "./contracts.js";
+import { resultSchema, attachmentSchema, admissionSchema, commandSchema, } from "./contracts.js";
+import { delegateSchema, runsSchema } from "./tool-schemas.js";
 import { enqueue, latest, launchAt, list, read, runDirectory, ownerDirectory, conversation, write, } from "./storage.js";
-import { hold, notify, settle, release } from "./notifications.js";
+import { notifications, deliver, settle } from "./notifications.js";
 import { prepareLaunch } from "./launch.js";
-import { toolResult, projection, render, summaries } from "./view.js";
-import { registerUsage } from "./usage.js";
-import { notifyLegacy } from "./legacy.js";
+import { renderReceipt, renderInventory, renderInspection } from "./view.js";
+import { legacyDirectory, legacyNotifications } from "./legacy.js";
+import { DirectoryWatch, pathStamp } from "./wake.js";
 import { savedContinuation } from "./saved.js";
 import { executionCwd } from "./cwd.js";
 import { getPiAgentDir } from "../pi-intercom/agent-dir.js";
+import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.js";
+/** `handoff` and `provisional` mean another worker under the same launcher may still own these children. */
+function retainsChildren(event) {
+    const disposition = Reflect.get(event, "disposition");
+    return disposition === "handoff" || disposition === "provisional";
+}
+function managedHost(context) {
+    const host = Reflect.get(context, "managedHost");
+    if (typeof host !== "object" || host === null) {
+        return undefined;
+    }
+    const owner = Reflect.get(host, "owner");
+    const pid = typeof owner === "object" && owner !== null ? Reflect.get(owner, "pid") : undefined;
+    const ready = 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() {
+    try {
+        return [legacyDirectory()];
+    }
+    catch {
+        return [];
+    }
+}
 class AgentRuntime {
     ctx;
+    // A managed launcher owns children across worker replacement; otherwise this process does.
+    host;
+    accepted = false;
     base = "";
     owner = "";
     generation = "";
+    // Polling remains only while change hints are unavailable or a reconciliation failed.
     timer;
+    woken;
+    // Change hints for the owner directory, legacy results and every awaited canonical file.
+    watches = new Map();
+    awaited = new Set();
+    // Input stamps the last reconciliation saw; a one-second probe recovers dropped hints.
+    observed = new Map();
+    probe;
     closing = false;
     reset = Promise.resolve();
     shutdown = new AbortController();
@@ -37,24 +75,120 @@ class AgentRuntime {
             throw new Error("Agent runtime is not attached.");
         }
     }
+    wake = () => {
+        this.woken ??= setImmediate(() => {
+            this.woken = undefined;
+            this.scan();
+        }).unref();
+    };
+    recover = () => {
+        for (const [file, seen] of this.observed) {
+            if (pathStamp(file) !== seen) {
+                this.wake();
+                return;
+            }
+        }
+    };
     scan = () => {
+        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();
+        }
     };
+    /** Watches every directory that can publish an awaited input; legacy results may never exist. */
+    watch() {
+        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) => {
+            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";
+    }
+    unwatch() {
+        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();
+    }
     start(context) {
-        this.reset = this.reset.then(() => this.attach(context));
-        return this.reset;
+        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) => {
+            console.error(`Agent runtime attachment: ${errorText(error)}`);
+        });
+        return undefined;
+    }
+    ownerIdentity() {
+        return ownIdentity(this.host?.owner.pid);
     }
     async attach(context) {
-        clearInterval(this.timer);
+        this.unwatch();
         this.ctx = context;
         if (this.child) {
             return;
@@ -64,54 +198,52 @@ 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();
     }
-    async dispose() {
+    async dispose(retain) {
         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;
     }
+    releases(attachment) {
+        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);
+    }
     stop(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) => {
@@ -123,62 +255,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.",
-        };
-    }
-    interrupted(launch, signal, owned) {
-        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;
-    }
-    async wait(launch, signal, owned) {
-        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);
-        }
+        });
     }
     async delegate(input, signal, context) {
         this.checkMain();
@@ -197,28 +278,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.",
         });
     }
     list(input) {
         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);
     }
     successor(launch, prompt) {
         const id = randomUUID();
@@ -248,7 +318,7 @@ class AgentRuntime {
         }
         return;
     }
-    async retryContinuation(launch, input, signal) {
+    async retryContinuation(launch, input) {
         const identity = actor(this.base, launch);
         const command = read(path.join(conversation(this.base, launch), "commands", `${launch.id}.json`), commandSchema);
         if (input.prompt !== launch.prompt ||
@@ -256,16 +326,13 @@ class AgentRuntime {
             command?.id !== launch.id ||
             command.runId !== launch.id ||
             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.`);
+            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. 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" });
     }
-    async continue(launch, input, signal) {
+    async continue(launch, input) {
         if (input.prompt === undefined) {
             throw new Error("continue requires the entire new prompt.");
         }
@@ -274,16 +341,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.",
@@ -291,44 +354,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" });
+        await ensureActor(this.base, next, this.shutdown.signal);
+        return renderReceipt(this.base, next, this.ctx, { receipt: "continuation" });
     }
-    async guidance(launch, command, signal) {
-        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);
-        }
-    }
-    async continueSaved(input, signal, context) {
+    async continueSaved(input, context) {
         if (input.prompt === undefined) {
             throw new Error("continue requires the entire new prompt.");
         }
@@ -342,17 +377,13 @@ class AgentRuntime {
         if (created) {
             // The durable adoption claim survives ambiguous after-launch failures.
             enqueue(this.base, launch, "run");
-            await ensureActor(this.base, launch);
-        }
-        if (input.async === false) {
-            return this.wait(launch, signal, created);
+            await ensureActor(this.base, launch, this.shutdown.signal);
         }
-        return toolResult({
-            ...projection(this.base, launch, this.ctx),
+        return renderReceipt(this.base, launch, this.ctx, {
             receipt: created ? "continuation" : "existing-successor",
         });
     }
-    async runs(input, signal, context) {
+    async runs(input, context) {
         this.checkMain();
         await this.reset;
         if (input.action === "list") {
@@ -364,31 +395,32 @@ class AgentRuntime {
         }
         if (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));
+            return this.stop(launch);
         }
-        if (input.action === "wait") {
-            return this.wait(launch, signal, false);
-        }
-        return this.continue(launch, input, signal);
+        return this.continue(launch, input);
     }
     register() {
-        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") {
@@ -401,18 +433,20 @@ class AgentRuntime {
         this.pi.registerTool({
             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.",
+            description: "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 = (...args) => this.runs(args[1], args[2], args[4]);
+        const runs = (...args) => 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.",
+            description: "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,
         });
     }