@semalt-ai/code 1.8.5 → 1.20.0

package/test/hooks.test.js

@@ -0,0 +1,216 @@
+'use strict';
+
+// Unit tests for lib/hooks.js (Task 3.4). Cover the pure normalization/matching
+// helpers and the dispatcher with an INJECTED spawn so exit-code semantics,
+// deny-list enforcement, timeout handling, and failure containment are tested
+// deterministically with no real subprocesses.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+const {
+  HOOK_EVENTS,
+  normalizeHooks,
+  normalizeHookDef,
+  hookMatches,
+  wrapUntrusted,
+  createHookRunner: _createHookRunner,
+} = require('../lib/hooks');
+
+// These tests exercise hook ORCHESTRATION (deny-list, exit semantics, matcher,
+// timeout/failure containment, payload) with an injected spawn — NOT the OS
+// sandbox, which has its own dedicated tests (hooks-verify-sandbox.test.js).
+// Inject a pass-through sandbox resolver so the command runs plain via the
+// 2-arg spawn(command, opts) form the injected stubs assume. The real sandbox
+// routing is proven separately.
+const NO_SANDBOX = (command) => ({ run: true, useShell: true, file: command, args: [], sandbox: 'off' });
+const createHookRunner = (opts = {}) => _createHookRunner({ sandbox: NO_SANDBOX, ...opts });
+
+// ---------------------------------------------------------------------------
+// normalizeHooks / normalizeHookDef
+// ---------------------------------------------------------------------------
+
+test('normalizeHooks always returns one array per known event', () => {
+  const out = normalizeHooks(undefined);
+  assert.deepStrictEqual(Object.keys(out).sort(), [...HOOK_EVENTS].sort());
+  for (const ev of HOOK_EVENTS) assert.deepStrictEqual(out[ev], []);
+});
+
+test('normalizeHooks drops malformed entries and unknown events', () => {
+  const out = normalizeHooks({
+    PreToolUse: [
+      { command: 'echo ok' },
+      { type: 'command' },              // no command → dropped
+      { type: 'prompt', prompt: '' },   // empty prompt → dropped
+      'not-an-object',                  // dropped
+      { type: 'prompt', prompt: 'hi' },
+    ],
+    BogusEvent: [{ command: 'echo nope' }], // unknown event key → ignored
+  });
+  assert.strictEqual(out.PreToolUse.length, 2);
+  assert.deepStrictEqual(out.PreToolUse[0], { type: 'command', command: 'echo ok' });
+  assert.deepStrictEqual(out.PreToolUse[1], { type: 'prompt', prompt: 'hi' });
+  assert.ok(!('BogusEvent' in out));
+});
+
+test('normalizeHookDef keeps matcher and positive integer timeout', () => {
+  const def = normalizeHookDef({ command: 'x', matcher: ' shell ', timeout_ms: 1500 });
+  assert.deepStrictEqual(def, { type: 'command', command: 'x', matcher: 'shell', timeout_ms: 1500 });
+  // Non-positive / non-integer timeouts are dropped.
+  assert.strictEqual(normalizeHookDef({ command: 'x', timeout_ms: 0 }).timeout_ms, undefined);
+  assert.strictEqual(normalizeHookDef({ command: 'x', timeout_ms: 1.5 }).timeout_ms, undefined);
+});
+
+// ---------------------------------------------------------------------------
+// hookMatches
+// ---------------------------------------------------------------------------
+
+test('hookMatches: no matcher / * matches everything', () => {
+  assert.ok(hookMatches({}, 'shell'));
+  assert.ok(hookMatches({ matcher: '*' }, 'anything'));
+});
+
+test('hookMatches: exact, pipe-list, and regex', () => {
+  assert.ok(hookMatches({ matcher: 'shell' }, 'shell'));
+  assert.ok(!hookMatches({ matcher: 'shell' }, 'read'));
+  assert.ok(hookMatches({ matcher: 'shell|exec' }, 'exec'));
+  assert.ok(hookMatches({ matcher: 'mcp__.*' }, 'mcp__fs__read'));
+  assert.ok(!hookMatches({ matcher: 'mcp__.*' }, 'shell'));
+  // Anchored: a partial name does not match.
+  assert.ok(!hookMatches({ matcher: 'read' }, 'read_file'));
+});
+
+test('wrapUntrusted fences text in the shared delimiter', () => {
+  const w = wrapUntrusted('payload', '[hook X]');
+  assert.match(w, /<<<UNTRUSTED_EXTERNAL_CONTENT/);
+  assert.match(w, /<<<END_UNTRUSTED_EXTERNAL_CONTENT>>>/);
+  assert.match(w, /payload/);
+  assert.match(w, /\[hook X\]/);
+});
+
+// ---------------------------------------------------------------------------
+// createHookRunner — dispatch with an injected spawn
+// ---------------------------------------------------------------------------
+
+// A spawn stub: maps a command string → a spawnSync-shaped result.
+function fakeSpawn(map) {
+  const calls = [];
+  const fn = (command, opts) => {
+    calls.push({ command, opts });
+    const r = typeof map === 'function' ? map(command, opts) : map[command];
+    return r || { status: 0, stdout: '', stderr: '' };
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+test('PreToolUse: non-zero exit BLOCKS and surfaces the reason', async () => {
+  const getConfig = () => ({ hooks: { PreToolUse: [{ type: 'command', command: 'guard' }] } });
+  const spawn = fakeSpawn({ guard: { status: 1, stdout: 'not allowed to touch prod', stderr: '' } });
+  const runner = createHookRunner({ getConfig, spawn });
+  const r = await runner.run('PreToolUse', { tool: 'shell', input: { command: 'deploy' } });
+  assert.strictEqual(r.blocked, true);
+  assert.match(r.blockReason, /not allowed to touch prod/);
+  assert.strictEqual(r.feedback.length, 0, 'a blocking hook does not also emit feedback');
+});
+
+test('PreToolUse: exit 0 ALLOWS, and stdout is surfaced as untrusted feedback', async () => {
+  const getConfig = () => ({ hooks: { PreToolUse: [{ type: 'command', command: 'note' }] } });
+  const spawn = fakeSpawn({ note: { status: 0, stdout: 'fyi: linting first', stderr: '' } });
+  const runner = createHookRunner({ getConfig, spawn });
+  const r = await runner.run('PreToolUse', { tool: 'shell' });
+  assert.strictEqual(r.blocked, false);
+  assert.strictEqual(r.feedback.length, 1);
+  assert.match(r.feedback[0], /fyi: linting first/);
+  assert.match(r.feedback[0], /UNTRUSTED_EXTERNAL_CONTENT/);
+});
+
+test('matcher filters which hooks run for a tool event', async () => {
+  const getConfig = () => ({ hooks: { PreToolUse: [
+    { type: 'command', command: 'only-shell', matcher: 'shell' },
+  ] } });
+  const spawn = fakeSpawn({ 'only-shell': { status: 1, stdout: 'blocked', stderr: '' } });
+  const runner = createHookRunner({ getConfig, spawn });
+
+  const blocked = await runner.run('PreToolUse', { tool: 'shell' });
+  assert.strictEqual(blocked.blocked, true);
+
+  const other = await runner.run('PreToolUse', { tool: 'read' });
+  assert.strictEqual(other.blocked, false, 'non-matching tool is unaffected');
+  assert.strictEqual(spawn.calls.length, 1, 'the hook only ran for the matching tool');
+});
+
+test('deny-listed hook command is NOT run (skipped, contained)', async () => {
+  const getConfig = () => ({ hooks: { PreToolUse: [{ type: 'command', command: 'rm -rf /' }] } });
+  const spawn = fakeSpawn(() => { throw new Error('spawn must not be called for a denied hook'); });
+  const logs = [];
+  const runner = createHookRunner({ getConfig, spawn, log: (m) => logs.push(m) });
+  const r = await runner.run('PreToolUse', { tool: 'shell' });
+  assert.strictEqual(spawn.calls.length, 0, 'deny-listed command never spawned');
+  assert.strictEqual(r.blocked, false, 'a denied hook does not block the tool');
+  assert.strictEqual(r.ran[0].denied && typeof r.ran[0].denied, 'string');
+  assert.ok(logs.some((l) => /deny-list/i.test(l)));
+});
+
+test('timeout is contained: not a block, not feedback, just logged', async () => {
+  const getConfig = () => ({ hooks: { PreToolUse: [{ type: 'command', command: 'slow', timeout_ms: 10 }] } });
+  // spawnSync surfaces a timeout via error.code ETIMEDOUT + signal SIGTERM.
+  const spawn = fakeSpawn({ slow: { status: null, signal: 'SIGTERM', stdout: '', stderr: '', error: { code: 'ETIMEDOUT', message: 'spawnSync timed out' } } });
+  const logs = [];
+  const runner = createHookRunner({ getConfig, spawn, log: (m) => logs.push(m) });
+  const r = await runner.run('PreToolUse', { tool: 'shell' });
+  assert.strictEqual(r.blocked, false, 'a timed-out PreToolUse hook does not block');
+  assert.strictEqual(r.feedback.length, 0);
+  assert.strictEqual(r.ran[0].timedOut, true);
+  assert.ok(logs.some((l) => /timed out/i.test(l)));
+});
+
+test('a spawn that throws is contained (no crash, recorded as failed)', async () => {
+  const getConfig = () => ({ hooks: { PostToolUse: [{ type: 'command', command: 'boom' }] } });
+  const spawn = fakeSpawn(() => { throw new Error('kaboom'); });
+  const runner = createHookRunner({ getConfig, spawn });
+  const r = await runner.run('PostToolUse', { tool: 'shell', result: 'x' });
+  assert.strictEqual(r.blocked, false);
+  assert.strictEqual(r.ran[0].ok, false);
+  assert.match(r.ran[0].error, /kaboom/);
+});
+
+test('prompt hook injects its text as untrusted feedback (no shell)', async () => {
+  const getConfig = () => ({ hooks: { UserPromptSubmit: [{ type: 'prompt', prompt: 'Follow the style guide.' }] } });
+  const spawn = fakeSpawn(() => { throw new Error('prompt hooks never spawn'); });
+  const runner = createHookRunner({ getConfig, spawn });
+  const r = await runner.run('UserPromptSubmit', { prompt: 'do a thing' });
+  assert.strictEqual(spawn.calls.length, 0);
+  assert.strictEqual(r.feedback.length, 1);
+  assert.match(r.feedback[0], /Follow the style guide/);
+});
+
+test('payload reaches the hook via env vars and stdin', async () => {
+  const getConfig = () => ({ hooks: { PostToolUse: [{ type: 'command', command: 'capture' }] } });
+  let seen = null;
+  const spawn = fakeSpawn((command, opts) => { seen = opts; return { status: 0, stdout: '', stderr: '' }; });
+  const runner = createHookRunner({ getConfig, spawn });
+  await runner.run('PostToolUse', { tool: 'read', input: { path: '/a' }, result: 'contents' });
+  assert.strictEqual(seen.env.SEMALT_HOOK_EVENT, 'PostToolUse');
+  assert.strictEqual(seen.env.SEMALT_TOOL_NAME, 'read');
+  assert.strictEqual(seen.env.SEMALT_TOOL_INPUT, JSON.stringify({ path: '/a' }));
+  assert.strictEqual(seen.env.SEMALT_TOOL_RESULT, 'contents');
+  const stdin = JSON.parse(seen.input);
+  assert.strictEqual(stdin.event, 'PostToolUse');
+  assert.strictEqual(stdin.tool, 'read');
+});
+
+test('unknown event name is a no-op', async () => {
+  const getConfig = () => ({ hooks: {} });
+  const runner = createHookRunner({ getConfig, spawn: fakeSpawn({}) });
+  const r = await runner.run('NotARealEvent', {});
+  assert.deepStrictEqual(r.feedback, []);
+  assert.strictEqual(r.blocked, false);
+});
+
+test('a getConfig that throws is contained (no hooks, no crash)', async () => {
+  const runner = createHookRunner({ getConfig: () => { throw new Error('boom'); }, spawn: fakeSpawn({}) });
+  const r = await runner.run('PreToolUse', { tool: 'shell' });
+  assert.strictEqual(r.blocked, false);
+  assert.deepStrictEqual(r.ran, []);
+});

package/test/http-get-user-agent.test.js

@@ -0,0 +1,142 @@
+'use strict';
+
+// http_get / download User-Agent (Task W.3 Part 2). The fetch tools must send a
+// fixed, realistic browser User-Agent so sites that reject empty/curl-like UAs
+// (Wikipedia 403, the Guardian 406) are less likely to block. It is:
+//   - operator-overridable via config.web.user_agent,
+//   - NOT model-selectable (no UA parameter in the tool spec the model sees),
+//   - applied uniformly to both http_get and download.
+//
+// Home-based paths are redirected to a temp dir BEFORE any lib module loads so
+// the secret-file/config guards resolve against the temp config path.
+
+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-ua-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 http = require('node:http');
+
+const ui = require('../lib/ui');
+const { createPermissionManager } = require('../lib/permissions');
+const { createToolExecutor } = require('../lib/tools');
+const { DEFAULT_USER_AGENT } = require('../lib/constants');
+const { normalizeConfig } = require('../lib/config');
+const { TOOL_SPECS } = require('../lib/tool_specs');
+
+let CWD;
+let PREV_CWD;
+let server;
+let baseUrl;
+let lastUserAgent; // captured from the most recent inbound request
+
+function mkExec({ web } = {}) {
+  const pm = createPermissionManager(ui, {});
+  const getConfig = () => ({
+    max_file_size_kb: 512,
+    command_timeout_ms: 30000,
+    http_fetch_max_bytes: 262144,
+    download_max_bytes: 1048576,
+    // summarize off → predictable pass-through, no summarizer needed.
+    web: { summarize: false, summary_model: '', max_content_tokens: 6000, ...(web || {}) },
+  });
+  return createToolExecutor(pm, ui, getConfig, {});
+}
+
+before(async () => {
+  PREV_CWD = process.cwd();
+  CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-ua-cwd-'));
+  process.chdir(CWD);
+  server = http.createServer((req, res) => {
+    lastUserAgent = req.headers['user-agent'];
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('hello body');
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  baseUrl = `http://127.0.0.1:${server.address().port}`;
+});
+
+after(async () => {
+  await new Promise((r) => server.close(r));
+  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;
+});
+
+// ---------------------------------------------------------------------------
+// http_get sends the default / configured UA
+// ---------------------------------------------------------------------------
+
+test('http_get: sends the default browser User-Agent', async () => {
+  const exec = mkExec();
+  lastUserAgent = undefined;
+  const r = await exec.agentExecFile('http_get', `${baseUrl}/page`, {}, { signal: null });
+  assert.ok(!r.error, `valid URL should not error: ${r.error}`);
+  assert.strictEqual(lastUserAgent, DEFAULT_USER_AGENT);
+  // The default looks like a real browser, not curl / empty.
+  assert.match(lastUserAgent, /Mozilla\/5\.0/);
+  assert.match(lastUserAgent, /Chrome\/\d+/);
+});
+
+test('http_get: a config web.user_agent override is honored', async () => {
+  const exec = mkExec({ web: { user_agent: 'AcmeCorpBot/2.0 (+https://acme.example/bot)' } });
+  lastUserAgent = undefined;
+  await exec.agentExecFile('http_get', `${baseUrl}/page`, {}, { signal: null });
+  assert.strictEqual(lastUserAgent, 'AcmeCorpBot/2.0 (+https://acme.example/bot)');
+});
+
+// ---------------------------------------------------------------------------
+// download carries the same UA
+// ---------------------------------------------------------------------------
+
+test('download: sends the default browser User-Agent', async () => {
+  const exec = mkExec();
+  lastUserAgent = undefined;
+  const r = await exec.agentExecFile('download', `${baseUrl}/file.txt`, 'file.txt');
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(lastUserAgent, DEFAULT_USER_AGENT);
+});
+
+test('download: a config web.user_agent override is honored', async () => {
+  const exec = mkExec({ web: { user_agent: 'AcmeCorpBot/2.0' } });
+  lastUserAgent = undefined;
+  await exec.agentExecFile('download', `${baseUrl}/file2.txt`, 'file2.txt');
+  assert.strictEqual(lastUserAgent, 'AcmeCorpBot/2.0');
+});
+
+// ---------------------------------------------------------------------------
+// The UA is operator-only — never exposed to the model
+// ---------------------------------------------------------------------------
+
+test('the tool spec exposes NO user-agent parameter (not model-selectable)', () => {
+  for (const tool of ['http_get', 'download']) {
+    const spec = TOOL_SPECS[tool];
+    const props = (spec && spec.parameters && spec.parameters.properties) || {};
+    for (const key of Object.keys(props)) {
+      assert.ok(!/user.?agent|^ua$|headers?/i.test(key),
+        `${tool} spec must not expose a UA/header parameter, found "${key}"`);
+    }
+    // Belt-and-suspenders: the whole spec JSON never mentions a user-agent knob.
+    assert.ok(!/user.?agent/i.test(JSON.stringify(spec)),
+      `${tool} spec text must not mention user-agent`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Normalization: config.web.user_agent defaults to the fixed UA
+// ---------------------------------------------------------------------------
+
+test('config normalization: web.user_agent defaults to DEFAULT_USER_AGENT, override trims', () => {
+  assert.strictEqual(normalizeConfig({}).web.user_agent, DEFAULT_USER_AGENT);
+  assert.strictEqual(normalizeConfig({ web: {} }).web.user_agent, DEFAULT_USER_AGENT);
+  assert.strictEqual(normalizeConfig({ web: { user_agent: '  CustomUA/1  ' } }).web.user_agent, 'CustomUA/1');
+  // An empty/whitespace override falls back to the default, not ''.
+  assert.strictEqual(normalizeConfig({ web: { user_agent: '   ' } }).web.user_agent, DEFAULT_USER_AGENT);
+});

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