@descryy/mcp 0.5.0 → 0.7.0

package/dist/browser/registry.d.ts

@@ -1,85 +1,27 @@
-/**
- * Live browser sessions belonging to one connection — `mcp-browser-tools.md`
- * §4.
- *
- * ## Why this is the hard part
- *
- * Every other tool on this surface is one-shot. It opens what it needs,
- * answers, and holds nothing; a crash in the middle costs the caller one
- * reply. A browser process that outlives a call is a different shape
- * entirely, and the failure it introduces is not "a call fails" but "a
- * process is still running on the developer's machine an hour after the
- * agent stopped caring about it".
- *
- * So the design rule here is that **there is no path on which a session stops
- * being tracked without its browser being closed and its evidence being
- * handed back**. Four paths reach that state — idle timeout, client
- * disconnect, crash, explicit close — and they converge on one private
- * function, `reap`, rather than each doing their own teardown. They were four
- * separate implementations in the first draft and the evidence flush was
- * correct on three of them.
- *
- * ## Evidence is held, not dropped, and not silently discarded either
- *
- * A timeout or a disconnect has no reply to attach evidence to. Discarding it
- * would be the failure rule 7 names — silently doing less — so a reaped
- * session leaves a `ReapedSession` record behind carrying the reason and the
- * final flush, and the next caller who names that id receives it instead of a
- * bare "unknown session". That record is what turns "your session vanished"
- * into "your session was idle for five minutes; here is what it saw before it
- * went".
- *
- * ## Per connection, never global
- *
- * A registry is created per `Session`, which is created per connection. A
- * global one would let a second client `use` a first client's browser by
- * guessing a uuid, and would make the disconnect reap ambiguous about whose
- * sessions it was reaping.
- */
+/** Live browser sessions belonging to one connection — `mcp-browser-tools.md` §4. Four
+ *  teardown paths (idle timeout, disconnect, crash, close) converge on one `reap` so a
+ *  session never stops being tracked without its browser closing and evidence being
+ *  flushed (kept, never dropped — rule 7). Per-connection, never global — a global
+ *  registry would let one client guess another's browser by session id. */
 import type { BrowserDriver, BrowserLaunchOptions, BrowserObservation, BrowserPageSession, ChromiumRefusal } from "./driver.ts";
-/**
- * How long a session may go untouched before it is torn down.
- *
- * A starting value, not a measurement, in this repo's usual sense: no agent
- * has yet been observed pausing mid-exploration, so there is nothing to fit
- * it to. Five minutes is long enough to survive a model thinking, short
- * enough that a forgotten browser is a five-minute leak rather than an
- * overnight one. It is deliberately the same figure as the action handshake's
- * token TTL — an agent that cannot decide within one is unlikely to be coming
- * back for the other.
- */
+/** How long a session may go untouched before torn down. Starting value, not a
+ *  measurement — 5 min balances agent-thinking time against leak size; matches the
+ *  action handshake's token TTL deliberately. */
 export declare const BROWSER_IDLE_TIMEOUT_MS: number;
-/**
- * How many sessions one connection may hold open at once.
- *
- * Small on purpose. A calling agent driving more than a couple of browsers
- * simultaneously is not doing something this surface was built for, and each
- * one is a real Chromium. Three leaves room for the honest case — a
- * comparison between two states, plus one being opened — without letting a
- * loop with a missing `browser_close_session` fill the machine.
- */
+/** Max sessions per connection. Small on purpose — each is a real Chromium process;
+ *  3 leaves room for comparing two states plus one opening, without a loop with a
+ *  missing `browser_close_session` filling the machine. */
 export declare const MAX_BROWSER_SESSIONS = 3;
 export type ReapReason = "idleTimeout" | "clientDisconnect" | "crashed" | "closed";
-/**
- * DEC-270's vocabulary, read here and defined nowhere near here.
- *
- * A browser session's safety level is the environment profile's — the same
- * field `observe_runtime` already reads. Declaring a second, browser-only
- * notion of "safe" is how a runtime run and a browser run end up disagreeing
- * about the same environment, which is the failure item 27 exists to prevent.
- * Null means no profile was supplied, in which case the session's consent is
- * the only authorization and it governs alone.
- */
+/** DEC-270's vocabulary. Reuses `observe_runtime`'s environment-profile field rather
+ *  than a browser-only notion of "safe" (item 27: two definitions could disagree).
+ *  Null means no profile — session consent alone governs. */
 export type BrowserSafetyLevel = "readOnly" | "write" | "destructiveWithApproval";
 export interface BrowserSessionEntry {
     readonly sessionId: string;
-    /**
-     * The run id every R4 edge this session witnesses is stamped with.
-     *
-     * One per session, not one per call: an edge's `observedByRun` answers
-     * "which run saw this", and a run that changed identity between a click and
-     * the request it caused would make that answer meaningless.
-     */
+    /** Run id every R4 edge this session witnesses is stamped with. One per session, not
+     *  per call — a run changing identity between a click and the request it caused would
+     *  make `observedByRun` meaningless. */
     readonly runId: string;
     readonly page: BrowserPageSession;
     /** The profile this session was opened under, or null when none was declared. */
@@ -87,14 +29,9 @@ export interface BrowserSessionEntry {
         readonly name: string;
         readonly safetyLevel: BrowserSafetyLevel;
     } | null;
-    /**
-     * The origin `browser_start_session` was consented for.
-     *
-     * Recorded at open time rather than read from the page later: the consent
-     * ruling binds the grant to the origin the developer approved, and a page
-     * that has since navigated is exactly the case where re-deriving it would
-     * launder a cross-origin move into an approved one.
-     */
+    /** Origin `browser_start_session` was consented for, recorded at open time — a page
+     *  that navigated since would let re-deriving it launder a cross-origin move into an
+     *  approved one. */
     readonly consentedOrigin: string;
     readonly openedAt: number;
     readonly lastUsedAt: number;
@@ -140,35 +77,18 @@ export interface BrowserSessionRegistryOptions {
     readonly now?: () => number;
     readonly maxSessions?: number;
     readonly idleTimeoutMs?: number;
-    /**
-     * Whether to run the background idle sweep.
-     *
-     * True in production: a session that goes idle because the agent wandered
-     * off is precisely the session that will never trigger a lazy sweep, so the
-     * timeout cannot be enforced only on the next call. The timer is `unref`'d,
-     * so it never holds the process open by itself.
-     *
-     * False in tests, which drive `sweepIdle()` against an injected clock —
-     * a real timer would make the idle assertions take real minutes.
-     */
+    /** Runs the background idle sweep. True in production — an idle session needs a
+     *  timer since it will never trigger a lazy sweep on its own; timer is `unref`'d.
+     *  False in tests, which drive `sweepIdle()` against an injected clock. */
     readonly startSweeper?: boolean;
 }
 export interface BrowserSessionRegistry {
     readonly idleTimeoutMs: number;
     readonly maxSessions: number;
     open(driver: BrowserDriver, options: BrowserOpenOptions): Promise<OpenResult>;
-    /**
-     * Look a session up for use, touching its idle clock. Detects a crash
-     * before handing anything back.
-     *
-     * Asynchronous because the crash path is not a lookup — it is a teardown.
-     * A synchronous `use` would have to either drop the dead page's final
-     * evidence or pretend to have collected it, and the first draft of this
-     * file did the second: it returned a record it then filled in from a
-     * floating promise, so the flush landed after the caller had already read
-     * the record. Awaiting the reap here is what makes "a crash flushes what
-     * preceded it" true rather than nearly true.
-     */
+    /** Looks up a session, touching its idle clock; detects a crash before returning.
+     *  Async because the crash path is a teardown, not a lookup — a sync version would
+     *  drop the dead page's evidence or (as the first draft did) flush it too late. */
     use(sessionId: string): Promise<UseResult>;
     close(sessionId: string): Promise<BrowserObservation>;
     sweepIdle(): Promise<readonly ReapedSession[]>;

package/dist/browser/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/browser/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/browser/registry.ts"],"names":[],"mappings":"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"}

package/dist/browser/registry.js

@@ -1,63 +1,16 @@
-/**
- * Live browser sessions belonging to one connection — `mcp-browser-tools.md`
- * §4.
- *
- * ## Why this is the hard part
- *
- * Every other tool on this surface is one-shot. It opens what it needs,
- * answers, and holds nothing; a crash in the middle costs the caller one
- * reply. A browser process that outlives a call is a different shape
- * entirely, and the failure it introduces is not "a call fails" but "a
- * process is still running on the developer's machine an hour after the
- * agent stopped caring about it".
- *
- * So the design rule here is that **there is no path on which a session stops
- * being tracked without its browser being closed and its evidence being
- * handed back**. Four paths reach that state — idle timeout, client
- * disconnect, crash, explicit close — and they converge on one private
- * function, `reap`, rather than each doing their own teardown. They were four
- * separate implementations in the first draft and the evidence flush was
- * correct on three of them.
- *
- * ## Evidence is held, not dropped, and not silently discarded either
- *
- * A timeout or a disconnect has no reply to attach evidence to. Discarding it
- * would be the failure rule 7 names — silently doing less — so a reaped
- * session leaves a `ReapedSession` record behind carrying the reason and the
- * final flush, and the next caller who names that id receives it instead of a
- * bare "unknown session". That record is what turns "your session vanished"
- * into "your session was idle for five minutes; here is what it saw before it
- * went".
- *
- * ## Per connection, never global
- *
- * A registry is created per `Session`, which is created per connection. A
- * global one would let a second client `use` a first client's browser by
- * guessing a uuid, and would make the disconnect reap ambiguous about whose
- * sessions it was reaping.
- */
+/** Live browser sessions belonging to one connection — `mcp-browser-tools.md` §4. Four
+ *  teardown paths (idle timeout, disconnect, crash, close) converge on one `reap` so a
+ *  session never stops being tracked without its browser closing and evidence being
+ *  flushed (kept, never dropped — rule 7). Per-connection, never global — a global
+ *  registry would let one client guess another's browser by session id. */
 import { EMPTY_OBSERVATION } from "./driver.js";
-/**
- * How long a session may go untouched before it is torn down.
- *
- * A starting value, not a measurement, in this repo's usual sense: no agent
- * has yet been observed pausing mid-exploration, so there is nothing to fit
- * it to. Five minutes is long enough to survive a model thinking, short
- * enough that a forgotten browser is a five-minute leak rather than an
- * overnight one. It is deliberately the same figure as the action handshake's
- * token TTL — an agent that cannot decide within one is unlikely to be coming
- * back for the other.
- */
+/** How long a session may go untouched before torn down. Starting value, not a
+ *  measurement — 5 min balances agent-thinking time against leak size; matches the
+ *  action handshake's token TTL deliberately. */
 export const BROWSER_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
-/**
- * How many sessions one connection may hold open at once.
- *
- * Small on purpose. A calling agent driving more than a couple of browsers
- * simultaneously is not doing something this surface was built for, and each
- * one is a real Chromium. Three leaves room for the honest case — a
- * comparison between two states, plus one being opened — without letting a
- * loop with a missing `browser_close_session` fill the machine.
- */
+/** Max sessions per connection. Small on purpose — each is a real Chromium process;
+ *  3 leaves room for comparing two states plus one opening, without a loop with a
+ *  missing `browser_close_session` filling the machine. */
 export const MAX_BROWSER_SESSIONS = 3;
 const SWEEP_INTERVAL_MS = 30_000;
 function originOf(url) {
@@ -65,9 +18,8 @@ function originOf(url) {
         return new URL(url).origin;
     }
     catch {
-        // An unparseable target is the tool's problem, not the registry's — it
-        // refuses at the schema. Recording the raw string keeps the consent
-        // comparison total rather than throwing from a bookkeeping call.
+        // Unparseable target already refused at the schema; return the raw string so
+        // consent comparison stays total instead of throwing from a bookkeeping call.
         return url;
     }
 }
@@ -77,14 +29,9 @@ export function createBrowserSessionRegistry(options = {}) {
     const idleTimeoutMs = options.idleTimeoutMs ?? BROWSER_IDLE_TIMEOUT_MS;
     const live = new Map();
     const reapedSessions = new Map();
-    /**
-     * The one teardown. Every path goes through here so that "closed the
-     * browser" and "kept what it saw" cannot come apart.
-     *
-     * `close()` on the port returns the final flush and is idempotent, so a
-     * crashed session still yields whatever it had buffered — which is the case
-     * that matters most, the page's last words before it died.
-     */
+    /** The one teardown; every path routes through here so "closed" and "evidence kept"
+     *  cannot come apart. `close()` on the port is idempotent, so even a crashed session
+     *  yields its last buffered evidence. */
     async function reap(sessionId, session, reason) {
         live.delete(sessionId);
         let observation = EMPTY_OBSERVATION;
@@ -92,9 +39,8 @@ export function createBrowserSessionRegistry(options = {}) {
             observation = await session.page.close();
         }
         catch {
-            // A teardown that throws must not leave the session tracked, and must
-            // not lose the record either. The browser may well be gone already;
-            // what matters is that this id is now unusable and says why.
+            // Teardown that throws must not leave the session tracked or lose the record —
+            // the browser may be gone already; this id is now unusable and says why.
         }
         const record = { sessionId, reason, observation, at: now() };
         reapedSessions.set(sessionId, record);
@@ -115,9 +61,7 @@ export function createBrowserSessionRegistry(options = {}) {
                 return {
                     opened: false,
                     kind: "atCapacity",
-                    // Both numbers, because "too many browser sessions" is not
-                    // something a caller can act on and "3 of 3" is — it tells them
-                    // whether to close one or to stop opening them in a loop.
+                    // Both numbers so the caller knows whether to close one or stop opening in a loop.
                     reason: `This connection already has ${live.size} of ${maxSessions} browser sessions open. Close one with ` +
                         "browser_close_session before starting another. The cap is per connection and exists because each " +
                         "session is a real browser process.",
@@ -155,8 +99,7 @@ export function createBrowserSessionRegistry(options = {}) {
                 };
             }
             if (!session.page.isUsable()) {
-                // Down the same teardown every other path uses, so the crash case
-                // cannot be the one where the flush is skipped.
+                // Same teardown as every other path, so the crash case can't skip the flush.
                 const record = await reap(sessionId, session, "crashed");
                 return { ok: false, kind: "crashed", reason: crashReason(sessionId), reaped: record };
             }

package/dist/browser/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/browser/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AASH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAqHjC,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,oEAAoE;QACpE,iEAAiE;QACjE,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,UAAyC,EAAE;IACtF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAChE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,uBAAuB,CAAC;IAEvE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC5C,MAAM,cAAc,GAAG,IAAI,GAAG,EAAyB,CAAC;IAExD;;;;;;;OAOG;IACH,KAAK,UAAU,IAAI,CAAC,SAAiB,EAAE,OAAoB,EAAE,MAAkB;QAC7E,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACvB,IAAI,WAAW,GAAuB,iBAAiB,CAAC;QACxD,IAAI,CAAC;YACH,WAAW,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,oEAAoE;YACpE,6DAA6D;QAC/D,CAAC;QACD,MAAM,MAAM,GAAkB,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC;QAC5E,cAAc,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,SAAS,EAAE,EAAE,iBAAiB,CAAC,CAAC;IAC/G,OAAO,EAAE,KAAK,EAAE,CAAC;IAEjB,KAAK,UAAU,SAAS;QACtB,MAAM,QAAQ,GAAG,GAAG,EAAE,GAAG,aAAa,CAAC;QACvC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC;QAC3F,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACrG,CAAC;IAED,OAAO;QACL,aAAa;QACb,WAAW;QAEX,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa;YAC9B,IAAI,IAAI,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC;gBAC7B,OAAO;oBACL,MAAM,EAAE,KAAK;oBACb,IAAI,EAAE,YAAY;oBAClB,2DAA2D;oBAC3D,gEAAgE;oBAChE,0DAA0D;oBAC1D,MAAM,EACJ,+BAA+B,IAAI,CAAC,IAAI,OAAO,WAAW,yCAAyC;wBACnG,mGAAmG;wBACnG,oCAAoC;iBACvC,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACrB,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC;gBACnD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,GAAG,OAAO,EAAE,CAAC;YACrE,CAAC;YAED,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC;YACjB,MAAM,OAAO,GAAgB;gBAC3B,KAAK,EAAE,WAAW,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE;gBAC5C,IAAI,EAAE,MAAM,CAAC,OAAO;gBACpB,OAAO,EAAE,aAAa,CAAC,OAAO,IAAI,IAAI;gBACtC,eAAe,EAAE,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC;gBAClD,QAAQ,EAAE,EAAE;gBACZ,UAAU,EAAE,EAAE;aACf,CAAC;YACF,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC5C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;QAC7E,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,SAAS;YACjB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBAC7C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;gBAClF,CAAC;gBACD,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,SAAS;oBACf,MAAM,EACJ,uBAAuB,SAAS,+DAA+D;wBAC/F,4DAA4D;iBAC/D,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;gBAC7B,kEAAkE;gBAClE,gDAAgD;gBAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;gBACzD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YACxF,CAAC;YAED,OAAO,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC;YAC3B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;QAC1D,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,SAAS;YACnB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACpC,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,WAAW,IAAI,iBAAiB,CAAC;YAClG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YACxD,OAAO,MAAM,CAAC,WAAW,CAAC;QAC5B,CAAC;QAED,SAAS;QAET,KAAK,CAAC,OAAO,CAAC,MAAM;YAClB,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;YAChC,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAC1F,CAAC;QAED,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC;QACpD,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI;QAC1B,IAAI;YACF,IAAI,OAAO,KAAK,IAAI;gBAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,SAAiB,EAAE,OAAoB;IACtD,OAAO;QACL,SAAS;QACT,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,OAAO,CACL,mBAAmB,SAAS,yEAAyE;QACrG,mGAAmG;QACnG,6DAA6D,CAC9D,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,MAAqB;IACtC,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,aAAa;YAChB,OAAO,CACL,mBAAmB,MAAM,CAAC,SAAS,gEAAgE;gBACnG,iDAAiD,CAClD,CAAC;QACJ,KAAK,kBAAkB;YACrB,OAAO,mBAAmB,MAAM,CAAC,SAAS,2CAA2C,CAAC;QACxF,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACvC,KAAK,QAAQ;YACX,OAAO,mBAAmB,MAAM,CAAC,SAAS,uCAAuC,CAAC;IACtF,CAAC;AACH,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/browser/registry.ts"],"names":[],"mappings":"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"}

package/dist/browser/scenario-resolve.d.ts

@@ -1,43 +1,14 @@
-/**
- * Turning a stored target descriptor back into something clickable —
- * `DEC-383` §2 and §3.
- *
- * This is where the anti-rot mechanism actually lives. A stored step carries
- * `role` + `name` + `selector` and no `ref`, because a ref is scoped to the
- * snapshot that issued it and a replay is always a later session. So every
- * step re-resolves against a fresh snapshot, and the resolution is
- * **exact-or-refuse**: exactly one element matching all three fields, or stop.
- *
- * **There is deliberately no fallback chain.** "Try the selector, else
- * role+name" is the dangerous option and it is dangerous in a specific way: it
- * turns a real disagreement into a quiet substitution, which is how a scenario
- * keeps reporting green against a page that changed underneath it. A
- * disagreement between the three fields is the highest-value signal this
- * format can produce, and a fallback is exactly the code that throws it away.
- *
- * The refusal messages are load-bearing rather than decorative, per
- * `DEC-384`: a stopped push that says "step 3
- * failed to resolve" is what developers route around, and one that says "the
- * button is still there; its accessible name changed from Delete to Remove" is
- * a one-line fix. So every refusal names which step, which descriptor, which
- * of the three fields disagreed, and what the page holds now.
- *
- * Lives beside the port rather than in `scenarios/`, on purpose: the format
- * module imports nothing from the driver and is tested without a browser in
- * the process, and this function needs a `PageSnapshot`.
- */
+/** Turning a stored target descriptor back into something clickable — DEC-383 §2/§3. Stored
+ *  steps carry role+name+selector, no `ref` (scoped to the issuing snapshot); resolution is
+ *  exact-or-refuse against a fresh snapshot, deliberately no fallback chain — substituting one
+ *  matching field for another turns a real disagreement into a quiet one, and the scenario
+ *  keeps reporting green against a changed page. Refusal messages name the exact disagreement (DEC-384). */
 import type { TargetDescriptor } from "../scenarios/index.ts";
 import type { PageSnapshot, SnapshotElement } from "./driver.ts";
 export type DescriptorField = "role" | "name" | "selector";
-/**
- * Why a descriptor did not resolve.
- *
- * Three kinds, kept apart because they send a developer to three different
- * places. `zero` — nothing on the page answers to this at all. `ambiguous` —
- * several do, and picking one would be reporting on a run nobody chose.
- * `partial` — something is still there and one part of the descriptor has
- * moved, which is the case worth the most and the reason `disagreed` exists.
- */
+/** Why a descriptor failed to resolve. `zero` — nothing matches at all. `ambiguous` —
+ *  several do, picking one would report on an unchosen run. `partial` — something still
+ *  matches part of it, the case `disagreed` exists for. */
 export interface ResolutionFailure {
     readonly kind: "zero" | "ambiguous" | "partial";
     /** Which of role/name/selector no longer agree. Empty for `zero` and `ambiguous`, where nothing partial matched to disagree with. */
@@ -51,12 +22,7 @@ export type TargetResolution = {
     readonly resolved: false;
     readonly failure: ResolutionFailure;
 };
-/**
- * Resolve one stored descriptor against a fresh snapshot.
- *
- * `where` is the caller's label for the thing being resolved — `"step 0"`,
- * `"assertion 2"` — and it is required rather than optional because a refusal
- * that does not say *which* step is the version this ruling exists to avoid.
- */
+/** Resolves one stored descriptor against a fresh snapshot. `where` labels what's being
+ *  resolved ("step 0") and is required — a refusal not saying which step is the failure this exists to avoid. */
 export declare function resolveTarget(where: string, target: TargetDescriptor, snapshot: PageSnapshot): TargetResolution;
 //# sourceMappingURL=scenario-resolve.d.ts.map

package/dist/browser/scenario-resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-resolve.d.ts","sourceRoot":"","sources":["../../src/browser/scenario-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEjE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAChD,qIAAqI;IACrI,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAuBtE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,GAAG,gBAAgB,CAgF/G"}
+{"version":3,"file":"scenario-resolve.d.ts","sourceRoot":"","sources":["../../src/browser/scenario-resolve.ts"],"names":[],"mappings":"AAAA;;;;4GAI4G;AAE5G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEjE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3D;;2DAE2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAChD,qIAAqI;IACrI,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAuBtE;iHACiH;AACjH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,GAAG,gBAAgB,CA6E/G"}

package/dist/browser/scenario-resolve.js

@@ -1,31 +1,8 @@
-/**
- * Turning a stored target descriptor back into something clickable —
- * `DEC-383` §2 and §3.
- *
- * This is where the anti-rot mechanism actually lives. A stored step carries
- * `role` + `name` + `selector` and no `ref`, because a ref is scoped to the
- * snapshot that issued it and a replay is always a later session. So every
- * step re-resolves against a fresh snapshot, and the resolution is
- * **exact-or-refuse**: exactly one element matching all three fields, or stop.
- *
- * **There is deliberately no fallback chain.** "Try the selector, else
- * role+name" is the dangerous option and it is dangerous in a specific way: it
- * turns a real disagreement into a quiet substitution, which is how a scenario
- * keeps reporting green against a page that changed underneath it. A
- * disagreement between the three fields is the highest-value signal this
- * format can produce, and a fallback is exactly the code that throws it away.
- *
- * The refusal messages are load-bearing rather than decorative, per
- * `DEC-384`: a stopped push that says "step 3
- * failed to resolve" is what developers route around, and one that says "the
- * button is still there; its accessible name changed from Delete to Remove" is
- * a one-line fix. So every refusal names which step, which descriptor, which
- * of the three fields disagreed, and what the page holds now.
- *
- * Lives beside the port rather than in `scenarios/`, on purpose: the format
- * module imports nothing from the driver and is tested without a browser in
- * the process, and this function needs a `PageSnapshot`.
- */
+/** Turning a stored target descriptor back into something clickable — DEC-383 §2/§3. Stored
+ *  steps carry role+name+selector, no `ref` (scoped to the issuing snapshot); resolution is
+ *  exact-or-refuse against a fresh snapshot, deliberately no fallback chain — substituting one
+ *  matching field for another turns a real disagreement into a quiet one, and the scenario
+ *  keeps reporting green against a changed page. Refusal messages name the exact disagreement (DEC-384). */
 const FIELDS = ["role", "name", "selector"];
 function describe(target) {
     return `role "${target.role}", name "${target.name}", selector "${target.selector}"`;
@@ -44,13 +21,8 @@ function pageContents(snapshot, limit = 8) {
 function disagreementsWith(target, element) {
     return FIELDS.filter((field) => element[field] !== target[field]);
 }
-/**
- * Resolve one stored descriptor against a fresh snapshot.
- *
- * `where` is the caller's label for the thing being resolved — `"step 0"`,
- * `"assertion 2"` — and it is required rather than optional because a refusal
- * that does not say *which* step is the version this ruling exists to avoid.
- */
+/** Resolves one stored descriptor against a fresh snapshot. `where` labels what's being
+ *  resolved ("step 0") and is required — a refusal not saying which step is the failure this exists to avoid. */
 export function resolveTarget(where, target, snapshot) {
     const exact = snapshot.elements.filter((e) => e.role === target.role && e.name === target.name && e.selector === target.selector);
     if (exact.length === 1)
@@ -81,10 +53,8 @@ export function resolveTarget(where, target, snapshot) {
             },
         };
     }
-    // The partial case, and the reason the format stores all three fields. Both
-    // halves are reported when both matched, because "the selector still points
-    // at something AND an element with this role and name still exists" is two
-    // candidates and a person is the one who knows which is theirs.
+    // The partial case — why the format stores all three fields. Both halves are reported
+    // when both matched, since two candidates exist and only a person knows which is theirs.
     const parts = [];
     const disagreed = new Set();
     if (bySelector.length === 1) {
@@ -114,8 +84,7 @@ export function resolveTarget(where, target, snapshot) {
         resolved: false,
         failure: {
             kind: "partial",
-            // Ordered the way the descriptor is, so a caller comparing two failures
-            // is comparing sets rather than orderings.
+            // Ordered like the descriptor, so callers compare sets, not orderings.
             disagreed: FIELDS.filter((field) => disagreed.has(field)),
             message: `${where}: ${describe(target)} does not match exactly one element on ${snapshot.url}, but part of it ` +
                 `still does — ${parts.join("; ")}. The step is not run: substituting the half that still matches would ` +

package/dist/browser/scenario-resolve.js.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-resolve.js","sourceRoot":"","sources":["../../src/browser/scenario-resolve.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scenario-resolve.js","sourceRoot":"","sources":["../../src/browser/scenario-resolve.ts"],"names":[],"mappings":"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"}

package/dist/browser/scenario-runner.d.ts

@@ -1,44 +1,7 @@
 /**
- * Replaying a stored scenario — §7's runner half.
- *
- * ## What this composes, and the four things it must not get wrong
- *
- * Everything below is composition: the port drives, `scenarios/` is the
- * artifact, `scenario-resolve.ts` re-resolves a descriptor, `tool-support.ts`
- * drains and correlates. What the runner adds is *order*, and four ordering
- * mistakes each fail as flakiness or as a false pass rather than as an error,
- * which is why each is named here rather than left to be rediscovered.
- *
- * 1. **`registry.use()` is called once per step.** It is not a lookup: it is
- *    asynchronous, it is the crash detector, and it touches the idle clock. A
- *    runner that resolved the session once and held the entry across N steps
- *    would be reaped mid-scenario at the five-minute idle timeout, and would
- *    read as a flaky test rather than as a design error.
- * 2. **`drainEvidence()` drains, it does not peek.** Once per step, aggregated
- *    into the summary. A single read at the end loses every earlier step's
- *    observations — and would silently pass an assertion anchored at step 0,
- *    which is the false green this whole feature exists to prevent.
- * 3. **A stored step carries no `ref`.** Every step re-resolves against a
- *    fresh snapshot, exact-or-refuse, with no fallback chain. See
- *    `scenario-resolve.ts`.
- * 4. **Assertions evaluate here, at replay.** An empty assertion list replays
- *    as `unverified`, never `passed`.
- *
- * ## The outcome rule
- *
- * `DEC-384`, implemented rather than restated. A
- * failed assertion is the scenario's own claim about the application, written
- * down by a person, and it blocks. A console error or a failed request is
- * reported and does not block — frequently true of a working page, and a check
- * people disable protects nothing. No assertions is `unverified`. An
- * unresolvable step is **neither pass nor fail**: Descry cannot tell a
- * deliberate rename from a vanished button, and both produce a byte-identical
- * unresolvable step, so it claims neither while still stopping the run.
- *
- * Three counts, **never summed** — `failed`, `unresolved`, `unverified` — and
- * only failed assertions join `blockingTotal`, because folding `unresolved`
- * into it would re-assert through arithmetic the defect claim the ruling
- * refused to make in prose.
+ * Replays a stored scenario (§7 runner). DEC-384: failed assertion blocks; console
+ * error/failed request doesn't; no assertions is `unverified`; unresolvable step is
+ * neither pass nor fail. `registry.use()` and evidence draining run once per step only.
  */
 import type { Scenario, ScenarioActionKind, ScenarioAssertionKind } from "../scenarios/index.ts";
 import type { ToolContext } from "../tools/kit.ts";
@@ -59,18 +22,9 @@ export interface ScenarioAssertionResult {
     readonly index: number;
     readonly kind: ScenarioAssertionKind;
     readonly afterStep: number | null;
-    /**
-     * `unevaluable` and `notReached` are deliberately distinct from each other
-     * and from `failed`.
-     *
-     * `unevaluable` is a hole in the stored artifact — a `textEquals` with
-     * nothing to compare against. `notReached` is an assertion anchored at a
-     * step the replay never got to. Neither is a defect claim about the
-     * application, so neither may be reported as `failed`; only `unevaluable`
-     * joins `unresolved`, because `notReached` is already accounted for by the
-     * unresolved step that stopped the run and counting it twice would inflate
-     * a count the ruling requires to stay separate.
-     */
+    /** `unevaluable` = hole in the artifact (e.g. missing comparison value); `notReached`
+     *  = anchored past where replay stopped. Neither is a defect claim; only
+     *  `unevaluable` joins `unresolved` (notReached is already counted there). */
     readonly status: "passed" | "failed" | "unevaluable" | "notReached";
     readonly detail: string;
 }
@@ -87,16 +41,9 @@ export interface ScenarioReplay {
     readonly counts: ScenarioCounts;
     /** Only failed assertions. See this file's header for why `unresolved` is not folded in. */
     readonly blockingTotal: number;
-    /**
-     * 0 clean, 1 blocking findings, 2 the check could not run — `descry check`'s
-     * existing vocabulary, computed here rather than in the CLI.
-     *
-     * The exit ruling governs the agentless CLI and explicitly does not govern
-     * MCP replies, so this is data on the reply rather than a verdict in it. It
-     * is computed in the one place that knows the outcome so the CLI box does
-     * not become a second implementation of the same rule, drifting from this
-     * one the first time either changes.
-     */
+    /** 0 clean, 1 blocking findings, 2 could-not-run — `descry check`'s exit vocabulary,
+     *  computed here (not in the CLI) so the two never drift. Governs the CLI only;
+     *  this reply carries it as data, not a verdict. */
     readonly exitCode: 0 | 1 | 2;
     readonly steps: readonly ScenarioStepResult[];
     readonly assertions: readonly ScenarioAssertionResult[];
@@ -105,14 +52,9 @@ export interface ScenarioReplay {
     readonly graph: BrowserGraphWrite;
     /** Set when the session went away mid-replay — a crash, a reap, a disconnect. Null on a replay that ran to its own end. */
     readonly sessionEnded: DeadSession | null;
-    /**
-     * True when the call's own signal was aborted mid-replay.
-     *
-     * Reported rather than folded into `outcome` alone, because "stopped because
-     * the caller cancelled" and "stopped because a step would not resolve" are
-     * different facts about the run and only one of them says anything about the
-     * application.
-     */
+    /** True when the caller's own signal aborted mid-replay — distinct from `outcome`
+     *  because "caller cancelled" vs "a step wouldn't resolve" are different facts,
+     *  and only one says anything about the application. */
     readonly cancelled: boolean;
     readonly notes: readonly string[];
 }