@archal/cli 0.7.12 → 0.9.0

package/dist/twin-assets/supabase/seeds/small-project.sql

@@ -0,0 +1,134 @@
+-- Small project seed: a typical blog application
+-- Creates users, posts, comments, tags tables with realistic data
+
+CREATE TABLE users (
+  id serial PRIMARY KEY,
+  email text NOT NULL UNIQUE,
+  name text NOT NULL,
+  role text NOT NULL DEFAULT 'member',
+  bio text,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE posts (
+  id serial PRIMARY KEY,
+  user_id int NOT NULL REFERENCES users(id),
+  title text NOT NULL,
+  body text,
+  published boolean NOT NULL DEFAULT false,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE comments (
+  id serial PRIMARY KEY,
+  post_id int NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  user_id int NOT NULL REFERENCES users(id),
+  body text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE tags (
+  id serial PRIMARY KEY,
+  name text NOT NULL UNIQUE
+);
+
+CREATE TABLE post_tags (
+  post_id int NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  tag_id int NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+  PRIMARY KEY (post_id, tag_id)
+);
+
+CREATE INDEX idx_posts_user_id ON posts(user_id);
+CREATE INDEX idx_comments_post_id ON comments(post_id);
+CREATE INDEX idx_comments_user_id ON comments(user_id);
+
+-- Seed users
+INSERT INTO users (email, name, role, bio) VALUES
+  ('alice@example.com', 'Alice Chen', 'admin', 'Full-stack engineer and tech lead'),
+  ('bob@example.com', 'Bob Smith', 'member', 'Backend developer'),
+  ('carol@example.com', 'Carol Davis', 'member', 'Frontend specialist'),
+  ('dave@example.com', 'Dave Wilson', 'member', NULL),
+  ('eve@example.com', 'Eve Martinez', 'moderator', 'DevOps and infrastructure');
+
+-- Seed posts
+INSERT INTO posts (user_id, title, body, published) VALUES
+  (1, 'Getting Started with Supabase', 'Supabase is an open source Firebase alternative. This guide walks through setting up your first project.', true),
+  (1, 'Advanced SQL Patterns', 'Common table expressions, window functions, and recursive queries explained.', true),
+  (2, 'Building REST APIs', 'A practical guide to designing and implementing RESTful services.', true),
+  (2, 'Database Indexing Strategies', 'When and how to add indexes for optimal query performance.', true),
+  (3, 'Modern CSS Techniques', 'Container queries, cascade layers, and other modern CSS features.', true),
+  (3, 'React Server Components', 'Understanding the new paradigm for server-rendered React applications.', true),
+  (1, 'Draft: Postgres Extensions', 'Notes on useful Postgres extensions for production use.', false),
+  (4, 'My First Post', 'Hello world! Just getting started here.', true),
+  (5, 'Infrastructure as Code', 'Managing cloud resources with Terraform and Pulumi.', true),
+  (5, 'Monitoring Best Practices', 'Setting up observability for production applications.', true),
+  (2, 'GraphQL vs REST', 'Comparing two popular API paradigms for modern applications.', true),
+  (3, 'Accessibility in Web Apps', 'Essential patterns for building inclusive web applications.', true),
+  (1, 'Draft: Testing Strategies', 'Unit tests, integration tests, and end-to-end testing approaches.', false),
+  (4, 'Learning TypeScript', 'Tips and resources for getting started with TypeScript.', true),
+  (5, 'Docker Fundamentals', 'Container basics for developers new to Docker.', true);
+
+-- Seed tags
+INSERT INTO tags (name) VALUES
+  ('tutorial'),
+  ('database'),
+  ('frontend'),
+  ('backend'),
+  ('devops'),
+  ('typescript'),
+  ('react');
+
+-- Seed post_tags
+INSERT INTO post_tags (post_id, tag_id) VALUES
+  (1, 1), (1, 2),
+  (2, 2),
+  (3, 1), (3, 4),
+  (4, 2),
+  (5, 3),
+  (6, 3), (6, 7),
+  (8, 1),
+  (9, 5),
+  (10, 5),
+  (11, 4),
+  (12, 3),
+  (14, 6),
+  (15, 5);
+
+-- Seed comments
+INSERT INTO comments (post_id, user_id, body) VALUES
+  (1, 2, 'Great introduction! Very helpful for beginners.'),
+  (1, 3, 'Would love to see a follow-up on authentication.'),
+  (1, 4, 'Thanks for sharing this.'),
+  (2, 5, 'The CTE examples are really clear.'),
+  (2, 3, 'Window functions finally make sense!'),
+  (3, 1, 'Nice breakdown of REST principles.'),
+  (3, 4, 'How does this compare to GraphQL?'),
+  (3, 5, 'The versioning section was particularly useful.'),
+  (4, 1, 'Good timing - we just hit performance issues with missing indexes.'),
+  (4, 3, 'Partial indexes are underrated.'),
+  (5, 2, 'Container queries are a game changer.'),
+  (5, 4, 'Finally catching up on modern CSS. Thanks!'),
+  (6, 1, 'RSC is going to change how we build apps.'),
+  (6, 2, 'Still trying to wrap my head around the mental model.'),
+  (6, 5, 'Any performance benchmarks?'),
+  (8, 1, 'Welcome aboard!'),
+  (8, 3, 'Good to have you here.'),
+  (9, 2, 'Terraform has been rock solid for our team.'),
+  (9, 1, 'Great comparison of Terraform vs Pulumi.'),
+  (10, 3, 'What monitoring stack do you recommend?'),
+  (10, 4, 'We use Grafana + Prometheus and it works well.'),
+  (11, 5, 'We ended up going with REST for our use case.'),
+  (11, 1, 'Both have their place depending on the requirements.'),
+  (12, 2, 'Accessibility should be the default, not an afterthought.'),
+  (12, 5, 'The ARIA examples are very practical.'),
+  (14, 1, 'TypeScript is worth the learning curve.'),
+  (14, 3, 'The type system is incredibly powerful once you get used to it.'),
+  (15, 1, 'Docker compose makes local development so much easier.'),
+  (15, 2, 'Multi-stage builds are essential for production images.'),
+  (15, 4, 'Great starting point for Docker beginners.');
+
+-- Record migrations
+INSERT INTO supabase_migrations.schema_migrations (version, name, statements) VALUES
+  ('20250101000000_init', 'create_initial_schema', 'CREATE TABLE users (...); CREATE TABLE posts (...); CREATE TABLE comments (...); CREATE TABLE tags (...); CREATE TABLE post_tags (...);'),
+  ('20250101000001_indexes', 'add_indexes', 'CREATE INDEX idx_posts_user_id ON posts(user_id); CREATE INDEX idx_comments_post_id ON comments(post_id); CREATE INDEX idx_comments_user_id ON comments(user_id);');

package/dist/twin-assets/telegram/fidelity.json

@@ -0,0 +1,19 @@
+{
+  "twin": "telegram",
+  "api": "telegram-bot-api",
+  "version": "0.1.0",
+  "capabilities": [
+    {
+      "name": "getMe (approved cold-start tool)",
+      "supported": true
+    },
+    {
+      "name": "getUpdates (approved cold-start tool)",
+      "supported": true
+    },
+    {
+      "name": "sendMessage (approved cold-start tool)",
+      "supported": true
+    }
+  ]
+}

package/dist/twin-assets/telegram/seeds/empty.json

@@ -0,0 +1 @@
+{}

package/dist/twin-assets/telegram/seeds/harvested.json

@@ -0,0 +1,130 @@
+{
+  "botProfiles": [
+    {
+      "id": 1,
+      "createdAt": "2026-03-14T04:55:49.843Z",
+      "updatedAt": "2026-03-14T04:55:49.843Z",
+      "payload": {
+        "id": 8620849624,
+        "is_bot": true,
+        "first_name": "twingen",
+        "username": "twingen_bot",
+        "can_join_groups": true,
+        "can_read_all_group_messages": false,
+        "supports_inline_queries": false,
+        "can_connect_to_business": false,
+        "has_main_web_app": false,
+        "has_topics_enabled": false,
+        "allows_users_to_create_topics": false
+      },
+      "telegramUserId": 8620849624
+    }
+  ],
+  "users": [
+    {
+      "id": 1,
+      "createdAt": "2026-03-14T04:55:49.843Z",
+      "updatedAt": "2026-03-14T04:55:49.843Z",
+      "payload": {
+        "id": 8620849624,
+        "is_bot": true,
+        "first_name": "twingen",
+        "username": "twingen_bot",
+        "can_join_groups": true,
+        "can_read_all_group_messages": false,
+        "supports_inline_queries": false,
+        "can_connect_to_business": false,
+        "has_main_web_app": false,
+        "has_topics_enabled": false,
+        "allows_users_to_create_topics": false
+      },
+      "telegramUserId": 8620849624
+    },
+    {
+      "id": 2,
+      "createdAt": "2026-03-14T04:55:49.843Z",
+      "updatedAt": "2026-03-14T04:55:49.843Z",
+      "payload": {
+        "id": 999000001,
+        "is_bot": false,
+        "first_name": "Test",
+        "last_name": "User",
+        "language_code": "en"
+      },
+      "telegramUserId": 999000001
+    }
+  ],
+  "chats": [
+    {
+      "id": 1,
+      "createdAt": "2026-03-14T04:55:49.843Z",
+      "updatedAt": "2026-03-14T04:55:49.843Z",
+      "payload": {
+        "id": 999000001,
+        "first_name": "Test",
+        "last_name": "User",
+        "type": "private"
+      },
+      "telegramChatId": 999000001
+    }
+  ],
+  "messages": [
+    {
+      "id": 1,
+      "createdAt": "2026-03-14T04:55:49.843Z",
+      "updatedAt": "2026-03-14T04:55:49.843Z",
+      "payload": {
+        "message_id": 111,
+        "from": {
+          "id": 8620849624,
+          "is_bot": true,
+          "first_name": "twingen",
+          "username": "twingen_bot"
+        },
+        "chat": {
+          "id": 999000001,
+          "first_name": "Test",
+          "last_name": "User",
+          "type": "private"
+        },
+        "date": 1773464149,
+        "text": "archal telegram fixture harvest 2026-03-14T04:55:49.194Z"
+      },
+      "telegramMessageId": 111,
+      "chatId": 999000001,
+      "fromTelegramUserId": 8620849624,
+      "date": 1773464149,
+      "text": "archal telegram fixture harvest 2026-03-14T04:55:49.194Z"
+    }
+  ],
+  "updates": [
+    {
+      "id": 1,
+      "createdAt": "2026-03-14T04:55:49.843Z",
+      "updatedAt": "2026-03-14T04:55:49.843Z",
+      "payload": {
+        "update_id": 707484527,
+        "message": {
+          "message_id": 103,
+          "from": {
+            "id": 999000001,
+            "is_bot": false,
+            "first_name": "Test",
+            "last_name": "User",
+            "language_code": "en"
+          },
+          "chat": {
+            "id": 999000001,
+            "first_name": "Test",
+            "last_name": "User",
+            "type": "private"
+          },
+          "date": 1773461017,
+          "text": "message"
+        }
+      },
+      "telegramUpdateId": 707484527,
+      "kind": "message"
+    }
+  ]
+}

package/harnesses/_lib/env-utils.mjs

@@ -0,0 +1,23 @@
+/**
+ * Shared environment variable parsing utilities for bundled harnesses.
+ */
+
+/**
+ * Parse an integer from an environment variable with validation and clamping.
+ * Replaces the repeated IIFE pattern across agent files.
+ *
+ * @param {string} envVar - Environment variable name
+ * @param {number} defaultValue - Default if env var is not set or invalid
+ * @param {{ min?: number, max?: number }} [opts] - Optional min/max bounds
+ * @returns {number}
+ */
+export function parseEnvInt(envVar, defaultValue, { min, max } = {}) {
+  const raw = process.env[envVar]?.trim();
+  if (!raw) return defaultValue;
+  const parsed = parseInt(raw, 10);
+  if (Number.isNaN(parsed)) return defaultValue;
+  let value = parsed;
+  if (min !== undefined && value < min) value = min;
+  if (max !== undefined && value > max) value = max;
+  return value;
+}

package/harnesses/_lib/harness-runner.mjs

@@ -0,0 +1,354 @@
+/**
+ * Shared harness scaffolding for bundled agent files.
+ *
+ * Extracts the common init sequence and run-loop structure that all 4
+ * bundled harnesses (naive, zero-shot, hardened, react) duplicate.
+ *
+ * Usage:
+ *   const ctx = await createHarnessContext('react');
+ *   await runAgentLoop(ctx, { ... });
+ */
+import { collectTwinUrls, discoverAllTools } from './rest-client.mjs';
+import {
+  detectProvider,
+  resolveApiKey,
+  formatToolsForProvider,
+  buildInitialMessages,
+  appendAssistantResponse,
+  appendToolResults,
+  appendUserInstruction,
+  callLlmWithMessages,
+  parseToolCalls,
+  getResponseText,
+  getThinkingContent,
+  getStopReason,
+  withRetry,
+} from './providers.mjs';
+import { createLogger } from './logging.mjs';
+import { writeMetrics } from './metrics.mjs';
+import { createAgentTrace } from './agent-trace.mjs';
+
+// ── Context creation ──────────────────────────────────────────────────
+
+/**
+ * @typedef {object} HarnessContext
+ * @property {string} harnessName
+ * @property {string} task
+ * @property {string} model
+ * @property {string} provider
+ * @property {string} apiKey
+ * @property {import('./logging.mjs').Logger} log
+ * @property {Record<string, string>} twinUrls
+ * @property {Array<{ name: string, description: string, inputSchema: object }>} allTools
+ * @property {Record<string, { twinName: string, baseUrl: string, originalName: string }>} toolToTwin
+ */
+
+/**
+ * Create the full harness context: validate env vars, detect provider,
+ * resolve API key, collect twin URLs, and discover tools.
+ *
+ * Exits with code 1 on missing env vars or unreachable twins.
+ *
+ * @param {string} harnessName
+ * @returns {Promise<HarnessContext>}
+ */
+export async function createHarnessContext(harnessName) {
+  const task = (process.env['ARCHAL_ENGINE_TASK'] || '').trim();
+  const model = process.env['ARCHAL_ENGINE_MODEL'];
+
+  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: harnessName, model, provider });
+
+  const twinUrls = collectTwinUrls();
+  if (Object.keys(twinUrls).length === 0) {
+    console.error(`[${harnessName}] 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(`[${harnessName}] No tools discovered from twins. Twin endpoints may be unreachable.`);
+    process.exit(1);
+  }
+
+  return { harnessName, task, model, provider, apiKey, log, twinUrls, allTools, toolToTwin };
+}
+
+// ── Run loop ──────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} RunLoopOptions
+ * @property {string} systemPrompt - System prompt text (empty string for none)
+ * @property {number} maxSteps - Maximum iteration count
+ * @property {boolean} [useRetry=false] - Wrap LLM calls in withRetry
+ * @property {number} [retryCount=4] - Max retries when useRetry is true
+ * @property {boolean} [useTrace=false] - Record agent trace
+ * @property {number} [maxConsecutiveErrors=0] - Bail threshold (0 = no limit)
+ * @property {number} [maxInitialNoToolRecoveries=0] - Reprompt attempts when model doesn't call tools initially
+ * @property {(ctx: HarnessContext, state: RunState) => Array} [selectTools] -
+ *   Per-step tool selection function. Receives context and current state,
+ *   returns the MCP tools array for this step. Default: use all tools.
+ * @property {(ctx: HarnessContext, state: RunState, stepResult: StepResult) => 'continue' | 'break' | void} [onBeforeToolExecution] -
+ *   Hook called after parsing tool calls but before executing them.
+ *   Return 'continue' to skip tool execution and loop, 'break' to stop.
+ * @property {(provider: string, messages: Array|object) => Array|object} [initMessages] -
+ *   Optional post-init hook to modify the initial messages array before the
+ *   run loop starts (e.g. to prepend a triage instruction).
+ * @property {(ctx: HarnessContext, state: RunState, stepResult: StepResult) => void} [onAfterToolExecution] -
+ *   Hook called after tool results are appended. Return value is ignored.
+ * @property {(ctx: HarnessContext, state: RunState, stepResult: StepResult) => 'continue' | void} [onNoToolCalls] -
+ *   Hook called when the model responds without tool calls. Return
+ *   'continue' to add instructions and continue the loop.
+ * @property {(tc: { name: string, arguments: object }) => void} [onToolSuccess] -
+ *   Called after each successful tool call.
+ */
+
+/**
+ * @typedef {object} RunState
+ * Mutable state tracked across loop iterations.
+ * @property {Array|object} messages
+ * @property {number} stepsCompleted
+ * @property {number} totalInputTokens
+ * @property {number} totalOutputTokens
+ * @property {number} totalToolCalls
+ * @property {number} totalToolErrors
+ * @property {number} consecutiveErrors
+ * @property {number} initialNoToolRecoveries
+ * @property {string} exitReason
+ * @property {import('./agent-trace.mjs').ReturnType<typeof createAgentTrace>|null} agentTrace
+ */
+
+/**
+ * @typedef {object} StepResult
+ * @property {number} step - 1-indexed step number
+ * @property {object} response - Raw LLM response wrapper
+ * @property {Array|null} toolCalls - Parsed tool calls or null
+ * @property {string|null} thinking - Model thinking content
+ * @property {string|null} text - Model text content
+ * @property {number} iterDurationMs
+ * @property {string|null} stopReason
+ */
+
+/**
+ * Run the agent loop with shared metrics, logging, and tool execution.
+ *
+ * @param {HarnessContext} ctx
+ * @param {RunLoopOptions} opts
+ */
+export async function runAgentLoop(ctx, opts) {
+  const {
+    systemPrompt,
+    maxSteps,
+    useRetry = false,
+    retryCount = 4,
+    useTrace = false,
+    maxConsecutiveErrors = 0,
+    maxInitialNoToolRecoveries = 0,
+    selectTools,
+    onBeforeToolExecution,
+    onAfterToolExecution,
+    onNoToolCalls,
+    onToolSuccess,
+  } = opts;
+
+  const { harnessName, task, model, provider, apiKey, log, allTools, toolToTwin } = ctx;
+
+  let messages = buildInitialMessages(provider, systemPrompt, task, model);
+
+  // Allow callers to modify initial messages (e.g. react's triage instruction)
+  if (opts.initMessages) {
+    messages = opts.initMessages(provider, messages);
+  }
+
+  const state = {
+    messages,
+    stepsCompleted: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalToolCalls: 0,
+    totalToolErrors: 0,
+    consecutiveErrors: 0,
+    initialNoToolRecoveries: 0,
+    exitReason: 'max_steps',
+    agentTrace: useTrace ? createAgentTrace() : null,
+  };
+
+  const runStart = Date.now();
+
+  log.info('run_start', { task: task.slice(0, 200), maxSteps });
+
+  try {
+    for (let step = 0; step < maxSteps; step++) {
+      state.stepsCompleted = step + 1;
+      const iterStart = Date.now();
+
+      // Select tools for this step (default: all tools)
+      const stepTools = selectTools ? selectTools(ctx, state) : allTools;
+      const providerTools = formatToolsForProvider(provider, stepTools);
+
+      // Call the LLM (optionally with retry)
+      log.llmCall(step + 1);
+      let response;
+      try {
+        const llmCall = () => callLlmWithMessages(provider, model, apiKey, state.messages, providerTools);
+        response = useRetry ? await withRetry(llmCall, retryCount) : await llmCall();
+      } catch (err) {
+        const msg = err?.message ?? String(err);
+        log.error('llm_call_failed', { step: step + 1, error: msg });
+        process.stderr.write(`[${harnessName}] LLM API error: ${msg.slice(0, 500)}\n`);
+        state.exitReason = 'llm_error';
+        break;
+      }
+
+      const iterDurationMs = Date.now() - iterStart;
+      state.totalInputTokens += response.usage.inputTokens;
+      state.totalOutputTokens += response.usage.outputTokens;
+
+      const toolCalls = parseToolCalls(provider, response);
+      const hasToolCalls = !!toolCalls;
+      const stopReason = getStopReason(provider, response);
+      log.llmResponse(step + 1, iterDurationMs, hasToolCalls, stopReason);
+      log.tokenUsage(step + 1, response.usage, {
+        inputTokens: state.totalInputTokens,
+        outputTokens: state.totalOutputTokens,
+      });
+
+      const thinking = getThinkingContent(provider, response);
+      const text = getResponseText(provider, response);
+
+      state.messages = appendAssistantResponse(provider, state.messages, response);
+
+      /** @type {StepResult} */
+      const stepResult = { step: step + 1, response, toolCalls, thinking, text, iterDurationMs, stopReason };
+
+      if (!toolCalls) {
+        // Record trace for no-tool-call steps
+        if (state.agentTrace) {
+          state.agentTrace.addStep({ step: step + 1, thinking, text, toolCalls: [], durationMs: iterDurationMs });
+        }
+        if (text) {
+          process.stderr.write(`[${harnessName}] Step ${step + 1}: ${text.slice(0, 200)}\n`);
+        }
+
+        // Initial no-tool recovery (reprompt)
+        const shouldRecoverInitial = state.totalToolCalls === 0
+          && maxInitialNoToolRecoveries > 0
+          && state.initialNoToolRecoveries < maxInitialNoToolRecoveries;
+        if (shouldRecoverInitial) {
+          state.initialNoToolRecoveries++;
+          state.messages = appendUserInstruction(
+            provider,
+            state.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: state.initialNoToolRecoveries,
+          });
+          continue;
+        }
+
+        // Harness-specific no-tool-call handling
+        if (onNoToolCalls) {
+          const directive = onNoToolCalls(ctx, state, stepResult);
+          if (directive === 'continue') continue;
+        }
+
+        state.exitReason = state.totalToolCalls === 0 ? 'no_tool_calls' : 'completed';
+        break;
+      }
+
+      state.initialNoToolRecoveries = 0;
+
+      // Pre-execution hook (e.g. react's repo content guard)
+      if (onBeforeToolExecution) {
+        const directive = onBeforeToolExecution(ctx, state, stepResult);
+        if (directive === 'continue') continue;
+        if (directive === 'break') break;
+      }
+
+      // Execute tool calls
+      const { executeToolCalls } = await import('./tool-executor.mjs');
+      const { results, bailout } = await executeToolCalls(toolCalls, {
+        toolToTwin,
+        harnessName,
+        step: step + 1,
+        log,
+        counters: state,
+        maxConsecutiveErrors,
+        onSuccess: onToolSuccess,
+      });
+
+      // Record trace
+      if (state.agentTrace) {
+        state.agentTrace.addStep({
+          step: step + 1,
+          thinking,
+          text,
+          toolCalls: toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })),
+          durationMs: iterDurationMs,
+        });
+      }
+
+      if (bailout) {
+        state.exitReason = 'consecutive_errors';
+        break;
+      }
+
+      // Append tool results to conversation
+      state.messages = appendToolResults(provider, state.messages, toolCalls, results);
+
+      // Post-execution hook
+      if (onAfterToolExecution) {
+        onAfterToolExecution(ctx, state, stepResult);
+      }
+    }
+  } finally {
+    const totalTimeMs = Date.now() - runStart;
+
+    log.summary({
+      iterations: state.stepsCompleted,
+      totalInputTokens: state.totalInputTokens,
+      totalOutputTokens: state.totalOutputTokens,
+      totalTimeMs,
+      toolCallCount: state.totalToolCalls,
+      toolErrorCount: state.totalToolErrors,
+      exitReason: state.exitReason,
+    });
+
+    writeMetrics({
+      inputTokens: state.totalInputTokens,
+      outputTokens: state.totalOutputTokens,
+      llmCallCount: state.stepsCompleted,
+      toolCallCount: state.totalToolCalls,
+      toolErrorCount: state.totalToolErrors,
+      totalTimeMs,
+      exitReason: state.exitReason,
+      provider,
+      model,
+    });
+
+    if (state.agentTrace) {
+      state.agentTrace.flush();
+    }
+
+    process.stderr.write(
+      `\n[${harnessName}] Summary: ${state.stepsCompleted} iterations, ${state.totalToolCalls} tool calls ` +
+      `(${state.totalToolErrors} errors), ${state.totalInputTokens} input tokens, ` +
+      `${state.totalOutputTokens} output tokens, ${(totalTimeMs / 1000).toFixed(1)}s total\n`
+    );
+
+    if (state.exitReason === 'llm_error') {
+      process.exit(1);
+    }
+  }
+}
+
+// Re-export for convenience — harnesses that need to build custom initial messages
+export { appendUserInstruction };