@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/extension/tool-input.ts

@@ -1,19 +1,46 @@
 import { Compile } from "../shared/native-typebox.ts";
+import { isRecord } from "../shared/unknown.ts";
 import { AgentRunsValidationParams } from "./schemas.ts";
 
 const runArguments = Compile(AgentRunsValidationParams);
 
-export function normalizeEverydayParams(params: Record<string, unknown>, control = false): Record<string, unknown> {
-	const acceptance = params.acceptance as { verify?: Array<{ env?: Array<{ name: string; value: string }> }> } | undefined;
-	const normalized = acceptance?.verify ? {
-		...params,
-		acceptance: { ...acceptance, verify: acceptance.verify.map((verify) => {
-			if (!Array.isArray(verify.env)) return verify;
-			const names = verify.env.map(({ name }) => name);
-			if (new Set(names).size !== names.length) throw new Error("Verification environment contains duplicate names.");
-			return { ...verify, env: Object.fromEntries(verify.env.map(({ name, value }) => [name, value])) };
-		}) },
-	} : params;
-	if (control && !runArguments.Check(normalized)) throw new Error(`Invalid agent_runs arguments: ${[...runArguments.Errors(normalized)].map((error) => error.message).join("; ")}`);
-	return normalized;
+function normalizeVerificationEnvironment(verify: unknown): unknown {
+  if (!isRecord(verify) || !Array.isArray(verify.env)) {
+    return verify;
+  }
+  const entries = verify.env.map((entry: unknown): [string, string] => {
+    if (!isRecord(entry) || typeof entry.name !== "string" || typeof entry.value !== "string") {
+      throw new Error("Verification environment entries require string names and values.");
+    }
+    return [entry.name, entry.value];
+  });
+  if (new Set(entries.map(([name]) => name)).size !== entries.length) {
+    throw new Error("Verification environment contains duplicate names.");
+  }
+  return { ...verify, env: Object.fromEntries(entries) };
+}
+
+export function normalizeEverydayParams(
+  params: Readonly<Record<string, unknown>>,
+  control = false,
+): Readonly<Record<string, unknown>> {
+  const acceptance = params.acceptance;
+  const normalized =
+    isRecord(acceptance) && Array.isArray(acceptance.verify)
+      ? {
+          ...params,
+          acceptance: {
+            ...acceptance,
+            verify: acceptance.verify.map((verify: unknown) =>
+              normalizeVerificationEnvironment(verify),
+            ),
+          },
+        }
+      : params;
+  if (control && !runArguments.Check(normalized)) {
+    throw new Error(
+      `Invalid agent_runs arguments: ${[...runArguments.Errors(normalized)].map((error) => error.message).join("; ")}`,
+    );
+  }
+  return normalized;
 }

package/src/extension/tool-result.ts

@@ -1,16 +1,47 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { Details, SubagentExecutionResult } from "../shared/types.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SubagentExecutionResult } from "../shared/types.ts";
+import type { ReadonlyInput } from "../shared/types/inputs.ts";
+import { isRecord } from "../shared/unknown.ts";
+import { copyExecutionResult } from "./result-snapshot.ts";
+import { finalizedChildUsage, type ParentUsageRegistration } from "../runs/shared/parent-usage.ts";
 
-export function registerToolResultAdapter(pi: ExtensionAPI, toolNames: readonly string[]) {
-	pi.on("tool_result", (event) => {
-		const details = event.details as (Details & { isError?: boolean }) | undefined;
-		if (!toolNames.includes(event.toolName) || details?.isError !== true) return;
-		const { isError, ...originalDetails } = details;
-		return { isError, details: originalDetails };
-	});
-	// Native execute ignores returned isError; throwing discards content/details.
-	// Carry the flag to its native result hook, which restores the original details.
-	return (result: SubagentExecutionResult) => result.isError
-		? { ...result, details: { ...result.details, isError: true } }
-		: result;
+/** Only completed, directly owned waits carry accounting intent to the native result boundary. */
+export function adaptFinalizedToolResult(
+  result: ReadonlyInput<SubagentExecutionResult>,
+  ctx: ExtensionContext,
+  parentUsage: ParentUsageRegistration,
+  adapt: (result: ReadonlyInput<SubagentExecutionResult>) => SubagentExecutionResult,
+): SubagentExecutionResult {
+  const attached =
+    result.details.wait?.status === "completed" &&
+    result.details.run?.ownerSessionId === ctx.sessionManager.getSessionId()
+      ? parentUsage.attach(
+          result,
+          finalizedChildUsage(result.details.run.children, result.details.wait.index),
+          ctx,
+        )
+      : result;
+  return adapt(attached);
+}
+
+export function registerToolResultAdapter(
+  pi: ExtensionAPI,
+  toolNames: readonly string[],
+): (result: ReadonlyInput<SubagentExecutionResult>) => SubagentExecutionResult {
+  pi.on("tool_result", (event) => {
+    const details: unknown = event.details;
+    if (!toolNames.includes(event.toolName) || !isRecord(details) || details.isError !== true) {
+      return;
+    }
+    const { isError, ...originalDetails } = details;
+    return { isError, details: originalDetails };
+  });
+  // Native execute ignores returned isError; throwing discards content/details.
+  // Carry the flag to its native result hook, which restores the original details.
+  return (result) => {
+    const snapshot = copyExecutionResult(result);
+    return result.isError === true
+      ? { ...snapshot, details: { ...snapshot.details, isError: true } }
+      : snapshot;
+  };
 }

package/src/history/answer-texts.ts

@@ -0,0 +1,74 @@
+import { stripTerminalSequences } from "../shared/native-tui.ts";
+import { stripAcceptanceReport } from "../runs/shared/acceptance-reports.ts";
+import { exactTextDigest } from "./store.ts";
+import { object, objects, string } from "./values.ts";
+
+/** Exact matches never use previews. Oversized selected text has no fingerprint. */
+export class AnswerTexts {
+  private readonly fields = new Map<number, string>();
+  private length = 0;
+  private unavailable = false;
+  write(keys: readonly (string | number)[], text: string): void {
+    if (
+      this.unavailable ||
+      keys.length !== 4 ||
+      keys[0] !== "message" ||
+      keys[1] !== "content" ||
+      !["text", "thinking"].includes(String(keys[3]))
+    ) {
+      return;
+    }
+    this.length += text.length;
+    if (this.length > 16 * 1024 * 1024 || Number(keys[2]) >= 4096) {
+      this.unavailable = true;
+      this.fields.clear();
+      return;
+    }
+    const index = Number(keys[2]);
+    this.fields.set(index, (this.fields.get(index) ?? "") + text);
+  }
+  private partText(part: Readonly<Record<string, unknown>>, index: number): string {
+    if (part.type === "text" || part.type === "thinking") {
+      return stripTerminalSequences(this.fields.get(index) ?? "");
+    }
+    return part.type === "image" ? `[Image: ${string(part.mimeType) ?? "image"}]` : "";
+  }
+  fingerprints(
+    value: Readonly<Record<string, unknown>>,
+    id: string,
+  ): readonly (readonly [string, string])[] {
+    const message = object(value.message);
+    if (this.unavailable || value.type !== "message" || message.role !== "assistant") {
+      return [];
+    }
+    const content = objects(message.content);
+    const first = content.findIndex(
+      (part, index) =>
+        (part.type === "text" || part.type === "thinking") &&
+        (this.fields.get(index)?.length ?? 0) > 0,
+    );
+    if (
+      first < 0 ||
+      !content.some(
+        (part, index) => part.type === "text" && (this.fields.get(index)?.length ?? 0) > 0,
+      )
+    ) {
+      return [];
+    }
+    const item = `${id}:${first}`;
+    const parts = content
+      .map((part, index) => this.partText(part, index))
+      .filter((text) => text.length > 0);
+    const texts = [
+      parts.join("\n"),
+      ...content.flatMap((part, index) =>
+        part.type === "text" ? [stripTerminalSequences(this.fields.get(index) ?? "")] : [],
+      ),
+    ];
+    return [
+      ...new Set(
+        texts.map((text) => stripAcceptanceReport(text).trim()).filter((text) => text.length > 0),
+      ),
+    ].map((text) => [exactTextDigest(text), item]);
+  }
+}

package/src/history/canonical-result.ts

@@ -2,61 +2,137 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { JsonProjection, readJsonProjection } from "../shared/journal-reader.ts";
 import { HistoryIndexError } from "./types.ts";
+import { at, object, objects } from "./values.ts";
 
 const budget = 16 * 1024 * 1024;
+function unchanged(file: string, fd: number, before: fs.BigIntStats): void {
+  const after = fs.fstatSync(fd, { bigint: true });
+  const current = fs.statSync(file, { bigint: true });
+  if (
+    before.size !== after.size ||
+    before.ctimeNs !== after.ctimeNs ||
+    before.dev !== current.dev ||
+    before.ino !== current.ino
+  ) {
+    throw new HistoryIndexError("SOURCE_CHANGED", "Selected output changed; retry details.");
+  }
+}
 export function readSavedOutput(file: string): string {
-	const fd = fs.openSync(file, "r");
-	try {
-		const before = fs.fstatSync(fd, { bigint: true });
-		if (!before.isFile() || before.size > BigInt(budget)) throw new HistoryIndexError("RECORD_TOO_LARGE", "Selected saved output exceeds the 16 MiB detail budget.");
-		const bytes = Buffer.alloc(Number(before.size));
-		for (let offset = 0; offset < bytes.length;) {
-			const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
-			if (!count) throw new HistoryIndexError("SOURCE_CHANGED", "Selected saved output was truncated.");
-			offset += count;
-		}
-		const after = fs.fstatSync(fd, { bigint: true }), current = fs.statSync(file, { bigint: true });
-		if (before.size !== after.size || before.ctimeNs !== after.ctimeNs || before.dev !== current.dev || before.ino !== current.ino) throw new HistoryIndexError("SOURCE_CHANGED", "Selected saved output changed; retry details.");
-		return new TextDecoder("utf8", { fatal: true }).decode(bytes);
-	} finally { fs.closeSync(fd); }
+  const fd = fs.openSync(file, "r");
+  try {
+    const before = fs.fstatSync(fd, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(budget)) {
+      throw new HistoryIndexError(
+        "RECORD_TOO_LARGE",
+        "Selected saved output exceeds the 16 MiB detail budget.",
+      );
+    }
+    const bytes = Buffer.alloc(Number(before.size));
+    for (let offset = 0; offset < bytes.length;) {
+      const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (count === 0) {
+        throw new HistoryIndexError("SOURCE_CHANGED", "Selected saved output was truncated.");
+      }
+      offset += count;
+    }
+    unchanged(file, fd, before);
+    return new TextDecoder("utf8", { fatal: true }).decode(bytes);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function childPrefix(file: string, index: number): readonly (string | number)[] | undefined {
+  if (path.basename(file) !== "foreground.json") {
+    return path.basename(file) === "result.json" ? ["results", index] : ["result"];
+  }
+  const metadata: unknown = readJsonProjection(
+    file,
+    (keys) =>
+      keys.length === 0 ||
+      (keys[0] === "children" && (keys.length <= 2 || (keys.length === 3 && keys[2] === "index"))),
+  );
+  const position = objects(object(metadata).children).findIndex((child) => child.index === index);
+  return position < 0 ? undefined : ["children", position, "result"];
+}
+function isOutput(
+  keys: readonly (string | number)[],
+  prefix: readonly (string | number)[],
+): boolean {
+  return (
+    keys.length === prefix.length + 1 &&
+    prefix.every((key, position) => key === keys[position]) &&
+    ["finalOutput", "output"].includes(String(keys.at(-1)))
+  );
+}
+function outputProjection(prefix: readonly (string | number)[]): JsonProjection {
+  let length = 0;
+  return new JsonProjection(
+    (keys) => {
+      if (
+        prefix[0] === "children" &&
+        keys.length === 3 &&
+        keys[0] === "children" &&
+        keys[1] === prefix[1] &&
+        keys[2] === "index"
+      ) {
+        return true;
+      }
+      if (keys.length <= prefix.length) {
+        return keys.every((key, position) => key === prefix[position]);
+      }
+      return isOutput(keys, prefix) ? budget : false;
+    },
+    (keys, text) => {
+      if (isOutput(keys, prefix)) {
+        length += Buffer.byteLength(text);
+        if (length > budget) {
+          throw new HistoryIndexError(
+            "RECORD_TOO_LARGE",
+            "Selected canonical output exceeds the 16 MiB detail budget.",
+          );
+        }
+      }
+    },
+  );
+}
+function readProjection(fd: number, size: number, projection: Readonly<JsonProjection>): unknown {
+  const decoder = new TextDecoder("utf8", { fatal: true });
+  const bytes = Buffer.allocUnsafe(64 * 1024);
+  for (let offset = 0; offset < size;) {
+    const count = fs.readSync(fd, bytes, 0, Math.min(bytes.length, size - offset), offset);
+    if (count === 0) {
+      throw new HistoryIndexError("SOURCE_CHANGED", "Selected canonical output was truncated.");
+    }
+    projection.write(decoder.decode(bytes.subarray(0, count), { stream: true }));
+    offset += count;
+  }
+  projection.write(decoder.decode());
+  return projection.finish();
 }
-
 /** Explicit legacy/compact owner detail: retain only this child's output, never transcript arrays. */
 export function readCanonicalOutput(file: string, index: number): string | undefined {
-	let prefix: Array<string | number>;
-	if (path.basename(file) === "foreground.json") {
-		const metadata = readJsonProjection(file, (keys) => !keys.length || keys[0] === "children" && (keys.length <= 2 || keys.length === 3 && keys[2] === "index"));
-		const position = metadata.children?.findIndex((child: { index: number } | null) => child?.index === index);
-		if (position === undefined || position < 0) return;
-		prefix = ["children", position, "result"];
-	} else prefix = path.basename(file) === "result.json" ? ["results", index] : ["result"];
-	let length = 0;
-	const projection = new JsonProjection((keys) => {
-		if (prefix[0] === "children" && keys.length === 3 && keys[0] === "children" && keys[1] === prefix[1] && keys[2] === "index") return true;
-		if (keys.length <= prefix.length) return keys.every((key, position) => key === prefix[position]);
-		return keys.length === prefix.length + 1 && prefix.every((key, position) => key === keys[position]) && ["finalOutput", "output"].includes(String(keys.at(-1))) ? budget : false;
-	}, (keys, text) => {
-		if (keys.length === prefix.length + 1 && prefix.every((key, position) => key === keys[position]) && ["finalOutput", "output"].includes(String(keys.at(-1)))) {
-			length += Buffer.byteLength(text);
-			if (length > budget) throw new HistoryIndexError("RECORD_TOO_LARGE", "Selected canonical output exceeds the 16 MiB detail budget.");
-		}
-	});
-	const fd = fs.openSync(file, "r"), decoder = new TextDecoder("utf8", { fatal: true });
-	try {
-		const before = fs.fstatSync(fd, { bigint: true }), bytes = Buffer.allocUnsafe(64 * 1024);
-		for (let offset = 0; offset < Number(before.size);) {
-			const count = fs.readSync(fd, bytes, 0, Math.min(bytes.length, Number(before.size) - offset), offset);
-			if (!count) throw new HistoryIndexError("SOURCE_CHANGED", "Selected canonical output was truncated.");
-			projection.write(decoder.decode(bytes.subarray(0, count), { stream: true })); offset += count;
-		}
-		projection.write(decoder.decode());
-		const value = projection.finish(), after = fs.fstatSync(fd, { bigint: true }), current = fs.statSync(file, { bigint: true });
-		if (prefix[0] === "children" && value?.children?.[prefix[1]]?.index !== index) throw new HistoryIndexError("SOURCE_CHANGED", "Selected canonical child changed; retry details.");
-		if (before.size !== after.size || before.ctimeNs !== after.ctimeNs || before.dev !== current.dev || before.ino !== current.ino) throw new HistoryIndexError("SOURCE_CHANGED", "Selected canonical output changed; retry details.");
-		let child: unknown = value;
-		for (const key of prefix) child = child && typeof child === "object" ? (child as Record<string | number, unknown>)[key] : undefined;
-		if (!child || typeof child !== "object") return;
-		const result = child as Record<string, unknown>;
-		return typeof result.finalOutput === "string" ? result.finalOutput : typeof result.output === "string" ? result.output : undefined;
-	} finally { fs.closeSync(fd); }
+  const prefix = childPrefix(file, index);
+  if (!prefix) {
+    return;
+  }
+  const projection = outputProjection(prefix);
+  const fd = fs.openSync(file, "r");
+  try {
+    const before = fs.fstatSync(fd, { bigint: true });
+    const value = readProjection(fd, Number(before.size), projection);
+    if (prefix[0] === "children" && at(value, ["children", Number(prefix[1]), "index"]) !== index) {
+      throw new HistoryIndexError(
+        "SOURCE_CHANGED",
+        "Selected canonical child changed; retry details.",
+      );
+    }
+    unchanged(file, fd, before);
+    const result = object(at(value, prefix));
+    if (typeof result.finalOutput === "string") {
+      return result.finalOutput;
+    }
+    return typeof result.output === "string" ? result.output : undefined;
+  } finally {
+    fs.closeSync(fd);
+  }
 }

package/src/history/canonical-selection.ts

@@ -0,0 +1,54 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getRunMetadataDir } from "../runs/shared/supervisor-questions.ts";
+import { HistoryIndexError, type HistoryResult, type HistoryRunRow } from "./types.ts";
+import type { HistoryQueries } from "./queries.ts";
+import { exactTextDigest, hasText } from "./text.ts";
+import { readCanonicalOutput, readSavedOutput } from "./canonical-result.ts";
+
+function output(view: HistoryRunRow, child: HistoryRunRow["children"][number]): string {
+  const result = child.result;
+  if (!result) {
+    return "";
+  }
+  if (hasText(result.fullOutputPath)) {
+    return readSavedOutput(result.fullOutputPath);
+  }
+  const file =
+    view.resultPath ?? path.join(getRunMetadataDir(view.runId), "contracts", `${child.index}.json`);
+  const preview = result.finalOutput ?? "";
+  return fs.existsSync(file) ? (readCanonicalOutput(file, child.index) ?? preview) : preview;
+}
+/** Saved full output takes precedence over canonical detail, which precedes the projected preview. */
+export function selectCanonicalResult(
+  view: HistoryRunRow,
+  index: number,
+  queries: Readonly<HistoryQueries>,
+): HistoryResult | null {
+  const child = view.children.find((candidate) => candidate.index === index);
+  if (!child) {
+    throw new HistoryIndexError("OWNERSHIP", "Child is not admitted by this owner.");
+  }
+  if (!child.result) {
+    return null;
+  }
+  const body = output(view, child);
+  if (Buffer.byteLength(body) > 16 * 1024 * 1024) {
+    throw new HistoryIndexError(
+      "RECORD_TOO_LARGE",
+      "Selected canonical output exceeds the 16 MiB detail budget.",
+    );
+  }
+  const boundary =
+    child.state === "live"
+      ? {}
+      : {
+          terminalEntryId: child.result.terminalEntryId,
+          endedAt: hasText(child.result.terminalEntryId) ? undefined : view.updatedAt,
+        };
+  const finalResultId = queries.finalResultId(
+    { runId: view.runId, index, ...boundary },
+    exactTextDigest(body),
+  );
+  return { text: body, timestamp: view.updatedAt, finalResultId };
+}

package/src/history/database-generation.ts

@@ -0,0 +1,86 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+import { historyDirectory, openHistoryDatabase } from "./database.ts";
+import { createHistorySchema, HISTORY_SCHEMA_VERSION } from "./schema.ts";
+import { hash } from "./text.ts";
+import { HistoryIndexError } from "./types.ts";
+import { object, errorMessage } from "./values.ts";
+import { hasErrorCode } from "../shared/unknown.ts";
+
+function manifestFile(manifest: string): string | undefined {
+  try {
+    const input: unknown = JSON.parse(fs.readFileSync(manifest, "utf8"));
+    const saved = object(input);
+    if (typeof saved.file === "string" && /^[a-f0-9-]+\.sqlite$/.test(saved.file)) {
+      return saved.file;
+    }
+  } catch (error) {
+    if (!hasErrorCode(error, "ENOENT") && !(error instanceof SyntaxError)) {
+      throw error;
+    }
+  }
+  return undefined;
+}
+function isCorruption(error: unknown): boolean {
+  return (
+    (error instanceof HistoryIndexError && error.code === "CORRUPT") ||
+    /malformed|not a database|no such table|corrupt/i.test(errorMessage(error))
+  );
+}
+function existingGeneration(file: string): DatabaseSync | undefined {
+  let db: DatabaseSync | undefined;
+  try {
+    if (!fs.existsSync(file) || fs.lstatSync(file).isSymbolicLink()) {
+      throw new HistoryIndexError("CORRUPT", "Invalid index generation.");
+    }
+    db = openHistoryDatabase(file);
+    if (db.prepare("PRAGMA user_version").get()?.user_version !== HISTORY_SCHEMA_VERSION) {
+      throw new HistoryIndexError("CORRUPT", "Invalid index schema.");
+    }
+    db.prepare("SELECT value FROM meta WHERE key='generation'").get();
+    return db;
+  } catch (error) {
+    db?.close();
+    if (!isCorruption(error)) {
+      throw error;
+    }
+    return undefined;
+  }
+}
+/** Manifest replacement selects a fresh projection without unlinking another connection's WAL. */
+export function openGeneration(
+  agentDir: string,
+  owner: string,
+): { readonly db: DatabaseSync; readonly file: string } {
+  const directory = historyDirectory(agentDir);
+  const manifest = path.join(directory, `${hash(owner)}.json`);
+  let name = manifestFile(manifest);
+  let db = name === undefined ? undefined : existingGeneration(path.join(directory, name));
+  try {
+    if (!db) {
+      name = `${randomUUID()}.sqlite`;
+      db = openHistoryDatabase(path.join(directory, name));
+      createHistorySchema(db);
+      const temporary = `${manifest}.${process.pid}.${randomUUID()}`;
+      fs.writeFileSync(temporary, JSON.stringify({ file: name }), { mode: 0o600 });
+      fs.renameSync(temporary, manifest);
+    }
+    if (name === undefined) {
+      throw new HistoryIndexError("CORRUPT", "Missing index generation name.");
+    }
+    const file = path.join(directory, name);
+    fs.chmodSync(file, 0o600);
+    for (const suffix of ["-wal", "-shm"]) {
+      if (fs.existsSync(file + suffix)) {
+        fs.chmodSync(file + suffix, 0o600);
+      }
+    }
+    return { db, file };
+  } catch (error) {
+    // Ownership transfers to HistoryStore only after schema, manifest and permissions succeed.
+    db?.close();
+    throw error;
+  }
+}