@reticlehq/server 2.14.0 → 3.2.0

package/dist/tools/snapshot-delta.d.ts

@@ -1,92 +0,0 @@
-/**
- * Server-side snapshot delta — return only what CHANGED since the agent's last look.
- *
- * Why (grounded): screenshot/Playwright-MCP agents accrue 60–80K tokens of stale accessibility-tree
- * data over a session and start hallucinating selectors that no longer exist. The agent-facing cost
- * is the MCP result it reads (not the internal WS payload), so computing the delta here — and
- * returning only added/removed lines — directly cuts the tokens the model spends AND removes the
- * stale full-tree that drives hallucination. Reuses the same normalize+diff the baseline layer uses,
- * so "what changed" means the same thing everywhere.
- *
- * Pure decision (`snapshotDelta`) + a small route-invalidated cache (`SnapshotCache`). A route change
- * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
- * returns full — never a misleading cross-page delta.
- */
-/**
- * Pure: was the prior snapshot of this scope both RECENT and SMALLER than this one? If so, the
- * earlier reading was very likely taken mid-load — content arrived in the gap between the two calls
- * — and any presence-grade conclusion drawn from that earlier snapshot ("this route renders
- * nothing") is suspect. Silent otherwise: a stale prior or a page that shrank (or stayed the same
- * size) is not this trap.
- */
-export declare function snapshotGrowthNote(prior: {
-    tree: string;
-    atMs: number;
-} | undefined, nextTree: string, nowMs: number, windowMs?: number): string | undefined;
-export declare const SnapshotDeltaMode: {
-    readonly FULL: "full";
-    readonly DELTA: "delta";
-    readonly UNCHANGED: "unchanged";
-};
-export type SnapshotDeltaMode = (typeof SnapshotDeltaMode)[keyof typeof SnapshotDeltaMode];
-interface SnapshotDelta {
-    added: string[];
-    removed: string[];
-    changed: string[];
-    addedCount: number;
-    removedCount: number;
-}
-/** Where focus moved, when it moved. Absent fields mean nothing held focus on that side. */
-interface FocusChange {
-    from?: string;
-    to?: string;
-}
-type DeltaDecision = {
-    mode: typeof SnapshotDeltaMode.FULL;
-} | {
-    mode: typeof SnapshotDeltaMode.UNCHANGED;
-    focusChanged?: FocusChange;
-} | {
-    mode: typeof SnapshotDeltaMode.DELTA;
-    delta: SnapshotDelta;
-    focusChanged?: FocusChange;
-};
-/** Pure: decide full vs delta vs unchanged given the previous tree (same route) and the next tree. */
-export declare function snapshotDelta(prevTree: string | undefined, nextTree: string): DeltaDecision;
-/** Per-(session,scope,mode) last-snapshot cache. Route-aware: a route change invalidates the entry. */
-export declare class SnapshotCache {
-    #private;
-    constructor(max?: number, now?: () => number);
-    /** True when an entry exists for this key (regardless of route match). */
-    has(key: string): boolean;
-    /** The clock this cache was constructed with — callers compare against it so `remember`'s
-     * timestamp and a caller's "now" can never drift onto two different clocks. */
-    now(): number;
-    /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
-    recall(key: string, route: string): string | undefined;
-    /**
-     * The last remembered tree for this key AND when it was remembered, IF the route still matches.
-     * Same route-gating as `recall` — a route change makes the prior entry meaningless for comparison,
-     * not just for diffing.
-     */
-    priorEntry(key: string, route: string): {
-        tree: string;
-        atMs: number;
-    } | undefined;
-    remember(key: string, route: string, tree: string): void;
-}
-export declare function snapshotCacheKey(sessionId: string, scope: string, mode: string): string;
-interface SnapshotDeltaOpts {
-    sessionId: string;
-    scope: string;
-    mode: string;
-    diff: boolean;
-}
-/**
- * Shape a raw snapshot result for the agent: when `diff` is requested and a same-route prior
- * snapshot exists, return only the delta (or `unchanged`) instead of the full tree. Always updates
- * the cache. Non-object/errorless results pass through. The cache is the only state; the decision is
- * the pure `snapshotDelta`.
- */
-export declare function applySnapshotDelta(raw: unknown, opts: SnapshotDeltaOpts, cache: SnapshotCache): unknown;
-export {};

package/dist/tools/snapshot-delta.js

@@ -1,356 +0,0 @@
-/**
- * Server-side snapshot delta — return only what CHANGED since the agent's last look.
- *
- * Why (grounded): screenshot/Playwright-MCP agents accrue 60–80K tokens of stale accessibility-tree
- * data over a session and start hallucinating selectors that no longer exist. The agent-facing cost
- * is the MCP result it reads (not the internal WS payload), so computing the delta here — and
- * returning only added/removed lines — directly cuts the tokens the model spends AND removes the
- * stale full-tree that drives hallucination. Reuses the same normalize+diff the baseline layer uses,
- * so "what changed" means the same thing everywhere.
- *
- * Pure decision (`snapshotDelta`) + a small route-invalidated cache (`SnapshotCache`). A route change
- * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
- * returns full — never a misleading cross-page delta.
- */
-/**
- * Identity for comparison, ref for action.
- *
- * The delta path used `normalizeLines` from the baseline layer, which strips the ref marker on
- * purpose — a ref stored in a baseline would make every later diff noisy. Correct there, wrong here:
- * every delta line came back as `- button "Row actions"` with no ref, and acting needs a ref, so the
- * full snapshot had to be taken anyway. The diff call cost tokens and bought nothing. One helper, two
- * callers, opposite requirements — so this path keeps the ref-stripped line as the KEY and emits the
- * ORIGINAL line with its ref.
- *
- * Focus is stripped from the key too. It rides in the line as `[focused]`, alone or comma-joined with
- * other states, so a focus move used to surface as one line removed and its twin added — structural
- * change reported where nothing had been added at all. Focus is a property OF a line, so it gets its
- * own field. Only focus is exempt: `disabled` moving is a real change and must still show.
- */
-/** The ref marker, as `formatLine` writes it. Bounded quantifier: `\s*` backtracks polynomially. */
-const REF_MARKER = /\s?\(ref=e\d+\)/;
-/** The state bracket — ` [disabled,checked,expanded,focused]` — and the one state that is not structural. */
-const STATE_BRACKET = /\s\[([a-z,]+)\]$/;
-const FOCUSED_STATE = 'focused';
-/** True when this line carries focus. */
-function isFocused(line) {
-    return true === STATE_BRACKET.exec(line)?.[1]?.split(',').includes(FOCUSED_STATE);
-}
-/** The same line with focus removed — and the bracket dropped when focus was all it held. */
-function withoutFocus(line) {
-    const match = STATE_BRACKET.exec(line);
-    const states = match?.[1];
-    if (null === match || undefined === match || undefined === states)
-        return line;
-    const rest = states.split(',').filter((s) => s !== FOCUSED_STATE);
-    const head = line.slice(0, match.index);
-    return 0 === rest.length ? head : `${head} [${rest.join(',')}]`;
-}
-/** What makes two lines "the same element" for diffing: no ref, no focus, no surrounding space. */
-function deltaKey(line) {
-    return withoutFocus(line.replace(REF_MARKER, '')).trim();
-}
-function deltaLines(tree) {
-    return tree
-        .split('\n')
-        .map((line) => ({ key: deltaKey(line), text: withoutFocus(line).trim() }))
-        .filter((line) => line.key.length > 0);
-}
-/**
- * Multiset diff on the key, emitting the original text.
- *
- * Multiset rather than set because duplicate labels are the norm — twelve identical `Row actions`
- * buttons — and the count is the only thing that says how many left. Emitting the ORIGINAL text is
- * what finally tells them apart: with refs, "which twelve" has an answer.
- */
-/** Extract the ref marker value from a text line, or undefined if absent. */
-function refOf(text) {
-    return REF_MARKER.exec(text)?.[0]?.trim();
-}
-/** Extract the role (first word after the bullet) from a snapshot line — the structural type that must match. */
-function roleOf(text) {
-    return (text
-        .trimStart()
-        .replace(/^-\s*/, '')
-        .split(/[\s"(]/)[0] ?? '');
-}
-function diffKeyed(prev, next) {
-    const bucket = (lines) => {
-        const map = new Map();
-        for (const line of lines) {
-            const existing = map.get(line.key);
-            if (existing === undefined)
-                map.set(line.key, [line.text]);
-            else
-                existing.push(line.text);
-        }
-        return map;
-    };
-    const before = bucket(prev);
-    const after = bucket(next);
-    const removed = [];
-    const added = [];
-    for (const key of new Set([...before.keys(), ...after.keys()])) {
-        const was = before.get(key) ?? [];
-        const now = after.get(key) ?? [];
-        // Pair the SAME REF first. Twelve identical `Row actions` buttons are one key, and the ref is the
-        // only thing that says which of them left — an end-of-list surplus would name an arbitrary one.
-        const survived = new Set(now);
-        const wentOrChanged = was.filter((text) => !survived.has(text));
-        const arrivedOrChanged = now.filter((text) => !new Set(was).has(text));
-        // Whatever is left over on both sides is the SAME element with a re-minted ref (a re-render, or a
-        // navigation that restarts the sequence). Pairing those off is what stops a ref change reading as
-        // a removal plus an addition; only the count difference is a real structural change.
-        const paired = Math.min(wentOrChanged.length, arrivedOrChanged.length);
-        removed.push(...wentOrChanged.slice(paired));
-        added.push(...arrivedOrChanged.slice(paired));
-    }
-    return { removed, added };
-}
-/**
- * Same ref AND same role in both added and removed = value change, not a structural
- * arrival/departure. Refs alone are not stable identities — they are re-minted on re-render — so a
- * removed button and an added textbox sharing a ref must stay in their respective lists.
- */
-function extractChanged(added, removed) {
-    const addedByRef = new Map();
-    for (const [i, text] of added.entries()) {
-        const ref = refOf(text);
-        if (ref !== undefined)
-            addedByRef.set(ref, { idx: i, text, role: roleOf(text) });
-    }
-    const changedIndicesInAdded = new Set();
-    const changedIndicesInRemoved = new Set();
-    const changed = [];
-    for (const [i, text] of removed.entries()) {
-        const ref = refOf(text);
-        if (ref === undefined)
-            continue;
-        const match = addedByRef.get(ref);
-        if (match !== undefined && match.role === roleOf(text)) {
-            changed.push(match.text);
-            changedIndicesInAdded.add(match.idx);
-            changedIndicesInRemoved.add(i);
-            addedByRef.delete(ref);
-        }
-    }
-    return {
-        added: added.filter((_, i) => !changedIndicesInAdded.has(i)),
-        removed: removed.filter((_, i) => !changedIndicesInRemoved.has(i)),
-        changed,
-    };
-}
-/**
- * Where focus sits now: the line to show, plus the identity to compare it BY.
- *
- * These have to be two different things. Comparing the rendered lines said focus had moved whenever
- * the focused element merely changed — typing into a focused textbox rewrites its `[value=...]`, so
- * `from` and `to` came back naming the same element with different text. Focus identity is the
- * ELEMENT, so the comparison is on the ref, and the line is only what gets displayed. Where there is
- * no ref to compare (a non-interactive line), the ref-stripped key stands in.
- *
- * Read from the raw tree so a line the diff filters out cannot silently swallow the focus report.
- */
-function focusedLine(tree) {
-    const focused = tree.split('\n').find((line) => isFocused(line));
-    if (focused === undefined)
-        return undefined;
-    const text = withoutFocus(focused).trim();
-    return { id: REF_MARKER.exec(focused)?.[0]?.trim() ?? deltaKey(focused), text };
-}
-/**
- * How recent a smaller prior snapshot has to be for its growth to be worth flagging (#787) — long
- * enough to catch the "route committed, then hydrated" window the bug report describes (hundreds of
- * ms up to a couple of seconds), short enough that an unrelated LATER snapshot of a page that simply
- * grew through normal use (an infinite-scroll load, a live feed) doesn't get blamed on load timing.
- */
-const GROWTH_NOTE_WINDOW_MS = 5000;
-/** Non-empty lines only — a blank line in the tree text is formatting, not a node. */
-function nodeCount(tree) {
-    return tree.split('\n').filter((line) => '' !== line.trim()).length;
-}
-/**
- * Pure: was the prior snapshot of this scope both RECENT and SMALLER than this one? If so, the
- * earlier reading was very likely taken mid-load — content arrived in the gap between the two calls
- * — and any presence-grade conclusion drawn from that earlier snapshot ("this route renders
- * nothing") is suspect. Silent otherwise: a stale prior or a page that shrank (or stayed the same
- * size) is not this trap.
- */
-export function snapshotGrowthNote(prior, nextTree, nowMs, windowMs = GROWTH_NOTE_WINDOW_MS) {
-    if (prior === undefined)
-        return undefined;
-    const elapsedMs = nowMs - prior.atMs;
-    if (elapsedMs < 0 || elapsedMs > windowMs)
-        return undefined;
-    const priorCount = nodeCount(prior.tree);
-    const nextCount = nodeCount(nextTree);
-    if (nextCount <= priorCount)
-        return undefined;
-    return (`this scope had ${String(priorCount)} nodes ${String(elapsedMs)}ms ago and has ${String(nextCount)} now — ` +
-        'content likely arrived after your last look; a presence conclusion drawn from that earlier snapshot may have been taken mid-load');
-}
-export const SnapshotDeltaMode = {
-    FULL: 'full',
-    DELTA: 'delta',
-    UNCHANGED: 'unchanged',
-};
-/** Pure: decide full vs delta vs unchanged given the previous tree (same route) and the next tree. */
-export function snapshotDelta(prevTree, nextTree) {
-    if (prevTree === undefined)
-        return { mode: SnapshotDeltaMode.FULL };
-    const raw = diffKeyed(deltaLines(prevTree), deltaLines(nextTree));
-    const { added, removed, changed } = extractChanged(raw.added, raw.removed);
-    const before = focusedLine(prevTree);
-    const now = focusedLine(nextTree);
-    // Reported only on a MOVE. Repeating "focus is still here" every turn is the noise the delta exists
-    // to remove, and an absent field is how the agent knows nothing happened.
-    const focusChanged = before?.id === now?.id
-        ? undefined
-        : {
-            ...(before === undefined ? {} : { from: before.text }),
-            ...(now === undefined ? {} : { to: now.text }),
-        };
-    const moved = focusChanged === undefined ? {} : { focusChanged };
-    if (0 === added.length && 0 === removed.length && 0 === changed.length) {
-        return { mode: SnapshotDeltaMode.UNCHANGED, ...moved };
-    }
-    return {
-        mode: SnapshotDeltaMode.DELTA,
-        delta: {
-            added,
-            removed,
-            changed,
-            addedCount: added.length,
-            removedCount: removed.length,
-        },
-        ...moved,
-    };
-}
-const DEFAULT_MAX_ENTRIES = 50;
-/** Per-(session,scope,mode) last-snapshot cache. Route-aware: a route change invalidates the entry. */
-export class SnapshotCache {
-    #map = new Map();
-    #max;
-    #now;
-    constructor(max = DEFAULT_MAX_ENTRIES, now = Date.now) {
-        this.#max = max;
-        this.#now = now;
-    }
-    /** True when an entry exists for this key (regardless of route match). */
-    has(key) {
-        return this.#map.has(key);
-    }
-    /** The clock this cache was constructed with — callers compare against it so `remember`'s
-     * timestamp and a caller's "now" can never drift onto two different clocks. */
-    now() {
-        return this.#now();
-    }
-    /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
-    recall(key, route) {
-        return this.priorEntry(key, route)?.tree;
-    }
-    /**
-     * The last remembered tree for this key AND when it was remembered, IF the route still matches.
-     * Same route-gating as `recall` — a route change makes the prior entry meaningless for comparison,
-     * not just for diffing.
-     */
-    priorEntry(key, route) {
-        const entry = this.#map.get(key);
-        if (entry === undefined || entry.route !== route)
-            return undefined;
-        // LRU touch: re-insert so a HOT key isn't evicted while colder, more-recently-added keys survive
-        // (Map preserves insertion order; delete+set moves it to the most-recently-used end).
-        this.#map.delete(key);
-        this.#map.set(key, entry);
-        return { tree: entry.tree, atMs: entry.atMs };
-    }
-    remember(key, route, tree) {
-        // Re-insert to move the key to the most-recently-used end (a plain set keeps its old position).
-        this.#map.delete(key);
-        if (this.#map.size >= this.#max) {
-            const oldest = this.#map.keys().next().value;
-            if (oldest !== undefined)
-                this.#map.delete(oldest);
-        }
-        this.#map.set(key, { route, tree, atMs: this.#now() });
-    }
-}
-/**
- * Joins the cache-key parts. NUL because `scope` is a caller-supplied selector that may contain any
- * printable character — a printable separator could be forged into a colliding key. Written as an
- * ESCAPE, never as a literal NUL byte: a raw one makes this file read as binary to grep/diff tooling,
- * which silently hid every symbol in it from repo-wide searches.
- */
-const CACHE_KEY_SEPARATOR = '\u0000';
-export function snapshotCacheKey(sessionId, scope, mode) {
-    return `${sessionId}${CACHE_KEY_SEPARATOR}${scope}${CACHE_KEY_SEPARATOR}${mode}`;
-}
-/** Said out loud when a diff was computed over a capped tree, so "unchanged" cannot mean "nothing happened". */
-const CAPPED_DIFF_NOTE = 'this diff covers only the first N nodes of the page (the snapshot hit its cap), so "unchanged" means "unchanged in the part that was captured" — narrow with `scope` to see the rest';
-/**
- * Shape a raw snapshot result for the agent: when `diff` is requested and a same-route prior
- * snapshot exists, return only the delta (or `unchanged`) instead of the full tree. Always updates
- * the cache. Non-object/errorless results pass through. The cache is the only state; the decision is
- * the pure `snapshotDelta`.
- */
-export function applySnapshotDelta(raw, opts, cache) {
-    if (typeof raw !== 'object' || null === raw)
-        return raw;
-    const r = raw;
-    // Only shape genuine snapshots (have a string tree). An error envelope passes through untouched.
-    if (typeof r['tree'] !== 'string')
-        return raw;
-    const tree = r['tree'];
-    const status = 'object' === typeof r['status'] && r['status'] !== null
-        ? r['status']
-        : {};
-    const route = 'string' === typeof status['route'] ? status['route'] : '';
-    const key = snapshotCacheKey(opts.sessionId, opts.scope, opts.mode);
-    // Read the growth signal BEFORE remember() overwrites the entry it compares against — needed on
-    // both branches below (#787), not only the diff:true path, since the reporter's own repro used a
-    // plain snapshot the second time.
-    const priorEntry = cache.priorEntry(key, route);
-    const growthNote = snapshotGrowthNote(priorEntry, tree, cache.now());
-    const growth = growthNote === undefined ? {} : { growthWarning: growthNote };
-    if (!opts.diff) {
-        cache.remember(key, route, tree);
-        return { ...r, ...growth };
-    }
-    const prev = priorEntry?.tree;
-    const hadEntry = cache.has(key);
-    cache.remember(key, route, tree);
-    const decision = snapshotDelta(prev, tree);
-    if (decision.mode === SnapshotDeltaMode.FULL) {
-        const reason = hadEntry ? 'route changed' : 'first snapshot for this route';
-        return { ...r, mode: SnapshotDeltaMode.FULL, reason, ...growth };
-    }
-    // The walk stops at a node cap and returns a DOCUMENT-ORDER PREFIX, so two capped snapshots of a
-    // large page are identical whenever the change happened past the cap — and "unchanged" is then a
-    // statement about the cap, not about the page. Carried through on both branches: a delta computed
-    // over a prefix is real but not exhaustive either.
-    const capped = true === r['truncated'] ? { truncated: true, note: CAPPED_DIFF_NOTE } : {};
-    // Spread onto BOTH branches. A value computed correctly and declared nowhere on the way out is the
-    // defect shape that hit this release five separate times: nothing throws, no test reddens, the
-    // field is simply absent forever.
-    const moved = decision.focusChanged === undefined ? {} : { focusChanged: decision.focusChanged };
-    if (decision.mode === SnapshotDeltaMode.UNCHANGED) {
-        return {
-            mode: SnapshotDeltaMode.UNCHANGED,
-            status: r['status'],
-            ...moved,
-            ...capped,
-            ...growth,
-        };
-    }
-    const { changed, ...structuralDelta } = decision.delta;
-    const changedField = changed.length > 0 ? { changed, changedCount: changed.length } : {};
-    return {
-        mode: SnapshotDeltaMode.DELTA,
-        delta: structuralDelta,
-        ...changedField,
-        status: r['status'],
-        ...moved,
-        ...capped,
-        ...growth,
-    };
-}

package/dist/tools/tool-kit.d.ts

@@ -1,221 +0,0 @@
-/**
- * Shared kit for the MCP tool modules — the tool shape, the dependency bag, the common
- * session-id arg, and the two helpers (commandOrThrow, snapshotTree) every tool group needs. Lives
- * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
- * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
- */
-import { z } from 'zod';
-import { ReticleCommand } from '@reticlehq/core';
-import type { SessionManager } from '../session/session.js';
-import type { RealInputProvider } from '../input/real-input.js';
-import type { BaselineStore } from '../project/baselines.js';
-import type { RecordingStore } from '../flows/recordings.js';
-import type { FileSystemPort } from '../project/fs-port.js';
-import type { ArtifactRoot } from '../project/artifact-root.js';
-import type { FlowStore } from '../flows/flows.js';
-import type { ProjectStore } from '../project/project-store.js';
-import type { AnnotationStore } from '../flows/annotation-store.js';
-import type { BrowserPool } from '../pool/browser-pool.js';
-import type { ChromiumProbe } from '../cli/chromium-hint.js';
-export interface ToolDeps<Ext = unknown> {
-    sessions: SessionManager;
-    /** shared one-browser/N-context pool for headless leases. undefined ⇒ lease tools report unavailable. */
-    pool?: BrowserPool;
-    /**
-     * Probe for a launchable Chromium, so the lease path can refuse at the FIRST call with the install
-     * fix rather than failing several calls in with a message that reads as "the app is not running".
-     * Optional: absent ⇒ no preflight — every existing test construction of ToolDeps keeps working, and
-     * the fake-pool lease tests are deliberately runnable without a real Chromium.
-     */
-    browserProbe?: () => Promise<ChromiumProbe>;
-    baselines: BaselineStore;
-    recordings: RecordingStore;
-    /** on-disk anchored-flow store (.reticle/flows/). */
-    flows: FlowStore;
-    /** structured annotations accumulating for the live recording. */
-    annotations: AnnotationStore;
-    /** cross-run outcome memory (.reticle/project.json). */
-    project: ProjectStore;
-    /** optional native-input provider. undefined ⇒ everything stays synthetic. */
-    realInput?: RealInputProvider;
-    /** injected filesystem seam (tests pass a fake/temp-dir adapter). */
-    fs: FileSystemPort;
-    /** absolute.reticle path (index.ts computes cwd/.reticle). The FALLBACK, not the answer. */
-    reticleRoot: string;
-    /**
-     * Which `.reticle` a SESSION's artifacts belong in, resolved per call.
-     *
-     * `reticleRoot` above is fixed at construction from the daemon's own `process.cwd()`, which is a
-     * statement about where the daemon was launched and was being read as a statement about which
-     * project is being verified. Those are usually not the same tree: an editor starts a user-scoped
-     * MCP server wherever it likes, so flows landed outside the repo they verify, or died on
-     * `mkdir '/.reticle'`.
-     *
-     * Optional because every existing construction of ToolDeps predates it and because a consumer
-     * embedding this engine may not have a filesystem to search. Absent ⇒ `reticleRoot`, which is
-     * exactly today's behaviour.
-     */
-    artifactRootFor?: (projectId: string | undefined) => ArtifactRoot;
-    /**
-     * A verification run just landed — wake cloud sync instead of waiting for its next tick.
-     *
-     * The run itself is pushed immediately on this path, but everything AROUND it — the impact
-     * counters, the flows it exercised, flake and intent — moves only on the timer. That is what
-     * produced a dashboard showing a fresh run beside stale numbers, which reads as a sync bug and is
-     * really just two different clocks. Waking the loop here makes the run and its context arrive
-     * together.
-     *
-     * Optional: absent ⇒ the timer alone, which is exactly today's behaviour.
-     */
-    onRunPersisted?: () => void;
-    /**
-     * This daemon's OWN project id, derived from the directory it was started in.
-     *
-     * Optional because a daemon above an uninitialised directory has none, and because every existing
-     * test construction of ToolDeps predates it. Absence means "cannot tell", which must never be
-     * treated as a mismatch.
-     */
-    projectId?: string;
-    /** injected clock for the contract's generatedAt stamp. */
-    now: () => number;
-    /**
-     * The port this daemon's bridge listens on.
-     *
-     * Needed wherever a message has to name the OTHER half of a port mismatch — the commonest reason
-     * a leased tab loads the app and never dials in. Optional so every existing test construction of
-     * ToolDeps keeps working; absent falls back to the default port.
-     */
-    bridgePort?: number;
-    /**
-     * A consumer's OWN dependencies, carried through untouched.
-     *
-     * Nothing in this package reads it. It exists so a consumer embedding the engine can add tools of
-     * its own — answering out of a store this package has never heard of — without either widening the
-     * fields above with a stranger's vocabulary or forking to get a handle through.
-     *
-     * The type parameter, rather than `unknown`, is what keeps the seam typed: a consumer writes
-     * `ToolDef<TheirExt>` once and their handlers see their own type. Casting out of `unknown` in every
-     * handler is how a typed seam quietly becomes an untyped one.
-     *
-     * Optional, and defaulted to `unknown`, so every existing construction of this bag — and every test
-     * that builds one — is unchanged.
-     */
-    ext?: Ext;
-}
-export interface ToolDef<Ext = unknown> {
-    name: string;
-    description: string;
-    inputSchema: z.ZodRawShape;
-    /**
-     * JSON Schema-compatible output schema for this tool. When present, the MCP server advertises it
-     * in the tools/list response so schema-aware clients (like @reticlehq/cli) can validate outputs and
-     * compose tool calls safely. Also drives TOON encoding for snapshot/query results.
-     */
-    outputSchema?: z.ZodRawShape;
-    /**
-     * One concrete, valid call — the shape, not the prose.
-     *
-     * A schema tells an agent the FIELD NAMES; it does not tell it how they compose, and under a lean
-     * profile only the first sentence of the description survives. So an agent reads "execute one
-     * action against a ref", sees `ref` / `action` / `args`, and guesses `{ action, testid }`. The
-     * guess fails inside the MCP SDK's own validation — BEFORE this package's error handling runs — so
-     * what comes back is a raw zod dump: the validator's internal state, naming no field and showing
-     * no correct shape. Two of those round trips cost more than the lean snapshot saves, which means
-     * arg-guessing quietly refunds the entire token advantage.
-     *
-     * Rendered into the advertised description, so it survives the terse profiles where it matters
-     * most. `tool-examples.test.ts` parses every one of these against its OWN inputSchema, because an
-     * example that does not validate is worse than none at all.
-     */
-    example?: Record<string, unknown>;
-    /**
-     * Declared method-style, not as a property, and that is load-bearing rather than stylistic.
-     *
-     * Under `strictFunctionTypes` a property holding a function has CONTRAVARIANT parameters, so
-     * `ToolDef<TheirExt>` and `ToolDef<unknown>` become mutually unassignable and a consumer composing
-     * `[...TOOLS, ...theirTools]` needs a cast — as does every internal helper that then touches the
-     * array. Method-style parameters are checked bivariantly, which collapses all of that.
-     *
-     * The unsoundness bivariance admits is that a handler written against `ToolDeps<TheirExt>` could be
-     * handed a bag carrying no `ext` at all. That costs nothing here, because `ext` is optional by
-     * design: any handler reading it already has to survive `undefined`.
-     */
-    handler(deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
-}
-/**
- * The optional inline intent, on every tool that draws a verdict.
- *
- * One field, carrying either prose or the id of an intent already declared, because the surface is
- * the scarce thing and a second field for the reference case would double the cost of the idea to
- * make one of its two uses marginally more explicit. Told apart by the ledger — see
- * `intent/inline-intent.ts`.
- *
- * The first sentence is what a lean surface advertises, so it carries both readings; the rest is for
- * the profiles that send the whole description.
- */
-export declare const intentArg: z.ZodOptional<z.ZodString>;
-export declare const sessionIdShape: {
-    sessionId: z.ZodOptional<z.ZodString>;
-};
-/**
- * Every key `runTool` splices onto a session-bound result, as a closed list.
- *
- * These are wire strings and were inlined at the splice sites, which is exactly how four of them
- * came to be spliced and never declared. `sessionEnvelopeShape` is derived from this object and
- * `envelope-keys-declared.test.ts` fails if a member is missing from it, so the two cannot drift.
- *
- * Each of these is a channel that exists BECAUSE the agent had no other way to learn the fact.
- * Undeclared, a schema-strict client validating `structuredContent` drops it, and the channel is
- * indistinguishable from never having been built.
- */
-export declare const EnvelopeKey: {
-    /** Session health — which tab, how fresh. */
-    readonly SESSION: "session";
-    /** One-shot pool-lease reminder. */
-    readonly SESSION_LEASE: "session_lease";
-    /** One-shot "these sessions are old, clean them up". */
-    readonly SESSION_AGE_WARNING: "session_age_warning";
-    /** The delivered-once human-in-the-loop guidance envelope. Losing it is a safety failure. */
-    readonly CONTROL: "control";
-    /**
-     * Rides alongside `session` whenever the tab is THROTTLED. It was declared on `reticle_act`'s
-     * schema and nowhere else, so on a validating profile every other session-bound tool silently
-     * dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
-     */
-    readonly WARNING: "warning";
-    /** One-shot "ask the human how this went". */
-    readonly FEEDBACK_PROMPT: "feedback_prompt";
-    /** One-shot "a newer Reticle exists". */
-    readonly UPDATE_AVAILABLE: "update_available";
-    /**
-     * "You have driven this page N times without asking for a verdict."
-     *
-     * The largest known lever on the metric this product is judged by: verdict-less sessions
-     * overwhelmingly never call a verdict-producing tool at all. It was spliced undeclared, so on a
-     * validating client the nudge was built, fired, and thrown away before any agent saw it.
-     */
-    readonly VERIFY_NEXT: "verify_next";
-    /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
-    readonly FEEDBACK_INVITE: "feedback_invite";
-    /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
-    readonly VERSION_SKEW: "version_skew";
-    /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
-    readonly FEEDBACK_UNDELIVERED: "feedback_undelivered";
-};
-export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
-/**
- * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
- * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
- * validation) keeps them instead of silently dropping them.
- *
- * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
- * whole release, and every key that went missing was a channel nobody could see was missing.
- */
-export declare const sessionEnvelopeShape: z.ZodRawShape;
-/** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
-export declare function commandOrThrow(deps: ToolDeps, sessionId: string | undefined, name: ReticleCommand, args: Record<string, unknown>): Promise<unknown>;
-/** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */
-export declare function snapshotTree(deps: ToolDeps, sessionId: string | undefined): Promise<{
-    lines: string[];
-    route: string;
-}>;