@semalt-ai/code 1.8.4 → 1.19.0

package/test/images-api.test.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// Integration tests for multimodal image input on the wire (Task 5.4). They
+// drive the REAL api client / SDK against the mock-LLM harness and assert the
+// PROVIDER-SPECIFIC content-part shape that actually leaves the client, the
+// fail-loud vision check (image is NEVER silently dropped), and that the
+// headless/SDK surface accepts images with the rest of the loop unaffected.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createApiClient } = require('../lib/api');
+const { createAgent } = require('../lib/sdk');
+const ui = require('../lib/ui');
+const { normalizeConfig } = require('../lib/config');
+const { startMockLLM } = require('./harness/mock-llm');
+
+const PNG_BUF = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13]);
+const IMG = { media_type: 'image/png', data: PNG_BUF.toString('base64') };
+
+function clientFor(mock, cfgOverride = {}) {
+  let config = normalizeConfig({ api_base: mock.base, api_key: 'k', default_model: 'gpt-4o', ...cfgOverride });
+  const getConfig = () => config;
+  const saveConfig = (c) => { config = normalizeConfig(c); };
+  return createApiClient({ getConfig, saveConfig, ui });
+}
+
+function lastRequestMessages(mock) {
+  const req = mock.requests[mock.requests.length - 1];
+  return JSON.parse(req.body).messages;
+}
+
+// ── provider-specific content-part shape (constraint #1) ─────────────────────
+
+test('OpenAI-style image_url is sent for an OpenAI-compatible vision model', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('It is a diagram.');
+  const client = clientFor(mock); // default model gpt-4o → vision via heuristic
+  try {
+    await client.chatStream(
+      [{ role: 'user', content: 'what is this', images: [IMG] }],
+      { model: 'gpt-4o', silent: true },
+    );
+    const msgs = lastRequestMessages(mock);
+    const user = msgs.find((m) => m.role === 'user');
+    assert.ok(Array.isArray(user.content), 'content is a multimodal array');
+    const textPart = user.content.find((p) => p.type === 'text');
+    const imgPart = user.content.find((p) => p.type === 'image_url');
+    assert.strictEqual(textPart.text, 'what is this');
+    assert.ok(imgPart, 'image_url part present');
+    assert.strictEqual(imgPart.image_url.url, `data:image/png;base64,${IMG.data}`);
+    assert.strictEqual(user.images, undefined, 'internal images field not on the wire');
+  } finally {
+    await mock.close();
+  }
+});
+
+test('Anthropic-style image source block is sent for an anthropic-format profile', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('ack');
+  const client = clientFor(mock, {
+    default_model: 'claude-vision',
+    models: [{ api_base: mock.base, api_key: 'k', model: 'claude-vision', image_format: 'anthropic', vision: true }],
+  });
+  try {
+    await client.chatStream(
+      [{ role: 'user', content: 'describe', images: [IMG] }],
+      { model: 'claude-vision', silent: true },
+    );
+    const msgs = lastRequestMessages(mock);
+    const user = msgs.find((m) => m.role === 'user');
+    const imgPart = user.content.find((p) => p.type === 'image');
+    assert.ok(imgPart, 'anthropic image part present');
+    assert.deepStrictEqual(imgPart.source, { type: 'base64', media_type: 'image/png', data: IMG.data });
+    assert.ok(!user.content.some((p) => p.type === 'image_url'), 'no OpenAI-style part');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ── vision capability: fail loud, NEVER silently drop (constraint #2) ─────────
+
+test('text-only model → clear error, image NOT sent (no silent drop)', async () => {
+  const mock = await startMockLLM();
+  // Deliberately queue NOTHING — a request would 500. We assert none is made.
+  const client = clientFor(mock, {
+    default_model: 'text-only',
+    models: [{ api_base: mock.base, api_key: 'k', model: 'text-only', vision: false }],
+  });
+  try {
+    await assert.rejects(
+      () => client.chatStream(
+        [{ role: 'user', content: 'see this', images: [IMG] }],
+        { model: 'text-only', silent: true },
+      ),
+      /not vision-capable/i,
+    );
+    assert.strictEqual(mock.requestCount(), 0, 'no request left the client — image not silently dropped');
+  } finally {
+    await mock.close();
+  }
+});
+
+test('paired positive: a vision model accepts the same image', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('I see a cat.');
+  const client = clientFor(mock, {
+    default_model: 'vision-ok',
+    models: [{ api_base: mock.base, api_key: 'k', model: 'vision-ok', vision: true }],
+  });
+  try {
+    const res = await client.chatStream(
+      [{ role: 'user', content: 'see this', images: [IMG] }],
+      { model: 'vision-ok', silent: true },
+    );
+    assert.match(res.content, /cat/);
+    assert.strictEqual(mock.requestCount(), 1);
+  } finally {
+    await mock.close();
+  }
+});
+
+// ── the rest of the loop is unaffected when images are present ───────────────
+
+test('a plain text turn (no images) still sends string content', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('hi');
+  const client = clientFor(mock);
+  try {
+    await client.chatStream([{ role: 'user', content: 'hello' }], { model: 'gpt-4o', silent: true });
+    const msgs = lastRequestMessages(mock);
+    const user = msgs.find((m) => m.role === 'user');
+    assert.strictEqual(user.content, 'hello', 'string content unchanged without images');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ── SDK / headless surface accepts images, envelope unaffected ───────────────
+
+test('SDK run({ images }) reads a real file, attaches it, returns the envelope', async () => {
+  const prevKey = process.env.SEMALT_API_KEY;
+  process.env.SEMALT_API_KEY = 'test-key';
+  const prevCwd = process.cwd();
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'images-sdk-'));
+  process.chdir(tmpDir);
+  const imgPath = path.join(tmpDir, 'shot.png');
+  fs.writeFileSync(imgPath, PNG_BUF);
+
+  const mock = await startMockLLM();
+  mock.replyWith('A screenshot of a form.');
+  const agent = createAgent({
+    apiBase: mock.base,
+    apiKey: 'test-key',
+    model: 'gpt-4o',
+    sandbox: { mode: 'off' },
+  });
+  try {
+    const res = await agent.run('what is in this screenshot', { images: [imgPath] });
+    assert.match(res.result, /screenshot/i);
+    assert.ok(Array.isArray(res.toolCalls));
+    assert.strictEqual(res.stopReason, 'end_turn');
+    // The image actually rode the request as an OpenAI-style part.
+    const msgs = lastRequestMessages(mock);
+    const user = msgs.find((m) => Array.isArray(m.content) && m.content.some((p) => p.type === 'image_url'));
+    assert.ok(user, 'image_url part sent from a real file path');
+  } finally {
+    await agent.close();
+    await mock.close();
+    process.chdir(prevCwd);
+    if (prevKey === undefined) delete process.env.SEMALT_API_KEY;
+    else process.env.SEMALT_API_KEY = prevKey;
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('SDK run({ images }) refuses an out-of-CWD path via isPathSafe', async () => {
+  const prevKey = process.env.SEMALT_API_KEY;
+  process.env.SEMALT_API_KEY = 'test-key';
+  const prevCwd = process.cwd();
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'images-sdk-cwd-'));
+  // Write the image OUTSIDE the CWD we will chdir into.
+  const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'images-outside-'));
+  const outsidePath = path.join(outsideDir, 'secret.png');
+  fs.writeFileSync(outsidePath, PNG_BUF);
+  process.chdir(tmpDir);
+
+  const mock = await startMockLLM();
+  const agent = createAgent({ apiBase: mock.base, apiKey: 'test-key', model: 'gpt-4o', sandbox: { mode: 'off' } });
+  try {
+    await assert.rejects(
+      () => agent.run('peek', { images: [outsidePath] }),
+      /outside allowed area/i,
+    );
+    assert.strictEqual(mock.requestCount(), 0, 'refused before any request');
+  } finally {
+    await agent.close();
+    await mock.close();
+    process.chdir(prevCwd);
+    if (prevKey === undefined) delete process.env.SEMALT_API_KEY;
+    else process.env.SEMALT_API_KEY = prevKey;
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+    try { fs.rmSync(outsideDir, { recursive: true, force: true }); } catch {}
+  }
+});

package/test/images.test.js

@@ -0,0 +1,238 @@
+'use strict';
+
+// Unit tests for the multimodal image-input module (Task 5.4). Pure surface:
+// media-type detection per format, the read path (size cap + isPathSafe + format
+// guards), provider-specific content-part shaping (Anthropic vs OpenAI), the
+// format-selection precedence, vision-capability resolution (fail-loud), and the
+// message transform helpers.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const images = require('../lib/images');
+const { DEFAULT_IMAGE_MAX_BYTES } = require('../lib/constants');
+
+// Minimal buffers with the right magic bytes for each format (≥12 bytes so the
+// WebP offset check is in range).
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13]);
+const JPEG = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0, 0, 0, 0, 0, 0, 0, 0]);
+const GIF = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0, 0, 0, 0, 0, 0]);
+const WEBP = Buffer.from([0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0, 0x57, 0x45, 0x42, 0x50]);
+
+let tmp;
+function tmpdir() {
+  if (!tmp) tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'images-test-'));
+  return tmp;
+}
+function writeTmp(name, buf) {
+  const p = path.join(tmpdir(), name);
+  fs.writeFileSync(p, buf);
+  return p;
+}
+
+// ── media-type detection ────────────────────────────────────────────────────
+
+test('detectMediaType: PNG/JPEG/WebP/GIF by magic bytes', () => {
+  assert.strictEqual(images.detectMediaType(PNG, 'x.bin'), 'image/png');
+  assert.strictEqual(images.detectMediaType(JPEG, 'x.bin'), 'image/jpeg');
+  assert.strictEqual(images.detectMediaType(GIF, 'x.bin'), 'image/gif');
+  assert.strictEqual(images.detectMediaType(WEBP, 'x.bin'), 'image/webp');
+});
+
+test('detectMediaType: magic bytes win over a misleading extension', () => {
+  // A JPEG body named .png is classified as JPEG (authoritative header).
+  assert.strictEqual(images.detectMediaType(JPEG, 'photo.png'), 'image/jpeg');
+});
+
+test('detectMediaType: extension fallback when header is inconclusive', () => {
+  const blank = Buffer.alloc(12, 0);
+  assert.strictEqual(images.detectMediaType(blank, 'a.jpeg'), 'image/jpeg');
+  assert.strictEqual(images.detectMediaType(blank, 'a.gif'), 'image/gif');
+  assert.strictEqual(images.detectMediaType(blank, 'a.txt'), null);
+});
+
+// ── readImage: encode + guards ──────────────────────────────────────────────
+
+test('readImage: reads, detects type, base64-encodes', () => {
+  const p = writeTmp('ok.png', PNG);
+  const img = images.readImage(p, { isPathSafe: () => true });
+  assert.strictEqual(img.media_type, 'image/png');
+  assert.strictEqual(img.data, PNG.toString('base64'));
+  assert.strictEqual(img.bytes, PNG.length);
+  assert.strictEqual(img.path, p);
+});
+
+test('readImage: out-of-CWD path refused by isPathSafe (clear error)', () => {
+  const p = writeTmp('blocked.png', PNG);
+  assert.throws(
+    () => images.readImage(p, { isPathSafe: () => false }),
+    /outside allowed area/i,
+  );
+});
+
+test('readImage: oversize → clear error, not an opaque endpoint failure', () => {
+  const p = writeTmp('big.png', PNG);
+  assert.throws(
+    () => images.readImage(p, { isPathSafe: () => true, maxBytes: 4 }),
+    /too large/i,
+  );
+});
+
+test('readImage: unsupported format → clear error', () => {
+  const p = writeTmp('note.txt', Buffer.from('hello world, not an image'));
+  assert.throws(
+    () => images.readImage(p, { isPathSafe: () => true }),
+    /Unsupported image format/i,
+  );
+});
+
+test('readImage: missing file → clear error', () => {
+  assert.throws(
+    () => images.readImage(path.join(tmpdir(), 'nope.png'), { isPathSafe: () => true }),
+    /not found or unreadable/i,
+  );
+});
+
+test('readImage: default size cap is the documented constant', () => {
+  // A 1-byte over the default cap would error; under it is fine. We only assert
+  // the default is wired (no maxBytes passed uses DEFAULT_IMAGE_MAX_BYTES).
+  const p = writeTmp('small.png', PNG);
+  assert.doesNotThrow(() => images.readImage(p, { isPathSafe: () => true }));
+  assert.ok(DEFAULT_IMAGE_MAX_BYTES > 0);
+});
+
+test('readImages: order preserved; throws on first bad input', () => {
+  const a = writeTmp('a.png', PNG);
+  const b = writeTmp('b.jpeg', JPEG);
+  const out = images.readImages([a, b], { isPathSafe: () => true });
+  assert.strictEqual(out.length, 2);
+  assert.strictEqual(out[0].media_type, 'image/png');
+  assert.strictEqual(out[1].media_type, 'image/jpeg');
+});
+
+// ── provider-specific content-part shaping (constraint #1) ───────────────────
+
+test('buildImagePart: OpenAI-style image_url data URL', () => {
+  const part = images.buildImagePart({ media_type: 'image/png', data: 'AAAA' }, 'openai');
+  assert.deepStrictEqual(part, {
+    type: 'image_url',
+    image_url: { url: 'data:image/png;base64,AAAA' },
+  });
+});
+
+test('buildImagePart: Anthropic-style base64 source block', () => {
+  const part = images.buildImagePart({ media_type: 'image/jpeg', data: 'BBBB' }, 'anthropic');
+  assert.deepStrictEqual(part, {
+    type: 'image',
+    source: { type: 'base64', media_type: 'image/jpeg', data: 'BBBB' },
+  });
+});
+
+test('buildMultimodalContent: text part first, then image parts', () => {
+  const parts = images.buildMultimodalContent('hello', [{ media_type: 'image/png', data: 'AAAA' }], 'openai');
+  assert.strictEqual(parts.length, 2);
+  assert.deepStrictEqual(parts[0], { type: 'text', text: 'hello' });
+  assert.strictEqual(parts[1].type, 'image_url');
+});
+
+test('buildMultimodalContent: empty text → image-only content', () => {
+  const parts = images.buildMultimodalContent('', [{ media_type: 'image/png', data: 'AAAA' }], 'anthropic');
+  assert.strictEqual(parts.length, 1);
+  assert.strictEqual(parts[0].type, 'image');
+});
+
+// ── provider-format selection precedence ─────────────────────────────────────
+
+test('selectImageFormat: profile.image_format wins', () => {
+  const config = { api_base: 'http://x', models: [{ api_base: 'http://x', model: 'm', image_format: 'anthropic' }] };
+  assert.strictEqual(images.selectImageFormat(config, 'm'), 'anthropic');
+});
+
+test('selectImageFormat: top-level config.image_format next', () => {
+  assert.strictEqual(images.selectImageFormat({ image_format: 'anthropic' }, 'm'), 'anthropic');
+});
+
+test('selectImageFormat: heuristic — anthropic api_base → anthropic, else openai default', () => {
+  assert.strictEqual(images.selectImageFormat({ api_base: 'https://api.anthropic.com' }, 'claude-x'), 'anthropic');
+  assert.strictEqual(images.selectImageFormat({ api_base: 'http://127.0.0.1:8800' }, 'gpt-4o'), 'openai');
+  assert.strictEqual(images.selectImageFormat({}, 'whatever'), 'openai');
+});
+
+// ── vision capability (constraint #2: fail loud) ─────────────────────────────
+
+test('resolveVisionCapability: profile vision:false → false (fail-loud signal)', () => {
+  const config = { api_base: 'http://x', models: [{ api_base: 'http://x', model: 'm', vision: false }] };
+  assert.strictEqual(images.resolveVisionCapability(config, 'm'), false);
+});
+
+test('resolveVisionCapability: profile vision:true → true', () => {
+  const config = { api_base: 'http://x', models: [{ api_base: 'http://x', model: 'm', vision: true }] };
+  assert.strictEqual(images.resolveVisionCapability(config, 'm'), true);
+});
+
+test('resolveVisionCapability: known text-only family → false', () => {
+  assert.strictEqual(images.resolveVisionCapability({}, 'text-embedding-3-large'), false);
+  assert.strictEqual(images.resolveVisionCapability({}, 'whisper-1'), false);
+});
+
+test('resolveVisionCapability: known vision family → true', () => {
+  assert.strictEqual(images.resolveVisionCapability({}, 'gpt-4o'), true);
+  assert.strictEqual(images.resolveVisionCapability({}, 'claude-sonnet-4-6'), true);
+});
+
+test('resolveVisionCapability: unknown → null (proceed, endpoint decides)', () => {
+  assert.strictEqual(images.resolveVisionCapability({}, 'some-random-model'), null);
+});
+
+// ── message transform helpers ────────────────────────────────────────────────
+
+test('buildProviderMessages: only image-bearing turns become content arrays', () => {
+  const msgs = [
+    { role: 'system', content: 'sys' },
+    { role: 'user', content: 'see this', images: [{ media_type: 'image/png', data: 'AAAA' }] },
+    { role: 'assistant', content: 'ok' },
+  ];
+  const out = images.buildProviderMessages(msgs, 'openai');
+  assert.strictEqual(out[0].content, 'sys');
+  assert.ok(Array.isArray(out[1].content));
+  assert.strictEqual(out[1].images, undefined, 'internal images field stripped');
+  assert.strictEqual(out[2].content, 'ok');
+});
+
+test('buildProviderMessages: strips a stray empty images field', () => {
+  const out = images.buildProviderMessages([{ role: 'user', content: 'hi', images: [] }], 'openai');
+  assert.strictEqual(out[0].content, 'hi');
+  assert.ok(!('images' in out[0]));
+});
+
+test('attachImagesToLastUser: attaches to the most recent user message', () => {
+  const msgs = [
+    { role: 'user', content: 'first' },
+    { role: 'assistant', content: 'a' },
+    { role: 'user', content: 'second' },
+  ];
+  images.attachImagesToLastUser(msgs, [{ media_type: 'image/png', data: 'AAAA' }]);
+  assert.strictEqual(msgs[0].images, undefined);
+  assert.strictEqual(msgs[2].images.length, 1);
+});
+
+test('resolveImageInputs: accepts paths and pre-encoded records', () => {
+  const p = writeTmp('mix.png', PNG);
+  const out = images.resolveImageInputs(
+    [p, { media_type: 'image/jpeg', data: 'BBBB' }],
+    { isPathSafe: () => true },
+  );
+  assert.strictEqual(out.length, 2);
+  assert.strictEqual(out[0].media_type, 'image/png');
+  assert.strictEqual(out[1].data, 'BBBB');
+});
+
+test('resolveImageInputs: rejects an invalid inline media type', () => {
+  assert.throws(
+    () => images.resolveImageInputs([{ media_type: 'application/pdf', data: 'x' }], {}),
+    /Unsupported image media type/i,
+  );
+});

package/test/max-iterations.test.js

@@ -0,0 +1,216 @@
+'use strict';
+
+// Iteration-cap tests (Pre-Task 4.0a). The primary agent loop must stop at an
+// explicit default (50), be overridable via --max-iterations / config, support
+// an explicit "unbounded" choice, terminate GRACEFULLY at the cap (clear
+// message + stopReason), and surface that stop reason in headless json output.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+
+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 { normalizeConfig, flagsConfigLayer, resolveMaxIterations } = require('../lib/config');
+const { DEFAULT_MAX_ITERATIONS } = require('../lib/constants');
+const { runHeadless } = require('../lib/headless');
+const { startMockLLM } = require('./harness/mock-llm');
+
+let prevKey;
+before(() => { prevKey = process.env.SEMALT_API_KEY; process.env.SEMALT_API_KEY = 'test-key'; });
+after(() => {
+  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 = (c) => { Object.assign(config, c); };
+  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,
+  });
+  return { runner, config };
+}
+
+function collector() {
+  const ev = { errors: [], tools: [] };
+  const cb = {
+    onToken: () => {},
+    onToolStart: () => {},
+    onToolEnd: (tag) => ev.tools.push(tag),
+    onError: (e) => ev.errors.push(e),
+    onAssistantMessage: () => {},
+  };
+  return { ev, cb };
+}
+
+// ---------------------------------------------------------------------------
+// 1. Reaching the cap terminates gracefully with a clear message + stopReason
+// ---------------------------------------------------------------------------
+
+test('reaching the iteration cap stops gracefully with a clear message and stopReason', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo a</exec>');
+  mock.replyWith('<exec>echo b</exec>');
+  mock.replyWith('<exec>echo c</exec>'); // would be a 3rd turn — must NOT be reached
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'loop forever' }];
+    const res = await runner.runAgentLoop(messages, 'test-model', 2, null, { callbacks: cb });
+
+    assert.strictEqual(res.stopReason, 'max_iterations', 'stopReason reports the cap');
+    assert.strictEqual(res.metrics.turns.length, 2, 'stopped at the cap');
+    assert.strictEqual(mock.requestCount(), 2, 'no third request made');
+
+    const warn = ev.errors.find((e) => e && /max(imum)?/i.test(e.message) && /iteration/i.test(e.message));
+    assert.ok(warn, 'a graceful cap message was surfaced');
+    assert.ok(warn.isWarning, 'cap message is a warning, not a hard error');
+    assert.match(warn.message, /2/, 'mentions the limit that was hit');
+    assert.match(warn.message, /--max-iterations/, 'tells the user how to raise it');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 2. --max-iterations / config overrides the default
+// ---------------------------------------------------------------------------
+
+test('an explicit cap overrides the default', async () => {
+  const mock = await startMockLLM();
+  for (let i = 0; i < 5; i++) mock.replyWith(`<exec>echo step${i}</exec>`);
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { cb } = collector();
+    const messages = [{ role: 'user', content: 'loop' }];
+    const res = await runner.runAgentLoop(messages, 'test-model', 3, null, { callbacks: cb });
+
+    assert.strictEqual(res.stopReason, 'max_iterations');
+    assert.strictEqual(res.metrics.turns.length, 3, 'honored the explicit cap of 3');
+    assert.strictEqual(mock.requestCount(), 3);
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 3. The unbounded option does not cap a naturally-terminating loop
+// ---------------------------------------------------------------------------
+
+test('unbounded (Infinity) runs until the model stops on its own', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo one</exec>');
+  mock.replyWith('<exec>echo two</exec>');
+  mock.replyWith('All done.');
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { cb } = collector();
+    const messages = [{ role: 'user', content: 'go' }];
+    const res = await runner.runAgentLoop(messages, 'test-model', Infinity, null, { callbacks: cb });
+
+    assert.notStrictEqual(res.stopReason, 'max_iterations', 'not stopped by a cap');
+    assert.strictEqual(res.stopReason, 'end_turn', 'ended on the final reply');
+    assert.strictEqual(mock.pending(), 0, 'ran to natural completion');
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'All done.'));
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 4. Config / flag resolution
+// ---------------------------------------------------------------------------
+
+test('config default max_iterations is 50', () => {
+  assert.strictEqual(DEFAULT_MAX_ITERATIONS, 50);
+  assert.strictEqual(normalizeConfig({}).max_iterations, 50);
+});
+
+test('normalizeConfig accepts a positive override and falls back on garbage', () => {
+  assert.strictEqual(normalizeConfig({ max_iterations: 7 }).max_iterations, 7);
+  assert.strictEqual(normalizeConfig({ max_iterations: -3 }).max_iterations, 50);
+  assert.strictEqual(normalizeConfig({ max_iterations: 'banana' }).max_iterations, 50);
+  assert.strictEqual(normalizeConfig({ max_iterations: 4.5 }).max_iterations, 50);
+});
+
+test('0 and "unlimited" normalize to the unlimited sentinel (0)', () => {
+  assert.strictEqual(normalizeConfig({ max_iterations: 0 }).max_iterations, 0);
+  assert.strictEqual(normalizeConfig({ max_iterations: 'unlimited' }).max_iterations, 0);
+  assert.strictEqual(normalizeConfig({ max_iterations: '0' }).max_iterations, 0);
+});
+
+test('--max-iterations flows through the flags config layer', () => {
+  assert.strictEqual(normalizeConfig(flagsConfigLayer(['--max-iterations', '12'])).max_iterations, 12);
+  assert.strictEqual(normalizeConfig(flagsConfigLayer(['--max-iterations', 'unlimited'])).max_iterations, 0);
+  assert.strictEqual(normalizeConfig(flagsConfigLayer(['--max-iterations', '0'])).max_iterations, 0);
+});
+
+test('resolveMaxIterations maps the unlimited sentinel to Infinity', () => {
+  assert.strictEqual(resolveMaxIterations(50), 50);
+  assert.strictEqual(resolveMaxIterations(7), 7);
+  assert.strictEqual(resolveMaxIterations(0), Infinity);
+  assert.strictEqual(resolveMaxIterations('unlimited'), Infinity);
+  assert.strictEqual(resolveMaxIterations(undefined), DEFAULT_MAX_ITERATIONS);
+  assert.strictEqual(resolveMaxIterations('garbage'), DEFAULT_MAX_ITERATIONS);
+});
+
+// ---------------------------------------------------------------------------
+// 5. Headless json surfaces the stop reason
+// ---------------------------------------------------------------------------
+
+test('headless json output reports stopReason when the cap is hit', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo a</exec>');
+  mock.replyWith('<exec>echo b</exec>');
+  mock.replyWith('<exec>echo c</exec>');
+  try {
+    const { runner } = buildRunner(mock.base);
+    let out = '';
+    await runHeadless({
+      runAgentLoop: runner.runAgentLoop,
+      messages: [{ role: 'user', content: 'loop' }],
+      model: 'test-model',
+      maxIterations: 2,
+      mode: 'json',
+      write: (s) => { out += s; },
+    });
+    const obj = JSON.parse(out.trim().split('\n').pop());
+    assert.strictEqual(obj.stopReason, 'max_iterations', 'json envelope carries the stop reason');
+  } finally {
+    await mock.close();
+  }
+});
+
+test('headless json reports end_turn on natural completion', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo a</exec>');
+  mock.replyWith('Done.');
+  try {
+    const { runner } = buildRunner(mock.base);
+    let out = '';
+    await runHeadless({
+      runAgentLoop: runner.runAgentLoop,
+      messages: [{ role: 'user', content: 'go' }],
+      model: 'test-model',
+      maxIterations: 10,
+      mode: 'json',
+      write: (s) => { out += s; },
+    });
+    const obj = JSON.parse(out.trim().split('\n').pop());
+    assert.strictEqual(obj.stopReason, 'end_turn');
+  } finally {
+    await mock.close();
+  }
+});