@mlola/browser-protocol 0.1.0

package/dist/decision.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Decision provider contracts (PRD §15, §16, §44).
+ *
+ * Provider roles are separate: the fast path decides *whether and where*,
+ * the text helper decides *what text*, the planner handles long horizons and
+ * recovery, vision is a fallback for visual-only surfaces.
+ */
+import type { ActionSpace, OperationId, TargetHeadId, TypedAction } from "./actions.ts";
+import type { ArtifactId, HelpId, RunId, SnapshotId, StepId } from "./ids.ts";
+import type { WorkingMemory } from "./memory.ts";
+import type { BrowserSnapshot, ObservedNode, TabInfo } from "./observation.ts";
+import type { ProvenanceClass } from "./provenance.ts";
+import type { BudgetSnapshot, Usage } from "./budget.ts";
+export interface StepSummary {
+    step: number;
+    action: string;
+    outcome: "ok" | "failed" | "no_effect";
+    detail?: string;
+    url?: string;
+}
+export interface DecisionInput {
+    runId: RunId;
+    step: number;
+    goal: string;
+    subgoal?: string;
+    snapshot: BrowserSnapshot;
+    actionSpace: ActionSpace;
+    memory: WorkingMemory;
+    artifacts: ArtifactSummary[];
+    history: StepSummary[];
+    failure?: string;
+    budget: BudgetSnapshot;
+}
+export interface DecisionOutput {
+    operation: OperationId;
+    operationProbabilities: Record<string, number>;
+    operationConfidence: number;
+    /** Key into the selected operation's target head. */
+    target?: string;
+    targetProbabilities?: Record<string, number>;
+    targetConfidence?: number;
+    usage?: Usage;
+    latencyMs: number;
+    provider: string;
+    model?: string;
+    /** Provider raw response, local only. Never fed back into another model. */
+    raw?: unknown;
+}
+export interface DecisionProvider {
+    readonly name: string;
+    decide(input: DecisionInput): Promise<DecisionOutput>;
+}
+export interface TextGenerationInput {
+    goal: string;
+    subgoal?: string;
+    /** What the field is for, e.g. `textbox "Search"` — structure, not content. */
+    targetLabel: string;
+    targetRole: string;
+    /** Bounded runtime context; never contains secrets. */
+    context?: string;
+    /** Literal candidate values extracted deterministically from the goal. */
+    literals: string[];
+    maxLength?: number;
+}
+export interface TextGenerationOutput {
+    text: string;
+    source: "literal" | "model" | "user";
+    usage?: Usage;
+    latencyMs?: number;
+    provider: string;
+}
+export interface TextProvider {
+    readonly name: string;
+    generate(input: TextGenerationInput): Promise<TextGenerationOutput>;
+}
+export interface PlannerInput {
+    runId: RunId;
+    goal: string;
+    reason: "initial" | "subgoal_complete" | "route_invalid" | "recovery_exhausted" | "goal_changed";
+    snapshotSummary: string;
+    memory: WorkingMemory;
+    history: StepSummary[];
+    artifacts: ArtifactSummary[];
+    previousSubgoals: PlannedSubgoal[];
+    budget: BudgetSnapshot;
+}
+export interface PlannedSubgoal {
+    id: string;
+    description: string;
+    /** Deterministic completion hints when the planner can express them. */
+    hints?: string[];
+    status?: "pending" | "active" | "done" | "failed" | "skipped";
+}
+export interface PlannerOutput {
+    subgoals: PlannedSubgoal[];
+    notes?: string;
+    usage?: Usage;
+    latencyMs?: number;
+    provider: string;
+    model?: string;
+}
+export interface PlannerProvider {
+    readonly name: string;
+    plan(input: PlannerInput): Promise<PlannerOutput>;
+    /**
+     * Strong-model fallback: choose one operation (and target) from the offered
+     * action space. Optional — a planner-only provider degrades to planning.
+     */
+    chooseAction?(input: FallbackDecisionInput): Promise<FallbackDecisionOutput>;
+}
+export interface FallbackDecisionInput extends DecisionInput {
+    /** Why the fast path could not decide. */
+    reason: string;
+}
+export interface FallbackDecisionOutput {
+    operation: OperationId;
+    target?: string;
+    notes?: string;
+    usage?: Usage;
+    latencyMs: number;
+    provider: string;
+    model?: string;
+    raw?: unknown;
+}
+export interface VisionLocateInput {
+    captureId: string;
+    imageBase64: string;
+    question: string;
+    candidates?: string[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export interface VisionLocateOutput {
+    /** Normalized point in the capture, 0..1. */
+    point?: {
+        x: number;
+        y: number;
+    };
+    label?: string;
+    confidence?: number;
+    usage?: Usage;
+    latencyMs?: number;
+    provider: string;
+}
+export interface VisionProvider {
+    readonly name: string;
+    locate(input: VisionLocateInput): Promise<VisionLocateOutput>;
+}
+export interface ArtifactSummary {
+    id: ArtifactId;
+    name: string;
+    mimeType: string;
+    documentType?: string;
+    source: "download" | "upload" | "provided";
+    verified: boolean;
+    sizeBytes?: number;
+}
+export interface CandidateTable {
+    snapshotId: SnapshotId;
+    stepId: StepId;
+    space: ActionSpace;
+    createdAt: number;
+}
+export interface TargetResolution {
+    head: TargetHeadId;
+    key: string;
+    node?: ObservedNode;
+    url?: string;
+    tab?: TabInfo;
+    artifactId?: ArtifactId;
+    provenance: ProvenanceClass;
+}
+export interface HumanHelpSummary {
+    id: HelpId;
+    prompt: string;
+    resolved: boolean;
+}
+export interface DecidedAction {
+    action: TypedAction;
+    decision: DecisionOutput;
+    snapshotId: SnapshotId;
+    stepId: StepId;
+    /** Provenance of the target that justified this action. */
+    targetProvenance?: ProvenanceClass;
+}
+//# sourceMappingURL=decision.d.ts.map

package/dist/decision.d.ts.map

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

package/dist/decision.js

@@ -0,0 +1,9 @@
+/**
+ * Decision provider contracts (PRD §15, §16, §44).
+ *
+ * Provider roles are separate: the fast path decides *whether and where*,
+ * the text helper decides *what text*, the planner handles long horizons and
+ * recovery, vision is a fallback for visual-only surfaces.
+ */
+export {};
+//# sourceMappingURL=decision.js.map

package/dist/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Failure classification (PRD §28.1) and the runtime error type.
+ *
+ * Failure classes are produced by deterministic code (executor, verifier,
+ * provider adapters) and drive the recovery ladder. A model may observe them,
+ * but never invents them.
+ */
+export declare const FAILURE_CLASSES: readonly ["STALE_DECISION", "DETACHED_TARGET", "TARGET_COVERED", "CLICK_INTERCEPTED", "TARGET_INVALID", "NAVIGATION_TIMEOUT", "PAGE_MUTATED", "UNEXPECTED_DIALOG", "UNEXPECTED_TAB", "DOWNLOAD_FAILED", "UPLOAD_FAILED", "FILL_MISMATCH", "SELECT_MISMATCH", "NETWORK_FAILURE", "PROVIDER_FAILURE", "DECISION_INVALID", "POLICY_DENIED", "APPROVAL_DENIED", "SECRET_TARGET", "BUDGET_EXHAUSTED", "NO_PROGRESS", "LOOP_DETECTED", "UNKNOWN_EFFECT", "EXECUTION_FAILED", "TARGET_NOT_FOUND", "HUMAN_HELP_TIMEOUT", "CANCELLED", "INTERNAL"];
+export type FailureClass = (typeof FAILURE_CLASSES)[number];
+export declare const isRecoverable: (c: FailureClass) => boolean;
+export interface RuntimeErrorOptions {
+    detail?: string;
+    retryable?: boolean;
+    /** Deterministic evidence collected at the failure site. */
+    evidence?: Record<string, unknown>;
+    cause?: unknown;
+    /** True when the action may have executed despite the failure (PRD §29). */
+    unknownEffect?: boolean;
+}
+export declare class RuntimeError extends Error {
+    readonly code: FailureClass;
+    readonly detail: string | undefined;
+    readonly retryable: boolean;
+    readonly evidence: Record<string, unknown>;
+    readonly unknownEffect: boolean;
+    constructor(code: FailureClass, message: string, opts?: RuntimeErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+export declare const asRuntimeError: (err: unknown) => RuntimeError;
+/** Plain object form used in traces and events. */
+export interface FailureRecord {
+    code: FailureClass;
+    message: string;
+    detail?: string;
+    retryable: boolean;
+    unknownEffect: boolean;
+    evidence?: Record<string, unknown>;
+}
+export declare const failureRecord: (err: RuntimeError) => FailureRecord;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,eAAe,2gBA6BlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AA4B5D,eAAO,MAAM,aAAa,GAAI,GAAG,YAAY,KAAG,OAA6B,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB;IAU/E,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAUlC;AAED,eAAO,MAAM,cAAc,GAAI,KAAK,OAAO,KAAG,YAI7C,CAAC;AAEF,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,eAAO,MAAM,aAAa,GAAI,KAAK,YAAY,KAAG,aAOhD,CAAC"}

package/dist/errors.js

@@ -0,0 +1,104 @@
+/**
+ * Failure classification (PRD §28.1) and the runtime error type.
+ *
+ * Failure classes are produced by deterministic code (executor, verifier,
+ * provider adapters) and drive the recovery ladder. A model may observe them,
+ * but never invents them.
+ */
+export const FAILURE_CLASSES = [
+    "STALE_DECISION",
+    "DETACHED_TARGET",
+    "TARGET_COVERED",
+    "CLICK_INTERCEPTED",
+    "TARGET_INVALID",
+    "NAVIGATION_TIMEOUT",
+    "PAGE_MUTATED",
+    "UNEXPECTED_DIALOG",
+    "UNEXPECTED_TAB",
+    "DOWNLOAD_FAILED",
+    "UPLOAD_FAILED",
+    "FILL_MISMATCH",
+    "SELECT_MISMATCH",
+    "NETWORK_FAILURE",
+    "PROVIDER_FAILURE",
+    "DECISION_INVALID",
+    "POLICY_DENIED",
+    "APPROVAL_DENIED",
+    "SECRET_TARGET",
+    "BUDGET_EXHAUSTED",
+    "NO_PROGRESS",
+    "LOOP_DETECTED",
+    "UNKNOWN_EFFECT",
+    "EXECUTION_FAILED",
+    "TARGET_NOT_FOUND",
+    "HUMAN_HELP_TIMEOUT",
+    "CANCELLED",
+    "INTERNAL",
+];
+/** Failures where re-observing and re-deciding is safe. */
+const RECOVERABLE = new Set([
+    "STALE_DECISION",
+    "DETACHED_TARGET",
+    "TARGET_COVERED",
+    "CLICK_INTERCEPTED",
+    "TARGET_INVALID",
+    "NAVIGATION_TIMEOUT",
+    "PAGE_MUTATED",
+    "UNEXPECTED_DIALOG",
+    "UNEXPECTED_TAB",
+    "DOWNLOAD_FAILED",
+    "UPLOAD_FAILED",
+    "FILL_MISMATCH",
+    "SELECT_MISMATCH",
+    "NETWORK_FAILURE",
+    "PROVIDER_FAILURE",
+    "DECISION_INVALID",
+    "TARGET_NOT_FOUND",
+    "NO_PROGRESS",
+    "LOOP_DETECTED",
+    "UNKNOWN_EFFECT",
+    "EXECUTION_FAILED",
+    "INTERNAL",
+]);
+export const isRecoverable = (c) => RECOVERABLE.has(c);
+export class RuntimeError extends Error {
+    code;
+    detail;
+    retryable;
+    evidence;
+    unknownEffect;
+    constructor(code, message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = "RuntimeError";
+        this.code = code;
+        this.detail = opts.detail;
+        this.retryable = opts.retryable ?? isRecoverable(code);
+        this.evidence = opts.evidence ?? {};
+        this.unknownEffect = opts.unknownEffect ?? false;
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            detail: this.detail,
+            retryable: this.retryable,
+            unknownEffect: this.unknownEffect,
+            evidence: this.evidence,
+        };
+    }
+}
+export const asRuntimeError = (err) => {
+    if (err instanceof RuntimeError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new RuntimeError("INTERNAL", `unexpected error: ${message}`, { cause: err });
+};
+export const failureRecord = (err) => ({
+    code: err.code,
+    message: err.message,
+    ...(err.detail !== undefined ? { detail: err.detail } : {}),
+    retryable: err.retryable,
+    unknownEffect: err.unknownEffect,
+    ...(Object.keys(err.evidence).length > 0 ? { evidence: err.evidence } : {}),
+});
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Event-sourced run log (PRD §41, §42).
+ *
+ * The log is append-only. Every decision, policy outcome, execution result,
+ * verification and recovery step is recorded with enough context to replay and
+ * debug a run locally.
+ */
+import type { ArtifactSummary, DecisionOutput, PlannerOutput, StepSummary } from "./decision.ts";
+import type { FailureRecord } from "./errors.ts";
+import type { ArtifactId, HelpId, RunId, SessionId, SnapshotId, StepId, TabId } from "./ids.ts";
+import type { Usage } from "./budget.ts";
+import type { ApprovalResolution, PermissionMode, PolicyOutcome } from "./policy.ts";
+import type { VerificationResult } from "./verification.ts";
+import type { RunStatus } from "./task.ts";
+export interface RunEventPayloads {
+    RUN_CREATED: {
+        goal: string;
+        startUrl?: string;
+        backend: string;
+    };
+    SESSION_CREATED: {
+        sessionId: SessionId;
+        backend: string;
+    };
+    SESSION_CONNECTED: {
+        sessionId: SessionId;
+        agentWindowId?: number;
+    };
+    RUN_STARTED: {
+        runId: RunId;
+    };
+    PLANNER_REQUESTED: {
+        reason: string;
+        step: number;
+    };
+    PLANNER_RECEIVED: {
+        plan: PlannerOutput;
+        subgoalCount: number;
+    };
+    SUBGOAL_STARTED: {
+        subgoal: string;
+        index: number;
+    };
+    SUBGOAL_COMPLETED: {
+        subgoal: string;
+        index: number;
+    };
+    PLAN_EXHAUSTED: {
+        reason: string;
+    };
+    SNAPSHOT_CAPTURED: {
+        snapshotId: SnapshotId;
+        generation: number;
+        url: string;
+        title: string;
+        nodeCount: number;
+        fingerprint: string;
+        latencyMs: number;
+        blocking?: string;
+    };
+    ACTION_SPACE_BUILT: {
+        operations: string[];
+        headSizes: Record<string, number>;
+        quarantined: number;
+    };
+    DECISION_REQUESTED: {
+        step: number;
+        provider: string;
+        operations: number;
+        targets: number;
+    };
+    DECISION_RECEIVED: {
+        decision: DecisionOutput;
+        usage?: Usage;
+    };
+    DECISION_INVALID: {
+        reason: string;
+        raw?: unknown;
+    };
+    FALLBACK_STARTED: {
+        reason: string;
+        from: string;
+        to: string;
+        step: number;
+    };
+    FALLBACK_COMPLETED: {
+        provider: string;
+        ok: boolean;
+        detail?: string;
+    };
+    POLICY_ALLOWED: {
+        outcome: PolicyOutcome;
+        summary: string;
+    };
+    POLICY_DENIED: {
+        outcome: PolicyOutcome;
+        summary: string;
+    };
+    APPROVAL_REQUESTED: {
+        approvalId: string;
+        summary: string;
+        risk: string;
+        url: string;
+    };
+    APPROVAL_RESOLVED: {
+        approvalId: string;
+        resolution: ApprovalResolution;
+    };
+    FRESHNESS_CHECK: {
+        snapshotId: SnapshotId;
+        ok: boolean;
+        reason?: string;
+    };
+    TARGET_VALIDATED: {
+        nodeId: number;
+        ok: boolean;
+        reason?: string;
+    };
+    ACTION_EXECUTED: {
+        stepId: StepId;
+        action: string;
+        latencyMs: number;
+        detail?: string;
+        unknownEffect?: boolean;
+    };
+    ACTION_FAILED: {
+        stepId: StepId;
+        failure: FailureRecord;
+        action: string;
+    };
+    ACTION_VERIFIED: {
+        stepId: StepId;
+        verification: VerificationResult;
+    };
+    ACTION_NO_EFFECT: {
+        stepId: StepId;
+        action: string;
+        reason: string;
+    };
+    STEP_COMPLETED: {
+        step: number;
+        summary: StepSummary;
+    };
+    LOOP_DETECTED: {
+        kind: "same_action" | "cycle" | "no_progress";
+        detail: string;
+        step: number;
+    };
+    RECOVERY_STARTED: {
+        failure: FailureRecord;
+        attempt: number;
+        strategy: string;
+    };
+    RECOVERY_COMPLETED: {
+        ok: boolean;
+        strategy: string;
+        detail?: string;
+    };
+    RECOVERY_ESCALATED: {
+        to: string;
+        reason: string;
+    };
+    DOWNLOAD_STARTED: {
+        url?: string;
+        suggestedName?: string;
+        nodeId?: number;
+    };
+    DOWNLOAD_COMPLETED: {
+        artifact: ArtifactSummary;
+        path: string;
+        latencyMs: number;
+    };
+    DOWNLOAD_FAILED: {
+        reason: string;
+        failure?: FailureRecord;
+    };
+    UPLOAD_STARTED: {
+        artifactId: ArtifactId;
+        nodeId: number;
+        mechanism: string;
+    };
+    UPLOAD_COMPLETED: {
+        artifactId: ArtifactId;
+        evidence: string;
+    };
+    UPLOAD_FAILED: {
+        artifactId: ArtifactId;
+        reason: string;
+    };
+    ARTIFACT_CREATED: {
+        artifact: ArtifactSummary;
+    };
+    ARTIFACT_VERIFIED: {
+        artifactId: ArtifactId;
+        detail: string;
+    };
+    TABS_CHANGED: {
+        tabs: {
+            id: TabId;
+            title: string;
+            url: string;
+            active: boolean;
+            ownership: string;
+        }[];
+    };
+    TAB_BORROWED: {
+        tabId: TabId;
+        approvedBy: string;
+    };
+    TAB_RETURNED: {
+        tabId: TabId;
+        windowId?: number;
+        index?: number;
+    };
+    BLOCKING_UI_DETECTED: {
+        kind: string;
+        title?: string;
+        text?: string;
+    };
+    DIALOG_HANDLED: {
+        kind: string;
+        resolution: string;
+    };
+    HUMAN_HELP_REQUESTED: {
+        helpId: HelpId;
+        prompt: string;
+        kind?: string;
+        timeoutMs?: number;
+    };
+    HUMAN_HELP_PROGRESS: {
+        helpId: HelpId;
+        note: string;
+    };
+    HUMAN_HELP_COMPLETED: {
+        helpId: HelpId;
+        criteriaMet: boolean;
+        detail?: string;
+    };
+    HUMAN_HELP_TIMEOUT: {
+        helpId: HelpId;
+    };
+    TAKEOVER_STARTED: {
+        reason: string;
+        prompt?: string;
+    };
+    TAKEOVER_ENDED: {
+        resumedBy: string;
+    };
+    SECRET_BLOCKED: {
+        reason: string;
+        summary: string;
+    };
+    BUDGET_WARNING: {
+        reason: string;
+        snapshot: Record<string, number>;
+    };
+    BUDGET_EXHAUSTED: {
+        reason: string;
+    };
+    VERIFICATION_RESULT: {
+        verification: VerificationResult;
+        stepId?: StepId;
+    };
+    RUN_COMPLETED: {
+        result: Record<string, unknown>;
+        status: RunStatus;
+    };
+    RUN_FAILED: {
+        failure: FailureRecord;
+        status: RunStatus;
+    };
+    RUN_CANCELLED: {
+        reason: string;
+    };
+    RUN_PAUSED: {
+        reason?: string;
+    };
+    RUN_RESUMED: {
+        reason?: string;
+    };
+    SESSION_STOPPING: {
+        reason: string;
+    };
+    SESSION_STOPPED: {
+        cleanup: Record<string, unknown>;
+    };
+    SCREENSHOT_CAPTURED: {
+        path: string;
+        reason: string;
+        captureId?: string;
+    };
+    PROVIDER_USAGE: {
+        role: string;
+        usage: Usage;
+    };
+    NOTE: {
+        text: string;
+        level?: "info" | "warn" | "error";
+    };
+    ERROR: {
+        failure: FailureRecord;
+    };
+}
+export type RunEventType = keyof RunEventPayloads;
+export type RunEvent = {
+    [K in RunEventType]: {
+        seq: number;
+        ts: number;
+        runId: RunId;
+        sessionId?: SessionId;
+        stepId?: StepId;
+        type: K;
+        payload: RunEventPayloads[K];
+    };
+}[RunEventType];
+export type RunEventOf<K extends RunEventType> = Extract<RunEvent, {
+    type: K;
+}>;
+export declare const RUN_EVENT_TYPES: readonly ["RUN_CREATED", "SESSION_CREATED", "SESSION_CONNECTED", "RUN_STARTED", "PLANNER_REQUESTED", "PLANNER_RECEIVED", "SUBGOAL_STARTED", "SUBGOAL_COMPLETED", "PLAN_EXHAUSTED", "SNAPSHOT_CAPTURED", "ACTION_SPACE_BUILT", "DECISION_REQUESTED", "DECISION_RECEIVED", "DECISION_INVALID", "FALLBACK_STARTED", "FALLBACK_COMPLETED", "POLICY_ALLOWED", "POLICY_DENIED", "APPROVAL_REQUESTED", "APPROVAL_RESOLVED", "FRESHNESS_CHECK", "TARGET_VALIDATED", "ACTION_EXECUTED", "ACTION_FAILED", "ACTION_VERIFIED", "ACTION_NO_EFFECT", "STEP_COMPLETED", "LOOP_DETECTED", "RECOVERY_STARTED", "RECOVERY_COMPLETED", "RECOVERY_ESCALATED", "DOWNLOAD_STARTED", "DOWNLOAD_COMPLETED", "DOWNLOAD_FAILED", "UPLOAD_STARTED", "UPLOAD_COMPLETED", "UPLOAD_FAILED", "ARTIFACT_CREATED", "ARTIFACT_VERIFIED", "TABS_CHANGED", "TAB_BORROWED", "TAB_RETURNED", "BLOCKING_UI_DETECTED", "DIALOG_HANDLED", "HUMAN_HELP_REQUESTED", "HUMAN_HELP_PROGRESS", "HUMAN_HELP_COMPLETED", "HUMAN_HELP_TIMEOUT", "TAKEOVER_STARTED", "TAKEOVER_ENDED", "SECRET_BLOCKED", "BUDGET_WARNING", "BUDGET_EXHAUSTED", "VERIFICATION_RESULT", "RUN_COMPLETED", "RUN_FAILED", "RUN_CANCELLED", "RUN_PAUSED", "RUN_RESUMED", "SESSION_STOPPING", "SESSION_STOPPED", "SCREENSHOT_CAPTURED", "PROVIDER_USAGE", "NOTE", "ERROR"];
+export interface EventSink {
+    emit<K extends RunEventType>(type: K, payload: RunEventPayloads[K], meta?: {
+        stepId?: StepId;
+    }): void;
+}
+export type PermissionModeSummary = PermissionMode;
+//# sourceMappingURL=events.d.ts.map