@semalt-ai/code 1.8.5 → 1.20.0

package/test/grep-path-target.test.js

@@ -0,0 +1,227 @@
+'use strict';
+
+// Focused coverage for the path-aware grep fix: `path` now denotes a FILE, a
+// DIRECTORY, or a GLOB filter, and an unresolvable path returns a diagnostic
+// error instead of a silent {count:0}. The original bug: `path` was treated ONLY
+// as a glob over a cwd-rooted walk, so a path pointing at a file/dir OUTSIDE the
+// cwd subtree was never reached → {count:0}, indistinguishable from a true
+// negative. See ROOT CAUSE in the task brief.
+//
+// Isolation mirrors grep-glob.test.js: temp $HOME (audit log + protected config
+// resolve there) set BEFORE any lib require, plus a temp cwd.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TMP_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-home-'));
+const PREV_HOME = process.env.HOME;
+const PREV_USERPROFILE = process.env.USERPROFILE;
+process.env.HOME = TMP_HOME;
+process.env.USERPROFILE = TMP_HOME;
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+
+const ui = require('../lib/ui');
+const { createPermissionManager } = require('../lib/permissions');
+const { createToolExecutor } = require('../lib/tools');
+const {
+  _grepSearch,
+  _resolveGrepPath,
+  _detectRipgrep,
+} = require('../lib/tool_registry');
+
+const HAVE_RG = !!_detectRipgrep();
+const rgOpts = HAVE_RG ? {} : { skip: 'ripgrep (rg) not on PATH' };
+
+let exec;
+let CWD;         // the agent's working directory (search root for the legacy walk)
+let OUTSIDE;     // a sibling directory OUTSIDE CWD — the heart of the original bug
+let OUTFILE;     // an explicit file under OUTSIDE that contains the needle
+let PREV_CWD;
+
+const NEEDLE = 'T.PICKUP'; // regex: '.' is a wildcard, matches "T.PICKUP" literally too
+
+before(() => {
+  PREV_CWD = process.cwd();
+  CWD = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-cwd-')));
+  OUTSIDE = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-out-')));
+  process.chdir(CWD);
+
+  // Inside the cwd tree: an ordinary JS file with the needle, plus a decoy.
+  fs.writeFileSync(path.join(CWD, 'in.js'), 'const x = 1;\nconst T_PICKUP = handler;\n');
+  fs.mkdirSync(path.join(CWD, 'sub'), { recursive: true });
+  fs.writeFileSync(path.join(CWD, 'sub', 'deep.js'), 'noop\nT.PICKUP here\nmore\n');
+  fs.writeFileSync(path.join(CWD, 'plain.txt'), 'just text, no needle\n');
+
+  // OUTSIDE the cwd subtree: the file the model would address by absolute path.
+  OUTFILE = path.join(OUTSIDE, 'registry.js');
+  fs.writeFileSync(OUTFILE, 'line one\nreturn T.PICKUP(args)\nline three\n');
+  fs.writeFileSync(path.join(OUTSIDE, 'other.js'), 'T.PICKUP again\n');
+
+  const pm = createPermissionManager(ui, {});
+  exec = createToolExecutor(pm, ui, () => ({ max_file_size_kb: 512, command_timeout_ms: 30000 }));
+});
+
+after(() => {
+  process.chdir(PREV_CWD);
+  if (PREV_HOME === undefined) delete process.env.HOME; else process.env.HOME = PREV_HOME;
+  if (PREV_USERPROFILE === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = PREV_USERPROFILE;
+});
+
+// ---------------------------------------------------------------------------
+// _resolveGrepPath — the file/dir/glob/omitted decision table
+// ---------------------------------------------------------------------------
+
+test('_resolveGrepPath: existing FILE → file mode', () => {
+  assert.deepStrictEqual(_resolveGrepPath(OUTFILE), { mode: 'file', file: OUTFILE, display: OUTFILE });
+});
+
+test('_resolveGrepPath: existing DIRECTORY → dir mode with that dir as baseDir', () => {
+  assert.deepStrictEqual(_resolveGrepPath(OUTSIDE), { mode: 'dir', baseDir: OUTSIDE, pathGlob: null });
+});
+
+test('_resolveGrepPath: non-existent path / glob → glob mode (legacy cwd walk)', () => {
+  assert.deepStrictEqual(_resolveGrepPath('*.js'), { mode: 'glob', baseDir: '.', pathGlob: '*.js' });
+  assert.deepStrictEqual(_resolveGrepPath('does/not/exist.js'), { mode: 'glob', baseDir: '.', pathGlob: 'does/not/exist.js' });
+});
+
+test('_resolveGrepPath: omitted → no filter', () => {
+  assert.deepStrictEqual(_resolveGrepPath(null), { mode: 'none', baseDir: '.', pathGlob: null });
+  assert.deepStrictEqual(_resolveGrepPath(''), { mode: 'none', baseDir: '.', pathGlob: null });
+});
+
+// ---------------------------------------------------------------------------
+// (a) THE BUG: an absolute FILE path OUTSIDE cwd now finds its matches.
+// ---------------------------------------------------------------------------
+
+test('(a) grep on an absolute FILE path outside cwd finds the matches (was {count:0})', () => {
+  const r = _grepSearch({ pattern: NEEDLE, path: OUTFILE, engine: 'node' });
+  assert.strictEqual(r.error, undefined);
+  assert.strictEqual(r.count, 1);
+  assert.deepStrictEqual(r.matches, [{ file: _posix(OUTFILE), line: 2, text: 'return T.PICKUP(args)' }]);
+});
+
+// ---------------------------------------------------------------------------
+// (b) a DIRECTORY path searches that directory recursively.
+// ---------------------------------------------------------------------------
+
+test('(b) grep on a DIRECTORY path searches that dir', () => {
+  const r = _grepSearch({ pattern: NEEDLE, path: OUTSIDE, engine: 'node' });
+  assert.strictEqual(r.error, undefined);
+  // dir mode → paths are relative to the directory used as the walk root
+  const files = r.matches.map((m) => m.file).sort();
+  assert.deepStrictEqual(files, ['other.js', 'registry.js']);
+});
+
+// ---------------------------------------------------------------------------
+// (c) a glob with no existing-path collision still glob-filters from cwd.
+// ---------------------------------------------------------------------------
+
+test('(c) grep with glob "*.js" still glob-filters the cwd walk (back-compat)', () => {
+  const r = _grepSearch({ pattern: NEEDLE, path: '*.js', engine: 'node' });
+  assert.strictEqual(r.error, undefined);
+  // in.js (T_PICKUP — '.' wildcard matches '_') and sub/deep.js, NOT plain.txt
+  const files = r.matches.map((m) => m.file).sort();
+  assert.deepStrictEqual(files, ['in.js', 'sub/deep.js']);
+});
+
+// ---------------------------------------------------------------------------
+// (d) a path that doesn't exist anywhere → diagnostic ERROR, not {count:0}.
+// ---------------------------------------------------------------------------
+
+test('(d) grep on a path that resolves to nothing returns a diagnostic error', () => {
+  const r = _grepSearch({ pattern: NEEDLE, path: '/no/such/place/file.js', engine: 'node' });
+  assert.ok(r.error, 'must be an error, not a silent count:0');
+  assert.match(r.error, /did not resolve to any file/);
+  assert.strictEqual(r.count, undefined);
+});
+
+test('(d2) grep on a glob matching zero files → diagnostic error (nothing to search)', () => {
+  const r = _grepSearch({ pattern: NEEDLE, path: '*.nonexistentext', engine: 'node' });
+  assert.ok(r.error);
+  assert.match(r.error, /did not resolve to any file/);
+});
+
+// ---------------------------------------------------------------------------
+// (e) THE GATING PROOF: a valid file/glob where the pattern is genuinely absent
+//     returns {count:0} — a true negative, NOT an error.
+// ---------------------------------------------------------------------------
+
+test('(e1) grep an existing FILE with no match → {count:0}, NOT an error (true negative)', () => {
+  const r = _grepSearch({ pattern: 'ZZZ_ABSENT_TOKEN', path: OUTFILE, engine: 'node' });
+  assert.strictEqual(r.error, undefined);
+  assert.strictEqual(r.count, 0);
+  assert.deepStrictEqual(r.matches, []);
+});
+
+test('(e2) grep a glob matching real files but pattern absent → {count:0}, NOT an error', () => {
+  // "*.js" matches in.js + sub/deep.js (real candidates) but the token is absent.
+  const r = _grepSearch({ pattern: 'ZZZ_ABSENT_TOKEN', path: '*.js', engine: 'node' });
+  assert.strictEqual(r.error, undefined, 'real candidate files exist → true negative, never an error');
+  assert.strictEqual(r.count, 0);
+});
+
+test('(e3) grep a DIRECTORY that exists but lacks the pattern → {count:0}, NOT an error', () => {
+  const r = _grepSearch({ pattern: 'ZZZ_ABSENT_TOKEN', path: OUTSIDE, engine: 'node' });
+  assert.strictEqual(r.error, undefined);
+  assert.strictEqual(r.count, 0);
+});
+
+// ---------------------------------------------------------------------------
+// (f) BOTH ENGINES consistent for the path-resolution path.
+// ---------------------------------------------------------------------------
+
+test('(f) file-target: node and rg agree', rgOpts, () => {
+  const viaNode = _grepSearch({ pattern: NEEDLE, path: OUTFILE, engine: 'node' });
+  const viaRg = _grepSearch({ pattern: NEEDLE, path: OUTFILE, engine: 'rg' });
+  assert.deepStrictEqual(viaRg, viaNode);
+});
+
+test('(f) dir-target: node and rg agree', rgOpts, () => {
+  const viaNode = _grepSearch({ pattern: NEEDLE, path: OUTSIDE, engine: 'node' });
+  const viaRg = _grepSearch({ pattern: NEEDLE, path: OUTSIDE, engine: 'rg' });
+  assert.deepStrictEqual(viaRg, viaNode);
+});
+
+test('(f) unresolvable-path error is identical across engines', rgOpts, () => {
+  const viaNode = _grepSearch({ pattern: NEEDLE, path: '/no/such/place.js', engine: 'node' });
+  const viaRg = _grepSearch({ pattern: NEEDLE, path: '/no/such/place.js', engine: 'rg' });
+  assert.deepStrictEqual(viaRg, viaNode);
+});
+
+// ---------------------------------------------------------------------------
+// (g) SANDBOX / path-safety: grep refuses a protected secret path exactly like
+//     read_file / search_in_file (isProtectedSecretPath). The OS sandbox remains
+//     the outer confinement; this is the name-based guard parity check.
+// ---------------------------------------------------------------------------
+
+test('(g) grep on a protected secret path is refused like other file reads', async () => {
+  const cfg = path.join(TMP_HOME, '.semalt-ai', 'config.json'); // == CONFIG_PATH under temp HOME
+  const r = await exec.agentExecFile('grep', NEEDLE, cfg);
+  assert.ok(r.error, 'must be refused');
+  assert.match(r.error, /secrets|credentials|cannot be read/i);
+  // parity: search_in_file refuses the same path the same way
+  const r2 = await exec.agentExecFile('search_in_file', cfg, NEEDLE);
+  assert.ok(r2.error);
+  assert.match(r2.error, /secrets|credentials|cannot be read/i);
+});
+
+// ---------------------------------------------------------------------------
+// End-to-end through the executor (auto engine) — the real model-facing path.
+// ---------------------------------------------------------------------------
+
+test('executor: agentExecFile grep on an out-of-cwd file finds the needle', async () => {
+  const r = await exec.agentExecFile('grep', NEEDLE, OUTFILE);
+  assert.strictEqual(r.error, undefined);
+  assert.strictEqual(r.count, 1);
+});
+
+test('executor: agentExecFile grep on a vanished path returns the diagnostic error', async () => {
+  const r = await exec.agentExecFile('grep', NEEDLE, '/no/such/place/file.js');
+  assert.ok(r.error);
+  assert.match(r.error, /did not resolve to any file/);
+});
+
+function _posix(p) { return p.split(path.sep).join('/'); }

package/test/harness/README.md

@@ -0,0 +1,57 @@
+# Test harness — mock LLM
+
+Deterministic, zero-dependency fakes for testing the streaming client and the
+agent loop without a real model or network. Built on Node's `http` module only.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `sse-server.js` | Low-level scriptable SSE server + `sse()` / `DONE` helpers. Serves one scripted response per request. Used by the streaming-parser tests (1.1). |
+| `mock-llm.js` | Queue-based mock LLM built on `sse-server`. Serves a FIFO queue of scripted responses — one per inbound POST — so a multi-turn agent loop or a retry sequence runs deterministically. Used by the agent-loop tests (1.2). |
+
+## `startMockLLM()`
+
+```js
+const { startMockLLM } = require('./harness/mock-llm');
+
+const mock = await startMockLLM();        // listens on 127.0.0.1:<random port>
+// Point config.api_base at mock.base, then script responses (FIFO):
+
+mock.replyWith('<exec>echo hi</exec>');   // streamed assistant content
+mock.replyWith('All done.');              // next turn's reply
+mock.replyWithToolCall('read_file', { path: 'a.txt' });  // native tool_calls
+mock.streamChunks([...customSSE]);        // full control over the SSE stream
+mock.failWith(429, { headers: { 'retry-after': '0' } }); // an error response
+mock.failWith(400, { body: JSON.stringify({ error: { message: 'context length is only 100' } }) });
+
+// Introspection:
+mock.pending();        // queued-but-unserved responses
+mock.requestCount();   // requests received so far
+mock.requests;         // [{ url, body, headers }] recorded per request
+
+await mock.close();    // always close in a finally / after()
+```
+
+### Response ordering
+
+Responses are served strictly FIFO, one per request. A single `chatStream` call
+is normally one request — **except** the 400/413 self-healing path in `api.js`,
+which transparently retries, consuming **two** queued responses (the error, then
+the recovery). The agent loop's own retry/backoff (429, 5xx) also consumes one
+queued response per attempt.
+
+### Determinism / timing
+
+- `gapMs` (default 2ms) controls the delay between SSE chunks. Raise it to keep a
+  stream open long enough to test mid-stream abort.
+- For retry tests, use `Retry-After: 0` so backoff is ~instant; this both keeps
+  the test fast and proves the header is honored (the base backoff is 1000ms).
+- No `Math.random`/wall-clock dependence; every run is reproducible.
+
+## Wiring the agent loop
+
+Inject `mock.base` through the existing `config.api_base` seam — no production
+code changes. Build the real `chatStream` (`createApiClient`) and a real tool
+executor, then `createAgentRunner(...)`. See `test/agent-loop.test.js` for the
+`buildRunner()` helper used across all scenarios.

package/test/harness/chat-harness.js

@@ -0,0 +1,143 @@
+'use strict';
+
+// Chat-loop smoke harness for cmdChat (Task 1.5, tests-first). Drives the real
+// createCommands().cmdChat() with a fully mocked UI so the interactive chat
+// closure can be characterized WITHOUT a TTY: the mock inputField captures the
+// onSubmit callback, and submit(text) invokes it exactly as a keypress would.
+//
+// Home-based paths (saved sessions, audit log) are redirected to a temp dir
+// before any lib module loads, so a chat session writes nothing real.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TMP_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-chat-home-'));
+process.env.HOME = TMP_HOME;
+process.env.USERPROFILE = TMP_HOME;
+
+const { createCommands } = require('../../lib/commands');
+const tools = require('../../lib/tools');
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// The mock UI handles returned by createUI().
+function makeChatUI() {
+  const chatHistory = {
+    messages: [],
+    addMessage(m) { this.messages.push(m); },
+    clearMessages() { this.messages = []; },
+    clearStreamingContent() {},
+    collapseById() {}, removeById() {}, rerenderById() {},
+    finalizeLastMessage() {}, streamToken() {},
+    texts() { return this.messages.map((m) => (typeof m.content === 'string' ? m.content : '')); },
+    last() { return this.messages[this.messages.length - 1]; },
+    find(re) { return this.texts().find((t) => re.test(t)); },
+  };
+  const statusBar = {
+    states: [],
+    update(...a) { this.states.push(a); },
+    setModel() {}, setContextLimit() {}, updateMetrics() {}, addPendingTokens() {}, onToken() {},
+  };
+  const inputField = {
+    _submit: null, _handlers: {}, _nav: null,
+    onSubmit(cb) { this._submit = cb; },
+    on(ev, cb) { (this._handlers[ev] = this._handlers[ev] || []).push(cb); },
+    removeListener(ev, cb) { const a = this._handlers[ev] || []; const i = a.indexOf(cb); if (i >= 0) a.splice(i, 1); },
+    captureNavigation(h) { this._nav = h; },
+    releaseNavigation() { this._nav = null; },
+    setDisabled() {}, setSearchItems() {}, captureSelect() { return Promise.resolve(null); },
+    isIdle() { return false; },
+    async submit(text) { if (!this._submit) throw new Error('onSubmit not registered'); return this._submit(text); },
+    emit(ev, ...args) { for (const cb of (this._handlers[ev] || [])) cb(...args); },
+  };
+  return { chatHistory, statusBar, inputField, layout: null, destroy: () => {}, redrawFixed: () => {} };
+}
+
+// The `ui` object createCommands destructures (colors + helpers + createUI).
+function makeUI(chatUI) {
+  const ui = { createUI: () => chatUI };
+  for (const k of ['BOLD', 'BG_SELECTED', 'FG_BLUE', 'FG_CYAN', 'FG_DARK', 'FG_GRAY', 'FG_GREEN', 'FG_RED', 'FG_TEAL', 'FG_YELLOW', 'RST', 'DIM']) ui[k] = '';
+  ui.approxTokens = (s) => Math.ceil(((s || '').length) / 4);
+  ui.getCols = () => 80;
+  ui.boxLine = (s) => s;
+  ui.interactiveSelect = async () => null;
+  return ui;
+}
+
+function makeDeps(chatUI, overrides = {}) {
+  const config = {
+    auth_token: '', default_model: 'test-model', dashboard_model_id: null,
+    dashboard_url: 'http://dash', api_base: 'http://api', models: [],
+    system_prompt_mode: 'system_role', temperature: 0.7,
+    ...(overrides.config || {}),
+  };
+  const getConfig = () => config;
+  const setConfig = (c) => Object.assign(config, c);
+
+  const calls = { runAgentLoop: [], chatStream: [], shell: [], permissionClear: 0 };
+
+  const permissionManager = {
+    setUICallbacks() {}, clear() { calls.permissionClear++; }, toggleAll() { return true; },
+    askPermission: async () => true, readonlyBlock: () => null, captureSelect: async () => null, state: {},
+  };
+
+  const apiClient = {
+    chatStream: async (...a) => { calls.chatStream.push(a); return { content: '', usage: null }; },
+    chatSync: async () => '',
+    dashboardCreateChat: async () => ({ chat: { id: 1 } }),
+    dashboardGetChat: async () => ({ chat: { title: 't' }, messages: [] }),
+    dashboardSaveMessages: async () => ({}),
+    dashboardListChats: async () => ({ chats: [] }),
+    dashboardListModels: async () => ({ models: [] }),
+    dashboardGetModelForCli: async () => ({ model: null }),
+    dashboardWhoAmI: async () => ({ user: null }),
+    dashboardLogout: async () => ({}),
+    estimateTokens: (s) => Math.ceil((s || '').length / 4),
+    getCliLoginStatus: async () => ({ status: 'authorized' }),
+    requestCliLogin: async () => ({ id: 1, hash: 'h', token: 'tok', verification_url: 'http://v' }),
+    setActiveModelProfile: () => {},
+    ...(overrides.apiClient || {}),
+  };
+
+  const runAgentLoop = overrides.runAgentLoop
+    || (async (messages, model, maxIter, limit, opts) => {
+      calls.runAgentLoop.push({ messages: messages.map((m) => ({ ...m })), model, opts });
+      return { messages, metrics: { summary: () => 'metrics-summary' } };
+    });
+  const readFileContext = overrides.readFileContext || ((f) => `ctx:${JSON.stringify(f)}`);
+  const agentExecShell = overrides.agentExecShell
+    || (async (cmd, o) => { calls.shell.push({ cmd, o }); return { exit_code: 0, stdout: `out:${cmd}`, stderr: '' }; });
+
+  return {
+    deps: { getConfig, setConfig, permissionManager, ui: makeUI(chatUI), apiClient, runAgentLoop, readFileContext, agentExecShell },
+    config, calls,
+  };
+}
+
+// Start a chat session. Returns once onSubmit is registered. `submit(text)` runs
+// a turn; `submit('exit')` ends the session (await `done` to confirm teardown).
+async function startChat(overrides = {}) {
+  const chatUI = makeChatUI();
+  const { deps, config, calls } = makeDeps(chatUI, overrides);
+  const commands = createCommands(deps);
+  const done = commands.cmdChat({ model: undefined, ...(overrides.opts || {}) });
+
+  // Wait for cmdChat's async setup (ensureDefaultModel + resolveTokenLimit) to
+  // register the submit handler.
+  for (let i = 0; i < 200 && !chatUI.inputField._submit; i++) await delay(2);
+  if (!chatUI.inputField._submit) throw new Error('cmdChat did not register onSubmit');
+
+  return {
+    chatHistory: chatUI.chatHistory,
+    statusBar: chatUI.statusBar,
+    inputField: chatUI.inputField,
+    config,
+    calls,
+    submit: (text) => chatUI.inputField.submit(text),
+    done,
+    cleanup: () => { try { tools.setUIActive(false); } catch {} },
+  };
+}
+
+module.exports = { startChat };

package/test/harness/memwarn-headless-child.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// Child process for the memory-truncation headless test. Runs cmdCode in json
+// mode with an oversized project AGENTS.md so the PARENT can capture this
+// process's stdout (the JSON envelope) and stderr (the truncation warning)
+// cleanly — running in a child avoids swapping the parent's global
+// process.stdout, which would collide with the node:test TAP reporter.
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..'); // project root
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'memwarn-child-home-'));
+process.env.HOME = home;
+process.env.USERPROFILE = home;
+process.env.SEMALT_API_KEY = 'test-key';
+
+const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'memwarn-child-repo-'));
+fs.mkdirSync(path.join(repo, '.git'), { recursive: true });
+const { DEFAULT_MEMORY_MAX_BYTES } = require(path.join(ROOT, 'lib', 'memory'));
+fs.writeFileSync(path.join(repo, 'AGENTS.md'), 'Z'.repeat(DEFAULT_MEMORY_MAX_BYTES + 4000));
+process.chdir(repo);
+
+const ui = require(path.join(ROOT, 'lib', 'ui'));
+const { createApiClient } = require(path.join(ROOT, 'lib', 'api'));
+const { createToolExecutor, extractToolCalls } = require(path.join(ROOT, 'lib', 'tools'));
+const { createPermissionManager } = require(path.join(ROOT, 'lib', 'permissions'));
+const { createAgentRunner } = require(path.join(ROOT, 'lib', 'agent'));
+const { createOneshotCommands } = require(path.join(ROOT, 'lib', 'commands', 'oneshot'));
+const { startMockLLM } = require(path.join(ROOT, 'test', 'harness', 'mock-llm'));
+
+(async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('All done.');
+  const config = {
+    api_base: mock.base, api_key: 'test-key', auth_token: 'tok', default_model: 'test-model',
+    temperature: 0.5, request_timeout_ms: 5000, stream: true, models: [],
+    max_iterations: 10, system_prompt_mode: 'system_role', pricing: {},
+  };
+  const getConfig = () => config;
+  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);
+  const runner = createAgentRunner({
+    chatStream: api.chatStream, extractToolCalls, agentExecShell, agentExecFile,
+    describePermission, permissionManager: pm, ui, getConfig,
+  });
+  const shared = {
+    ...ui,
+    writer: { scrollback() {} },
+    getConfig, setConfig() {},
+    runAgentLoop: runner.runAgentLoop,
+    readFileContext: () => '',
+    ensureDefaultModel: async () => {},
+    msgs: require(path.join(ROOT, 'lib', 'ui', 'messages')),
+    dbg: require(path.join(ROOT, 'lib', 'debug')),
+  };
+  const { cmdCode } = createOneshotCommands(shared);
+  await cmdCode({ outputFormat: 'json' }, ['do something']);
+  await mock.close();
+  process.exit(0);
+})().catch((e) => { process.stderr.write('CHILDERR:' + (e && e.stack || e) + '\n'); process.exit(1); });

package/test/harness/mock-llm.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// Scriptable mock LLM server for agent-loop integration tests (Task 1.2).
+// Built on the SSE primitives in ./sse-server. A single server instance serves
+// a FIFO queue of scripted responses — one per inbound POST — so a multi-turn
+// agent loop (or a retry sequence) is driven deterministically with no real
+// network and no real model.
+//
+// Each queued response is either:
+//   * a streamed 200 SSE reply (assistant content and/or native tool_calls), or
+//   * an error (non-200) with an optional JSON body and headers (e.g.
+//     Retry-After) — used to exercise the retry/backoff and 400/413 paths.
+//
+// See ./README.md for the full contract and examples.
+
+const http = require('http');
+const { sse, DONE } = require('./sse-server');
+
+// Build the SSE chunk list for a plain assistant message that streams `content`.
+// `content` may be a string (sent as one delta) or an array of strings (sent as
+// successive deltas, to exercise token-by-token handling and mid-stream abort).
+function contentChunks(content, { finish = 'stop', usage = null } = {}) {
+  const parts = Array.isArray(content) ? content : (content ? [content] : []);
+  const chunks = parts.map((p) => sse({ choices: [{ delta: { content: p } }] }));
+  chunks.push(sse({ choices: [{ finish_reason: finish, delta: {} }] }));
+  if (usage) chunks.push(sse({ usage }));
+  chunks.push(DONE);
+  return chunks;
+}
+
+// Build the SSE chunk list for a native OpenAI tool_calls response.
+function toolCallChunks(name, args, { id = 'call_1' } = {}) {
+  return [
+    sse({ choices: [{ delta: { tool_calls: [{ index: 0, id, type: 'function', function: { name, arguments: JSON.stringify(args) } }] } }] }),
+    sse({ choices: [{ finish_reason: 'tool_calls', delta: {} }] }),
+    DONE,
+  ];
+}
+
+function startMockLLM() {
+  const queue = [];
+  const requests = [];
+
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.setEncoding('utf8');
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      requests.push({ url: req.url, body, headers: req.headers });
+      const spec = queue.shift();
+      if (!spec) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end('{"error":"mock-llm: response queue empty"}');
+        return;
+      }
+      serve(res, spec);
+    });
+  });
+
+  function serve(res, spec) {
+    const status = spec.status || 200;
+    const isSse = status === 200;
+    res.writeHead(status, {
+      'Content-Type': isSse ? 'text/event-stream' : 'application/json',
+      ...(spec.headers || {}),
+    });
+    if (!isSse) {
+      res.end(spec.body != null ? spec.body : '{}');
+      return;
+    }
+    const chunks = spec.chunks || [];
+    const gap = spec.gapMs == null ? 2 : spec.gapMs;
+    let i = 0;
+    const next = () => {
+      if (res.writableEnded) return;
+      if (i >= chunks.length) { res.end(); return; }
+      res.write(chunks[i++]);
+      if (gap > 0) setTimeout(next, gap); else next();
+    };
+    next();
+  }
+
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolve({
+        base: `http://127.0.0.1:${port}`,
+        port,
+        requests,
+
+        // Enqueue a streamed assistant message (string or string[] of deltas).
+        replyWith(content, opts = {}) {
+          queue.push({ status: 200, chunks: contentChunks(content, opts), gapMs: opts.gapMs });
+          return this;
+        },
+        // Enqueue a native tool_calls response.
+        replyWithToolCall(name, args, opts = {}) {
+          queue.push({ status: 200, chunks: toolCallChunks(name, args, opts), gapMs: opts.gapMs });
+          return this;
+        },
+        // Enqueue raw SSE chunks (full control).
+        streamChunks(chunks, opts = {}) {
+          queue.push({ status: 200, chunks, gapMs: opts.gapMs });
+          return this;
+        },
+        // Enqueue an error (non-200) response.
+        failWith(status, { body, headers } = {}) {
+          queue.push({ status, body, headers });
+          return this;
+        },
+
+        pending() { return queue.length; },
+        requestCount() { return requests.length; },
+        close() { return new Promise((r) => server.close(r)); },
+      });
+    });
+  });
+}
+
+module.exports = { startMockLLM, contentChunks, toolCallChunks };