aiden-runtime 4.1.5 → 4.5.0

package/dist/core/v4/dryRun.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/dryRun.ts — v4.4 Phase 4: dry-run preview infrastructure.
+ *
+ * AIDEN_DRYRUN=1 makes every `mutates: true` tool emit a preview of
+ * what it would do instead of doing it. Read-only tools are
+ * unaffected — the HOC passes them through unchanged.
+ *
+ * Two consumers wire into this module:
+ *   1. tools/v4/index.ts — wraps every registered handler in
+ *      withDryRun(...) so AIDEN_DRYRUN=1 short-circuits `execute`
+ *      to a preview before any side-effect runs.
+ *   2. core/v4/toolRegistry.ts (executeOne) — for dangerous-tier
+ *      tools, calls handler.buildPreview before forwarding to
+ *      ApprovalEngine so the approval prompt can show the user
+ *      exactly what they're being asked to allow.
+ *
+ * Design choices (v4.4 Phase 4 audit):
+ *   - HOC pattern (Q-P4-1 (a)) — uniform envelope across 27 tools.
+ *   - buildPreview is an OPTIONAL method on ToolHandler
+ *     (Q-P4-2 (a)) — tools without one are passed through with a
+ *     generic "would execute" envelope.
+ *   - Browser/unpredictable tools surface intent only
+ *     (Q-P4-3 (a)).
+ *   - aiden_self_update returns a `refuse` side-effect
+ *     (Q-P4-4 (a)).
+ *   - Dangerous-tier auto-preview reaches the user via approval
+ *     prompt only, never as a duplicate field on a successful
+ *     execution result (Q-P4-5 (a)).
+ *
+ * Gated by `SandboxConfig.dryRun` (AIDEN_DRYRUN=1 strict). Phase 6
+ * does NOT flip this default — dry-run stays opt-in by design.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDryRun = withDryRun;
+exports.genericPreview = genericPreview;
+exports.truncatePreview = truncatePreview;
+exports.makeWouldExecute = makeWouldExecute;
+const sandboxConfig_1 = require("./sandboxConfig");
+// ── HOC ─────────────────────────────────────────────────────────────────────
+/**
+ * Wrap a tool handler so its `execute` short-circuits to a preview
+ * when AIDEN_DRYRUN=1. Read-only tools (`mutates: false`) are
+ * returned unchanged — dry-run is meaningless for them.
+ *
+ * Tools without a `buildPreview` method get a generic preview that
+ * just echoes their args. We never block on missing previews; the
+ * coverage sentinel test catches the omission at gate time.
+ */
+function withDryRun(handler) {
+    if (!handler.mutates)
+        return handler;
+    const innerExecute = handler.execute.bind(handler);
+    const wrappedExecute = async (args, ctx) => {
+        const config = (0, sandboxConfig_1.getSandboxConfig)();
+        if (!config.dryRun) {
+            return innerExecute(args, ctx);
+        }
+        const would = handler.buildPreview
+            ? await handler.buildPreview(args, ctx)
+            : genericPreview(handler, args);
+        const out = {
+            success: true,
+            dryRun: true,
+            wouldExecute: would,
+        };
+        return out;
+    };
+    return {
+        ...handler,
+        execute: wrappedExecute,
+    };
+}
+/**
+ * Fallback preview for a tool that doesn't define `buildPreview`.
+ * Surfaces the call shape so the user at least sees what would
+ * have run. The coverage sentinel ensures we don't ship any
+ * mutating tool without a real preview, but the safety net keeps
+ * runtime well-behaved even if a plugin tool slips through.
+ */
+function genericPreview(handler, args) {
+    return {
+        tool: handler.schema.name,
+        args,
+        riskTier: handler.riskTier ?? (handler.mutates ? 'caution' : 'safe'),
+        sideEffects: [],
+        detectedRisks: [],
+        summary: `${handler.schema.name} would execute (no detailed preview registered)`,
+    };
+}
+// ── Helpers for tool authors ────────────────────────────────────────────────
+/** Truncate a string for inline preview display. */
+function truncatePreview(s, max = 200) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + `… (${s.length - max} more chars)`;
+}
+/**
+ * Compose a `WouldExecute` for a tool that wants the boilerplate
+ * filled in. Tool's buildPreview can call this and add side-effects.
+ */
+function makeWouldExecute(opts) {
+    return {
+        tool: opts.handler.schema.name,
+        args: opts.args,
+        riskTier: opts.handler.riskTier ?? (opts.handler.mutates ? 'caution' : 'safe'),
+        sideEffects: opts.sideEffects,
+        detectedRisks: opts.detectedRisks ?? [],
+        summary: opts.summary,
+    };
+}