@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/agent/runner.js

@@ -1,12 +1,27 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-import { attachmentSchema, commandSchema, } from "./contracts.js";
-import { launchAt, read, runDirectory, write } from "./storage.js";
-import { alive, ownIdentity, shellCommand } from "./process.js";
+import { commandSchema } from "./contracts.js";
+import { launchAt, missing, read, runDirectory, write } from "./storage.js";
+import { ownIdentity, ParentCheck, shells, signalProcess } from "./process.js";
 import { errorText, loadSDK } from "./host.js";
+import { Parking } from "./parking.js";
 import { childUsage } from "./usage.js";
-import { initializeCwd, localCwdOwner } from "./cwd.js";
+import { initializeCwd } from "./cwd.js";
+import { childRuntime } from "./child-runtime.js";
+import { ActorObservation } from "./observation.js";
+import { DirectoryWatch, Wake } from "./wake.js";
+function commandIdentity(file) {
+    try {
+        const stat = fs.statSync(file, { bigint: true });
+        return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    }
+    catch (error) {
+        if (missing(error)) {
+            return;
+        }
+        throw error;
+    }
+}
 function completionStatus(stopping, message, error) {
     if (stopping || message?.stopReason === "aborted") {
         return "stopped";
@@ -16,30 +31,24 @@ function completionStatus(stopping, message, error) {
     }
     return "completed";
 }
-function guard(pi, directory, token) {
-    pi.on("tool_call", (event) => {
-        if (event.toolName === "delegate" || event.toolName === "agent_runs") {
-            return { block: true, reason: "Only a main session may delegate or control children." };
-        }
-        const owner = pi.getAllTools().find((tool) => tool.name === "bash")?.sourceInfo;
-        if (event.toolName === "bash" &&
-            typeof event.input.command === "string" &&
-            owner &&
-            (owner.source === "builtin" || localCwdOwner(owner))) {
-            // Preserve the selected local owner's cwd/env and leave remote/custom tools alone.
-            const input = event.input;
-            input.command = shellCommand(event.input.command, directory, token);
-        }
-        return;
-    });
-}
 class Actor {
     active;
     stopping = false;
+    stopDeadline;
+    nextParentCheck = 0;
+    parking = false;
+    parent = new ParentCheck();
+    // Raised when durable commands may need admission: change hints and stop.
+    wake = new Wake();
+    // A deferred run waits for an idle session, which has no command-file event.
+    retry = false;
     current;
     errors = [];
     started = new Set();
+    // Actor-local validation metadata only; never retain command prompts or receipt authority.
+    validated = new Map();
     session;
+    observation;
     context;
     base;
     initial;
@@ -105,65 +114,40 @@ class Actor {
             .map((block) => block.text)
             .join("\n") ?? "");
     }
-    createRuntime(sdk) {
-        return async ({ sessionManager }) => {
-            const launch = this.initial;
-            if (!fs.existsSync(launch.sessionFile)) {
-                throw new Error("Missing saved native session; refusing to create another.");
-            }
-            const settingsManager = sdk.SettingsManager.create(launch.cwd, launch.agentDir, {
-                projectTrusted: launch.trusted,
-            });
-            const services = await sdk.createAgentSessionServices({
-                cwd: launch.cwd,
-                agentDir: launch.agentDir,
-                settingsManager,
-                resourceLoaderOptions: {
-                    additionalExtensionPaths: [launch.entry],
-                    extensionFactories: [
-                        {
-                            name: "codemode",
-                            builtin: true,
-                            factory: sdk.createCodemodeExtension({ mode: "on" }),
-                        },
-                        { name: "tool_search", builtin: true, factory: sdk.createToolSearchExtension() },
-                        { name: "mcp", builtin: true, factory: sdk.createMcpExtension() },
-                        (pi) => {
-                            guard(pi, this.dir, this.token);
-                            pi.on("session_start", (_event, ctx) => {
-                                this.context = { pi, ctx };
-                            });
-                        },
-                    ],
-                },
-            });
-            const diagnostics = services.resourceLoader.getExtensions().errors;
-            if (diagnostics.length > 0) {
-                throw new Error(`Child extension load failed: ${JSON.stringify(diagnostics)}`);
-            }
-            const model = services.modelRuntime.getModel(launch.provider, launch.model);
-            if (!model) {
-                throw new Error(`Saved model ${launch.provider}/${launch.model} is unavailable; no fallback was used.`);
-            }
-            return {
-                ...(await sdk.createAgentSessionFromServices({
-                    services,
-                    sessionManager,
-                    model,
-                    thinkingLevel: launch.thinking,
-                })),
-                services,
-                diagnostics: services.diagnostics,
-            };
-        };
-    }
     stop = () => {
-        write(path.join(this.dir, "stop-acknowledged.json"), { at: Date.now(), id: this.current?.id });
+        if (this.stopping) {
+            return;
+        }
         this.stopping = true;
+        this.wake.raise();
+        write(path.join(this.dir, `stopping-${this.token}.json`), { at: Date.now() });
+        write(path.join(this.dir, "stop-acknowledged.json"), { at: Date.now(), id: this.current?.id });
         this.session?.abort().catch((error) => {
             this.errors.push(errorText(error));
         });
+        this.stopShells("SIGTERM");
+        // Parent death leaves no parent-side escalation timer to stop an uncooperative tool.
+        this.stopDeadline = setTimeout(() => {
+            this.stopShells("SIGKILL");
+            process.exit(1);
+        }, 3000);
+        this.stopDeadline.unref();
     };
+    stopShells(signal) {
+        try {
+            for (const identity of shells(this.base, this.initial, this.token)) {
+                try {
+                    signalProcess(identity, signal);
+                }
+                catch (error) {
+                    this.errors.push(errorText(error));
+                }
+            }
+        }
+        catch (error) {
+            this.errors.push(errorText(error));
+        }
+    }
     run(launch) {
         const session = this.session;
         if (!session) {
@@ -171,6 +155,7 @@ class Actor {
         }
         this.current = launch;
         const baseline = new Set(session.sessionManager.getEntries().map((entry) => entry.id));
+        this.observation?.working(true);
         this.active = (async () => {
             try {
                 if (launch.provider !== this.initial.provider ||
@@ -188,6 +173,7 @@ class Actor {
             finally {
                 this.active = undefined;
                 this.current = undefined;
+                this.observation?.working(false);
             }
         })();
     }
@@ -219,6 +205,7 @@ class Actor {
         }
         if (command.action === "run" &&
             (this.stopping || this.active !== undefined || !session.isIdle)) {
+            this.retry = true;
             return;
         }
         this.started.add(command.id);
@@ -263,6 +250,22 @@ class Actor {
             timestamp: Date.now(),
         });
     }
+    pendingCommand(file) {
+        const identity = commandIdentity(file);
+        const cached = this.validated.get(file);
+        if (identity !== undefined &&
+            cached?.identity === identity &&
+            fs.existsSync(path.join(this.dir, "admissions", `${cached.id}.json`))) {
+            return;
+        }
+        this.validated.delete(file);
+        const command = read(file, commandSchema);
+        // A replacement during validation must not inherit the old body's validated identity.
+        if (command && identity !== undefined && commandIdentity(file) === identity) {
+            this.validated.set(file, { identity, id: command.id });
+        }
+        return command;
+    }
     pending() {
         const dir = path.join(this.dir, "commands");
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -270,23 +273,81 @@ class Actor {
             .readdirSync(dir)
             .filter((file) => file.endsWith(".json"))
             .flatMap((file) => {
-            const command = read(path.join(dir, file), commandSchema);
+            const command = this.pendingCommand(path.join(dir, file));
             return command ? [command] : [];
         })
             .sort((a, b) => a.createdAt - b.createdAt);
     }
     shouldExit() {
-        if (this.active !== undefined) {
-            return false;
+        const now = performance.now();
+        if (!this.stopping && now >= this.nextParentCheck) {
+            this.nextParentCheck = now + 1000;
+            // One observation at a time; a slow one keeps the regular schedule.
+            const file = path.join(this.base, "attachment.json");
+            this.parent.check(file, this.stop).catch((error) => {
+                this.errors.push(errorText(error));
+            });
         }
-        if (this.stopping) {
-            return true;
+        return this.stopping && this.active === undefined && (this.session?.isIdle ?? true);
+    }
+    /** Durable command readiness, not elapsed time, defines admission. */
+    async admitCommands(runtime, parked) {
+        // Queued commands create this directory; otherwise pending() does and the next pass arms.
+        const directory = path.join(this.dir, "commands");
+        const commands = new DirectoryWatch(directory, () => true, this.wake.raise);
+        try {
+            while (!this.shouldExit()) {
+                // Each liveness tick also rechecks the directory for change hints the OS dropped.
+                const watch = commands.ensure();
+                if ((this.wake.take() || this.retry || watch !== "watching") && !this.stopping) {
+                    this.retry = false;
+                    this.pending().forEach((command) => this.accept(command));
+                }
+                // oxlint-disable-next-line no-await-in-loop
+                if (await this.park(runtime, parked)) {
+                    return;
+                }
+                const polling = this.retry || this.stopping || watch === "unwatched";
+                const tick = Math.max(1, this.nextParentCheck - performance.now());
+                // oxlint-disable-next-line no-await-in-loop
+                await this.wake.sleep(polling ? 100 : tick);
+            }
         }
-        if (this.session && (!this.session.isIdle || this.session.pendingMessageCount > 0)) {
-            return false;
+        finally {
+            // A verdict settling after the loop ends must not act.
+            this.parent.cancel();
+            commands.close();
         }
-        const attachment = read(path.join(this.base, "attachment.json"), attachmentSchema);
-        return attachment === undefined || !attachment.attached || !alive(attachment);
+    }
+    /** Parks a final-idle actor; the parent/stop owner stays live while preparation awaits. */
+    async park(runtime, parked) {
+        const owner = new AbortController();
+        const watch = setInterval(() => {
+            if (this.shouldExit() || this.stopping) {
+                owner.abort();
+            }
+        }, 100);
+        try {
+            this.parking = await parked.park(runtime, {
+                signal: owner.signal,
+                pi: this.context?.pi,
+                busy: this.stopping || this.active !== undefined || this.observation?.watched === true,
+                // Raced commands and viewers keep this actor resident; the loop admits after release.
+                quiet: () => {
+                    const queued = this.pending().some((command) => this.commandLaunch(command));
+                    if (queued) {
+                        this.wake.raise();
+                    }
+                    const idle = this.active === undefined && !this.stopping;
+                    return !queued && idle && this.observation?.watched !== true;
+                },
+                errors: this.errors,
+            });
+        }
+        finally {
+            clearInterval(watch);
+        }
+        return this.parking;
     }
     failure(error) {
         const launch = this.current ?? this.initial;
@@ -304,62 +365,104 @@ class Actor {
         }
         process.exitCode = 1;
     }
+    async start(sdk, parked) {
+        const sessionManager = parked.open();
+        const factory = childRuntime(sdk, this.initial, {
+            directory: this.dir,
+            token: this.token,
+            saved: parked.saved,
+            started: (pi, ctx) => {
+                this.context = { pi, ctx };
+            },
+            tool: (event) => this.observation?.tool(event),
+        });
+        const runtime = await sdk.createAgentSessionRuntime(factory, {
+            cwd: this.initial.cwd,
+            agentDir: this.initial.agentDir,
+            sessionManager,
+        });
+        try {
+            await this.ready(runtime, parked);
+        }
+        catch (error) {
+            // A runtime that never became ready is still disposed, so the failed actor exits.
+            await runtime.dispose();
+            throw error;
+        }
+        return runtime;
+    }
+    async ready(runtime, parked) {
+        this.session = runtime.session;
+        await this.session.bindExtensions({
+            mode: "print",
+            onError: (error) => {
+                this.errors.push(error.error);
+            },
+        });
+        if (!this.context) {
+            throw new Error("Child extension context is unavailable.");
+        }
+        initializeCwd(this.context.pi, this.context.ctx, this.initial.cwd, this.dir);
+        if (this.initial.name !== undefined && !parked.saved) {
+            this.session.sessionManager.appendSessionInfo(this.initial.name);
+        }
+        // Optional live view, bound before readiness; its faults never change native execution.
+        this.observation = await ActorObservation.open(this.session, {
+            token: this.token,
+            rootId: this.initial.rootId,
+            sessionId: this.session.sessionManager.getSessionId(),
+        });
+        write(path.join(this.dir, "actor.lock", "process.json"), {
+            ...ownIdentity(),
+            token: this.token,
+        });
+        write(path.join(this.dir, "ready.json"), {
+            pid: process.pid,
+            token: this.token,
+            sessionId: this.session.sessionManager.getSessionId(),
+            at: Date.now(),
+        });
+        parked.adopt();
+    }
     async serve() {
         const sdk = await loadSDK(this.initial.sdk);
+        const parked = new Parking(this.base, this.initial, this.token, sdk);
         let runtime;
         try {
-            runtime = await sdk.createAgentSessionRuntime(this.createRuntime(sdk), {
-                cwd: this.initial.cwd,
-                agentDir: this.initial.agentDir,
-                sessionManager: sdk.SessionManager.open(this.initial.sessionFile, undefined, this.initial.cwd),
-            });
-            this.session = runtime.session;
-            await this.session.bindExtensions({
-                mode: "print",
-                onError: (error) => {
-                    this.errors.push(error.error);
-                },
-            });
-            if (!this.context) {
-                throw new Error("Child extension context is unavailable.");
-            }
-            initializeCwd(this.context.pi, this.context.ctx, this.initial.cwd, this.dir);
-            if (this.initial.name !== undefined) {
-                this.session.sessionManager.appendSessionInfo(this.initial.name);
-            }
-            write(path.join(this.dir, "actor.lock", "process.json"), {
-                ...ownIdentity(),
-                token: this.token,
-            });
-            write(path.join(this.dir, "ready.json"), {
-                pid: process.pid,
-                token: this.token,
-                sessionId: this.session.sessionManager.getSessionId(),
-                at: Date.now(),
-            });
+            runtime = await this.start(sdk, parked);
             process.on("SIGTERM", this.stop);
             process.on("SIGINT", this.stop);
-            do {
-                this.pending().forEach((command) => this.accept(command));
-                // Durable command readiness, not elapsed time, defines admission.
-                // oxlint-disable-next-line no-await-in-loop
-                await delay(100);
-            } while (!this.shouldExit());
+            await this.admitCommands(runtime, parked);
             await this.active;
         }
         catch (error) {
             this.failure(error);
         }
         finally {
-            process.off("SIGTERM", this.stop);
-            process.off("SIGINT", this.stop);
+            await this.finish(runtime);
+        }
+    }
+    async finish(runtime) {
+        process.off("SIGTERM", this.stop);
+        process.off("SIGINT", this.stop);
+        const observation = this.observation?.close();
+        if (!this.parking) {
             await runtime?.dispose();
-            write(path.join(this.dir, `shutdown-${this.token}.json`), {
-                at: Date.now(),
-                errors: this.errors,
-            });
-            // Keep the process claim until a launcher proves this exact actor is gone.
         }
+        if (this.stopping) {
+            this.stopShells("SIGKILL");
+        }
+        clearTimeout(this.stopDeadline);
+        write(path.join(this.dir, `shutdown-${this.token}.json`), {
+            at: Date.now(),
+            errors: this.errors,
+            ...(observation === undefined ? {} : { observation }),
+        });
+        if (this.parking) {
+            // Parked authority requires actual exit; no leftover extension handle may keep it alive.
+            process.exit();
+        }
+        // Keep the process claim until a launcher proves this exact actor is gone.
     }
 }
 const base = process.argv.at(2);

package/dist/agent/shell.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { readChildProcessIdentity } from "../shared/post-exit-stdio-guard.js";
+import { readChildProcessIdentity, readProcessClock } from "../shared/post-exit-stdio-guard.js";
 import { read, write } from "./storage.js";
 import { processSchema } from "./contracts.js";
 import { verifyProcess } from "./process.js";
@@ -39,5 +39,6 @@ write(path.join(directory, "shells", token, `${randomUUID()}.json`), {
     pid,
     identity,
     token,
+    clock: readProcessClock(),
 }, true);
 verifyOwner(directory, token);

package/dist/agent/storage.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { readJsonProjection } from "../shared/journal-frames.js";
 import { Assert } from "./typebox.js";
 import { launchSchema, successorSchema } from "./contracts.js";
+import { hasErrorCode } from "../shared/unknown.js";
 export function missing(error) {
     return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
@@ -19,31 +20,47 @@ export function read(file, schema, select = () => true) {
         throw error;
     }
     Assert(schema, value);
-    // TypeBox's generic Static<T> is intentionally the asserted schema's type.
-    // oxlint-disable-next-line typescript/no-unsafe-return
     return value;
 }
-export function write(file, value, exclusive = false) {
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    const temp = `${file}.${randomUUID()}.tmp`;
-    const fd = fs.openSync(temp, "wx", 0o600);
+/** Publish complete bytes without replacing a winner, even where Android denies hard links. */
+function publishExclusive(temp, file) {
     try {
-        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
-        fs.fsyncSync(fd);
+        fs.linkSync(temp, file);
+        return false;
     }
-    finally {
-        fs.closeSync(fd);
+    catch (error) {
+        if (!["EACCES", "EPERM", "ENOTSUP"].some((code) => hasErrorCode(error, code))) {
+            throw error;
+        }
+        // The immutable, private backing file must outlive its atomic no-clobber symlink.
+        fs.symlinkSync(path.basename(temp), file);
+        return true;
     }
+}
+export function write(file, value, exclusive = false) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${randomUUID()}.${exclusive ? "data" : "tmp"}`;
+    const fd = fs.openSync(temp, "wx", 0o600);
+    let retained = false;
     try {
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
         if (exclusive) {
-            fs.linkSync(temp, file);
+            retained = publishExclusive(temp, file);
         }
         else {
             fs.renameSync(temp, file);
         }
     }
     finally {
-        fs.rmSync(temp, { force: true });
+        if (!retained) {
+            fs.rmSync(temp, { force: true });
+        }
     }
 }
 export function safeId(id) {
@@ -65,6 +82,24 @@ export function launchAt(base, id, owner) {
     }
     return launch;
 }
+/** Claims the single successor of a saved run; undefined when another caller already has. */
+export function successor(base, launch, prompt) {
+    const id = randomUUID();
+    const next = { ...launch, id, predecessor: launch.id, prompt, createdAt: Date.now() };
+    fs.mkdirSync(runDirectory(base, id), { mode: 0o700 });
+    write(path.join(runDirectory(base, id), "launch.json"), next, true);
+    try {
+        write(path.join(runDirectory(base, launch.id), "successor.json"), { id }, true);
+    }
+    catch (error) {
+        fs.rmSync(runDirectory(base, id), { recursive: true });
+        if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) {
+            throw error;
+        }
+        return undefined;
+    }
+    return next;
+}
 export function latest(base, initial) {
     const seen = new Set();
     let launch = initial;

package/dist/agent/tool-schemas.js

@@ -0,0 +1,20 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "./typebox.js";
+// Main-session tool parameters only; the detached runner must not load pi-ai values.
+export const delegateSchema = Type.Object({
+    prompt: Type.String({ minLength: 1 }),
+    name: Type.Optional(Type.String({ minLength: 1 })),
+    cwd: Type.Optional(Type.String({ minLength: 1 })),
+    model: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Exact provider/model ID (:thinking and any case need host support); no fuzzy match or fallback.",
+    })),
+    context: Type.Optional(StringEnum(["fresh", "fork"])),
+}, { additionalProperties: false });
+export const runsSchema = Type.Object({
+    action: StringEnum(["list", "inspect", "continue", "stop"]),
+    id: Type.Optional(Type.String()),
+    prompt: Type.Optional(Type.String({ minLength: 1 })),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    length: Type.Optional(Type.Integer({ minimum: 4, maximum: 262144 })),
+}, { additionalProperties: false });

package/dist/agent/typebox.js

@@ -9,12 +9,17 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
-import { packageRoot } from "./host.js";
-const require = createRequire(path.join(packageRoot(), "dist/index.js"));
-// The detached runner needs the selected host's dependencies, not Jiti aliases.
+import { isChild, packageRoot } from "./host.js";
+// Pi aliases these imports to its own instance (including bundled virtual modules).
+// Only the detached runner needs absolute imports from the selected host package.
+const require = isChild() ? createRequire(path.join(packageRoot(), "dist/index.js")) : undefined;
 // oxlint-disable-next-line typescript/no-unsafe-assignment
-const typebox = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox")).href));
+const typebox = require === undefined
+    ? await import("typebox")
+    : await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox")).href));
 // oxlint-disable-next-line typescript/no-unsafe-assignment
-const value = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox/value")).href));
+const value = require === undefined
+    ? await import("typebox/value")
+    : await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox/value")).href));
 export const { Type } = typebox;
 export const Assert = value.Assert;