@tomflow/proflow-execution-browser-extension 0.1.0

package/dist/src/bridge.js

@@ -0,0 +1,288 @@
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer, } from "node:http";
+export class BrowserRealityBridgeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "BrowserRealityBridgeError";
+        this.code = code;
+    }
+}
+const jsonHeaders = {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(value, key) {
+    const item = value[key];
+    if (typeof item !== "string" || item.length === 0)
+        throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", `${key} must be a non-empty string`);
+    return item;
+}
+function numberField(value, key) {
+    const item = value[key];
+    if (typeof item !== "number" || !Number.isFinite(item))
+        throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", `${key} must be a finite number`);
+    return item;
+}
+function parseObservation(value) {
+    if (!isRecord(value))
+        throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "observation must be an object");
+    const tabId = value.tabId;
+    const windowId = value.windowId;
+    const pageState = value.pageState;
+    const activityKind = value.activityKind;
+    if (!Number.isInteger(tabId) || !Number.isInteger(windowId))
+        throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "observation tab and window identity must be integers");
+    if (!["IDLE", "BUSY", "BLOCKED", "UNKNOWN"].includes(String(pageState)))
+        throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "observation page state is invalid");
+    if (activityKind !== null &&
+        ![
+            "GENERATING",
+            "ACTION_PERMISSION",
+            "ACTION_RUNNING",
+            "WAITING_HUMAN",
+            "WAITING_PEER",
+            "RECOVERING",
+        ].includes(String(activityKind)))
+        throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "observation activity kind is invalid");
+    return {
+        tabId: tabId,
+        windowId: windowId,
+        url: stringField(value, "url"),
+        contentInstanceId: stringField(value, "contentInstanceId"),
+        pageState: pageState,
+        activityKind: activityKind,
+        observedAt: stringField(value, "observedAt"),
+    };
+}
+function safeEqual(left, right) {
+    const leftBytes = Buffer.from(left);
+    const rightBytes = Buffer.from(right);
+    return (leftBytes.length === rightBytes.length &&
+        timingSafeEqual(leftBytes, rightBytes));
+}
+async function readJson(request) {
+    let body = "";
+    for await (const chunk of request) {
+        body += String(chunk);
+        if (body.length > 100_000)
+            throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "bridge body exceeds 100000 characters");
+    }
+    try {
+        return body.length === 0 ? {} : JSON.parse(body);
+    }
+    catch {
+        throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "bridge body is not valid JSON");
+    }
+}
+function send(response, status, value) {
+    response.writeHead(status, jsonHeaders);
+    response.end(value === undefined ? "" : JSON.stringify(value));
+}
+export async function createBrowserRealityBridgeServer(options) {
+    if (options.token.length < 32)
+        throw new TypeError("bridge token must contain at least 32 characters");
+    if (!/^[a-z]{32}$/.test(options.extensionId))
+        throw new TypeError("extensionId must be a canonical Chromium extension id");
+    const now = options.now ?? (() => new Date());
+    const idFactory = options.idFactory ?? randomUUID;
+    const freshnessMs = options.heartbeatFreshnessMs ?? 10_000;
+    const commandTimeoutMs = options.commandTimeoutMs ?? 15_000;
+    const expectedOrigin = `chrome-extension://${options.extensionId}`;
+    const queue = [];
+    const pending = new Map();
+    let session;
+    let closed = false;
+    const authenticate = (request) => {
+        const authorization = request.headers.authorization;
+        const origin = request.headers.origin;
+        if (!authorization?.startsWith("Bearer ") ||
+            !safeEqual(authorization.slice(7), options.token) ||
+            origin !== expectedOrigin)
+            throw new BrowserRealityBridgeError("BRIDGE_AUTH_INVALID", "bridge authentication failed");
+    };
+    const server = createServer(async (request, response) => {
+        try {
+            response.setHeader("access-control-allow-origin", expectedOrigin);
+            response.setHeader("vary", "origin");
+            if (request.method === "OPTIONS") {
+                response.setHeader("access-control-allow-headers", "authorization, content-type");
+                response.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+                response.writeHead(204);
+                response.end();
+                return;
+            }
+            authenticate(request);
+            const url = new URL(request.url ?? "/", "http://127.0.0.1");
+            if (request.method === "POST" && url.pathname === "/v1/session/hello") {
+                const body = await readJson(request);
+                if (!isRecord(body) ||
+                    stringField(body, "extensionId") !== options.extensionId)
+                    throw new BrowserRealityBridgeError("BRIDGE_AUTH_INVALID", "extension identity mismatch");
+                session = {
+                    extensionInstanceId: stringField(body, "extensionInstanceId"),
+                    lastHeartbeatAt: now().getTime(),
+                };
+                send(response, 200, { accepted: true });
+                return;
+            }
+            if (!session)
+                throw new BrowserRealityBridgeError("BRIDGE_OFFLINE", "extension session has not completed hello");
+            if (url.searchParams.get("extensionInstanceId") !==
+                session.extensionInstanceId)
+                throw new BrowserRealityBridgeError("BRIDGE_AUTH_INVALID", "stale extension session");
+            if (request.method === "POST" &&
+                url.pathname === "/v1/session/heartbeat") {
+                session.lastHeartbeatAt = now().getTime();
+                send(response, 200, { accepted: true });
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/v1/commands/next") {
+                session.lastHeartbeatAt = now().getTime();
+                const command = queue.shift();
+                if (command) {
+                    const tracked = pending.get(command.commandId);
+                    if (tracked)
+                        tracked.stage = "DELIVERED";
+                }
+                send(response, command ? 200 : 204, command);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/v1/commands/result") {
+                const body = await readJson(request);
+                if (!isRecord(body))
+                    throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "command result must be an object");
+                const commandId = stringField(body, "commandId");
+                const command = pending.get(commandId);
+                if (!command)
+                    throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "command result is stale or unknown");
+                pending.delete(commandId);
+                clearTimeout(command.timer);
+                if (body.ok === true)
+                    command.resolve(body.value);
+                else
+                    command.reject(new BrowserRealityBridgeError("BRIDGE_COMMAND_FAILED", typeof body.error === "string"
+                        ? body.error
+                        : "extension command failed"));
+                send(response, 200, { accepted: true });
+                return;
+            }
+            send(response, 404, { error: "NOT_FOUND" });
+        }
+        catch (error) {
+            const bridgeError = error instanceof BrowserRealityBridgeError
+                ? error
+                : new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", error instanceof Error ? error.message : "bridge request failed");
+            send(response, bridgeError.code === "BRIDGE_AUTH_INVALID" ? 401 : 400, {
+                error: bridgeError.code,
+            });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("bridge address missing");
+    const endpoint = `http://127.0.0.1:${address.port}`;
+    const online = () => !closed &&
+        session !== undefined &&
+        now().getTime() - session.lastHeartbeatAt <= freshnessMs;
+    const requestCommand = (command) => {
+        if (!online())
+            return Promise.reject(new BrowserRealityBridgeError("BRIDGE_OFFLINE", "extension heartbeat is not fresh"));
+        const commandId = `browser-command:${idFactory()}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const tracked = pending.get(commandId);
+                if (tracked?.stage === "QUEUED") {
+                    const index = queue.findIndex((item) => item.commandId === commandId);
+                    if (index >= 0)
+                        queue.splice(index, 1);
+                }
+                pending.delete(commandId);
+                reject(new BrowserRealityBridgeError("BRIDGE_COMMAND_TIMEOUT", "extension command result timed out"));
+            }, commandTimeoutMs);
+            const materialized = { ...command, commandId };
+            pending.set(commandId, {
+                command: materialized,
+                stage: "QUEUED",
+                resolve,
+                reject,
+                timer,
+            });
+            queue.push(materialized);
+        });
+    };
+    const browser = {
+        async listTabs() {
+            const value = await requestCommand({ type: "LIST_TABS" });
+            if (!Array.isArray(value))
+                throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "LIST_TABS result must be an array");
+            return value.map(parseObservation);
+        },
+        async open(url) {
+            return parseObservation(await requestCommand({ type: "OPEN", url }));
+        },
+        async observe(tabId) {
+            return parseObservation(await requestCommand({ type: "OBSERVE", tabId }));
+        },
+        async submit(tabId, text, fingerprint) {
+            return parseObservation(await requestCommand({ type: "SUBMIT", tabId, text, fingerprint }));
+        },
+        async hasMessage(tabId, fingerprint) {
+            const value = await requestCommand({
+                type: "VERIFY",
+                tabId,
+                fingerprint,
+            });
+            if (!isRecord(value) || typeof value.verified !== "boolean")
+                throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "VERIFY result is invalid");
+            return value.verified;
+        },
+        async screenshot(tabId) {
+            const value = await requestCommand({ type: "SCREENSHOT", tabId });
+            if (!isRecord(value))
+                throw new BrowserRealityBridgeError("BRIDGE_INPUT_INVALID", "SCREENSHOT result is invalid");
+            return {
+                evidenceRef: stringField(value, "evidenceRef"),
+                dataUrl: stringField(value, "dataUrl"),
+                mimeType: stringField(value, "mimeType"),
+                sizeBytes: numberField(value, "sizeBytes"),
+                hash: stringField(value, "hash"),
+            };
+        },
+        async perform(request, tabId) {
+            return parseObservation(await requestCommand({ type: "PERFORM", tabId, request }));
+        },
+    };
+    return Object.freeze({
+        endpoint,
+        browser,
+        status() {
+            return {
+                online: online(),
+                extensionInstanceId: session?.extensionInstanceId ?? null,
+                queuedCommands: queue.length,
+                pendingCommands: pending.size,
+            };
+        },
+        async close() {
+            closed = true;
+            for (const item of pending.values()) {
+                clearTimeout(item.timer);
+                item.reject(new BrowserRealityBridgeError("BRIDGE_OFFLINE", "bridge server closed"));
+            }
+            pending.clear();
+            queue.length = 0;
+            await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+        },
+    });
+}

package/dist/src/collaboration-carrier.d.ts

@@ -0,0 +1,65 @@
+import { type ExecuteCapabilityRequest } from "@tomflow/proflow-execution-contracts";
+export type PendingCollaborationCarrierMessage = {
+    messageId: string;
+    threadId: string;
+    taskId: string;
+    kind: "QUESTION" | "REPLY";
+    fromRoleRef: string;
+    fromWorkerRef: string;
+    targetRoleRef: string;
+    targetWorkerRef: string;
+    replyToMessageId: string | null;
+    content: string;
+    status: "PENDING";
+    deliveryAttemptCount: number;
+    lastDeliveryErrorCode: string | null;
+    executionRef: string | null;
+    evidenceRef: string | null;
+};
+export interface CollaborationCarrierTaskPort {
+    getWorkerBinding(taskId: string, roleRef: string): Promise<{
+        workerRef: string;
+        conversationLocator: string | null;
+    } | null>;
+}
+export interface CollaborationCarrierAgentPort {
+    listPendingMessages(limit: number): Promise<PendingCollaborationCarrierMessage[]>;
+    getPendingMessage(messageRef: string): Promise<PendingCollaborationCarrierMessage>;
+    reportDeliveryOutcome(input: {
+        messageRef: string;
+        outcome: "DELIVERED" | "FAILED" | "UNKNOWN";
+        executionRef?: string;
+        evidenceRef?: string;
+        errorCode?: string;
+    }): Promise<void>;
+}
+export interface CollaborationCarrierExecutionPort {
+    execute(request: ExecuteCapabilityRequest): Promise<unknown>;
+}
+export type CollaborationCarrierOutcome = {
+    status: "DELIVERED";
+    messageRef: string;
+    executionRef: string;
+} | {
+    status: "PENDING" | "FAILED" | "UNKNOWN";
+    messageRef: string;
+    executionRef: string | null;
+};
+/**
+ * Event-driven Collaboration Carrier application.
+ *
+ * The Agent owner keeps the durable PENDING message. This coordinator owns no
+ * queue and runs no timer. A normal ask/reply event may call `deliverMessage`
+ * once; process startup may call `recoverPending` once as a bounded recovery
+ * scan. Physical delivery remains an Execution effect and logical DELIVERED is
+ * written only after the durable Execution record proves APPLIED + delivered.
+ */
+export declare function createCollaborationCarrierApplication(options: {
+    task: CollaborationCarrierTaskPort;
+    agent: CollaborationCarrierAgentPort;
+    execution: CollaborationCarrierExecutionPort;
+    callerRef?: string;
+}): Readonly<{
+    deliverMessage: (messageRef: string) => Promise<CollaborationCarrierOutcome>;
+    recoverPending: (limit?: number) => Promise<CollaborationCarrierOutcome[]>;
+}>;

package/dist/src/collaboration-carrier.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import { parseExecutionRecord, } from "@tomflow/proflow-execution-contracts";
+function contentFingerprint(message) {
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify({
+        messageId: message.messageId,
+        taskId: message.taskId,
+        targetRoleRef: message.targetRoleRef,
+        targetWorkerRef: message.targetWorkerRef,
+        content: message.content,
+    }))
+        .digest("hex")}`;
+}
+/**
+ * Event-driven Collaboration Carrier application.
+ *
+ * The Agent owner keeps the durable PENDING message. This coordinator owns no
+ * queue and runs no timer. A normal ask/reply event may call `deliverMessage`
+ * once; process startup may call `recoverPending` once as a bounded recovery
+ * scan. Physical delivery remains an Execution effect and logical DELIVERED is
+ * written only after the durable Execution record proves APPLIED + delivered.
+ */
+export function createCollaborationCarrierApplication(options) {
+    const callerRef = options.callerRef ?? "extension:collaboration-carrier";
+    const deliverMessage = async (messageRef) => {
+        const message = await options.agent.getPendingMessage(messageRef);
+        // UNKNOWN is a durable hold state. Startup recovery must not turn an
+        // uncertain physical side effect into another Browser submission.
+        if (message.lastDeliveryErrorCode === "UNKNOWN") {
+            return {
+                status: "UNKNOWN",
+                messageRef,
+                executionRef: message.executionRef,
+            };
+        }
+        if (message.deliveryAttemptCount >= 3) {
+            return {
+                status: "FAILED",
+                messageRef,
+                executionRef: message.executionRef,
+            };
+        }
+        const binding = await options.task.getWorkerBinding(message.taskId, message.targetRoleRef);
+        if (!binding ||
+            binding.workerRef !== message.targetWorkerRef ||
+            !binding.conversationLocator)
+            return { status: "PENDING", messageRef, executionRef: null };
+        const request = {
+            contract: "execution",
+            contractVersion: "1.0.0",
+            idempotencyKey: `collaboration-deliver:${message.messageId}`,
+            callerRef,
+            correlationId: message.messageId,
+            taskId: message.taskId,
+            roleRef: message.targetRoleRef,
+            workerRef: message.targetWorkerRef,
+            capability: "collaboration.deliver",
+            input: {
+                roleRef: message.targetRoleRef,
+                workerRef: message.targetWorkerRef,
+                messageRef: message.messageId,
+                contentFingerprint: contentFingerprint(message),
+            },
+        };
+        const execution = parseExecutionRecord(await options.execution.execute(request));
+        if (execution.status === "SUCCEEDED" &&
+            execution.sideEffectState === "APPLIED" &&
+            execution.result?.capability === "collaboration.deliver" &&
+            execution.result.data.delivered === true) {
+            await options.agent.reportDeliveryOutcome({
+                messageRef: message.messageId,
+                outcome: "DELIVERED",
+                executionRef: execution.executionRef,
+                evidenceRef: execution.result.data.evidenceRef,
+            });
+            return {
+                status: "DELIVERED",
+                messageRef,
+                executionRef: execution.executionRef,
+            };
+        }
+        if (execution.status === "UNKNOWN" ||
+            execution.sideEffectState === "UNKNOWN") {
+            await options.agent.reportDeliveryOutcome({
+                messageRef: message.messageId,
+                outcome: "UNKNOWN",
+                executionRef: execution.executionRef,
+                errorCode: "UNKNOWN",
+            });
+            return {
+                status: "UNKNOWN",
+                messageRef,
+                executionRef: execution.executionRef,
+            };
+        }
+        if (execution.status === "FAILED") {
+            await options.agent.reportDeliveryOutcome({
+                messageRef: message.messageId,
+                outcome: "FAILED",
+                executionRef: execution.executionRef,
+                errorCode: execution.error?.code ?? "EXECUTION_FAILED",
+            });
+            return {
+                status: "FAILED",
+                messageRef,
+                executionRef: execution.executionRef,
+            };
+        }
+        return {
+            status: "PENDING",
+            messageRef,
+            executionRef: execution.executionRef,
+        };
+    };
+    const recoverPending = async (limit = 50) => {
+        if (!Number.isInteger(limit) || limit <= 0 || limit > 100)
+            throw new TypeError("limit must be an integer from 1 through 100");
+        const messages = await options.agent.listPendingMessages(limit);
+        const outcomes = [];
+        for (const message of messages) {
+            try {
+                outcomes.push(await deliverMessage(message.messageId));
+            }
+            catch {
+                // The Agent PENDING fact is authoritative. A failed trigger is left
+                // pending for the next explicit event/recovery; never synthesize a
+                // second physical intent here.
+                outcomes.push({
+                    status: "PENDING",
+                    messageRef: message.messageId,
+                    executionRef: null,
+                });
+            }
+        }
+        return outcomes;
+    };
+    return Object.freeze({ deliverMessage, recoverPending });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,137 @@
+import { type ExecuteCapabilityRequest, type ExecutionExecutorPort, type ExecutorPrecondition } from "@tomflow/proflow-execution-contracts";
+import type { BrowserVisionObservationContext, BrowserVisionPort, TypedVisionObservation } from "./vision.ts";
+export type { BrowserRealityBridgeOptions } from "./bridge.ts";
+export { BrowserRealityBridgeError, createBrowserRealityBridgeServer, } from "./bridge.ts";
+export { type CollaborationCarrierAgentPort, type CollaborationCarrierExecutionPort, type CollaborationCarrierOutcome, type CollaborationCarrierTaskPort, createCollaborationCarrierApplication, type PendingCollaborationCarrierMessage, } from "./collaboration-carrier.ts";
+export { createSystemObserver, type SystemObserverAssessment, type SystemObserverPriority, type SystemObserverReasonFailure, type SystemObserverReasonRequest, type SystemObserverReasonResult, type SystemObserverSnapshotPort, type SystemObserverView, } from "./system-observer.ts";
+export { createTaskObserver, type TaskDriveProjection, type TaskObserverAnomalySignal, type TaskObserverCarrierPort, type TaskObserverDecision, type TaskObserverDiagnosticAssessment, type TaskObserverDiagnosticFailure, type TaskObserverDiagnosticPort, type TaskObserverOwnerPort, type TaskObserverResumeSignal, } from "./task-observer.ts";
+export type { BrowserVisionDeferral, BrowserVisionDeferralReason, BrowserVisionImage, BrowserVisionObservation, BrowserVisionObservationContext, BrowserVisionPort, TypedVisionObservation, VisionMimeType, VisionRecommendedNext, } from "./vision.ts";
+export { deferVisionObservation, isVisionObservationVerified, parseCapturedScreenshot, VISION_OBSERVATION_MIN_CONFIDENCE, visionMimeTypes, visionRecommendedNext, } from "./vision.ts";
+export type BrowserPageState = "IDLE" | "BUSY" | "BLOCKED" | "UNKNOWN";
+export type BrowserActivityKind = "GENERATING" | "ACTION_PERMISSION" | "ACTION_RUNNING" | "WAITING_HUMAN" | "WAITING_PEER" | "RECOVERING" | null;
+export interface BrowserPageObservation {
+    tabId: number;
+    windowId: number;
+    url: string;
+    contentInstanceId: string;
+    pageState: BrowserPageState;
+    activityKind: BrowserActivityKind;
+    observedAt: string;
+}
+export interface BrowserRealityPort {
+    listTabs(): Promise<BrowserPageObservation[]>;
+    open(url: string): Promise<BrowserPageObservation>;
+    observe(tabId: number): Promise<BrowserPageObservation>;
+    submit(tabId: number, text: string, fingerprint: string): Promise<BrowserPageObservation>;
+    hasMessage(tabId: number, fingerprint: string): Promise<boolean>;
+    screenshot(tabId: number): Promise<{
+        evidenceRef: string;
+        dataUrl: string;
+        mimeType: string;
+        sizeBytes: number;
+        hash: string;
+    }>;
+    perform?(request: ExecuteCapabilityRequest, tabId: number): Promise<BrowserPageObservation>;
+}
+export interface TaskBrowserPort {
+    getWorkerBinding(taskId: string, roleRef: string): Promise<{
+        workerRef: string;
+        conversationLocator: string | null;
+    } | null>;
+    bindWorker(input: {
+        taskId: string;
+        roleRef: string;
+        workerRef: string;
+        conversationLocator: string;
+    }): Promise<void>;
+}
+export interface AgentDeliveryPort {
+    getPendingMessage(messageRef: string): Promise<{
+        messageId: string;
+        threadId: string;
+        taskId: string;
+        kind: "QUESTION" | "REPLY";
+        fromRoleRef: string;
+        fromWorkerRef: string;
+        targetRoleRef: string;
+        targetWorkerRef: string;
+        replyToMessageId: string | null;
+        content: string;
+        status: "PENDING";
+    }>;
+    reportPhysicalDelivery(messageRef: string, evidenceRef: string, executionRef: string): Promise<void>;
+}
+export interface ExecutionBrowserOptions {
+    browser: BrowserRealityPort;
+    task: TaskBrowserPort;
+    agent: AgentDeliveryPort;
+    vision?: BrowserVisionPort;
+    idFactory?: () => string;
+    now?: () => Date;
+}
+type ExecutorInvocation = Parameters<ExecutionExecutorPort["execute"]>[0];
+type ExecutorResult = Awaited<ReturnType<ExecutionExecutorPort["execute"]>>;
+type Reconciliation = Awaited<ReturnType<ExecutionExecutorPort["reconcile"]>>;
+export declare class ExecutionBrowserError extends Error {
+    readonly code: "PRECONDITION_FAILED" | "EXECUTOR_UNAVAILABLE" | "UNKNOWN_SIDE_EFFECT" | "CANCELLED";
+    readonly retryable = false;
+    constructor(code: ExecutionBrowserError["code"], message: string);
+}
+declare function parseCarrierIdentity(raw: string): {
+    roleRef: string;
+    workerRef: string | null;
+};
+export declare function createExecutionBrowserExtension(options: ExecutionBrowserOptions): Readonly<{
+    extensionInstanceId: string;
+    parseCarrierIdentity: typeof parseCarrierIdentity;
+    registerContentSession: (observation: BrowserPageObservation) => void;
+    isContentSessionCurrent(tabId: number, contentInstanceId: string): boolean;
+    classifyProgress(input: {
+        pageState: BrowserPageState;
+        nodeInProgress: boolean;
+        millisecondsWithoutProgress: number;
+        legitimateWait: boolean;
+    }): "EXPECTED_WAIT" | "NORMAL" | "PROGRESS_GAP" | "RUNTIME_STALL";
+    inspectScreenshot(tabId: number, observationContext: BrowserVisionObservationContext): Promise<TypedVisionObservation>;
+    handlePermissionFallback(tabId: number, continuationRef: string): Promise<{
+        status: "WAITING_HUMAN";
+        continuationRef: string;
+        evidenceRef: string;
+    }>;
+    getSidePanelSnapshot(): Readonly<{
+        extensionInstanceId: string;
+        observedAt: string;
+        sessions: {
+            tabId: number;
+            windowId: number;
+            url: string;
+            contentInstanceId: string;
+            pageState: BrowserPageState;
+            activityKind: BrowserActivityKind;
+        }[];
+        lanes: {
+            roleRef: string;
+            workerRef: string;
+            tabId: number;
+            pageState: BrowserPageState;
+            activityKind: BrowserActivityKind;
+            currentExecutionRef: string | null;
+            continuationRef: string | null;
+            lastProgressAt: string;
+        }[];
+    }>;
+    execute: (raw: ExecutorInvocation) => Promise<ExecutorResult>;
+    observePrecondition: (request: ExecuteCapabilityRequest) => Promise<ExecutorPrecondition | undefined>;
+    reconcile: (requestRaw: ExecuteCapabilityRequest, preconditionRaw: ExecutorPrecondition) => Promise<Reconciliation>;
+    readArtifact(): Promise<never>;
+    recoveryScan(unfinished: Array<{
+        request: ExecuteCapabilityRequest;
+        effectStarted: boolean;
+    }>): Promise<{
+        status: "ALREADY_COMPLETED";
+        reconciled: never[];
+    } | {
+        status: "COMPLETED";
+        reconciled: import("@tomflow/proflow-execution-contracts").ExecutorReconciliation[];
+    }>;
+}>;