nubos-pilot 1.2.3 → 1.3.0

package/lib/headless-guard.cjs

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { atomicCreateExclusiveSync } = require('./core.cjs');
+
+const HEADLESS_ENV = 'NUBOS_PILOT_HEADLESS';
+const DEPTH_ENV = 'NUBOS_PILOT_HOOK_DEPTH';
+const MAX_DEPTH_ENV = 'NUBOS_PILOT_MAX_HOOK_DEPTH';
+const DEFAULT_MAX_DEPTH = 1;
+const DEFAULT_LOCK_STALE_MS = 15 * 60 * 1000;
+
+function isHeadless(env) {
+  const e = env || process.env;
+  return e[HEADLESS_ENV] === '1';
+}
+
+function currentDepth(env) {
+  const e = env || process.env;
+  const n = parseInt(e[DEPTH_ENV], 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function maxDepth(env) {
+  const e = env || process.env;
+  const n = parseInt(e[MAX_DEPTH_ENV], 10);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_MAX_DEPTH;
+}
+
+function depthExceeded(env) {
+  return currentDepth(env) >= maxDepth(env);
+}
+
+function childSpawnEnv(env) {
+  const out = Object.create(null);
+  out[HEADLESS_ENV] = '1';
+  out[DEPTH_ENV] = String(currentDepth(env) + 1);
+  return out;
+}
+
+function _isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (err) {
+    if (err && err.code === 'ESRCH') return false;
+    if (err && err.code === 'EPERM') return true;
+    return true;
+  }
+}
+
+function _lockPath(root, agent) {
+  return path.join(root, '.nubos-pilot', 'run', 'headless-' + agent + '.lock');
+}
+
+function _reclaimStaleLock(lockPath) {
+  const aside = lockPath + '.stale.' + process.pid + '.' + crypto.randomBytes(4).toString('hex');
+  try { fs.renameSync(lockPath, aside); }
+  catch { return; }
+  try { fs.unlinkSync(aside); } catch {}
+}
+
+function tryAcquireSpawnLock(root, agent, opts) {
+  const o = opts || {};
+  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : DEFAULT_LOCK_STALE_MS;
+  const lockPath = _lockPath(root, agent);
+  try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch {}
+  const payload = JSON.stringify({
+    pid: process.pid,
+    agent,
+    hostname: os.hostname(),
+    acquiredAt: new Date().toISOString(),
+  });
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      atomicCreateExclusiveSync(lockPath, payload);
+      let released = false;
+      return {
+        acquired: true,
+        lockPath,
+        release() {
+          if (released) return;
+          released = true;
+          let meta = null;
+          try { meta = JSON.parse(fs.readFileSync(lockPath, 'utf-8')); } catch {}
+          if (meta && meta.pid !== process.pid) return;
+          try { fs.unlinkSync(lockPath); } catch {}
+        },
+      };
+    } catch (err) {
+      if (!err || err.code !== 'EEXIST') {
+        return { acquired: false, error: (err && err.code) || 'unknown' };
+      }
+      let meta = null;
+      let stat = null;
+      try { meta = JSON.parse(fs.readFileSync(lockPath, 'utf-8')); } catch {}
+      try { stat = fs.statSync(lockPath); } catch {}
+      const ageStale = !!stat && (Date.now() - stat.mtimeMs > staleMs);
+      const pidDead = !!meta && _isPidAlive(meta.pid) === false;
+      if (ageStale || pidDead) {
+        _reclaimStaleLock(lockPath);
+        continue;
+      }
+      return { acquired: false, holder: meta };
+    }
+  }
+  return { acquired: false };
+}
+
+module.exports = {
+  HEADLESS_ENV,
+  DEPTH_ENV,
+  MAX_DEPTH_ENV,
+  DEFAULT_MAX_DEPTH,
+  DEFAULT_LOCK_STALE_MS,
+  isHeadless,
+  currentDepth,
+  maxDepth,
+  depthExceeded,
+  childSpawnEnv,
+  tryAcquireSpawnLock,
+  _isPidAlive,
+  _lockPath,
+};

package/lib/headless-guard.test.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const guard = require('./headless-guard.cjs');
+
+const _sandboxes = [];
+
+function _mkRoot() {
+  const r = fs.mkdtempSync(path.join(os.tmpdir(), 'np-headless-guard-'));
+  fs.mkdirSync(path.join(r, '.nubos-pilot'), { recursive: true });
+  _sandboxes.push(r);
+  return r;
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    const r = _sandboxes.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('HG-1: isHeadless is true only when NUBOS_PILOT_HEADLESS=1', () => {
+  assert.equal(guard.isHeadless({}), false);
+  assert.equal(guard.isHeadless({ NUBOS_PILOT_HEADLESS: '0' }), false);
+  assert.equal(guard.isHeadless({ NUBOS_PILOT_HEADLESS: 'yes' }), false);
+  assert.equal(guard.isHeadless({ NUBOS_PILOT_HEADLESS: '1' }), true);
+});
+
+test('HG-2: currentDepth parses NUBOS_PILOT_HOOK_DEPTH, defaults to 0', () => {
+  assert.equal(guard.currentDepth({}), 0);
+  assert.equal(guard.currentDepth({ NUBOS_PILOT_HOOK_DEPTH: 'x' }), 0);
+  assert.equal(guard.currentDepth({ NUBOS_PILOT_HOOK_DEPTH: '0' }), 0);
+  assert.equal(guard.currentDepth({ NUBOS_PILOT_HOOK_DEPTH: '2' }), 2);
+});
+
+test('HG-3: depthExceeded honours default cap of 1 and the env override', () => {
+  assert.equal(guard.depthExceeded({}), false);
+  assert.equal(guard.depthExceeded({ NUBOS_PILOT_HOOK_DEPTH: '1' }), true);
+  assert.equal(guard.depthExceeded({ NUBOS_PILOT_HOOK_DEPTH: '1', NUBOS_PILOT_MAX_HOOK_DEPTH: '2' }), false);
+  assert.equal(guard.depthExceeded({ NUBOS_PILOT_HOOK_DEPTH: '2', NUBOS_PILOT_MAX_HOOK_DEPTH: '2' }), true);
+});
+
+test('HG-4: childSpawnEnv marks headless and increments depth', () => {
+  assert.deepEqual({ ...guard.childSpawnEnv({}) }, { NUBOS_PILOT_HEADLESS: '1', NUBOS_PILOT_HOOK_DEPTH: '1' });
+  assert.deepEqual(
+    { ...guard.childSpawnEnv({ NUBOS_PILOT_HOOK_DEPTH: '1' }) },
+    { NUBOS_PILOT_HEADLESS: '1', NUBOS_PILOT_HOOK_DEPTH: '2' },
+  );
+});
+
+test('HG-5: tryAcquireSpawnLock acquires, then refuses a live concurrent holder', () => {
+  const r = _mkRoot();
+  const first = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(first.acquired, true);
+  assert.ok(fs.existsSync(first.lockPath));
+
+  const second = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(second.acquired, false, 'second concurrent acquire must be refused');
+  assert.ok(second.holder && second.holder.pid === process.pid);
+
+  first.release();
+  assert.equal(fs.existsSync(first.lockPath), false, 'release removes the lock');
+
+  const third = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(third.acquired, true, 'lock is re-acquirable after release');
+  third.release();
+});
+
+test('HG-6: different agents get independent locks', () => {
+  const r = _mkRoot();
+  const a = guard.tryAcquireSpawnLock(r, 'np-security-reviewer');
+  const b = guard.tryAcquireSpawnLock(r, 'np-learnings-extractor');
+  assert.equal(a.acquired, true);
+  assert.equal(b.acquired, true, 'a second agent must not be blocked by the first');
+  a.release();
+  b.release();
+});
+
+test('HG-7: a stale lock (old mtime) is reclaimed', () => {
+  const r = _mkRoot();
+  const held = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(held.acquired, true);
+  const past = new Date(Date.now() - 60 * 60 * 1000);
+  fs.utimesSync(held.lockPath, past, past);
+
+  const next = guard.tryAcquireSpawnLock(r, 'np-test-critic', { staleMs: 1000 });
+  assert.equal(next.acquired, true, 'a lock older than staleMs must be reclaimed');
+  next.release();
+});
+
+test('HG-8: a dead-pid lock is reclaimed even when fresh', () => {
+  const r = _mkRoot();
+  const lockPath = guard._lockPath(r, 'np-test-critic');
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  fs.writeFileSync(lockPath, JSON.stringify({ pid: 2147483646, hostname: os.hostname(), acquiredAt: new Date().toISOString() }), 'utf-8');
+  assert.equal(guard._isPidAlive(2147483646), false);
+
+  const next = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(next.acquired, true, 'a lock owned by a dead pid must be reclaimed');
+  next.release();
+});
+
+test('HG-9: stale reclaim leaves no .stale residue behind', () => {
+  const r = _mkRoot();
+  const held = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  const past = new Date(Date.now() - 60 * 60 * 1000);
+  fs.utimesSync(held.lockPath, past, past);
+  const next = guard.tryAcquireSpawnLock(r, 'np-test-critic', { staleMs: 1000 });
+  assert.equal(next.acquired, true);
+  next.release();
+  const runDir = path.join(r, '.nubos-pilot', 'run');
+  const residue = fs.readdirSync(runDir).filter((n) => n.includes('.stale.'));
+  assert.deepEqual(residue, [], 'rename-aside reclaim must clean up its temp file');
+});

package/lib/learnings/extract.cjs

@@ -124,7 +124,7 @@ function parseExtractorOutput(raw) {
   return { candidates, parse_ok: true };
 }
 
-function _defaultSpawn(promptText, opts) {
+async function _defaultSpawn(promptText, opts) {
   const spawnHeadless = require('../../bin/np-tools/spawn-headless.cjs');
   const tmp = os.tmpdir();
   const tag = process.pid + '-' + crypto.randomBytes(4).toString('hex');
@@ -132,7 +132,7 @@ function _defaultSpawn(promptText, opts) {
   const outputPath = path.join(tmp, 'np-learn-out-' + tag + '.json');
   fs.writeFileSync(promptPath, promptText, 'utf-8');
   try {
-    spawnHeadless.run(
+    await spawnHeadless.run(
       ['--agent', EXTRACTOR_AGENT, '--prompt-path', promptPath, '--output-path', outputPath,
         '--timeout-ms', String(opts.timeoutMs)],
       { cwd: opts.cwd, stdout: { write: () => {} } },
@@ -144,7 +144,7 @@ function _defaultSpawn(promptText, opts) {
   }
 }
 
-function runExtract(opts) {
+async function runExtract(opts) {
   const o = opts || {};
   const cwd = o.cwd || process.cwd();
   const config = o.config || {};
@@ -164,7 +164,7 @@ function runExtract(opts) {
   const promptText = buildExtractorPrompt(diff);
   let raw = '';
   try {
-    raw = spawn(promptText, { cwd, timeoutMs: config.timeout_ms || 120000 });
+    raw = await spawn(promptText, { cwd, timeoutMs: config.timeout_ms || 120000 });
   } catch {
     return { ran: true, logged: 0, reason: 'spawn-failed' };
   }

package/lib/learnings/extract.test.cjs

@@ -67,31 +67,31 @@ test('EX-6: non-JSON output → parse_ok false', () => {
   assert.strictEqual(extract.parseExtractorOutput('').parse_ok, false);
 });
 
-test('EX-7: runExtract on a non-repo returns not-a-repo, logs nothing', () => {
+test('EX-7: runExtract on a non-repo returns not-a-repo, logs nothing', async () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-norepo-'));
   try {
     const logged = [];
-    const r = extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: (c) => logged.push(c) });
+    const r = await extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: (c) => logged.push(c) });
     assert.strictEqual(r.ran, false);
     assert.strictEqual(r.reason, 'not-a-repo');
     assert.strictEqual(logged.length, 0);
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 });
 
-test('EX-8: runExtract on empty repo (no commit, no changes) → empty-diff', () => {
+test('EX-8: runExtract on empty repo (no commit, no changes) → empty-diff', async () => {
   const dir = _gitRepo(false);
   try {
-    const r = extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: () => {} });
+    const r = await extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: () => {} });
     assert.strictEqual(r.ran, true);
     assert.strictEqual(r.reason, 'empty-diff');
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 });
 
-test('EX-9: runExtract over a commit logs parsed candidates', () => {
+test('EX-9: runExtract over a commit logs parsed candidates', async () => {
   const dir = _gitRepo(true);
   try {
     const logged = [];
-    const r = extract.runExtract({
+    const r = await extract.runExtract({
       cwd: dir,
       spawnImpl: () => JSON.stringify({ result: JSON.stringify({ learnings: [
         { pattern: 'keep add() pure and total', outcome: 'verified' },
@@ -104,11 +104,11 @@ test('EX-9: runExtract over a commit logs parsed candidates', () => {
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 });
 
-test('EX-10: runExtract with unparseable spawn output → parse-failed, no log', () => {
+test('EX-10: runExtract with unparseable spawn output → parse-failed, no log', async () => {
   const dir = _gitRepo(true);
   try {
     const logged = [];
-    const r = extract.runExtract({ cwd: dir, spawnImpl: () => 'garbage', logImpl: (c) => logged.push(c) });
+    const r = await extract.runExtract({ cwd: dir, spawnImpl: () => 'garbage', logImpl: (c) => logged.push(c) });
     assert.strictEqual(r.reason, 'parse-failed');
     assert.strictEqual(logged.length, 0);
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }

package/lib/model-providers.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+const { NubosPilotError } = require('./core.cjs');
+
+const VALID_PROVIDER_KINDS = Object.freeze(['native', 'openai-compat']);
+const DEFAULT_PROVIDER = 'claude';
+
+function matchRouting(agentName, routing) {
+  if (!agentName || !routing || typeof routing !== 'object') return null;
+  if (Object.prototype.hasOwnProperty.call(routing, agentName)) {
+    return { key: agentName, entry: routing[agentName], match: 'exact' };
+  }
+  let best = null;
+  for (const key of Object.keys(routing)) {
+    if (key.length > 1 && key.endsWith('*')) {
+      const prefix = key.slice(0, -1);
+      if (agentName.startsWith(prefix) && (!best || prefix.length > best.prefixLen)) {
+        best = { key, entry: routing[key], match: 'glob', prefixLen: prefix.length };
+      }
+    }
+  }
+  return best ? { key: best.key, entry: best.entry, match: 'glob' } : null;
+}
+
+function resolveProvider({ agentName, tier, config }) {
+  const cfg = config || {};
+  const providers = cfg.model_providers;
+  const routing = cfg.agent_routing;
+
+  const matched = matchRouting(agentName || null, routing);
+
+  let providerName;
+  let pinnedModel = null;
+  let source;
+  if (matched) {
+    const entry = matched.entry;
+    if (!entry || typeof entry !== 'object') {
+      throw new NubosPilotError(
+        'agent-routing-invalid-entry',
+        'agent_routing["' + matched.key + '"] must be an object with a "provider" field',
+        { key: matched.key },
+      );
+    }
+    providerName = entry.provider;
+    if (typeof providerName !== 'string' || !providerName) {
+      throw new NubosPilotError(
+        'agent-routing-missing-provider',
+        'agent_routing["' + matched.key + '"] has no "provider" field',
+        { key: matched.key },
+      );
+    }
+    if (typeof entry.model === 'string' && entry.model) pinnedModel = entry.model;
+    source = 'agent_routing["' + matched.key + '"]';
+  } else if (providers && typeof providers.default === 'string' && providers.default) {
+    providerName = providers.default;
+    source = 'model_providers.default';
+  } else {
+    providerName = DEFAULT_PROVIDER;
+    source = 'default';
+  }
+
+  let def;
+  if (providerName === DEFAULT_PROVIDER && (!providers || !providers[DEFAULT_PROVIDER])) {
+    def = { kind: 'native' };
+  } else if (providers && typeof providers === 'object' && providers[providerName]
+             && typeof providers[providerName] === 'object') {
+    def = providers[providerName];
+  } else {
+    throw new NubosPilotError(
+      'provider-undefined',
+      source + ' references provider "' + providerName
+        + '", but model_providers.' + providerName + ' is not defined',
+      { provider: providerName, source },
+    );
+  }
+
+  const kind = def.kind || 'native';
+  if (!VALID_PROVIDER_KINDS.includes(kind)) {
+    throw new NubosPilotError(
+      'provider-invalid-kind',
+      'model_providers.' + providerName + '.kind must be one of ' + VALID_PROVIDER_KINDS.join('/'),
+      { provider: providerName, got: kind, allowed: VALID_PROVIDER_KINDS.slice() },
+    );
+  }
+
+  let model = null;
+  if (kind === 'native') {
+    model = pinnedModel || null;
+  } else if (pinnedModel) {
+    model = pinnedModel;
+  } else if (def.models && typeof def.models === 'object' && typeof def.models[tier] === 'string' && def.models[tier]) {
+    model = def.models[tier];
+  } else {
+    throw new NubosPilotError(
+      'provider-model-unresolved',
+      'cannot resolve a model for provider "' + providerName + '" at tier "' + tier
+        + '": no pinned model in agent_routing and no model_providers.' + providerName + '.models.' + tier,
+      { provider: providerName, tier },
+    );
+  }
+
+  return {
+    provider: providerName,
+    kind,
+    model,
+    baseUrl: (typeof def.base_url === 'string' && def.base_url) ? def.base_url : null,
+    apiKeyEnv: (typeof def.api_key_env === 'string' && def.api_key_env) ? def.api_key_env : null,
+    routed: !!matched,
+    source,
+  };
+}
+
+module.exports = {
+  matchRouting,
+  resolveProvider,
+  VALID_PROVIDER_KINDS,
+  DEFAULT_PROVIDER,
+};

package/lib/model-providers.test.cjs

@@ -0,0 +1,85 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { matchRouting, resolveProvider, VALID_PROVIDER_KINDS, DEFAULT_PROVIDER } = require('./model-providers.cjs');
+
+test('MPV-1: exact routing key beats glob', () => {
+  const r = { 'np-critic': { provider: 'a' }, 'np-critic*': { provider: 'b' } };
+  assert.equal(matchRouting('np-critic', r).match, 'exact');
+  assert.equal(matchRouting('np-critic', r).entry.provider, 'a');
+});
+
+test('MPV-2: trailing-* glob matches by prefix, longest prefix wins', () => {
+  const r = { 'np-*': { provider: 'wide' }, 'np-critic*': { provider: 'narrow' } };
+  assert.equal(matchRouting('np-critic-style', r).entry.provider, 'narrow');
+  assert.equal(matchRouting('np-planner', r).entry.provider, 'wide');
+});
+
+test('MPV-3: no match returns null; empty agentName returns null', () => {
+  assert.equal(matchRouting('np-x', { 'np-y*': {} }), null);
+  assert.equal(matchRouting(null, { 'np-y*': {} }), null);
+  assert.equal(matchRouting('np-x', null), null);
+});
+
+test('MPV-4: absent config resolves to implicit claude-native default', () => {
+  const out = resolveProvider({ agentName: 'np-planner', tier: 'opus', config: {} });
+  assert.deepEqual(
+    { provider: out.provider, kind: out.kind, model: out.model, routed: out.routed },
+    { provider: DEFAULT_PROVIDER, kind: 'native', model: null, routed: false },
+  );
+});
+
+test('MPV-5: openai-compat resolves models[tier] when unpinned', () => {
+  const config = {
+    model_providers: { ollama: { kind: 'openai-compat', base_url: 'http://x/v1', models: { sonnet: 'm-s', opus: 'm-o' } } },
+    agent_routing: { 'np-executor': { provider: 'ollama' } },
+  };
+  assert.equal(resolveProvider({ agentName: 'np-executor', tier: 'sonnet', config }).model, 'm-s');
+  assert.equal(resolveProvider({ agentName: 'np-executor', tier: 'opus', config }).model, 'm-o');
+});
+
+test('MPV-6: undefined provider reference throws provider-undefined', () => {
+  let thrown = null;
+  try {
+    resolveProvider({
+      agentName: 'np-executor', tier: 'opus',
+      config: { model_providers: { claude: { kind: 'native' } }, agent_routing: { 'np-executor': { provider: 'ghost' } } },
+    });
+  } catch (e) { thrown = e; }
+  assert.equal(thrown && thrown.code, 'provider-undefined');
+});
+
+test('MPV-7: invalid kind throws provider-invalid-kind', () => {
+  let thrown = null;
+  try {
+    resolveProvider({
+      agentName: 'np-executor', tier: 'opus',
+      config: { model_providers: { weird: { kind: 'grpc' } }, agent_routing: { 'np-executor': { provider: 'weird' } } },
+    });
+  } catch (e) { thrown = e; }
+  assert.equal(thrown && thrown.code, 'provider-invalid-kind');
+});
+
+test('MPV-8: routing entry without provider throws agent-routing-missing-provider', () => {
+  let thrown = null;
+  try {
+    resolveProvider({ agentName: 'np-executor', tier: 'opus', config: { agent_routing: { 'np-executor': { model: 'x' } } } });
+  } catch (e) { thrown = e; }
+  assert.equal(thrown && thrown.code, 'agent-routing-missing-provider');
+});
+
+test('MPV-9: baseUrl + apiKeyEnv surfaced for openai-compat', () => {
+  const out = resolveProvider({
+    agentName: 'np-executor', tier: 'opus',
+    config: {
+      model_providers: { openai: { kind: 'openai-compat', base_url: 'https://api.openai.com/v1', api_key_env: 'OPENAI_API_KEY', models: { opus: 'gpt-4.1' } } },
+      agent_routing: { 'np-executor': { provider: 'openai' } },
+    },
+  });
+  assert.equal(out.baseUrl, 'https://api.openai.com/v1');
+  assert.equal(out.apiKeyEnv, 'OPENAI_API_KEY');
+});
+
+test('MPV-10: VALID_PROVIDER_KINDS is the closed set [native, openai-compat]', () => {
+  assert.deepEqual(VALID_PROVIDER_KINDS, ['native', 'openai-compat']);
+});

package/lib/runtime/agent-loop.cjs

@@ -0,0 +1,64 @@
+'use strict';
+
+const { NubosPilotError } = require('../core.cjs');
+
+const DEFAULT_MAX_ITERATIONS = 25;
+
+async function runAgentLoop(a) {
+  const {
+    systemPrompt, task, toolset, provider, cwd,
+    maxIterations, chatImpl,
+  } = a || {};
+  if (!toolset || typeof toolset.execute !== 'function') {
+    throw new NubosPilotError('agent-loop-no-toolset', 'runAgentLoop requires a toolset with execute()', {});
+  }
+  if (!provider || typeof provider.model !== 'string') {
+    throw new NubosPilotError('agent-loop-no-provider', 'runAgentLoop requires a provider with a model', {});
+  }
+  const chat = chatImpl || require('./providers/openai-compat.cjs').chat;
+  const max = Math.max(1, maxIterations || DEFAULT_MAX_ITERATIONS);
+  const schemas = (toolset.schemas && toolset.schemas.length) ? toolset.schemas : undefined;
+
+  const messages = [];
+  if (systemPrompt) messages.push({ role: 'system', content: String(systemPrompt) });
+  messages.push({ role: 'user', content: String(task == null ? '' : task) });
+
+  const toolLog = [];
+
+  for (let i = 0; i < max; i++) {
+    const resp = await chat({ ...provider, messages, tools: schemas });
+
+    if (!resp.toolCalls || resp.toolCalls.length === 0) {
+      return { content: resp.content || '', iterations: i + 1, stopped: 'final', toolLog };
+    }
+
+    messages.push({
+      role: 'assistant',
+      content: resp.content || '',
+      tool_calls: resp.toolCalls.map((tc) => ({
+        id: tc.id,
+        type: 'function',
+        function: {
+          name: tc.name,
+          arguments: typeof tc.arguments === 'string' ? tc.arguments : JSON.stringify(tc.arguments || {}),
+        },
+      })),
+    });
+
+    for (const tc of resp.toolCalls) {
+      const result = toolset.execute(tc.name, tc.arguments, { cwd: cwd || process.cwd() });
+      toolLog.push({ name: tc.name, ok: !String(result).startsWith('Error:') });
+      messages.push({ role: 'tool', tool_call_id: tc.id, content: String(result) });
+    }
+  }
+
+  const last = messages[messages.length - 1];
+  return {
+    content: (last && typeof last.content === 'string') ? last.content : '',
+    iterations: max,
+    stopped: 'max-iterations',
+    toolLog,
+  };
+}
+
+module.exports = { runAgentLoop, DEFAULT_MAX_ITERATIONS };