@semalt-ai/code 1.8.5 → 1.20.0

package/test/harness/mock-mcp-server.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+
+// Mock MCP server over stdio (Task 3.3).
+// ----------------------------------------------------------------------------
+// A tiny, dependency-free, spec-correct MCP server the tests spawn as a local
+// subprocess (no network). It speaks newline-delimited JSON-RPC 2.0 on
+// stdin/stdout — exactly the framing `StdioClientTransport` reads — so the REAL
+// MCP SDK client connects to it and the whole discovery/dispatch path is
+// exercised against a deterministic peer.
+//
+// Implemented methods: `initialize`, `notifications/initialized` (ignored),
+// `tools/list`, `tools/call`, `ping`. It deliberately does NOT depend on the
+// SDK server classes (which require zod schemas) — the raw protocol is ~60
+// lines and keeps the test self-contained and reproducible.
+//
+// Behavior knobs (env vars, so a test can script edge cases):
+//   MOCK_MCP_NAME           server name advertised in initialize (default "mock")
+//   MOCK_MCP_EXIT_ON_START  if set, exit(1) immediately — simulates a server
+//                           that dies on launch (graceful-degradation test).
+//
+// Tools exposed:
+//   echo  { text }       → returns the text back (untrusted-content payloads
+//                          can be injected here to test the delimiter).
+//   add   { a, b }       → returns a+b.
+//   boom  {}             → returns an MCP tool-level error (isError: true).
+
+const SERVER_NAME = process.env.MOCK_MCP_NAME || 'mock';
+
+const TOOLS = [
+  {
+    name: 'echo',
+    description: 'Echo the provided text back verbatim.',
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string', description: 'Text to echo' } },
+      required: ['text'],
+    },
+  },
+  {
+    name: 'add',
+    description: 'Add two numbers and return the sum.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        a: { type: 'number', description: 'First addend' },
+        b: { type: 'number', description: 'Second addend' },
+      },
+      required: ['a', 'b'],
+    },
+  },
+  {
+    name: 'boom',
+    description: 'Always reports a tool-level error.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+function ok(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function err(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+function callTool(name, args) {
+  if (name === 'echo') {
+    return { content: [{ type: 'text', text: String((args && args.text) ?? '') }] };
+  }
+  if (name === 'add') {
+    const sum = Number((args && args.a) || 0) + Number((args && args.b) || 0);
+    return { content: [{ type: 'text', text: String(sum) }] };
+  }
+  if (name === 'boom') {
+    return { content: [{ type: 'text', text: 'the boom tool failed as designed' }], isError: true };
+  }
+  return null; // unknown tool
+}
+
+function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === 'initialize') {
+    // Echo the client's requested protocol version — by definition one the
+    // client supports — and advertise the tools capability.
+    ok(id, {
+      protocolVersion: (params && params.protocolVersion) || '2025-06-18',
+      capabilities: { tools: {} },
+      serverInfo: { name: SERVER_NAME, version: '1.0.0' },
+    });
+    return;
+  }
+  if (method === 'notifications/initialized') return; // notification, no reply
+  if (method === 'ping') { ok(id, {}); return; }
+  if (method === 'tools/list') { ok(id, { tools: TOOLS }); return; }
+  if (method === 'tools/call') {
+    const name = params && params.name;
+    const result = callTool(name, params && params.arguments);
+    if (!result) { err(id, -32602, `Unknown tool: ${name}`); return; }
+    ok(id, result);
+    return;
+  }
+  if (id !== undefined) err(id, -32601, `Method not found: ${method}`);
+}
+
+function run() {
+  // Behavior knob: simulate a server that dies on launch (degradation test).
+  if (process.env.MOCK_MCP_EXIT_ON_START) {
+    process.stderr.write('mock-mcp-server: simulated startup failure\n');
+    process.exit(1);
+  }
+  let buffer = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      try { handle(msg); } catch (e) {
+        if (msg && msg.id !== undefined) err(msg.id, -32603, e.message);
+      }
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+}
+
+// Only attach the stdin server loop when spawned directly (as the MCP client
+// does). The Node test runner discovers and EXECUTES every file under test/ —
+// including this one — each in a child process where `require.main === module`
+// is also true. It sets NODE_TEST_CONTEXT in that child, so we use its ABSENCE
+// (plus require.main) to mean "spawned as a real MCP server"; otherwise this
+// stdin loop would hang the test runner forever waiting on input.
+if (require.main === module && !process.env.NODE_TEST_CONTEXT) run();
+

package/test/harness/sse-server.js

@@ -0,0 +1,69 @@
+'use strict';
+
+// Minimal scriptable SSE server for streaming-parser tests (Task 1.1).
+// Task 1.2 extends this into the full mock-LLM harness (queues, status codes,
+// Retry-After, delays); for now it serves one scripted response per request.
+//
+// Usage:
+//   const srv = await startSseServer({ chunks: ['data: {...}\n', 'data: [DONE]\n'] });
+//   // point config.api_base at srv.base, make the request, then:
+//   await srv.close();
+
+const http = require('http');
+
+// opts:
+//   chunks   string[] — written sequentially (with a tiny gap) so the client's
+//            cross-chunk line buffering is genuinely exercised. A single string
+//            is also accepted and sent as one chunk.
+//   status   HTTP status code (default 200).
+//   headers  extra response headers (merged over the SSE defaults).
+//   gapMs    delay between chunks (default 4ms).
+function startSseServer(opts = {}) {
+  const status = opts.status || 200;
+  const gapMs = opts.gapMs == null ? 4 : opts.gapMs;
+  const chunks = Array.isArray(opts.chunks)
+    ? opts.chunks
+    : [opts.body != null ? opts.body : ''];
+
+  const server = http.createServer((req, res) => {
+    // Drain the request body before responding.
+    req.resume();
+    req.on('end', () => {
+      res.writeHead(status, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        ...(opts.headers || {}),
+      });
+      let i = 0;
+      const writeNext = () => {
+        if (i >= chunks.length) { res.end(); return; }
+        res.write(chunks[i++]);
+        if (gapMs > 0) setTimeout(writeNext, gapMs);
+        else writeNext();
+      };
+      writeNext();
+    });
+  });
+
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolve({
+        server,
+        port,
+        base: `http://127.0.0.1:${port}`,
+        close: () => new Promise((r) => server.close(r)),
+      });
+    });
+  });
+}
+
+// Build a `data: {json}\n` SSE line.
+function sse(obj) {
+  return `data: ${JSON.stringify(obj)}\n`;
+}
+
+const DONE = 'data: [DONE]\n';
+
+module.exports = { startSseServer, sse, DONE };

package/test/headless.test.js

@@ -0,0 +1,348 @@
+'use strict';
+
+// Headless output tests (Task 2.4). Drives the REAL runAgentLoop against the
+// mock LLM through runHeadless in each output mode, capturing stdout. Proves:
+//   * json   → a single JSON object { result, toolCalls, usage, cost }
+//   * stream-json → newline-delimited JSON events (assistant / tool / result)
+//   * machine modes are byte-pure: no ANSI escapes leak, even though a tool runs
+//     (write_file's green ✓ and the permission diff would otherwise print).
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ui = require('../lib/ui');
+const { createApiClient } = require('../lib/api');
+const { createToolExecutor, extractToolCalls } = require('../lib/tools');
+const { createPermissionManager } = require('../lib/permissions');
+const { createAgentRunner } = require('../lib/agent');
+const { startMockLLM } = require('./harness/mock-llm');
+const { runHeadless, usageFromMetrics, finalResult, isMachineMode, createHeadlessSink } = require('../lib/headless');
+
+let prevKey;
+let CWD;
+let PREV_CWD;
+before(() => {
+  prevKey = process.env.SEMALT_API_KEY; process.env.SEMALT_API_KEY = 'test-key';
+  PREV_CWD = process.cwd();
+  CWD = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-headless-')));
+  process.chdir(CWD);
+});
+after(() => {
+  process.chdir(PREV_CWD);
+  if (prevKey === undefined) delete process.env.SEMALT_API_KEY; else process.env.SEMALT_API_KEY = prevKey;
+});
+
+function buildRunner(base) {
+  const config = {
+    api_base: base, api_key: 'test-key', default_model: 'test-model',
+    temperature: 0.5, request_timeout_ms: 5000, stream: true, models: [],
+  };
+  const getConfig = () => config;
+  const saveConfig = () => {};
+  const api = createApiClient({ getConfig, saveConfig, ui });
+  const pm = createPermissionManager(ui, { skipPermissions: true });
+  pm.setUICallbacks({ onAddMessage: () => {}, onShowModal: () => {}, onCloseModal: () => {}, onCaptureNavigation: () => () => {} });
+  const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(pm, ui, getConfig);
+  return createAgentRunner({
+    chatStream: api.chatStream, extractToolCalls, agentExecShell, agentExecFile,
+    describePermission, permissionManager: pm, ui, getConfig,
+  });
+}
+
+// Capture the headless JSON via the injectable `write` sink — no global stdout
+// swap (which would collide with the node:test TAP reporter). Chrome is
+// suppressed inside runHeadless via setUIActive, so the sink receives ONLY the
+// structured output.
+async function runCapture(mode, runner, messages) {
+  const chunks = [];
+  const res = await runHeadless({
+    runAgentLoop: runner.runAgentLoop,
+    messages, model: 'test-model', mode, maxIterations: 10,
+    agentOpts: { systemPromptMode: 'system_role' },
+    write: (s) => { chunks.push(typeof s === 'string' ? s : s.toString('utf8')); return true; },
+  });
+  return { out: chunks.join(''), res };
+}
+
+const HAS_ANSI = (s) => /\x1b\[/.test(s);
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+test('usageFromMetrics aggregates turns', () => {
+  const metrics = { turns: [
+    { promptTokens: 10, completionTokens: 4 },
+    { promptTokens: 20, completionTokens: 6 },
+  ] };
+  assert.deepStrictEqual(usageFromMetrics(metrics), {
+    prompt_tokens: 30, completion_tokens: 10, total_tokens: 40, context_tokens: 20,
+    context_base_est: 0, context_working_est: 0, turns: 2,
+  });
+});
+
+test('finalResult returns the last assistant message', () => {
+  const messages = [
+    { role: 'user', content: 'hi' },
+    { role: 'assistant', content: 'first' },
+    { role: 'user', content: 'tool results' },
+    { role: 'assistant', content: 'final answer' },
+  ];
+  assert.strictEqual(finalResult(messages, []), 'final answer');
+});
+
+test('isMachineMode classifies the formats', () => {
+  assert.strictEqual(isMachineMode('json'), true);
+  assert.strictEqual(isMachineMode('stream-json'), true);
+  assert.strictEqual(isMachineMode('text'), false);
+});
+
+// ---------------------------------------------------------------------------
+// json mode
+// ---------------------------------------------------------------------------
+
+test('json mode prints exactly one JSON object with the documented shape', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<write_file path="hl.txt">hi</write_file>', { usage: { prompt_tokens: 30, completion_tokens: 10 } });
+  mock.replyWith('Wrote it.', { usage: { prompt_tokens: 12, completion_tokens: 7 } });
+  try {
+    const runner = buildRunner(mock.base);
+    const { out } = await runCapture('json', runner, [{ role: 'user', content: 'write a file' }]);
+
+    assert.ok(!HAS_ANSI(out), 'no ANSI escapes leak into json stdout');
+    const lines = out.split('\n').filter((l) => l.trim());
+    assert.strictEqual(lines.length, 1, 'exactly one line of output');
+    const obj = JSON.parse(lines[0]);
+    assert.deepStrictEqual(Object.keys(obj).sort(), ['cost', 'result', 'stopReason', 'toolCalls', 'usage', 'verifyStatus']);
+    assert.strictEqual(obj.result, 'Wrote it.');
+    assert.strictEqual(obj.stopReason, 'end_turn', 'natural completion reports end_turn');
+    assert.strictEqual(obj.verifyStatus, 'skipped', 'no verify command configured → skipped');
+    assert.strictEqual(obj.cost, null);
+    assert.strictEqual(obj.usage.total_tokens, 59); // 30+10 (tool turn) + 12+7 (final)
+    assert.strictEqual(obj.usage.turns, 2);
+    assert.strictEqual(obj.toolCalls.length, 1, 'the write_file tool call is recorded');
+    assert.strictEqual(obj.toolCalls[0].tool, 'write');
+    assert.deepStrictEqual(obj.toolCalls[0].args, ['hl.txt', 'hi']);
+    assert.strictEqual(obj.toolCalls[0].ok, true);
+    assert.strictEqual(fs.readFileSync(path.join(CWD, 'hl.txt'), 'utf8'), 'hi', 'tool actually executed');
+  } finally {
+    await mock.close();
+  }
+});
+
+test('json mode computes cost from the price table when the model is priced', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('Answer.', { usage: { prompt_tokens: 1_000_000, completion_tokens: 1_000_000 } });
+  try {
+    const runner = buildRunner(mock.base);
+    const chunks = [];
+    await runHeadless({
+      runAgentLoop: runner.runAgentLoop, messages: [{ role: 'user', content: 'q' }],
+      model: 'test-model', mode: 'json', maxIterations: 10,
+      agentOpts: { systemPromptMode: 'system_role' },
+      priceOverrides: { 'test-model': { input: 2, output: 8 } }, // per Mtok
+      write: (s) => { chunks.push(s); return true; },
+    });
+    const obj = JSON.parse(chunks.join('').trim());
+    assert.strictEqual(obj.cost, 10, '1M in × $2 + 1M out × $8 = $10');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// stream-json mode
+// ---------------------------------------------------------------------------
+
+test('stream-json mode emits valid NDJSON events (assistant / tool / result)', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<write_file path="s.txt">x</write_file>', { usage: { prompt_tokens: 3, completion_tokens: 1 } });
+  mock.replyWith('Done streaming.', { usage: { prompt_tokens: 5, completion_tokens: 2 } });
+  try {
+    const runner = buildRunner(mock.base);
+    const { out } = await runCapture('stream-json', runner, [{ role: 'user', content: 'go' }]);
+
+    assert.ok(!HAS_ANSI(out), 'no ANSI escapes leak into stream-json stdout');
+    const events = out.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+    const types = events.map((e) => e.type);
+    assert.ok(types.includes('tool'), 'a tool event was emitted');
+    assert.ok(types.includes('result'), 'a terminal result event was emitted');
+    assert.strictEqual(types[types.length - 1], 'result', 'result is last');
+
+    const toolEvent = events.find((e) => e.type === 'tool');
+    assert.strictEqual(toolEvent.tool, 'write');
+    assert.deepStrictEqual(toolEvent.args, ['s.txt', 'x']);
+
+    const resultEvent = events[events.length - 1];
+    assert.strictEqual(resultEvent.result, 'Done streaming.');
+    assert.strictEqual(resultEvent.cost, null);
+    assert.strictEqual(resultEvent.usage.total_tokens, 11); // 3+1 + 5+2
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// text mode does not emit machine output
+// ---------------------------------------------------------------------------
+
+test('text mode returns the loop result and emits no JSON envelope', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('Just a plain answer.');
+  try {
+    const runner = buildRunner(mock.base);
+    const { out, res } = await runCapture('text', runner, [{ role: 'user', content: 'hello' }]);
+    assert.ok(res && Array.isArray(res.messages), 'runHeadless returns the loop result');
+    assert.ok(!/"result"\s*:/.test(out), 'text mode does not print a json result envelope');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Phase 6d-ii — descriptor-derived ADDITIVE enrichment of per-tool recs
+// ---------------------------------------------------------------------------
+
+// The legacy fields every per-tool rec MUST carry byte-identically (names,
+// types, values) — the public contract pin guarded by the characterization test.
+const LEGACY_KEYS = ['tool', 'args', 'ok', 'ms'];
+// The descriptor-derived fields 6d-ii adds. Present additively; never replace a
+// legacy field. (`tag`/`noDuration`/`error` also ride along from the core.)
+const ENRICHED_KEYS = ['status', 'category', 'durationMs', 'detail', 'meta', 'target', 'attrs'];
+
+// THE GUARD (§4.1) — characterizes a representative run end-to-end: legacy fields
+// stay byte-identical in the stream {type:'tool'} event AND the toolCalls[] entry;
+// the additive enriched fields are present with correct values; and the FINALIZE
+// top-level key-set is byte-identical (no new top-level finalize key).
+test('per-tool recs are additively enriched; legacy + finalize key-sets unchanged', async () => {
+  const mock = await startMockLLM();
+  // Two runs below (json + stream-json); the FIFO queue needs a pair each.
+  mock.replyWith('<write_file path="enrich.txt">hi</write_file>', { usage: { prompt_tokens: 3, completion_tokens: 1 } });
+  mock.replyWith('Done.', { usage: { prompt_tokens: 2, completion_tokens: 1 } });
+  mock.replyWith('<write_file path="enrich.txt">hi</write_file>', { usage: { prompt_tokens: 3, completion_tokens: 1 } });
+  mock.replyWith('Done.', { usage: { prompt_tokens: 2, completion_tokens: 1 } });
+  try {
+    const runner = buildRunner(mock.base);
+    // json mode → finalize object with toolCalls[]; stream-json → tool events.
+    const { out: jsonOut } = await runCapture('json', runner, [{ role: 'user', content: 'go' }]);
+    const finalObj = JSON.parse(jsonOut.split('\n').filter((l) => l.trim())[0]);
+
+    // Finalize top-level key-set BYTE-IDENTICAL (no new top-level key from 6d-ii).
+    assert.deepStrictEqual(
+      Object.keys(finalObj).sort(),
+      ['cost', 'result', 'stopReason', 'toolCalls', 'usage', 'verifyStatus'],
+    );
+
+    const arrEntry = finalObj.toolCalls[0];
+    // Legacy fields byte-identical in the toolCalls[] entry.
+    assert.strictEqual(arrEntry.tool, 'write');
+    assert.deepStrictEqual(arrEntry.args, ['enrich.txt', 'hi']);
+    assert.strictEqual(arrEntry.ok, true);
+    assert.strictEqual(typeof arrEntry.ms, 'number');
+    // Enriched fields present with correct values.
+    for (const k of ENRICHED_KEYS) assert.ok(k in arrEntry, `toolCalls entry has additive ${k}`);
+    assert.strictEqual(arrEntry.status, 'ok');
+    assert.strictEqual(arrEntry.category, 'file');
+    assert.strictEqual(arrEntry.target, 'enrich.txt');
+    assert.strictEqual(arrEntry.durationMs, arrEntry.ms, 'durationMs mirrors ms');
+    assert.strictEqual(arrEntry.detail.kind, 'diff', 'write carries a structured diff detail');
+    assert.strictEqual(arrEntry.detail.payload.after, 'hi');
+    // toolCalls[] entry must NOT carry the stream-only `type` tag.
+    assert.ok(!('type' in arrEntry), 'array entry has no type tag');
+
+    const { out: streamOut } = await runCapture('stream-json', runner, [{ role: 'user', content: 'go' }]);
+    const events = streamOut.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+    const toolEvent = events.find((e) => e.type === 'tool');
+    // Same enriched rec in the stream event (plus type:'tool').
+    assert.strictEqual(toolEvent.type, 'tool');
+    assert.strictEqual(toolEvent.tool, 'write');
+    assert.deepStrictEqual(toolEvent.args, ['enrich.txt', 'hi']);
+    assert.strictEqual(toolEvent.ok, true);
+    for (const k of ENRICHED_KEYS) assert.ok(k in toolEvent, `stream tool event has additive ${k}`);
+    assert.strictEqual(toolEvent.category, 'file');
+    assert.strictEqual(toolEvent.detail.kind, 'diff');
+  } finally {
+    await mock.close();
+  }
+});
+
+// §4.2 — enrichment correctness for an ERROR case: status reflects the error,
+// durationMs mirrors ms, category is correct, no detail on errors. Driven through
+// the sink directly so the meta shape (incl. error) is exact and deterministic.
+test('error op enriches with status:error and no detail; legacy ok:false preserved', () => {
+  const lines = [];
+  const sink = createHeadlessSink('stream-json', (o) => lines.push(o));
+  // shell op with non-zero exit → meta.error present (mirrors agent.js).
+  sink.callbacks.onToolEnd('exec', 'Command `false`:\nExit code: 3\n', 7, {
+    id: 1, call: ['exec', 'false'], attrs: { command: 'false' },
+    meta: { exit_code: 3 }, error: { message: 'exit 3', code: 3 },
+  });
+  const event = lines.find((e) => e.type === 'tool');
+  const arrEntry = sink.toolCalls[0];
+  for (const rec of [event, arrEntry]) {
+    assert.strictEqual(rec.tool, 'exec');           // legacy byte-identical
+    assert.deepStrictEqual(rec.args, ['false']);
+    assert.strictEqual(rec.ok, false);              // legacy ok reflects error
+    assert.strictEqual(rec.ms, 7);
+    assert.strictEqual(rec.status, 'error');        // enriched status reflects error
+    assert.strictEqual(rec.durationMs, 7);          // mirrors ms
+    assert.strictEqual(rec.category, 'shell');
+    assert.strictEqual(rec.detail, null);           // errors carry no detail
+    assert.deepStrictEqual(rec.error, { message: 'exit 3', code: 3 });
+  }
+});
+
+// §4.3 — web stays per-op: web_search + http_get emit N enriched {type:'tool'}
+// events, NO collapsed web summary (the headless rail must not import the
+// web-activity collapse). Driven through the sink so no real network is needed.
+test('web ops emit N per-op enriched events (no collapse)', () => {
+  const lines = [];
+  const sink = createHeadlessSink('stream-json', (o) => lines.push(o));
+  sink.callbacks.onToolEnd('web_search', 'results…', 4, {
+    id: 1, call: ['web_search', 'cats'], attrs: { query: 'cats' }, meta: null, error: null,
+  });
+  sink.callbacks.onToolEnd('http_get', 'page body', 9, {
+    id: 2, call: ['http_get', 'https://x.test'], attrs: { url: 'https://x.test' },
+    meta: { status_code: 200 }, error: null,
+  });
+  const toolEvents = lines.filter((e) => e.type === 'tool');
+  assert.strictEqual(toolEvents.length, 2, 'two per-op tool events, not one summary');
+  assert.strictEqual(sink.toolCalls.length, 2, 'two per-op entries in toolCalls[]');
+  assert.strictEqual(toolEvents[0].tool, 'web_search');
+  assert.strictEqual(toolEvents[1].tool, 'http_get');
+  assert.strictEqual(toolEvents[1].category, 'net', 'http_get is category net');
+  assert.strictEqual(toolEvents[1].target, 'https://x.test');
+  // No collapsed web-summary event leaked into the stream.
+  assert.ok(!lines.some((e) => e.type === 'web' || e.type === 'web-summary'), 'no collapsed web summary');
+});
+
+// §4.4 — abort / no-descriptor safety: an aborted op (meta.error present, no diff)
+// emits a valid enriched event with status:error and never crashes; a totally
+// missing meta still produces a valid event (buildToolOperation defaults every
+// field, so it never throws) with the legacy fields intact — and if a descriptor
+// genuinely can't be built the bare legacy-only rec is the floor.
+test('aborted op is safe and enriched; missing meta still yields a valid event', () => {
+  const lines = [];
+  const sink = createHeadlessSink('stream-json', (o) => lines.push(o));
+  // Aborted op (mirrors agent.js abort path: meta:null, error:{message:'aborted'}).
+  sink.callbacks.onToolEnd('exec', 'User interrupted…', 5, {
+    id: 1, call: ['exec', 'sleep 100'], attrs: { command: 'sleep 100' },
+    meta: null, error: { message: 'aborted' },
+  });
+  const aborted = lines.find((e) => e.type === 'tool');
+  assert.strictEqual(aborted.ok, false);
+  assert.strictEqual(aborted.status, 'error');
+  assert.strictEqual(aborted.category, 'shell');
+
+  // No meta at all → still a valid event, no crash; legacy fields intact.
+  sink.callbacks.onToolEnd('weird_tool', 'x', 1, null);
+  const bare = lines.filter((e) => e.type === 'tool')[1];
+  assert.strictEqual(bare.tool, 'weird_tool');
+  assert.deepStrictEqual(bare.args, []);
+  assert.strictEqual(bare.ok, true);
+  assert.strictEqual(bare.ms, 1);
+  assert.strictEqual(bare.type, 'tool');
+});

package/test/history-utils.test.js

@@ -0,0 +1,88 @@
+'use strict';
+
+// Unit tests for the pure history helpers extracted in Task 1.5.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+const { cleanOrphanedToolMessages, reconstructLoadedMessage } = require('../lib/commands/history-utils');
+
+test('cleanOrphanedToolMessages keeps fully-paired tool calls/results', () => {
+  const msgs = [
+    { role: 'user', content: 'hi' },
+    { role: 'assistant', content: '', tool_calls: [{ id: 'a', type: 'function', function: { name: 'read', arguments: '{}' } }] },
+    { role: 'tool', tool_call_id: 'a', content: 'result' },
+  ];
+  const r = cleanOrphanedToolMessages(msgs);
+  assert.deepStrictEqual(r.messages, msgs);
+  assert.strictEqual(r.droppedTool, 0);
+  assert.strictEqual(r.droppedAssistantCalls, 0);
+  assert.strictEqual(r.droppedAssistantMsgs, 0);
+});
+
+test('drops a tool result with no matching tool_call', () => {
+  const msgs = [
+    { role: 'user', content: 'hi' },
+    { role: 'tool', tool_call_id: 'orphan', content: 'x' },
+  ];
+  const r = cleanOrphanedToolMessages(msgs);
+  assert.deepStrictEqual(r.messages, [{ role: 'user', content: 'hi' }]);
+  assert.strictEqual(r.droppedTool, 1);
+});
+
+test('drops a tool result with empty/missing tool_call_id', () => {
+  const r = cleanOrphanedToolMessages([{ role: 'tool', tool_call_id: '', content: 'x' }]);
+  assert.strictEqual(r.messages.length, 0);
+  assert.strictEqual(r.droppedTool, 1);
+});
+
+test('strips an unpaired tool_call but keeps the assistant message when it has content', () => {
+  const msgs = [
+    { role: 'assistant', content: 'here you go', tool_calls: [{ id: 'unpaired', type: 'function', function: { name: 'x', arguments: '{}' } }] },
+  ];
+  const r = cleanOrphanedToolMessages(msgs);
+  assert.strictEqual(r.messages.length, 1);
+  assert.strictEqual(r.messages[0].content, 'here you go');
+  assert.ok(!('tool_calls' in r.messages[0]), 'unpaired tool_calls removed');
+  assert.strictEqual(r.droppedAssistantCalls, 1);
+  assert.strictEqual(r.droppedAssistantMsgs, 0);
+});
+
+test('drops an assistant message that has only unpaired tool_calls and no content', () => {
+  const msgs = [
+    { role: 'assistant', content: '', tool_calls: [{ id: 'unpaired', type: 'function', function: { name: 'x', arguments: '{}' } }] },
+  ];
+  const r = cleanOrphanedToolMessages(msgs);
+  assert.strictEqual(r.messages.length, 0);
+  assert.strictEqual(r.droppedAssistantCalls, 1);
+  assert.strictEqual(r.droppedAssistantMsgs, 1);
+});
+
+test('partially-paired tool_calls keep only the paired ids', () => {
+  const msgs = [
+    { role: 'assistant', content: '', tool_calls: [
+      { id: 'a', type: 'function', function: { name: 'x', arguments: '{}' } },
+      { id: 'b', type: 'function', function: { name: 'y', arguments: '{}' } },
+    ] },
+    { role: 'tool', tool_call_id: 'a', content: 'ra' },
+  ];
+  const r = cleanOrphanedToolMessages(msgs);
+  assert.strictEqual(r.messages[0].tool_calls.length, 1);
+  assert.strictEqual(r.messages[0].tool_calls[0].id, 'a');
+  assert.strictEqual(r.droppedAssistantCalls, 1);
+});
+
+test('reconstructLoadedMessage carries role/content and only present optional fields', () => {
+  assert.deepStrictEqual(reconstructLoadedMessage({ role: 'user', content: 'hi' }), { role: 'user', content: 'hi' });
+  assert.deepStrictEqual(
+    reconstructLoadedMessage({ role: 'tool', content: 'r', tool_call_id: 'a' }),
+    { role: 'tool', content: 'r', tool_call_id: 'a' },
+  );
+  // Empty tool_call_id and empty tool_calls are omitted.
+  assert.deepStrictEqual(
+    reconstructLoadedMessage({ role: 'tool', content: 'r', tool_call_id: '', tool_calls: [] }),
+    { role: 'tool', content: 'r' },
+  );
+  const withCalls = reconstructLoadedMessage({ role: 'assistant', content: '', tool_calls: [{ id: 'a' }] });
+  assert.deepStrictEqual(withCalls.tool_calls, [{ id: 'a' }]);
+});