@cloc/provider-ai-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cloc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/agent.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @cloc/provider-ai-sdk · agent.ts — `AiSdkAgent`, the default AgentProvider over AI SDK v6
+ * (FR-002, FR-003, FR-004, data-model §1, contracts/agent-provider.ts).
+ *
+ * Implements the vendor-free core contract `generate(p, o?) → Promise<Output>` and
+ * `stream(p, o?) → AsyncIterable<Delta>` by composing: gateway routing + failover (gateway.ts),
+ * the budgeted render-time tool loop (tool-loop.ts), the `Output.object` structured path
+ * (output.ts), the validate-or-repair boundary (validate.ts), partial-object streaming (stream.ts),
+ * the `agent.generate` trace subtree (trace.ts), and data-not-instructions safety (safety.ts).
+ *
+ * v2 (027-agentic-primitives §16b): `generate()`/`stream()` may run a BUDGETED AI SDK 6
+ * `ToolLoopAgent` loop (`call → execute-tools → feed-results → repeat`) that surfaces the three
+ * OPTIONAL, GATED primitives from `GenOpts` — Skills (progressive disclosure; only level-1 metadata
+ * enters the prompt), Memory (the Anthropic memory-tool interface, `unstorage`-backed), and Tools
+ * (the three sources, joined to the loop). The loop is bounded by `stopWhen` (the SAME trajectory
+ * budget as the `0` console agent, §9.1) and shaped per-step by `prepareStep`; EVERY tool/skill/
+ * memory access clears the §58 policy gate BEFORE execution, and a denial DEGRADES (FR-014/FR-021).
+ * When none of the primitives are set the render is the plain pre-027 path (FR-002, zero added cost).
+ *
+ * No AI SDK / AI Gateway type crosses the public signature — they live ONLY inside this package
+ * (FR-002, Principle 8). The model is a swappable FIELD (GenOpts.model), never the contract.
+ *
+ * AI SDK v6 surface (verified against the installed ai@6.0.195 .d.ts, not stale memory):
+ *   - `generateText({ model, output: Output.object({ schema }), prompt|messages, tools, stopWhen,
+ *      prepareStep, maxOutputTokens, seed, abortSignal })` → `result.output` (typed; the older
+ *      `result.experimental_output` is now `@deprecated` — we read the stable name first and fall
+ *      back to the experimental/`output`-less alias so a rename in EITHER direction can't crash us).
+ *   - `streamText({ ...same... })` → `result.partialOutputStream` (the `experimental_*` alias is
+ *      `@deprecated`), `result.output` (a Promise of the final typed object), `result.fullStream`.
+ *   - `maxTokens` is `maxOutputTokens`; `maxSteps` is `stopWhen: stepCountIs(n)`; the other stop
+ *      conditions are `hasToolCall(name)` / `isLoopFinished()`; `prepareStep({ stepNumber, steps,
+ *      model, messages }) => { model?, activeTools?, toolChoice? }` does per-step engineering;
+ *      `generateObject` is deprecated in favor of `output: Output.object(...)` (FR-013).
+ *   - `result.usage` is a `LanguageModelUsage` (`{ inputTokens, outputTokens, totalTokens,
+ *      inputTokenDetails.cacheReadTokens, ... }`); on the streaming result it is a `Promise`.
+ */
+import type { AgentProvider, GenOpts, Prompt, Output, Delta } from "./tokens.js";
+import type { PolicyGateHook } from "./tokens.js";
+import type { AgentConfig } from "./config.js";
+import { type SecretHandle } from "./secrets.js";
+import { type SpanSink, type AgentGenerateContext } from "./trace.js";
+/** Host hooks the kernel supplies at boot (least-privilege; never read from cloc.yml). */
+export interface AgentDeps {
+    /** The parsed `agent:` config (config.ts). */
+    config: AgentConfig;
+    /** By-name handle to the gateway credential (secrets.ts) — resolved lazily, granted at boot. */
+    secret: SecretHandle;
+    /** Optional OTel span opener the host backs with its real tracer (trace.ts). */
+    startSpan?: (name: "agent.generate", context: AgentGenerateContext) => SpanSink;
+    /**
+     * The §58 policy-before-execution gate every render-time PRIMITIVE access (tool / skill / memory)
+     * clears BEFORE execution (027-agentic-primitives FR-014, FR-021; §58). Injected by the kernel
+     * from 016-policy-gate; when absent the adapter falls back to {@link ALLOW_ALL_GATE} so the seam
+     * is exercisable without 016 present (tests/conformance ONLY — a real deployment injects 016's
+     * gate). A denial DEGRADES the render (proceeds without that capability), never bypasses.
+     */
+    gate?: PolicyGateHook;
+    /**
+     * OPTIONAL override for how a repair re-prompt is framed from the base prompt + the validation
+     * issues. Defaults to {@link defaultRepairPrompt} (the prior, current behavior: the issues are
+     * appended as an inert `<validation-issues>` data block, FR-005). A host can swap a richer
+     * strategy (e.g. per-kit guidance) WITHOUT touching the adapter; the default preserves behavior.
+     */
+    frameRepairPrompt?: (args: {
+        basePrompt: string;
+        issues: unknown;
+        attempt: number;
+    }) => string;
+}
+/**
+ * The default repair re-prompt framer: append the validation issues as an inert, clearly-delimited
+ * DATA block (never as instructions the model could be steered by — FR-015) plus a terse directive
+ * to return a corrected object. Extracted so {@link AiSdkAgent.generate} and `stream` share ONE
+ * framing and a host can override it via {@link AgentDeps.frameRepairPrompt} (additive seam).
+ */
+export declare function defaultRepairPrompt(args: {
+    basePrompt: string;
+    issues: unknown;
+    attempt: number;
+}): string;
+/**
+ * The reference Agent. EXACTLY ONE AgentProvider wins per environment, resolved by token (FR-010).
+ * Constructed once at boot from the kernel-supplied {@link AgentDeps}; the request path never
+ * re-decides the Agent (§75.3).
+ */
+export declare class AiSdkAgent implements AgentProvider {
+    #private;
+    private readonly deps;
+    constructor(deps: AgentDeps);
+    generate(p: Prompt, o?: GenOpts): Promise<Output>;
+    stream(p: Prompt, o?: GenOpts): AsyncIterable<Delta>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,aAAa,CAAC;AAGjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,KAAK,YAAY,EAAqB,MAAM,cAAc,CAAC;AAcpE,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAUpB,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,MAAM,EAAE,WAAW,CAAC;IACpB,gGAAgG;IAChG,MAAM,EAAE,YAAY,CAAC;IACrB,gFAAgF;IAChF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,KAAK,QAAQ,CAAC;IAChF;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CAChG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAO1G;AAaD;;;;GAIG;AACH,qBAAa,UAAW,YAAW,aAAa;;IAIlC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,SAAS;IAkFtC,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IA+CvD,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC;CA0HrD"}

package/dist/agent.js

@@ -0,0 +1,359 @@
+/**
+ * @cloc/provider-ai-sdk · agent.ts — `AiSdkAgent`, the default AgentProvider over AI SDK v6
+ * (FR-002, FR-003, FR-004, data-model §1, contracts/agent-provider.ts).
+ *
+ * Implements the vendor-free core contract `generate(p, o?) → Promise<Output>` and
+ * `stream(p, o?) → AsyncIterable<Delta>` by composing: gateway routing + failover (gateway.ts),
+ * the budgeted render-time tool loop (tool-loop.ts), the `Output.object` structured path
+ * (output.ts), the validate-or-repair boundary (validate.ts), partial-object streaming (stream.ts),
+ * the `agent.generate` trace subtree (trace.ts), and data-not-instructions safety (safety.ts).
+ *
+ * v2 (027-agentic-primitives §16b): `generate()`/`stream()` may run a BUDGETED AI SDK 6
+ * `ToolLoopAgent` loop (`call → execute-tools → feed-results → repeat`) that surfaces the three
+ * OPTIONAL, GATED primitives from `GenOpts` — Skills (progressive disclosure; only level-1 metadata
+ * enters the prompt), Memory (the Anthropic memory-tool interface, `unstorage`-backed), and Tools
+ * (the three sources, joined to the loop). The loop is bounded by `stopWhen` (the SAME trajectory
+ * budget as the `0` console agent, §9.1) and shaped per-step by `prepareStep`; EVERY tool/skill/
+ * memory access clears the §58 policy gate BEFORE execution, and a denial DEGRADES (FR-014/FR-021).
+ * When none of the primitives are set the render is the plain pre-027 path (FR-002, zero added cost).
+ *
+ * No AI SDK / AI Gateway type crosses the public signature — they live ONLY inside this package
+ * (FR-002, Principle 8). The model is a swappable FIELD (GenOpts.model), never the contract.
+ *
+ * AI SDK v6 surface (verified against the installed ai@6.0.195 .d.ts, not stale memory):
+ *   - `generateText({ model, output: Output.object({ schema }), prompt|messages, tools, stopWhen,
+ *      prepareStep, maxOutputTokens, seed, abortSignal })` → `result.output` (typed; the older
+ *      `result.experimental_output` is now `@deprecated` — we read the stable name first and fall
+ *      back to the experimental/`output`-less alias so a rename in EITHER direction can't crash us).
+ *   - `streamText({ ...same... })` → `result.partialOutputStream` (the `experimental_*` alias is
+ *      `@deprecated`), `result.output` (a Promise of the final typed object), `result.fullStream`.
+ *   - `maxTokens` is `maxOutputTokens`; `maxSteps` is `stopWhen: stepCountIs(n)`; the other stop
+ *      conditions are `hasToolCall(name)` / `isLoopFinished()`; `prepareStep({ stepNumber, steps,
+ *      model, messages }) => { model?, activeTools?, toolChoice? }` does per-step engineering;
+ *      `generateObject` is deprecated in favor of `output: Output.object(...)` (FR-013).
+ *   - `result.usage` is a `LanguageModelUsage` (`{ inputTokens, outputTokens, totalTokens,
+ *      inputTokenDetails.cacheReadTokens, ... }`); on the streaming result it is a `Promise`.
+ */
+import { generateText, streamText } from "ai";
+import { ALLOW_ALL_GATE } from "./tokens.js";
+import { modelRefToString } from "@cloc/core";
+import { resolveGateway, withFailover, AgentError } from "./gateway.js";
+import { resolveGatewayKey } from "./secrets.js";
+import { outputSpecFor, makeStructuredOutput } from "./output.js";
+import { validateOrRepair } from "./validate.js";
+import { buildToolSet, buildAgenticToolSet, toAiStopWhen, toAiPrepareStep, } from "./tool-loop.js";
+import { buildMemoryTools } from "./memory-tool.js";
+import { frameSkillsForPrompt } from "./skills-loader.js";
+import { frameGroundingAsData, collectProvenance } from "./safety.js";
+import { startAgentSpan, } from "./trace.js";
+import { chunkToDelta, loopEventToChunk, partialChunk, toCoreOutput, } from "./stream.js";
+import { toAgentTurn } from "./request.js";
+/**
+ * The default repair re-prompt framer: append the validation issues as an inert, clearly-delimited
+ * DATA block (never as instructions the model could be steered by — FR-015) plus a terse directive
+ * to return a corrected object. Extracted so {@link AiSdkAgent.generate} and `stream` share ONE
+ * framing and a host can override it via {@link AgentDeps.frameRepairPrompt} (additive seam).
+ */
+export function defaultRepairPrompt(args) {
+    const { basePrompt, issues, attempt } = args;
+    return (`${basePrompt}\n\n` +
+        `<validation-issues attempt="${attempt}">${JSON.stringify(issues)}</validation-issues>\n` +
+        `Return a corrected object that satisfies the schema.`);
+}
+/** The default kit version stamped on the Output meta when the runtime does not pin one. */
+const UNKNOWN_KIT_VERSION = "unknown";
+/**
+ * The reference Agent. EXACTLY ONE AgentProvider wins per environment, resolved by token (FR-010).
+ * Constructed once at boot from the kernel-supplied {@link AgentDeps}; the request path never
+ * re-decides the Agent (§75.3).
+ */
+export class AiSdkAgent {
+    deps;
+    #gatewayKey;
+    #keyResolved = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The §58 gate every primitive access clears; defaults to ALLOW_ALL only when none is wired. */
+    get #gate() {
+        return this.deps.gate ?? ALLOW_ALL_GATE;
+    }
+    /** Resolve the gateway credential BY NAME, once, lazily (FR-009). */
+    async #gateway() {
+        if (!this.#keyResolved) {
+            this.#gatewayKey = await resolveGatewayKey(this.deps.secret);
+            this.#keyResolved = true;
+        }
+        return resolveGateway(this.deps.config, this.#gatewayKey);
+    }
+    #span(turn) {
+        const ctx = {
+            "cloc.data_version": String(turn.providerOptions?.["dataVersion"] ?? ""),
+            "cloc.kit_version": String(turn.providerOptions?.["kitVersion"] ?? UNKNOWN_KIT_VERSION),
+            "cloc.tier": turn.tier,
+            ...(turn.seed !== undefined ? { "cloc.seed": String(turn.seed) } : {}),
+        };
+        return startAgentSpan(ctx, this.deps.startSpan);
+    }
+    /**
+     * The shared `generateText`/`streamText` option base for a turn (vendor types stay internal).
+     *
+     * Assembles the budgeted render-time tool loop (027-agentic-primitives §16b.3): the loop's tool
+     * set is the union of (1) the legacy per-turn `tools`, (2) the 027 agentic `GenOpts.tools` from
+     * all three sources (`plugin`/`capability`/`wired`, FR-012), and (3) the memory-tool interface
+     * when memory is enabled (§16b.2) — each GATED by the §58 gate before execution (FR-014). The
+     * budget is `stopWhen` mapped from the core trajectory budget (default `stepCountIs(N)`, §9.1,
+     * FR-013); `prepareStep` does per-step context engineering (model swap / activeTools / toolChoice,
+     * FR-011). Skill metadata (level-1 only) is prepended to the prompt; the body/bundled load lazily.
+     * When NONE of the primitives are set the loop is the plain pre-027 path (FR-002, zero added cost).
+     */
+    #callOptions(turn, onEvent, gw) {
+        const gate = this.#gate;
+        // (1) legacy per-turn tools (gate-checked) + (2) agentic GenOpts.tools (3 sources) + (3) memory.
+        const tools = {
+            ...buildToolSet(turn.tools, onEvent, gate),
+            ...buildAgenticToolSet(turn.agenticTools, onEvent, gate),
+            ...buildMemoryTools(turn.memory, gate, onEvent),
+        };
+        const prepareStep = toAiPrepareStep(turn.prepareStep, (d) => this.#resolveStepModel(d, gw));
+        return {
+            output: outputSpecFor(turn.outputSchema),
+            tools,
+            // The trajectory budget bounds the loop so it can never thrash unbounded (§9.1, FR-013).
+            stopWhen: toAiStopWhen(turn.stopWhen),
+            ...(prepareStep !== undefined ? { prepareStep } : {}),
+            prompt: this.#composePrompt(turn),
+            ...(turn.maxTokens !== undefined ? { maxOutputTokens: turn.maxTokens } : {}),
+            ...(turn.seed !== undefined ? { seed: turn.seed } : {}),
+            ...(turn.signal !== undefined ? { abortSignal: turn.signal } : {}),
+            ...(turn.providerOptions !== undefined ? { providerOptions: turn.providerOptions } : {}),
+        };
+    }
+    /** Resolve a `prepareStep` per-step model swap (a core `ModelRef`) to the routed v6 model. */
+    #resolveStepModel(directive, gw) {
+        if (directive.model === undefined)
+            return undefined;
+        const id = modelRefToString(directive.model);
+        return id ? gw.model(id) : undefined;
+    }
+    /**
+     * Frame the intent + grounded facts + level-1 skill metadata as a prompt where grounding is inert
+     * DATA (FR-015) and skills disclose only `name`+`description` (§16b.1 — the body is NOT in the
+     * prompt until activation; FR-005). When no skills/grounding are present this is just the intent.
+     */
+    #composePrompt(turn) {
+        const intent = typeof turn.intent === "string" ? turn.intent : JSON.stringify(turn.intent);
+        const data = frameGroundingAsData(turn.grounding);
+        const skills = turn.skills ? frameSkillsForPrompt(turn.skills) : "";
+        return [intent, skills, data].filter((s) => s.length > 0).join("\n\n");
+    }
+    // --- AgentProvider.generate ----------------------------------------------
+    async generate(p, o) {
+        const turn = toAgentTurn(p, o, false);
+        const span = this.#span(turn);
+        const events = [];
+        const onEvent = (e) => {
+            events.push(e);
+            span.addEvent(e.kind === "tool-call" ? { name: "tool.call", tool: e.tool } : { name: "tool.result", tool: e.tool });
+        };
+        try {
+            const gw = await this.#gateway();
+            const base = this.#callOptions(turn, onEvent, gw);
+            // Route hosted-first with per-request failover (FR-006/8). Each attempt runs the tool loop
+            // and the Output.object path; the first provider that yields a parseable object wins. An
+            // abort short-circuits the chain (it is a cancel, not a provider failure; conformance C1).
+            const { value: raw, modelId, hop } = await withFailover(gw, async (model) => generateText({ model, ...base }), undefined, turn.signal !== undefined ? { signal: turn.signal } : undefined);
+            // Validate-or-repair against the kit schema; re-prompt the SAME provider on repair (FR-005).
+            const plan = await validateOrRepair({
+                schema: turn.outputSchema,
+                initial: readOutput(raw),
+                policy: this.deps.config.repair,
+                events: {
+                    onValidate: (ok) => span.addEvent({ name: "validate", ok }),
+                    onRepair: (attempt, ok) => span.addEvent({ name: "repair", attempt, ok }),
+                },
+                repair: (issues, attempt) => this.#repair(base, gw, modelId, issues, attempt),
+            });
+            const structured = this.#finish(turn, plan, span, { modelId, hop, usage: readUsage(raw) });
+            return toCoreOutput(structured, turn.outputSchema);
+        }
+        catch (err) {
+            this.#fail(span, err);
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    // --- AgentProvider.stream ------------------------------------------------
+    stream(p, o) {
+        const turn = toAgentTurn(p, o, true);
+        const self = this;
+        return {
+            async *[Symbol.asyncIterator]() {
+                const span = self.#span(turn);
+                const queue = [];
+                const onEvent = (e) => {
+                    queue.push(loopEventToChunk(e));
+                    span.addEvent(e.kind === "tool-call" ? { name: "tool.call", tool: e.tool } : { name: "tool.result", tool: e.tool });
+                };
+                try {
+                    const gw = await self.#gateway();
+                    const base = self.#callOptions(turn, onEvent, gw);
+                    // Failover for the streaming path: bind the first provider that starts a stream. An
+                    // abort short-circuits the chain (cancel, not a provider failure; conformance C1).
+                    const { value: result, modelId, hop } = await withFailover(gw, async (model) => streamText({ model, ...base }), undefined, turn.signal !== undefined ? { signal: turn.signal } : undefined);
+                    // Drain any tool events captured before the first partial, then stream partial objects.
+                    for (const c of queue.splice(0))
+                        yield* emit(c);
+                    for await (const snap of partialOutputStream(result)) {
+                        for (const c of queue.splice(0))
+                            yield* emit(c);
+                        yield* emit(partialChunk(snap));
+                    }
+                    for (const c of queue.splice(0))
+                        yield* emit(c);
+                    // Terminal: validate-or-repair the completed object, then emit the single `final`.
+                    const finalObject = await readFinalOutput(result);
+                    const plan = await validateOrRepair({
+                        schema: turn.outputSchema,
+                        initial: finalObject,
+                        policy: self.deps.config.repair,
+                        events: {
+                            onValidate: (ok) => span.addEvent({ name: "validate", ok }),
+                            onRepair: (attempt, ok) => span.addEvent({ name: "repair", attempt, ok }),
+                        },
+                        // Streaming repair re-runs non-streamed against the same provider (bounded).
+                        repair: (issues, attempt) => self.#repair(base, gw, modelId, issues, attempt),
+                    });
+                    const structured = self.#finish(turn, plan, span, { modelId, hop, usage: await readStreamUsage(result) });
+                    const delta = chunkToDelta({ kind: "final", output: structured }, turn.outputSchema);
+                    if (delta)
+                        yield delta;
+                }
+                catch (err) {
+                    // Invalidate any streamed partial: surface the error by REJECTING — never a fake `final`
+                    // the runtime could mistake for completion (edge case, core Delta contract).
+                    self.#fail(span, err);
+                    throw err;
+                }
+                finally {
+                    span.end();
+                }
+                function* emit(chunk) {
+                    const d = chunkToDelta(chunk, turn.outputSchema);
+                    if (d)
+                        yield d;
+                }
+            },
+        };
+    }
+    // --- shared repair / finish / fail ---------------------------------------
+    /**
+     * The shared validate-or-repair repair channel: re-prompt the SAME provider (`modelId`) with the
+     * validation issues framed as an inert data block, NON-streamed, honoring the turn's abort signal.
+     * Used by BOTH `generate()` and `stream()` so the two paths repair identically (DRY; FR-005). The
+     * framing is overridable via {@link AgentDeps.frameRepairPrompt}; the default reproduces the prior
+     * inline behavior exactly.
+     */
+    async #repair(base, gw, modelId, issues, attempt) {
+        const frame = this.deps.frameRepairPrompt ?? defaultRepairPrompt;
+        const repaired = await generateText({
+            model: gw.model(modelId),
+            ...base,
+            prompt: frame({ basePrompt: base.prompt, issues, attempt }),
+        });
+        return readOutput(repaired);
+    }
+    #finish(turn, plan, span, routed) {
+        const [provider, ...rest] = routed.modelId.split("/");
+        const usage = routed.usage;
+        span.setAttributes({
+            "gateway.provider": provider ?? routed.modelId,
+            "gateway.model": rest.join("/") || routed.modelId,
+            "gateway.fallback": routed.hop,
+            "cost.usd": usage?.costUsd ?? 0,
+            ...(usage?.inputTokens !== undefined ? { "prompt.tokens": usage.inputTokens } : {}),
+            ...(usage?.outputTokens !== undefined ? { "output.tokens": usage.outputTokens } : {}),
+            ...(usage?.totalTokens !== undefined ? { "total.tokens": usage.totalTokens } : {}),
+            ...(usage?.cachedInputTokens !== undefined ? { "cache.read.tokens": usage.cachedInputTokens } : {}),
+        });
+        return makeStructuredOutput({
+            plan,
+            provenance: collectProvenance(turn.grounding),
+            kitVersion: String(turn.providerOptions?.["kitVersion"] ?? UNKNOWN_KIT_VERSION),
+            ...(turn.seed !== undefined ? { seed: String(turn.seed) } : {}),
+        });
+    }
+    #fail(span, err) {
+        const code = err instanceof AgentError ? err.code : "tool-failed";
+        const message = err instanceof Error ? err.message : String(err);
+        span.recordError(code, message);
+    }
+}
+/**
+ * Read the typed object from a non-streaming v6 result. v6 exposes the stable `result.output`; the
+ * older `result.experimental_output` is `@deprecated`. We read the STABLE name first and fall back
+ * to the deprecated alias (and `undefined`-safe) so a rename in either direction can't crash us.
+ */
+function readOutput(result) {
+    const r = result;
+    return r.output ?? r.experimental_output;
+}
+/** Map a vendor `LanguageModelUsage` + provider metadata to the adapter's {@link ReadUsage}. */
+function mapUsage(usage, cost) {
+    if (!usage && cost === undefined)
+        return undefined;
+    return {
+        ...(usage?.inputTokens !== undefined ? { inputTokens: usage.inputTokens } : {}),
+        ...(usage?.outputTokens !== undefined ? { outputTokens: usage.outputTokens } : {}),
+        ...(usage?.totalTokens !== undefined ? { totalTokens: usage.totalTokens } : {}),
+        ...(usage?.inputTokenDetails?.cacheReadTokens !== undefined
+            ? { cachedInputTokens: usage.inputTokenDetails.cacheReadTokens }
+            : {}),
+        ...(cost !== undefined ? { costUsd: cost } : {}),
+    };
+}
+/** Read token/cost usage from a non-streaming v6 result, when present (TODO(C3): mandated-metric set). */
+function readUsage(result) {
+    const r = result;
+    return mapUsage(r.usage, r.providerMetadata?.gateway?.cost);
+}
+/**
+ * The v6 partial-object stream: the stable `result.partialOutputStream` (the `experimental_*` alias
+ * is `@deprecated`). Each snapshot is a partial of the kit plan — i.e. an object — so we read it as a
+ * partial record (assignable to `Partial<unknown>` for {@link partialChunk}; a bare `unknown` is not).
+ * We prefer the stable name and fall back to the deprecated alias, then an empty stream.
+ */
+function partialOutputStream(result) {
+    const r = result;
+    return r.partialOutputStream ?? r.experimental_partialOutputStream ?? EMPTY_PARTIAL_STREAM();
+}
+/** A reusable empty async-iterable for the "no partial stream present" fallback (allocation-light). */
+async function* EMPTY_PARTIAL_STREAM() {
+    /* yields nothing */
+}
+/**
+ * Await the final typed object of a v6 stream result. v6 exposes the stable `result.output` (a
+ * `Promise`); the older `result.experimental_output` is `@deprecated`. We prefer the stable name,
+ * fall back to the deprecated alias, and await whichever is a thenable.
+ */
+async function readFinalOutput(result) {
+    const r = result;
+    const value = r.output ?? r.experimental_output;
+    return isThenable(value) ? await value : value;
+}
+/** Await stream usage (v6 `result.usage` is a Promise on the streaming result). */
+async function readStreamUsage(result) {
+    const r = result;
+    const usage = isThenable(r.usage) ? await r.usage : r.usage;
+    const meta = isThenable(r.providerMetadata) ? await r.providerMetadata : r.providerMetadata;
+    return mapUsage(usage, meta?.gateway?.cost);
+}
+/** True for a thenable (a Promise or Promise-like), narrowing for `await`. */
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.then === "function");
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @cloc/provider-ai-sdk · config.ts — the declarative `cloc.yml` `agent:` slice (data-model §5).
+ *
+ * Selection + tuning is data, never code (Constitution Principle 1; Appendix L.1 — `cloc.yml`
+ * is declarative/non-executable, never `cloc.config.ts`). The model is a FIELD (a gateway
+ * `provider/model` string), changeable with NO adapter-code edit (FR-007, FR-014). The gateway
+ * credential is referenced BY NAME (`secretRef`) — a secret VALUE in `cloc.yml` is rejected
+ * (FR-009, NFR-005, Principle 9).
+ *
+ * TODO(C2 — spec Clarification 2): the bounded-repair `maxAttempts` default below is provisional;
+ *   the design doc names "validate / repair" without a limit. Routed to Governance (research.md C2).
+ * TODO(C1 — spec Clarification 1): whether a built-in default provider/model ships (so the block
+ *   is optional) vs. BYO before the first synthesis request. Routed to Governance (research.md C1).
+ */
+import { z } from "zod";
+/** A gateway `provider/model` selection. Mirrors `cloc.yml` `model: { vendor, name }`. */
+export interface ModelField {
+    /** Gateway provider string, e.g. "anthropic" (a FIELD of the Agent, FR-014). */
+    vendor: string;
+    /** Gateway model string, e.g. "claude-sonnet-4-5". */
+    name: string;
+}
+/** Per-request routing + ordered failover policy (FR-008, data-model §5). */
+export interface GatewayRouting {
+    /** Ordered failover alternates; tried in order after the primary errors. */
+    fallbacks: ModelField[];
+}
+/** Bounded validate/repair policy (NFR-001, data-model §5). */
+export interface RepairPolicy {
+    /** Max repair attempts before the request is rejected. TODO(C2): default is provisional. */
+    maxAttempts: number;
+    /** MUST reject on exhaustion — invalid output is NEVER passed through (FR-005). */
+    onExhaustion: "reject";
+}
+/** The parsed, validated `agent:` block (data-model §5). */
+export interface AgentConfig {
+    /** The AgentProvider token's plugin id; the default is this package. */
+    provider: string;
+    /** The model FIELD — provider/model selection (FR-014). */
+    model: ModelField;
+    /** Optional routing + failover (FR-008). */
+    routing?: GatewayRouting;
+    /** NAME of the gateway credential — resolved by the secrets provider (FR-009). */
+    secretRef: string;
+    /** Bounded validate/repair (NFR-001). Defaulted when absent. */
+    repair: RepairPolicy;
+}
+/** Provisional default repair bound. TODO(C2): routed to Governance (research.md C2). */
+export declare const DEFAULT_REPAIR_POLICY: RepairPolicy;
+/** This plugin's id; also the default `provider` value when the block omits it. */
+export declare const PROVIDER_ID = "provider-ai-sdk";
+/** The raw `agent:` block schema as it appears in `cloc.yml`. */
+export declare const AgentConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodString>;
+    model: z.ZodObject<{
+        vendor: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    routing: z.ZodOptional<z.ZodObject<{
+        fallbacks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            vendor: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    secretRef: z.ZodString;
+    repair: z.ZodOptional<z.ZodObject<{
+        maxAttempts: z.ZodNumber;
+        onExhaustion: z.ZodLiteral<"reject">;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RawAgentConfig = z.input<typeof AgentConfigSchema>;
+/**
+ * Parse + validate a raw `cloc.yml` `agent:` block into a normalized {@link AgentConfig}.
+ * Throws (Zod) on an invalid block — including a `secretRef` that holds a value, not a name.
+ */
+export declare function parseAgentConfig(raw: unknown): AgentConfig;
+/** Render one {@link ModelField} as the gateway `provider/model` string the SDK routes on. */
+export declare function modelFieldToString(field: ModelField): string;
+/**
+ * The ordered list of `provider/model` strings to try: primary first, then failovers, with
+ * consecutive/duplicate entries collapsed so the same provider is never retried twice in a row
+ * (a fallback identical to the primary would only waste a hop). Order is otherwise preserved.
+ */
+export declare function modelChain(config: AgentConfig): string[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,SAAS,EAAE,UAAU,EAAE,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,YAAY,EAAE,QAAQ,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,KAAK,EAAE,UAAU,CAAC;IAClB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,EAAE,YAGnC,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAqC7C,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;iBAM5B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAS1D;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAaxD"}