nubos-pilot 1.2.4 → 1.3.0

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 };

package/lib/runtime/agent-loop.test.cjs

@@ -0,0 +1,135 @@
+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 { runAgentLoop, DEFAULT_MAX_ITERATIONS } = require('./agent-loop.cjs');
+const { toolsetFor } = require('./tools/index.cjs');
+
+const _dirs = [];
+function _ws(files) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'np-loop-')));
+  for (const [rel, content] of Object.entries(files || {})) {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf-8');
+  }
+  _dirs.push(root);
+  return root;
+}
+afterEach(() => { while (_dirs.length) { try { fs.rmSync(_dirs.pop(), { recursive: true, force: true }); } catch {} } });
+
+function _scriptedChat(turns) {
+  let i = 0;
+  const seen = [];
+  const fn = async ({ messages }) => {
+    seen.push(JSON.parse(JSON.stringify(messages)));
+    const t = turns[Math.min(i, turns.length - 1)];
+    i++;
+    if (t.toolCalls) {
+      return { content: t.content || '', toolCalls: t.toolCalls, finishReason: 'tool_calls', raw: { role: 'assistant', content: t.content || '', tool_calls: t.toolCalls.map((c) => ({ id: c.id, function: { name: c.name, arguments: c.arguments } })) } };
+    }
+    return { content: t.content, toolCalls: [], finishReason: 'stop', raw: { role: 'assistant', content: t.content } };
+  };
+  fn.seen = seen;
+  return fn;
+}
+
+test('AL-1: a final-answer turn returns immediately, stopped=final', async () => {
+  const chatImpl = _scriptedChat([{ content: 'done' }]);
+  const out = await runAgentLoop({
+    systemPrompt: 'you are x', task: 'do it',
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl,
+  });
+  assert.equal(out.content, 'done');
+  assert.equal(out.stopped, 'final');
+  assert.equal(out.iterations, 1);
+});
+
+test('AL-2: a tool call is executed in the workspace and fed back, then a final answer', async () => {
+  const cwd = _ws({ 'data.txt': 'hello' });
+  const chatImpl = _scriptedChat([
+    { toolCalls: [{ id: 't1', name: 'Read', arguments: '{"path":"data.txt"}' }] },
+    { content: 'the file says hello' },
+  ]);
+  const out = await runAgentLoop({
+    systemPrompt: 's', task: 'read data.txt', cwd,
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl,
+  });
+  assert.equal(out.stopped, 'final');
+  assert.equal(out.iterations, 2);
+  assert.deepEqual(out.toolLog, [{ name: 'Read', ok: true }]);
+  const lastTurnMsgs = chatImpl.seen[1];
+  const toolMsg = lastTurnMsgs.find((m) => m.role === 'tool');
+  assert.equal(toolMsg.tool_call_id, 't1');
+  assert.equal(toolMsg.content, '1\thello');
+});
+
+test('AL-3: a failing tool call returns an error string, ok=false, loop continues', async () => {
+  const cwd = _ws({});
+  const chatImpl = _scriptedChat([
+    { toolCalls: [{ id: 't1', name: 'Read', arguments: '{"path":"missing.txt"}' }] },
+    { content: 'could not read' },
+  ]);
+  const out = await runAgentLoop({
+    systemPrompt: 's', task: 't', cwd,
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl,
+  });
+  assert.equal(out.toolLog[0].ok, false);
+  assert.equal(out.stopped, 'final');
+});
+
+test('AL-4: a model that never stops hits the iteration cap', async () => {
+  const cwd = _ws({ 'a.txt': 'x' });
+  const chatImpl = _scriptedChat([{ toolCalls: [{ id: 't', name: 'Read', arguments: '{"path":"a.txt"}' }] }]);
+  const out = await runAgentLoop({
+    systemPrompt: 's', task: 't', cwd, maxIterations: 3,
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl,
+  });
+  assert.equal(out.stopped, 'max-iterations');
+  assert.equal(out.iterations, 3);
+  assert.equal(out.toolLog.length, 3);
+});
+
+test('AL-5: missing toolset / provider throw loud', async () => {
+  let a = null; try { await runAgentLoop({ provider: { model: 'm' } }); } catch (e) { a = e; }
+  assert.equal(a.code, 'agent-loop-no-toolset');
+  let b = null; try { await runAgentLoop({ toolset: toolsetFor(['Read']) }); } catch (e) { b = e; }
+  assert.equal(b.code, 'agent-loop-no-provider');
+});
+
+test('AL-6: DEFAULT_MAX_ITERATIONS is a sane positive cap', () => {
+  assert.ok(DEFAULT_MAX_ITERATIONS >= 1 && DEFAULT_MAX_ITERATIONS <= 100);
+});
+
+test('AL-7: assistant echo is rebuilt in OpenAI wire shape; ids round-trip even if provider omits them', async () => {
+  const cwd = _ws({ 'a.txt': 'A', 'b.txt': 'B' });
+  const chatImpl = async ({ messages }) => {
+    chatImpl.seen = (chatImpl.seen || []).concat([JSON.parse(JSON.stringify(messages))]);
+    if (!chatImpl.called) {
+      chatImpl.called = true;
+      return {
+        content: '', finishReason: 'tool_calls',
+        toolCalls: [
+          { id: 'call_0', name: 'Read', arguments: '{"path":"a.txt"}' },
+          { id: 'call_1', name: 'Read', arguments: '{"path":"b.txt"}' },
+        ],
+        raw: { role: 'assistant', content: '', tool_calls: [{ function: { name: 'Read' } }] },
+      };
+    }
+    return { content: 'done', toolCalls: [], finishReason: 'stop', raw: { role: 'assistant', content: 'done' } };
+  };
+  const out = await runAgentLoop({
+    systemPrompt: 's', task: 't', cwd,
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl,
+  });
+  assert.equal(out.stopped, 'final');
+  const secondTurn = chatImpl.seen[1];
+  const assistant = secondTurn.find((m) => m.role === 'assistant' && m.tool_calls);
+  assert.equal(assistant.tool_calls[0].type, 'function');
+  assert.equal(assistant.tool_calls[0].function.name, 'Read');
+  assert.deepEqual(assistant.tool_calls.map((c) => c.id), ['call_0', 'call_1']);
+  const toolMsgs = secondTurn.filter((m) => m.role === 'tool');
+  assert.deepEqual(toolMsgs.map((m) => m.tool_call_id), ['call_0', 'call_1']);
+});

package/lib/runtime/dispatch.cjs

@@ -0,0 +1,174 @@
+'use strict';
+
+const path = require('node:path');
+const { NubosPilotError } = require('../core.cjs');
+const { loadAgentSource } = require('../agents.cjs');
+const { resolveFromConfig } = require('../../bin/np-tools/resolve-model.cjs');
+const { assertPreflight } = require('./preflight.cjs');
+const { runAgentLoop } = require('./agent-loop.cjs');
+const { toolsetFor } = require('./tools/index.cjs');
+const { AUDITED_AGENTS, auditToolUse } = require('../nubosloop-audit.cjs');
+const { TASK_ID_RE } = require('../ids.cjs');
+const metrics = require('../metrics.cjs');
+
+function _lintOutput(content, schemaName) {
+  if (!schemaName) return null;
+  try {
+    const { getSchema } = require('../schemas/index.cjs');
+    const { lintContent } = require('../output-lint.cjs');
+    const res = lintContent(String(content == null ? '' : content), getSchema(schemaName));
+    return { ok: !!res.ok, schema: schemaName, violations: res.violations || [] };
+  } catch (err) {
+    return { ok: false, schema: schemaName, error: (err && err.code) || 'output-lint-failed' };
+  }
+}
+
+function _defaultInWorktree(cwd) {
+  try {
+    const { listSliceWorktrees } = require('../worktree.cjs');
+    return listSliceWorktrees(cwd).some((w) => cwd === w.path || cwd.startsWith(w.path + path.sep));
+  } catch { return false; }
+}
+
+function _parseTools(toolsField) {
+  if (Array.isArray(toolsField)) return toolsField.map((s) => String(s).trim()).filter(Boolean);
+  if (typeof toolsField === 'string') return toolsField.split(',').map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+async function dispatchOffHost(o) {
+  const opts = o || {};
+  const cwd = opts.cwd || process.cwd();
+  const deps = opts.deps || {};
+  const resolve = deps.resolve || resolveFromConfig;
+  const preflight = deps.preflight || assertPreflight;
+  const loadSource = deps.loadSource || loadAgentSource;
+  const runLoop = deps.runLoop || runAgentLoop;
+  const isInWorktree = deps.isInWorktree || _defaultInWorktree;
+  const now = deps.now || (() => new Date().toISOString());
+
+  if (typeof opts.agent !== 'string' || !opts.agent) {
+    throw new NubosPilotError('dispatch-no-agent', 'dispatchOffHost requires an agent name', {});
+  }
+
+  const res = resolve({ agentOrTier: opts.agent, cwd });
+  if (res.kind !== 'openai-compat') {
+    throw new NubosPilotError(
+      'dispatch-not-offhost',
+      'agent "' + opts.agent + '" resolves to provider "' + res.provider + '" (kind ' + res.kind
+        + ') — dispatchOffHost only runs openai-compat providers',
+      { provider: res.provider, kind: res.kind },
+    );
+  }
+  const audited = AUDITED_AGENTS.includes(opts.agent);
+  const hasTaskCtx = typeof opts.taskId === 'string' && TASK_ID_RE.test(opts.taskId);
+  if (audited && !hasTaskCtx) {
+    throw new NubosPilotError(
+      'offhost-audited-agent-unsupported',
+      'agent "' + opts.agent + '" is Rule-9-audited and needs a task context off-host — pass --task-id '
+        + 'M<NNN>-S<NNN>-T<NNNN> so the search-evidence ledger + audit apply. (Wired into execute-phase in ADR-0021 Slice 4b.)',
+      { agent: opts.agent, audited: AUDITED_AGENTS.slice() },
+    );
+  }
+
+  if (opts.allowBash && !isInWorktree(cwd)) {
+    throw new NubosPilotError(
+      'offhost-bash-requires-sandbox',
+      'off-host Bash needs worktree isolation — run inside a slice worktree (workflow.worktree_isolation) so model-driven shell is confined. Refused outside one.',
+      { cwd: path.basename(cwd) },
+    );
+  }
+
+  const src = loadSource(opts.agent, cwd);
+  const declared = _parseTools(src.frontmatter && src.frontmatter.tools);
+  const toolset = toolsetFor(declared, {
+    readOnly: !!opts.readOnly,
+    allowBash: !!opts.allowBash,
+    withSearch: audited,
+    ctx: { taskId: hasTaskCtx ? opts.taskId : null, customRulesPath: opts.customRulesPath },
+  });
+  const provider = { baseUrl: res.baseUrl, apiKeyEnv: res.apiKeyEnv, model: res.model };
+
+  await preflight(provider);
+
+  const started = now();
+  let result = null;
+  let status = 'ok';
+  let errObj = null;
+  try {
+    result = await runLoop({
+      systemPrompt: src.body,
+      task: opts.task,
+      toolset,
+      provider,
+      cwd,
+      maxIterations: opts.maxIterations,
+    });
+  } catch (err) {
+    status = 'error';
+    errObj = { code: (err && err.code) || 'dispatch-loop-failed', message: (err && err.message) || 'loop failed' };
+  }
+  const ended = now();
+
+  let metricsRecorded = false;
+  try {
+    const record = metrics.buildRecord({
+      agent: opts.agent,
+      tier: res.tier,
+      resolved_model: res.model,
+      phase: opts.phase || '',
+      plan: opts.plan || 'offhost',
+      task: opts.taskId || 'adhoc',
+      started_at: started,
+      ended_at: ended,
+      status,
+      runtime: res.provider,
+      error: errObj,
+    });
+    metrics.appendRecord(record, { cwd });
+    metricsRecorded = true;
+  } catch {}
+
+  if (status === 'error') {
+    throw new NubosPilotError(errObj.code, errObj.message, { agent: opts.agent, provider: res.provider });
+  }
+
+  let rule9 = null;
+  if (audited && hasTaskCtx && !opts.skipAudit) {
+    try {
+      rule9 = auditToolUse(opts.taskId, opts.agent, (result.toolLog || []).map((t) => t.name), cwd);
+    } catch (err) { rule9 = { ok: false, error: (err && err.code) || 'audit-failed' }; }
+  }
+
+  // Tool-calling capability signal: if the toolset advertised tools but the model
+  // made zero tool calls across the whole loop, the provider/model very likely does
+  // not support OpenAI function-calling. The loop does not crash on this (a tool-less
+  // turn is treated as a final answer), so it must be surfaced loudly — an off-host
+  // editor in this state silently produces no edits. Not fatal: read-only emit-only
+  // agents legitimately call no tools, so this is a hint, scoped by `mutating`.
+  const toolsAdvertised = (toolset.schemas || []).length;
+  const toolCalls = (result.toolLog || []).length;
+  const capability = {
+    toolsAdvertised,
+    toolCalls,
+    mutating: toolset.names.some((n) => n === 'Write' || n === 'Edit' || n === 'Bash'),
+    ok: !(toolsAdvertised > 0 && toolCalls === 0),
+  };
+
+  return {
+    agent: opts.agent,
+    provider: res.provider,
+    model: res.model,
+    content: result.content,
+    stopped: result.stopped,
+    iterations: result.iterations,
+    toolLog: result.toolLog,
+    tools: toolset.names,
+    rule9,
+    capability,
+    output_lint: _lintOutput(result.content, opts.outputSchema),
+    metrics_recorded: metricsRecorded,
+  };
+}
+
+module.exports = { dispatchOffHost, _parseTools };