@descryy/mcp 0.2.0 → 0.3.0

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"}

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

@@ -0,0 +1,272 @@
+/**
+ * `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 { browserAnswer, emptyEvidence, observeAndCorrelate } from "../browser/tool-support.js";
+import { NO_GRAPH_WRITE } from "../browser/graph-write.js";
+import { isAbsolute, join } from "node:path";
+import { loadStackParser, StackParserLoadError } from "../browser/stack-parser.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.",
+            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,
+        },
+        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. 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"];
+/**
+ * Read the profile, do not re-derive it.
+ *
+ * Only the two fields this surface actually consults are read; everything
+ * else a caller sends is carried by the profile it came from and is none of
+ * this tool's business. `additionalProperties: true` on the schema is what
+ * lets a caller pass the same object it passes `observe_runtime` rather than
+ * trimming a second copy of it.
+ */
+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 };
+}
+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");
+    try {
+        return 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.");
+    }
+}
+async function run(args, ctx) {
+    const target = parseTarget(args);
+    const headless = optionalBoolean(args, "headless") ?? true;
+    const profile = readProfile(args);
+    const parserSpec = readStackParserSpec(args);
+    const documentRoot = optionalString(args, "documentRoot");
+    const backend = ctx.session.browserBackend();
+    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 },
+        });
+    }
+    // The parser is loaded before anything launches. A parser that will not
+    // import is a refusal the caller can fix, and finding that out after a
+    // browser is open would mean either tearing it down again or running a
+    // session that quietly cannot write the edge it was 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 },
+        });
+    }
+    // Trap A, closed here rather than left to a caller to get right silently.
+    // The origin being driven maps to the directory that actually serves its
+    // scripts; `documentRoot` overrides the repository root for exactly 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,
+    });
+    const opened = await ctx.session.browserSessions().open(driver, { targetUrl: target.href, headless, profile });
+    if (!opened.opened) {
+        const notes = opened.kind === "atCapacity"
+            ? [opened.reason]
+            : // The remedy travels verbatim. A refusal that says "could not launch"
+                // and stops is one the developer has to go and research.
+                [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 },
+        });
+    }
+    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: [
+            `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.",
+            ...(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);
+        return (`Launch a browser and open ${target.href}. For as long as the session lives, Descry may navigate, ` +
+            `click, type and fill anywhere on ${target.origin} without asking again — including actions that ` +
+            "change data in that application. It may not leave that origin.");
+    },
+};
+//# sourceMappingURL=browser-start-session.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser-start-session.js","sourceRoot":"","sources":["../../src/tools/browser-start-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAAE,cAAc,EAA0B,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAK7C,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAwB,MAAM,4BAA4B,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAyC,MAAM,UAAU,CAAC;AAkBhJ,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,6FAA6F;gBAC7F,6FAA6F;gBAC7F,6FAA6F;SAChG;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,gFAAgF;SAC9F;QACD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,mGAAmG;gBACnG,qGAAqG;gBACrG,sGAAsG;gBACtG,oGAAoG;gBACpG,UAAU;YACZ,UAAU,EAAE;gBACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0GAA0G,EAAE;gBACnJ,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qIAAqI,EAAE;aAC/K;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,oBAAoB,EAAE,KAAK;SAC5B;QACD,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,oGAAoG;gBACpG,mGAAmG;gBACnG,uGAAuG;gBACvG,sGAAsG;gBACtG,sGAAsG;gBACtG,kCAAkC;SACrC;QACD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,8FAA8F;gBAC9F,mGAAmG;gBACnG,oGAAoG;gBACpG,+FAA+F;gBAC/F,qGAAqG;gBACrG,uGAAuG;YACzG,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4EAA4E,EAAE;gBACnH,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,yBAAyB,CAAC;oBACtD,WAAW,EACT,+FAA+F;wBAC/F,oFAAoF;iBACvF;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC;YACjC,oBAAoB,EAAE,IAAI;SAC3B;QACD,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,+FAA+F;gBAC/F,+FAA+F;gBAC/F,iGAAiG;gBACjG,6BAA6B;SAChC;KACF;IACD,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,MAAM,aAAa,GAAkC,CAAC,UAAU,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC;AAEtG;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,IAA6B;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IAChC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,iCAAiC,CAAC,CAAC;IAE/G,MAAM,MAAM,GAAG,GAA8B,CAAC;IAC9C,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;IACvE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,cAAc,CACtB,kGAAkG;YAChG,4GAA4G,CAC/G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC;AAED,SAAS,mBAAmB,CAAC,IAA6B;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IAChC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,iCAAiC,CAAC,CAAC;IAC/G,MAAM,MAAM,GAAG,GAA8B,CAAC;IAC9C,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACtE,CAAC;AAED,SAAS,WAAW,CAAC,IAA6B;IAChD,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,cAAc,CACtB,+DAA+D,GAAG,mCAAmC;YACnG,kFAAkF,CACrF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAA6B,EAAE,GAAgB;IAChE,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,CAAC;IAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,YAAY,GAAG,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;IAE7C,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,OAAO,aAAa,CAA0B;YAC5C,GAAG;YACH,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,mCAAmC;YAC7C,KAAK,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,OAAO,CAAC,MAAM,EAAE,CAAC;YACpD,IAAI,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE;SAC5K,CAAC,CAAC;IACL,CAAC;IAED,wEAAwE;IACxE,uEAAuE;IACvE,uEAAuE;IACvE,gEAAgE;IAChE,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IAC/E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,oBAAoB,CAAC;YAAE,MAAM,KAAK,CAAC;QAC1D,OAAO,aAAa,CAA0B;YAC5C,GAAG;YACH,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,0CAA0C,KAAK,CAAC,SAAS,IAAI;YACvE,KAAK,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;YACtB,IAAI,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE;SAC5K,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,yEAAyE;IACzE,wEAAwE;IACxE,uCAAuC;IACvC,MAAM,UAAU,GAAG,YAAY,KAAK,SAAS;QAC3C,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ;QACtB,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC;YACxB,CAAC,CAAC,YAAY;YACd,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAC/C,MAAM,iBAAiB,GAAG,CAAC,MAAc,EAAqB,EAAE,CAC9D,MAAM,KAAK,MAAM,CAAC,MAAM;QACtB,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE;QAC1F,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,MAAM,oDAAoD,EAAE,CAAC;IAE3H,GAAG,CAAC,QAAQ,CAAC,wBAAwB,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC;QACxC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;QACxD,iBAAiB;QACjB,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI;KACjC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IAE/G,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,KAAK,GACT,MAAM,CAAC,IAAI,KAAK,YAAY;YAC1B,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;YACjB,CAAC,CAAC,sEAAsE;gBACtE,yDAAyD;gBACzD,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,MAAM,CAAC,MAAM,EAAE,EAAE,2BAA2B,MAAM,CAAC,sBAAsB,GAAG,CAAC,CAAC;QAEhH,OAAO,aAAa,CAA0B;YAC5C,GAAG;YACH,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,MAAM,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,6CAA6C,CAAC,CAAC,CAAC,0BAA0B;YACnH,KAAK;YACL,IAAI,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE;SACpM,CAAC,CAAC;IACL,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACzB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAEnC,OAAO,aAAa,CAA0B;QAC5C,GAAG;QACH,QAAQ,EAAE,mBAAmB,KAAK,CAAC,SAAS,YAAY,QAAQ,CAAC,GAAG,KAAK,QAAQ,CAAC,aAAa,aAAa;QAC5G,KAAK,EAAE;YACL,kBAAkB,KAAK,CAAC,eAAe,+DAA+D;gBACpG,qGAAqG;gBACrG,0FAA0F;YAC5F,GAAG,CAAC,UAAU,KAAK,IAAI;gBACrB,CAAC,CAAC;oBACE,8FAA8F;wBAC5F,6FAA6F;wBAC7F,qEAAqE;iBACxE;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,IAAI;gBACxB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC;oBACE,sCAAsC,KAAK,CAAC,OAAO,CAAC,IAAI,iBAAiB;wBACvE,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,KAAK;wBAClC,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,KAAK,UAAU;4BACvC,CAAC,CAAC,wFAAwF;4BAC1F,CAAC,CAAC,EAAE,CAAC;iBACV,CAAC;YACN,GAAG,QAAQ,CAAC,KAAK;SAClB;QACD,IAAI,EAAE;YACJ,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,WAAW,EAAE,KAAK,CAAC,OAAO,EAAE,WAAW,IAAI,IAAI;YAC/C,aAAa,EAAE,QAAQ,CAAC,aAAa;YACrC,QAAQ;YACR,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EACT,qGAAqG;QACrG,wGAAwG;QACxG,mGAAmG;QACnG,uGAAuG;QACvG,0BAA0B;IAC5B,KAAK,EAAE,QAAQ;IACf,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,MAAM;IACnB,GAAG;IACH,cAAc,CAAC,IAA6B;QAC1C,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,CACL,6BAA6B,MAAM,CAAC,IAAI,2DAA2D;YACnG,oCAAoC,MAAM,CAAC,MAAM,iDAAiD;YAClG,gEAAgE,CACjE,CAAC;IACJ,CAAC;CACF,CAAC"}

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

@@ -0,0 +1,48 @@
+/**
+ * `browser_type` — type into a field with real keystrokes.
+ *
+ * ## Consent, and why this tool asks for none
+ *
+ * `DEC-380` grants consent once, at
+ * `browser_start_session`, bound to that call's origin. So this tool declares
+ * `class: "action"` — it does change a running application, and pretending
+ * otherwise would be the lie — while its `describeAction` returns `undefined`,
+ * the existing "this particular call has nothing to confirm" path that
+ * `questions` uses when asked to read rather than write.
+ *
+ * The property that makes that safe rather than merely cheap: **a verb cannot
+ * mint consent for itself.** Called against a session with no consent record,
+ * it refuses. There is deliberately no path from a click to a token.
+ *
+ * ## A ref, never a selector
+ *
+ * The element is named by a ref from a snapshot the calling agent actually
+ * saw. A raw selector would let an agent act on an element it never looked
+ * at, and a ref from a superseded snapshot refuses rather than resolving
+ * against whatever now matches — that is the same mistake, arriving later.
+ */
+/**
+ * ## Why this is not the same tool as `browser_fill`
+ *
+ * The visible difference is that this appends and `fill` replaces. The
+ * difference that decides which one is correct for a real page is that **this
+ * one fires key events and `fill` fires none.** A field that opens an
+ * autocomplete on keydown, validates per character, or debounces a search as
+ * you type sees nothing at all from a `fill`. An agent that reaches for
+ * `fill` on a search box gets a page that was never typed into — a wrong
+ * answer produced by entirely correct tool code, which is why the schema
+ * prose below says so rather than describing only the tidy half.
+ */
+import type { BrowserEvidenceReport } from "../browser/evidence.ts";
+import { type BrowserGraphWrite } from "../browser/graph-write.ts";
+import { type ToolDefinition } from "./kit.ts";
+export interface BrowserTypeData {
+    readonly sessionId: string;
+    readonly ref: string;
+    readonly url: string;
+    readonly evidence: BrowserEvidenceReport;
+    /** Graph nodes this action's own requests reached, and any R4 edges it witnessed. */
+    readonly graph: BrowserGraphWrite;
+}
+export declare const browserTypeTool: ToolDefinition;
+//# sourceMappingURL=browser-type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser-type.d.ts","sourceRoot":"","sources":["../../src/tools/browser-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnF,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAyFD,eAAO,MAAM,eAAe,EAAE,cAiB7B,CAAC"}