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

package/src/providers/openai.ts

@@ -1,139 +0,0 @@
-/**
- * OpenAI provider implementation with full tool calling support
- */
-
-import type { LLMRequest, LLMResponse } from '@studio-foundation/contracts';
-import type { Provider } from './provider.js';
-import OpenAI from 'openai';
-import type { ChatCompletionMessageParam, ChatCompletionTool, ChatCompletionChunk } from 'openai/resources/chat/completions';
-
-export class OpenAIProvider implements Provider {
-  readonly name = 'openai';
-  private client: OpenAI;
-
-  constructor(apiKey?: string, private baseUrl?: string) {
-    this.client = new OpenAI({
-      apiKey: apiKey || process.env.OPENAI_API_KEY,
-      baseURL: baseUrl
-    });
-  }
-
-  async call(request: LLMRequest, onToken?: (token: string) => void, signal?: AbortSignal): Promise<LLMResponse> {
-    const openaiMessages = this.buildMessages(request);
-    const tools = this.buildTools(request);
-
-    if (onToken) {
-      return this.callStreaming(request, openaiMessages, tools, onToken, signal);
-    }
-
-    // Non-streaming path (existing behavior)
-    const completion = await this.client.chat.completions.create({
-      model: request.model,
-      messages: openaiMessages,
-      tools: tools && tools.length > 0 ? tools : undefined,
-      temperature: request.temperature,
-      max_completion_tokens: request.max_tokens
-    }, { signal });
-
-    const choice = completion.choices[0];
-
-    // Extract tool calls if any
-    const tool_calls = choice.message.tool_calls?.map(tc => ({
-      id: tc.id,
-      name: tc.function.name,
-      arguments: JSON.parse(tc.function.arguments)
-    })) || [];
-
-    return {
-      content: choice.message.content || '',
-      tool_calls,
-      finish_reason: choice.finish_reason,
-      usage: {
-        prompt_tokens: completion.usage?.prompt_tokens || 0,
-        completion_tokens: completion.usage?.completion_tokens || 0,
-        total_tokens: completion.usage?.total_tokens || 0
-      }
-    };
-  }
-
-  private async callStreaming(
-    request: LLMRequest,
-    openaiMessages: ChatCompletionMessageParam[],
-    tools: ChatCompletionTool[] | undefined,
-    onToken: (token: string) => void,
-    signal?: AbortSignal
-  ): Promise<LLMResponse> {
-    const stream = this.client.chat.completions.create({
-      model: request.model,
-      messages: openaiMessages,
-      tools: tools && tools.length > 0 ? tools : undefined,
-      temperature: request.temperature,
-      max_completion_tokens: request.max_tokens,
-      stream: true as const,
-      stream_options: { include_usage: true },
-    }, { signal }) as unknown as AsyncIterable<ChatCompletionChunk>;
-
-    let textContent = '';
-    const toolCallMap = new Map<number, { id: string; name: string; args: string }>();
-    let finishReason = 'stop';
-    let usage: LLMResponse['usage'];
-
-    for await (const chunk of stream) {
-      // KEY FIX: check signal at the start of each chunk so we don't keep
-      // consuming buffered data after Ctrl-C.
-      if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');
-      const delta = chunk.choices[0]?.delta;
-      if (delta?.content) {
-        textContent += delta.content;
-        onToken(delta.content);
-      }
-      if (delta?.tool_calls) {
-        for (const tc of delta.tool_calls) {
-          if (!toolCallMap.has(tc.index)) {
-            toolCallMap.set(tc.index, { id: '', name: '', args: '' });
-          }
-          const acc = toolCallMap.get(tc.index)!;
-          if (tc.id) acc.id = tc.id;
-          if (tc.function?.name) acc.name += tc.function.name;
-          if (tc.function?.arguments) acc.args += tc.function.arguments;
-        }
-      }
-      if (chunk.choices[0]?.finish_reason) finishReason = chunk.choices[0].finish_reason;
-      if (chunk.usage) {
-        usage = {
-          prompt_tokens: chunk.usage.prompt_tokens,
-          completion_tokens: chunk.usage.completion_tokens,
-          total_tokens: chunk.usage.total_tokens,
-        };
-      }
-    }
-
-    const tool_calls = Array.from(toolCallMap.values()).map(tc => ({
-      id: tc.id,
-      name: tc.name,
-      arguments: JSON.parse(tc.args || '{}'),
-    }));
-
-    return { content: textContent, tool_calls, finish_reason: finishReason, usage };
-  }
-
-  private buildMessages(request: LLMRequest): ChatCompletionMessageParam[] {
-    return request.messages.map(msg => {
-      if (msg.role === 'system') return { role: 'system', content: msg.content };
-      if (msg.role === 'user') return { role: 'user', content: msg.content };
-      if (msg.role === 'assistant') return { role: 'assistant', content: msg.content };
-      throw new Error(`Unsupported message role: ${msg.role}`);
-    });
-  }
-
-  private buildTools(request: LLMRequest): ChatCompletionTool[] | undefined {
-    return request.tools?.map(tool => ({
-      type: 'function' as const,
-      function: {
-        name: tool.name,
-        description: tool.description,
-        parameters: tool.parameters
-      }
-    }));
-  }
-}

package/src/providers/provider.ts

@@ -1,54 +0,0 @@
-/**
- * Provider interface - aligned with @studio/contracts
- */
-
-import type { LLMRequest, LLMResponse } from '@studio-foundation/contracts';
-
-export interface Provider {
-  readonly name: string;
-  call(request: LLMRequest, onToken?: (token: string) => void, signal?: AbortSignal): Promise<LLMResponse>;
-}
-
-export interface ToolCallOutcome {
-  result?: unknown;
-  error?: string;
-}
-
-/**
- * Extended interface for providers that own the full agent loop.
- * Used by providers (e.g. OpenAI Responses API) where multi-turn
- * tool calling cannot be expressed as plain text messages.
- */
-export interface AgentLoopProvider extends Provider {
-  runAgentLoop(
-    request: LLMRequest,
-    executeTool: (name: string, args: Record<string, unknown>, callId: string) => Promise<ToolCallOutcome>,
-    onToken?: (token: string) => void,
-    signal?: AbortSignal
-  ): Promise<AgentLoopResult>;
-}
-
-/**
- * Full result of an agent loop execution.
- * Distinct from LLMResponse (in @studio/contracts) because it includes
- * per-tool-call execution outcomes (result/error) that are only known
- * after the runner has actually invoked each tool.
- */
-export interface AgentLoopResult {
-  content: string;
-  tool_calls: Array<{
-    id: string;
-    name: string;
-    arguments: Record<string, unknown>;
-  } & ToolCallOutcome>;
-  finish_reason: string;
-  usage?: {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-  };
-}
-
-export function isAgentLoopProvider(p: Provider): p is AgentLoopProvider {
-  return typeof (p as AgentLoopProvider).runAgentLoop === 'function';
-}

package/src/providers/registry.ts

@@ -1,77 +0,0 @@
-/**
- * Provider registry - factory for LLM providers
- */
-
-import type { Provider } from './provider.js';
-import { OpenAIProvider } from './openai.js';
-import { AnthropicProvider } from './anthropic.js';
-import { OpenAIResponsesProvider } from './openai-responses.js';
-import { OllamaProvider } from './ollama.js';
-
-export class ProviderRegistry {
-  private providers: Map<string, Provider> = new Map();
-
-  /**
-   * Register a provider instance
-   */
-  register(provider: Provider): void {
-    this.providers.set(provider.name, provider);
-  }
-
-  /**
-   * Get provider by name
-   */
-  get(name: string): Provider {
-    const provider = this.providers.get(name);
-    if (!provider) {
-      const available = this.list();
-      const detail = available.length > 0 ? available.join(', ') : '(none registered)';
-      throw new Error(`Provider not found: ${name}. Available providers: ${detail}`);
-    }
-    return provider;
-  }
-
-  /**
-   * Check if provider exists
-   */
-  has(name: string): boolean {
-    return this.providers.has(name);
-  }
-
-  /**
-   * List available provider names
-   */
-  list(): string[] {
-    return Array.from(this.providers.keys());
-  }
-}
-
-/**
- * Factory function to create a registry with default providers
- */
-export function createDefaultRegistry(config: {
-  openai?: { apiKey: string; baseUrl?: string };
-  anthropic?: { apiKey: string };
-  openaiResponses?: { apiKey: string };
-  ollama?: { baseUrl?: string };
-}): ProviderRegistry {
-  const registry = new ProviderRegistry();
-
-  if (config.openai) {
-    registry.register(new OpenAIProvider(config.openai.apiKey, config.openai.baseUrl));
-  }
-
-  if (config.anthropic) {
-    registry.register(new AnthropicProvider(config.anthropic.apiKey));
-  }
-
-  if (config.openaiResponses) {
-    registry.register(new OpenAIResponsesProvider(config.openaiResponses.apiKey));
-  }
-
-  if (config.ollama) {
-    registry.register(new OllamaProvider(config.ollama.baseUrl));
-  }
-
-  return registry;
-}

package/src/runner.test.ts

@@ -1,343 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { runAgent } from './runner.js';
-import { ToolRegistry } from './tools/tool-registry.js';
-import { ProviderRegistry } from './providers/registry.js';
-import { MockProvider } from './providers/mock.js';
-import type { ResolvedAgentConfig, LLMRequest, LLMResponse } from '@studio-foundation/contracts';
-import type { Provider } from './providers/provider.js';
-
-/**
- * A minimal Chat Completions-style provider (NOT AgentLoopProvider).
- * First call returns one tool call; second call returns the final content.
- * Tracks the messages received on each call so tests can assert on them.
- */
-class StandardProvider implements Provider {
-  readonly name = 'standard-mock';
-  private callCount = 0;
-  public receivedMessages: unknown[] = [];
-
-  async call(request: LLMRequest): Promise<LLMResponse> {
-    this.receivedMessages = request.messages as unknown[];
-    this.callCount++;
-    if (this.callCount === 1) {
-      return {
-        content: '',
-        tool_calls: [{ id: 'call-1', name: 'repo_manager-write_file', arguments: { path: '/tmp/foo.ts', content: 'hello' } }],
-        finish_reason: 'tool_calls',
-      };
-    }
-    // Second call: final response
-    return {
-      content: JSON.stringify({ summary: 'done' }),
-      tool_calls: [],
-      finish_reason: 'stop',
-    };
-  }
-}
-
-function makeConfig(toolCallName: string, toolCallArgs: Record<string, unknown>) {
-  const toolRegistry = new ToolRegistry();
-  const mockExecute = vi.fn().mockResolvedValue({ success: true, output: 'wrote file' });
-  toolRegistry.register({
-    name: toolCallName,
-    description: 'A test tool',
-    parameters: {
-      type: 'object',
-      properties: Object.fromEntries(
-        Object.keys(toolCallArgs).map(k => [k, { type: 'string' }])
-      ),
-    },
-    execute: mockExecute,
-  });
-
-  const mockProvider = new MockProvider(
-    new Map([
-      ['test-stage', {
-        output: { summary: 'done' },
-        tool_calls: [{ name: toolCallName, arguments: toolCallArgs }],
-      }],
-    ])
-  );
-
-  const providerRegistry = new ProviderRegistry();
-  providerRegistry.register(mockProvider);
-
-  const agent: ResolvedAgentConfig = {
-    name: 'test-agent',
-    provider: 'mock',
-    model: 'mock',
-  };
-
-  return { agent, toolRegistry, providerRegistry, mockExecute };
-}
-
-/**
- * A Chat Completions-style provider that always returns a tool call — simulates an infinite loop.
- */
-class LoopingProvider implements Provider {
-  readonly name = 'looping-mock';
-  public callCount = 0;
-
-  async call(_request: LLMRequest): Promise<LLMResponse> {
-    this.callCount++;
-    return {
-      content: '',
-      tool_calls: [{ id: `call-${this.callCount}`, name: 'repo_manager-write_file', arguments: { path: '/tmp/foo.ts', content: 'hello' } }],
-      finish_reason: 'tool_calls',
-    };
-  }
-}
-
-describe('runner — max tool iterations', () => {
-  it('returns an error result instead of throwing when max iterations is reached', async () => {
-    const toolRegistry = new ToolRegistry();
-    toolRegistry.register({
-      name: 'repo_manager-write_file',
-      description: 'Write a file',
-      parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } } },
-      execute: vi.fn().mockResolvedValue({ success: true }),
-    });
-
-    const loopingProvider = new LoopingProvider();
-    const providerRegistry = new ProviderRegistry();
-    providerRegistry.register(loopingProvider);
-
-    const agent: ResolvedAgentConfig = { name: 'test-agent', provider: 'looping-mock', model: 'mock' };
-
-    const result = await runAgent({
-      agent,
-      task: { description: 'write a file' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      maxToolCalls: 3,
-    });
-
-    expect(result.error).toBeDefined();
-    expect(result.error).toContain('Maximum tool calling iterations');
-    expect(result.error).toContain('3');
-    expect(loopingProvider.callCount).toBe(3);
-  });
-
-  it('includes tool calls made before hitting the limit in the error result', async () => {
-    const toolRegistry = new ToolRegistry();
-    const mockExecute = vi.fn().mockResolvedValue({ success: true });
-    toolRegistry.register({
-      name: 'repo_manager-write_file',
-      description: 'Write a file',
-      parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } } },
-      execute: mockExecute,
-    });
-
-    const providerRegistry = new ProviderRegistry();
-    providerRegistry.register(new LoopingProvider());
-
-    const agent: ResolvedAgentConfig = { name: 'test-agent', provider: 'looping-mock', model: 'mock' };
-
-    const result = await runAgent({
-      agent,
-      task: { description: 'write a file' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      maxToolCalls: 2,
-    });
-
-    expect(result.error).toBeDefined();
-    expect(result.tool_calls).toHaveLength(2);
-    expect(mockExecute).toHaveBeenCalledTimes(2);
-  });
-});
-
-describe('runner — onPreToolUse callback', () => {
-  it('blocks tool execution when callback returns blocked: true', async () => {
-    const { agent, toolRegistry, providerRegistry, mockExecute } = makeConfig(
-      'repo_manager-write_file',
-      { path: '/tmp/foo.ts', content: 'hello' }
-    );
-
-    const onPreToolUse = vi.fn().mockResolvedValue({ blocked: true, error: 'pre-hook blocked' });
-
-    const result = await runAgent({
-      agent,
-      task: { description: 'write a file', contract_name: 'test-stage' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      callbacks: { onPreToolUse },
-    });
-
-    // Tool should appear in tool_calls with error (not actually executed)
-    expect(result.tool_calls).toHaveLength(1);
-    expect(result.tool_calls[0].error).toContain('pre-hook blocked');
-    expect(result.tool_calls[0].result).toBeUndefined();
-    expect(mockExecute).not.toHaveBeenCalled();
-  });
-
-  it('allows tool execution when callback returns blocked: false', async () => {
-    const { agent, toolRegistry, providerRegistry, mockExecute } = makeConfig(
-      'repo_manager-write_file',
-      { path: '/tmp/foo.ts', content: 'hello' }
-    );
-
-    const onPreToolUse = vi.fn().mockResolvedValue({ blocked: false });
-
-    const result = await runAgent({
-      agent,
-      task: { description: 'write a file', contract_name: 'test-stage' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      callbacks: { onPreToolUse },
-    });
-
-    expect(result.tool_calls).toHaveLength(1);
-    expect(result.tool_calls[0].result).toBe('wrote file');
-    expect(mockExecute).toHaveBeenCalledOnce();
-  });
-
-  it('blocks tool execution in standard (Chat Completions) path', async () => {
-    const toolRegistry = new ToolRegistry();
-    const mockExecute = vi.fn().mockResolvedValue({ success: true, output: 'wrote file' });
-    toolRegistry.register({
-      name: 'repo_manager-write_file',
-      description: 'A test tool',
-      parameters: {
-        type: 'object',
-        properties: {
-          path: { type: 'string' },
-          content: { type: 'string' },
-        },
-      },
-      execute: mockExecute,
-    });
-
-    const standardProvider = new StandardProvider();
-    const providerRegistry = new ProviderRegistry();
-    providerRegistry.register(standardProvider);
-
-    const agent: ResolvedAgentConfig = {
-      name: 'test-agent',
-      provider: 'standard-mock',
-      model: 'mock',
-    };
-
-    const onPreToolUse = vi.fn().mockResolvedValue({ blocked: true, error: 'standard-path blocked' });
-
-    const result = await runAgent({
-      agent,
-      task: { description: 'write a file', contract_name: 'test-stage' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      callbacks: { onPreToolUse },
-    });
-
-    expect(result.tool_calls).toHaveLength(1);
-    expect(result.tool_calls[0].error).toContain('standard-path blocked');
-    expect(result.tool_calls[0].result).toBeUndefined();
-    expect(mockExecute).not.toHaveBeenCalled();
-  });
-});
-
-describe('runner — onPostToolUse callback', () => {
-  it('is called after successful tool execution', async () => {
-    const { agent, toolRegistry, providerRegistry } = makeConfig(
-      'repo_manager-write_file',
-      { path: '/tmp/foo.ts', content: 'hello' }
-    );
-
-    const onPostToolUse = vi.fn().mockResolvedValue({});
-
-    await runAgent({
-      agent,
-      task: { description: 'write a file', contract_name: 'test-stage' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      callbacks: { onPostToolUse },
-    });
-
-    expect(onPostToolUse).toHaveBeenCalledOnce();
-    expect(onPostToolUse.mock.calls[0][0]).toMatchObject({
-      tool: 'repo_manager-write_file',
-      params: { path: '/tmp/foo.ts', content: 'hello' },
-      result: 'wrote file',
-    });
-  });
-
-  it('appends hook message to conversation when returned (standard path — no-op in agent loop)', async () => {
-    // The MockProvider uses the agent loop path, so append_message is a no-op here.
-    // This test verifies onPostToolUse IS called and no error is thrown.
-    const { agent, toolRegistry, providerRegistry } = makeConfig(
-      'repo_manager-write_file',
-      { path: '/tmp/foo.ts', content: 'hello' }
-    );
-
-    const onPostToolUse = vi.fn().mockResolvedValue({
-      append_message: 'prettier ran successfully',
-    });
-
-    const result = await runAgent({
-      agent,
-      task: { description: 'write a file', contract_name: 'test-stage' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      callbacks: { onPostToolUse },
-    });
-
-    expect(onPostToolUse).toHaveBeenCalled();
-    // Result still succeeds
-    expect(result.tool_calls_count).toBe(1);
-  });
-
-  it('injects append_message into conversation in standard (Chat Completions) path', async () => {
-    const toolRegistry = new ToolRegistry();
-    const mockExecute = vi.fn().mockResolvedValue({ success: true, output: 'wrote file' });
-    toolRegistry.register({
-      name: 'repo_manager-write_file',
-      description: 'A test tool',
-      parameters: {
-        type: 'object',
-        properties: {
-          path: { type: 'string' },
-          content: { type: 'string' },
-        },
-      },
-      execute: mockExecute,
-    });
-
-    const standardProvider = new StandardProvider();
-    const providerRegistry = new ProviderRegistry();
-    providerRegistry.register(standardProvider);
-
-    const agent: ResolvedAgentConfig = {
-      name: 'test-agent',
-      provider: 'standard-mock',
-      model: 'mock',
-    };
-
-    const onPostToolUse = vi.fn().mockResolvedValue({
-      append_message: 'prettier ran and formatted the file',
-    });
-
-    const result = await runAgent({
-      agent,
-      task: { description: 'write a file', contract_name: 'test-stage' },
-      context: {},
-      toolRegistry,
-      providerRegistry,
-      callbacks: { onPostToolUse },
-    });
-
-    expect(onPostToolUse).toHaveBeenCalledOnce();
-    expect(result.tool_calls_count).toBe(1);
-
-    // Verify the post-hook message was injected into the conversation.
-    // The second call to provider.call() should include the tool result message with the append.
-    const secondCallMessages = standardProvider.receivedMessages as Array<{ role: string; content: string }>;
-    const toolResultMessage = secondCallMessages.find(m => m.role === 'user' && m.content.includes('Tool execution results'));
-    expect(toolResultMessage?.content).toContain('Post-hook note: prettier ran and formatted the file');
-  });
-});