@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/src/agent/runner.ts

@@ -1,6 +1,5 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
 import type {
   AgentSession,
   CreateAgentSessionRuntimeFactory,
@@ -8,19 +7,27 @@ import type {
   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, shellCommand, shells, signalProcess } from "./process.ts";
 import { errorText, loadSDK } from "./host.ts";
 import { childUsage } from "./usage.ts";
 import { initializeCwd, localCwdOwner } from "./cwd.ts";
+import { ActorObservation, type ObservationStats } from "./observation.ts";
+import type { ToolEvent } from "./observation-state.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,
@@ -56,10 +63,20 @@ function guard(pi: ExtensionAPI, directory: string, token: string): void {
 class Actor {
   private active?: Promise<void>;
   private stopping = false;
+  private stopDeadline?: NodeJS.Timeout;
+  private nextParentCheck = 0;
+  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;
@@ -164,6 +181,11 @@ class Actor {
               pi.on("session_start", (_event, ctx) => {
                 this.context = { pi, ctx };
               });
+              // Sparse tool lifecycle keeps the live view's tools even while nobody watches.
+              const tool = (event: ToolEvent): void => this.observation?.tool(event);
+              pi.on("tool_execution_start", tool);
+              pi.on("tool_execution_update", tool);
+              pi.on("tool_execution_end", tool);
             },
           ],
         },
@@ -191,12 +213,37 @@ class Actor {
     };
   }
   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 +251,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 +269,7 @@ class Actor {
       } finally {
         this.active = undefined;
         this.current = undefined;
+        this.observation?.working(false);
       }
     })();
   }
@@ -256,6 +305,7 @@ class Actor {
       command.action === "run" &&
       (this.stopping || this.active !== undefined || !session.isIdle)
     ) {
+      this.retry = true;
       return;
     }
     this.started.add(command.id);
@@ -306,6 +356,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 +381,46 @@ 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;
-    }
-    if (this.stopping) {
-      return true;
+    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.session && (!this.session.isIdle || this.session.pendingMessageCount > 0)) {
-      return false;
+    return this.stopping && this.active === undefined && (this.session?.isIdle ?? true);
+  }
+  /** Durable command readiness, not elapsed time, defines admission. */
+  private async admitCommands(): 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));
+        }
+        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();
     }
-    const attachment = read(path.join(this.base, "attachment.json"), attachmentSchema);
-    return attachment === undefined || !attachment.attached || !alive(attachment);
   }
   private failure(error: unknown): void {
     const launch = this.current ?? this.initial;
@@ -374,6 +465,12 @@ class Actor {
       if (this.initial.name !== undefined) {
         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,
@@ -386,22 +483,23 @@ class Actor {
       });
       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();
       await this.active;
     } catch (error) {
       this.failure(error);
     } finally {
       process.off("SIGTERM", this.stop);
       process.off("SIGINT", this.stop);
+      const observation: ObservationStats | undefined = this.observation?.close();
       await runtime?.dispose();
+      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 }),
       });
       // Keep the process claim until a launcher proves this exact actor is gone.
     }

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 {

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;

package/src/agent/usage.ts

@@ -1,12 +1,8 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Usage } from "@earendil-works/pi-ai";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { journalStamp } from "../shared/native-journal.ts";
-import { isDeepStrictEqual } from "node:util";
 import { nativeProjection } from "../shared/journal-projections.ts";
 import { scanJournal } from "../shared/journal-frames.ts";
-import type { Projection } from "../shared/json-projection.ts";
 import { isRecord } from "../shared/unknown.ts";
 import { Assert } from "./typebox.ts";
 import {
@@ -18,132 +14,6 @@ import {
 } from "./contracts.ts";
 import { read, runDirectory, write } from "./storage.ts";
 
-export function sumUsage(values: readonly Contribution[]): Usage {
-  const total: Usage = {
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    totalTokens: 0,
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-  };
-  for (const { usage } of values) {
-    for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
-      total[key] += usage[key];
-    }
-    for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
-      total.cost[key] += usage.cost[key];
-    }
-    for (const key of ["reasoning", "cacheWrite1h"] as const) {
-      if (usage[key] !== undefined) {
-        total[key] = (total[key] ?? 0) + usage[key];
-      }
-    }
-  }
-  return total;
-}
-function intents(details: unknown): Contribution[] | undefined {
-  if (!isRecord(details) || details.agentUsage === undefined) {
-    return;
-  }
-  const values: unknown = details.agentUsage;
-  Assert(contributionsSchema, values);
-  return values;
-}
-function publishedContributions(entry: unknown): Contribution[] {
-  if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message)) {
-    return [];
-  }
-  const message = entry.message;
-  if (
-    message.role !== "toolResult" ||
-    (message.toolName !== "delegate" && message.toolName !== "agent_runs")
-  ) {
-    return [];
-  }
-  const values = intents(message.details);
-  if (values === undefined || !isDeepStrictEqual(sumUsage(values), message.usage)) {
-    return [];
-  }
-  return values;
-}
-const receiptProjection: Projection = (keys) => {
-  if (keys.length === 0 || keys[0] === "type") {
-    return true;
-  }
-  if (keys[0] !== "message") {
-    return false;
-  }
-  if (keys.length === 1 || ["role", "toolName", "usage"].includes(String(keys[1]))) {
-    return true;
-  }
-  return keys[1] === "details" && (keys.length === 2 || keys[2] === "agentUsage");
-};
-function priorUsage(ctx: ExtensionContext): Map<string, Contribution> {
-  const values = new Map<string, Contribution>();
-  const file = ctx.sessionManager.getSessionFile();
-  if (file !== undefined) {
-    scanJournal(
-      file,
-      receiptProjection,
-      ({ value: entry }) => {
-        for (const value of publishedContributions(entry)) {
-          values.set(value.id, value);
-        }
-      },
-      { policy: "live", requireNewline: true },
-    );
-  }
-  for (const entry of ctx.sessionManager.getEntries()) {
-    for (const value of publishedContributions(entry)) {
-      values.set(value.id, value);
-    }
-  }
-  return values;
-}
-function uncharged(
-  values: readonly Contribution[],
-  prior: Map<string, Contribution>,
-): Contribution[] {
-  const pending: Contribution[] = [];
-  for (const value of values) {
-    const earlier = prior.get(value.id);
-    if (earlier && !isDeepStrictEqual(earlier, value)) {
-      throw new Error(`Conflicting native usage contribution ${value.id}`);
-    }
-    if (!earlier) {
-      pending.push(value);
-      prior.set(value.id, value);
-    }
-  }
-  return pending;
-}
-export function registerUsage(pi: ExtensionAPI): void {
-  pi.on("message_end", (event, ctx) => {
-    const message = event.message;
-    if (
-      message.role !== "toolResult" ||
-      (message.toolName !== "delegate" && message.toolName !== "agent_runs")
-    ) {
-      return;
-    }
-    const values = intents(message.details);
-    if (values === undefined || !isRecord(message.details)) {
-      return;
-    }
-    const pending = uncharged(values, priorUsage(ctx));
-    const { usage: _usage, ...rest } = message;
-    // Finalized native tool messages are serialized even for concurrent tools.
-    // Preparing or discarding a result cannot reserve a charge.
-    return {
-      message: {
-        ...rest,
-        details: { ...message.details, agentUsage: pending },
-        ...(pending.length > 0 ? { usage: sumUsage(pending) } : {}),
-      },
-    };
-  });
-}
 function billing(entry: Record<string, unknown>) {
   if (entry.checkpoint === true) {
     return;