nubos-pilot 1.2.4 → 1.3.1

package/bin/np-tools/spawn-offhost.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+const fs = require('node:fs');
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { dispatchOffHost } = require('../../lib/runtime/dispatch.cjs');
+
+function _usage() {
+  process.stderr.write(
+    'Usage: np-tools.cjs spawn-offhost --agent <name> (--task <str> | --task-file <path>) '
+    + '[--cwd <dir>] [--phase P] [--plan P] [--task-id T] [--max-iterations N] [--allow-bash] [--read-only] [--no-audit]\n',
+  );
+}
+
+function _parse(argv) {
+  const out = { allowBash: false, readOnly: false };
+  const a = argv.slice();
+  while (a.length) {
+    const f = a.shift();
+    if (f === '--agent') out.agent = a.shift();
+    else if (f === '--task') out.task = a.shift();
+    else if (f === '--task-file') out.taskFile = a.shift();
+    else if (f === '--phase') out.phase = a.shift();
+    else if (f === '--plan') out.plan = a.shift();
+    else if (f === '--task-id') out.taskId = a.shift();
+    else if (f === '--max-iterations') out.maxIterations = Number(a.shift());
+    else if (f === '--cwd') out.cwd = a.shift();
+    else if (f === '--output-schema') out.outputSchema = a.shift();
+    else if (f === '--allow-bash') out.allowBash = true;
+    else if (f === '--read-only') out.readOnly = true;
+    else if (f === '--no-audit') out.skipAudit = true;
+  }
+  return out;
+}
+
+async function run(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : process.argv.slice(3);
+  if (!args.length || args[0] === '--help') { _usage(); return 1; }
+  const parsed = _parse(args);
+
+  let task = parsed.task;
+  if (parsed.taskFile) {
+    try { task = fs.readFileSync(parsed.taskFile, 'utf-8'); }
+    catch { process.stderr.write(JSON.stringify({ code: 'spawn-offhost-task-file-unreadable', file: require('node:path').basename(parsed.taskFile) }) + '\n'); return 1; }
+  }
+  if (!parsed.agent || typeof task !== 'string') { _usage(); return 1; }
+
+  try {
+    const result = await dispatchOffHost({
+      agent: parsed.agent,
+      task,
+      cwd: parsed.cwd || process.cwd(),
+      phase: parsed.phase,
+      plan: parsed.plan,
+      taskId: parsed.taskId,
+      maxIterations: parsed.maxIterations,
+      allowBash: parsed.allowBash,
+      readOnly: parsed.readOnly,
+      skipAudit: parsed.skipAudit,
+      outputSchema: parsed.outputSchema,
+    });
+    if (result && result.metrics_recorded === false) {
+      process.stderr.write('spawn-offhost: metrics row was not recorded (telemetry only; run succeeded)\n');
+    }
+    if (result && result.rule9 && result.rule9.ok === false) {
+      process.stderr.write('spawn-offhost: Rule-9 violation (' + (result.rule9.violation || result.rule9.error)
+        + ') — the agent did not satisfy the search bar. Do NOT commit this output as-is; re-run or route back to the agent.\n');
+    }
+    if (result && result.capability && result.capability.ok === false) {
+      const c = result.capability;
+      process.stderr.write('spawn-offhost: the model advertised ' + c.toolsAdvertised
+        + ' tool(s) but made zero tool calls — the provider/model likely does NOT support OpenAI function/tool-calling. '
+        + (c.mutating
+          ? 'This agent edits files; off-host it produced NO changes. Route it to a tool-calling-capable model or keep it native.'
+          : 'If this agent was expected to inspect the workspace, its output may be ungrounded — verify before relying on it.')
+        + '\n');
+    }
+    process.stdout.write(JSON.stringify(result) + '\n');
+    return 0;
+  } catch (err) {
+    if (err && err.name === 'NubosPilotError') {
+      process.stderr.write(JSON.stringify({ code: err.code, message: err.message, details: err.details }) + '\n');
+    } else {
+      process.stderr.write(String((err && err.stack) || err) + '\n');
+    }
+    return 1;
+  }
+}
+
+module.exports = { run, _parse };
+
+if (require.main === module) {
+  run(process.argv.slice(2)).then((code) => process.exit(code || 0));
+}

package/bin/np-tools/spawn-offhost.test.cjs

@@ -0,0 +1,38 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const subcmd = require('./spawn-offhost.cjs');
+
+function _capture(fn) {
+  const out = []; const err = [];
+  const oo = process.stdout.write.bind(process.stdout);
+  const oe = process.stderr.write.bind(process.stderr);
+  process.stdout.write = (c) => { out.push(String(c)); return true; };
+  process.stderr.write = (c) => { err.push(String(c)); return true; };
+  return Promise.resolve(fn()).then((rc) => {
+    process.stdout.write = oo; process.stderr.write = oe;
+    return { rc, stdout: out.join(''), stderr: err.join('') };
+  }, (e) => { process.stdout.write = oo; process.stderr.write = oe; throw e; });
+}
+
+test('SOH-1: _parse reads agent/task, the boolean flags, --cwd and --no-audit', () => {
+  const p = subcmd._parse(['--agent', 'np-executor', '--task', 'do x', '--allow-bash', '--max-iterations', '5', '--cwd', '/wt', '--no-audit']);
+  assert.equal(p.agent, 'np-executor');
+  assert.equal(p.task, 'do x');
+  assert.equal(p.allowBash, true);
+  assert.equal(p.readOnly, false);
+  assert.equal(p.maxIterations, 5);
+  assert.equal(p.cwd, '/wt');
+  assert.equal(p.skipAudit, true);
+});
+
+test('SOH-2: missing args prints usage and returns 1', async () => {
+  const { rc, stderr } = await _capture(() => subcmd.run([]));
+  assert.equal(rc, 1);
+  assert.match(stderr, /Usage:/);
+});
+
+test('SOH-3: --agent without a task returns 1', async () => {
+  const { rc } = await _capture(() => subcmd.run(['--agent', 'np-executor']));
+  assert.equal(rc, 1);
+});

package/lib/agents.cjs

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { extractFrontmatter } = require('./frontmatter.cjs');
+const { extractFrontmatter, stripFrontmatter } = require('./frontmatter.cjs');
 const { NubosPilotError, findProjectRoot } = require('./core.cjs');
 
 const REQUIRED = ['name', 'description', 'tier', 'tools'];
@@ -60,7 +60,7 @@ function validateAgentFrontmatter(fm, agentName) {
 
 const AGENT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
-function _loadAgentFromDisk(name, cwd) {
+function _resolveAgentPath(name, cwd) {
   if (typeof name !== 'string' || !AGENT_NAME_RE.test(name)) {
     throw new NubosPilotError(
       'agent-invalid-name',
@@ -83,10 +83,23 @@ function _loadAgentFromDisk(name, cwd) {
       { name, path: candidates[0], tried: candidates },
     );
   }
+  return found;
+}
+
+function _loadAgentFromDisk(name, cwd) {
+  const found = _resolveAgentPath(name, cwd);
   const { frontmatter } = extractFrontmatter(fs.readFileSync(found, 'utf-8'));
   return validateAgentFrontmatter(frontmatter, name);
 }
 
+function loadAgentSource(name, cwd) {
+  const found = _resolveAgentPath(name, cwd);
+  const raw = fs.readFileSync(found, 'utf-8');
+  const { frontmatter } = extractFrontmatter(raw);
+  validateAgentFrontmatter(frontmatter, name);
+  return { frontmatter, body: stripFrontmatter(raw), path: found };
+}
+
 function loadAgent(name, cwd) {
   const fm = _loadAgentFromDisk(name, cwd);
   if (fm.module === true) {
@@ -143,6 +156,7 @@ module.exports = {
   validateAgentFrontmatter,
   loadAgent,
   loadAgentModule,
+  loadAgentSource,
   listAgents,
   getAgentSkills,
   AGENT_NAME_RE,

package/lib/cache-align.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+const UUID_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+const ISO_RE = /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+const JWT_RE = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/;
+const HEX_RE = /\b[0-9a-f]{32,64}\b/i;
+const VOLATILE = Object.freeze([
+  ['uuid', UUID_RE],
+  ['iso_datetime', ISO_RE],
+  ['jwt', JWT_RE],
+  ['hex_hash', HEX_RE],
+]);
+
+function _systemText(system) {
+  if (typeof system === 'string') return system;
+  if (Array.isArray(system)) {
+    return system.map((b) => (b && typeof b.text === 'string' ? b.text : '')).join('\n');
+  }
+  return '';
+}
+
+function detectVolatile(system) {
+  const text = _systemText(system);
+  const findings = [];
+  for (const [kind, re] of VOLATILE) {
+    const m = text.match(re);
+    if (m) findings.push({ kind, sample_len: m[0].length });
+  }
+  return findings;
+}
+
+function _sortKeys(v) {
+  if (Array.isArray(v)) return v.map(_sortKeys);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = _sortKeys(v[k]);
+    return out;
+  }
+  return v;
+}
+
+function _byCodepoint(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function normalizeTools(tools) {
+  return tools
+    .map(_sortKeys)
+    .map((t) => ({ t, name: String(t && t.name), body: JSON.stringify(t) }))
+    .sort((a, b) => _byCodepoint(a.name, b.name) || _byCodepoint(a.body, b.body))
+    .map((x) => x.t);
+}
+
+function _anyCacheControl(system, tools) {
+  if (Array.isArray(system) && system.some((b) => b && b.cache_control)) return true;
+  if (Array.isArray(tools) && tools.some((t) => t && t.cache_control)) return true;
+  return false;
+}
+
+function alignAnthropicBody(body) {
+  const findings = detectVolatile(body && body.system);
+  if (!body || !Array.isArray(body.tools) || body.tools.length === 0) {
+    return { body, findings, applied: false };
+  }
+  if (_anyCacheControl(body.system, body.tools)) {
+    return { body, findings, applied: false };
+  }
+  const tools = normalizeTools(body.tools);
+  const last = tools.length - 1;
+  tools[last] = Object.assign({}, tools[last], { cache_control: { type: 'ephemeral' } });
+  return { body: Object.assign({}, body, { tools }), findings, applied: true };
+}
+
+module.exports = {
+  detectVolatile,
+  normalizeTools,
+  alignAnthropicBody,
+};

package/lib/cache-align.test.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const ca = require('./cache-align.cjs');
+
+test('CA-1: detectVolatile flags UUID/ISO-date/JWT/hex in the system prompt', () => {
+  const sys = 'Run id 550e8400-e29b-41d4-a716-446655440000 at 2026-06-23T10:00:00Z '
+    + 'token eyJhbGc.eyJzdWI.sig hash d41d8cd98f00b204e9800998ecf8427e';
+  const kinds = ca.detectVolatile(sys).map((f) => f.kind).sort();
+  assert.deepEqual(kinds, ['hex_hash', 'iso_datetime', 'jwt', 'uuid']);
+});
+
+test('CA-2: detectVolatile reads an array-form system prompt and is clean when stable', () => {
+  assert.deepEqual(ca.detectVolatile([{ type: 'text', text: 'You are a stable agent.' }]), []);
+  assert.deepEqual(ca.detectVolatile('plain stable instructions'), []);
+});
+
+test('CA-3: normalizeTools sorts tools by name and recursively sorts schema keys; arrays keep order', () => {
+  const tools = [
+    { name: 'zeta', description: 'z', input_schema: { type: 'object', required: ['b', 'a'], properties: { y: {}, x: {} } } },
+    { name: 'alpha', description: 'a', input_schema: { properties: { n: {} }, type: 'object' } },
+  ];
+  const out = ca.normalizeTools(tools);
+  assert.deepEqual(out.map((t) => t.name), ['alpha', 'zeta']);
+  assert.deepEqual(Object.keys(out[1]), ['description', 'input_schema', 'name']);
+  assert.deepEqual(Object.keys(out[1].input_schema.properties), ['x', 'y']);
+  assert.deepEqual(out[1].input_schema.required, ['b', 'a']);
+});
+
+test('CA-4: alignAnthropicBody adds exactly one ephemeral breakpoint on the last tool and is idempotent', () => {
+  const body = { system: 'sys', tools: [{ name: 'b' }, { name: 'a' }], messages: [] };
+  const r1 = ca.alignAnthropicBody(body);
+  assert.equal(r1.applied, true);
+  assert.deepEqual(r1.body.tools.map((t) => t.name), ['a', 'b']);
+  assert.equal(r1.body.tools[0].cache_control, undefined);
+  assert.deepEqual(r1.body.tools[1].cache_control, { type: 'ephemeral' });
+  const r2 = ca.alignAnthropicBody(r1.body);
+  assert.equal(r2.applied, false, 'second pass is a no-op — breakpoint already present');
+  assert.equal(JSON.stringify(r2.body), JSON.stringify(r1.body), 'byte-identical second pass');
+});
+
+test('CA-4b: normalizeTools is byte-deterministic regardless of input order (codepoint, not locale)', () => {
+  const a = [{ name: 'get_A' }, { name: 'get-a' }, { name: 'get_a' }, { name: 'tool10' }, { name: 'tool2' }];
+  const b = a.slice().reverse();
+  assert.equal(JSON.stringify(ca.normalizeTools(a)), JSON.stringify(ca.normalizeTools(b)), 'order-independent, stable bytes');
+  assert.deepEqual(ca.normalizeTools(a).map((t) => t.name), ['get-a', 'get_A', 'get_a', 'tool10', 'tool2']);
+});
+
+test('CA-4c: duplicate/degenerate names still order deterministically via body tiebreak', () => {
+  const x = [{ name: 'x', id: 2 }, { name: 'x', id: 1 }];
+  assert.equal(JSON.stringify(ca.normalizeTools(x)), JSON.stringify(ca.normalizeTools(x.slice().reverse())));
+});
+
+test('CA-5: customer-placement-wins — a caller-set cache_control is never disturbed', () => {
+  const body = { tools: [{ name: 'z', cache_control: { type: 'ephemeral' } }, { name: 'a' }], messages: [] };
+  const r = ca.alignAnthropicBody(body);
+  assert.equal(r.applied, false);
+  assert.deepEqual(r.body.tools.map((t) => t.name), ['z', 'a'], 'tool order untouched when caller manages caching');
+});
+
+test('CA-6: no tools → no normalization, detection still runs', () => {
+  const body = { system: 'id 550e8400-e29b-41d4-a716-446655440000', messages: [] };
+  const r = ca.alignAnthropicBody(body);
+  assert.equal(r.applied, false);
+  assert.equal(r.body, body);
+  assert.deepEqual(r.findings.map((f) => f.kind), ['uuid']);
+});