@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/background-tasks/src/delegate/budget.ts

@@ -1,415 +0,0 @@
-import {
-  TOKEN_BUDGET_CALIBRATION_VERSION,
-  TOKEN_BUDGET_FAMILY_CALIBRATIONS,
-  TOKEN_BUDGET_RATE_SCALE,
-  estimateInputTokens,
-  knownTextSegment,
-  resolveTokenBudgetFamily,
-  utf8ByteClassBreakdown,
-  allowedInputTokens,
-  isUsableContextWindow,
-  type EstimateInputTokensResult,
-  type TokenBudgetByteClassBreakdown,
-  type TokenBudgetFamily,
-  type TokenBudgetFamilyCalibration,
-  type TokenBudgetRateSource,
-} from '../context-token-budget.js';
-import {
-  DELEGATE_BUDGET_PLAN_SCHEMA_VERSION,
-  DelegateError,
-  type DelegateLimits,
-  type DelegatePinnedRoute,
-} from './types.js';
-
-/**
- * Delegate budgeting.
- *
- * A delegate child is a multi-turn, tool-using agent, so its budget has two
- * distinct phases rather than Fusion's single-shot stage forecast:
- *
- * 1. Launch admission checks the frozen seed, framing, and child system prompt
- *    with the same backed family calibration used by Fusion for large prompts.
- * 2. A separate provable 1 B/token forecast sizes the transcript-growth runway
- *    used for explicit tool-result spilling.
- * 3. Runtime measurements are advisory. Package-owned growth is controlled
- *    before transcript entry; Pi and the provider own live context handling.
- *
- * Nothing here clips, substitutes, or silently reduces content. Tool bytes that
- * do not fit the retained-growth runway are preserved as hashed spill artifacts.
- */
-
-/** Output tokens reserved so the child can always finish an answer. */
-export const DELEGATE_RESERVED_OUTPUT_TOKENS = 16_384;
-/** Provider/tool-schema framing the package does not directly control. */
-export const DELEGATE_FRAMING_RESERVE_TOKENS = 8_192;
-export const DELEGATE_SAFETY_RESERVE_TOKENS = 4_096;
-/** Below this, a route cannot hold a useful seed plus real investigation. */
-export const DELEGATE_MIN_USABLE_INPUT_TOKENS = 8_192;
-export const DELEGATE_MIN_CONTEXT_WINDOW_TOKENS =
-  DELEGATE_MIN_USABLE_INPUT_TOKENS +
-  DELEGATE_RESERVED_OUTPUT_TOKENS +
-  DELEGATE_FRAMING_RESERVE_TOKENS +
-  DELEGATE_SAFETY_RESERVE_TOKENS;
-
-export const DELEGATE_DEFAULT_MAX_TURNS = 24;
-export const DELEGATE_DEFAULT_MAX_TOOL_CALLS = 120;
-export const DELEGATE_DEFAULT_TIMEOUT_SECONDS = 1200;
-export const DELEGATE_MAX_TOOL_RESULT_BYTES = 64 * 1024;
-export const DELEGATE_MAX_TOTAL_TOOL_OUTPUT_BYTES = 64 * 1024 * 1024;
-export const DELEGATE_MAX_ANSWER_BYTES = 4 * 1024 * 1024;
-/** Input runway held back for a final no-tool answer after investigation. */
-export const DELEGATE_FINALIZATION_INPUT_RESERVE_TOKENS = 32 * 1024;
-/** Remaining retained-growth runway at which the child disables tools. */
-export const DELEGATE_FINALIZATION_TRIGGER_TOKENS = 8 * 1024;
-/** Answers at or under this serialize inline; larger ones degrade explicitly. */
-export const DELEGATE_INLINE_ANSWER_BYTES = 48 * 1024;
-
-export const DELEGATE_BUDGET_POLICY_ID = 'delegate-budget-policy-v3';
-
-export interface DelegateBudgetPolicyDescriptor {
-  id: typeof DELEGATE_BUDGET_POLICY_ID;
-  calibration_version: string;
-  calibration_table: Readonly<Record<TokenBudgetFamily, TokenBudgetFamilyCalibration>>;
-  reserved_output_tokens: number;
-  framing_reserve_tokens: number;
-  safety_reserve_tokens: number;
-  min_usable_input_tokens: number;
-  inline_answer_bytes: number;
-  finalization_input_reserve_tokens: number;
-  finalization_trigger_tokens: number;
-  launch_estimator_scope: 'calibrated_large_prompt';
-  retained_growth_estimator_scope: 'provable_1_byte_per_token';
-  live_provider_context_owner: 'pi_and_provider';
-}
-
-export const DELEGATE_BUDGET_POLICY: DelegateBudgetPolicyDescriptor = {
-  id: DELEGATE_BUDGET_POLICY_ID,
-  calibration_version: TOKEN_BUDGET_CALIBRATION_VERSION,
-  calibration_table: TOKEN_BUDGET_FAMILY_CALIBRATIONS,
-  reserved_output_tokens: DELEGATE_RESERVED_OUTPUT_TOKENS,
-  framing_reserve_tokens: DELEGATE_FRAMING_RESERVE_TOKENS,
-  safety_reserve_tokens: DELEGATE_SAFETY_RESERVE_TOKENS,
-  min_usable_input_tokens: DELEGATE_MIN_USABLE_INPUT_TOKENS,
-  inline_answer_bytes: DELEGATE_INLINE_ANSWER_BYTES,
-  finalization_input_reserve_tokens: DELEGATE_FINALIZATION_INPUT_RESERVE_TOKENS,
-  finalization_trigger_tokens: DELEGATE_FINALIZATION_TRIGGER_TOKENS,
-  launch_estimator_scope: 'calibrated_large_prompt',
-  retained_growth_estimator_scope: 'provable_1_byte_per_token',
-  live_provider_context_owner: 'pi_and_provider',
-};
-
-export interface DelegateAdmissionPlanV1 {
-  schema_version: typeof DELEGATE_BUDGET_PLAN_SCHEMA_VERSION;
-  policy: DelegateBudgetPolicyDescriptor;
-  route: {
-    provider: string;
-    model: string;
-    qualified_id: string;
-    context_window_tokens: number;
-    allowed_input_tokens: number;
-    family: TokenBudgetFamily;
-    backed: boolean;
-    rate_source: TokenBudgetRateSource;
-    byte_capacity_utf8_bytes: number;
-  };
-  child_prompt_utf8_bytes: number;
-  child_prompt_multibyte_utf8_bytes: number;
-  system_prompt_utf8_bytes: number;
-  system_prompt_multibyte_utf8_bytes: number;
-  launch_utf8_bytes: number;
-  launch_input_tokens_upper_bound: number;
-  conservative_launch_input_tokens: number;
-  conservative_launch_fits: boolean;
-  signed_headroom_tokens: number;
-  utilization_basis_points: number;
-  retained_growth_budget_tokens: number;
-  finalization_input_reserve_tokens: number;
-  byte_class_breakdown: TokenBudgetByteClassBreakdown;
-  dominant_byte_class: EstimateInputTokensResult['rateSource']['dominant_byte_class'];
-  estimate: EstimateInputTokensResult;
-  conservative_estimate: EstimateInputTokensResult;
-  fits: boolean;
-  limits: DelegateLimits;
-}
-
-function utilizationBasisPoints(tokens: number, allowed: number): number {
-  if (!Number.isSafeInteger(tokens) || tokens < 0) {
-    throw new TypeError('tokens must be a non-negative safe integer');
-  }
-  if (!Number.isSafeInteger(allowed) || allowed <= 0) {
-    throw new TypeError('allowed must be a positive safe integer');
-  }
-  return Math.floor(((tokens * 10_000) + allowed - 1) / allowed);
-}
-
-function routeFamily(route: DelegatePinnedRoute): ReturnType<typeof resolveTokenBudgetFamily> {
-  return resolveTokenBudgetFamily({ provider: route.provider, model: route.model });
-}
-
-/**
- * Usable input tokens for a pinned route.
- *
- * A route with an unknown, non-integral, or non-positive context window is a
- * loud `route_capacity_unknown` refusal. The delegate never assumes a default
- * window, because assuming one is how oversized prompts reach a provider.
- */
-export function delegateAllowedInputTokens(route: DelegatePinnedRoute): number {
-  if (!isUsableContextWindow(route.context_window_tokens)) {
-    throw new DelegateError(
-      `bg_delegate route ${route.qualified_id} reports no usable context-window capacity`,
-      {
-        code: 'route_capacity_unknown',
-        childCreated: false,
-        remediation: [
-          'Pin an explicit route whose model catalogue entry declares a context window.',
-          'No child was created and no capacity was assumed.',
-        ],
-      },
-    );
-  }
-  const allowed = allowedInputTokens(route.context_window_tokens, {
-    reservedOutputTokens: DELEGATE_RESERVED_OUTPUT_TOKENS,
-    framingReserveTokens: DELEGATE_FRAMING_RESERVE_TOKENS,
-    safetyReserveTokens: DELEGATE_SAFETY_RESERVE_TOKENS,
-  });
-  if (allowed < DELEGATE_MIN_USABLE_INPUT_TOKENS) {
-    throw new DelegateError(
-      `bg_delegate route ${route.qualified_id} has a ${String(route.context_window_tokens)}-token context window, but a delegate child requires at least ${String(DELEGATE_MIN_CONTEXT_WINDOW_TOKENS)} tokens: ${String(DELEGATE_RESERVED_OUTPUT_TOKENS)} output + ${String(DELEGATE_FRAMING_RESERVE_TOKENS)} framing + ${String(DELEGATE_SAFETY_RESERVE_TOKENS)} safety + ${String(DELEGATE_MIN_USABLE_INPUT_TOKENS)} usable input`,
-      {
-        code: 'route_capacity_unknown',
-        childCreated: false,
-        remediation: ['Pin a larger-context route for this delegate.'],
-      },
-    );
-  }
-  return allowed;
-}
-
-export interface DelegateAdmissionInput {
-  route: DelegatePinnedRoute;
-  childPrompt: string;
-  childSystemPrompt: string;
-  limits: DelegateLimits;
-}
-
-/** Deterministic launch-admission forecast. Pure; creates nothing. */
-export function planDelegateAdmission(input: DelegateAdmissionInput): DelegateAdmissionPlanV1 {
-  const allowed = delegateAllowedInputTokens(input.route);
-  const family = routeFamily(input.route);
-  const childPrompt = utf8ByteClassBreakdown(input.childPrompt);
-  const system = utf8ByteClassBreakdown(input.childSystemPrompt);
-  const segments = [knownTextSegment(input.childPrompt), knownTextSegment(input.childSystemPrompt)];
-  const estimate = estimateInputTokens({
-    family: family.family,
-    calibrationBacked: family.backed,
-    familyResolution: family.resolution,
-    allowedInputTokens: allowed,
-    scope: 'delegate_launch',
-    segments,
-  });
-  const conservativeEstimate = estimateInputTokens({
-    family: family.family,
-    calibrationBacked: family.backed,
-    familyResolution: family.resolution,
-    allowedInputTokens: allowed,
-    scope: 'conservative',
-    segments,
-  });
-  // `conservativeEstimate.tokens` intentionally uses the shared estimator's
-  // calibrated multibyte diagnostic rate. The counter-forecast published as
-  // "provable" must instead use that estimator's explicit 1 B/token ceiling
-  // for multibyte bytes as well as normal/dense bytes.
-  const provableConservativeLaunchTokens =
-    conservativeEstimate.advisory.input_tokens_if_multibyte_used_provable_ceiling;
-  const byteCapacity = Math.floor(
-    (allowed * estimate.rateSource.effective_rate_bytes_per_token_x100) / TOKEN_BUDGET_RATE_SCALE,
-  );
-  const launchBytes = childPrompt.bytes + system.bytes;
-  const retainedGrowthBudget = Math.max(
-    0,
-    allowed - estimate.tokens - DELEGATE_FINALIZATION_INPUT_RESERVE_TOKENS,
-  );
-  return {
-    schema_version: DELEGATE_BUDGET_PLAN_SCHEMA_VERSION,
-    policy: DELEGATE_BUDGET_POLICY,
-    route: {
-      provider: input.route.provider,
-      model: input.route.model,
-      qualified_id: input.route.qualified_id,
-      context_window_tokens: input.route.context_window_tokens,
-      allowed_input_tokens: allowed,
-      family: family.family,
-      backed: estimate.rateSource.backed,
-      rate_source: estimate.rateSource,
-      byte_capacity_utf8_bytes: byteCapacity,
-    },
-    child_prompt_utf8_bytes: childPrompt.bytes,
-    child_prompt_multibyte_utf8_bytes: childPrompt.multibyteBytes,
-    system_prompt_utf8_bytes: system.bytes,
-    system_prompt_multibyte_utf8_bytes: system.multibyteBytes,
-    launch_utf8_bytes: launchBytes,
-    launch_input_tokens_upper_bound: estimate.tokens,
-    conservative_launch_input_tokens: provableConservativeLaunchTokens,
-    conservative_launch_fits: provableConservativeLaunchTokens <= allowed,
-    signed_headroom_tokens: allowed - estimate.tokens,
-    utilization_basis_points: utilizationBasisPoints(estimate.tokens, allowed),
-    retained_growth_budget_tokens: retainedGrowthBudget,
-    finalization_input_reserve_tokens: DELEGATE_FINALIZATION_INPUT_RESERVE_TOKENS,
-    byte_class_breakdown: estimate.byte_class_breakdown,
-    dominant_byte_class: estimate.rateSource.dominant_byte_class,
-    estimate,
-    conservative_estimate: conservativeEstimate,
-    fits: estimate.tokens <= allowed,
-    limits: input.limits,
-  };
-}
-
-function rateWarningText(rateSource: TokenBudgetRateSource, qualifiedId: string): string {
-  if (rateSource.warning === null) return '';
-  return ` Estimator warning for ${qualifiedId}: ${rateSource.warning}.`;
-}
-
-function requiredByteReduction(plan: DelegateAdmissionPlanV1): number {
-  const variableTokens =
-    plan.route.allowed_input_tokens - plan.route.rate_source.affine_f_tokens;
-  const maximumBytes = variableTokens <= 0
-    ? 0
-    : Math.floor(
-        (variableTokens * plan.route.rate_source.effective_rate_bytes_per_token_x100) /
-          TOKEN_BUDGET_RATE_SCALE,
-      );
-  return Math.max(0, plan.launch_utf8_bytes - maximumBytes);
-}
-
-/**
- * Enforce the admission plan.
- *
- * Called before the child process, the child session, and the artifact
- * directory exist, so a refusal leaves zero children and zero artifacts.
- */
-export function assertDelegateAdmission(plan: DelegateAdmissionPlanV1): void {
-  if (plan.fits) return;
-  const overage = plan.launch_input_tokens_upper_bound - plan.route.allowed_input_tokens;
-  throw new DelegateError(
-    `bg_delegate child prompt does not fit the pinned route before launch. Route ${plan.route.qualified_id} allows ${String(plan.route.allowed_input_tokens)} input tokens; the exact child prompt plus child system prompt measure ${String(plan.launch_utf8_bytes)} UTF-8 bytes (<= ${String(plan.launch_input_tokens_upper_bound)} input tokens), over by ${String(overage)} tokens. Estimator family ${plan.route.family}, source ${plan.route.rate_source.source}, backed=${String(plan.route.rate_source.backed)}, dominant_byte_class=${plan.dominant_byte_class}, rate ${String(plan.route.rate_source.effective_rate_bytes_per_token_x100)}/100 B/tok + ${String(plan.route.rate_source.affine_f_tokens)} tokens.${rateWarningText(plan.route.rate_source, plan.route.qualified_id)} Required reduction is at least ${String(requiredByteReduction(plan))} UTF-8 bytes. No child process, child session, or artifact was created. Nothing was clipped, dropped, or substituted.`,
-    {
-      code: 'seed_budget_exceeded',
-      childCreated: false,
-      budget: {
-        measurement_kind: 'launch_admission',
-        measured_utf8_bytes: plan.launch_utf8_bytes,
-        measured_input_tokens_upper_bound: plan.launch_input_tokens_upper_bound,
-        allowed_input_tokens: plan.route.allowed_input_tokens,
-        rate_source: plan.route.rate_source,
-        backed: plan.route.rate_source.backed,
-        dominant_byte_class: plan.dominant_byte_class,
-        byte_class_breakdown: plan.byte_class_breakdown,
-      },
-      remediation: [
-        'Pin a larger-context route with the route argument.',
-        'Delegate earlier in the session, or start a fresh conversation, so less history is projected.',
-        'Restate only the required findings as visible conversation text; omitted tool payloads are not what is large here.',
-      ],
-    },
-  );
-}
-
-export interface DelegateRuntimeMeasurement {
-  /** Complete retained input for the next model call, in UTF-8 bytes. */
-  retainedInputBytes: number;
-  retainedInputMultibyteBytes: number;
-  retainedInputDenseBytes: number;
-}
-
-export interface DelegateGovernorVerdict {
-  withinBudget: boolean;
-  measuredTokens: number;
-  allowedTokens: number;
-  overageTokens: number;
-  byteClassBreakdown: TokenBudgetByteClassBreakdown;
-  dominantByteClass: EstimateInputTokensResult['rateSource']['dominant_byte_class'];
-  backed: boolean;
-  rateSource: TokenBudgetRateSource;
-}
-
-/**
- * Advisory runtime measurement for one prospective model call.
- *
- * This deliberately uses the calibrated large-prompt policy and never decides
- * whether transport may occur. Fusion's BUG-185 proved that a package-local
- * estimator must not reject a live provider payload by subtracting hypothetical
- * output. The delegate child uses this result for evidence and graceful
- * finalization while proactive spilling controls package-owned growth.
- */
-export function evaluateDelegateRuntimeBudget(
-  measurement: DelegateRuntimeMeasurement,
-  allowedTokens: number,
-  route: { provider: string; model: string },
-): DelegateGovernorVerdict {
-  const family = resolveTokenBudgetFamily(route);
-  const estimate = estimateInputTokens({
-    family: family.family,
-    calibrationBacked: family.backed,
-    familyResolution: family.resolution,
-    allowedInputTokens: allowedTokens,
-    scope: 'delegate_launch',
-    segments: [
-      {
-        kind: 'known_text',
-        bytes: measurement.retainedInputBytes,
-        multibyteBytes: measurement.retainedInputMultibyteBytes,
-        denseBytes: measurement.retainedInputDenseBytes,
-      },
-    ],
-  });
-  return {
-    withinBudget: estimate.tokens <= allowedTokens,
-    measuredTokens: estimate.tokens,
-    allowedTokens,
-    overageTokens: Math.max(0, estimate.tokens - allowedTokens),
-    byteClassBreakdown: estimate.byte_class_breakdown,
-    dominantByteClass: estimate.rateSource.dominant_byte_class,
-    backed: estimate.rateSource.backed,
-    rateSource: estimate.rateSource,
-  };
-}
-
-export interface DelegateLimitOverrides {
-  maxTurns?: number | undefined;
-  maxToolCalls?: number | undefined;
-  timeoutSeconds?: number | undefined;
-}
-
-function positiveInteger(value: number | undefined, fallback: number, label: string): number {
-  if (value === undefined) return fallback;
-  if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
-    throw new DelegateError(`bg_delegate ${label} must be a positive integer`, {
-      code: 'invalid_arguments',
-      childCreated: false,
-    });
-  }
-  return value;
-}
-
-export function resolveDelegateLimits(
-  route: DelegatePinnedRoute,
-  overrides: DelegateLimitOverrides = {},
-): DelegateLimits {
-  return {
-    max_turns: positiveInteger(overrides.maxTurns, DELEGATE_DEFAULT_MAX_TURNS, 'maxTurns'),
-    max_tool_calls: positiveInteger(
-      overrides.maxToolCalls,
-      DELEGATE_DEFAULT_MAX_TOOL_CALLS,
-      'maxToolCalls',
-    ),
-    timeout_seconds: positiveInteger(
-      overrides.timeoutSeconds,
-      DELEGATE_DEFAULT_TIMEOUT_SECONDS,
-      'timeoutSeconds',
-    ),
-    max_tool_result_bytes: DELEGATE_MAX_TOOL_RESULT_BYTES,
-    max_total_tool_output_bytes: DELEGATE_MAX_TOTAL_TOOL_OUTPUT_BYTES,
-    max_answer_bytes: DELEGATE_MAX_ANSWER_BYTES,
-    allowed_input_tokens: delegateAllowedInputTokens(route),
-  };
-}

package/packages/background-tasks/src/delegate/hook-contract-evidence.json

@@ -1,18 +0,0 @@
-{
-  "schema_version": "pi-background-tasks.delegate-hook-contract.v1",
-  "contract_id": "context-measure-abort-v1+tool-result-spill-v1",
-  "guarantees": {
-    "context_fires_before_every_model_call": true,
-    "context_result_messages_reach_provider": true,
-    "context_abort_blocks_provider_call": true,
-    "context_abort_skips_stream_invocation": false,
-    "context_abort_terminates_run": true,
-    "context_throw_blocks_provider_call": false,
-    "context_throw_isolated_to_throwing_handler": true,
-    "tool_result_fires_before_transcript_entry": true,
-    "tool_result_replacement_reaches_provider": true,
-    "tool_result_replacement_preserves_identity": true,
-    "tool_result_chains_in_load_order": true,
-    "handlers_run_in_extension_load_order": true
-  }
-}

package/packages/background-tasks/src/delegate/hook-contract.ts

@@ -1,154 +0,0 @@
-/**
- * Pi extension-hook contract required by the `bg_delegate` child-side guard.
- *
- * The guard installed inside a delegate child depends on runtime behaviour of
- * Pi's `context` and `tool_result` hooks. That behaviour is proven by the
- * `tests/scripted-provider/pi-hook-contract.test.ts` characterisation gate,
- * which drives a real Pi agent loop and writes the observed guarantees to
- * `tests/scripted-provider/pi-hook-contract-evidence.json`.
- *
- * Nothing here infers behaviour from type declarations. A guarantee is either
- * observed by that gate or the delegate launch refuses to spawn a child.
- */
-
-export const DELEGATE_HOOK_CONTRACT_SCHEMA_VERSION =
-  'pi-background-tasks.delegate-hook-contract.v1' as const;
-
-/**
- * Identifier for the exact guard mechanism the child installs.
- *
- * `context-measure-abort-v1`: measure the outgoing message set inside the
- * `context` hook and, when it would exceed the pinned route window, call
- * `ctx.abort()` so the request is never issued, then report a typed failure over
- * the child result channel.
- *
- * Empirically established across the supported Pi lines by the characterisation
- * and exact-version compatibility gates: Pi 0.81.1-0.83.0 invoke the provider
- * entry point with an already-aborted `AbortSignal`, while Pi 0.84.0 propagates
- * that signal through auth resolution and skips the entry point. No network
- * request is issued in either mode, and the run terminates. Throwing from a
- * `context` handler is NOT a barrier at all: Pi catches the exception, reports
- * it as an extension error, and continues dispatch. The guard therefore uses
- * abort, never a throw, and additionally suppresses the oversized content itself
- * so a non-conforming provider cannot transmit it.
- *
- * `tool-result-spill-v1`: replace an oversized `tool_result` payload with an
- * explicit hash-accounted receipt before it enters the transcript.
- */
-export const DELEGATE_HOOK_CONTRACT_ID = 'context-measure-abort-v1+tool-result-spill-v1' as const;
-
-export const DELEGATE_HOOK_GUARANTEE_NAMES = [
-  'context_fires_before_every_model_call',
-  'context_result_messages_reach_provider',
-  'context_abort_blocks_provider_call',
-  'context_abort_skips_stream_invocation',
-  'context_abort_terminates_run',
-  'context_throw_blocks_provider_call',
-  'context_throw_isolated_to_throwing_handler',
-  'tool_result_fires_before_transcript_entry',
-  'tool_result_replacement_reaches_provider',
-  'tool_result_replacement_preserves_identity',
-  'tool_result_chains_in_load_order',
-  'handlers_run_in_extension_load_order',
-] as const;
-
-export type DelegateHookGuaranteeName = (typeof DELEGATE_HOOK_GUARANTEE_NAMES)[number];
-
-export type DelegateHookGuarantees = Readonly<Record<DelegateHookGuaranteeName, boolean>>;
-
-export interface DelegateHookContractEvidence {
-  schema_version: typeof DELEGATE_HOOK_CONTRACT_SCHEMA_VERSION;
-  contract_id: typeof DELEGATE_HOOK_CONTRACT_ID;
-  guarantees: DelegateHookGuarantees;
-}
-
-/**
- * Guarantees the child guard actually depends on.
- *
- * `context_throw_blocks_provider_call` and
- * `context_abort_skips_stream_invocation` are deliberately absent. Throws do
- * not block dispatch, and skipping the stream entry point is not shared by every
- * supported Pi line. The guard needs neither behavior: it aborts the run AND
- * removes the oversized content from the outgoing message set, so the request
- * cannot be issued and could not carry the content even if it were.
- */
-export const DELEGATE_REQUIRED_HOOK_GUARANTEES: readonly DelegateHookGuaranteeName[] = [
-  'context_fires_before_every_model_call',
-  'context_result_messages_reach_provider',
-  'context_abort_blocks_provider_call',
-  'context_abort_terminates_run',
-  'context_throw_isolated_to_throwing_handler',
-  'tool_result_fires_before_transcript_entry',
-  'tool_result_replacement_reaches_provider',
-  'tool_result_replacement_preserves_identity',
-  'tool_result_chains_in_load_order',
-  'handlers_run_in_extension_load_order',
-];
-
-export interface DelegateHookContractVerdict {
-  supported: boolean;
-  missing: readonly DelegateHookGuaranteeName[];
-}
-
-export function evaluateDelegateHookContract(
-  evidence: DelegateHookContractEvidence,
-): DelegateHookContractVerdict {
-  const missing = DELEGATE_REQUIRED_HOOK_GUARANTEES.filter(
-    (guarantee) => evidence.guarantees[guarantee] !== true,
-  );
-  return { supported: missing.length === 0, missing };
-}
-
-function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/** Strict parse. A malformed or partial evidence file is a loud failure, never a default-allow. */
-export function parseDelegateHookContractEvidence(value: unknown): DelegateHookContractEvidence {
-  if (!isRecord(value)) throw new Error('delegate hook-contract evidence must be an object');
-  if (value['schema_version'] !== DELEGATE_HOOK_CONTRACT_SCHEMA_VERSION) {
-    throw new Error(
-      `delegate hook-contract evidence schema_version must be ${DELEGATE_HOOK_CONTRACT_SCHEMA_VERSION}`,
-    );
-  }
-  if (value['contract_id'] !== DELEGATE_HOOK_CONTRACT_ID) {
-    throw new Error(
-      `delegate hook-contract evidence contract_id must be ${DELEGATE_HOOK_CONTRACT_ID}`,
-    );
-  }
-  const raw = value['guarantees'];
-  if (!isRecord(raw)) throw new Error('delegate hook-contract evidence guarantees must be an object');
-  const keys = Object.keys(raw).sort();
-  const expected = [...DELEGATE_HOOK_GUARANTEE_NAMES].sort();
-  if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
-    throw new Error(
-      `delegate hook-contract evidence guarantees keys mismatch: expected ${expected.join(', ')}`,
-    );
-  }
-  const flag = (name: DelegateHookGuaranteeName): boolean => {
-    const observed = raw[name];
-    if (typeof observed !== 'boolean') {
-      throw new Error(`delegate hook-contract evidence guarantee ${name} must be a boolean`);
-    }
-    return observed;
-  };
-  const guarantees: DelegateHookGuarantees = {
-    context_fires_before_every_model_call: flag('context_fires_before_every_model_call'),
-    context_result_messages_reach_provider: flag('context_result_messages_reach_provider'),
-    context_abort_blocks_provider_call: flag('context_abort_blocks_provider_call'),
-    context_abort_skips_stream_invocation: flag('context_abort_skips_stream_invocation'),
-    context_abort_terminates_run: flag('context_abort_terminates_run'),
-    context_throw_blocks_provider_call: flag('context_throw_blocks_provider_call'),
-    context_throw_isolated_to_throwing_handler: flag('context_throw_isolated_to_throwing_handler'),
-    tool_result_fires_before_transcript_entry: flag('tool_result_fires_before_transcript_entry'),
-    tool_result_replacement_reaches_provider: flag('tool_result_replacement_reaches_provider'),
-    tool_result_replacement_preserves_identity: flag('tool_result_replacement_preserves_identity'),
-    tool_result_chains_in_load_order: flag('tool_result_chains_in_load_order'),
-    handlers_run_in_extension_load_order: flag('handlers_run_in_extension_load_order'),
-  };
-  return {
-    schema_version: DELEGATE_HOOK_CONTRACT_SCHEMA_VERSION,
-    contract_id: DELEGATE_HOOK_CONTRACT_ID,
-    guarantees,
-  };
-}