@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/src/agent/runner.ts

@@ -1,26 +1,29 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-import type {
-  AgentSession,
-  CreateAgentSessionRuntimeFactory,
-  ExtensionAPI,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import {
-  attachmentSchema,
-  commandSchema,
-  type Command,
-  type Launch,
-  type Result,
-} from "./contracts.ts";
-import { launchAt, read, runDirectory, write } from "./storage.ts";
-import { alive, ownIdentity, shellCommand } from "./process.ts";
+import { commandSchema, type Command, type Launch, type Result } from "./contracts.ts";
+import { launchAt, missing, read, runDirectory, write } from "./storage.ts";
+import { ownIdentity, ParentCheck, shells, signalProcess } from "./process.ts";
 import { errorText, loadSDK } from "./host.ts";
+import { Parking, type Runtime } from "./parking.ts";
 import { childUsage } from "./usage.ts";
-import { initializeCwd, localCwdOwner } from "./cwd.ts";
+import { initializeCwd } from "./cwd.ts";
+import { childRuntime } from "./child-runtime.ts";
+import { ActorObservation, type ObservationStats } from "./observation.ts";
+import { DirectoryWatch, Wake } from "./wake.ts";
 
+function commandIdentity(file: string): string | undefined {
+  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: boolean,
   message: AssistantMessage | undefined,
@@ -34,32 +37,24 @@ function completionStatus(
   }
   return "completed";
 }
-function guard(pi: ExtensionAPI, directory: string, token: string): void {
-  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 {
   private active?: Promise<void>;
   private stopping = false;
+  private stopDeadline?: NodeJS.Timeout;
+  private nextParentCheck = 0;
+  private parking = false;
+  private readonly parent = new ParentCheck();
+  // Raised when durable commands may need admission: change hints and stop.
+  private readonly wake = new Wake();
+  // A deferred run waits for an idle session, which has no command-file event.
+  private retry = false;
   private current?: Launch;
   private readonly errors: string[] = [];
   private readonly started = new Set<string>();
+  // Actor-local validation metadata only; never retain command prompts or receipt authority.
+  private readonly validated = new Map<string, { identity: string; id: string }>();
   private session?: AgentSession;
+  private observation?: ActorObservation;
   private context?: { pi: ExtensionAPI; ctx: ExtensionContext };
   private readonly base: string;
   private readonly initial: Launch;
@@ -134,69 +129,38 @@ class Actor {
         .join("\n") ?? ""
     );
   }
-  private createRuntime(
-    sdk: Awaited<ReturnType<typeof loadSDK>>,
-  ): CreateAgentSessionRuntimeFactory {
-    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,
-      };
-    };
-  }
   private readonly stop = (): void => {
-    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: unknown) => {
       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();
   };
+  private stopShells(signal: NodeJS.Signals): void {
+    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));
+    }
+  }
   private run(launch: Launch): void {
     const session = this.session;
     if (!session) {
@@ -204,6 +168,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 (
@@ -221,6 +186,7 @@ class Actor {
       } finally {
         this.active = undefined;
         this.current = undefined;
+        this.observation?.working(false);
       }
     })();
   }
@@ -256,6 +222,7 @@ class Actor {
       command.action === "run" &&
       (this.stopping || this.active !== undefined || !session.isIdle)
     ) {
+      this.retry = true;
       return;
     }
     this.started.add(command.id);
@@ -306,6 +273,24 @@ class Actor {
       timestamp: Date.now(),
     });
   }
+  private pendingCommand(file: string): Command | undefined {
+    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;
+  }
   private pending(): Command[] {
     const dir = path.join(this.dir, "commands");
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -313,23 +298,79 @@ 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);
   }
   private shouldExit(): boolean {
-    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: unknown) => {
+        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. */
+  private async admitCommands(runtime: Runtime, parked: Parking): Promise<void> {
+    // 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);
+      }
+    } finally {
+      // A verdict settling after the loop ends must not act.
+      this.parent.cancel();
+      commands.close();
     }
-    if (this.session && (!this.session.isIdle || this.session.pendingMessageCount > 0)) {
-      return false;
+  }
+  /** Parks a final-idle actor; the parent/stop owner stays live while preparation awaits. */
+  private async park(runtime: Runtime, parked: Parking): Promise<boolean> {
+    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);
     }
-    const attachment = read(path.join(this.base, "attachment.json"), attachmentSchema);
-    return attachment === undefined || !attachment.attached || !alive(attachment);
+    return this.parking;
   }
   private failure(error: unknown): void {
     const launch = this.current ?? this.initial;
@@ -347,64 +388,101 @@ class Actor {
     }
     process.exitCode = 1;
   }
+  private async start(sdk: Awaited<ReturnType<typeof loadSDK>>, parked: Parking): Promise<Runtime> {
+    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;
+  }
+  private async ready(runtime: Runtime, parked: Parking): Promise<void> {
+    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(): Promise<void> {
     const sdk = await loadSDK(this.initial.sdk);
-    let runtime: Awaited<ReturnType<typeof sdk.createAgentSessionRuntime>> | undefined;
+    const parked = new Parking(this.base, this.initial, this.token, sdk);
+    let runtime: Runtime | undefined;
     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);
+    }
+  }
+  private async finish(runtime: Runtime | undefined): Promise<void> {
+    process.off("SIGTERM", this.stop);
+    process.off("SIGINT", this.stop);
+    const observation: ObservationStats | undefined = 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/src/agent/shell.ts

@@ -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.ts";
+import { readChildProcessIdentity, readProcessClock } from "../shared/post-exit-stdio-guard.ts";
 import { read, write } from "./storage.ts";
 import { processSchema } from "./contracts.ts";
 import { verifyProcess } from "./process.ts";
@@ -50,6 +50,7 @@ write(
     pid,
     identity,
     token,
+    clock: readProcessClock(),
   },
   true,
 );

package/src/agent/storage.ts

@@ -6,6 +6,7 @@ import type { Projection } from "../shared/json-projection.ts";
 import { Assert } from "./typebox.ts";
 import type { Static, TSchema } from "typebox";
 import { launchSchema, successorSchema, type Launch, type Command } from "./contracts.ts";
+import { hasErrorCode } from "../shared/unknown.ts";
 
 export function missing(error: unknown): boolean {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
@@ -25,28 +26,43 @@ export function read<T extends TSchema>(
     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;
 }
+/** Publish complete bytes without replacing a winner, even where Android denies hard links. */
+function publishExclusive(temp: string, file: string): boolean {
+  try {
+    fs.linkSync(temp, file);
+    return false;
+  } 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: string, value: unknown, exclusive = false): void {
   fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  const temp = `${file}.${randomUUID()}.tmp`;
+  const temp = `${file}.${randomUUID()}.${exclusive ? "data" : "tmp"}`;
   const fd = fs.openSync(temp, "wx", 0o600);
+  let retained = false;
   try {
-    fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
-    fs.fsyncSync(fd);
-  } finally {
-    fs.closeSync(fd);
-  }
-  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: string): string {
@@ -68,6 +84,23 @@ export function launchAt(base: string, id: string, owner: string): Launch {
   }
   return launch;
 }
+/** Claims the single successor of a saved run; undefined when another caller already has. */
+export function successor(base: string, launch: Launch, prompt: string): Launch | undefined {
+  const id = randomUUID();
+  const next: Launch = { ...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: string, initial: Launch): Launch {
   const seen = new Set<string>();
   let launch = initial;

package/src/agent/tool-schemas.ts

@@ -0,0 +1,33 @@
+import type { Static } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "./typebox.ts";
+
+// 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"] as const)),
+  },
+  { additionalProperties: false },
+);
+export type DelegateInput = Static<typeof delegateSchema>;
+export const runsSchema = Type.Object(
+  {
+    action: StringEnum(["list", "inspect", "continue", "stop"] as const),
+    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 },
+);
+export type RunsInput = Static<typeof runsSchema>;

package/src/agent/typebox.ts

@@ -3,15 +3,20 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import type * as NativeTypebox from "typebox";
 import type * as NativeValue from "typebox/value";
-import { packageRoot } from "./host.ts";
+import { isChild, packageRoot } from "./host.ts";
 
-const require = createRequire(path.join(packageRoot(), "dist/index.js"));
-// The detached runner needs the selected host's dependencies, not Jiti aliases.
+// 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: typeof NativeTypebox = await import(pathToFileURL(require.resolve("typebox")).href);
+const typebox: typeof NativeTypebox =
+  require === undefined
+    ? await import("typebox")
+    : await import(pathToFileURL(require.resolve("typebox")).href);
 // oxlint-disable-next-line typescript/no-unsafe-assignment
-const value: typeof NativeValue = await import(
-  pathToFileURL(require.resolve("typebox/value")).href
-);
+const value: typeof NativeValue =
+  require === undefined
+    ? await import("typebox/value")
+    : await import(pathToFileURL(require.resolve("typebox/value")).href);
 export const { Type } = typebox;
 export const Assert: typeof NativeValue.Assert = value.Assert;