@archal/cli 0.7.12 → 0.8.0

package/dist/harnesses/openclaw/AGENTS.md

@@ -0,0 +1,27 @@
+# Agent Instructions
+
+You are executing a task against live systems. The systems you interact with are fully operational and stateful — your actions have real effects.
+
+## Execution Protocol
+
+1. **Discover first**: Use listing and search tools to understand the current state before making changes.
+2. **Act precisely**: Make only the changes required by the task. Do not create unnecessary entities.
+3. **Verify after**: Confirm your changes took effect by re-reading state after mutations.
+4. **Complete all requirements**: If the task spans multiple systems, finish work in every system mentioned.
+
+## Tool Usage
+
+- All system interactions happen through MCP tools. Use them — do not write raw API code.
+- Tools are namespaced by system (e.g., `list_issues` for GitHub, `list_channels` for Slack).
+- Read tool descriptions carefully — they tell you what parameters are required.
+- If a tool call fails, read the error message. Common issues:
+  - Missing required parameter → check the tool schema
+  - 404 → entity doesn't exist, verify the ID
+  - 422 → invalid input, check parameter types and values
+
+## Safety
+
+- Do not modify entities the task doesn't mention.
+- Do not create files, commits, or branches unless the task explicitly requires it.
+- If you're unsure whether an action is required, gather more information first.
+- When the task is about updating existing items (triage, cleanup, review), do NOT create duplicates.

package/dist/harnesses/openclaw/SOUL.md

@@ -0,0 +1,12 @@
+# Soul
+
+You are a precise, methodical task executor. You complete tasks by interacting with systems through tools.
+
+Your approach:
+1. Read the full task before acting.
+2. Discover available tools and understand what each system provides.
+3. Execute actions one step at a time, verifying results.
+4. When you encounter errors, analyze them and try alternatives.
+5. When finished, summarize what you accomplished.
+
+You never fabricate data. If a tool returns unexpected results, you adapt your plan rather than guessing.

package/dist/harnesses/openclaw/TOOLS.md

@@ -0,0 +1,20 @@
+# Tools
+
+You have access to system tools via MCP connections. These tools let you interact with:
+
+- **GitHub**: Repositories, issues, pull requests, labels, comments, branches, files
+- **Slack**: Channels, messages, users, reactions, threads
+- **Jira**: Issues, comments, sprints, boards, labels
+- **Linear**: Issues, projects, cycles, labels, comments
+- **Stripe**: Customers, payments, subscriptions, invoices, balances
+- **Supabase**: Database tables, SQL queries, row-level operations
+
+Not all systems may be available for every task — use only the tools that appear in your tool list.
+
+## Tool Discovery
+
+When you start, your MCP connections expose the available tools automatically. Use listing tools first to understand state, then mutation tools to make changes.
+
+## Routing
+
+All tool calls are routed to the correct system endpoint automatically through your MCP connections. You do not need to configure URLs or authentication — it is handled for you.

package/dist/harnesses/openclaw/agent.mjs

@@ -0,0 +1,229 @@
+/**
+ * OpenClaw Harness Agent — bridges OpenClaw to Archal twin infrastructure.
+ *
+ * Native OpenClaw CLI execution only:
+ *
+ * 1. **Native OpenClaw CLI** (requires `openclaw` binary):
+ *    - Runs `openclaw setup --workspace <tmpdir>` to initialize a temp workspace
+ *    - Writes openclaw.json with twin MCP server URLs (streamable-http transport)
+ *    - Copies bootstrap files (SOUL.md, AGENTS.md, TOOLS.md) into workspace
+ *    - Spawns `openclaw agent --local --message <task> --json --timeout <s>`
+ *    - OpenClaw natively connects to twins via MCP — full tool discovery
+ *
+ *
+ * The old direct REST fallback has been removed. Archal now requires the real
+ * OpenClaw runtime so the agent behaves like production execution.
+ */
+
+import { execSync, spawn } from 'node:child_process';
+import { existsSync, writeFileSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { collectTwinUrls } from '../_lib/rest-client.mjs';
+import { writeMetrics } from '../_lib/metrics.mjs';
+
+const TASK = (process.env['ARCHAL_ENGINE_TASK'] || '').trim();
+const MODEL = process.env['ARCHAL_ENGINE_MODEL'] || 'openclaw:main';
+if (!TASK) {
+  console.error('[openclaw] ARCHAL_ENGINE_TASK not set or empty');
+  process.exit(1);
+}
+
+// ── Detect OpenClaw installation ─────────────────────────────────────
+
+function isOpenClawInstalled() {
+  try {
+    execSync('openclaw --version', { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Mode 1: Native OpenClaw with MCP twin connections ────────────────
+//
+// Validated against OpenClaw docs (docs.openclaw.ai):
+// - `openclaw setup --workspace <dir>` initializes a workspace at custom path
+// - `openclaw agent --local --message <text> --json --timeout <s>` runs locally
+// - MCP config in openclaw.json under mcpServers key
+// - Streamable HTTP transport uses { url: "..." } format
+// - No --workspace or --agent flags on `agent` subcommand
+// - Workspace override is via openclaw.json `agent.workspace` or setup flag
+
+async function runWithOpenClawCli() {
+  const twinUrls = collectTwinUrls();
+  const twinNames = Object.keys(twinUrls);
+  const harnessDir = dirname(new URL(import.meta.url).pathname);
+
+  if (twinNames.length === 0) {
+    console.error('[openclaw] No twin URLs found. Check ARCHAL_TWIN_NAMES and ARCHAL_<TWIN>_URL env vars.');
+    process.exit(1);
+  }
+
+  // Create a temp workspace directory
+  const workspaceDir = join(tmpdir(), `archal-openclaw-${randomUUID().slice(0, 8)}`);
+  mkdirSync(workspaceDir, { recursive: true });
+
+  // Build MCP server config for twin endpoints (streamable-http transport).
+  // OpenClaw reads mcpServers from openclaw.json — for HTTP transport,
+  // each entry needs just a `url` field pointing at the MCP endpoint.
+  const mcpServers = {};
+  for (const [twinName, baseUrl] of Object.entries(twinUrls)) {
+    const trimmed = baseUrl.trim().replace(/\/+$/, '');
+    const mcpUrl = trimmed.endsWith('/mcp') ? trimmed : `${trimmed}/mcp`;
+    mcpServers[`archal-${twinName}`] = { url: mcpUrl };
+  }
+
+  // Write openclaw.json config — this is the canonical config location
+  // that OpenClaw reads on startup. We set agent.workspace to this dir
+  // and configure mcpServers with twin endpoints.
+  const openclawConfig = {
+    agent: {
+      workspace: workspaceDir,
+    },
+    mcpServers,
+  };
+  // OpenClaw looks for openclaw.json in ~/.openclaw/ by default,
+  // but with --local mode it also checks the current working directory.
+  // We write both locations to be safe.
+  const dotOpenclawDir = join(workspaceDir, '.openclaw');
+  mkdirSync(dotOpenclawDir, { recursive: true });
+  writeFileSync(
+    join(dotOpenclawDir, 'openclaw.json'),
+    JSON.stringify(openclawConfig, null, 2),
+  );
+  // Also write a .mcp.json in workspace root (project-level MCP config)
+  writeFileSync(
+    join(workspaceDir, '.mcp.json'),
+    JSON.stringify({ mcpServers }, null, 2),
+  );
+
+  // Copy bootstrap files from harness into workspace
+  for (const file of ['SOUL.md', 'AGENTS.md', 'TOOLS.md', 'IDENTITY.md']) {
+    const src = join(harnessDir, file);
+    if (existsSync(src)) {
+      writeFileSync(join(workspaceDir, file), readFileSync(src, 'utf-8'));
+    }
+  }
+
+  // Build environment for the OpenClaw process
+  const env = { ...process.env };
+  // Use OPENCLAW_PROFILE to isolate this run's config from user's default
+  const profileName = `archal-${randomUUID().slice(0, 6)}`;
+  env['OPENCLAW_PROFILE'] = profileName;
+  // Pass gateway token if available
+  if (process.env['ARCHAL_TOKEN'] && !env['OPENCLAW_GATEWAY_TOKEN']) {
+    env['OPENCLAW_GATEWAY_TOKEN'] = process.env['ARCHAL_TOKEN'];
+  }
+
+  const timeoutSeconds = parseInt(process.env['ARCHAL_ENGINE_TIMEOUT'] || '240', 10);
+  const runStart = Date.now();
+
+  return new Promise((resolve, reject) => {
+    // OpenClaw agent CLI: --local runs embedded, --message is the task,
+    // --json gives machine-readable output, --timeout sets deadline
+    const args = [
+      'agent',
+      '--local',
+      '--message', TASK,
+      '--json',
+      '--timeout', String(timeoutSeconds),
+    ];
+
+    console.error(`[openclaw] Spawning: openclaw ${args.slice(0, 3).join(' ')} ... --timeout ${timeoutSeconds}`);
+    console.error(`[openclaw] Workspace: ${workspaceDir}`);
+    console.error(`[openclaw] Twins: ${twinNames.join(', ')} (MCP streamable-http)`);
+    console.error(`[openclaw] Profile: ${profileName}`);
+
+    const child = spawn('openclaw', args, {
+      env,
+      cwd: workspaceDir, // Run from workspace so .mcp.json is discovered
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: (timeoutSeconds + 30) * 1000, // Buffer above agent timeout
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on('data', (data) => {
+      const text = data.toString();
+      stderr += text;
+      process.stderr.write(text);
+    });
+
+    child.on('close', (code) => {
+      const totalTimeMs = Date.now() - runStart;
+
+      // Parse structured JSON output from OpenClaw
+      let parsedOutput = null;
+      try {
+        // OpenClaw --json may output multiple JSON objects; take the last one
+        const jsonLines = stdout.trim().split('\n').filter((l) => l.startsWith('{'));
+        if (jsonLines.length > 0) {
+          parsedOutput = JSON.parse(jsonLines[jsonLines.length - 1]);
+        }
+      } catch {
+        // Non-JSON output — extract what we can
+      }
+
+      // Extract metrics from OpenClaw's structured output
+      const metrics = {
+        inputTokens: parsedOutput?.usage?.input_tokens ?? parsedOutput?.usage?.inputTokens ?? 0,
+        outputTokens: parsedOutput?.usage?.output_tokens ?? parsedOutput?.usage?.outputTokens ?? 0,
+        llmCallCount: parsedOutput?.turns ?? parsedOutput?.steps ?? 0,
+        toolCallCount: parsedOutput?.tool_calls ?? parsedOutput?.toolCalls ?? 0,
+        toolErrorCount: parsedOutput?.tool_errors ?? parsedOutput?.toolErrors ?? 0,
+        totalTimeMs,
+        exitReason: code === 0 ? 'completed' : (code === null ? 'timeout' : 'error'),
+        provider: 'openclaw',
+        model: MODEL,
+      };
+
+      writeMetrics(metrics);
+
+      // Write output for the orchestrator
+      if (stdout) {
+        process.stdout.write(stdout);
+      }
+
+      if (code !== 0) {
+        console.error(`[openclaw] Process exited with code ${code}`);
+        if (stderr.includes('unknown option') || stderr.includes('Unknown flag')) {
+          console.error('[openclaw] Hint: OpenClaw CLI version may be incompatible. Try updating: npm install -g openclaw@latest');
+        }
+      }
+
+      // Cleanup temp workspace (best-effort)
+      try { rmSync(workspaceDir, { recursive: true, force: true }); } catch { /* ignore */ }
+
+      resolve(code ?? 1);
+    });
+
+    child.on('error', (err) => {
+      console.error(`[openclaw] Failed to spawn: ${err.message}`);
+      try { rmSync(workspaceDir, { recursive: true, force: true }); } catch { /* ignore */ }
+      reject(err);
+    });
+  });
+}
+
+// ── Main ─────────────────────────────────────────────────────────────
+
+const useOpenClawCli = isOpenClawInstalled();
+if (!useOpenClawCli) {
+  console.error('[openclaw] OpenClaw CLI not found. Install OpenClaw to run this harness.');
+  console.error('[openclaw] Use sandbox mode (`archal run ... --sandbox`) or install openclaw locally.');
+  process.exit(1);
+}
+
+console.error('[openclaw] Mode: native OpenClaw CLI');
+console.error(`[openclaw] Model: ${MODEL}`);
+console.error(`[openclaw] Task: ${TASK.slice(0, 200)}${TASK.length > 200 ? '...' : ''}`);
+
+const exitCode = await runWithOpenClawCli();
+process.exit(exitCode);

package/dist/harnesses/openclaw/archal-harness.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "name": "openclaw",
+  "description": "OpenClaw agent harness. Runs the real OpenClaw CLI against Archal twins; sandbox mode is the recommended path for production-fidelity evaluations.",
+  "defaultModel": "openclaw:main",
+  "promptFiles": [
+    "SOUL.md",
+    "AGENTS.md",
+    "TOOLS.md"
+  ],
+  "local": {
+    "command": "node",
+    "args": ["agent.mjs"]
+  },
+  "maxSteps": 80,
+  "supportedProviders": ["openclaw"],
+  "requiredEnvVars": [
+    "ARCHAL_ENGINE_TASK",
+    "ARCHAL_ENGINE_MODEL"
+  ],
+  "configDefaults": {
+    "maxSteps": 80,
+    "systemPrompt": true,
+    "errorHandling": true,
+    "retryOnTransient": true,
+    "maxConsecutiveErrors": 5
+  }
+}