@outputai/llm 0.1.0

package/src/cost/index.js

@@ -0,0 +1,73 @@
+import { fetchModelsPricing } from './fetch_models_pricing.js';
+import Decimal from 'decimal.js';
+
+const M = 1_000_000;
+const calcCost = ( tokens, ppm ) => Decimal( tokens ?? 0 ).div( M ).mul( ppm ).toNumber();
+
+/**
+ * Calculates the input cost based on the input value
+ */
+const calculateInput = ( { tokens, cost } ) =>
+  !Number.isFinite( cost.input ) ? { value: null, message: 'Missing input cost' } : { value: calcCost( tokens, cost.input ) };
+
+/**
+ * Calculates the input cost based on the cache_read
+ */
+const calculateCachedInput = ( { tokens, cost } ) =>
+  !Number.isFinite( cost.cache_read ) ? { value: null, message: 'Missing cache input cost' } : { value: calcCost( tokens, cost.cache_read ) };
+
+/**
+ * Calculates the output cost based on the output value
+ */
+const calculateOutput = ( { tokens, cost } ) =>
+  !Number.isFinite( cost.output ) ? { value: null, message: 'Missing output' } : { value: calcCost( tokens, cost.output ) };
+
+/**
+ * Calculates the reasoning cost based on the reasoning token's
+ * If there isn't reasoning costs, this means this providers doesn't differentiate reasoning vs output,
+ * so don't calculate it as the price is included in output
+ */
+const calculateReasoning = ( { tokens, cost } ) =>
+  Number.isFinite( cost.reasoning ) ? { value: calcCost( tokens, cost.reasoning ) } : undefined;
+
+/**
+ * Calculates the total cost based on the components
+ */
+const calculateTotal = components => Object.values( components ).reduce( ( v, e ) => v.plus( e?.value ? e.value : 0 ), Decimal( 0 ) ).toNumber();
+
+/**
+ * Calculates the cost of an llm call based on the model and usage.
+ * @param {object} args
+ * @param {string} args.modelId - Name of the mode, provider prefix is optional
+ * @param {object} args.usage - Usage, as returned from AI SDK
+ * @returns {object} The cost with total value and components
+ */
+export const calculateLLMCallCost = async ( { modelId, usage } ) => {
+  try {
+    const models = await fetchModelsPricing();
+    if ( !models ) {
+      return { total: null, message: 'Failed to fetch models pricing' };
+    }
+
+    const cost = models.get( modelId );
+    if ( !cost ) {
+      return { total: null, message: 'Missing cost reference for model' };
+    }
+
+    const { inputTokens, cachedInputTokens, outputTokens, reasoningTokens } = usage;
+
+    const nonCachedTokens = inputTokens - ( cachedInputTokens ?? 0 );
+
+    const components = {
+      input: calculateInput( { tokens: nonCachedTokens, cost } ),
+      cachedInput: calculateCachedInput( { tokens: cachedInputTokens, cost } ),
+      output: calculateOutput( { tokens: outputTokens, cost } ),
+      reasoning: calculateReasoning( { tokens: reasoningTokens ?? 0, cost } )
+    };
+
+    return { total: calculateTotal( components ), components };
+  } catch ( error ) {
+    console.error( 'Error calculating LLM call costs', error );
+    return { total: null, message: `Error calculating LLM call costs: ${error.constructor.name} - ${error.message}` };
+  }
+};

package/src/cost/index.spec.js

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockFetchModelsPricing = vi.fn();
+vi.mock( './fetch_models_pricing.js', () => ( {
+  fetchModelsPricing: ( ...args ) => mockFetchModelsPricing( ...args )
+} ) );
+
+import { calculateLLMCallCost } from './index.js';
+
+describe( 'calculateLLMCallCost', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+  } );
+
+  it( 'returns total null and message when fetchModelsPricing returns null', async () => {
+    mockFetchModelsPricing.mockResolvedValue( null );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'gpt-4o',
+      usage: { inputTokens: 100, outputTokens: 50 }
+    } );
+
+    expect( result ).toEqual( { total: null, message: 'Failed to fetch models pricing' } );
+  } );
+
+  it( 'returns total null and message when model is missing from cost table', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map() );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'unknown-model',
+      usage: { inputTokens: 100, outputTokens: 50 }
+    } );
+
+    expect( result ).toEqual( {
+      total: null,
+      message: 'Missing cost reference for model'
+    } );
+  } );
+
+  it( 'calculates input and output cost from mock model', async () => {
+    const cost = { input: 2, output: 10, cache_read: 1 };
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'gpt-4o', cost ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'gpt-4o',
+      usage: { inputTokens: 1_000_000, outputTokens: 500_000 }
+    } );
+
+    expect( result.total ).toBe( 7 );
+    expect( result.components.input ).toEqual( { value: 2 } );
+    expect( result.components.cachedInput ).toEqual( { value: 0 } );
+    expect( result.components.output ).toEqual( { value: 5 } );
+    expect( result.components.reasoning ).toBeUndefined();
+  } );
+
+  it( 'splits input into non-cached and cached at respective rates', async () => {
+    const cost = { input: 4, cache_read: 1, output: 10 };
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'cached-model', cost ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'cached-model',
+      usage: { inputTokens: 1_000_000, cachedInputTokens: 500_000, outputTokens: 100_000 }
+    } );
+
+    expect( result.components.input ).toEqual( { value: 2 } );
+    expect( result.components.cachedInput ).toEqual( { value: 0.5 } );
+    expect( result.components.output ).toEqual( { value: 1 } );
+    expect( result.total ).toBeCloseTo( 3.5 );
+  } );
+
+  it( 'sets cachedInput to null when model has no cache_read', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'no-cache', { input: 2, output: 10 } ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'no-cache',
+      usage: { inputTokens: 1_000_000, cachedInputTokens: 200_000, outputTokens: 0 }
+    } );
+
+    expect( result.components.input ).toEqual( { value: 1.6 } );
+    expect( result.components.cachedInput ).toEqual( { value: null, message: 'Missing cache input cost' } );
+    expect( result.total ).toBe( 1.6 );
+  } );
+
+  it( 'sets input to null and message when pricing has no input', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'out-only', { output: 10 } ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'out-only',
+      usage: { inputTokens: 100, outputTokens: 50 }
+    } );
+
+    expect( result.total ).toBe( 0.0005 );
+    expect( result.components.input ).toEqual( { value: null, message: 'Missing input cost' } );
+    expect( result.components.output ).toEqual( { value: 0.0005 } );
+  } );
+
+  it( 'sets output to null and message when pricing has no output', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'in-only', { input: 1 } ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'in-only',
+      usage: { inputTokens: 100, outputTokens: 50 }
+    } );
+
+    expect( result.total ).toBe( 0.0001 );
+    expect( result.components.input ).toEqual( { value: 0.0001 } );
+    expect( result.components.output ).toEqual( { value: null, message: 'Missing output' } );
+  } );
+
+  it( 'uses reasoning cost when present', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [
+      'with-reasoning',
+      { input: 1, output: 10, reasoning: 60 }
+    ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'with-reasoning',
+      usage: { inputTokens: 100, outputTokens: 20, reasoningTokens: 50 }
+    } );
+
+    expect( result.total ).toBeCloseTo( 0.0033 );
+    expect( result.components.reasoning ).toEqual( { value: 0.003 } );
+  } );
+
+  it( 'omits reasoning component when reasoning cost missing (included in output)', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'no-reasoning', { input: 1, output: 10 } ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'no-reasoning',
+      usage: { inputTokens: 100, outputTokens: 20, reasoningTokens: 50 }
+    } );
+
+    expect( result.total ).toBeCloseTo( 0.0003 );
+    expect( result.components.reasoning ).toBeUndefined();
+  } );
+
+  it( 'Calculate reasoning component when reasoningTokens is zero', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [
+      'full',
+      { input: 2, output: 8, reasoning: 60 }
+    ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'full',
+      usage: { inputTokens: 100, outputTokens: 50, reasoningTokens: 0 }
+    } );
+
+    expect( result.components.reasoning ).toEqual( { value: 0 } );
+    expect( result.total ).toBeCloseTo( 0.0006 );
+  } );
+
+  it( 'treats null/undefined token counts as 0', async () => {
+    mockFetchModelsPricing.mockResolvedValue( new Map( [ [ 'm', { input: 1, output: 2 } ] ] ) );
+
+    const result = await calculateLLMCallCost( {
+      modelId: 'm',
+      usage: { inputTokens: null, outputTokens: undefined }
+    } );
+
+    expect( result.total ).toBe( 0 );
+  } );
+} );

package/src/index.d.ts

@@ -0,0 +1,309 @@
+import type {
+  GenerateTextResult as AIGenerateTextResult,
+  StreamTextResult as AIStreamTextResult,
+  CallSettings,
+  ToolSet,
+  ToolChoice,
+  StopCondition,
+  GenerateTextOnStepFinishCallback,
+  StreamTextOnStepFinishCallback,
+  StreamTextTransform,
+  PrepareStepFunction,
+  StreamTextOnChunkCallback,
+  StreamTextOnFinishCallback,
+  StreamTextOnErrorCallback
+} from 'ai';
+import type { Output as AIOutput } from 'ai';
+
+/**
+ * Represents a single message in a prompt conversation.
+ *
+ * @example
+ * ```ts
+ * const msg: PromptMessage = {
+ *   role: 'user',
+ *   content: 'Hello, Claude!'
+ * };
+ * ```
+ */
+export type PromptMessage = {
+  /** The role of the message. Examples include 'system', 'user', and 'assistant'. */
+  role: string;
+  /** The content of the message */
+  content: string;
+};
+
+/**
+ * Configuration for LLM prompt generation.
+ *
+ * @example
+ * ```ts
+ * const prompt: Prompt = {
+ *   name: 'summarizePrompt',
+ *   config: {
+ *     provider: 'anthropic',
+ *     model: 'claude-opus-4-1',
+ *     temperature: 0.7,
+ *     maxTokens: 2048
+ *   },
+ *   messages: [...]
+ * };
+ * ```
+ */
+export type Prompt = {
+  /** Name of the prompt file */
+  name: string;
+
+  /** General configuration for the LLM */
+  config: {
+    /** LLM provider (built-in: 'anthropic', 'openai', 'azure', 'vertex', 'bedrock', 'perplexity'; or any registered custom provider) */
+    provider: string;
+
+    /** Model name/identifier */
+    model: string;
+
+    /** Generation temperature (0-2). Lower = more deterministic */
+    temperature?: number;
+
+    /** Maximum number of tokens in the response */
+    maxTokens?: number;
+
+    /**
+     * Provider-specific tools with configuration.
+     *
+     * @example Vertex googleSearch with config
+     * ```yaml
+     * tools:
+     *   googleSearch:
+     *     mode: MODE_DYNAMIC
+     *     dynamicThreshold: 0.8
+     * ```
+     *
+     * @example OpenAI webSearch with filters
+     * ```yaml
+     * tools:
+     *   webSearch:
+     *     searchContextSize: high
+     *     filters:
+     *       allowedDomains: [wikipedia.org]
+     * ```
+     */
+    tools?: Record<string, Record<string, unknown>>;
+
+    /** Provider-specific options */
+    providerOptions?: Record<string, unknown>;
+  };
+
+  /** Array of messages in the conversation */
+  messages: PromptMessage[];
+};
+
+// Re-export AI SDK types directly (auto-synced with AI SDK updates)
+export type {
+  LanguageModelUsage,
+  FinishReason,
+  LanguageModelResponseMetadata,
+  ProviderMetadata,
+  CallWarning,
+  Warning,
+  CallSettings,
+  ToolSet,
+  ToolChoice,
+  Tool,
+  StopCondition,
+  StepResult,
+  GenerateTextOnStepFinishCallback,
+  PrepareStepFunction,
+  PrepareStepResult,
+  StreamTextOnChunkCallback,
+  StreamTextOnFinishCallback,
+  StreamTextOnErrorCallback,
+  StreamTextTransform,
+  TextStreamPart
+} from 'ai';
+
+// Re-export the tool helper function, Output, smoothStream, and stop condition helpers
+export { tool, Output, smoothStream, stepCountIs, hasToolCall } 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';
+
+/**
+ * Common AI SDK options that can be passed through to all generate functions.
+ * These options are passed directly to the underlying AI SDK call.
+ */
+type AiSdkOptions = Partial<Omit<CallSettings, 'maxOutputTokens'>>;
+
+/**
+ * AI SDK options specific to generateText, including tool calling and multi-step support.
+ * @typeParam Tools - The tools available for the model to call
+ */
+type GenerateTextAiSdkOptions<
+  Tools extends ToolSet = ToolSet,
+  Output extends AIOutput<unknown, unknown> = AIOutput<unknown, unknown>
+> = AiSdkOptions & {
+  /** Tools the model can call */
+  tools?: Tools;
+  /** Tool choice strategy: 'auto', 'none', 'required', or specific tool */
+  toolChoice?: ToolChoice<Tools>;
+  /** Limit which tools are active without changing types */
+  activeTools?: Array<keyof Tools>;
+  /** Maximum number of automatic tool execution rounds (multi-step) */
+  maxSteps?: number;
+  /** Custom stop conditions for multi-step execution */
+  stopWhen?: StopCondition<Tools> | StopCondition<Tools>[];
+  /** Callback after each step completes */
+  onStepFinish?: GenerateTextOnStepFinishCallback<Tools>;
+  /** Customize each step before execution */
+  prepareStep?: PrepareStepFunction<Tools>;
+  /** Structured output specification (e.g., Output.object({ schema })) */
+  output?: Output;
+};
+
+/**
+ * AI SDK options specific to streamText, including tool calling, multi-step, and streaming callbacks.
+ * @typeParam Tools - The tools available for the model to call
+ */
+type StreamTextAiSdkOptions<
+  Tools extends ToolSet = ToolSet,
+  Output extends AIOutput<unknown, unknown> = AIOutput<unknown, unknown>
+> = AiSdkOptions & {
+  /** Tools the model can call */
+  tools?: Tools;
+  /** Tool choice strategy: 'auto', 'none', 'required', or specific tool */
+  toolChoice?: ToolChoice<Tools>;
+  /** Limit which tools are active without changing types */
+  activeTools?: Array<keyof Tools>;
+  /** Maximum number of automatic tool execution rounds (multi-step) */
+  maxSteps?: number;
+  /** Custom stop conditions for multi-step execution */
+  stopWhen?: StopCondition<Tools> | StopCondition<Tools>[];
+  /** Callback after each step completes */
+  onStepFinish?: StreamTextOnStepFinishCallback<Tools>;
+  /** Customize each step before execution */
+  prepareStep?: PrepareStepFunction<Tools>;
+  /** Structured output specification (e.g., Output.object({ schema })) */
+  output?: Output;
+  /** Callback for each stream chunk */
+  onChunk?: StreamTextOnChunkCallback<Tools>;
+  /** Callback when stream finishes. Called after internal tracing records the result. */
+  onFinish?: StreamTextOnFinishCallback<Tools>;
+  /** Callback when stream errors. Called after internal tracing records the error. */
+  onError?: StreamTextOnErrorCallback;
+  /** Stream transformation (e.g., smoothStream()) */
+  experimental_transform?: StreamTextTransform<Tools> | Array<StreamTextTransform<Tools>>;
+};
+
+/** A source extracted from search tool results during multi-step LLM execution. */
+export type ExtractedSource = {
+  type: 'source';
+  sourceType: 'url';
+  id: string;
+  url: string;
+  title: string;
+};
+
+/**
+ * Result from generateText including full AI SDK response metadata.
+ * Extends AI SDK's GenerateTextResult with a unified `result` field.
+ * @typeParam Tools - The tools available for the model to call (preserves typing on steps)
+ */
+export type GenerateTextResult<
+  Tools extends ToolSet = ToolSet,
+  Output extends AIOutput<unknown, unknown> = AIOutput<unknown, unknown>
+> = AIGenerateTextResult<Tools, Output> & {
+  /** Unified field name alias for 'text' - provides consistency across all generate* functions */
+  result: string;
+  /** Sources extracted from search tool results, merged with any native provider sources */
+  sources: ExtractedSource[];
+};
+
+/**
+ * Loads a prompt file and interpolates variables into its content.
+ *
+ * @param name - Name of the prompt file (without `.prompt` extension).
+ * @param variables - Variables to interpolate.
+ * @returns The loaded prompt object.
+ */
+export function loadPrompt(
+  name: string,
+  variables?: Record<string, string | number | boolean>
+): Prompt;
+
+/**
+ * Register a custom LLM provider for use in prompt files.
+ *
+ * @param name - Provider name (used in prompt config `provider` field)
+ * @param providerFn - Factory function that creates a model from a model name string
+ *
+ * @example
+ * ```ts
+ * import { createDeepSeek } from '@ai-sdk/deepseek';
+ * import { registerProvider } from '@outputai/llm';
+ *
+ * registerProvider('deepseek', createDeepSeek({ apiKey: '...' }));
+ * ```
+ */
+export function registerProvider(
+  name: string,
+  providerFn: ( modelName: string ) => unknown
+): void;
+
+/**
+ * Get the list of all registered provider names (built-in and custom).
+ *
+ * @returns Array of provider name strings
+ */
+export function getRegisteredProviders(): 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`.
+ * Additional AI SDK options (tools, maxRetries, etc.) can be passed through.
+ *
+ * @param args - Generation arguments.
+ * @param args.prompt - Prompt file name.
+ * @param args.variables - Variables to interpolate.
+ * @param args.tools - Tools the model can call (optional).
+ * @param args.toolChoice - Tool selection strategy (optional).
+ * @returns AI SDK response with text and metadata.
+ */
+export function generateText<
+  Tools extends ToolSet = ToolSet,
+  Output extends AIOutput<unknown, unknown> = AIOutput<unknown, unknown>
+>(
+  args: {
+    prompt: string,
+    variables?: Record<string, string | number | boolean>,
+    promptDir?: string
+  } & GenerateTextAiSdkOptions<Tools, Output>
+): Promise<GenerateTextResult<Tools, Output>>;
+
+/**
+ * Use an LLM model to stream text generation.
+ *
+ * This function is a wrapper over the AI SDK's `streamText`.
+ * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
+ * Additional AI SDK options (tools, onChunk, onFinish, onError, etc.) can be passed through.
+ *
+ * @param args - Generation arguments.
+ * @param args.prompt - Prompt file name.
+ * @param args.variables - Variables to interpolate.
+ * @param args.onChunk - Callback for each stream chunk (optional).
+ * @param args.onFinish - Callback when stream finishes (optional).
+ * @param args.onError - Callback when stream errors (optional).
+ * @returns AI SDK stream result with textStream, fullStream, and metadata promises.
+ */
+export function streamText<
+  Tools extends ToolSet = ToolSet,
+  Output extends AIOutput<unknown, unknown> = AIOutput<unknown, unknown>
+>(
+  args: {
+    prompt: string,
+    variables?: Record<string, string | number | boolean>
+  } & StreamTextAiSdkOptions<Tools, Output>
+): AIStreamTextResult<Tools, Output>;

package/src/index.js

@@ -0,0 +1,8 @@
+export { generateText, streamText } from './ai_sdk.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 { tool, Output, smoothStream, stepCountIs, hasToolCall } from 'ai';
+export * as ai from 'ai';

package/src/load_content.js

@@ -0,0 +1,43 @@
+import { join } from 'path';
+import { readdirSync, readFileSync } from 'node:fs';
+import { resolveInvocationDir } from '@outputai/core/sdk_utils';
+import { FatalError } from '@outputai/core';
+
+const scanDir = dir => {
+  try {
+    return readdirSync( dir, { withFileTypes: true } );
+  } catch ( error ) {
+    throw new FatalError( `Error scanning directory "${dir}"`, { cause: error } );
+  }
+};
+
+const loadFile = path => {
+  try {
+    return readFileSync( path, 'utf-8' );
+  } catch ( error ) {
+    throw new FatalError( `Error reading file "${path}"`, { cause: error } );
+  }
+};
+
+/**
+ * Recursively search for a file by its name and load its content.
+ *
+ * @param {string} name - Name of the file load its content
+ * @param {string} [dir] - The directory to search for the file, defaults to invocation directory
+ * @returns {string | null} - File content or null if not found
+ */
+export const loadContent = ( name, dir = resolveInvocationDir() ) => {
+  for ( const entry of scanDir( dir ) ) {
+    if ( entry.name === name ) {
+      return loadFile( join( dir, entry.name ) );
+    }
+
+    if ( entry.isDirectory() && !entry.isSymbolicLink() ) {
+      const content = loadContent( name, join( dir, entry.name ) );
+      if ( content ) {
+        return content;
+      }
+    }
+  }
+  return null;
+};

package/src/load_content.spec.js

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { join } from 'path';
+import { mkdtempSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+// Hoisted state so mocks can read dynamic values set in tests
+const state = vi.hoisted( () => ( { dir: '', entries: {} } ) );
+
+// Mock core utils to control resolveInvocationDir
+vi.mock( '@outputai/core/sdk_utils', () => ( {
+  resolveInvocationDir: () => state.dir
+} ) );
+
+// Mock node:fs.readFileSync for directory scans while delegating file reads
+vi.mock( 'node:fs', async importOriginal => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    readFileSync: vi.fn( ( path, options ) => {
+      if ( options && typeof options === 'object' && options.withFileTypes ) {
+        return state.entries[path] || [];
+      }
+      return actual.readFileSync( path, options );
+    } )
+  };
+} );
+
+const dirEntry = ( name, { isDir = false, isLink = false } = {} ) => ( {
+  name,
+  isDirectory: () => isDir,
+  isSymbolicLink: () => isLink
+} );
+
+beforeEach( () => {
+  state.dir = '';
+  state.entries = {};
+} );
+
+describe( 'loadContent', () => {
+  it( 'loads file from root directory using mocked resolveInvocationDir', async () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+    state.dir = tempDir;
+    const testContent = 'test file content';
+    writeFileSync( join( tempDir, 'test.txt' ), testContent );
+    state.entries[tempDir] = [ dirEntry( 'test.txt' ) ];
+
+    const { loadContent } = await import( './load_content.js' );
+    const content = loadContent( 'test.txt' );
+
+    expect( content ).toBe( testContent );
+  } );
+
+  it( 'loads file from nested subdirectory via recursion', async () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+    const subDir = join( tempDir, 'subdir' );
+    mkdirSync( subDir );
+    state.dir = tempDir;
+
+    const testContent = 'nested file content';
+    writeFileSync( join( subDir, 'nested.txt' ), testContent );
+
+    state.entries[tempDir] = [ dirEntry( 'subdir', { isDir: true } ) ];
+    state.entries[subDir] = [ dirEntry( 'nested.txt' ) ];
+
+    const { loadContent } = await import( './load_content.js' );
+    const content = loadContent( 'nested.txt' );
+
+    expect( content ).toBe( testContent );
+  } );
+
+  it( 'returns null when file does not exist', async () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+    state.dir = tempDir;
+    state.entries[tempDir] = [ dirEntry( 'other.txt' ) ];
+
+    const { loadContent } = await import( './load_content.js' );
+    const content = loadContent( 'nonexistent.txt' );
+
+    expect( content ).toBeNull();
+  } );
+} );