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

package/src/prompt-builder.ts

@@ -1,332 +0,0 @@
-/**
- * Prompt builder - constructs messages for LLM with retry escalation
- */
-
-import type { Message, AgentConfig, OutputContract, ResolvedContextPack, ToolCall } from '@studio-foundation/contracts';
-import type { SkillContent } from './tools/skills/skill-loader.js';
-
-export interface ExecutionContext {
-  attempt: number;
-  previous_failures?: Array<{
-    error: string;
-    tool_calls_count: number;
-  }>;
-}
-
-export interface TaskInput {
-  description: string;
-  expected_output?: string;
-  contract_name?: string;
-}
-
-export interface GroupFeedbackContext {
-  iteration: number;
-  max_iterations: number;
-  rejection_reason: string;
-  rejection_details?: string[];
-}
-
-export interface AgentContext {
-  previous_outputs?: Record<string, unknown>;
-  previous_tool_results?: Record<string, ToolCall[]>;
-  repo_files?: string[];
-  additional_context?: string;
-  group_feedback?: GroupFeedbackContext;
-  context_packs?: ResolvedContextPack[];
-  startup_context?: Record<string, string>;
-  stage_name?: string;
-}
-
-export interface PromptBuildConfig {
-  agent: AgentConfig;
-  task: TaskInput;
-  context: AgentContext;
-  executionContext?: ExecutionContext;
-  outputContract?: OutputContract;
-  promptSnippets?: string[];
-  skills?: SkillContent[];
-}
-
-/**
- * Build prompt messages with retry escalation support
- */
-export function buildPrompt(config: PromptBuildConfig): Message[] {
-  const { agent, task, context, executionContext } = config;
-  const messages: Message[] = [];
-
-  // Build system message
-  let systemContent = agent.system_prompt || 'You are a helpful AI assistant.';
-
-  // Add output format with concrete schema when available
-  const contract = config.outputContract;
-  if (contract?.schema?.required_fields?.length) {
-    const fields = contract.schema.required_fields;
-    const requiresToolCalls = (contract.tool_calls?.minimum ?? 0) > 0;
-    systemContent += `
-
-## REQUIRED OUTPUT FORMAT
-
-You MUST ${requiresToolCalls ? 'end with' : 'respond with'} a valid JSON object. ${requiresToolCalls ? 'Your final message (after all tool calls)' : 'Your entire response'} must be parseable JSON — no markdown, no code blocks, no explanatory text${requiresToolCalls ? ' in that final message' : ' before or after'}.
-
-The JSON object MUST contain these fields:
-${fields.map((f: string) => `- "${f}" — ${getFieldTypeHint(f)}`).join('\n')}
-
-Example structure:
-{
-${fields.map((f: string) => `  "${f}": ${getFieldExample(f)}`).join(',\n')}
-}
-
-CRITICAL: If your response is not valid JSON with ALL required fields, it will be rejected and you will be asked to retry.
-Pay attention to field types: arrays must be arrays, objects must be objects. Do NOT flatten structured fields into plain strings.`;
-
-    // Inject accepted values for rejection detection fields
-    const rd = contract.post_validation?.rejection_detection;
-    if (rd?.field && rd?.approved_values?.length) {
-      systemContent += `
-
-The "${rd.field}" field MUST be one of: ${rd.approved_values.map((v: string) => `"${v}"`).join(', ')}.
-Any other value means rejection.`;
-    }
-  } else if (task.contract_name || task.expected_output) {
-    systemContent += `
-
-## Output Format
-
-${task.expected_output || `Provide your response according to the ${task.contract_name} contract.`}
-`;
-  }
-  // Inject prompt snippets from active tool plugins
-  if (config.promptSnippets && config.promptSnippets.length > 0) {
-    systemContent += '\n\n' + config.promptSnippets.join('\n\n');
-  }
-
-  // Inject skills (.studio/skills/*.skill.md) declared by the agent
-  if (config.skills && config.skills.length > 0) {
-    const skillChunks = config.skills.map(s => `## Skill: ${s.name}\n\n${s.content}`);
-    systemContent += '\n\n' + skillChunks.join('\n\n---\n\n');
-  }
-
-  messages.push({
-    role: 'system',
-    content: systemContent
-  });
-
-  // Build user message with context
-  let userContent = '';
-
-  // Group feedback FIRST — must be the most prominent thing the model sees
-  if (context.group_feedback) {
-    const fb = context.group_feedback;
-    userContent += `## ⚠️ REVISION REQUIRED — Iteration ${fb.iteration + 1}/${fb.max_iterations}\n\n`;
-    userContent += `Your previous implementation was **REJECTED**. You MUST address ALL issues below before proceeding.\n\n`;
-    userContent += `**Reason:** ${fb.rejection_reason}\n\n`;
-    if (fb.rejection_details?.length) {
-      userContent += `**Issues to fix:**\n`;
-      for (const detail of fb.rejection_details) {
-        userContent += `- ${detail}\n`;
-      }
-      userContent += '\n';
-    }
-    userContent += `DO NOT repeat the same approach. Each issue above MUST be resolved in your new implementation.\n\n---\n\n`;
-  }
-
-  // Add previous outputs if any
-  if (context.previous_outputs && Object.keys(context.previous_outputs).length > 0) {
-    userContent += '## Previous Stage Outputs\n\n';
-    for (const [stage, output] of Object.entries(context.previous_outputs)) {
-      userContent += `### ${stage}\n\`\`\`json\n${JSON.stringify(output, null, 2)}\n\`\`\`\n\n`;
-    }
-  }
-
-  // Add repository context if provided
-  if (context.repo_files && context.repo_files.length > 0) {
-    userContent += `## Repository Files\n\nRelevant files:\n${context.repo_files.map(f => `- ${f}`).join('\n')}\n\n`;
-  }
-
-  // Add additional context
-  if (context.additional_context) {
-    userContent += `## Additional Context\n\n${context.additional_context}\n\n`;
-  }
-
-  // Add stage name (used in parallel groups so agents can identify their slot)
-  if (context.stage_name) {
-    userContent += `## Stage Name\n\n${context.stage_name}\n\n`;
-  }
-
-  // Render pipeline startup context — each key as a ### section
-  if (context.startup_context && Object.keys(context.startup_context).length > 0) {
-    userContent += '## Pipeline Startup Context\n\n';
-    for (const [key, value] of Object.entries(context.startup_context)) {
-      userContent += `### ${key}\n\`\`\`\n${value}\n\`\`\`\n\n`;
-    }
-  }
-
-  // Add context packs — each as a top-level ## section, sections as ###
-  if (context.context_packs?.length) {
-    for (const pack of context.context_packs) {
-      userContent += `## ${pack.name}`;
-      if (pack.description) userContent += ` — ${pack.description}`;
-      userContent += '\n\n';
-      for (const section of pack.sections) {
-        userContent += `### ${section.title}\n\n${section.content}\n\n`;
-      }
-    }
-  }
-
-  // Add previous stage tool results (discoveries) — placed last before the task
-  // so they have high recency salience for the LLM
-  if (context.previous_tool_results && Object.keys(context.previous_tool_results).length > 0) {
-    userContent += renderToolResults(context.previous_tool_results);
-  }
-
-  // Add task description
-  userContent += `## Task\n\n${task.description}`;
-
-  // Add retry escalation if this is a retry attempt
-  if (executionContext && executionContext.attempt > 1) {
-    userContent += getRetryEscalationMessage(executionContext);
-  }
-
-  messages.push({
-    role: 'user',
-    content: userContent
-  });
-
-  return messages;
-}
-
-/**
- * Get retry escalation message based on attempt number
- * Progressively stronger messaging to enforce tool usage
- */
-function getRetryEscalationMessage(executionContext: ExecutionContext): string {
-  const { attempt, previous_failures } = executionContext;
-  let message = '\n\n---\n\n';
-
-  const hasStringError = previous_failures?.some(f => f.error.includes('Expected object output, got string'));
-  const hasMissingTool = previous_failures?.some(f => f.error.includes('Required tool'));
-
-  if (attempt === 2) {
-    message += `⚠️ **RETRY ATTEMPT ${attempt}**
-
-Your previous attempt failed. Please review the errors below and fix the issues:
-
-`;
-    previous_failures?.forEach((failure, idx) => {
-      message += `Attempt ${idx + 1}: ${failure.error}\n`;
-      if (failure.tool_calls_count === 0) {
-        message += `  → Problem: No tool calls were made. You need to use the available tools.\n`;
-      }
-    });
-
-    if (hasStringError) {
-      message += `\n⚠️ Your response was plain text, not JSON. Your FINAL message (after all tool calls) must be ONLY a raw JSON object — no explanations, no markdown.`;
-    }
-    if (hasMissingTool) {
-      message += `\n⚠️ You must use the required tools to make the actual changes, not just read or explore.`;
-    }
-
-    message += `\nMake sure to use the tools available to you to complete the task.`;
-  } else if (attempt === 3) {
-    message += `🚨 **CRITICAL: RETRY ATTEMPT ${attempt}**
-
-Multiple previous attempts have failed. This is your ${attempt}rd attempt.
-
-Previous errors:
-`;
-    previous_failures?.forEach((failure, idx) => {
-      message += `- Attempt ${idx + 1}: ${failure.error} (tool_calls: ${failure.tool_calls_count})\n`;
-    });
-
-    message += `
-**YOU MUST:**
-1. Use the available tools to make the requested changes — reading and exploring is NOT enough
-2. After all tool calls are done, send ONE final message that is ONLY a raw JSON object
-3. No markdown, no explanations, no code fences — just {"summary": "...", ...}
-
-DO NOT just provide instructions or descriptions. EXECUTE the changes, then return JSON.`;
-  } else if (attempt >= 4) {
-    message += `⛔ **FINAL WARNING: RETRY ATTEMPT ${attempt}**
-
-This is attempt ${attempt}. Previous attempts all failed:
-
-`;
-    previous_failures?.forEach((failure, idx) => {
-      message += `Attempt ${idx + 1}:\n  Error: ${failure.error}\n  Tool calls made: ${failure.tool_calls_count}\n\n`;
-    });
-
-    message += `
-🔴 **ABSOLUTE REQUIREMENTS:**
-
-1. Use the required tools to make the actual changes — DO NOT just describe them
-2. tool_calls = 0 is an AUTOMATIC FAILURE
-3. You must make ACTUAL changes, not describe them
-4. Read existing files before modifying them
-5. Your FINAL message must be ONLY a JSON object
-6. If your final message contains ANY text outside the JSON, it WILL be rejected
-
-If you do not make real tool calls AND return valid JSON, this task will fail permanently.`;
-  }
-
-  return message;
-}
-
-/** Known field type hints for required_fields schema injection */
-const FIELD_TYPE_HINTS: Record<string, string> = {
-  summary: 'string',
-  requirements: 'array of objects, each with relevant keys (e.g. {id, description, priority})',
-  acceptance_criteria: 'array of strings',
-  files_changed: 'array of objects with {path, status, changes}',
-  files_to_modify: 'array of strings (file paths)',
-  steps: 'array of strings',
-  issues: 'array of strings or objects',
-};
-
-/** Known field example values for required_fields schema injection */
-const FIELD_EXAMPLES: Record<string, string> = {
-  summary: '"A concise summary of the result"',
-  requirements: '[{"id": "REQ-1", "description": "...", "priority": "high"}]',
-  acceptance_criteria: '["criterion 1", "criterion 2"]',
-  files_changed: '[{"path": "src/file.tsx", "status": "modified", "changes": "description of changes"}]',
-  files_to_modify: '["src/file.tsx", "src/utils/helper.ts"]',
-  steps: '["step 1", "step 2", "step 3"]',
-  issues: '["issue 1", "issue 2"]',
-};
-
-const TOOL_RESULT_MAX_CHARS = 2000;
-
-function renderToolResults(previous_tool_results: Record<string, ToolCall[]>): string {
-  let out = '';
-  for (const [stage, toolCalls] of Object.entries(previous_tool_results)) {
-    out += `## Previous Stage Discoveries (${stage})\n\n`;
-    for (const tc of toolCalls) {
-      // Use first string argument value as the display label
-      const label = Object.values(tc.arguments).find(v => typeof v === 'string') ?? JSON.stringify(tc.arguments);
-      out += `### ${tc.name}(${label})\n`;
-      if (tc.error) {
-        out += `Error: ${tc.error}\n\n`;
-      } else {
-        // For write operations, render the content being written from arguments
-        // (the result is just {written: true} which is not useful for reviewers).
-        // For all other operations, render the result as usual.
-        const writeContent = typeof tc.arguments?.content === 'string'
-          ? tc.arguments.content as string
-          : null;
-        const raw = writeContent ?? JSON.stringify(tc.result, null, 2);
-        const body = raw.length > TOOL_RESULT_MAX_CHARS
-          ? raw.slice(0, TOOL_RESULT_MAX_CHARS) + '\n[truncated]'
-          : raw;
-        out += `\`\`\`\n${body}\n\`\`\`\n\n`;
-      }
-    }
-  }
-  return out;
-}
-
-function getFieldTypeHint(field: string): string {
-  return FIELD_TYPE_HINTS[field] || 'string';
-}
-
-function getFieldExample(field: string): string {
-  return FIELD_EXAMPLES[field] || '"..."';
-}

package/src/providers/anthropic.test.ts

@@ -1,101 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { AnthropicProvider } from './anthropic.js';
-
-// We mock the entire SDK so no real HTTP calls are made.
-// The fake stream hangs on finalMessage() to simulate the bug scenario.
-vi.mock('@anthropic-ai/sdk', () => {
-  return {
-    default: class FakeAnthropic {
-      messages = {
-        stream: (_params: unknown, _opts: unknown) => {
-          const listeners = new Map<string, ((...args: unknown[]) => void)[]>();
-          return {
-            on(event: string, handler: (...args: unknown[]) => void) {
-              if (!listeners.has(event)) listeners.set(event, []);
-              listeners.get(event)!.push(handler);
-              return this;
-            },
-            // finalMessage() hangs forever — this is the bug we're fixing
-            finalMessage: () => new Promise(() => {}),
-          };
-        },
-        create: (_params: unknown, _opts: unknown) => new Promise(() => {}),
-      };
-    },
-  };
-});
-
-describe('AnthropicProvider', () => {
-  let provider: AnthropicProvider;
-
-  beforeEach(() => {
-    provider = new AnthropicProvider('test-key');
-  });
-
-  it('aborts streaming call when signal fires', async () => {
-    const controller = new AbortController();
-    const onToken = vi.fn();
-
-    const callPromise = provider.call(
-      {
-        model: 'claude-haiku-4-20250514',
-        messages: [{ role: 'user', content: 'hello' }],
-      },
-      onToken,
-      controller.signal,
-    );
-
-    // Fire signal after a tick to let the stream start
-    await Promise.resolve();
-    controller.abort();
-
-    await expect(callPromise).rejects.toSatisfy(
-      (e: unknown) => e instanceof DOMException && (e as DOMException).name === 'AbortError',
-    );
-  });
-
-  it('aborts non-streaming call when signal fires', async () => {
-    const controller = new AbortController();
-
-    const callPromise = provider.call(
-      {
-        model: 'claude-haiku-4-20250514',
-        messages: [{ role: 'user', content: 'hello' }],
-      },
-      undefined,
-      controller.signal,
-    );
-
-    await Promise.resolve();
-    controller.abort();
-
-    await expect(callPromise).rejects.toSatisfy(
-      (e: unknown) => e instanceof DOMException && (e as DOMException).name === 'AbortError',
-    );
-  });
-
-  it('resolves normally when signal is not aborted', async () => {
-    // Directly override stream on the already-created client instance.
-    // (prototype override won't work because messages is an instance property.)
-    const client = (provider as unknown as { client: { messages: Record<string, unknown> } }).client;
-    client.messages.stream = () => ({
-      on: (_: string, __: unknown) => ({}),
-      finalMessage: () => Promise.resolve({
-        content: [{ type: 'text', text: '{"ok":true}' }],
-        stop_reason: 'end_turn',
-        usage: { input_tokens: 10, output_tokens: 5 },
-      }),
-    });
-
-    const controller = new AbortController();
-    const result = await provider.call(
-      {
-        model: 'claude-haiku-4-20250514',
-        messages: [{ role: 'user', content: 'hello' }],
-      },
-      vi.fn(),
-      controller.signal,
-    );
-    expect(result).toBeDefined();
-  });
-});

package/src/providers/anthropic.ts

@@ -1,135 +0,0 @@
-/**
- * Anthropic provider implementation with full tool calling support
- */
-
-import type { LLMRequest, LLMResponse } from '@studio-foundation/contracts';
-import type { Provider } from './provider.js';
-import Anthropic from '@anthropic-ai/sdk';
-import type {
-  Message,
-  MessageParam,
-  Tool,
-  TextBlockParam
-} from '@anthropic-ai/sdk/resources/messages';
-import { raceSignal } from '../utils/race-signal.js';
-
-export class AnthropicProvider implements Provider {
-  readonly name = 'anthropic';
-  private client: Anthropic;
-
-  constructor(apiKey?: string) {
-    this.client = new Anthropic({
-      apiKey: apiKey || process.env.ANTHROPIC_API_KEY
-    });
-  }
-
-  async call(request: LLMRequest, onToken?: (token: string) => void, signal?: AbortSignal): Promise<LLMResponse> {
-    const params = this.buildParams(request);
-
-    if (onToken) {
-      // Streaming path
-      const stream = this.client.messages.stream(params, { signal });
-      stream.on('text', (textDelta: string) => {
-        if (signal?.aborted) return; // guard: don't emit after abort
-        onToken(textDelta);
-      });
-      // KEY FIX: race finalMessage() against signal abort.
-      // Without this, finalMessage() hangs forever when the HTTP connection
-      // is killed mid-stream (the stream 'end' event never fires).
-      const response = await raceSignal(stream.finalMessage(), signal);
-      return this.parseResponse(response);
-    }
-
-    // Non-streaming path
-    const response = await raceSignal(this.client.messages.create(params, { signal }), signal);
-    return this.parseResponse(response);
-  }
-
-  private buildParams(request: LLMRequest) {
-    // Extract system messages (Anthropic handles them separately)
-    const systemMessages = request.messages.filter(m => m.role === 'system');
-    const systemContent = systemMessages.map(m => m.content).join('\n\n');
-
-    // Convert remaining messages to Anthropic format
-    const anthropicMessages: MessageParam[] = request.messages
-      .filter(m => m.role !== 'system')
-      .map(msg => {
-        if (msg.role === 'user') {
-          return { role: 'user' as const, content: msg.content };
-        }
-        if (msg.role === 'assistant') {
-          return { role: 'assistant' as const, content: msg.content };
-        }
-        throw new Error(`Unsupported message role: ${msg.role}`);
-      });
-
-    // Convert tool definitions to Anthropic format
-    // Mark the last tool with cache_control so Anthropic caches system + tools block
-    const rawTools = request.tools ?? [];
-    const tools: Tool[] | undefined = rawTools.length > 0
-      ? rawTools.map((tool, index) => ({
-          name: tool.name,
-          description: tool.description,
-          input_schema: {
-            type: 'object',
-            ...tool.parameters
-          } as Tool['input_schema'],
-          ...(index === rawTools.length - 1
-            ? { cache_control: { type: 'ephemeral' as const } }
-            : {})
-        }))
-      : undefined;
-
-    // Mark system prompt with cache_control — stable across retries and group iterations
-    const systemParam: TextBlockParam[] | undefined = systemContent
-      ? [{ type: 'text', text: systemContent, cache_control: { type: 'ephemeral' as const } }]
-      : undefined;
-
-    return {
-      model: request.model,
-      max_tokens: request.max_tokens || 4096,
-      system: systemParam,
-      messages: anthropicMessages,
-      tools: tools,
-      temperature: request.temperature
-    };
-  }
-
-  private parseResponse(response: Message): LLMResponse {
-    // Parse tool calls and text content from response
-    const tool_calls: Array<{
-      id: string;
-      name: string;
-      arguments: Record<string, unknown>;
-    }> = [];
-    let textContent = '';
-
-    for (const block of response.content) {
-      if (block.type === 'text') {
-        textContent += block.text;
-      } else if (block.type === 'tool_use') {
-        tool_calls.push({
-          id: block.id,
-          name: block.name,
-          arguments: block.input as Record<string, unknown>
-        });
-      }
-    }
-
-    const cachedInputTokens = response.usage.cache_read_input_tokens ?? 0;
-    const cacheCreationTokens = response.usage.cache_creation_input_tokens ?? 0;
-
-    return {
-      content: textContent,
-      tool_calls,
-      finish_reason: response.stop_reason || 'stop',
-      usage: {
-        prompt_tokens: response.usage.input_tokens,
-        completion_tokens: response.usage.output_tokens,
-        total_tokens: response.usage.input_tokens + response.usage.output_tokens,
-        cached_input_tokens: cachedInputTokens > 0 ? cachedInputTokens : undefined,
-        cache_creation_tokens: cacheCreationTokens > 0 ? cacheCreationTokens : undefined
-      }
-    };
-  }
-}

package/src/providers/mock.ts

@@ -1,57 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import type { LLMRequest, LLMResponse } from '@studio-foundation/contracts';
-import type { AgentLoopProvider, AgentLoopResult, ToolCallOutcome } from './provider.js';
-
-export interface MockStageConfig {
-  output: Record<string, unknown>;
-  tool_calls: Array<{
-    name: string;
-    arguments: Record<string, unknown>;
-  }>;
-}
-
-export class MockProvider implements AgentLoopProvider {
-  readonly name = 'mock';
-
-  constructor(private readonly stages: Map<string, MockStageConfig>) {}
-
-  async call(_request: LLMRequest, _onToken?: (token: string) => void, _signal?: AbortSignal): Promise<LLMResponse> {
-    throw new Error('MockProvider: use runAgentLoop, not call()');
-  }
-
-  async runAgentLoop(
-    request: LLMRequest,
-    executeTool: (name: string, args: Record<string, unknown>, callId: string) => Promise<ToolCallOutcome>,
-    onToken?: (token: string) => void,
-    _signal?: AbortSignal
-  ): Promise<AgentLoopResult> {
-    if (!request.stage_name) {
-      throw new Error('MockProvider requires stage_name in LLMRequest');
-    }
-
-    const config = this.stages.get(request.stage_name);
-    if (!config) {
-      throw new Error(
-        `Unknown mock stage: "${request.stage_name}". Add it to mock.yaml.`
-      );
-    }
-
-    // Emit a fake token to exercise the streaming pipeline in tests
-    onToken?.('...');
-
-    const toolCallResults: AgentLoopResult['tool_calls'] = [];
-
-    for (const tc of config.tool_calls) {
-      const callId = randomUUID();
-      const outcome = await executeTool(tc.name, tc.arguments, callId);
-      toolCallResults.push({ id: callId, name: tc.name, arguments: tc.arguments, ...outcome });
-    }
-
-    return {
-      content: JSON.stringify(config.output),
-      tool_calls: toolCallResults,
-      finish_reason: 'stop',
-      usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
-    };
-  }
-}