@studio-foundation/runner 0.3.0-beta.1 → 0.3.0-beta.6

package/src/tools/plugin-loader.ts

@@ -1,203 +0,0 @@
-// runner/src/tools/plugin-loader.ts
-import { readdir, readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import yaml from 'js-yaml';
-import type { ToolPluginDef, ToolCommandDef } from '@studio-foundation/contracts';
-import type { Tool } from './tool-registry.js';
-import { renderTemplate, executeShellCommand } from './yaml-executor.js';
-import { createRepoManagerTools } from './builtin/repo-manager.js';
-import { createShellTools } from './builtin/shell.js';
-import { createSearchTools } from './builtin/search.js';
-import { createPatchTools } from './builtin/patch.js';
-import { createGitTools } from './builtin/git.js';
-import { createWebSearchTools } from './builtin/web-search.js';
-import { ToolYamlError } from './errors.js';
-
-export interface LoadedPlugin {
-  name: string;
-  tools: Tool[];
-  promptSnippet?: string;
-}
-
-/** Build a map of tool name → Tool from all builtin factories. */
-function buildBuiltinMap(repoPath: string): Map<string, Tool> {
-  const map = new Map<string, Tool>();
-  const add = (tools: Tool[]) => tools.forEach(t => map.set(t.name, t));
-  add(createRepoManagerTools(repoPath));
-  add(createShellTools(repoPath));
-  add(createSearchTools(repoPath));
-  add(createPatchTools(repoPath));
-  add(createGitTools(repoPath));
-  add(createWebSearchTools());
-  return map;
-}
-
-/** Convert a ParameterDef map to a JSON Schema object for the LLM. */
-function buildJsonSchema(
-  parameters: ToolCommandDef['parameters']
-): Record<string, unknown> {
-  const properties: Record<string, unknown> = {};
-  const required: string[] = [];
-
-  for (const [key, def] of Object.entries(parameters ?? {})) {
-    properties[key] = {
-      type: def.type,
-      ...(def.description ? { description: def.description } : {}),
-      ...(def.type === 'array' && def.items ? { items: def.items } : {}),
-    };
-    if (def.required) required.push(key);
-  }
-
-  return {
-    type: 'object',
-    properties,
-    ...(required.length > 0 ? { required } : {}),
-  };
-}
-
-/** Template keywords that appear as {{word}} but are not parameter names.
- *  Note: block tags like {{#if}} and {{/if}} are already excluded because
- *  '#' and '/' are not matched by [\w-]+. */
-const TEMPLATE_KEYWORDS = new Set(['else']);
-
-/**
- * Validate that every {{placeholder}} in a shell command template
- * is declared in the command's parameters.
- * Throws ToolYamlError if any undeclared placeholder is found.
- */
-function validateShellTemplate(fileName: string, cmd: ToolCommandDef): void {
-  const exec = cmd.execute as { type: string; command?: string };
-  if (exec.type !== 'shell' || !exec.command) return;
-
-  const declared = new Set(Object.keys(cmd.parameters ?? {}));
-  const used = new Set<string>();
-
-  for (const match of exec.command.matchAll(/\{\{([\w-]+)\}\}/g)) {
-    const name = match[1];
-    if (!TEMPLATE_KEYWORDS.has(name)) used.add(name);
-  }
-
-  const unknown = [...used].filter(p => !declared.has(p));
-  if (unknown.length > 0) {
-    throw new ToolYamlError(
-      `${fileName} › command '${cmd.name}':\n` +
-      `  template uses ${unknown.map(p => `{{${p}}}`).join(', ')} but no such parameter is declared.\n` +
-      `  Declared parameters: ${[...declared].join(', ') || '(none)'}`
-    );
-  }
-}
-
-/** Create a Tool that renders the command template and runs it in a shell. */
-function createShellTool(cmd: ToolCommandDef, repoPath: string, configsDir: string): Tool {
-  const exec = cmd.execute as { type: 'shell'; command: string; parse_output?: 'text' | 'json'; timeout_ms?: number };
-  return {
-    name: cmd.name,
-    description: cmd.description,
-    parameters: buildJsonSchema(cmd.parameters),
-    async execute(args) {
-      const rendered = renderTemplate(exec.command, args);
-      return executeShellCommand(rendered, exec.parse_output ?? 'text', repoPath, exec.timeout_ms, { STUDIO_CONFIG_DIR: configsDir });
-    },
-  };
-}
-
-/**
- * Load all `.tool.yaml` files from a project's tools directory.
- * Returns an empty array if the directory does not exist.
- */
-export async function loadProjectTools(
-  toolsDir: string,
-  repoPath: string
-): Promise<LoadedPlugin[]> {
-  if (!existsSync(toolsDir)) return [];
-
-  let files: string[];
-  try {
-    files = (await readdir(toolsDir)).filter(f => f.endsWith('.tool.yaml'));
-  } catch {
-    return [];
-  }
-
-  if (files.length === 0) return [];
-
-  const configsDir = resolve(dirname(toolsDir));
-  const builtinMap = buildBuiltinMap(repoPath);
-  const plugins: LoadedPlugin[] = [];
-
-  for (const file of files.sort()) {
-    const content = await readFile(resolve(toolsDir, file), 'utf-8');
-    const def = yaml.load(content) as ToolPluginDef;
-
-    const tools: Tool[] = [];
-    for (const cmd of def.commands ?? []) {
-      if (cmd.execute.type === 'builtin') {
-        const tool = builtinMap.get(cmd.name);
-        if (tool) tools.push(tool);
-        // If unknown builtin name, skip silently (no crash)
-      } else {
-        validateShellTemplate(file, cmd);
-        tools.push(createShellTool(cmd, repoPath, configsDir));
-      }
-    }
-
-    plugins.push({
-      name: def.name,
-      tools,
-      promptSnippet: def.prompt_snippet,
-    });
-  }
-
-  return plugins;
-}
-
-const BUNDLED_TOOL_TEMPLATES_DIR = resolve(
-  __dirname,
-  '../../templates/tools'
-);
-
-/**
- * Names of built-in tool plugins that have bundled installable templates.
- * Mirrors runner/templates/tools/*.tool.yaml.
- * Note: 'patch' is a TypeScript-only builtin with no installable template and is intentionally excluded.
- */
-export const BUILTIN_TOOL_NAMES = new Set([
-  'repo-manager',
-  'shell',
-  'search',
-  'git',
-  'web-search',
-]);
-
-/**
- * List all tool plugins available for installation from the bundled registry.
- * Returns an array of { name, description } objects.
- */
-export async function listAvailableToolTemplates(): Promise<{ name: string; description: string }[]> {
-  let files: string[];
-  try {
-    files = (await readdir(BUNDLED_TOOL_TEMPLATES_DIR)).filter(f => f.endsWith('.tool.yaml')).sort();
-  } catch {
-    return [];
-  }
-  const result: { name: string; description: string }[] = [];
-  for (const file of files) {
-    const content = await readFile(resolve(BUNDLED_TOOL_TEMPLATES_DIR, file), 'utf-8');
-    const def = yaml.load(content) as ToolPluginDef;
-    result.push({ name: file.replace('.tool.yaml', ''), description: def.description ?? '' });
-  }
-  return result;
-}
-
-/**
- * Return the raw YAML content of a bundled tool template by name.
- * Returns null if the tool does not exist in the bundled registry.
- */
-export async function getBundledToolTemplate(name: string): Promise<string | null> {
-  const filePath = resolve(BUNDLED_TOOL_TEMPLATES_DIR, `${name}.tool.yaml`);
-  try {
-    return await readFile(filePath, 'utf-8');
-  } catch {
-    return null;
-  }
-}

package/src/tools/skills/README.md

@@ -1,49 +0,0 @@
-# Skills
-
-## What are Skills?
-
-Skills are pluggable tool packs that can be dynamically loaded into the runner. A skill is a collection of related tools packaged together, typically defined in YAML configuration files with accompanying code.
-
-## Status
-
-**NOT YET IMPLEMENTED** - This is a placeholder for future functionality.
-
-## Future Implementation
-
-Skills will allow:
-- Loading tools from external YAML + TypeScript/JavaScript files
-- Packaging related tools together (e.g., "database skill", "api skill")
-- Dynamic tool discovery and registration
-- Versioning and dependency management for tool sets
-
-## Planned Structure
-
-```
-skills/
-├── database/
-│   ├── skill.yaml
-│   └── tools.ts
-├── api/
-│   ├── skill.yaml
-│   └── tools.ts
-└── custom/
-    ├── skill.yaml
-    └── tools.ts
-```
-
-Where `skill.yaml` would define:
-- Skill metadata (name, version, description)
-- Tool definitions (names, descriptions, parameters)
-- Dependencies on other skills or system requirements
-
-And `tools.ts` would implement:
-- The actual tool execution functions
-- Any helper utilities needed by the tools
-
-## Implementation TODO
-
-- [ ] Design skill manifest format (YAML schema)
-- [ ] Implement skill loader (scan directories, parse YAML, load code)
-- [ ] Add skill validation (check required fields, validate tool signatures)
-- [ ] Support skill dependencies and version constraints
-- [ ] Create example skills for common use cases

package/src/tools/skills/skill-loader.test.ts

@@ -1,106 +0,0 @@
-import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
-import { mkdir, writeFile, rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import { loadSkills, loadSkill, validateSkillManifest } from './skill-loader.js';
-
-const TMP = join('/tmp', '.studio-runner-skill-loader-test-' + Date.now());
-const SKILLS_DIR = join(TMP, 'skills');
-
-describe('loadSkill', () => {
-  beforeAll(async () => {
-    await mkdir(SKILLS_DIR, { recursive: true });
-    await writeFile(join(SKILLS_DIR, 'commit-conventions.skill.md'), '# Commit Conventions\n\nUse conventional commits.');
-    await writeFile(join(SKILLS_DIR, 'react-patterns.skill.md'), '# React Patterns\n\nPrefer hooks.');
-  });
-
-  afterAll(async () => {
-    await rm(TMP, { recursive: true, force: true });
-  });
-
-  it('returns SkillContent for an existing skill file', async () => {
-    const skill = await loadSkill('commit-conventions', TMP);
-    expect(skill).toEqual({
-      name: 'commit-conventions',
-      content: '# Commit Conventions\n\nUse conventional commits.',
-    });
-  });
-
-  it('returns null and warns for a missing skill file', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const skill = await loadSkill('nonexistent', TMP);
-    expect(skill).toBeNull();
-    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('nonexistent'));
-    warnSpy.mockRestore();
-  });
-
-  it('returns null when studioDir has no skills/ subdirectory', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const skill = await loadSkill('commit-conventions', '/tmp/nonexistent-studio-dir-xyz');
-    expect(skill).toBeNull();
-    warnSpy.mockRestore();
-  });
-});
-
-describe('loadSkills', () => {
-  beforeAll(async () => {
-    await mkdir(SKILLS_DIR, { recursive: true }).catch(() => {});
-    await writeFile(join(SKILLS_DIR, 'commit-conventions.skill.md'), '# Commit Conventions\n\nUse conventional commits.').catch(() => {});
-    await writeFile(join(SKILLS_DIR, 'react-patterns.skill.md'), '# React Patterns\n\nPrefer hooks.').catch(() => {});
-  });
-
-  it('loads all named skills from .studio/skills/', async () => {
-    const skills = await loadSkills(['commit-conventions', 'react-patterns'], TMP);
-    expect(skills).toHaveLength(2);
-    expect(skills[0]).toEqual({ name: 'commit-conventions', content: '# Commit Conventions\n\nUse conventional commits.' });
-    expect(skills[1]).toEqual({ name: 'react-patterns', content: '# React Patterns\n\nPrefer hooks.' });
-  });
-
-  it('skips missing skills and returns the ones that exist', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const skills = await loadSkills(['commit-conventions', 'missing-skill'], TMP);
-    expect(skills).toHaveLength(1);
-    expect(skills[0].name).toBe('commit-conventions');
-    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('missing-skill'));
-    warnSpy.mockRestore();
-  });
-
-  it('returns empty array when names list is empty', async () => {
-    const skills = await loadSkills([], TMP);
-    expect(skills).toHaveLength(0);
-  });
-
-  it('returns empty array when studioDir has no skills/ directory', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const skills = await loadSkills(['commit-conventions'], '/tmp/nonexistent-studio-xyz');
-    expect(skills).toHaveLength(0);
-    warnSpy.mockRestore();
-  });
-});
-
-describe('validateSkillManifest', () => {
-  it('returns true for a valid skill manifest', () => {
-    expect(validateSkillManifest({ name: 'my-skill', content: '# My Skill\n\nContent here.' })).toBe(true);
-  });
-
-  it('throws when manifest is missing name', () => {
-    expect(() => validateSkillManifest({ content: 'some content' })).toThrow();
-  });
-
-  it('throws when manifest is missing content', () => {
-    expect(() => validateSkillManifest({ name: 'my-skill' })).toThrow();
-  });
-
-  it('throws when manifest is not an object', () => {
-    expect(() => validateSkillManifest(null)).toThrow();
-    expect(() => validateSkillManifest('string')).toThrow();
-    expect(() => validateSkillManifest(42)).toThrow();
-  });
-
-  it('throws when name is not a string', () => {
-    expect(() => validateSkillManifest({ name: 123, content: 'content' })).toThrow();
-  });
-
-  it('throws when content is not a string', () => {
-    expect(() => validateSkillManifest({ name: 'skill', content: [] })).toThrow();
-  });
-});

package/src/tools/skills/skill-loader.ts

@@ -1,62 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import type { SkillContent } from '../../plugins/plugin-loader.js';
-
-export type { SkillContent };
-
-/** Minimal structure required for a valid skill manifest */
-export interface SkillManifest {
-  name: string;
-  content: string;
-}
-
-/**
- * Load multiple `.skill.md` files by name from `.studio/skills/`.
- * Missing files are skipped with a warning (non-fatal).
- */
-export async function loadSkills(skillNames: string[], studioDir: string): Promise<SkillContent[]> {
-  const results: SkillContent[] = [];
-  for (const name of skillNames) {
-    const skill = await loadSkill(name, studioDir);
-    if (skill) results.push(skill);
-  }
-  return results;
-}
-
-/**
- * Load a single `.skill.md` file by name from `<studioDir>/skills/`.
- * Returns null if the file does not exist.
- */
-export async function loadSkill(name: string, studioDir: string): Promise<SkillContent | null> {
-  const filePath = join(studioDir, 'skills', `${name}.skill.md`);
-  if (!existsSync(filePath)) {
-    console.warn(`[studio] Skill '${name}' not found at ${filePath} — skipping.`);
-    return null;
-  }
-  try {
-    const content = await readFile(filePath, 'utf-8');
-    return { name, content };
-  } catch {
-    console.warn(`[studio] Failed to load skill '${name}' — skipping.`);
-    return null;
-  }
-}
-
-/**
- * Validate that a skill manifest has the required structure.
- * Throws a descriptive error if invalid.
- */
-export function validateSkillManifest(manifest: unknown): boolean {
-  if (!manifest || typeof manifest !== 'object') {
-    throw new Error('Skill manifest must be an object');
-  }
-  const m = manifest as Record<string, unknown>;
-  if (typeof m.name !== 'string') {
-    throw new Error('Skill manifest must have a string "name" field');
-  }
-  if (typeof m.content !== 'string') {
-    throw new Error('Skill manifest must have a string "content" field');
-  }
-  return true;
-}

package/src/tools/tool-executor.test.ts

@@ -1,88 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { ToolExecutor } from './tool-executor.js';
-import { ToolRegistry } from './tool-registry.js';
-
-function makeRegistry(paramSchema: Record<string, unknown>): ToolRegistry {
-  const registry = new ToolRegistry();
-  registry.register({
-    name: 'test-tool',
-    description: 'A test tool',
-    parameters: paramSchema,
-    execute: vi.fn().mockResolvedValue({ success: true, output: 'ok' }),
-  });
-  return registry;
-}
-
-const SCHEMA_WITH_REQUIRED = {
-  type: 'object',
-  properties: {
-    query: { type: 'string', description: 'Search query' },
-  },
-  required: ['query'],
-};
-
-const SCHEMA_NO_REQUIRED = {
-  type: 'object',
-  properties: {
-    query: { type: 'string', description: 'Search query' },
-  },
-};
-
-describe('ToolExecutor — argument validation', () => {
-  it('returns error for missing required parameter', async () => {
-    const executor = new ToolExecutor(makeRegistry(SCHEMA_WITH_REQUIRED));
-    const result = await executor.execute({
-      id: '1',
-      name: 'test-tool',
-      arguments: {},
-    });
-    expect(result.error).toMatch(/missing required parameter.*query/);
-    expect(result.result).toBeUndefined();
-  });
-
-  it('returns error for unknown parameter', async () => {
-    const executor = new ToolExecutor(makeRegistry(SCHEMA_WITH_REQUIRED));
-    const result = await executor.execute({
-      id: '2',
-      name: 'test-tool',
-      arguments: { query: 'hello', pattern: 'oops' },
-    });
-    expect(result.error).toMatch(/unknown parameter.*pattern/);
-    expect(result.error).toMatch(/declared: query/);
-    expect(result.result).toBeUndefined();
-  });
-
-  it('executes successfully with correct required parameters', async () => {
-    const registry = makeRegistry(SCHEMA_WITH_REQUIRED);
-    const executor = new ToolExecutor(registry);
-    const result = await executor.execute({
-      id: '3',
-      name: 'test-tool',
-      arguments: { query: 'ramen' },
-    });
-    expect(result.error).toBeUndefined();
-    expect(result.result).toBe('ok');
-  });
-
-  it('executes successfully with no required parameters and empty args', async () => {
-    const executor = new ToolExecutor(makeRegistry(SCHEMA_NO_REQUIRED));
-    const result = await executor.execute({
-      id: '4',
-      name: 'test-tool',
-      arguments: {},
-    });
-    expect(result.error).toBeUndefined();
-    expect(result.result).toBe('ok');
-  });
-
-  it('executes successfully with optional parameter provided', async () => {
-    const executor = new ToolExecutor(makeRegistry(SCHEMA_NO_REQUIRED));
-    const result = await executor.execute({
-      id: '5',
-      name: 'test-tool',
-      arguments: { query: 'ramen' },
-    });
-    expect(result.error).toBeUndefined();
-    expect(result.result).toBe('ok');
-  });
-});

package/src/tools/tool-executor.ts

@@ -1,84 +0,0 @@
-import { ToolCall } from '@studio-foundation/contracts';
-import { ToolRegistry } from './tool-registry.js';
-
-/**
- * Validate LLM-provided arguments against the tool's JSON Schema.
- * Returns an error string if invalid, null if OK.
- */
-function validateArgs(
-  toolName: string,
-  schema: Record<string, unknown>,
-  args: Record<string, unknown>
-): string | null {
-  const properties = (schema.properties as Record<string, unknown> | undefined) ?? {};
-  const required = (schema.required as string[] | undefined) ?? [];
-  const declared = new Set(Object.keys(properties));
-
-  const missing = required.filter(p => !(p in args));
-  if (missing.length > 0) {
-    return `Tool ${toolName}: missing required parameter${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`;
-  }
-
-  const unknown = Object.keys(args).filter(p => !declared.has(p));
-  if (unknown.length > 0) {
-    return `Tool ${toolName}: unknown parameter${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')} (declared: ${[...declared].join(', ')})`;
-  }
-
-  return null;
-}
-
-export class ToolExecutor {
-  constructor(private registry: ToolRegistry) {}
-
-  async execute(toolCall: { id: string; name: string; arguments: Record<string, unknown> }): Promise<ToolCall> {
-    const tool = this.registry.get(toolCall.name);
-
-    if (!tool) {
-      return {
-        id: toolCall.id,
-        name: toolCall.name,
-        arguments: toolCall.arguments,
-        error: `Tool not found: ${toolCall.name}`
-      };
-    }
-
-    // Validate arguments against the tool's parameter schema
-    const validationError = validateArgs(toolCall.name, tool.parameters, toolCall.arguments);
-    if (validationError) {
-      return {
-        id: toolCall.id,
-        name: toolCall.name,
-        arguments: toolCall.arguments,
-        error: validationError,
-      };
-    }
-
-    try {
-      const toolResult = await tool.execute(toolCall.arguments);
-
-      if (!toolResult.success) {
-        return {
-          id: toolCall.id,
-          name: toolCall.name,
-          arguments: toolCall.arguments,
-          error: toolResult.error || 'Tool execution failed'
-        };
-      }
-
-      return {
-        id: toolCall.id,
-        name: toolCall.name,
-        arguments: toolCall.arguments,
-        result: toolResult.output
-      };
-    } catch (error: unknown) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      return {
-        id: toolCall.id,
-        name: toolCall.name,
-        arguments: toolCall.arguments,
-        error: errorMessage
-      };
-    }
-  }
-}