@cloc/provider-ai-sdk 0.1.0

package/src/plugin.ts

@@ -0,0 +1,123 @@
+/**
+ * @cloc/provider-ai-sdk · plugin.ts — the manifest + `provides` wiring (FR-001, FR-010, FR-014,
+ * data-model §7, contracts/cloc-config.schema.json).
+ *
+ * `definePlugin(...)` PROVIDES the `AgentProviderRef` token with `AiSdkAgent`, so the kernel
+ * resolves this as the DEFAULT AgentProvider with no `agent:` block required for resolution
+ * (FR-001). Exactly one AgentProvider wins per environment; selecting a different one by token
+ * replaces this with NO edit to this plugin or @cloc/core (FR-010, NFR-004). The least-privilege
+ * `needs` (gateway host + the named secret) is declared so the kernel grants only those (FR-009).
+ *
+ * Naming carries NO "model" — the token is `AgentProviderRef`, the package is `provider-ai-sdk`,
+ * the impl is `AiSdkAgent` (FR-014). The model is a `cloc.yml` `agent.model` FIELD.
+ *
+ * TODO(C1 — spec Clarification 1): whether a built-in default provider/model ships (so the
+ *   `agent:` block is optional) vs. BYO before the first synthesis request. Routed to Governance.
+ * TODO(T031): the kernel threads the granted secret handle + parsed config through PluginContext
+ *   at boot; until that capability surface lands in @cloc/plugin, the factory reads them off an
+ *   augmented context (see `agentDepsFromContext`) and falls back to ambient resolution.
+ */
+
+import { definePlugin } from "@cloc/plugin";
+import type { ProviderRegistration, PluginContext } from "@cloc/plugin";
+import { AgentProviderRef } from "./tokens.js";
+import type { PolicyGateHook } from "./tokens.js";
+import { AiSdkAgent, type AgentDeps } from "./agent.js";
+import { parseAgentConfig, type AgentConfig, PROVIDER_ID } from "./config.js";
+import { needsFor, GATEWAY_HOST, type SecretHandle, type AgentNeeds } from "./secrets.js";
+import type { SpanSink, AgentGenerateContext } from "./trace.js";
+
+/** This package's name — no "model" in it (FR-014). */
+export const PLUGIN_NAME = "@cloc/provider-ai-sdk";
+
+/**
+ * The boot-time surface the kernel supplies to the provider factory: the parsed `agent:` config,
+ * the granted by-name secret handle, and (optionally) the host's OTel span opener. Mirrors what
+ * T031 will thread through `PluginContext`; modeled here so the factory is typed end-to-end.
+ */
+export interface AgentBootContext {
+  /** Raw `cloc.yml` `agent:` block (parsed + validated here). */
+  agent?: unknown;
+  /** The kernel-granted, by-name secret handle (scoped to the declared `secretRef`). */
+  secret?: SecretHandle;
+  /** Optional OTel span opener backed by the pipeline's tracer (nests under req.trace). */
+  startSpan?: (name: "agent.generate", context: AgentGenerateContext) => SpanSink;
+  /**
+   * The §58 policy-before-execution gate (016-policy-gate) the kernel injects so every render-time
+   * tool/skill/memory access clears it BEFORE execution (027-agentic-primitives FR-014). When the
+   * kernel has not wired 016, the adapter falls back to an allow-all gate (tests/conformance only;
+   * a deny degrades rather than bypasses — FR-021).
+   */
+  gate?: PolicyGateHook;
+  /**
+   * OPTIONAL override for how a repair re-prompt is framed (see {@link AgentDeps.frameRepairPrompt}).
+   * Threaded straight through to the Agent; when absent the adapter's default framing is used.
+   */
+  frameRepairPrompt?: AgentDeps["frameRepairPrompt"];
+}
+
+/** A by-name secret handle that always denies — the safe default before the kernel grants one. */
+function denyingSecret(name: string): SecretHandle {
+  return { name, async resolve() { return undefined; } };
+}
+
+/**
+ * Resolve the boot dependencies for the Agent from the (augmented) plugin context. Parses the
+ * `agent:` block per the config schema and binds the granted secret handle. When the kernel has
+ * not yet threaded these (pre-T031), it falls back to a denying secret + an env-driven config so
+ * the adapter is constructible; a real synthesis request then surfaces a clear secret/config error.
+ */
+export function agentDepsFromContext(ctx: AgentBootContext): AgentDeps {
+  const config: AgentConfig = parseAgentConfig(ctx.agent ?? defaultAgentBlock());
+  const secret = ctx.secret ?? denyingSecret(config.secretRef);
+  return {
+    config,
+    secret,
+    ...(ctx.startSpan ? { startSpan: ctx.startSpan } : {}),
+    // The §58 gate (016) every render-time primitive access clears; allow-all only when unwired.
+    ...(ctx.gate ? { gate: ctx.gate } : {}),
+    // Optional repair-prompt framing override (defaults to the adapter's framing when unset).
+    ...(ctx.frameRepairPrompt ? { frameRepairPrompt: ctx.frameRepairPrompt } : {}),
+  };
+}
+
+/**
+ * A provisional default `agent:` block so the plugin is constructible with zero `cloc.yml` wiring
+ * for resolution (FR-001). It pins NO usable default model — `secretRef` names the gateway key and
+ * `model` MUST be set by the developer before the first synthesis request.
+ * TODO(C1): replace with a shipped default once Governance decides (research.md C1).
+ */
+function defaultAgentBlock(): unknown {
+  return {
+    provider: PROVIDER_ID,
+    model: { vendor: "anthropic", name: "claude-sonnet-4-5" }, // TODO(C1): provisional, not mandated
+    secretRef: "AI_GATEWAY_API_KEY",
+  };
+}
+
+/** The least-privilege resource needs the manifest declares (gateway host + the named secret). */
+export function declaredNeeds(ctx?: AgentBootContext): AgentNeeds {
+  const config = parseAgentConfig(ctx?.agent ?? defaultAgentBlock());
+  return needsFor(config);
+}
+
+/** The single `provides` entry: the AgentProvider token → `AiSdkAgent` (one winner, §32). */
+export const agentProvider: ProviderRegistration = {
+  ref: AgentProviderRef,
+  // The registry passes the (least-privilege) plugin context; we build deps + the Agent from it.
+  impl: (ctx: PluginContext) => new AiSdkAgent(agentDepsFromContext(ctx as AgentBootContext)),
+  lifetime: "singleton", // resolved ONCE at boot; the request path never re-decides (§75.3)
+};
+
+/**
+ * The plugin value. `provides` the AgentProvider token (default winner, FR-001); the manifest
+ * `needs` (gateway host + named secret) is declared in package.json `cloc` and surfaced here for
+ * the kernel's grant check (FR-009, NFR-005).
+ */
+export const plugin = definePlugin({
+  name: PLUGIN_NAME,
+  provides: [agentProvider],
+});
+
+/** The gateway host the plugin egresses to — the only network `need` (hosted-first, FR-006). */
+export { GATEWAY_HOST };

package/src/request.ts

@@ -0,0 +1,178 @@
+/**
+ * @cloc/provider-ai-sdk · request.ts — the adapter-internal turn request, and how it maps to the
+ * core's vendor-free `Prompt` / `GenOpts` surface (contracts/agent-provider.ts, data-model §2).
+ *
+ * The core `AgentProvider` contract is `generate(p: Prompt, o?: GenOpts)` / `stream(...)`. The
+ * richer per-turn inputs the design's contract sketch names (grounding, the kit `outputSchema`,
+ * tools, tier, trace) arrive through the STRUCTURED prompt + the `GenOpts.providerOptions`
+ * passthrough (GenOpts keeps tier/grammar internals OUT of the model contract, §75.3). This module
+ * normalizes both into one internal {@link AgentTurn} the agent modules consume.
+ */
+
+import type { GenOpts, Prompt, StandardSchemaV1, ModelRef } from "./tokens.js";
+import type {
+  SkillRef,
+  MemoryStore,
+  CoreToolSet,
+  StopCondition,
+  PrepareStep,
+  PolicyGateHook,
+} from "./tokens.js";
+import { modelRefToString } from "@cloc/core";
+import type { GroundedContext } from "./safety.js";
+
+/** A tool the plan→act→observe loop may invoke; its result is fed back as DATA (FR-003, FR-015). */
+export interface AgentTool {
+  name: string;
+  description?: string;
+  /** Tool input schema (Standard Schema — Zod exposes `~standard`). */
+  input: StandardSchemaV1;
+  /** Result returned to the loop as DATA, never executed as instructions (FR-015). */
+  invoke(args: unknown): Promise<unknown>;
+}
+
+/** The active trace context the `agent.generate` subtree attaches under (FR-012). */
+export interface TraceContext {
+  readonly traceId: string;
+}
+
+/**
+ * The normalized internal turn the agent modules run. Assembled from the core `Prompt` + `GenOpts`
+ * by {@link toAgentTurn}; the kit schema / grounding / tools / tier / trace ride through the
+ * structured prompt and `providerOptions` passthrough (§75.3) so the core contract stays vendor-
+ * and tier-free.
+ */
+export interface AgentTurn<TPlan = unknown> {
+  /** The resolved intent (opaque to the core; concrete shape is feature 003). */
+  intent: unknown;
+  /** Grounded facts — DATA, never instructions (FR-015). */
+  grounding: GroundedContext;
+  /** The kit's Output schema the result is validated against (imported, 004-render-ir). */
+  outputSchema: StandardSchemaV1<unknown, TPlan>;
+  /** Legacy per-turn tools the loop may call (pre-027 `providerOptions.tools` shape). */
+  tools: ReadonlyArray<AgentTool>;
+  /** Synthesis tier (§72.1). */
+  tier: 2 | 3;
+  // --- Agentic primitives (v2, 027-agentic-primitives §16b) — all OPTIONAL (FR-002) ---
+  /** SKILL.md folders, three-level progressive disclosure (§16b.1). Only metadata enters the
+   *  prompt by default; body/bundled load lazily on a match / on demand. */
+  skills?: readonly SkillRef[];
+  /** `.cloc/memory/` via the memory-tool interface, `unstorage`-backed (§16b.2). */
+  memory?: MemoryStore;
+  /** AI-SDK `tool()` defs / MCP servers joined to the bounded render loop (§16b.3). The three
+   *  sources (`plugin`/`capability`/`wired`) all join here (FR-012). */
+  agenticTools?: CoreToolSet;
+  /** The trajectory budget that bounds the loop, e.g. `stepCountIs(N)` (§9.1, FR-013). */
+  stopWhen?: StopCondition;
+  /** Per-step context engineering callback (§16b.3, FR-011). Supplied via `providerOptions`. */
+  prepareStep?: PrepareStep;
+  /** The model FIELD for this turn (gateway provider/model), if the caller pinned one. */
+  model?: ModelRef;
+  /** Determinism seed (golden snapshots, §10 keys). */
+  seed?: number;
+  /** Soft cap on generated tokens (→ AI SDK `maxOutputTokens`). */
+  maxTokens?: number;
+  /** Cancellation (§ conformance C1 / A6). */
+  signal?: AbortSignal;
+  /** Whether the caller requested the streaming path. */
+  stream: boolean;
+  /** Active OTel trace to nest `agent.generate` under (FR-012). */
+  trace?: TraceContext;
+  /** Adapter passthrough verbatim (kit version, data version, etc.). */
+  providerOptions?: Readonly<Record<string, unknown>>;
+}
+
+/** The shape we read out of `GenOpts.providerOptions` (the runtime's per-turn binding). */
+interface ProviderOptionsSlice {
+  outputSchema?: StandardSchemaV1;
+  grounding?: GroundedContext;
+  tools?: ReadonlyArray<AgentTool>;
+  tier?: 2 | 3;
+  trace?: TraceContext;
+  kitVersion?: string;
+  dataVersion?: string;
+  /** Per-step context engineering (§16b.3, FR-011) — a callback can't ride the typed GenOpts, so
+   *  the runtime threads it through the opaque `providerOptions` passthrough (§75.3). */
+  prepareStep?: PrepareStep;
+}
+
+function readSlice(opts?: GenOpts): ProviderOptionsSlice {
+  return (opts?.providerOptions ?? {}) as ProviderOptionsSlice;
+}
+
+/** Pull the intent + grounding out of a structured prompt (a bare string prompt has neither). */
+function readPrompt(p: Prompt): { intent: unknown; grounding?: GroundedContext } {
+  if (typeof p === "string") return { intent: p };
+  const grounding = p.grounding as GroundedContext | undefined;
+  return grounding ? { intent: p.intent, grounding } : { intent: p.intent };
+}
+
+const EMPTY_GROUNDING: GroundedContext = { facts: [] };
+
+/** The default synthesis tier when the runtime does not pin one (§72.1). */
+const DEFAULT_TIER = 2 as const;
+
+/**
+ * Normalize the synthesis tier from the (untyped) provider-options slice to the valid `2 | 3` set.
+ * An absent or out-of-range value defaults to {@link DEFAULT_TIER} so a malformed passthrough can
+ * never produce an invalid tier on the span/turn (defense-in-depth; preserves the prior default).
+ */
+function normalizeTier(tier: unknown): 2 | 3 {
+  return tier === 3 ? 3 : DEFAULT_TIER;
+}
+
+/** Coerce a grounding slice to a well-formed {@link GroundedContext} (an array of facts), or empty. */
+function normalizeGrounding(g: GroundedContext | undefined): GroundedContext | undefined {
+  if (!g) return undefined;
+  return Array.isArray(g.facts) ? g : EMPTY_GROUNDING;
+}
+
+/**
+ * Normalize the core `Prompt` + `GenOpts` into the internal {@link AgentTurn}. The kit
+ * `outputSchema`, grounding, tools, tier and trace arrive via the structured prompt /
+ * `providerOptions` passthrough; the model/seed/maxTokens/signal arrive on `GenOpts` directly.
+ *
+ * Throws when no `outputSchema` is available — the turn MUST end in a validated structured Output
+ * (FR-004); without the kit schema there is nothing to validate against.
+ */
+export function toAgentTurn<TPlan = unknown>(
+  p: Prompt,
+  o: GenOpts | undefined,
+  stream: boolean,
+): AgentTurn<TPlan> {
+  const slice = readSlice(o);
+  const fromPrompt = readPrompt(p);
+  const outputSchema = slice.outputSchema as StandardSchemaV1<unknown, TPlan> | undefined;
+  if (!outputSchema) {
+    throw new Error(
+      "provider-ai-sdk: missing kit outputSchema (GenOpts.providerOptions.outputSchema) — the turn must end in a validated structured Output (FR-004/FR-013)",
+    );
+  }
+  const grounding =
+    normalizeGrounding(fromPrompt.grounding) ?? normalizeGrounding(slice.grounding) ?? EMPTY_GROUNDING;
+  return {
+    intent: fromPrompt.intent,
+    grounding,
+    outputSchema,
+    tools: Array.isArray(slice.tools) ? slice.tools : [],
+    tier: normalizeTier(slice.tier),
+    ...(o?.model !== undefined ? { model: o.model } : {}),
+    ...(o?.seed !== undefined ? { seed: o.seed } : {}),
+    ...(o?.maxTokens !== undefined ? { maxTokens: o.maxTokens } : {}),
+    ...(o?.signal !== undefined ? { signal: o.signal } : {}),
+    stream,
+    ...(slice.trace !== undefined ? { trace: slice.trace } : {}),
+    ...(o?.providerOptions !== undefined ? { providerOptions: o.providerOptions } : {}),
+    // --- Agentic primitives (v2, 027) — surfaced from the extended GenOpts, all optional (FR-002).
+    ...(o?.skills !== undefined ? { skills: o.skills } : {}),
+    ...(o?.memory !== undefined ? { memory: o.memory } : {}),
+    ...(o?.tools !== undefined ? { agenticTools: o.tools } : {}),
+    ...(o?.stopWhen !== undefined ? { stopWhen: o.stopWhen } : {}),
+    ...(slice.prepareStep !== undefined ? { prepareStep: slice.prepareStep } : {}),
+  };
+}
+
+/** The `provider/model` string a turn pins, if any (purely for logging / cache-key composition). */
+export function turnModelString(turn: AgentTurn): string | undefined {
+  return turn.model !== undefined ? modelRefToString(turn.model) : undefined;
+}

package/src/secrets.ts

@@ -0,0 +1,71 @@
+/**
+ * @cloc/provider-ai-sdk · secrets.ts — the secrets-by-name boundary (FR-009, NFR-005, §73.2).
+ *
+ * The gateway credential is referenced BY NAME (`config.secretRef`) and resolved LAZILY through
+ * an injected secrets-provider handle — never read from `cloc.yml` / `AgentConfig`. The adapter
+ * declares a LEAST-PRIVILEGE `needs` descriptor (the gateway network host + the named secret);
+ * the kernel grants only those (Constitution Principle 9).
+ *
+ * This module owns no secrets-provider implementation — that is a host integration (env/vault/
+ * KMS). It mirrors the kernel's `SecretHandle` shape structurally so the kernel-supplied handle
+ * satisfies it without a runtime import of @cloc/kernel.
+ */
+
+import type { AgentConfig } from "./config.js";
+
+/** The gateway host the adapter talks to (the only network egress it `needs`). */
+export const GATEWAY_HOST = "ai-gateway.vercel.sh";
+
+/**
+ * A live, by-name handle to ONE secret. Structurally identical to @cloc/kernel's `SecretHandle`
+ * — the kernel passes its handle straight in. Resolution is lazy; the value never touches config.
+ */
+export interface SecretHandle {
+  readonly name: string;
+  resolve(): Promise<string | undefined>;
+}
+
+/**
+ * The least-privilege resource needs this plugin declares (FR-009, NFR-005). The kernel reads
+ * this off the manifest and grants exactly: egress to the gateway host + the one named secret.
+ */
+export interface AgentNeeds {
+  /** Network hosts the adapter may reach — hosted-first, gateway only. */
+  net: readonly string[];
+  /** Secret NAMES the adapter may resolve — exactly the configured `secretRef`. */
+  secrets: readonly string[];
+}
+
+/** Build the least-privilege `needs` descriptor for a given config (gateway host + secretRef). */
+export function needsFor(config: AgentConfig): AgentNeeds {
+  return { net: [GATEWAY_HOST], secrets: [config.secretRef] };
+}
+
+/**
+ * Resolve the gateway credential BY NAME through the injected handle. Returns `undefined` when
+ * the handle denies it (undeclared / not present) — callers MUST treat a missing credential as a
+ * boot/config error, never fabricate one. The value is read here and nowhere else (FR-009).
+ *
+ * An empty / whitespace-only resolution is treated as ABSENT (returns `undefined`): a blank env var
+ * is a misconfiguration, not a usable key — surfacing it as `undefined` lets the gateway fall back
+ * to ambient/OIDC resolution rather than sending an empty Bearer token (defense-in-depth, NFR-005).
+ */
+export async function resolveGatewayKey(handle: SecretHandle): Promise<string | undefined> {
+  const value = await handle.resolve();
+  if (value === undefined || value === null) return undefined;
+  const trimmed = String(value).trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * Guard: assert no secret VALUE leaked into the config surface. `parseAgentConfig` already
+ * rejects an inlined value in `secretRef`; this is a belt-and-braces check usable at boot.
+ */
+export function assertNoInlineSecret(config: AgentConfig): void {
+  // `secretRef` is the ONLY credential field; it is a name (enforced in config.ts). There is no
+  // field on AgentConfig that carries a value, so a leaked value is structurally impossible here.
+  // Kept as an explicit invariant the conformance suite can assert against (data-model §5 rule).
+  if (config.secretRef.length === 0) {
+    throw new Error("agent.secretRef is required (the gateway credential NAME) — FR-009");
+  }
+}

package/src/skills-loader.ts

@@ -0,0 +1,153 @@
+/**
+ * @cloc/provider-ai-sdk · skills-loader.ts — the three-level progressive-disclosure loader for
+ * `SKILL.md` skills the render Agent activates (027-agentic-primitives §16b.1; FR-004, FR-005,
+ * FR-006, FR-014, NFR-008).
+ *
+ * Skills load by Discovery → Activation → Execution:
+ *   - level 1 (Discovery):  ONLY `manifest.name` + `manifest.description` enter the render prompt;
+ *   - level 2 (Activation): the full SKILL.md Markdown body loads ONLY when a request matches;
+ *   - level 3 (Execution):  bundled scripts/references/templates are read or run ON DEMAND — the
+ *                           script's SOURCE is NEVER loaded into the model context, and executing a
+ *                           bundled script clears the §58 policy gate FIRST (FR-014).
+ *
+ * The SKILL.md *recipe* (front-matter + body + references) is a committed FACT under `.cloc/skills/`
+ * (§13.1, §45); any CODE a skill bakes is cached OUTSIDE the repo and never committed (FR-006). This
+ * loader exposes the recipe and routes bake/exec through a repo-EXTERNAL path, never writing code
+ * back into the data repo (Principle 1).
+ *
+ * Vendor edge: NONE. This module turns the core's vendor-free `SkillRef` shapes (@cloc/core) into
+ * the level-1 prompt fragment + the gated activation/execution helpers the loop uses; the model SDK
+ * is touched only in tool-loop.ts.
+ */
+
+import type {
+  SkillRef,
+  SkillBody,
+  SkillManifest,
+  BundledResource,
+  PolicyGateHook,
+  GateDecision,
+} from "./tokens.js";
+
+/** The level-1 metadata that is the ONLY skill surface entering the render prompt by default. */
+export interface SkillMetadataLine {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+}
+
+/**
+ * Render the level-1 (Discovery) skill metadata for the prompt — `name` + `description` ONLY, never
+ * the body or bundled bytes (§16b.1, FR-005). This is the "just enough for the model to know when
+ * each skill should be used" fragment; it keeps the prompt small (the ~84% token reduction §16b.2).
+ */
+export function skillMetadata(skills: ReadonlyArray<SkillRef>): SkillMetadataLine[] {
+  return skills.map((s) => ({
+    id: s.id,
+    name: s.manifest.name,
+    description: s.manifest.description,
+  }));
+}
+
+/**
+ * Frame the level-1 skill metadata as an inert prompt block. ONLY name+description appear — the
+ * body and bundled files are absent until activation/execution (FR-005, NFR-002). Returns "" when
+ * no skills are enabled so a baseline render adds nothing to the prompt (FR-002, acceptance #1).
+ */
+export function frameSkillsForPrompt(skills: ReadonlyArray<SkillRef>): string {
+  if (skills.length === 0) return "";
+  const lines = skillMetadata(skills).map(
+    // `id`/`name`/`description` come from a SKILL.md manifest (model-influenced bytes), so any line
+    // break or `[ ]` is neutralized — a crafted description can't forge a new `[skill …]` envelope
+    // or inject a directive line into the prompt block (defense-in-depth, §16b.1; mirrors safety.ts).
+    (m) => `  [skill ${neutralize(m.id)}] ${neutralize(m.name)}: ${neutralize(m.description)}`,
+  );
+  return [
+    "<available-skills>",
+    "These SKILLs may help. Only their name+description are shown; request a skill by name to load",
+    "its full instructions (this is progressive disclosure — the body is NOT loaded yet).",
+    ...lines,
+    "</available-skills>",
+  ].join("\n");
+}
+
+/**
+ * Neutralize the characters in a skill-metadata field that could forge a `[skill …]` envelope or a
+ * line break (`[`, `]`, `\n`, `\r`, `\\`) when interpolated into the prompt block. A backslash-escape
+ * keeps the value human-readable; NO-OP for normal names/descriptions (mirrors safety.ts framing).
+ */
+function neutralize(value: string): string {
+  return value.replace(/[\\[\]\r\n]/g, (c) => (c === "\n" ? "\\n" : c === "\r" ? "\\r" : `\\${c}`));
+}
+
+/** A degrade outcome — a gate denial that proceeds without the capability, attributably (FR-021). */
+export interface SkillGateDenied {
+  readonly ok: false;
+  readonly reason: string;
+}
+
+/** Activation succeeded — the level-2 body is now available (the loop may feed it in). */
+export interface SkillActivated {
+  readonly ok: true;
+  readonly id: string;
+  readonly manifest: SkillManifest;
+  readonly body: SkillBody;
+}
+
+export type ActivateResult = SkillActivated | SkillGateDenied;
+
+/**
+ * Level-2 ACTIVATION: load the full `SKILL.md` body for a matched skill, AFTER clearing the §58
+ * gate (`kind: 'skill', level: 2`). A denial DEGRADES — it returns `{ ok: false, reason }` so the
+ * render proceeds without the skill rather than crashing or bypassing the gate (FR-014, FR-021).
+ */
+export async function activateSkill(
+  skill: SkillRef,
+  gate: PolicyGateHook,
+): Promise<ActivateResult> {
+  const decision = await gate.check({ kind: "skill", skill: skill.id, level: 2 });
+  if (!decision.allow) {
+    return { ok: false, reason: gateReason(decision, `skill "${skill.id}" activation denied`) };
+  }
+  const body = await skill.loadBody();
+  return { ok: true, id: skill.id, manifest: skill.manifest, body };
+}
+
+/** Execution succeeded — the bundled resource's bytes (NOT its source-in-context) are available. */
+export interface BundledOpened {
+  readonly ok: true;
+  readonly path: string;
+  readonly kind: BundledResource["kind"];
+  readonly bytes: Uint8Array;
+}
+
+export type OpenBundledResult = BundledOpened | SkillGateDenied;
+
+/**
+ * Level-3 EXECUTION: read or run a bundled resource ON DEMAND, AFTER clearing the §58 gate
+ * (`kind: 'skill', level: 3`). The script's SOURCE is never loaded into the model context — the
+ * runner calls `resource.open()` only after the gate clears, holding bundled-script execution to
+ * the SAME banned-pattern/allowlist/budget gate as generated code (§58, §16b.1, FR-014). A denial
+ * DEGRADES (FR-021).
+ */
+export async function openBundled(
+  skillId: string,
+  resource: BundledResource,
+  gate: PolicyGateHook,
+): Promise<OpenBundledResult> {
+  const decision = await gate.check({ kind: "skill", skill: skillId, level: 3 });
+  if (!decision.allow) {
+    return {
+      ok: false,
+      reason: gateReason(decision, `skill "${skillId}" bundled "${resource.path}" execution denied`),
+    };
+  }
+  // The gate cleared: only NOW is the resource read/executed (its source never entered context).
+  const bytes = await resource.open();
+  return { ok: true, path: resource.path, kind: resource.kind, bytes };
+}
+
+/** A truthy, attributable reason for a degrade (FR-021, NFR-004). */
+function gateReason(decision: GateDecision, fallback: string): string {
+  return decision.reason && decision.reason.length > 0 ? decision.reason : fallback;
+}

package/src/stream.ts

@@ -0,0 +1,80 @@
+/**
+ * @cloc/provider-ai-sdk · stream.ts — the partial-object stream adapter (FR-011, NFR-007, §60).
+ *
+ * Synthesized regions stream in as the model produces them so the projector renders KNOWN FIELDS
+ * of a half-arrived plan without blocking (low TTFB, §60). This maps the AI SDK v6 partial-object
+ * stream → the adapter's {@link StreamChunk} (and the core's `Delta`): `partial-object` deltas,
+ * interleaved `tool-call`/`tool-result` loop events, ending in a terminal `final` validated Output
+ * — or an `error`. On error/exhaustion ANY already-streamed partial is INVALIDATED: the stream
+ * ends WITHOUT a `final` the runtime could mistake for completion (edge case, data-model §4).
+ *
+ * AI SDK v6 surface (verified, not stale memory): `streamText({ ..., output: Output.object(...) })`
+ * exposes `result.experimental_partialOutputStream` (async-iterable partial objects) and
+ * `result.fullStream` (tool-call/tool-result/finish parts). `result.experimental_output` resolves
+ * the final typed object. We do not assume property names beyond these v6 docs shapes.
+ */
+
+import { partial as coreDelta, final as coreFinal, makeOutput } from "@cloc/core";
+import type { Delta, Output, StandardSchema } from "./tokens.js";
+import type { StructuredOutput } from "./output.js";
+import type { LoopEvent } from "./tool-loop.js";
+
+/** Adapter stream chunk (contracts/agent-provider.ts StreamChunk). `TPlan` is the kit plan type. */
+export type StreamChunk<TPlan = unknown> =
+  | { kind: "partial-object"; value: Partial<TPlan> }
+  | { kind: "tool-call"; tool: string; args: unknown }
+  | { kind: "tool-result"; tool: string; result: unknown }
+  | { kind: "final"; output: StructuredOutput<TPlan> }
+  | { kind: "error"; error: { code: string; message: string; fatal: boolean } };
+
+/** Map a loop event to its stream chunk. */
+export function loopEventToChunk<TPlan>(event: LoopEvent): StreamChunk<TPlan> {
+  return event.kind === "tool-call"
+    ? { kind: "tool-call", tool: event.tool, args: event.args }
+    : { kind: "tool-result", tool: event.tool, result: event.result };
+}
+
+/** Wrap a half-arrived plan snapshot as a `partial-object` chunk (parse-and-heal input, §60). */
+export function partialChunk<TPlan>(value: Partial<TPlan>): StreamChunk<TPlan> {
+  return { kind: "partial-object", value };
+}
+
+/**
+ * Lower an adapter {@link StreamChunk} to the core's vendor-free `Delta` (the surface
+ * `AgentProvider.stream` actually yields). `partial-object` and the loop events become a
+ * `{ kind: "partial", patch }`; the terminal validated Output becomes `{ kind: "final", output }`.
+ * On `error` we DO NOT emit a `final` — the agent throws/rejects the iterator instead so the
+ * runtime never mistakes a failed stream for completion (output.ts §3 rule; core Delta contract).
+ *
+ * `schema` brands the final payload's `Output` (the core requires the validated schema on it).
+ */
+export function chunkToDelta<TPlan>(
+  chunk: StreamChunk<TPlan>,
+  schema: StandardSchema<unknown>,
+): Delta | undefined {
+  switch (chunk.kind) {
+    case "partial-object":
+      return coreDelta({ partialPlan: chunk.value });
+    case "tool-call":
+      return coreDelta({ toolCall: { tool: chunk.tool, args: chunk.args } });
+    case "tool-result":
+      return coreDelta({ toolResult: { tool: chunk.tool, result: chunk.result } });
+    case "final":
+      return coreFinal(toCoreOutput(chunk.output, schema));
+    case "error":
+      // The agent surfaces errors by rejecting the iterator (never a fabricated `final`).
+      return undefined;
+  }
+}
+
+/** Brand a validated {@link StructuredOutput} as the core's `Output` (a typed UI plan, never markup). */
+export function toCoreOutput<TPlan>(
+  output: StructuredOutput<TPlan>,
+  schema: StandardSchema<unknown>,
+): Output {
+  return makeOutput({
+    // The kit plan IS the UI-plan / IR node tree the RenderEngine later lowers (output.ts §3).
+    plan: output.plan as never,
+    schema,
+  });
+}