@cloc/provider-ai-sdk 0.1.0

package/dist/tool-loop.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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 type { ToolSet as AiToolSet, StopCondition as AiStopCondition, PrepareStepFunction, LanguageModel } from "ai";
+import type { AgentTool } from "./request.js";
+import type { StopCondition, PrepareStep, StepDirective, PolicyGateHook, CoreToolSet } from "./tokens.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;
+};
+/**
+ * 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 declare 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 declare function buildToolSet(tools: ReadonlyArray<AgentTool>, onEvent: (event: LoopEvent) => void, gate?: PolicyGateHook): AiToolSet;
+/**
+ * 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 declare function buildAgenticToolSet(tools: CoreToolSet | undefined, onEvent: (event: LoopEvent) => void, gate: PolicyGateHook): AiToolSet;
+/** The v6 multi-step stop condition (replaces the removed `maxSteps`). Legacy single-turn default. */
+export declare function stopAfter(maxSteps?: number): AiStopCondition<AiToolSet>;
+/**
+ * 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 declare function toAiStopWhen(stopWhen: StopCondition | undefined, fallbackSteps?: number): AiStopCondition<AiToolSet>;
+/**
+ * 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 declare function toAiPrepareStep(prepareStep: PrepareStep | undefined, resolveModel: (directive: StepDirective) => PrepareStepResultModel | undefined, onDirective?: (step: number, directive: StepDirective) => void): PrepareStepFunction<AiToolSet> | undefined;
+/** The v6 `LanguageModel` a per-step model swap resolves to (kept vendor-internal). */
+export type PrepareStepResultModel = LanguageModel;
+//# sourceMappingURL=tool-loop.d.ts.map

package/dist/tool-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loop.d.ts","sourceRoot":"","sources":["../src/tool-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EACV,OAAO,IAAI,SAAS,EAEpB,aAAa,IAAI,eAAe,EAChC,mBAAmB,EAEnB,aAAa,EACd,MAAM,IAAI,CAAC;AACZ,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,aAAa,EACb,cAAc,EACd,WAAW,EAEZ,MAAM,aAAa,CAAC;AAGrB,wEAAwE;AACxE,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAwC3D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,EAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,EACnC,IAAI,CAAC,EAAE,cAAc,GACpB,SAAS,CAeX;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,EACnC,IAAI,EAAE,cAAc,GACnB,SAAS,CAOX;AA2BD,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,QAAQ,GAAE,MAA0B,GAAG,eAAe,CAAC,SAAS,CAAC,CAE1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,aAAa,GAAE,MAA0B,GACxC,eAAe,CAAC,SAAS,CAAC,CAkB5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,YAAY,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,sBAAsB,GAAG,SAAS,EAC9E,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,KAAK,IAAI,GAC7D,mBAAmB,CAAC,SAAS,CAAC,GAAG,SAAS,CAmB5C;AAeD,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC"}

package/dist/tool-loop.js

@@ -0,0 +1,210 @@
+/**
+ * @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 { frameToolResultAsData } from "./safety.js";
+/**
+ * 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, 
+// 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, onEvent, gate) {
+    return async (args) => {
+        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, onEvent, gate) {
+    const set = {};
+    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,
+            // 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, onEvent, gate) {
+    if (!tools)
+        return {};
+    const set = {};
+    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, def, onEvent, gate) {
+    const base = {
+        ...(def.description !== undefined ? { description: def.description } : {}),
+        inputSchema: def.inputSchema,
+    };
+    // 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" };
+    }
+    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 = DEFAULT_MAX_STEPS) {
+    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, fallbackSteps = DEFAULT_MAX_STEPS) {
+    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 = 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, resolveModel, onDirective) {
+    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 = {};
+        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 : 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) {
+    return typeof choice === "string"
+        ? choice
+        : { type: "tool", toolName: choice.tool };
+}
+//# sourceMappingURL=tool-loop.js.map

package/dist/tool-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loop.js","sourceRoot":"","sources":["../src/tool-loop.ts"],"names":[],"mappings":"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"}

package/dist/trace.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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 declare const NOOP_SPAN: SpanSink;
+/**
+ * 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 declare function startAgentSpan(context: AgentGenerateContext, start?: (name: "agent.generate", context: AgentGenerateContext) => SpanSink): SpanSink;
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wEAAwE;AACxE,MAAM,WAAW,uBAAuB;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,8FAA8F;AAC9F,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;CACpB;AAED,wEAAwE;AACxE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,uBAAuB,GAAG,oBAAoB,CAAC,GAAG,IAAI,CAAC;IACpF,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,sEAAsE;IACtE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,GAAG,IAAI,IAAI,CAAC;CACb;AAED,4EAA4E;AAC5E,eAAO,MAAM,SAAS,EAAE,QAKvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,oBAAoB,EAC7B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,KAAK,QAAQ,GAC1E,QAAQ,CAKV"}

package/dist/trace.js

@@ -0,0 +1,39 @@
+/**
+ * @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.
+ */
+/** A no-op sink — used when no tracer is wired (the adapter still runs). */
+export const NOOP_SPAN = {
+    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, start) {
+    if (!start)
+        return NOOP_SPAN;
+    const span = start("agent.generate", context);
+    span.setAttributes(context);
+    return span;
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA+CH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,SAAS,GAAa;IACjC,aAAa,KAAI,CAAC;IAClB,QAAQ,KAAI,CAAC;IACb,WAAW,KAAI,CAAC;IAChB,GAAG,KAAI,CAAC;CACT,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA6B,EAC7B,KAA2E;IAE3E,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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 type { StandardSchemaV1 } from "./tokens.js";
+import type { RepairPolicy } from "./config.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 declare function validateOnce<T>(schema: StandardSchemaV1<unknown, T>, candidate: unknown): Promise<ValidateOutcome<T>>;
+/** 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 declare const ISSUE_SUMMARY_LIMIT = 3;
+export declare 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>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,GAAG;QAAE,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,oCAAoC;AACpC,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,CAAA;CAAE,CAAC;AAE1D,6EAA6E;AAC7E,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,EACpC,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAM7B;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wGAAwG;AACxG,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE;IAC9C,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAClG,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,GAAG,OAAO,CAAC,CAAC,CAAC,CAiCb"}

package/dist/validate.js

@@ -0,0 +1,81 @@
+/**
+ * @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 { AgentError } from "./gateway.js";
+/** Run the kit schema's own validator once (no repair). Async-normalized. */
+export async function validateOnce(schema, candidate) {
+    const result = await runStandardValidate(schema, candidate);
+    if (result.issues === undefined) {
+        return { ok: true, value: result.value };
+    }
+    return { ok: false, issues: result.issues };
+}
+/**
+ * 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(args) {
+    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 = initial;
+    let lastIssues = [];
+    // 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) {
+    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) {
+    const path = (issue.path ?? [])
+        .map((seg) => (typeof seg === "object" && seg !== null ? String(seg.key) : String(seg)))
+        .join(".");
+    return path ? `${path}: ${issue.message}` : issue.message;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}