aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/suggestionCatalog.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/suggestionCatalog.ts — v4.5 Phase 8b.
+ *
+ * Pre-rendered user-facing copy for each contextual suggestion slot.
+ * Centralised here so future tone tuning / i18n can change one file
+ * without touching the engine.
+ *
+ * Style guide (approved tone Q-P8b-5(b)):
+ *   - One line per tip.
+ *   - ≤ 90 visible chars (room for indentation + emoji).
+ *   - "💡 tip:" prefix, lowercase command + brief why.
+ *   - No trailing punctuation gymnastics.
+ *   - No second-person preaching ("you should" → drop).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUGGESTION_COPY = void 0;
+exports.suggestionMessageFor = suggestionMessageFor;
+/**
+ * Slot → message map. The engine resolves the slot and the
+ * catalog renders the matching copy.
+ */
+exports.SUGGESTION_COPY = Object.freeze({
+    sandbox: '💡 tip: enable /sandbox on for a safer guardrail against destructive ops.',
+    browser_depth: '💡 tip: enable /browser-depth on to capture page state + auto-retry stale refs.',
+    daemon_scheduling: '💡 tip: this looks like a recurring task — `aiden cron add` or `aiden trigger add file` can run it on a schedule.',
+    tce_recovery: '💡 tip: enable /tce on so Aiden classifies tool failures + auto-recovers.',
+});
+/**
+ * Look up the rendered tip string for a slot. Pure — caller decides
+ * when to display (`display.dim()` is the conventional sink).
+ */
+function suggestionMessageFor(slot) {
+    return exports.SUGGESTION_COPY[slot];
+}

package/dist/core/v4/suggestionEngine.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/suggestionEngine.ts — v4.5 Phase 8b.
+ *
+ * Contextual one-time suggestions for the v4.4/v4.5 subsystems the
+ * user hasn't enabled yet. Fires when their CURRENT task would
+ * genuinely benefit:
+ *
+ *   - sandbox            → destructive shell pattern + sandbox is OFF
+ *   - browser_depth      → browser_* tool call + browser_depth is OFF
+ *   - daemon_scheduling  → user said "every day", "watch this folder",
+ *                          "when an email arrives", etc.
+ *   - tce_recovery       → recovery situation reached + TCE is OFF
+ *                          (lower priority; most users keep TCE on)
+ *
+ * Budget Q-P8b-1(a): 2 suggestions per session global. Each slot
+ * fires AT MOST ONCE per session. Resets on REPL restart.
+ *
+ * Dismissal Q-P8b-4(c) + Q-P8b-6(a):
+ *   - Per-session: `dismissAll()` silences for the rest of the session.
+ *   - Permanent: `runtime_toggles.suggestions = false` in config.yaml
+ *     (slash command persists). Engine reads via runtimeToggles
+ *     singleton — when the toggle reports OFF the engine treats every
+ *     classification as "no tip".
+ *
+ * Pure module — no I/O. Display happens at the call site
+ * (`display.dim()` per audit Q-P8b-3). Engine only classifies +
+ * tracks state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSuggestionEngine = buildSuggestionEngine;
+exports.getSuggestionEngine = getSuggestionEngine;
+exports._resetSuggestionEngineForTests = _resetSuggestionEngineForTests;
+const dangerousPatterns_1 = require("../../moat/dangerousPatterns");
+const runtimeToggles_1 = require("./runtimeToggles");
+const suggestionCatalog_1 = require("./suggestionCatalog");
+// ── Daemon-scheduling regex (Q-P8b-2a — simple keyword) ────────────────────
+const SCHEDULING_PATTERNS = [
+    /\b(every|each)\s+(day|hour|minute|week|morning|evening|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/i,
+    /\b(daily|hourly|weekly|nightly)\b/i,
+    /\bat\s+\d{1,2}(:\d{2})?\s*(am|pm)?\s+(every|each)\b/i,
+    /\bwatch\s+(this|the)?\s*(folder|directory|path)\b/i,
+    /\bmonitor\s+(changes|files?|directory|folder)\b/i,
+    /\bwhen\s+(an?\s+)?(email|webhook|file|message)\s+(arrives|comes|is\s+received|drops)\b/i,
+    /\b(remind|alert|notify)\s+me\s+(when|to|every)\b/i,
+    /\bset\s+up\s+(a\s+)?(cron|schedule|trigger|watcher|webhook)\b/i,
+];
+// ── System-path heuristic for file_* tool sandbox tips ─────────────────────
+const SYSTEM_PATH_PATTERNS = [
+    /^\/etc\b/i,
+    /^\/System\b/i,
+    /^\/Library\/System\b/i,
+    /^\/usr\/(s)?bin\b/i,
+    /^[A-Z]:\\Windows\b/i,
+    /^[A-Z]:\\Program\s+Files\b/i,
+    /\\System32\\/i,
+];
+function isSystemPath(p) {
+    if (typeof p !== 'string' || p.length === 0)
+        return false;
+    return SYSTEM_PATH_PATTERNS.some((r) => r.test(p));
+}
+// ── Classifiers (pure) ─────────────────────────────────────────────────────
+/** sandbox slot — destructive shell or system-path write. */
+function classifySandbox(call) {
+    const args = (call.arguments ?? {});
+    if (call.name === 'shell_exec') {
+        const cmd = typeof args.command === 'string' ? args.command : '';
+        if (cmd.length === 0)
+            return false;
+        const cls = (0, dangerousPatterns_1.classifyCommand)(cmd);
+        return cls.tier === 'caution' || cls.tier === 'dangerous';
+    }
+    if (call.name === 'file_write' || call.name === 'file_delete'
+        || call.name === 'file_move' || call.name === 'file_patch') {
+        const target = typeof args.path === 'string' ? args.path
+            : typeof args.target === 'string' ? args.target
+                : '';
+        return isSystemPath(target);
+    }
+    return false;
+}
+/** browser_depth slot — any browser_* tool fires the suggestion when off. */
+function classifyBrowserDepth(call) {
+    return call.name.startsWith('browser_');
+}
+/** daemon_scheduling slot — keyword regex on initial message. */
+function classifySchedulingIntent(message) {
+    if (typeof message !== 'string' || message.length < 6)
+        return false;
+    return SCHEDULING_PATTERNS.some((r) => r.test(message));
+}
+// ── Singleton ──────────────────────────────────────────────────────────────
+const DEFAULT_BUDGET_PER_SESSION = 2;
+function buildSuggestionEngine(opts = {}) {
+    const budget = opts.budgetPerSession ?? DEFAULT_BUDGET_PER_SESSION;
+    const getRT = opts.runtimeTogglesGetter ?? (() => (0, runtimeToggles_1.getRuntimeToggles)());
+    const firedSlots = new Set();
+    let dismissedSession = false;
+    function permanentlyOff() {
+        try {
+            // 'suggestions' is wired as a runtime toggle key via Phase 8b
+            // schema extension. When the user has typed `/suggestions off`
+            // (persisted to config.yaml runtime_toggles.suggestions=false),
+            // the toggle reports off and we skip every classification.
+            return !getRT().isEnabled('suggestions');
+        }
+        catch {
+            // Defensive — if the toggle key isn't registered yet we treat
+            // suggestions as on (the default).
+            return false;
+        }
+    }
+    function canFire(slot) {
+        if (dismissedSession)
+            return false;
+        if (permanentlyOff())
+            return false;
+        if (firedSlots.has(slot))
+            return false;
+        if (firedSlots.size >= budget)
+            return false;
+        // Only suggest when the relevant subsystem is OFF — otherwise the
+        // tip is noise. Mapping: slot → underlying runtimeToggles key.
+        try {
+            switch (slot) {
+                case 'sandbox':
+                    if (getRT().isEnabled('sandbox'))
+                        return false;
+                    break;
+                case 'browser_depth':
+                    if (getRT().isEnabled('browser_depth'))
+                        return false;
+                    break;
+                case 'tce_recovery':
+                    if (getRT().isEnabled('tce'))
+                        return false;
+                    break;
+                case 'daemon_scheduling':
+                    // No matching toggle — daemon mode is a process-level
+                    // boolean (AIDEN_DAEMON). Suggest only when daemon is off,
+                    // which we detect by reading the env var (the daemon
+                    // toggle isn't part of runtime_toggles by design).
+                    if (process.env.AIDEN_DAEMON === '1')
+                        return false;
+                    break;
+            }
+        }
+        catch { /* defensive */ }
+        return true;
+    }
+    function build(slot) {
+        return { slot, message: (0, suggestionCatalog_1.suggestionMessageFor)(slot) };
+    }
+    return {
+        checkToolCall(call) {
+            if (!call || typeof call.name !== 'string')
+                return null;
+            if (classifyBrowserDepth(call) && canFire('browser_depth')) {
+                return build('browser_depth');
+            }
+            if (classifySandbox(call) && canFire('sandbox')) {
+                return build('sandbox');
+            }
+            return null;
+        },
+        checkInitialMessage(message) {
+            if (classifySchedulingIntent(message) && canFire('daemon_scheduling')) {
+                return build('daemon_scheduling');
+            }
+            return null;
+        },
+        recordFired(slot) {
+            firedSlots.add(slot);
+        },
+        dismissAll() {
+            dismissedSession = true;
+        },
+        snapshot() {
+            return {
+                firedSlots: [...firedSlots],
+                dismissedSession,
+                permanentlyOff: permanentlyOff(),
+                budgetRemaining: Math.max(0, budget - firedSlots.size),
+            };
+        },
+        _resetForTests() {
+            firedSlots.clear();
+            dismissedSession = false;
+        },
+    };
+}
+// ── Process-wide singleton ─────────────────────────────────────────────────
+let _singleton = null;
+function getSuggestionEngine() {
+    if (!_singleton)
+        _singleton = buildSuggestionEngine();
+    return _singleton;
+}
+function _resetSuggestionEngineForTests() {
+    if (_singleton)
+        _singleton._resetForTests();
+    _singleton = null;
+}

package/dist/core/v4/toolRegistry.js

@@ -49,10 +49,19 @@ class ToolRegistry {
         return [...this.handlers.keys()];
     }
     /**
-     * Schemas to advertise to the LLM. When `filterToolsets` is provided,
-     * only handlers whose `toolset` matches one of the entries are returned.
+     * Schemas to advertise to the LLM. Two optional filters, AND-combined:
+     *
+     *   - `filterToolsets`: include only handlers whose `toolset` matches
+     *     one of the entries. Applied first (preserves pre-v4.6 behaviour
+     *     when called with one argument).
+     *   - `context` (v4.6 Phase 1): include only handlers whose
+     *     `contexts` array contains this value, OR whose `contexts` is
+     *     undefined (default = visible everywhere). Applied second.
+     *
+     * Both filters default to "no filter" when omitted. Callers that
+     * predate v4.6 pass one arg or none and continue working unchanged.
      */
-    getSchemas(filterToolsets) {
+    getSchemas(filterToolsets, context) {
         const out = [];
         for (const handler of this.handlers.values()) {
             if (filterToolsets && filterToolsets.length > 0) {
@@ -60,6 +69,13 @@ class ToolRegistry {
                     continue;
                 }
             }
+            if (context !== undefined) {
+                // contexts undefined → tool is visible in both REPL and daemon
+                // (backward-compat default for every pre-v4.6 tool).
+                if (handler.contexts !== undefined && !handler.contexts.includes(context)) {
+                    continue;
+                }
+            }
             out.push(handler.schema);
         }
         return out;
@@ -136,12 +152,30 @@ class ToolRegistry {
                     riskTier = c.tier;
                     reason = c.reason;
                 }
+                // v4.4 Phase 4 — dangerous-tier auto-preview. Surface
+                // "what would happen if you say yes" to the approval prompt.
+                // Effective tier is the handler annotation (Phase 1 floor)
+                // OR the classifier escalation above (whichever is higher).
+                let preview;
+                const effectiveTier = (riskTier === 'dangerous' || handler.riskTier === 'dangerous')
+                    ? 'dangerous' : (riskTier ?? handler.riskTier);
+                if (effectiveTier === 'dangerous' && typeof handler.buildPreview === 'function') {
+                    try {
+                        preview = await handler.buildPreview(args, context);
+                    }
+                    catch {
+                        // Preview is best-effort. A bad preview never blocks
+                        // the underlying approval decision.
+                        preview = undefined;
+                    }
+                }
                 const allowed = await context.approvalEngine.checkApproval({
                     toolName: call.name,
                     category: handler.category,
                     args,
                     riskTier,
                     reason,
+                    preview,
                 });
                 if (!allowed) {
                     return {