@mlola/browser-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MLola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @mlola/browser-protocol
+
+Typed contracts for the [MLola Browser Runtime](https://mlola.com/browser-runtime):
+observations, typed actions, decision providers, verification, policy, budgets
+and the event log.
+
+No browser, no model, no filesystem — this is the stable vocabulary the rest of
+the runtime is built from.
+
+```ts
+import { OPERATIONS, headForOperation, type BrowserSnapshot } from "@mlola/browser-protocol";
+```
+
+Full documentation: <https://mlola.com/browser-runtime>

package/dist/actions.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Typed action protocol (PRD §14, §25, §33).
+ *
+ * Models choose among runtime-owned operations and runtime-owned targets. Model
+ * output never becomes a selector, an XPath, a raw coordinate, JavaScript, a
+ * shell command or a browser protocol method.
+ */
+import type { ArtifactId, ElementIndex, NodeId, TabId } from "./ids.ts";
+import type { ProvenanceClass } from "./provenance.ts";
+export declare const OPERATIONS: readonly ["CLICK", "TYPE_TEXT", "SELECT", "SCROLL_UP", "SCROLL_DOWN", "WAIT", "BACK", "FORWARD", "OPEN_TAB", "SWITCH_TAB", "CLOSE_TAB", "DOWNLOAD", "UPLOAD", "PRESS", "ACCEPT_DIALOG", "DISMISS_DIALOG", "DONE", "BLOCKED", "ASK_USER"];
+export type OperationId = (typeof OPERATIONS)[number];
+/** Operations offered to the decision model in the normal loop. */
+export declare const DECISION_OPERATIONS: readonly OperationId[];
+/** Operations the runtime executes but never offers to the model by default. */
+export declare const INTERNAL_OPERATIONS: readonly OperationId[];
+export declare const TARGET_HEADS: readonly ["click_target", "type_text_target", "select_target", "switch_tab_target", "open_tab_target", "download_target", "upload_target"];
+export type TargetHeadId = (typeof TARGET_HEADS)[number];
+export interface TargetCandidate {
+    /** Model-facing key: element index ("2"), option ("4:1") or tab id ("t2"). */
+    key: string;
+    /** One-line description shown to the decision model. */
+    label: string;
+    nodeIndex?: ElementIndex;
+    nodeId?: NodeId;
+    optionIndex?: number;
+    optionValue?: string;
+    tabId?: TabId;
+    url?: string;
+    artifactId?: ArtifactId;
+    provenance: ProvenanceClass;
+    /** Excluded from the offered space; kept for audit. */
+    quarantined?: boolean;
+    quarantineReason?: string;
+}
+export interface ActionSpace {
+    /** Operation head alternatives. */
+    operations: OperationId[];
+    /** Speculative target heads; runtime uses only the selected operation's head. */
+    heads: Partial<Record<TargetHeadId, TargetCandidate[]>>;
+    /** Which head each offered operation must use. */
+    headForOperation: Partial<Record<OperationId, TargetHeadId>>;
+    /** Targets removed by deterministic safety filters, kept for observability. */
+    quarantined: TargetCandidate[];
+}
+export declare const headForOperation: (op: OperationId) => TargetHeadId | undefined;
+/** Runtime-owned element reference. Bound to a snapshot generation. */
+export interface ElementRef {
+    index: ElementIndex;
+    nodeId: NodeId;
+    pageToken: string;
+    generation: number;
+    labelHash: string;
+}
+export type PressKey = "Enter" | "Escape" | "Tab" | "ArrowDown" | "ArrowUp" | "ArrowLeft" | "ArrowRight" | "Home" | "End" | "PageDown" | "PageUp" | "Backspace" | "Delete";
+export type TypedAction = {
+    op: "CLICK";
+    ref: ElementRef;
+    clickCount?: 1 | 2;
+} | {
+    op: "TYPE_TEXT";
+    ref: ElementRef;
+    /** Text is produced by the runtime (literal reuse or validated generation). */
+    text: string;
+    mode: "fill" | "keyboard";
+    submitAfter?: boolean;
+} | {
+    op: "SELECT";
+    ref: ElementRef;
+    /** Copied from the observation, re-validated before execution. */
+    option: {
+        index: number;
+        label: string;
+        value: string;
+    };
+} | {
+    op: "SCROLL_UP";
+    ref?: ElementRef;
+    amount: "page" | "half" | "small";
+} | {
+    op: "SCROLL_DOWN";
+    ref?: ElementRef;
+    amount: "page" | "half" | "small";
+} | {
+    op: "WAIT";
+    ms: number;
+} | {
+    op: "BACK";
+} | {
+    op: "FORWARD";
+} | {
+    op: "OPEN_TAB";
+    url: string;
+    sourceRef?: ElementRef;
+} | {
+    op: "SWITCH_TAB";
+    tabId: TabId;
+} | {
+    op: "CLOSE_TAB";
+    tabId: TabId;
+} | {
+    op: "DOWNLOAD";
+    ref: ElementRef;
+} | {
+    op: "UPLOAD";
+    ref: ElementRef;
+    artifactId: ArtifactId;
+    mechanism: "file_input" | "file_chooser" | "drop_zone";
+} | {
+    op: "PRESS";
+    key: PressKey;
+    ref?: ElementRef;
+} | {
+    op: "ACCEPT_DIALOG";
+} | {
+    op: "DISMISS_DIALOG";
+};
+export declare const operationOf: (action: TypedAction) => OperationId;
+export declare const mayHaveUnknownEffect: (action: TypedAction) => boolean;
+/** Deterministic signature used for loop detection (PRD §30). */
+export declare const actionSignature: (action: TypedAction) => string;
+export declare const describeAction: (action: TypedAction) => string;
+/** Actions that are a claim about task state rather than a browser interaction. */
+export declare const isTerminalClaim: (op: OperationId) => boolean;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

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

package/dist/actions.js

@@ -0,0 +1,155 @@
+/**
+ * Typed action protocol (PRD §14, §25, §33).
+ *
+ * Models choose among runtime-owned operations and runtime-owned targets. Model
+ * output never becomes a selector, an XPath, a raw coordinate, JavaScript, a
+ * shell command or a browser protocol method.
+ */
+export const OPERATIONS = [
+    "CLICK",
+    "TYPE_TEXT",
+    "SELECT",
+    "SCROLL_UP",
+    "SCROLL_DOWN",
+    "WAIT",
+    "BACK",
+    "FORWARD",
+    "OPEN_TAB",
+    "SWITCH_TAB",
+    "CLOSE_TAB",
+    "DOWNLOAD",
+    "UPLOAD",
+    "PRESS",
+    "ACCEPT_DIALOG",
+    "DISMISS_DIALOG",
+    "DONE",
+    "BLOCKED",
+    "ASK_USER",
+];
+/** Operations offered to the decision model in the normal loop. */
+export const DECISION_OPERATIONS = [
+    "CLICK",
+    "TYPE_TEXT",
+    "SELECT",
+    "SCROLL_UP",
+    "SCROLL_DOWN",
+    "WAIT",
+    "BACK",
+    "FORWARD",
+    "OPEN_TAB",
+    "SWITCH_TAB",
+    "DOWNLOAD",
+    "UPLOAD",
+    "ACCEPT_DIALOG",
+    "DISMISS_DIALOG",
+    "DONE",
+    "BLOCKED",
+    "ASK_USER",
+];
+/** Operations the runtime executes but never offers to the model by default. */
+export const INTERNAL_OPERATIONS = ["CLOSE_TAB", "PRESS"];
+export const TARGET_HEADS = [
+    "click_target",
+    "type_text_target",
+    "select_target",
+    "switch_tab_target",
+    "open_tab_target",
+    "download_target",
+    "upload_target",
+];
+export const headForOperation = (op) => {
+    switch (op) {
+        case "CLICK":
+            return "click_target";
+        case "TYPE_TEXT":
+            return "type_text_target";
+        case "SELECT":
+            return "select_target";
+        case "SWITCH_TAB":
+            return "switch_tab_target";
+        case "OPEN_TAB":
+            return "open_tab_target";
+        case "DOWNLOAD":
+            return "download_target";
+        case "UPLOAD":
+            return "upload_target";
+        default:
+            return undefined;
+    }
+};
+export const operationOf = (action) => action.op;
+/** Actions with possibly harmful side effects if duplicated (PRD §29). */
+const UNKNOWN_EFFECT_OPS = new Set(["CLICK", "UPLOAD", "DOWNLOAD"]);
+export const mayHaveUnknownEffect = (action) => UNKNOWN_EFFECT_OPS.has(action.op);
+/** Deterministic signature used for loop detection (PRD §30). */
+export const actionSignature = (action) => {
+    const base = action.op;
+    switch (action.op) {
+        case "CLICK":
+            return `${base}:${action.ref.nodeId}`;
+        case "TYPE_TEXT":
+            return `${base}:${action.ref.nodeId}:${action.text.length}`;
+        case "SELECT":
+            return `${base}:${action.ref.nodeId}:${action.option.index}`;
+        case "SCROLL_UP":
+        case "SCROLL_DOWN":
+            return `${base}:${action.ref?.nodeId ?? "page"}:${action.amount}`;
+        case "SWITCH_TAB":
+        case "CLOSE_TAB":
+            return `${base}:${action.tabId}`;
+        case "OPEN_TAB":
+            return `${base}:${safeHost(action.url)}`;
+        case "DOWNLOAD":
+            return `${base}:${action.ref.nodeId}`;
+        case "UPLOAD":
+            return `${base}:${action.ref.nodeId}:${action.artifactId}`;
+        case "PRESS":
+            return `${base}:${action.key}`;
+        default:
+            return base;
+    }
+};
+const safeHost = (url) => {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "invalid";
+    }
+};
+export const describeAction = (action) => {
+    switch (action.op) {
+        case "CLICK":
+            return `CLICK [${action.ref.index}]`;
+        case "TYPE_TEXT":
+            return `${action.mode === "fill" ? "TYPE" : "KEYBOARD"} [${action.ref.index}] "${truncate(action.text, 60)}"`;
+        case "SELECT":
+            return `SELECT [${action.ref.index}] -> ${truncate(action.option.label, 40)}`;
+        case "SCROLL_UP":
+        case "SCROLL_DOWN":
+            return `${action.op} ${action.amount}`;
+        case "WAIT":
+            return `WAIT ${action.ms}ms`;
+        case "OPEN_TAB":
+            return `OPEN_TAB ${truncate(action.url, 80)}`;
+        case "SWITCH_TAB":
+        case "CLOSE_TAB":
+            return `${action.op} ${action.tabId}`;
+        case "DOWNLOAD":
+            return `DOWNLOAD [${action.ref.index}]`;
+        case "UPLOAD":
+            return `UPLOAD ${action.artifactId} -> [${action.ref.index}]`;
+        case "PRESS":
+            return `PRESS ${action.key}`;
+        case "ACCEPT_DIALOG":
+            return "ACCEPT_DIALOG";
+        case "DISMISS_DIALOG":
+            return "DISMISS_DIALOG";
+        default:
+            return action.op;
+    }
+};
+const truncate = (s, n) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`);
+/** Actions that are a claim about task state rather than a browser interaction. */
+export const isTerminalClaim = (op) => op === "DONE" || op === "BLOCKED" || op === "ASK_USER";
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

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

package/dist/budget.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Budgets and usage accounting (PRD §45, §55).
+ */
+export interface Budgets {
+    maxSteps: number;
+    maxDecisionCalls: number;
+    maxPlannerCalls: number;
+    maxTextCalls: number;
+    maxVisionCalls: number;
+    maxCostUsd: number;
+    maxDurationMs: number;
+    maxRecoveryAttemptsPerStep: number;
+    maxRecoveryAttemptsTotal: number;
+    maxConsecutiveNoProgress: number;
+    maxHumanHelpRequests: number;
+}
+export declare const DEFAULT_BUDGETS: Budgets;
+export type ProviderRole = "decision" | "planner" | "text" | "vision";
+export interface Usage {
+    provider: string;
+    model?: string;
+    calls?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+}
+export interface BudgetSnapshot {
+    steps: number;
+    calls: Record<ProviderRole, number>;
+    costUsd: number;
+    durationMs: number;
+    recoveryAttempts: number;
+    humanHelpRequests: number;
+}
+export type BudgetVerdict = {
+    kind: "continue";
+} | {
+    kind: "degrade";
+    reason: string;
+} | {
+    kind: "ask_user";
+    reason: string;
+} | {
+    kind: "fail";
+    reason: string;
+    code: "BUDGET_EXHAUSTED";
+};
+export interface CostRates {
+    /** USD per million input tokens. */
+    inputPerMTok?: number;
+    /** USD per million output tokens. */
+    outputPerMTok?: number;
+    /** USD per call, when a provider prices per call. */
+    perCall?: number;
+}
+export declare const estimateCost: (usage: Usage, rates: CostRates | undefined) => number;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,0BAA0B,EAAE,MAAM,CAAC;IACnC,wBAAwB,EAAE,MAAM,CAAC;IACjC,wBAAwB,EAAE,MAAM,CAAC;IACjC,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,eAAe,EAAE,OAY7B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEtE,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE/D,MAAM,WAAW,SAAS;IACxB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,EAAE,OAAO,SAAS,GAAG,SAAS,KAAG,MAMzE,CAAC"}

package/dist/budget.js

@@ -0,0 +1,25 @@
+/**
+ * Budgets and usage accounting (PRD §45, §55).
+ */
+export const DEFAULT_BUDGETS = {
+    maxSteps: 80,
+    maxDecisionCalls: 160,
+    maxPlannerCalls: 12,
+    maxTextCalls: 24,
+    maxVisionCalls: 8,
+    maxCostUsd: 2.0,
+    maxDurationMs: 20 * 60 * 1000,
+    maxRecoveryAttemptsPerStep: 3,
+    maxRecoveryAttemptsTotal: 12,
+    maxConsecutiveNoProgress: 3,
+    maxHumanHelpRequests: 4,
+};
+export const estimateCost = (usage, rates) => {
+    if (!rates)
+        return usage.costUsd ?? 0;
+    const calls = usage.calls ?? 1;
+    const inCost = ((usage.inputTokens ?? 0) / 1_000_000) * (rates.inputPerMTok ?? 0);
+    const outCost = ((usage.outputTokens ?? 0) / 1_000_000) * (rates.outputPerMTok ?? 0);
+    return (usage.costUsd ?? 0) + inCost + outCost + (rates.perCall ?? 0) * calls;
+};
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,MAAM,CAAC,MAAM,eAAe,GAAY;IACtC,QAAQ,EAAE,EAAE;IACZ,gBAAgB,EAAE,GAAG;IACrB,eAAe,EAAE,EAAE;IACnB,YAAY,EAAE,EAAE;IAChB,cAAc,EAAE,CAAC;IACjB,UAAU,EAAE,GAAG;IACf,aAAa,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IAC7B,0BAA0B,EAAE,CAAC;IAC7B,wBAAwB,EAAE,EAAE;IAC5B,wBAAwB,EAAE,CAAC;IAC3B,oBAAoB,EAAE,CAAC;CACxB,CAAC;AAqCF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAY,EAAE,KAA4B,EAAU,EAAE;IACjF,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC;IAClF,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC;IACrF,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,MAAM,GAAG,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;AAChF,CAAC,CAAC"}

package/dist/capabilities.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Protocol versioning and capability negotiation (PRD §47, §48).
+ *
+ * Daemon ↔ SDK ↔ browser backend must agree explicitly. Unsupported features
+ * fail loudly; they are never silently emulated with unsafe substitutes.
+ */
+export declare const PROTOCOL_VERSION: "1.0";
+export declare const BACKEND_CAPABILITIES: readonly ["observe", "click", "type", "select", "scroll", "press", "history", "tabs", "open_tab", "close_tab", "borrow", "return_tab", "human_help", "download", "upload", "console", "network", "screenshot", "canvas", "dialog_handling", "clipboard"];
+export type BackendCapability = (typeof BACKEND_CAPABILITIES)[number];
+export interface CapabilitySet {
+    protocol: typeof PROTOCOL_VERSION;
+    browser: Partial<Record<BackendCapability, boolean>>;
+    /** Session/client level capabilities (daemon ↔ client). */
+    runtime: {
+        borrow_tabs: boolean;
+        request_help: boolean;
+        downloads: boolean;
+        uploads: boolean;
+        canvas_click: boolean;
+        approvals: boolean;
+        human_takeover: boolean;
+    };
+}
+export declare const RUNTIME_CAPABILITIES: CapabilitySet["runtime"];
+export declare class UnsupportedCapabilityError extends Error {
+    readonly capability: BackendCapability | string;
+    constructor(capability: BackendCapability | string, detail?: string);
+}
+export declare const supports: (caps: Partial<Record<BackendCapability, boolean>>, capability: BackendCapability) => boolean;
+export declare const requireCapability: (caps: Partial<Record<BackendCapability, boolean>>, capability: BackendCapability) => void;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,gBAAgB,EAAG,KAAc,CAAC;AAE/C,eAAO,MAAM,oBAAoB,0PAsBvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,gBAAgB,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,2DAA2D;IAC3D,OAAO,EAAE;QACP,WAAW,EAAE,OAAO,CAAC;QACrB,YAAY,EAAE,OAAO,CAAC;QACtB,SAAS,EAAE,OAAO,CAAC;QACnB,OAAO,EAAE,OAAO,CAAC;QACjB,YAAY,EAAE,OAAO,CAAC;QACtB,SAAS,EAAE,OAAO,CAAC;QACnB,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,SAAS,CAQzD,CAAC;AAEF,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAAC;gBACpC,UAAU,EAAE,iBAAiB,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAQpE;AAED,eAAO,MAAM,QAAQ,GACnB,MAAM,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,EACjD,YAAY,iBAAiB,KAC5B,OAAoC,CAAC;AAExC,eAAO,MAAM,iBAAiB,GAC5B,MAAM,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,EACjD,YAAY,iBAAiB,KAC5B,IAEF,CAAC"}

package/dist/capabilities.js

@@ -0,0 +1,54 @@
+/**
+ * Protocol versioning and capability negotiation (PRD §47, §48).
+ *
+ * Daemon ↔ SDK ↔ browser backend must agree explicitly. Unsupported features
+ * fail loudly; they are never silently emulated with unsafe substitutes.
+ */
+export const PROTOCOL_VERSION = "1.0";
+export const BACKEND_CAPABILITIES = [
+    "observe",
+    "click",
+    "type",
+    "select",
+    "scroll",
+    "press",
+    "history",
+    "tabs",
+    "open_tab",
+    "close_tab",
+    "borrow",
+    "return_tab",
+    "human_help",
+    "download",
+    "upload",
+    "console",
+    "network",
+    "screenshot",
+    "canvas",
+    "dialog_handling",
+    "clipboard",
+];
+export const RUNTIME_CAPABILITIES = {
+    borrow_tabs: true,
+    request_help: true,
+    downloads: true,
+    uploads: true,
+    canvas_click: false,
+    approvals: true,
+    human_takeover: true,
+};
+export class UnsupportedCapabilityError extends Error {
+    capability;
+    constructor(capability, detail) {
+        super(`unsupported capability "${capability}"${detail ? `: ${detail}` : ""}. ` +
+            `The selected backend does not advertise it; refusing to emulate unsafely.`);
+        this.name = "UnsupportedCapabilityError";
+        this.capability = capability;
+    }
+}
+export const supports = (caps, capability) => caps[capability] === true;
+export const requireCapability = (caps, capability) => {
+    if (!supports(caps, capability))
+        throw new UnsupportedCapabilityError(capability);
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAc,CAAC;AAE/C,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS;IACT,OAAO;IACP,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,SAAS;IACT,MAAM;IACN,UAAU;IACV,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;IACT,SAAS;IACT,YAAY;IACZ,QAAQ;IACR,iBAAiB;IACjB,WAAW;CACH,CAAC;AAmBX,MAAM,CAAC,MAAM,oBAAoB,GAA6B;IAC5D,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,IAAI;IAClB,SAAS,EAAE,IAAI;IACf,OAAO,EAAE,IAAI;IACb,YAAY,EAAE,KAAK;IACnB,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,IAAI;CACrB,CAAC;AAEF,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,UAAU,CAA6B;IAChD,YAAY,UAAsC,EAAE,MAAe;QACjE,KAAK,CACH,2BAA2B,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI;YACtE,2EAA2E,CAC9E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,IAAiD,EACjD,UAA6B,EACpB,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AAExC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,IAAiD,EACjD,UAA6B,EACvB,EAAE;IACR,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;QAAE,MAAM,IAAI,0BAA0B,CAAC,UAAU,CAAC,CAAC;AACpF,CAAC,CAAC"}