@descryy/mcp 0.1.2 → 0.3.0

package/dist/bin/descry-mcp.js

@@ -15,10 +15,33 @@
  * writes nothing itself and does its argument handling before opening anything.
  */
 import process from "node:process";
+import { createRequire } from "node:module";
 import { resolve } from "node:path";
 import { createMcpServer } from "../server.js";
 import { Session } from "../session.js";
 import { serveStdio } from "../transport.js";
+/**
+ * The version this build actually is, read from the installed package rather
+ * than written here.
+ *
+ * It was the literal `"0.0.0"` for every release, so every host reported the
+ * same version no matter which package it was running — and that is not a
+ * cosmetic gap. `@descryy/mcp` 0.1.2 went to npm from a branch that never
+ * reached `main`, carrying a tool `main` did not have, and nothing any host
+ * could see said so: `tools/list` showed seventeen tools and `serverInfo` said
+ * 0.0.0. A server that cannot say what it is cannot be caught drifting.
+ */
+const VERSION = (() => {
+    try {
+        const pkg = createRequire(import.meta.url)("../../package.json");
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        // Never fatal. A host that cannot read a version still gets a server, and
+        // failing the handshake over a label would be the worse trade.
+        return "0.0.0";
+    }
+})();
 const USAGE = `descry-mcp — Descry's MCP server (stdio)
 
   descry-mcp [repository-path]
@@ -34,7 +57,7 @@ async function main() {
     }
     const repoPath = resolve(args[0] ?? process.cwd());
     const session = await Session.open({ repoPath });
-    const server = createMcpServer({ session, name: "descry", version: "0.0.0" });
+    const server = createMcpServer({ session, name: "descry", version: VERSION });
     try {
         await serveStdio({ stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }, (line, transport) => server.dispatch(line, transport));
         return 0;
@@ -42,7 +65,12 @@ async function main() {
     finally {
         // The SQLite handle and anything else with a lifetime. Held open past the
         // end of stdin, a WAL journal outlives the process that owned it.
-        session.close();
+        //
+        // `dispose`, not `close`, because end-of-stdin is how an MCP host says
+        // "disconnect" — and §4 requires that signal to reap every browser this
+        // connection owns. A leaked SQLite handle costs a file descriptor; a
+        // leaked Chromium keeps running on the developer's machine.
+        await session.dispose();
     }
 }
 main().then((code) => {

package/dist/bin/descry-mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"descry-mcp.js","sourceRoot":"","sources":["../../src/bin/descry-mcp.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,KAAK,GAAG;;;;;;CAMb,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAE9E,IAAI,CAAC;QACH,MAAM,UAAU,CACd,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,EACxE,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CACtD,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;YAAS,CAAC;QACT,0EAA0E;QAC1E,kEAAkE;QAClE,OAAO,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;IACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,eAAe,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACzF,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}
+{"version":3,"file":"descry-mcp.js","sourceRoot":"","sources":["../../src/bin/descry-mcp.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,OAAO,GAAW,CAAC,GAAW,EAAE;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAA0B,CAAC;QAC1F,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,+DAA+D;QAC/D,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC,CAAC,EAAE,CAAC;AAEL,MAAM,KAAK,GAAG;;;;;;CAMb,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAE9E,IAAI,CAAC;QACH,MAAM,UAAU,CACd,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,EACxE,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CACtD,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;YAAS,CAAC;QACT,0EAA0E;QAC1E,kEAAkE;QAClE,EAAE;QACF,uEAAuE;QACvE,wEAAwE;QACxE,qEAAqE;QACrE,4DAA4D;QAC5D,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;IACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,eAAe,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACzF,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/browser/driver.d.ts

@@ -0,0 +1,236 @@
+/**
+ * The browser port — what `@descryy/mcp` needs from a browser, stated as an
+ * interface this package owns.
+ *
+ * ## Why a port at all
+ *
+ * `@descryy/runtime-browser` is not on the registry yet
+ * (`mcp-browser-tools.md` §3.1), so a lane that imported it directly could
+ * not run today. That is the immediate reason and it is the weakest one.
+ * The lasting reason is that everything above this line — seven tools, the
+ * session registry, the scenario runner — otherwise becomes untestable
+ * without launching a real Chromium per assertion, and a suite that needs a
+ * browser to test its session bookkeeping is a suite people stop running.
+ *
+ * ## Derived, not invented
+ *
+ * Every member below exists because a real export in
+ * `descry-runtime/packages/browser/src/index.ts` provides it. The refusal
+ * shape is `launchBrowserSessionOrRefuse`'s verbatim; `isUsable()` is
+ * `BrowserSession`'s, including its reason for existing (a crashed page
+ * still reports `isClosed() === false`, so crash tracking cannot be derived
+ * from closure); the action verbs are `BrowserActionCollector`'s; the
+ * console and network observations are what the two collectors emit. The
+ * port narrows that surface — it does not add to it. Nothing here can be
+ * satisfied by the real package only by writing new runtime code, with one
+ * disclosed exception, `type()` below.
+ *
+ * ## What the port deliberately does not carry
+ *
+ * A verdict. There is no `severity`, no `isBug`, no `category` on any
+ * observation, because `DEC-381` rules that
+ * classification stays in the desktop pipeline. That is enforced structurally
+ * rather than by convention: a tool cannot report a triaged finding through
+ * a port that has nowhere to put one.
+ *
+ * Rule 1 holds here as everywhere — nothing in this file names a language, a
+ * framework, or a file extension.
+ */
+import type { StackTrace } from "@descryy/runtime-contracts";
+/** A page element as a snapshot presented it. `ref` is the handle an action takes. */
+export interface SnapshotElement {
+    readonly ref: string;
+    readonly role: string;
+    readonly name: string;
+    /**
+     * How the driver will find this element again. Present so a reply can be
+     * read by a human, **not** so a caller can act on it: every verb takes a
+     * `ref`, never a selector, because a ref ties the action to a snapshot the
+     * agent actually saw and a selector does not.
+     */
+    readonly selector: string;
+}
+export interface PageSnapshot {
+    readonly url: string;
+    readonly title: string;
+    readonly elements: readonly SnapshotElement[];
+    /**
+     * How many elements the page had, before any budget applied.
+     *
+     * Always present, and always the uncapped figure. §5.2's requirement in one
+     * field: without it a caller cannot tell "there are no more elements" from
+     * "the rest did not fit", and those are different facts about their page.
+     * The driver never truncates — it returns what it saw and this equals
+     * `elements.length` here — but the field is on the port rather than
+     * invented by the tool, so the tool cannot lose track of the real count
+     * while paging.
+     */
+    readonly totalElements: number;
+}
+export type BrowserActionKind = "navigate" | "click" | "type" | "fill";
+export interface ObservedAction {
+    readonly action: BrowserActionKind;
+    /** Null for `navigate`, which acts on the page rather than on an element. */
+    readonly ref: string | null;
+    /**
+     * How text reached the field — `"append"` for `type`, `"replace"` for
+     * `fill`, null for actions that enter no text.
+     *
+     * Carried because without it the two text verbs' evidence reads
+     * identically, and "the field now contains X" and "X was added to whatever
+     * the field already contained" are different facts about a run. The runtime
+     * collector's own `INPUT` payload carries the same field for the same
+     * reason.
+     */
+    readonly mode: "replace" | "append" | null;
+    readonly url: string;
+    readonly at: string;
+}
+export interface ObservedConsoleError {
+    readonly text: string;
+    /**
+     * Raw stack text as the page produced it, or null. **Not yet rewritten to
+     * real files and lines** — that is `rewriteScriptUrls`' job and it needs a
+     * source-root resolver the driver does not have. The port carries the raw
+     * text so the mapping happens once, above, where the repo root is known.
+     */
+    readonly stackText: string | null;
+    readonly at: string;
+}
+export interface ObservedRequest {
+    readonly method: string;
+    readonly url: string;
+    /** Null when the request produced no response at all, which is a different fact from a 500. */
+    readonly status: number | null;
+    /** The `fetch()` call site as raw text, when the initiator capture claimed one. Null is honest absence. */
+    readonly stackText: string | null;
+    /**
+     * The same call site, parsed into frames with real file paths.
+     *
+     * Null unless the caller named a stack-trace parser for the application
+     * being driven — this package cannot parse a stack itself without naming a
+     * language, which rule 1 forbids above the IR. **This is the field the R4
+     * edge write needs**: `confirmObservedFrontendCaller` takes a `StackTrace`,
+     * not text, and a run with no parser produces no arrow and says so.
+     */
+    readonly stackTrace: StackTrace | null;
+    readonly at: string;
+}
+/** A request that did not succeed. Mechanical, not a judgement: no response, or a 4xx/5xx status. */
+export declare function isFailedRequest(request: ObservedRequest): boolean;
+/** Everything witnessed since the last drain. Raw — see this file's header. */
+export interface BrowserObservation {
+    readonly actions: readonly ObservedAction[];
+    readonly consoleErrors: readonly ObservedConsoleError[];
+    /**
+     * Every request the page issued, not only the ones that failed.
+     *
+     * A successful call is what proves *this frontend action reached this
+     * backend route* — the arrow the whole plan exists for — so filtering to
+     * failures here would throw away the evidence the R4 edge write runs on.
+     * The reply narrows to failures for readability; the correlation does not.
+     */
+    readonly requests: readonly ObservedRequest[];
+}
+export declare const EMPTY_OBSERVATION: BrowserObservation;
+export interface BrowserLaunchOptions {
+    readonly targetUrl: string;
+    readonly headless?: boolean;
+}
+/**
+ * `launchBrowserSessionOrRefuse`'s refusal, unchanged.
+ *
+ * `remedy` is the exact command that fixes it, **supplied by the driver and
+ * never held as a constant in this package**. The real driver passes
+ * `CHROMIUM_INSTALL_REMEDY` through; a copy here would be a second source of
+ * truth for one string, and the copy is the one that goes stale.
+ */
+export interface ChromiumRefusal {
+    readonly refusal: "chromiumNotInstalled";
+    readonly message: string;
+    readonly remedy: string;
+    readonly expectedExecutablePath: string;
+}
+export type BrowserLaunchResult = {
+    readonly launched: true;
+    readonly session: BrowserPageSession;
+} | ({
+    readonly launched: false;
+} & ChromiumRefusal);
+/** The browser died. Distinct from a closed session: a crash invalidates the id rather than ending it cleanly. */
+export declare class BrowserSessionCrashedError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/**
+ * The ref named no element in the current snapshot.
+ *
+ * Thrown for an invented ref **and** for a ref from a superseded snapshot,
+ * because those are the same mistake: acting on an element the agent has not
+ * seen. Falling back to the stale selector would let a click land on whatever
+ * now matches it on a page the caller has never inspected.
+ */
+export declare class UnknownElementRefError extends Error {
+    constructor(ref: string);
+}
+export interface BrowserPageSession {
+    readonly sessionId: string;
+    /** When the page was actually created, ISO-8601. What evidence is ordered by. */
+    readonly startedAt: string;
+    /**
+     * False once the page has crashed or closed. Not derivable from closure —
+     * `runtime-browser` verified directly that a real crash still reports
+     * `isClosed() === false`, which is why this is a member rather than
+     * something a caller computes.
+     */
+    isUsable(): boolean;
+    currentUrl(): string;
+    navigate(url: string): Promise<void>;
+    snapshot(): Promise<PageSnapshot>;
+    click(ref: string): Promise<void>;
+    /**
+     * Type `text` as real keystrokes, appending to whatever the field holds.
+     *
+     * The append/replace difference against `fill` is the visible half. The
+     * half that decides which verb is correct for a page is that **this one
+     * fires key events and `fill` fires none**: a field that opens an
+     * autocomplete on keydown, validates per character, or debounces a search
+     * sees nothing at all from a `fill`. A caller reaching for `fill` on a
+     * search box gets a page that was never typed into — a wrong answer
+     * produced by entirely correct code — so both members exist and the tool
+     * prose has to state the real distinction, not the tidy one.
+     */
+    type(ref: string, text: string): Promise<void>;
+    /** Replace the element's value with `text`, setting it directly. Fires no key events. */
+    fill(ref: string, text: string): Promise<void>;
+    /**
+     * Everything witnessed since the last drain, removed from the session as it
+     * is returned.
+     *
+     * Drained rather than peeked, and that is a contract, not an implementation
+     * detail: §4 requires evidence to be flushed on four separate teardown
+     * paths, and a peeking read would make the flush re-report every
+     * observation already attached to an earlier reply.
+     */
+    drainEvidence(): Promise<BrowserObservation>;
+    /**
+     * Tear down and return whatever was still held.
+     *
+     * Idempotent, and returns the final flush rather than `void`. Evidence
+     * captured and then dropped is worse than evidence never captured, because
+     * nothing discloses it — so the last thing a session does is hand back what
+     * it was holding, on every path including a crash.
+     */
+    close(): Promise<BrowserObservation>;
+}
+export interface BrowserDriver {
+    /**
+     * Open a session at `targetUrl`, or refuse.
+     *
+     * A missing browser is a **returned value**, never a thrown error, so a
+     * tool mapping it onto the `refused` state cannot forget to catch it —
+     * `refused` is a fact about Descry, never about the user's code.
+     */
+    launch(options: BrowserLaunchOptions): Promise<BrowserLaunchResult>;
+}
+//# sourceMappingURL=driver.d.ts.map

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

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

package/dist/browser/driver.js

@@ -0,0 +1,70 @@
+/**
+ * The browser port — what `@descryy/mcp` needs from a browser, stated as an
+ * interface this package owns.
+ *
+ * ## Why a port at all
+ *
+ * `@descryy/runtime-browser` is not on the registry yet
+ * (`mcp-browser-tools.md` §3.1), so a lane that imported it directly could
+ * not run today. That is the immediate reason and it is the weakest one.
+ * The lasting reason is that everything above this line — seven tools, the
+ * session registry, the scenario runner — otherwise becomes untestable
+ * without launching a real Chromium per assertion, and a suite that needs a
+ * browser to test its session bookkeeping is a suite people stop running.
+ *
+ * ## Derived, not invented
+ *
+ * Every member below exists because a real export in
+ * `descry-runtime/packages/browser/src/index.ts` provides it. The refusal
+ * shape is `launchBrowserSessionOrRefuse`'s verbatim; `isUsable()` is
+ * `BrowserSession`'s, including its reason for existing (a crashed page
+ * still reports `isClosed() === false`, so crash tracking cannot be derived
+ * from closure); the action verbs are `BrowserActionCollector`'s; the
+ * console and network observations are what the two collectors emit. The
+ * port narrows that surface — it does not add to it. Nothing here can be
+ * satisfied by the real package only by writing new runtime code, with one
+ * disclosed exception, `type()` below.
+ *
+ * ## What the port deliberately does not carry
+ *
+ * A verdict. There is no `severity`, no `isBug`, no `category` on any
+ * observation, because `DEC-381` rules that
+ * classification stays in the desktop pipeline. That is enforced structurally
+ * rather than by convention: a tool cannot report a triaged finding through
+ * a port that has nowhere to put one.
+ *
+ * Rule 1 holds here as everywhere — nothing in this file names a language, a
+ * framework, or a file extension.
+ */
+/** A request that did not succeed. Mechanical, not a judgement: no response, or a 4xx/5xx status. */
+export function isFailedRequest(request) {
+    return request.status === null || request.status >= 400;
+}
+export const EMPTY_OBSERVATION = { actions: [], consoleErrors: [], requests: [] };
+/** The browser died. Distinct from a closed session: a crash invalidates the id rather than ending it cleanly. */
+export class BrowserSessionCrashedError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Browser session ${sessionId} is no longer usable — the browser process crashed or the page closed. ` +
+            "The session id is invalidated; start a new session. It is deliberately not reopened against a " +
+            "different browser, which would silently change what later evidence refers to.");
+        this.name = "BrowserSessionCrashedError";
+        this.sessionId = sessionId;
+    }
+}
+/**
+ * The ref named no element in the current snapshot.
+ *
+ * Thrown for an invented ref **and** for a ref from a superseded snapshot,
+ * because those are the same mistake: acting on an element the agent has not
+ * seen. Falling back to the stale selector would let a click land on whatever
+ * now matches it on a page the caller has never inspected.
+ */
+export class UnknownElementRefError extends Error {
+    constructor(ref) {
+        super(`"${ref}" is not an element in this session's current snapshot. Refs are issued per snapshot and are ` +
+            "invalidated by navigation — call browser_snapshot and use a ref from the result.");
+        this.name = "UnknownElementRefError";
+    }
+}
+//# sourceMappingURL=driver.js.map

package/dist/browser/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/browser/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAyFH,qGAAqG;AACrG,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,OAAO,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC;AAC1D,CAAC;AAiBD,MAAM,CAAC,MAAM,iBAAiB,GAAuB,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AA0BtG,kHAAkH;AAClH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,SAAS,CAAS;IAE3B,YAAY,SAAiB;QAC3B,KAAK,CACH,mBAAmB,SAAS,yEAAyE;YACnG,gGAAgG;YAChG,+EAA+E,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,GAAW;QACrB,KAAK,CACH,IAAI,GAAG,+FAA+F;YACpG,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}

package/dist/browser/evidence.d.ts

@@ -0,0 +1,47 @@
+/**
+ * How a browser observation becomes part of a tool reply — §5.3.
+ *
+ * Two rules live here rather than in each of the seven tools, because seven
+ * copies of a disclosure is seven chances for one of them to be missing.
+ *
+ * **Attached, not fetched.** Evidence rides on the reply for the action that
+ * produced it. A separate `browser_get_evidence` would make the caller
+ * correlate two replies to learn that its own click caused the error, and
+ * would let it skip the second call entirely.
+ *
+ * **Raw, and disclosed as raw.** Per
+ * `DEC-381`, nothing here classifies. The
+ * note below is not decoration: a calling agent that receives a console error
+ * has to know Descry is not claiming it is a bug, or it will report Descry as
+ * having said so.
+ */
+import { type BrowserObservation, type ObservedRequest } from "./driver.ts";
+export interface BrowserEvidenceReport {
+    readonly consoleErrors: BrowserObservation["consoleErrors"];
+    /**
+     * The requests that did not succeed, listed.
+     *
+     * Narrowed from everything the page issued, because a page load can issue
+     * fifty requests and a reply that lists every stylesheet is a reply nobody
+     * reads. The narrowing is mechanical — no response, or a 4xx/5xx — and it
+     * is **only a narrowing of the reply**: the correlation that mints R4 edges
+     * runs over every request, since a successful call is exactly what proves a
+     * frontend action reached a backend route.
+     */
+    readonly failedRequests: readonly ObservedRequest[];
+    /** How many requests the page issued in total, so the list above is read as a subset and not as all of it. */
+    readonly totalRequests: number;
+    readonly actions: BrowserObservation["actions"];
+}
+export declare function evidenceReport(observation: BrowserObservation): BrowserEvidenceReport;
+export declare function isEmpty(report: BrowserEvidenceReport): boolean;
+/**
+ * The notes any reply carrying evidence must include.
+ *
+ * The triage disclaimer is emitted **only when there is something to
+ * disclaim**. A reply with no errors that solemnly explained it had not
+ * triaged them would be noise on the overwhelmingly common path, and noise is
+ * how a real disclosure stops being read.
+ */
+export declare function evidenceNotes(report: BrowserEvidenceReport): string[];
+//# sourceMappingURL=evidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/browser/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAmB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC5D;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD,8GAA8G;IAC9G,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;CACjD;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,kBAAkB,GAAG,qBAAqB,CAOrF;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAsBrE"}

package/dist/browser/evidence.js

@@ -0,0 +1,55 @@
+/**
+ * How a browser observation becomes part of a tool reply — §5.3.
+ *
+ * Two rules live here rather than in each of the seven tools, because seven
+ * copies of a disclosure is seven chances for one of them to be missing.
+ *
+ * **Attached, not fetched.** Evidence rides on the reply for the action that
+ * produced it. A separate `browser_get_evidence` would make the caller
+ * correlate two replies to learn that its own click caused the error, and
+ * would let it skip the second call entirely.
+ *
+ * **Raw, and disclosed as raw.** Per
+ * `DEC-381`, nothing here classifies. The
+ * note below is not decoration: a calling agent that receives a console error
+ * has to know Descry is not claiming it is a bug, or it will report Descry as
+ * having said so.
+ */
+import { isFailedRequest } from "./driver.js";
+export function evidenceReport(observation) {
+    return {
+        consoleErrors: observation.consoleErrors,
+        failedRequests: observation.requests.filter(isFailedRequest),
+        totalRequests: observation.requests.length,
+        actions: observation.actions,
+    };
+}
+export function isEmpty(report) {
+    return report.consoleErrors.length === 0 && report.failedRequests.length === 0;
+}
+/**
+ * The notes any reply carrying evidence must include.
+ *
+ * The triage disclaimer is emitted **only when there is something to
+ * disclaim**. A reply with no errors that solemnly explained it had not
+ * triaged them would be noise on the overwhelmingly common path, and noise is
+ * how a real disclosure stops being read.
+ */
+export function evidenceNotes(report) {
+    if (isEmpty(report))
+        return [];
+    const notes = [
+        `${report.consoleErrors.length} console error(s) and ${report.failedRequests.length} failed request(s) ` +
+            "were observed in the browser during this call. They are reported raw and have not been triaged — " +
+            "Descry is not claiming any of them is a bug, only that the page produced them. Deciding which " +
+            "matter is the calling agent's job.",
+    ];
+    const unmapped = [...report.consoleErrors, ...report.failedRequests].filter((item) => item.stackText !== null && !item.stackText.startsWith("/") && item.stackText.includes("http")).length;
+    if (unmapped > 0) {
+        notes.push(`${unmapped} stack trace(s) still name script URLs rather than repository files. Mapping them back ` +
+            "to real files and lines needs the browser backend's source-root resolver, which this build does " +
+            "not have wired yet, so the raw text is passed through rather than a guess being printed.");
+    }
+    return notes;
+}
+//# sourceMappingURL=evidence.js.map

package/dist/browser/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/browser/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,eAAe,EAAiD,MAAM,aAAa,CAAC;AAoB7F,MAAM,UAAU,cAAc,CAAC,WAA+B;IAC5D,OAAO;QACL,aAAa,EAAE,WAAW,CAAC,aAAa;QACxC,cAAc,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,eAAe,CAAC;QAC5D,aAAa,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM;QAC1C,OAAO,EAAE,WAAW,CAAC,OAAO;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,MAA6B;IACnD,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAA6B;IACzD,IAAI,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IAE/B,MAAM,KAAK,GAAG;QACZ,GAAG,MAAM,CAAC,aAAa,CAAC,MAAM,yBAAyB,MAAM,CAAC,cAAc,CAAC,MAAM,qBAAqB;YACtG,mGAAmG;YACnG,gGAAgG;YAChG,oCAAoC;KACvC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CACzE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CACxG,CAAC,MAAM,CAAC;IACT,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CACR,GAAG,QAAQ,yFAAyF;YAClG,kGAAkG;YAClG,0FAA0F,CAC7F,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/browser/fake-driver.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A `BrowserDriver` with no browser behind it.
+ *
+ * Not a stub. It implements every rule the port states — ref issuance and
+ * invalidation, drain-not-peek, crash invalidation, idempotent close that
+ * still flushes — and `browser-driver-contract.test.ts` runs the same
+ * assertions against it that the real driver will have to pass. Its purpose
+ * is to make those rules *checkable in milliseconds*, so the session
+ * lifecycle in §4 is tested against timeouts, disconnects and crashes that
+ * would otherwise each need a real Chromium.
+ *
+ * Two deliberate non-goals. It does not simulate a page — pages are declared
+ * with `setPage`, because a fake DOM would be a second, wrong browser. And it
+ * does not classify anything, for the same structural reason the port does
+ * not: there is nowhere to put a verdict.
+ */
+import { type BrowserDriver, type ObservedRequest } from "./driver.ts";
+/** A page as a test declares it. `ref` is issued by the fake, not written here. */
+export interface FakePage {
+    readonly url: string;
+    readonly title: string;
+    readonly elements: readonly {
+        readonly role: string;
+        readonly name: string;
+        readonly selector: string;
+    }[];
+}
+export interface FakeBrowserDriver extends BrowserDriver {
+    /** Declare what is served at `url`. Navigating anywhere undeclared yields an empty page, not an error — an empty page is a real thing a URL can serve. */
+    setPage(url: string, page: FakePage): void;
+    /** Every subsequent launch refuses, in `launchBrowserSessionOrRefuse`'s shape. */
+    setChromiumMissing(remedy?: string): void;
+    emitConsoleError(sessionId: string, error: {
+        readonly text: string;
+        readonly stackText: string | null;
+    }): void;
+    /** Record a request the page issued. Status and stack are whatever the test needs them to be. */
+    emitRequest(sessionId: string, request: {
+        readonly method: string;
+        readonly url: string;
+        readonly status: number | null;
+        readonly stackText: string | null;
+        readonly stackTrace?: ObservedRequest["stackTrace"];
+    }): void;
+    /** Sugar for `emitRequest` with a failing status. */
+    emitFailedRequest(sessionId: string, request: {
+        readonly method: string;
+        readonly url: string;
+        readonly status: number | null;
+        readonly stackText: string | null;
+    }): void;
+    /** Kill the browser behind a session, the way a real crash does — usable goes false, the id stays invalid. */
+    crash(sessionId: string): void;
+    /** Every session this driver has opened and not closed. What the registry's orphan-cleanup tests assert against. */
+    openSessionIds(): readonly string[];
+}
+export declare function createFakeBrowserDriver(): FakeBrowserDriver;
+//# sourceMappingURL=fake-driver.d.ts.map

package/dist/browser/fake-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-driver.d.ts","sourceRoot":"","sources":["../../src/browser/fake-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAGL,KAAK,aAAa,EAOlB,KAAK,eAAe,EAGrB,MAAM,aAAa,CAAC;AAErB,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3G;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,0JAA0J;IAC1J,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3C,kFAAkF;IAClF,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/G,iGAAiG;IACjG,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;QACP,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;KACrD,GACA,IAAI,CAAC;IACR,qDAAqD;IACrD,iBAAiB,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAC5H,IAAI,CAAC;IACR,8GAA8G;IAC9G,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oHAAoH;IACpH,cAAc,IAAI,SAAS,MAAM,EAAE,CAAC;CACrC;AAeD,wBAAgB,uBAAuB,IAAI,iBAAiB,CAsJ3D"}