@dogpile/sdk 0.3.1 → 0.5.0

package/src/runtime/defaults.ts

@@ -1,3 +1,4 @@
+import { DogpileError } from "../types.js";
 import type {
   AgentSpec,
   Budget,
@@ -18,7 +19,9 @@ import type {
   RunEventLog,
   RunMetadata,
   RunUsage,
+  OnChildFailureMode,
   Tier,
+  Trace,
   TranscriptEntry,
   TranscriptLink
 } from "../types.js";
@@ -129,6 +132,38 @@ export function addCost(left: CostSummary, right: CostSummary): CostSummary {
   };
 }
 
+export function resolveOnChildFailure(
+  runOption: OnChildFailureMode | undefined,
+  engineOption: OnChildFailureMode | undefined
+): OnChildFailureMode {
+  // onChildFailure precedence: per-run option > engine option > default.
+  return runOption ?? engineOption ?? "continue";
+}
+
+/**
+ * Walk a parent's events and accumulate the cost contributed by every
+ * sub-run (BUDGET-03 / D-06). Internal helper — not part of the public surface.
+ *
+ * - `sub-run-completed` events contribute `event.subResult.cost`.
+ * - `sub-run-failed` events contribute `event.partialCost` (real provider
+ *   spend captured before the throw).
+ *
+ * Used by the `parent-rollup-drift` parity check in
+ * {@link recomputeAccountingFromTrace} to verify the parent's recorded
+ * accounting equals `localOnly + Σ children` recursively.
+ */
+export function accumulateSubRunCost(events: readonly RunEvent[]): CostSummary {
+  let total = emptyCost();
+  for (const event of events) {
+    if (event.type === "sub-run-completed") {
+      total = addCost(total, event.subResult.cost);
+    } else if (event.type === "sub-run-failed") {
+      total = addCost(total, event.partialCost);
+    }
+  }
+  return total;
+}
+
 export function createTranscriptLink(transcript: readonly TranscriptEntry[]): TranscriptLink {
   return {
     kind: "trace-transcript",
@@ -201,8 +236,8 @@ export function createRunMetadata(options: {
     tier: options.tier,
     modelProviderId: options.modelProviderId,
     agentsUsed: options.agentsUsed,
-    startedAt: firstEvent?.at ?? "",
-    completedAt: lastEvent?.at ?? ""
+    startedAt: eventTimestamp(firstEvent) ?? "",
+    completedAt: eventTimestamp(lastEvent) ?? ""
   };
 }
 
@@ -274,6 +309,13 @@ export function createReplayTraceBudgetStateChanges(
       case "model-output-chunk":
       case "tool-call":
       case "tool-result":
+      case "sub-run-started":
+      case "sub-run-completed":
+      case "sub-run-failed":
+      case "sub-run-parent-aborted":
+      case "sub-run-budget-clamped":
+      case "sub-run-queued":
+      case "sub-run-concurrency-clamped":
         return [];
     }
   });
@@ -323,7 +365,7 @@ export function createReplayTraceProtocolDecision(
     eventType: event.type,
     protocol,
     decision: options.decision ?? defaultProtocolDecision(event),
-    at: event.at,
+    at: eventTimestamp(event),
     ...(options.turn !== undefined ? { turn: options.turn } : {}),
     ...(options.phase !== undefined ? { phase: options.phase } : {}),
     ...(options.round !== undefined ? { round: options.round } : {}),
@@ -408,6 +450,39 @@ export function createReplayTraceProtocolDecision(
         output: event.output,
         cost: event.cost
       };
+    case "sub-run-started":
+      return {
+        ...base,
+        input: event.intent
+      };
+    case "sub-run-completed":
+      return {
+        ...base,
+        output: event.subResult.output,
+        cost: event.subResult.cost
+      };
+    case "sub-run-failed":
+      return {
+        ...base
+      };
+    case "sub-run-parent-aborted":
+      return {
+        ...base
+      };
+    case "sub-run-budget-clamped":
+      return {
+        ...base
+      };
+    case "sub-run-queued":
+      return {
+        ...base,
+        childRunId: event.childRunId,
+        queuePosition: event.queuePosition
+      };
+    case "sub-run-concurrency-clamped":
+      return {
+        ...base
+      };
   }
 }
 
@@ -433,6 +508,20 @@ function defaultProtocolDecision(event: RunEvent): ReplayTraceProtocolDecisionTy
       return "stop-for-budget";
     case "final":
       return "finalize-output";
+    case "sub-run-started":
+      return "start-sub-run";
+    case "sub-run-completed":
+      return "complete-sub-run";
+    case "sub-run-failed":
+      return "fail-sub-run";
+    case "sub-run-parent-aborted":
+      return "mark-sub-run-parent-aborted";
+    case "sub-run-budget-clamped":
+      return "mark-sub-run-budget-clamped";
+    case "sub-run-queued":
+      return "queue-sub-run";
+    case "sub-run-concurrency-clamped":
+      return "mark-sub-run-concurrency-clamped";
   }
 }
 
@@ -461,7 +550,7 @@ export function createReplayTraceFinalOutput(output: string, event: RunEvent): R
     kind: "replay-trace-final-output",
     output,
     cost: emptyCost(),
-    completedAt: event.at,
+    completedAt: eventTimestamp(event),
     transcript: {
       kind: "trace-transcript",
       entryCount: 0,
@@ -470,6 +559,14 @@ export function createReplayTraceFinalOutput(output: string, event: RunEvent): R
   };
 }
 
+function eventTimestamp(event: RunEvent): string;
+function eventTimestamp(event: RunEvent | undefined): string | undefined;
+function eventTimestamp(event: RunEvent | undefined): string | undefined {
+  if (event === undefined) return undefined;
+  if ("at" in event) return event.at;
+  return event.type === "model-response" ? event.completedAt : event.startedAt;
+}
+
 export function nextProviderCallId(
   runId: string,
   providerCalls: readonly ReplayTraceProviderCall[]
@@ -500,6 +597,7 @@ export function canonicalizeRunResult(result: RunResult): RunResult {
     cost: canonicalizeSerializable(result.cost),
     ...(result.evaluation !== undefined ? { evaluation: canonicalizeSerializable(result.evaluation) } : {}),
     eventLog,
+    health: canonicalizeSerializable(result.health),
     metadata: canonicalizeSerializable(result.metadata),
     output: result.output,
     ...(result.quality !== undefined ? { quality: canonicalizeSerializable(result.quality) } : {}),
@@ -515,6 +613,293 @@ export function stableJsonStringify(value: unknown): string {
   return JSON.stringify(canonicalizeSerializable(value));
 }
 
+/**
+ * The eight numeric fields recursively verified by `recomputeAccountingFromTrace`.
+ *
+ * These are the only summable scalars on `RunAccounting`. Non-numeric fields
+ * (`kind`, `tier`, `budget`, `termination`, `budgetStateChanges`) and derived
+ * ratios (`usdCapUtilization`, `totalTokenCapUtilization`) are NOT in this set.
+ */
+const RECOMPUTE_FIELD_ORDER: readonly [
+  "cost.usd",
+  "cost.inputTokens",
+  "cost.outputTokens",
+  "cost.totalTokens",
+  "usage.usd",
+  "usage.inputTokens",
+  "usage.outputTokens",
+  "usage.totalTokens"
+] = [
+  "cost.usd",
+  "cost.inputTokens",
+  "cost.outputTokens",
+  "cost.totalTokens",
+  "usage.usd",
+  "usage.inputTokens",
+  "usage.outputTokens",
+  "usage.totalTokens"
+];
+
+const USD_FIELDS: ReadonlySet<string> = new Set(["cost.usd", "usage.usd"]);
+const FLOAT_EPSILON = 1e-9;
+
+function readNumericField(accounting: RunAccounting, field: (typeof RECOMPUTE_FIELD_ORDER)[number]): number {
+  switch (field) {
+    case "cost.usd":
+      return accounting.cost.usd;
+    case "cost.inputTokens":
+      return accounting.cost.inputTokens;
+    case "cost.outputTokens":
+      return accounting.cost.outputTokens;
+    case "cost.totalTokens":
+      return accounting.cost.totalTokens;
+    case "usage.usd":
+      return accounting.usage.usd;
+    case "usage.inputTokens":
+      return accounting.usage.inputTokens;
+    case "usage.outputTokens":
+      return accounting.usage.outputTokens;
+    case "usage.totalTokens":
+      return accounting.usage.totalTokens;
+  }
+}
+
+function fieldsEqual(field: (typeof RECOMPUTE_FIELD_ORDER)[number], a: number, b: number): boolean {
+  if (USD_FIELDS.has(field)) {
+    return Math.abs(a - b) < FLOAT_EPSILON;
+  }
+  return a === b;
+}
+
+function firstDifferingField(
+  recorded: RunAccounting,
+  recomputed: RunAccounting
+): { readonly field: (typeof RECOMPUTE_FIELD_ORDER)[number]; readonly recorded: number; readonly recomputed: number } | null {
+  for (const field of RECOMPUTE_FIELD_ORDER) {
+    const a = readNumericField(recorded, field);
+    const b = readNumericField(recomputed, field);
+    if (!fieldsEqual(field, a, b)) {
+      return { field, recorded: a, recomputed: b };
+    }
+  }
+  return null;
+}
+
+function buildLocalAccounting(trace: Trace): RunAccounting {
+  return createRunAccounting({
+    tier: trace.tier,
+    ...(trace.budget.caps ? { budget: trace.budget.caps } : {}),
+    ...(trace.budget.termination ? { termination: trace.budget.termination } : {}),
+    cost: trace.finalOutput.cost,
+    events: trace.events
+  });
+}
+
+export function lastCostBearingEventCost(events: readonly RunEvent[]): CostSummary | null {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event === undefined) continue;
+    if (
+      event.type === "final" ||
+      event.type === "agent-turn" ||
+      event.type === "broadcast" ||
+      event.type === "budget-stop"
+    ) {
+      return event.cost;
+    }
+  }
+  return null;
+}
+
+/**
+ * Recompute a parent's `RunAccounting` from a saved `Trace` for replay-time
+ * tamper detection.
+ *
+ * @remarks
+ * Returns the parent's local `RunAccounting` (built the same way `replay()`
+ * builds it today, from `trace.finalOutput.cost` and `trace.events`). While
+ * walking events, every `sub-run-completed` is recursed into and the
+ * recomputed child accounting is compared field-by-field to the recorded
+ * `event.subResult.accounting`. A mismatch on any of the eight enumerated
+ * numeric fields throws `DogpileError({ code: "invalid-configuration" })`
+ * with `detail.reason: "trace-accounting-mismatch"` and a concrete
+ * `detail.field` identifying the first differing numeric.
+ *
+ * Pure: no provider calls, no I/O, no clock reads.
+ *
+ * Non-summed fields (`kind`, `tier`, `budget`, `termination`,
+ * `budgetStateChanges`) and derived ratios (`usdCapUtilization`,
+ * `totalTokenCapUtilization`) are not in the comparison set.
+ */
+export function recomputeAccountingFromTrace(trace: Trace): RunAccounting {
+  const local = buildLocalAccounting(trace);
+
+  // Parent-level integrity: the recorded `trace.finalOutput.cost` must match
+  // the cost on the last cost-bearing event. On a clean trace this holds by
+  // construction (every protocol writes `totalCost` into the final event).
+  // On a trace where `finalOutput.cost` was mutated without updating the
+  // events (or vice versa), this catches the drift.
+  const lastEventCost = lastCostBearingEventCost(trace.events);
+  if (lastEventCost !== null) {
+    const reconstructedFromEvents: RunAccounting = createRunAccounting({
+      tier: trace.tier,
+      ...(trace.budget.caps ? { budget: trace.budget.caps } : {}),
+      ...(trace.budget.termination ? { termination: trace.budget.termination } : {}),
+      cost: lastEventCost,
+      events: trace.events
+    });
+    const drift = firstDifferingField(local, reconstructedFromEvents);
+    if (drift !== null) {
+      throw new DogpileError({
+        code: "invalid-configuration",
+        message: `Trace accounting mismatch at parent run ${trace.runId}: field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed}.`,
+        retryable: false,
+        detail: {
+          kind: "trace-validation",
+          reason: "trace-accounting-mismatch",
+          eventIndex: -1,
+          childRunId: trace.runId,
+          field: drift.field,
+          recorded: drift.recorded,
+          recomputed: drift.recomputed
+        }
+      });
+    }
+  }
+
+  // BUDGET-03 / D-04: parent-rollup-drift parity check. Runs BEFORE the
+  // child recurse loop so a tampered child cost surfaces with the dedicated
+  // `subReason: "parent-rollup-drift"` rather than the generic
+  // `trace-accounting-mismatch` from the recurse check.
+  //
+  // The discriminator: each sub-run-completed event stores cost in TWO places
+  // (`subResult.cost` and `subResult.accounting.cost`). They must agree
+  // field-by-field — they are the parent-side roll-up source vs the
+  // child-side accounting source. Drift indicates someone mutated one without
+  // the other. For sub-run-failed events, `partialCost` must equal the cost
+  // implied by the partial trace's last cost-bearing event.
+  //
+  // Plus: Σ children must not exceed the parent's recorded total — cost is
+  // monotonic. A child total > parent total is unambiguous tampering.
+  for (let eventIndex = 0; eventIndex < trace.events.length; eventIndex += 1) {
+    const event = trace.events[eventIndex];
+    if (event === undefined) continue;
+    if (event.type === "sub-run-completed") {
+      const childRecordedRollup = createRunAccounting({
+        tier: trace.tier,
+        cost: event.subResult.cost,
+        events: []
+      });
+      const childRecordedAccounting = event.subResult.accounting;
+      const drift = firstDifferingField(childRecordedAccounting, childRecordedRollup);
+      if (drift !== null) {
+        throw new DogpileError({
+          code: "invalid-configuration",
+          message: `Trace parent-rollup mismatch at sub-run ${event.childRunId}: field "${drift.field}" recorded ${drift.recorded} on accounting, ${drift.recomputed} on subResult.cost.`,
+          retryable: false,
+          detail: {
+            kind: "trace-validation",
+            reason: "trace-accounting-mismatch",
+            subReason: "parent-rollup-drift",
+            eventIndex,
+            childRunId: event.childRunId,
+            field: drift.field,
+            recorded: drift.recorded,
+            recomputed: drift.recomputed
+          }
+        });
+      }
+    } else if (event.type === "sub-run-failed") {
+      const partialFromTrace = lastCostBearingEventCost(event.partialTrace.events) ?? emptyCost();
+      const recordedAccounting = createRunAccounting({
+        tier: trace.tier,
+        cost: event.partialCost,
+        events: []
+      });
+      const recomputedAccounting = createRunAccounting({
+        tier: trace.tier,
+        cost: partialFromTrace,
+        events: []
+      });
+      const drift = firstDifferingField(recordedAccounting, recomputedAccounting);
+      if (drift !== null) {
+        throw new DogpileError({
+          code: "invalid-configuration",
+          message: `Trace parent-rollup mismatch at sub-run ${event.childRunId}: partialCost field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed} from partialTrace events.`,
+          retryable: false,
+          detail: {
+            kind: "trace-validation",
+            reason: "trace-accounting-mismatch",
+            subReason: "parent-rollup-drift",
+            eventIndex,
+            childRunId: event.childRunId,
+            field: drift.field,
+            recorded: drift.recorded,
+            recomputed: drift.recomputed
+          }
+        });
+      }
+    }
+  }
+
+  // Tree-level monotonicity: Σ children must be ≤ parent's recorded total
+  // across all 8 fields. Cost is non-negative and monotonic.
+  const subRunTotal = accumulateSubRunCost(trace.events);
+  const parentTotal = trace.finalOutput.cost;
+  for (const field of RECOMPUTE_FIELD_ORDER) {
+    if (field.startsWith("usage.")) continue; // usage mirrors cost; one check is enough.
+    const [, key] = field.split(".") as [string, keyof CostSummary];
+    const parentValue = parentTotal[key];
+    const childValue = subRunTotal[key];
+    if (childValue - parentValue > FLOAT_EPSILON) {
+      throw new DogpileError({
+        code: "invalid-configuration",
+        message: `Trace parent-rollup mismatch at run ${trace.runId}: field "${field}" Σ children ${childValue} exceeds parent recorded ${parentValue}.`,
+        retryable: false,
+        detail: {
+          kind: "trace-validation",
+          reason: "trace-accounting-mismatch",
+          subReason: "parent-rollup-drift",
+          eventIndex: -1,
+          childRunId: trace.runId,
+          field,
+          recorded: parentValue,
+          recomputed: childValue
+        }
+      });
+    }
+  }
+
+  // Child-level integrity: recurse into every sub-run-completed and verify
+  // its recorded `subResult.accounting` matches what the child trace recomputes.
+  for (let eventIndex = 0; eventIndex < trace.events.length; eventIndex += 1) {
+    const event = trace.events[eventIndex];
+    if (event === undefined || event.type !== "sub-run-completed") continue;
+
+    const childRecomputed = recomputeAccountingFromTrace(event.subResult.trace);
+    const childRecorded = event.subResult.accounting;
+    const drift = firstDifferingField(childRecorded, childRecomputed);
+    if (drift !== null) {
+      throw new DogpileError({
+        code: "invalid-configuration",
+        message: `Trace accounting mismatch at sub-run ${event.childRunId}: field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed}.`,
+        retryable: false,
+        detail: {
+          kind: "trace-validation",
+          reason: "trace-accounting-mismatch",
+          eventIndex,
+          childRunId: event.childRunId,
+          field: drift.field,
+          recorded: drift.recorded,
+          recomputed: drift.recomputed
+        }
+      });
+    }
+  }
+
+  return local;
+}
+
 export function canonicalizeSerializable<T>(value: T): T {
   if (Array.isArray(value)) {
     return value.map((item) => canonicalizeSerializable(item)) as T;