pi-background-tasks 1.0.4 → 1.0.6

package/src/core/fusion/budget.ts

@@ -88,7 +88,8 @@ export const FUSION_MIN_CONTEXT_WINDOW_TOKENS =
   FUSION_SAFETY_RESERVE_TOKENS;
 
 export const FUSION_BUDGET_POLICY: FusionBudgetPolicyDescriptor = {
-  id: 'fusion-budget-policy-v3',
+  id: 'fusion-budget-policy-v4',
+  route_output_reserve_strategy: 'max_fusion_contract_or_model_max',
   calibration_version: TOKEN_BUDGET_CALIBRATION_VERSION,
   calibration_table: FUSION_CALIBRATED_BYTES_PER_TOKEN,
   reserved_output_tokens: FUSION_RESERVED_OUTPUT_TOKENS,
@@ -288,14 +289,20 @@ function routeCapacity(
   role: FusionRouteCapacity['role'],
 ): FusionRouteCapacity {
   const contextWindow = requirePositiveContextWindow(model, role);
+  const reservedOutputTokens = Math.max(FUSION_RESERVED_OUTPUT_TOKENS, model.maxOutputTokens);
   const allowed = allowedInputTokens(contextWindow, {
-    reservedOutputTokens: FUSION_RESERVED_OUTPUT_TOKENS,
+    reservedOutputTokens,
     framingReserveTokens: FUSION_FRAMING_RESERVE_TOKENS,
     safetyReserveTokens: FUSION_SAFETY_RESERVE_TOKENS,
   });
   if (allowed < FUSION_MIN_CANONICAL_INPUT_TOKENS) {
+    const minimumContextWindow =
+      reservedOutputTokens +
+      FUSION_FRAMING_RESERVE_TOKENS +
+      FUSION_SAFETY_RESERVE_TOKENS +
+      FUSION_MIN_CANONICAL_INPUT_TOKENS;
     throw new FusionError(
-      `fusion ${role} route ${model.qualifiedId} has a ${String(contextWindow)}-token context window, but Fusion requires at least ${String(FUSION_MIN_CONTEXT_WINDOW_TOKENS)} tokens per configured route: ${String(FUSION_RESERVED_OUTPUT_TOKENS)} output + ${String(FUSION_FRAMING_RESERVE_TOKENS)} framing + ${String(FUSION_SAFETY_RESERVE_TOKENS)} safety + ${String(FUSION_MIN_CANONICAL_INPUT_TOKENS)} usable input. Choose a larger-context model for this slot with /fusion-models.`,
+      `fusion ${role} route ${model.qualifiedId} has a ${String(contextWindow)}-token context window, but Fusion requires at least ${String(minimumContextWindow)} tokens: ${String(reservedOutputTokens)} reserved for the route's configured maximum output + ${String(FUSION_FRAMING_RESERVE_TOKENS)} framing + ${String(FUSION_SAFETY_RESERVE_TOKENS)} safety + ${String(FUSION_MIN_CANONICAL_INPUT_TOKENS)} usable input. Choose a larger-context or lower-max-output subscription model for this slot with /fusion-models.`,
       { code: 'model_capacity_unknown', childCreated: false },
     );
   }
@@ -322,7 +329,7 @@ function routeCapacity(
     model: model.model,
     qualified_id: model.qualifiedId,
     context_window_tokens: contextWindow,
-    reserved_output_tokens: FUSION_RESERVED_OUTPUT_TOKENS,
+    reserved_output_tokens: reservedOutputTokens,
     framing_reserve_tokens: FUSION_FRAMING_RESERVE_TOKENS,
     safety_reserve_tokens: FUSION_SAFETY_RESERVE_TOKENS,
     allowed_input_tokens: allowed,

package/src/core/fusion/child-protocol.ts

@@ -1,9 +1,13 @@
 import { createHash } from 'node:crypto';
 import type { Usage } from '@earendil-works/pi-ai';
+import type { FusionClaudeCacheObservation } from './claude-cache.js';
 
 export const FUSION_CHILD_RESULT_SCHEMA_VERSION =
-  'pi-background-tasks.fusion-child-result.v2' as const;
+  'pi-background-tasks.fusion-child-result.v3' as const;
 export const FUSION_CHILD_RESULT_PREFIX = '\u001ePI_FUSION_CHILD_RESULT ';
+export const FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-child-settlement.v2' as const;
+export const FUSION_CHILD_SETTLEMENT_PREFIX = '\u001ePI_FUSION_CHILD_SETTLEMENT ';
 export const FUSION_TOOL_CALL_LOG_PATH_ENV = 'PI_FUSION_TOOL_CALL_LOG_PATH';
 export const FUSION_RESEARCH_ENABLED_ENV = 'PI_FUSION_RESEARCH_ENABLED';
 export const FUSION_SOURCE_POLICY_PATH_ENV = 'PI_FUSION_SOURCE_POLICY_PATH';
@@ -11,17 +15,47 @@ export const FUSION_SOURCE_POLICY_SHA256_ENV = 'PI_FUSION_SOURCE_POLICY_SHA256';
 export const FUSION_TOOL_CALL_SEAL_SCHEMA_VERSION =
   'pi-background-tasks.fusion-tool-call-seal.v1' as const;
 export const FUSION_TOOL_CALL_SEAL_SUFFIX = '.seal.json';
+export const FUSION_RUNTIME_GUARD_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-runtime-guard.v1' as const;
+export const FUSION_RUNTIME_GUARD_PREFIX = '\u001ePI_FUSION_RUNTIME_GUARD ';
+export const FUSION_CHILD_MAX_PROVIDER_REQUESTS = 128;
+export const FUSION_CHILD_MAX_TOOL_CALLS = 192;
+export const FUSION_CHILD_MIN_OUTPUT_RESERVE_TOKENS = 32_768;
+export const FUSION_CHILD_SAFETY_RESERVE_TOKENS = 4_096;
 
 /**
  * Aggregate ceiling on tool-result bytes a single candidate child may accumulate.
  *
- * v1 deliberately has no tool-call-count cap, so this byte budget is the only bound on
- * how much a read-only candidate can pull into its context. 8 MiB is generous for
- * targeted grep/read investigation while still preventing an unbounded read loop from
- * degrading into an opaque provider-side context failure.
+ * The byte ceiling complements the runtime provider-payload governor and tool/request
+ * count limits. It remains an independent bound on total tool material even when Pi
+ * compaction keeps each individual provider request within the route context window.
  */
 export const FUSION_CHILD_MAX_TOTAL_TOOL_RESULT_BYTES = 8 * 1024 * 1024;
 
+export type FusionRuntimeGuardCode =
+  | 'provider_request_limit'
+  | 'provider_request_budget'
+  | 'provider_payload_invalid'
+  | 'claude_cache_policy'
+  | 'tool_call_limit';
+
+export interface FusionRuntimeGuardRecord {
+  schema_version: typeof FUSION_RUNTIME_GUARD_SCHEMA_VERSION;
+  code: FusionRuntimeGuardCode;
+  provider: string;
+  model: string;
+  request_ordinal: number;
+  tool_call_count: number;
+  payload_bytes: number;
+  payload_sha256: string;
+  estimated_input_tokens: number;
+  context_window_tokens: number;
+  reserved_output_tokens: number;
+  safety_reserve_tokens: number;
+  allowed_input_tokens: number;
+  message: string;
+}
+
 export interface FusionChildTextBlockMetadata {
   utf8_bytes: number;
   sha256: string;
@@ -37,19 +71,109 @@ export interface FusionChildResultMetadata {
   text_blocks: FusionChildTextBlockMetadata[];
   text_sha256: string;
   usage: FusionChildResultUsageMetadata;
+  cache_observation: FusionClaudeCacheObservation;
+}
+
+export type FusionChildSettlementFailureReason =
+  | 'no_records'
+  | 'final_not_stop'
+  | 'invalid_non_final'
+  | 'runtime_guard'
+  | 'cache_observation';
+
+export interface FusionChildSettlementRecord {
+  schema_version: typeof FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION;
+  status: 'complete' | 'failed';
+  record_count: number;
+  records_sha256: string;
+  final_record_index: number | null;
+  final_text_sha256: string | null;
+  recovered_error_ordinals: number[];
+  failure_reason: FusionChildSettlementFailureReason | null;
 }
 
 function protocolSha256(value: string | Buffer): string {
   return createHash('sha256').update(value).digest('hex');
 }
 
-export function buildFusionChildResultMetadata(message: {
-  provider: string;
-  model: string;
-  stopReason: string;
-  content: ReadonlyArray<{ type: string; text?: string }>;
-  usage: Usage;
-}): FusionChildResultMetadata {
+export function serializeFusionChildResultRecords(
+  records: readonly FusionChildResultMetadata[],
+): Buffer {
+  return Buffer.from(
+    records.length === 0 ? '' : `${records.map((record) => JSON.stringify(record)).join('\n')}\n`,
+    'utf8',
+  );
+}
+
+function hasZeroUsage(record: FusionChildResultMetadata): boolean {
+  const usage = record.usage;
+  return (
+    usage.input === 0 &&
+    usage.output === 0 &&
+    usage.cacheRead === 0 &&
+    usage.cacheWrite === 0 &&
+    usage.totalTokens === 0 &&
+    usage.cost.input === 0 &&
+    usage.cost.output === 0 &&
+    usage.cost.cacheRead === 0 &&
+    usage.cost.cacheWrite === 0 &&
+    usage.cost.total === 0
+  );
+}
+
+export function isRecoverableFusionChildErrorRecord(record: FusionChildResultMetadata): boolean {
+  return (
+    record.stop_reason === 'error' &&
+    record.text_blocks.length === 0 &&
+    record.text_sha256 === protocolSha256(Buffer.alloc(0)) &&
+    hasZeroUsage(record)
+  );
+}
+
+export function buildFusionChildSettlement(
+  records: readonly FusionChildResultMetadata[],
+  runtimeGuardFailed = false,
+  cacheObservationFailed = false,
+): FusionChildSettlementRecord {
+  const finalRecordIndex = records.length === 0 ? null : records.length - 1;
+  const final = records.at(-1);
+  const recoveredErrorOrdinals = records.flatMap((record, ordinal) =>
+    ordinal < records.length - 1 && isRecoverableFusionChildErrorRecord(record) ? [ordinal] : [],
+  );
+  const invalidNonFinal = records.some(
+    (record, ordinal) =>
+      ordinal < records.length - 1 &&
+      record.stop_reason !== 'toolUse' &&
+      !isRecoverableFusionChildErrorRecord(record),
+  );
+  let failureReason: FusionChildSettlementFailureReason | null = null;
+  if (runtimeGuardFailed) failureReason = 'runtime_guard';
+  else if (cacheObservationFailed) failureReason = 'cache_observation';
+  else if (final === undefined) failureReason = 'no_records';
+  else if (final.stop_reason !== 'stop') failureReason = 'final_not_stop';
+  else if (invalidNonFinal) failureReason = 'invalid_non_final';
+  return {
+    schema_version: FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION,
+    status: failureReason === null ? 'complete' : 'failed',
+    record_count: records.length,
+    records_sha256: protocolSha256(serializeFusionChildResultRecords(records)),
+    final_record_index: finalRecordIndex,
+    final_text_sha256: final?.text_sha256 ?? null,
+    recovered_error_ordinals: recoveredErrorOrdinals,
+    failure_reason: failureReason,
+  };
+}
+
+export function buildFusionChildResultMetadata(
+  message: {
+    provider: string;
+    model: string;
+    stopReason: string;
+    content: ReadonlyArray<{ type: string; text?: string }>;
+    usage: Usage;
+  },
+  cacheObservation: FusionClaudeCacheObservation,
+): FusionChildResultMetadata {
   const textBlocks = message.content.flatMap((part) =>
     part.type === 'text' && typeof part.text === 'string' ? [part.text] : [],
   );
@@ -78,5 +202,6 @@ export function buildFusionChildResultMetadata(message: {
     })),
     text_sha256: protocolSha256(textBlocks.join('')),
     usage,
+    cache_observation: cacheObservation,
   };
 }

package/src/core/fusion/claude-cache.ts

@@ -0,0 +1,186 @@
+import type { JsonObject } from '../common.js';
+
+export const FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-claude-cache-observation.v1' as const;
+export const FUSION_CLAUDE_CACHE_RETENTION_ENV = 'PI_CACHE_RETENTION';
+export const FUSION_CLAUDE_CACHE_DEFAULT_RETENTION = 'long' as const;
+export const FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT = 4;
+
+export type FusionClaudeCacheRetention = 'none' | 'short' | 'long';
+export type FusionClaudeCachePolicySource =
+  | 'default'
+  | typeof FUSION_CLAUDE_CACHE_RETENTION_ENV
+  | 'not_applicable';
+
+export interface FusionClaudeCacheObservation {
+  schema_version: typeof FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION;
+  applicability: 'anthropic' | 'not_applicable';
+  source: FusionClaudeCachePolicySource;
+  requested_retention: FusionClaudeCacheRetention | null;
+  effective_retention: FusionClaudeCacheRetention | null;
+  breakpoint_count: number;
+  request_ordinal: number;
+}
+
+export interface FusionClaudeCacheNormalization {
+  payload: JsonObject;
+  observation: FusionClaudeCacheObservation;
+}
+
+function isRecord(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function unknownArray(value: unknown): unknown[] | undefined {
+  return Array.isArray(value) ? (value as unknown[]) : undefined;
+}
+
+function requireRequestOrdinal(value: number): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error('Fusion Claude cache request ordinal must be a positive safe integer');
+  }
+  return value;
+}
+
+function parseRetention(value: string): FusionClaudeCacheRetention {
+  if (value === 'none' || value === 'short' || value === 'long') return value;
+  throw new Error(
+    `${FUSION_CLAUDE_CACHE_RETENTION_ENV} must be one of none, short, or long; got ${JSON.stringify(value)}`,
+  );
+}
+
+export function resolveFusionClaudeCachePolicy(env: Readonly<NodeJS.ProcessEnv> = process.env): {
+  retention: FusionClaudeCacheRetention;
+  source: FusionClaudeCachePolicySource;
+} {
+  const configured = env[FUSION_CLAUDE_CACHE_RETENTION_ENV];
+  if (configured === undefined) {
+    return { retention: FUSION_CLAUDE_CACHE_DEFAULT_RETENTION, source: 'default' };
+  }
+  return {
+    retention: parseRetention(configured),
+    source: FUSION_CLAUDE_CACHE_RETENTION_ENV,
+  };
+}
+
+function validateCacheControl(value: unknown): JsonObject {
+  if (!isRecord(value)) {
+    throw new Error('Fusion Claude cache_control must be an object');
+  }
+  if (value['type'] !== 'ephemeral') {
+    throw new Error('Fusion Claude cache_control.type must be "ephemeral"');
+  }
+  const ttl = value['ttl'];
+  if (ttl !== undefined && ttl !== '1h' && ttl !== '5m') {
+    throw new Error('Fusion Claude cache_control.ttl must be "1h" or "5m" when present');
+  }
+  return value;
+}
+
+/**
+ * Normalize only cache breakpoints already selected by Pi's Anthropic adapter.
+ *
+ * Not creating new breakpoints is deliberate: an empty marker set may represent
+ * Pi's explicit cacheRetention="none" compaction request or a model compatibility
+ * restriction. The package may strengthen or disable native markers, but it must
+ * not override an upstream call-level opt-out that is no longer visible in the
+ * final provider payload.
+ */
+export function normalizeFusionClaudeCachePayload(input: {
+  payload: unknown;
+  requestOrdinal: number;
+  env?: Readonly<NodeJS.ProcessEnv>;
+  supportsLongCacheRetention?: boolean | undefined;
+}): FusionClaudeCacheNormalization {
+  if (!isRecord(input.payload)) {
+    throw new Error('Fusion Claude provider payload must be an object');
+  }
+  const requestOrdinal = requireRequestOrdinal(input.requestOrdinal);
+  const policy = resolveFusionClaudeCachePolicy(input.env ?? process.env);
+  const normalizedRetention: FusionClaudeCacheRetention =
+    policy.retention === 'long' && input.supportsLongCacheRetention === false
+      ? 'short'
+      : policy.retention;
+  let incomingBreakpoints = 0;
+  let outputBreakpoints = 0;
+
+  const normalizeBlock = (value: unknown): unknown => {
+    if (!isRecord(value) || !Object.hasOwn(value, 'cache_control')) return value;
+    const existing = value['cache_control'];
+    if (existing === undefined) {
+      const next = { ...value };
+      Reflect.deleteProperty(next, 'cache_control');
+      return next;
+    }
+    incomingBreakpoints += 1;
+    if (incomingBreakpoints > FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT) {
+      throw new Error(
+        `Fusion Claude payload has ${String(incomingBreakpoints)} cache_control breakpoints; Anthropic supports at most ${String(FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT)}`,
+      );
+    }
+    const control = validateCacheControl(existing);
+    const next = { ...value };
+    if (normalizedRetention === 'none') {
+      Reflect.deleteProperty(next, 'cache_control');
+      return next;
+    }
+    const normalizedControl = { ...control, type: 'ephemeral' };
+    Reflect.deleteProperty(normalizedControl, 'ttl');
+    if (normalizedRetention === 'long') Object.assign(normalizedControl, { ttl: '1h' });
+    next['cache_control'] = normalizedControl;
+    outputBreakpoints += 1;
+    return next;
+  };
+
+  const system = unknownArray(input.payload['system']);
+  const tools = unknownArray(input.payload['tools']);
+  const messages = unknownArray(input.payload['messages']);
+  const payload = {
+    ...input.payload,
+    ...(system === undefined ? {} : { system: system.map(normalizeBlock) }),
+    ...(tools === undefined ? {} : { tools: tools.map(normalizeBlock) }),
+    ...(messages === undefined
+      ? {}
+      : {
+          messages: messages.map((message) => {
+            if (!isRecord(message)) return message;
+            const content = unknownArray(message['content']);
+            return content === undefined
+              ? message
+              : { ...message, content: content.map(normalizeBlock) };
+          }),
+        }),
+  };
+  if (outputBreakpoints > FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT) {
+    throw new Error(
+      `Fusion Claude payload produced ${String(outputBreakpoints)} cache_control breakpoints; Anthropic supports at most ${String(FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT)}`,
+    );
+  }
+
+  return {
+    payload,
+    observation: {
+      schema_version: FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION,
+      applicability: 'anthropic',
+      source: policy.source,
+      requested_retention: policy.retention,
+      effective_retention: outputBreakpoints === 0 ? 'none' : normalizedRetention,
+      breakpoint_count: outputBreakpoints,
+      request_ordinal: requestOrdinal,
+    },
+  };
+}
+
+export function nonAnthropicFusionCacheObservation(
+  requestOrdinal: number,
+): FusionClaudeCacheObservation {
+  return {
+    schema_version: FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION,
+    applicability: 'not_applicable',
+    source: 'not_applicable',
+    requested_retention: null,
+    effective_retention: null,
+    breakpoint_count: 0,
+    request_ordinal: requireRequestOrdinal(requestOrdinal),
+  };
+}

package/src/core/fusion/config.ts

@@ -158,6 +158,17 @@ function requireContextWindow(model: Model<Api>, label: string): number {
   return Math.floor(value);
 }
 
+function requireMaxOutputTokens(model: Model<Api>, label: string): number {
+  const value = model.maxTokens;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new FusionError(`${label} has no positive maximum output token capacity`, {
+      code: 'model_unavailable',
+      childCreated: false,
+    });
+  }
+  return Math.floor(value);
+}
+
 function modelIndex(models: readonly Model<Api>[]): Map<string, Model<Api>> {
   const out = new Map<string, Model<Api>>();
   for (const model of models) out.set(qualifiedModelKey(model), model);
@@ -305,6 +316,7 @@ function resolveSelection(
       qualifiedId,
       thinkingLevel,
       contextWindow: requireContextWindow(available, slotLabel),
+      maxOutputTokens: requireMaxOutputTokens(available, slotLabel),
     };
   }
   const model = availableByKey.get(selection);
@@ -323,6 +335,7 @@ function resolveSelection(
     qualifiedId: selection,
     thinkingLevel,
     contextWindow: requireContextWindow(model, slotLabel),
+    maxOutputTokens: requireMaxOutputTokens(model, slotLabel),
   };
 }