@outputai/llm 0.1.11 → 0.1.12-dev.d521efb.0

package/src/skill.d.ts

@@ -0,0 +1,49 @@
+/**
+ * An instruction package that an agent can load on demand via the load_skill tool.
+ *
+ * Skills are declared in prompt frontmatter (as file paths) or passed inline
+ * to agent(). The LLM sees skill names and descriptions in `{{ _system_skills }}`
+ * and calls `load_skill` to retrieve full instructions when needed.
+ */
+export type Skill = {
+  name: string;
+  description: string;
+  instructions: string;
+};
+
+/**
+ * The skills argument for agent(). Either a static list or a function
+ * that receives the agent's input and returns skills dynamically.
+ */
+export type SkillsArg<Input = unknown> = Skill[] |
+  ( ( input: Input ) => Skill[] | Promise<Skill[]> );
+
+/**
+ * Create an inline skill instruction package.
+ *
+ * @example
+ * ```ts
+ * const researchSkill = skill( {
+ *   name: 'web_research',
+ *   description: 'Search and synthesize web information',
+ *   instructions: '# Web Research\n1. Break into queries\n2. Search\n3. Cite sources'
+ * } );
+ * ```
+ */
+export declare function skill( params: {
+  name: string;
+  description?: string;
+  instructions: string;
+} ): Skill;
+
+/** Load a single skill from a markdown file. */
+export declare function loadSkillFile( filePath: string ): Skill;
+
+/** Load skills from an array of file/directory paths, resolved relative to promptDir. */
+export declare function loadPromptSkills( skillPaths: string | string[], promptDir: string ): Skill[];
+
+/** Build the `{{ _system_skills }}` template variable listing available skills. */
+export declare function buildSystemSkillsVar( skills: Skill[] ): string;
+
+/** Build the `load_skill` AI SDK tool that returns full instructions for a named skill. */
+export declare function buildLoadSkillTool( skills: Skill[] ): import( 'ai' ).Tool;

package/src/skill.js

@@ -0,0 +1,109 @@
+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 );
+};
+
+/**
+ * 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/trace_utils.js

@@ -0,0 +1,30 @@
+import { Tracing, emitEvent } from '@outputai/core/sdk_activity_integration';
+import { calculateLLMCallCost } from './cost/index.js';
+
+export const startTrace = ( name, details ) => {
+  const traceId = `${name}-${Date.now()}`;
+  Tracing.addEventStart( { kind: 'llm', name, id: traceId, details } );
+  return traceId;
+};
+
+export const endTraceWithError = ( traceId, error ) => {
+  Tracing.addEventError( { id: traceId, details: error } );
+};
+
+export const endTraceWithSuccess = async ( traceId, modelId, response, extraDetails = {} ) => {
+  const { text: result, totalUsage: usage, providerMetadata } = response;
+  const cost = await calculateLLMCallCost( { usage, modelId } );
+  emitEvent( 'llm:call_cost', { modelId, cost, usage } );
+  Tracing.addEventEnd( { id: traceId, details: { result, usage, cost, providerMetadata, ...extraDetails } } );
+};
+
+export const traceStreamCallbacks = ( traceId, modelId, { onFinish: userOnFinish, onError: userOnError } = {} ) => ( {
+  async onFinish( response ) {
+    await endTraceWithSuccess( traceId, modelId, response );
+    userOnFinish?.( response );
+  },
+  onError( event ) {
+    Tracing.addEventError( { id: traceId, details: event.error } );
+    userOnError?.( event );
+  }
+} );