@cloc/provider-ai-sdk 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@cloc/provider-ai-sdk",
+  "version": "0.1.0",
+  "description": "Default AgentProvider plugin, backed by the Vercel AI SDK v6 (+ AI Gateway, hosted-first). The model is one config field of the Agent, never the contract. Siblings: provider-ai-langchain, provider-ai-claude, provider-ai-open-ai.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "cloc": {
+    "name": "@cloc/provider-ai-sdk",
+    "provides": [
+      "@cloc/core:agent-provider"
+    ],
+    "needs": {
+      "net": [
+        "ai-gateway.vercel.sh"
+      ],
+      "secrets": [
+        "AI_GATEWAY_API_KEY"
+      ]
+    }
+  },
+  "dependencies": {
+    "ai": "^6.0.34",
+    "unstorage": "^1.16.0",
+    "zod": "^4.0.0",
+    "@cloc/plugin": "0.1.0",
+    "@cloc/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/agent.ts

@@ -0,0 +1,487 @@
+/**
+ * @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 type { ToolSet as AiToolSet } from "ai";
+import type { AgentProvider, GenOpts, Prompt, Output, Delta } from "./tokens.js";
+import type { PolicyGateHook, StepDirective } from "./tokens.js";
+import { ALLOW_ALL_GATE } from "./tokens.js";
+import { modelRefToString } from "@cloc/core";
+import type { AgentConfig } from "./config.js";
+import { resolveGateway, withFailover, AgentError, type ResolvedGateway } from "./gateway.js";
+import { type SecretHandle, resolveGatewayKey } from "./secrets.js";
+import { outputSpecFor, makeStructuredOutput, type StructuredOutput } from "./output.js";
+import { validateOrRepair } from "./validate.js";
+import {
+  buildToolSet,
+  buildAgenticToolSet,
+  toAiStopWhen,
+  toAiPrepareStep,
+  type LoopEvent,
+  type PrepareStepResultModel,
+} from "./tool-loop.js";
+import { buildMemoryTools } from "./memory-tool.js";
+import { frameSkillsForPrompt } from "./skills-loader.js";
+import { frameGroundingAsData, collectProvenance } from "./safety.js";
+import {
+  startAgentSpan,
+  type SpanSink,
+  type AgentGenerateContext,
+} from "./trace.js";
+import {
+  chunkToDelta,
+  loopEventToChunk,
+  partialChunk,
+  toCoreOutput,
+  type StreamChunk,
+} from "./stream.js";
+import { toAgentTurn, type AgentTurn } from "./request.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 function defaultRepairPrompt(args: { basePrompt: string; issues: unknown; attempt: number }): string {
+  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 assembled `generateText`/`streamText` option base for a turn (vendor types stay internal).
+ * `prompt` is always present; the rest of the v6 call surface (output/tools/stopWhen/seed/…) rides
+ * along as an opaque record so it can be spread verbatim into a repair re-run. Named so the shared
+ * {@link AiSdkAgent}.#repair channel can take it without re-deriving the inline shape.
+ */
+type CallOptions = { readonly prompt: string } & Record<string, 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 implements AgentProvider {
+  #gatewayKey: string | undefined;
+  #keyResolved = false;
+
+  constructor(private readonly deps: AgentDeps) {}
+
+  /** The §58 gate every primitive access clears; defaults to ALLOW_ALL only when none is wired. */
+  get #gate(): PolicyGateHook {
+    return this.deps.gate ?? ALLOW_ALL_GATE;
+  }
+
+  /** Resolve the gateway credential BY NAME, once, lazily (FR-009). */
+  async #gateway(): Promise<ResolvedGateway> {
+    if (!this.#keyResolved) {
+      this.#gatewayKey = await resolveGatewayKey(this.deps.secret);
+      this.#keyResolved = true;
+    }
+    return resolveGateway(this.deps.config, this.#gatewayKey);
+  }
+
+  #span(turn: AgentTurn): SpanSink {
+    const ctx: AgentGenerateContext = {
+      "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: AgentTurn, onEvent: (e: LoopEvent) => void, gw: ResolvedGateway): CallOptions {
+    const gate = this.#gate;
+    // (1) legacy per-turn tools (gate-checked) + (2) agentic GenOpts.tools (3 sources) + (3) memory.
+    const tools: AiToolSet = {
+      ...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 as never } : {}),
+    } as const;
+  }
+
+  /** Resolve a `prepareStep` per-step model swap (a core `ModelRef`) to the routed v6 model. */
+  #resolveStepModel(directive: StepDirective, gw: ResolvedGateway): PrepareStepResultModel | undefined {
+    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: AgentTurn): string {
+    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: Prompt, o?: GenOpts): Promise<Output> {
+    const turn = toAgentTurn(p, o, false);
+    const span = this.#span(turn);
+    const events: LoopEvent[] = [];
+    const onEvent = (e: LoopEvent): void => {
+      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 as never);
+    } catch (err) {
+      this.#fail(span, err);
+      throw err;
+    } finally {
+      span.end();
+    }
+  }
+
+  // --- AgentProvider.stream ------------------------------------------------
+
+  stream(p: Prompt, o?: GenOpts): AsyncIterable<Delta> {
+    const turn = toAgentTurn(p, o, true);
+    const self = this;
+    return {
+      async *[Symbol.asyncIterator](): AsyncGenerator<Delta> {
+        const span = self.#span(turn);
+        const queue: StreamChunk[] = [];
+        const onEvent = (e: LoopEvent): void => {
+          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<unknown>({ kind: "final", output: structured }, turn.outputSchema as never);
+          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: StreamChunk): Generator<Delta> {
+          const d = chunkToDelta<unknown>(chunk, turn.outputSchema as never);
+          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: CallOptions,
+    gw: ResolvedGateway,
+    modelId: string,
+    issues: unknown,
+    attempt: number,
+  ): Promise<unknown> {
+    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<TPlan>(
+    turn: AgentTurn,
+    plan: TPlan,
+    span: SpanSink,
+    routed: { modelId: string; hop: number; usage?: ReadUsage },
+  ): StructuredOutput<TPlan> {
+    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: SpanSink, err: unknown): void {
+    const code = err instanceof AgentError ? err.code : "tool-failed";
+    const message = err instanceof Error ? err.message : String(err);
+    span.recordError(code, message);
+  }
+}
+
+// --- AI SDK v6 result readers (localized; the only place we touch vendor result shapes) -------
+
+/** The token/cost usage the adapter surfaces to the trace. All fields OPTIONAL (recorded when present). */
+interface ReadUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Total tokens for the turn (v6 `usage.totalTokens`); recorded additively when reported. */
+  totalTokens?: number;
+  /** Cached-prompt-token reads (v6 `usage.inputTokenDetails.cacheReadTokens`); when reported. */
+  cachedInputTokens?: number;
+  /** Per-request cost from the gateway provider metadata (`providerMetadata.gateway.cost`). */
+  costUsd?: number;
+}
+
+/** The vendor result fields the adapter reads, prefer-stable-then-deprecated. Localized to this file. */
+interface VendorUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  inputTokenDetails?: { cacheReadTokens?: number };
+}
+
+/**
+ * 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: unknown): unknown {
+  const r = result as { output?: unknown; experimental_output?: unknown };
+  return r.output ?? r.experimental_output;
+}
+
+/** Map a vendor `LanguageModelUsage` + provider metadata to the adapter's {@link ReadUsage}. */
+function mapUsage(usage: VendorUsage | undefined, cost: number | undefined): ReadUsage | undefined {
+  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: unknown): ReadUsage | undefined {
+  const r = result as { usage?: VendorUsage; providerMetadata?: { gateway?: { cost?: number } } };
+  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: unknown): AsyncIterable<Record<string, unknown>> {
+  const r = result as {
+    partialOutputStream?: AsyncIterable<Record<string, unknown>>;
+    experimental_partialOutputStream?: AsyncIterable<Record<string, unknown>>;
+  };
+  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(): AsyncGenerator<Record<string, unknown>> {
+  /* 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: unknown): Promise<unknown> {
+  const r = result as { output?: Promise<unknown> | unknown; experimental_output?: Promise<unknown> | unknown };
+  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: unknown): Promise<ReadUsage | undefined> {
+  const r = result as {
+    usage?: Promise<VendorUsage> | VendorUsage;
+    providerMetadata?: Promise<{ gateway?: { cost?: number } } | undefined> | { gateway?: { cost?: number } };
+  };
+  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<T>(value: unknown): value is PromiseLike<T> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}