@open-everywhere/core 0.1.0

package/dist/agent/access/browser-toolkit.d.ts

@@ -0,0 +1,48 @@
+import type { WindowGrain } from "../identity/binding.js";
+/** Structural view of a vendor defineTool entry: contravariant members make a concrete tool unassignable to the bare ToolDefinition, so the shape stays any-loose. Entries must be approval-less. */
+export interface BrowserToolEntry {
+    readonly description: string;
+    readonly inputSchema: unknown;
+    readonly outputSchema?: unknown;
+    execute(input: any, ctx: any): any;
+    toModelOutput?(output: any): any;
+}
+/**
+ * WHY THE PLANE CANNOT ARM ON THIS PLATFORM, in one sentence, or undefined when it can (OPE-1793).
+ * It is the ONE road every arming path reads: {@link openBrowserEgressHosts} and {@link resolveBrowserKit} read it HERE, in core, and the adapter's config loader reads it for the tool mount and the sandbox bake (packages/adapters/agent/browser/config.ts) — so the four cannot drift.
+ * 🔴 IT IS NOT A BEHAVIOUR SETTING, AND IT IS NOT ABSOLUTE EITHER. Only the Vercel Sandbox backend carries Chromium — the self-host image (`node:24-alpine`) ships none — so the answer is read off the platform rather than off `browser.enabled`, and no domain override or capability declaration can move it. The ONE thing that can is the operator's own `OE_PLATFORM`: `platformName()` (access/platform.ts) reads that override BEFORE Vercel's own `VERCEL` var, so a self-host deployment that sets `OE_PLATFORM=vercel` answers `undefined` here and arms the whole plane again for a browser that cannot run. That is the operator's choice, made in env they own and documented as such in docs/capabilities/browser-qa.md; it is not a hole this function can close, because the same override is how a Vercel deployment declares itself self-host.
+ * WHAT THE REFUSAL BUYS where the override is not set: the plane arming there mounted 20 tools and OPENED the declared egress hosts for a browser that cannot run, which is a widened reach bought for nothing.
+ */
+export declare function browserPlaneRefusal(): string | undefined;
+/**
+ * THE BROWSER PLANE'S EGRESS-HOST OPENING, and the platform refusal is IN IT (OPE-1793).
+ * It exists so the refusal is true BY MECHANISM rather than by the adapter remembering to ask: a second registrar that called `registerBrowserToolkit` and `registerExtraEgressHosts` directly, without the adapter's config loader, would otherwise open the declared hosts at the firewall on a platform with no browser. Returns whether the hosts were opened, and logs the one-sentence reason when they were not.
+ * 🔴 IT IS THE UNCREDENTIALED HALF ONLY, unchanged from the caller it replaces: a row declaring a credential is compiled by access/egress.ts, and passing it here would drop its narrowing and its credential. The caller still filters.
+ */
+export declare function openBrowserEgressHosts(hosts: readonly string[]): boolean;
+/** The closed set of names this family may mount. An adapter entry whose name is not listed is SKIPPED with a loud log, so a vendor upgrade that adds a tool must extend this list in the same diff. */
+export declare const BROWSER_TOOL_NAMES: readonly ["browser_navigate", "browser_snapshot", "browser_read", "browser_click", "browser_fill", "browser_press_key", "browser_hover", "browser_select_option", "browser_set_checked", "browser_scroll", "browser_drag", "browser_upload", "browser_wait_for", "browser_get", "browser_find", "browser_screenshot", "browser_evaluate", "browser_tabs", "browser_console", "browser_network_requests", "browser_close"];
+export declare const BROWSER_UNFENCED_OPS: ReadonlySet<string>;
+/** Fences a content-bearing browser op's result through the shared ingest funnel, with byte-identical framing to every other read tool. */
+export declare function browserContentModelOutput(name: string, output: unknown): Promise<{
+    type: "text";
+    value: string;
+}>;
+/** The page host this session is believed to be on, or undefined when nothing has been observed. */
+export declare function currentBrowseHost(ctx: unknown): string | undefined;
+/** Wall 2. Throws unless the session's last known page host is one the operator armed `evaluate` on. */
+export declare function assertEvaluateArmedFor(ctx: unknown): void;
+/** TEST SEAM: forget every tracked page host. */
+export declare function resetBrowseHostsForTest(): void;
+/** Every name must carry the `browser_` prefix and no `__`. Idempotent per boot: a re-registration replaces the set wholesale. */
+export declare function registerBrowserToolkit(entries: Readonly<Record<string, BrowserToolEntry>>): void;
+/** The registered family, or undefined when the capability is unarmed (flag off / config absent). */
+export declare function registeredBrowserToolkit(): Readonly<Record<string, BrowserToolEntry>> | undefined;
+/** TEST SEAM: return to the unarmed state. */
+export declare function resetBrowserToolkitForTest(): void;
+/**
+ * Null when unarmed, so flag-off is byte-identical and no tool appears, and null on any grain outside the wide-hands kit.
+ * 🔴 NULL OFF VERCEL, WHATEVER IS REGISTERED (OPE-1793). The mount road refuses there already, so this arm is the backstop for anything that registered by another door — a second registrar, a test double, a future adapter — and it is what makes "the plane is off this platform" true of the RESOLVER and not only of the boot path.
+ */
+export declare function resolveBrowserKit(grain: WindowGrain): Readonly<Record<string, BrowserToolEntry>> | null;
+//# sourceMappingURL=browser-toolkit.d.ts.map

package/dist/agent/access/browser-toolkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-toolkit.d.ts","sourceRoot":"","sources":["../../../agent/access/browser-toolkit.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAU1D,qMAAqM;AACrM,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC;IACnC,aAAa,CAAC,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;CAClC;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAIxD;AAKD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAQxE;AAED,wMAAwM;AACxM,eAAO,MAAM,kBAAkB,YAC7B,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,CACP,CAAC;AAGX,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAAoD,CAAC;AAsB1G,2IAA2I;AAC3I,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CASjH;AAoDD,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGlE;AAED,wGAAwG;AACxG,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAezD;AAED,iDAAiD;AACjD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAoBD,kIAAkI;AAClI,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,IAAI,CAsChG;AAED,qGAAqG;AACrG,wBAAgB,wBAAwB,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAEjG;AAED,8CAA8C;AAC9C,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,IAAI,CAIvG"}

package/dist/agent/access/browser-toolkit.js

@@ -0,0 +1,240 @@
+// The neutral core registry for the flag-gated in-sandbox browser tool family; an adapter registers the vendor entries at boot. Names take ONE underscore prefix because `__` is the connector-op separator, the kit mounts only on the wide-hands grains, and every entry must be approval-less.
+import { defineTool } from "eve/tools";
+import { preRegisterDynamicEntry, grainBackstopAtExecute, fullKit } from "./window-gated.js";
+import { currentSessionId } from "../identity/binding.js";
+import { auditToolAction } from "../audit/tool-action.js";
+import { ingestUntrustedModelOutput } from "./untrusted.js";
+import { browserEvaluateHosts } from "./browser-hosts.js";
+import { onVercel } from "./platform.js";
+import { registerExtraEgressHosts } from "./extra-hosts.js";
+const BROWSER_TOOLS_SLUG = "browser_tools";
+/**
+ * WHY THE PLANE CANNOT ARM ON THIS PLATFORM, in one sentence, or undefined when it can (OPE-1793).
+ * It is the ONE road every arming path reads: {@link openBrowserEgressHosts} and {@link resolveBrowserKit} read it HERE, in core, and the adapter's config loader reads it for the tool mount and the sandbox bake (packages/adapters/agent/browser/config.ts) — so the four cannot drift.
+ * 🔴 IT IS NOT A BEHAVIOUR SETTING, AND IT IS NOT ABSOLUTE EITHER. Only the Vercel Sandbox backend carries Chromium — the self-host image (`node:24-alpine`) ships none — so the answer is read off the platform rather than off `browser.enabled`, and no domain override or capability declaration can move it. The ONE thing that can is the operator's own `OE_PLATFORM`: `platformName()` (access/platform.ts) reads that override BEFORE Vercel's own `VERCEL` var, so a self-host deployment that sets `OE_PLATFORM=vercel` answers `undefined` here and arms the whole plane again for a browser that cannot run. That is the operator's choice, made in env they own and documented as such in docs/capabilities/browser-qa.md; it is not a hole this function can close, because the same override is how a Vercel deployment declares itself self-host.
+ * WHAT THE REFUSAL BUYS where the override is not set: the plane arming there mounted 20 tools and OPENED the declared egress hosts for a browser that cannot run, which is a widened reach bought for nothing.
+ */
+export function browserPlaneRefusal() {
+    return onVercel()
+        ? undefined
+        : "the browser plane needs the Vercel Sandbox backend — the self-host image ships no Chromium, so nothing arms here (agent/access/browser-toolkit.ts).";
+}
+/** The `registerExtraEgressHosts` source key the browser plane's hosts ride under. One constant, because {@link openBrowserEgressHosts} is the only writer and the key is what dedupes the plane's own set. */
+const BROWSER_EGRESS_SOURCE = "agent-browser";
+/**
+ * THE BROWSER PLANE'S EGRESS-HOST OPENING, and the platform refusal is IN IT (OPE-1793).
+ * It exists so the refusal is true BY MECHANISM rather than by the adapter remembering to ask: a second registrar that called `registerBrowserToolkit` and `registerExtraEgressHosts` directly, without the adapter's config loader, would otherwise open the declared hosts at the firewall on a platform with no browser. Returns whether the hosts were opened, and logs the one-sentence reason when they were not.
+ * 🔴 IT IS THE UNCREDENTIALED HALF ONLY, unchanged from the caller it replaces: a row declaring a credential is compiled by access/egress.ts, and passing it here would drop its narrowing and its credential. The caller still filters.
+ */
+export function openBrowserEgressHosts(hosts) {
+    const refusal = browserPlaneRefusal();
+    if (refusal !== undefined) {
+        console.error(`[open-everywhere:agent-browser] NOT opening ${hosts.length} declared egress host(s): ${refusal}`);
+        return false;
+    }
+    registerExtraEgressHosts(BROWSER_EGRESS_SOURCE, hosts);
+    return true;
+}
+/** The closed set of names this family may mount. An adapter entry whose name is not listed is SKIPPED with a loud log, so a vendor upgrade that adds a tool must extend this list in the same diff. */
+export const BROWSER_TOOL_NAMES = [
+    "browser_navigate",
+    "browser_snapshot",
+    "browser_read",
+    "browser_click",
+    "browser_fill",
+    "browser_press_key",
+    "browser_hover",
+    "browser_select_option",
+    "browser_set_checked",
+    "browser_scroll",
+    "browser_drag",
+    "browser_upload",
+    "browser_wait_for",
+    "browser_get",
+    "browser_find",
+    "browser_screenshot",
+    "browser_evaluate",
+    "browser_tabs",
+    "browser_console",
+    "browser_network_requests",
+    "browser_close",
+];
+// FAIL-CLOSED: every browser op's textual result is fenced through the shared untrusted funnel unless it is listed here, so a new content tool is fenced by default. The two exclusions return no page-derived text: screenshot returns a host-assigned path ref, close returns nothing.
+export const BROWSER_UNFENCED_OPS = new Set(["browser_screenshot", "browser_close"]);
+/** Best-effort host label for the source provenance. Cosmetic only: a missing domain just shortens the source label. */
+function browserDomainOf(output) {
+    const host = (u) => {
+        if (typeof u !== "string")
+            return undefined;
+        try {
+            return new URL(u).host || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    if (output !== null && typeof output === "object") {
+        const o = output;
+        const direct = host(o.url) ?? host(o.href);
+        if (direct !== undefined)
+            return direct;
+    }
+    const text = typeof output === "string" ? output : JSON.stringify(output ?? null);
+    const m = text.match(/https?:\/\/[^\s"'<>)]+/);
+    return m ? host(m[0]) : undefined;
+}
+/** Fences a content-bearing browser op's result through the shared ingest funnel, with byte-identical framing to every other read tool. */
+export function browserContentModelOutput(name, output) {
+    const op = name.startsWith("browser_") ? name.slice("browser_".length) : name;
+    const domain = browserDomainOf(output);
+    const text = typeof output === "string" ? output : JSON.stringify(output ?? null);
+    // The ingestion kind is declared so it is REPRESENTED: an absent kind in the log is indistinguishable from an unwired one.
+    return ingestUntrustedModelOutput(text, {
+        source: domain ? `browser ${op} ${domain}` : `browser ${op}`,
+        ingestion: { kind: "web", label: `browser_${op}` },
+    });
+}
+// Page scripting is opt-in per host: with no declared host carrying `evaluate: true`, browser_evaluate is not registered at all. The per-host check at execute is best-effort, because the vendor call carries no URL, so a stale tracked host bounds exposure to a declared host that did not opt in; an unknown host refuses.
+/** Per-session last-known page host, keyed by eve's session id. Bounded by {@link HOST_TRACK_CAP}:
+ *  a long-lived process must not accumulate one entry per session that ever browsed. */
+const lastBrowseHost = new Map();
+/** How many sessions' page hosts to remember. Well past any real concurrency; the oldest entry is
+ *  dropped on overflow, which costs that session one refusal and a re-navigate, never a wrong pass. */
+const HOST_TRACK_CAP = 256;
+/** The vendor ops whose INPUT carries the URL being navigated to: browser_navigate goto and browser_tabs new, which are two real navigation seams. Measured against @agent-browser/eve 0.32.4; a vendor upgrade that adds another url-taking verb extends this set in the same diff. */
+const URL_TAKING_OPS = new Set(["browser_navigate", "browser_tabs"]);
+/** Read from the INPUT, not the result: it is the one host fact that does not depend on what the vendor CLI chose to print. */
+function navigationTargetHost(name, input) {
+    if (!URL_TAKING_OPS.has(name) || input === null || typeof input !== "object")
+        return undefined;
+    const url = input.url;
+    return typeof url === "string" ? hostOf(url) : undefined;
+}
+function hostOf(u) {
+    try {
+        return new URL(u).hostname.toLowerCase() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Reads the host-assigned `url`/`href` field and nothing else. It must not fall back to scanning the body like browserDomainOf does: page TEXT is attacker-controllable, so a hostile page naming an armed host would move the tracker and let wall 2 admit an evaluate the operator never armed. */
+function resultReportedHost(output) {
+    if (output === null || typeof output !== "object")
+        return undefined;
+    const o = output;
+    const url = typeof o.url === "string" ? o.url : typeof o.href === "string" ? o.href : undefined;
+    return url === undefined ? undefined : hostOf(url);
+}
+/** Called after EVERY op, so a post-action navigation URL refreshes the tracker as well as a navigate's own input. The PORT is stripped, because a declaration names a bare hostname and comparing the two spellings would refuse every armed host served on a non-default port; IPv6 literals keep their brackets. */
+function noteBrowseHost(ctx, host) {
+    if (host === undefined)
+        return;
+    const bare = host.startsWith("[") ? (host.match(/^\[[^\]]*\]/)?.[0] ?? host) : host.replace(/:\d+$/, "");
+    if (bare.length === 0)
+        return;
+    const session = currentSessionId(ctx);
+    if (session === undefined)
+        return;
+    if (!lastBrowseHost.has(session) && lastBrowseHost.size >= HOST_TRACK_CAP) {
+        const oldest = lastBrowseHost.keys().next();
+        if (!oldest.done)
+            lastBrowseHost.delete(oldest.value);
+    }
+    lastBrowseHost.set(session, bare.toLowerCase());
+}
+/** The page host this session is believed to be on, or undefined when nothing has been observed. */
+export function currentBrowseHost(ctx) {
+    const session = currentSessionId(ctx);
+    return session === undefined ? undefined : lastBrowseHost.get(session);
+}
+/** Wall 2. Throws unless the session's last known page host is one the operator armed `evaluate` on. */
+export function assertEvaluateArmedFor(ctx) {
+    const armed = browserEvaluateHosts();
+    const host = currentBrowseHost(ctx);
+    if (host === undefined) {
+        throw new Error("browser_evaluate: no page host is known for this session — navigate to a declared host first. " +
+            "Page scripting is armed per host in the operator's browser host declaration (agent/access/browser-hosts.ts).");
+    }
+    if (!armed.has(host)) {
+        throw new Error(`browser_evaluate: "${host}" does not declare \`evaluate: true\` — page scripting is off for it. ` +
+            "Drive the page from browser_snapshot plus browser_find/click/fill, or ask the operator to arm this host.");
+    }
+}
+/** TEST SEAM: forget every tracked page host. */
+export function resetBrowseHostsForTest() {
+    lastBrowseHost.clear();
+}
+let registered;
+/** It MUST stay a module-level factory that the caller CALLS. eve's build transform rewrites an execute authored inline in a defineTool literal and stamps a durable descriptor capturing every enclosing identifier, which here captures a non-serializable entry object and makes eve drop the whole resolver's result at replay. */
+function browserBackstoppedExecute(name, entry, auditAction) {
+    return async (input, ctx) => {
+        await grainBackstopAtExecute(name, fullKit(), ctx);
+        // OPE-1624 wall 2 — BEFORE the vendor runs, so a refused evaluate executes no script at all.
+        if (name === "browser_evaluate")
+            assertEvaluateArmedFor(ctx);
+        // The target is recorded before the call because the result may report no URL. A navigation the inner wall refuses, or one that fails on DNS, leaves the tracker naming a page the browser is not on; that page is still a DECLARED host, which is the bound wall 2 claims.
+        noteBrowseHost(ctx, navigationTargetHost(name, input));
+        const result = await entry.execute(input, ctx);
+        // Any op whose result names a URL refreshes the tracker. Structured field only: see resultReportedHost for why the body-scanning fallback must not be used here.
+        noteBrowseHost(ctx, resultReportedHost(result));
+        await auditToolAction(ctx, auditAction);
+        return result;
+    };
+}
+/** Every name must carry the `browser_` prefix and no `__`. Idempotent per boot: a re-registration replaces the set wholesale. */
+export function registerBrowserToolkit(entries) {
+    const armed = {};
+    // Read ONCE per registration, not per entry: registration runs at boot after the app's declaration registered, and a declaration cannot change inside a process.
+    const evaluateArmedHosts = browserEvaluateHosts();
+    for (const [name, entry] of Object.entries(entries)) {
+        if (name === "browser_evaluate" && evaluateArmedHosts.size === 0) {
+            console.log("[open-everywhere:agent-browser] browser_evaluate NOT mounted — no declared host carries `evaluate: true` " +
+                "(the kit is snapshot-driven by default; arm a host in agent/access/browser-hosts.ts to re-add page scripting)");
+            continue;
+        }
+        if (!BROWSER_TOOL_NAMES.includes(name)) {
+            // Skipped rather than thrown: refusing the whole registration for one unknown name would take every known tool down with it. The unknown name has no module-load replay step, so mounting it would be a silent replay hole.
+            console.error(`[open-everywhere:agent-browser] skipping unknown tool "${name}" — not in core's BROWSER_TOOL_NAMES canonical list (a vendor upgrade that adds a tool must extend the list in access/browser-toolkit.ts)`);
+            continue;
+        }
+        if (entry.approval !== undefined) {
+            // House policy (CONSEQUENCE POSTURE above): reach is bounded by the operator's egress
+            // allowlist, made once at arming time — not a per-call approval decision.
+            throw new Error(`registerBrowserToolkit: "${name}" carries an approval policy — browser toolkit entries must be approval-less`);
+        }
+        // Audit action uses the dotted shape (`browser_navigate` becomes `browser.navigate`), because `__` is the connector-op separator. It records ids and the verb only, never args or output, and is best-effort: a failed audit never fails the tool.
+        const auditAction = `browser.${name.slice("browser_".length)}`;
+        // Authored here so preRegisterDynamicEntry gives it a durable descriptor, which eve rebuilds toModelOutput from on replay. It overrides any vendor toModelOutput.
+        const fenced = !BROWSER_UNFENCED_OPS.has(name);
+        const backstopped = defineTool({
+            ...entry,
+            // 🔴 A CALL, never an inline function — see browserBackstoppedExecute's header (OPE-1063).
+            execute: browserBackstoppedExecute(name, entry, auditAction),
+            ...(fenced ? { toModelOutput: (output) => browserContentModelOutput(name, output) } : {}),
+        });
+        preRegisterDynamicEntry(BROWSER_TOOLS_SLUG, name, backstopped);
+        armed[name] = backstopped;
+    }
+    registered = armed;
+}
+/** The registered family, or undefined when the capability is unarmed (flag off / config absent). */
+export function registeredBrowserToolkit() {
+    return registered;
+}
+/** TEST SEAM: return to the unarmed state. */
+export function resetBrowserToolkitForTest() {
+    registered = undefined;
+}
+/**
+ * Null when unarmed, so flag-off is byte-identical and no tool appears, and null on any grain outside the wide-hands kit.
+ * 🔴 NULL OFF VERCEL, WHATEVER IS REGISTERED (OPE-1793). The mount road refuses there already, so this arm is the backstop for anything that registered by another door — a second registrar, a test double, a future adapter — and it is what makes "the plane is off this platform" true of the RESOLVER and not only of the boot path.
+ */
+export function resolveBrowserKit(grain) {
+    if (browserPlaneRefusal() !== undefined)
+        return null;
+    if (registered === undefined || Object.keys(registered).length === 0)
+        return null;
+    return fullKit().includes(grain) ? registered : null;
+}
+//# sourceMappingURL=browser-toolkit.js.map

package/dist/agent/access/browser-toolkit.js.map

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

package/dist/agent/access/bundle.d.ts

@@ -0,0 +1,239 @@
+import type { OperatorApprover } from "./approver-chain.js";
+import { type PreApprovalRule } from "./pre-approval-rules.js";
+import { type RepoCapability } from "./repo-capabilities.js";
+import { type ResourceGrant } from "./resource-grant.js";
+import type { Group } from "../identity/groups.js";
+export type ScopeLevel = "org" | "tenant" | "domain" | "surface" | "group" | "principal";
+export interface Scope {
+    readonly level: ScopeLevel;
+    /** `platform/<tenant-id>` — required when level is "tenant". */
+    readonly tenant?: string;
+    /** A memory/config/domains.ts domain NAME, bare (no tenant qualifier) — required when level is "domain". */
+    readonly domain?: string;
+    /** `platform/<tenant-id>/<container-id>` — required when level is "surface". */
+    readonly surface?: string;
+    /** An identity/groups.ts group NAME, bare (no platform qualifier — a group is a set of humans,
+     *  cross-platform by construction) — required when level is "group". */
+    readonly group?: string;
+    /** Required at `principal` level: EITHER `platform/<principal-id>` (one account) OR `linkSet:<id>` (one human across their confirmed accounts). The two forms are disjoint — a key contains "/", a ref never does — so a matcher tells them apart by shape. */
+    readonly principal?: string;
+}
+export type CredentialType = "bearer" | "basic" | "github-app";
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface CustomHeader {
+    readonly name: string;
+    /** Optional literal prefix before the secret, e.g. "Token " or "SSWS ". */
+    readonly prefix?: string;
+    /** Reference to the secret value (resolved via the credential broker). */
+    readonly secretRef: string;
+}
+export interface CredentialAuthorizationDetail {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+export interface Connection {
+    readonly id: string;
+    readonly credentialType: CredentialType;
+    /** Reference to the secret (e.g. env key), never the secret value itself. */
+    readonly secretRef: string;
+    /**
+     * The HOME broker `secretRef` resolves through ("env", "db", or any registered name); custom headers ride the same one.
+     * There is NO default: an absent broker on a connection that actually resolves FAILS CLOSED rather than guessing. It is optional in the type only for a fixture connection that never resolves.
+     */
+    readonly broker?: string;
+    /** Hosts this connection may reach AND the only hosts its credential is sent to. A wildcard is allowed only as the leftmost label, e.g. "*.googleapis.com". */
+    readonly allowedWebsites: readonly string[];
+    /** Optional path-prefix narrowing (OAuth-authcode connections only, upstream). */
+    readonly pathPrefixes?: readonly string[];
+    /** Secret-valued custom headers (Claude Tag's "Custom headers": name + prefix +
+     *  secret value). Resolved from `secretRef`s via the broker, stacked on top of the
+     *  credentialType's own header. */
+    readonly customHeaders?: readonly CustomHeader[];
+    /** Optional read-only narrowing: restrict to these methods. */
+    readonly methods?: readonly HttpMethod[];
+    /** Optional down-scoping detail forwarded verbatim to the broker's `getSecret`. Unset means exactly today's behaviour: the broker mints its default (blanket) grant for this ref. */
+    readonly authorizationDetails?: readonly CredentialAuthorizationDetail[];
+}
+/**
+ * ONE normalised egress host — the single spelling every plane compares by. The egress policy keys the credential on the host alone, so two modules normalising differently would hide a collision from the guard that refuses it.
+ * A wildcard label SURVIVES: this normalises a spelling, it does not expand a pattern.
+ */
+export declare function normaliseEgressHost(host: string): string;
+/**
+ * Can these two host patterns ever name ONE destination? String equality is not that test: `*.vendor.com` and `api.vendor.com` are two map keys and one destination, so equality lets two connections claim it and the firewall's matching order then decides which credential is stamped.
+ * The relation is symmetric and one wildcard form is expanded — a LEADING `*.`, which covers subdomains but not the apex.
+ * 🔴 That is the only wildcard spelling config may carry, refused elsewhere by `assertBundlesValid`, so this grammar is total over what can reach it.
+ */
+export declare function egressHostsOverlap(a: string, b: string): boolean;
+/** What a connector grant may declare about who authors the bytes the connection returns. Both
+ *  members are real claims — unlike `SurfaceTrust`, `"external"` IS writable here, because the
+ *  table has a positive row for it (an exact verdict, not the fail-closed default wearing its
+ *  clothes). */
+export type ConnectorContentOrigin = "internal" | "external";
+/** The per-tool form of a content-origin declaration: one answer for the connection, overridden
+ *  for named tools. `except` keys are BARE tool names — the eve-mounted name with its
+ *  `<connection>__` prefix stripped — so an entry can only ever apply to its own connection. */
+export interface ConnectorContentOriginOverrides {
+    readonly default: ConnectorContentOrigin;
+    readonly except: Readonly<Record<string, ConnectorContentOrigin>>;
+}
+export type ConnectorContentOriginSpec = ConnectorContentOrigin | ConnectorContentOriginOverrides;
+/**
+ * The one connector-grant grammar: `name` is the eve connection slug, `credential` names which configured identity this scope reaches it as, and `contentOrigin` says who authors what it returns.
+ * 🔴 `credential` is MANDATORY and has no default — one list with one mandatory field leaves no second place for consumers to disagree about which connectors a config defines. `contentOrigin` is optional in the TYPE and required by `assertBundlesValid` outside the machine-written overlays.
+ */
+export interface ConnectorGrant {
+    readonly name: string;
+    /** A credential id configured for `name` in the connector's credential catalogue
+     *  (access/connector-credentials.ts). MANDATORY; `lint:connections` fails a grant naming one that
+     *  is not configured, and the resolver contributes nothing for it. */
+    readonly credential: string;
+    readonly contentOrigin?: ConnectorContentOriginSpec;
+}
+/**
+ * The bare-slug member is no longer valid config — `assertBundlesValid` rejects it for every bundle, the machine-written overlays included.
+ * It stays in the TYPE so the shared readers still serve the plugin connector lists, so the pure resolver still answers correctly for a grant that never passed validation, and so the rejection stays testable.
+ */
+export type ConnectorGrantSpec = string | ConnectorGrant;
+/** The Eve connection slug a grant names, whichever form it is written in. Every consumer that
+ *  wants "which connectors does this bundle grant" goes through this — there is deliberately no
+ *  second place that knows the two shapes. */
+export declare function connectorGrantName(grant: ConnectorGrantSpec): string;
+/** The content origin a grant DECLARES, or `undefined` when it declares nothing. `undefined` is not
+ *  `"external"` — see the plane header. */
+export declare function connectorGrantContentOrigin(grant: ConnectorGrantSpec): ConnectorContentOriginSpec | undefined;
+/** The credential id a grant NAMES, or `undefined` for the bare-slug form that names none. Every
+ *  consumer that asks "as which identity?" goes through this, exactly as `connectorGrantName` is the
+ *  only reader of the two shapes' slug. `undefined` here is not a default — it is a grant
+ *  `assertBundlesValid` refuses and the resolver resolves to nothing. */
+export declare function connectorGrantCredential(grant: ConnectorGrantSpec): string | undefined;
+/**
+ * Resolve a spec to ONE origin for one BARE tool name — the only place that knows the scalar-versus-object shapes.
+ * `Object.hasOwn` rather than a bare index, so a tool named `__proto__` reads the operator's declaration or nothing; an unvalidated override falls back to `default`, because `undefined` at this seam would erase a declaration the operator did write.
+ */
+export declare function contentOriginForTool(spec: ConnectorContentOriginSpec, bareToolName: string): ConnectorContentOrigin;
+/** Every connector slug a bundle grants, in declaration order (duplicates are a config error the
+ *  load-time assert rejects, so this does not dedupe). */
+export declare function bundleConnectorNames(bundle: Pick<Bundle, "connectors">): readonly string[];
+/**
+ * Raise the consequence tier of NAMED operations on one connector.
+ * 🔴 RAISE-ONLY, and the vocabulary is why: there is no `open`/`read` field, so no config can spell a lowering — and the runtime combines declarations by lattice JOIN rather than assignment.
+ * The baseline is the verb classifier, where an unrecognised verb already fails closed to `destructive`. Op names match the operation half of `<connection>__<op>` case-insensitively, with `-`/`_` equivalent and "*" for every op.
+ */
+export interface ConnectorOpGating {
+    /** The connector slug these ops belong to — the `<connection>` half of `<connection>__<op>`. */
+    readonly connector: string;
+    /** Ops raised to at least `write`: gated behind an approval card, but session-skippable — an "Approve for session" grant may cover the rest of the session. */
+    readonly gated?: readonly string[];
+    /** Ops raised to `destructive`: gated PER CALL, never covered by a session grant. For an irreversible op whose verb the classifier does not recognise as destructive. */
+    readonly destructive?: readonly string[];
+}
+export interface AwsRoleGrant {
+    /** The IAM role to assume, e.g. "arn:aws:iam::123456789012:role/oe-payments". */
+    readonly roleArn: string;
+    /** AWS region for STS + the signed calls (e.g. "eu-west-2"). Optional — the adapter
+     *  may default it (global services sign against us-east-1 regardless). */
+    readonly region?: string;
+    /** OIDC audience claim the role's trust policy pins (the `aud` the deployment token
+     *  is minted for). Optional — the adapter may carry a deployment-wide default. */
+    readonly audience?: string;
+    /**
+     * REQUIRED host-side service/action allow-list, enforced before the CLI runs.
+     * 🔴 Unrestricted MUST be spelled ["*"]: absence or emptiness is a config error AND a runtime refusal, never a pass-through, because an omitted narrowing and a decision not to narrow looked the same in review.
+     * Grammar: a bare `service`, or `service:action` with IAM-native names and globs or the CLI kebab spelling; s3 high-level commands fan out to enumerated IAM action sets. Matched case-insensitively.
+     * On the domain-role mint path the same list compiles into an STS session policy — defence-in-depth on top of the IAM role, able only to restrict further.
+     */
+    readonly allow: readonly string[];
+}
+/** A repo grant that opts INTO named capability sets over the per-plane defaults. `capabilities` names sets from access/repo-capabilities.ts and can never name a raw vendor permission string — `assertBundlesValid` refuses an unknown name, so the reachable permission families stay closed in code. */
+export interface RepoGrant {
+    /** "owner/name", the same form the bare-string spelling takes. */
+    readonly repo: string;
+    /** Named capability sets this binding expands into. Absent = the per-plane defaults, which is
+     *  exactly what the bare-string spelling means. An EMPTY array is a config error, not a synonym
+     *  for absent (see repoCapabilityProblems). */
+    readonly capabilities?: readonly RepoCapability[];
+}
+/** One entry of `Bundle.repos`: the bare string (defaults) or the object form (opt-in expansion). */
+export type RepoGrantSpec = string | RepoGrant;
+/** The "owner/name" a repo grant names, whichever spelling it is written in. Every consumer that
+ *  asks "which repos does this bundle grant" goes through this — there is deliberately no second
+ *  place that knows the two shapes (the `connectorGrantName` convention). */
+export declare function repoGrantName(grant: RepoGrantSpec): string;
+/** The capability sets a repo grant opts into — EMPTY for the bare string, which is what makes the
+ *  back-compatible spelling mean "today's defaults" rather than "unspecified". */
+export declare function repoGrantCapabilities(grant: RepoGrantSpec): readonly RepoCapability[];
+export interface Bundle {
+    /** ⚠️ IMMUTABLE ONCE REFERENCED: renaming orphans every binding that names it — config load catches the ones in this repo, but a live grants overlay written against the old name silently resolves to nothing. Change {@link Bundle.title} for anything a human reads. */
+    readonly name: string;
+    /** Optional human-facing display label. Cosmetic only — no binding, resolver rule, lint
+     *  or audit record reads it. Absent → `name`. */
+    readonly title?: string;
+    /** Egress (sandbox-firewall) credential plane. */
+    readonly connections?: readonly Connection[];
+    /**
+     * CONNECTOR plane: eve connection slugs this bundle grants, host-side MCP/OpenAPI — distinct from the egress `connections` above. Additive union across matching scopes.
+     * One grant grammar, `{ name, credential, contentOrigin }`: the resolver binds the credential per surface, narrowest-wins, and a bare slug is refused at config load.
+     */
+    readonly connectors?: readonly ConnectorGrantSpec[];
+    /** CONNECTOR-OP plane: RAISE the consequence tier of named operations on a granted connector. Purely additive over the verb classifier — see {@link ConnectorOpGating} for the raise-only guarantee. */
+    readonly connectorOps?: readonly ConnectorOpGating[];
+    /**
+     * WORK-SOURCE plane: GitHub repos this bundle grants. A grant is not an auto-clone; a repo clones only when named.
+     * The bare string is today's grant byte-for-byte (the per-plane job sets decide what a call may do); the object form is the opt-in expansion. Additive union, capabilities unioned per repo.
+     */
+    readonly repos?: readonly RepoGrantSpec[];
+    /**
+     * RESOURCE plane: named CONTAINERS on a chat surface this scope may act on, beyond the container its turns arrive in. One row per connector, additive union, capabilities unioned per address.
+     * 🔴 It grants reach, NEVER a domain crossing: a granted container is admitted only when it is also in the caller's own memory domain, checked at execute, which is what makes a cross-domain post unreachable rather than merely refused.
+     */
+    readonly resourceGrants?: readonly ResourceGrant[];
+    /** Credential-LESS egress allowlist: hosts reachable without a credential. These are egress HOSTS, distinct from the `domain` SCOPE level — different concept, unfortunate word overlap. */
+    readonly domains?: readonly string[];
+    /** Plugin grants by NAME; each expands via the registry to its connectors, skills and subagents. Additive union across matching scopes. */
+    readonly plugins?: readonly string[];
+    /** AWS-ROLE plane: IAM roles this bundle grants permission to assume host-side. Additive union deduped by `roleArn` (narrowest-wins for region/audience); credentialed capability, but carrying no `secretRef`. */
+    readonly awsRoles?: readonly AwsRoleGrant[];
+    /**
+     * APPROVER plane: operator-authored chain elements that join L1 for every scope this bundle binds to, config-ordered within the band — config can never reorder the LEVELS.
+     * An operator element may LOWER a built-in verdict, since a bundle author already grants the credentials this plane governs; a connector or remote element is clamped raise-only unless granted `mayAllow`. No runtime surface edits this.
+     */
+    readonly approvers?: readonly OperatorApprover[];
+    /** Scope custom instructions: standing rules that outrank channel memory. Verbatim plain text, no templating, concatenated across matching scopes in precedence order. */
+    readonly instructions?: string;
+    /**
+     * Admin-authored pre-approval rules that reach the approval judge as curated context, resolved per scope and ADDED down the ladder.
+     * 🔴 A rule can PRE-APPROVE a routine action; it can never remove an ask that policy code forces — it is an input to the judge, not a chain element.
+     */
+    readonly preApprovalRules?: readonly PreApprovalRule[];
+}
+export interface Binding {
+    readonly bundle: string;
+    readonly scope: Scope;
+    /**
+     * EXPLICIT escape for the broad-grant lint: binding a bundle with credentialed capability (connections, repos, connectors, awsRoles) at `org` or `tenant` scope is a hard CI failure, because every channel beneath the scope, including future ones, inherits it.
+     * Set a non-empty REASON to accept that deliberately; an empty string fails the lint, and credential-less grants never need it.
+     */
+    readonly allowBroad?: string;
+}
+/**
+ * The package-registry hosts, offered as a named constant a bundle grants in one reviewed line (`domains: [...PACKAGE_REGISTRY_HOSTS]`).
+ * 🔴 Deliberately NOT a compiled-in default: a default would widen every deployment's egress with no diff to review, reach domains scoped to nothing on purpose, and make `compileNetworkPolicy`'s `deny-all` branch unreachable.
+ */
+export declare const PACKAGE_REGISTRY_HOSTS: readonly string[];
+export declare function defineBundle(bundle: Bundle): Bundle;
+export declare function defineBinding(binding: Binding): Binding;
+/** Validate the bundle DEFINITIONS at config load and fail loud, listing every problem. Pairs with {@link assertBindingsValid}, the binding side. */
+export declare function assertBundlesValid(bundles: readonly Bundle[]): void;
+/** `platform/<tenant-id>` — exactly two non-empty, slash-free segments. */
+export declare const TENANT_KEY: RegExp;
+/** `platform/<tenant-id>/<container-id>` — three+ segments; only the container may hold a "/".
+ *  The one authority on the surface-key form: bindings (assertBindingsValid), the
+ *  access-request delta (delta.ts) and the grants codemod all test against THIS. */
+export declare const SURFACE_KEY: RegExp;
+/**
+ * Validate the BINDINGS at config load (fail loud): a known bundle, exactly the level's one address field, qualified tenant/surface/principal keys, and bare domain and group names. Pairs with {@link assertBundlesValid}.
+ * 🔴 The group registry is an ARGUMENT, not a lookup: existence is a joint property of two config files, so the check belongs to the app tier's merged validation — and `undefined` SKIPS the existence check, it does not silently approve.
+ */
+export declare function assertBindingsValid(bindings: readonly Binding[], bundles: readonly Bundle[], groups?: readonly Group[]): void;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/agent/access/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../agent/access/bundle.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOhF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;AAKzF,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4GAA4G;IAC5G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;4EACwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+PAA+P;IAC/P,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAGD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;AAE/D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAG9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAGD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAGD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+JAA+J;IAC/J,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;uCAEmC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACjD,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,qLAAqL;IACrL,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC1E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAGhE;AAcD;;;gBAGgB;AAChB,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,UAAU,CAAC;AAE7D;;gGAEgG;AAChG,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CACnE;AAED,MAAM,MAAM,0BAA0B,GAAG,sBAAsB,GAAG,+BAA+B,CAAC;AAElG;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;0EAEsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,0BAA0B,CAAC;CACrD;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,cAAc,CAAC;AAKzD;;8CAE8C;AAC9C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAEpE;AAED;2CAC2C;AAC3C,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,kBAAkB,GAAG,0BAA0B,GAAG,SAAS,CAE7G;AAED;;;yEAGyE;AACzE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAEtF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,0BAA0B,EAAE,YAAY,EAAE,MAAM,GAAG,sBAAsB,CAInH;AAED;0DAC0D;AAC1D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,MAAM,EAAE,CAE1F;AAKD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+JAA+J;IAC/J,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yKAAyK;IACzK,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAKD,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;8EAC0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;sFACkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAMD,4SAA4S;AAC5S,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;mDAE+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACnD;AAED,qGAAqG;AACrG,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/C;;6EAE6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAE1D;AAED;kFACkF;AAClF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,cAAc,EAAE,CAErF;AAED,MAAM,WAAW,MAAM;IACrB,2QAA2Q;IAC3Q,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;qDACiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,wMAAwM;IACxM,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnD,4LAA4L;IAC5L,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,2IAA2I;IAC3I,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mNAAmN;IACnN,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,0KAA0K;IAC1K,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAUnD,CAAC;AAGF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEvD;AAoHD,qJAAqJ;AACrJ,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAmLnE;AAeD,2EAA2E;AAC3E,eAAO,MAAM,UAAU,QAAwB,CAAC;AAChD;;oFAEoF;AACpF,eAAO,MAAM,WAAW,QAA6B,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI,CA+D7H"}