@outputai/core 0.15.1-next.4a437bf.0 → 0.15.1-next.8ef04e2.0

package/src/llm/prompt/interpolations.js

@@ -0,0 +1,58 @@
+import { isPlainObject } from '#helpers/object';
+import { encodeXML, decodeXML } from 'entities';
+
+export const interpolationFilterToken = '__var_safe';
+
+/**
+ * XML-escapes a value.
+ * @param {unknown} value - Any value to escape
+ * @returns {string} Escaped value or '' if original value was null/undefined
+ */
+export const encode = value => [ null, undefined ].includes( value ) ? '' : encodeXML( String( value ) );
+
+/**
+ * Matches {% raw %}...{% endraw %} or {{ ... }} tags
+ */
+const VAR_OR_RAW = /(\{%\s*raw\s*%\}[\s\S]*?\{%\s*endraw\s*%\})|\{\{\s*([\s\S]+?)\s*\}\}/g;
+
+/**
+ * Appends `| __var_safe` filter to every `{{ ... }}` expression.
+ *
+ * The filter XML-escape the interpolated content so it cannot be parsed as new message blocks.
+ *
+ * Without this, a variable whose value contains `<system>` or `</user>` would inject extra
+ * message blocks.
+ *
+ * Raw regions `{% raw %} ... {% endraw %}` are emitted verbatim by Liquid and preserved
+ * unchanged.
+ *
+ * Note: The `g` flag advances past any matched raw regions, so `{{ ... }}` inside them are
+ * preserved as well.
+ *
+ * @param {string} raw - Raw template string
+ * @returns {string} Template with `| __var_safe` appended to each interpolation
+ */
+export const pipeInterpolations = raw =>
+  raw.replace( VAR_OR_RAW, ( _, rawRegion, expressionContent ) =>
+    rawRegion === undefined ? `{{ ${expressionContent.trim()} | ${interpolationFilterToken} }}` : rawRegion
+  );
+
+/**
+ * Recursive decode a XML-encoded value.
+ * @param {unknown} value - Value to decode
+ * @returns {unknown} Decoded value
+ */
+export const decode = value => {
+  if ( typeof value === 'string' ) {
+    return decodeXML( value );
+  }
+  if ( Array.isArray( value ) ) {
+    return value.map( decode );
+  }
+  if ( isPlainObject( value ) ) {
+    return Object.fromEntries(
+      Object.entries( value ).map( ( [ key, item ] ) => [ key, decode( item ) ] )
+    );
+  }
+  return value;
+};

package/src/llm/prompt/loader.js

@@ -0,0 +1,67 @@
+import { Context, Liquid } from 'liquidjs';
+import { parsePromptSchema } from './validations.js';
+import { FatalError } from '#errors';
+import { pipeInterpolations, interpolationFilterToken, encode, decode } from './interpolations.js';
+import { resolveInvocationDir } from '#helpers/path';
+import { searchAndReadFile } from '../utils/file.js';
+import matter from 'gray-matter';
+import { parseContent } from './content.js';
+
+const liquid = new Liquid( {
+  strictFilters: true,
+  strictVariables: true,
+  lenientIf: true
+} );
+
+liquid.registerFilter( interpolationFilterToken, encode );
+
+const splitPromptContent = text => {
+  const dummyEngine = () => ( {} ); // dummy engine to allow for split only
+  const file = matter( text, { engines: { yaml: dummyEngine } } );
+  return { rawFrontmatter: file.matter, rawContent: file.content };
+};
+
+const renderContent = ( rawContent, context ) => liquid.parseAndRenderSync( pipeInterpolations( rawContent ), context ).trim();
+
+const renderFrontmatter = ( rawFrontmatter, context ) => liquid.parseAndRenderSync( pipeInterpolations( rawFrontmatter ), context );
+
+const parseFrontmatter = yml => decode( matter( `---\n${yml}\n---\n` ).data );
+
+/**
+ * Load a prompt file and render it with variables.
+ *
+ * @param {string} name - Name of the prompt file (without .prompt extension)
+ * @param {Record<string, unknown>} [variables] - Variables to interpolate
+ * @param {string} [dir] - Directory to search for the prompt file (defaults to stack-resolved invocation dir)
+ * @returns {Prompt} Loaded and rendered prompt object.
+ */
+export const loadPrompt = ( name, variables = {}, dir = resolveInvocationDir() ) => {
+  // Small closure to encapsulate errors with "name"
+  const tryStep = ( fn, msg ) => {
+    try {
+      return fn();
+    } catch ( e ) {
+      throw new FatalError( [ `${msg} on prompt "${name}"`, e.message ].join( ': ' ), { cause: e } );
+    }
+  };
+
+  const file = searchAndReadFile( dir, `${name}.prompt` );
+  if ( !file ) {
+    throw new FatalError( `Prompt file "${name}" not found.` );
+  }
+
+  const { rawFrontmatter, rawContent } = tryStep( () => splitPromptContent( file.content ), 'Error parsing frontmatter' );
+  const context = new Context( variables, liquid.options, { sync: true } );
+  const renderedFrontmatter = tryStep( () => renderFrontmatter( rawFrontmatter, context ), 'Error rendering frontmatter' );
+  const content = tryStep( () => renderContent( rawContent, context ), 'Error rendering content' );
+
+  if ( !content ) {
+    throw new FatalError( `Prompt "${name}" has no content.` );
+  }
+
+  const config = tryStep( () => parseFrontmatter( renderedFrontmatter ), 'Error converting frontmatter yaml to js' );
+
+  const { messages, instructions } = tryStep( () => parseContent( content, config.messageOptions ), 'Error parsing content' );
+
+  return parsePromptSchema( { name, config, messages, instructions, fileDir: file.dir, variables } );
+};

package/src/llm/prompt/markup/attributes.js

@@ -0,0 +1,52 @@
+import { ValidationError } from '#errors';
+
+const attributeSeparator = /(?<![=\s])\s+(?!\s*=)(?=(?:[^"']|"[^"]*"|'[^']*')*$)/;
+
+export const extractAttributes = rawAttributes => {
+  if ( !rawAttributes?.trim() ) {
+    return {};
+  }
+  const pairs = rawAttributes.trim().split( attributeSeparator );
+  const attributeKeyRule = /^[A-Za-z][\w-]*$/;
+
+  return Object.fromEntries(
+    pairs.map( p => {
+      const splitIndex = p.indexOf( '=' );
+      if ( splitIndex === -1 ) {
+        const key = p.toLowerCase();
+        if ( !attributeKeyRule.test( key ) ) {
+          throw new ValidationError( `Invalid attribute name "${key}".` );
+        }
+        return [ key, true ];
+      }
+
+      const key = p.slice( 0, splitIndex ).trim().toLowerCase();
+      if ( !key ) {
+        throw new ValidationError( `Invalid attribute "${p}": name is missing.` );
+      }
+      if ( !attributeKeyRule.test( key ) ) {
+        throw new ValidationError( `Invalid attribute name "${key}".` );
+      }
+      const value = p.slice( splitIndex + 1 ).trim();
+      const openingQuote = value[0];
+      const isQuoted = openingQuote === '\'' || openingQuote === '"';
+
+      if ( !isQuoted ) {
+        const invalidCharacter = value.match( /['"<>=]/ )?.[0];
+        if ( invalidCharacter ) {
+          throw new ValidationError( `Invalid attribute "${key}": unquoted value contains invalid character \`${invalidCharacter}\`.` );
+        }
+        return [ key, value ];
+      } else {
+        if ( value.at( -1 ) !== openingQuote ) {
+          throw new ValidationError( `Invalid attribute "${key}": quoted value is missing its closing quote (${openingQuote}).` );
+        }
+        const unquoted = value.slice( 1, -1 );
+        if ( unquoted.includes( openingQuote ) ) {
+          throw new ValidationError( `Invalid attribute "${key}": quoted value contains an unexpected quote (${openingQuote}).` );
+        }
+        return [ key, unquoted ];
+      }
+    } )
+  );
+};

package/src/llm/prompt/markup/nodes.js

@@ -0,0 +1,71 @@
+import { isOpeningTag, isClosingTag, isEmptyText, isSelfClosingTag, isComment, extractTag } from './tokens.js' ;
+import { tokenize } from './tokenizer.js';
+import { ValidationError } from '#errors';
+
+class Node {
+  constructor( tagName, attributes, content = '' ) {
+    this.tagName = tagName;
+    this.attributes = attributes;
+    this.content = content;
+  }
+}
+
+export const parseMarkup = content => {
+  const tokens = tokenize( content );
+  if ( !tokens ) {
+    return [];
+  }
+
+  const state = {
+    currentNode: null
+  };
+
+  const nodes = [];
+
+  // If the first ever valid text isnt a markup or comment, don't try to parse and return no nodes
+  const firstContentToken = tokens.find( token => !isComment( token ) && !isEmptyText( token ) );
+  if ( firstContentToken && !isOpeningTag( firstContentToken ) && !isClosingTag( firstContentToken ) && !isSelfClosingTag( firstContentToken ) ) {
+    return [];
+  }
+
+  for ( const token of tokens ) {
+    if ( isOpeningTag( token ) ) {
+      const { tagName, attributes } = extractTag( token );
+      if ( !state.currentNode ) {
+        state.currentNode = new Node( tagName, attributes );
+      } else {
+        if ( tagName === state.currentNode.tagName ) {
+          throw new ValidationError(
+            `Invalid child tag: <${tagName}> cannot appear inside another <${tagName}>. Escape it as "&lt;${tagName}&gt;".`
+          );
+        }
+        state.currentNode.content += token;
+      }
+    } else if ( isClosingTag( token ) ) {
+      if ( !state.currentNode ) {
+        throw new ValidationError( `Invalid root tag: closing tag "${token}" has no matching opening tag.` );
+      }
+      if ( extractTag( token ).tagName === state.currentNode.tagName ) {
+        nodes.push( state.currentNode );
+        state.currentNode = null;
+      } else {
+        state.currentNode.content += token;
+      }
+    } else {
+      if ( state.currentNode ) {
+        state.currentNode.content += token;
+      } else {
+        if ( isSelfClosingTag( token ) ) {
+          throw new ValidationError( `Invalid root tag: self-closing tag "${token}" is not allowed.` );
+        } else if ( !isComment( token ) && !isEmptyText( token ) ) {
+          throw new ValidationError( 'Invalid root text: text is not allowed outside message tags.' );
+        }
+      }
+    }
+  }
+
+  if ( state.currentNode ) {
+    throw new ValidationError( `Invalid tag: <${state.currentNode.tagName}> is missing its closing tag.` );
+  }
+  return nodes;
+};

package/src/llm/prompt/markup/tokenizer.js

@@ -0,0 +1,3 @@
+const tokenizer = /<!--[\s\S]*?-->|<\/\s*[A-Za-z][\w-]*\s*>|<[A-Za-z][\w-]*(?:"[^"]*"|'[^']*'|[^'"<>])*>|<[A-Za-z][\w-]*[^<>]*>|[^<]+|</g;
+
+export const tokenize = value => value.match( tokenizer );

package/src/llm/prompt/markup/tokens.js

@@ -0,0 +1,26 @@
+import { ValidationError } from '#errors';
+import { extractAttributes } from './attributes.js';
+
+export const extractTag = v => {
+  const capture = v.match( /^<\/?\s*([\w-]+)(?:\s+(.+?))?\s*>$/ );
+  if ( !capture ) {
+    throw new ValidationError( `Could not parse tag "${v}".` );
+  }
+  const [ name, rawAttributes ] = capture.slice( 1, 3 );
+  if ( !name ) {
+    throw new ValidationError( `Could not parse tag "${v}".` );
+  }
+  return {
+    tagName: name.toLowerCase(),
+    attributes: rawAttributes ? extractAttributes( rawAttributes ) : {}
+  };
+};
+
+const hasClosing = v => /\/\s*>$/.test( v );
+const hasOpening = v => /^<[A-Za-z][\w-]*(?=\s|\/?>)[^<]*>$/.test( v );
+
+export const isOpeningTag = v => hasOpening( v ) && !hasClosing( v );
+export const isComment = v => v.startsWith( '<!--' ) && v.endsWith( '-->' ) && v.length >= 7 && !v.slice( 4, -3 ).includes( '-->' );
+export const isSelfClosingTag = v => hasOpening( v ) && hasClosing( v );
+export const isEmptyText = v => /^\s*$/.test( v );
+export const isClosingTag = v => /^<\/\s*[A-Za-z]+[\w-]*\s*>$/.test( v );

package/src/llm/prompt/validations.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { ValidationError } from '#errors';
+import { Logger } from '#runtime_logger';
+import { deprecatedProviderAliases } from '../deprecated_provider_aliases.js';
+import { Role } from '../consts.js';
+
+const log = Logger.createLogger( 'LLM' );
+
+const handleDeprecatedKeys = prompt => {
+  const { config: { maxTokens, maxOutputTokens, provider } } = prompt;
+
+  // @TODO: maxTokens was replaced by maxOutputTokens in v0.12, it can be removed down the road
+  if ( Number.isFinite( maxTokens ) ) {
+    if ( Number.isFinite( maxOutputTokens ) ) {
+      log.warn( 'Prompt has both "maxOutputTokens" and deprecated "maxTokens" keys set, "maxTokens" value will be ignored.' );
+    } else {
+      log.warn( 'Prompt has deprecated key "maxTokens". Its value was set to "maxOutputTokens".' );
+      prompt.config.maxOutputTokens = maxTokens;
+    }
+  }
+
+  // @TODO: this handle aliases removal in v0.11, it can be removed down the road
+  if ( Object.hasOwn( deprecatedProviderAliases, provider ) ) {
+    const canonical = deprecatedProviderAliases[provider];
+    log.warn( `Prompt uses deprecated provider alias "${provider}". Use "${canonical}" instead.` );
+    prompt.config.provider = canonical;
+  }
+
+  return prompt;
+};
+
+const objectMapSchema = z.record(
+  z.string(),
+  z.record(
+    z.string(),
+    z.unknown()
+  )
+);
+
+const promptConfigSchema = z.object( {
+  aspectRatio: z.string().regex( /^\d+:\d+$/ ).optional(),
+  frequencyPenalty: z.number().optional(),
+  maxImagesPerCall: z.number().int().positive().optional(),
+  maxOutputTokens: z.number().int().positive().optional(),
+  maxSteps: z.number().int().positive().default( 10 ),
+  maxTokens: z.number().int().positive().optional(),
+  // A provider-namespaced options object, e.g. { anthropic: { cacheControl: { type: 'ephemeral' } } }
+  messageOptions: z.record( z.string(), objectMapSchema ).optional(),
+  model: z.string().min( 1 ),
+  n: z.number().int().positive().optional(),
+  presencePenalty: z.number().optional(),
+  provider: z.string().min( 1 ),
+  providerOptions: z.object( {
+    thinking: z.object( {
+      type: z.enum( [ 'enabled', 'disabled' ] ),
+      budgetTokens: z.number().optional()
+    } ).loose().optional()
+  } ).loose().optional(),
+  seed: z.number().int().optional(),
+  size: z.string().regex( /^\d+x\d+$/ ).optional(),
+  skills: z.preprocess( v => Array.isArray( v ) ? v : [].concat( v ?? [] ), z.array( z.string().min( 1 ) ) ),
+  stopSequences: z.array( z.string() ).optional(),
+  temperature: z.number().nonnegative().optional(),
+  topK: z.number().nonnegative().optional(),
+  topP: z.number().nonnegative().optional(),
+  tools: objectMapSchema.optional()
+} ).strict();
+
+export const promptSchema = z.object( {
+  name: z.string(),
+  config: promptConfigSchema,
+  messages: z.array(
+    z.object( {
+      role: z.enum( Object.values( Role ) ),
+      content: z.string(),
+      providerOptions: objectMapSchema.optional()
+    } ).strict()
+  ),
+  instructions: z.string().trim().min( 1 ).nullable().default( null ),
+  fileDir: z.string(),
+  variables: z.record( z.string(), z.unknown() ).default( {} )
+} ).strict().superRefine( ( prompt, ctx ) => {
+  const hasMessages = prompt.messages.length > 0;
+  const hasInstructions = !!prompt.instructions;
+  const addIssue = message => ctx.addIssue( { code: 'custom', path: [ 'messages', 'instructions' ], message } );
+
+  if ( !hasMessages && !hasInstructions ) {
+    addIssue( 'Prompt must include either message blocks or plain instructions.' );
+  } else if ( hasMessages && hasInstructions ) {
+    addIssue( 'Prompt cannot include both message blocks and plain instructions.' );
+  }
+} ).transform( handleDeprecatedKeys );
+
+const promptConfigKeys = new Set( Object.keys( promptConfigSchema.shape ) );
+
+/** Converts a string to camel case */
+const toCamelCase = value => value.replace( /_([a-z])/g, ( _, letter ) => letter.toUpperCase() );
+
+/** Appends camelCase suggestions to unrecognized top-level config keys written in snake_case. */
+const appendCamelCaseSuggestions = error => {
+  for ( const issue of error.issues ) {
+    if ( issue.code !== 'unrecognized_keys' || issue.path.length !== 1 || issue.path[0] !== 'config' ) {
+      continue;
+    }
+
+    const suggestions = issue.keys
+      .filter( key => key.includes( '_' ) )
+      .map( key => ( { key, camel: toCamelCase( key ) } ) )
+      .filter( ( { key, camel } ) => camel !== key && promptConfigKeys.has( camel ) )
+      .map( ( { key, camel } ) => `"${key}" is not valid; use "${camel}"` );
+
+    if ( suggestions.length > 0 ) {
+      issue.message = `${issue.message}. ${suggestions.join( '. ' )}`;
+    }
+  }
+};
+
+export const parsePromptSchema = prompt => {
+  const result = promptSchema.safeParse( prompt );
+  if ( !result.success ) {
+    appendCamelCaseSuggestions( result.error );
+
+    throw new ValidationError(
+      `Invalid prompt file ${prompt.name}: ${z.prettifyError( result.error )}`,
+      { cause: result.error }
+    );
+  }
+  return result.data;
+};

package/src/llm/utils/cost.js

@@ -0,0 +1,150 @@
+import { fetchModelsPricing, Freshness } from './models_pricing.js';
+import { BaseAttribute } from '#trace_attribute';
+import { LLMGenerationUsage, LLMGenerationUsageItem } from './usage.js';
+import { GroundingPpmMap } from './grounding.js';
+import { Logger } from '#runtime_logger';
+import Decimal from 'decimal.js';
+
+const exists = v => Number.isFinite( v );
+
+export class LLMGenerationCostItem {
+  static Status = Object.freeze( {
+    OK: 'ok',
+    FALLBACK: 'fallback',
+    MISSING: 'missing'
+  } );
+
+  group;
+  label;
+  amount;
+  ppm;
+  total;
+  status;
+
+  constructor( group, label, amount, ppm, total, status ) {
+    this.group = group;
+    this.label = label;
+    this.amount = amount;
+    this.ppm = ppm;
+    this.total = total;
+    this.status = status;
+  }
+}
+
+export class LLMGenerationCost extends BaseAttribute {
+  static TYPE = 'llm:generation:cost';
+  static Status = Object.freeze( {
+    PRECISE: 'precise',
+    IMPRECISE: 'imprecise',
+    INCOMPLETE: 'incomplete'
+  } );
+  providerId;
+  modelId;
+  input = null;
+  output = null;
+  tools = null;
+  total = null;
+  status = LLMGenerationCost.Status.INCOMPLETE;
+  pricingFreshness = null;
+  items = [];
+
+  constructor( modelId, providerId, items, usageStatus, pricingFreshness ) {
+    super( LLMGenerationCost.TYPE );
+    this.modelId = modelId;
+    this.providerId = providerId;
+    this.items = items;
+    this.pricingFreshness = pricingFreshness;
+
+    const meaningfulItems = items.filter( v => v.amount > 0 );
+
+    if ( meaningfulItems.some( v => v.status === LLMGenerationCostItem.Status.MISSING ) || usageStatus === LLMGenerationUsage.Status.INCOMPLETE ) {
+      this.status = LLMGenerationCost.Status.INCOMPLETE;
+    } else if ( meaningfulItems.some( v => v.status === LLMGenerationCostItem.Status.FALLBACK ) || pricingFreshness === Freshness.SNAPSHOT ) {
+      this.status = LLMGenerationCost.Status.IMPRECISE;
+    } else {
+      this.status = LLMGenerationCost.Status.PRECISE;
+    }
+    const sumGroup = group => {
+      const groupItems = items.filter( p => p.group === group && exists( p.total ) );
+      return groupItems.length > 0 ? groupItems.reduce( ( s, p ) => s.add( p.total ), Decimal( 0 ) ).toNumber() : null;
+    };
+    this.input = sumGroup( LLMGenerationUsageItem.Group.INPUT );
+    this.output = sumGroup( LLMGenerationUsageItem.Group.OUTPUT );
+    this.tools = sumGroup( LLMGenerationUsageItem.Group.TOOLS );
+    if ( exists( this.input ) || exists( this.output ) || exists( this.tools ) ) {
+      this.total = Decimal( this.input ?? 0 ).add( this.output ?? 0 ).add( this.tools ?? 0 ).toNumber();
+    }
+  }
+}
+
+const resolveValue = values => {
+  if ( exists( values[0] ) ) {
+    return { ppm: values[0], status: LLMGenerationCostItem.Status.OK };
+  }
+  const fallback = values.slice( 1 ).find( exists );
+  if ( exists( fallback ) ) {
+    return { ppm: fallback, status: LLMGenerationCostItem.Status.FALLBACK };
+  }
+  return { ppm: null, status: LLMGenerationCostItem.Status.MISSING };
+};
+
+const resolvePrice = ( { group, label, pricing } ) => {
+  // Tool charges are never token-priced: models.dev has no rate for them.
+  if ( group === LLMGenerationUsageItem.Group.TOOLS ) {
+    return resolveValue( [ GroundingPpmMap.get( label ) ] );
+  }
+  if ( !pricing ) {
+    return resolveValue( [] );
+  }
+  if ( group === LLMGenerationUsageItem.Group.OUTPUT ) {
+    const values = [ pricing.output ];
+    if ( label === 'reasoning' ) {
+      values.unshift( pricing.reasoning );
+    }
+    return resolveValue( values );
+  }
+
+  const values = [ pricing.input ];
+  if ( label === 'cache_read' ) {
+    values.unshift( pricing.cache_read );
+  } else if ( label === 'cache_write' ) {
+    values.unshift( pricing.cache_write );
+  }
+  return resolveValue( values );
+};
+
+/**
+ * Calculates the cost of an LLM call based on the LLMGenerationUsage.
+ *
+ * @param {LLMGenerationUsage} usage - Normalized LLM generation usage
+ * @returns {Promise<LLMGenerationCost | null>} LLM generation cost with input, output, total and breakdown
+ */
+export const calculateCosts = async usage => {
+  const { models, freshness: pricingFreshness } = await fetchModelsPricing();
+
+  if ( !models ) {
+    Logger.warn( 'Failed to fetch models pricing', { namespace: 'LLM' } );
+    return null;
+  }
+
+  const { providerId, modelId } = usage;
+
+  const pricing = models.get( `${providerId}/${modelId}` );
+  if ( !pricing ) {
+    Logger.warn( 'Missing pricing reference for model', { namespace: 'LLM', modelId, providerId } );
+  }
+
+  const items = usage.items.map( ( { group, label, amount } ) => {
+    const { ppm, status } = resolvePrice( { pricing, group, label } );
+    const total = exists( ppm ) ? Decimal( amount ).div( 1_000_000 ).mul( ppm ).toNumber() : null;
+    return new LLMGenerationCostItem( group, label, amount, ppm, total, status );
+  } );
+
+  const unrated = items.find( v =>
+    v.group === LLMGenerationUsageItem.Group.TOOLS && v.status === LLMGenerationCostItem.Status.MISSING );
+  if ( unrated ) {
+    Logger.warn( 'Tool call with no rate for model', { namespace: 'LLM', modelId, providerId, type: unrated.label } );
+  }
+
+  return new LLMGenerationCost( modelId, providerId, items, usage.status, pricingFreshness );
+};

package/src/llm/utils/error_handler.js

@@ -0,0 +1,53 @@
+import * as ai from 'ai';
+import { FatalError, TransparentFatalError } from '#errors';
+
+const nonRetryableAiSdkErrorTypes = [
+  ai.InvalidArgumentError, // Invalid call settings are deterministic caller bugs, so retrying the same activity cannot fix them.
+  ai.InvalidDataContentError, // Invalid media content has the wrong local shape/encoding and will fail again with the same input.
+  ai.InvalidPromptError, // Invalid prompt structure is a deterministic request-construction error.
+  ai.LoadAPIKeyError, // Missing or invalid API key configuration will not change during an activity retry.
+  ai.LoadSettingError, // Missing or invalid provider settings are deployment/configuration problems.
+  ai.NoImageGeneratedError, // Image generation completed provider calls but collected zero images; repeating identical input is not useful.
+  ai.NoSuchProviderError, // A missing provider id is a deterministic provider registry/configuration error.
+  ai.NoSuchModelError, // A missing model id is a deterministic provider/model configuration error.
+  ai.UnsupportedFunctionalityError // The selected model/output mode does not support the requested feature.
+];
+
+/**
+ * Maps an AI SDK error to a framework error:
+ * - AI SDK Unrecoverable error types become TransparentFatalErrors;
+ * - AI SDK API error with isRetryable=false become TransparentFatalErrors;
+ * Some errors are not mapped:
+ * - Grammar which technically are isRetryable=false, will be rethrown, because they are actually transient;
+ * - Other errors are rethrown as well;
+ *
+ * @param {object} error - Original Error
+ * @returns {object} A new Error
+ */
+export const mapAiError = error => {
+  if ( !( error instanceof Error ) ) {
+    return error;
+  }
+
+  if ( error instanceof FatalError ) {
+    return error;
+  }
+
+  const isApiError = ai.APICallError.isInstance( error );
+  const isGrammarCompilationError = error.message === 'Grammar compilation timed out.';
+
+  // This error is actually transient, so instead of FatalError, return it
+  if ( isApiError && error.statusCode === 400 && isGrammarCompilationError ) {
+    return error;
+  }
+
+  // Non-retryable API failures are already classified by AI SDK as permanent provider failures.
+  if ( isApiError && !error.isRetryable ) {
+    return new TransparentFatalError( error );
+  }
+
+  if ( nonRetryableAiSdkErrorTypes.some( E => E.isInstance( error ) ) ) {
+    return new TransparentFatalError( error );
+  }
+  return error;
+};

package/src/llm/utils/file.js

@@ -0,0 +1,42 @@
+import { join } from 'path';
+import { readdirSync, readFileSync } from 'node:fs';
+import { FatalError } from '#errors';
+
+const scanDir = dir => {
+  try {
+    return readdirSync( dir, { withFileTypes: true } );
+  } catch ( error ) {
+    throw new FatalError( `Error scanning directory "${dir}"`, { cause: error } );
+  }
+};
+
+const readFile = path => {
+  try {
+    return readFileSync( path, 'utf-8' );
+  } catch ( error ) {
+    throw new FatalError( `Error reading file "${path}"`, { cause: error } );
+  }
+};
+
+/**
+ * Recursively search for a file by name and return both its content and containing directory.
+ *
+ * @param {string} dir - Directory to search
+ * @param {string} name - File name to find
+ * @returns {{ content: string, dir: string } | null}
+ */
+export const searchAndReadFile = ( dir, name ) => {
+  for ( const entry of scanDir( dir ) ) {
+    const path = join( dir, entry.name );
+    if ( entry.name === name ) {
+      return { dir, content: readFile( path ) };
+    }
+    if ( entry.isDirectory() && !entry.isSymbolicLink() ) {
+      const result = searchAndReadFile( path, name );
+      if ( result ) {
+        return result;
+      }
+    }
+  }
+  return null;
+};