nubos-pilot 1.2.4 → 1.3.1

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/nubosloop.cjs

@@ -357,7 +357,7 @@ async function preflightCacheLookup(query, opts, cwd) {
   const spawnInput = taskId
     ? { task_id: taskId, task_query: query }
     : { task_query: query };
-  const spawnSpecs = swarm.buildSpawnSpecs(spawnInput, o.k);
+  const spawnSpecs = swarm.buildSpawnSpecs(spawnInput, o.k, { cwd });
   const swarmBlock = {
     k: o.k,
     threshold: o.threshold,

package/lib/output-steering.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+const OPEN = '<nubos_output_shaping>';
+const CLOSE = '</nubos_output_shaping>';
+const SHAPING_RE = /\n*<nubos_output_shaping>[\s\S]*?<\/nubos_output_shaping>\s*$/;
+
+const PROFILES = Object.freeze({
+  balanced: '',
+  concise: 'Skip preamble and postamble; lead with the substance. Do not restate code, file '
+    + 'contents, diffs, or tool output that already appear above — reference them by path and line.',
+  terse: 'Skip preamble and postamble; lead with the substance. Never restate code, files, '
+    + 'diffs, or tool output already present — reference them by path and line. After a tool '
+    + 'call succeeds, continue without narrating the result.',
+  minimal: 'Minimum tokens. Fragments are fine. No preamble, no postamble, no narration. Never '
+    + 'restate existing code, files, diffs, or tool output — reference by path and line. State '
+    + 'only what changed or what the answer is.',
+});
+
+const EFFORT_RANK = Object.freeze({ low: 0, medium: 1, high: 2, xhigh: 3, max: 4 });
+
+function steeringDirective(profile) {
+  const key = typeof profile === 'string' ? profile.toLowerCase() : 'balanced';
+  return Object.prototype.hasOwnProperty.call(PROFILES, key) ? PROFILES[key] : '';
+}
+
+function enrichSystemPrompt(prompt, profile) {
+  const base = String(prompt == null ? '' : prompt).replace(SHAPING_RE, '');
+  const directive = steeringDirective(profile);
+  if (!directive) return base;
+  return base + '\n\n' + OPEN + '\n' + directive + '\n' + CLOSE;
+}
+
+function classifyTurn(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return 'new_user_ask';
+  let lastAssistant = -1;
+  for (let k = messages.length - 1; k >= 0; k -= 1) {
+    if (messages[k] && messages[k].role === 'assistant') { lastAssistant = k; break; }
+  }
+  const pending = messages.slice(lastAssistant + 1);
+  if (pending.length === 0) return 'new_user_ask';
+  if (pending.some((m) => m && m.role === 'user')) return 'new_user_ask';
+  const tools = pending.filter((m) => m && m.role === 'tool');
+  if (tools.length === 0) return 'new_user_ask';
+  return tools.some((m) => _isErrorResult(m.content)) ? 'error_continuation' : 'mechanical_continuation';
+}
+
+function _isErrorResult(content) {
+  const s = String(content == null ? '' : content);
+  return /^Error:/.test(s) || /\b(ERROR|FAILED|FATAL|Exception|Traceback)\b/.test(s);
+}
+
+function routeEffort(currentEffort, turnKind, opts) {
+  const o = opts || {};
+  if (typeof currentEffort !== 'string' || !(currentEffort in EFFORT_RANK)) return currentEffort;
+  if (turnKind !== 'mechanical_continuation') return currentEffort;
+  const target = typeof o.mechanicalEffort === 'string' && o.mechanicalEffort in EFFORT_RANK
+    ? o.mechanicalEffort : 'low';
+  return EFFORT_RANK[target] < EFFORT_RANK[currentEffort] ? target : currentEffort;
+}
+
+module.exports = {
+  PROFILES,
+  EFFORT_RANK,
+  steeringDirective,
+  enrichSystemPrompt,
+  classifyTurn,
+  routeEffort,
+};

package/lib/output-steering.test.cjs

@@ -0,0 +1,74 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const steering = require('./output-steering.cjs');
+
+test('OS-1: balanced/unknown profile is a no-op (no shaping block)', () => {
+  const p = 'You are an agent.';
+  assert.equal(steering.enrichSystemPrompt(p, 'balanced'), p);
+  assert.equal(steering.enrichSystemPrompt(p, 'nonsense'), p);
+  assert.equal(steering.enrichSystemPrompt(p, undefined), p);
+});
+
+test('OS-2: a real profile appends one tagged, byte-stable block', () => {
+  const out = steering.enrichSystemPrompt('You are an agent.', 'terse');
+  assert.match(out, /^You are an agent\./);
+  assert.match(out, /<nubos_output_shaping>[\s\S]*<\/nubos_output_shaping>$/);
+  assert.equal(out, steering.enrichSystemPrompt('You are an agent.', 'terse'), 'deterministic');
+});
+
+test('OS-3: enrichment is idempotent and profile-switchable (always exactly one block)', () => {
+  const once = steering.enrichSystemPrompt('base', 'terse');
+  const twice = steering.enrichSystemPrompt(once, 'terse');
+  assert.equal(twice, once, 're-enriching with same profile converges');
+  const switched = steering.enrichSystemPrompt(once, 'minimal');
+  assert.equal((switched.match(/<nubos_output_shaping>/g) || []).length, 1, 'never stacks blocks');
+  assert.match(switched, /Minimum tokens/);
+  assert.equal(steering.enrichSystemPrompt(once, 'balanced'), 'base', 'balanced strips back to bare prompt');
+});
+
+test('OS-4: classifyTurn — fresh user ask', () => {
+  const msgs = [{ role: 'system', content: 's' }, { role: 'user', content: 'do x' }];
+  assert.equal(steering.classifyTurn(msgs), 'new_user_ask');
+  assert.equal(steering.classifyTurn([]), 'new_user_ask');
+});
+
+test('OS-5: classifyTurn — clean tool results are a mechanical continuation', () => {
+  const msgs = [
+    { role: 'user', content: 'do x' },
+    { role: 'assistant', content: '', tool_calls: [] },
+    { role: 'tool', tool_call_id: 'a', content: 'file written ok' },
+    { role: 'tool', tool_call_id: 'b', content: 'ok' },
+  ];
+  assert.equal(steering.classifyTurn(msgs), 'mechanical_continuation');
+});
+
+test('OS-6: classifyTurn — an error tool result forces full effort', () => {
+  const msgs = [
+    { role: 'user', content: 'do x' },
+    { role: 'assistant', content: '' },
+    { role: 'tool', tool_call_id: 'a', content: 'ok' },
+    { role: 'tool', tool_call_id: 'b', content: 'Error: file not found' },
+  ];
+  assert.equal(steering.classifyTurn(msgs), 'error_continuation');
+});
+
+test('OS-8: classifyTurn — a fresh user message after a tool turn is a new ask', () => {
+  const msgs = [
+    { role: 'user', content: 'do x' },
+    { role: 'assistant', content: '' },
+    { role: 'user', content: 'actually do y' },
+    { role: 'tool', tool_call_id: 'a', content: 'ok' },
+  ];
+  assert.equal(steering.classifyTurn(msgs), 'new_user_ask');
+});
+
+test('OS-7: routeEffort downgrades only on mechanical turns, never injects or upgrades', () => {
+  assert.equal(steering.routeEffort(undefined, 'mechanical_continuation', {}), undefined);
+  assert.equal(steering.routeEffort('high', 'mechanical_continuation', { mechanicalEffort: 'low' }), 'low');
+  assert.equal(steering.routeEffort('high', 'new_user_ask', { mechanicalEffort: 'low' }), 'high');
+  assert.equal(steering.routeEffort('high', 'error_continuation', { mechanicalEffort: 'low' }), 'high');
+  assert.equal(steering.routeEffort('low', 'mechanical_continuation', { mechanicalEffort: 'high' }), 'low');
+});

package/lib/researcher-swarm.cjs

@@ -4,6 +4,7 @@ const crypto = require('node:crypto');
 
 const { DEFAULT_THRESHOLD, DEFAULT_MIN_OCCURRENCE } = require('./knowledge-adapter.cjs');
 const config = require('./config.cjs');
+const elision = require('./elision.cjs');
 const { normalizeText } = require('./core.cjs');
 
 const DEFAULT_K = 3;
@@ -50,19 +51,29 @@ function resolveSwarmOpts(cwd, override) {
   return { k, threshold, minOccurrence };
 }
 
-function buildSpawnSpecs(input, k) {
+function _dedupInputRef(input, cwd) {
+  if (!cwd) return null;
+  const cx = elision.compressionContext(cwd);
+  return cx.store ? cx.store(JSON.stringify(input), 'json-array') : null;
+}
+
+function buildSpawnSpecs(input, k, opts) {
   if (!input || typeof input !== 'object') {
     throw new TypeError('buildSpawnSpecs: input object is required');
   }
   const safeK = _coerceK(k);
+  const o = opts || {};
+  const inputRef = _dedupInputRef(input, o.cwd);
   const specs = [];
   for (let i = 0; i < safeK; i += 1) {
-    specs.push({
+    const spec = {
       index: i,
       seed_delta: i,
       seed_nudge: SEED_DELTAS[i % SEED_DELTAS.length],
       input,
-    });
+    };
+    if (inputRef) spec.input_ref = inputRef;
+    specs.push(spec);
   }
   return specs;
 }

package/lib/runtime/agent-loop.cjs

@@ -0,0 +1,94 @@
+'use strict';
+
+const { NubosPilotError } = require('../core.cjs');
+const compress = require('../compress.cjs');
+const elision = require('../elision.cjs');
+const steering = require('../output-steering.cjs');
+const { EXPAND_TOOL_NAME } = require('./tools/index.cjs');
+
+const DEFAULT_MAX_ITERATIONS = 25;
+
+function _compressToolResult(text, cx) {
+  if (!cx || !cx.enabled || typeof cx.store !== 'function') return text;
+  try {
+    const res = compress.compressBlock(text, { minBlockBytes: cx.minBlockBytes, store: cx.store });
+    return (res && res.changed) ? res.compressed : text;
+  } catch {
+    return text;
+  }
+}
+
+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 cx = elision.compressionContext(cwd);
+  const os = cx.outputSteering || { enabled: false, effortRouting: false };
+  const compression = { tool_results: 0, blocks_compressed: 0, bytes_before: 0, bytes_after: 0 };
+
+  const messages = [];
+  if (systemPrompt) {
+    const sys = os.enabled ? steering.enrichSystemPrompt(String(systemPrompt), os.profile) : String(systemPrompt);
+    messages.push({ role: 'system', content: sys });
+  }
+  messages.push({ role: 'user', content: String(task == null ? '' : task) });
+
+  const toolLog = [];
+
+  for (let i = 0; i < max; i++) {
+    const turnProvider = os.effortRouting
+      ? { ...provider, effort: steering.routeEffort(provider.effort, steering.classifyTurn(messages), { mechanicalEffort: os.mechanicalEffort }) }
+      : provider;
+    const resp = await chat({ ...turnProvider, messages, tools: schemas });
+
+    if (!resp.toolCalls || resp.toolCalls.length === 0) {
+      return { content: resp.content || '', iterations: i + 1, stopped: 'final', toolLog, compression };
+    }
+
+    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 raw = String(toolset.execute(tc.name, tc.arguments, { cwd: cwd || process.cwd() }));
+      toolLog.push({ name: tc.name, ok: !raw.startsWith('Error:') });
+      const stored = tc.name === EXPAND_TOOL_NAME ? raw : _compressToolResult(raw, cx);
+      compression.tool_results += 1;
+      compression.bytes_before += Buffer.byteLength(raw, 'utf-8');
+      compression.bytes_after += Buffer.byteLength(stored, 'utf-8');
+      if (stored !== raw) compression.blocks_compressed += 1;
+      messages.push({ role: 'tool', tool_call_id: tc.id, content: stored });
+    }
+  }
+
+  const last = messages[messages.length - 1];
+  return {
+    content: (last && typeof last.content === 'string') ? last.content : '',
+    iterations: max,
+    stopped: 'max-iterations',
+    toolLog,
+    compression,
+  };
+}
+
+module.exports = { runAgentLoop, DEFAULT_MAX_ITERATIONS };