@mlola/decision-jev 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,18 @@
+# @mlola/decision-jev
+
+The TypeSafe Jev fast path for the
+[MLola Browser Runtime](https://mlola.com/browser-runtime): one request per
+decision cycle carrying the operation head plus speculative target heads, with
+response validation before anything can execute.
+
+Also ships the planner/text adapters for any OpenAI-compatible endpoint, and the
+deterministic offline baselines used by tests and demos (`/testing`).
+
+```ts
+import { JevDecisionProvider, buildQuestions, renderDecisionState } from "@mlola/decision-jev";
+import { ScriptedDecisionProvider } from "@mlola/decision-jev/testing";
+```
+
+```bash
+export TYPESAFE_API_KEY=…   # https://typesafe.ai
+```

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * TypeSafe System One (Jev) client.
+ *
+ * Contract: POST {base}/v1/systemone with {model, state, questions}; the reply
+ * carries `answers` keyed by question name. Both `state` and the questions are
+ * built by the runtime — nothing here parses model prose.
+ */
+import { type JevResponse } from "@mlola/browser-protocol";
+import type { JevQuestion } from "./questions.ts";
+export interface JevClientOptions {
+    apiKey?: string;
+    apiKeyEnv?: string;
+    baseUrl?: string;
+    path?: string;
+    model?: string;
+    timeoutMs?: number;
+    /** Bounded retries for transient network/5xx failures. */
+    maxRetries?: number;
+}
+export interface JevCallResult {
+    response: JevResponse;
+    latencyMs: number;
+}
+export declare class JevClient {
+    #private;
+    readonly model: string;
+    constructor(options?: JevClientOptions);
+    get baseUrl(): string;
+    /**
+     * Opens DNS/TCP/TLS before a run is timed. The first request of a session
+     * otherwise pays a handshake premium that has nothing to do with the model.
+     */
+    warmup(): Promise<void>;
+    decide(input: {
+        state: string;
+        questions: Record<string, JevQuestion>;
+    }): Promise<JevCallResult>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmC,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,WAAW,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,qBAAa,SAAS;;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAQX,OAAO,GAAE,gBAAqB;IAkB1C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAUvB,MAAM,CAAC,KAAK,EAAE;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;KACxC,GAAG,OAAO,CAAC,aAAa,CAAC;CAuE3B"}

package/dist/client.js

@@ -0,0 +1,119 @@
+/**
+ * TypeSafe System One (Jev) client.
+ *
+ * Contract: POST {base}/v1/systemone with {model, state, questions}; the reply
+ * carries `answers` keyed by question name. Both `state` and the questions are
+ * built by the runtime — nothing here parses model prose.
+ */
+import { RuntimeError, jevResponseSchema } from "@mlola/browser-protocol";
+const DEFAULT_BASE = "https://api.typesafe.ai";
+const DEFAULT_PATH = "/v1/systemone";
+const DEFAULT_MODEL = "jev-latest";
+export class JevClient {
+    model;
+    #baseUrl;
+    #path;
+    #apiKey;
+    #timeoutMs;
+    #maxRetries;
+    #warmed = false;
+    constructor(options = {}) {
+        const envKey = process.env[options.apiKeyEnv ?? "TYPESAFE_API_KEY"];
+        const apiKey = options.apiKey ?? envKey;
+        if (!apiKey || apiKey.trim().length === 0) {
+            throw new RuntimeError("PROVIDER_FAILURE", `missing Jev API key: set ${options.apiKeyEnv ?? "TYPESAFE_API_KEY"} (or pass apiKey)`, { retryable: false });
+        }
+        this.#apiKey = apiKey.trim();
+        this.#baseUrl = (options.baseUrl ?? process.env["MLOLA_JEV_BASE_URL"] ?? DEFAULT_BASE).replace(/\/+$/, "");
+        this.#path = options.path ?? DEFAULT_PATH;
+        this.model = options.model ?? process.env["MLOLA_JEV_MODEL"] ?? DEFAULT_MODEL;
+        this.#timeoutMs = options.timeoutMs ?? Number(process.env["MLOLA_JEV_TIMEOUT_MS"] ?? 20_000);
+        this.#maxRetries = options.maxRetries ?? 1;
+    }
+    get baseUrl() {
+        return this.#baseUrl;
+    }
+    /**
+     * Opens DNS/TCP/TLS before a run is timed. The first request of a session
+     * otherwise pays a handshake premium that has nothing to do with the model.
+     */
+    async warmup() {
+        if (this.#warmed)
+            return;
+        this.#warmed = true;
+        try {
+            await this.#fetch(`${this.#baseUrl}/v1/models`, { method: "GET" }, 5000);
+        }
+        catch {
+            /* a cold first decision is better than refusing to run */
+        }
+    }
+    async decide(input) {
+        const started = Date.now();
+        const body = JSON.stringify({ model: this.model, state: input.state, questions: input.questions });
+        let lastError;
+        for (let attempt = 0; attempt <= this.#maxRetries; attempt += 1) {
+            try {
+                const response = await this.#fetch(`${this.#baseUrl}${this.#path}`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body,
+                }, this.#timeoutMs);
+                if (response.status >= 500) {
+                    lastError = new Error(`Jev returned ${response.status}`);
+                    continue;
+                }
+                if (!response.ok) {
+                    const text = await response.text().catch(() => "");
+                    throw new RuntimeError("PROVIDER_FAILURE", `Jev request failed with ${response.status}`, {
+                        detail: text.slice(0, 400),
+                        retryable: response.status === 429,
+                    });
+                }
+                const json = await response.json();
+                const parsed = jevResponseSchema.safeParse(json);
+                if (!parsed.success) {
+                    throw new RuntimeError("PROVIDER_FAILURE", "Jev response did not match the expected shape", {
+                        detail: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
+                        evidence: { received: Object.keys(json ?? {}).slice(0, 8) },
+                    });
+                }
+                return { response: parsed.data, latencyMs: Date.now() - started };
+            }
+            catch (err) {
+                if (err instanceof RuntimeError && err.code === "PROVIDER_FAILURE" && !err.retryable)
+                    throw err;
+                lastError = err;
+                if (attempt < this.#maxRetries)
+                    await new Promise((r) => setTimeout(r, 150 * (attempt + 1)));
+            }
+        }
+        throw new RuntimeError("PROVIDER_FAILURE", `Jev request failed: ${String(lastError)}`, {
+            cause: lastError,
+        });
+    }
+    async #fetch(url, init, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        timer.unref?.();
+        try {
+            return await fetch(url, {
+                ...init,
+                headers: { ...(init.headers ?? {}), authorization: `Bearer ${this.#apiKey}` },
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new RuntimeError("PROVIDER_FAILURE", `Jev request timed out after ${timeoutMs}ms`, {
+                    cause: err,
+                });
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./client.ts";
+export * from "./questions.ts";
+export * from "./state.ts";
+export * from "./provider.ts";
+export * from "./llm-providers.ts";
+export * from "./testing/index.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,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./client.js";
+export * from "./questions.js";
+export * from "./state.js";
+export * from "./provider.js";
+export * from "./llm-providers.js";
+export * from "./testing/index.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,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/llm-providers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OpenAI-compatible provider adapters (PRD §17.2, §32, §44).
+ *
+ * Used for the text helper (what text to type) and the planner role (what to
+ * do next / which action to fall back to). Both are optional: the runtime works
+ * without them, escalating to the person instead, and every response is parsed
+ * against a schema before it is trusted.
+ */
+import { type FallbackDecisionInput, type FallbackDecisionOutput, type PlannerInput, type PlannerOutput, type PlannerProvider, type TextGenerationInput, type TextGenerationOutput, type TextProvider, type Usage } from "@mlola/browser-protocol";
+export interface OpenAICompatibleOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    model?: string;
+    timeoutMs?: number;
+    temperature?: number;
+}
+interface ChatOptions extends OpenAICompatibleOptions {
+    system: string;
+    user: string;
+    maxTokens?: number;
+}
+export declare class OpenAICompatibleClient {
+    #private;
+    readonly model: string;
+    constructor(options?: OpenAICompatibleOptions);
+    chatJson(options: ChatOptions, envFallbacks?: {
+        baseUrl?: string;
+        apiKey?: string;
+        model?: string;
+    }): Promise<{
+        json: unknown;
+        usage?: Usage;
+        latencyMs: number;
+    }>;
+}
+export interface OpenAITextProviderOptions extends OpenAICompatibleOptions {
+    name?: string;
+}
+export declare class OpenAITextProvider implements TextProvider {
+    #private;
+    readonly name: string;
+    constructor(options?: OpenAITextProviderOptions);
+    generate(input: TextGenerationInput): Promise<TextGenerationOutput>;
+}
+export interface OpenAIPlannerProviderOptions extends OpenAICompatibleOptions {
+    name?: string;
+}
+export declare class OpenAIPlannerProvider implements PlannerProvider {
+    #private;
+    readonly name: string;
+    constructor(options?: OpenAIPlannerProviderOptions);
+    plan(input: PlannerInput): Promise<PlannerOutput>;
+    chooseAction(input: FallbackDecisionInput): Promise<FallbackDecisionOutput>;
+}
+export {};
+//# sourceMappingURL=llm-providers.d.ts.map

package/dist/llm-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-providers.d.ts","sourceRoot":"","sources":["../src/llm-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAKL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,KAAK,EACX,MAAM,yBAAyB,CAAC;AAGjC,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,WAAY,SAAQ,uBAAuB;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,sBAAsB;;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAMX,OAAO,GAAE,uBAA4B;IAkB3C,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC;QACtH,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,CAAC,EAAE,KAAK,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CAmEH;AAID,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAWD,qBAAa,kBAAmB,YAAW,YAAY;;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAMV,OAAO,GAAE,yBAA8B;IAgB7C,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAkC1E;AAID,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAmBD,qBAAa,qBAAsB,YAAW,eAAe;;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAMV,OAAO,GAAE,4BAAiC;IAiBhD,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IA8CjD,YAAY,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;CAiDlF"}

package/dist/llm-providers.js

@@ -0,0 +1,279 @@
+/**
+ * OpenAI-compatible provider adapters (PRD §17.2, §32, §44).
+ *
+ * Used for the text helper (what text to type) and the planner role (what to
+ * do next / which action to fall back to). Both are optional: the runtime works
+ * without them, escalating to the person instead, and every response is parsed
+ * against a schema before it is trusted.
+ */
+import { RuntimeError, plannerModelResponseSchema, textModelResponseSchema, } from "@mlola/browser-protocol";
+import { renderElement } from "./state.js";
+export class OpenAICompatibleClient {
+    model;
+    #baseUrl;
+    #apiKey;
+    #timeoutMs;
+    #temperature;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ??
+            process.env[options.apiKeyEnv ?? "MLOLA_PLANNER_API_KEY"] ??
+            process.env["OPENAI_API_KEY"];
+        if (!apiKey) {
+            throw new RuntimeError("PROVIDER_FAILURE", "missing API key for the OpenAI-compatible provider", {
+                retryable: false,
+            });
+        }
+        this.#apiKey = apiKey;
+        const base = options.baseUrl ?? process.env["MLOLA_PLANNER_BASE_URL"] ?? "https://api.openai.com/v1";
+        this.#baseUrl = base.replace(/\/+$/, "");
+        this.model = options.model ?? process.env["MLOLA_PLANNER_MODEL"] ?? "gpt-4o-mini";
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+        this.#temperature = options.temperature ?? 0;
+    }
+    async chatJson(options, envFallbacks = {}) {
+        const started = Date.now();
+        const base = (options.baseUrl ?? envFallbacks.baseUrl ?? this.#baseUrl).replace(/\/+$/, "");
+        const apiKey = options.apiKey ?? envFallbacks.apiKey ?? this.#apiKey;
+        const model = options.model ?? envFallbacks.model ?? this.model;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? this.#timeoutMs);
+        timer.unref?.();
+        try {
+            const response = await fetch(`${base}/chat/completions`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+                body: JSON.stringify({
+                    model,
+                    temperature: options.temperature ?? this.#temperature,
+                    max_tokens: options.maxTokens ?? 700,
+                    response_format: { type: "json_object" },
+                    messages: [
+                        { role: "system", content: options.system },
+                        { role: "user", content: options.user },
+                    ],
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new RuntimeError("PROVIDER_FAILURE", `model request failed with ${response.status}`, {
+                    detail: text.slice(0, 300),
+                    retryable: response.status >= 500 || response.status === 429,
+                });
+            }
+            const payload = (await response.json());
+            const content = payload.choices?.[0]?.message?.content;
+            if (!content) {
+                throw new RuntimeError("PROVIDER_FAILURE", "model returned an empty response");
+            }
+            let json;
+            try {
+                json = JSON.parse(content);
+            }
+            catch {
+                throw new RuntimeError("PROVIDER_FAILURE", "model response was not valid JSON", {
+                    detail: content.slice(0, 300),
+                });
+            }
+            const usage = {
+                provider: "openai-compatible",
+                model,
+                calls: 1,
+                ...(payload.usage?.prompt_tokens !== undefined ? { inputTokens: payload.usage.prompt_tokens } : {}),
+                ...(payload.usage?.completion_tokens !== undefined ? { outputTokens: payload.usage.completion_tokens } : {}),
+            };
+            return { json, usage, latencyMs: Date.now() - started };
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new RuntimeError("PROVIDER_FAILURE", "model request timed out", { cause: err });
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+const TEXT_SYSTEM = [
+    "You produce the exact literal text that a browser agent should type into a web form field.",
+    "Reply with JSON only: {\"text\": \"...\"}.",
+    "Rules: output a single plain string; no explanations, no formatting, no URLs unless the task requires one;",
+    "never output credentials, API keys, passwords or one-time codes;",
+    "if the value cannot be determined from the task, output an empty string.",
+    "Reuse the task's own wording when it already contains the value.",
+].join(" ");
+export class OpenAITextProvider {
+    name;
+    #client;
+    #baseUrl;
+    #apiKey;
+    #model;
+    constructor(options = {}) {
+        this.name = options.name ?? "openai-compatible:text";
+        const apiKey = options.apiKey ?? process.env["MLOLA_TEXT_API_KEY"] ?? process.env["OPENAI_API_KEY"];
+        const baseUrl = options.baseUrl ?? process.env["MLOLA_TEXT_BASE_URL"] ?? process.env["MLOLA_PLANNER_BASE_URL"];
+        const model = options.model ?? process.env["MLOLA_TEXT_MODEL"] ?? "gpt-4o-mini";
+        if (!apiKey) {
+            throw new RuntimeError("PROVIDER_FAILURE", "missing text provider API key (MLOLA_TEXT_API_KEY)", {
+                retryable: false,
+            });
+        }
+        this.#apiKey = apiKey;
+        this.#baseUrl = baseUrl;
+        this.#model = model;
+        this.#client = new OpenAICompatibleClient({ ...options, apiKey, ...(baseUrl ? { baseUrl } : {}), model });
+    }
+    async generate(input) {
+        const user = [
+            `Task: ${input.goal}`,
+            input.subgoal ? `Current step: ${input.subgoal}` : undefined,
+            `Field: ${input.targetRole} ${JSON.stringify(input.targetLabel)}`,
+            input.literals.length > 0 ? `Values mentioned in the task: ${JSON.stringify(input.literals)}` : undefined,
+            input.context ? `Page context: ${input.context}` : undefined,
+            `Maximum length: ${input.maxLength ?? 200} characters.`,
+        ]
+            .filter((line) => line !== undefined)
+            .join("\n");
+        const { json, usage, latencyMs } = await this.#client.chatJson({ system: TEXT_SYSTEM, user, maxTokens: 120 }, {
+            ...(this.#baseUrl ? { baseUrl: this.#baseUrl } : {}),
+            ...(this.#apiKey ? { apiKey: this.#apiKey } : {}),
+            ...(this.#model ? { model: this.#model } : {}),
+        });
+        const parsed = textModelResponseSchema.safeParse(json);
+        if (!parsed.success) {
+            throw new RuntimeError("DECISION_INVALID", "text provider returned an invalid payload", {
+                detail: parsed.error.issues.map((i) => i.message).join("; "),
+            });
+        }
+        return {
+            text: parsed.data.text,
+            source: "model",
+            provider: this.name,
+            latencyMs,
+            ...(usage ? { usage } : {}),
+        };
+    }
+}
+const PLANNER_SYSTEM = [
+    "You are the planner for a browser automation runtime.",
+    "Plan the shortest deterministic sequence of subgoals that completes the user's task in the browser.",
+    "Reply with JSON only: {\"subgoals\": [{\"description\": \"...\", \"hints\": [\"...\"]}], \"notes\": \"...\"}.",
+    "Each subgoal must be a single verifiable browser step (open a page, sign in, download a file, upload a file, stop before submitting).",
+    "Never include destructive or financial actions unless the task explicitly asks for them.",
+    "Keep the plan under 8 subgoals.",
+].join(" ");
+const CHOOSE_SYSTEM = [
+    "You choose one action for a browser agent from a fixed, runtime-provided action space.",
+    "Reply with JSON only: {\"operation\": \"<OP>\", \"target\": \"<key>\"}.",
+    "The operation must be one of the offered operations; the target must be one of the offered keys for the matching head.",
+    "Never invent selectors, coordinates, URLs, JavaScript or element ids that were not offered.",
+    "Prefer the action that most directly advances the stated goal; avoid repeating actions that failed before.",
+].join(" ");
+export class OpenAIPlannerProvider {
+    name;
+    #client;
+    #baseUrl;
+    #apiKey;
+    #model;
+    constructor(options = {}) {
+        this.name = options.name ?? "openai-compatible:planner";
+        const apiKey = options.apiKey ?? process.env["MLOLA_PLANNER_API_KEY"] ?? process.env["OPENAI_API_KEY"];
+        if (!apiKey) {
+            throw new RuntimeError("PROVIDER_FAILURE", "missing planner API key (MLOLA_PLANNER_API_KEY)", {
+                retryable: false,
+            });
+        }
+        const baseUrl = options.baseUrl ?? process.env["MLOLA_PLANNER_BASE_URL"];
+        const model = options.model ?? process.env["MLOLA_PLANNER_MODEL"] ?? "gpt-4o-mini";
+        this.#apiKey = apiKey;
+        this.#baseUrl = baseUrl;
+        this.#model = model;
+        this.#client = new OpenAICompatibleClient({ ...options, apiKey, ...(baseUrl ? { baseUrl } : {}), model });
+    }
+    async plan(input) {
+        const user = [
+            `Task: ${input.goal}`,
+            `Reason for planning: ${input.reason}`,
+            input.memory.facts.length > 0
+                ? `Known facts:\n${input.memory.facts.map((f) => `- ${f.text}`).join("\n")}`
+                : undefined,
+            input.history.length > 0
+                ? `Steps already taken:\n${input.history.slice(-10).map((h) => `${h.step}. ${h.action} -> ${h.outcome}`).join("\n")}`
+                : undefined,
+            input.artifacts.length > 0
+                ? `Files already obtained:\n${input.artifacts.map((a) => `- ${a.id} ${a.name}`).join("\n")}`
+                : undefined,
+            `Current page state:\n${input.snapshotSummary}`,
+        ]
+            .filter((line) => line !== undefined)
+            .join("\n\n");
+        const { json, usage, latencyMs } = await this.#client.chatJson({ system: PLANNER_SYSTEM, user, maxTokens: 700 }, {
+            ...(this.#baseUrl ? { baseUrl: this.#baseUrl } : {}),
+            ...(this.#apiKey ? { apiKey: this.#apiKey } : {}),
+            ...(this.#model ? { model: this.#model } : {}),
+        });
+        const parsed = plannerModelResponseSchema.safeParse(json);
+        if (!parsed.success) {
+            throw new RuntimeError("PROVIDER_FAILURE", "planner returned an invalid plan", {
+                detail: parsed.error.issues.map((i) => i.message).join("; "),
+            });
+        }
+        return {
+            subgoals: parsed.data.subgoals.map((s, i) => ({
+                id: `g${i + 1}`,
+                description: s.description,
+                ...(s.hints ? { hints: s.hints } : {}),
+            })),
+            ...(parsed.data.notes !== undefined ? { notes: parsed.data.notes } : {}),
+            provider: this.name,
+            model: this.#model,
+            latencyMs,
+            usage,
+        };
+    }
+    async chooseAction(input) {
+        const space = input.actionSpace;
+        const operations = space.operations.map((op) => {
+            const head = space.headForOperation[op];
+            const targets = head ? (space.heads[head] ?? []) : [];
+            const targetList = targets.length > 0 ? ` targets: ${targets.map((t) => `${t.key} = ${t.label}`).join(" | ")}` : "";
+            return `- ${op}${targetList}`;
+        });
+        const user = [
+            `Task: ${input.goal}`,
+            input.subgoal ? `Current step: ${input.subgoal}` : undefined,
+            input.failure ? `Previous attempt failed: ${input.failure}` : undefined,
+            `Page: ${input.snapshot.url} — ${input.snapshot.title}`,
+            "",
+            "Visible elements:",
+            input.snapshot.nodes.slice(0, 60).map((n) => `~${renderElement(n)}`).join("\n"),
+            "",
+            "Offered operations and targets:",
+            operations.join("\n"),
+            "",
+            `Crash context: ${input.reason}`,
+        ]
+            .filter((line) => line !== undefined)
+            .join("\n");
+        const { json, usage, latencyMs } = await this.#client.chatJson({ system: CHOOSE_SYSTEM, user, maxTokens: 120, temperature: 0 }, {
+            ...(this.#baseUrl ? { baseUrl: this.#baseUrl } : {}),
+            ...(this.#apiKey ? { apiKey: this.#apiKey } : {}),
+            ...(this.#model ? { model: this.#model } : {}),
+        });
+        const candidate = json;
+        if (typeof candidate.operation !== "string") {
+            throw new RuntimeError("PROVIDER_FAILURE", "fallback provider did not return an operation");
+        }
+        return {
+            operation: candidate.operation,
+            ...(typeof candidate.target === "string" ? { target: candidate.target } : {}),
+            latencyMs,
+            provider: this.name,
+            ...(this.#model ? { model: this.#model } : {}),
+            ...(usage ? { usage } : {}),
+            raw: json,
+        };
+    }
+}
+//# sourceMappingURL=llm-providers.js.map

package/dist/llm-providers.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Jev fast-path decision provider (PRD §15, §44).
+ *
+ * One request per normal decision cycle: operation head + speculative target
+ * heads built from the runtime's own action space.
+ */
+import { type DecisionInput, type DecisionOutput, type DecisionProvider } from "@mlola/browser-protocol";
+import { JevClient, type JevClientOptions } from "./client.ts";
+export interface JevDecisionProviderOptions extends JevClientOptions {
+    /** Provider name recorded in traces (default "typesafe"). */
+    name?: string;
+    /** Cost rates for usage accounting. */
+    cost?: {
+        inputPerMTok?: number;
+        outputPerMTok?: number;
+    };
+}
+export declare class JevDecisionProvider implements DecisionProvider {
+    readonly name: string;
+    readonly client: JevClient;
+    constructor(options?: JevDecisionProviderOptions);
+    get model(): string;
+    warmup(): Promise<void>;
+    decide(input: DecisionInput): Promise<DecisionOutput>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAGtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/D,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAED,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;gBAEf,OAAO,GAAE,0BAA+B;IAKpD,IAAI,KAAK,IAAI,MAAM,CAElB;IAEK,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;CA6C5D"}