@outputai/llm 0.6.1-next.fc6a93e.0 → 0.7.1-dev.144d64f.0

package/src/ai_provider.js

@@ -0,0 +1,86 @@
+import { FatalError, ValidationError, z } from '@outputai/core';
+import { Agent, fetch } from 'undici';
+// providers
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createAzure } from '@ai-sdk/azure';
+import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createPerplexity } from '@ai-sdk/perplexity';
+import { createVertex } from '@ai-sdk/google-vertex';
+
+/** This custom dispatcher has longer timeouts */
+const customDispatcher = new Agent( {
+  headersTimeout: 15 * 60 * 1000, // 15 min
+  bodyTimeout: 15 * 60 * 1000
+} );
+
+/** This custom fetch instance uses the custom dispatcher */
+const customFetch = ( input, init ) => fetch( input, { dispatcher: customDispatcher, ...init } );
+
+/** Available provider to initialize. */
+const providerInitializers = {
+  anthropic: createAnthropic,
+  azure: createAzure,
+  bedrock: createAmazonBedrock,
+  openai: createOpenAI,
+  perplexity: createPerplexity,
+  vertex: createVertex
+};
+
+/** Providers already initialized due usage */
+const initializedProviders = {};
+
+/** Providers registered by the user */
+const registeredProviders = {};
+
+/**
+ * Get all available provider names, including shipped and registered.
+ * @returns {string[]} Provider names
+ */
+export const getProviderNames = () =>
+  new Set( Object.keys( providerInitializers ).concat( Object.keys( registeredProviders ) ) ).values().toArray();
+
+const registerProviderSchema = z.object( {
+  name: z.string().min( 1, 'Provider name must be a non-empty string' ),
+  providerFn: z.function()
+} );
+
+/**
+ * Register or override an AI SDK provider factory by name.
+ * @param {string} name - Provider name used in prompt frontmatter
+ * @param {Function} providerFn - Factory function that receives a model id
+ * @returns {void}
+ */
+export function registerProvider( name, providerFn ) {
+  const result = registerProviderSchema.safeParse( { name, providerFn } );
+  if ( !result.success ) {
+    throw new ValidationError( `Invalid provider registration: ${z.prettifyError( result.error )}` );
+  }
+  registeredProviders[name] = providerFn;
+}
+
+/**
+ * Return a provider by its name.
+ * Look for registered providers first.
+ * If none, looks for initialized providers.
+ * Finally, looks for available provider initializers, and if found, init it.
+ *
+ * @param {string} name
+ * @returns {object} provider
+ */
+export const getProvider = name => {
+  const provider = registeredProviders[name] ?? initializedProviders[name];
+
+  if ( provider ) {
+    return provider;
+  }
+  if ( providerInitializers[name] ) {
+    try {
+      return initializedProviders[name] = providerInitializers[name]( { fetch: customFetch } );
+    } catch ( error ) {
+      throw new FatalError( `Failed to initialize provider "${name}": ${error.message}`, { cause: error } );
+    }
+  }
+
+  throw new FatalError( `Unsupported provider "${name}"` );
+};

package/src/ai_provider.spec.js

@@ -0,0 +1,147 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const SHIPPED_PROVIDERS = [
+  { name: 'anthropic', pkg: '@ai-sdk/anthropic', exportName: 'createAnthropic' },
+  { name: 'azure', pkg: '@ai-sdk/azure', exportName: 'createAzure' },
+  { name: 'bedrock', pkg: '@ai-sdk/amazon-bedrock', exportName: 'createAmazonBedrock' },
+  { name: 'openai', pkg: '@ai-sdk/openai', exportName: 'createOpenAI' },
+  { name: 'perplexity', pkg: '@ai-sdk/perplexity', exportName: 'createPerplexity' },
+  { name: 'vertex', pkg: '@ai-sdk/google-vertex', exportName: 'createVertex' }
+];
+
+const makeProviderModules = () => Object.fromEntries(
+  SHIPPED_PROVIDERS.map( ( { name, pkg, exportName } ) => [
+    pkg,
+    {
+      [exportName]: vi.fn( options => ( { name, options } ) )
+    }
+  ] )
+);
+
+const importWithMockedProviders = async ( modules = makeProviderModules() ) => {
+  await vi.resetModules();
+
+  for ( const { pkg, exportName } of SHIPPED_PROVIDERS ) {
+    vi.doMock( pkg, () => ( {
+      [exportName]: modules[pkg][exportName]
+    } ) );
+  }
+
+  return {
+    modules,
+    ...( await import( './ai_provider.js' ) )
+  };
+};
+
+afterEach( () => {
+  for ( const { pkg } of SHIPPED_PROVIDERS ) {
+    vi.doUnmock( pkg );
+  }
+  vi.resetModules();
+  vi.restoreAllMocks();
+} );
+
+describe( 'getProvider', () => {
+  it( 'does not initialize shipped providers on import', async () => {
+    const { modules } = await importWithMockedProviders();
+
+    for ( const { pkg, exportName } of SHIPPED_PROVIDERS ) {
+      expect( modules[pkg][exportName] ).not.toHaveBeenCalled();
+    }
+  } );
+
+  it( 'initializes each shipped provider with custom fetch when requested', async () => {
+    const { modules, getProvider } = await importWithMockedProviders();
+
+    for ( const { name, pkg, exportName } of SHIPPED_PROVIDERS ) {
+      const provider = getProvider( name );
+
+      expect( provider ).toMatchObject( { name, options: { fetch: expect.any( Function ) } } );
+      expect( modules[pkg][exportName] ).toHaveBeenCalledWith( { fetch: expect.any( Function ) } );
+    }
+  } );
+
+  it( 'can import and initialize all installed shipped providers', async () => {
+    const { getProvider } = await import( './ai_provider.js' );
+
+    for ( const { name } of SHIPPED_PROVIDERS ) {
+      expect( getProvider( name ) ).toEqual( expect.any( Function ) );
+    }
+  } );
+
+  it( 'caches initialized providers', async () => {
+    const { modules, getProvider } = await importWithMockedProviders();
+
+    const first = getProvider( 'openai' );
+    const second = getProvider( 'openai' );
+
+    expect( second ).toBe( first );
+    expect( modules['@ai-sdk/openai'].createOpenAI ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'uses registered providers before shipped providers', async () => {
+    const { modules, getProvider, registerProvider } = await importWithMockedProviders();
+    const customProvider = vi.fn( model => ( { provider: 'custom', model } ) );
+
+    registerProvider( 'openai', customProvider );
+
+    expect( getProvider( 'openai' ) ).toBe( customProvider );
+    expect( modules['@ai-sdk/openai'].createOpenAI ).not.toHaveBeenCalled();
+  } );
+
+  it( 'throws FatalError for unsupported providers', async () => {
+    const { getProvider } = await importWithMockedProviders();
+
+    expect( () => getProvider( 'not-real' ) ).toThrow( 'Unsupported provider "not-real"' );
+  } );
+
+  it( 'throws a friendly error when provider initialization fails', async () => {
+    const modules = makeProviderModules();
+    modules['@ai-sdk/openai'].createOpenAI.mockImplementation( () => {
+      throw new Error( 'Missing OpenAI API key' );
+    } );
+    const { getProvider } = await importWithMockedProviders( modules );
+
+    expect( () => getProvider( 'openai' ) ).toThrow(
+      'Failed to initialize provider "openai": Missing OpenAI API key'
+    );
+  } );
+} );
+
+describe( 'registerProvider', () => {
+  it( 'registers custom providers', async () => {
+    const { getProvider, getProviderNames, registerProvider } = await importWithMockedProviders();
+    const customProvider = vi.fn();
+
+    registerProvider( 'custom', customProvider );
+
+    expect( getProvider( 'custom' ) ).toBe( customProvider );
+    expect( getProviderNames() ).toContain( 'custom' );
+  } );
+
+  it( 'validates provider registration arguments', async () => {
+    const { registerProvider } = await importWithMockedProviders();
+
+    expect( () => registerProvider( '', vi.fn() ) ).toThrow( 'Provider name must be a non-empty string' );
+    expect( () => registerProvider( 'custom', 'not-a-function' ) ).toThrow( 'expected function, received string' );
+  } );
+} );
+
+describe( 'getProviderNames', () => {
+  it( 'returns shipped and registered provider names without duplicates', async () => {
+    const { getProviderNames, registerProvider } = await importWithMockedProviders();
+
+    registerProvider( 'custom', vi.fn() );
+    registerProvider( 'openai', vi.fn() );
+
+    expect( getProviderNames() ).toEqual( [
+      'anthropic',
+      'azure',
+      'bedrock',
+      'openai',
+      'perplexity',
+      'vertex',
+      'custom'
+    ] );
+  } );
+} );

package/src/ai_sdk_options.js

@@ -1,4 +1,5 @@
 import { loadImageModel, loadTextModel, loadTools } from './ai_model.js';
+import { resolveMessageProviderOptions } from './prompt/block_options.js';
 import { FatalError } from '@outputai/core';
 
 /**
@@ -13,7 +14,7 @@ export const loadAiSdkTextOptions = prompt => {
   }
   const options = {
     model: loadTextModel( prompt ),
-    messages: prompt.messages,
+    messages: resolveMessageProviderOptions( prompt ),
     providerOptions: prompt.config.providerOptions
   };
 

package/src/ai_sdk_options.spec.js

@@ -161,4 +161,32 @@ describe( 'ai_sdk_options', () => {
     );
     expect( loadImageModelImpl ).not.toHaveBeenCalled();
   } );
+
+  it( 'resolves block attributes into per-message providerOptions', async () => {
+    const prompt = {
+      name: 'cache@v1',
+      config: {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-5',
+        messageOptions: { cached: { anthropic: { cacheControl: { type: 'ephemeral', ttl: '1h' } } } }
+      },
+      messages: [
+        { role: 'system', content: 'Static', attributes: { options: 'cached' } },
+        { role: 'user', content: 'Hello' }
+      ],
+      instructions: null
+    };
+
+    const { loadAiSdkTextOptions } = await importSut();
+    const result = loadAiSdkTextOptions( prompt );
+
+    expect( result.messages ).toEqual( [
+      {
+        role: 'system',
+        content: 'Static',
+        providerOptions: { anthropic: { cacheControl: { type: 'ephemeral', ttl: '1h' } } }
+      },
+      { role: 'user', content: 'Hello' }
+    ] );
+  } );
 } );

package/src/cost/index.js

@@ -32,8 +32,13 @@ export const calculateLLMCallCost = async ( { modelId, usage } ) => {
     if ( Number.isFinite( pricing.input ) && Number.isFinite( nonCachedTokens ) ) {
       llmUsage.addUsage( { type: 'input', ppm: pricing.input, amount: nonCachedTokens } );
     }
-    if ( Number.isFinite( pricing.cache_read ) && Number.isFinite( cachedInputTokens ) ) {
-      llmUsage.addUsage( { type: 'input_cached', ppm: pricing.cache_read, amount: cachedInputTokens } );
+    // Surface cached input tokens whenever the provider reports them, even if the model's
+    // pricing lacks a cache_read rate — otherwise caching savings vanish from the token
+    // aggregation (these tokens are already excluded from the input line above). Price at
+    // cache_read when available, otherwise at 0.
+    if ( Number.isFinite( cachedInputTokens ) ) {
+      const cacheReadPpm = Number.isFinite( pricing.cache_read ) ? pricing.cache_read : 0;
+      llmUsage.addUsage( { type: 'input_cached', ppm: cacheReadPpm, amount: cachedInputTokens } );
     }
     if ( Number.isFinite( pricing.output ) && Number.isFinite( outputTokens ) ) {
       llmUsage.addUsage( { type: 'output', ppm: pricing.output, amount: outputTokens } );

package/src/cost/index.spec.js

@@ -132,7 +132,7 @@ describe( 'calculateLLMCallCost', () => {
     } );
   } );
 
-  it( 'omits cached usage when model has no cache_read rate', async () => {
+  it( 'still counts cached tokens when the model has no cache_read rate', async () => {
     mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'no-cache', { input: 2, output: 10 } ] ] ) );
 
     const result = await calculateLLMCallCost( {
@@ -140,14 +140,17 @@ describe( 'calculateLLMCallCost', () => {
       usage: { inputTokens: 1_000_000, cachedInputTokens: 200_000, outputTokens: 0 }
     } );
 
+    // Cached tokens are surfaced (priced at 0 without a cache_read rate) so caching is
+    // visible in the aggregation; cost is unchanged since they are excluded from `input`.
     expectLLMUsage( result, {
       modelId: 'no-cache',
       usage: [
         { type: 'input', ppm: 2, amount: 800_000, total: 1.6 },
+        { type: 'input_cached', ppm: 0, amount: 200_000, total: 0 },
         { type: 'output', ppm: 10, amount: 0, total: 0 }
       ],
       total: 1.6,
-      tokensUsed: 800_000
+      tokensUsed: 1_000_000
     } );
   } );
 

package/src/index.d.ts

@@ -6,6 +6,7 @@ import type {
   StreamTextResult as AIStreamTextResult,
   ToolLoopAgent as AIToolLoopAgent,
   ToolSet,
+  ModelMessage,
   StreamTextOnFinishCallback,
   generateText as aiGenerateText,
   streamText as aiStreamText,
@@ -40,11 +41,6 @@ export type {
 // Re-export the tool helper function, Output, smoothStream, stop condition helpers, and jsonSchema
 export { tool, Output, smoothStream, stepCountIs, hasToolCall, jsonSchema } from 'ai';
 
-// Web search tool factories
-export { tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap } from '@tavily/ai-sdk';
-export { webSearch as exaSearch } from '@exalabs/ai-sdk';
-export { perplexitySearch } from '@perplexity-ai/ai-sdk';
-
 /**
  * Represents a single message in a prompt conversation.
  *
@@ -61,6 +57,12 @@ export type PromptMessage = {
   role: string;
   /** The content of the message */
   content: string;
+  /**
+   * Parsed opening-tag attributes for the block. Currently `options` — a space-separated list of
+   * frontmatter `messageOptions` set names — which is resolved into per-message `providerOptions`
+   * at call time and stripped before the request is sent. Authored as `<system options="set_a set_b">`.
+   */
+  attributes?: Record<string, string | true>;
 };
 
 /**
@@ -143,6 +145,13 @@ export type Prompt = {
 
     /** Provider-specific options */
     providerOptions?: Record<string, unknown>;
+
+    /**
+     * Named, reusable per-message `providerOptions` sets, referenced from message blocks via the
+     * `options="<name>"` attribute. Each value is a provider-namespaced options object, e.g.
+     * `{ anthropic: { cacheControl: { type: 'ephemeral' } } }`.
+     */
+    messageOptions?: Record<string, Record<string, Record<string, unknown>>>;
   };
 
   /** Array of messages in the conversation */
@@ -171,11 +180,40 @@ export type SkillsArg<Input = unknown> = Skill[] |
   ( ( input: Input ) => Skill[] | Promise<Skill[]> );
 
 /** Prompt-owned AI SDK fields supplied by Output prompt files. */
-type PromptOwnedTextOptions = 'model' | 'messages' | 'prompt';
+type PromptOwnedTextOptions = 'model' | 'messages' | 'prompt' | 'tools';
 type AnyAiOutput = AIOutputNamespace.Output<unknown, unknown, unknown>;
+type CompatibleToolFunction = ( ...args: never[] ) => unknown | PromiseLike<unknown>;
+type CompatibleApprovalFunction = ( ...args: never[] ) => boolean | PromiseLike<boolean>;
+
+/**
+ * Structurally-compatible AI SDK tool shape.
+ *
+ * This intentionally avoids referencing AI SDK's concrete `Tool` schema types so tools
+ * from packages resolved with a different Zod peer instance remain assignable.
+ */
+export type CompatibleTool = {
+  description?: string;
+  title?: string;
+  providerOptions?: Record<string, unknown>;
+  inputSchema?: unknown;
+  parameters?: unknown;
+  execute?: CompatibleToolFunction;
+  onInputStart?: CompatibleToolFunction;
+  onInputDelta?: CompatibleToolFunction;
+  onInputAvailable?: CompatibleToolFunction;
+  needsApproval?: boolean | CompatibleApprovalFunction;
+} & (
+  { inputSchema: unknown } |
+  { parameters: unknown } |
+  { execute: CompatibleToolFunction }
+);
+
+/** AI SDK tools accepted by Output APIs without requiring one exact Zod peer instance. */
+export type CompatibleToolSet = Record<string, CompatibleTool>;
 
 /**
  * AI SDK options accepted by generateText, with prompt-owned fields supplied by Output prompt files.
+ * `tools` is accepted separately as {@link CompatibleToolSet} to support third-party tool packages.
  *
  * @typeParam Tools - The tools available for the model to call
  */
@@ -186,6 +224,7 @@ export type GenerateTextAiSdkOptions<
 
 /**
  * AI SDK options accepted by streamText, with prompt-owned fields supplied by Output prompt files.
+ * `tools` is accepted separately as {@link CompatibleToolSet} to support third-party tool packages.
  *
  * @typeParam Tools - The tools available for the model to call
  */
@@ -205,7 +244,8 @@ type GenerateImagePromptWithImages = Exclude<GenerateImagePrompt, string>;
 type GenerateImageInput = GenerateImagePromptWithImages['images'][number];
 
 /** Agent {@link Agent.stream} options: same as AI SDK plus wrapped `onFinish` (adds `cost`). */
-export type OutputAgentStreamParameters = Omit<AgentStreamParameters<never, ToolSet>, 'onFinish'> & {
+export type OutputAgentStreamParameters = Omit<AgentStreamParameters<never, ToolSet>, 'onFinish' | 'tools'> & {
+  tools?: CompatibleToolSet;
   onFinish?: WrappedStreamTextOnFinishCallback<ToolSet>;
 };
 
@@ -224,7 +264,7 @@ export type OutputAgentConstructorParameters<
   /** Static skill packages made available to the LLM */
   skills?: Skill[];
   /** AI SDK tools available during the reasoning loop */
-  tools?: ConstructorParameters<typeof AIToolLoopAgent>[0]['tools'];
+  tools?: CompatibleToolSet;
   /** Maximum tool-loop iterations when stopWhen is not specified (default: 10) */
   maxSteps?: number;
   /** Pluggable conversation store — opt-in, stateless by default */
@@ -232,7 +272,9 @@ export type OutputAgentConstructorParameters<
 };
 
 /** Agent generate options accepted by the underlying AI SDK agent. */
-export type OutputAgentGenerateParameters = AgentCallParameters<never, ToolSet>;
+export type OutputAgentGenerateParameters = Omit<AgentCallParameters<never, ToolSet>, 'tools'> & {
+  tools?: CompatibleToolSet;
+};
 
 /** Parameters accepted by {@link generateText}. */
 export type GenerateTextParameters<
@@ -249,6 +291,8 @@ export type GenerateTextParameters<
   skills?: SkillsArg<Record<string, string | number | boolean> | undefined>;
   /** Used to create a default `stepCountIs(maxSteps)` when tools are present and `stopWhen` is omitted */
   maxSteps?: number;
+  /** AI SDK tools, accepted structurally to tolerate different Zod peer versions. */
+  tools?: CompatibleToolSet;
 } & GenerateTextAiSdkOptions<Tools, OutputSpec>;
 
 /** Parameters accepted by {@link streamText}. */
@@ -266,6 +310,8 @@ export type StreamTextParameters<
   skills?: Skill[] | ( ( input: Record<string, string | number | boolean> | undefined ) => Skill[] );
   /** Used to create a default `stepCountIs(maxSteps)` when tools are present and `stopWhen` is omitted */
   maxSteps?: number;
+  /** AI SDK tools, accepted structurally to tolerate different Zod peer versions. */
+  tools?: CompatibleToolSet;
   /** Callback when stream finishes. Receives the wrapped event with optional `cost`. */
   onFinish?: WrappedStreamTextOnFinishCallback<Tools>;
 } & Omit<StreamTextAiSdkOptions<Tools, OutputSpec>, 'onFinish'>;
@@ -391,15 +437,16 @@ export function registerProvider(
  *
  * @returns Array of provider name strings
  */
-export function getRegisteredProviders(): string[];
+export function getProviderNames(): string[];
 
 /**
  * Use an LLM model to generate text.
  *
  * This function is a wrapper over the AI SDK's `generateText`.
  * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
- * All other AI SDK `generateText` options are accepted via {@link GenerateTextAiSdkOptions}, including
- * tools, tool choice, structured output, callbacks, retries, and sampling settings.
+ * AI SDK-compatible `tools` are accepted structurally via {@link CompatibleToolSet}. Other AI SDK
+ * `generateText` options are accepted via {@link GenerateTextAiSdkOptions}, including tool choice,
+ * structured output, callbacks, retries, and sampling settings.
  *
  * @param args - Generation arguments. See {@link GenerateTextParameters}.
  * @returns AI SDK response with text and metadata.
@@ -416,8 +463,9 @@ export function generateText<
  *
  * This function is a wrapper over the AI SDK's `streamText`.
  * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
- * All other AI SDK `streamText` options are accepted via {@link StreamTextAiSdkOptions}, except
- * `onFinish`, which Output wraps to add optional cost data.
+ * AI SDK-compatible `tools` are accepted structurally via {@link CompatibleToolSet}. Other AI SDK
+ * `streamText` options are accepted via {@link StreamTextAiSdkOptions}, except `onFinish`, which
+ * Output wraps to add optional cost data.
  *
  * @param args - Streaming arguments. See {@link StreamTextParameters}.
  * @returns AI SDK stream result with textStream, fullStream, and metadata promises.
@@ -463,8 +511,8 @@ export function skill( params: {
 
 /** Pluggable conversation store for multi-turn Agent interactions. */
 export interface ConversationStore {
-  getMessages(): import( 'ai' ).ModelMessage[] | Promise<import( 'ai' ).ModelMessage[]>;
-  addMessages( messages: import( 'ai' ).ModelMessage[] ): void | Promise<void>;
+  getMessages(): ModelMessage[] | Promise<ModelMessage[]>;
+  addMessages( messages: ModelMessage[] ): void | Promise<void>;
 }
 
 /** Create an in-memory conversation store backed by a closure array. */

package/src/index.js

@@ -1,9 +1,6 @@
 export { generateText, streamText, generateImage } from './ai_sdk.js';
 export { Agent, createMemoryConversationStore, skill } from './agent.js';
 export { loadPrompt } from './prompt/loader.js';
-export { registerProvider, getRegisteredProviders } from './ai_model.js';
-export { tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap } from '@tavily/ai-sdk';
-export { webSearch as exaSearch } from '@exalabs/ai-sdk';
-export { perplexitySearch } from '@perplexity-ai/ai-sdk';
+export { registerProvider, getProviderNames } from './ai_provider.js';
 export { tool, Output, smoothStream, stepCountIs, hasToolCall, jsonSchema } from 'ai';
 export * as ai from 'ai';

package/src/prompt/block_options.js

@@ -0,0 +1,58 @@
+import { FatalError, z } from '@outputai/core';
+
+/** Shallow-merge two providerOptions objects, combining keys within each provider namespace. */
+const mergeProviderOptions = ( base = {}, extra = {} ) => {
+  const merged = { ...base };
+  for ( const [ namespace, options ] of Object.entries( extra ) ) {
+    merged[namespace] = { ...merged[namespace], ...options };
+  }
+  return merged;
+};
+
+/** Merge the named `messageOptions` sets referenced by a block's `options` attribute. */
+const resolveOptions = ( value, { name, config } ) => {
+  const sets = config.messageOptions ?? {};
+  return value.trim().split( /\s+/ ).reduce( ( acc, setName ) => {
+    if ( !sets[setName] ) {
+      throw new FatalError( `Prompt "${name}" references unknown messageOptions set "${setName}"` );
+    }
+    return mergeProviderOptions( acc, sets[setName] );
+  }, {} );
+};
+
+/**
+ * Registry of supported block attributes. Each entry declares how the attribute is validated
+ * (`schema`) and how it contributes to a message's per-message `providerOptions` (`resolve`).
+ * Add an entry to support a new block option — validation ({@link attributesSchema}) and
+ * resolution ({@link resolveMessageProviderOptions}) both derive from this table.
+ */
+const BLOCK_OPTIONS = {
+  options: {
+    schema: z.string().min( 1 ),
+    resolve: resolveOptions
+  }
+};
+
+/** Zod schema for a block's `attributes` object, derived from the option registry. */
+export const attributesSchema = z.object(
+  Object.fromEntries(
+    Object.entries( BLOCK_OPTIONS ).map( ( [ name, def ] ) => [ name, def.schema.optional() ] )
+  )
+).strict();
+
+/**
+ * Resolve each message's authoring `attributes` into AI SDK per-message `providerOptions`,
+ * returning clean messages with the `attributes` helper stripped.
+ *
+ * @param {object} prompt - Loaded prompt object (`{ name, config, messages }`)
+ * @returns {Array<object>} Messages with resolved `providerOptions`
+ */
+export const resolveMessageProviderOptions = ( { name, config, messages } ) =>
+  messages.map( ( { attributes, providerOptions, ...message } ) => {
+    const resolved = Object.entries( attributes ?? {} ).reduce( ( acc, [ key, value ] ) => {
+      const option = BLOCK_OPTIONS[key];
+      return option ? mergeProviderOptions( acc, option.resolve( value, { name, config } ) ) : acc;
+    }, providerOptions ?? {} );
+
+    return Object.keys( resolved ).length > 0 ? { ...message, providerOptions: resolved } : message;
+  } );

package/src/prompt/block_options.spec.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { FatalError } from '@outputai/core';
+import { attributesSchema, resolveMessageProviderOptions } from './block_options.js';
+
+const textPrompt = ( { config = {}, messages } ) => ( {
+  name: 'test@v1',
+  config: { provider: 'anthropic', model: 'claude-sonnet-4-5', ...config },
+  messages
+} );
+
+describe( 'attributesSchema', () => {
+  it( 'accepts the options attribute', () => {
+    expect( attributesSchema.safeParse( { options: 'cached' } ).success ).toBe( true );
+    expect( attributesSchema.safeParse( { options: 'cached fast' } ).success ).toBe( true );
+    expect( attributesSchema.safeParse( {} ).success ).toBe( true );
+  } );
+
+  it( 'rejects unknown attributes, including the removed cache shorthand', () => {
+    expect( attributesSchema.safeParse( { cache: true } ).success ).toBe( false );
+    expect( attributesSchema.safeParse( { unknown: 'x' } ).success ).toBe( false );
+  } );
+} );
+
+describe( 'resolveMessageProviderOptions', () => {
+  it( 'merges a referenced messageOptions set into per-message providerOptions', () => {
+    const result = resolveMessageProviderOptions( textPrompt( {
+      config: { messageOptions: { cached: { anthropic: { cacheControl: { type: 'ephemeral' } } } } },
+      messages: [
+        { role: 'system', content: 'Docs', attributes: { options: 'cached' } },
+        { role: 'user', content: 'Hello' }
+      ]
+    } ) );
+
+    expect( result ).toEqual( [
+      {
+        role: 'system',
+        content: 'Docs',
+        providerOptions: { anthropic: { cacheControl: { type: 'ephemeral' } } }
+      },
+      { role: 'user', content: 'Hello' }
+    ] );
+  } );
+
+  it( 'merges multiple referenced sets onto one block', () => {
+    const [ system ] = resolveMessageProviderOptions( textPrompt( {
+      config: {
+        messageOptions: {
+          cached: { anthropic: { cacheControl: { type: 'ephemeral', ttl: '1h' } } },
+          openaiKey: { openai: { promptCacheKey: 'enrich-v1' } }
+        }
+      },
+      messages: [ { role: 'system', content: 'Docs', attributes: { options: 'cached openaiKey' } } ]
+    } ) );
+
+    expect( system.providerOptions ).toEqual( {
+      anthropic: { cacheControl: { type: 'ephemeral', ttl: '1h' } },
+      openai: { promptCacheKey: 'enrich-v1' }
+    } );
+  } );
+
+  it( 'throws when the options attribute references an unknown set', () => {
+    expect( () => resolveMessageProviderOptions( textPrompt( {
+      messages: [ { role: 'user', content: 'Hello', attributes: { options: 'missing' } } ]
+    } ) ) ).toThrow( FatalError );
+  } );
+
+  it( 'leaves messages without attributes unchanged', () => {
+    const messages = [ { role: 'user', content: 'Hello' } ];
+    expect( resolveMessageProviderOptions( textPrompt( { messages } ) ) ).toEqual( messages );
+  } );
+} );