aiden-runtime 4.1.5 → 4.5.0

package/dist/core/v4/browserState.js

@@ -0,0 +1,436 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/browserState.ts — v4.3 Phase 1: Page-state observer.
+ *
+ * Per-agent-session observer that captures structured browser-page
+ * state before and after every browser tool action. The captured
+ * states embed on the tool result as a `browserState` sidecar; Phase 5
+ * will use the sidecar to classify "tool succeeded but UI did nothing"
+ * cases that currently look identical to genuine success.
+ *
+ * Three production rules from the consult shape this module:
+ *
+ *   - **Element refs are leases, not identifiers.** ElementLease defined
+ *     here, validated in Phase 2 — carries snapshot_id + frame_id +
+ *     visible_text_hash + bbox so mismatches signal "DOM changed since
+ *     we took this ref".
+ *
+ *   - **Frame_id is part of the contract.** Iframe blindness is a real
+ *     gap; BrowserStateSnapshot carries frame_id + frame_tree_hash so
+ *     cross-frame DOM churn is observable.
+ *
+ *   - **Never equate tool success with UI progress.** ActionResult
+ *     includes progress_score + maybe_noop + needs_verifier; a tool
+ *     returning success:true AND maybe_noop:true is the structural
+ *     signal for "click executed but nothing changed".
+ *
+ * **Default ON** as of v4.3 Phase 6 — set `AIDEN_BROWSER_DEPTH=0`
+ * to disable. Symmetric with v4.2 Phase 6's TCE flip. When disabled,
+ * `captureState()` returns null and the HOC wrapper
+ * (`tools/v4/browser/_observer.ts`) skips snapshot work entirely.
+ * Zero behavioural change vs v4.2.5 when disabled.
+ *
+ * Pure module — types + class + helpers. No I/O on the disabled path;
+ * two `page.evaluate()` calls per action when enabled (URL + title +
+ * innerText hash + recursive iframe URL walk). Latency ~5-15ms per
+ * snapshot; observer overhead per action ~10-30ms total.
+ *
+ * Reference notes: the snapshot shape (URL/title/dom_hash/frame_id)
+ * mirrors a pattern seen in a comparable reference system; the
+ * ElementLease shape was contributed by a downstream consult. Aiden
+ * keeps the typing clean and the implementation Aiden-shaped.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserState = void 0;
+exports.sha256Hex = sha256Hex;
+exports.normalizeUrl = normalizeUrl;
+exports.createBrowserState = createBrowserState;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+// ── Helpers (exported for tests + ElementLease lifecycle in Phase 2) ───────
+const SHORT_TEXT_HASH_CAP = 5000;
+const TRACKING_PARAMS = new Set([
+    'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
+    'gclid', 'fbclid', 'mc_eid', 'mc_cid', '_ga', 'ref', '_hsenc', '_hsmi',
+    'igshid', 'msclkid', 'yclid',
+]);
+/**
+ * Stable sha256 over a string. Hex-encoded. Truncated input — caller
+ * is responsible for slicing to a sensible bound.
+ */
+function sha256Hex(input) {
+    return node_crypto_1.default.createHash('sha256').update(input).digest('hex');
+}
+/**
+ * Strip hash + common tracking params + trailing slash. Pure helper;
+ * exported for tests + ElementLease URL normalization.
+ */
+function normalizeUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return raw; // unparseable — return as-is rather than crashing
+    }
+    url.hash = '';
+    const next = new URLSearchParams();
+    for (const [k, v] of url.searchParams) {
+        if (!TRACKING_PARAMS.has(k.toLowerCase()))
+            next.append(k, v);
+    }
+    url.search = next.toString();
+    let out = url.toString();
+    // Drop trailing slash on the path component when query is empty.
+    if (out.endsWith('/') && !url.search && url.pathname === '/') {
+        out = out.slice(0, -1);
+    }
+    return out;
+}
+// ── Snapshot-pair evidence + score ─────────────────────────────────────────
+const PROGRESS_WEIGHTS = [
+    ['url_changed', 0.8],
+    ['normalized_url_changed', 0.7],
+    ['dom_hash_changed', 0.6],
+    ['frame_tree_changed', 0.5],
+    ['title_changed', 0.4],
+];
+function computeEvidence(pre, post) {
+    const evidence = [];
+    if (pre.url !== post.url)
+        evidence.push('url_changed');
+    if (pre.normalized_url !== post.normalized_url)
+        evidence.push('normalized_url_changed');
+    if (pre.title !== post.title)
+        evidence.push('title_changed');
+    if (pre.dom_text_hash !== post.dom_text_hash)
+        evidence.push('dom_hash_changed');
+    if (pre.frame_tree_hash !== post.frame_tree_hash)
+        evidence.push('frame_tree_changed');
+    return evidence;
+}
+function computeProgressScore(evidence) {
+    let score = 0;
+    for (const [name, weight] of PROGRESS_WEIGHTS) {
+        if (evidence.includes(name) && weight > score)
+            score = weight;
+    }
+    return score;
+}
+// ── BrowserState class ─────────────────────────────────────────────────────
+const NEEDS_VERIFIER_THRESHOLD = 0.3;
+/**
+ * Per-agent-session observer. Lifecycle matches the playwrightBridge's
+ * persistent context. Reads AIDEN_BROWSER_DEPTH at construction; all
+ * methods short-circuit when disabled.
+ */
+class BrowserState {
+    constructor(opts = {}) {
+        this.snapshotCounter = 0;
+        /** v4.3 Phase 4 — per-tab metadata. Keyed by stable tab_id. */
+        this.tabs = new Map();
+        /** v4.3 Phase 4 — id of the currently-focused tab. */
+        this.activeTabId = null;
+        // v4.3 Phase 6 — state-aware browser depth is ON by default.
+        // Strict `'0'` opt-out semantic: env var must be literally the
+        // string `'0'` to disable; everything else (unset, `'1'`, empty
+        // string, junk) enables. Mirrors v4.2 Phase 6's TCE flip exactly.
+        // The opts.enabled override still wins when explicitly passed
+        // by callers (test fixtures, embedded usage).
+        // v4.5 Phase 8a — route through runtimeToggles singleton so
+        // /browser-depth slash-command flips and config.yaml overrides
+        // take effect on the next constructed BrowserState. Explicit
+        // opts.enabled still wins for test fixtures.
+        if (typeof opts.enabled === 'boolean') {
+            this.enabled = opts.enabled;
+        }
+        else {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const rt = require('./runtimeToggles');
+                this.enabled = rt.getRuntimeToggles().isEnabled('browser_depth');
+            }
+            catch {
+                this.enabled = process.env.AIDEN_BROWSER_DEPTH !== '0';
+            }
+        }
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Inject a bridge loader for tests. Production code uses the default
+     * `() => import('../playwrightBridge')` loader set by `createBrowserState`.
+     */
+    setBridgeLoader(loader) {
+        this.bridgeLoader = loader;
+    }
+    /**
+     * Capture current page state. Returns null when:
+     *   - opt'd out (AIDEN_BROWSER_DEPTH=0)
+     *   - bridge loader missing
+     *   - underlying pwSnapshotHash fails (browser not open, page error, etc.)
+     *
+     * Never throws — observer must not break the inner tool execute.
+     */
+    async captureState() {
+        if (!this.enabled)
+            return null;
+        if (!this.bridgeLoader)
+            return null;
+        let raw;
+        try {
+            raw = await this.bridgeLoader();
+        }
+        catch {
+            return null;
+        }
+        let result;
+        try {
+            result = await raw.pwSnapshotHash();
+        }
+        catch {
+            return null;
+        }
+        if (!result.ok)
+            return null;
+        this.snapshotCounter += 1;
+        const url = result.url ?? '';
+        const title = result.title ?? '';
+        const snapshot = {
+            url,
+            normalized_url: normalizeUrl(url),
+            title,
+            dom_text_hash: result.dom_text_hash ?? '',
+            frame_id: 'main',
+            frame_tree_hash: result.frame_tree_hash ?? '',
+            ts: this.snapshotCounter,
+        };
+        // v4.3 Phase 4 — reconcile the tabs map. Lazy: runs after the
+        // snapshot is built so a captureState failure (bridge ok:false)
+        // skips reconciliation entirely. Never throws.
+        await this.reconcileTabs(snapshot.dom_text_hash);
+        return snapshot;
+    }
+    // ── v4.3 Phase 4 — multi-tab state API ─────────────────────────────────
+    /**
+     * Reconcile the tabs map against the bridge's current page set.
+     * Adds newly-observed tabs, updates `last_seen_ts` (and
+     * `last_snapshot_hash` for the active tab), removes tabs absent
+     * from the bridge's enumeration. Sets `activeTabId`.
+     *
+     * Called from `captureState()` after a successful snapshot. Public
+     * for tests + future v4.4 multi-tab dispatch flows.
+     *
+     * No-op when:
+     *   - disabled (opt-out via AIDEN_BROWSER_DEPTH=0)
+     *   - bridge loader missing pwSnapshotTabs (older test fixtures)
+     *   - bridge returns ok:false (browser closed, page error)
+     *
+     * Never throws — observer must not break the inner tool execute.
+     */
+    async reconcileTabs(activeSnapshotHash) {
+        if (!this.enabled)
+            return;
+        if (!this.bridgeLoader)
+            return;
+        let raw;
+        try {
+            raw = await this.bridgeLoader();
+        }
+        catch {
+            return;
+        }
+        if (!raw.pwSnapshotTabs)
+            return;
+        let result;
+        try {
+            result = await raw.pwSnapshotTabs();
+        }
+        catch {
+            return;
+        }
+        if (!result.ok || !result.tabs)
+            return;
+        const now = Date.now();
+        const seenIds = new Set();
+        let activeId = null;
+        for (const t of result.tabs) {
+            seenIds.add(t.tab_id);
+            if (t.is_active)
+                activeId = t.tab_id;
+            const existing = this.tabs.get(t.tab_id);
+            if (existing) {
+                existing.url = t.url;
+                existing.title = t.title;
+                existing.is_active = t.is_active;
+                existing.opener_id = t.opener_id;
+                existing.last_seen_ts = now;
+                if (t.is_active && activeSnapshotHash) {
+                    existing.last_snapshot_hash = activeSnapshotHash;
+                }
+            }
+            else {
+                const fresh = {
+                    tab_id: t.tab_id,
+                    url: t.url,
+                    title: t.title,
+                    is_active: t.is_active,
+                    opener_id: t.opener_id,
+                    created_ts: now,
+                    last_seen_ts: now,
+                };
+                if (t.is_active && activeSnapshotHash) {
+                    fresh.last_snapshot_hash = activeSnapshotHash;
+                }
+                this.tabs.set(t.tab_id, fresh);
+            }
+        }
+        // Drop closed tabs — anything in the map that wasn't in this
+        // reconciliation pass.
+        for (const id of [...this.tabs.keys()]) {
+            if (!seenIds.has(id))
+                this.tabs.delete(id);
+        }
+        this.activeTabId = activeId;
+    }
+    /**
+     * Update the active tab's `last_blocker` field. Called by the HOC
+     * after Phase 3 detection — pass the BlockerSurface to record, or
+     * null to clear (e.g. a later action on the same tab succeeded
+     * without blocker text). No-op when disabled or when there's no
+     * active tab.
+     */
+    updateActiveTabBlocker(blocker) {
+        if (!this.enabled || !this.activeTabId)
+            return;
+        const tab = this.tabs.get(this.activeTabId);
+        if (!tab)
+            return;
+        if (blocker === null) {
+            delete tab.last_blocker;
+        }
+        else {
+            tab.last_blocker = blocker;
+        }
+    }
+    /**
+     * Read-only view of the tabs map. Returns a defensive shallow-clone
+     * array. Order is the bridge-reported order (which typically tracks
+     * Playwright's internal target ordering — first-opened first).
+     */
+    getTabs() {
+        return [...this.tabs.values()].map((t) => ({ ...t }));
+    }
+    /** Convenience: the tab marked is_active, or null when none. */
+    getActiveTab() {
+        if (!this.activeTabId)
+            return null;
+        const tab = this.tabs.get(this.activeTabId);
+        return tab ? { ...tab } : null;
+    }
+    /** Lookup a tab by id. Returns null when not in the map. */
+    getTab(tabId) {
+        const tab = this.tabs.get(tabId);
+        return tab ? { ...tab } : null;
+    }
+    /**
+     * Build the ActionResult sidecar from a pair of snapshots. Returns
+     * null when either snapshot is null (disabled or capture failed) —
+     * caller should skip embedding the sidecar entirely in that case.
+     */
+    buildActionResult(input) {
+        if (!input.pre || !input.post)
+            return null;
+        const evidence = computeEvidence(input.pre, input.post);
+        const progress_score = computeProgressScore(evidence);
+        const maybe_noop = evidence.length === 0;
+        const needs_verifier = maybe_noop || progress_score < NEEDS_VERIFIER_THRESHOLD;
+        return {
+            pre_state: input.pre,
+            post_state: input.post,
+            progress_score,
+            evidence,
+            maybe_noop,
+            needs_verifier,
+        };
+    }
+    /**
+     * v4.3 Phase 2 — compute evidence-array delta between two snapshots.
+     * Public so the observer HOC can record `state_delta` on a
+     * stale-ref retry without re-deriving from `buildActionResult`
+     * (which expects a pair representing one action, not a pair across
+     * a failed attempt + resnapshot).
+     *
+     * Returns the same set of evidence strings produced by
+     * `buildActionResult`: `url_changed`, `normalized_url_changed`,
+     * `title_changed`, `dom_hash_changed`, `frame_tree_changed`.
+     * Returns `[]` when either snapshot is null.
+     */
+    computeStateDelta(pre, post) {
+        if (!pre || !post)
+            return [];
+        return computeEvidence(pre, post);
+    }
+    /** Public for tests + ElementLease text-hash construction in Phase 2. */
+    normalizeUrl(raw) {
+        return normalizeUrl(raw);
+    }
+    /** Public for tests + ElementLease visible_text_hash construction. */
+    hashText(text) {
+        return sha256Hex(text.slice(0, SHORT_TEXT_HASH_CAP));
+    }
+}
+exports.BrowserState = BrowserState;
+// ── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Default factory. Constructs a BrowserState wired to the production
+ * playwrightBridge. One instance is shared across all browser tool
+ * wrappers in `tools/v4/browser/_observer.ts`.
+ */
+function createBrowserState() {
+    const bs = new BrowserState();
+    bs.setBridgeLoader(() => Promise.resolve().then(() => __importStar(require('../playwrightBridge'))));
+    return bs;
+}

package/dist/core/v4/checkpoint.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/checkpoint.ts — v4.2 Phase 4: Checkpoint data types +
+ * rollback helpers.
+ *
+ * Phase 4 is the first phase that MUTATES agent state. Phases 1-3
+ * recorded data and synthesised reports; Phase 4 lets the recovery
+ * controller restore conversation messages + TurnState internals to
+ * an earlier iteration when a tool loop is detected, so the model
+ * retries from a clean baseline instead of accumulating noise.
+ *
+ * Critical constraint: **rollback NEVER claims to undo executed
+ * side effects**. A file_write that already happened is still on
+ * disk — rollback only affects in-memory conversation state, not
+ * the world. Enforcement is structural via the
+ * `containedMutations` flag — iterations that ran any mutating
+ * tool (`ToolHandler.mutates === true`) are not eligible for
+ * rollback at all (HARD BLOCK per Q-CP3 approval).
+ *
+ * Storage is in-memory only, ring buffer of configurable depth
+ * (default 3). Disk-backed checkpoints are out of scope for v4.2 —
+ * adds I/O, crash-recovery complexity, and a serialization contract
+ * that the spike doesn't need.
+ *
+ * Provider cache safety: a restored message array is a strict
+ * prefix of the pre-rollback state. Anthropic prompt caching keys
+ * on the message prefix and handles prefix matches natively — no
+ * cache invalidation concern. OpenAI / Ollama / Groq don't use
+ * prefix caching at the wire level.
+ *
+ * Reference-system note: a comparable reference system has no
+ * checkpoint/restore primitive — only a counter-refund pattern that
+ * gives back iteration budget when a "cheap RPC" tool ran. Aiden's
+ * Phase 4 is genuinely new ground. No code patterns ported.
+ *
+ * Pure module — only types, frozen-data factories, and a
+ * deterministic message builder. No I/O, no async, no
+ * side effects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRollbackMessage = buildRollbackMessage;
+// ── Rollback message builder ───────────────────────────────────────────────
+/**
+ * Build the corrective system message inserted into history after a
+ * successful rollback. Includes:
+ *   - Which iteration we rolled back to
+ *   - The cooldown rationale (model needs to use different approach)
+ *   - When `blockedBy` is non-empty, an explicit acknowledgement that
+ *     those mutating tools' world effects CANNOT be undone (defensive
+ *     even though Q-CP3 hard-blocks rollback when any mutations ran —
+ *     leaves the door open for a Phase 5+ soft-rollback variant
+ *     without changing the message shape).
+ *
+ * Pure deterministic helper — same inputs always produce the same
+ * output. Public for tests.
+ */
+function buildRollbackMessage(input) {
+    const { iteration, toolName, blockedBy } = input;
+    const toolPart = toolName ? `\`${toolName}\`` : 'the looping tool';
+    const targetPart = iteration > 0
+        ? `to iteration ${iteration}`
+        : 'to the start of this turn';
+    const parts = [
+        `[tce] Rolled back ${targetPart} because ${toolPart} was failing repeatedly. ` +
+            `${toolPart === 'the looping tool' ? 'That tool' : `\`${toolName}\``} is now cooled down — ` +
+            `try a different approach with the tools that remain.`,
+    ];
+    if (blockedBy && blockedBy.length > 0) {
+        parts.push(`Note: ${blockedBy.join(', ')} ran during this turn and produced real-world ` +
+            `side effects that this rollback CANNOT undo. Those effects persist.`);
+    }
+    return parts.join(' ');
+}