@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/browser-start-session.js

@@ -0,0 +1,653 @@
+/**
+ * `browser_start_session` — opens a real browser (DEC-380: consent lives here only,
+ * bound to the target URL's origin — `browser_navigate` refuses to leave it). Class
+ * `action`: the only browser tool that mints a token; the verbs it consents for
+ * redeem nothing, since the session is already confirmed. */
+import { CANCELLED_STATE, cancellationHeadline, cancellationNotes } from "../cancellation.js";
+import { browserAnswer, emptyEvidence, observeAndCorrelate, reachNotes } from "../browser/tool-support.js";
+import { NO_GRAPH_WRITE } from "../browser/graph-write.js";
+import { isAbsolute, join } from "node:path";
+import { runPreflight } from "@descryy/runtime-controller";
+import { loadStackParser, StackParserLoadError } from "../browser/stack-parser.js";
+import { headerSecrets, loadStorageStateFile, parseStorageStateJson, resolveSavePath, storageStateSecrets } from "../browser/auth.js";
+import { checkUrlScheme } from "../browser/url-scheme.js";
+import { buildBrowserToolReadyChecks } from "../ready-checks.js";
+import { optionalBoolean, optionalEnum, optionalString, requiredString, ToolInputError } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        targetUrl: {
+            type: "string",
+            description: "REQUIRED. The URL to open, including scheme and port — \"http://localhost:3000/invoices\". " +
+                "This is also what consent is granted for: the browser may be driven anywhere on this URL's " +
+                "origin for the life of the session, and navigating off it refuses rather than asking again.",
+        },
+        headless: {
+            type: "boolean",
+            description: "Run without a visible window. Defaults to true; pass false to watch it happen.",
+        },
+        stackParser: {
+            type: "object",
+            description: "The module that can parse this application's stack traces, named the way observe_runtime names a " +
+                "runtime adapter. Without one, requests are still observed and the endpoints they reached are still " +
+                "named, but NO frontend→backend caller edge is written — a parsed call site is what the confirmation " +
+                "needs, and there is no way to guess one. The reply says so rather than reporting a run that found " +
+                "nothing.\n\n" +
+                'WORKED EXAMPLE: the module to name is "@descryy/runtime-adapter-<language>" — one such package ' +
+                "exists per frontend language (never guess a name; a wrong one refuses rather than silently doing " +
+                'nothing), each exporting a single "create<Name>StackTraceParser" factory, so most calls need only ' +
+                '{ "module": "@descryy/runtime-adapter-<language>" } with no "export". Pick the package matching the ' +
+                "language the *frontend* is written in, not the backend. The intuitively-named " +
+                "@descryy/runtime-browser is never the right answer here — despite the name, it exports no " +
+                'stack-trace parser at all. A package exporting more than one factory (one per web framework it ' +
+                'covers) requires "export" to say which.',
+            properties: {
+                module: { type: "string", description: "Module specifier to import, e.g. a runtime adapter package for the language your frontend is written in." },
+                export: { type: "string", description: "Named export to call. Defaults to the module's single create*StackTraceParser factory; two matches is an error rather than a guess." },
+            },
+            required: ["module"],
+            additionalProperties: false,
+        },
+        documentRoot: {
+            type: "string",
+            description: "The directory on disk that the target URL's origin serves files from, if it is not the repository " +
+                "root. Absolute, or relative to the repository. THIS IS THE ONE THAT SILENTLY BREAKS THE ARROW: a " +
+                "server that serves scripts out of \"public/\" makes public/ the document root while the repo root is " +
+                "one level above it, and getting it wrong resolves a script URL to a path that does not exist, which " +
+                "degrades the call-site stack to nothing and produces a run that looks clean and confirmed no edges. " +
+                "Defaults to the repository root.",
+        },
+        environment: {
+            type: "object",
+            description: "The environment profile this session runs against, if you have one. Its safetyLevel governs " +
+                "whether the session may change the application: \"readOnly\" refuses browser_click, browser_type " +
+                "and browser_fill while still permitting browser_navigate and browser_snapshot. Declared once here " +
+                "rather than per call, and it is the same profile observe_runtime takes — a browser run and a " +
+                "runtime run must not hold two different opinions about the same environment (DEC-270). Omit it and " +
+                "the session's own consent is the only authorization, which still means this call had to be confirmed.",
+            properties: {
+                name: { type: "string", description: "The profile's name, free-form. Named back to you in any refusal it causes." },
+                safetyLevel: {
+                    type: "string",
+                    enum: ["readOnly", "write", "destructiveWithApproval"],
+                    description: "\"readOnly\" refuses every action that could change the application, whatever the profile is " +
+                        "called — a profile named \"local\" with safetyLevel \"readOnly\" is read-only too.",
+                },
+            },
+            required: ["name", "safetyLevel"],
+            additionalProperties: true,
+        },
+        storageState: {
+            type: "object",
+            description: "11.4-b: an already-authenticated session to seed before the first navigation. Without this, " +
+                "browser_click/type/fill can drive a login form within the consented origin, but cannot reach a " +
+                "screen that requires an existing session, and every fresh session re-authenticates from scratch. " +
+                "Both fields are scoped to targetUrl's own origin by construction — there is no way to name a " +
+                "second origin here, so this cannot widen the session's consent.",
+            properties: {
+                cookies: {
+                    type: "array",
+                    description: "Cookies to set before navigating, scoped to targetUrl's own origin.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            value: { type: "string" },
+                            path: { type: "string", description: "Defaults to \"/\"." },
+                            httpOnly: { type: "boolean" },
+                            secure: { type: "boolean" },
+                            sameSite: { type: "string", enum: ["Strict", "Lax", "None"] },
+                        },
+                        required: ["name", "value"],
+                        additionalProperties: false,
+                    },
+                },
+                localStorage: {
+                    type: "object",
+                    description: "localStorage entries to set for targetUrl's own origin before navigating, as string values.",
+                    additionalProperties: { type: "string" },
+                },
+            },
+            additionalProperties: false,
+        },
+        storageStatePath: {
+            type: "string",
+            description: "A FILE holding a saved browser storage state, instead of naming cookies inline. Absolute, or " +
+                "relative to the repository root. This is the practical way to reach a logged-in screen: start one " +
+                "session with headless false and saveStorageStateTo, log in by hand, close it — every later session " +
+                "seeds from that file and nobody logs in again. Anything in the file outside this session's " +
+                "consented origin is REFUSED by name, not quietly dropped.",
+        },
+        storageStateCredential: {
+            type: "string",
+            description: "The NAME of a credential holding a saved browser storage state (the same JSON shape " +
+                "storageStatePath reads: a \"cookies\" array and an \"origins\" array), instead of a file on disk. " +
+                "Reused a logged-in session without a login-form step or a live file. Set with `descry credential " +
+                "set <name>`, reading the JSON from stdin. Refuses by name when no credential store is configured on " +
+                "this server, when nothing is stored under the name, or when the value isn't a storage state this " +
+                "session's origin can use — never quietly falls back to an unauthenticated session. Anything in it " +
+                "outside this session's consented origin is REFUSED by name, not quietly dropped, exactly as " +
+                "storageStatePath's own file check does.",
+        },
+        extraHttpHeaders: {
+            type: "object",
+            description: "Headers added to every request this session makes TO THE CONSENTED ORIGIN — typically " +
+                "{\"Authorization\": \"Bearer ...\"} for an application whose credential is a token rather than a " +
+                "cookie. Deliberately NOT sent to any other host: headers set on a whole browser travel with every " +
+                "request it makes, which on an ordinary page means handing your token to every third-party script, " +
+                "font and analytics endpoint the page loads.",
+            additionalProperties: { type: "string" },
+        },
+        saveStorageStateTo: {
+            type: "string",
+            description: "Write this session's cookies and stored data to this file when the session closes, so a login done " +
+                "once here can seed later sessions with storageStatePath. Must be an ABSOLUTE PATH OUTSIDE THE " +
+                "REPOSITORY — the file is a live credential, and one written into a working tree is one `git add .` " +
+                "from being committed.",
+        },
+        confirmToken: {
+            type: "string",
+            description: "The token returned by a previous call. Starting a browser session takes two calls: the first " +
+                "returns a token and launches nothing, the second redeems it — with the arguments frozen when the " +
+                "token was minted, never whatever the second call supplies, so changing targetUrl, stackParser or " +
+                "any other field on the confirming call is discarded rather than applied, and the reply discloses " +
+                "that it was; call again without confirmToken for a fresh " +
+                "token if something needs to change. A token is single-use, expires, and is only valid for this " +
+                "tool. Consent is granted once here — the click, type and fill tools need no token of their own.",
+        },
+    },
+    required: ["targetUrl"],
+    additionalProperties: false,
+};
+const SAFETY_LEVELS = ["readOnly", "write", "destructiveWithApproval"];
+/** Reads the profile, doesn't re-derive it — only the 2 fields this surface consults.
+ *  `additionalProperties: true` lets a caller pass the same object it gives
+ *  `observe_runtime` without trimming a second copy. */
+function readProfile(args) {
+    const raw = args["environment"];
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw new ToolInputError('"environment" must be an object');
+    const fields = raw;
+    const name = requiredString(fields, "name");
+    const safetyLevel = optionalEnum(fields, "safetyLevel", SAFETY_LEVELS);
+    if (safetyLevel === undefined) {
+        throw new ToolInputError('"environment.safetyLevel" is required when an environment is given — a profile with no declared ' +
+            "safety level would be read as permitting everything, which is the one reading it must never get by default");
+    }
+    return { name, safetyLevel };
+}
+const COOKIE_SAME_SITE = ["Strict", "Lax", "None"];
+/**
+ * 11.4-b: an already-authenticated session to seed before the first navigation.
+ * No "domain" field is read from a cookie — not merely ignored, refused — so a
+ * caller cannot silently widen a session's consent to a second origin the way
+ * accepting and dropping one would risk if a future reader trusted the field
+ * existed. The driver scopes every seeded cookie to `targetUrl`'s own origin.
+ */
+function readStorageState(args) {
+    const raw = args["storageState"];
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw new ToolInputError('"storageState" must be an object');
+    const fields = raw;
+    const rawCookies = fields["cookies"];
+    let cookies;
+    if (rawCookies !== undefined) {
+        if (!Array.isArray(rawCookies))
+            throw new ToolInputError('"storageState.cookies" must be an array');
+        cookies = rawCookies.map((entry, index) => {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+                throw new ToolInputError(`"storageState.cookies[${index}]" must be an object`);
+            }
+            const cookie = entry;
+            if ("domain" in cookie) {
+                throw new ToolInputError(`"storageState.cookies[${index}].domain" is not accepted — a seeded cookie is always scoped to ` +
+                    "targetUrl's own origin, never a domain the caller names, so a session's consent cannot be " +
+                    "silently widened to a second origin.");
+            }
+            const name = requiredString(cookie, "name");
+            const value = requiredString(cookie, "value");
+            const path = optionalString(cookie, "path");
+            const httpOnly = optionalBoolean(cookie, "httpOnly");
+            const secure = optionalBoolean(cookie, "secure");
+            const sameSite = optionalEnum(cookie, "sameSite", COOKIE_SAME_SITE);
+            return {
+                name,
+                value,
+                ...(path === undefined ? {} : { path }),
+                ...(httpOnly === undefined ? {} : { httpOnly }),
+                ...(secure === undefined ? {} : { secure }),
+                ...(sameSite === undefined ? {} : { sameSite }),
+            };
+        });
+    }
+    const rawLocalStorage = fields["localStorage"];
+    let localStorage;
+    if (rawLocalStorage !== undefined) {
+        if (typeof rawLocalStorage !== "object" || rawLocalStorage === null || Array.isArray(rawLocalStorage)) {
+            throw new ToolInputError('"storageState.localStorage" must be an object of string values');
+        }
+        for (const [key, value] of Object.entries(rawLocalStorage)) {
+            if (typeof value !== "string")
+                throw new ToolInputError(`"storageState.localStorage.${key}" must be a string`);
+        }
+        localStorage = rawLocalStorage;
+    }
+    if (cookies === undefined && localStorage === undefined)
+        return null;
+    return { ...(cookies === undefined ? {} : { cookies }), ...(localStorage === undefined ? {} : { localStorage }) };
+}
+/**
+ * Resolves `storageStateCredential` against `Session.credentialStore` — the smaller of the two
+ * reuse mechanisms RG-1(4)'s "signin" lane chose to build (the other, wiring
+ * `BrowserPageSession.injectStorageState` into scenario replay, would need a new step kind in
+ * the scenario schema and its own projection/replay path; this reuses the storage-state
+ * machinery `loadStorageStateFile` already established for the file case).
+ *
+ * Same refusal discipline as a missing/malformed file: named, before anything launches, never a
+ * silent fall-through to an unauthenticated session.
+ */
+async function readStorageStateCredential(name, origin, ctx) {
+    if (ctx.session.credentialStore === undefined) {
+        throw new ToolInputError(`"storageStateCredential" named "${name}", but no credential store is configured on this server. Set one ` +
+            'up and store the value with `descry credential set ${name}` (piped through stdin, never typed as an ' +
+            "argument), reading the JSON that a session started with saveStorageStateTo already wrote.");
+    }
+    const value = await ctx.session.credentialStore.retrieve(name);
+    if (value === null) {
+        throw new ToolInputError(`"storageStateCredential" named "${name}", and nothing is stored under that name. Store a saved storage ` +
+            `state there first: start a session with headless false and saveStorageStateTo, log in by hand, close ` +
+            `it, then \`descry credential set ${name}\` < that file.`);
+    }
+    if (value === "") {
+        throw new ToolInputError(`the credential "${name}" is stored and empty. An empty storage state is refused rather than used — it ` +
+            "would seed a session with nothing, which reads as an ordinary logged-out run rather than the " +
+            "misconfiguration it actually is.");
+    }
+    return parseStorageStateJson(value, `credential "${name}"`, { consentedOrigin: origin, repoPath: ctx.session.repoPath });
+}
+/**
+ * Extra headers, or null. Values are checked but never echoed.
+ */
+function readExtraHttpHeaders(args) {
+    const raw = args["extraHttpHeaders"];
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw new ToolInputError('"extraHttpHeaders" must be an object');
+    const headers = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (typeof value !== "string")
+            throw new ToolInputError(`"extraHttpHeaders.${name}" must be a string`);
+        headers[name] = value;
+    }
+    if (Object.keys(headers).length === 0)
+        throw new ToolInputError('"extraHttpHeaders" was given with no headers in it');
+    return headers;
+}
+function readStackParserSpec(args) {
+    const raw = args["stackParser"];
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw new ToolInputError('"stackParser" must be an object');
+    const fields = raw;
+    const module = requiredString(fields, "module");
+    const named = optionalString(fields, "export");
+    return named === undefined ? { module } : { module, export: named };
+}
+function parseTarget(args) {
+    const raw = requiredString(args, "targetUrl");
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new ToolInputError(`"targetUrl" must be an absolute URL including scheme — got "${raw}". A bare host or path cannot be ` +
+            "opened, and cannot be turned into the origin this session's consent is bound to.");
+    }
+    // file:/data: (untrusted schemes) resolve to origin "null", collapsing
+    // tool-support.ts's same-origin containment — see url-scheme.ts.
+    const scheme = checkUrlScheme(url);
+    if (!scheme.allowed)
+        throw new ToolInputError(scheme.reason);
+    return url;
+}
+function cancelledBeforeLaunch(ctx, target, safetyLevel) {
+    return browserAnswer({
+        ctx,
+        state: CANCELLED_STATE,
+        headline: cancellationHeadline("no browser session is open"),
+        notes: cancellationNotes("No browser was left running.", "If a browser had already opened when the cancellation arrived, it has been closed and whatever it " +
+            "had observed was flushed with it."),
+        data: {
+            sessionId: "",
+            url: target.href,
+            title: "",
+            consentedOrigin: target.origin,
+            safetyLevel,
+            totalElements: 0,
+            evidence: emptyEvidence(),
+            graph: NO_GRAPH_WRITE,
+        },
+    });
+}
+async function run(args, ctx) {
+    const target = parseTarget(args);
+    const headless = optionalBoolean(args, "headless") ?? true;
+    const profile = readProfile(args);
+    const inlineState = readStorageState(args);
+    const statePath = optionalString(args, "storageStatePath");
+    const stateCredential = optionalString(args, "storageStateCredential");
+    const stateSourcesGiven = [inlineState !== null, statePath !== undefined, stateCredential !== undefined].filter(Boolean).length;
+    if (stateSourcesGiven > 1) {
+        throw new ToolInputError('"storageState", "storageStatePath" and "storageStateCredential" — more than one was given. There is no ' +
+            "precedence rule between them on purpose — picking one silently is how a session ends up seeded from a " +
+            "source the caller believed they had overridden. Give exactly one.");
+    }
+    // Read before anything launches, for the same reason the stack parser below
+    // is: an unreadable file, an unresolvable credential, or a cookie for
+    // another host is a refusal the caller can fix, and discovering it after a
+    // browser is open would mean a session that silently drove the logged-out
+    // surface instead.
+    const storageState = statePath !== undefined
+        ? loadStorageStateFile(statePath, { consentedOrigin: target.origin, repoPath: ctx.session.repoPath })
+        : stateCredential !== undefined
+            ? await readStorageStateCredential(stateCredential, target.origin, ctx)
+            : inlineState;
+    const extraHttpHeaders = readExtraHttpHeaders(args);
+    const rawSavePath = optionalString(args, "saveStorageStateTo");
+    const saveStorageStateTo = rawSavePath === undefined ? undefined : resolveSavePath(rawSavePath, ctx.session.repoPath);
+    // Registered before the launch, not after: if the launch throws, these are
+    // still the values anything this server writes must refuse to carry.
+    ctx.session.noteBrowserSecrets([...storageStateSecrets(storageState), ...headerSecrets(extraHttpHeaders)]);
+    const parserSpec = readStackParserSpec(args);
+    const documentRoot = optionalString(args, "documentRoot");
+    const backend = ctx.session.browserBackend();
+    // Before anything launches — a browser opened for a caller who's already gone is
+    // one nothing will ever close (its session id never reaches a suppressed reply);
+    // only the 5-minute idle reaper would eventually catch it.
+    if (ctx.signal.aborted)
+        return cancelledBeforeLaunch(ctx, target, null);
+    if (!backend.available) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: "This build cannot open a browser.",
+            notes: [backend.reason, `Remedy: ${backend.remedy}`],
+            data: { sessionId: "", url: target.href, title: "", consentedOrigin: target.origin, safetyLevel: null, totalElements: 0, evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+        });
+    }
+    // Parser loaded before anything launches — a bad parser is a fixable refusal here;
+    // discovering it after a browser is open means tearing it down or running a
+    // session that silently can't write the edge it opened for.
+    let parser;
+    try {
+        parser = parserSpec === null ? undefined : await loadStackParser(parserSpec);
+    }
+    catch (error) {
+        if (!(error instanceof StackParserLoadError))
+            throw error;
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `Could not load the stack-trace parser "${error.specifier}".`,
+            notes: [error.message],
+            data: { sessionId: "", url: target.href, title: "", consentedOrigin: target.origin, safetyLevel: null, totalElements: 0, evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+        });
+    }
+    // Closed here rather than left to a caller: the origin driven must map to
+    // the directory actually serving its scripts — `documentRoot` overrides the repo
+    // root for the `public/` case the schema describes.
+    const servedFrom = documentRoot === undefined
+        ? ctx.session.repoPath
+        : isAbsolute(documentRoot)
+            ? documentRoot
+            : join(ctx.session.repoPath, documentRoot);
+    const resolveSourceRoot = (origin) => origin === target.origin
+        ? { found: true, root: { serviceName: ctx.session.config.repo, declaredCwd: servedFrom } }
+        : { found: false, refusal: "noProcessOnPort", message: `${origin} is not the origin this session was opened against` };
+    ctx.progress(`Opening a browser at ${target.href}`);
+    const driver = await backend.createDriver({
+        ...(parser === undefined ? {} : { stackParser: parser }),
+        resolveSourceRoot,
+        service: ctx.session.config.repo,
+    });
+    // RT-263: ready check before a real Chromium is spent learning the same thing the
+    // slow way -- the "the port is free, or the app answers (for attach)" bullet of
+    // Build A. Every `browser_start_session` call is the attach case: this tool never
+    // boots a service of its own, it only opens a browser against one the caller says
+    // is already running. Optional on the port (`driver.probeTargetReachable`) so the
+    // fake driver `packages/mcp/test`'s suites use -- pointed at made-up ports nothing
+    // really listens on -- never runs a real network probe; only the real Chromium
+    // driver (`playwright-driver.ts`) implements it.
+    const reachability = await driver.probeTargetReachable?.(target.href);
+    if (reachability !== undefined && reachability !== null && !reachability.reachable) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `Cannot open a browser session at ${target.href} — the target does not answer.`,
+            notes: [reachability.message],
+            data: { sessionId: "", url: target.href, title: "", consentedOrigin: target.origin, safetyLevel: null, totalElements: 0, evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+        });
+    }
+    const ready = await runPreflight(buildBrowserToolReadyChecks(ctx.session));
+    if (ready.status === "broken") {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `Cannot open a browser session at ${target.href} — the environment is not ready.`,
+            notes: ready.checks.filter((check) => check.required && !check.ok).map((check) => `${check.label} — ${check.message}`),
+            data: { sessionId: "", url: target.href, title: "", consentedOrigin: target.origin, safetyLevel: null, totalElements: 0, evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+        });
+    }
+    const opened = await ctx.session.browserSessions().open(driver, {
+        targetUrl: target.href,
+        headless,
+        profile,
+        ...(storageState === null ? {} : { storageState }),
+        ...(extraHttpHeaders === null ? {} : { extraHttpHeaders }),
+        ...(saveStorageStateTo === undefined ? {} : { saveStorageStateTo }),
+    });
+    if (!opened.opened) {
+        const notes = opened.kind === "atCapacity"
+            ? [opened.reason]
+            : // Remedy travels verbatim — "could not launch" and stopping there is a
+                // refusal the developer has to go research themselves.
+                [opened.message, `Remedy: ${opened.remedy}`, `Expected the browser at ${opened.expectedExecutablePath}.`];
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: opened.kind === "atCapacity" ? "Too many browser sessions are already open." : "No browser is installed.",
+            notes,
+            data: { sessionId: "", url: target.href, title: "", consentedOrigin: target.origin, safetyLevel: profile?.safetyLevel ?? null, totalElements: 0, evidence: emptyEvidence(), graph: NO_GRAPH_WRITE },
+        });
+    }
+    // The race actually lost in practice: caller cancelled while Chromium was
+    // starting, so the launch succeeded for nobody. Closes the session just opened
+    // — the one resource this call started, the only one it may tear down.
+    if (ctx.signal.aborted) {
+        await ctx.session.browserSessions().close(opened.entry.sessionId);
+        return cancelledBeforeLaunch(ctx, target, profile?.safetyLevel ?? null);
+    }
+    const { entry } = opened;
+    const snapshot = await entry.page.snapshot();
+    const observed = await observeAndCorrelate(ctx, entry);
+    const evidence = observed.evidence;
+    return browserAnswer({
+        ctx,
+        headline: `Browser session ${entry.sessionId} open at ${snapshot.url} (${snapshot.totalElements} elements).`,
+        notes: [
+            ...ready.disclosures,
+            ...reachNotes(snapshot),
+            `Consent covers ${entry.consentedOrigin} for the life of this session — click, type and fill need no ` +
+                "further confirmation, and navigating to another origin will refuse. The session is torn down after " +
+                "five idle minutes, when the client disconnects, or when browser_close_session is called.",
+            // Names what was seeded, never the values themselves — a cookie or localStorage
+            // value is a credential, and this disclosure exists so a caller can tell an
+            // authenticated run from an anonymous one without this reply repeating it back.
+            ...(storageState === null
+                ? []
+                : [
+                    `Storage state was seeded before the first navigation: ${storageState.cookies?.length ?? 0} ` +
+                        `cookie(s), ${Object.keys(storageState.localStorage ?? {}).length} localStorage key(s) — both ` +
+                        `scoped to ${entry.consentedOrigin}. No value is printed here or kept in this session's ` +
+                        "recorded arguments.",
+                ]),
+            ...(extraHttpHeaders === null
+                ? []
+                : [
+                    `Extra request header(s) ${Object.keys(extraHttpHeaders).join(", ")} will be sent on ` +
+                        `${entry.consentedOrigin} and on no other host — a credential set on the whole browser would ` +
+                        "travel to every third-party script the page loads. Values are not printed.",
+                ]),
+            ...(saveStorageStateTo === undefined
+                ? []
+                : [
+                    `This session's cookies and stored data will be written to ${saveStorageStateTo} when it closes, ` +
+                        "so a login performed here can seed later sessions with storageStatePath. That file is a live " +
+                        "credential; it is outside the repository for that reason.",
+                ]),
+            // Rule 7: an unauthenticated run is a real, disclosed limit on what was
+            // tested, not a neutral default to leave a caller to infer from silence.
+            ...(storageState === null && extraHttpHeaders === null
+                ? [
+                    "No authentication material was given, so this session sees what a logged-out visitor sees. " +
+                        "Anything behind a login was not reached and is not reported on — pass storageStatePath, " +
+                        "storageState or extraHttpHeaders to reach it.",
+                ]
+                : []),
+            ...(parserSpec === null
+                ? [
+                    "No stackParser was named, so requests will be observed and the endpoints they reach will be " +
+                        "named, but no frontend→backend caller edge can be written from this session. That is a gap " +
+                        "in what this run can confirm, not a finding about your application.",
+                ]
+                : []),
+            ...(entry.profile === null
+                ? []
+                : [
+                    `Running under environment profile "${entry.profile.name}" (safetyLevel ` +
+                        `"${entry.profile.safetyLevel}").` +
+                        (entry.profile.safetyLevel === "readOnly"
+                            ? " Clicking, typing and filling will be refused; navigate and snapshot remain available."
+                            : ""),
+                ]),
+            ...observed.notes,
+        ],
+        data: {
+            sessionId: entry.sessionId,
+            url: snapshot.url,
+            title: snapshot.title,
+            consentedOrigin: entry.consentedOrigin,
+            safetyLevel: entry.profile?.safetyLevel ?? null,
+            totalElements: snapshot.totalElements,
+            evidence,
+            graph: observed.graph,
+        },
+    });
+}
+export const browserStartSessionTool = {
+    name: "browser_start_session",
+    title: "Open a browser session",
+    description: "Open a real browser at a URL in your running application and return a session id the other browser " +
+        "tools take. This is where consent is granted: confirming it allows Descry to drive a browser anywhere " +
+        "on that URL's origin until the session ends, so the click, type and fill tools do not ask again. " +
+        "Reports what the page produced — console errors, failed requests — raw and untriaged; deciding which " +
+        "of them matter is yours.",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    inputSchema: SCHEMA,
+    run,
+    describeAction(args) {
+        const target = parseTarget(args);
+        // Same parse the run path uses to enforce the gate (`mutationRefusal` in
+        // `tool-support.ts`) — read here, not re-derived, so what's confirmed matches
+        // what's enforced.
+        const profile = readProfile(args);
+        if (profile?.safetyLevel === "readOnly") {
+            return (`Descry may navigate, snapshot and wait anywhere on ${target.origin}. Clicking, typing, filling, ` +
+                `choosing an option and submitting a form will be refused. It may not leave that origin.`);
+        }
+        const grant = `Launch a browser and open ${target.href}. For as long as the session lives, Descry may navigate, ` +
+            `click, type, fill, choose an option and submit a form anywhere on ${target.origin} without asking ` +
+            "again — including actions that change data in that application. It may not leave that origin.";
+        // UAT phase 5 §7/B9: absent an explicit safety level, the enforcement really
+        // is unrestricted (`mutationRefusal`: no profile ⇒ no refusal) — but the
+        // prompt must say that is *because no profile was supplied*, not state
+        // unrestricted authority as though it had been deliberately chosen. A
+        // consent prompt that reads the same whether a level was set or omitted
+        // hides the one piece of information that would tell a caller to go set one.
+        // B1: credentials change what is being approved, so they change this
+        // text. The unseeded sentence already warns that data may change; a
+        // seeded session changes *whose* data — every action runs as the account
+        // whose session was handed over. A prompt that read identically either
+        // way would be asking for consent to something it had not mentioned.
+        const seeded = args["storageState"] !== undefined ||
+            args["storageStatePath"] !== undefined ||
+            args["storageStateCredential"] !== undefined ||
+            args["extraHttpHeaders"] !== undefined;
+        const asUser = seeded
+            ? " The session will be started ALREADY LOGGED IN, from the authentication material in this call: " +
+                "everything it does will be done as that user, with whatever that account is permitted to do, on " +
+                "screens a logged-out visitor could not reach. The credential itself is not shown here and will " +
+                "not appear in any reply."
+            : "";
+        return profile === null
+            ? `No environment profile was supplied, so nothing here restricts what Descry may do. ${grant}${asUser}`
+            : `Environment profile "${profile.name}" declares safetyLevel "${profile.safetyLevel}". ${grant}${asUser}`;
+    },
+    /**
+     * What may be remembered about this call — B1's secrets rule, at the one
+     * place a credential enters this server.
+     *
+     * `server.ts` records every completed call's arguments on the `Session` so
+     * `verify_claim` can check a citation against them. This is the only tool
+     * whose arguments can be a credential, so it is the only one that
+     * implements this.
+     *
+     * Structural rather than a known-value substitution, deliberately: this
+     * runs on the arguments **as the caller sent them**, including for a call
+     * refused before any state was built, so there is no validated seed to take
+     * a value list from. Names are kept — a reader of a recorded call must
+     * still be able to see that a session was seeded and with what kind of
+     * material.
+     */
+    redactArgs(args) {
+        const out = { ...args };
+        let touched = false;
+        if (out["storageState"] !== undefined && out["storageState"] !== null) {
+            out["storageState"] = redactStorageStateArgument(out["storageState"]);
+            touched = true;
+        }
+        if (typeof out["extraHttpHeaders"] === "object" && out["extraHttpHeaders"] !== null) {
+            out["extraHttpHeaders"] = Object.fromEntries(Object.keys(out["extraHttpHeaders"]).map((name) => [name, REDACTED]));
+            touched = true;
+        }
+        // A path is not a credential, and it is the one thing a reader needs in
+        // order to reproduce a run or clean up after it. Left intact.
+        return touched ? out : args;
+    },
+};
+const REDACTED = "[REDACTED]";
+function redactStorageStateArgument(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return REDACTED;
+    const fields = raw;
+    const cookies = Array.isArray(fields["cookies"])
+        ? fields["cookies"].map((cookie) => typeof cookie === "object" && cookie !== null ? { ...cookie, value: REDACTED } : REDACTED)
+        : fields["cookies"];
+    const stored = typeof fields["localStorage"] === "object" && fields["localStorage"] !== null
+        ? Object.fromEntries(Object.keys(fields["localStorage"]).map((key) => [key, REDACTED]))
+        : fields["localStorage"];
+    return {
+        ...fields,
+        ...(cookies === undefined ? {} : { cookies }),
+        ...(stored === undefined ? {} : { localStorage: stored }),
+    };
+}
+//# sourceMappingURL=browser-start-session.js.map