@dna113p/machines 0.2.0 → 0.3.1

package/dist/src/index.d.ts

@@ -6,29 +6,50 @@ export interface Event {
 export type HumanOptions = {
     readonly choices: readonly string[];
     readonly suggestions?: never;
+    readonly discussion?: boolean;
 } | {
     readonly choices?: never;
     readonly suggestions?: readonly string[];
+    readonly discussion?: boolean;
 };
 export type HumanPrompt = string | (() => string);
 export interface HumanRequest {
+    /** A separate question channel; never an approval or a restricted choice. */
+    readonly discussion?: boolean;
     readonly prompt: string;
     readonly choices?: readonly string[];
     readonly suggestions?: readonly string[];
 }
-export type HumanRunner = (request: HumanRequest) => string | Promise<string>;
+export type HumanResponse = string | {
+    readonly type: "question";
+    readonly text: string;
+};
+export type HumanRunner = (request: HumanRequest) => HumanResponse | Promise<HumanResponse>;
 export interface AgentOptions {
     readonly cwd?: string;
     readonly using?: string;
+    /**
+     * The transition this state takes when its Agent is at a usage limit. The
+     * event is delivered by the runtime and never offered to the Agent. A state
+     * that names it decides what a limit means: no fallback preset, no waiting.
+     */
+    readonly onLimit?: string;
 }
 export type AgentPrompt = string | (() => string);
 export interface AgentRequest {
     readonly prompt: string;
     readonly outcomes: readonly string[];
     readonly cwd?: string;
+    /**
+     * Set for a state that handles its own usage limit: a limit is to be thrown
+     * as it is found, not swapped away from or waited out. Runners that do
+     * neither ignore it.
+     */
+    readonly limits?: "report";
 }
 interface AgentInvocation extends AgentRequest {
     readonly using: string;
+    readonly onLimit?: string;
 }
 export type AgentUpdate = {
     readonly type: "identity";
@@ -43,8 +64,21 @@ export type AgentUpdate = {
     readonly id: string;
     readonly title?: string;
     readonly status?: "pending" | "in_progress" | "completed" | "failed";
+} | {
+    /** A usage limit changed which preset runs this Agent, or made it wait. `text` is a ready one-line summary. */
+    readonly type: "limit";
+    readonly status: "swapped" | "waiting" | "resumed";
+    /** The limited preset. */
+    readonly agent: string;
+    /** The preset that continues the request. */
+    readonly to?: string;
+    /** ISO time the wait is expected to end. */
+    readonly until?: string;
+    readonly text: string;
 };
 export type AgentReporter = (update: AgentUpdate) => void;
+export type { JsonValue } from "./json.ts";
+export { AgentLimitError, agentLimitOf, type AgentLimit } from "./agent-limit.ts";
 export type AgentRunner = (request: AgentRequest, report?: AgentReporter) => Event | Promise<Event>;
 export interface RunOptions {
     readonly agents?: Readonly<Record<string, AgentRunner>>;
@@ -160,6 +194,7 @@ export declare function human<const TTransitions extends Readonly<Record<string,
         readonly src: "human";
         readonly input: () => {
             prompt: string;
+            discussion?: boolean | undefined;
             choices?: readonly string[] | undefined;
             suggestions?: readonly string[] | undefined;
         };
@@ -176,6 +211,7 @@ export declare function agent<const TTransitions extends Readonly<Record<string,
     readonly meta: {
         readonly "machines.agent": {
             readonly using: string;
+            readonly onLimit?: string | undefined;
         };
     };
     readonly invoke: {
@@ -185,6 +221,8 @@ export declare function agent<const TTransitions extends Readonly<Record<string,
             prompt: string;
             outcomes: string[];
             cwd?: string | undefined;
+            limits?: "report" | undefined;
+            onLimit?: string | undefined;
         };
         readonly onDone: {
             readonly actions: readonly [(args: unknown) => void, import("xstate").ActionFunction<any, any, Event, undefined, never, never, never, never, never>];
@@ -207,4 +245,3 @@ export interface MachinePrimitives {
 }
 export declare function requiredAgentNames(definition: AnyStateMachine): readonly string[];
 export declare function run<TMachine extends AnyStateMachine>(definition: TMachine, options?: RunOptions): Promise<SnapshotFrom<TMachine>>;
-export {};

package/dist/src/index.js

@@ -1,5 +1,7 @@
+import { agentLimitOf } from "./agent-limit.js";
 import { terminalHuman } from "./terminal-human.js";
 import { createActor, fromPromise, raise, setup, } from "xstate";
+export { AgentLimitError, agentLimitOf } from "./agent-limit.js";
 const machines = setup({
     actions: {
         humanInputFinished: () => { },
@@ -27,6 +29,9 @@ export function human(prompt, on, options = {}) {
     if (options.choices !== undefined && options.choices.length === 0) {
         throw new Error("Human choices must include at least one value");
     }
+    if (options.discussion && !Object.hasOwn(on, "question")) {
+        throw new Error("Discussion-enabled Human states must handle a question event");
+    }
     return {
         entry: "humanInputStarted",
         exit: "humanInputFinished",
@@ -34,6 +39,7 @@ export function human(prompt, on, options = {}) {
             src: "human",
             input: () => ({
                 prompt: typeof prompt === "function" ? prompt() : prompt,
+                ...(options.discussion ? { discussion: true } : {}),
                 ...(options.choices === undefined ? {} : { choices: options.choices }),
                 ...(options.suggestions === undefined
                     ? {}
@@ -49,17 +55,32 @@ export function agent(prompt, on, options = {}) {
     if (typeof using !== "string" || using.trim() === "" || using !== using.trim()) {
         throw new Error("Agent runner name must be a non-empty trimmed string");
     }
+    const onLimit = options.onLimit;
+    if (onLimit !== undefined) {
+        if (typeof onLimit !== "string" || onLimit.trim() === "" || onLimit !== onLimit.trim()) {
+            throw new Error("Agent onLimit must be a non-empty trimmed event name");
+        }
+        if (!Object.hasOwn(on, onLimit)) {
+            throw new Error(`Agent onLimit event "${onLimit}" must be one of the state's transitions`);
+        }
+    }
+    // The limit event comes from the runtime, so the Agent is never offered it.
+    const outcomes = Object.keys(on).filter((outcome) => outcome !== onLimit);
+    if (onLimit !== undefined && outcomes.length === 0) {
+        throw new Error(`Agent onLimit event "${onLimit}" cannot be the state's only transition: the Agent needs an outcome of its own`);
+    }
     return {
         meta: {
-            [agentMetaKey]: { using },
+            [agentMetaKey]: { using, ...(onLimit === undefined ? {} : { onLimit }) },
         },
         invoke: {
             src: "agent",
             input: () => ({
                 using,
                 prompt: typeof prompt === "function" ? prompt() : prompt,
-                outcomes: Object.keys(on),
+                outcomes,
                 ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+                ...(onLimit === undefined ? {} : { limits: "report", onLimit }),
             }),
             ...actorLifecycle("Agent", on),
         },
@@ -90,7 +111,11 @@ async function submittedHumanEvent(request, runner) {
     // Let onHumanInput(true) release terminal hotkeys before the runner takes stdin.
     const answer = await Promise.resolve().then(() => runner(request));
     if (typeof answer !== "string") {
-        throw new Error("Human runner must return a string");
+        if (answer && request.discussion === true && answer.type === "question" &&
+            typeof answer.text === "string" && answer.text.trim() !== "" && answer.text.length <= 8000) {
+            return { type: "question", value: answer.text };
+        }
+        throw new Error("Human runner must return a string or an explicitly supported discussion question");
     }
     if (request.choices !== undefined && !request.choices.includes(answer)) {
         throw new Error(`Expected one of: ${request.choices.join(", ")}`);
@@ -121,12 +146,28 @@ export function run(definition, options = {}) {
                     ? {}
                     : {
                         agent: fromPromise(async ({ input }) => {
-                            const { using, ...request } = input;
+                            const { using, onLimit, ...request } = input;
                             const runner = agentRunners[using];
                             if (runner === undefined) {
                                 throw new Error(`Agent runner "${using}" was not supplied`);
                             }
-                            return runner(request, options.onAgentUpdate);
+                            if (onLimit === undefined)
+                                return runner(request, options.onAgentUpdate);
+                            let event;
+                            try {
+                                event = await runner(request, options.onAgentUpdate);
+                            }
+                            catch (cause) {
+                                const limit = agentLimitOf(cause);
+                                if (limit === undefined)
+                                    throw cause;
+                                return limitEvent(onLimit, using, limit, cause);
+                            }
+                            // Only the runtime may say that the Agent is at a limit.
+                            if (event !== null && typeof event === "object" && event.type === onLimit) {
+                                throw new Error(`the runner returned "${onLimit}", which this state reserves for its usage-limit event`);
+                            }
+                            return event;
                         }),
                     }),
             },
@@ -150,6 +191,22 @@ export function run(definition, options = {}) {
         actor.start();
     });
 }
+/** The event a state that names `onLimit` receives. It is plain JSON, so a Machine can keep or publish it. */
+function limitEvent(type, role, limit, cause) {
+    const resets = typeof limit.resetsAt === "number" ? new Date(limit.resetsAt) : undefined;
+    return {
+        type,
+        limit: {
+            role,
+            ...(typeof limit.agent === "string" ? { agent: limit.agent } : {}),
+            harness: limit.harness,
+            ...(typeof limit.kind === "string" ? { kind: limit.kind } : {}),
+            // A reset outside the range of a date has no ISO form.
+            ...(resets === undefined || Number.isNaN(resets.getTime()) ? {} : { resetsAt: resets.toISOString() }),
+        },
+        message: cause instanceof Error ? cause.message : String(cause),
+    };
+}
 function collectAgentNames(value, names) {
     if (value === null || typeof value !== "object")
         return;

package/dist/src/jev.d.ts

@@ -0,0 +1,15 @@
+import { type DecisionAgentOptions, type DecisionProvider } from "./decision.ts";
+export interface JevProviderOptions {
+    /** Read lazily from TYPESAFE_API_KEY when omitted. Never used during discovery. */
+    readonly apiKey?: string;
+    /** Overrides JEV_MODEL, then the pinned default jev-1.13.0. */
+    readonly model?: string;
+    readonly timeoutMs?: number;
+    /** Transport injection for tests or an explicitly configured HTTP client. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+export type JevAgentOptions = JevProviderOptions & DecisionAgentOptions;
+/** TypeSafe Choice transport. No tool access, retries, or workflow policy. */
+export declare function jevProvider(options?: JevProviderOptions): DecisionProvider;
+/** Convenience preset; workflows can swap providers through decisionAgent instead. */
+export declare function jevAgent(options?: JevAgentOptions): (request: import("./index.ts").AgentRequest, report?: import("./index.ts").AgentReporter) => Promise<import("./decision.ts").DecisionEvent>;

package/dist/src/jev.js

@@ -0,0 +1,90 @@
+import * as v from "valibot";
+import { decisionAgent } from "./decision.js";
+const probability = v.pipe(v.number(), v.minValue(0), v.maxValue(1));
+const responseSchema = v.object({
+    model: v.pipe(v.string(), v.check(value => value.trim().length > 0)),
+    answers: v.object({
+        decision: v.object({
+            type: v.literal("choice"),
+            choice: v.string(),
+            probabilities: v.record(v.string(), probability),
+            confidence: probability,
+        }),
+    }),
+});
+/** TypeSafe Choice transport. No tool access, retries, or workflow policy. */
+export function jevProvider(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new Error("Jev timeoutMs must be a positive 32-bit integer");
+    }
+    return {
+        name: "jev",
+        async decide(request) {
+            const apiKey = options.apiKey ?? process.env.TYPESAFE_API_KEY;
+            if (typeof apiKey !== "string" || !apiKey.trim()) {
+                throw new Error("Jev requires TYPESAFE_API_KEY or an explicit apiKey");
+            }
+            const model = options.model ?? process.env.JEV_MODEL ?? "jev-1.13.0";
+            if (typeof model !== "string" || !model.trim()) {
+                throw new Error("Jev model must be non-empty");
+            }
+            const count = Object.keys(request.choices).length;
+            if (count === 0 || count > 255) {
+                throw new Error("Jev Choice requires between 1 and 255 outcomes");
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const timeoutError = () => new Error(`Jev request timed out after ${timeoutMs}ms`);
+            try {
+                let response;
+                try {
+                    response = await (options.fetch ?? globalThis.fetch)("https://api.typesafe.ai/v1/systemone", {
+                        method: "POST",
+                        redirect: "error",
+                        signal: controller.signal,
+                        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            model,
+                            state: request.input,
+                            questions: {
+                                decision: { type: "choice", instructions: request.question, criteria: request.choices },
+                            },
+                        }),
+                    });
+                }
+                catch {
+                    // Do not forward transport errors that might contain credentials or input.
+                    throw controller.signal.aborted ? timeoutError() : new Error("Jev network request failed");
+                }
+                if (!response.ok) {
+                    await response.body?.cancel().catch(() => { });
+                    throw new Error(`Jev request failed (HTTP ${response.status}); no automatic retry`);
+                }
+                let body;
+                try {
+                    body = await response.json();
+                }
+                catch {
+                    throw controller.signal.aborted ? timeoutError() : new Error("Jev returned invalid JSON");
+                }
+                const parsed = v.safeParse(responseSchema, body);
+                if (!parsed.success)
+                    throw new Error("Jev returned an invalid Choice response");
+                const { choice, probabilities, confidence } = parsed.output.answers.decision;
+                if (!Object.hasOwn(probabilities, choice)
+                    || Object.values(probabilities).some(value => value > probabilities[choice])) {
+                    throw new Error("Jev choice must have the highest probability");
+                }
+                return { choice, probabilities, confidence, model: parsed.output.model };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+/** Convenience preset; workflows can swap providers through decisionAgent instead. */
+export function jevAgent(options = {}) {
+    return decisionAgent(jevProvider(options), options);
+}

package/dist/src/json.d.ts

@@ -0,0 +1,6 @@
+/** Values that can cross the hosted-run process boundary without conversion. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function isJsonValue(value: unknown): value is JsonValue;
+export declare function assertJsonValue(value: unknown, label?: string): asserts value is JsonValue;

package/dist/src/json.js

@@ -0,0 +1,28 @@
+export function isJsonValue(value) {
+    const ancestors = new Set();
+    function visit(item) {
+        if (item === null || typeof item === "string" || typeof item === "boolean")
+            return true;
+        if (typeof item === "number")
+            return Number.isFinite(item);
+        if (typeof item !== "object" || ancestors.has(item))
+            return false;
+        if (!Array.isArray(item) &&
+            Object.getPrototypeOf(item) !== Object.prototype &&
+            Object.getPrototypeOf(item) !== null)
+            return false;
+        if (Object.getOwnPropertySymbols(item).length > 0)
+            return false;
+        ancestors.add(item);
+        const valid = Array.isArray(item)
+            ? [...item].every(visit)
+            : Object.values(item).every(visit);
+        ancestors.delete(item);
+        return valid;
+    }
+    return visit(value);
+}
+export function assertJsonValue(value, label = "value") {
+    if (!isJsonValue(value))
+        throw new Error(`${label} must be a JSON-serializable value`);
+}

package/dist/src/launcher.d.ts

@@ -1,11 +1,21 @@
 import type { AnyStateMachine, SnapshotFrom } from "xstate";
+import { type JsonValue } from "./json.ts";
 import { type LauncherLocation, type MachineSummary, type AgentPresetSummary } from "./catalog.ts";
 export type { LauncherLocation, MachineSummary, AgentPresetSummary } from "./catalog.ts";
 import { type RunOptions } from "./index.ts";
 export interface PrepareMachineRunOptions extends LauncherLocation {
     readonly machine: string;
-    readonly input?: string;
+    readonly input?: JsonValue;
     readonly agents?: Readonly<Record<string, string>>;
+    /**
+     * How this process waits at an Agent usage limit. `waitMinutes` overrides
+     * MACHINES_AGENT_LIMIT_WAIT_MINUTES; a hosted run reads the variable instead.
+     */
+    readonly agentLimits?: {
+        readonly waitMinutes?: number;
+        readonly now?: () => number;
+        readonly sleep?: (milliseconds: number) => Promise<void>;
+    };
 }
 export interface PreparedMachineRun {
     readonly name: string;

package/dist/src/launcher.js

@@ -1,4 +1,7 @@
 import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { assertJsonValue } from "./json.js";
+import { fallbackPresets } from "./agent-bindings.js";
+import { createLimitMemory, defaultProbeMs, limitAwareRunner } from "./agent-limits.js";
 import { configuredAgentPresets } from "./catalog.js";
 import { queryCatalog } from "./discovery-worker.js";
 import { loadMachineModule, readAgentRoles, requireMachineDescription } from "./machine-module.js";
@@ -11,6 +14,8 @@ export async function listAgentPresets(location = {}) {
     return queryCatalog("agents", location);
 }
 export async function prepareMachineRun(options) {
+    if (options.input !== undefined)
+        assertJsonValue(options.input, "Machine input");
     const cwd = options.cwd ?? process.cwd();
     const home = options.home ?? machinesUserHome();
     const path = await resolveMachine(options.machine, cwd, home);
@@ -20,11 +25,14 @@ export async function prepareMachineRun(options) {
     if (typeof loaded.default !== "function") {
         throw new Error(`Machine "${path}" must default-export a factory`);
     }
-    const definition = await loaded.default({ agent, final, human, machine, operation }, options.input ?? "");
+    const definition = await loaded.default({ agent, final, human, machine, operation }, options.input === undefined ? "" : options.input);
     const configured = await configuredAgentPresets(cwd, home);
     const usedAgentRoles = requiredAgentNames(definition);
-    const agents = applyAgentOverrides(path, configured.agents, configured.presets, new Set([...usedAgentRoles, ...Object.keys(agentRoles)]), options.agents ?? {});
+    const requiredRoles = new Set([...usedAgentRoles, ...Object.keys(agentRoles)]);
+    const overrides = options.agents ?? {};
+    const agents = applyAgentOverrides(path, configured.agents, configured.presets, requiredRoles, overrides);
     preflightAgentRoles(path, usedAgentRoles, agentRoles, agents);
+    const limitAware = limitAwareAgents(requiredRoles, overrides, configured, limitPolicy(options.agentLimits));
     let started = false;
     return {
         name: machineName(path),
@@ -35,7 +43,7 @@ export async function prepareMachineRun(options) {
             if (started)
                 throw new Error(`Prepared Machine "${path}" has already started`);
             started = true;
-            return run(definition, { ...runOptions, agents });
+            return run(definition, { ...runOptions, agents: { ...agents, ...limitAware } });
         },
     };
 }
@@ -71,6 +79,67 @@ function applyAgentOverrides(machinePath, agents, presets, requiredRoles, overri
     }
     return resolved;
 }
+/**
+ * Wraps each role the Machine uses or declares so that a usage limit swaps to
+ * the bound preset's fallbacks or waits for a reset. The roles share one memory
+ * of limited presets, kept only for this prepared run.
+ */
+function limitAwareAgents(roles, overrides, configured, policy) {
+    const swapping = fallbackEnabled();
+    const memory = createLimitMemory();
+    const wrapped = {};
+    for (const role of roles) {
+        const bound = Object.hasOwn(overrides, role) ? overrides[role] ?? role : role;
+        // With swapping off a role still waits for its own preset's reset, and names no other preset.
+        const fallback = swapping
+            ? fallbackPresets(bound, presetNamed(configured.presets, bound) ?? {}, configured.fallback) ?? []
+            : [];
+        const candidates = [bound, ...fallback].map((name) => {
+            const preset = presetNamed(configured.presets, name);
+            if (preset === undefined) {
+                const available = Object.keys(configured.presets).sort().join(", ");
+                throw new Error(`Agent preset "${bound}" for role "${role}" falls back to "${name}", which is not a configured preset. Available presets: ${available}`);
+            }
+            return { name, runner: preset.runner, ...(preset.harness === undefined ? {} : { harness: preset.harness }) };
+        });
+        wrapped[role] = limitAwareRunner(role, candidates, memory, policy);
+    }
+    return wrapped;
+}
+function presetNamed(presets, name) {
+    return Object.hasOwn(presets, name) ? presets[name] : undefined;
+}
+function fallbackEnabled() {
+    const configured = process.env.MACHINES_AGENT_FALLBACK;
+    if (configured === undefined || configured === "" || configured === "on")
+        return true;
+    if (configured === "off")
+        return false;
+    throw new Error(`MACHINES_AGENT_FALLBACK must be "off" or "on", not "${configured}"`);
+}
+const defaultLimitWaitMinutes = 360;
+function limitPolicy(options = {}) {
+    const configured = process.env.MACHINES_AGENT_LIMIT_WAIT_MINUTES;
+    let minutes = defaultLimitWaitMinutes;
+    if (options.waitMinutes !== undefined) {
+        if (!Number.isFinite(options.waitMinutes) || options.waitMinutes < 0) {
+            throw new Error("agentLimits.waitMinutes must be a non-negative number of minutes");
+        }
+        minutes = options.waitMinutes;
+    }
+    else if (configured !== undefined && configured !== "") {
+        if (!/^\d+(?:\.\d+)?$/u.test(configured)) {
+            throw new Error(`MACHINES_AGENT_LIMIT_WAIT_MINUTES must be a non-negative number of minutes, not "${configured}"`);
+        }
+        minutes = Number(configured);
+    }
+    return {
+        maxWaitMs: minutes * 60_000,
+        probeMs: defaultProbeMs,
+        ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+    };
+}
 function preflightAgentRoles(machinePath, usedNames, declaredRoles, agents) {
     const undeclared = usedNames.filter((name) => name !== "default" && !Object.hasOwn(declaredRoles, name));
     if (undeclared.length > 0) {

package/dist/src/laya.d.ts

@@ -0,0 +1,15 @@
+import { type DecisionAgentOptions, type DecisionProvider } from "./decision.ts";
+import { type SystemOneHttpOptions } from "./system-one-http.ts";
+export interface LayaProviderOptions extends SystemOneHttpOptions {
+    /** Overrides LAYA_BASE_URL, then http://127.0.0.1:8001. */
+    readonly baseUrl?: string;
+    /** Overrides LAYA_API_KEY. No other provider's credentials are used. */
+    readonly apiKey?: string;
+    /** Overrides LAYA_MODEL, then laya. Must match the bridge's --model identifier. */
+    readonly model?: string;
+}
+export type LayaAgentOptions = LayaProviderOptions & DecisionAgentOptions;
+/** Choice adapter for services/laya/server.py; the server owns checkpoint loading. */
+export declare function layaProvider(options?: LayaProviderOptions): DecisionProvider;
+/** Convenience binding. The initial Laya checkpoint needs at least two choices. */
+export declare function layaAgent(options?: LayaAgentOptions): (request: import("./index.ts").AgentRequest, report?: import("./index.ts").AgentReporter) => Promise<import("./decision.ts").DecisionEvent>;

package/dist/src/laya.js

@@ -0,0 +1,13 @@
+import { decisionAgent } from "./decision.js";
+import { systemOneHttpProvider } from "./system-one-http.js";
+/** Choice adapter for services/laya/server.py; the server owns checkpoint loading. */
+export function layaProvider(options = {}) {
+    return systemOneHttpProvider({
+        name: "laya", label: "Laya", envPrefix: "LAYA",
+        baseUrl: "http://127.0.0.1:8001", model: "laya", minChoices: 2,
+    }, options);
+}
+/** Convenience binding. The initial Laya checkpoint needs at least two choices. */
+export function layaAgent(options = {}) {
+    return decisionAgent(layaProvider(options), options);
+}

package/dist/src/openrouter.d.ts

@@ -0,0 +1,16 @@
+import { type DecisionAgentOptions, type DecisionProvider } from "./decision.ts";
+export interface OpenRouterDecisionProviderOptions {
+    /** Read lazily from OPENROUTER_API_KEY. Never needed during discovery. */
+    readonly apiKey?: string;
+    /** Overrides OPENROUTER_DECISION_MODEL, then the pinned typesafe/jev-1.13. */
+    readonly model?: string;
+    /** Defaults to 10 seconds; covers both the request and response-body read. */
+    readonly timeoutMs?: number;
+    /** Explicit transport injection. Custom clients must honor the AbortSignal. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+export type OpenRouterDecisionAgentOptions = OpenRouterDecisionProviderOptions & DecisionAgentOptions;
+/** OpenRouter Decisions transport, not chat completions or a coding agent. */
+export declare function openRouterDecisionProvider(options?: OpenRouterDecisionProviderOptions): DecisionProvider;
+/** Convenience preset; workflow policy stays in the Machine. */
+export declare function openRouterDecisionAgent(options?: OpenRouterDecisionAgentOptions): (request: import("./index.ts").AgentRequest, report?: import("./index.ts").AgentReporter) => Promise<import("./decision.ts").DecisionEvent>;

package/dist/src/openrouter.js

@@ -0,0 +1,97 @@
+import * as v from "valibot";
+import { decisionAgent } from "./decision.js";
+const nonBlank = v.pipe(v.string(), v.check(value => value.trim().length > 0));
+const probability = v.pipe(v.number(), v.minValue(0), v.maxValue(1));
+// Validate only the fields consumed by this adapter. Usage and other metadata
+// are not forwarded into workflow events or observer output.
+const responseSchema = v.object({
+    model: nonBlank,
+    answers: v.object({
+        decision: v.object({
+            type: v.literal("choice"),
+            choice: nonBlank,
+            probabilities: v.optional(v.pipe(v.unknown(), v.check(value => !Array.isArray(value)), v.record(v.string(), probability))),
+            confidence: v.optional(probability),
+        }),
+    }),
+});
+/** OpenRouter Decisions transport, not chat completions or a coding agent. */
+export function openRouterDecisionProvider(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new Error("OpenRouter Decisions timeoutMs must be a positive 32-bit integer");
+    }
+    return {
+        name: "openrouter-decision",
+        async decide(request) {
+            const apiKey = options.apiKey ?? process.env.OPENROUTER_API_KEY;
+            if (typeof apiKey !== "string" || !apiKey.trim()) {
+                throw new Error("OpenRouter Decisions requires OPENROUTER_API_KEY or an explicit apiKey");
+            }
+            const model = options.model ?? process.env.OPENROUTER_DECISION_MODEL ?? "typesafe/jev-1.13";
+            if (typeof model !== "string" || !model.trim()) {
+                throw new Error("OpenRouter Decisions model must be non-empty");
+            }
+            if (Object.keys(request.choices).length === 0) {
+                throw new Error("OpenRouter Decisions requires at least one outcome");
+            }
+            // OpenRouter requires string criteria; the neutral contract allows null.
+            // Preserve labels verbatim and use the label when no description is given.
+            const criteria = Object.fromEntries(Object.entries(request.choices).map(([label, description]) => [label, description ?? label]));
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const timeoutError = () => new Error(`OpenRouter Decisions request timed out after ${timeoutMs}ms`);
+            try {
+                let response;
+                try {
+                    response = await (options.fetch ?? globalThis.fetch)("https://openrouter.ai/api/alpha/decisions", {
+                        method: "POST",
+                        redirect: "error",
+                        signal: controller.signal,
+                        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            model,
+                            state: request.input,
+                            questions: {
+                                decision: { type: "choice", instructions: request.question, criteria },
+                            },
+                        }),
+                    });
+                }
+                catch {
+                    // Transport errors may contain credentials or evidence; do not expose them.
+                    throw controller.signal.aborted ? timeoutError() : new Error("OpenRouter Decisions network request failed");
+                }
+                if (!response.ok) {
+                    // Discard diagnostics without waiting on an untrusted error-body stream.
+                    void response.body?.cancel().catch(() => { });
+                    throw new Error(`OpenRouter Decisions request failed (HTTP ${response.status}); no automatic retry`);
+                }
+                let body;
+                try {
+                    body = await response.json();
+                }
+                catch {
+                    throw controller.signal.aborted ? timeoutError() : new Error("OpenRouter Decisions returned invalid JSON");
+                }
+                const parsed = v.safeParse(responseSchema, body);
+                if (!parsed.success)
+                    throw new Error("OpenRouter Decisions returned an invalid Choice response");
+                const { choice, probabilities, confidence } = parsed.output.answers.decision;
+                return {
+                    choice,
+                    ...(probabilities === undefined ? {} : { probabilities }),
+                    ...(confidence === undefined ? {} : { confidence }),
+                    model: parsed.output.model,
+                };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+/** Convenience preset; workflow policy stays in the Machine. */
+export function openRouterDecisionAgent(options = {}) {
+    return decisionAgent(openRouterDecisionProvider(options), options);
+}