lazyclaw 3.99.28 → 4.2.1

package/loop-engine.mjs

@@ -0,0 +1,182 @@
+// Engine for `/loop` REPL command and `lazyclaw loop` detached subcommand.
+//
+// Repeats one prompt against the active provider up to N times, stopping
+// early when (a) an `--until` regex matches the latest assistant turn, or
+// (b) an external `AbortSignal` fires (Ctrl+C in the REPL, SIGTERM in the
+// detached worker).
+//
+// Design constraints from spec:
+//   - Default --max is 3, hard ceiling 50 (refuse otherwise — runaway guard)
+//   - Per-iteration persistence: both the user and assistant turns must
+//     reach the session jsonl. On abort mid-iteration only completed
+//     pairs land — we defer the user-turn `persist` call until the
+//     assistant turn succeeds so a Ctrl+C between them leaves no orphan.
+//   - The engine is pure: callers inject `sendOnce` and `persist`. This
+//     lets the REPL stream chunks to stdout while the detached worker
+//     buffers silently and writes to its own iterations.log.
+
+export const LOOP_MAX_CEILING = 50;
+export const LOOP_MAX_DEFAULT = 3;
+
+export class LoopError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'LoopError';
+    this.code = code || 'LOOP_ERR';
+  }
+}
+
+// Lightweight tokenizer for the `/loop` argument tail. Honors double
+// quotes so `/loop "say hi" --until "DONE"` produces three tokens. No
+// escape sequences, no nested quotes — the spec doesn't require shell
+// fidelity and adding it would just give the user more rope.
+export function splitArgs(raw) {
+  const out = [];
+  let buf = '';
+  let inQuote = false;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === '"') { inQuote = !inQuote; continue; }
+    if (!inQuote && /\s/.test(ch)) {
+      if (buf) { out.push(buf); buf = ''; }
+      continue;
+    }
+    buf += ch;
+  }
+  if (inQuote) throw new LoopError('unterminated quoted argument', 'LOOP_BAD_QUOTE');
+  if (buf) out.push(buf);
+  return out;
+}
+
+export function parseLoopArgs(raw) {
+  const argv = splitArgs(raw);
+  let max = LOOP_MAX_DEFAULT;
+  let until = null;
+  let session = null;
+  let detach = false;
+  let useMemory = false;
+  let recall = null;
+  const promptParts = [];
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--max') {
+      const v = argv[++i];
+      if (v === undefined) throw new LoopError('--max requires a value', 'LOOP_BAD_FLAG');
+      const n = Number(v);
+      if (!Number.isInteger(n) || n <= 0) {
+        throw new LoopError(`--max must be a positive integer, got "${v}"`, 'LOOP_BAD_FLAG');
+      }
+      max = n;
+    } else if (t === '--until') {
+      const v = argv[++i];
+      if (v === undefined) throw new LoopError('--until requires a regex', 'LOOP_BAD_FLAG');
+      until = v;
+    } else if (t === '--session') {
+      const v = argv[++i];
+      if (v === undefined) throw new LoopError('--session requires an id', 'LOOP_BAD_FLAG');
+      session = v;
+    } else if (t === '--detach') {
+      detach = true;
+    } else if (t === '--use-memory') {
+      useMemory = true;
+    } else if (t === '--recall') {
+      const v = argv[++i];
+      if (v === undefined) throw new LoopError('--recall requires a query', 'LOOP_BAD_FLAG');
+      recall = v;
+    } else if (t.startsWith('--')) {
+      throw new LoopError(`unknown flag ${t}`, 'LOOP_BAD_FLAG');
+    } else {
+      promptParts.push(t);
+    }
+  }
+  if (max > LOOP_MAX_CEILING) {
+    throw new LoopError(
+      `--max ${max} exceeds ceiling ${LOOP_MAX_CEILING} (runaway guard). Refusing.`,
+      'LOOP_OVER_CEILING',
+    );
+  }
+  return { prompt: promptParts.join(' '), max, until, session, detach, useMemory, recall };
+}
+
+export function compileUntil(pattern) {
+  if (!pattern) return null;
+  try { return new RegExp(pattern); }
+  catch (e) { throw new LoopError(`bad --until regex: ${e?.message || e}`, 'LOOP_BAD_REGEX'); }
+}
+
+/**
+ * Run one prompt N times. Mutates `messages` in place.
+ *
+ * @param {object} o
+ * @param {string} o.prompt
+ * @param {number} o.max
+ * @param {RegExp|null} o.until
+ * @param {Array<{role:string,content:string}>} o.messages
+ * @param {(messages: any[], signal: AbortSignal|undefined) => Promise<string>} o.sendOnce
+ * @param {((role: 'user'|'assistant', content: string) => void)|undefined} o.persist
+ * @param {((evt: { i: number, max: number, reply: string }) => void)|undefined} o.onIteration
+ * @param {AbortSignal|undefined} o.signal
+ * @returns {Promise<{ iterations: number, stoppedBy: 'max'|'until'|'abort', lastReply: string }>}
+ */
+export async function runLoop({ prompt, max, until, messages, sendOnce, persist, onIteration, signal, buildSystem }) {
+  if (!prompt || !prompt.trim()) {
+    throw new LoopError('prompt is required', 'LOOP_NO_PROMPT');
+  }
+  if (!Number.isInteger(max) || max <= 0) {
+    throw new LoopError('max must be a positive integer', 'LOOP_BAD_MAX');
+  }
+  if (max > LOOP_MAX_CEILING) {
+    throw new LoopError(`max ${max} exceeds ceiling ${LOOP_MAX_CEILING}`, 'LOOP_OVER_CEILING');
+  }
+  if (typeof sendOnce !== 'function') {
+    throw new LoopError('sendOnce is required', 'LOOP_NO_SENDER');
+  }
+  let i = 0;
+  let lastReply = '';
+  let stoppedBy = 'max';
+  while (i < max) {
+    if (signal?.aborted) { stoppedBy = 'abort'; break; }
+    i++;
+    // Per-iteration system rebuild. The caller decides what `sys` is —
+    // memory.loadCore(), recall results, the chat's prior skill block,
+    // or any combination. Empty / falsy return = remove the system
+    // message. The rebuild runs every iteration so a parallel writer
+    // mutating core.md mid-loop is reflected in the next call.
+    if (buildSystem) {
+      const sys = buildSystem();
+      const sysIdx = messages.findIndex(m => m.role === 'system');
+      if (sys && String(sys).trim()) {
+        if (sysIdx >= 0) messages[sysIdx] = { role: 'system', content: sys };
+        else messages.unshift({ role: 'system', content: sys });
+      } else if (sysIdx >= 0) {
+        messages.splice(sysIdx, 1);
+      }
+    }
+    messages.push({ role: 'user', content: prompt });
+    let reply;
+    try {
+      reply = await sendOnce(messages, signal);
+    } catch (err) {
+      // Roll back the unpaired user turn so the in-memory messages stay
+      // consistent. The persist() call hasn't happened yet for this
+      // iteration, so the session jsonl is untouched.
+      messages.pop();
+      if (err?.code === 'ABORT' || signal?.aborted) {
+        stoppedBy = 'abort';
+        i--;
+        break;
+      }
+      throw err;
+    }
+    lastReply = reply;
+    persist?.('user', prompt);
+    messages.push({ role: 'assistant', content: lastReply });
+    persist?.('assistant', lastReply);
+    onIteration?.({ i, max, reply: lastReply });
+    if (until && until.test(lastReply)) {
+      stoppedBy = 'until';
+      break;
+    }
+  }
+  return { iterations: i, stoppedBy, lastReply };
+}

package/loops.mjs

@@ -0,0 +1,135 @@
+// Persistent state and helpers for `lazyclaw loop` runs.
+//
+// Storage layout under <configDir>/loops/<loopId>/:
+//   meta.json        — { prompt, max, until, sessionId, pid, pgid?, status,
+//                        startedAt, finishedAt?, provider, model }
+//   iterations.log   — newline-delimited iteration summaries (one per turn)
+//   result.json      — final outcome ({ stoppedBy, iterations, lastReply,
+//                                       error?, exitCode? }) on completion
+//
+// Status transitions:
+//   running -> completed | killed | failed | budget_exhausted
+//
+// Why three files instead of one:
+//   - meta.json mutates with the status field; iterations.log is append-only;
+//     result.json is written exactly once. Keeping them separate avoids
+//     read-modify-write contention between the worker (appending iter logs)
+//     and any reader (`lazyclaw loops show <id>`) running concurrently.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+const LOOPS_DIRNAME = 'loops';
+
+export function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+export function loopsDir(configDir = defaultConfigDir()) {
+  return path.join(configDir, LOOPS_DIRNAME);
+}
+
+export function loopDir(loopId, configDir = defaultConfigDir()) {
+  if (!loopId || /[/\\]/.test(loopId) || loopId === '.' || loopId === '..') {
+    throw new Error(`invalid loop id: ${loopId}`);
+  }
+  return path.join(loopsDir(configDir), loopId);
+}
+
+export function newLoopId() {
+  // ISO timestamp (filesystem-safe) + 6 random hex chars. Sorts
+  // chronologically and avoids collisions across rapid `--detach` invocations.
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const suffix = crypto.randomBytes(3).toString('hex');
+  return `${ts}-${suffix}`;
+}
+
+export function writeMeta(loopId, meta, configDir = defaultConfigDir()) {
+  const dir = loopDir(loopId, configDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, '.meta.json.tmp');
+  fs.writeFileSync(tmp, JSON.stringify(meta, null, 2));
+  fs.renameSync(tmp, path.join(dir, 'meta.json'));
+}
+
+export function readMeta(loopId, configDir = defaultConfigDir()) {
+  const dir = loopDir(loopId, configDir);
+  const p = path.join(dir, 'meta.json');
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+export function patchMeta(loopId, patch, configDir = defaultConfigDir()) {
+  const cur = readMeta(loopId, configDir) || {};
+  writeMeta(loopId, { ...cur, ...patch }, configDir);
+}
+
+export function appendIteration(loopId, entry, configDir = defaultConfigDir()) {
+  const dir = loopDir(loopId, configDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify({ ts: Date.now(), ...entry }) + '\n';
+  fs.appendFileSync(path.join(dir, 'iterations.log'), line);
+}
+
+export function readIterations(loopId, configDir = defaultConfigDir()) {
+  const p = path.join(loopDir(loopId, configDir), 'iterations.log');
+  if (!fs.existsSync(p)) return [];
+  const out = [];
+  for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip */ }
+  }
+  return out;
+}
+
+export function writeResult(loopId, result, configDir = defaultConfigDir()) {
+  const dir = loopDir(loopId, configDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, '.result.json.tmp');
+  fs.writeFileSync(tmp, JSON.stringify(result, null, 2));
+  fs.renameSync(tmp, path.join(dir, 'result.json'));
+}
+
+export function readResult(loopId, configDir = defaultConfigDir()) {
+  const p = path.join(loopDir(loopId, configDir), 'result.json');
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+export function listLoops(configDir = defaultConfigDir()) {
+  const dir = loopsDir(configDir);
+  if (!fs.existsSync(dir)) return [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const meta = readMeta(ent.name, configDir);
+    if (!meta) continue;
+    out.push({ id: ent.name, ...meta });
+  }
+  out.sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+  return out;
+}
+
+// Inspect a meta record and decide whether the worker is still alive.
+// We don't kill or reap; just synthesize a more truthful status field
+// for `loops list` / `loops show` after the process has gone away.
+export function isProcessAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e?.code === 'EPERM'; }
+}
+
+export function reconcileStatus(meta) {
+  if (!meta) return meta;
+  if (meta.status === 'running' && !isProcessAlive(meta.pid)) {
+    // Worker exited without flipping the status. Most likely a crash
+    // before the SIGTERM handler / finally block could update meta.
+    return { ...meta, status: 'failed' };
+  }
+  return meta;
+}

package/mas/agent_memory.mjs

@@ -0,0 +1,189 @@
+// Per-agent memory store — Phase 18.
+//
+// Each agent gets a plain-markdown file at
+//   <configDir>/memory/agents/<name>.md
+// with newest reflections at the TOP. Reads truncate to a configurable
+// byte budget (default 12 KB so the system prompt doesn't balloon).
+// Writes are append-to-top so the freshest entry is always inside the
+// truncation window.
+//
+// All I/O is best-effort: a missing/unreadable file returns '' and a
+// failed write is logged (when a logger is supplied) but never thrown.
+// The router calls these from the hot path; we don't want a transient
+// fs hiccup to kill a multi-agent turn.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const DEFAULT_MAX_CHARS = 12 * 1024;
+const AGENTS_MEM_DIR = path.join('memory', 'agents');
+
+export class AgentMemoryError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'AgentMemoryError';
+    this.code = code || 'AGENT_MEMORY_ERR';
+  }
+}
+
+export function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+export function memoryPath(name, configDir = defaultConfigDir()) {
+  if (!name || typeof name !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new AgentMemoryError(`bad agent name "${name}"`, 'AGENT_MEMORY_BAD_NAME');
+  }
+  return path.join(configDir, AGENTS_MEM_DIR, `${name}.md`);
+}
+
+// Read the agent's memory, truncated to `maxChars` from the top
+// (newest-first). Returns '' when the file is missing.
+export function readMemory(name, configDir = defaultConfigDir(), maxChars = DEFAULT_MAX_CHARS) {
+  let p;
+  try { p = memoryPath(name, configDir); }
+  catch { return ''; }
+  if (!fs.existsSync(p)) return '';
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    if (raw.length <= maxChars) return raw;
+    // Cut at a paragraph boundary if possible so a truncated entry
+    // doesn't bleed into the truncation marker.
+    let cut = raw.slice(0, maxChars);
+    const lastBlank = cut.lastIndexOf('\n\n');
+    if (lastBlank > maxChars * 0.6) cut = cut.slice(0, lastBlank);
+    return cut + '\n\n…[older entries truncated]\n';
+  } catch {
+    return '';
+  }
+}
+
+export function writeRaw(name, text, configDir = defaultConfigDir()) {
+  const p = memoryPath(name, configDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, String(text ?? ''));
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+export function clear(name, configDir = defaultConfigDir()) {
+  let p;
+  try { p = memoryPath(name, configDir); }
+  catch { return false; }
+  if (!fs.existsSync(p)) return false;
+  fs.unlinkSync(p);
+  return true;
+}
+
+// Prepend a new reflection block to the top of the file. Body should
+// be the LLM-generated bullets (no header) — we add the date + task
+// header ourselves so the format stays consistent.
+export function prependEntry(name, { taskId, title, body, ts = new Date() } = {}, configDir = defaultConfigDir()) {
+  const cleanBody = String(body || '').trim();
+  if (!cleanBody) return null;
+  const date = ts.toISOString().slice(0, 10);
+  const header = `## ${date} — task ${taskId}${title ? ` (${title})` : ''}`;
+  const entry = `${header}\n${cleanBody}\n\n`;
+  const p = memoryPath(name, configDir);
+  let existing = '';
+  if (fs.existsSync(p)) {
+    try { existing = fs.readFileSync(p, 'utf8'); } catch { /* keep going */ }
+  }
+  if (!existing) {
+    existing = `# ${name} — memory\n\n`;
+  }
+  // Split off the "# name — memory" title (line 1) so new entries land
+  // ABOVE the older entries but BELOW the title.
+  let title_line, rest;
+  const firstNewline = existing.indexOf('\n');
+  if (firstNewline >= 0 && existing.startsWith('# ')) {
+    title_line = existing.slice(0, firstNewline + 1);
+    rest = existing.slice(firstNewline + 1).replace(/^\n+/, '');
+  } else {
+    title_line = `# ${name} — memory\n`;
+    rest = existing;
+  }
+  const next = `${title_line}\n${entry}${rest}`;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, next);
+  fs.renameSync(tmp, p);
+  return { path: p, entry };
+}
+
+// Build the system-prompt block the router injects between agent.role
+// and the team-metadata footer. Returns '' when memory is empty.
+export function buildMemoryBlock(name, configDir = defaultConfigDir(), maxChars = DEFAULT_MAX_CHARS) {
+  const raw = readMemory(name, configDir, maxChars);
+  if (!raw.trim()) return '';
+  return [
+    '---',
+    '',
+    'What you remember from prior tasks (newest first):',
+    '',
+    raw.trim(),
+    '',
+    '---',
+    '',
+  ].join('\n');
+}
+
+// Run one reflection LLM call for an agent. Returns the trimmed bullet
+// body (without the date header) so the caller can either prepend it
+// to the on-disk file (auto mode) or surface it to the user (manual
+// command). Throws on hard failure; the router catches and logs.
+//
+// We use the agent's own provider via the existing tool-use callOnce
+// adapters because they are already wired up with apiKey/baseUrl
+// passthrough. No tools are advertised — reflection is pure text.
+export async function reflectOnce({ agent, task, apiKey, baseUrl, fetchImpl, maxBullets = 6 } = {}) {
+  if (!agent || !task) throw new AgentMemoryError('agent and task are required', 'AGENT_MEMORY_BAD_INPUT');
+  const adapter = await pickAdapter(agent.provider);
+
+  const transcript = (Array.isArray(task.turns) ? task.turns : [])
+    .map((t) => {
+      const who = t.agent === 'user' ? 'User' : t.agent === 'system' ? 'System' : t.agent;
+      return `[${who}] ${t.text || ''}`;
+    })
+    .join('\n\n') || '(no turns)';
+
+  const userMessage =
+    `You just finished task "${task.title || '(untitled)'}" (id ${task.id}). Here is the full transcript:\n\n` +
+    transcript +
+    `\n\nWrite a SHORT markdown block (≤ ${maxBullets} bullet points) capturing what you learned ` +
+    `during this task that would be useful next time. Be concrete: file paths, decisions, ` +
+    `gotchas, teammate preferences. Do NOT repeat generic advice. Do NOT exceed ${maxBullets} ` +
+    `bullets. Reply with the bullets only — no headers, no preamble.`;
+
+  const initialUser = adapter.initialUserMessage
+    ? adapter.initialUserMessage(userMessage)
+    : { role: 'user', content: userMessage };
+
+  const resp = await adapter.callOnce({
+    messages: [initialUser],
+    tools: [],
+    model: agent.model,
+    apiKey,
+    system: agent.role || '',
+    baseUrl,
+    fetchImpl,
+  });
+  if (resp.kind !== 'final') {
+    throw new AgentMemoryError(`reflection expected text reply, got ${resp.kind}`, 'AGENT_MEMORY_NO_TEXT');
+  }
+  const text = (resp.text || '').trim();
+  return text;
+}
+
+async function pickAdapter(provider) {
+  switch (provider) {
+    case 'anthropic':  return await import('../providers/tool_use/anthropic.mjs');
+    case 'openai':     return await import('../providers/tool_use/openai.mjs');
+    case 'gemini':     return await import('../providers/tool_use/gemini.mjs');
+    case 'claude-cli': return await import('../providers/tool_use/claude_cli.mjs');
+    default:
+      throw new AgentMemoryError(`provider "${provider}" does not support reflection`, 'AGENT_MEMORY_NO_PROVIDER');
+  }
+}

package/mas/agent_turn.mjs

@@ -0,0 +1,147 @@
+// Agent turn runner — given an agent record, a thread of history, and
+// a new user message, drives the provider-specific tool-use loop until
+// the model emits a final text reply (or the iteration budget runs
+// out).
+//
+// Provider routing:
+//   anthropic → providers/tool_use/anthropic.mjs   (Phase 12b)
+//   openai    → providers/tool_use/openai.mjs      (Phase 12c — todo)
+//   gemini    → providers/tool_use/gemini.mjs      (Phase 12d — todo)
+//   claude-cli → not supported (subprocess provider — Phase 12 scope
+//                excludes it; runAgentTurn throws so callers can flag
+//                the agent in the dashboard).
+//
+// The loop:
+//   1. Build messages = [...history, {role:user, content:input}]
+//   2. Call adapter.callOnce → response
+//   3. If response.kind === 'final', return { text, turns, iterations }
+//   4. Else (tool_calls): for each call, run the tool, append a
+//      tool_result message, loop back to step 2.
+//   5. If iterations > opts.maxIterations (default 10), bail with
+//      partial text and `stoppedBy: 'budget'`.
+
+import { listToolSchemas, runTool, ToolError } from './tool_runner.mjs';
+import * as anthropic from '../providers/tool_use/anthropic.mjs';
+import * as openai from '../providers/tool_use/openai.mjs';
+import * as gemini from '../providers/tool_use/gemini.mjs';
+import * as claudeCli from '../providers/tool_use/claude_cli.mjs';
+
+export class AgentTurnError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'AgentTurnError';
+    this.code = code || 'AGENT_TURN_ERR';
+  }
+}
+
+const DEFAULT_MAX_ITERATIONS = 10;
+
+function adapterFor(provider) {
+  switch (provider) {
+    case 'anthropic':  return { ...anthropic,  toolSchemas: anthropic.toAnthropicTools };
+    case 'openai':     return { ...openai,     toolSchemas: openai.toOpenAITools };
+    case 'gemini':     return { ...gemini,     toolSchemas: gemini.toGeminiTools };
+    // claude-cli runs the tool-use loop INSIDE the binary. Our adapter
+    // resolves every call to kind:'final' so the mention router still
+    // gets a normalised reply, even though no tool_calls envelope is
+    // ever observed.
+    case 'claude-cli': return { ...claudeCli, toolSchemas: (s) => s };
+    default:
+      throw new AgentTurnError(`provider "${provider}" does not support tool-use yet`, 'PROVIDER_UNSUPPORTED');
+  }
+}
+
+// Run one full agent turn. Returns:
+//   { text, iterations, stoppedBy: 'final' | 'budget' | 'tool_error', toolCalls }
+//
+// `toolCalls` lists every tool invocation that actually ran (with its
+// result). `stoppedBy: 'tool_error'` means the runner aborted because a
+// tool denied/threw; the previous text (if any) is returned but the
+// next provider call was skipped.
+export async function runAgentTurn({
+  agent,
+  userMessage,
+  history = [],
+  taskId,
+  configDir,
+  cwd,
+  fetchImpl,
+  baseUrl,
+  apiKey,
+  maxIterations = DEFAULT_MAX_ITERATIONS,
+  signal,
+} = {}) {
+  if (!agent) throw new AgentTurnError('agent is required', 'NO_AGENT');
+  const adapter = adapterFor(agent.provider);
+
+  const tools = adapter.toolSchemas(listToolSchemas(agent.tools));
+
+  // Seed messages from prior history + the new user input. Callers
+  // pass history in a provider-neutral [{role, content}] shape; the
+  // adapter normalises it into its native message format (e.g. Gemini's
+  // `parts: [...]` representation). The new user message is wrapped
+  // identically.
+  const normalize = adapter.normalizeHistory || ((h) => [...h]);
+  const initialUser = adapter.initialUserMessage || ((t) => ({ role: 'user', content: t }));
+  const messages = normalize(history);
+  if (userMessage && String(userMessage).trim()) {
+    messages.push(initialUser(String(userMessage)));
+  }
+
+  const toolCalls = [];
+  let iterations = 0;
+  let lastText = '';
+
+  while (iterations < maxIterations) {
+    if (signal?.aborted) return { text: lastText, iterations, stoppedBy: 'abort', toolCalls };
+    iterations++;
+    const resp = await adapter.callOnce({
+      messages, tools, model: agent.model, apiKey, system: agent.role,
+      fetchImpl, baseUrl, signal,
+    });
+    if (resp.text) lastText = resp.text;
+
+    if (resp.kind === 'final') {
+      return { text: resp.text || '', iterations, stoppedBy: 'final', toolCalls };
+    }
+
+    // tool_calls path: echo the model's assistant turn back so future
+    // tool_result messages correlate, then run each tool and append the
+    // adapter-shaped tool-result entries (one for Anthropic, N for
+    // OpenAI, …).
+    messages.push(...adapter.assistantTurnMessages(resp));
+    const results = [];
+    let toolErrored = false;
+    for (const call of resp.calls) {
+      let result;
+      let ok = true;
+      try {
+        result = await runTool({
+          agent, tool: call.name, args: call.input,
+          taskId, configDir, cwd,
+        });
+        if (result && result.ok === false) ok = false;
+      } catch (err) {
+        ok = false;
+        if (err instanceof ToolError) {
+          result = { ok: false, error: err.message, code: err.code };
+        } else {
+          result = { ok: false, error: `runTool threw: ${err?.message || err}` };
+        }
+      }
+      toolCalls.push({ id: call.id, name: call.name, input: call.input, result, ok });
+      results.push({ id: call.id, content: result, isError: !ok });
+      if (!ok) toolErrored = true;
+    }
+    messages.push(...adapter.toolResultMessages(results));
+
+    // We feed every tool error (denied/unknown/runtime) back to the
+    // model so it can recover. Only an extraordinary error (e.g. the
+    // provider returned a malformed envelope) bails out here.
+    if (toolErrored && process.env.LAZYCLAW_TOOL_STRICT === '1') {
+      return { text: lastText, iterations, stoppedBy: 'tool_error', toolCalls };
+    }
+  }
+
+  return { text: lastText, iterations, stoppedBy: 'budget', toolCalls };
+}