@outputai/llm 0.6.1-dev.aab2335.0 → 0.6.1-next.0d08ff5.0

package/src/{parser.spec.js → prompt/parser.spec.js}

@@ -11,7 +11,7 @@ model: claude-3-5-sonnet-20241022
 <system>You are a helpful assistant.</system>
 <user>Hello!</user>`;
 
-    const result = parsePrompt( raw );
+    const result = parsePrompt( { name: 'test', raw } );
 
     expect( result.config ).toEqual( {
       provider: 'anthropic',
@@ -26,39 +26,58 @@ model: claude-3-5-sonnet-20241022
       role: 'user',
       content: 'Hello!'
     } );
+    expect( result.instructions ).toBeNull();
   } );
 
-  it( 'throws error when content is empty', () => {
+  it( 'parses raw instructions when no message blocks are present', () => {
     const raw = `---
-provider: anthropic
-model: claude-3-5-sonnet-20241022
+provider: openai
+model: gpt-image-1
 ---
 
+Generate a cinematic image of a NASCAR race at sunset.`;
+
+    const result = parsePrompt( { name: 'image_prompt', raw } );
+
+    expect( result ).toEqual( {
+      config: {
+        provider: 'openai',
+        model: 'gpt-image-1'
+      },
+      messages: [],
+      instructions: 'Generate a cinematic image of a NASCAR race at sunset.'
+    } );
+  } );
+
+  it( 'trims raw instructions', () => {
+    const raw = `---
+provider: openai
+model: gpt-image-1
+---
+
+  Generate a poster.
+
 `;
 
-    expect( () => {
-      parsePrompt( raw );
-    } ).toThrow( /no content after frontmatter/ );
+    const result = parsePrompt( { name: 'image_prompt', raw } );
+
+    expect( result.instructions ).toBe( 'Generate a poster.' );
   } );
 
-  it( 'throws error when no valid message blocks found', () => {
+  it( 'throws error when content is empty', () => {
     const raw = `---
 provider: anthropic
 model: claude-3-5-sonnet-20241022
 ---
 
-This is just plain text without any message tags.`;
+`;
 
     expect( () => {
-      parsePrompt( raw );
-    } ).toThrow( /No valid message blocks found/ );
-    expect( () => {
-      parsePrompt( raw );
-    } ).toThrow( /Expected format/ );
+      parsePrompt( { name: 'empty_prompt', raw } );
+    } ).toThrow( /Prompt "empty_prompt" has no content after frontmatter/ );
   } );
 
-  it( 'should use providerOptions with budgetTokens in camelCase', () => {
-    // Frontmatter uses canonical format: providerOptions.thinking.budgetTokens
+  it( 'parses providerOptions with budgetTokens in camelCase', () => {
     const raw = `---
 provider: anthropic
 model: claude-sonnet-4-20250514
@@ -72,22 +91,19 @@ providerOptions:
 
 <user>Test</user>`;
 
-    const result = parsePrompt( raw );
+    const result = parsePrompt( { name: 'test', raw } );
 
     expect( result.config.provider ).toBe( 'anthropic' );
     expect( result.config.model ).toBe( 'claude-sonnet-4-20250514' );
     expect( result.config.temperature ).toBe( 0.7 );
     expect( result.config.maxTokens ).toBe( 64000 );
-
-    // Now expects canonical schema format in front-matter
     expect( result.config.providerOptions ).toBeDefined();
     expect( result.config.providerOptions.thinking ).toBeDefined();
     expect( result.config.providerOptions.thinking.type ).toBe( 'enabled' );
     expect( result.config.providerOptions.thinking.budgetTokens ).toBe( 1500 );
   } );
 
-  it( 'should parse snake_case fields as-is (validation catches them later)', () => {
-    // Parser extracts fields as-is from frontmatter; validation happens later
+  it( 'parses snake_case fields as-is so validation can catch them later', () => {
     const raw = `---
 provider: anthropic
 model: claude-sonnet-4-20250514
@@ -101,22 +117,51 @@ providerOptions:
 
 <user>Test</user>`;
 
-    const result = parsePrompt( raw );
+    const result = parsePrompt( { name: 'test', raw } );
 
-    // Parser extracts snake_case fields as-is
     expect( result.config.provider ).toBe( 'anthropic' );
     expect( result.config.model ).toBe( 'claude-sonnet-4-20250514' );
     expect( result.config.temperature ).toBe( 0.7 );
-    // snake_case preserved here because we're only calling parsePrompt, not validatePrompt
     expect( result.config.max_tokens ).toBe( 64000 );
-    // camelCase not set because we only call parsePrompt
     expect( result.config.maxTokens ).toBeUndefined();
-
-    // Snake_case fields in nested objects also preserved
     expect( result.config.providerOptions ).toBeDefined();
     expect( result.config.providerOptions.thinking ).toBeDefined();
     expect( result.config.providerOptions.thinking.type ).toBe( 'enabled' );
-    expect( result.config.providerOptions.thinking.budget_tokens ).toBe( 1500 ); // snake_case preserved
-    expect( result.config.providerOptions.thinking.budgetTokens ).toBeUndefined(); // camelCase not set
+    expect( result.config.providerOptions.thinking.budget_tokens ).toBe( 1500 );
+    expect( result.config.providerOptions.thinking.budgetTokens ).toBeUndefined();
+  } );
+
+  it( 'parses supported message roles', () => {
+    const raw = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+---
+
+<system>System message</system>
+<assistant>Assistant message</assistant>
+<tool>Tool message</tool>
+<user>User message</user>`;
+
+    const result = parsePrompt( { name: 'test', raw } );
+
+    expect( result.messages ).toEqual( [
+      {
+        role: 'system',
+        content: 'System message'
+      },
+      {
+        role: 'assistant',
+        content: 'Assistant message'
+      },
+      {
+        role: 'tool',
+        content: 'Tool message'
+      },
+      {
+        role: 'user',
+        content: 'User message'
+      }
+    ] );
+    expect( result.instructions ).toBeNull();
   } );
 } );

package/src/prompt/prepare_text.js

@@ -0,0 +1,27 @@
+import { loadPrompt } from './loader.js';
+import { buildSystemSkillsVar, buildLoadSkillTool, resolvePromptSkills } from './skill.js';
+
+export const prepareTextPrompt = ( { prompt, variables, promptDir, skills, tools } ) => {
+  const loadedPrompt = loadPrompt( prompt, variables, promptDir );
+
+  const resolvedSkills = resolvePromptSkills( loadedPrompt, skills );
+
+  const result = { loadedPrompt, tools: tools ? { ...tools } : null };
+
+  if ( resolvedSkills.length > 0 ) {
+    result.tools = {
+      load_skill: buildLoadSkillTool( resolvedSkills ),
+      ...( result.tools ?? {} )
+    };
+
+    const skillsMessage = { role: 'system', content: buildSystemSkillsVar( resolvedSkills ) };
+    const systemMessage = loadedPrompt.messages.find( m => m.role === 'system' );
+    if ( systemMessage ) {
+      systemMessage.content = `${systemMessage.content}\n\n${skillsMessage.content}`;
+    } else {
+      loadedPrompt.messages.unshift( skillsMessage );
+    }
+  }
+
+  return result;
+};

package/src/prompt/prepare_text.spec.js

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const loadPromptImpl = vi.fn();
+const resolvePromptSkillsImpl = vi.fn();
+const buildLoadSkillToolImpl = vi.fn();
+const buildSystemSkillsVarImpl = vi.fn();
+
+vi.mock( './loader.js', () => ( {
+  loadPrompt: ( ...args ) => loadPromptImpl( ...args )
+} ) );
+
+vi.mock( './skill.js', () => ( {
+  resolvePromptSkills: ( ...args ) => resolvePromptSkillsImpl( ...args ),
+  buildLoadSkillTool: ( ...args ) => buildLoadSkillToolImpl( ...args ),
+  buildSystemSkillsVar: ( ...args ) => buildSystemSkillsVarImpl( ...args )
+} ) );
+
+const importSut = async () => import( './prepare_text.js' );
+
+const makePrompt = messages => ( {
+  name: 'test@v1',
+  config: { provider: 'anthropic', model: 'claude-haiku-4-5' },
+  messages,
+  promptFileDir: '/prompts'
+} );
+
+describe( 'prepareTextPrompt', () => {
+  beforeEach( () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    resolvePromptSkillsImpl.mockReturnValue( [] );
+    buildLoadSkillToolImpl.mockReturnValue( { type: 'load-skill-tool' } );
+    buildSystemSkillsVarImpl.mockReturnValue( 'Available skills:\n- copy: Copy guidance' );
+  } );
+
+  it( 'loads and returns a prompt with caller tools when no skills resolve', async () => {
+    const loadedPrompt = makePrompt( [ { role: 'user', content: 'Hello' } ] );
+    const tools = { search: { type: 'search-tool' } };
+    loadPromptImpl.mockReturnValue( loadedPrompt );
+
+    const { prepareTextPrompt } = await importSut();
+    const result = prepareTextPrompt( {
+      prompt: 'test@v1',
+      variables: { name: 'Ada' },
+      promptDir: '/workflow',
+      skills: [],
+      tools
+    } );
+
+    expect( loadPromptImpl ).toHaveBeenCalledWith( 'test@v1', { name: 'Ada' }, '/workflow' );
+    expect( resolvePromptSkillsImpl ).toHaveBeenCalledWith( loadedPrompt, [] );
+    expect( result ).toEqual( {
+      loadedPrompt,
+      tools
+    } );
+    expect( result.tools ).not.toBe( tools );
+    expect( buildLoadSkillToolImpl ).not.toHaveBeenCalled();
+    expect( buildSystemSkillsVarImpl ).not.toHaveBeenCalled();
+  } );
+
+  it( 'returns null tools when no caller tools or skills resolve', async () => {
+    const loadedPrompt = makePrompt( [ { role: 'user', content: 'Hello' } ] );
+    loadPromptImpl.mockReturnValue( loadedPrompt );
+
+    const { prepareTextPrompt } = await importSut();
+    const result = prepareTextPrompt( {
+      prompt: 'test@v1',
+      variables: {},
+      skills: []
+    } );
+
+    expect( result ).toEqual( {
+      loadedPrompt,
+      tools: null
+    } );
+    expect( buildLoadSkillToolImpl ).not.toHaveBeenCalled();
+    expect( buildSystemSkillsVarImpl ).not.toHaveBeenCalled();
+  } );
+
+  it( 'adds load_skill and prepends a system message when skills resolve without an existing system message', async () => {
+    const loadedPrompt = makePrompt( [ { role: 'user', content: 'Hello' } ] );
+    const resolvedSkills = [ { name: 'copy', description: 'Copy guidance', instructions: '# Copy' } ];
+    loadPromptImpl.mockReturnValue( loadedPrompt );
+    resolvePromptSkillsImpl.mockReturnValue( resolvedSkills );
+
+    const { prepareTextPrompt } = await importSut();
+    const result = prepareTextPrompt( {
+      prompt: 'test@v1',
+      variables: {},
+      skills: resolvedSkills
+    } );
+
+    expect( buildLoadSkillToolImpl ).toHaveBeenCalledWith( resolvedSkills );
+    expect( buildSystemSkillsVarImpl ).toHaveBeenCalledWith( resolvedSkills );
+    expect( result.tools.load_skill ).toEqual( { type: 'load-skill-tool' } );
+    expect( loadedPrompt.messages ).toEqual( [
+      { role: 'system', content: 'Available skills:\n- copy: Copy guidance' },
+      { role: 'user', content: 'Hello' }
+    ] );
+  } );
+
+  it( 'merges skill instructions into an existing system message', async () => {
+    const loadedPrompt = makePrompt( [
+      { role: 'system', content: 'You are concise.' },
+      { role: 'user', content: 'Hello' }
+    ] );
+    const resolvedSkills = [ { name: 'copy', description: 'Copy guidance', instructions: '# Copy' } ];
+    loadPromptImpl.mockReturnValue( loadedPrompt );
+    resolvePromptSkillsImpl.mockReturnValue( resolvedSkills );
+
+    const { prepareTextPrompt } = await importSut();
+    prepareTextPrompt( {
+      prompt: 'test@v1',
+      variables: {},
+      skills: resolvedSkills
+    } );
+
+    expect( loadedPrompt.messages ).toEqual( [
+      { role: 'system', content: 'You are concise.\n\nAvailable skills:\n- copy: Copy guidance' },
+      { role: 'user', content: 'Hello' }
+    ] );
+  } );
+
+  it( 'allows caller tools to override the generated load_skill tool', async () => {
+    const loadedPrompt = makePrompt( [ { role: 'user', content: 'Hello' } ] );
+    const resolvedSkills = [ { name: 'copy', description: 'Copy guidance', instructions: '# Copy' } ];
+    const callerLoadSkill = { type: 'caller-load-skill-tool' };
+    loadPromptImpl.mockReturnValue( loadedPrompt );
+    resolvePromptSkillsImpl.mockReturnValue( resolvedSkills );
+
+    const { prepareTextPrompt } = await importSut();
+    const result = prepareTextPrompt( {
+      prompt: 'test@v1',
+      variables: {},
+      skills: resolvedSkills,
+      tools: { load_skill: callerLoadSkill }
+    } );
+
+    expect( result.tools.load_skill ).toBe( callerLoadSkill );
+  } );
+} );

package/src/{skill.js → prompt/skill.js}

@@ -80,6 +80,25 @@ export const loadColocatedSkills = promptDir => {
   return loadPromptSkills( [ './skills/' ], promptDir );
 };
 
+/**
+ * Resolve all skills available to a prompt.
+ *
+ * @param {object} prompt - Loaded prompt object
+ * @param {{ name: string, description: string, instructions: string }[]} [callerSkills] - Inline caller-provided skills
+ * @returns {{ name: string, description: string, instructions: string }[]}
+ */
+export const resolvePromptSkills = ( prompt, callerSkills = [] ) => {
+  const hasExplicitSkills = prompt.config.skills && prompt.promptFileDir;
+  const frontmatterSkills = hasExplicitSkills ?
+    loadPromptSkills( prompt.config.skills, prompt.promptFileDir ) :
+    [];
+  const autoSkills = !hasExplicitSkills && prompt.promptFileDir ?
+    loadColocatedSkills( prompt.promptFileDir ) :
+    [];
+
+  return [ ...frontmatterSkills, ...autoSkills, ...callerSkills ];
+};
+
 /**
  * Build the skills system message content listing available skills.
  *

package/src/prompt/skill.spec.js

@@ -0,0 +1,172 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { FatalError, ValidationError } from '@outputai/core';
+
+const aiMocks = vi.hoisted( () => ( {
+  tool: vi.fn( def => ( { ...def, _tool: true } ) )
+} ) );
+
+vi.mock( 'ai', () => ( {
+  tool: ( ...args ) => aiMocks.tool( ...args )
+} ) );
+
+const importSut = async () => import( './skill.js' );
+
+const makeTempDir = () => mkdtempSync( join( tmpdir(), 'skill-test-' ) );
+
+describe( 'skill', () => {
+  it( 'creates an inline skill with a default description', async () => {
+    const { skill } = await importSut();
+
+    expect( skill( { name: 'writer', instructions: '# Writer' } ) ).toEqual( {
+      name: 'writer',
+      description: 'writer',
+      instructions: '# Writer'
+    } );
+  } );
+
+  it( 'throws when name or instructions are missing', async () => {
+    const { skill } = await importSut();
+
+    expect( () => skill( { instructions: '# Missing name' } ) ).toThrow( ValidationError );
+    expect( () => skill( { name: 'missing_instructions' } ) ).toThrow( ValidationError );
+  } );
+} );
+
+describe( 'skill file loading', () => {
+  it( 'loads a skill file using frontmatter metadata', async () => {
+    const dir = makeTempDir();
+    const filePath = join( dir, 'copy.md' );
+    writeFileSync( filePath, `---
+name: copywriter
+description: Writes concise copy
+---
+
+# Copy
+Write clearly.
+` );
+
+    const { loadSkillFile } = await importSut();
+
+    expect( loadSkillFile( filePath ) ).toEqual( {
+      name: 'copywriter',
+      description: 'Writes concise copy',
+      instructions: '# Copy\nWrite clearly.'
+    } );
+  } );
+
+  it( 'uses the markdown filename when frontmatter omits name and description', async () => {
+    const dir = makeTempDir();
+    const filePath = join( dir, 'research.md' );
+    writeFileSync( filePath, '# Research\nSearch carefully.\n' );
+
+    const { loadSkillFile } = await importSut();
+
+    expect( loadSkillFile( filePath ) ).toEqual( {
+      name: 'research',
+      description: 'research',
+      instructions: '# Research\nSearch carefully.'
+    } );
+  } );
+
+  it( 'loads skills from a file path and a directory path, sorting directory markdown files', async () => {
+    const promptDir = makeTempDir();
+    const skillsDir = join( promptDir, 'skills' );
+    mkdirSync( skillsDir );
+    writeFileSync( join( promptDir, 'single.md' ), '# Single' );
+    writeFileSync( join( skillsDir, 'b.md' ), '# B' );
+    writeFileSync( join( skillsDir, 'a.md' ), '# A' );
+    writeFileSync( join( skillsDir, 'ignore.txt' ), '# Ignored' );
+
+    const { loadPromptSkills } = await importSut();
+    const result = loadPromptSkills( [ './single.md', './skills' ], promptDir );
+
+    expect( result.map( s => s.name ) ).toEqual( [ 'single', 'a', 'b' ] );
+  } );
+
+  it( 'throws FatalError for a missing skill path', async () => {
+    const { loadPromptSkills } = await importSut();
+
+    expect( () => loadPromptSkills( './missing.md', makeTempDir() ) ).toThrow( FatalError );
+  } );
+
+  it( 'loads colocated skills and returns an empty array when no skills directory exists', async () => {
+    const promptDir = makeTempDir();
+    const skillsDir = join( promptDir, 'skills' );
+    mkdirSync( skillsDir );
+    writeFileSync( join( skillsDir, 'style.md' ), '# Style' );
+
+    const { loadColocatedSkills } = await importSut();
+
+    expect( loadColocatedSkills( promptDir ).map( s => s.name ) ).toEqual( [ 'style' ] );
+    expect( loadColocatedSkills( makeTempDir() ) ).toEqual( [] );
+  } );
+} );
+
+describe( 'resolvePromptSkills', () => {
+  it( 'uses explicit prompt skills and skips colocated auto-discovery', async () => {
+    const promptDir = makeTempDir();
+    const explicitDir = join( promptDir, 'explicit' );
+    const autoDir = join( promptDir, 'skills' );
+    mkdirSync( explicitDir );
+    mkdirSync( autoDir );
+    writeFileSync( join( explicitDir, 'explicit.md' ), '# Explicit' );
+    writeFileSync( join( autoDir, 'auto.md' ), '# Auto' );
+    const callerSkill = { name: 'caller', description: 'Caller', instructions: '# Caller' };
+
+    const { resolvePromptSkills } = await importSut();
+    const result = resolvePromptSkills( {
+      config: { skills: [ './explicit' ] },
+      promptFileDir: promptDir
+    }, [ callerSkill ] );
+
+    expect( result.map( s => s.name ) ).toEqual( [ 'explicit', 'caller' ] );
+  } );
+
+  it( 'auto-discovers colocated skills when prompt config has no explicit skills', async () => {
+    const promptDir = makeTempDir();
+    const skillsDir = join( promptDir, 'skills' );
+    mkdirSync( skillsDir );
+    writeFileSync( join( skillsDir, 'auto.md' ), '# Auto' );
+
+    const { resolvePromptSkills } = await importSut();
+    const result = resolvePromptSkills( { config: {}, promptFileDir: promptDir } );
+
+    expect( result.map( s => s.name ) ).toEqual( [ 'auto' ] );
+  } );
+} );
+
+describe( 'skill prompt helpers', () => {
+  it( 'builds the system skills message', async () => {
+    const { buildSystemSkillsVar } = await importSut();
+
+    expect( buildSystemSkillsVar( [
+      { name: 'copy', description: 'Copywriting' },
+      { name: 'research', description: 'Research' }
+    ] ) ).toBe(
+      'Available skills (use load_skill to get full instructions):\n' +
+      '- copy: Copywriting\n' +
+      '- research: Research'
+    );
+  } );
+
+  it( 'builds a load_skill tool that returns instructions or an available-skills message', async () => {
+    const skills = [
+      { name: 'copy', description: 'Copywriting', instructions: '# Copy' },
+      { name: 'research', description: 'Research', instructions: '# Research' }
+    ];
+
+    const { buildLoadSkillTool } = await importSut();
+    const result = buildLoadSkillTool( skills );
+
+    expect( aiMocks.tool ).toHaveBeenCalledWith( expect.objectContaining( {
+      description: 'Get detailed instructions for a named skill',
+      inputSchema: expect.any( Object ),
+      execute: expect.any( Function )
+    } ) );
+    expect( result.execute( { name: 'copy' } ) ).toBe( '# Copy' );
+    expect( result.execute( { name: 'missing' } ) ).toBe( 'Skill "missing" not found. Available: copy, research' );
+  } );
+} );

package/src/{prompt_validations.js → prompt/validations.js}

@@ -7,24 +7,50 @@ export const promptSchema = z.object( {
     model: z.string(),
     temperature: z.number().optional(),
     maxTokens: z.number().optional(),
-    tools: z.record( z.string(), z.object( {} ).passthrough() ).optional(),
+    n: z.number().int().positive().optional(),
+    maxImagesPerCall: z.number().int().positive().optional(),
+    size: z.string().regex( /^\d+x\d+$/ ).optional(),
+    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(),
     providerOptions: z.object( {
       thinking: z.object( {
         type: z.enum( [ 'enabled', 'disabled' ] ),
         budgetTokens: z.number().optional()
-      } ).passthrough().optional()
-    } ).passthrough().optional()
-  } ).passthrough(),
+      } ).loose().optional()
+    } ).loose().optional()
+  } ).loose(),
   messages: z.array(
     z.object( {
       role: z.string(),
       content: z.string()
     } ).strict()
-  )
-} ).strict();
+  ),
+  instructions: z.string().trim().min( 1 ).nullable().optional()
+} ).strict().superRefine( ( prompt, ctx ) => {
+  const hasMessages = prompt.messages.length > 0;
+  const hasInstructions = !!prompt.instructions;
+  if ( !hasMessages && !hasInstructions ) {
+    ctx.addIssue( {
+      code: 'custom',
+      path: [ 'messages', 'instructions' ],
+      message: 'Prompt must include either message blocks or plain instructions.'
+    } );
+  }
+  if ( hasMessages && hasInstructions ) {
+    ctx.addIssue( {
+      code: 'custom',
+      path: [ 'messages', 'instructions' ],
+      message: 'Prompt cannot include both message blocks and plain instructions.'
+    } );
+  }
+} );
 
 const SNAKE_CASE_WARNINGS = {
   max_tokens: 'maxTokens',
+  max_images_per_call: 'maxImagesPerCall',
+  aspect_ratio: 'aspectRatio',
   budget_tokens: 'budgetTokens',
   top_p: 'topP',
   top_k: 'topK',