@cloc/provider-ai-sdk 0.1.0

package/src/tokens.ts

@@ -0,0 +1,82 @@
+/**
+ * @cloc/provider-ai-sdk · tokens.ts — re-export the AgentProvider ref this adapter answers,
+ * and pull in the vendor-free contract TYPES from @cloc/core (FR-002, data-model §1).
+ *
+ * This is the ONLY seam the adapter binds: `AgentProviderRef` selects exactly one
+ * AgentProvider per environment (§32 / §75.3). Downstream modules type-check against the
+ * core contract — never against an AI SDK / AI Gateway type — so no vendor type leaks across
+ * the public signature (FR-002, Constitution Principle 8).
+ *
+ * NOTE: the model is a swappable FIELD (`GenOpts.model: ModelRef`), never part of this
+ * contract; the token/package/capability names carry no "model" (FR-014).
+ */
+
+// The token (value) the kernel resolves this plugin against. EXACTLY ONE wins (§32).
+export { AgentProviderRef } from "@cloc/core";
+
+// The vendor-free contract + result types every internal module builds on (no vendor edge).
+export type {
+  AgentProvider,
+  GenOpts,
+  Prompt,
+  StructuredPrompt,
+  Output,
+  OutputPayload,
+  Delta,
+  PlanNode,
+  ModelRef,
+  StandardSchema,
+  StandardSchemaV1,
+  ProviderRef,
+} from "@cloc/core";
+
+// --- The agentic-primitives contract this runner EXECUTES (027-agentic-primitives) -------------
+//
+// These shapes are owned by @cloc/core (`src/agentic/*`): the render-time Agent's three optional,
+// gated primitives — Skills (progressive disclosure), Memory (the memory-tool interface), and the
+// budgeted Tool loop — plus the §58 gate hook. The runner consumes them as TYPES only; the loop
+// that EXECUTES them (the AI SDK 6 `ToolLoopAgent`) lives in THIS package (tool-loop.ts /
+// memory-tool.ts / skills-loader.ts) with the single vendor edge. No vendor type leaks across the
+// core seam (FR-016, CON-001, Principle 8).
+export type {
+  // Skills (§16b.1)
+  SkillRef,
+  SkillManifest,
+  SkillBody,
+  BundledResource,
+  DisclosureLevel,
+  // Memory (§16b.2)
+  MemoryStore,
+  MemoryBackend,
+  MemoryOp,
+  // Tools (§16b.3)
+  ToolDef,
+  ToolSet as CoreToolSet,
+  ToolSource,
+  // Loop / budget / prepareStep (§16b.3, §9.1)
+  ToolLoop,
+  LoopOpts,
+  StopCondition,
+  StepContext,
+  StepDirective,
+  PrepareStep,
+  // Gate (§58)
+  PolicyGateHook,
+  PrimitiveAccess,
+  GateDecision,
+} from "@cloc/core";
+
+// Agentic runtime helpers (pure, vendor-free) the runner reuses from the core contract.
+export {
+  isStopTool,
+  validateSkillManifest,
+  isValidSkillName,
+  isValidSkillDescription,
+  stepCountIs as coreStepCountIs,
+  hasToolCall as coreHasToolCall,
+  isLoopFinished as coreIsLoopFinished,
+  defaultStopCondition,
+  DEFAULT_STEP_COUNT,
+  MEMORY_ROLE,
+  ALLOW_ALL_GATE,
+} from "@cloc/core";

package/src/tool-loop.ts

@@ -0,0 +1,268 @@
+/**
+ * @cloc/provider-ai-sdk · tool-loop.ts — the budgeted render-time tool loop over the AI SDK v6
+ * `ToolLoopAgent` surface (007-provider-ai-sdk; 027-agentic-primitives §16b.3, §17, §9.1).
+ *
+ * The render Agent runs a bounded `call → execute-tools → feed-results → repeat` loop: the model
+ * may CALL a declared tool, its result is FED BACK as DATA (through safety.ts), and the loop runs
+ * until `stopWhen` terminates it (default `stepCountIs(20)` — the SAME trajectory budget that bounds
+ * the `0` console agent, §9.1, FR-013). `prepareStep` runs BEFORE each step to swap the model,
+ * restrict `activeTools`/`toolChoice`, and select which skills/memory enter that step (FR-011). A
+ * tool WITHOUT `execute` is a STOP SIGNAL (the model emits the call and the loop ends). Every tool
+ * call clears the §58 policy gate BEFORE execution; a denial DEGRADES (FR-014, FR-021).
+ *
+ * AI SDK v6 surface (verified against the installed ai@6 .d.ts, not stale memory):
+ *   - `ToolLoopAgent` is the default `Agent` impl; `tool()`/`dynamicTool({ description, inputSchema,
+ *     execute })` (v6 renamed `parameters` → `inputSchema`); multi-step loops use
+ *     `stopWhen: stepCountIs(n)` (v6 removed `maxSteps`); `hasToolCall(name)` / `isLoopFinished()`
+ *     are the other stop conditions; `StopCondition<TOOLS>` is `(opts) => boolean | PromiseLike`;
+ *     `prepareStep({ steps, stepNumber, model, messages }) => { model?, toolChoice?, activeTools? }`.
+ *   - The non-streaming `generateText`/`streamText` calls in agent.ts already drive this loop via
+ *     `tools` + `stopWhen`; this module assembles those vendor values from the core contract.
+ *
+ * Vendor edge: this is one of the THREE files (with memory-tool.ts, skills-loader.ts) that touch
+ * `ai`. The core's `StopCondition`/`PrepareStep`/`ToolDef` shapes stay vendor-free (@cloc/core).
+ */
+
+import { dynamicTool, stepCountIs, hasToolCall, isLoopFinished } from "ai";
+import type {
+  ToolSet as AiToolSet,
+  FlexibleSchema,
+  StopCondition as AiStopCondition,
+  PrepareStepFunction,
+  ToolChoice,
+  LanguageModel,
+} from "ai";
+import type { AgentTool } from "./request.js";
+import type {
+  StopCondition,
+  PrepareStep,
+  StepDirective,
+  PolicyGateHook,
+  CoreToolSet,
+  ToolDef,
+} from "./tokens.js";
+import { frameToolResultAsData } from "./safety.js";
+
+/** Observable loop event the trace + stream consume (data-model §4). */
+export type LoopEvent =
+  | { kind: "tool-call"; tool: string; args: unknown }
+  | { kind: "tool-result"; tool: string; result: unknown };
+
+/**
+ * The ONE gated-tool-execution path shared by the legacy ({@link buildToolSet}) and the 027 agentic
+ * ({@link buildAgenticToolSet}) tool sets — so both gate, emit, degrade, and frame IDENTICALLY (DRY;
+ * FR-014, FR-015, FR-021). Steps, in order:
+ *   1. emit a `tool-call` event (the trace/stream observe the call in order),
+ *   2. clear the §58 gate (when one is supplied) — a DENY degrades: emit a `tool-result` denial and
+ *      return it framed as DATA (never throws, never bypasses, never runs the user fn),
+ *   3. run the user-supplied `invoke`,
+ *   4. emit a `tool-result` event and return the result framed as DATA (FR-003 feedback path).
+ *
+ * `gate` is OPTIONAL so the legacy path stays callable without the §58 wiring (current behavior).
+ */
+function makeGatedToolExecute(
+  name: string,
+  // The user fn may return sync OR a Promise (core `ToolDef.execute` is `(i) => Promise<O> | O`);
+  // we always `await` so a synchronous tool is handled identically.
+  invoke: (args: unknown) => Promise<unknown> | unknown,
+  onEvent: (event: LoopEvent) => void,
+  gate: PolicyGateHook | undefined,
+): (args: unknown) => Promise<string> {
+  return async (args: unknown): Promise<string> => {
+    onEvent({ kind: "tool-call", tool: name, args });
+    if (gate) {
+      const decision = await gate.check({ kind: "tool", tool: name });
+      if (!decision.allow) {
+        const reason = decision.reason ?? `tool "${name}" denied`;
+        onEvent({ kind: "tool-result", tool: name, result: { denied: true, reason } });
+        // Degrade: hand the model an attributable denial as DATA (never crash, never bypass).
+        return frameToolResultAsData(name, { denied: true, reason });
+      }
+    }
+    const result = await invoke(args);
+    onEvent({ kind: "tool-result", tool: name, result });
+    // The observation re-enters the loop as DATA, never as instructions (FR-015).
+    return frameToolResultAsData(name, result);
+  };
+}
+
+/**
+ * Default loop bound — the SAME trajectory budget that bounds the `0` console agent (§9.1). v6's
+ * own default is `stepCountIs(20)`; we keep a smaller render default but the render layer MUST set
+ * `stopWhen` explicitly (FR-013). Kept for the legacy single-turn path; the agentic render path
+ * maps `GenOpts.stopWhen` through {@link toAiStopWhen}.
+ */
+export const DEFAULT_MAX_STEPS = 8;
+
+/**
+ * Build the AI SDK v6 `ToolSet` from the turn's legacy declared tools (the pre-027 shape on
+ * `AgentTurn.tools`). Each tool's `execute`:
+ *   1. emits a `tool-call` event,
+ *   2. invokes the user-provided `invoke` (the actual DataSource query / declared action),
+ *   3. frames the result as DATA (safety.ts) and emits a `tool-result` event,
+ *   4. returns the framed result to the loop as the observation (FR-003 feedback path).
+ *
+ * `onEvent` lets the agent forward `tool-call`/`tool-result` to the stream + trace in order. When a
+ * {@link PolicyGateHook} is supplied, each call clears the §58 gate FIRST and a denial DEGRADES
+ * (the tool returns an attributable denial as DATA, never throwing — FR-014, FR-021).
+ */
+export function buildToolSet(
+  tools: ReadonlyArray<AgentTool>,
+  onEvent: (event: LoopEvent) => void,
+  gate?: PolicyGateHook,
+): AiToolSet {
+  const set: AiToolSet = {};
+  for (const t of tools) {
+    // v6: runtime tools whose input/output types are not known at dev time use `dynamicTool`
+    // (the typed `tool({...})` overloads infer INPUT/OUTPUT from a static schema we don't have).
+    set[t.name] = dynamicTool({
+      ...(t.description !== undefined ? { description: t.description } : {}),
+      // v6: `inputSchema` (was `parameters`). Zod / Standard-Schema validators are accepted.
+      inputSchema: t.input as FlexibleSchema<unknown>,
+      // v6 `execute(input, options)` — we ignore the options (no abort/streaming hooks here).
+      // Gating + eventing + DATA-framing run through the ONE shared gated executor (DRY).
+      execute: makeGatedToolExecute(t.name, (args) => t.invoke(args), onEvent, gate),
+    });
+  }
+  return set;
+}
+
+/**
+ * Build the AI SDK v6 `ToolSet` from the 027 core {@link CoreToolSet} (`GenOpts.tools`) — the three
+ * sources (`plugin` / `capability` / `wired`) all join the render loop (FR-012). Each `ToolDef`'s
+ * `execute` is gate-checked then framed as DATA; a tool WITHOUT `execute` is registered as a STOP
+ * SIGNAL (v6: a tool with no `execute` ends the loop — §16b.3, isStopTool). Returns `{}` for an
+ * empty/undefined set so a baseline render adds no tools (FR-002).
+ */
+export function buildAgenticToolSet(
+  tools: CoreToolSet | undefined,
+  onEvent: (event: LoopEvent) => void,
+  gate: PolicyGateHook,
+): AiToolSet {
+  if (!tools) return {};
+  const set: AiToolSet = {};
+  for (const [name, def] of Object.entries(tools)) {
+    set[name] = agenticTool(name, def, onEvent, gate);
+  }
+  return set;
+}
+
+/** One core {@link ToolDef} → a gated v6 `dynamicTool`. `execute`-less = stop signal (§16b.3). */
+function agenticTool(
+  name: string,
+  def: ToolDef,
+  onEvent: (event: LoopEvent) => void,
+  gate: PolicyGateHook,
+): AiToolSet[string] {
+  const base = {
+    ...(def.description !== undefined ? { description: def.description } : {}),
+    inputSchema: def.inputSchema as unknown as FlexibleSchema<unknown>,
+  };
+  // A tool WITHOUT execute is a STOP SIGNAL: register a dynamic tool with NO execute so the loop
+  // ends when the model emits the call (AI SDK v6 semantics; isStopTool narrows it). `dynamicTool`
+  // requires `execute`, so a stop tool is registered as the equivalent dynamic-tool object literal.
+  const execute = def.execute;
+  if (execute === undefined) {
+    return { ...base, type: "dynamic" } as unknown as AiToolSet[string];
+  }
+  return dynamicTool({
+    ...base,
+    // Same gated executor as the legacy path — gate-check, emit, degrade-to-DATA, frame (DRY).
+    execute: makeGatedToolExecute(name, (args) => execute(args), onEvent, gate),
+  });
+}
+
+/** The v6 multi-step stop condition (replaces the removed `maxSteps`). Legacy single-turn default. */
+export function stopAfter(maxSteps: number = DEFAULT_MAX_STEPS): AiStopCondition<AiToolSet> {
+  return stepCountIs(maxSteps);
+}
+
+/**
+ * Map the core vendor-free {@link StopCondition} (`GenOpts.stopWhen`) to the AI SDK v6 stop
+ * condition — `stepCountIs(n)` / `hasToolCall(name)` / `isLoopFinished()` (§16b.3, §9.1). When the
+ * render layer sets no budget we fall back to the loop default so it can never thrash unbounded
+ * (FR-013, NFR-005).
+ *
+ * TODO(027/003/012, NEEDS CLARIFICATION): cache keying of a tool-using (non-pure) render — whether
+ * tool outputs fold into `dataVersion`, the render is uncacheable, or it is cached per tool-result
+ * hash. Owned by 003/012; routed to Governance.
+ * TODO(027, NEEDS CLARIFICATION): degraded-render behavior when the budget is exhausted BEFORE a
+ * complete `Output` (cheaper tier? best partial-but-valid plan?). §16b.3 guarantees boundedness but
+ * not the exact fallback; today we let `validateOrRepair` (validate.ts) reject an incomplete plan so
+ * an invalid/partial structure is NEVER emitted (Principle 3). Routed to Governance.
+ */
+export function toAiStopWhen(
+  stopWhen: StopCondition | undefined,
+  fallbackSteps: number = DEFAULT_MAX_STEPS,
+): AiStopCondition<AiToolSet> {
+  if (!stopWhen) return stepCountIs(fallbackSteps);
+  switch (stopWhen.kind) {
+    case "stepCount":
+      // Guard a non-finite/negative step count from a hand-built condition so the loop stays bounded.
+      return stepCountIs(Number.isFinite(stopWhen.n) && stopWhen.n > 0 ? Math.trunc(stopWhen.n) : fallbackSteps);
+    case "hasToolCall":
+      return hasToolCall(stopWhen.name);
+    case "isLoopFinished":
+      return isLoopFinished();
+    default: {
+      // Exhaustiveness: a new core StopCondition kind must be handled here. Fall back to the bounded
+      // step cap so an unrecognized condition can never leave the loop unbounded (NFR-005).
+      const _exhaustive: never = stopWhen;
+      void _exhaustive;
+      return stepCountIs(fallbackSteps);
+    }
+  }
+}
+
+/**
+ * Adapt the core vendor-free {@link PrepareStep} (per-step context engineering, FR-011) to the AI
+ * SDK v6 `prepareStep` callback. Runs BEFORE each step and returns the per-step overrides v6
+ * honors: `model` (swap), `activeTools` (restrict), `toolChoice` (restrict). Skill/memory SELECTION
+ * carried on the core {@link StepDirective} is applied by the caller (it owns the typed tool/skill
+ * maps); v6's surface only takes the model/tools knobs, so those pass straight through. Returns
+ * `undefined` (use outer settings) when the directive sets nothing for the step.
+ *
+ * `resolveModel` turns a core `ModelRef`-bearing directive into the routed v6 `LanguageModel`; when
+ * absent the step keeps the outer model. The per-step skill/memory selection is surfaced via
+ * `onDirective` so the runner can re-frame the prompt fragment / gate the chosen skills.
+ */
+export function toAiPrepareStep(
+  prepareStep: PrepareStep | undefined,
+  resolveModel: (directive: StepDirective) => PrepareStepResultModel | undefined,
+  onDirective?: (step: number, directive: StepDirective) => void,
+): PrepareStepFunction<AiToolSet> | undefined {
+  if (!prepareStep) return undefined;
+  return ({ stepNumber, steps }) => {
+    const directive = prepareStep({
+      step: stepNumber,
+      ...(steps.length > 0 ? { lastOutput: steps[steps.length - 1] } : {}),
+    });
+    onDirective?.(stepNumber, directive);
+    const model = resolveModel(directive);
+    const result: {
+      model?: PrepareStepResultModel;
+      activeTools?: Array<string>;
+      toolChoice?: ToolChoice<AiToolSet>;
+    } = {};
+    if (model !== undefined) result.model = model;
+    if (directive.activeTools !== undefined) result.activeTools = [...directive.activeTools];
+    if (directive.toolChoice !== undefined) result.toolChoice = toAiToolChoice(directive.toolChoice);
+    return Object.keys(result).length > 0 ? (result as never) : undefined;
+  };
+}
+
+/**
+ * Map the core vendor-free tool-choice (a string like `"auto"`/`"required"`/`"none"`, or a named
+ * `{ tool }` selector) to the AI SDK v6 {@link ToolChoice} shape (`"auto"` | `{ type: "tool",
+ * toolName }`). Extracted so the mapping lives in ONE place (DRY); behavior is unchanged.
+ */
+function toAiToolChoice(
+  choice: NonNullable<StepDirective["toolChoice"]>,
+): ToolChoice<AiToolSet> {
+  return typeof choice === "string"
+    ? (choice as ToolChoice<AiToolSet>)
+    : { type: "tool", toolName: choice.tool };
+}
+
+/** The v6 `LanguageModel` a per-step model swap resolves to (kept vendor-internal). */
+export type PrepareStepResultModel = LanguageModel;

package/src/trace.ts

@@ -0,0 +1,87 @@
+/**
+ * @cloc/provider-ai-sdk · trace.ts — the `agent.generate` OTel subtree (FR-012, §72.2,
+ * contracts/trace.contract.ts).
+ *
+ * The render pipeline contributes the STRUCTURAL spans (route/ground/project/cache/eval); the
+ * AgentProvider contributes the `agent.generate` subtree, which the AI SDK + AI Gateway emit
+ * natively (provider, model, fallback hops, token counts, cost). This module pins the attribute
+ * names and NESTS the subtree under the active pipeline trace so the two compose into one trace =
+ * one replay recipe (§72.2).
+ *
+ * To stay runtime-agnostic and vendor-light, the adapter does not hard-depend on
+ * `@opentelemetry/api`; it records against a small structural `SpanSink` the pipeline/host backs
+ * with its real tracer (the AI SDK already emits OTel — the host wires `experimental_telemetry`).
+ * A no-op sink is the default so the adapter runs without a tracer present.
+ *
+ * TODO(C3 — spec Clarification 3): whether `prompt.tokens`/`output.tokens` (and latency) are
+ *   MANDATED at MVP, or `cost.usd` is the only required metric. §72.2 shows tokens; routed to
+ *   Governance (research.md C3). They are recorded when available, asserted only for cost.
+ */
+
+/** The `agent.generate` attribute bag (contracts/trace.contract.ts). */
+export interface AgentGenerateAttributes {
+  "gateway.provider": string;
+  "gateway.model": string;
+  /** Failover hops; 0 when the primary served. */
+  "gateway.fallback": number;
+  /** Per-request cost — REQUIRED (FR-012). */
+  "cost.usd": number;
+  /** §72.2 shows these; mandate is TODO(C3). Recorded when the SDK/gateway reports them. */
+  "prompt.tokens"?: number;
+  "output.tokens"?: number;
+  /** Total tokens for the turn (v6 `usage.totalTokens`); recorded additively when reported. */
+  "total.tokens"?: number;
+  /** Cached input tokens read (v6 `usage.inputTokenDetails.cacheReadTokens`); when reported. */
+  "cache.read.tokens"?: number;
+}
+
+/** Shared provenance keys carried with the pipeline spans so the trace is a replay recipe. */
+export interface AgentGenerateContext {
+  "cloc.data_version": string;
+  "cloc.kit_version": string;
+  "cloc.seed"?: string;
+  "cloc.tier": 2 | 3;
+}
+
+/** Span events: the loop + validation boundary as observable events. */
+export type AgentGenerateEvent =
+  | { name: "tool.call"; tool: string }
+  | { name: "tool.result"; tool: string }
+  | { name: "validate"; ok: boolean }
+  | { name: "repair"; attempt: number; ok: boolean };
+
+/**
+ * The minimal structural sink the adapter records against. The host backs this with its real OTel
+ * tracer (nesting under `req.trace`); the default is a no-op. Mirrors the OTel span surface the
+ * adapter needs without importing the vendor package (keeps the adapter dependency-light, §43).
+ */
+export interface SpanSink {
+  setAttributes(attrs: Partial<AgentGenerateAttributes & AgentGenerateContext>): void;
+  addEvent(event: AgentGenerateEvent): void;
+  /** Mark the subtree failed (carries the surfaced AgentError code). */
+  recordError(code: string, message: string): void;
+  end(): void;
+}
+
+/** A no-op sink — used when no tracer is wired (the adapter still runs). */
+export const NOOP_SPAN: SpanSink = {
+  setAttributes() {},
+  addEvent() {},
+  recordError() {},
+  end() {},
+};
+
+/**
+ * Open the `agent.generate` span under the active pipeline trace. `start` is supplied by the host
+ * (it owns the real tracer + the active OTel context from `req.trace`); when absent we return the
+ * no-op sink. The returned sink is the seam every internal module reports through.
+ */
+export function startAgentSpan(
+  context: AgentGenerateContext,
+  start?: (name: "agent.generate", context: AgentGenerateContext) => SpanSink,
+): SpanSink {
+  if (!start) return NOOP_SPAN;
+  const span = start("agent.generate", context);
+  span.setAttributes(context);
+  return span;
+}

package/src/validate.ts

@@ -0,0 +1,118 @@
+/**
+ * @cloc/provider-ai-sdk · validate.ts — the validate-or-repair boundary (FR-005, NFR-001, §3).
+ *
+ * Probabilistic PLANNING is allowed; probabilistic final OUTPUT is not (Constitution Principle 3).
+ * The produced object is validated against the kit's Standard Schema (`req.outputSchema`, Zod).
+ * On failure a BOUNDED repair loop runs (`RepairPolicy.maxAttempts`); on exhaustion the request is
+ * REJECTED with a fatal `validation-exhausted` error — a structurally invalid object NEVER passes
+ * through to the client (FR-005, edge case, quickstart §6).
+ *
+ * TODO(C2 — spec Clarification 2): `maxAttempts` is provisional (research.md C2, config.ts
+ *   DEFAULT_REPAIR_POLICY). The doc says "validate / repair" with no limit; routed to Governance.
+ */
+
+import { validate as runStandardValidate } from "@cloc/core";
+import type { StandardSchemaV1 } from "./tokens.js";
+import type { RepairPolicy } from "./config.js";
+import { AgentError } from "./gateway.js";
+
+/** One validation failure (mirrors the Standard-Schema issue shape). */
+export interface ValidationIssue {
+  message: string;
+  path?: ReadonlyArray<PropertyKey | { key: PropertyKey }>;
+}
+
+/** Outcome of one validate pass. */
+export type ValidateOutcome<T> =
+  | { ok: true; value: T }
+  | { ok: false; issues: ReadonlyArray<ValidationIssue> };
+
+/** Run the kit schema's own validator once (no repair). Async-normalized. */
+export async function validateOnce<T>(
+  schema: StandardSchemaV1<unknown, T>,
+  candidate: unknown,
+): Promise<ValidateOutcome<T>> {
+  const result = await runStandardValidate(schema, candidate);
+  if (result.issues === undefined) {
+    return { ok: true, value: result.value };
+  }
+  return { ok: false, issues: result.issues };
+}
+
+/** Reported to the trace/agent on each repair attempt (data-model §6 events). */
+export interface ValidateEvents {
+  onValidate?(ok: boolean): void;
+  onRepair?(attempt: number, ok: boolean): void;
+}
+
+/**
+ * Validate `initial`; if invalid, ask `repair(issues, attempt)` for a corrected candidate, up to
+ * `policy.maxAttempts` times. The first valid candidate is returned. On exhaustion, REJECT with a
+ * fatal `validation-exhausted` error — never return an invalid object (FR-005, NFR-001).
+ *
+ * `repair` is injected by the Agent: it re-prompts the model with the validation issues. Returning
+ * `undefined` (the model gave up / no repair channel) short-circuits to rejection.
+ */
+/** How many issue messages to surface in the rejection summary (the rest are summarized as a count). */
+export const ISSUE_SUMMARY_LIMIT = 3;
+
+export async function validateOrRepair<T>(args: {
+  schema: StandardSchemaV1<unknown, T>;
+  initial: unknown;
+  policy: RepairPolicy;
+  repair: (issues: ReadonlyArray<ValidationIssue>, attempt: number) => Promise<unknown | undefined>;
+  events?: ValidateEvents;
+}): Promise<T> {
+  const { schema, initial, policy, repair, events } = args;
+
+  // A non-finite / negative bound is a config error; clamp to a sane floor so the loop is finite
+  // and at least validates the original once (never an infinite or skipped loop). Defaults preserve
+  // current behavior for the documented `maxAttempts >= 1` configs.
+  const maxAttempts = Number.isFinite(policy.maxAttempts) ? Math.max(0, Math.trunc(policy.maxAttempts)) : 0;
+
+  let candidate: unknown = initial;
+  let lastIssues: ReadonlyArray<ValidationIssue> = [];
+
+  // attempt 0 is the original; attempts 1..maxAttempts are repairs.
+  for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+    const outcome = await validateOnce(schema, candidate);
+    const ok = outcome.ok;
+    if (attempt === 0) events?.onValidate?.(ok);
+    else events?.onRepair?.(attempt, ok);
+
+    if (outcome.ok) return outcome.value;
+    lastIssues = outcome.issues;
+
+    if (attempt === maxAttempts) break; // bound reached → reject below
+    const next = await repair(outcome.issues, attempt + 1);
+    if (next === undefined) break; // no repair produced → reject
+    candidate = next;
+  }
+
+  // onExhaustion is "reject" by contract; invalid output is never passed through (FR-005).
+  throw new AgentError(
+    "validation-exhausted",
+    `output failed kit-schema validation after ${maxAttempts} repair attempt(s): ${summarizeIssues(lastIssues)}`,
+    true,
+  );
+}
+
+/**
+ * Summarize validation issues for the rejection message: the first {@link ISSUE_SUMMARY_LIMIT}
+ * messages joined, plus a `(+N more)` tail when there are more. Each message is annotated with its
+ * dotted path when present so the failure is actionable (e.g. `title: Required`).
+ */
+function summarizeIssues(issues: ReadonlyArray<ValidationIssue>): string {
+  if (issues.length === 0) return "(no issue detail reported)";
+  const head = issues.slice(0, ISSUE_SUMMARY_LIMIT).map(formatIssue).join("; ");
+  const extra = issues.length - ISSUE_SUMMARY_LIMIT;
+  return extra > 0 ? `${head} (+${extra} more)` : head;
+}
+
+/** Format one issue as `path: message` (or just `message` when it has no path). */
+function formatIssue(issue: ValidationIssue): string {
+  const path = (issue.path ?? [])
+    .map((seg) => (typeof seg === "object" && seg !== null ? String(seg.key) : String(seg)))
+    .join(".");
+  return path ? `${path}: ${issue.message}` : issue.message;
+}