@studio-foundation/runner 0.3.0-beta.1

package/src/providers/openai.ts

@@ -0,0 +1,139 @@
+/**
+ * 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

@@ -0,0 +1,54 @@
+/**
+ * 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

@@ -0,0 +1,77 @@
+/**
+ * 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

@@ -0,0 +1,343 @@
+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');
+  });
+});