okengine 0.22.0 → 0.23.1

package/src/elements/ai/decisions/fixtures/openrouter-response.json

@@ -0,0 +1,22 @@
+{
+  "id": "gen-fixture",
+  "model": "typesafe/jev-1.13-20260917",
+  "provider": "TypeSafe",
+  "answers": {
+    "team": {
+      "type": "choice",
+      "choice": "technical",
+      "probabilities": { "billing": 0.46, "technical": 0.52, "none_of_these": 0.02 },
+      "confidence": 0.29
+    },
+    "severity": {
+      "type": "score",
+      "score": 1.82,
+      "legend": { "0": "low", "1": "medium", "2": "high" },
+      "probabilities": { "0": 0.01, "1": 0.16, "2": 0.83 },
+      "confidence": 0.73
+    },
+    "urgent": { "type": "noul", "noul": 0.57 }
+  },
+  "usage": { "input_tokens": 384, "output_tokens": 71, "cost": 0.000016128 }
+}

package/src/elements/ai/decisions/fixtures/typesafe-request.json

@@ -0,0 +1,19 @@
+{
+  "state": { "ticket": "Checkout is blank after Pay." },
+  "model": "jev-1.13.0",
+  "questions": {
+    "team": {
+      "type": "choice",
+      "instructions": "Which team should own this ticket?",
+      "criteria": {
+        "billing": "Payments and refunds",
+        "technical": "Bugs and outages",
+        "none_of_these": "None of the listed options fit"
+      }
+    },
+    "urgent": {
+      "type": "noul",
+      "instructions": "Does this convey urgency?"
+    }
+  }
+}

package/src/elements/ai/decisions/fixtures/typesafe-response.json

@@ -0,0 +1,13 @@
+{
+  "model": "jev-1.13.0",
+  "answers": {
+    "team": {
+      "type": "choice",
+      "choice": "technical",
+      "probabilities": { "billing": 0.08, "technical": 0.9, "none_of_these": 0.02 },
+      "confidence": 0.85
+    },
+    "urgent": { "type": "noul", "noul": 0.22 }
+  },
+  "usage": { "input_tokens": 180, "output_tokens": 24 }
+}

package/src/elements/ai/decisions/http.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Decision HTTP: fixtures parse, and 422 does not open the breaker.
+ */
+
+import { describe, expect, test } from "bun:test";
+import openrouterResponse from "./fixtures/openrouter-response.json";
+import typesafeResponse from "./fixtures/typesafe-response.json";
+import {
+  decisionBreakerOpen,
+  decisionHttp,
+  parseDecisionResponse,
+  resetDecisionBreakers,
+} from "./http.ts";
+import { DecisionOutageError, DecisionRequestError } from "./provider.ts";
+
+const request = {
+  model: "typesafe/jev-1.13",
+  state: { ticket: "Checkout is blank after Pay." },
+  questions: {
+    urgent: { type: "noul" as const, instructions: "Does this convey urgency?" },
+  },
+};
+
+describe("decision fixtures", () => {
+  test("typesafe and openrouter bodies parse", () => {
+    expect(parseDecisionResponse(typesafeResponse).model).toBe("jev-1.13.0");
+    expect(parseDecisionResponse(openrouterResponse).provider).toBe("TypeSafe");
+    expect(parseDecisionResponse(openrouterResponse).usage.cost).toBe(0.000016128);
+  });
+});
+
+describe("decision breaker", () => {
+  test("422 fails fast and leaves the breaker closed", async () => {
+    resetDecisionBreakers();
+    const fetchImpl = async () => new Response("bad question", { status: 422 });
+    await expect(
+      decisionHttp({
+        url: "https://openrouter.ai/api/alpha/decisions",
+        apiKey: "test",
+        request,
+        timeoutMs: 1000,
+        breakerKey: "openrouter-422",
+        fetch: fetchImpl,
+      }),
+    ).rejects.toBeInstanceOf(DecisionRequestError);
+    expect(decisionBreakerOpen("openrouter-422")).toBe(false);
+  });
+
+  test("429 retries without opening the breaker", async () => {
+    resetDecisionBreakers();
+    let calls = 0;
+    const fetchImpl = async () => {
+      calls += 1;
+      if (calls === 1)
+        return new Response("slow", { status: 429, headers: { "retry-after": "0" } });
+      return Response.json({ model: "jev", answers: { urgent: { noul: 0.9 } }, usage: {} });
+    };
+    const result = await decisionHttp({
+      url: "https://example.test/decisions",
+      apiKey: "test",
+      request,
+      timeoutMs: 1000,
+      breakerKey: "openrouter-429",
+      fetch: fetchImpl,
+    });
+    expect(result.model).toBe("jev");
+    expect(calls).toBe(2);
+    expect(decisionBreakerOpen("openrouter-429")).toBe(false);
+  });
+
+  test("500 counts toward the breaker and is not retried", async () => {
+    resetDecisionBreakers();
+    let calls = 0;
+    const fetchImpl = async () => {
+      calls += 1;
+      return new Response("down", { status: 500 });
+    };
+    await expect(
+      decisionHttp({
+        url: "https://example.test/decisions",
+        apiKey: "test",
+        request,
+        timeoutMs: 1000,
+        breakerKey: "openrouter-500",
+        fetch: fetchImpl,
+      }),
+    ).rejects.toBeInstanceOf(DecisionOutageError);
+    expect(calls).toBe(1);
+    await decisionHttp({
+      url: "https://example.test/decisions",
+      apiKey: "test",
+      request,
+      timeoutMs: 1000,
+      breakerKey: "openrouter-500",
+      fetch: fetchImpl,
+    }).catch(() => undefined);
+    await decisionHttp({
+      url: "https://example.test/decisions",
+      apiKey: "test",
+      request,
+      timeoutMs: 1000,
+      breakerKey: "openrouter-500",
+      fetch: fetchImpl,
+    }).catch(() => undefined);
+    expect(decisionBreakerOpen("openrouter-500")).toBe(true);
+  });
+
+  test("an aborted call is not retried", async () => {
+    resetDecisionBreakers();
+    let calls = 0;
+    const controller = new AbortController();
+    controller.abort();
+    const fetchImpl = async () => {
+      calls += 1;
+      return new Response("nope", { status: 429, headers: { "retry-after": "0" } });
+    };
+    await expect(
+      decisionHttp({
+        url: "https://example.test/decisions",
+        apiKey: "test",
+        request: { ...request, signal: controller.signal },
+        timeoutMs: 1000,
+        breakerKey: "openrouter-abort",
+        fetch: fetchImpl,
+      }),
+    ).rejects.toThrow();
+    expect(calls).toBeLessThanOrEqual(1);
+    expect(decisionBreakerOpen("openrouter-abort")).toBe(false);
+  });
+
+  test("invalid JSON is not retried", async () => {
+    resetDecisionBreakers();
+    let calls = 0;
+    const fetchImpl = async () => {
+      calls += 1;
+      return new Response("not-json", {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    };
+    await expect(
+      decisionHttp({
+        url: "https://example.test/decisions",
+        apiKey: "test",
+        request,
+        timeoutMs: 1000,
+        breakerKey: "openrouter-json",
+        fetch: fetchImpl,
+      }),
+    ).rejects.toBeInstanceOf(DecisionRequestError);
+    expect(calls).toBe(1);
+    expect(decisionBreakerOpen("openrouter-json")).toBe(false);
+  });
+});

package/src/elements/ai/decisions/http.ts

@@ -0,0 +1,240 @@
+/**
+ * Raw decision HTTP: deadline, 429/529 retry, and a breaker that ignores 401/402/422.
+ */
+
+import {
+  DecisionOutageError,
+  DecisionRequestError,
+  type DecisionRequest,
+  type DecisionResponse,
+  type DecisionUsage,
+} from "./provider.ts";
+
+/** Fetch used by {@link decisionHttp}. Tests inject this. */
+export type DecisionFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+/** Options for one decision POST. */
+export interface DecisionHttpOptions {
+  readonly url: string;
+  readonly apiKey: string;
+  readonly request: DecisionRequest;
+  readonly timeoutMs: number;
+  readonly fetch?: DecisionFetch;
+  /** Max attempts including the first. Default 3. */
+  readonly attempts?: number;
+  /** Breaker key. Calls that share it share the open/closed state. */
+  readonly breakerKey: string;
+}
+
+interface BreakerState {
+  failures: number;
+  openUntil: number;
+}
+
+const breakers = new Map<string, BreakerState>();
+
+const FAILURES_TO_OPEN = 3;
+const OPEN_MS = 30_000;
+
+/**
+ * Reset breaker state. Tests only.
+ */
+export function resetDecisionBreakers(): void {
+  breakers.clear();
+}
+
+/**
+ * Whether `key` is currently open.
+ *
+ * @param key - Breaker key
+ * @param now - Clock
+ */
+export function decisionBreakerOpen(key: string, now: number = Date.now()): boolean {
+  const state = breakers.get(key);
+  return state !== undefined && state.openUntil > now;
+}
+
+function noteFailure(key: string, now: number): void {
+  const state = breakers.get(key) ?? { failures: 0, openUntil: 0 };
+  state.failures += 1;
+  if (state.failures >= FAILURES_TO_OPEN) state.openUntil = now + OPEN_MS;
+  breakers.set(key, state);
+}
+
+function noteSuccess(key: string): void {
+  breakers.delete(key);
+}
+
+const REQUEST_STATUSES = new Set([400, 401, 402, 403, 404, 422]);
+
+/** Waits longer than this take the outage path. */
+const RETRY_CAP_MS = 60_000;
+
+function retryAfterMs(res: Response, now = Date.now()): number | "outage" {
+  const header = res.headers.get("retry-after");
+  if (!header) return 250;
+  const seconds = Number(header);
+  const ms =
+    Number.isFinite(seconds) && seconds >= 0
+      ? seconds * 1000
+      : Number.isFinite(Date.parse(header))
+        ? Math.max(0, Date.parse(header) - now)
+        : 250;
+  if (ms > RETRY_CAP_MS) return "outage";
+  return ms;
+}
+
+function abortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new DOMException("The operation was aborted", "AbortError");
+}
+
+async function waitForRetry(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  if (signal?.aborted) throw abortError(signal);
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(signal!));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function usageFrom(raw: unknown): DecisionUsage {
+  if (!raw || typeof raw !== "object") return {};
+  const usage = raw as {
+    input_tokens?: unknown;
+    output_tokens?: unknown;
+    cost?: unknown;
+    inputTokens?: unknown;
+    outputTokens?: unknown;
+  };
+  const input = usage.input_tokens ?? usage.inputTokens;
+  const output = usage.output_tokens ?? usage.outputTokens;
+  return {
+    ...(typeof input === "number" ? { inputTokens: input } : {}),
+    ...(typeof output === "number" ? { outputTokens: output } : {}),
+    ...(typeof usage.cost === "number" ? { cost: usage.cost } : {}),
+  };
+}
+
+/**
+ * Parse a provider JSON body into {@link DecisionResponse}.
+ *
+ * @param body - Parsed JSON
+ */
+export function parseDecisionResponse(body: unknown): DecisionResponse {
+  if (!body || typeof body !== "object") {
+    throw new DecisionRequestError(422, "decision response was not an object");
+  }
+  const record = body as {
+    model?: unknown;
+    provider?: unknown;
+    answers?: unknown;
+    usage?: unknown;
+  };
+  if (typeof record.model !== "string" || !record.answers || typeof record.answers !== "object") {
+    throw new DecisionRequestError(422, "decision response missing model or answers");
+  }
+  return {
+    model: record.model,
+    ...(typeof record.provider === "string" ? { provider: record.provider } : {}),
+    answers: record.answers as Readonly<Record<string, unknown>>,
+    usage: usageFrom(record.usage),
+  };
+}
+
+/**
+ * POST one decision request.
+ *
+ * @param options - URL, key, body, deadline, breaker
+ */
+export async function decisionHttp(options: DecisionHttpOptions): Promise<DecisionResponse> {
+  const now = Date.now();
+  if (decisionBreakerOpen(options.breakerKey, now)) {
+    throw new DecisionOutageError(`decision breaker open for ${options.breakerKey}`);
+  }
+  const fetchImpl = options.fetch ?? fetch;
+  const attempts = options.attempts ?? 3;
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const local = new AbortController();
+    const timer = setTimeout(() => local.abort(), options.timeoutMs);
+    const parent = options.request.signal;
+    const onParent = () => local.abort();
+    parent?.addEventListener("abort", onParent);
+    try {
+      const res = await fetchImpl(options.url, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${options.apiKey}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          model: options.request.model,
+          state: options.request.state,
+          questions: options.request.questions,
+        }),
+        signal: local.signal,
+      });
+      if (REQUEST_STATUSES.has(res.status)) {
+        const text = await res.text();
+        throw new DecisionRequestError(
+          res.status as 400 | 401 | 402 | 403 | 404 | 422,
+          text.slice(0, 500),
+        );
+      }
+      if (res.status === 429) {
+        lastError = new Error(`decision HTTP ${res.status}`);
+        const wait = retryAfterMs(res);
+        if (wait === "outage") throw new DecisionOutageError(`decision HTTP ${res.status}`);
+        if (attempt < attempts) {
+          await waitForRetry(wait, parent);
+          continue;
+        }
+        throw new DecisionOutageError(`decision HTTP ${res.status}`);
+      }
+      if (res.status === 529 || res.status >= 500) {
+        noteFailure(options.breakerKey, Date.now());
+        lastError = new Error(`decision HTTP ${res.status}`);
+        const wait = retryAfterMs(res);
+        if (wait === "outage") throw new DecisionOutageError(`decision HTTP ${res.status}`);
+        if (res.status === 529 && attempt < attempts) {
+          await waitForRetry(wait, parent);
+          continue;
+        }
+        throw new DecisionOutageError(`decision HTTP ${res.status}`);
+      }
+      if (!res.ok) {
+        throw new DecisionOutageError(`decision HTTP ${res.status}`);
+      }
+      let body: unknown;
+      try {
+        body = await res.json();
+      } catch {
+        throw new DecisionRequestError(422, "decision response was not JSON");
+      }
+      const parsed = parseDecisionResponse(body);
+      noteSuccess(options.breakerKey);
+      return parsed;
+    } catch (err) {
+      if (parent?.aborted) throw abortError(parent);
+      if (err instanceof DecisionRequestError) throw err;
+      if (err instanceof DecisionOutageError) throw err;
+      noteFailure(options.breakerKey, Date.now());
+      lastError = err;
+      throw new DecisionOutageError(
+        err instanceof Error ? err.message : "decision transport failed",
+      );
+    } finally {
+      clearTimeout(timer);
+      parent?.removeEventListener("abort", onParent);
+    }
+  }
+  throw new DecisionOutageError(lastError instanceof Error ? lastError.message : "decision failed");
+}