okengine 0.23.2 → 0.24.0

package/src/console/ui-next/src/features/flows/decisions/decisions-page.tsx

@@ -118,6 +118,17 @@ export function DecisionsPage(): JSX.Element {
           >
             <span className="min-w-0 flex-1 truncate">{decision.name}</span>
             <span className={EXPLORER_COUNT_CLASS}>{decisionStateLabel(decision.state)}</span>
+            {decision.certificates?.map((certificate) => (
+              <span
+                key={certificate.decider}
+                className={EXPLORER_COUNT_CLASS}
+                data-slot="decision-certificate"
+                data-pinned={certificate.pinned ? "true" : "false"}
+              >
+                {certificate.decider} {certificate.model}
+                {certificate.pinned ? "" : " unpinned"}
+              </span>
+            ))}
             {decision.metrics ? (
               <span className={EXPLORER_COUNT_CLASS} data-slot="decision-metrics">
                 {Object.entries(decision.metrics)
@@ -151,6 +162,11 @@ export function DecisionsPage(): JSX.Element {
             <span className="min-w-0 flex-1 truncate">
               {row.decision}
               {row.labelOnly ? " · label" : ""}
+              {row.why === "refused" && row.by
+                ? ` · refused by ${row.by}`
+                : row.why
+                  ? ` · ${row.why}`
+                  : ""}
             </span>
             <span className={EXPLORER_COUNT_CLASS} data-slot="decision-age">
               {formatAge(row.ageMs)}

package/src/elements/ai/deciders/presets.ts

@@ -0,0 +1,182 @@
+/**
+ * Verified decision hosts. Anything else is `driverId` + `baseUrl` + `capabilities`.
+ * Codecs stay out of this module so the edge graph does not load them.
+ */
+
+/** Wire a decider speaks. */
+export type DeciderProtocol = "systemone" | "openai-decisions";
+
+/** How a certificate binds to a model id. */
+export type DeciderPinning = "dated" | "alias";
+
+/** What one decider can answer. Numeric limits apply only when present. */
+export interface DeciderCapabilities {
+  readonly boolean: boolean;
+  readonly choice: boolean;
+  readonly score: boolean;
+  readonly refusal: boolean;
+  readonly maxChoices?: number;
+  readonly minLevels?: number;
+  readonly maxLevels?: number;
+  readonly maxContext?: number;
+}
+
+/** One verified host. */
+export interface DeciderPreset {
+  readonly protocol: DeciderProtocol;
+  readonly baseUrl: string;
+  readonly secret: string;
+  readonly pinning: DeciderPinning;
+  readonly capabilities: DeciderCapabilities;
+}
+
+/** Literal capabilities for the OpenRouter preset. */
+type OpenRouterPreset = {
+  readonly protocol: "systemone";
+  readonly baseUrl: "https://openrouter.ai/api/alpha/decisions";
+  readonly secret: "OPENROUTER_API_KEY";
+  readonly pinning: "dated";
+  readonly capabilities: {
+    readonly boolean: true;
+    readonly choice: true;
+    readonly score: true;
+    readonly refusal: false;
+  };
+};
+
+/** Literal capabilities for the OpenAI preset. */
+type OpenAIPreset = {
+  readonly protocol: "openai-decisions";
+  readonly baseUrl: "https://api.openai.com/v1/decisions";
+  readonly secret: "OPENAI_API_KEY";
+  readonly pinning: "alias";
+  readonly capabilities: {
+    readonly boolean: true;
+    readonly choice: true;
+    readonly score: true;
+    readonly refusal: true;
+  };
+};
+
+/** OpenRouter System One and OpenAI Decisions. No other host is filled in. */
+export const DECIDER_PRESETS: {
+  readonly openrouter: OpenRouterPreset;
+  readonly openai: OpenAIPreset;
+} = {
+  openrouter: {
+    protocol: "systemone",
+    baseUrl: "https://openrouter.ai/api/alpha/decisions",
+    secret: "OPENROUTER_API_KEY",
+    pinning: "dated",
+    capabilities: { boolean: true, choice: true, score: true, refusal: false },
+  },
+  openai: {
+    protocol: "openai-decisions",
+    baseUrl: "https://api.openai.com/v1/decisions",
+    secret: "OPENAI_API_KEY",
+    pinning: "alias",
+    capabilities: { boolean: true, choice: true, score: true, refusal: true },
+  },
+};
+
+/** Preset provider id. */
+export type DeciderPresetName = keyof typeof DECIDER_PRESETS;
+
+/** Alias certificates expire this long after certify. */
+export const ALIAS_CERTIFICATE_MS: number = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * Whether `provider` is a shipped preset.
+ *
+ * @param provider - Author provider id
+ */
+export function isDeciderPreset(provider: string): provider is DeciderPresetName {
+  return Object.prototype.hasOwnProperty.call(DECIDER_PRESETS, provider);
+}
+
+/** Fields shared by a preset and a custom host. */
+export interface ResolvedDecider {
+  readonly protocol: DeciderProtocol;
+  readonly baseUrl: string;
+  readonly model: string;
+  readonly secret: string;
+  readonly pinning: DeciderPinning;
+  readonly capabilities: DeciderCapabilities;
+  readonly provider?: string;
+  readonly region?: string;
+  readonly regionStatus?: "declared";
+  readonly zdr?: boolean;
+  readonly zdrStatus?: "declared";
+  readonly timeout?: number | string;
+  readonly concurrency?: number;
+}
+
+/**
+ * Fill a preset, or require the custom host fields.
+ * Region and ZDR are the app's declaration. Neither preset publishes a verified value.
+ *
+ * @param name - Decider name, for the error
+ * @param options - Author options
+ */
+export function resolveDecider(
+  name: string,
+  options: {
+    readonly provider?: string;
+    readonly driverId?: string;
+    readonly baseUrl?: string;
+    readonly model?: string;
+    readonly secret?: string;
+    readonly capabilities?: DeciderCapabilities;
+    readonly region?: string;
+    readonly zdr?: boolean;
+    readonly timeout?: number | string;
+    readonly concurrency?: number;
+  },
+): ResolvedDecider {
+  if (!options.model) throw new TypeError(`ai.decider("${name}"): model is required`);
+  const declared = {
+    ...(options.region !== undefined
+      ? { region: options.region, regionStatus: "declared" as const }
+      : {}),
+    ...(options.zdr !== undefined ? { zdr: options.zdr, zdrStatus: "declared" as const } : {}),
+    ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+    ...(options.concurrency !== undefined ? { concurrency: options.concurrency } : {}),
+  };
+  if (options.provider && isDeciderPreset(options.provider)) {
+    const preset = DECIDER_PRESETS[options.provider];
+    return {
+      protocol: preset.protocol,
+      baseUrl: preset.baseUrl,
+      model: options.model,
+      secret: options.secret ?? preset.secret,
+      pinning: preset.pinning,
+      capabilities: preset.capabilities,
+      provider: options.provider,
+      ...declared,
+    };
+  }
+  if (options.driverId !== "systemone" && options.driverId !== "openai-decisions") {
+    throw new TypeError(
+      `ai.decider("${name}"): provider "${options.provider ?? ""}" needs driverId "systemone" or "openai-decisions", baseUrl, and capabilities`,
+    );
+  }
+  if (!options.baseUrl) {
+    throw new TypeError(`ai.decider("${name}"): baseUrl is required`);
+  }
+  if (!options.secret) {
+    throw new TypeError(`ai.decider("${name}"): secret is required`);
+  }
+  if (!options.capabilities) {
+    throw new TypeError(`ai.decider("${name}"): capabilities are required`);
+  }
+  return {
+    protocol: options.driverId,
+    baseUrl: options.baseUrl,
+    model: options.model,
+    secret: options.secret,
+    pinning: options.driverId === "openai-decisions" ? "alias" : "dated",
+    capabilities: options.capabilities,
+    ...(options.provider !== undefined ? { provider: options.provider } : {}),
+    ...declared,
+  };
+}

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

@@ -63,15 +63,16 @@ export function bindDecisionFlows(adopt: (binding: Binding) => void, manifest: M
         const decl = aiDecisionRegistry.find((item) => item.name === name);
         const pinned = pinnedDecision(name);
         const rows = await loadDecisionLabels(name);
-        const fitted = aggregateDecisionCandidate(name, () =>
-          certifyLabels({
-            model: pinned?.model ?? decl?.model ?? "",
+        const fitted = aggregateDecisionCandidate(name, () => {
+          const cert = certifyLabels({
+            model: pinned?.model ?? "",
             maxError: decl?.autonomy?.maxError ?? 0.05,
             delta: decl?.autonomy?.risk ?? 0.1,
             ask: decl?.ask ?? {},
             labels: rows,
-          }),
-        );
+          });
+          return { decider: decl?.decider ?? "", ...cert };
+        });
         await persistDecisionCandidate(name, fitted);
       }
       return { ok: true };

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

@@ -0,0 +1,93 @@
+/**
+ * OpenRouter decision-model catalog. Only fields the catalog actually returns.
+ */
+
+const CATALOG_URL = "https://openrouter.ai/api/v1/models?output_modalities=decisions";
+
+interface CatalogRow {
+  readonly id?: unknown;
+  readonly canonical_slug?: unknown;
+  readonly context_length?: unknown;
+  readonly architecture?: { readonly input_modalities?: unknown };
+  readonly alias_target?: { readonly slug?: unknown };
+}
+
+/**
+ * Lines for `oke decide models`: id, canonical slug, context, input modalities.
+ *
+ * @param body - Catalog JSON
+ */
+export function formatDecisionModels(body: unknown): string {
+  const rows = catalogRows(body);
+  if (rows.length === 0) return "oke decide models: no decision models\n";
+  const lines = ["id\tcanonical_slug\tcontext\tinput"];
+  for (const row of rows) {
+    const id = typeof row.id === "string" ? row.id : "";
+    const canonical = typeof row.canonical_slug === "string" ? row.canonical_slug : "";
+    const context = typeof row.context_length === "number" ? String(row.context_length) : "";
+    const input = Array.isArray(row.architecture?.input_modalities)
+      ? row.architecture.input_modalities.filter((item) => typeof item === "string").join(",")
+      : "";
+    lines.push(`${id}\t${canonical}\t${context}\t${input}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Fetch the public decision catalog and format it.
+ *
+ * @param fetcher - Injected fetch
+ */
+export async function fetchDecisionModels(
+  fetcher: (input: string, init?: RequestInit) => Promise<Response> = fetch,
+): Promise<string> {
+  const res = await fetcher(CATALOG_URL);
+  if (!res.ok) throw new Error(`oke decide models: ${res.status}`);
+  return formatDecisionModels(await res.json());
+}
+
+/**
+ * Dated slug the catalog lists for `model`, when it differs from `model`.
+ * Missing catalog, unknown id, or an undated canonical slug returns undefined.
+ *
+ * @param model - Decider model id
+ * @param baseUrl - Decider URL. Only OpenRouter is queried.
+ * @param pinning - `dated` looks up a slug. `alias` does not.
+ * @param fetcher - Injected fetch
+ */
+export async function requiredDatedModel(
+  model: string,
+  baseUrl: string,
+  pinning: "dated" | "alias",
+  fetcher: (input: string, init?: RequestInit) => Promise<Response> = fetch,
+): Promise<string | undefined> {
+  if (pinning !== "dated" || !baseUrl.includes("openrouter.ai")) return undefined;
+  try {
+    const res = await fetcher(CATALOG_URL);
+    if (!res.ok) return undefined;
+    return datedSlug(catalogRows(await res.json()), model);
+  } catch {
+    return undefined;
+  }
+}
+
+function catalogRows(body: unknown): CatalogRow[] {
+  if (!body || typeof body !== "object") return [];
+  const data = (body as { data?: unknown }).data;
+  return Array.isArray(data) ? (data as CatalogRow[]) : [];
+}
+
+function datedSlug(rows: readonly CatalogRow[], model: string): string | undefined {
+  const row = rows.find((item) => item.id === model);
+  if (!row) return undefined;
+  const target = typeof row.alias_target?.slug === "string" ? row.alias_target.slug : undefined;
+  const followed = target ? rows.find((item) => item.id === target) : undefined;
+  const canonical =
+    typeof followed?.canonical_slug === "string"
+      ? followed.canonical_slug
+      : typeof row.canonical_slug === "string"
+        ? row.canonical_slug
+        : undefined;
+  if (!canonical || !/-\d{8}$/.test(canonical) || canonical === model) return undefined;
+  return canonical;
+}

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

@@ -36,6 +36,7 @@ function answer() {
     answers: {
       team: {
         type: "choice",
+        choice: "technical",
         probabilities: { billing: 0.08, technical: 0.9, none_of_these: 0.02 },
       },
     },
@@ -54,22 +55,29 @@ async function run(
 ) {
   const question = ai.choice("which team", { billing: "Billing", technical: "Technical" });
   const decl = ai.decision("triage", {
-    onUncertain: "abstain",
+    decider: ai.decider("jev", { provider: "openrouter", model: "typesafe/jev-1.13.0" }),
+    otherwise: "abstain",
     autonomy: { maxError: 0.05, audit: 0 },
     ...(extra?.locale ? { locale: () => "ar" } : {}),
     ask: { team: question },
   });
   if (lock) {
     setDecisionLock({
+      version: 2,
       decisions: {
         triage: {
-          model: extra?.mismatch ? "other" : "typesafe/jev-1.13.0",
-          questions: {
-            team: {
-              "": {
-                hash: extra?.stale ? "nope" : questionHash(question),
-                calibrator: { kind: "temperature" as const, t: 1 },
-                threshold: 0.5,
+          deciders: {
+            jev: {
+              model: extra?.mismatch ? "other" : "typesafe/jev-1.13.0",
+              pinned: true,
+              questions: {
+                team: {
+                  "": {
+                    hash: extra?.stale ? "nope" : questionHash(question),
+                    calibrator: { kind: "temperature" as const, t: 1 },
+                    threshold: 0.5,
+                  },
+                },
               },
             },
           },
@@ -133,7 +141,9 @@ describe("decision certificates", () => {
 
   test("promote writes the fetched candidate", async () => {
     const candidate = {
+      decider: "jev",
       model: "typesafe/jev-1.13.0",
+      pinned: true,
       questions: {
         team: {
           "": {
@@ -144,34 +154,45 @@ describe("decision certificates", () => {
         },
       },
     };
+    const slot = {
+      deciders: {
+        jev: {
+          model: candidate.model,
+          pinned: true,
+          questions: candidate.questions,
+        },
+      },
+    };
     const dir = await mkdtemp(join(tmpdir(), "oke-decide-"));
     const lockPath = join(dir, "oke-decisions.lock.json");
     const written = await promoteDecision({
       name: "triage",
       origin: "http://127.0.0.1:6530",
       lockPath,
-      current: { decisions: {} },
+      current: { version: 2, decisions: {} },
       fetcher: async () => new Response(JSON.stringify(candidate), { status: 200 }),
     });
-    expect(written.decisions.triage).toEqual(candidate);
+    expect(written.version).toBe(2);
+    expect(written.decisions.triage).toEqual(slot);
     const disk = JSON.parse(await readFile(lockPath, "utf8")) as { decisions: { triage: unknown } };
-    expect(disk.decisions.triage).toEqual(candidate);
-    await Bun.write(lockPath, `${JSON.stringify({ decisions: { other: candidate } })}\n`);
+    expect(disk.decisions.triage).toEqual(slot);
+    await Bun.write(lockPath, `${JSON.stringify({ version: 2, decisions: { other: slot } })}\n`);
     const merged = await promoteDecision({
       name: "triage",
       origin: "http://127.0.0.1:6530",
       lockPath,
       fetcher: async () => new Response(JSON.stringify(candidate), { status: 200 }),
     });
-    expect(merged.decisions.other).toEqual(candidate);
-    expect(merged.decisions.triage).toEqual(candidate);
+    expect(merged.decisions.other).toEqual(slot);
+    expect(merged.decisions.triage).toEqual(slot);
     expect(await loadDecisionLockfile(dir)).toEqual(merged);
   });
 
   test("certify fits a threshold from the provider and hashes the question", async () => {
     const question = ai.choice("which team", { billing: "Billing", technical: "Technical" });
     const decl = ai.decision("triage", {
-      onUncertain: "abstain",
+      decider: ai.decider("jev", { provider: "openrouter", model: "typesafe/jev-1.13.0" }),
+      otherwise: "abstain",
       autonomy: { maxError: 0.05, audit: 0 },
       evals: "seed.jsonl",
       ask: { team: question },
@@ -192,14 +213,15 @@ describe("decision certificates", () => {
         answers: {
           team: {
             type: "choice",
+            choice: "technical",
             probabilities: { billing: 0.05, technical: 0.93, none_of_these: 0.02 },
           },
         },
         usage: {},
       }),
     });
-    expect(entry.questions.team?.[""]?.hash).toBe(questionHash(question));
-    expect(entry.questions.team?.[""]?.threshold).toBeGreaterThan(0);
+    expect(entry.cert.questions.team?.[""]?.hash).toBe(questionHash(question));
+    expect(entry.cert.questions.team?.[""]?.threshold).toBeGreaterThan(0);
     const dir = await mkdtemp(join(tmpdir(), "oke-cert-"));
     const seedPath = join(dir, "seed.jsonl");
     await Bun.write(seedPath, seed);
@@ -212,6 +234,8 @@ describe("decision certificates", () => {
           decisions: {
             triage: {
               mode: "abstain",
+              decider: "jev",
+              otherwise: "abstain",
               questions: ["team"],
               evals: seedPath,
               autonomy: { maxError: 0.05, audit: 0 },
@@ -224,6 +248,7 @@ describe("decision certificates", () => {
         answers: {
           team: {
             type: "choice",
+            choice: "technical",
             probabilities: { billing: 0.05, technical: 0.93, none_of_these: 0.02 },
           },
         },
@@ -232,7 +257,9 @@ describe("decision certificates", () => {
     });
     expect(code).toBe(0);
     const loaded = await loadDecisionLockfile(dir);
-    expect(loaded?.decisions.triage?.questions.team?.[""]?.hash).toBe(questionHash(question));
+    expect(loaded?.decisions.triage?.deciders.jev?.questions.team?.[""]?.hash).toBe(
+      questionHash(question),
+    );
   });
 
   test("one seed row does not certify a slice", async () => {
@@ -247,13 +274,14 @@ describe("decision certificates", () => {
         answers: {
           team: {
             type: "choice",
+            choice: "technical",
             probabilities: { billing: 0.05, technical: 0.93, none_of_these: 0.02 },
           },
         },
         usage: {},
       }),
     });
-    expect(entry.questions.team).toBeUndefined();
+    expect(entry.cert.questions.team).toBeUndefined();
   });
 
   test("choice and score labels certify from the stored distribution", () => {