@semalt-ai/code 1.8.5 → 1.20.0

package/test/sandbox.test.js

@@ -0,0 +1,408 @@
+'use strict';
+
+// Unit tests for the OS sandbox layer (Task 4.4). These cover the PURE pieces —
+// config normalization, platform detection (with injected tooling so they run on
+// any OS), policy/argv generation, command wrapping, the config×detection
+// decision, and the fallback rules — without requiring a real bwrap/sandbox-exec
+// on the runner. Kernel-level enforcement is exercised separately in
+// test/sandbox-integration.test.js (which skips gracefully when the primitive is
+// absent, mirroring the ripgrep-parity pattern).
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const sandbox = require('../lib/sandbox');
+const {
+  normalizeSandbox, protectedPaths, buildSeatbeltPolicy, buildBwrapArgs,
+  detectSandbox, _resetSandboxDetection, wrapCommand, decideSandbox, sandboxStatusReport,
+} = sandbox;
+
+// ---------------------------------------------------------------------------
+// normalizeSandbox
+// ---------------------------------------------------------------------------
+
+test('normalizeSandbox defaults to auto + no hard gate + network on', () => {
+  assert.deepStrictEqual(normalizeSandbox(undefined), { mode: 'auto', failIfUnavailable: false, network: 'on' });
+  assert.deepStrictEqual(normalizeSandbox({}), { mode: 'auto', failIfUnavailable: false, network: 'on' });
+  assert.deepStrictEqual(normalizeSandbox(null), { mode: 'auto', failIfUnavailable: false, network: 'on' });
+  assert.deepStrictEqual(normalizeSandbox('off'), { mode: 'auto', failIfUnavailable: false, network: 'on' });
+});
+
+test('normalizeSandbox honors off + failIfUnavailable', () => {
+  assert.deepStrictEqual(normalizeSandbox({ mode: 'off' }), { mode: 'off', failIfUnavailable: false, network: 'on' });
+  assert.deepStrictEqual(normalizeSandbox({ failIfUnavailable: true }), { mode: 'auto', failIfUnavailable: true, network: 'on' });
+  assert.deepStrictEqual(normalizeSandbox({ mode: 'off', failIfUnavailable: true }), { mode: 'off', failIfUnavailable: true, network: 'on' });
+});
+
+test('normalizeSandbox rejects unknown modes / truthy-but-not-true flags', () => {
+  assert.strictEqual(normalizeSandbox({ mode: 'on' }).mode, 'auto');
+  assert.strictEqual(normalizeSandbox({ mode: 'disabled' }).mode, 'auto');
+  assert.strictEqual(normalizeSandbox({ failIfUnavailable: 'yes' }).failIfUnavailable, false);
+  assert.strictEqual(normalizeSandbox({ failIfUnavailable: 1 }).failIfUnavailable, false);
+});
+
+// --- network: binary on/off + anti-fail-open (Task 4.4b, CVE-2025-66479 lesson) ---
+
+test('normalizeSandbox: network defaults ON only when the key is ABSENT', () => {
+  assert.strictEqual(normalizeSandbox({}).network, 'on');
+  assert.strictEqual(normalizeSandbox({ mode: 'auto' }).network, 'on');
+  assert.strictEqual(normalizeSandbox({ network: 'on' }).network, 'on');
+});
+
+test('normalizeSandbox: explicit network off resolves to off', () => {
+  assert.strictEqual(normalizeSandbox({ network: 'off' }).network, 'off');
+});
+
+test('ANTI-FAIL-OPEN: a PRESENT-but-malformed network value resolves to off (never silently on)', () => {
+  // The allowedDomains:[] → "allow all" trap (CVE-2025-66479): once the human has
+  // TOUCHED the network key, anything we do not recognize as exactly 'on' must be
+  // the SAFE isolated state. The intended-most-restrictive input is the most
+  // restrictive outcome.
+  for (const bad of ['', 'On', 'ON', 'enabled', 'true', 'yes', '0', 'allow', {}, [], null, false, true, 0, 1]) {
+    assert.strictEqual(normalizeSandbox({ network: bad }).network, 'off',
+      `network=${JSON.stringify(bad)} must fail toward isolation (off)`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// protectedPaths (constraint #2)
+// ---------------------------------------------------------------------------
+
+test('protectedPaths includes ~/.semalt-ai, secret dirs, and /etc', () => {
+  const home = '/home/tester';
+  const ps = protectedPaths({ home });
+  // realpathSync may resolve missing paths to themselves (path.resolve fallback).
+  assert.ok(ps.includes(path.join(home, '.semalt-ai')), 'must protect the config dir');
+  assert.ok(ps.includes(path.join(home, '.ssh')), 'must protect ~/.ssh');
+  assert.ok(ps.includes(path.join(home, '.aws')), 'must protect ~/.aws');
+  assert.ok(ps.includes(path.join(home, '.gnupg')), 'must protect ~/.gnupg');
+  assert.ok(ps.includes('/etc'), 'must protect /etc');
+});
+
+test('protectedPaths includes the project .semalt dir for the given cwd (Pre-Task 5.0b)', () => {
+  // A real cwd (no .git) so the walk halts at the filesystem root; the .semalt
+  // dir directly under cwd must be among the protected paths so a sandboxed
+  // shell cannot write .semalt/config.json even though cwd is writable.
+  const cwd = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-sbx-cfg-')));
+  const ps = protectedPaths({ home: '/home/tester', cwd });
+  assert.ok(ps.includes(path.join(cwd, '.semalt')), 'must protect the project .semalt dir');
+});
+
+// ---------------------------------------------------------------------------
+// buildSeatbeltPolicy (macOS)
+// ---------------------------------------------------------------------------
+
+test('buildSeatbeltPolicy denies all writes then re-allows working dir, re-denies protected', () => {
+  const policy = buildSeatbeltPolicy({
+    writableRoots: ['/work/dir'],
+    protectedPaths: ['/home/tester/.semalt-ai', '/etc'],
+    rootWritable: false,
+  });
+  assert.match(policy, /\(version 1\)/);
+  assert.match(policy, /\(allow default\)/);
+  assert.match(policy, /\(deny file-write\* \(subpath "\/"\)\)/);
+  assert.match(policy, /\(allow file-write\* \(subpath "\/work\/dir"\)\)/);
+  // protected re-denials come AFTER the allow so last-match-wins denies them.
+  const denyAll = policy.indexOf('(deny file-write* (subpath "/"))');
+  const allowWork = policy.indexOf('(allow file-write* (subpath "/work/dir"))');
+  const denySemalt = policy.indexOf('(deny file-write* (subpath "/home/tester/.semalt-ai"))');
+  assert.ok(denyAll < allowWork, 'deny-all precedes allow-work');
+  assert.ok(allowWork < denySemalt, 'protected re-deny comes last (wins)');
+});
+
+test('buildSeatbeltPolicy: network off adds a (deny network*) clause; on does not', () => {
+  const off = buildSeatbeltPolicy({ writableRoots: ['/w'], protectedPaths: [], network: 'off' });
+  assert.match(off, /\(deny network\*\)/);
+  // The network deny must come right after (allow default) so last-match-wins keeps it.
+  assert.ok(off.indexOf('(allow default)') < off.indexOf('(deny network*)'));
+  const on = buildSeatbeltPolicy({ writableRoots: ['/w'], protectedPaths: [], network: 'on' });
+  assert.doesNotMatch(on, /\(deny network\*\)/);
+  // Default (omitted) is network on — no deny clause.
+  assert.doesNotMatch(buildSeatbeltPolicy({ writableRoots: ['/w'], protectedPaths: [] }), /\(deny network\*\)/);
+});
+
+test('buildSeatbeltPolicy with rootWritable skips the blanket deny but still re-denies protected', () => {
+  const policy = buildSeatbeltPolicy({
+    writableRoots: [],
+    protectedPaths: ['/home/tester/.semalt-ai'],
+    rootWritable: true,
+  });
+  assert.doesNotMatch(policy, /\(deny file-write\* \(subpath "\/"\)\)/);
+  assert.match(policy, /\(deny file-write\* \(subpath "\/home\/tester\/\.semalt-ai"\)\)/);
+});
+
+// ---------------------------------------------------------------------------
+// buildBwrapArgs (Linux)
+// ---------------------------------------------------------------------------
+
+test('buildBwrapArgs ro-binds root, fresh /proc, rw working dir, ro protected, chdir', () => {
+  const args = buildBwrapArgs({
+    writableRoots: ['/work'],
+    protectedPaths: ['/prot'],
+    rootWritable: false,
+    chdir: '/work',
+    fsExists: () => true,
+  });
+  const j = args.join(' ');
+  assert.match(j, /--ro-bind \/ \//);
+  assert.match(j, /--proc \/proc/); // fresh procfs ⇒ /proc/self/root confined (constraint #3)
+  assert.match(j, /--bind \/work \/work/);
+  assert.match(j, /--ro-bind \/prot \/prot/);
+  assert.match(j, /--chdir \/work/);
+  // protected ro-bind must come AFTER the writable bind so it wins on overlap.
+  assert.ok(j.indexOf('--bind /work /work') < j.indexOf('--ro-bind /prot /prot'));
+});
+
+test('buildBwrapArgs: network off adds --unshare-net; on (and default) does not', () => {
+  const off = buildBwrapArgs({ writableRoots: ['/work'], protectedPaths: [], chdir: '/work', fsExists: () => true, network: 'off' });
+  assert.ok(off.includes('--unshare-net'), 'no-network jail must unshare the network namespace');
+  const on = buildBwrapArgs({ writableRoots: ['/work'], protectedPaths: [], chdir: '/work', fsExists: () => true, network: 'on' });
+  assert.ok(!on.includes('--unshare-net'), 'network-on jail keeps the host network');
+  const dflt = buildBwrapArgs({ writableRoots: ['/work'], protectedPaths: [], chdir: '/work', fsExists: () => true });
+  assert.ok(!dflt.includes('--unshare-net'), 'default is network on');
+});
+
+test('buildBwrapArgs rootWritable binds / read-write (for --allow-anywhere) but keeps protected ro', () => {
+  const args = buildBwrapArgs({
+    writableRoots: [],
+    protectedPaths: ['/prot'],
+    rootWritable: true,
+    chdir: '/work',
+    fsExists: () => true,
+  });
+  const j = args.join(' ');
+  assert.match(j, /--bind \/ \//);
+  assert.doesNotMatch(j, /--ro-bind \/ \//);
+  assert.match(j, /--ro-bind \/prot \/prot/); // protected stays read-only even under allow-anywhere
+});
+
+test('buildBwrapArgs skips binds for paths that do not exist', () => {
+  const args = buildBwrapArgs({
+    writableRoots: ['/missing'],
+    protectedPaths: ['/also-missing'],
+    rootWritable: false,
+    chdir: '/work',
+    fsExists: (p) => p === '/', // only root exists
+  });
+  const j = args.join(' ');
+  assert.doesNotMatch(j, /--bind \/missing/);
+  assert.doesNotMatch(j, /--ro-bind \/also-missing/);
+});
+
+// ---------------------------------------------------------------------------
+// detectSandbox — every platform path, with injected tooling
+// ---------------------------------------------------------------------------
+
+test('detectSandbox: macOS uses sandbox-exec when present', () => {
+  _resetSandboxDetection();
+  const d = detectSandbox({ platform: 'darwin', which: () => '/usr/bin/sandbox-exec', force: true, noCache: true });
+  assert.strictEqual(d.supported, true);
+  assert.strictEqual(d.tool, 'sandbox-exec');
+  assert.strictEqual(d.available, true);
+});
+
+test('detectSandbox: Linux with usable bwrap is available', () => {
+  _resetSandboxDetection();
+  const d = detectSandbox({
+    platform: 'linux',
+    which: (n) => (n === 'bwrap' ? '/usr/bin/bwrap' : null),
+    probe: () => true,
+    readFile: () => 'Linux version 6.0',
+    force: true, noCache: true,
+  });
+  assert.strictEqual(d.tool, 'bwrap');
+  assert.strictEqual(d.available, true);
+});
+
+test('detectSandbox: Linux without bwrap is unavailable with an install hint', () => {
+  _resetSandboxDetection();
+  const d = detectSandbox({
+    platform: 'linux',
+    which: () => null,
+    readFile: () => 'Linux version 6.0',
+    force: true, noCache: true,
+  });
+  assert.strictEqual(d.available, false);
+  assert.match(d.reason, /not found/);
+  assert.match(d.installHint, /bubblewrap/);
+});
+
+test('detectSandbox: Linux with bwrap present but unusable (probe fails) is unavailable', () => {
+  _resetSandboxDetection();
+  const d = detectSandbox({
+    platform: 'linux',
+    which: () => '/usr/bin/bwrap',
+    probe: () => false,
+    readFile: () => 'Linux version 6.0',
+    force: true, noCache: true,
+  });
+  assert.strictEqual(d.available, false);
+  assert.match(d.reason, /could not start a jail|namespaces/);
+});
+
+test('detectSandbox: WSL1 is detected and explained even if bwrap is installed', () => {
+  _resetSandboxDetection();
+  const d = detectSandbox({
+    platform: 'linux',
+    which: () => '/usr/bin/bwrap',
+    probe: () => false,
+    readFile: () => 'Linux version 4.4.0-19041-Microsoft (WSL)',
+    force: true, noCache: true,
+  });
+  assert.strictEqual(d.available, false);
+  assert.match(d.reason, /WSL1/);
+  assert.match(d.installHint, /WSL2/);
+});
+
+test('detectSandbox: native Windows is unsupported, not crashing', () => {
+  _resetSandboxDetection();
+  const d = detectSandbox({ platform: 'win32', force: true, noCache: true });
+  assert.strictEqual(d.supported, false);
+  assert.strictEqual(d.available, false);
+  assert.match(d.reason, /Windows/);
+});
+
+test('detectSandbox caches by default and force re-evaluates', () => {
+  _resetSandboxDetection();
+  let calls = 0;
+  const which = () => { calls++; return '/usr/bin/sandbox-exec'; };
+  detectSandbox({ platform: 'darwin', which, force: true });
+  detectSandbox({ platform: 'darwin', which }); // cached
+  assert.strictEqual(calls, 1, 'second call should hit the cache');
+  detectSandbox({ platform: 'darwin', which, force: true });
+  assert.strictEqual(calls, 2, 'force re-evaluates');
+  _resetSandboxDetection();
+});
+
+// ---------------------------------------------------------------------------
+// wrapCommand
+// ---------------------------------------------------------------------------
+
+test('wrapCommand builds a bwrap argv that runs the command via /bin/sh -c', () => {
+  const w = wrapCommand('echo hi', { tool: 'bwrap', cwd: os.tmpdir(), home: '/home/tester' });
+  assert.strictEqual(w.file, 'bwrap');
+  assert.deepStrictEqual(w.args.slice(-3), ['/bin/sh', '-c', 'echo hi']);
+  assert.ok(w.args.includes('--proc'));
+});
+
+test('wrapCommand builds a sandbox-exec argv carrying the policy', () => {
+  const w = wrapCommand('echo hi', { tool: 'sandbox-exec', cwd: os.tmpdir(), home: '/home/tester' });
+  assert.strictEqual(w.file, 'sandbox-exec');
+  assert.strictEqual(w.args[0], '-p');
+  assert.match(w.args[1], /\(version 1\)/);
+  assert.deepStrictEqual(w.args.slice(-3), ['/bin/sh', '-c', 'echo hi']);
+});
+
+test('wrapCommand returns null for an unknown tool or empty command', () => {
+  assert.strictEqual(wrapCommand('echo hi', { tool: 'nope' }), null);
+  assert.strictEqual(wrapCommand('', { tool: 'bwrap' }), null);
+});
+
+test('wrapCommand threads the network mode into the bwrap argv', () => {
+  const off = wrapCommand('echo hi', { tool: 'bwrap', cwd: os.tmpdir(), home: '/home/tester', network: 'off' });
+  assert.ok(off.args.includes('--unshare-net'));
+  const on = wrapCommand('echo hi', { tool: 'bwrap', cwd: os.tmpdir(), home: '/home/tester', network: 'on' });
+  assert.ok(!on.args.includes('--unshare-net'));
+});
+
+test('wrapCommand threads the network mode into the sandbox-exec policy', () => {
+  const off = wrapCommand('echo hi', { tool: 'sandbox-exec', cwd: os.tmpdir(), home: '/home/tester', network: 'off' });
+  assert.match(off.args[1], /\(deny network\*\)/);
+  const on = wrapCommand('echo hi', { tool: 'sandbox-exec', cwd: os.tmpdir(), home: '/home/tester', network: 'on' });
+  assert.doesNotMatch(on.args[1], /\(deny network\*\)/);
+});
+
+// ---------------------------------------------------------------------------
+// decideSandbox — config × detection
+// ---------------------------------------------------------------------------
+
+const detAvail = { platform: 'linux', supported: true, tool: 'bwrap', available: true };
+const detUnavail = { platform: 'linux', supported: true, tool: 'bwrap', available: false, reason: 'no bwrap', installHint: 'install it' };
+
+test('decideSandbox: auto + available → on', () => {
+  const d = decideSandbox({ getConfig: () => ({ sandbox: { mode: 'auto' } }), detection: detAvail });
+  assert.strictEqual(d.status, 'on');
+  assert.strictEqual(d.tool, 'bwrap');
+});
+
+test('decideSandbox: mode off → off (deliberate human opt-out, even when available)', () => {
+  const d = decideSandbox({ getConfig: () => ({ sandbox: { mode: 'off' } }), detection: detAvail });
+  assert.strictEqual(d.status, 'off');
+});
+
+test('decideSandbox: auto + unavailable → unavailable, carrying failIfUnavailable + hint', () => {
+  const d = decideSandbox({ getConfig: () => ({ sandbox: { mode: 'auto', failIfUnavailable: true } }), detection: detUnavail });
+  assert.strictEqual(d.status, 'unavailable');
+  assert.strictEqual(d.failIfUnavailable, true);
+  assert.match(d.installHint, /install it/);
+});
+
+test('decideSandbox: a throwing getConfig is contained (defaults to auto)', () => {
+  const d = decideSandbox({ getConfig: () => { throw new Error('boom'); }, detection: detAvail });
+  assert.strictEqual(d.status, 'on');
+});
+
+test('decideSandbox: network defaults on; carries the kernel-enforced network mode on the decision', () => {
+  // noNetwork passed explicitly so the test never depends on the real process argv.
+  const onByDefault = decideSandbox({ getConfig: () => ({ sandbox: { mode: 'auto' } }), detection: detAvail, noNetwork: false });
+  assert.strictEqual(onByDefault.status, 'on');
+  assert.strictEqual(onByDefault.network, 'on');
+
+  const offByConfig = decideSandbox({ getConfig: () => ({ sandbox: { mode: 'auto', network: 'off' } }), detection: detAvail, noNetwork: false });
+  assert.strictEqual(offByConfig.network, 'off');
+
+  const offByFlag = decideSandbox({ getConfig: () => ({ sandbox: { mode: 'auto' } }), detection: detAvail, noNetwork: true });
+  assert.strictEqual(offByFlag.network, 'off', '--no-network forces off even when config says nothing');
+});
+
+test('decideSandbox: ANTI-FAIL-OPEN — a malformed network config yields net off on an on decision', () => {
+  const d = decideSandbox({ getConfig: () => ({ sandbox: { mode: 'auto', network: '' } }), detection: detAvail, noNetwork: false });
+  assert.strictEqual(d.status, 'on');
+  assert.strictEqual(d.network, 'off', 'present-but-malformed network must resolve to the isolated state');
+});
+
+// ---------------------------------------------------------------------------
+// sandboxStatusReport
+// ---------------------------------------------------------------------------
+
+test('sandboxStatusReport reflects an available auto sandbox as effective ON', () => {
+  const r = sandboxStatusReport({ getConfig: () => ({ sandbox: { mode: 'auto' } }), detection: detAvail });
+  assert.match(r, /mode:\s+auto/);
+  assert.match(r, /effective:\s+ON/);
+});
+
+test('sandboxStatusReport shows the hard-block when unavailable + failIfUnavailable', () => {
+  const r = sandboxStatusReport({ getConfig: () => ({ sandbox: { mode: 'auto', failIfUnavailable: true } }), detection: detUnavail });
+  assert.match(r, /HARD-BLOCKED/);
+  assert.match(r, /install it/);
+});
+
+test('sandboxStatusReport shows the approval fallback when unavailable without the hard gate', () => {
+  const r = sandboxStatusReport({ getConfig: () => ({ sandbox: { mode: 'auto' } }), detection: detUnavail });
+  assert.match(r, /require human approval/);
+});
+
+test('sandboxStatusReport shows OFF when mode is off', () => {
+  const r = sandboxStatusReport({ getConfig: () => ({ sandbox: { mode: 'off' } }), detection: detAvail });
+  assert.match(r, /effective:\s+OFF/);
+});
+
+test('sandboxStatusReport surfaces the network mode (net:on by default, net:off when isolated)', () => {
+  const on = sandboxStatusReport({ getConfig: () => ({ sandbox: { mode: 'auto' } }), detection: detAvail, noNetwork: false });
+  assert.match(on, /network:\s+on/);
+  assert.match(on, /effective:\s+ON \(net:on\)/);
+
+  const off = sandboxStatusReport({ getConfig: () => ({ sandbox: { mode: 'auto', network: 'off' } }), detection: detAvail, noNetwork: false });
+  assert.match(off, /network:\s+off/);
+  assert.match(off, /effective:\s+ON \(net:off\)/);
+  // Binary semantics are stated, not a domain allowlist.
+  assert.match(off, /no host proxy, no domain allowlist, no TLS interception/);
+});
+
+test('sandboxStatusReport notes that no-network needs an active sandbox when the sandbox is off', () => {
+  const r = sandboxStatusReport({ getConfig: () => ({ sandbox: { mode: 'off', network: 'off' } }), detection: detAvail, noNetwork: false });
+  assert.match(r, /no-network requires an active sandbox/);
+});

package/test/sdk.test.js

@@ -0,0 +1,234 @@
+'use strict';
+
+// Integration tests for the embedding SDK facade (Task 5.2). They drive the
+// REAL createAgent() against the mock-LLM harness, exercising:
+//   * run() returns the documented { result, toolCalls, usage, cost, stopReason,
+//     verifyStatus } envelope;
+//   * the SAFE EMBEDDED DEFAULT — a mutating tool is refused with no policy —
+//     paired with the positive case (an approver/allow-rule lets it proceed);
+//   * the deny-list stays active in embedded mode (not disabled by absence of a
+//     TTY) and the sandbox opt-out is via explicit config only;
+//   * close() releases resources (a real MCP stdio server is disconnected);
+//   * two instances don't collide on per-instance config state;
+//   * the package `exports` map resolves the facade and the /internals subpath.
+
+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 { createAgent } = require('../lib/sdk');
+const { startMockLLM } = require('./harness/mock-llm');
+
+const MOCK_MCP = path.join(__dirname, 'harness', 'mock-mcp-server.js');
+
+let prevKey;
+let tmpDir;
+let prevCwd;
+
+before(() => {
+  prevKey = process.env.SEMALT_API_KEY;
+  process.env.SEMALT_API_KEY = 'test-key';
+  // Run inside an isolated temp dir so file writes that pass the gate land in a
+  // throwaway CWD (isPathSafe confines writes to process.cwd()).
+  prevCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sdk-test-'));
+  process.chdir(tmpDir);
+});
+
+after(() => {
+  if (prevKey === undefined) delete process.env.SEMALT_API_KEY;
+  else process.env.SEMALT_API_KEY = prevKey;
+  process.chdir(prevCwd);
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+});
+
+function agentFor(mock, extra = {}) {
+  return createAgent({
+    apiBase: mock.base,
+    apiKey: 'test-key',
+    model: 'test-model',
+    // These suites test the FACADE + permission perimeter, not the OS sandbox
+    // (covered by the sandbox suites). Default sandbox off for determinism
+    // across the CI matrix; the dedicated test below proves the default is on.
+    sandbox: { mode: 'off' },
+    ...extra,
+  });
+}
+
+test('run() returns the documented headless-shaped envelope', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('The answer is 42.');
+  const agent = agentFor(mock);
+  try {
+    const res = await agent.run('what is the answer');
+    assert.strictEqual(typeof res.result, 'string');
+    assert.match(res.result, /42/);
+    assert.ok(Array.isArray(res.toolCalls), 'toolCalls is an array');
+    assert.ok(res.usage && typeof res.usage.total_tokens === 'number', 'usage present');
+    assert.ok('cost' in res, 'cost key present (may be null)');
+    assert.strictEqual(res.stopReason, 'end_turn');
+    assert.strictEqual(res.verifyStatus, 'skipped');
+    assert.ok(Array.isArray(res.messages), 'messages returned for continuation');
+  } finally {
+    await agent.close();
+    await mock.close();
+  }
+});
+
+test('SAFE DEFAULT: a mutating tool is refused with no policy', async () => {
+  const mock = await startMockLLM();
+  // The model asks to write a file. With no policy the gate refuses, which
+  // aborts the turn (no further LLM request needed).
+  mock.replyWith('<write_file path="should-not-exist.txt">secret</write_file>');
+  const agent = agentFor(mock); // NO approve, NO rules → refuse mutations
+  try {
+    const res = await agent.run('please write the file');
+    assert.strictEqual(
+      fs.existsSync(path.join(tmpDir, 'should-not-exist.txt')),
+      false,
+      'mutating write must NOT happen without an explicit policy',
+    );
+    assert.match(JSON.stringify(res.messages), /Permission denied/i, 'denial surfaced to the host');
+  } finally {
+    await agent.close();
+    await mock.close();
+  }
+});
+
+test('PAIRED POSITIVE: an approver lets the same mutating tool proceed', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<write_file path="allowed.txt">hello sdk</write_file>');
+  mock.replyWith('Done writing.');
+  const calls = [];
+  const agent = agentFor(mock, {
+    approve: (call) => { calls.push(call); return true; },
+  });
+  try {
+    const res = await agent.run('write the file');
+    const target = path.join(tmpDir, 'allowed.txt');
+    assert.strictEqual(fs.existsSync(target), true, 'approved write happened');
+    assert.strictEqual(fs.readFileSync(target, 'utf8'), 'hello sdk');
+    assert.ok(calls.length >= 1, 'approver was consulted');
+    assert.ok(calls[0] && typeof calls[0].description === 'string', 'approver gets a call descriptor');
+    // The successful tool shows up in the structured envelope (canonical action
+    // for <write_file> is 'write').
+    assert.ok(res.toolCalls.some((t) => t.tool === 'write' && t.ok), 'write recorded as ok');
+  } finally {
+    await agent.close();
+    await mock.close();
+  }
+});
+
+test('PAIRED POSITIVE: an allow rule lets a mutating tool proceed (no approver)', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<write_file path="by-rule.txt">rule data</write_file>');
+  mock.replyWith('Done.');
+  const agent = agentFor(mock, {
+    rules: [{ tool: 'write_file', path: '**', action: 'allow' }],
+  });
+  try {
+    await agent.run('write it');
+    assert.strictEqual(fs.existsSync(path.join(tmpDir, 'by-rule.txt')), true, 'allow rule permitted the write');
+  } finally {
+    await agent.close();
+    await mock.close();
+  }
+});
+
+test('deny-list stays active in embedded mode even with an approver', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>rm -rf /</exec>');
+  mock.replyWith('Stopped.');
+  const toolEvents = [];
+  const agent = agentFor(mock, { approve: () => true }); // approve the gate…
+  agent.on('tool', (e) => toolEvents.push(e));
+  try {
+    await agent.run('wipe everything');
+    // …but the destructive-command deny-list (which the approver cannot bypass)
+    // must still hard-block it.
+    const blocked = toolEvents.some((e) => /deny-list/i.test(String(e.result || '')));
+    assert.ok(blocked, 'rm -rf / blocked by the deny-list despite gate approval');
+  } finally {
+    await agent.close();
+    await mock.close();
+  }
+});
+
+test('sandbox defaults ON (auto); opt-out is explicit config only', async () => {
+  const mock = await startMockLLM();
+  const onByDefault = createAgent({ apiBase: mock.base, apiKey: 'k', model: 'm' });
+  const offByOptIn = createAgent({ apiBase: mock.base, apiKey: 'k', model: 'm', sandbox: { mode: 'off' } });
+  try {
+    assert.strictEqual(onByDefault.getConfig().sandbox.mode, 'auto', 'sandbox on by default in embedded mode');
+    assert.strictEqual(offByOptIn.getConfig().sandbox.mode, 'off', 'explicit opt-out honored');
+  } finally {
+    await onByDefault.close();
+    await offByOptIn.close();
+    await mock.close();
+  }
+});
+
+test('two instances keep independent config (no global-state collision)', async () => {
+  const mock = await startMockLLM();
+  const a = createAgent({ apiBase: mock.base, apiKey: 'k', model: 'model-a' });
+  const b = createAgent({ apiBase: mock.base, apiKey: 'k', model: 'model-b' });
+  try {
+    assert.strictEqual(a.getConfig().default_model, 'model-a');
+    assert.strictEqual(b.getConfig().default_model, 'model-b');
+    assert.notStrictEqual(a.getConfig(), b.getConfig(), 'configs are distinct objects');
+  } finally {
+    await a.close();
+    await b.close();
+    await mock.close();
+  }
+});
+
+test('close() releases resources: a real MCP server is disconnected', async () => {
+  const { toolRegistry } = require('../lib/internals');
+  const mock = await startMockLLM();
+  mock.replyWith('Hi.'); // one reply for the run() that triggers MCP connect
+  const agent = createAgent({
+    apiBase: mock.base,
+    apiKey: 'k',
+    model: 'm',
+    sandbox: { mode: 'off' },
+    config: {
+      mcp: { servers: { sdkfs: { transport: 'stdio', command: process.execPath, args: [MOCK_MCP], allowAll: true } } },
+    },
+  });
+  try {
+    await agent.run('hello'); // lazily connects MCP + registers its tools
+    const namesConnected = toolRegistry.dynamicToolEntries().map((e) => e.tool);
+    assert.ok(namesConnected.some((n) => n.startsWith('mcp__sdkfs__')), 'MCP tools registered after run()');
+    await agent.close();
+    const namesAfter = toolRegistry.dynamicToolEntries().map((e) => e.tool);
+    assert.ok(!namesAfter.some((n) => n.startsWith('mcp__sdkfs__')), 'MCP tools unregistered after close()');
+  } finally {
+    if (!agent.closed) await agent.close();
+    await mock.close();
+  }
+});
+
+test('run() after close() throws', async () => {
+  const mock = await startMockLLM();
+  const agent = agentFor(mock);
+  await agent.close();
+  await assert.rejects(() => agent.run('anything'), /close/i);
+  await mock.close();
+});
+
+test('exports map resolves the facade and the /internals subpath', () => {
+  const facade = require('@semalt-ai/code');
+  assert.strictEqual(typeof facade.createAgent, 'function', 'main entry exposes createAgent');
+
+  const internals = require('@semalt-ai/code/internals');
+  assert.strictEqual(internals.__unstable__, true, 'internals carries the instability marker');
+  assert.strictEqual(typeof internals.createAgentRunner, 'function');
+  assert.strictEqual(typeof internals.createApiClient, 'function');
+
+  const pkg = require('../package.json');
+  assert.strictEqual(pkg.exports['.'], './lib/sdk.js', 'main subpath → facade');
+  assert.strictEqual(pkg.exports['./internals'], './lib/internals.js', 'internals subpath → building blocks');
+});