@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/src/agent/launch.ts

@@ -0,0 +1,136 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Launch } from "./contracts.ts";
+import type { DelegateInput } from "./tool-schemas.ts";
+import { loadSDK, packageRoot, runtimeEntry } from "./host.ts";
+import { runDirectory, write } from "./storage.ts";
+
+function selectedModel(
+  input: DelegateInput,
+  context: ExtensionContext,
+  thinking: ThinkingLevel,
+  sdk: Awaited<ReturnType<typeof loadSDK>>,
+) {
+  if (input.model === undefined) {
+    if (!context.model) {
+      throw new Error("No selected model; no fallback was used.");
+    }
+    return { model: context.model, thinking };
+  }
+  const slash = input.model.indexOf("/");
+  if (slash < 1) {
+    throw new Error("model must be an exact provider/model ID.");
+  }
+  const model = context.modelRegistry.find(
+    input.model.slice(0, slash),
+    input.model.slice(slash + 1),
+  );
+  if (model) {
+    return { model, thinking };
+  }
+  if (typeof sdk.resolveModelReference !== "function") {
+    throw new Error(
+      `Model ${input.model} is unavailable; no fallback was used. Check the provider/model ID. This host supports literal IDs only. If you intended a thinking suffix, update Pi for native thinking-suffix support.`,
+    );
+  }
+  const resolved = sdk.resolveModelReference(
+    {
+      text: input.model,
+      provider: input.model.slice(0, slash),
+      thinkingSuffix: "strict",
+      fuzzy: false,
+    },
+    context.modelRegistry.getAll(),
+    () => true,
+  );
+  if (resolved.status !== "resolved") {
+    throw new Error(`Model ${input.model} is unavailable; no fallback was used.`);
+  }
+  return { model: resolved.model, thinking: resolved.thinkingLevel ?? thinking };
+}
+function targetTrust(
+  sdk: Awaited<ReturnType<typeof loadSDK>>,
+  cwd: string,
+  context: ExtensionContext,
+  agentDir: string,
+): boolean {
+  if (fs.realpathSync(cwd) === fs.realpathSync(context.cwd)) {
+    return context.isProjectTrusted();
+  }
+  if (!sdk.hasTrustRequiringProjectResources(cwd)) {
+    return true;
+  }
+  const remembered = new sdk.ProjectTrustStore(agentDir).get(cwd);
+  if (remembered !== null) {
+    return remembered;
+  }
+  // Resolve another project's global policy without loading its untrusted settings.
+  const settings = sdk.SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+  return settings.getDefaultProjectTrust() === "always";
+}
+export async function prepareLaunch(options: {
+  input: DelegateInput;
+  context: ExtensionContext;
+  base: string;
+  owner: string;
+  agentDir: string;
+  thinking: ThinkingLevel;
+  executionCwd: string;
+}): Promise<Launch> {
+  const { input, context, base, owner, agentDir, thinking } = options;
+  const sdkRoot = packageRoot();
+  const sdk = await loadSDK(sdkRoot);
+  const cwd = path.resolve(options.executionCwd, input.cwd ?? ".");
+  if (!fs.statSync(cwd).isDirectory()) {
+    throw new Error("Delegation cwd is not a directory.");
+  }
+  const selection = selectedModel(input, context, thinking, sdk);
+  const trusted = targetTrust(sdk, cwd, context, agentDir);
+  const id = randomUUID();
+  const directory = runDirectory(base, id);
+  fs.mkdirSync(directory, { mode: 0o700 });
+  const manager = sdk.SessionManager.create(cwd, directory);
+  const sessionFile = manager.getSessionFile();
+  const header = manager.getHeader();
+  if (sessionFile === undefined || !header) {
+    throw new Error("Native session did not allocate a durable identity.");
+  }
+  const inherited = input.context === "fork" ? context.sessionManager.getBranch() : [];
+  const savedHeader =
+    input.context === "fork"
+      ? { ...header, parentSession: context.sessionManager.getSessionFile() }
+      : header;
+  // Preserve the full native branch: no semantic tool filter or canned body.
+  fs.writeFileSync(
+    sessionFile,
+    [savedHeader, ...inherited].map((entry) => JSON.stringify(entry)).join("\n") + "\n",
+    { flag: "wx", mode: 0o600 },
+  );
+  const launch: Launch = {
+    version: 1,
+    id,
+    rootId: id,
+    owner,
+    cwd,
+    agentDir,
+    sdk: sdkRoot,
+    entry: runtimeEntry(),
+    sessionFile,
+    sessionId: manager.getSessionId(),
+    prompt: input.prompt,
+    context: input.context ?? "fresh",
+    provider: selection.model.provider,
+    model: selection.model.id,
+    thinking: selection.thinking,
+    trusted,
+    name: input.name,
+    createdAt: Date.now(),
+  };
+  // Retain even unpublished native journals on failure, including full fork evidence.
+  // Inventory admits only directories with a canonical launch.json.
+  write(path.join(directory, "launch.json"), launch, true);
+  return launch;
+}

package/src/agent/legacy.ts

@@ -0,0 +1,221 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { journalStamp } from "../shared/native-journal.ts";
+import { receiptId } from "./receipts.ts";
+import { resolveTempRootDir } from "../shared/types.ts";
+import { isRecord } from "../shared/unknown.ts";
+import { release, isHeld, type Completion } from "./notifications.ts";
+import { missing } from "./storage.ts";
+import { errorText } from "./host.ts";
+
+interface LegacyInput {
+  file: string;
+  raw: string;
+  stamp: string;
+  id: string;
+  key: string;
+  owner: string;
+  single: boolean;
+}
+interface IgnoredInputs {
+  readonly owner: string;
+  readonly directory: string;
+  readonly ignored: Map<string, string>;
+}
+interface LegacyScan extends IgnoredInputs {
+  readonly known: ReadonlyMap<string, string> | undefined;
+}
+// Retain only foreign classifications, never their saved output, for each live native manager.
+const ignoredInputs = new WeakMap<ExtensionContext["sessionManager"], IgnoredInputs>();
+function fileStamp(file: string): string | undefined {
+  const stat = fs.lstatSync(file, { bigint: true });
+  return stat.isFile() && !stat.isSymbolicLink() ? journalStamp(stat) : undefined;
+}
+function legacyInput(file: string, scan: LegacyScan): LegacyInput | undefined {
+  const stamp = fileStamp(file);
+  if (stamp === undefined) {
+    return;
+  }
+  if (scan.known?.get(file) === stamp) {
+    scan.ignored.set(file, stamp);
+    return;
+  }
+  const raw = fs.readFileSync(file, "utf8");
+  const data: unknown = JSON.parse(raw);
+  if (!isRecord(data) || data.sessionId !== scan.owner) {
+    if (fileStamp(file) === stamp) {
+      scan.ignored.set(file, stamp);
+    }
+    return;
+  }
+  return ownedInput({ file, raw, stamp, owner: scan.owner }, data);
+}
+function ownedInput(
+  source: Pick<LegacyInput, "file" | "raw" | "stamp" | "owner">,
+  data: Record<string, unknown>,
+): LegacyInput | undefined {
+  const id = typeof data.runId === "string" ? data.runId : data.id;
+  if (typeof id !== "string" || path.basename(source.file, ".json") !== id) {
+    return;
+  }
+  const legacy = `legacy:${id}:${typeof data.timestamp === "number" ? data.timestamp : "unknown"}`;
+  const completionId = typeof data.completionId === "string" ? data.completionId : legacy;
+  return {
+    ...source,
+    id,
+    key: `completion:${completionId}`,
+    single: data.mode === "single",
+  };
+}
+function legacyCompletion(details: unknown, input: LegacyInput): boolean {
+  if (!isRecord(details)) {
+    return false;
+  }
+  const value = details.completion ?? details.subagentCompletion;
+  if (!isRecord(value) || value.runId !== input.id) {
+    return false;
+  }
+  if (value.ownerSessionId !== undefined && value.ownerSessionId !== input.owner) {
+    return false;
+  }
+  return completionKey(value, input.key);
+}
+function completionKey(value: Record<string, unknown>, key: string): boolean {
+  return (
+    value.key === key ||
+    `completion:${typeof value.completionId === "string" ? value.completionId : ""}` === key ||
+    (key.startsWith("completion:legacy:") && value.completionId === undefined)
+  );
+}
+function legacyWait(message: unknown, input: LegacyInput): boolean {
+  if (
+    !isRecord(message) ||
+    message.role !== "toolResult" ||
+    message.isError === true ||
+    !isRecord(message.details)
+  ) {
+    return false;
+  }
+  if (
+    !["delegate", "subagent", "agent_runs"].includes(
+      typeof message.toolName === "string" ? message.toolName : "",
+    )
+  ) {
+    return false;
+  }
+  return completedWait(message.details.wait, input);
+}
+function completedWait(wait: unknown, input: LegacyInput): boolean {
+  return (
+    isRecord(wait) &&
+    wait.status === "completed" &&
+    wait.runId === input.id &&
+    (wait.index === undefined || (input.single && wait.index === 0))
+  );
+}
+function receipt(body: unknown, input: LegacyInput): boolean {
+  if (!isRecord(body)) {
+    return false;
+  }
+  if (body.type === "custom_message") {
+    return legacyCompletion(body.details, input);
+  }
+  return body.type === "message" && legacyWait(body.message, input);
+}
+function published(ctx: ExtensionContext, input: LegacyInput): boolean {
+  return (
+    receiptId(ctx.sessionManager.getSessionFile(), input.owner, (body) => receipt(body, input)) !==
+    undefined
+  );
+}
+function notification(ctx: ExtensionContext, input: LegacyInput): Completion | undefined {
+  const identity = `legacy:${input.id}:${input.key}`;
+  if (published(ctx, input)) {
+    release(input.owner, identity);
+    // Retire only the unchanged recovery input whose actual native receipt exists.
+    if (
+      journalStamp(fs.lstatSync(input.file, { bigint: true })) === input.stamp &&
+      fs.readFileSync(input.file, "utf8") === input.raw
+    ) {
+      fs.unlinkSync(input.file);
+    }
+    return;
+  }
+  if (isHeld(input.owner, identity)) {
+    return;
+  }
+  return {
+    owner: input.owner,
+    id: identity,
+    message: {
+      customType: "subagent-notify",
+      display: true,
+      // Full saved bytes, not a replacement summary. No owner/run record is invented.
+      content: input.raw,
+      details: { completion: { runId: input.id, key: input.key, ownerSessionId: input.owner } },
+    },
+  };
+}
+function legacyNotice(
+  ctx: ExtensionContext,
+  file: string,
+  scan: LegacyScan,
+): Completion | undefined {
+  try {
+    const input = legacyInput(file, scan);
+    return input ? notification(ctx, input) : undefined;
+  } catch (error) {
+    console.error(`Skipped legacy completion ${file}: ${errorText(error)}`);
+    return;
+  }
+}
+function startScan(ctx: ExtensionContext, directory: string): LegacyScan {
+  const manager = ctx.sessionManager;
+  const owner = manager.getSessionId();
+  const prior = ignoredInputs.get(manager);
+  const scan: LegacyScan = {
+    directory,
+    owner,
+    known: prior?.directory === directory && prior.owner === owner ? prior.ignored : undefined,
+    ignored: new Map(),
+  };
+  // Replace even on a failed directory scan; vanished/unsafe inputs keep no cached decision.
+  ignoredInputs.set(manager, { directory, owner, ignored: scan.ignored });
+  return scan;
+}
+/** Retired releases created this directory at session start, before any of their runners. */
+export function legacyDirectory(): string {
+  return path.join(resolveTempRootDir(), "async-subagent-results");
+}
+export function legacyNotifications(ctx: ExtensionContext): Completion[] {
+  const notices: Completion[] = [];
+  const directory = legacyDirectory();
+  const root = path.dirname(directory);
+  const scan = startScan(ctx, directory);
+  let names: string[];
+  try {
+    for (const candidate of [root, directory]) {
+      const stat = fs.lstatSync(candidate);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Unsafe legacy recovery directory: ${candidate}`);
+      }
+    }
+    names = fs.readdirSync(directory);
+  } catch (error) {
+    if (missing(error)) {
+      return notices;
+    }
+    throw error;
+  }
+  for (const name of names) {
+    if (!name.endsWith(".json")) {
+      continue;
+    }
+    const notice = legacyNotice(ctx, path.join(directory, name), scan);
+    if (notice) {
+      notices.push(notice);
+    }
+  }
+  return notices;
+}

package/src/agent/notifications.ts

@@ -0,0 +1,256 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { completionReceipts } from "./receipts.ts";
+import { readOutputPage } from "../shared/output-page.ts";
+import { journalStamp } from "../shared/native-journal.ts";
+import type { Launch, Result } from "./contracts.ts";
+import { launchAt, list, runDirectory } from "./storage.ts";
+import { readCanonicalResult, readResult } from "./usage.ts";
+
+function queuedAdmissions(): Set<string> {
+  const store = globalThis as Record<string, unknown>;
+  const existing = store.__pi_single_agent_admissions__;
+  if (existing instanceof Set) {
+    const values: Set<unknown> = existing;
+    const strings = [...values].filter((value): value is string => typeof value === "string");
+    if (strings.length === values.size) {
+      // Keep one live queue identity across native extension reloads.
+      // oxlint-disable-next-line typescript/no-unsafe-return
+      return existing;
+    }
+  }
+  const queued = new Set<string>();
+  store.__pi_single_agent_admissions__ = queued;
+  return queued;
+}
+const admissions = queuedAdmissions();
+function hold(owner: string, id: string): boolean {
+  const key = `${owner}/${id}`;
+  if (admissions.has(key)) {
+    return false;
+  }
+  admissions.add(key);
+  return true;
+}
+export function release(owner: string, id: string): void {
+  admissions.delete(`${owner}/${id}`);
+}
+export function isHeld(owner: string, id: string): boolean {
+  return admissions.has(`${owner}/${id}`);
+}
+/** Returns whether any admission was released for reconciliation. */
+export function settle(owner: string, pending: boolean): boolean {
+  if (pending) {
+    return false;
+  }
+  let released = false;
+  for (const key of admissions) {
+    if (key.startsWith(`${owner}/`)) {
+      admissions.delete(key);
+      released = true;
+    }
+  }
+  return released;
+}
+export function published(ctx: ExtensionContext, launch: Launch): string | undefined {
+  return completionReceipts(ctx.sessionManager.getSessionFile(), launch.owner).get(launch.id);
+}
+export interface Completion {
+  readonly owner: string;
+  readonly id: string;
+  readonly message: Parameters<ExtensionAPI["sendMessage"]>[0];
+}
+export function deliver(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  notices: readonly Completion[],
+): void {
+  const idle = ctx.isIdle();
+  for (const [index, notice] of notices.entries()) {
+    hold(notice.owner, notice.id);
+    try {
+      // Pi defers settlement-triggered runs separately. Publish the idle batch first,
+      // then trigger once so no unstarted wakeup can outlive its admission hold.
+      pi.sendMessage(notice.message, {
+        triggerTurn: !idle || index === notices.length - 1,
+        deliverAs: "steer",
+      });
+    } catch (error) {
+      release(notice.owner, notice.id);
+      throw error;
+    }
+  }
+}
+function notification(base: string, launch: Launch, result: Result): Completion {
+  const file = path.join(runDirectory(base, launch.id), "output.txt");
+  const page = fs.existsSync(file) ? readOutputPage(file, { offset: 0, length: 32768 }) : undefined;
+  const more =
+    page?.nextOffset !== undefined
+      ? `\n[More output: agent_runs inspect id=${launch.id} offset=${page.nextOffset}; ${page.size} bytes total.]`
+      : "";
+  return {
+    owner: launch.owner,
+    id: launch.id,
+    message: {
+      customType: "agent-completion",
+      display: true,
+      content: `Agent run ${launch.id}: ${result.status}. ${result.error ?? ""}\n${page?.text ?? ""}${more}\nNative journal: ${launch.sessionFile}`,
+      details: {
+        owner: launch.owner,
+        id: launch.id,
+        completed: true,
+        result,
+        outputFile: file,
+        page,
+      },
+    },
+  };
+}
+interface PendingJournal {
+  readonly file: string;
+  readonly stamp: string | undefined;
+}
+interface Loaded {
+  readonly launch: Launch;
+  readonly result: Result | undefined;
+  readonly journal?: PendingJournal;
+}
+interface Settled {
+  readonly launch: string;
+  readonly result: string;
+  readonly pending?: Loaded;
+  readonly endedAt: number;
+  readonly createdAt: number;
+}
+interface Completed {
+  readonly id: string;
+  readonly endedAt: number;
+  readonly createdAt: number;
+  readonly loaded?: Loaded;
+}
+// Validated settled runs by file stamp, so polling does not reparse unchanged history.
+const settledRuns = new Map<string, Map<string, Settled>>();
+function stamp(file: string): string | undefined {
+  const stat = fs.statSync(file, { bigint: true, throwIfNoEntry: false });
+  return stat === undefined ? undefined : journalStamp(stat);
+}
+function pendingJournal(file: string): PendingJournal | undefined {
+  try {
+    return { file, stamp: stamp(file) };
+  } catch {
+    // Unavailable metadata cannot validate a cached attempt or hide execution.
+    return undefined;
+  }
+}
+function unchangedPending(pending: Loaded | undefined): boolean {
+  if (pending === undefined) {
+    return true;
+  }
+  const journal = pending.journal;
+  if (journal === undefined) {
+    return false;
+  }
+  const current = pendingJournal(journal.file);
+  return current !== undefined && current.stamp === journal.stamp;
+}
+function load(base: string, id: string, owner: string): Loaded {
+  const launch = launchAt(base, id, owner);
+  const result = readCanonicalResult(base, launch);
+  if (result?.accountingPending === undefined) {
+    return { launch, result };
+  }
+  // Only pending runs need this pre-read stamp to observe concurrent publication.
+  // readResult revalidates canonical state afterward: a miss intentionally reads result.json twice.
+  const journal = pendingJournal(launch.sessionFile);
+  return { launch, result: readResult(base, launch), journal };
+}
+function cacheableResult(loaded: Loaded): boolean {
+  return loaded.result?.accountingPending === undefined || loaded.journal !== undefined;
+}
+interface Scan {
+  readonly base: string;
+  readonly owner: string;
+  readonly known: ReadonlyMap<string, Settled>;
+  readonly settled: Map<string, Settled>;
+}
+function completedRun({ base, owner, known, settled }: Scan, id: string): Completed | undefined {
+  const directory = runDirectory(base, id);
+  const launch = stamp(path.join(directory, "launch.json"));
+  const result = stamp(path.join(directory, "result.json"));
+  const prior = known.get(id);
+  if (
+    prior !== undefined &&
+    prior.launch === launch &&
+    prior.result === result &&
+    unchangedPending(prior.pending)
+  ) {
+    settled.set(id, prior);
+    return { id, ...prior, loaded: prior.pending };
+  }
+  const loaded = load(base, id, owner);
+  if (loaded.result === undefined) {
+    return;
+  }
+  const order = { endedAt: loaded.result.endedAt, createdAt: loaded.launch.createdAt };
+  // Pending accounting retries on child changes, even after the completion receipt.
+  // Ordinary settled history retains its launch/result-only idle probes.
+  const pending = loaded.result.accountingPending === undefined ? undefined : loaded;
+  if (launch !== undefined && result !== undefined && cacheableResult(loaded)) {
+    settled.set(id, { launch, result, pending, ...order });
+  }
+  return { id, ...order, loaded };
+}
+function completed(base: string, owner: string, awaited: Set<string>): Completed[] {
+  const key = JSON.stringify([base, owner]);
+  const scan = {
+    base,
+    owner,
+    known: settledRuns.get(key) ?? new Map<string, Settled>(),
+    settled: new Map<string, Settled>(),
+  };
+  const runs = list(base).flatMap((id) => {
+    const run = completedRun(scan, id);
+    if (run === undefined) {
+      awaited.add(path.join(runDirectory(base, id), "result.json"));
+    } else if (run.loaded?.result?.accountingPending !== undefined) {
+      awaited.add(run.loaded.launch.sessionFile);
+    }
+    return run ?? [];
+  });
+  settledRuns.delete(key);
+  settledRuns.set(key, scan.settled);
+  if (settledRuns.size > 8) {
+    settledRuns.delete(settledRuns.keys().next().value ?? key);
+  }
+  return runs.sort((a, b) => {
+    if (a.endedAt !== b.endedAt) {
+      return a.endedAt - b.endedAt;
+    }
+    return a.createdAt !== b.createdAt ? a.createdAt - b.createdAt : a.id.localeCompare(b.id);
+  });
+}
+export interface Reconciliation {
+  readonly notices: Completion[];
+  /** Canonical files whose publication can change what this owner must deliver. */
+  readonly awaited: ReadonlySet<string>;
+}
+export function notifications(ctx: ExtensionContext, base: string, owner: string): Reconciliation {
+  const notices: Completion[] = [];
+  const awaited = new Set<string>();
+  const runs = completed(base, owner, awaited);
+  const receipts =
+    runs.length === 0 ? undefined : completionReceipts(ctx.sessionManager.getSessionFile(), owner);
+  for (const run of runs) {
+    const key = `${owner}/${run.id}`;
+    if (receipts?.get(run.id) !== undefined) {
+      admissions.delete(key);
+      continue;
+    }
+    const loaded = admissions.has(key) ? undefined : (run.loaded ?? load(base, run.id, owner));
+    if (loaded?.result !== undefined) {
+      notices.push(notification(base, loaded.launch, loaded.result));
+    }
+  }
+  return { notices, awaited };
+}