@fitchmultz/pi-subagents 0.49.0 → 0.50.0

package/src/agent/index.ts

@@ -0,0 +1,486 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import {
+  actor,
+  alive,
+  ensureActor,
+  ownIdentity,
+  signalProcess,
+  verifyProcess,
+  shells,
+} from "./process.ts";
+import { isChild, errorText } from "./host.ts";
+import {
+  delegateSchema,
+  runsSchema,
+  resultSchema,
+  attachmentSchema,
+  admissionSchema,
+  commandSchema,
+  type Launch,
+  type Result,
+  type DelegateInput,
+  type RunsInput,
+} from "./contracts.ts";
+import {
+  enqueue,
+  latest,
+  launchAt,
+  list,
+  read,
+  runDirectory,
+  ownerDirectory,
+  conversation,
+  write,
+} from "./storage.ts";
+import { hold, notify, settle, release } from "./notifications.ts";
+import { prepareLaunch } from "./launch.ts";
+import { toolResult, projection, render, summaries } from "./view.ts";
+import { registerUsage } from "./usage.ts";
+import { notifyLegacy } from "./legacy.ts";
+import { savedContinuation } from "./saved.ts";
+import { executionCwd } from "./cwd.ts";
+import { getPiAgentDir } from "../pi-intercom/agent-dir.ts";
+
+class AgentRuntime {
+  private ctx?: ExtensionContext;
+  private base = "";
+  private owner = "";
+  private generation = "";
+  private timer?: NodeJS.Timeout;
+  private closing = false;
+  private reset: Promise<void> = Promise.resolve();
+  private readonly shutdown = new AbortController();
+  private readonly child = isChild();
+  private readonly agentDir = path.resolve(getPiAgentDir());
+  private readonly pi: ExtensionAPI;
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi;
+  }
+  private checkMain(): void {
+    if (isChild()) {
+      throw new Error("Only a main session may delegate or control agent runs.");
+    }
+    if (this.closing || !this.ctx || this.base.length === 0) {
+      throw new Error("Agent runtime is not attached.");
+    }
+  }
+  private readonly scan = (): void => {
+    if (this.closing || !this.ctx || this.child) {
+      return;
+    }
+    try {
+      notify(this.pi, this.ctx, this.base, this.owner);
+      notifyLegacy(this.pi, this.ctx);
+    } catch (error) {
+      console.error(`Agent completion reconciliation: ${errorText(error)}`);
+    }
+  };
+  private start(context: ExtensionContext): Promise<void> {
+    this.reset = this.reset.then(() => this.attach(context));
+    return this.reset;
+  }
+  private async attach(context: ExtensionContext): Promise<void> {
+    clearInterval(this.timer);
+    this.ctx = context;
+    if (this.child) {
+      return;
+    }
+    this.owner = context.sessionManager.getSessionId();
+    this.base = ownerDirectory(this.agentDir, this.owner);
+    this.generation = randomUUID();
+    await fs.promises.mkdir(this.base, { recursive: true, mode: 0o700 });
+    write(path.join(this.base, "attachment.json"), {
+      ...ownIdentity(),
+      generation: this.generation,
+      attached: true,
+    });
+    if (this.closing) {
+      return;
+    }
+    this.timer = setInterval(this.scan, 200);
+    this.timer.unref();
+    this.scan();
+  }
+  private async dispose(): Promise<void> {
+    this.closing = true;
+    clearInterval(this.timer);
+    this.shutdown.abort();
+    await this.reset;
+    if (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 });
+      }
+    }
+    this.ctx = undefined;
+  }
+  private stop(launch: Launch) {
+    const base = this.base;
+    const identity = actor(base, launch);
+    const targets = identity ? [identity, ...shells(base, launch, identity.token)] : [];
+    // Verify all targets before admitting a request or signaling any process.
+    const live = targets.filter(verifyProcess);
+    if (live.length === 0) {
+      return {
+        ...projection(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) => {
+          signalProcess(target, "SIGKILL");
+        });
+      } catch (error) {
+        console.error(`Agent stop escalation: ${errorText(error)}`);
+      }
+    }, 3000);
+    escalation.unref();
+    return {
+      ...projection(base, launch, this.ctx),
+      stopRequest: id,
+      stopAcknowledged: false,
+      note: "Stop requested; neither native admission nor process exit is implied.",
+    };
+  }
+  private interrupted(launch: Launch, signal: AbortSignal | undefined, owned: boolean) {
+    if (this.shutdown.signal.aborted) {
+      return toolResult({
+        ...projection(this.base, launch, this.ctx),
+        wait: "detached",
+        note: "Parent runtime disposed; producer was not stopped.",
+      });
+    }
+    if (signal?.aborted === true) {
+      if (owned) {
+        this.stop(launch);
+      }
+      return toolResult({
+        ...projection(this.base, launch, this.ctx),
+        wait: "cancelled",
+        note: owned
+          ? "Owned foreground work was asked to stop; exit is unconfirmed."
+          : "Only the wait was cancelled; producer was not stopped.",
+      });
+    }
+    const identity = actor(this.base, launch);
+    if (identity && !alive(identity)) {
+      return toolResult({
+        ...projection(this.base, launch, this.ctx),
+        wait: "interrupted",
+        note: "Actor is not live; no completion or exit code was invented.",
+      });
+    }
+    return;
+  }
+  private async wait(launch: Launch, signal: AbortSignal | undefined, owned: boolean) {
+    const held = hold(this.owner, launch.id);
+    for (;;) {
+      const result = read(
+        path.join(runDirectory(this.base, launch.id), "result.json"),
+        resultSchema,
+      );
+      if (result) {
+        hold(this.owner, launch.id);
+        return render(this.base, launch, this.ctx, { receivedResult: true });
+      }
+      const interruption = this.interrupted(launch, signal, owned);
+      if (interruption) {
+        if (held) {
+          release(this.owner, launch.id);
+        }
+        return interruption;
+      }
+      // Cancellation of an observer never removes canonical producer state.
+      // oxlint-disable-next-line no-await-in-loop
+      await delay(50);
+    }
+  }
+  private async delegate(
+    input: DelegateInput,
+    signal: AbortSignal | undefined,
+    context: ExtensionContext,
+  ) {
+    this.checkMain();
+    await this.reset;
+    if (signal?.aborted === true) {
+      throw new Error("Delegation cancelled before launch.");
+    }
+    const launch = await prepareLaunch({
+      input,
+      context,
+      base: this.base,
+      owner: this.owner,
+      agentDir: this.agentDir,
+      thinking: context.thinkingLevel ?? this.pi.getThinkingLevel(),
+      executionCwd: executionCwd(this.pi, context),
+    });
+    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),
+      receipt: "launch",
+      note: "Launch accepted, not actual completion or native receipt publication.",
+    });
+  }
+  private list(input: RunsInput) {
+    const all = list(this.base)
+      .map((id) => launchAt(this.base, id, this.owner))
+      .sort((a, b) => a.createdAt - b.createdAt);
+    const offset = input.offset ?? 0;
+    const page = summaries(this.base, all.slice(offset, offset + 50), this.ctx);
+    return toolResult({
+      runs: page,
+      offset,
+      nextOffset: offset + page.length < all.length ? offset + page.length : undefined,
+      total: all.length,
+    });
+  }
+  private successor(launch: Launch, prompt: string): Launch | undefined {
+    const id = randomUUID();
+    const next: Launch = { ...launch, id, predecessor: launch.id, prompt, createdAt: Date.now() };
+    fs.mkdirSync(runDirectory(this.base, id), { mode: 0o700 });
+    write(path.join(runDirectory(this.base, id), "launch.json"), next, true);
+    try {
+      write(path.join(runDirectory(this.base, launch.id), "successor.json"), { id }, true);
+    } catch (error) {
+      fs.rmSync(runDirectory(this.base, id), { recursive: true });
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) {
+        throw error;
+      }
+      return undefined;
+    }
+    return next;
+  }
+  private continuationResult(launch: Launch): Result | "pending" | undefined {
+    const result = read(path.join(runDirectory(this.base, launch.id), "result.json"), resultSchema);
+    if (result) {
+      return result;
+    }
+    const admission = read(
+      path.join(conversation(this.base, launch), "admissions", `${launch.id}.json`),
+      admissionSchema,
+    );
+    if (!admission || admission.id !== launch.id || admission.action !== "run") {
+      return "pending";
+    }
+    return;
+  }
+  private async retryContinuation(
+    launch: Launch,
+    input: RunsInput,
+    signal: AbortSignal | undefined,
+  ) {
+    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 ||
+      (identity && alive(identity)) ||
+      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.`,
+      );
+    }
+    // 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" });
+  }
+  private async continue(launch: Launch, input: RunsInput, signal: AbortSignal | undefined) {
+    if (input.prompt === undefined) {
+      throw new Error("continue requires the entire new prompt.");
+    }
+    if (!fs.existsSync(launch.sessionFile)) {
+      throw new Error("Missing saved native session; no process was launched.");
+    }
+    const completed = this.continuationResult(launch);
+    if (completed === "pending") {
+      return this.retryContinuation(launch, input, signal);
+    }
+    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),
+        receipt: "guidance",
+        command,
+        note: "Guidance queued, not actual completion or model consumption.",
+      });
+    }
+    const next = this.successor(launch, input.prompt);
+    if (!next) {
+      return toolResult({
+        ...projection(this.base, latest(this.base, launch), this.ctx),
+        receipt: "existing-successor",
+      });
+    }
+    // Retain successor claims on ambiguous after-launch failures: no replay.
+    enqueue(this.base, next, "run");
+    await ensureActor(this.base, next);
+    if (input.async === false) {
+      return this.wait(next, signal, true);
+    }
+    return toolResult({ ...projection(this.base, next, this.ctx), receipt: "continuation" });
+  }
+  private async guidance(launch: Launch, command: string, signal: AbortSignal | undefined) {
+    const file = path.join(conversation(this.base, launch), "admissions", `${command}.json`);
+    for (;;) {
+      const admission = read(file, admissionSchema);
+      if (admission) {
+        if (admission.state === "stale") {
+          return toolResult({
+            ...projection(this.base, launch, this.ctx),
+            command,
+            guidance: "stale",
+            note: "The native turn settled before guidance admission. Retry the entire prompt as a continuation; no new work was started.",
+          });
+        }
+        return this.wait(launch, signal, false);
+      }
+      const interruption = this.interrupted(launch, signal, false);
+      if (interruption) {
+        return interruption;
+      }
+      // Observe the actor's actual admission, not a timer-based model-consumption claim.
+      // oxlint-disable-next-line no-await-in-loop
+      await delay(50);
+    }
+  }
+  private async continueSaved(
+    input: RunsInput & { id: string },
+    signal: AbortSignal | undefined,
+    context: ExtensionContext,
+  ) {
+    if (input.prompt === undefined) {
+      throw new Error("continue requires the entire new prompt.");
+    }
+    const { launch, created } = savedContinuation({
+      id: input.id,
+      prompt: input.prompt,
+      context,
+      base: this.base,
+      agentDir: this.agentDir,
+    });
+    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);
+    }
+    return toolResult({
+      ...projection(this.base, launch, this.ctx),
+      receipt: created ? "continuation" : "existing-successor",
+    });
+  }
+  private async runs(input: RunsInput, signal: AbortSignal | undefined, context: ExtensionContext) {
+    this.checkMain();
+    await this.reset;
+    if (input.action === "list") {
+      return this.list(input);
+    }
+    this.scan();
+    if (input.id === undefined) {
+      throw new Error("id is required.");
+    }
+    if (
+      input.action === "continue" &&
+      !fs.existsSync(path.join(runDirectory(this.base, input.id), "launch.json"))
+    ) {
+      return this.continueSaved({ ...input, id: input.id }, signal, context);
+    }
+    const original = launchAt(this.base, input.id, this.owner);
+    if (input.action === "inspect") {
+      return render(this.base, original, this.ctx, input);
+    }
+    const launch = latest(this.base, original);
+    if (input.action === "stop") {
+      return toolResult(this.stop(launch));
+    }
+    if (input.action === "wait") {
+      return this.wait(launch, signal, false);
+    }
+    return this.continue(launch, input, signal);
+  }
+  register(): void {
+    registerUsage(this.pi);
+    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("agent_settled", () => {
+      this.scan();
+    });
+    this.pi.on("session_shutdown", () => this.dispose());
+    if (this.child) {
+      this.pi.on("tool_call", (event) => {
+        if (event.toolName === "delegate" || event.toolName === "agent_runs") {
+          return { block: true, reason: "Only main sessions may delegate or control agent runs." };
+        }
+        return;
+      });
+    }
+    const execute: ToolDefinition<typeof delegateSchema>["execute"] = (...args) =>
+      this.delegate(args[1], args[2], args[4]);
+    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.",
+      parameters: delegateSchema,
+      exposure: this.child ? "hidden" : "direct",
+      execute,
+    });
+    const runs: ToolDefinition<typeof runsSchema>["execute"] = (...args) =>
+      this.runs(args[1], args[2], 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.",
+      parameters: runsSchema,
+      exposure: this.child ? "hidden" : "direct",
+      execute: runs,
+    });
+  }
+}
+export default function agents(pi: ExtensionAPI): void {
+  new AgentRuntime(pi).register();
+}

package/src/agent/journal-tail.ts

@@ -0,0 +1,184 @@
+import * as fs from "node:fs";
+
+const READ_BYTES = 65536;
+const LINE_BYTES = 32768;
+const KEEP_LINES = 80;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function plainText(value: string, length = 512): string {
+  // Journal content is untrusted terminal input, never terminal control sequences.
+  return Array.from(value.slice(0, length))
+    .map((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      return code < 32 || (code >= 127 && code <= 159) ? " " : char;
+    })
+    .join("");
+}
+function contentLines(content: unknown): string[] {
+  if (typeof content === "string") {
+    return [plainText(content)];
+  }
+  if (!Array.isArray(content)) {
+    return [];
+  }
+  return content.slice(0, 12).flatMap((block: unknown) => {
+    if (!record(block)) {
+      return [];
+    }
+    if (block.type === "text" && typeof block.text === "string") {
+      return [plainText(block.text)];
+    }
+    if (block.type === "toolCall" && typeof block.name === "string") {
+      return [`tool ${plainText(block.name, 80)} ${plainText(JSON.stringify(block.arguments))}`];
+    }
+    return block.type === "thinking"
+      ? []
+      : [`[${typeof block.type === "string" ? plainText(block.type, 40) : "non-text"} omitted]`];
+  });
+}
+function activity(value: unknown): string[] {
+  if (!record(value) || value.type !== "message" || !record(value.message)) {
+    return [];
+  }
+  const message = value.message;
+  if (message.role === "assistant") {
+    const lines = contentLines(message.content).map((line) => `assistant: ${line}`);
+    if (typeof message.errorMessage === "string") {
+      lines.push(`assistant error: ${plainText(message.errorMessage)}`);
+    }
+    return lines;
+  }
+  if (message.role === "toolResult") {
+    const label = message.isError === true ? "tool error" : "tool result";
+    const name = typeof message.toolName === "string" ? plainText(message.toolName, 80) : "unknown";
+    return [`${label} ${name}:`, ...contentLines(message.content)];
+  }
+  return [];
+}
+
+/** A lossy display tail; the native journal remains the complete source of truth. */
+export class JournalTail {
+  readonly lines: string[] = [];
+  notice = "Waiting for published native activity.";
+  private offset = 0;
+  private partial: Buffer = Buffer.alloc(0);
+  private dropping = false;
+  private identity = "";
+  private stamp = 0;
+  private readonly file: string;
+  private readonly sessionId: string;
+  constructor(file: string, sessionId: string) {
+    this.file = file;
+    this.sessionId = sessionId;
+  }
+  private reset(size: number): void {
+    this.lines.length = 0;
+    this.offset = 0;
+    this.partial = Buffer.alloc(0);
+    this.dropping = false;
+    if (size > READ_BYTES) {
+      this.skip(size);
+    }
+  }
+  private skip(size: number): void {
+    this.offset = size - READ_BYTES;
+    this.partial = Buffer.alloc(0);
+    this.dropping = true;
+    this.lines.push("[Earlier native activity omitted; full journal retained.]");
+  }
+  private header(fd: number): void {
+    const head = Buffer.alloc(4096);
+    const count = fs.readSync(fd, head, 0, head.length, 0);
+    const lf = head.indexOf(10, 0);
+    if (lf < 0 || lf >= count) {
+      throw new Error("Native journal header is incomplete or too large.");
+    }
+    const value: unknown = JSON.parse(head.subarray(0, lf).toString("utf8"));
+    if (!record(value) || value.type !== "session" || value.id !== this.sessionId) {
+      throw new Error("Native journal identity does not match this child.");
+    }
+  }
+  private line(line: Buffer): void {
+    if (line.length > LINE_BYTES) {
+      this.lines.push("[Large native entry omitted; read the full journal.]");
+      return;
+    }
+    try {
+      const value: unknown = JSON.parse(line.toString("utf8"));
+      this.lines.push(...activity(value));
+    } catch {
+      this.lines.push("[Malformed published native entry omitted.]");
+    }
+  }
+  private consume(chunk: Buffer): void {
+    const bytes = Buffer.concat([this.partial, chunk]);
+    let start = 0;
+    let lf = bytes.indexOf(10);
+    while (lf >= 0) {
+      if (!this.dropping) {
+        this.line(bytes.subarray(start, lf));
+      }
+      this.dropping = false;
+      start = lf + 1;
+      lf = bytes.indexOf(10, start);
+    }
+    this.partial = bytes.subarray(start);
+    if (this.partial.length > LINE_BYTES) {
+      this.partial = Buffer.alloc(0);
+      this.dropping = true;
+      this.lines.push("[Large native entry omitted; read the full journal.]");
+    }
+    this.lines.splice(0, Math.max(0, this.lines.length - KEEP_LINES));
+    if (this.partial.length > 0) {
+      this.notice = "Waiting for newline publication of the latest native entry.";
+    }
+  }
+  private changed(stat: fs.Stats, identity: string): boolean {
+    return (
+      identity !== this.identity ||
+      stat.size < this.offset ||
+      (stat.size === this.offset && stat.mtimeMs !== this.stamp)
+    );
+  }
+  private observe(fd: number, stat: fs.Stats): void {
+    const identity = `${stat.dev}:${stat.ino}`;
+    if (this.changed(stat, identity)) {
+      this.reset(stat.size);
+    } else if (stat.size - this.offset > READ_BYTES) {
+      this.skip(stat.size);
+    }
+    this.identity = identity;
+    this.stamp = stat.mtimeMs;
+    const chunk = Buffer.alloc(Math.min(READ_BYTES, stat.size - this.offset));
+    const count = fs.readSync(fd, chunk, 0, chunk.length, this.offset);
+    this.offset += count;
+    this.notice =
+      this.offset > READ_BYTES ? "Recent journal tail only; full journal retained." : "";
+    this.consume(chunk.subarray(0, count));
+    if (this.lines.length === 0 && this.notice.length === 0) {
+      this.notice = "Waiting for published native activity.";
+    }
+  }
+  poll(): void {
+    let fd: number | undefined;
+    try {
+      fd = fs.openSync(this.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      const stat = fs.fstatSync(fd);
+      if (!stat.isFile()) {
+        throw new Error("Native journal is not a regular file.");
+      }
+      this.header(fd);
+      this.observe(fd, stat);
+    } catch (error) {
+      this.lines.length = 0;
+      this.identity = "";
+      this.notice = error instanceof Error ? plainText(error.message) : "Journal unavailable.";
+    } finally {
+      if (fd !== undefined) {
+        fs.closeSync(fd);
+      }
+    }
+  }
+}