@semalt-ai/code 1.8.5 → 1.19.0

package/test/headless.test.js

@@ -0,0 +1,203 @@
+'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 } = 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();
+  }
+});

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' }]);
+});

package/test/hooks-agent.test.js

@@ -0,0 +1,238 @@
+'use strict';
+
+// Integration tests for lifecycle hooks (Task 3.4) driving the REAL runAgentLoop
+// against the mock-LLM harness, with the REAL createHookRunner reading
+// config.hooks (so spawnSync actually runs the hook commands). Hook commands use
+// `node -e …` so they are portable across the CI matrix (Linux/macOS/Windows).
+// Sentinel paths are passed via env vars (merged into the hook's environment) to
+// avoid embedding OS-specific path separators in a `node -e` string literal.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('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');
+
+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;
+});
+
+const NODE = JSON.stringify(process.execPath);
+
+// buildRunner mirrors agent-loop.test.js, but threads `hooks` into the config so
+// the real hook runner (built inside createAgentRunner from getConfig) sees them.
+function buildRunner(base, hooks) {
+  const config = {
+    api_base: base, api_key: 'test-key', default_model: 'test-model',
+    temperature: 0.5, request_timeout_ms: 5000, stream: true, models: [],
+    hooks: hooks || {},
+    // This suite tests hook ORCHESTRATION, not the OS sandbox (covered by
+    // hooks-verify-sandbox.test.js). Disable the sandbox so the command hooks
+    // run deterministically across the CI matrix regardless of bwrap/Seatbelt.
+    sandbox: { mode: 'off' },
+  };
+  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 = { tools: [], errors: [], assistants: [] };
+  const cb = {
+    onToolEnd: (tag, result) => ev.tools.push({ tag, result }),
+    onError: (e) => ev.errors.push(e),
+    onAssistantMessage: (m) => ev.assistants.push(m),
+  };
+  return { ev, cb };
+}
+
+function tmpdir() { return fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-hooks-')); }
+
+// ---------------------------------------------------------------------------
+// 1. PreToolUse hook blocks a tool (non-zero exit) — the tool never runs
+// ---------------------------------------------------------------------------
+
+test('PreToolUse hook with a non-zero exit BLOCKS the tool; it does not run and the agent gets the reason', async () => {
+  const dir = tmpdir();
+  const sentinel = path.join(dir, 'written.txt');
+  const hooks = { PreToolUse: [{
+    type: 'command', matcher: '*',
+    command: `${NODE} -e "process.stdout.write('blocked: writes are frozen'); process.exit(1)"`,
+  }] };
+  const mock = await startMockLLM();
+  // The model tries to write a file; the hook must stop it.
+  mock.replyWith(`<write_file path="${sentinel}">DATA</write_file>`);
+  mock.replyWith('Understood, I will not write.');
+  try {
+    const { runner } = buildRunner(mock.base, hooks);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'write the file' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.ok(!fs.existsSync(sentinel), 'the write tool was blocked — no file on disk');
+    assert.strictEqual(ev.tools.length, 0, 'a blocked tool never reaches onToolEnd');
+    const fed = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+    assert.ok(fed, 'the blocked-tool result is fed back to the model');
+    assert.match(fed.content, /BLOCKED by a PreToolUse hook/);
+    assert.match(fed.content, /writes are frozen/, 'hook stdout is the block reason');
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'Understood, I will not write.'));
+  } finally {
+    await mock.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 2. PostToolUse hook observes a result and injects feedback
+// ---------------------------------------------------------------------------
+
+test('PostToolUse hook observes the tool result and its stdout is appended (untrusted-fenced)', async () => {
+  const dir = tmpdir();
+  const file = path.join(dir, 'fixture.txt');
+  fs.writeFileSync(file, 'FILE_BODY_7', 'utf8');
+  const hooks = { PostToolUse: [{
+    type: 'command',
+    // Echo back the tool name the hook saw via env — proof it observed the call.
+    command: `${NODE} -e "process.stdout.write('POSTHOOK_SAW=' + process.env.SEMALT_TOOL_NAME)"`,
+  }] };
+  const mock = await startMockLLM();
+  mock.replyWith(`<read_file>${file}</read_file>`);
+  mock.replyWith('Read it.');
+  try {
+    const { runner } = buildRunner(mock.base, hooks);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'read the file' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.strictEqual(ev.tools.length, 1);
+    assert.strictEqual(ev.tools[0].tag, 'read');
+    const fed = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+    assert.ok(fed);
+    assert.match(fed.content, /FILE_BODY_7/, 'the real tool result is present');
+    assert.match(fed.content, /POSTHOOK_SAW=read/, 'PostToolUse stdout was appended');
+    assert.match(fed.content, /UNTRUSTED_EXTERNAL_CONTENT/, 'hook feedback is fenced as untrusted');
+  } finally {
+    await mock.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 3. UserPromptSubmit hook injects context before the loop
+// ---------------------------------------------------------------------------
+
+test('UserPromptSubmit hook stdout is injected into the conversation as context', async () => {
+  const hooks = { UserPromptSubmit: [{
+    type: 'command',
+    command: `${NODE} -e "process.stdout.write('INJECTED_CONTEXT_42')"`,
+  }] };
+  const mock = await startMockLLM();
+  mock.replyWith('Acknowledged.');
+  try {
+    const { runner } = buildRunner(mock.base, hooks);
+    const { cb } = collector();
+    const messages = [{ role: 'user', content: 'hello' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    const injected = messages.find((m) => m.role === 'user' && /INJECTED_CONTEXT_42/.test(m.content));
+    assert.ok(injected, 'hook output was injected as a user message');
+    assert.match(injected.content, /UNTRUSTED_EXTERNAL_CONTENT/, 'injected context is fenced as untrusted');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 4. A failing hook does not crash the loop
+// ---------------------------------------------------------------------------
+
+test('a failing (non-zero, no-output) PostToolUse hook is contained — the loop completes normally', async () => {
+  const hooks = { PostToolUse: [{ type: 'command', command: `${NODE} -e "process.exit(3)"` }] };
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo hi</exec>');
+  mock.replyWith('All good.');
+  try {
+    const { runner } = buildRunner(mock.base, hooks);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'run it' }];
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.strictEqual(ev.tools.length, 1, 'the tool still executed');
+    assert.strictEqual(metrics.turns.length, 2, 'tool turn + final turn — the loop did not crash');
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'All good.'));
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 5. A deny-listed hook command is never executed
+// ---------------------------------------------------------------------------
+
+test('a deny-listed PreToolUse hook command is skipped (never run) and does not block the tool', async () => {
+  const hooks = { PreToolUse: [{ type: 'command', matcher: '*', command: 'rm -rf /' }] };
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo ALLOWED</exec>');
+  mock.replyWith('Done.');
+  try {
+    const { runner } = buildRunner(mock.base, hooks);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'go' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    // The deny-listed hook is skipped, so the tool is NOT blocked and runs.
+    assert.strictEqual(ev.tools.length, 1, 'tool ran — a denied hook does not block');
+    const fed = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+    assert.match(fed.content, /ALLOWED/);
+    assert.ok(!fed.content.includes('BLOCKED by a PreToolUse hook'), 'no spurious block');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 6. Stop hook fires once when the turn ends
+// ---------------------------------------------------------------------------
+
+test('Stop hook fires when the agent loop finishes the turn', async () => {
+  const dir = tmpdir();
+  const sentinel = path.join(dir, 'stopped.txt');
+  const prev = process.env.SEMALT_TEST_STOP_FILE;
+  process.env.SEMALT_TEST_STOP_FILE = sentinel;
+  const hooks = { Stop: [{
+    type: 'command',
+    command: `${NODE} -e "require('fs').writeFileSync(process.env.SEMALT_TEST_STOP_FILE,'x')"`,
+  }] };
+  const mock = await startMockLLM();
+  mock.replyWith('Final answer, no tools.');
+  try {
+    const { runner } = buildRunner(mock.base, hooks);
+    const { cb } = collector();
+    const messages = [{ role: 'user', content: 'just answer' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+    assert.ok(fs.existsSync(sentinel), 'the Stop hook ran at end of turn');
+  } finally {
+    await mock.close();
+    if (prev === undefined) delete process.env.SEMALT_TEST_STOP_FILE;
+    else process.env.SEMALT_TEST_STOP_FILE = prev;
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});