@outputai/llm 0.11.0 → 0.11.1-next.2223fa5.0

package/src/prompt/prepare_text.js

@@ -1,27 +0,0 @@
-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

@@ -1,141 +0,0 @@
-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/prompt/skill.js

@@ -1,128 +0,0 @@
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
-import matter from 'gray-matter';
-import { tool } from 'ai';
-import { z, ValidationError, FatalError } from '@outputai/core';
-
-/**
- * Create an inline skill instruction package.
- *
- * @param {object} params
- * @param {string} params.name - Skill identifier
- * @param {string} [params.description] - When to use this skill (defaults to name)
- * @param {string} params.instructions - Full instructions returned when LLM calls load_skill
- * @returns {{ name: string, description: string, instructions: string }}
- */
-export function skill( { name, description, instructions } ) {
-  if ( !name ) {
-    throw new ValidationError( 'skill() requires a name' );
-  }
-  if ( !instructions ) {
-    throw new ValidationError( 'skill() requires instructions' );
-  }
-  return { name, description: description ?? name, instructions };
-}
-
-/**
- * Load a single skill from a markdown file.
- * Frontmatter may provide `name` and `description`; body becomes the instructions.
- *
- * @param {string} filePath - Absolute path to the .md skill file
- * @returns {{ name: string, description: string, instructions: string }}
- */
-export const loadSkillFile = filePath => {
-  const raw = readFileSync( filePath, 'utf-8' );
-  const { data, content } = matter( raw );
-  return {
-    name: data.name ?? basename( filePath, '.md' ),
-    description: data.description ?? basename( filePath, '.md' ),
-    instructions: content.trim()
-  };
-};
-
-/**
- * Load skills from an array of paths (files or directories of .md files).
- * Paths are resolved relative to `promptDir`.
- *
- * @param {string[]} skillPaths - Paths from prompt frontmatter (may be files or directories)
- * @param {string} promptDir - Base directory for resolving relative paths
- * @returns {{ name: string, description: string, instructions: string }[]}
- */
-export const loadPromptSkills = ( skillPaths, promptDir ) => {
-  const paths = Array.isArray( skillPaths ) ? skillPaths : [ skillPaths ];
-  return paths.flatMap( skillPath => {
-    const resolved = resolve( promptDir, skillPath );
-    if ( !existsSync( resolved ) ) {
-      throw new FatalError( `Skill path not found: "${skillPath}" (resolved to "${resolved}")` );
-    }
-    if ( statSync( resolved ).isDirectory() ) {
-      return readdirSync( resolved )
-        .filter( f => f.endsWith( '.md' ) )
-        .sort()
-        .map( f => loadSkillFile( join( resolved, f ) ) );
-    }
-    return [ loadSkillFile( resolved ) ];
-  } );
-};
-
-/**
- * Load skills from a colocated `skills/` directory next to the prompt file.
- * Returns empty array if the directory doesn't exist or has no .md files.
- *
- * @param {string} promptDir - Directory containing the prompt file
- * @returns {{ name: string, description: string, instructions: string }[]}
- */
-export const loadColocatedSkills = promptDir => {
-  const skillsDir = resolve( promptDir, 'skills' );
-  if ( !existsSync( skillsDir ) || !statSync( skillsDir ).isDirectory() ) {
-    return [];
-  }
-  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.
- *
- * @param {{ name: string, description: string }[]} skills
- * @returns {string}
- */
-export const buildSystemSkillsVar = skills =>
-  'Available skills (use load_skill to get full instructions):\n' +
-  skills.map( s => `- ${s.name}: ${s.description}` ).join( '\n' );
-
-/**
- * Build the `load_skill` AI SDK tool that the LLM calls to retrieve full skill instructions.
- *
- * @param {{ name: string, instructions: string }[]} skills
- * @returns {import('ai').Tool}
- */
-export const buildLoadSkillTool = skills => tool( {
-  description: 'Get detailed instructions for a named skill',
-  inputSchema: z.object( { name: z.string().describe( 'Name of the skill to load' ) } ),
-  execute: ( { name } ) => {
-    const sk = skills.find( s => s.name === name );
-    if ( !sk ) {
-      return `Skill "${name}" not found. Available: ${skills.map( s => s.name ).join( ', ' )}`;
-    }
-    return sk.instructions;
-  }
-} );

package/src/prompt/skill.spec.js

@@ -1,172 +0,0 @@
-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/utils/message.js

@@ -1,3 +0,0 @@
-export const ROLE = { SYSTEM: 'system', USER: 'user', ASSISTANT: 'assistant', TOOL: 'tool' };
-export const isRole = role => msg => msg.role === role;
-export const getContent = msg => msg.content;

package/src/utils/message.spec.js

@@ -1,29 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { ROLE, getContent, isRole } from './message.js';
-
-describe( 'message utils', () => {
-  describe( 'ROLE', () => {
-    it( 'exposes expected role string constants', () => {
-      expect( ROLE ).toEqual( {
-        SYSTEM: 'system',
-        USER: 'user',
-        ASSISTANT: 'assistant',
-        TOOL: 'tool'
-      } );
-    } );
-  } );
-
-  describe( 'isRole', () => {
-    it( 'returns a predicate that matches messages by role', () => {
-      const isUser = isRole( ROLE.USER );
-      expect( isUser( { role: 'user', content: 'hi' } ) ).toBe( true );
-      expect( isUser( { role: 'assistant', content: 'bye' } ) ).toBe( false );
-    } );
-  } );
-
-  describe( 'getContent', () => {
-    it( 'returns message content', () => {
-      expect( getContent( { role: 'user', content: 'hello' } ) ).toBe( 'hello' );
-    } );
-  } );
-} );

package/src/utils/response_wrappers.js

@@ -1,100 +0,0 @@
-import { combineSources, extractSourcesFromSteps } from './source_extraction.js';
-import { calculateLLMCallCost } from '../cost/index.js';
-import { endTraceWithSuccess } from './trace.js';
-import { calculateBase64FileSize } from './image.js';
-
-/**
- * Calculates the cost and wraps an AI SDK text response in a Proxy with shortcut for 'result' and 'cost'
- *
- * Emits the `cost:llm:request` event.
- *
- * Also finishes the trace events.
- *
- * @param {object} args
- * @param {string} args.traceId - id created by the startTrace
- * @param {string} args.providerId - id of the provider used
- * @param {string} args.modelId - id of the model used
- * @param {object} args.response - AI SDK's text response
- * @returns {object} Proxied response
- */
-export const wrapTextResponse = async ( { traceId, providerId, modelId, response } ) => {
-  const { totalUsage: usage, providerMetadata, text: result, steps, sources } = response;
-
-  const cost = await calculateLLMCallCost( { usage, modelId, providerId } );
-  const sourcesFromTools = extractSourcesFromSteps( steps );
-
-  endTraceWithSuccess( { traceId, usage, cost, result, providerMetadata, sourcesFromTools } );
-
-  return new Proxy( response, {
-    get( target, prop, receiver ) {
-      if ( prop === 'result' ) {
-        return target.text;
-      }
-      if ( prop === 'cost' ) {
-        return cost;
-      }
-      if ( prop === 'sources' && sourcesFromTools.length > 0 ) {
-        return combineSources( { sourcesFromTools, sourcesFromResponse: sources } );
-      }
-      return Reflect.get( target, prop, receiver );
-    }
-  } );
-};
-
-/**
- * Wraps the response returned by the onFinish callback from the stream.
- *
- * When the onFinish is triggered, concludes the trace event, calculates cost and emits `cost:llm:request`.
- * Returns a proxy around the response with `cost` property.
- *
- * @param {object} args
- * @param {string} args.traceId - id created by the startTrace
- * @param {string} args.providerId - id of the provider used
- * @param {string} args.modelId - id of the model used
- * @param {Function} args.onFinish - Original callback to call with the proxied response
- * @returns {object} Proxied response
- */
-export const wrapStreamOnFinishResponse = ( { traceId, providerId, modelId, onFinish: _onFinish } ) => ( {
-  async onFinish( response ) {
-    const proxiedResponse = await wrapTextResponse( { traceId, providerId, modelId, response } );
-    _onFinish?.( proxiedResponse );
-  }
-} );
-
-/**
- * Calculates the cost and wraps an AI SDK image response in a Proxy with shortcut for 'result' and 'cost'
- *
- * Emits the `cost:llm:request` event.
- *
- * Also finishes the trace events.
- *
- * @param {object} args
- * @param {string} args.traceId - id created by the startTrace
- * @param {string} args.providerId - id of the provider used
- * @param {string} args.modelId - id of the model used
- * @param {object} args.response - AI SDK's image response
- * @returns {object} Proxied response
- */
-export const wrapImageResponse = async ( { traceId, providerId, modelId, response } ) => {
-  const { usage, providerMetadata } = response;
-  const cost = await calculateLLMCallCost( { usage, providerId, modelId } );
-
-  const result = response.images.map( ( { mediaType, base64 } ) => ( {
-    size: calculateBase64FileSize( base64 ),
-    mediaType
-  } ) );
-
-  endTraceWithSuccess( { traceId, usage, cost, result, providerMetadata } );
-
-  return new Proxy( response, {
-    get( target, prop, receiver ) {
-      if ( prop === 'result' ) {
-        return target.image;
-      }
-      if ( prop === 'cost' ) {
-        return cost;
-      }
-      return Reflect.get( target, prop, receiver );
-    }
-  } );
-};