@bluecopa/harness 1.0.0 → 2.0.0

package/src/agent/create-agent.ts

@@ -1,884 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import type { BatchOp, BatchResult, ToolProvider, ToolResult } from '../interfaces/tool-provider';
-import type { SandboxProvider } from '../interfaces/sandbox-provider';
-import { recordAgentError, recordAgentStep, recordToolCallDuration } from '../observability/metrics';
-import { traceStep } from '../observability/tracing';
-import type { HarnessTelemetry } from '../observability/otel';
-import { HookRunner } from '../hooks/hook-runner';
-import { PermissionManager } from '../permissions/permission-manager';
-import { VercelAgentLoop } from '../loop/vercel-agent-loop';
-import { SkillManager } from '../skills/skill-manager';
-import { SkillRouter } from '../skills/skill-router';
-import type { SkillSummary } from '../skills/skill-types';
-import { SingleFlightStepExecutor } from './step-executor';
-import type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo } from './types';
-export type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo };
-export { HookRunner } from '../hooks/hook-runner';
-export { PermissionManager } from '../permissions/permission-manager';
-export type { PermissionMode, PermissionResolver, PermissionRequest } from '../permissions/permission-manager';
-export type { HookCallback, HookContext, HookDecision, HookEventName } from '../interfaces/hooks';
-
-export interface AgentRuntime {
-  toolProvider: ToolProvider;
-  sandboxProvider?: SandboxProvider;
-  skillManager?: SkillManager;
-  skillIndexPath?: string;
-  loop?: AgentLoop;
-  nextAction?(messages: AgentMessage[]): Promise<AgentAction>;
-  askUser?(question: string, options?: string[]): Promise<string>;
-  tellUser?(message: string): Promise<void>;
-  downloadRawFile?(path: string): Promise<string>;
-  maxSteps?: number;
-  telemetry?: HarnessTelemetry;
-  /** Hook runner for PreToolUse/PostToolUse lifecycle hooks. When provided, hooks are applied to ALL tool calls including custom ones via executeToolAction. */
-  hookRunner?: HookRunner;
-  /** Permission manager for tool-level access control. When provided, permission checks are applied to ALL tool calls including custom ones via executeToolAction. */
-  permissionManager?: PermissionManager;
-  /** Custom tool executor. Called for every tool action. Return null to fall through to built-in dispatch.
-   *  When hookRunner/permissionManager are provided on the runtime, they are automatically applied before/after this callback — no manual wiring needed. */
-  executeToolAction?: (action: ToolCallAction) => Promise<ToolResult | null>;
-}
-
-/**
- * Run PreToolUse hook + PermissionManager check + execute + PostToolUse hook + telemetry.
- * Wraps any tool execution (custom or built-in) with the full lifecycle when configured.
- */
-async function guardedExecute(
-  action: ToolCallAction,
-  execute: () => Promise<ToolResult>,
-  runtime: AgentRuntime,
-): Promise<ToolResult> {
-  const { hookRunner, permissionManager, telemetry } = runtime;
-  if (!hookRunner && !permissionManager) {
-    return execute();
-  }
-
-  return traceStep(telemetry, 'tool.call', { tool: action.name }, async () => {
-    const started = Date.now();
-
-    // PreToolUse hook
-    if (hookRunner) {
-      const pre = await hookRunner.run({ event: 'PreToolUse', toolName: action.name, input: action.args });
-      if (!pre.allow) {
-        const result = { success: false, output: '', error: pre.reason ?? 'blocked by pre-hook' };
-        recordToolCallDuration(telemetry, action.name, Date.now() - started, false);
-        return result;
-      }
-    }
-
-    // Permission check
-    if (permissionManager) {
-      const permission = await permissionManager.check({ toolName: action.name, input: action.args });
-      if (!permission.allow) {
-        const result = { success: false, output: '', error: permission.reason ?? 'blocked by permission manager' };
-        recordToolCallDuration(telemetry, action.name, Date.now() - started, false);
-        return result;
-      }
-    }
-
-    const result = await execute();
-
-    // PostToolUse hook
-    if (hookRunner) {
-      await hookRunner.run({ event: 'PostToolUse', toolName: action.name, input: action.args, output: result });
-    }
-
-    recordToolCallDuration(telemetry, action.name, Date.now() - started, result.success);
-    return result;
-  });
-}
-
-async function executeTool(provider: ToolProvider, action: ToolCallAction, runtime: AgentRuntime): Promise<ToolResult> {
-  return guardedExecute(action, async () => {
-    if (runtime.executeToolAction) {
-      const result = await runtime.executeToolAction(action);
-      if (result) return result;
-    }
-
-    return executeBuiltinTool(provider, action, runtime);
-  }, runtime);
-}
-
-async function executeBuiltinTool(provider: ToolProvider, action: ToolCallAction, runtime: AgentRuntime): Promise<ToolResult> {
-  if (action.name === 'Bash') {
-    return provider.bash(String(action.args.command ?? ''), {
-      cwd: action.args.cwd as string | undefined,
-      timeout: action.args.timeout as number | undefined
-    });
-  }
-
-  if (action.name === 'Read') {
-    return provider.readFile(String(action.args.path ?? ''));
-  }
-
-  if (action.name === 'Write') {
-    return provider.writeFile(String(action.args.path ?? ''), String(action.args.content ?? ''));
-  }
-
-  if (action.name === 'Edit') {
-    return provider.editFile(
-      String(action.args.path ?? ''),
-      String(action.args.old_text ?? ''),
-      String(action.args.new_text ?? '')
-    );
-  }
-
-  if (action.name === 'Glob') {
-    return provider.glob(String(action.args.pattern ?? ''));
-  }
-
-  if (action.name === 'WebFetch') {
-    if (!provider.webFetch) {
-      return { success: false, output: '', error: 'WebFetch unavailable: provider.webFetch not configured' };
-    }
-    return provider.webFetch({
-      url: String(action.args.url ?? ''),
-      selector: action.args.selector as string | undefined,
-      maxContentLength: action.args.maxContentLength as number | undefined,
-      headers: action.args.headers as Record<string, string> | undefined
-    });
-  }
-
-  if (action.name === 'WebSearch') {
-    if (!provider.webSearch) {
-      return { success: false, output: '', error: 'WebSearch unavailable: provider.webSearch not configured' };
-    }
-    return provider.webSearch(String(action.args.query ?? ''));
-  }
-
-  if (action.name === 'AskUser') {
-    if (!runtime.askUser) {
-      return { success: false, output: '', error: 'AskUser unavailable: runtime.askUser not configured' };
-    }
-    const answer = await runtime.askUser(
-      String(action.args.question ?? ''),
-      Array.isArray(action.args.options)
-        ? action.args.options.map((item) => String(item))
-        : undefined
-    );
-    return { success: true, output: answer };
-  }
-
-  if (action.name === 'TellUser') {
-    if (!runtime.tellUser) {
-      return { success: false, output: '', error: 'TellUser unavailable: runtime.tellUser not configured' };
-    }
-    await runtime.tellUser(String(action.args.message ?? ''));
-    return { success: true, output: 'ok' };
-  }
-
-  if (action.name === 'DownloadRawFile') {
-    if (!runtime.downloadRawFile) {
-      return { success: false, output: '', error: 'DownloadRawFile unavailable: runtime.downloadRawFile not configured' };
-    }
-    const localPath = await runtime.downloadRawFile(String(action.args.path ?? ''));
-    return { success: true, output: localPath };
-  }
-
-  if (action.name === 'Grep') {
-    return provider.grep(String(action.args.pattern ?? ''), action.args.path as string | undefined);
-  }
-
-  return { success: false, output: '', error: `Unknown tool: ${action.name}` };
-}
-
-function validateToolAction(action: ToolCallAction): string | null {
-  const requireNonEmpty = (value: unknown, field: string): string | null => {
-    if (typeof value !== 'string' || value.trim().length === 0) {
-      return `${action.name} requires non-empty ${field}`;
-    }
-    return null;
-  };
-
-  if (action.name === 'Bash') return requireNonEmpty(action.args.command, 'command');
-  if (action.name === 'Read') return requireNonEmpty(action.args.path, 'path');
-  if (action.name === 'Write') {
-    return requireNonEmpty(action.args.path, 'path') ?? requireNonEmpty(action.args.content, 'content');
-  }
-  if (action.name === 'Edit') {
-    return (
-      requireNonEmpty(action.args.path, 'path') ??
-      requireNonEmpty(action.args.old_text, 'old_text') ??
-      requireNonEmpty(action.args.new_text, 'new_text')
-    );
-  }
-  if (action.name === 'Glob') return requireNonEmpty(action.args.pattern, 'pattern');
-  if (action.name === 'Grep') return requireNonEmpty(action.args.pattern, 'pattern');
-  if (action.name === 'WebFetch') return requireNonEmpty(action.args.url, 'url');
-  if (action.name === 'WebSearch') return requireNonEmpty(action.args.query, 'query');
-  if (action.name === 'AskUser') return requireNonEmpty(action.args.question, 'question');
-  if (action.name === 'TellUser') return requireNonEmpty(action.args.message, 'message');
-  if (action.name === 'DownloadRawFile') return requireNonEmpty(action.args.path, 'path');
-  return null;
-}
-
-function toStreamResult(r: ToolResult): { success: boolean; output: string; error?: string } {
-  const base: { success: boolean; output: string; error?: string } = { success: r.success, output: r.output };
-  if (r.error != null) base.error = r.error;
-  return base;
-}
-
-/** Format a display-friendly content string for tool results (used in content field). */
-function formatToolResultContent(call: ToolCallAction, result: ToolResult): string {
-  const content = result.success ? result.output : `ERROR: ${result.error ?? 'unknown failure'}`;
-  switch (call.name) {
-    case 'Write':
-      return `Write(${call.args.path}): ${result.success ? 'ok' : content}`;
-    case 'Read':
-      return `Read(${call.args.path}): ${content}`;
-    case 'Edit':
-      return `Edit(${call.args.path}): ${content}`;
-    case 'Bash': {
-      const cmd = String(call.args.command ?? '').slice(0, 100);
-      return `Bash(${JSON.stringify(cmd)}): ${content}`;
-    }
-    default:
-      return `${call.name}: ${content}`;
-  }
-}
-
-/** Format a display-friendly content string for assistant tool call summaries. */
-function formatToolCallContent(calls: ToolCallAction[]): string {
-  const lines = calls.map(call => {
-    switch (call.name) {
-      case 'Write': {
-        const p = String(call.args.path ?? '');
-        const len = String(call.args.content ?? '').length;
-        return `- Write: path="${p}" (${len} chars)`;
-      }
-      case 'Bash': {
-        const cmd = String(call.args.command ?? '').slice(0, 200);
-        return `- Bash: ${JSON.stringify(cmd)}`;
-      }
-      case 'Read':
-        return `- Read: path="${call.args.path}"`;
-      case 'Edit':
-        return `- Edit: path="${call.args.path}"`;
-      case 'Glob':
-        return `- Glob: pattern="${call.args.pattern}"`;
-      case 'Grep':
-        return `- Grep: pattern="${call.args.pattern}" path="${call.args.path ?? '.'}"`;
-      default: {
-        const summary = JSON.stringify(call.args);
-        return `- ${call.name}: ${summary.length > 200 ? summary.slice(0, 200) + '…' : summary}`;
-      }
-    }
-  });
-  return `[Tool calls:\n${lines.join('\n')}]`;
-}
-
-const SANDBOX_TOOLS = new Set(['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep']);
-
-function isSandboxTool(name: string): boolean {
-  return SANDBOX_TOOLS.has(name);
-}
-
-/**
- * Convert a validated ToolCallAction into BatchOp(s).
- * Edit expands into a read_file placeholder — the actual read+replace+write
- * is handled by expandEditOps after the batch returns.
- */
-function toolCallToBatchOps(call: ToolCallAction): BatchOp[] {
-  switch (call.name) {
-    case 'Bash': {
-      const op: BatchOp = {
-        op: 'exec' as const,
-        command: String(call.args.command ?? ''),
-        timeoutMs: (call.args.timeout as number | undefined) ?? 60_000,
-      };
-      if (call.args.cwd) (op as { cwd?: string }).cwd = String(call.args.cwd);
-      return [op];
-    }
-    case 'Write':
-      return [{
-        op: 'write_file' as const,
-        path: String(call.args.path ?? ''),
-        content: String(call.args.content ?? ''),
-      }];
-    case 'Read':
-      return [{
-        op: 'read_file' as const,
-        path: String(call.args.path ?? ''),
-      }];
-    case 'Edit':
-      // Edit = read_file + write_file; we'll read first, then apply the
-      // replacement client-side and append a write_file op.
-      return [{
-        op: 'read_file' as const,
-        path: String(call.args.path ?? ''),
-      }];
-    case 'Glob': {
-      const escaped = String(call.args.pattern ?? '').replace(/'/g, "'\\''");
-      return [{
-        op: 'exec' as const,
-        command: `find / -type f -name '${escaped}' 2>/dev/null | head -n 200`,
-      }];
-    }
-    case 'Grep': {
-      const escapedPattern = String(call.args.pattern ?? '').replace(/'/g, "'\\''");
-      const escapedPath = (String(call.args.path ?? '/') || '/').replace(/'/g, "'\\''");
-      return [{
-        op: 'exec' as const,
-        command: `grep -R -n -- '${escapedPattern}' '${escapedPath}' 2>/dev/null | head -n 200`,
-      }];
-    }
-    default:
-      return [];
-  }
-}
-
-/** Map a BatchResult back to a ToolResult */
-function batchResultToToolResult(result: BatchResult): ToolResult {
-  if (!result.success) {
-    return { success: false, output: '', error: (result as { error: string }).error };
-  }
-  if (result.op === 'exec') {
-    const success = result.exitCode === 0;
-    return {
-      success,
-      output: result.stdout ?? '',
-      error: success ? undefined : result.stderr || `exit code ${result.exitCode}`,
-    };
-  }
-  if (result.op === 'read_file') {
-    return { success: true, output: result.content };
-  }
-  // write_file
-  return { success: true, output: 'ok' };
-}
-
-/**
- * Execute a batch of tool calls using provider.batch() when available.
- * Sandbox ops go through the batch endpoint (sequential, single HTTP call).
- * Non-sandbox ops run locally in parallel.
- * Returns results in the same order as the input calls.
- */
-async function executeBatch(
-  calls: ToolCallAction[],
-  provider: ToolProvider,
-  runtime: AgentRuntime,
-): Promise<ToolResult[]> {
-  // If batch not available, fall back to parallel execution
-  if (!provider.batch) {
-    return Promise.all(
-      calls.map(async (call) => {
-        try {
-          return await executeTool(provider, call, runtime);
-        } catch (error) {
-          return { success: false, output: '', error: error instanceof Error ? error.message : String(error) };
-        }
-      })
-    );
-  }
-
-  // Partition into sandbox ops and non-sandbox ops
-  const sandboxCalls: { index: number; call: ToolCallAction }[] = [];
-  const nonSandboxCalls: { index: number; call: ToolCallAction }[] = [];
-  for (let i = 0; i < calls.length; i++) {
-    if (isSandboxTool(calls[i]!.name)) {
-      sandboxCalls.push({ index: i, call: calls[i]! });
-    } else {
-      nonSandboxCalls.push({ index: i, call: calls[i]! });
-    }
-  }
-
-  // If no sandbox calls, just run everything in parallel
-  if (sandboxCalls.length === 0) {
-    return Promise.all(
-      calls.map(async (call) => {
-        try {
-          return await executeTool(provider, call, runtime);
-        } catch (error) {
-          return { success: false, output: '', error: error instanceof Error ? error.message : String(error) };
-        }
-      })
-    );
-  }
-
-  const allResults: ToolResult[] = new Array(calls.length);
-
-  // Build BatchOp[] from sandbox calls, tracking which original call each op maps to.
-  // Edit calls produce a read_file op; we'll need a second pass to add write_file ops.
-  const batchOps: BatchOp[] = [];
-  // Maps: batchOps index → { callsIndex, isEditRead }
-  const opMapping: { callsIndex: number; isEditRead: boolean }[] = [];
-
-  for (const { index, call } of sandboxCalls) {
-    const ops = toolCallToBatchOps(call);
-    for (const op of ops) {
-      opMapping.push({ callsIndex: index, isEditRead: call.name === 'Edit' });
-      batchOps.push(op);
-    }
-  }
-
-  // First batch pass (includes Edit reads)
-  let batchResults: BatchResult[];
-  try {
-    batchResults = await provider.batch(batchOps);
-  } catch (error) {
-    // If batch fails entirely, fall back to parallel
-    return Promise.all(
-      calls.map(async (call) => {
-        try {
-          return await executeTool(provider, call, runtime);
-        } catch (err) {
-          return { success: false, output: '', error: err instanceof Error ? err.message : String(err) };
-        }
-      })
-    );
-  }
-
-  // Process Edit calls: for each Edit read result, apply the text replacement
-  // and do a second batch with the write_file ops.
-  const editWrites: BatchOp[] = [];
-  const editWriteMapping: { callsIndex: number }[] = [];
-
-  for (let i = 0; i < batchResults.length; i++) {
-    const mapping = opMapping[i]!;
-    const result = batchResults[i]!;
-
-    if (mapping.isEditRead) {
-      const call = calls[mapping.callsIndex]!;
-      if (!result.success) {
-        allResults[mapping.callsIndex] = batchResultToToolResult(result);
-        continue;
-      }
-      const content = (result as { content: string }).content;
-      const oldText = String(call.args.old_text ?? '');
-      if (!content.includes(oldText)) {
-        allResults[mapping.callsIndex] = {
-          success: false,
-          output: '',
-          error: 'old text not found',
-          metadata: { path: String(call.args.path ?? '') },
-        };
-        continue;
-      }
-      const newContent = content.replace(oldText, String(call.args.new_text ?? ''));
-      editWrites.push({
-        op: 'write_file' as const,
-        path: String(call.args.path ?? ''),
-        content: newContent,
-      });
-      editWriteMapping.push({ callsIndex: mapping.callsIndex });
-    } else {
-      allResults[mapping.callsIndex] = batchResultToToolResult(result);
-    }
-  }
-
-  // Second batch pass for Edit writes (if any)
-  if (editWrites.length > 0) {
-    try {
-      const writeResults = await provider.batch(editWrites);
-      for (let i = 0; i < writeResults.length; i++) {
-        allResults[editWriteMapping[i]!.callsIndex] = batchResultToToolResult(writeResults[i]!);
-      }
-    } catch (error) {
-      const errMsg = error instanceof Error ? error.message : String(error);
-      for (const { callsIndex } of editWriteMapping) {
-        allResults[callsIndex] = { success: false, output: '', error: errMsg };
-      }
-    }
-  }
-
-  // Run non-sandbox ops in parallel
-  if (nonSandboxCalls.length > 0) {
-    const localResults = await Promise.all(
-      nonSandboxCalls.map(async ({ call }) => {
-        try {
-          return await executeTool(provider, call, runtime);
-        } catch (error) {
-          return { success: false, output: '', error: error instanceof Error ? error.message : String(error) };
-        }
-      })
-    );
-    for (let i = 0; i < nonSandboxCalls.length; i++) {
-      allResults[nonSandboxCalls[i]!.index] = localResults[i]!;
-    }
-  }
-
-  return allResults;
-}
-
-export function createAgent(runtime: AgentRuntime) {
-  const executor = new SingleFlightStepExecutor();
-  const skillManager =
-    runtime.skillManager ??
-    (runtime.sandboxProvider ? new SkillManager(runtime.sandboxProvider, runtime.telemetry) : undefined);
-  const skillIndexPath = runtime.skillIndexPath ?? process.env.SKILL_INDEX_PATH;
-  let skillSummariesPromise: Promise<SkillSummary[]> | null = null;
-  const skillRouter = new SkillRouter();
-
-  const loop: AgentLoop =
-    runtime.loop ??
-    (runtime.nextAction
-      ? { nextAction: runtime.nextAction }
-      : new VercelAgentLoop());
-
-  async function resolveSkillContext(prompt: string): Promise<string> {
-    if (!skillManager || !skillIndexPath) return '';
-
-    try {
-      skillSummariesPromise ??= skillManager.discover(skillIndexPath);
-      const summaries = await skillSummariesPromise;
-      if (summaries.length === 0) return '';
-
-      const matched = await skillRouter.selectSkill(prompt, summaries);
-      if (!matched) return '';
-
-      const invoked = await skillManager.invoke(matched.name);
-      const exec = invoked.execution;
-      const execSummary = exec
-        ? `Skill execution: attempted=${exec.attempted} success=${exec.success} commandsRun=${exec.commandsRun ?? 0}`
-        : 'Skill execution: n/a';
-      return `Skill selected: ${matched.name}\n${execSummary}\n${invoked.instructions}`;
-    } catch {
-      return '';
-    }
-  }
-
-  return {
-    async run(prompt: string, options?: { history?: AgentMessage[] }): Promise<AgentRunResult> {
-      return traceStep(runtime.telemetry, 'agent.run', { component: 'agent' }, async () => {
-        const skillContext = await resolveSkillContext(prompt);
-        const effectivePrompt = skillContext
-          ? `${prompt}\n\nSkill guidance:\n${skillContext}`
-          : prompt;
-        const history = options?.history ?? [];
-        const messages: AgentMessage[] = [...history, { role: 'user', content: effectivePrompt }];
-        const maxSteps = runtime.maxSteps ?? 50;
-        const maxConsecutiveInvalid = 3;
-        let consecutiveInvalid = 0;
-
-        for (let step = 1; step <= maxSteps; step += 1) {
-          recordAgentStep(runtime.telemetry);
-
-          const action = await traceStep(
-            runtime.telemetry,
-            'agent.step',
-            { step },
-            () => executor.run(() => loop.nextAction(messages))
-          );
-
-          if (action.type === 'final') {
-            messages.push({ role: 'assistant', content: action.content });
-            return {
-              messages,
-              output: action.content,
-              steps: step
-            };
-          }
-
-          if (action.type === 'tool_batch') {
-            // Validate each call individually; partition into valid and invalid
-            const validCalls: ToolCallAction[] = [];
-            const invalidMessages: string[] = [];
-            for (const call of action.calls) {
-              const err = validateToolAction(call);
-              if (err) {
-                invalidMessages.push(`${call.name}: ERROR: ${err}`);
-              } else {
-                validCalls.push(call);
-              }
-            }
-
-            // Record assistant message with structured toolCalls
-            const allCalls = action.calls;
-            messages.push({
-              role: 'assistant',
-              content: formatToolCallContent(allCalls),
-              toolCalls: allCalls.map(c => ({
-                toolCallId: c.toolCallId ?? randomUUID(),
-                toolName: c.name,
-                args: c.args,
-              })),
-            });
-
-            // Execute valid calls via batch (sequential sandbox ops) or parallel fallback
-            if (validCalls.length > 0) {
-              const results = await executeBatch(validCalls, runtime.toolProvider, runtime);
-              for (let i = 0; i < validCalls.length; i++) {
-                const call = validCalls[i]!;
-                const r = results[i]!;
-                if (!r.success) {
-                  recordAgentError(runtime.telemetry);
-                }
-                const resultText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
-                messages.push({
-                  role: 'tool',
-                  content: formatToolResultContent(call, r),
-                  toolResults: [{
-                    toolCallId: call.toolCallId ?? '',
-                    toolName: call.name,
-                    result: resultText,
-                    isError: !r.success,
-                  }],
-                });
-              }
-            }
-
-            // Append messages for invalid calls so the LLM sees the errors
-            for (const msg of invalidMessages) {
-              messages.push({ role: 'tool', content: msg });
-            }
-
-            consecutiveInvalid = invalidMessages.length > 0 && validCalls.length === 0
-              ? consecutiveInvalid + 1
-              : 0;
-
-            if (consecutiveInvalid >= maxConsecutiveInvalid) {
-              recordAgentError(runtime.telemetry);
-              const msg = `ERROR: ${maxConsecutiveInvalid} consecutive invalid actions. Stopping.`;
-              return { messages, output: msg, steps: step };
-            }
-
-            continue;
-          }
-
-          // Single tool call — record assistant message with structured toolCalls
-          const singleCallId = action.toolCallId ?? randomUUID();
-          messages.push({
-            role: 'assistant',
-            content: formatToolCallContent([action]),
-            toolCalls: [{
-              toolCallId: singleCallId,
-              toolName: action.name,
-              args: action.args,
-            }],
-          });
-
-          const validationError = validateToolAction(action);
-          if (validationError) {
-            consecutiveInvalid += 1;
-            if (consecutiveInvalid >= maxConsecutiveInvalid) {
-              recordAgentError(runtime.telemetry);
-              const msg = `ERROR: ${maxConsecutiveInvalid} consecutive invalid actions (last: ${validationError}). Stopping.`;
-              messages.push({ role: 'tool', content: `${action.name}: ${msg}` });
-              return { messages, output: msg, steps: step };
-            }
-          } else {
-            consecutiveInvalid = 0;
-          }
-          const result = validationError
-            ? ({ success: false, output: '', error: validationError } as ToolResult)
-            : await executor.run(async () => {
-                try {
-                  return await executeTool(runtime.toolProvider, action, runtime);
-                } catch (error) {
-                  return {
-                    success: false,
-                    output: '',
-                    error: error instanceof Error ? error.message : String(error)
-                  };
-                }
-              });
-          if (!result.success) {
-            recordAgentError(runtime.telemetry);
-          }
-          const singleResultText = result.success ? result.output : `ERROR: ${result.error ?? 'unknown failure'}`;
-          messages.push({
-            role: 'tool',
-            content: formatToolResultContent(action, result),
-            toolResults: [{
-              toolCallId: singleCallId,
-              toolName: action.name,
-              result: singleResultText,
-              isError: !result.success,
-            }],
-          });
-        }
-
-        recordAgentError(runtime.telemetry);
-        return {
-          messages,
-          output: 'ERROR: max steps exceeded',
-          steps: maxSteps
-        };
-      });
-    },
-
-    async *stream(prompt: string, options?: { history?: AgentMessage[] }): AsyncGenerator<AgentStreamEvent> {
-      const REPL_MARKER = '##REPL##\n';
-      const skillContext = await resolveSkillContext(prompt);
-      const effectivePrompt = skillContext
-        ? `${prompt}\n\nSkill guidance:\n${skillContext}`
-        : prompt;
-      const history = options?.history ?? [];
-      const messages: AgentMessage[] = [...history, { role: 'user', content: effectivePrompt }];
-      const maxSteps = runtime.maxSteps ?? 50;
-
-      for (let step = 1; step <= maxSteps; step++) {
-        yield { type: 'step_start', step };
-
-        if (loop.streamAction) {
-          // Streaming path: yield text deltas + collect tool calls
-          const pendingTools: ToolCallAction[] = [];
-          let finalText = '';
-          for await (const event of loop.streamAction(messages)) {
-            if (event.type === 'text_delta') {
-              finalText += event.text;
-              yield event;
-            }
-            if (event.type === 'tool_start') {
-              pendingTools.push({
-                type: 'tool',
-                name: event.name,
-                args: event.args,
-                ...(event.toolCallId != null ? { toolCallId: event.toolCallId } : {}),
-              });
-              yield event;
-            }
-          }
-
-          // If no tools → final response
-          if (pendingTools.length === 0) {
-            messages.push({ role: 'assistant', content: finalText });
-            yield { type: 'step_end', step };
-            yield { type: 'done', output: finalText, steps: step };
-            return;
-          }
-
-          // Record the assistant message with structured toolCalls
-          messages.push({
-            role: 'assistant',
-            content: finalText || formatToolCallContent(pendingTools),
-            toolCalls: pendingTools.map(t => ({
-              toolCallId: t.toolCallId ?? randomUUID(),
-              toolName: t.name,
-              args: t.args,
-            })),
-          });
-
-          // REPL fallback: if any Bash command starts with ##REPL##, fall back to
-          // non-streaming nextAction() which routes through LCMToolLoop REPL handling
-          const hasRepl = pendingTools.some(
-            t => t.name === 'Bash' && String(t.args.command ?? '').startsWith(REPL_MARKER)
-          );
-          if (hasRepl) {
-            const action = await loop.nextAction(messages);
-            if (action.type === 'final') {
-              yield { type: 'text_delta', text: action.content };
-              messages.push({ role: 'assistant', content: action.content });
-              yield { type: 'step_end', step };
-              yield { type: 'done', output: action.content, steps: step };
-              return;
-            }
-            // Non-final REPL result: execute tools and continue loop
-            if (action.type === 'tool_batch') {
-              for (const call of action.calls) {
-                const callId = call.toolCallId ?? randomUUID();
-                yield { type: 'tool_start', name: call.name, args: call.args, toolCallId: callId };
-                try {
-                  const r = await executeTool(runtime.toolProvider, call, runtime);
-                  yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-                  const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
-                  messages.push({
-                    role: 'tool',
-                    content: formatToolResultContent(call, r),
-                    toolResults: [{ toolCallId: callId, toolName: call.name, result: rText, isError: !r.success }],
-                  });
-                } catch (error) {
-                  const errMsg = error instanceof Error ? error.message : String(error);
-                  yield { type: 'tool_end', name: call.name, result: { success: false, output: '', error: errMsg } };
-                  messages.push({
-                    role: 'tool',
-                    content: `${call.name}: ERROR: ${errMsg}`,
-                    toolResults: [{ toolCallId: callId, toolName: call.name, result: errMsg, isError: true }],
-                  });
-                }
-              }
-            } else if (action.type === 'tool') {
-              const callId = action.toolCallId ?? randomUUID();
-              yield { type: 'tool_start', name: action.name, args: action.args, toolCallId: callId };
-              try {
-                const r = await executeTool(runtime.toolProvider, action, runtime);
-                yield { type: 'tool_end', name: action.name, result: toStreamResult(r) };
-                const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
-                messages.push({
-                  role: 'tool',
-                  content: formatToolResultContent(action, r),
-                  toolResults: [{ toolCallId: callId, toolName: action.name, result: rText, isError: !r.success }],
-                });
-              } catch (error) {
-                const errMsg = error instanceof Error ? error.message : String(error);
-                yield { type: 'tool_end', name: action.name, result: { success: false, output: '', error: errMsg } };
-                messages.push({
-                  role: 'tool',
-                  content: `${action.name}: ERROR: ${errMsg}`,
-                  toolResults: [{ toolCallId: callId, toolName: action.name, result: errMsg, isError: true }],
-                });
-              }
-            }
-            yield { type: 'step_end', step };
-            continue;
-          }
-
-          // Execute tools via batch (sequential sandbox ops) or parallel fallback
-          const results = await executeBatch(pendingTools, runtime.toolProvider, runtime);
-          for (let i = 0; i < pendingTools.length; i++) {
-            const call = pendingTools[i]!;
-            const r = results[i]!;
-            yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-            const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
-            messages.push({
-              role: 'tool',
-              content: formatToolResultContent(call, r),
-              toolResults: [{
-                toolCallId: call.toolCallId ?? '',
-                toolName: call.name,
-                result: rText,
-                isError: !r.success,
-              }],
-            });
-          }
-        } else {
-          // Fallback: wrap nextAction() in synthetic events
-          const action = await loop.nextAction(messages);
-
-          if (action.type === 'final') {
-            messages.push({ role: 'assistant', content: action.content });
-            yield { type: 'step_end', step };
-            yield { type: 'done', output: action.content, steps: step };
-            return;
-          }
-
-          const calls: ToolCallAction[] = action.type === 'tool_batch' ? action.calls : [action];
-          // Record assistant message with structured toolCalls
-          messages.push({
-            role: 'assistant',
-            content: formatToolCallContent(calls),
-            toolCalls: calls.map(c => ({
-              toolCallId: c.toolCallId ?? randomUUID(),
-              toolName: c.name,
-              args: c.args,
-            })),
-          });
-          for (const call of calls) {
-            yield { type: 'tool_start', name: call.name, args: call.args, ...(call.toolCallId != null ? { toolCallId: call.toolCallId } : {}) };
-          }
-          const results = await executeBatch(calls, runtime.toolProvider, runtime);
-          for (let i = 0; i < calls.length; i++) {
-            const call = calls[i]!;
-            const r = results[i]!;
-            yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-            const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
-            messages.push({
-              role: 'tool',
-              content: formatToolResultContent(call, r),
-              toolResults: [{
-                toolCallId: call.toolCallId ?? '',
-                toolName: call.name,
-                result: rText,
-                isError: !r.success,
-              }],
-            });
-          }
-        }
-
-        yield { type: 'step_end', step };
-      }
-
-      yield { type: 'done', output: 'ERROR: max steps exceeded', steps: maxSteps };
-    }
-  };
-}