@fitchmultz/pi-subagents 0.49.1 → 0.50.0

package/src/runs/shared/native-finalization.ts

@@ -1,252 +0,0 @@
-import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-  AgentBeforeSettleEvent,
-  AgentBeforeSettleEventResult,
-} from "@earendil-works/pi-coding-agent";
-import type {
-  AcceptanceLedger,
-  ResolvedAcceptanceConfig,
-  ObservedMessage,
-  ReadonlyInput,
-} from "../../shared/types.ts";
-import { setPromptSection } from "../../shared/prompt-sections.ts";
-import { detectSubagentError, getFinalOutput } from "../../shared/utils.ts";
-import {
-  acceptanceFailureMessage,
-  acceptanceSelfReviewConfig,
-  createFinalizationReportRuntime,
-  evaluateAcceptance,
-  formatAcceptanceFinalizationPrompt,
-  readFinalizationReport,
-  resolveFinalizationOutput,
-  stripAcceptanceReport,
-} from "./acceptance.ts";
-import { captureSingleOutputSnapshot, resolveSingleOutput } from "./single-output.ts";
-import { readStructuredOutput, type StructuredOutputRuntime } from "./structured-output.ts";
-import { compactObservedMessage } from "./child-observations.ts";
-import { registerChildStructuredTool } from "./child-structured-tool.ts";
-import { parseNativeFinalizationConfig } from "../background/run-schemas.ts";
-import {
-  FINALIZATION_EVENT,
-  type NativeFinalizationConfig,
-  type NativeFinalizationEvent,
-} from "./native-finalization-types.ts";
-import { nonempty } from "./child-presence.ts";
-export {
-  FINALIZATION_EVENT,
-  type NativeFinalizationConfig,
-  type NativeFinalizationEvent,
-} from "./native-finalization-types.ts";
-
-const CONFIG_ENV = "PI_SUBAGENT_FINALIZATION_CONFIG";
-export function createNativeFinalization(
-  acceptance: ResolvedAcceptanceConfig,
-  publicOutput?: StructuredOutputRuntime,
-  outputPath?: string,
-): NativeFinalizationConfig {
-  return {
-    nonce: randomUUID(),
-    acceptance,
-    reportRuntime: createFinalizationReportRuntime(publicOutput?.schema),
-    publicOutput,
-    outputPath,
-    outputSnapshot: captureSingleOutputSnapshot(outputPath),
-  };
-}
-export function nativeFinalizationLaunch(config: ReadonlyInput<NativeFinalizationConfig>): {
-  extension: string;
-  env: Record<string, string>;
-} {
-  const configPath = path.join(path.dirname(config.reportRuntime.schemaPath), "finalization.json");
-  fs.writeFileSync(configPath, JSON.stringify(config), { mode: 0o600 });
-  return {
-    extension: fileURLToPath(
-      new URL(
-        `native-finalization${import.meta.url.endsWith(".ts") ? ".ts" : ".js"}`,
-        import.meta.url,
-      ),
-    ),
-    env: { [CONFIG_ENV]: configPath },
-  };
-}
-
-/** Owns self-review turns; command verification remains exclusively owner-run. */
-class NativeReview {
-  private readonly config: ReadonlyInput<NativeFinalizationConfig>;
-  private readonly messages: ObservedMessage[] = [];
-  private messageOffset = 0;
-  private turn = 0;
-  private initialOutput = "";
-  private latestOutput = "";
-  private initialLedger?: AcceptanceLedger;
-  private resolvedOutput: ReturnType<typeof resolveSingleOutput> = { fullOutput: "" };
-  constructor(config: ReadonlyInput<NativeFinalizationConfig>) {
-    this.config = config;
-  }
-
-  observe(message: ObservedMessage): void {
-    if (["assistant", "user", "toolResult"].includes(message.role)) {
-      const output = getFinalOutput([message]);
-      if (output.length > 0) {
-        this.latestOutput = output;
-      }
-      this.messages.push(compactObservedMessage(message));
-    }
-  }
-  private submission(): NativeFinalizationEvent["submission"] {
-    const submission: NativeFinalizationEvent["submission"] =
-      this.turn === 0
-        ? { output: this.latestOutput }
-        : readFinalizationReport(this.messages, this.config.reportRuntime, {
-            messageOffset: this.messageOffset,
-          });
-    if (this.turn === 0) {
-      this.initialOutput = submission.output;
-      const hiddenError = detectSubagentError(this.messages);
-      if (hiddenError.hasError) {
-        submission.error = hiddenError.details ?? `${hiddenError.errorType ?? "Subagent"} failed`;
-      }
-      if (this.config.publicOutput) {
-        submission.error ??= readStructuredOutput(this.config.publicOutput).error;
-      }
-    }
-    return submission;
-  }
-  private saveOutput(
-    submission: ReadonlyInput<NativeFinalizationEvent["submission"]>,
-  ): string | undefined {
-    if (nonempty(submission.error) || nonempty(submission.reportSubmissionError)) {
-      return;
-    }
-    const output =
-      this.turn === 0
-        ? stripAcceptanceReport(submission.output)
-        : resolveFinalizationOutput(submission.output, this.resolvedOutput.fullOutput);
-    this.resolvedOutput = resolveSingleOutput(
-      this.config.outputPath,
-      output,
-      this.turn === 0 ? this.config.outputSnapshot : this.resolvedOutput.writtenSnapshot,
-    );
-    return nonempty(this.resolvedOutput.saveError)
-      ? `Failed to save output file '${this.config.outputPath ?? ""}': ${this.resolvedOutput.saveError}`
-      : undefined;
-  }
-  private nextPrompt(
-    submission: ReadonlyInput<NativeFinalizationEvent["submission"]>,
-    ledger: AcceptanceLedger,
-  ): string | undefined {
-    if (
-      nonempty(submission.error) ||
-      ledger.status === "blocked" ||
-      this.turn >= this.config.acceptance.finalization.maxTurns
-    ) {
-      return;
-    }
-    if (!this.initialLedger) {
-      throw new Error("Native self-review initial acceptance ledger is missing");
-    }
-    if (
-      this.turn !== 0 &&
-      !nonempty(submission.reportSubmissionError) &&
-      ledger.status !== "rejected"
-    ) {
-      return;
-    }
-    return formatAcceptanceFinalizationPrompt({
-      acceptance: this.config.acceptance,
-      initialOutput: this.initialOutput,
-      initialLedger: this.initialLedger,
-      turn: this.turn + 1,
-      maxTurns: this.config.acceptance.finalization.maxTurns,
-      previousFailure: submission.reportSubmissionError ?? acceptanceFailureMessage(ledger),
-      nativeReport: true,
-      outputSchema: this.config.publicOutput?.schema,
-    });
-  }
-  async settle(
-    event: AgentBeforeSettleEvent,
-    ctx: ExtensionContext,
-    pi: ExtensionAPI,
-  ): Promise<AgentBeforeSettleEventResult | undefined> {
-    if (event.outcome !== "completed") {
-      return;
-    }
-    const submission = this.submission();
-    const ledger = await evaluateAcceptance({
-      acceptance: acceptanceSelfReviewConfig(this.config.acceptance),
-      governing: this.config.acceptance,
-      cwd: ctx.cwd,
-      output: nonempty(submission.reportSubmissionError) ? "" : submission.output,
-      report: nonempty(submission.reportSubmissionError) ? undefined : submission.report,
-    });
-    this.initialLedger ??= ledger;
-    const saveError = this.saveOutput(submission);
-    submission.error ??= saveError;
-    const nextPrompt = this.nextPrompt(submission, ledger);
-    const marker: NativeFinalizationEvent = {
-      type: FINALIZATION_EVENT,
-      nonce: this.config.nonce,
-      turn: this.turn,
-      lastEntryId: ctx.sessionManager.getLeafId() ?? undefined,
-      messageCount: this.messages.length,
-      at: Date.now(),
-      submission,
-      acceptance: ledger,
-      resolvedOutput: this.resolvedOutput,
-      nextPrompt,
-    };
-    fs.appendFileSync(
-      path.join(path.dirname(this.config.reportRuntime.schemaPath), "boundaries.jsonl"),
-      `${JSON.stringify(marker)}\n`,
-      { mode: 0o600 },
-    );
-    if (!nonempty(nextPrompt)) {
-      return;
-    }
-    if (this.turn === 0) {
-      registerChildStructuredTool(pi, this.config.reportRuntime);
-      pi.setActiveTools([...new Set([...pi.getActiveTools(), "structured_output"])]);
-    }
-    this.turn++;
-    this.messageOffset = this.messages.length;
-    return {
-      entries: [
-        ...event.entries,
-        {
-          type: "custom_message",
-          customType: "subagent-self-review",
-          content: nextPrompt,
-          display: false,
-        },
-      ],
-      continue: true,
-    };
-  }
-}
-
-export default function registerNativeFinalization(pi: ExtensionAPI): void {
-  const configPath = process.env[CONFIG_ENV];
-  if (!nonempty(configPath)) {
-    return;
-  }
-  const value: unknown = JSON.parse(fs.readFileSync(configPath, "utf8"));
-  const config = parseNativeFinalizationConfig(value);
-  const review = new NativeReview(config);
-  if (config.publicOutput) {
-    registerChildStructuredTool(pi, config.publicOutput);
-    pi.on("before_agent_start", (event) => {
-      setPromptSection(
-        event.systemPromptOptions,
-        "subagent_output",
-        "Your final action must call structured_output with JSON matching the current schema. Prose alone does not complete this output contract.",
-      );
-    });
-  }
-  pi.on("message_end", (event) => review.observe(event.message));
-  pi.on("agent_before_settle", (event, ctx) => review.settle(event, ctx, pi));
-}

package/src/runs/shared/native-usage.ts

@@ -1,396 +0,0 @@
-import type { Usage as NativeUsage } from "@earendil-works/pi-ai";
-import { isDeepStrictEqual } from "node:util";
-import type {
-  ObservedUsage,
-  ReadonlyInput,
-  Usage,
-  UsageAccumulator,
-  UsageContribution,
-} from "../../shared/types.ts";
-import { scanJournal, nativeProjection } from "../../shared/journal-reader.ts";
-import { hasErrorCode, isRecord as isObject } from "../../shared/unknown.ts";
-import { nonempty } from "./child-presence.ts";
-import {
-  observedUsage,
-  optionalNumber,
-  optionalString,
-  requiredString,
-} from "./child-message-validation.ts";
-
-export interface NativeBaseline {
-  readonly ids: Readonly<ReadonlySet<string>>;
-  readonly entryCount: number;
-  readonly legacy: boolean;
-  readonly sessionId?: string;
-}
-
-export function snapshotNativeBaseline(
-  file: string | undefined,
-): NativeBaseline & { readonly ids: Set<string> } {
-  const ids = new Set<string>();
-  let first = true;
-  let native = false;
-  let entryCount = 0;
-  let legacy = false;
-  let sessionId: string | undefined;
-  if (nonempty(file)) {
-    try {
-      scanJournal(
-        file,
-        (path) =>
-          path.length === 0 ||
-          (path.length === 1 && ["id", "type", "version"].includes(String(path[0]))),
-        ({ value }) => {
-          if (first) {
-            first = false;
-            native = value.type === "session";
-            if (native) {
-              sessionId = requiredString(value.id, "native session identity");
-              if (sessionId.length === 0) {
-                throw new SyntaxError("Invalid native session identity");
-              }
-              legacy = value.version === 1;
-            }
-          } else if (native) {
-            entryCount++;
-          }
-          if (native && typeof value.id === "string") {
-            ids.add(value.id);
-          }
-        },
-        { requireNewline: true },
-      );
-    } catch (error) {
-      if (!hasErrorCode(error, "ENOENT")) {
-        throw error;
-      }
-    }
-  }
-  return { ids, entryCount, legacy, sessionId };
-}
-
-export function snapshotNativeUsage(file: string | undefined): Set<string> {
-  return snapshotNativeBaseline(file).ids;
-}
-
-function validateObservedCounters(value: ObservedUsage): void {
-  // This exported reducer may receive external observations; static types are not wire validation.
-  observedUsage(value);
-  for (const [key, counter] of Object.entries(value)) {
-    if (typeof counter === "number" && (!Number.isFinite(counter) || counter < 0)) {
-      throw new Error(`Invalid native usage counter: ${key}`);
-    }
-  }
-  if (value.cost) {
-    for (const counter of Object.values(value.cost)) {
-      if (!Number.isFinite(counter) || counter < 0) {
-        throw new Error("Invalid native usage cost");
-      }
-    }
-  }
-}
-
-/** Mutating accounting boundary: the caller owns this accumulator, observations stay readonly. */
-export function addUsage(
-  usage: UsageAccumulator,
-  value: ObservedUsage,
-  attribution?: Omit<UsageContribution, "usage">,
-): void {
-  validateObservedCounters(value);
-  usage.input += value.input ?? 0;
-  usage.output += value.output ?? 0;
-  usage.cacheRead += value.cacheRead ?? 0;
-  usage.cacheWrite += value.cacheWrite ?? 0;
-  usage.cost += value.cost?.total ?? 0;
-  if (attribution) {
-    (usage.contributions ??= []).push({ ...attribution, usage: value });
-  }
-}
-
-/** Complete native receipts are required for billing; partial observations remain audit-only. */
-export function validateNativeUsage(
-  value: ObservedUsage,
-): asserts value is ReadonlyInput<NativeUsage> {
-  for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
-    const counter = value[key];
-    if (counter === undefined || !Number.isFinite(counter) || counter < 0) {
-      throw new Error(`Native usage ${key} is unavailable or invalid`);
-    }
-  }
-  for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
-    const counter = value.cost?.[key];
-    if (counter === undefined || !Number.isFinite(counter) || counter < 0) {
-      throw new Error(`Native usage cost.${key} is unavailable or invalid`);
-    }
-  }
-}
-
-export interface NativeUsageMetadata {
-  readonly type: string;
-  readonly id: string;
-  readonly checkpoint?: boolean;
-  readonly provider?: string;
-  readonly model?: string;
-  readonly usage?: ObservedUsage;
-  readonly message?: {
-    readonly role: string;
-    readonly timestamp?: number;
-    readonly toolCallId?: string;
-    readonly provider?: string;
-    readonly model?: string;
-    readonly responseModel?: string;
-    readonly usage?: ObservedUsage;
-  };
-}
-
-export function nativeUsageMetadata(value: unknown): NativeUsageMetadata {
-  if (!isObject(value)) {
-    throw new SyntaxError("Invalid native entry");
-  }
-  const message = isObject(value.message) ? value.message : undefined;
-  if (value.type === "message" && !message) {
-    throw new SyntaxError("Invalid native message");
-  }
-  if (value.checkpoint !== undefined && typeof value.checkpoint !== "boolean") {
-    throw new SyntaxError("Invalid native checkpoint");
-  }
-  return {
-    ...value,
-    type: requiredString(value.type, "native entry type"),
-    id: requiredString(value.id, "native entry identity"),
-    checkpoint: value.checkpoint,
-    provider: optionalString(value.provider, "provider"),
-    model: optionalString(value.model, "model"),
-    usage: observedUsage(value.usage),
-    message: message
-      ? {
-          role: requiredString(message.role, "native message role"),
-          timestamp: optionalNumber(message.timestamp, "timestamp"),
-          toolCallId: optionalString(message.toolCallId, "toolCallId"),
-          provider: optionalString(message.provider, "provider"),
-          model: optionalString(message.model, "model"),
-          responseModel: optionalString(message.responseModel, "responseModel"),
-          usage: observedUsage(message.usage),
-        }
-      : undefined,
-  };
-}
-
-interface EntryUsage {
-  readonly value?: ObservedUsage;
-  readonly provider?: string;
-  readonly model?: string;
-}
-function messageUsage(message: NativeUsageMetadata["message"]): EntryUsage {
-  if (message?.role === "assistant") {
-    return {
-      value: message.usage,
-      provider: message.provider,
-      model: message.responseModel ?? message.model,
-    };
-  }
-  return { value: message?.role === "toolResult" ? message.usage : undefined };
-}
-function entryUsage(entry: NativeUsageMetadata): EntryUsage {
-  if (entry.type === "usage") {
-    return { value: entry.usage, provider: entry.provider, model: entry.model };
-  }
-  if (entry.type === "compaction" || entry.type === "branch_summary") {
-    return { value: entry.usage };
-  }
-  return entry.type === "message" ? messageUsage(entry.message) : {};
-}
-function requiredReceipt(entry: NativeUsageMetadata): EntryUsage {
-  const receipt = entryUsage(entry);
-  const required =
-    entry.type === "usage" || (entry.type === "message" && entry.message?.role === "assistant");
-  if (!receipt.value && required) {
-    throw new Error(`Required native usage is unavailable: ${entry.id}`);
-  }
-  return receipt;
-}
-export interface NativeUsageCollector {
-  readonly totals: readonly Usage[];
-  readonly append: (entry: NativeUsageMetadata) => void;
-}
-
-class UsageCollector implements NativeUsageCollector {
-  private readonly sessionId: string;
-  private readonly baseline: Readonly<ReadonlySet<string>>;
-  private readonly boundaries: readonly (string | undefined)[];
-  private readonly segments: UsageAccumulator[];
-  private readonly contributions = new Map<string, UsageContribution>();
-  private readonly turns = new Set<string>();
-  private segment = 0;
-  constructor(
-    sessionId: string,
-    baseline: Readonly<ReadonlySet<string>>,
-    boundaries: readonly (string | undefined)[],
-  ) {
-    this.sessionId = sessionId;
-    this.baseline = baseline;
-    this.boundaries = boundaries;
-    this.segments = Array.from({ length: Math.max(1, boundaries.length) }, () => ({
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      cost: 0,
-      turns: 0,
-      contributions: [],
-    }));
-  }
-  get totals(): readonly Usage[] {
-    return this.segments;
-  }
-  private total(): UsageAccumulator {
-    const total = this.segments.at(this.segment);
-    if (!total) {
-      throw new Error("Missing native usage segment");
-    }
-    return total;
-  }
-  private countTurn(entry: NativeUsageMetadata): void {
-    if (
-      entry.type === "message" &&
-      entry.message?.role === "assistant" &&
-      !this.turns.has(entry.id)
-    ) {
-      this.total().turns++;
-      this.turns.add(entry.id);
-    }
-  }
-  private account(entry: NativeUsageMetadata): void {
-    const { value, provider, model } = requiredReceipt(entry);
-    this.countTurn(entry);
-    if (!value) {
-      return;
-    }
-    validateNativeUsage(value);
-    if (entry.id.length === 0) {
-      throw new Error("Native usage entry identity is unavailable");
-    }
-    const next = { id: `${this.sessionId}:${entry.id}`, provider, model, usage: value };
-    const previous = this.contributions.get(next.id);
-    if (previous && !isDeepStrictEqual(previous, next)) {
-      throw new Error(`Conflicting native usage contribution: ${next.id}`);
-    }
-    if (!previous) {
-      this.contributions.set(next.id, next);
-      addUsage(this.total(), value, { id: next.id, provider, model });
-    }
-  }
-  append(entry: NativeUsageMetadata): void {
-    if (!this.baseline.has(entry.id) && entry.checkpoint !== true) {
-      this.account(entry);
-    }
-    if (entry.id === this.boundaries.at(this.segment) && this.segment < this.segments.length - 1) {
-      this.segment++;
-    }
-  }
-}
-
-/** One reducer for published journals and settled, once-audited in-memory sessions. */
-export function nativeUsageCollector(
-  sessionId: string,
-  baseline: Readonly<ReadonlySet<string>>,
-  boundaries: readonly (string | undefined)[] = [],
-): NativeUsageCollector {
-  return new UsageCollector(sessionId, baseline, boundaries);
-}
-
-interface NativeUsageReadOptions {
-  readonly terminalEntryId?: string;
-  readonly onEntry?: (entry: NativeUsageMetadata) => void;
-  readonly onBoundary?: (boundary: {
-    readonly sessionId: string;
-    readonly lastEntryId?: string;
-  }) => void;
-}
-class UsageReader {
-  private readonly baseline: Readonly<ReadonlySet<string>>;
-  private readonly boundaries: readonly (string | undefined)[];
-  private readonly options: NativeUsageReadOptions;
-  private first = true;
-  private sessionId?: string;
-  private lastEntryId?: string;
-  private reached = false;
-  private collector?: NativeUsageCollector;
-  constructor(
-    baseline: Readonly<ReadonlySet<string>>,
-    boundaries: readonly (string | undefined)[],
-    options: NativeUsageReadOptions,
-  ) {
-    this.baseline = baseline;
-    this.boundaries = boundaries;
-    this.options = options;
-  }
-  observe(value: Readonly<Record<string, unknown>>): boolean {
-    if (this.first) {
-      this.first = false;
-      this.sessionId =
-        value.type === "session" ? requiredString(value.id, "native session identity") : undefined;
-      if (nonempty(this.sessionId)) {
-        this.collector = nativeUsageCollector(this.sessionId, this.baseline, this.boundaries);
-      }
-    }
-    if (!this.collector) {
-      return false;
-    }
-    const entry = nativeUsageMetadata(value);
-    this.options.onEntry?.(entry);
-    this.collector.append(entry);
-    if (entry.type !== "session") {
-      this.lastEntryId = entry.id;
-    }
-    if (entry.id === this.options.terminalEntryId) {
-      this.reached = true;
-      return true;
-    }
-    return false;
-  }
-  finish(): Usage[] | undefined {
-    if (nonempty(this.options.terminalEntryId) && !this.reached) {
-      throw new Error("Native accounting terminal entry is missing");
-    }
-    if (nonempty(this.sessionId)) {
-      this.options.onBoundary?.({ sessionId: this.sessionId, lastEntryId: this.lastEntryId });
-    }
-    return this.collector?.totals.slice();
-  }
-}
-
-/** Read journals without opening a second writer or copying their transcripts. */
-export function readNativeUsage(
-  file: string | undefined,
-  baseline: Readonly<ReadonlySet<string>>,
-  boundaries: readonly (string | undefined)[] = [],
-  options: NativeUsageReadOptions = {},
-): Usage[] | undefined {
-  if (!nonempty(file)) {
-    return;
-  }
-  const reader = new UsageReader(baseline, boundaries, options);
-  const boundaryReached = new Error("terminal entry reached");
-  try {
-    scanJournal(
-      file,
-      (keys, root) =>
-        keys[0] === "message" && keys[1] === "content" ? false : nativeProjection(keys, root),
-      ({ value }) => {
-        if (reader.observe(value)) {
-          throw boundaryReached;
-        }
-      },
-      { requireNewline: true },
-    );
-  } catch (error) {
-    if (hasErrorCode(error, "ENOENT")) {
-      return;
-    }
-    if (error !== boundaryReached) {
-      throw error;
-    }
-  }
-  return reader.finish();
-}