@archal/cli 0.8.0 → 0.9.0

package/harnesses/react/agent.mjs

@@ -15,60 +15,20 @@
  *   ARCHAL_<TWIN>_URL    — twin REST base URL (per twin)
  *   ARCHAL_ENGINE_API_KEY / GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY
  */
-import { collectTwinUrls, discoverAllTools, callToolRest } from '../_lib/rest-client.mjs';
 import {
-  detectProvider,
-  resolveApiKey,
-  formatToolsForProvider,
-  buildInitialMessages,
-  appendAssistantResponse,
-  appendToolResults,
+  createHarnessContext,
+  runAgentLoop,
   appendUserInstruction,
-  callLlmWithMessages,
-  parseToolCalls,
-  getResponseText,
-  getThinkingContent,
-  getStopReason,
-  withRetry,
+} from '../_lib/harness-runner.mjs';
+import {
+  appendToolResults,
 } from '../_lib/providers.mjs';
-import { createLogger } from '../_lib/logging.mjs';
-import { writeMetrics } from '../_lib/metrics.mjs';
-import { createAgentTrace } from '../_lib/agent-trace.mjs';
+import { parseEnvInt } from '../_lib/env-utils.mjs';
 import { classifyTask, selectStepTools } from './tool-selection.mjs';
 
-const DEFAULT_MAX_STEPS = 80;
-const MAX_STEPS = (() => {
-  const raw = process.env['ARCHAL_MAX_STEPS']?.trim();
-  if (!raw) return DEFAULT_MAX_STEPS;
-  const parsed = parseInt(raw, 10);
-  if (Number.isNaN(parsed) || parsed <= 0) return DEFAULT_MAX_STEPS;
-  return Math.min(parsed, 200);
-})();
-const MAX_CONSECUTIVE_ERRORS = (() => {
-  const raw = process.env['ARCHAL_MAX_CONSECUTIVE_ERRORS']?.trim();
-  if (!raw) return 8;
-  const parsed = parseInt(raw, 10);
-  if (Number.isNaN(parsed) || parsed <= 0) return 8;
-  return Math.min(parsed, 20);
-})();
-const MAX_INITIAL_NO_TOOL_RECOVERIES = (() => {
-  const raw = process.env['ARCHAL_MAX_INITIAL_NO_TOOL_RECOVERIES']?.trim();
-  if (!raw) return 2;
-  const parsed = parseInt(raw, 10);
-  if (Number.isNaN(parsed) || parsed <= 0) return 2;
-  return Math.min(parsed, 5);
-})();
-const TASK = (process.env['ARCHAL_ENGINE_TASK'] || '').trim();
-const MODEL = process.env['ARCHAL_ENGINE_MODEL'];
-const TASK_LOWER = TASK.toLowerCase();
-
-if (!TASK) { console.error('ARCHAL_ENGINE_TASK not set or empty'); process.exit(1); }
-if (!MODEL) { console.error('ARCHAL_ENGINE_MODEL not set'); process.exit(1); }
-
-const provider = detectProvider(MODEL);
-const apiKey = resolveApiKey(provider);
-const log = createLogger({ harness: 'react', model: MODEL, provider });
-const TASK_FLAGS = classifyTask(TASK);
+const MAX_STEPS = parseEnvInt('ARCHAL_MAX_STEPS', 80, { min: 1, max: 200 });
+const MAX_CONSECUTIVE_ERRORS = parseEnvInt('ARCHAL_MAX_CONSECUTIVE_ERRORS', 8, { min: 1, max: 20 });
+const MAX_INITIAL_NO_TOOL_RECOVERIES = parseEnvInt('ARCHAL_MAX_INITIAL_NO_TOOL_RECOVERIES', 2, { min: 1, max: 5 });
 
 const SYSTEM_PROMPT = `You are a capable AI agent performing a task using tools. Think step by step.
 
@@ -92,329 +52,182 @@ GUIDELINES:
 const MUTATING_TOOL_NAME = /(?:^|_)(create|update|add|post|reply|delete|close|merge|approve|archive|send)(?:_|$)/i;
 const REPO_CONTENT_MUTATION_TOOL = /(?:^|_)(create_or_update_file|delete_file|create_branch|create_commit)(?:_|$)/i;
 const CREATE_ISSUE_TOOL = /(?:^|_)create_issue(?:_|$)/i;
-const TASK_ALLOWS_REPO_CONTENT_MUTATION = /\b(file|files|code|commit|branch|pull request|pull requests|pr|readme|source|implementation|repository)\b/i.test(TASK_LOWER);
 
 function isMutatingToolName(toolName) {
   return MUTATING_TOOL_NAME.test(toolName);
 }
 
-function isRepoContentMutationTool(toolName) {
-  return REPO_CONTENT_MUTATION_TOOL.test(toolName);
-}
-
-function isCreateIssueTool(toolName) {
-  return CREATE_ISSUE_TOOL.test(toolName);
-}
-
-// ── Twin REST transport ─────────────────────────────────────────────
-const twinUrls = collectTwinUrls();
-const knownTwinNames = new Set(Object.keys(twinUrls));
-if (Object.keys(twinUrls).length === 0) {
-  console.error('[react] No twin URLs found. Check ARCHAL_TWIN_NAMES and ARCHAL_<TWIN>_URL env vars.');
-  process.exit(1);
-}
-const { tools: allTools, toolToTwin } = await discoverAllTools(twinUrls);
-if (allTools.length === 0) {
-  console.error('[react] No tools discovered from twins. Twin endpoints may be unreachable.');
-  process.exit(1);
-}
-
-let messages = buildInitialMessages(provider, SYSTEM_PROMPT, TASK, MODEL);
-if (TASK_FLAGS.isExistingIssueTriage) {
-  messages = appendUserInstruction(
-    provider,
-    messages,
-    'This task is issue triage on the existing repository issues. Update those issues in place. ' +
-      'Do not use comments, files, or duplicate issues as a substitute for labels. ' +
-      'If the task asks you to prioritize bug reports, every bug issue must also receive an appropriate priority label. ' +
-      'Use the repository priority labels exactly as named: priority:high, priority:medium, or priority:low.',
-  );
-}
-let consecutiveErrors = 0;
+const ctx = await createHarnessContext('react');
+const TASK_FLAGS = classifyTask(ctx.task);
+const TASK_LOWER = ctx.task.toLowerCase();
+const TASK_ALLOWS_REPO_CONTENT_MUTATION = /\b(file|files|code|commit|branch|pull request|pull requests|pr|readme|source|implementation|repository)\b/i.test(TASK_LOWER);
 
-const runStart = Date.now();
-let totalInputTokens = 0;
-let totalOutputTokens = 0;
-let totalToolCalls = 0;
-let totalToolErrors = 0;
-let stepsCompleted = 0;
-let exitReason = 'max_steps';
-let initialNoToolRecoveries = 0;
-let repoContentGuardRecoveries = 0;
-let pendingFollowupTwins = null;
+const knownTwinNames = new Set(Object.keys(ctx.twinUrls));
 const updatedTwins = new Set();
-const agentTrace = createAgentTrace();
-
-log.info('run_start', { task: TASK.slice(0, 200), maxSteps: MAX_STEPS });
-
-try {
-  for (let step = 0; step < MAX_STEPS; step++) {
-    stepsCompleted = step + 1;
-    const iterStart = Date.now();
-    const stepTools = selectStepTools(allTools, TASK_FLAGS, toolToTwin, pendingFollowupTwins);
-    const providerTools = formatToolsForProvider(provider, stepTools);
+let mutatedTwinsThisStep = new Set();
+let pendingFollowupTwins = null;
+let repoContentGuardRecoveries = 0;
 
-    // Call the LLM with retry on transient errors
-    log.llmCall(step + 1);
-    let response;
-    try {
-      response = await withRetry(
-        () => callLlmWithMessages(provider, MODEL, apiKey, messages, providerTools),
-        4,
+await runAgentLoop(ctx, {
+  systemPrompt: SYSTEM_PROMPT,
+  maxSteps: MAX_STEPS,
+  useRetry: true,
+  retryCount: 4,
+  useTrace: true,
+  maxConsecutiveErrors: MAX_CONSECUTIVE_ERRORS,
+  maxInitialNoToolRecoveries: MAX_INITIAL_NO_TOOL_RECOVERIES,
+
+  initMessages(provider, messages) {
+    if (TASK_FLAGS.isExistingIssueTriage) {
+      return appendUserInstruction(
+        provider,
+        messages,
+        'This task is issue triage on the existing repository issues. Update those issues in place. ' +
+          'Do not use comments, files, or duplicate issues as a substitute for labels. ' +
+          'If the task asks you to prioritize bug reports, every bug issue must also receive an appropriate priority label. ' +
+          'Use the repository priority labels exactly as named: priority:high, priority:medium, or priority:low.',
       );
-    } catch (err) {
-      const msg = err?.message ?? String(err);
-      log.error('llm_call_failed', { step: step + 1, error: msg });
-      process.stderr.write(`[react] LLM API error: ${msg.slice(0, 500)}\n`);
-      exitReason = 'llm_error';
-      break;
     }
+    return messages;
+  },
 
-    const iterDurationMs = Date.now() - iterStart;
-    totalInputTokens += response.usage.inputTokens;
-    totalOutputTokens += response.usage.outputTokens;
-
-    const hasToolCalls = !!parseToolCalls(provider, response);
-    const stopReason = getStopReason(provider, response);
-    log.llmResponse(step + 1, iterDurationMs, hasToolCalls, stopReason);
-    log.tokenUsage(step + 1, response.usage, {
-      inputTokens: totalInputTokens,
-      outputTokens: totalOutputTokens,
-    });
+  selectTools(_ctx, _state) {
+    return selectStepTools(ctx.allTools, TASK_FLAGS, ctx.toolToTwin, pendingFollowupTwins);
+  },
 
-    // Extract thinking/reasoning before appending (so we capture it before it's lost)
-    const thinking = getThinkingContent(provider, response);
-    const text = getResponseText(provider, response);
+  onBeforeToolExecution(_ctx, state, stepResult) {
+    const { toolCalls, thinking, text, iterDurationMs, step } = stepResult;
 
-    // Append assistant response to conversation
-    messages = appendAssistantResponse(provider, messages, response);
-
-    // Check for tool calls
-    const toolCalls = parseToolCalls(provider, response);
-
-    if (!toolCalls) {
-      // No tool calls — model is done or just providing text
-      agentTrace.addStep({ step: step + 1, thinking, text, toolCalls: [], durationMs: iterDurationMs });
-      if (text) {
-        process.stderr.write(`[react] Step ${step + 1}: ${text.slice(0, 200)}\n`);
-      }
-      const shouldRecoverInitialNoToolCall = totalToolCalls === 0
-        && initialNoToolRecoveries < MAX_INITIAL_NO_TOOL_RECOVERIES;
-      if (shouldRecoverInitialNoToolCall) {
-        initialNoToolRecoveries++;
-        messages = appendUserInstruction(
-          provider,
-          messages,
-          'You must use tools to make progress. ' +
-            'On your next response, call at least one relevant tool before giving any summary or conclusion. ' +
-            'Start by gathering concrete evidence from the systems, then execute the required actions.',
-        );
-        log.info('no_tool_calls_reprompt', {
-          step: step + 1,
-          attempt: initialNoToolRecoveries,
-        });
-        continue;
-      }
-      if (pendingFollowupTwins && pendingFollowupTwins.size > 0) {
-        const remainingTwins = [...pendingFollowupTwins].join(', ');
-        messages = appendUserInstruction(
-          provider,
-          messages,
-          `You have not finished the required follow-up in ${remainingTwins}. ` +
-            'Continue using the remaining system tools until those actions are complete before you conclude.',
-        );
-        log.info('cross_system_followup_reprompt', {
-          step: step + 1,
-          remainingTwins,
-        });
-        continue;
-      }
-      // If the model still avoids tools, we're done.
-      // Distinguish genuine startup no-tool failures from normal completion
-      // after the agent already used tools in earlier turns.
-      exitReason = totalToolCalls === 0 ? 'no_tool_calls' : 'completed';
-      break;
-    }
-    initialNoToolRecoveries = 0;
-
-    const proposedRepoContentMutation = toolCalls.some((tc) => isRepoContentMutationTool(tc.name));
+    // Block repo content mutations when the task doesn't warrant them
+    const proposedRepoContentMutation = toolCalls.some((tc) => REPO_CONTENT_MUTATION_TOOL.test(tc.name));
     if (proposedRepoContentMutation && (!TASK_ALLOWS_REPO_CONTENT_MUTATION || TASK_FLAGS.isExistingIssueTriage) && repoContentGuardRecoveries < 2) {
       repoContentGuardRecoveries++;
-      agentTrace.addStep({
-        step: step + 1,
-        thinking,
-        text,
-        toolCalls: toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })),
-        durationMs: iterDurationMs,
-      });
-      messages = appendToolResults(
-        provider,
-        messages,
+      if (state.agentTrace) {
+        state.agentTrace.addStep({
+          step,
+          thinking,
+          text,
+          toolCalls: toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })),
+          durationMs: iterDurationMs,
+        });
+      }
+      state.messages = appendToolResults(
+        ctx.provider,
+        state.messages,
         toolCalls,
         toolCalls.map(() =>
           'Blocked by harness: this task must update the existing issue or message state directly, not repository files or commits.',
         ),
       );
-      messages = appendUserInstruction(
-        provider,
-        messages,
+      state.messages = appendUserInstruction(
+        ctx.provider,
+        state.messages,
         'This task is about updating existing issues/messages, not repository content. ' +
           'Do not create or edit files or commits as a substitute for labels, issue state changes, or replies. ' +
           'Use the issue or messaging mutation tools directly.',
       );
-      log.info('repo_content_mutation_blocked', {
-        step: step + 1,
+      ctx.log.info('repo_content_mutation_blocked', {
+        step,
         attemptedTools: toolCalls.map((tc) => tc.name),
       });
-      continue;
+      return 'continue';
     }
-    if (TASK_FLAGS.isExistingIssueTriage && toolCalls.some((tc) => isCreateIssueTool(tc.name)) && repoContentGuardRecoveries < 2) {
+
+    // Block issue creation during triage tasks
+    if (TASK_FLAGS.isExistingIssueTriage && toolCalls.some((tc) => CREATE_ISSUE_TOOL.test(tc.name)) && repoContentGuardRecoveries < 2) {
       repoContentGuardRecoveries++;
-      agentTrace.addStep({
-        step: step + 1,
-        thinking,
-        text,
-        toolCalls: toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })),
-        durationMs: iterDurationMs,
-      });
-      messages = appendToolResults(
-        provider,
-        messages,
+      if (state.agentTrace) {
+        state.agentTrace.addStep({
+          step,
+          thinking,
+          text,
+          toolCalls: toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })),
+          durationMs: iterDurationMs,
+        });
+      }
+      state.messages = appendToolResults(
+        ctx.provider,
+        state.messages,
         toolCalls,
         toolCalls.map(() =>
           'Blocked by harness: this task is to triage the existing issues in the repository, not create duplicate issues.',
         ),
       );
-      messages = appendUserInstruction(
-        provider,
-        messages,
+      state.messages = appendUserInstruction(
+        ctx.provider,
+        state.messages,
         'This task is to triage the existing issues that are already in the repository. ' +
           'Do not create duplicate issues. Inspect the current issues and use the issue update tools to apply category labels and priority labels directly to those existing issues.',
       );
-      log.info('issue_creation_blocked_for_triage', {
-        step: step + 1,
+      ctx.log.info('issue_creation_blocked_for_triage', {
+        step,
         attemptedTools: toolCalls.map((tc) => tc.name),
       });
-      continue;
+      return 'continue';
     }
     // NOTE: Do NOT reset repoContentGuardRecoveries here. The counter must
     // persist across the entire run so alternating clean/blocked steps cannot
     // bypass the 2-attempt safety limit indefinitely.
-
-    // Execute each tool call via REST
-    const results = [];
-    const mutatedTwinsThisStep = new Set();
-    for (const tc of toolCalls) {
-      const toolStart = Date.now();
-      process.stderr.write(`[react] Step ${step + 1}: ${tc.name}(${JSON.stringify(tc.arguments).slice(0, 100)})\n`);
-      try {
-        const result = await callToolRest(toolToTwin, tc.name, tc.arguments);
-        results.push(result);
-        consecutiveErrors = 0;
-        totalToolCalls++;
-        if (isMutatingToolName(tc.name)) {
-          const twinName = toolToTwin[tc.name]?.twinName;
-          if (twinName) {
-            updatedTwins.add(twinName);
-            mutatedTwinsThisStep.add(twinName);
-          }
-        }
-        log.toolCall(step + 1, tc.name, tc.arguments, Date.now() - toolStart);
-      } catch (err) {
-        const errorMsg = `Error: ${err.message}`;
-        results.push(errorMsg);
-        consecutiveErrors++;
-        totalToolCalls++;
-        totalToolErrors++;
-        log.toolError(step + 1, tc.name, err.message);
-        process.stderr.write(`[react] Tool error (${consecutiveErrors}): ${err.message}\n`);
-
-        // Bail if too many consecutive errors
-        if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
-          process.stderr.write('[react] Too many consecutive tool errors — stopping.\n');
-          exitReason = 'consecutive_errors';
-          break;
-        }
+  },
+
+  onToolSuccess(tc) {
+    if (isMutatingToolName(tc.name)) {
+      const twinName = ctx.toolToTwin[tc.name]?.twinName;
+      if (twinName) {
+        updatedTwins.add(twinName);
+        mutatedTwinsThisStep.add(twinName);
       }
     }
+  },
 
-    // Record thinking trace for this step (before bailout check so the final step is captured)
-    agentTrace.addStep({
-      step: step + 1,
-      thinking,
-      text,
-      toolCalls: toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })),
-      durationMs: iterDurationMs,
-    });
-
-    if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) break;
-
-    // Append tool results to conversation
-    messages = appendToolResults(provider, messages, toolCalls, results);
+  onAfterToolExecution(_ctx, state, stepResult) {
+    const { step } = stepResult;
+    // Capture and reset per-step tracking (populated by onToolSuccess)
+    const stepMutations = mutatedTwinsThisStep;
+    mutatedTwinsThisStep = new Set();
 
+    // Clear pending followup if a pending twin was mutated
     if (pendingFollowupTwins && pendingFollowupTwins.size > 0) {
-      const completedFollowups = [...mutatedTwinsThisStep].filter((twin) => pendingFollowupTwins.has(twin));
+      const completedFollowups = [...stepMutations].filter((twin) => pendingFollowupTwins.has(twin));
       if (completedFollowups.length > 0) {
         pendingFollowupTwins = null;
       }
     }
 
-    // Only trigger cross-system followup when the task actually involves
-    // multiple distinct services. Without this gate, single-system tasks
-    // running in a multi-twin configuration would incorrectly nag the
-    // agent to act in twins the task never mentions.
-    if (TASK_FLAGS.requiresCrossSystemFollowup && !pendingFollowupTwins && knownTwinNames.size > 1 && mutatedTwinsThisStep.size > 0) {
+    // Trigger cross-system followup when the task spans multiple services
+    if (TASK_FLAGS.requiresCrossSystemFollowup && !pendingFollowupTwins && knownTwinNames.size > 1 && stepMutations.size > 0) {
       const untouchedTwins = [...knownTwinNames].filter((twinName) => !updatedTwins.has(twinName));
       if (untouchedTwins.length > 0) {
         pendingFollowupTwins = new Set(untouchedTwins);
-        messages = appendUserInstruction(
-          provider,
-          messages,
+        state.messages = appendUserInstruction(
+          ctx.provider,
+          state.messages,
           `You have updated ${[...updatedTwins].join(', ')} but not ${untouchedTwins.join(', ')}. ` +
             'Continue and finish the remaining required actions in the untouched system before you conclude.',
         );
-        log.info('cross_system_followup_required', {
-          step: step + 1,
+        ctx.log.info('cross_system_followup_required', {
+          step,
           updatedTwins: [...updatedTwins],
           remainingTwins: untouchedTwins,
         });
       }
     }
-  }
-} finally {
-  const totalTimeMs = Date.now() - runStart;
-
-  log.summary({
-    iterations: stepsCompleted,
-    totalInputTokens,
-    totalOutputTokens,
-    totalTimeMs,
-    toolCallCount: totalToolCalls,
-    toolErrorCount: totalToolErrors,
-    exitReason,
-  });
-
-  writeMetrics({
-    inputTokens: totalInputTokens,
-    outputTokens: totalOutputTokens,
-    llmCallCount: stepsCompleted,
-    toolCallCount: totalToolCalls,
-    toolErrorCount: totalToolErrors,
-    totalTimeMs,
-    exitReason,
-    provider,
-    model: MODEL,
-  });
+  },
 
-  agentTrace.flush();
-
-  process.stderr.write(
-    `\n[react] Summary: ${stepsCompleted} iterations, ${totalToolCalls} tool calls ` +
-    `(${totalToolErrors} errors), ${totalInputTokens} input tokens, ` +
-    `${totalOutputTokens} output tokens, ${(totalTimeMs / 1000).toFixed(1)}s total\n`
-  );
-
-  if (exitReason === 'llm_error') {
-    process.exit(1);
-  }
-}
+  onNoToolCalls(_ctx, state, stepResult) {
+    if (pendingFollowupTwins && pendingFollowupTwins.size > 0) {
+      const remainingTwins = [...pendingFollowupTwins].join(', ');
+      state.messages = appendUserInstruction(
+        ctx.provider,
+        state.messages,
+        `You have not finished the required follow-up in ${remainingTwins}. ` +
+          'Continue using the remaining system tools until those actions are complete before you conclude.',
+      );
+      ctx.log.info('cross_system_followup_reprompt', {
+        step: stepResult.step,
+        remainingTwins,
+      });
+      return 'continue';
+    }
+  },
+});