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

package/src/prompt/blocks.js

@@ -0,0 +1,47 @@
+/**
+ * Roles that introduce a message block. Add a role here to support a new
+ * `<role>...</role>` block — the tokenizer pattern is derived from this set,
+ * so no other parser change is required.
+ */
+export const BLOCK_ROLES = new Set( [ 'system', 'user', 'assistant', 'tool' ] );
+
+const BLOCK_PATTERN = new RegExp(
+  `<(${[ ...BLOCK_ROLES ].join( '|' )})((?:\\s[^>]*)?)>([\\s\\S]*?)<\\/\\1>`,
+  'gm'
+);
+
+const ATTRIBUTE_PATTERN = /([a-zA-Z][\w-]*)(?:=(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
+
+/**
+ * Parse a raw opening-tag attribute string into a plain object. Supports bare booleans
+ * (`cache`), double/single-quoted values, and unquoted values:
+ * `cache options="a b" ttl='1h'` → `{ cache: true, options: 'a b', ttl: '1h' }`.
+ *
+ * @param {string} [raw] - Raw attribute text between the role and the closing `>`
+ * @returns {Record<string, string | true>} Parsed attributes
+ */
+export const parseAttributes = ( raw = '' ) =>
+  Object.fromEntries(
+    [ ...raw.matchAll( ATTRIBUTE_PATTERN ) ].map(
+      ( [ _, key, doubleQuoted, singleQuoted, bare ] ) =>
+        [ key, doubleQuoted ?? singleQuoted ?? bare ?? true ]
+    )
+  );
+
+/**
+ * Tokenize a rendered prompt body into message blocks. Each block is `{ role, content }`,
+ * plus `attributes` when the opening tag carried any. Content between role tags is treated
+ * as opaque text, so prompt bodies may freely contain other angle-bracket markup.
+ *
+ * @param {string} content - Rendered prompt body (after frontmatter is stripped)
+ * @returns {Array<{ role: string, content: string, attributes?: Record<string, string | true> }>}
+ */
+export const tokenizeBlocks = content =>
+  [ ...content.matchAll( BLOCK_PATTERN ) ].map( ( [ _, role, rawAttributes, text ] ) => {
+    const attributes = parseAttributes( rawAttributes.trim() );
+    return {
+      role,
+      content: text.trim(),
+      ...( Object.keys( attributes ).length > 0 && { attributes } )
+    };
+  } );

package/src/prompt/blocks.spec.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { parseAttributes, tokenizeBlocks, BLOCK_ROLES } from './blocks.js';
+
+describe( 'parseAttributes', () => {
+  it( 'parses a bare attribute as boolean true', () => {
+    expect( parseAttributes( 'pinned' ) ).toEqual( { pinned: true } );
+  } );
+
+  it( 'parses double- and single-quoted values', () => {
+    expect( parseAttributes( 'ttl="1h" mode=\'fast\'' ) ).toEqual( { ttl: '1h', mode: 'fast' } );
+  } );
+
+  it( 'parses unquoted values', () => {
+    expect( parseAttributes( 'ttl=1h' ) ).toEqual( { ttl: '1h' } );
+  } );
+
+  it( 'parses multiple attributes and preserves spaces inside quotes', () => {
+    expect( parseAttributes( 'pinned options="cached fast"' ) ).toEqual( {
+      pinned: true,
+      options: 'cached fast'
+    } );
+  } );
+
+  it( 'returns an empty object for blank input', () => {
+    expect( parseAttributes( '' ) ).toEqual( {} );
+    expect( parseAttributes() ).toEqual( {} );
+  } );
+} );
+
+describe( 'tokenizeBlocks', () => {
+  it( 'tokenizes plain blocks without an attributes key', () => {
+    const blocks = tokenizeBlocks( '<system>Hi</system>\n<user>Yo</user>' );
+    expect( blocks ).toEqual( [
+      { role: 'system', content: 'Hi' },
+      { role: 'user', content: 'Yo' }
+    ] );
+  } );
+
+  it( 'attaches parsed attributes to the block', () => {
+    const blocks = tokenizeBlocks( '<system options="a b" pinned>Hi</system>' );
+    expect( blocks[0] ).toEqual( {
+      role: 'system',
+      content: 'Hi',
+      attributes: { options: 'a b', pinned: true }
+    } );
+  } );
+
+  it( 'captures unknown attributes generically (validation rejects them later)', () => {
+    const blocks = tokenizeBlocks( '<user data="x">Hi</user>' );
+    expect( blocks[0].attributes ).toEqual( { data: 'x' } );
+  } );
+
+  it( 'treats angle-bracket markup inside a block as opaque content', () => {
+    const blocks = tokenizeBlocks( '<user>Compare <div> and <span> tags</user>' );
+    expect( blocks[0] ).toEqual( { role: 'user', content: 'Compare <div> and <span> tags' } );
+  } );
+
+  it( 'tokenizes every registered role', () => {
+    const body = [ ...BLOCK_ROLES ].map( role => `<${role}>${role} body</${role}>` ).join( '\n' );
+    const blocks = tokenizeBlocks( body );
+    expect( blocks.map( block => block.role ) ).toEqual( [ ...BLOCK_ROLES ] );
+  } );
+} );

package/src/prompt/parser.js

@@ -1,5 +1,6 @@
 import matter from 'gray-matter';
 import { FatalError } from '@outputai/core';
+import { tokenizeBlocks } from './blocks.js';
 
 export function parsePrompt( { name, raw } ) {
   const { data: config, content } = matter( raw );
@@ -8,11 +9,7 @@ export function parsePrompt( { name, raw } ) {
     throw new FatalError( `Prompt "${name}" has no content after frontmatter` );
   }
 
-  const infoExtractor = /<(system|user|assistant|tool)>([\s\S]*?)<\/\1>/gm;
-  const messages = [ ...content.matchAll( infoExtractor ) ].map(
-    ( [ _, role, text ] ) => ( { role, content: text.trim() } )
-  );
-
+  const messages = tokenizeBlocks( content );
   const instructions = messages.length === 0 ? content.trim() : null;
 
   return { config, messages, instructions };

package/src/prompt/parser.spec.js

@@ -164,4 +164,23 @@ model: claude-3-5-sonnet-20241022
     ] );
     expect( result.instructions ).toBeNull();
   } );
+
+  it( 'surfaces block opening-tag attributes as an attributes object', () => {
+    const raw = `---
+provider: anthropic
+model: claude-sonnet-4-5
+---
+
+<system options="cached">Static.</system>
+<user>Question</user>`;
+
+    const result = parsePrompt( { name: 'test', raw } );
+
+    expect( result.messages[0] ).toEqual( {
+      role: 'system',
+      content: 'Static.',
+      attributes: { options: 'cached' }
+    } );
+    expect( result.messages[1] ).toEqual( { role: 'user', content: 'Question' } );
+  } );
 } );

package/src/prompt/validations.js

@@ -1,4 +1,11 @@
 import { ValidationError, z } from '@outputai/core';
+import { attributesSchema } from './block_options.js';
+
+const toolConfigSchema = z.record( z.string(), z.unknown() );
+const toolsConfigSchema = z.record( z.string(), toolConfigSchema );
+
+// A provider-namespaced options object, e.g. { anthropic: { cacheControl: { type: 'ephemeral' } } }
+const providerOptionsSchema = z.record( z.string(), z.record( z.string(), z.unknown() ) );
 
 export const promptSchema = z.object( {
   name: z.string(),
@@ -13,18 +20,20 @@ export const promptSchema = z.object( {
     aspectRatio: z.string().regex( /^\d+:\d+$/ ).optional(),
     seed: z.number().int().optional(),
     skills: z.union( [ z.string().min( 1 ), z.array( z.string().min( 1 ) ) ] ).optional(),
-    tools: z.record( z.string(), z.object( {} ).loose() ).optional(),
+    tools: toolsConfigSchema.optional(),
     providerOptions: z.object( {
       thinking: z.object( {
         type: z.enum( [ 'enabled', 'disabled' ] ),
         budgetTokens: z.number().optional()
       } ).loose().optional()
-    } ).loose().optional()
+    } ).loose().optional(),
+    messageOptions: z.record( z.string(), providerOptionsSchema ).optional()
   } ).loose(),
   messages: z.array(
     z.object( {
       role: z.string(),
-      content: z.string()
+      content: z.string(),
+      attributes: attributesSchema.optional()
     } ).strict()
   ),
   instructions: z.string().trim().min( 1 ).nullable().optional()

package/src/prompt/validations.spec.js

@@ -384,6 +384,71 @@ describe( 'validatePrompt', () => {
     expect( () => validatePrompt( promptWithSkill ) ).not.toThrow();
   } );
 
+  it( 'should validate provider tool config records', () => {
+    const promptWithTools = {
+      name: 'tools-prompt',
+      config: {
+        provider: 'vertex',
+        model: 'gemini-2.0-flash',
+        tools: {
+          googleSearch: {
+            mode: 'MODE_DYNAMIC',
+            dynamicThreshold: 0.8
+          },
+          urlContext: {}
+        }
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Research this.'
+        }
+      ]
+    };
+
+    expect( () => validatePrompt( promptWithTools ) ).not.toThrow();
+  } );
+
+  it( 'should throw ValidationError when tools config is not a record', () => {
+    const invalidToolsPrompt = {
+      name: 'invalid-tools-prompt',
+      config: {
+        provider: 'vertex',
+        model: 'gemini-2.0-flash',
+        tools: [ 'googleSearch' ]
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Research this.'
+        }
+      ]
+    };
+
+    expect( () => validatePrompt( invalidToolsPrompt ) ).toThrow( ValidationError );
+  } );
+
+  it( 'should throw ValidationError when a tool config is not a record', () => {
+    const invalidToolConfigPrompt = {
+      name: 'invalid-tool-config-prompt',
+      config: {
+        provider: 'vertex',
+        model: 'gemini-2.0-flash',
+        tools: {
+          googleSearch: 'MODE_DYNAMIC'
+        }
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Research this.'
+        }
+      ]
+    };
+
+    expect( () => validatePrompt( invalidToolConfigPrompt ) ).toThrow( ValidationError );
+  } );
+
   it( 'should throw ValidationError for invalid skill path config', () => {
     const invalidSkillsPrompt = {
       name: 'invalid-skills-prompt',
@@ -531,4 +596,53 @@ describe( 'validatePrompt', () => {
 
     expect( () => validatePrompt( maxTokensSnakeCase ) ).not.toThrow();
   } );
+
+  it( 'should validate the options attribute referencing messageOptions sets', () => {
+    const promptWithMessageOptions = {
+      name: 'message-options-prompt',
+      config: {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-5',
+        messageOptions: {
+          cached: { anthropic: { cacheControl: { type: 'ephemeral' } } }
+        }
+      },
+      messages: [
+        { role: 'system', content: 'Docs.', attributes: { options: 'cached' } },
+        { role: 'user', content: 'Question' }
+      ]
+    };
+
+    expect( () => validatePrompt( promptWithMessageOptions ) ).not.toThrow();
+  } );
+
+  it( 'should reject the removed cache shorthand as an unknown block attribute', () => {
+    const cacheShorthandPrompt = {
+      name: 'cache-shorthand-prompt',
+      config: {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-5'
+      },
+      messages: [
+        { role: 'system', content: 'Static.', attributes: { cache: true } }
+      ]
+    };
+
+    expect( () => validatePrompt( cacheShorthandPrompt ) ).toThrow( ValidationError );
+  } );
+
+  it( 'should throw ValidationError for unknown top-level message fields', () => {
+    const unknownFieldPrompt = {
+      name: 'unknown-field-prompt',
+      config: {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-5'
+      },
+      messages: [
+        { role: 'user', content: 'Hi', options: 'cached' }
+      ]
+    };
+
+    expect( () => validatePrompt( unknownFieldPrompt ) ).toThrow( ValidationError );
+  } );
 } );

package/src/utils/error_handler.js

@@ -13,6 +13,9 @@ import {
 } from 'ai';
 import { FatalError } from '@outputai/core';
 
+// AI SDK does not expose a dedicated schema-mismatch discriminator for NoObjectGeneratedError.
+const NO_OBJECT_SCHEMA_MISMATCH_MESSAGE = 'No object generated: response did not match schema.';
+
 /**
  * Recursively search an error cause chain until finds an error which is instance of given prototype.
  *
@@ -25,7 +28,7 @@ export const findInstanceInCauseChain = ( error, _class, depth = 0 ) => {
   if ( !error || typeof error !== 'object' ) {
     return null;
   }
-  if ( typeof _class === 'string' && error.constructor.name === _class ) {
+  if ( typeof _class === 'string' && error.constructor?.name === _class ) {
     return error;
   }
   if ( typeof _class === 'function' && error instanceof _class ) {
@@ -42,20 +45,34 @@ const toFatalError = ( error, extraMessage = '' ) => new FatalError(
   { cause: error }
 );
 
+/**
+ * Map an AI SDK error to a framework specific error:
+ *
+ * - AI SDK Unrecoverable errors become FatalErrors, check code to see options.
+ * - NoObjectGeneratedError from invalid schema are reinitialized with a better message.
+ * - Other errors are preserved.
+ * @param {object} error - Original Error
+ * @returns {object} A new Error
+ */
 export const mapAiError = error => {
   if ( error instanceof FatalError ) {
     return error;
   }
 
-  // NoObjectGeneratedError can be thrown when the response doesn't match the schema
-  // This adds a wrapper to that error serializing the first zod validation in the message, to make it easier to debug.
-  if ( NoObjectGeneratedError.isInstance( error ) && error.message.includes( 'No object generated: response did not match schema.' ) ) {
+  // NoObjectGeneratedError can be thrown when the response doesn't match the schema.
+  // This re-creates the error with a better message, making it easier to debug.
+  if ( NoObjectGeneratedError.isInstance( error ) && error.message.includes( NO_OBJECT_SCHEMA_MISMATCH_MESSAGE ) ) {
     const zodError = findInstanceInCauseChain( error, 'ZodError' );
     if ( zodError && zodError.issues?.length > 0 ) {
-      const { path, message } = zodError.issues[0];
-      const wrapper = new Error( `${error.message} First issue is "${message}" at path [${path.join( ', ' )}].`, { cause: error } );
-      wrapper.name = 'NoObjectGeneratedError';
-      return wrapper;
+      const [ { path, message } ] = zodError.issues;
+      return new NoObjectGeneratedError( {
+        message: `${error.message} First issue is "${message}" at path [${path.join( ', ' )}].`,
+        cause: error.cause,
+        text: error.text,
+        response: error.response,
+        usage: error.usage,
+        finishReason: error.finishReason
+      } );
     }
     return error;
   }

package/src/utils/error_handler.spec.js

@@ -171,6 +171,13 @@ describe( 'findInstanceInCauseChain', () => {
     expect( findInstanceInCauseChain( 'not an error', Error ) ).toBeNull();
   } );
 
+  it( 'returns null for object causes without constructors', () => {
+    const cause = Object.create( null );
+    const error = new FirstCustomError( 'first', { cause } );
+
+    expect( findInstanceInCauseChain( error, 'SecondCustomError' ) ).toBeNull();
+  } );
+
   it( 'stops searching after the depth limit', () => {
     const makeErrorChain = depth => depth === 0 ?
       new SecondCustomError( 'target' ) :
@@ -204,17 +211,25 @@ describe( 'mapAiError', () => {
     const error = new NoObjectGeneratedError( {
       message: 'No object generated: response did not match schema.',
       text: '{"items":[{}]}',
+      response: { id: 'response-1' },
+      usage: { totalTokens: 10 },
+      finishReason: 'stop',
       cause: validationError
     } );
 
     const result = mapAiError( error );
 
     expect( result ).not.toBe( error );
-    expect( result.name ).toBe( 'NoObjectGeneratedError' );
+    expect( NoObjectGeneratedError.isInstance( result ) ).toBe( true );
+    expect( result.name ).toBe( 'AI_NoObjectGeneratedError' );
     expect( result.message ).toBe(
       'No object generated: response did not match schema. First issue is "Expected string" at path [items, 0, title].'
     );
-    expect( result.cause ).toBe( error );
+    expect( result.cause ).toBe( validationError );
+    expect( result.text ).toBe( error.text );
+    expect( result.response ).toBe( error.response );
+    expect( result.usage ).toBe( error.usage );
+    expect( result.finishReason ).toBe( error.finishReason );
   } );
 
   it( 'preserves NoObjectGeneratedError schema mismatches when no schema issue is available', () => {