@mlola/browser-core 0.1.0

package/dist/decision-validation.js

@@ -0,0 +1,114 @@
+/**
+ * Decision response validation (PRD §16).
+ *
+ * Provider output is never trusted blindly: the selected choice must exist and
+ * be top-ranked, probabilities must be well-formed, and the target must belong
+ * to the selected operation's head. An invalid response is discarded and turns
+ * into a provider error for the recovery ladder.
+ */
+import { headForOperation } from "@mlola/browser-protocol";
+const SUM_TOLERANCE = 0.12;
+export const validateDecision = (decision, space, opts = {}) => {
+    const issues = [];
+    const warnings = [];
+    if (!space.operations.includes(decision.operation)) {
+        issues.push({
+            code: "UNKNOWN_OPERATION",
+            detail: `operation "${decision.operation}" is not in the offered space (${space.operations.join(", ")})`,
+        });
+        return { ok: false, issues, warnings };
+    }
+    const opResult = checkChoices(`operation`, decision.operation, space.operations, decision.operationProbabilities, decision.operationConfidence, { min: opts.minOperationConfidence ?? 0, requireTop: opts.requireTopChoice ?? true });
+    issues.push(...opResult.issues);
+    warnings.push(...opResult.warnings);
+    const head = headForOperation(decision.operation);
+    if (head === undefined) {
+        if (decision.target !== undefined) {
+            warnings.push({
+                code: "UNEXPECTED_TARGET",
+                detail: `operation ${decision.operation} takes no target but a target was returned`,
+            });
+        }
+        return { ok: issues.length === 0, issues, warnings };
+    }
+    const candidates = space.heads[head] ?? [];
+    if (candidates.length === 0) {
+        issues.push({
+            code: "EMPTY_TARGET_HEAD",
+            detail: `operation ${decision.operation} has no compatible targets`,
+        });
+        return { ok: false, issues, warnings };
+    }
+    if (decision.target === undefined || decision.target.length === 0) {
+        issues.push({
+            code: "MISSING_TARGET",
+            detail: `operation ${decision.operation} requires a target from ${head}`,
+        });
+        return { ok: false, issues, warnings };
+    }
+    const keys = candidates.map((c) => c.key);
+    const targetResult = checkChoices(`target for ${head}`, decision.target, keys, decision.targetProbabilities, decision.targetConfidence, { min: opts.minTargetConfidence ?? 0, requireTop: opts.requireTopChoice ?? true });
+    issues.push(...targetResult.issues);
+    warnings.push(...targetResult.warnings);
+    return {
+        ok: issues.length === 0,
+        issues,
+        warnings,
+        targetHead: head,
+        targetKey: decision.target,
+    };
+};
+const checkChoices = (what, selected, allowed, probabilities, confidence, opts) => {
+    const issues = [];
+    const warnings = [];
+    if (!allowed.includes(selected)) {
+        issues.push({ code: "UNKNOWN_CHOICE", detail: `${what}: choice "${selected}" is not offered` });
+        return { issues, warnings };
+    }
+    if (confidence !== undefined) {
+        if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+            issues.push({
+                code: "BAD_CONFIDENCE",
+                detail: `${what}: confidence ${confidence} is not in [0,1]`,
+            });
+        }
+        else if (opts.min > 0 && confidence < opts.min) {
+            issues.push({
+                code: "LOW_CONFIDENCE",
+                detail: `${what}: confidence ${confidence.toFixed(3)} < minimum ${opts.min}`,
+            });
+        }
+    }
+    if (probabilities !== undefined) {
+        const entries = Object.entries(probabilities);
+        let sum = 0;
+        for (const [key, value] of entries) {
+            if (!Number.isFinite(value) || value < 0 || value > 1) {
+                issues.push({ code: "BAD_PROBABILITY", detail: `${what}: probability ${key}=${value} is invalid` });
+                continue;
+            }
+            sum += value;
+            if (!allowed.includes(key)) {
+                warnings.push({ code: "EXTRA_PROBABILITY", detail: `${what}: probability key "${key}" is not offered` });
+            }
+        }
+        if (entries.length > 0 && Math.abs(sum - 1) > SUM_TOLERANCE) {
+            warnings.push({
+                code: "PROBABILITY_SUM",
+                detail: `${what}: probabilities sum to ${sum.toFixed(3)}`,
+            });
+        }
+        if (opts.requireTop && entries.length > 0) {
+            const top = entries.reduce((a, b) => (b[1] > a[1] ? b : a));
+            if (top[0] !== selected && top[1] > (probabilities[selected] ?? 0) + 0.02) {
+                issues.push({
+                    code: "SELECTED_NOT_TOP",
+                    detail: `${what}: selected "${selected}" but top choice is "${top[0]}" (${top[1].toFixed(3)})`,
+                });
+            }
+        }
+    }
+    return { issues, warnings };
+};
+export const terminalOperation = (op) => op === "DONE" || op === "BLOCKED" || op === "ASK_USER";
+//# sourceMappingURL=decision-validation.js.map

package/dist/decision-validation.js.map

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

package/dist/executor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Safe executor (PRD §23, §24, §25, §26, §29).
+ *
+ *   freshness → preflight (visibility, enabled, geometry, occlusion) →
+ *   typed execution → bounded settle → fresh observation → verification
+ *
+ * Failures are classified, never retried blindly, and every step records
+ * enough evidence for the recovery ladder to choose a strategy.
+ */
+import { RuntimeError } from "@mlola/browser-protocol";
+import type { BrowserSnapshot, DecidedAction } from "@mlola/browser-protocol";
+import type { ActionOutcome, BrowserBackend } from "@mlola/browser-backend";
+import type { ArtifactRecord, ArtifactRegistry } from "@mlola/browser-artifacts";
+import type { EventLog } from "@mlola/browser-trace";
+import { type StepVerification } from "./verifier.ts";
+export interface ExecutorOptions {
+    backend: BrowserBackend;
+    events: EventLog;
+    artifacts: ArtifactRegistry;
+    sessionId: string;
+    runId: string;
+}
+export interface ExecutorResult {
+    ok: boolean;
+    outcome: ActionOutcome;
+    /** Observation taken after the action; reusable as the next step's input. */
+    after: BrowserSnapshot;
+    verification: StepVerification;
+    artifact?: ArtifactRecord;
+    failure?: RuntimeError;
+}
+export declare class Executor {
+    #private;
+    constructor(opts: ExecutorOptions);
+    execute(decided: DecidedAction, before: BrowserSnapshot): Promise<ExecutorResult>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAuD,MAAM,yBAAyB,CAAC;AAC5G,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAGd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,aAAa,CAAC;IACvB,6EAA6E;IAC7E,KAAK,EAAE,eAAe,CAAC;IACvB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,qBAAa,QAAQ;;gBAOP,IAAI,EAAE,eAAe;IAQ3B,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAwLxF"}

package/dist/executor.js

@@ -0,0 +1,209 @@
+/**
+ * Safe executor (PRD §23, §24, §25, §26, §29).
+ *
+ *   freshness → preflight (visibility, enabled, geometry, occlusion) →
+ *   typed execution → bounded settle → fresh observation → verification
+ *
+ * Failures are classified, never retried blindly, and every step records
+ * enough evidence for the recovery ladder to choose a strategy.
+ */
+import { RuntimeError, failureRecord, mayHaveUnknownEffect, describeAction } from "@mlola/browser-protocol";
+import { classifyError } from "@mlola/browser-recovery";
+import { verifyStep } from "./verifier.js";
+export class Executor {
+    #backend;
+    #events;
+    #artifacts;
+    #sessionId;
+    #runId;
+    constructor(opts) {
+        this.#backend = opts.backend;
+        this.#events = opts.events;
+        this.#artifacts = opts.artifacts;
+        this.#sessionId = opts.sessionId;
+        this.#runId = opts.runId;
+    }
+    async execute(decided, before) {
+        const action = decided.action;
+        // 1. Freshness + target validation (PRD §23, §24).
+        const preflight = await this.#backend.preflight(this.#sessionId, action);
+        if (!preflight.ok) {
+            const err = new RuntimeError(preflight.code ?? "TARGET_INVALID", preflight.detail ?? "preflight failed", {
+                evidence: preflight.evidence ?? {},
+                retryable: true,
+            });
+            this.#events.emit("ACTION_FAILED", { stepId: decided.stepId, action: describeAction(action), failure: failureRecord(err) });
+            return this.#failure(err, before, decided, preflight.evidence?.["snapshot"]);
+        }
+        // 2. Execute the typed action.
+        let outcome;
+        try {
+            if (action.op === "UPLOAD") {
+                this.#events.emit("UPLOAD_STARTED", {
+                    artifactId: action.artifactId,
+                    nodeId: action.ref.nodeId,
+                    mechanism: action.mechanism,
+                });
+            }
+            outcome = await this.#backend.execute(this.#sessionId, action);
+        }
+        catch (err) {
+            const classified = classifyError(err, { unknownEffect: mayHaveUnknownEffect(action) });
+            const runtimeError = new RuntimeError(classified.code, classified.detail, {
+                cause: err,
+                unknownEffect: classified.unknownEffect,
+            });
+            this.#events.emit("ACTION_FAILED", { stepId: decided.stepId, action: describeAction(action), failure: failureRecord(runtimeError) });
+            if (action.op === "UPLOAD") {
+                this.#events.emit("UPLOAD_FAILED", { artifactId: action.artifactId, reason: classified.detail });
+            }
+            return this.#failure(runtimeError, before, decided);
+        }
+        // 3. Register a downloaded file as an artifact (PRD §35).
+        let artifact;
+        if (outcome.downloadedFile) {
+            const file = outcome.downloadedFile;
+            if (!file.completed || file.failure) {
+                this.#events.emit("DOWNLOAD_FAILED", { reason: file.failure ?? "download did not complete" });
+            }
+            else {
+                try {
+                    artifact = await this.#artifacts.add({
+                        filePath: file.path,
+                        source: "download",
+                        ...(file.suggestedName !== undefined ? { name: file.suggestedName } : {}),
+                        ...(file.url !== undefined ? { sourceUrl: file.url } : {}),
+                    });
+                    const verification = await this.#artifacts.verify(artifact.id);
+                    this.#events.emit("DOWNLOAD_COMPLETED", {
+                        artifact: artifactSummary(artifact),
+                        path: artifact.localPath,
+                        latencyMs: outcome.latencyMs,
+                    });
+                    this.#events.emit("ARTIFACT_CREATED", { artifact: artifactSummary(artifact) });
+                    if (verification.ok)
+                        this.#events.emit("ARTIFACT_VERIFIED", { artifactId: artifact.id, detail: verification.detail });
+                }
+                catch (err) {
+                    this.#events.emit("DOWNLOAD_FAILED", { reason: `failed to register artifact: ${String(err)}` });
+                }
+            }
+        }
+        // 4. Bounded settle + fresh observation; reused by the next step.
+        let after;
+        try {
+            after = await this.#backend.observe(this.#sessionId);
+        }
+        catch (err) {
+            const classified = classifyError(err, { unknownEffect: true });
+            const runtimeError = new RuntimeError(classified.code, classified.detail, {
+                cause: err,
+                unknownEffect: true,
+            });
+            return this.#failure(runtimeError, before, decided, undefined, outcome);
+        }
+        // 5. Deterministic verification.
+        const uploadEvidence = action.op === "UPLOAD" ? this.#uploadEvidence(action, after) : undefined;
+        const verification = verifyStep({
+            action,
+            before,
+            after,
+            outcome,
+            ...(artifact ? { artifact: artifactSummary(artifact) } : {}),
+            artifacts: this.#artifacts.summaries(),
+            ...(uploadEvidence !== undefined ? { uploadEvidence } : {}),
+        });
+        this.#events.emit("ACTION_EXECUTED", {
+            stepId: decided.stepId,
+            action: describeAction(action),
+            latencyMs: outcome.latencyMs,
+            ...(outcome.detail !== undefined ? { detail: outcome.detail } : {}),
+            ...(outcome.unknownEffect ? { unknownEffect: true } : {}),
+        });
+        if (action.op === "UPLOAD") {
+            if (verification.status === "verified") {
+                this.#events.emit("UPLOAD_COMPLETED", {
+                    artifactId: action.artifactId,
+                    evidence: uploadEvidence ?? verification.evidence.map((e) => e.detail).join("; "),
+                });
+            }
+            else {
+                this.#events.emit("UPLOAD_FAILED", {
+                    artifactId: action.artifactId,
+                    reason: verification.evidence.map((e) => e.detail).join("; "),
+                });
+            }
+        }
+        this.#events.emit("ACTION_VERIFIED", { stepId: decided.stepId, verification });
+        if (verification.noEffect) {
+            this.#events.emit("ACTION_NO_EFFECT", {
+                stepId: decided.stepId,
+                action: describeAction(action),
+                reason: verification.evidence.map((e) => e.detail).join("; "),
+            });
+        }
+        const ok = verification.status !== "refuted" && !outcome.unknownEffect;
+        return {
+            ok,
+            outcome,
+            after,
+            verification,
+            ...(artifact ? { artifact } : {}),
+        };
+    }
+    #uploadEvidence(action, after) {
+        const artifact = this.#artifacts.get(action.artifactId);
+        if (!artifact)
+            return undefined;
+        const name = artifact.name;
+        const stem = name.replace(/\.[^.]+$/, "");
+        const haystack = `${after.textSummary}\n${after.nodes.map((n) => `${n.label} ${n.value ?? ""}`).join("\n")}`;
+        if (name.length > 3 && haystack.toLowerCase().includes(name.toLowerCase())) {
+            return `file name "${name}" appears on the page`;
+        }
+        if (stem.length > 4 && haystack.toLowerCase().includes(stem.toLowerCase())) {
+            return `file name stem "${stem}" appears on the page`;
+        }
+        return undefined;
+    }
+    async #failure(error, before, decided, afterOverride, outcome) {
+        let after = afterOverride;
+        if (!after) {
+            try {
+                after = await this.#backend.observe(this.#sessionId);
+            }
+            catch {
+                after = before;
+            }
+        }
+        const verification = {
+            status: "unverified",
+            evidence: [
+                { kind: "runtime_event", ok: false, detail: error.message, at: Date.now() },
+            ],
+        };
+        return {
+            ok: false,
+            outcome: outcome ?? {
+                ok: false,
+                effect: "unknown",
+                latencyMs: 0,
+                ...(error.unknownEffect ? { unknownEffect: true } : {}),
+            },
+            after,
+            verification: verification,
+            failure: error,
+            // rethrow-free: the orchestrator decides the ladder
+        };
+    }
+}
+const artifactSummary = (record) => ({
+    id: record.id,
+    name: record.name,
+    mimeType: record.mimeType,
+    ...(record.documentType ? { documentType: record.documentType } : {}),
+    source: record.source,
+    verified: record.verified,
+    ...(record.sizeBytes !== undefined ? { sizeBytes: record.sizeBytes } : {}),
+});
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

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

package/dist/fallback.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Strong-model decision fallback (PRD §44).
+ *
+ * When the fast path cannot produce a valid decision, the planner role is asked
+ * to choose one operation (and target) from the *same* runtime-built action
+ * space. The answer is validated exactly like a fast-path answer: the model
+ * still never produces a selector, a coordinate or code.
+ */
+import { type DecisionProvider, type PlannerProvider } from "@mlola/browser-protocol";
+export interface FallbackDecisionProviderOptions {
+    planner: PlannerProvider;
+    /** Human-readable reason shown to the model. */
+    reason?: string;
+}
+export declare const createFallbackDecisionProvider: (planner: PlannerProvider, opts?: FallbackDecisionProviderOptions | {
+    planner: PlannerProvider;
+    reason?: string;
+}) => DecisionProvider;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../src/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAyD,KAAK,gBAAgB,EAA8B,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEzK,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,eAAe,CAAC;IACzB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,8BAA8B,GACzC,SAAS,eAAe,EACxB,OAAM,+BAA+B,GAAG;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAgB,KAClG,gBAyBD,CAAC"}

package/dist/fallback.js

@@ -0,0 +1,36 @@
+/**
+ * Strong-model decision fallback (PRD §44).
+ *
+ * When the fast path cannot produce a valid decision, the planner role is asked
+ * to choose one operation (and target) from the *same* runtime-built action
+ * space. The answer is validated exactly like a fast-path answer: the model
+ * still never produces a selector, a coordinate or code.
+ */
+import { RuntimeError } from "@mlola/browser-protocol";
+export const createFallbackDecisionProvider = (planner, opts = { planner }) => ({
+    name: `${planner.name}:fallback`,
+    async decide(input) {
+        if (!planner.chooseAction) {
+            throw new RuntimeError("PROVIDER_FAILURE", "planner provider does not support choosing an action", {
+                retryable: false,
+            });
+        }
+        const fallbackInput = {
+            ...input,
+            reason: opts.reason ?? input.failure ?? "fast path unavailable",
+        };
+        const chosen = await planner.chooseAction(fallbackInput);
+        return {
+            operation: chosen.operation,
+            operationProbabilities: {},
+            operationConfidence: 0,
+            ...(chosen.target !== undefined ? { target: chosen.target } : {}),
+            latencyMs: chosen.latencyMs,
+            provider: chosen.provider,
+            ...(chosen.model !== undefined ? { model: chosen.model } : {}),
+            ...(chosen.usage !== undefined ? { usage: chosen.usage } : {}),
+            ...(chosen.raw !== undefined ? { raw: chosen.raw } : {}),
+        };
+    },
+});
+//# sourceMappingURL=fallback.js.map

package/dist/fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../src/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAoH,MAAM,yBAAyB,CAAC;AAQzK,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAC5C,OAAwB,EACxB,OAAwF,EAAE,OAAO,EAAE,EACjF,EAAE,CAAC,CAAC;IACtB,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,WAAW;IAChC,KAAK,CAAC,MAAM,CAAC,KAAoB;QAC/B,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC1B,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,sDAAsD,EAAE;gBACjG,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QACD,MAAM,aAAa,GAA0B;YAC3C,GAAG,KAAK;YACR,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,uBAAuB;SAChE,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;QACzD,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,sBAAsB,EAAE,EAAE;YAC1B,mBAAmB,EAAE,CAAC;YACtB,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./action-space.ts";
+export * from "./decision-validation.ts";
+export * from "./budget.ts";
+export * from "./executor.ts";
+export * from "./text.ts";
+export * from "./verifier.ts";
+export * from "./state.ts";
+export * from "./fallback.ts";
+export * from "./orchestrator.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./action-space.js";
+export * from "./decision-validation.js";
+export * from "./budget.js";
+export * from "./executor.js";
+export * from "./text.js";
+export * from "./verifier.js";
+export * from "./state.js";
+export * from "./fallback.js";
+export * from "./orchestrator.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/orchestrator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Task orchestrator (PRD §8.1).
+ *
+ * Owns the run lifecycle: observation → action space → decision → policy →
+ * execution → verification → recovery, plus planning, memory, budgets, human
+ * intervention, artifacts and the event log.
+ *
+ * The loop is deliberately boring: every step is observable, every effect is
+ * verified, and no model has direct browser authority.
+ */
+import { type ArtifactSummary, type CostRates, type DecisionProvider, type PlannerProvider, type PolicyConfig, type ProviderRole, type RunEvent, type RunResult, type RunStatus, type TaskSpec, type TextProvider, type VisionProvider } from "@mlola/browser-protocol";
+import { ApprovalBroker } from "@mlola/browser-policy";
+import { type HumanHelpHost } from "@mlola/browser-takeover";
+import type { BrowserBackend } from "@mlola/browser-backend";
+import { type ValidationOptions } from "./decision-validation.ts";
+export interface OrchestratorProviders {
+    decision: DecisionProvider;
+    /** Strong-model fallback for decisions (planner role). */
+    fallbackDecision?: DecisionProvider;
+    text?: TextProvider;
+    planner?: PlannerProvider;
+    vision?: VisionProvider;
+}
+export interface OrchestratorOptions {
+    backend: BrowserBackend;
+    providers: OrchestratorProviders;
+    humanHelp?: HumanHelpHost;
+    approvals?: ApprovalBroker;
+    policy?: Partial<PolicyConfig>;
+    home?: string;
+    validation?: ValidationOptions;
+    costRates?: Partial<Record<ProviderRole, CostRates>>;
+    /** Screenshot policy (PRD §43). Default: off. */
+    screenshot?: "off" | "on-failure" | "always";
+    onEvent?: (event: RunEvent) => void;
+    now?: () => number;
+}
+export declare class TaskOrchestrator {
+    #private;
+    constructor(opts: OrchestratorOptions);
+    get status(): RunStatus;
+    get runId(): string;
+    get events(): readonly RunEvent[];
+    get artifacts(): readonly ArtifactSummary[];
+    pause(reason?: string): void;
+    resume(reason?: string): void;
+    cancel(reason?: string): void;
+    run(task: TaskSpec): Promise<RunResult>;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAgBL,KAAK,eAAe,EAGpB,KAAK,SAAS,EAGd,KAAK,gBAAgB,EAIrB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,SAAS,EAEd,KAAK,QAAQ,EACb,KAAK,YAAY,EAGjB,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,cAAc,EAMf,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAUxG,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,wBAAwB,CAAC;AAE7E,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAOpF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,qBAAqB,CAAC;IACjC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IACrD,iDAAiD;IACjD,UAAU,CAAC,EAAE,KAAK,GAAG,YAAY,GAAG,QAAQ,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAaD,qBAAa,gBAAgB;;gBA+Bf,IAAI,EAAE,mBAAmB;IAqBrC,IAAI,MAAM,IAAI,SAAS,CAEtB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,MAAM,IAAI,SAAS,QAAQ,EAAE,CAEhC;IAED,IAAI,SAAS,IAAI,SAAS,eAAe,EAAE,CAE1C;IAED,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAM5B,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAO7B,MAAM,CAAC,MAAM,SAAsB,GAAG,IAAI;IAMpC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;CAoqC9C"}