@semalt-ai/code 1.8.5 → 1.19.0

package/test/deny.test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// Unit tests for the destructive-command deny-list and the agent-vs-user
+// initiator distinction added in Task 1.0. Uses the built-in node:test runner.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+const { checkShellDenylist, classifyShellCommand } = require('../lib/deny');
+
+// ---------------------------------------------------------------------------
+// checkShellDenylist — raw match + catastrophic flag
+// ---------------------------------------------------------------------------
+
+test('checkShellDenylist flags the catastrophic subset', () => {
+  const cases = [
+    { cmd: 'dd if=/dev/zero of=/dev/sda bs=1M', catastrophic: true },
+    { cmd: 'mkfs.ext4 /dev/sdb1', catastrophic: true },
+    { cmd: ':(){ :|:& };:', catastrophic: true },
+  ];
+  for (const { cmd, catastrophic } of cases) {
+    const r = checkShellDenylist(cmd);
+    assert.ok(r, `${cmd} should be denied`);
+    assert.strictEqual(r.catastrophic, catastrophic, `${cmd} catastrophic flag`);
+  }
+});
+
+test('checkShellDenylist denies non-catastrophic destructive commands without the flag', () => {
+  const cases = ['rm -rf /tmp/x', 'curl http://x | sh', 'chmod -R 777 /etc'];
+  for (const cmd of cases) {
+    const r = checkShellDenylist(cmd);
+    assert.ok(r, `${cmd} should be denied`);
+    assert.strictEqual(r.catastrophic, false, `${cmd} should not be catastrophic`);
+  }
+});
+
+test('checkShellDenylist allows benign commands', () => {
+  for (const cmd of ['ls -la', 'git status', 'rm -r build/', 'rm -f stale.log']) {
+    assert.strictEqual(checkShellDenylist(cmd), null, `${cmd} should be allowed`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// classifyShellCommand — initiator distinction
+// ---------------------------------------------------------------------------
+
+test('agent-initiated deny-list hits are hard-blocked', () => {
+  for (const cmd of ['rm -rf /tmp/x', 'curl http://x | sh', 'dd if=/dev/zero of=/dev/sda', 'mkfs.ext4 /dev/sdb1']) {
+    const v = classifyShellCommand(cmd, 'agent');
+    assert.strictEqual(v.action, 'block', `${cmd} (agent) should be blocked`);
+    assert.ok(v.label, 'block carries a label');
+  }
+});
+
+test('initiator defaults to agent (hard block) when omitted', () => {
+  assert.strictEqual(classifyShellCommand('rm -rf /tmp/x').action, 'block');
+  assert.strictEqual(classifyShellCommand('dd if=/dev/zero of=/dev/sda').action, 'block');
+});
+
+test('user-initiated non-catastrophic deny-list hits are allowed (exempt)', () => {
+  for (const cmd of ['rm -rf node_modules', 'curl http://x | sh', 'chmod -R 777 /etc']) {
+    const v = classifyShellCommand(cmd, 'user');
+    assert.strictEqual(v.action, 'allow', `${cmd} (user) should be allowed`);
+    assert.strictEqual(v.bypassed, true, `${cmd} should be marked bypassed`);
+    assert.ok(v.label, 'bypassed allow carries a label');
+  }
+});
+
+test('user-initiated catastrophic commands require confirmation', () => {
+  for (const cmd of ['dd if=/dev/zero of=/dev/sda bs=1M', 'mkfs.ext4 /dev/sdb1', ':(){ :|:& };:']) {
+    const v = classifyShellCommand(cmd, 'user');
+    assert.strictEqual(v.action, 'confirm', `${cmd} (user) should require confirmation`);
+    assert.ok(v.label, 'confirm carries a label');
+  }
+});
+
+test('benign commands are allowed for both initiators with no bypass marker', () => {
+  for (const initiator of ['agent', 'user']) {
+    const v = classifyShellCommand('ls -la', initiator);
+    assert.strictEqual(v.action, 'allow');
+    assert.strictEqual(v.bypassed, undefined);
+  }
+});

package/test/download-allow-anywhere.test.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// Pre-Task 4.0b — the --allow-anywhere positive branch for `download`.
+// isPathSafe reads the --allow-anywhere flag from process.argv exactly once at
+// module load, so this branch must run in its own process with the flag set
+// before lib/tools is required. `node --test` runs each test file in a separate
+// process, giving us that isolation.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+if (!process.argv.includes('--allow-anywhere')) process.argv.push('--allow-anywhere');
+
+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');
+
+let CWD;
+let PREV_CWD;
+let OUTSIDE_DIR;
+
+function mkExec() {
+  const pm = createPermissionManager(ui, {});
+  return createToolExecutor(pm, ui, () => ({
+    max_file_size_kb: 512,
+    command_timeout_ms: 30000,
+    download_max_bytes: 1048576,
+  }));
+}
+
+async function withServer(body, fn) {
+  const server = http.createServer((req, res) => { res.writeHead(200); res.end(body); });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const { port } = server.address();
+  try {
+    return await fn(port);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+}
+
+before(() => {
+  PREV_CWD = process.cwd();
+  CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-dl-aa-cwd-'));
+  OUTSIDE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-dl-aa-out-'));
+  process.chdir(CWD);
+});
+
+after(() => {
+  process.chdir(PREV_CWD);
+});
+
+test('download to a destination outside CWD is allowed under --allow-anywhere', async () => {
+  const exec = mkExec();
+  const outside = path.join(OUTSIDE_DIR, 'fetched.txt');
+  await withServer('outside-ok', async (port) => {
+    const r = await exec.agentExecFile('download', `http://127.0.0.1:${port}/x`, outside);
+    assert.strictEqual(r.status, 'ok');
+    assert.strictEqual(fs.readFileSync(outside, 'utf8'), 'outside-ok');
+  });
+});

package/test/download-confine.test.js

@@ -0,0 +1,153 @@
+'use strict';
+
+// Pre-Task 4.0b — confine the `download` tool.
+// download was the one write path not routed through isPathSafe, with no byte
+// cap and no --readonly check. These tests pin the new confinement: path
+// refusal, secret-file guard, --readonly block, a byte cap that aborts and
+// cleans up the partial file, and an in-bounds happy path that still works.
+//
+// Home-based paths (config.json / memory.json / audit.log) are redirected into
+// a temp dir BEFORE any lib module loads, so the secret-file guard resolves
+// against the temp config path. The process argv here has neither
+// --allow-anywhere nor --readonly, so isPathSafe defaults to "confined to CWD"
+// (the allow-anywhere positive branch lives in download-allow-anywhere.test.js,
+// which needs the flag set at module load and so runs in its own process).
+
+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-dl-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 { CONFIG_PATH } = require('../lib/constants');
+
+let CWD;
+let PREV_CWD;
+
+// Build a tool executor with an injectable config + permission-manager options.
+function mkExec({ config = {}, pmOpts = {} } = {}) {
+  const pm = createPermissionManager(ui, pmOpts);
+  return createToolExecutor(pm, ui, () => ({
+    max_file_size_kb: 512,
+    command_timeout_ms: 30000,
+    download_max_bytes: 1048576,
+    ...config,
+  }));
+}
+
+// Spin up a localhost server that returns the given body, run fn(port), close.
+async function withServer(body, fn) {
+  const server = http.createServer((req, res) => { res.writeHead(200); res.end(body); });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const { port } = server.address();
+  try {
+    return await fn(port);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+}
+
+before(() => {
+  PREV_CWD = process.cwd();
+  CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-dl-cwd-'));
+  process.chdir(CWD);
+});
+
+after(() => {
+  process.chdir(PREV_CWD);
+  if (PREV_HOME === undefined) delete process.env.HOME; else process.env.HOME = PREV_HOME;
+  if (PREV_USERPROFILE === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = PREV_USERPROFILE;
+});
+
+// ---------------------------------------------------------------------------
+// happy path — an in-bounds download still works
+// ---------------------------------------------------------------------------
+
+test('download saves an in-bounds URL to a file in cwd', async () => {
+  const exec = mkExec();
+  await withServer('filedata', async (port) => {
+    const r = await exec.agentExecFile('download', `http://127.0.0.1:${port}/payload.txt`);
+    assert.strictEqual(r.status, 'ok');
+    assert.strictEqual(fs.readFileSync(path.join(CWD, 'payload.txt'), 'utf8'), 'filedata');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// byte cap — oversized download is aborted and the partial file removed
+// ---------------------------------------------------------------------------
+
+test('download aborts past the byte cap and removes the partial file', async () => {
+  const exec = mkExec({ config: { download_max_bytes: 16 } });
+  const big = 'a'.repeat(5000);
+  await withServer(big, async (port) => {
+    const r = await exec.agentExecFile('download', `http://127.0.0.1:${port}/big.bin`);
+    assert.ok(r.error, 'should return an error');
+    assert.match(r.error, /cap/i);
+    assert.strictEqual(r.capped, true);
+    assert.strictEqual(fs.existsSync(path.join(CWD, 'big.bin')), false, 'partial file must be cleaned up');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// path confinement — a destination outside CWD is refused
+// ---------------------------------------------------------------------------
+
+test('download to a destination outside CWD is refused', async () => {
+  const exec = mkExec();
+  const outside = path.join(os.tmpdir(), 'semalt-dl-outside-' + process.pid + '.txt');
+  await withServer('data', async (port) => {
+    const r = await exec.agentExecFile('download', `http://127.0.0.1:${port}/x`, outside);
+    assert.ok(r.error, 'should be refused');
+    assert.match(r.error, /outside allowed area/i);
+    assert.strictEqual(fs.existsSync(outside), false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// secret-file guard — refuses writing over a protected secret path
+// ---------------------------------------------------------------------------
+
+test('download over a protected secret path is refused by the secret guard', async () => {
+  const exec = mkExec();
+  await withServer('data', async (port) => {
+    const r = await exec.agentExecFile('download', `http://127.0.0.1:${port}/x`, CONFIG_PATH);
+    assert.ok(r.error, 'should be refused');
+    assert.match(r.error, /secret|credential/i);
+    assert.strictEqual(fs.existsSync(CONFIG_PATH), false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// --readonly — blocks the mutating download
+// ---------------------------------------------------------------------------
+
+test('download is blocked under --readonly', async () => {
+  const exec = mkExec({ pmOpts: { readonly: true } });
+  await withServer('data', async (port) => {
+    const r = await exec.agentExecFile('download', `http://127.0.0.1:${port}/ro.txt`);
+    assert.ok(r.error, 'should be blocked');
+    assert.match(r.error, /readonly/i);
+    assert.strictEqual(fs.existsSync(path.join(CWD, 'ro.txt')), false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// describePermission short-circuits download under --readonly (parity with
+// delete/move/copy) so no approval prompt precedes the deterministic block.
+// ---------------------------------------------------------------------------
+
+test('describePermission returns null for download under --readonly', async () => {
+  const exec = mkExec({ pmOpts: { readonly: true } });
+  assert.strictEqual(await exec.describePermission(['download', 'http://x/y.zip']), null);
+});

package/test/executors.test.js

@@ -0,0 +1,362 @@
+'use strict';
+
+// Characterization tests for the agentExecFile branch executors (Task 1.4b).
+// Written BEFORE the executors are moved into the tool registry, and must stay
+// green after the move. fs mutations are real but isolated: a temp $HOME (so
+// config.json / memory.json / audit.log resolve under it) and a temp working
+// directory (so isPathSafe permits writes). Captures current behavior exactly,
+// including quirks — reported, not fixed.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Redirect home-based paths (memory store, audit log, config) into a temp dir
+// BEFORE any lib module is required — those paths are computed at module load.
+const TMP_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-home-'));
+const PREV_HOME = process.env.HOME;
+const PREV_USERPROFILE = process.env.USERPROFILE;
+process.env.HOME = TMP_HOME;
+process.env.USERPROFILE = TMP_HOME;
+
+const { test, before, after, beforeEach } = 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');
+
+let exec;          // { agentExecFile, agentExecShell, describePermission }
+let CWD;           // temp working directory (also process.cwd during the suite)
+let PREV_CWD;
+
+before(() => {
+  PREV_CWD = process.cwd();
+  CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-cwd-'));
+  process.chdir(CWD);
+  const pm = createPermissionManager(ui, {});
+  exec = createToolExecutor(pm, ui, () => ({ max_file_size_kb: 512, command_timeout_ms: 30000 }));
+});
+
+after(() => {
+  process.chdir(PREV_CWD);
+  if (PREV_HOME === undefined) delete process.env.HOME; else process.env.HOME = PREV_HOME;
+  if (PREV_USERPROFILE === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = PREV_USERPROFILE;
+});
+
+const ef = (...a) => exec.agentExecFile(...a);
+const read = (p) => fs.readFileSync(path.join(CWD, p), 'utf8');
+
+// ---------------------------------------------------------------------------
+// write / append / read
+// ---------------------------------------------------------------------------
+
+test('write creates a file (and parent dirs) and returns byte count', async () => {
+  const r = await ef('write', 'sub/dir/a.txt', 'hello');
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(r.path, 'sub/dir/a.txt');
+  assert.strictEqual(r.bytes, 5);
+  assert.strictEqual(read('sub/dir/a.txt'), 'hello');
+});
+
+test('write overwrites existing content', async () => {
+  await ef('write', 'ow.txt', 'first');
+  await ef('write', 'ow.txt', 'second');
+  assert.strictEqual(read('ow.txt'), 'second');
+});
+
+test('QUIRK: write/append byte count is the NEW content length, not total file size', async () => {
+  await ef('write', 'ap.txt', 'AAAA');
+  const r = await ef('append', 'ap.txt', 'BB');
+  assert.strictEqual(read('ap.txt'), 'AAAABB');
+  assert.strictEqual(r.bytes, 2, 'bytes reflects only the appended chunk');
+});
+
+test('write outside the working tree is sandbox-blocked', async () => {
+  const r = await ef('write', '/etc/should-not-write.txt', 'x');
+  assert.ok(r.error && /outside allowed area/i.test(r.error));
+});
+
+test('read returns content + byte length', async () => {
+  await ef('write', 'r.txt', 'abcdef');
+  const r = await ef('read', 'r.txt');
+  assert.strictEqual(r.content, 'abcdef');
+  assert.strictEqual(r.bytes, 6);
+  assert.strictEqual(r.path, 'r.txt');
+});
+
+test('read refuses a protected secret path (config.json)', async () => {
+  const cfgPath = path.join(os.homedir(), '.semalt-ai', 'config.json');
+  const r = await ef('read', cfgPath);
+  assert.ok(r.error && /secrets|credentials/i.test(r.error));
+});
+
+test('read rejects a file over max_file_size_kb', async () => {
+  const pm = createPermissionManager(ui, {});
+  const tinyExec = createToolExecutor(pm, ui, () => ({ max_file_size_kb: 1 }));
+  await ef('write', 'big.txt', 'x'.repeat(2000)); // ~2 KB > 1 KB limit
+  const r = await tinyExec.agentExecFile('read', path.join(CWD, 'big.txt'));
+  assert.ok(r.error && /too large/i.test(r.error));
+});
+
+test('QUIRK: max_file_size_kb of 0 falls back to the byte backstop default (Task W.7)', async () => {
+  // The byte cap is now a BACKSTOP (DEFAULT_READ_MAX_FILE_KB = 50 MB), not the
+  // primary bound — pagination is. A falsy limit falls back to that default, so a
+  // 2 KB file reads fine (it would also paginate via formatReadResult if large).
+  const pm = createPermissionManager(ui, {});
+  const zeroExec = createToolExecutor(pm, ui, () => ({ max_file_size_kb: 0 }));
+  await ef('write', 'small.txt', 'x'.repeat(2000));
+  const r = await zeroExec.agentExecFile('read', path.join(CWD, 'small.txt'));
+  assert.strictEqual(r.error, undefined, 'a falsy limit is treated as the backstop default, not 0');
+  assert.strictEqual(r.content.length, 2000);
+});
+
+test('read of a missing file returns an error', async () => {
+  const r = await ef('read', 'nope.txt');
+  assert.ok(r.error);
+});
+
+// ---------------------------------------------------------------------------
+// delete / make_dir / remove_dir
+// ---------------------------------------------------------------------------
+
+test('delete_file removes a file', async () => {
+  await ef('write', 'del.txt', 'x');
+  const r = await ef('delete_file', 'del.txt');
+  assert.strictEqual(r.status, 'ok');
+  assert.ok(!fs.existsSync(path.join(CWD, 'del.txt')));
+});
+
+test('delete_file outside the tree is blocked', async () => {
+  const r = await ef('delete_file', '/etc/hosts');
+  assert.ok(r.error && /outside allowed area/i.test(r.error));
+});
+
+test('make_dir then remove_dir (recursive)', async () => {
+  const mk = await ef('make_dir', 'd1/d2');
+  assert.strictEqual(mk.status, 'ok');
+  assert.ok(fs.existsSync(path.join(CWD, 'd1/d2')));
+  await ef('write', 'd1/d2/f.txt', 'y');
+  const rm = await ef('remove_dir', 'd1');
+  assert.strictEqual(rm.status, 'ok');
+  assert.ok(!fs.existsSync(path.join(CWD, 'd1')));
+});
+
+// ---------------------------------------------------------------------------
+// move / copy
+// ---------------------------------------------------------------------------
+
+test('move_file relocates a file', async () => {
+  await ef('write', 'm-src.txt', 'data');
+  const r = await ef('move_file', 'm-src.txt', 'moved/m-dst.txt');
+  assert.strictEqual(r.status, 'ok');
+  assert.ok(!fs.existsSync(path.join(CWD, 'm-src.txt')));
+  assert.strictEqual(read('moved/m-dst.txt'), 'data');
+});
+
+test('copy_file duplicates a file', async () => {
+  await ef('write', 'c-src.txt', 'data');
+  const r = await ef('copy_file', 'c-src.txt', 'c-dst.txt');
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(read('c-src.txt'), 'data');
+  assert.strictEqual(read('c-dst.txt'), 'data');
+});
+
+test('copy_file to a path outside the tree is blocked', async () => {
+  await ef('write', 'cc.txt', 'data');
+  const r = await ef('copy_file', 'cc.txt', '/etc/x');
+  assert.ok(r.error && /outside allowed area/i.test(r.error));
+});
+
+// ---------------------------------------------------------------------------
+// edit / search_in_file / replace_in_file / search_files / file_stat
+// ---------------------------------------------------------------------------
+
+test('edit_file replaces a 1-based line', async () => {
+  await ef('write', 'e.txt', 'l1\nl2\nl3');
+  const r = await ef('edit_file', 'e.txt', 2, 'REPLACED');
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(read('e.txt'), 'l1\nREPLACED\nl3');
+});
+
+test('edit_file out-of-range line returns an error', async () => {
+  await ef('write', 'e2.txt', 'only one line');
+  const r = await ef('edit_file', 'e2.txt', 99, 'x');
+  assert.ok(r.error && /out of range/i.test(r.error));
+});
+
+test('search_in_file returns matching lines with 1-based numbers', async () => {
+  await ef('write', 's.txt', 'alpha\nbeta\ngamma beta');
+  const r = await ef('search_in_file', 's.txt', 'beta');
+  assert.deepStrictEqual(r.matches, [
+    { line: 2, content: 'beta' },
+    { line: 3, content: 'gamma beta' },
+  ]);
+});
+
+test('search_in_file refuses a protected secret path', async () => {
+  const r = await ef('search_in_file', path.join(os.homedir(), '.semalt-ai', 'config.json'), 'x');
+  assert.ok(r.error && /secrets|credentials/i.test(r.error));
+});
+
+test('replace_in_file with explicit "g" flag replaces all and reports the count', async () => {
+  await ef('write', 'repg.txt', 'a a a');
+  const r = await ef('replace_in_file', 'repg.txt', 'a', 'b', 'g');
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(r.count, 3);
+  assert.strictEqual(read('repg.txt'), 'b b b');
+});
+
+test('replace_in_file without "g" flag replaces only the first match and reports count 1', async () => {
+  // Fixed in Task 1.4c (was a count bug pinned in 1.4b): the replacement
+  // semantics are unchanged — without "g", only the first occurrence is replaced
+  // — but the returned count now reflects the replacements ACTUALLY performed
+  // (1) instead of the always-global match total (3).
+  await ef('write', 'rep.txt', 'a a a');
+  const r = await ef('replace_in_file', 'rep.txt', 'a', 'b', '');
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(read('rep.txt'), 'b a a', 'only the first occurrence is replaced (semantics unchanged)');
+  assert.strictEqual(r.count, 1, 'count equals the actual number of replacements');
+});
+
+test('replace_in_file reports count 0 when there is no match (no file change)', async () => {
+  await ef('write', 'rep0.txt', 'xyz');
+  const r = await ef('replace_in_file', 'rep0.txt', 'q', 'b', '');
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(r.count, 0);
+  assert.strictEqual(read('rep0.txt'), 'xyz');
+});
+
+test('search_files finds files by glob', async () => {
+  await ef('write', 'find/x.ts', '1');
+  await ef('write', 'find/y.js', '2');
+  await ef('write', 'find/z.ts', '3');
+  const r = await ef('search_files', '*.ts', 'find');
+  assert.deepStrictEqual(r.files.sort(), ['x.ts', 'z.ts']);
+});
+
+test('file_stat returns size/type/mode/mtime', async () => {
+  await ef('write', 'st.txt', 'hello');
+  const r = await ef('file_stat', path.join(CWD, 'st.txt'));
+  assert.strictEqual(r.type, 'file');
+  assert.match(r.mode, /^0o\d+$/);
+  assert.ok(typeof r.size_kb === 'string');
+  assert.ok(!Number.isNaN(Date.parse(r.mtime)));
+});
+
+// ---------------------------------------------------------------------------
+// env / upload
+// ---------------------------------------------------------------------------
+
+test('set_env then get_env round-trips through process.env', async () => {
+  const set = await ef('set_env', 'SEMALT_TEST_VAR', 'hi');
+  assert.strictEqual(set.status, 'ok');
+  const got = await ef('get_env', 'SEMALT_TEST_VAR');
+  assert.strictEqual(got.value, 'hi');
+  delete process.env.SEMALT_TEST_VAR;
+});
+
+test('get_env returns null for an unset variable', async () => {
+  const r = await ef('get_env', 'DEFINITELY_NOT_SET_SEMALT_XYZ');
+  assert.strictEqual(r.value, null);
+});
+
+test('upload decodes base64 to a file and reports byte length', async () => {
+  const b64 = Buffer.from('binary-ish').toString('base64');
+  const r = await ef('upload', 'up.bin', b64);
+  assert.strictEqual(r.status, 'ok');
+  assert.strictEqual(r.bytes, 'binary-ish'.length);
+  assert.strictEqual(read('up.bin'), 'binary-ish');
+});
+
+// ---------------------------------------------------------------------------
+// memory store (isolated under the temp $HOME)
+// ---------------------------------------------------------------------------
+
+test('store_memory / recall_memory / list_memories round-trip', async () => {
+  const s = await ef('store_memory', 'lang', 'TypeScript');
+  assert.strictEqual(s.status, 'ok');
+  const rc = await ef('recall_memory', 'lang');
+  assert.deepStrictEqual(rc, { key: 'lang', value: 'TypeScript', found: true });
+  const miss = await ef('recall_memory', 'nope');
+  assert.deepStrictEqual(miss, { key: 'nope', value: null, found: false });
+  const list = await ef('list_memories');
+  assert.ok(list.keys.includes('lang'));
+});
+
+// ---------------------------------------------------------------------------
+// system_info / ask_user / unknown action
+// ---------------------------------------------------------------------------
+
+test('system_info returns host metadata', async () => {
+  const r = await ef('system_info');
+  assert.strictEqual(typeof r.platform, 'string');
+  assert.strictEqual(typeof r.node_version, 'string');
+  assert.strictEqual(r.cwd, process.cwd());
+});
+
+test('ask_user auto-answers "y" in non-TTY mode', async () => {
+  const r = await ef('ask_user', 'Proceed?');
+  assert.deepStrictEqual(r, { question: 'Proceed?', answer: 'y' });
+});
+
+test('unknown action returns an error', async () => {
+  const r = await ef('frobnicate', 'x');
+  assert.ok(r.error && /unknown action/i.test(r.error));
+});
+
+// ---------------------------------------------------------------------------
+// network executors against a localhost server (isolated, no external calls)
+// ---------------------------------------------------------------------------
+
+test('http_get fetches a body and status code from a local server', async () => {
+  const server = http.createServer((req, res) => { res.writeHead(200); res.end('pong'); });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const { port } = server.address();
+  try {
+    const r = await ef('http_get', `http://127.0.0.1:${port}/`);
+    assert.strictEqual(r.status_code, 200);
+    assert.strictEqual(r.body, 'pong');
+    assert.strictEqual(r.bytes, 4);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+});
+
+test('download saves a URL to a file in cwd', async () => {
+  const server = http.createServer((req, res) => { res.writeHead(200); res.end('filedata'); });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const { port } = server.address();
+  try {
+    const r = await ef('download', `http://127.0.0.1:${port}/payload.txt`);
+    assert.strictEqual(r.status, 'ok');
+    assert.strictEqual(read('payload.txt'), 'filedata');
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+});
+
+// ---------------------------------------------------------------------------
+// describePermission — representative descriptors (moves alongside executors)
+// ---------------------------------------------------------------------------
+
+test('describePermission returns null for read-only ops, descriptors for gated ops', async () => {
+  assert.strictEqual(await exec.describePermission(['read', 'a.txt']), null);
+  assert.strictEqual(await exec.describePermission(['list_dir', '.']), null);
+  assert.deepStrictEqual(await exec.describePermission(['delete_file', 'x']), {
+    actionType: 'file', description: 'Delete x', tag: 'delete_file',
+  });
+  assert.deepStrictEqual(await exec.describePermission(['make_dir', 'd']), {
+    actionType: 'file', description: 'Create directory d', tag: 'make_dir',
+  });
+  const shellDesc = await exec.describePermission(['shell', 'ls']);
+  assert.deepStrictEqual(shellDesc, { actionType: 'shell', description: 'ls', tag: 'exec' });
+});
+
+test('describePermission for write includes a char count and write_file tag', async () => {
+  const d = await exec.describePermission(['write', 'w.txt', 'abc']);
+  assert.strictEqual(d.tag, 'write_file');
+  assert.strictEqual(d.actionType, 'file');
+  assert.match(d.description, /Write w\.txt \(3 chars\)/);
+});