@nifrajs/core 2.11.0 → 2.12.0

package/src/tool-contract.ts

@@ -0,0 +1,896 @@
+/**
+ * Typed tool contracts.
+ *
+ * A tool is an owned effect seam for an agent. The contract carries the data shape, authority,
+ * approval, idempotency, dimensionless cost, and sensitivity metadata that every adapter needs.
+ * Adapters call {@link executeTool}; they do not reimplement admission.
+ *
+ * This module is deliberately token-only in its evidence and idempotency stores. It never persists
+ * tool arguments, results, request bodies, or business values.
+ */
+
+import type { RequestBudget } from "./budget.ts"
+import {
+  defineExecutionPolicy,
+  type ExecutionPolicy,
+  type ExecutionPolicyAdapter,
+} from "./execution-policy.ts"
+import {
+  type IdempotencyScope,
+  validIdempotencyKey,
+  validIdempotencyNamespace,
+} from "./idempotency.ts"
+import { validCapabilityId } from "./internal/capability-runtime.ts"
+import {
+  createRequestLedger,
+  type EffectCost,
+  normalizeEffectMetadata,
+  type RequestLedger,
+  type SealedEffectLedger,
+} from "./ledger.ts"
+import { reflectSchema } from "./reflection.ts"
+import {
+  type InferOutput,
+  type StandardIssue,
+  type StandardSchemaV1,
+  validateStandard,
+} from "./schema/standard.ts"
+import { assertByteLimit, readBoundedBytes } from "./server/body.ts"
+import { type ProtoPoisoning, parseJsonGuarded } from "./server/proto-guard.ts"
+
+const TOOL_NAME = /^[a-z][a-z0-9._-]{0,63}$/
+const MAX_EVIDENCE = 64
+const DEFAULT_NAMESPACE = "tool"
+const DEFAULT_CAPABILITY = "tool.execute"
+
+export type ToolSensitivity = "public" | "internal" | "sensitive" | "secret"
+
+export type ToolApprovalPolicy =
+  | { readonly kind: "none" }
+  | { readonly kind: "required" }
+  | { readonly kind: "threshold"; readonly level: number }
+
+export type ToolApproval =
+  | { readonly granted: true; readonly level?: number }
+  | { readonly granted: false; readonly reason?: string }
+
+export interface ToolAnnotations {
+  readonly title?: string
+  readonly readOnlyHint?: boolean
+  readonly destructiveHint?: boolean
+  readonly idempotentHint?: boolean
+  readonly openWorldHint?: boolean
+}
+
+export interface ToolIdempotencyPolicy<Input = unknown> {
+  readonly scope: Exclude<IdempotencyScope, "none">
+  /** Return an opaque bounded key. The key must not contain a request body or secret. */
+  readonly key: (input: Input) => string | PromiseLike<string>
+}
+
+export interface ToolContractOptions<
+  Input,
+  Output,
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+> {
+  readonly name: string
+  readonly description: string
+  readonly input: InputSchema
+  readonly output: OutputSchema
+  readonly capability?: string
+  readonly approval?: ToolApprovalPolicy
+  readonly idempotency?: ToolIdempotencyPolicy<Input>
+  /** Dimensionless counters such as `{ calls: 1, ms: 20 }`; never prices. */
+  readonly cost?: EffectCost
+  readonly sensitivity?: ToolSensitivity
+  readonly annotations?: ToolAnnotations
+  readonly policy?: ExecutionPolicy
+  readonly execute: (input: Input, context: ToolExecutionContext) => Output | PromiseLike<Output>
+}
+
+export interface ToolContract<Input = unknown, Output = unknown> {
+  readonly name: string
+  readonly description: string
+  readonly input: StandardSchemaV1<unknown, Input>
+  readonly output: StandardSchemaV1<unknown, Output>
+  readonly capability: string
+  readonly approval: ToolApprovalPolicy
+  readonly idempotency?: ToolIdempotencyPolicy<Input>
+  readonly cost?: EffectCost
+  readonly sensitivity: ToolSensitivity
+  readonly annotations: ToolAnnotations
+  readonly policy?: ExecutionPolicy
+  readonly execute: (input: Input, context: ToolExecutionContext) => Output | PromiseLike<Output>
+}
+
+export interface ToolExecutionContext {
+  readonly effectId: string
+  readonly signal: AbortSignal
+  /** Wall-clock budget shared with the parent request, when an agent supplies one. */
+  readonly deadline?: RequestBudget
+  readonly dryRun: boolean
+  readonly policy?: ExecutionPolicy
+}
+
+export interface ToolBudget {
+  readonly consume: (cost: EffectCost | undefined) => boolean
+  readonly snapshot: () => EffectCost
+}
+
+export interface CreateToolBudgetOptions {
+  readonly limits: EffectCost
+  readonly initial?: EffectCost
+}
+
+export function createToolBudget(options: CreateToolBudgetOptions): ToolBudget {
+  const limits = normalizeCost(options.limits, "tool budget limits")
+  const spent = normalizeCost(options.initial ?? {}, "tool budget initial")
+  for (const [axis, value] of Object.entries(spent)) {
+    if ((limits[axis] ?? 0) < value) {
+      throw new RangeError(`tool budget: initial ${axis} exceeds its limit`)
+    }
+  }
+  return {
+    consume(cost) {
+      const next = normalizeCost(cost ?? {}, "tool cost")
+      for (const [axis, value] of Object.entries(next)) {
+        if ((limits[axis] ?? 0) < (spent[axis] ?? 0) + value) return false
+      }
+      for (const [axis, value] of Object.entries(next)) spent[axis] = (spent[axis] ?? 0) + value
+      return true
+    },
+    snapshot() {
+      return Object.freeze({ ...spent })
+    },
+  }
+}
+
+export interface ToolIdempotencyBeginInput {
+  readonly namespace: string
+  readonly key: string
+}
+
+export type ToolIdempotencyBeginResult =
+  | { readonly state: "new"; readonly reservation: string }
+  | { readonly state: "duplicate" }
+  | { readonly state: "in-flight" }
+  | { readonly state: "capacity" }
+
+export interface ToolIdempotencyStore {
+  readonly durability?: "memory" | "durable"
+  begin(
+    input: ToolIdempotencyBeginInput,
+  ): ToolIdempotencyBeginResult | PromiseLike<ToolIdempotencyBeginResult>
+  complete(input: {
+    readonly namespace: string
+    readonly key: string
+    readonly reservation: string
+  }): boolean | PromiseLike<boolean>
+  abandon(input: {
+    readonly namespace: string
+    readonly key: string
+    readonly reservation: string
+  }): boolean | PromiseLike<boolean>
+}
+
+interface ToolIdempotencyEntry {
+  readonly reservation: string
+  readonly expiresAt: number
+  completed: boolean
+}
+
+export interface MemoryToolIdempotencyStoreOptions {
+  readonly maxEntries?: number
+  readonly ttlMs?: number
+  readonly now?: () => number
+}
+
+export class MemoryToolIdempotencyStore implements ToolIdempotencyStore {
+  readonly durability = "memory" as const
+  private readonly entries = new Map<string, ToolIdempotencyEntry>()
+  private readonly maxEntries: number
+  private readonly ttlMs: number
+  private readonly now: () => number
+
+  constructor(options: MemoryToolIdempotencyStoreOptions = {}) {
+    this.maxEntries = options.maxEntries ?? 10_000
+    this.ttlMs = options.ttlMs ?? 86_400_000
+    this.now = options.now ?? Date.now
+    if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 1) {
+      throw new RangeError("tool idempotency: maxEntries must be a positive safe integer")
+    }
+    if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs < 1) {
+      throw new RangeError("tool idempotency: ttlMs must be a positive safe integer")
+    }
+  }
+
+  begin(input: ToolIdempotencyBeginInput): ToolIdempotencyBeginResult {
+    validateIdempotencyInput(input)
+    const key = `${input.namespace.length}:${input.namespace}${input.key}`
+    const existing = this.entries.get(key)
+    const now = this.now()
+    if (existing !== undefined && existing.expiresAt > now) {
+      return { state: existing.completed ? "duplicate" : "in-flight" }
+    }
+    if (existing !== undefined) this.entries.delete(key)
+    this.sweep()
+    if (this.entries.size >= this.maxEntries) return { state: "capacity" }
+    this.entries.set(key, {
+      reservation: crypto.randomUUID(),
+      expiresAt: now + this.ttlMs,
+      completed: false,
+    })
+    return { state: "new", reservation: this.entries.get(key)!.reservation }
+  }
+
+  complete(input: {
+    readonly namespace: string
+    readonly key: string
+    readonly reservation: string
+  }): boolean {
+    validateIdempotencyInput(input)
+    const entry = this.entries.get(`${input.namespace.length}:${input.namespace}${input.key}`)
+    if (
+      entry === undefined ||
+      entry.reservation !== input.reservation ||
+      entry.expiresAt <= this.now()
+    )
+      return false
+    entry.completed = true
+    return true
+  }
+
+  abandon(input: {
+    readonly namespace: string
+    readonly key: string
+    readonly reservation: string
+  }): boolean {
+    validateIdempotencyInput(input)
+    const key = `${input.namespace.length}:${input.namespace}${input.key}`
+    const entry = this.entries.get(key)
+    if (entry === undefined || entry.reservation !== input.reservation || entry.completed)
+      return false
+    this.entries.delete(key)
+    return true
+  }
+
+  sweep(): void {
+    const now = this.now()
+    for (const [key, entry] of this.entries) if (entry.expiresAt <= now) this.entries.delete(key)
+  }
+}
+
+export type ToolEvidenceStage =
+  | "input"
+  | "capability"
+  | "policy"
+  | "approval"
+  | "idempotency"
+  | "budget"
+  | "execution"
+  | "output"
+
+export type ToolEvidenceOutcome =
+  | "passed"
+  | "denied"
+  | "failed"
+  | "skipped"
+  | "committed"
+  | "dry-run"
+
+export interface ToolEvidence {
+  readonly seq: number
+  readonly stage: ToolEvidenceStage
+  readonly outcome: ToolEvidenceOutcome
+  readonly code?: string
+}
+
+export interface ToolError {
+  readonly code:
+    | "input_invalid"
+    | "capability_denied"
+    | "execution_policy_unsatisfied"
+    | "approval_required"
+    | "approval_denied"
+    | "idempotency_store_missing"
+    | "idempotency_durability"
+    | "idempotency_duplicate"
+    | "idempotency_in_flight"
+    | "idempotency_capacity"
+    | "budget_exceeded"
+    | "cancelled"
+    | "execution_failed"
+    | "output_invalid"
+    | "ledger_failed"
+  readonly stage: ToolEvidenceStage
+  readonly issues?: readonly StandardIssue[]
+}
+
+export type ToolCallResult<Output> =
+  | {
+      readonly ok: true
+      readonly output?: Output
+      readonly dryRun: boolean
+      readonly evidence: readonly ToolEvidence[]
+      readonly ledger: SealedEffectLedger
+    }
+  | {
+      readonly ok: false
+      readonly dryRun: boolean
+      readonly output?: undefined
+      readonly error: ToolError
+      readonly evidence: readonly ToolEvidence[]
+      readonly ledger: SealedEffectLedger
+    }
+
+export interface ToolCallOptions {
+  readonly effectId?: string
+  readonly clock?: () => number
+  readonly signal?: AbortSignal
+  /** Wall-clock budget shared with the parent request, distinct from the cost `budget`. */
+  readonly deadline?: RequestBudget
+  readonly capabilities?: readonly string[]
+  readonly approval?: ToolApproval
+  readonly budget?: ToolBudget
+  readonly idempotency?: ToolIdempotencyStore
+  readonly namespace?: string
+  readonly dryRun?: boolean
+  readonly ledger?: RequestLedger
+  readonly executionPolicy?: ExecutionPolicyAdapter
+}
+
+export function defineTool<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+>(
+  options: ToolContractOptions<
+    InferOutput<InputSchema>,
+    InferOutput<OutputSchema>,
+    InputSchema,
+    OutputSchema
+  >,
+): ToolContract<InferOutput<InputSchema>, InferOutput<OutputSchema>> {
+  if (typeof options !== "object" || options === null)
+    throw new TypeError("tool contract: options must be an object")
+  if (!TOOL_NAME.test(options.name))
+    throw new TypeError(`tool contract: invalid name ${JSON.stringify(options.name)}`)
+  if (typeof options.description !== "string" || options.description.trim() === "") {
+    throw new TypeError("tool contract: description must not be empty")
+  }
+  if (!isStandardSchema(options.input) || !isStandardSchema(options.output)) {
+    throw new TypeError("tool contract: input and output must implement Standard Schema")
+  }
+  if (options.capability !== undefined && !validCapabilityId(options.capability)) {
+    throw new TypeError(`tool contract: invalid capability ${JSON.stringify(options.capability)}`)
+  }
+  const approval = validateApprovalPolicy(options.approval ?? { kind: "none" })
+  const cost =
+    options.cost === undefined ? undefined : normalizeEffectMetadata({ cost: options.cost }).cost
+  const sensitivity = options.sensitivity ?? "internal"
+  if (!isSensitivity(sensitivity)) throw new TypeError("tool contract: invalid sensitivity")
+  const policy = options.policy === undefined ? undefined : defineExecutionPolicy(options.policy)
+  if (options.idempotency !== undefined) validateIdempotencyPolicy(options.idempotency)
+  if (typeof options.execute !== "function")
+    throw new TypeError("tool contract: execute must be a function")
+  return Object.freeze({
+    name: options.name,
+    description: options.description.trim(),
+    input: options.input,
+    output: options.output,
+    capability: options.capability ?? `${DEFAULT_CAPABILITY}.${options.name}`,
+    approval,
+    ...(options.idempotency === undefined ? {} : { idempotency: options.idempotency }),
+    ...(cost === undefined ? {} : { cost }),
+    sensitivity,
+    annotations: Object.freeze({ ...(options.annotations ?? {}) }),
+    ...(policy === undefined ? {} : { policy }),
+    execute: options.execute,
+  })
+}
+
+export async function executeTool<Input, Output>(
+  tool: ToolContract<Input, Output>,
+  input: unknown,
+  options: ToolCallOptions = {},
+): Promise<ToolCallResult<Output>> {
+  const signal = options.signal ?? new AbortController().signal
+  const dryRun = options.dryRun === true
+  const ledger =
+    options.ledger ??
+    createRequestLedger({
+      method: "TOOL",
+      path: `/${tool.name}`,
+      declared: [tool.capability],
+      chain: true,
+      ...(options.clock === undefined ? {} : { clock: options.clock }),
+    })
+  const evidence: ToolEvidence[] = []
+  const effectId = options.effectId ?? crypto.randomUUID()
+  let reservation:
+    | { readonly namespace: string; readonly key: string; readonly value: string }
+    | undefined
+  const record = (stage: ToolEvidenceStage, outcome: ToolEvidenceOutcome, code?: string): void => {
+    if (evidence.length >= MAX_EVIDENCE) return
+    evidence.push({ seq: evidence.length, stage, outcome, ...(code === undefined ? {} : { code }) })
+  }
+  const appendIntent = (): void => {
+    ledger.append({
+      capability: tool.capability,
+      effectId,
+      phase: "intent",
+      target: `tool:${tool.name}`,
+      ...(tool.cost === undefined ? {} : { cost: tool.cost }),
+    })
+  }
+  type ToolCallOutcome =
+    | { readonly ok: true; readonly dryRun: boolean; readonly output?: Output }
+    | { readonly ok: false; readonly dryRun: boolean; readonly error: ToolError }
+  const finish = async (result: ToolCallOutcome): Promise<ToolCallResult<Output>> => {
+    try {
+      if (result.ok) {
+        ledger.append({
+          capability: tool.capability,
+          effectId,
+          phase: "committed",
+          target: `tool:${tool.name}`,
+          ...(tool.cost === undefined ? {} : { cost: tool.cost }),
+        })
+      } else {
+        ledger.append({
+          capability: tool.capability,
+          effectId,
+          phase: "failed",
+          target: `tool:${tool.name}`,
+          ...(tool.cost === undefined ? {} : { cost: tool.cost }),
+          error: { code: result.error.code },
+        })
+      }
+      const sealed = await ledger.seal()
+      return { ...result, evidence: Object.freeze([...evidence]), ledger: sealed }
+    } catch {
+      const fallback: ToolCallResult<Output> = {
+        ok: false,
+        dryRun,
+        error: { code: "ledger_failed", stage: "execution" },
+        evidence: Object.freeze([
+          ...evidence,
+          { seq: evidence.length, stage: "execution", outcome: "failed", code: "ledger_failed" },
+        ]),
+        ledger: await createRequestLedger({
+          method: "TOOL",
+          path: `/${tool.name}`,
+          declared: [tool.capability],
+          ...(options.clock === undefined ? {} : { clock: options.clock }),
+        }).seal(),
+      }
+      return fallback
+    }
+  }
+
+  try {
+    appendIntent()
+    const validatedInput = await validateStandard(tool.input, input)
+    if (!validatedInput.ok) {
+      record("input", "denied", "input_invalid")
+      return finish({
+        ok: false,
+        dryRun,
+        error: { code: "input_invalid", stage: "input", issues: validatedInput.issues },
+      })
+    }
+    record("input", "passed")
+
+    if (signal.aborted) {
+      record("capability", "denied", "cancelled")
+      return finish({ ok: false, dryRun, error: { code: "cancelled", stage: "capability" } })
+    }
+    if (!hasCapability(options.capabilities, tool.capability)) {
+      record("capability", "denied", "capability_denied")
+      return finish({
+        ok: false,
+        dryRun,
+        error: { code: "capability_denied", stage: "capability" },
+      })
+    }
+    record("capability", "passed")
+
+    if (tool.policy !== undefined) {
+      if (
+        !tool.policy.capabilityCeiling.includes(tool.capability) ||
+        options.executionPolicy === undefined ||
+        !(await options.executionPolicy.canSatisfy(tool.policy))
+      ) {
+        record("policy", "denied", "execution_policy_unsatisfied")
+        return finish({
+          ok: false,
+          dryRun,
+          error: { code: "execution_policy_unsatisfied", stage: "policy" },
+        })
+      }
+      record("policy", "passed")
+    }
+
+    const approvalError = checkApproval(tool.approval, options.approval)
+    if (approvalError !== undefined) {
+      record("approval", "denied", approvalError)
+      return finish({ ok: false, dryRun, error: { code: approvalError, stage: "approval" } })
+    }
+    record("approval", tool.approval.kind === "none" ? "skipped" : "passed")
+
+    if (tool.idempotency !== undefined) {
+      const namespace = options.namespace ?? DEFAULT_NAMESPACE
+      if (!validIdempotencyNamespace(namespace)) {
+        record("idempotency", "denied", "idempotency_store_missing")
+        return finish({
+          ok: false,
+          dryRun,
+          error: { code: "idempotency_store_missing", stage: "idempotency" },
+        })
+      }
+      if (options.idempotency === undefined) {
+        record("idempotency", "denied", "idempotency_store_missing")
+        return finish({
+          ok: false,
+          dryRun,
+          error: { code: "idempotency_store_missing", stage: "idempotency" },
+        })
+      }
+      if (tool.idempotency.scope === "durable" && options.idempotency.durability !== "durable") {
+        record("idempotency", "denied", "idempotency_durability")
+        return finish({
+          ok: false,
+          dryRun,
+          error: { code: "idempotency_durability", stage: "idempotency" },
+        })
+      }
+      const key = await tool.idempotency.key(validatedInput.value)
+      if (!validIdempotencyKey(key)) {
+        record("idempotency", "denied", "idempotency_store_missing")
+        return finish({
+          ok: false,
+          dryRun,
+          error: { code: "idempotency_store_missing", stage: "idempotency" },
+        })
+      }
+      const began = await options.idempotency.begin({ namespace, key })
+      if (began.state !== "new") {
+        const code =
+          began.state === "duplicate"
+            ? "idempotency_duplicate"
+            : began.state === "in-flight"
+              ? "idempotency_in_flight"
+              : "idempotency_capacity"
+        record("idempotency", "denied", code)
+        return finish({ ok: false, dryRun, error: { code, stage: "idempotency" } })
+      }
+      reservation = { namespace, key, value: began.reservation }
+    }
+    record("idempotency", tool.idempotency === undefined ? "skipped" : "passed")
+
+    if (options.budget !== undefined && !options.budget.consume(tool.cost)) {
+      if (reservation !== undefined)
+        await options.idempotency?.abandon(reservationInput(reservation))
+      record("budget", "denied", "budget_exceeded")
+      return finish({ ok: false, dryRun, error: { code: "budget_exceeded", stage: "budget" } })
+    }
+    record("budget", tool.cost === undefined ? "skipped" : "passed")
+
+    if (signal.aborted) {
+      if (reservation !== undefined)
+        await options.idempotency?.abandon(reservationInput(reservation))
+      record("execution", "denied", "cancelled")
+      return finish({ ok: false, dryRun, error: { code: "cancelled", stage: "execution" } })
+    }
+    if (dryRun) {
+      if (reservation !== undefined)
+        await options.idempotency?.abandon(reservationInput(reservation))
+      record("execution", "dry-run")
+      return finish({ ok: true, dryRun })
+    }
+    const output = await tool.execute(validatedInput.value, {
+      effectId,
+      signal,
+      ...(options.deadline === undefined ? {} : { deadline: options.deadline }),
+      dryRun,
+      ...(tool.policy === undefined ? {} : { policy: tool.policy }),
+    })
+    record("execution", "committed")
+    const validatedOutput = await validateStandard(tool.output, output)
+    if (!validatedOutput.ok) {
+      // The executor has already run. Keep the reservation completed even when its return shape is
+      // invalid, so a caller cannot retry and duplicate a side effect that may have committed.
+      if (reservation !== undefined) {
+        const completed = await options.idempotency?.complete(reservationInput(reservation))
+        if (completed !== true) {
+          record("idempotency", "failed", "idempotency_capacity")
+          return finish({
+            ok: false,
+            dryRun,
+            error: { code: "idempotency_capacity", stage: "idempotency" },
+          })
+        }
+      }
+      record("output", "failed", "output_invalid")
+      return finish({
+        ok: false,
+        dryRun,
+        error: { code: "output_invalid", stage: "output", issues: validatedOutput.issues },
+      })
+    }
+    record("output", "passed")
+    if (reservation !== undefined) {
+      const completed = await options.idempotency?.complete(reservationInput(reservation))
+      if (completed !== true) {
+        record("idempotency", "failed", "idempotency_capacity")
+        return finish({
+          ok: false,
+          dryRun,
+          error: { code: "idempotency_capacity", stage: "idempotency" },
+        })
+      }
+    }
+    return finish({ ok: true, dryRun, output: validatedOutput.value })
+  } catch (error) {
+    if (reservation !== undefined) await options.idempotency?.abandon(reservationInput(reservation))
+    const code = signal.aborted || isAbortError(error) ? "cancelled" : "execution_failed"
+    record("execution", "failed", code)
+    return finish({ ok: false, dryRun, error: { code, stage: "execution" } })
+  }
+}
+
+export interface ToolHttpOptions extends Omit<ToolCallOptions, "signal" | "ledger"> {
+  readonly method?: string
+  /** Prototype-poisoning policy for the JSON request body - mirrors the server option (this
+   * handler is standalone, so it carries its own). Default `"reject"`. */
+  readonly protoPoisoning?: ProtoPoisoning
+  /** Transport body cap in bytes for the JSON request body. Default {@link DEFAULT_TOOL_MAX_BYTES}
+   * (1 MiB). `"unlimited"` removes the cap and requires a written {@link maxBytesReason}: the
+   * mounting platform then owns the limit, and the exemption is reviewable rather than implicit. */
+  readonly maxBytes?: number | "unlimited"
+  /** Why this handler runs uncapped. Required with `maxBytes: "unlimited"`, rejected without it. */
+  readonly maxBytesReason?: string
+}
+
+/** Default transport body cap for {@link createToolHttpHandler}: 1 MiB. */
+export const DEFAULT_TOOL_MAX_BYTES = 1_048_576
+
+/** Validate the handler's body cap at construction, so a misdeclared limit is a startup error
+ * rather than a request-time surprise. `undefined` means the caller opted out with a reason. */
+function resolveToolMaxBytes(name: string, options: ToolHttpOptions): number | undefined {
+  const { maxBytes, maxBytesReason } = options
+  if (maxBytes === "unlimited") {
+    if (typeof maxBytesReason !== "string" || maxBytesReason.trim().length === 0) {
+      throw new Error(`tool ${name}: maxBytes: "unlimited" requires a non-empty maxBytesReason`)
+    }
+    return undefined
+  }
+  if (maxBytesReason !== undefined) {
+    throw new Error(`tool ${name}: maxBytesReason is only valid with maxBytes: "unlimited"`)
+  }
+  if (maxBytes === undefined) return DEFAULT_TOOL_MAX_BYTES
+  assertByteLimit(maxBytes, "tool maxBytes")
+  return maxBytes
+}
+
+/**
+ * Mount one contract behind a Web-standard handler. The handler accepts one JSON request body.
+ * A body carrying a poisoned key (own `__proto__`, or `constructor.prototype`) is rejected with
+ * the same `input_invalid` result as malformed JSON. The body is capped at
+ * {@link ToolHttpOptions.maxBytes} (1 MiB by default); over-cap answers a flat `413` and a
+ * malformed `Content-Length` a flat `400`, before any parse.
+ */
+export function createToolHttpHandler<Input, Output>(
+  tool: ToolContract<Input, Output>,
+  options: ToolHttpOptions = {},
+): (request: Request) => Promise<Response> {
+  const method = (options.method ?? "POST").toUpperCase()
+  const protoPoisoning = options.protoPoisoning ?? "reject"
+  const maxBytes = resolveToolMaxBytes(tool.name, options)
+  const decoder = new TextDecoder()
+  return async (request) => {
+    if (request.method.toUpperCase() !== method) {
+      return new Response(null, { status: 405, headers: { allow: method } })
+    }
+    let text: string
+    if (maxBytes === undefined) {
+      text = await request.text()
+    } else {
+      // The cap is enforced BEFORE the parse, so an oversized payload is never materialized as a
+      // JS value. A flat status carries no tool ledger: nothing was admitted to produce one.
+      const read = await readBoundedBytes(request, maxBytes)
+      if (!read.ok) return new Response(null, { status: read.status })
+      text = decoder.decode(read.bytes)
+    }
+    let input: unknown
+    try {
+      input =
+        protoPoisoning === "ignore" ? JSON.parse(text) : parseJsonGuarded(text, protoPoisoning)
+    } catch {
+      return toolHttpResult({
+        ok: false,
+        dryRun: options.dryRun === true,
+        error: { code: "input_invalid", stage: "input" },
+        evidence: [],
+        ledger: await createRequestLedger({
+          method: "TOOL",
+          path: `/${tool.name}`,
+          declared: [tool.capability],
+        }).seal(),
+      })
+    }
+    const result = await executeTool(tool, input, { ...options, signal: request.signal })
+    return toolHttpResult(result)
+  }
+}
+
+export function toolHttpResult<Output>(result: ToolCallResult<Output>): Response {
+  const body = JSON.stringify(
+    result.ok
+      ? { ok: true, output: result.output, dryRun: result.dryRun, evidence: result.evidence }
+      : { ok: false, error: result.error, dryRun: result.dryRun, evidence: result.evidence },
+  )
+  const status = result.ok
+    ? 200
+    : result.error.code === "input_invalid"
+      ? 422
+      : result.error.code === "approval_required" ||
+          result.error.code === "approval_denied" ||
+          result.error.code === "capability_denied"
+        ? 403
+        : result.error.code === "budget_exceeded"
+          ? 429
+          : 500
+  return new Response(body, { status, headers: { "content-type": "application/json" } })
+}
+
+export function toolInputJsonSchema<Input, Output>(
+  tool: ToolContract<Input, Output>,
+): Record<string, unknown> {
+  const reflected = reflectSchema(tool.input).jsonSchema
+  if (
+    reflected !== undefined &&
+    typeof reflected === "object" &&
+    reflected !== null &&
+    !Array.isArray(reflected)
+  )
+    return { ...reflected }
+  return { type: "object", properties: {}, additionalProperties: false }
+}
+
+export type ToolAdapterResult<Output = unknown> =
+  | {
+      readonly ok: true
+      readonly output?: Output
+      readonly dryRun: boolean
+      readonly evidence: readonly ToolEvidence[]
+    }
+  | {
+      readonly ok: false
+      readonly dryRun: boolean
+      readonly error: ToolError
+      readonly evidence: readonly ToolEvidence[]
+    }
+
+export interface ToolAdapter {
+  readonly name: string
+  call(input: unknown, options?: ToolCallOptions): Promise<ToolAdapterResult>
+}
+
+export interface ToolConformanceResult {
+  readonly adapter: string
+  readonly checks: readonly string[]
+}
+
+/** Shared conformance assertions for adapters. It intentionally checks only public, token-only behavior. */
+export async function runToolContractConformance(
+  adapter: ToolAdapter,
+  options: {
+    readonly input: unknown
+    readonly capability: string
+    readonly approval: ToolApproval
+    readonly dryRun: ToolCallOptions
+  },
+): Promise<ToolConformanceResult> {
+  if (typeof adapter.call !== "function")
+    throw new TypeError("tool conformance: adapter must be callable")
+  const checks: string[] = []
+  const denied = await adapter.call(options.input, { capabilities: [] })
+  if (denied.ok || denied.error.code !== "capability_denied")
+    throw new Error("tool conformance: capability denial failed")
+  checks.push("capability denial")
+  const pending = await adapter.call(options.input, {
+    capabilities: [options.capability],
+    approval: options.approval,
+  })
+  if (!pending.ok && pending.error.code === "approval_required")
+    throw new Error("tool conformance: approval was not supplied")
+  checks.push("approval admission")
+  const dry = await adapter.call(options.input, {
+    capabilities: [options.capability],
+    approval: options.approval,
+    ...options.dryRun,
+    dryRun: true,
+  })
+  if (!dry.ok || !dry.dryRun || dry.evidence.every((item) => item.outcome !== "dry-run"))
+    throw new Error("tool conformance: dry-run failed")
+  checks.push("dry-run")
+  return Object.freeze({ adapter: adapter.name, checks: Object.freeze(checks) })
+}
+
+function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  if (value === null || typeof value !== "object") return false
+  const standard = (value as { readonly [key: string]: unknown })["~standard"]
+  return (
+    standard !== null &&
+    typeof standard === "object" &&
+    (standard as { readonly version?: unknown }).version === 1 &&
+    typeof (standard as { readonly validate?: unknown }).validate === "function"
+  )
+}
+
+function validateApprovalPolicy(policy: ToolApprovalPolicy): ToolApprovalPolicy {
+  if (policy.kind === "none" || policy.kind === "required")
+    return Object.freeze({ kind: policy.kind })
+  if (policy.kind === "threshold" && Number.isSafeInteger(policy.level) && policy.level > 0)
+    return Object.freeze({ kind: "threshold", level: policy.level })
+  throw new TypeError("tool contract: approval policy is invalid")
+}
+
+function validateIdempotencyPolicy<Input>(policy: ToolIdempotencyPolicy<Input>): void {
+  if (policy.scope !== "request" && policy.scope !== "durable")
+    throw new TypeError("tool contract: idempotency scope is invalid")
+  if (typeof policy.key !== "function")
+    throw new TypeError("tool contract: idempotency key must be a function")
+}
+
+function validateIdempotencyInput(input: {
+  readonly namespace: string
+  readonly key: string
+}): void {
+  if (!validIdempotencyNamespace(input.namespace) || !validIdempotencyKey(input.key))
+    throw new TypeError("tool idempotency: namespace/key is invalid")
+}
+
+function reservationInput(input: {
+  readonly namespace: string
+  readonly key: string
+  readonly value: string
+}): { readonly namespace: string; readonly key: string; readonly reservation: string } {
+  return { namespace: input.namespace, key: input.key, reservation: input.value }
+}
+
+function checkApproval(
+  policy: ToolApprovalPolicy,
+  approval: ToolApproval | undefined,
+): ToolError["code"] | undefined {
+  if (policy.kind === "none") return undefined
+  if (approval === undefined) return "approval_required"
+  if (!approval.granted) return "approval_denied"
+  if (policy.kind === "threshold" && (approval.level ?? 0) < policy.level) return "approval_denied"
+  return undefined
+}
+
+function hasCapability(values: readonly string[] | undefined, required: string): boolean {
+  if (!Array.isArray(values)) return false
+  for (const value of values)
+    if (typeof value !== "string" || !validCapabilityId(value)) return false
+  return values.includes(required)
+}
+
+function normalizeCost(value: EffectCost, label: string): Record<string, number> {
+  try {
+    const normalized = normalizeEffectMetadata({ cost: value }).cost
+    return { ...(normalized ?? {}) }
+  } catch (error) {
+    throw new TypeError(`${label}: ${error instanceof Error ? error.message : "invalid cost"}`)
+  }
+}
+
+function isSensitivity(value: string): value is ToolSensitivity {
+  return value === "public" || value === "internal" || value === "sensitive" || value === "secret"
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError"
+}