aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/runtimeToggles.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/runtimeToggles.ts — v4.5 Phase 8a.
+ *
+ * Single source of truth for the v4.2/v4.3/v4.4 subsystem
+ * default-on toggles (TCE, browser depth, sandbox). Replaces the
+ * direct `process.env.AIDEN_*` reads scattered across:
+ *
+ *   - core/v4/sandboxConfig.ts        (AIDEN_SANDBOX)
+ *   - core/v4/turnState.ts            (AIDEN_TCE)
+ *   - core/v4/browserState.ts         (AIDEN_BROWSER_DEPTH)
+ *
+ * with a centralised resolver that supports:
+ *
+ *   - **Live flip** via slash commands (/sandbox on|off, /tce on|off,
+ *     /browser-depth on|off). The slash command updates the in-process
+ *     state + persists to config.yaml, and fires onChange callbacks so
+ *     cached consumers (sandboxConfig's singleton) invalidate.
+ *
+ *   - **Persistence** across restarts via
+ *     `<AIDEN_HOME>/config.yaml :: runtime_toggles.{sandbox,tce,browser_depth}`.
+ *
+ *   - **Env-var precedence** (Q-P8a-1a): explicit env var > config.yaml >
+ *     default (true for all three). Matches the existing AIDEN_*
+ *     escape-hatch contract.
+ *
+ * The singleton is initialised by the CLI at boot via `initRuntimeToggles`
+ * with a ConfigProvider seam. Core modules that read the toggles call
+ * `getRuntimeToggles().isEnabled(key)` — when the singleton hasn't been
+ * initialised (test bench, core-only invocation), an env-only fallback
+ * resolver is used so the modules keep working with their pre-v4.5
+ * semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._TOGGLE_KEYS = void 0;
+exports.buildRuntimeToggles = buildRuntimeToggles;
+exports.getRuntimeToggles = getRuntimeToggles;
+exports.initRuntimeToggles = initRuntimeToggles;
+exports._resetRuntimeTogglesForTests = _resetRuntimeTogglesForTests;
+// ── Env var mapping ────────────────────────────────────────────────────────
+const ENV_VAR = {
+    sandbox: 'AIDEN_SANDBOX',
+    tce: 'AIDEN_TCE',
+    browser_depth: 'AIDEN_BROWSER_DEPTH',
+    // v4.5 Phase 8b — contextual capability suggestions. Rarely set as
+    // env (this is mostly a UX toggle) but included for symmetry with
+    // the other subsystem toggles.
+    suggestions: 'AIDEN_SUGGESTIONS',
+    // v4.6 Phase 2M — keyword-based per-turn tool narrowing.
+    // Default OFF: smart models (GPT-5.5, Claude Sonnet 4.5+, Opus)
+    // pick tools fine from a full catalog. PlannerGuard adds latency
+    // (1 LLM call when mode=llm_classified) and occasionally strips
+    // tools the model genuinely needed. Opt in for small local models
+    // that get overwhelmed by 50+ tool schemas.
+    planner_guard: 'AIDEN_PLANNER_GUARD',
+};
+const CONFIG_KEY = {
+    sandbox: 'runtime_toggles.sandbox',
+    tce: 'runtime_toggles.tce',
+    browser_depth: 'runtime_toggles.browser_depth',
+    suggestions: 'runtime_toggles.suggestions',
+    planner_guard: 'runtime_toggles.planner_guard',
+};
+const ALL_KEYS = [
+    'sandbox', 'tce', 'browser_depth', 'suggestions', 'planner_guard',
+];
+/**
+ * v4.6 Phase 2M — per-key default. Pre-2M every toggle defaulted to
+ * `true` (sandbox/tce/browser-depth/suggestions all ship on); the
+ * `planner_guard` toggle is the first to default `false`, so the
+ * resolver needs a per-key default map rather than a hardcoded `true`.
+ *
+ * Smart models (GPT-5.5, Claude Sonnet 4.5+, Opus) pick from the
+ * full tool catalog without help — keyword-based narrowing is a
+ * legacy workaround for smaller local models, opt in when needed.
+ */
+const DEFAULT_VALUE = {
+    sandbox: true,
+    tce: true,
+    browser_depth: true,
+    suggestions: true,
+    planner_guard: false,
+};
+// ── Resolver primitives ────────────────────────────────────────────────────
+/**
+ * Strict env interpretation matching existing v4.2/v4.3/v4.4
+ * semantics: literal `'0'` (or `'false'` for forgiveness) means off;
+ * unset means defer to next leg; anything else means on. Returns
+ * `null` when the env var is unset / empty — caller falls through to
+ * config or default.
+ */
+function readEnv(env, key) {
+    const raw = env[ENV_VAR[key]];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed === '0' || trimmed === 'false' || trimmed === 'off' || trimmed === 'no') {
+        return false;
+    }
+    return true;
+}
+function readConfig(cfg, key) {
+    if (!cfg)
+        return null;
+    const raw = cfg(CONFIG_KEY[key]);
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === 'boolean')
+        return raw;
+    if (typeof raw === 'string') {
+        const t = raw.trim().toLowerCase();
+        if (t === 'true' || t === '1' || t === 'on' || t === 'yes')
+            return true;
+        if (t === 'false' || t === '0' || t === 'off' || t === 'no')
+            return false;
+    }
+    if (typeof raw === 'number')
+        return raw !== 0;
+    return null;
+}
+// ── Singleton ──────────────────────────────────────────────────────────────
+let _singleton = null;
+/**
+ * Build a RuntimeToggles instance bound to the supplied deps.
+ * Public so tests can construct isolated instances.
+ */
+function buildRuntimeToggles(deps = {}) {
+    const env = deps.env ?? process.env;
+    // In-process overrides — set() updates this map; subsequent
+    // isEnabled() reads see the override before falling through to
+    // env/config/default.
+    const overrides = new Map();
+    const subscribers = new Map();
+    function resolve(key) {
+        // 1. env (Q-P8a-1a — explicit env always wins)
+        const envValue = readEnv(env, key);
+        if (envValue !== null)
+            return { value: envValue, source: 'env' };
+        // 2. in-process override (slash-command flip not yet persisted)
+        if (overrides.has(key))
+            return { value: overrides.get(key), source: 'config' };
+        // 3. config.yaml
+        const cfgValue = readConfig(deps.configRead, key);
+        if (cfgValue !== null)
+            return { value: cfgValue, source: 'config' };
+        // 4. default (v4.6 Phase 2M — per-key, see DEFAULT_VALUE)
+        return { value: DEFAULT_VALUE[key], source: 'default' };
+    }
+    function fire(key) {
+        const set = subscribers.get(key);
+        if (!set)
+            return;
+        for (const cb of set) {
+            try {
+                cb();
+            }
+            catch { /* never let an invalidation callback crash the flip */ }
+        }
+    }
+    return {
+        isEnabled(key) { return resolve(key).value; },
+        async set(key, value, opts = {}) {
+            overrides.set(key, value);
+            if (opts.persist !== false && deps.configWriteAndSave) {
+                await deps.configWriteAndSave(CONFIG_KEY[key], value);
+            }
+            fire(key);
+        },
+        snapshot() {
+            const out = {};
+            for (const k of ALL_KEYS)
+                out[k] = resolve(k);
+            return out;
+        },
+        onChange(key, cb) {
+            let set = subscribers.get(key);
+            if (!set) {
+                set = new Set();
+                subscribers.set(key, set);
+            }
+            set.add(cb);
+        },
+    };
+}
+/**
+ * Return the process-wide RuntimeToggles. When `initRuntimeToggles`
+ * hasn't been called, returns a env-only fallback resolver so core
+ * modules (sandboxConfig, turnState, browserState) keep working in
+ * test benches + core-only invocations.
+ */
+function getRuntimeToggles() {
+    if (!_singleton)
+        _singleton = buildRuntimeToggles();
+    return _singleton;
+}
+/**
+ * Initialise the singleton with the CLI's ConfigManager seam. Called
+ * once by `aidenCLI.ts::buildAgentRuntime` after config.yaml is loaded.
+ */
+function initRuntimeToggles(deps) {
+    _singleton = buildRuntimeToggles(deps);
+    return _singleton;
+}
+/** Test-only reset. */
+function _resetRuntimeTogglesForTests() {
+    _singleton = null;
+}
+exports._TOGGLE_KEYS = ALL_KEYS;

package/dist/core/v4/sandboxConfig.js

@@ -0,0 +1,285 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRealPath = resolveRealPath;
+exports._clearRealPathCacheForTests = _clearRealPathCacheForTests;
+exports.inferDefaultRiskTier = inferDefaultRiskTier;
+exports.readSandboxConfig = readSandboxConfig;
+exports.getSandboxConfig = getSandboxConfig;
+exports._resetSandboxConfigForTests = _resetSandboxConfigForTests;
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+const runtimeToggles_1 = require("./runtimeToggles");
+/**
+ * core/v4/sandboxConfig.ts — v4.4 Phase 1: Execution sandbox configuration.
+ *
+ * Single source of truth for sandbox enablement + resource policies +
+ * filesystem allow/deny lists + Docker hardening flags. Read from
+ * environment variables at construction time (matches v4.2's TurnState
+ * + v4.3's BrowserState env-driven pattern).
+ *
+ * Phase 1 ships the config types + reader + default-tier inference;
+ * downstream phases consume:
+ *   - Phase 2 — fsAllowList / fsDenyList used by file_* tools
+ *   - Phase 3 — defaultBackend / resourceLimits / networkMode /
+ *               persistent / idleReaperMs used by shell_exec + Docker
+ *               backend (long-lived container reuse, hardening flags)
+ *   - Phase 4 — dryRun used by all `mutates: true` tools
+ *   - Phase 5 — riskTier annotations consumed by FailureClassifier +
+ *               ApprovalEngine (as a FLOOR; patterns can escalate)
+ *
+ * v4.4 Phase 6 — default-on transition. AIDEN_SANDBOX is now
+ * enabled by default; users opt out with `AIDEN_SANDBOX=0`. The
+ * strict `!== '0'` flip mirrors v4.2 Phase 6 (TCE) + v4.3 Phase 6
+ * (browser depth) semantics exactly.
+ *
+ * AIDEN_DRYRUN is orthogonal — independent flag, independent semantics.
+ * Phase 6 does NOT flip dry-run; it stays opt-in by design (dry-run
+ * is a deliberate "preview-only" mode users opt into, not a default).
+ *
+ * Pure module — no I/O, no side effects, no Playwright/Docker
+ * dependencies. Just env-var reads + path normalization helpers.
+ * Easy to unit test by passing a stubbed `env` argument.
+ */
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+// ── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_RESOURCE_LIMITS = {
+    memory: '1g',
+    cpus: '2',
+    pidsLimit: 256,
+};
+const DEFAULT_IDLE_REAPER_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_IMAGE = 'node:22-alpine';
+/**
+ * v4.4 Phase 2 — default write-permitted paths. Real-resolved at
+ * config-build time to handle symlinked HOME / cwd. Caller can
+ * extend via `AIDEN_SANDBOX_ALLOW=p1:p2:...`.
+ */
+function buildDefaultAllowList() {
+    const home = node_os_1.default.homedir();
+    const tmp = node_os_1.default.tmpdir();
+    const cwd = process.cwd();
+    const paths = [
+        cwd,
+        node_path_1.default.join(home, 'Documents'),
+        node_path_1.default.join(home, 'Downloads'),
+        node_path_1.default.join(home, 'Desktop'),
+        tmp,
+    ];
+    return resolveRealPaths(paths);
+}
+/**
+ * v4.4 Phase 2 — default write-denied paths. Always wins over the
+ * allow list. Mirrors the consult-shaped deny-list pattern (sensitive
+ * configs, system dirs).
+ */
+function buildDefaultDenyList() {
+    const home = node_os_1.default.homedir();
+    const paths = [
+        node_path_1.default.join(home, '.ssh'),
+        node_path_1.default.join(home, '.aws'),
+        node_path_1.default.join(home, '.gnupg'),
+        node_path_1.default.join(home, '.env'),
+        node_path_1.default.join(home, '.netrc'),
+        node_path_1.default.join(home, '.pgpass'),
+        node_path_1.default.join(home, '.npmrc'),
+        node_path_1.default.join(home, '.pypirc'),
+        node_path_1.default.join(home, '.bashrc'),
+        node_path_1.default.join(home, '.zshrc'),
+        node_path_1.default.join(home, '.profile'),
+        '/etc',
+        '/var',
+        '/usr',
+        '/boot',
+        '/sys',
+        '/proc',
+    ];
+    return resolveRealPaths(paths);
+}
+// ── Path normalization ──────────────────────────────────────────────────────
+const _realPathCache = new Map();
+/**
+ * Resolve a path to its canonical absolute form. `path.resolve` first
+ * (handles relative + `..`); then `fs.realpathSync` to follow symlinks.
+ * Symlink resolution defeats the bypass attack where an allowlisted
+ * directory contains a symlink to a denied path.
+ *
+ * Results cached for the lifetime of the module (paths rarely change
+ * during a process; the cache hit rate is high on the file-tool path
+ * where every call resolves the same handful of allowlist entries).
+ *
+ * Falls back gracefully when the path doesn't exist (returns the
+ * resolved-but-unrealpath form) — caller may be checking a path
+ * about to be created.
+ */
+function resolveRealPath(input) {
+    if (_realPathCache.has(input))
+        return _realPathCache.get(input);
+    const resolved = node_path_1.default.resolve(input);
+    let real = resolved;
+    try {
+        real = node_fs_1.default.realpathSync.native ? node_fs_1.default.realpathSync.native(resolved) : node_fs_1.default.realpathSync(resolved);
+    }
+    catch {
+        // Path may not exist yet (e.g. file_write target). Use the
+        // resolved form; symlink-bypass on a non-existent path isn't
+        // a real attack vector.
+    }
+    _realPathCache.set(input, real);
+    return real;
+}
+/** Resolve an array of paths to their canonical forms; deduplicate. */
+function resolveRealPaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const p of paths) {
+        const real = resolveRealPath(p);
+        if (!seen.has(real)) {
+            seen.add(real);
+            out.push(real);
+        }
+    }
+    return out;
+}
+/** Public for tests — clears the realpath cache so env-var changes
+ *  in test isolation pick up fresh resolutions. Production code never
+ *  calls this. */
+function _clearRealPathCacheForTests() {
+    _realPathCache.clear();
+}
+// ── Env-var parsing helpers ─────────────────────────────────────────────────
+function parseList(raw) {
+    if (!raw)
+        return [];
+    return raw.split(':').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function parseIntSafe(raw, fallback) {
+    if (raw === undefined || raw === null || raw === '')
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function parseNetworkMode(raw) {
+    if (raw === 'none')
+        return 'none';
+    return 'bridge'; // bridge for unset / 'bridge' / junk
+}
+// ── Risk-tier inference ─────────────────────────────────────────────────────
+/**
+ * Default risk tier for a tool that doesn't carry an explicit
+ * `riskTier` annotation. Leverages the existing `mutates: boolean`
+ * field — mutating tools default to `caution`, read-only tools
+ * default to `safe`. Plugin tools without annotation get a safe
+ * default for free.
+ *
+ * Phase 5 ApprovalEngine integration treats explicit annotations as
+ * a FLOOR — DANGEROUS_PATTERNS can escalate but never demote. The
+ * inference here is the floor when no annotation exists at all.
+ */
+function inferDefaultRiskTier(mutates) {
+    return mutates ? 'caution' : 'safe';
+}
+// ── Reader ──────────────────────────────────────────────────────────────────
+/**
+ * Pure factory. Reads env vars + defaults into a frozen-snapshot
+ * SandboxConfig. Idempotent for a given env. The CLI calls this
+ * once at boot via the singleton factory below; tests pass a custom
+ * `env` argument.
+ */
+function readSandboxConfig(env = process.env) {
+    // v4.4 Phase 6 — default-on transition. AIDEN_SANDBOX is now
+    // enabled by default; users opt out with `AIDEN_SANDBOX=0`.
+    //
+    // v4.5 Phase 8a — the actual read goes through the runtimeToggles
+    // singleton so /sandbox slash-command flips and config.yaml
+    // overrides take effect without restart. When the singleton was
+    // initialised by the CLI it consults env > config.yaml > default;
+    // when not initialised (test bench) it falls back to env > default
+    // — the existing semantics.
+    //   unset / '1' / 'true' / junk → enabled
+    //   '0'                          → disabled
+    // Mirrors v4.2 Phase 6 (TCE) + v4.3 Phase 6 (browser depth)
+    // semantics exactly. The strict `!== '0'` check matches the
+    // pattern those phases set: any explicit "off" value disables;
+    // everything else (including unset) enables.
+    // v4.5 Phase 8a — when env (the readSandboxConfig input) is not the
+    // process env (test bench passing a custom env), honour the input
+    // directly to keep test isolation. Otherwise route through the
+    // runtimeToggles singleton.
+    const enabled = env === process.env
+        ? (0, runtimeToggles_1.getRuntimeToggles)().isEnabled('sandbox')
+        : env.AIDEN_SANDBOX !== '0';
+    // Allow/deny lists: defaults + user-provided extensions.
+    const customAllow = parseList(env.AIDEN_SANDBOX_ALLOW).map(resolveRealPath);
+    const customDeny = parseList(env.AIDEN_SANDBOX_DENY).map(resolveRealPath);
+    const fsAllowList = Array.from(new Set([...buildDefaultAllowList(), ...customAllow]));
+    const fsDenyList = Array.from(new Set([...buildDefaultDenyList(), ...customDeny]));
+    // Resource limits — string values pass through Docker as-is.
+    const resourceLimits = {
+        memory: env.AIDEN_SANDBOX_MEMORY ?? DEFAULT_RESOURCE_LIMITS.memory,
+        cpus: env.AIDEN_SANDBOX_CPUS ?? DEFAULT_RESOURCE_LIMITS.cpus,
+        pidsLimit: parseIntSafe(env.AIDEN_SANDBOX_PIDS, DEFAULT_RESOURCE_LIMITS.pidsLimit),
+    };
+    const networkMode = parseNetworkMode(env.AIDEN_SANDBOX_NETWORK);
+    const persistent = env.AIDEN_SANDBOX_PERSISTENT !== '0'; // default true
+    const idleReaperMs = parseIntSafe(env.AIDEN_SANDBOX_IDLE_MS, DEFAULT_IDLE_REAPER_MS);
+    const dryRun = env.AIDEN_DRYRUN === '1';
+    const image = typeof env.AIDEN_SANDBOX_IMAGE === 'string' && env.AIDEN_SANDBOX_IMAGE.trim().length > 0
+        ? env.AIDEN_SANDBOX_IMAGE.trim()
+        : DEFAULT_IMAGE;
+    // Phase 3 will route to 'docker' when enabled AND docker is
+    // available. Phase 1 reports the abstract default — Phase 3's
+    // runtime probe decides the actual route.
+    const defaultBackend = enabled ? 'docker' : 'local';
+    return {
+        enabled,
+        fsAllowList,
+        fsDenyList,
+        defaultBackend,
+        persistent,
+        resourceLimits,
+        networkMode,
+        idleReaperMs,
+        dryRun,
+        image,
+    };
+}
+// ── Singleton ───────────────────────────────────────────────────────────────
+let _singleton = null;
+let _toggleHookInstalled = false;
+/**
+ * Read the singleton sandbox config. Initialized on first call from
+ * `process.env` (matches v4.2 TurnState / v4.3 BrowserState lifecycle).
+ * Tests construct fresh configs via `readSandboxConfig(env)` directly
+ * — the singleton path is for production CLI startup.
+ */
+function getSandboxConfig() {
+    if (!_toggleHookInstalled) {
+        // v4.5 Phase 8a — invalidate the singleton when /sandbox toggles.
+        // Registered lazily on first read so test benches that build
+        // their own runtimeToggles + reset between cases don't carry
+        // hooks across instances.
+        try {
+            (0, runtimeToggles_1.getRuntimeToggles)().onChange('sandbox', () => { _singleton = null; });
+            _toggleHookInstalled = true;
+        }
+        catch { /* runtimeToggles import / init race — best-effort */ }
+    }
+    if (!_singleton)
+        _singleton = readSandboxConfig();
+    return _singleton;
+}
+/** Reset the singleton for test isolation. Production code never calls this. */
+function _resetSandboxConfigForTests() {
+    _singleton = null;
+    _toggleHookInstalled = false;
+    _clearRealPathCacheForTests();
+}