@descryy/mcp 0.1.2 → 0.3.0

package/dist/tools/browser-save-scenario.js

@@ -0,0 +1,298 @@
+/**
+ * `browser_save_scenario` — an explored session becomes a durable, repeatable
+ * scenario.
+ *
+ * ## Everything goes out through `writeScenario`
+ *
+ * There is deliberately no private path to disk here. `writeScenario`
+ * validates on the way *out* as well as in, and that is not redundant: a
+ * scenario is written once and read on every push afterwards, so a fault saved
+ * today surfaces during a check somebody is waiting on, long after the session
+ * that could have explained it is gone. A tool that serialized its own JSON
+ * would be a second writer with a first writer's rules, and the second one is
+ * the one that ships a file nothing can read.
+ *
+ * ## A step carries no ref, and this schema offers no way to send one
+ *
+ * The ref refusal is enforced twice on purpose. The format module rejects a
+ * step carrying a `ref` **by name**, with the reason in the message; this
+ * schema does not declare the field at all. A caller working from a
+ * `browser_snapshot` reply has the three durable fields already — every
+ * snapshot element carries `role`, `name` and `selector` — so the natural
+ * thing to copy is the right thing to store.
+ *
+ * ## What the session supplies
+ *
+ * The consented origin (a scenario may not be saved pointing somewhere this
+ * session was never allowed to drive), the URL to start from, and the
+ * provenance pair. The steps are the caller's: this server has no exploration
+ * planner and does not pretend to have recorded intent it never saw.
+ */
+import { gitHead } from "@descryy/core";
+import { browserAnswer, useSession, withinConsent } from "../browser/tool-support.js";
+import { SCENARIO_SCHEMA_VERSION, scenarioPath, writeScenario } from "../scenarios/index.js";
+import { optionalString, requiredString, ToolInputError } from "./kit.js";
+const TARGET_SCHEMA = {
+    type: "object",
+    description: "The element, named the way a replay can find it again: all three of role, name and selector, together, " +
+        "always. Copy them from a browser_snapshot element — every one carries all three. There is no ref field " +
+        "and there cannot be one: a ref is scoped to the snapshot that issued it and a replay is always a later " +
+        "session. There is also no fallback between the three at replay: a selector that still matches while the " +
+        "role or name disagrees stops the replay rather than substituting quietly, because that substitution is " +
+        "how a scenario keeps reporting green against a page that changed underneath it.",
+    properties: {
+        role: { type: "string", description: "The element's ARIA role, as browser_snapshot reported it." },
+        name: { type: "string", description: "The element's accessible name, as browser_snapshot reported it." },
+        selector: { type: "string", description: "The selector browser_snapshot reported for it." },
+    },
+    required: ["role", "name", "selector"],
+    additionalProperties: false,
+};
+const SCHEMA = {
+    type: "object",
+    properties: {
+        sessionId: { type: "string", description: "REQUIRED. The browser session this scenario was explored in." },
+        name: {
+            type: "string",
+            description: "REQUIRED. What to call it. Becomes descry/scenarios/<name>.scenario.json — a committed file, " +
+                "reviewable in a diff, and deliberately not under .descry/, which is gitignored and would make the " +
+                "scenario vanish on CI's fresh checkout.",
+        },
+        description: { type: "string", description: "Free text for whoever reads the file later. Optional." },
+        targetUrl: {
+            type: "string",
+            description: "Where a replay should start. Defaults to the session's current URL, and must be on the origin this " +
+                "session was consented for — a saved file cannot widen a consent grant.",
+        },
+        steps: {
+            type: "array",
+            description: "REQUIRED, and at least one. The sequence to replay, in order. Every step is re-resolved against a " +
+                "fresh page at replay time.",
+            items: {
+                type: "object",
+                properties: {
+                    action: { type: "string", enum: ["navigate", "click", "type", "fill"], description: "navigate acts on the page; click, type and fill act on an element and need a target." },
+                    target: TARGET_SCHEMA,
+                    url: { type: "string", description: "Where to go. For navigate steps only." },
+                    text: {
+                        type: "string",
+                        description: "What to enter. For type and fill only, and the two differ in a way that decides whether a page " +
+                            "behaves: type fires real keystrokes and appends, fill sets the value directly and fires none, " +
+                            "so a field that opens an autocomplete or validates per character sees nothing at all from a fill.",
+                    },
+                },
+                required: ["action"],
+                additionalProperties: false,
+            },
+        },
+        assertions: {
+            type: "array",
+            description: "REQUIRED, and may be empty. What this scenario claims about the application. Absent is refused " +
+                "rather than defaulted, because absent and empty are different statements: an empty list is an " +
+                "exploration saved honestly, and it replays as \"unverified\" — never as passed. A replay that clicks " +
+                "through a broken page and reports success is a false negative with a confident face on it, and the " +
+                "runner cannot invent a check it was never told about.",
+            items: {
+                type: "object",
+                properties: {
+                    kind: {
+                        type: "string",
+                        enum: ["elementVisible", "textEquals", "urlEquals", "noConsoleErrors", "noFailedRequests"],
+                        description: "elementVisible and textEquals are about one element and need a target; textEquals and urlEquals " +
+                            "compare against expected. noConsoleErrors and noFailedRequests read the evidence gathered up to " +
+                            "that point — an OBSERVED console error never blocks a push, but one the author asserted would " +
+                            "not happen does, because a person claimed it.",
+                    },
+                    afterStep: {
+                        type: "integer",
+                        description: "Which step this runs after, by index. Omit for end-of-scenario. An index past the last step is " +
+                            "refused here rather than discovered at replay: an assertion that never runs never says so, and " +
+                            "the scenario reports green because its only check was unreachable.",
+                    },
+                    target: TARGET_SCHEMA,
+                    expected: { type: "string", description: "The value to compare against, for the kinds that compare one." },
+                },
+                required: ["kind"],
+                additionalProperties: false,
+            },
+        },
+        confirmToken: {
+            type: "string",
+            description: "Not normally needed. Consent for this session was granted at browser_start_session, and this call " +
+                "writes a file rather than driving the browser. The field is declared because the handshake reads it " +
+                "for every action-class tool.",
+        },
+    },
+    required: ["sessionId", "name", "steps", "assertions"],
+    additionalProperties: false,
+};
+function readObjectArray(args, key) {
+    const raw = args[key];
+    if (raw === undefined || raw === null) {
+        throw new ToolInputError(`"${key}" is required. Absent and empty are different statements here — send [] to say this scenario ` +
+            "has none, which is stored honestly and replays as unverified.");
+    }
+    if (!Array.isArray(raw) || raw.some((item) => typeof item !== "object" || item === null || Array.isArray(item))) {
+        throw new ToolInputError(`"${key}" must be an array of objects`);
+    }
+    return raw;
+}
+/**
+ * Shape the caller's arguments into a `Scenario` **without validating them**.
+ *
+ * Deliberate: `writeScenario` is the validator, and a second one here would be
+ * a second set of rules to keep in step with the first. Everything a caller
+ * got wrong comes back through the format module's own messages, which are the
+ * ones the file's future readers will see.
+ */
+function shape(args, name, targetUrl, savedAtCommit) {
+    const steps = readObjectArray(args, "steps").map((step) => ({
+        action: step["action"],
+        target: (step["target"] ?? null),
+        url: (step["url"] ?? null),
+        text: (step["text"] ?? null),
+    }));
+    const assertions = readObjectArray(args, "assertions").map((assertion) => ({
+        kind: assertion["kind"],
+        afterStep: (assertion["afterStep"] ?? null),
+        target: (assertion["target"] ?? null),
+        expected: (assertion["expected"] ?? null),
+    }));
+    return {
+        schemaVersion: SCENARIO_SCHEMA_VERSION,
+        name,
+        description: optionalString(args, "description") ?? null,
+        targetUrl,
+        savedAt: new Date().toISOString(),
+        savedAtCommit,
+        steps,
+        assertions,
+    };
+}
+/**
+ * The commit this scenario was authored against.
+ *
+ * Provenance only — nothing expires on it and nothing refuses because of it.
+ * It exists so a replay failure can say *the scenario was written against a
+ * different revision of this application*, which is usually the answer to "why
+ * did this break". A directory that is not a git checkout records the empty
+ * string and the reply says so, rather than a plausible-looking placeholder
+ * that a later reader would try to `git show`.
+ */
+async function commitOf(repoPath) {
+    try {
+        return await gitHead(repoPath);
+    }
+    catch {
+        return "";
+    }
+}
+async function run(args, ctx) {
+    const sessionId = requiredString(args, "sessionId");
+    const name = requiredString(args, "name");
+    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,
+                "Nothing was written. A scenario records a session somebody explored, and there is no session here " +
+                    "to record.",
+            ],
+            data: blank(sessionId, name),
+        });
+    }
+    const { entry } = found;
+    const targetUrl = optionalString(args, "targetUrl") ?? entry.page.currentUrl();
+    if (!withinConsent(entry, targetUrl)) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `${targetUrl} is outside this session's consented origin.`,
+            notes: [
+                `This session's consent covers the origin ${entry.consentedOrigin} alone, and a saved scenario cannot point somewhere ` +
+                    "it was never allowed to drive — storing one would launder a consent grant into a file that outlives " +
+                    "the session. Nothing was written.",
+            ],
+            data: blank(sessionId, name),
+        });
+    }
+    const scenario = shape(args, name, targetUrl, await commitOf(ctx.session.repoPath));
+    try {
+        // The one write path. `writeScenario` validates on the way out, so an
+        // artifact that this reader could not read back never reaches disk.
+        await writeScenario(ctx.session.repoPath, scenario);
+    }
+    catch (error) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `Scenario "${name}" was not saved.`,
+            notes: [
+                String(error instanceof Error ? error.message : error),
+                "Validated on the way out on purpose: a scenario is written once and read on every push afterwards, " +
+                    "so a fault stored today would surface during a check somebody is waiting on, long after this " +
+                    "session could have explained it.",
+            ],
+            data: blank(sessionId, name),
+        });
+    }
+    const path = scenarioPath(ctx.session.repoPath, name);
+    return browserAnswer({
+        ctx,
+        headline: `Saved scenario "${name}" — ${scenario.steps.length} step(s), ${scenario.assertions.length} assertion(s).`,
+        notes: [
+            `Written to ${path}. Commit it: scenarios are source, and one that is not committed works locally, ` +
+                "vanishes on CI's fresh checkout, and reports nothing rather than failing.",
+            ...(scenario.assertions.length === 0
+                ? [
+                    "This scenario asserts nothing, so a replay of it will report \"unverified\" rather than passed. " +
+                        "Saving an exploration is deliberately possible; an exploration replayed without incident has " +
+                        "verified nothing.",
+                ]
+                : []),
+            ...(scenario.savedAtCommit === ""
+                ? [
+                    "No commit was recorded — this directory is not a git checkout. The scenario is stored and " +
+                        "replayable; a later failure just cannot say which revision it was written against.",
+                ]
+                : []),
+        ],
+        data: {
+            sessionId,
+            name,
+            path,
+            targetUrl,
+            stepCount: scenario.steps.length,
+            assertionCount: scenario.assertions.length,
+            savedAt: scenario.savedAt,
+            savedAtCommit: scenario.savedAtCommit,
+        },
+    });
+}
+function blank(sessionId, name) {
+    return { sessionId, name, path: "", targetUrl: "", stepCount: 0, assertionCount: 0, savedAt: "", savedAtCommit: "" };
+}
+export const browserSaveScenarioTool = {
+    name: "browser_save_scenario",
+    title: "Save an explored session as a scenario",
+    description: "Turn a session you have explored into a durable, repeatable scenario — a committed file under " +
+        "descry/scenarios/ that browser_run_scenario replays and a pre-push check can run with no agent in the " +
+        "loop. Steps name their elements by role, name and selector together, never by a snapshot ref, because a " +
+        "ref means nothing in a later session. Assertions are required and may be empty; an empty one is stored " +
+        "honestly and replays as unverified rather than passed. The file is validated before it is written, so " +
+        "a scenario that could not be read back is refused now rather than during a check somebody is waiting on.",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    inputSchema: SCHEMA,
+    run,
+    // Undefined, for the reason the verbs have and one of its own: this call
+    // writes into the repository the developer already pointed Descry at, in a
+    // path they name, and the session it records was confirmed at
+    // browser_start_session.
+    describeAction: () => undefined,
+};
+//# sourceMappingURL=browser-save-scenario.js.map

package/dist/tools/browser-save-scenario.js.map

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

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

@@ -0,0 +1,60 @@
+/**
+ * `browser_snapshot` — what is on the page, as refs an action can take.
+ *
+ * ## Why this tool implements `fitToBudget` from its first commit
+ *
+ * A real accessibility tree is tens of thousands of bytes. `get_git_diff`
+ * shipped without an aggregate reply ceiling, returned 228,860 characters on
+ * an ordinary branch diff, and was rejected by the host before the caller saw
+ * any of it; the fix that followed bounded patch text and still failed at
+ * 84,516, because a reply is not only patch text. That lesson was paid for
+ * twice, and a brand-new tool whose payload grows with the user's application
+ * is precisely where it would be paid for a third time.
+ *
+ * So the budget hook is here from day one, and the test asserts the
+ * serialized `CallToolResult` rather than asserting that a cap ran.
+ *
+ * ## `totalElements` is never the capped number
+ *
+ * A snapshot that quietly returned the first forty elements would teach a
+ * calling agent that the page has forty elements. It would then conclude the
+ * button it needs is absent, which is a wrong answer produced by a correct
+ * tool. So the uncapped count is always present and always the real one, and
+ * a shortened reply says so in a note.
+ */
+import type { BrowserEvidenceReport } from "../browser/evidence.ts";
+import { type BrowserGraphWrite } from "../browser/graph-write.ts";
+import { type ToolDefinition } from "./kit.ts";
+import type { ReplyFit } from "../render.ts";
+import type { SnapshotElement } from "../browser/driver.ts";
+export interface BrowserPageData {
+    readonly sessionId: string;
+    readonly url: string;
+    readonly title: string;
+    readonly elements: readonly SnapshotElement[];
+    /**
+     * How many elements the page has. **Never the number in `elements`** when
+     * the two differ — that is the whole point of carrying it.
+     */
+    readonly totalElements: number;
+    readonly evidence: BrowserEvidenceReport;
+    /** Graph nodes this page's own requests reached, and any R4 edges witnessed. §5.3's "any graph node reached, surfaced in the same reply". */
+    readonly graph: BrowserGraphWrite;
+}
+/**
+ * What `browser_snapshot` returns. An alias of the shared page shape, so
+ * `browser_navigate` — which answers the same question — cannot drift from it.
+ */
+export type BrowserSnapshotData = BrowserPageData;
+/**
+ * Shrink by dropping elements from the end of the window, never by dropping
+ * the count or the evidence.
+ *
+ * Evidence stays because it is the part a caller cannot re-request by paging —
+ * the observations were drained when this reply was built, and a second
+ * snapshot would return a different set. Elements can always be asked for
+ * again with `startAt`, so they are what gives way.
+ */
+export declare function fitSnapshot(data: BrowserSnapshotData, budgetBytes: number): ReplyFit<BrowserSnapshotData>;
+export declare const browserSnapshotTool: ToolDefinition;
+//# sourceMappingURL=browser-snapshot.d.ts.map

package/dist/tools/browser-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/browser-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAAqD,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAClG,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,6IAA6I;IAC7I,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC;AA6ElD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAwBzG;AAED,eAAO,MAAM,mBAAmB,EAAE,cAajC,CAAC"}

package/dist/tools/browser-snapshot.js

@@ -0,0 +1,139 @@
+/**
+ * `browser_snapshot` — what is on the page, as refs an action can take.
+ *
+ * ## Why this tool implements `fitToBudget` from its first commit
+ *
+ * A real accessibility tree is tens of thousands of bytes. `get_git_diff`
+ * shipped without an aggregate reply ceiling, returned 228,860 characters on
+ * an ordinary branch diff, and was rejected by the host before the caller saw
+ * any of it; the fix that followed bounded patch text and still failed at
+ * 84,516, because a reply is not only patch text. That lesson was paid for
+ * twice, and a brand-new tool whose payload grows with the user's application
+ * is precisely where it would be paid for a third time.
+ *
+ * So the budget hook is here from day one, and the test asserts the
+ * serialized `CallToolResult` rather than asserting that a cap ran.
+ *
+ * ## `totalElements` is never the capped number
+ *
+ * A snapshot that quietly returned the first forty elements would teach a
+ * calling agent that the page has forty elements. It would then conclude the
+ * button it needs is absent, which is a wrong answer produced by a correct
+ * tool. So the uncapped count is always present and always the real one, and
+ * a shortened reply says so in a note.
+ */
+import { browserAnswer, observeAndCorrelate, useSession } from "../browser/tool-support.js";
+import { NO_GRAPH_WRITE } from "../browser/graph-write.js";
+import { optionalInteger, requiredString } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        sessionId: {
+            type: "string",
+            description: "REQUIRED. The id returned by browser_start_session.",
+        },
+        startAt: {
+            type: "integer",
+            minimum: 0,
+            description: "Skip this many elements before listing. Use it to page through a large page: compare the number " +
+                "of elements you received against totalElements, which is always the real count, and ask again " +
+                "with startAt set past what you have seen.",
+        },
+        limit: {
+            type: "integer",
+            minimum: 1,
+            description: "At most this many elements. A reply too large for the host is shortened further regardless, and says so.",
+        },
+    },
+    required: ["sessionId"],
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const sessionId = requiredString(args, "sessionId");
+    const startAt = optionalInteger(args, "startAt", 0) ?? 0;
+    const limit = optionalInteger(args, "limit", 1);
+    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: "", url: "", title: "", elements: [], totalElements: 0, evidence: found.dead.evidence, graph: NO_GRAPH_WRITE },
+        });
+    }
+    const { entry } = found;
+    ctx.progress("Reading the page");
+    const snapshot = await entry.page.snapshot();
+    const observed = await observeAndCorrelate(ctx, entry);
+    const evidence = observed.evidence;
+    const windowed = snapshot.elements.slice(startAt, limit === undefined ? undefined : startAt + limit);
+    const notes = [...observed.notes];
+    if (windowed.length < snapshot.totalElements) {
+        notes.push(`Showing ${windowed.length} of ${snapshot.totalElements} elements, from index ${startAt}. ` +
+            "totalElements is always the real count — ask again with startAt past what you have seen.");
+    }
+    const data = {
+        sessionId: entry.sessionId,
+        url: snapshot.url,
+        title: snapshot.title,
+        elements: windowed,
+        totalElements: snapshot.totalElements,
+        evidence,
+        graph: observed.graph,
+    };
+    return browserAnswer({
+        ctx,
+        headline: `${snapshot.url} — ${windowed.length} of ${snapshot.totalElements} elements.`,
+        notes,
+        data,
+        fitToBudget: (budgetBytes) => fitSnapshot(data, budgetBytes),
+    });
+}
+/**
+ * Shrink by dropping elements from the end of the window, never by dropping
+ * the count or the evidence.
+ *
+ * Evidence stays because it is the part a caller cannot re-request by paging —
+ * the observations were drained when this reply was built, and a second
+ * snapshot would return a different set. Elements can always be asked for
+ * again with `startAt`, so they are what gives way.
+ */
+export function fitSnapshot(data, budgetBytes) {
+    const fits = (elements) => Buffer.byteLength(JSON.stringify({ ...data, elements }), "utf8") <= budgetBytes;
+    if (fits(data.elements))
+        return { data, notes: [] };
+    let low = 0;
+    let high = data.elements.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (fits(data.elements.slice(0, mid)))
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    const kept = data.elements.slice(0, low);
+    return {
+        data: { ...data, elements: kept },
+        notes: [
+            `The page's elements did not fit in one reply, so ${kept.length} of ${data.totalElements} are included. ` +
+                `totalElements is the real count, not the number shown — ask again with startAt set to ${kept.length} ` +
+                "for the next batch.",
+        ],
+        truncatedDetail: { shown: kept.length, total: data.totalElements, more: null },
+    };
+}
+export const browserSnapshotTool = {
+    name: "browser_snapshot",
+    title: "Read the current page",
+    description: "Return the elements on the page an open browser session is showing, each with a ref the click, type " +
+        "and fill tools take. Also returns anything the page produced since your last call — console errors and " +
+        "failed requests, raw and untriaged. totalElements is always the page's real element count, so a short " +
+        "list means the rest did not fit rather than that the page is small.",
+    class: "stateful-read",
+    tier: "evidence",
+    version: "1.0.0",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=browser-snapshot.js.map

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

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

package/dist/tools/browser-start-session.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `browser_start_session` — open a real browser against the developer's app.
+ *
+ * ## Why this one is the gate
+ *
+ * `DEC-380` puts consent here and nowhere
+ * else. This is the call where a target URL is named, so it is the only call
+ * where the fact a developer actually approves — *Descry may drive a browser
+ * against this application* — can be stated. A per-click confirmation would
+ * describe "click ref-14", which is a string the caller supplied one call
+ * earlier and can neither evaluate nor be surprised by, and it would train
+ * callers to confirm reflexively.
+ *
+ * The grant is bound to this URL's **origin**. `browser_navigate` refuses to
+ * leave it. Without that bound, "drive my local app" would silently become
+ * "drive anything".
+ *
+ * ## Class
+ *
+ * `action`, unambiguously: this launches a process and points it at a running
+ * application. It is the only browser tool that mints a token; the verbs it
+ * consents for redeem nothing, because the session they run in has already
+ * been confirmed.
+ */
+import type { BrowserEvidenceReport } from "../browser/evidence.ts";
+import { type BrowserGraphWrite } from "../browser/graph-write.ts";
+import { type ToolDefinition } from "./kit.ts";
+export interface BrowserStartSessionData {
+    /** Hand this to every other browser tool. Valid on this connection only. */
+    readonly sessionId: string;
+    readonly url: string;
+    readonly title: string;
+    /** The origin this session's consent covers. Navigation outside it refuses. */
+    readonly consentedOrigin: string;
+    /** The safety level this session runs under, or null when no profile was given. */
+    readonly safetyLevel: "readOnly" | "write" | "destructiveWithApproval" | null;
+    /** How many elements the landing page has, before any reply budget applies. */
+    readonly totalElements: number;
+    readonly evidence: BrowserEvidenceReport;
+    readonly graph: BrowserGraphWrite;
+}
+export declare const browserStartSessionTool: ToolDefinition;
+//# sourceMappingURL=browser-start-session.d.ts.map

package/dist/tools/browser-start-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-start-session.d.ts","sourceRoot":"","sources":["../../src/tools/browser-start-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAOnF,OAAO,EAAmG,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGhJ,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAAC;IAC9E,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAoPD,eAAO,MAAM,uBAAuB,EAAE,cAsBrC,CAAC"}