@fitchmultz/pi-subagents 0.49.0 → 0.50.0

package/src/agent/storage.ts

@@ -0,0 +1,123 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { readJsonProjection } from "../shared/journal-frames.ts";
+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";
+
+export function missing(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+export function read<T extends TSchema>(
+  file: string,
+  schema: T,
+  select: Projection = () => true,
+): Static<T> | undefined {
+  let value: unknown;
+  try {
+    value = readJsonProjection(file, select);
+  } catch (error) {
+    if (missing(error)) {
+      return;
+    }
+    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: string, value: unknown, exclusive = false): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  const fd = fs.openSync(temp, "wx", 0o600);
+  try {
+    fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    if (exclusive) {
+      fs.linkSync(temp, file);
+    } else {
+      fs.renameSync(temp, file);
+    }
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+export function safeId(id: string): string {
+  if (!/^[a-zA-Z0-9_-]{1,128}$/.test(id)) {
+    throw new Error("Invalid run/session ID.");
+  }
+  return id;
+}
+export function ownerDirectory(agentDir: string, owner: string): string {
+  return path.join(agentDir, "sessions", "agent-runs", safeId(owner));
+}
+export function runDirectory(base: string, id: string): string {
+  return path.join(base, safeId(id));
+}
+export function launchAt(base: string, id: string, owner: string): Launch {
+  const launch = read(path.join(runDirectory(base, id), "launch.json"), launchSchema);
+  if (!launch || launch.id !== id || launch.owner !== owner) {
+    throw new Error("Missing saved launch or foreign run owner; nothing was launched.");
+  }
+  return launch;
+}
+export function latest(base: string, initial: Launch): Launch {
+  const seen = new Set<string>();
+  let launch = initial;
+  for (;;) {
+    if (seen.has(launch.id)) {
+      throw new Error("Cyclic saved continuation.");
+    }
+    seen.add(launch.id);
+    const next = read(path.join(runDirectory(base, launch.id), "successor.json"), successorSchema);
+    if (!next) {
+      return launch;
+    }
+    launch = launchAt(base, next.id, initial.owner);
+  }
+}
+export function conversation(base: string, launch: Launch): string {
+  return runDirectory(base, launch.rootId);
+}
+export function enqueue(
+  base: string,
+  launch: Launch,
+  action: Command["action"],
+  options: Pick<Command, "prompt" | "actorToken"> = {},
+): string {
+  const id = action === "run" ? launch.id : randomUUID();
+  const command: Command = {
+    id,
+    runId: launch.id,
+    action,
+    ...options,
+    createdAt: Date.now(),
+  };
+  write(path.join(conversation(base, launch), "commands", `${id}.json`), command, true);
+  return id;
+}
+export function list(base: string): string[] {
+  try {
+    return fs
+      .readdirSync(base, { withFileTypes: true })
+      .filter(
+        (e) =>
+          e.isDirectory() &&
+          fs.lstatSync(path.join(base, e.name, "launch.json"), { throwIfNoEntry: false }) !==
+            undefined,
+      )
+      .map((e) => e.name);
+  } catch (error) {
+    if (missing(error)) {
+      return [];
+    }
+    throw error;
+  }
+}

package/src/agent/typebox.ts

@@ -0,0 +1,17 @@
+import { createRequire } from "node:module";
+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";
+
+const require = createRequire(path.join(packageRoot(), "dist/index.js"));
+// The detached runner needs the selected host's dependencies, not Jiti aliases.
+// oxlint-disable-next-line typescript/no-unsafe-assignment
+const typebox: typeof NativeTypebox = 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
+);
+export const { Type } = typebox;
+export const Assert: typeof NativeValue.Assert = value.Assert;

package/src/agent/usage.ts

@@ -0,0 +1,263 @@
+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 {
+  contributionsSchema,
+  resultSchema,
+  type Contribution,
+  type Launch,
+  type Result,
+} 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;
+  }
+  const message = isRecord(entry.message) ? entry.message : entry;
+  if (
+    !["message", "usage", "compaction", "branch_summary"].some((type) => type === entry.type) ||
+    (entry.type === "message" && !["assistant", "toolResult"].some((role) => role === message.role))
+  ) {
+    return;
+  }
+  const required = entry.type === "usage" || message.role === "assistant";
+  if (required && message.usage === undefined) {
+    throw new Error("Required native usage is unavailable.");
+  }
+  return message.usage === undefined ? undefined : message;
+}
+function attribution(message: Record<string, unknown>, launch: Launch) {
+  if (message.role === "toolResult") {
+    return { provider: launch.provider, model: launch.model };
+  }
+  const model =
+    message.role === "assistant" && typeof message.responseModel === "string"
+      ? message.responseModel
+      : message.model;
+  return {
+    provider: typeof message.provider === "string" ? message.provider : launch.provider,
+    model: typeof model === "string" ? model : launch.model,
+  };
+}
+export function childUsage(
+  launch: Launch,
+  baseline: ReadonlySet<string>,
+  terminal?: string,
+): Contribution[] {
+  const values: unknown[] = [];
+  const observed = { header: false, ended: false };
+  const reachedTerminal = new Error("Native terminal boundary reached.");
+  const fd = fs.openSync(launch.sessionFile, "r");
+  try {
+    const stamp = journalStamp(fs.fstatSync(fd, { bigint: true }));
+    try {
+      scanJournal(
+        fd,
+        nativeProjection,
+        ({ value }) => {
+          if (!observed.header) {
+            if (value.type !== "session" || value.id !== launch.sessionId) {
+              throw new Error("Foreign native usage journal identity.");
+            }
+            observed.header = true;
+            return;
+          }
+          if (typeof value.id !== "string" || typeof value.type !== "string") {
+            throw new Error("Missing native usage entry identity.");
+          }
+          const message = baseline.has(value.id) ? undefined : billing(value);
+          if (message) {
+            values.push({
+              id: `${launch.sessionId}:${value.id}`,
+              ...attribution(message, launch),
+              usage: message.usage,
+            });
+          }
+          if (value.id === terminal) {
+            observed.ended = true;
+            throw reachedTerminal;
+          }
+        },
+        { policy: "live", requireNewline: true },
+      );
+    } catch (error) {
+      if (error !== reachedTerminal) {
+        throw error;
+      }
+    }
+    if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== stamp) {
+      throw new Error("Native usage journal changed while reading.");
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (!observed.header || (terminal !== undefined && !observed.ended)) {
+    throw new Error("Native terminal or session identity is not LF-published.");
+  }
+  Assert(contributionsSchema, values);
+  return values;
+}
+export function readCanonicalResult(base: string, launch: Launch): Result | undefined {
+  const file = path.join(runDirectory(base, launch.id), "result.json");
+  const result = read(file, resultSchema);
+  if (result && (result.id !== launch.id || result.owner !== launch.owner)) {
+    throw new Error("Foreign canonical result identity.");
+  }
+  return result;
+}
+export function readResult(base: string, launch: Launch): Result | undefined {
+  const result = readCanonicalResult(base, launch);
+  if (!result) {
+    return;
+  }
+  const pending = result.accountingPending;
+  if (pending === undefined) {
+    return result;
+  }
+  let contributions;
+  try {
+    contributions = childUsage(launch, new Set(pending.baseline), pending.terminalCandidate);
+  } catch {
+    // Execution and output remain canonical while native billing publication is incomplete.
+    return result;
+  }
+  const { accountingPending: _pending, accountingError: _error, ...execution } = result;
+  const repaired = { ...execution, terminalEntryId: pending.terminalCandidate, contributions };
+  write(path.join(runDirectory(base, launch.id), "result.json"), repaired);
+  return repaired;
+}

package/src/agent/view.ts

@@ -0,0 +1,246 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readOutputPage } from "../shared/output-page.ts";
+import { actor, alive } from "./process.ts";
+import {
+  admissionSchema,
+  commandSchema,
+  exitSchema,
+  successorSchema,
+  type Launch,
+  type RunsInput,
+  type Result,
+} from "./contracts.ts";
+import { conversation, read, runDirectory } from "./storage.ts";
+import { published } from "./notifications.ts";
+import { readCanonicalResult, readResult } from "./usage.ts";
+import { Type } from "./typebox.ts";
+
+const commandMetadataSchema = Type.Pick(commandSchema, ["id", "runId", "action", "createdAt"]);
+interface Guidance {
+  id: string;
+  runId: string;
+  action: "steer";
+  state: "pending" | "accepted" | "stale";
+  at: number;
+}
+
+interface ToolReply {
+  content: { type: "text"; text: string }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface RunSummary {
+  id: string;
+  owner: string;
+  rootId: string;
+  predecessor?: string;
+  name?: string;
+  cwd: string;
+  model: string;
+  thinking: string;
+  context: string;
+  admission: string;
+  status: string;
+  completed: boolean;
+  result?: Pick<Result, "status" | "endedAt" | "error">;
+  nativeReceipt: string | null;
+  process: ReturnType<typeof processView>;
+  sessionId: string;
+  sessionFile: string;
+  outputFile: string;
+  guidance: Guidance[];
+}
+interface RunView extends Omit<RunSummary, "result"> {
+  result?: Result;
+  output: ReturnType<typeof outputView>;
+}
+export function toolResult(value: unknown, text = JSON.stringify(value, null, 2)): ToolReply {
+  return { content: [{ type: "text" as const, text }], details: value };
+}
+function processView(base: string, launch: Launch) {
+  const identity = actor(base, launch);
+  const exit = identity
+    ? read(path.join(conversation(base, launch), `exit-${identity.token}.json`), exitSchema)
+    : undefined;
+  return {
+    live: identity !== undefined && alive(identity),
+    exit: exit ?? null,
+    exitKnown: exit !== undefined,
+  };
+}
+function outputView(file: string, input: Pick<RunsInput, "offset" | "length">) {
+  return fs.existsSync(file)
+    ? readOutputPage(file, { offset: input.offset ?? 0, length: input.length ?? 32768 })
+    : undefined;
+}
+function guidanceView(base: string, launches: readonly Launch[]): Map<string, Guidance[]> {
+  const runs = new Map<string, Guidance[]>(launches.map((launch) => [launch.id, []]));
+  for (const rootId of new Set(launches.map((launch) => launch.rootId))) {
+    const runIds = new Set(
+      launches.filter((launch) => launch.rootId === rootId).map((launch) => launch.id),
+    );
+    const directory = runDirectory(base, rootId);
+    const dir = path.join(directory, "commands");
+    if (!fs.existsSync(dir)) {
+      continue;
+    }
+    fs.readdirSync(dir)
+      .filter((file) => file.endsWith(".json"))
+      .forEach((file) => {
+        const command = read(
+          path.join(dir, file),
+          commandMetadataSchema,
+          (keys) =>
+            keys.length === 0 ||
+            (keys.length === 1 && Object.hasOwn(commandMetadataSchema.properties, String(keys[0]))),
+        );
+        const guidance = command && runIds.has(command.runId) ? runs.get(command.runId) : undefined;
+        if (command?.action !== "steer" || !guidance) {
+          return;
+        }
+        const admission = read(
+          path.join(directory, "admissions", `${command.id}.json`),
+          admissionSchema,
+        );
+        guidance.push({
+          id: command.id,
+          runId: command.runId,
+          action: command.action,
+          state: admission ? (admission.state ?? "accepted") : "pending",
+          at: admission?.at ?? command.createdAt,
+        });
+        guidance.sort((a, b) => b.at - a.at).splice(20);
+      });
+  }
+  return runs;
+}
+function metadata(
+  base: string,
+  launch: Launch,
+  result: Result | undefined,
+  options: { ctx?: ExtensionContext; guidance: Guidance[] },
+): Omit<RunView, "output"> {
+  const directory = runDirectory(base, launch.id);
+  const process = processView(base, launch);
+  const outputFile = path.join(directory, "output.txt");
+  const admission = read(
+    path.join(conversation(base, launch), "admissions", `${launch.id}.json`),
+    admissionSchema,
+  );
+  const status =
+    result?.status ??
+    (process.live && read(path.join(directory, "successor.json"), successorSchema) === undefined
+      ? "running"
+      : "interrupted");
+  return {
+    id: launch.id,
+    owner: launch.owner,
+    rootId: launch.rootId,
+    predecessor: launch.predecessor,
+    name: launch.name,
+    cwd: launch.cwd,
+    model: `${launch.provider}/${launch.model}`,
+    thinking: launch.thinking,
+    context: launch.context,
+    admission: admission ? "admitted" : "pending",
+    status,
+    completed: result !== undefined,
+    result,
+    nativeReceipt: options.ctx ? (published(options.ctx, launch) ?? null) : null,
+    process,
+    sessionId: launch.sessionId,
+    sessionFile: launch.sessionFile,
+    outputFile,
+    guidance: options.guidance,
+  };
+}
+export function summaries(
+  base: string,
+  launches: readonly Launch[],
+  ctx?: ExtensionContext,
+): RunSummary[] {
+  const guidance = guidanceView(base, launches);
+  return launches.map((launch) => {
+    const view = metadata(base, launch, readCanonicalResult(base, launch), {
+      ctx,
+      guidance: guidance.get(launch.id) ?? [],
+    });
+    return {
+      ...view,
+      name: view.name?.slice(0, 256),
+      result: view.result
+        ? {
+            status: view.result.status,
+            endedAt: view.result.endedAt,
+            error: view.result.error?.slice(0, 2048),
+          }
+        : undefined,
+    };
+  });
+}
+export function projection(
+  base: string,
+  launch: Launch,
+  ctx?: ExtensionContext,
+  input: Pick<RunsInput, "offset" | "length"> = {},
+): RunView {
+  const view = metadata(base, launch, readResult(base, launch), {
+    ctx,
+    guidance: guidanceView(base, [launch]).get(launch.id) ?? [],
+  });
+  return {
+    ...view,
+    output: outputView(view.outputFile, input),
+  };
+}
+function receiptText(details: RunView): string {
+  return details.nativeReceipt !== null
+    ? `Native completion receipt: published (${details.nativeReceipt}); publication does not prove model consumption.`
+    : "Native completion receipt: not observed published; queue admission is not publication or model consumption.";
+}
+function exitText(details: RunView): string {
+  return details.process.exit
+    ? `Process exit observed: code ${details.process.exit.code ?? "unknown"}, signal ${details.process.exit.signal ?? "none"}.`
+    : "Process exit: unknown; run completion does not imply process exit.";
+}
+function resultText(details: RunView): string {
+  const page = details.output;
+  const suffix =
+    page?.nextOffset !== undefined
+      ? `\n[Output continues: agent_runs inspect id=${details.id} offset=${page.nextOffset}; ${page.size} bytes total.]`
+      : "";
+  const guidance = details.guidance
+    .map((command) => `  ${command.id}: ${command.state}`)
+    .join("\n");
+  return [
+    `Agent run ${details.id}: ${details.status}; admission ${details.admission}; process ${details.process.live ? "live" : "not observed live"}.`,
+    receiptText(details),
+    exitText(details),
+    `Guidance (latest 20):\n${guidance.length > 0 ? guidance : "  none"}`,
+    "Guidance states: pending = not yet admitted; accepted = native queue admission, not journal publication or model consumption; stale = rejected, no new work was started (retry the entire prompt as a continuation).",
+    details.result?.error ?? "",
+    `${page?.text ?? ""}${suffix}`,
+    `Native journal: ${details.sessionFile}`,
+  ].join("\n");
+}
+export function render(
+  base: string,
+  launch: Launch,
+  ctx?: ExtensionContext,
+  input: Pick<RunsInput, "offset" | "length"> & { receivedResult?: boolean } = {},
+): ToolReply {
+  const view = projection(base, launch, ctx, input);
+  const details = {
+    ...view,
+    receivedResult: input.receivedResult === true,
+    ...(input.receivedResult === true && view.result?.contributions !== undefined
+      ? { agentUsage: view.result.contributions }
+      : {}),
+  };
+  return {
+    ...toolResult(details, resultText(details)),
+    isError: details.result?.status === "failed",
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import agents from "./agent/index.ts";
+import observe from "./agent/observe.ts";
+import intercom from "./pi-intercom/index.ts";
+
+export default function extension(pi: ExtensionAPI): void {
+  agents(pi);
+  observe(pi);
+  intercom(pi);
+}