@descryy/mcp 0.9.1 → 0.11.0

package/dist/tools/browser-submit.js

@@ -0,0 +1,106 @@
+/** `browser_submit` submits the form an element sits in, through that form's own submit
+ *  control — so the page sees the submission a person would produce, validation included.
+ *  Consent is granted once, at `browser_start_session` (DEC-380): `class: "action"`,
+ *  `describeAction` undefined, a verb cannot mint its own consent. Nothing is guessed: an
+ *  element in no form, or in a form with no submit control, is refused by name. */
+import { browserAnswer, emptyEvidence, mutationRefusal, observeAndCorrelate, useSession } from "../browser/tool-support.js";
+import { NO_GRAPH_WRITE } from "../browser/graph-write.js";
+import { NotSubmittableError, UnknownElementRefError } from "../browser/driver.js";
+import { CANCELLED_STATE, cancellationHeadline, cancellationNotes } from "../cancellation.js";
+import { requiredString } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        sessionId: { type: "string", description: "REQUIRED. The id returned by browser_start_session." },
+        ref: {
+            type: "string",
+            description: "REQUIRED. An element ref from a browser_snapshot reply, for any element inside the form to submit — " +
+                "a field or the submit button will both do. Refs are issued per snapshot and are invalidated by " +
+                "navigation, so take a fresh snapshot after the page changes.",
+        },
+        confirmToken: {
+            type: "string",
+            description: "Not normally needed. Consent is granted once, for the whole session, by browser_start_session, " +
+                "so this call performs its action directly. The field is declared because the handshake reads it " +
+                "for every action-class tool.",
+        },
+    },
+    required: ["sessionId", "ref"],
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const sessionId = requiredString(args, "sessionId");
+    const ref = requiredString(args, "ref");
+    if (ctx.signal.aborted) {
+        return browserAnswer({
+            ctx,
+            state: CANCELLED_STATE,
+            headline: cancellationHeadline("nothing was submitted"),
+            notes: cancellationNotes("The form was left as it was.", "The browser session is still open and can still be used."),
+            data: { sessionId, ref, url: "", evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+        });
+    }
+    const found = await useSession(ctx.session.browserSessions(), sessionId);
+    if (!found.ok) {
+        return browserAnswer({
+            ctx,
+            state: found.dead.state,
+            headline: found.dead.headline,
+            notes: found.dead.notes,
+            data: { sessionId, ref, url: "", evidence: found.dead.evidence, graph: NO_GRAPH_WRITE },
+        });
+    }
+    const { entry } = found;
+    const refused = mutationRefusal(entry);
+    if (refused !== null) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `${entry.profile?.name ?? "This environment"} is read-only.`,
+            notes: [refused],
+            data: { sessionId, ref, url: entry.page.currentUrl(), evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+        });
+    }
+    try {
+        ctx.progress("Submitting");
+        await entry.page.submit(ref);
+    }
+    catch (error) {
+        if (error instanceof UnknownElementRefError || error instanceof NotSubmittableError) {
+            return browserAnswer({
+                ctx,
+                state: "refused",
+                headline: error instanceof UnknownElementRefError
+                    ? `"${ref}" is not an element in this session's current snapshot.`
+                    : `"${ref}" has nothing browser_submit can submit.`,
+                notes: [error.message],
+                data: { sessionId, ref, url: entry.page.currentUrl(), evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+            });
+        }
+        throw error;
+    }
+    const observed = await observeAndCorrelate(ctx, entry);
+    return browserAnswer({
+        ctx,
+        headline: `Submitting on ${entry.page.currentUrl()}.`,
+        notes: observed.notes,
+        data: { sessionId, ref, url: entry.page.currentUrl(), evidence: observed.evidence, graph: observed.graph },
+    });
+}
+export const browserSubmitTool = {
+    name: "browser_submit",
+    title: "submit the form an element sits in",
+    description: "Submit the form containing an element in an open browser session, named by a ref from a " +
+        "browser_snapshot reply. It goes through the form's own submit control, so the page's submit handler " +
+        "runs and the form's validation is not bypassed — a form the application would reject is rejected here " +
+        "too. An element in no form, or in a form with no submit control, is refused rather than guessed at: " +
+        "in the second case something else on the page submits it, and clicking that is the honest route. " +
+        "Refused when the session's environment profile declares safetyLevel \"readOnly\".",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    inputSchema: SCHEMA,
+    run,
+    describeAction: () => undefined,
+};
+//# sourceMappingURL=browser-submit.js.map

package/dist/tools/browser-submit.js.map

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

package/dist/tools/browser-wait-for.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `browser_wait_for`: wait until a named element is on the page, or say it never arrived.
+ *
+ * Every other verb waits for the page to settle *after* it acted. This is the one that waits
+ * before acting, and it exists because the alternative an agent reaches for otherwise is
+ * snapshotting in a loop, or acting immediately and reporting whatever half-rendered page it
+ * happened to catch.
+ *
+ * It is `stateful-read`, not `action`: it changes nothing about the application. What it does
+ * change is what a later call in the same session sees — it takes a fresh snapshot, and that
+ * invalidates every ref issued before it. That is the same reason `browser_snapshot` is
+ * stateful-read rather than a pure read, so a `readOnly` profile permits this exactly as it
+ * permits navigate and snapshot.
+ *
+ * A timeout is an outcome, never a failure: the reply carries `appeared: false` *and* the
+ * page as it stood, because "it did not appear" alone leaves the caller with nothing to do
+ * next but guess again.
+ */
+import type { BrowserEvidenceReport } from "../browser/evidence.ts";
+import { type BrowserGraphWrite } from "../browser/graph-write.ts";
+import type { SnapshotElement } from "../browser/driver.ts";
+import { type ToolDefinition } from "./kit.ts";
+export interface BrowserWaitForData {
+    readonly sessionId: string;
+    readonly appeared: boolean;
+    /** How long was actually spent waiting, in ms. Short on an element already there. */
+    readonly waitedMs: number;
+    /** The ceiling that applied, after clamping. A caller asking for more than the maximum sees the maximum here rather than what it asked for. */
+    readonly timeoutMs: number;
+    readonly matched: SnapshotElement | null;
+    /** How many elements satisfied the target. More than one is not an error — the question was whether it is there — but `matched` is then one of several. */
+    readonly matchCount: number;
+    readonly url: string;
+    /** The page when the wait ended, on both outcomes. Every ref from before this call is now stale. */
+    readonly elements: readonly SnapshotElement[];
+    readonly totalElements: number;
+    readonly evidence: BrowserEvidenceReport;
+    readonly graph: BrowserGraphWrite;
+}
+export declare const browserWaitForTool: ToolDefinition;
+//# sourceMappingURL=browser-wait-for.d.ts.map

package/dist/tools/browser-wait-for.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-wait-for.d.ts","sourceRoot":"","sources":["../../src/tools/browser-wait-for.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAqE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGlH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+IAA+I;IAC/I,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,2JAA2J;IAC3J,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAiID,eAAO,MAAM,kBAAkB,EAAE,cAehC,CAAC"}

package/dist/tools/browser-wait-for.js

@@ -0,0 +1,148 @@
+/**
+ * `browser_wait_for`: wait until a named element is on the page, or say it never arrived.
+ *
+ * Every other verb waits for the page to settle *after* it acted. This is the one that waits
+ * before acting, and it exists because the alternative an agent reaches for otherwise is
+ * snapshotting in a loop, or acting immediately and reporting whatever half-rendered page it
+ * happened to catch.
+ *
+ * It is `stateful-read`, not `action`: it changes nothing about the application. What it does
+ * change is what a later call in the same session sees — it takes a fresh snapshot, and that
+ * invalidates every ref issued before it. That is the same reason `browser_snapshot` is
+ * stateful-read rather than a pure read, so a `readOnly` profile permits this exactly as it
+ * permits navigate and snapshot.
+ *
+ * A timeout is an outcome, never a failure: the reply carries `appeared: false` *and* the
+ * page as it stood, because "it did not appear" alone leaves the caller with nothing to do
+ * next but guess again.
+ */
+import { browserAnswer, observeAndCorrelate, useSession } from "../browser/tool-support.js";
+import { NO_GRAPH_WRITE } from "../browser/graph-write.js";
+import { describeWaitTarget, isEmptyWaitTarget, WAIT_TIMEOUT_MAX_MS } from "../browser/wait-target.js";
+import { optionalInteger, optionalString, requiredString } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        sessionId: { type: "string", description: "REQUIRED. The id returned by browser_start_session." },
+        role: {
+            type: "string",
+            description: "The role to wait for, as browser_snapshot reports one — button, link, textbox, combobox, and so on. " +
+                "Give this, name, or both; at least one is required.",
+        },
+        name: {
+            type: "string",
+            description: "The element's name to wait for, as browser_snapshot reports it. Matched exactly, ignoring case and " +
+                "surrounding space — never as a substring, because a loose match would report that the thing you " +
+                "meant appeared when something merely similar did.",
+        },
+        timeoutMs: {
+            type: "integer",
+            minimum: 0,
+            description: `How long to wait at most, in ms. Defaults to 5000 and is capped at ${WAIT_TIMEOUT_MAX_MS}; the reply ` +
+                "says which ceiling actually applied. Running out is a normal answer, not an error — the reply then " +
+                "carries appeared: false together with the page as it stood, so you can see what is there instead.",
+        },
+    },
+    required: ["sessionId"],
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const sessionId = requiredString(args, "sessionId");
+    const role = optionalString(args, "role");
+    const name = optionalString(args, "name");
+    const timeoutMs = optionalInteger(args, "timeoutMs", 0);
+    const target = { ...(role === undefined ? {} : { role }), ...(name === undefined ? {} : { name }) };
+    const empty = () => ({
+        sessionId,
+        appeared: false,
+        waitedMs: 0,
+        timeoutMs: 0,
+        matched: null,
+        matchCount: 0,
+        url: "",
+        elements: [],
+        totalElements: 0,
+        evidence: { consoleErrors: [], failedRequests: [], pendingRequests: [], totalRequests: 0, actions: [], unsettled: [], evidenceWarnings: [] },
+        graph: NO_GRAPH_WRITE,
+    });
+    // Refused before the session is touched: a target naming nothing would match the first
+    // element on the page, and a caller that got "it appeared" from that learned nothing true.
+    if (isEmptyWaitTarget(target)) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: "browser_wait_for needs something to wait for.",
+            notes: [
+                `Give role, name, or both — ${describeWaitTarget(target)} was supplied. Waiting for nothing in ` +
+                    "particular would match whatever element happens to be first on the page, and report that as the " +
+                    "thing you were waiting for.",
+            ],
+            data: empty(),
+        });
+    }
+    const found = await useSession(ctx.session.browserSessions(), sessionId);
+    if (!found.ok) {
+        return browserAnswer({
+            ctx,
+            state: found.dead.state,
+            headline: found.dead.headline,
+            notes: found.dead.notes,
+            data: { ...empty(), evidence: found.dead.evidence },
+        });
+    }
+    const { entry } = found;
+    // No mutationRefusal here, deliberately: waiting changes nothing about the application, so
+    // a readOnly profile permits it exactly as it permits navigate and snapshot.
+    ctx.progress(`Waiting for ${describeWaitTarget(target)}`);
+    const outcome = await entry.page.waitFor(target, timeoutMs === undefined ? {} : { timeoutMs });
+    const observed = await observeAndCorrelate(ctx, entry);
+    const notes = [...observed.notes];
+    if (outcome.appeared) {
+        notes.push("This reply's snapshot is fresh, so any ref you were holding before this call is now stale — act on a " +
+            "ref from here.");
+        if (outcome.matchCount > 1) {
+            notes.push(`${outcome.matchCount} elements match ${describeWaitTarget(target)}; matched is the first of them. If ` +
+                "that is not the one you meant, narrow the target with the other field.");
+        }
+    }
+    else {
+        notes.push(`Nothing matching ${describeWaitTarget(target)} appeared within ${outcome.timeoutMs}ms. That is what the ` +
+            "page did, not a failure of the wait — the elements below are what it is showing instead.");
+    }
+    return browserAnswer({
+        ctx,
+        headline: outcome.appeared
+            ? `${describeWaitTarget(target)} is on ${outcome.snapshot.url}, after ${outcome.waitedMs}ms.`
+            : `${describeWaitTarget(target)} did not appear on ${outcome.snapshot.url} within ${outcome.timeoutMs}ms.`,
+        notes,
+        data: {
+            sessionId: entry.sessionId,
+            appeared: outcome.appeared,
+            waitedMs: outcome.waitedMs,
+            timeoutMs: outcome.timeoutMs,
+            matched: outcome.matched,
+            matchCount: outcome.matchCount,
+            url: outcome.snapshot.url,
+            elements: outcome.snapshot.elements,
+            totalElements: outcome.snapshot.totalElements,
+            evidence: observed.evidence,
+            graph: observed.graph,
+        },
+    });
+}
+export const browserWaitForTool = {
+    name: "browser_wait_for",
+    title: "wait for an element to appear",
+    description: "Wait until an element with a given role and/or name is on the page in an open browser session, or " +
+        "until a ceiling you set. Use it instead of snapshotting in a loop, and instead of acting immediately " +
+        "on a page that is still rendering. It changes nothing about the application, so a readOnly environment " +
+        "permits it — but it does take a fresh snapshot, which invalidates every ref issued before the call. " +
+        "Running out of time is a normal answer: the reply then says the element did not appear and hands back " +
+        "the page as it stood, so you can see what is there instead of guessing again.",
+    class: "stateful-read",
+    tier: "evidence",
+    version: "1.0.0",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=browser-wait-for.js.map

package/dist/tools/browser-wait-for.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-wait-for.js","sourceRoot":"","sources":["../../src/tools/browser-wait-for.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC5F,OAAO,EAAE,cAAc,EAA0B,MAAM,2BAA2B,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,mBAAmB,EAAsB,MAAM,2BAA2B,CAAC;AAC3H,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAyC,MAAM,UAAU,CAAC;AAqBlH,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qDAAqD,EAAE;QACjG,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,sGAAsG;gBACtG,qDAAqD;SACxD;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,qGAAqG;gBACrG,kGAAkG;gBAClG,mDAAmD;SACtD;QACD,SAAS,EAAE;YACT,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,WAAW,EACT,sEAAsE,mBAAmB,cAAc;gBACvG,qGAAqG;gBACrG,mGAAmG;SACtG;KACF;IACD,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,KAAK,UAAU,GAAG,CAAC,IAA6B,EAAE,GAAgB;IAChE,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAExD,MAAM,MAAM,GAAkB,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAEnH,MAAM,KAAK,GAAG,GAAuB,EAAE,CAAC,CAAC;QACvC,SAAS;QACT,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,CAAC;QACX,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,CAAC;QACb,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,EAAE;QACZ,aAAa,EAAE,CAAC;QAChB,QAAQ,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,gBAAgB,EAAE,EAAE,EAAE;QAC5I,KAAK,EAAE,cAAc;KACtB,CAAC,CAAC;IAEH,uFAAuF;IACvF,2FAA2F;IAC3F,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,OAAO,aAAa,CAAqB;YACvC,GAAG;YACH,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,+CAA+C;YACzD,KAAK,EAAE;gBACL,8BAA8B,kBAAkB,CAAC,MAAM,CAAC,wCAAwC;oBAC9F,kGAAkG;oBAClG,6BAA6B;aAChC;YACD,IAAI,EAAE,KAAK,EAAE;SACd,CAAC,CAAC;IACL,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,SAAS,CAAC,CAAC;IACzE,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,aAAa,CAAqB;YACvC,GAAG;YACH,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK;YACvB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;YAC7B,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK;YACvB,IAAI,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;SACpD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACxB,2FAA2F;IAC3F,6EAA6E;IAC7E,GAAG,CAAC,QAAQ,CAAC,eAAe,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/F,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAEvD,MAAM,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CACR,uGAAuG;YACrG,gBAAgB,CACnB,CAAC;QACF,IAAI,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CACR,GAAG,OAAO,CAAC,UAAU,mBAAmB,kBAAkB,CAAC,MAAM,CAAC,qCAAqC;gBACrG,wEAAwE,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CACR,oBAAoB,kBAAkB,CAAC,MAAM,CAAC,oBAAoB,OAAO,CAAC,SAAS,uBAAuB;YACxG,0FAA0F,CAC7F,CAAC;IACJ,CAAC;IAED,OAAO,aAAa,CAAqB;QACvC,GAAG;QACH,QAAQ,EAAE,OAAO,CAAC,QAAQ;YACxB,CAAC,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,UAAU,OAAO,CAAC,QAAQ,CAAC,GAAG,WAAW,OAAO,CAAC,QAAQ,KAAK;YAC7F,CAAC,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,sBAAsB,OAAO,CAAC,QAAQ,CAAC,GAAG,WAAW,OAAO,CAAC,SAAS,KAAK;QAC5G,KAAK;QACL,IAAI,EAAE;YACJ,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG;YACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ;YACnC,aAAa,EAAE,OAAO,CAAC,QAAQ,CAAC,aAAa;YAC7C,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAChD,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,+BAA+B;IACtC,WAAW,EACT,oGAAoG;QACpG,uGAAuG;QACvG,yGAAyG;QACzG,sGAAsG;QACtG,wGAAwG;QACxG,+EAA+E;IACjF,KAAK,EAAE,eAAe;IACtB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,MAAM;IACnB,GAAG;CACJ,CAAC"}

package/dist/tools/chain.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `chain` — RG-9's five-hop user chain (click → request → endpoint → route →
+ * handler → line) as one MCP call. `impact`/`propagation` each answer one
+ * hop's worth of question; nothing before this walked all five in one call
+ * with a computed completeness verdict, so "chain complete" was a mockup
+ * string rather than a field.
+ *
+ * Two disclosed degradations carried through from `traceUserChain`
+ * (`@descryy/core`): the browser→endpoint hop only exists when the browser
+ * session that produced it was started with a `stackParser`
+ * (`browser_start_session`); and the route→handler hop ships for
+ * express/koa-router/fastify/hono/the Next.js App Router today, TypeScript
+ * only. Neither is a language check here — this tool walks whatever edges
+ * the graph holds and reports what it finds.
+ */
+import { type ChainStageName } from "@descryy/core";
+import { type BriefNode, type NodeCandidates, type ToolDefinition } from "./kit.ts";
+/** One named point in the chain, as reported to a caller. */
+export interface ChainStageReport {
+    readonly name: ChainStageName;
+    readonly present: boolean;
+    /** Omitted, not null, wherever the stage carries no node of its own
+     *  ("request" — no node type for an HTTP request; "line" — a location on
+     *  the handler, not a separate node) or is missing. */
+    readonly node?: BriefNode;
+    /** Set iff `!present`. */
+    readonly reason?: string;
+}
+export interface ChainReport {
+    readonly origin: BriefNode;
+    readonly stages: readonly ChainStageReport[];
+    readonly verdict: "complete" | "partial";
+    readonly missingStage: ChainStageName | null;
+    readonly location: {
+        readonly file: string;
+        readonly startLine: number;
+    } | null;
+}
+export type ChainData = ChainReport | NodeCandidates;
+export declare const chainTool: ToolDefinition;
+//# sourceMappingURL=chain.d.ts.map

package/dist/tools/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/tools/chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAErF,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,cAAc,EAEnB,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAIlB,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;2DAEuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjF;AAED,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,cAAc,CAAC;AAmFrD,eAAO,MAAM,SAAS,EAAE,cAevB,CAAC"}

package/dist/tools/chain.js

@@ -0,0 +1,105 @@
+/**
+ * `chain` — RG-9's five-hop user chain (click → request → endpoint → route →
+ * handler → line) as one MCP call. `impact`/`propagation` each answer one
+ * hop's worth of question; nothing before this walked all five in one call
+ * with a computed completeness verdict, so "chain complete" was a mockup
+ * string rather than a field.
+ *
+ * Two disclosed degradations carried through from `traceUserChain`
+ * (`@descryy/core`): the browser→endpoint hop only exists when the browser
+ * session that produced it was started with a `stackParser`
+ * (`browser_start_session`); and the route→handler hop ships for
+ * express/koa-router/fastify/hono/the Next.js App Router today, TypeScript
+ * only. Neither is a language check here — this tool walks whatever edges
+ * the graph holds and reports what it finds.
+ */
+import { traceUserChain } from "@descryy/core";
+import { briefNode, optionalString, ToolInputError, } from "./kit.js";
+import { resolveOneNode } from "./lookup.js";
+function reportStage(stage) {
+    return {
+        name: stage.name,
+        present: stage.present,
+        ...(stage.node === null ? {} : { node: briefNode(stage.node) }),
+        ...(stage.reason === null ? {} : { reason: stage.reason }),
+    };
+}
+const SCHEMA = {
+    type: "object",
+    properties: {
+        nodeId: { type: "string", description: "Graph node id to start the chain from — the click's origin." },
+        symbol: {
+            type: "string",
+            description: "Symbol name to start from (a COMPONENT, PAGE or FUNCTION), when you do not have a node id. " +
+                "Ambiguity is reported rather than guessed at — narrow it with \"file\".",
+        },
+        file: {
+            type: "string",
+            description: "Repository-relative path, to disambiguate \"symbol\" or to start from a file.",
+        },
+    },
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const nodeId = optionalString(args, "nodeId");
+    const symbol = optionalString(args, "symbol");
+    const file = optionalString(args, "file");
+    if (nodeId === undefined && symbol === undefined && file === undefined) {
+        throw new ToolInputError('give one of "nodeId", "symbol" or "file"');
+    }
+    const provider = ctx.session.provider();
+    const found = resolveOneNode(ctx.session, { nodeId, symbol, file });
+    if (found.node === null) {
+        const base = provider.baseStamp();
+        return {
+            result: {
+                data: { candidates: found.candidates.map(briefNode) },
+                stamp: { ...base, resolutionFloor: 0 },
+                truncated: false,
+                notes: found.notes,
+            },
+            nameLevel: true,
+            state: "refused",
+            headline: found.headline,
+        };
+    }
+    ctx.progress(`Walking the chain from ${found.node.name}`);
+    const chain = traceUserChain(provider, found.node.id);
+    const notes = [...found.notes, ...chain.notes];
+    return {
+        result: {
+            data: {
+                origin: briefNode(chain.data.origin),
+                stages: chain.data.stages.map(reportStage),
+                verdict: chain.data.verdict,
+                missingStage: chain.data.missingStage,
+                location: chain.data.location,
+            },
+            stamp: chain.stamp,
+            truncated: chain.truncated,
+            notes,
+        },
+        nameLevel: true,
+        ...(chain.data.verdict === "partial" ? { state: "refused" } : {}),
+        headline: chain.data.verdict === "complete"
+            ? `Chain complete: ${found.node.name} reaches ${chain.data.location?.file ?? "its handler"}` +
+                `${chain.data.location === null ? "" : `:${chain.data.location.startLine}`}.`
+            : `Chain incomplete at "${chain.data.missingStage}" — see stages for what is missing and why.`,
+    };
+}
+export const chainTool = {
+    name: "chain",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "The click-to-line chain: click, request, endpoint, route, handler, line",
+    description: "Given a COMPONENT, PAGE or FUNCTION, walks click → request → endpoint → route → handler → " +
+        "line as one traversal and reports a computed completeness verdict: \"complete\", or " +
+        "\"partial\" naming which hop is missing and why. Never assumes complete. Two disclosed " +
+        "degradations: the browser→endpoint hop needs a stackParser on browser_start_session to exist " +
+        "at all, and route→handler is produced only by a narrow set of adapters and frameworks today " +
+        "— outside that reach this tool still runs, it will just name \"handler\" as missing.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=chain.js.map

package/dist/tools/chain.js.map

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

package/dist/tools/draw-conclusion.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `draw_conclusion` — RG-8(a): routes evidence and a graph path through the real finding
+ * funnel (`@descryy/ir`'s G3/G4 gate, `packages/ir/src/finding.ts`) and returns a governed
+ * category, in the same five-category vocabulary (`ReportCategory`) the desktop's pipeline
+ * uses — not a raw evidence tally the caller has to interpret itself.
+ *
+ * This closes the open half of the `FINDING_CAPS` ruling: until this tool existed, nothing on
+ * the MCP surface ever called `reportCategory` — `observe_runtime` writes R4 facts and reports
+ * evidence counts, but never gates them into a category. An MCP client reading `observe_runtime`'s
+ * reply was, at most, "reading the evidence back" — this tool is what makes "the finding" an
+ * honest word for what MCP returns.
+ *
+ * **What this tool does not do.** It does not draw its own graph path or gather its own runtime
+ * evidence — those come from the caller, who already holds them from `impact`/`propagation` (a
+ * `GraphPathHop[]`) and `observe_runtime`/the browser tools (runtime observations). This tool is
+ * the gate alone: the same `reportCategory` arithmetic the architecture specifies, called once,
+ * from one place, so a category MCP returns and a category the desktop's pipeline computes are
+ * never two independently-typed re-implementations agreeing by coincidence.
+ *
+ * `class: "read"` — same as this server's other three conclusion tools (`validate`, `contracts`,
+ * `cross_pr`): it changes nothing and mints no token. A category computed from evidence the
+ * caller already supplied is a read over that evidence, not a new write against the target.
+ */
+import { type ResolutionLevel } from "@descryy/ir";
+import { type ToolDefinition } from "./kit.ts";
+export interface DrawConclusionData {
+    readonly failurePoint: string;
+    /** §19's five-category vocabulary — the same `ReportCategory` the desktop's report surface renders. */
+    readonly category: string;
+    /** The class (A/B/C) that capped it — rule 3, `reliabilityCap`. */
+    readonly reliabilityClass: string;
+    /** Step 2 alone, uncapped by the structural path — how strongly the evidence says the failure is real. */
+    readonly existence: string;
+    readonly resolution: ResolutionLevel;
+    readonly independentSignalTypes: number;
+    readonly directMechanismEvidence: boolean;
+    readonly hasRuntimeEvidence: boolean;
+    readonly humanAsserted: boolean;
+    /** Echoed back only when the caller supplied one — see the schema's own doc for why this is
+     *  inert unless a future call also names `requireReproductionForConfirmed`. */
+    readonly reproductionCount: number | null;
+}
+export declare const drawConclusionTool: ToolDefinition;
+//# sourceMappingURL=draw-conclusion.d.ts.map

package/dist/tools/draw-conclusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draw-conclusion.d.ts","sourceRoot":"","sources":["../../src/tools/draw-conclusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAWL,KAAK,eAAe,EAGrB,MAAM,aAAa,CAAC;AAErB,OAAO,EAA8F,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAG3I,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uGAAuG;IACvG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,0GAA0G;IAC1G,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;mFAC+E;IAC/E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAwND,eAAO,MAAM,kBAAkB,EAAE,cAgBhC,CAAC"}