nubos-pilot 1.3.0 → 1.3.2

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

@@ -1,9 +1,23 @@
 '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,
@@ -19,17 +33,27 @@ async function runAgentLoop(a) {
   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) messages.push({ role: 'system', content: String(systemPrompt) });
+  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 resp = await chat({ ...provider, messages, tools: schemas });
+    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 };
+      return { content: resp.content || '', iterations: i + 1, stopped: 'final', toolLog, compression };
     }
 
     messages.push({
@@ -46,9 +70,14 @@ async function runAgentLoop(a) {
     });
 
     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 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 });
     }
   }
 
@@ -58,6 +87,7 @@ async function runAgentLoop(a) {
     iterations: max,
     stopped: 'max-iterations',
     toolLog,
+    compression,
   };
 }
 

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

@@ -6,6 +6,16 @@ const assert = require('node:assert/strict');
 
 const { runAgentLoop, DEFAULT_MAX_ITERATIONS } = require('./agent-loop.cjs');
 const { toolsetFor } = require('./tools/index.cjs');
+const elision = require('../elision.cjs');
+
+function _bigLog() {
+  const lines = [];
+  for (let i = 0; i < 300; i++) {
+    if (i % 73 === 0) lines.push('ERROR: boom at module_' + i);
+    else lines.push('[info] step ' + i + ' ok processed record ' + (i * 7) + ' ' + 'x'.repeat(30));
+  }
+  return lines.join('\n');
+}
 
 const _dirs = [];
 function _ws(files) {
@@ -103,6 +113,73 @@ test('AL-6: DEFAULT_MAX_ITERATIONS is a sane positive cap', () => {
   assert.ok(DEFAULT_MAX_ITERATIONS >= 1 && DEFAULT_MAX_ITERATIONS <= 100);
 });
 
+test('AL-8: compression default OFF — tool result enters history verbatim, no blocks compressed', async () => {
+  const cwd = _ws({ 'log.txt': _bigLog() });
+  const chatImpl = _scriptedChat([
+    { toolCalls: [{ id: 't1', name: 'Read', arguments: '{"path":"log.txt"}' }] },
+    { content: 'done' },
+  ]);
+  const out = await runAgentLoop({
+    systemPrompt: 's', task: 't', cwd,
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl,
+  });
+  const toolMsg = chatImpl.seen[1].find((m) => m.role === 'tool');
+  assert.ok(!toolMsg.content.includes('⟦elided:'), 'no marker when compression off');
+  assert.equal(out.compression.blocks_compressed, 0);
+  assert.equal(out.compression.bytes_after, out.compression.bytes_before);
+});
+
+test('AL-9: compression ON — large tool result is crushed in history, original retrievable from Elision store', async () => {
+  const cwd = _ws({
+    'log.txt': _bigLog(),
+    '.nubos-pilot/config.json': JSON.stringify({ compression: { enabled: true } }),
+  });
+  const chatImpl = _scriptedChat([
+    { toolCalls: [{ id: 't1', name: 'Read', arguments: '{"path":"log.txt"}' }] },
+    { content: 'done' },
+  ]);
+  const out = await runAgentLoop({
+    systemPrompt: 's', task: 't', cwd,
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl,
+  });
+  const toolMsg = chatImpl.seen[1].find((m) => m.role === 'tool');
+  assert.equal(out.compression.blocks_compressed, 1);
+  assert.ok(out.compression.bytes_after < out.compression.bytes_before, 'history shrank');
+  const m = toolMsg.content.match(/⟦elided:([a-f0-9]{12})/);
+  assert.ok(m, 'marker with hash present in history');
+  const back = elision.retrieve(m[1], cwd);
+  assert.equal(back.status, 'ok');
+  assert.ok(back.original.includes('ERROR: boom at module_0'), 'original recoverable byte-for-byte');
+});
+
+test('AL-10: end-to-end — model retrieves an elided original mid-loop via context-expand', async () => {
+  const cwd = _ws({
+    'log.txt': _bigLog(),
+    '.nubos-pilot/config.json': JSON.stringify({ compression: { enabled: true } }),
+  });
+  let expanded = null;
+  const chat = async ({ messages }) => {
+    chat.n = (chat.n || 0) + 1;
+    if (chat.n === 1) {
+      return { content: '', finishReason: 'tool_calls', toolCalls: [{ id: 'r1', name: 'Read', arguments: '{"path":"log.txt"}' }] };
+    }
+    if (chat.n === 2) {
+      const toolMsg = messages.filter((m) => m.role === 'tool').pop();
+      const hash = toolMsg.content.match(/⟦elided:([a-f0-9]{12})/)[1];
+      return { content: '', finishReason: 'tool_calls', toolCalls: [{ id: 'r2', name: 'context-expand', arguments: JSON.stringify({ hash }) }] };
+    }
+    expanded = messages.filter((m) => m.role === 'tool').pop().content;
+    return { content: 'done', finishReason: 'stop', toolCalls: [] };
+  };
+  const out = await runAgentLoop({
+    systemPrompt: 's', task: 't', cwd,
+    toolset: toolsetFor(['Read'], { withExpand: true }), provider: { baseUrl: 'http://x/v1', model: 'm' }, chatImpl: chat,
+  });
+  assert.equal(out.stopped, 'final');
+  assert.ok(expanded.includes('ERROR: boom at module_0'), 'model recovered the full original byte-for-byte');
+  assert.ok(!expanded.includes('⟦elided:'), 'the expanded original carries no marker');
+});
+
 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 }) => {
@@ -133,3 +210,31 @@ test('AL-7: assistant echo is rebuilt in OpenAI wire shape; ids round-trip even
   const toolMsgs = secondTurn.filter((m) => m.role === 'tool');
   assert.deepEqual(toolMsgs.map((m) => m.tool_call_id), ['call_0', 'call_1']);
 });
+
+test('AL-12: output_steering ON — system prompt is enriched and mechanical turns downgrade effort', async () => {
+  const cwd = _ws({
+    'a.txt': 'A',
+    '.nubos-pilot/config.json': JSON.stringify({
+      compression: {
+        enabled: true,
+        output_steering: { enabled: true, verbosity_profile: 'terse', effort_routing: { enabled: true, base_effort: 'high', mechanical_effort: 'low' } },
+      },
+    }),
+  });
+  const seen = [];
+  const chatImpl = async (args) => {
+    seen.push({ effort: args.effort, system: (args.messages.find((m) => m.role === 'system') || {}).content });
+    if (seen.length === 1) {
+      return { content: '', finishReason: 'tool_calls', toolCalls: [{ id: 'c0', name: 'Read', arguments: '{"path":"a.txt"}' }], raw: { role: 'assistant', content: '' } };
+    }
+    return { content: 'done', toolCalls: [], finishReason: 'stop', raw: { role: 'assistant', content: 'done' } };
+  };
+  const out = await runAgentLoop({
+    systemPrompt: 'you are x', task: 't', cwd,
+    toolset: toolsetFor(['Read']), provider: { baseUrl: 'http://x/v1', model: 'm', effort: 'high' }, chatImpl,
+  });
+  assert.equal(out.stopped, 'final');
+  assert.match(seen[0].system, /<nubos_output_shaping>[\s\S]*<\/nubos_output_shaping>$/, 'system prompt carries the shaping block');
+  assert.equal(seen[0].effort, 'high', 'first turn (new user ask) keeps full effort');
+  assert.equal(seen[1].effort, 'low', 'second turn (clean tool result) downgrades to low');
+});

package/lib/runtime/dispatch.cjs

@@ -7,6 +7,7 @@ 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 elision = require('../elision.cjs');
 const { AUDITED_AGENTS, auditToolUse } = require('../nubosloop-audit.cjs');
 const { TASK_ID_RE } = require('../ids.cjs');
 const metrics = require('../metrics.cjs');
@@ -81,13 +82,17 @@ async function dispatchOffHost(o) {
 
   const src = loadSource(opts.agent, cwd);
   const declared = _parseTools(src.frontmatter && src.frontmatter.tools);
+  const cx = elision.compressionContext(cwd);
   const toolset = toolsetFor(declared, {
     readOnly: !!opts.readOnly,
     allowBash: !!opts.allowBash,
     withSearch: audited,
+    withExpand: cx.enabled,
     ctx: { taskId: hasTaskCtx ? opts.taskId : null, customRulesPath: opts.customRulesPath },
   });
   const provider = { baseUrl: res.baseUrl, apiKeyEnv: res.apiKeyEnv, model: res.model };
+  const _os = cx.outputSteering;
+  if (_os && _os.effortRouting && _os.baseEffort) provider.effort = _os.baseEffort;
 
   await preflight(provider);
 
@@ -140,12 +145,6 @@ async function dispatchOffHost(o) {
     } 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 = {
@@ -168,6 +167,7 @@ async function dispatchOffHost(o) {
     capability,
     output_lint: _lintOutput(result.content, opts.outputSchema),
     metrics_recorded: metricsRecorded,
+    compression: result.compression || null,
   };
 }
 

package/lib/runtime/dispatch.test.cjs

@@ -42,6 +42,23 @@ test('DSP-1: happy path returns the envelope and records a metrics row', async (
   assert.equal(rec.status, 'ok');
 });
 
+test('DSP-1c: provider.effort is seeded from base_effort only when effort routing is opted in', async () => {
+  const bare = _root();
+  let seenBare;
+  await dispatchOffHost({ agent: 'np-architect', task: 't', cwd: bare,
+    deps: _deps({ runLoop: async ({ provider }) => { seenBare = provider; return { content: 'x', stopped: 'final', iterations: 1, toolLog: [] }; } }) });
+  assert.equal(seenBare.effort, undefined, 'no effort field absent opt-in (providers without support unaffected)');
+
+  const on = _root();
+  fs.writeFileSync(path.join(on, '.nubos-pilot', 'config.json'), JSON.stringify({
+    compression: { enabled: true, output_steering: { enabled: true, effort_routing: { enabled: true, base_effort: 'high', mechanical_effort: 'low' } } },
+  }));
+  let seenOn;
+  await dispatchOffHost({ agent: 'np-architect', task: 't', cwd: on,
+    deps: _deps({ runLoop: async ({ provider }) => { seenOn = provider; return { content: 'x', stopped: 'final', iterations: 1, toolLog: [] }; } }) });
+  assert.equal(seenOn.effort, 'high', 'base_effort seeds the provider effort');
+});
+
 test('DSP-2: a native-kind agent is refused (dispatch-not-offhost)', async () => {
   const cwd = _root();
   const deps = _deps({ resolve: () => ({ kind: 'native', provider: 'claude', model: null, tier: 'opus' }) });
@@ -166,7 +183,6 @@ test('DSP-13: outputSchema lints the result and rides the envelope (null when un
 
 test('DSP-14: capability flags zero tool-calls despite an advertised toolset (tool-calling unsupported signal)', async () => {
   const cwd = _root();
-  // model made no tool calls but tools were advertised → not ok, mutating true (Write/Bash in toolset)
   const noTools = _deps({ runLoop: async () => ({ content: 'just text', stopped: 'final', iterations: 1, toolLog: [] }) });
   const out1 = await dispatchOffHost({ agent: 'np-architect', task: 't', cwd, deps: noTools });
   assert.equal(out1.capability.ok, false);
@@ -174,12 +190,10 @@ test('DSP-14: capability flags zero tool-calls despite an advertised toolset (to
   assert.ok(out1.capability.toolsAdvertised > 0);
   assert.equal(out1.capability.mutating, true);
 
-  // model used a tool → ok
   const usedTool = _deps({ runLoop: async () => ({ content: 'x', stopped: 'final', iterations: 2, toolLog: [{ name: 'Read', ok: true }] }) });
   const out2 = await dispatchOffHost({ agent: 'np-architect', task: 't', cwd, deps: usedTool });
   assert.equal(out2.capability.ok, true);
 
-  // read-only emitter with no tool calls → not ok but mutating false (softer hint)
   const ro = _deps({ runLoop: async () => ({ content: 'x', stopped: 'final', iterations: 1, toolLog: [] }) });
   const out3 = await dispatchOffHost({ agent: 'np-architect', task: 't', cwd, deps: ro, readOnly: true });
   assert.equal(out3.capability.ok, false);

package/lib/runtime/providers/openai-compat.cjs

@@ -31,7 +31,7 @@ function _parse(json) {
   };
 }
 
-async function chat({ baseUrl, apiKeyEnv, model, messages, tools, timeoutMs, fetchImpl, env }) {
+async function chat({ baseUrl, apiKeyEnv, model, messages, tools, effort, timeoutMs, fetchImpl, env }) {
   if (typeof baseUrl !== 'string' || !baseUrl) {
     throw new NubosPilotError('provider-no-base-url', 'openai-compat chat requires a base_url', {});
   }
@@ -61,6 +61,7 @@ async function chat({ baseUrl, apiKeyEnv, model, messages, tools, timeoutMs, fet
     body.tools = tools;
     body.tool_choice = 'auto';
   }
+  if (typeof effort === 'string' && effort) body.reasoning_effort = effort;
 
   const url = baseUrl.replace(/\/+$/, '') + '/chat/completions';
   const host = _hostOf(url);

package/lib/runtime/providers/openai-compat.test.cjs

@@ -49,6 +49,15 @@ test('OAC-3: chat POSTs to <base>/chat/completions with model + tools and parses
   assert.equal(out.content, 'hi');
 });
 
+test('OAC-3b: chat forwards effort as reasoning_effort only when set', async () => {
+  let captured = null;
+  const fetchImpl = async (_url, opts) => { captured = JSON.parse(opts.body); return _res({ json: { choices: [{ message: { content: 'ok' } }] } }); };
+  await chat({ baseUrl: 'http://x/v1', model: 'm', messages: [{ role: 'user', content: 'x' }], effort: 'low', fetchImpl });
+  assert.equal(captured.reasoning_effort, 'low', 'a set effort reaches the request body');
+  await chat({ baseUrl: 'http://x/v1', model: 'm', messages: [{ role: 'user', content: 'x' }], fetchImpl });
+  assert.ok(!('reasoning_effort' in captured), 'absent effort is never sent (providers without support unaffected)');
+});
+
 test('OAC-4: api_key_env adds a bearer header; missing key throws provider-missing-api-key', async () => {
   let auth = null;
   const fetchImpl = async (_url, opts) => { auth = opts.headers.authorization; return _res({ json: { choices: [{ message: { content: 'ok' } }] } }); };

package/lib/runtime/tools/index.cjs

@@ -8,6 +8,7 @@ const { assertInsideBase } = require('../../safe-path.cjs');
 const { scanContent, _looksCatastrophic } = require('../../security/scan.cjs');
 const { search: knowledgeSearch } = require('../../knowledge.cjs');
 const { recordSearchEvidence } = require('../../nubosloop-audit.cjs');
+const elision = require('../../elision.cjs');
 
 const MAX_FILE_BYTES = 1024 * 1024;
 const MAX_READ_LINES = 2000;
@@ -226,7 +227,35 @@ function _knowledgeSearch(args, ctx) {
   return hits.map((h) => h.rel_path + ':' + h.line_start + ' (score ' + h.score + ')\n  ' + String(h.preview || '').slice(0, 200)).join('\n');
 }
 
+function _contextExpand(args, ctx) {
+  const hash = args && args.hash;
+  if (typeof hash !== 'string' || !hash) throw new NubosPilotError('tool-bad-args', 'context-expand requires a "hash"', {});
+  const res = elision.retrieve(hash, ctx && ctx.cwd);
+  if (res.status === 'ok') return res.original;
+  if (res.status === 'expired') {
+    return 'Error: context-expand: marker ' + hash + ' has expired (its retention window elapsed) and is no longer retrievable';
+  }
+  return 'Error: context-expand: no stored original for ' + hash;
+}
+
 const TOOLS = {
+  'context-expand': {
+    run: _contextExpand,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'context-expand',
+        description: 'Retrieve the full original text behind a ⟦elided:<hash>⟧ marker that appeared in an earlier tool result (large outputs are compressed in place). Pass the 12-char hash. Only call this when you actually need the elided detail.',
+        parameters: {
+          type: 'object',
+          properties: {
+            hash: { type: 'string', description: 'The 12-character hash from a ⟦elided:<hash>⟧ marker.' },
+          },
+          required: ['hash'],
+        },
+      },
+    },
+  },
   'knowledge-search': {
     run: _knowledgeSearch,
     schema: {
@@ -359,7 +388,8 @@ const TOOLS = {
 const READ_ONLY_TOOL_NAMES = Object.freeze(['Read', 'Glob', 'Grep']);
 const MUTATING_TOOL_NAMES = Object.freeze(['Write', 'Edit']);
 const SEARCH_TOOL_NAME = 'knowledge-search';
-const IMPLEMENTED_TOOL_NAMES = Object.freeze([...READ_ONLY_TOOL_NAMES, ...MUTATING_TOOL_NAMES, 'Bash', SEARCH_TOOL_NAME]);
+const EXPAND_TOOL_NAME = 'context-expand';
+const IMPLEMENTED_TOOL_NAMES = Object.freeze([...READ_ONLY_TOOL_NAMES, ...MUTATING_TOOL_NAMES, 'Bash', SEARCH_TOOL_NAME, EXPAND_TOOL_NAME]);
 
 function toolsetFor(declaredNames, opts) {
   const o = opts || {};
@@ -371,6 +401,7 @@ function toolsetFor(declaredNames, opts) {
   }
   const names = declared.filter((n) => allowed.includes(n));
   if (o.withSearch && !names.includes(SEARCH_TOOL_NAME)) names.push(SEARCH_TOOL_NAME);
+  if (o.withExpand && !names.includes(EXPAND_TOOL_NAME)) names.push(EXPAND_TOOL_NAME);
   const extraCtx = o.ctx || {};
   return {
     names,
@@ -407,6 +438,7 @@ module.exports = {
   READ_ONLY_TOOL_NAMES,
   MUTATING_TOOL_NAMES,
   SEARCH_TOOL_NAME,
+  EXPAND_TOOL_NAME,
   IMPLEMENTED_TOOL_NAMES,
   BASH_DENYLIST,
   toolsetFor,

package/lib/runtime/tools/index.test.cjs

@@ -228,3 +228,27 @@ test('TOOL-29: knowledge-search records search evidence when a taskId is in ctx'
   const { searchEvidenceForRound } = require('../../nubosloop-audit.cjs');
   assert.ok(searchEvidenceForRound(taskId, 1, cwd).length > 0, 'evidence must be recorded for the round');
 });
+
+test('TOOL-30: withExpand injects context-expand only on demand', () => {
+  assert.ok(!toolsetFor(['Read']).names.includes('context-expand'));
+  const ts = toolsetFor(['Read'], { withExpand: true });
+  assert.ok(ts.names.includes('context-expand'));
+  assert.ok(ts.schemas.some((s) => s.function.name === 'context-expand'));
+});
+
+test('TOOL-31: context-expand returns the stored original for a known hash, error for unknown', () => {
+  const elision = require('../../elision.cjs');
+  const cwd = _ws({});
+  const original = 'the full uncompressed tool output\nwith many lines\n'.repeat(20);
+  const hash = elision.store(original, { type: 'log' }, cwd);
+  const ts = toolsetFor(['Read'], { withExpand: true });
+  assert.equal(ts.execute('context-expand', { hash }, { cwd }), original);
+  assert.match(ts.execute('context-expand', { hash: 'ffffffffffff' }, { cwd }), /no stored original/);
+  assert.match(ts.execute('context-expand', {}, { cwd }), /requires a "hash"/);
+});
+
+test('TOOL-32: context-expand is not callable unless it was injected (allow-list)', () => {
+  const cwd = _ws({});
+  const ts = toolsetFor(['Read']);
+  assert.match(ts.execute('context-expand', { hash: 'aaaaaaaaaaaa' }, { cwd }), /not available to this agent/);
+});

package/lib/schemas/data/elision-entry.v1.json

@@ -0,0 +1,16 @@
+{
+  "$id": "elision-entry.v1",
+  "title": "Elision cache entry (.nubos-pilot/elision/<hash>.json)",
+  "type": "object",
+  "required": ["version", "hash", "original", "type", "created_at", "ttl_ms", "original_bytes", "compressed_bytes"],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{12}$" },
+    "original": { "type": "string", "maxBytes": 8388608 },
+    "type": { "type": "string", "maxBytes": 64 },
+    "created_at": { "type": "string" },
+    "ttl_ms": { "type": "integer", "minimum": 0 },
+    "original_bytes": { "type": "integer", "minimum": 0 },
+    "compressed_bytes": { "type": "integer", "minimum": 0 }
+  }
+}

package/lib/token-cost.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+const DEFAULT_CHARS_PER_TOKEN = 4;
+
+function _round(n) {
+  return Number.isFinite(n) ? Math.round(n) : 0;
+}
+
+function estimateTokens(bytes, charsPerToken) {
+  const cpt = Number.isFinite(charsPerToken) && charsPerToken > 0 ? charsPerToken : DEFAULT_CHARS_PER_TOKEN;
+  return Math.max(0, _round((Number(bytes) || 0) / cpt));
+}
+
+function estimateCost(tokens, pricePerMTok) {
+  if (!Number.isFinite(pricePerMTok) || pricePerMTok <= 0) return null;
+  return (Number(tokens) || 0) / 1e6 * pricePerMTok;
+}
+
+function summarizeSavings(opts) {
+  const o = opts || {};
+  const before = Number(o.bytesBefore) || 0;
+  const after = Number(o.bytesAfter) || 0;
+  const bytesSaved = Math.max(0, before - after);
+  const cpt = Number.isFinite(o.charsPerToken) && o.charsPerToken > 0 ? o.charsPerToken : DEFAULT_CHARS_PER_TOKEN;
+  const tokensSaved = estimateTokens(bytesSaved, cpt);
+  const cost = estimateCost(tokensSaved, o.pricePerMTok);
+  const out = {
+    bytes_saved: bytesSaved,
+    chars_per_token: cpt,
+    tokens_saved_est: tokensSaved,
+    saved_pct: before ? Math.round((bytesSaved / before) * 100) : 0,
+  };
+  if (cost !== null) {
+    out.price_per_mtok = o.pricePerMTok;
+    out.currency = typeof o.currency === 'string' && o.currency ? o.currency : 'USD';
+    out.cost_saved_est = Math.round(cost * 10000) / 10000;
+  }
+  return out;
+}
+
+module.exports = {
+  DEFAULT_CHARS_PER_TOKEN,
+  estimateTokens,
+  estimateCost,
+  summarizeSavings,
+};

package/lib/token-cost.test.cjs

@@ -0,0 +1,42 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const tc = require('./token-cost.cjs');
+
+test('TC-1: estimateTokens uses chars-per-token and defaults sanely', () => {
+  assert.equal(tc.estimateTokens(4000, 4), 1000);
+  assert.equal(tc.estimateTokens(4000), 1000);
+  assert.equal(tc.estimateTokens(0, 4), 0);
+  assert.equal(tc.estimateTokens(100, 0), 25);
+});
+
+test('TC-2: estimateCost returns null without a positive price', () => {
+  assert.equal(tc.estimateCost(1_000_000, null), null);
+  assert.equal(tc.estimateCost(1_000_000, 0), null);
+  assert.equal(tc.estimateCost(1_000_000, 3), 3);
+});
+
+test('TC-3: summarizeSavings reports tokens only when no price is given', () => {
+  const s = tc.summarizeSavings({ bytesBefore: 8000, bytesAfter: 2000, charsPerToken: 4 });
+  assert.equal(s.bytes_saved, 6000);
+  assert.equal(s.tokens_saved_est, 1500);
+  assert.equal(s.saved_pct, 75);
+  assert.equal(s.cost_saved_est, undefined, 'no cost without a price');
+  assert.equal(s.currency, undefined);
+});
+
+test('TC-4: summarizeSavings adds a cost estimate + currency when priced', () => {
+  const s = tc.summarizeSavings({ bytesBefore: 8000, bytesAfter: 2000, charsPerToken: 4, pricePerMTok: 3, currency: 'EUR' });
+  assert.equal(s.tokens_saved_est, 1500);
+  assert.equal(s.cost_saved_est, 0.0045);
+  assert.equal(s.currency, 'EUR');
+  assert.equal(s.price_per_mtok, 3);
+});
+
+test('TC-5: never negative when output is somehow larger than input', () => {
+  const s = tc.summarizeSavings({ bytesBefore: 100, bytesAfter: 400 });
+  assert.equal(s.bytes_saved, 0);
+  assert.equal(s.tokens_saved_est, 0);
+});

package/np-tools.cjs

@@ -91,6 +91,8 @@ const topLevelCommands = {
   'knowledge-index':  require('./bin/np-tools/knowledge-index.cjs'),
   'knowledge-search': require('./bin/np-tools/knowledge-search.cjs'),
   'knowledge-stats':  require('./bin/np-tools/knowledge-stats.cjs'),
+  'elision-get':      require('./bin/np-tools/elision-get.cjs'),
+  'elision-bench':    require('./bin/np-tools/elision-bench.cjs'),
   'context-stats':    require('./bin/np-tools/context-stats.cjs'),
   'session-snapshot-write': require('./bin/np-tools/session-snapshot-write.cjs'),
   'session-snapshot-read':  require('./bin/np-tools/session-snapshot-read.cjs'),