jev-layer 0.1.0 → 0.3.0

package/src/model-routing.mjs

@@ -0,0 +1,87 @@
+import { routeRequest } from "./route.mjs";
+
+/**
+ * Recommend one host-declared model profile for the next model call.
+ * This is a shadow decision: it never mutates the host model/provider setting.
+ */
+export async function recommendModelRoute({
+  intent,
+  context = {},
+  models,
+  harness = "unknown",
+  policy = {},
+  provider = "demo",
+  config,
+} = {}) {
+  if (!Array.isArray(models) || models.length === 0) throw new TypeError("models[] is required");
+  const profiles = models.map(normalizeProfile);
+  const profileById = new Map(profiles.map((profile) => [profile.id, profile]));
+  const decision = await routeRequest({
+    harness,
+    intent,
+    context: { ...context, model_route: { mode: "shadow", profiles: profiles.map(publicProfile) } },
+    capabilities: profiles.map(toCapability),
+    policy: {
+      ...policy,
+      // A recommendation must never create an approval boundary by itself.
+      confirmation_risk_levels: [],
+    },
+  }, { provider, config });
+  return {
+    ...decision,
+    route_mode: "shadow",
+    recommended_model: decision.selected ? publicProfile(profileById.get(decision.selected)) : null,
+  };
+}
+
+function normalizeProfile(value, index) {
+  if (!value || typeof value !== "object") throw new TypeError(`models[${index}] must be an object`);
+  const id = required(value.id, `models[${index}].id`);
+  const model = required(value.model ?? value.id, `models[${index}].model`);
+  const provider = string(value.provider, "unknown");
+  const reasoning_effort = string(value.reasoning_effort, "default");
+  const description = string(value.description, `${provider}/${model}; reasoning=${reasoning_effort}`);
+  return {
+    id,
+    provider,
+    model,
+    reasoning_effort,
+    description,
+    available: value.available !== false && value.availability?.available !== false,
+    availability_reason: value.availability?.reason ?? null,
+  };
+}
+
+function toCapability(profile) {
+  return {
+    id: profile.id,
+    kind: "model",
+    name: profile.model,
+    description: profile.description,
+    risk: "low",
+    available: profile.available,
+    availability: { available: profile.available, reason: profile.availability_reason },
+    source: profile.provider,
+    metadata: { model: profile.model },
+  };
+}
+
+function publicProfile(profile) {
+  if (!profile) return null;
+  return {
+    id: profile.id,
+    provider: profile.provider,
+    model: profile.model,
+    reasoning_effort: profile.reasoning_effort,
+    available: profile.available,
+  };
+}
+
+function required(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${label} is required`);
+  return value.trim();
+}
+
+function string(value, fallback) {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}

package/src/providers/demo.mjs

@@ -1,52 +1,52 @@
-import { stableJson } from "../contract.mjs";
-
-const TOKEN_RE = /[\p{L}\p{N}_-]+/gu;
-
-export class DemoProvider {
-  name = "jev-demo";
-
-  async decide({ state, candidates }) {
-    const requestTokens = tokens(`${state.intent} ${stableJson(state.context ?? {})}`);
-    const scored = candidates.map((candidate) => {
-      const candidateTokens = tokens(`${candidate.id} ${candidate.name} ${candidate.description}`);
-      const overlap = [...requestTokens].filter((token) => candidateTokens.has(token)).length;
-      return { id: candidate.id, score: overlap + 0.01 };
-    });
-    const total = scored.reduce((sum, item) => sum + item.score, 0);
-    const probabilities = Object.fromEntries(scored.map(({ id, score }) => [id, score / total]));
-    const choice = [...scored].sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))[0]?.id ?? "";
-    const top = choice ? probabilities[choice] : 0;
-    const confidence = scored.length <= 1
-      ? 1
-      : Math.max(0, Math.min(1, (top - 1 / scored.length) / Math.max(1 - 1 / scored.length, 0.0001)));
-    return {
-      model: "jev-demo",
-      answers: {
-        tool: {
-          type: "choice",
-          choice,
-          probabilities,
-          confidence,
-        },
-      },
-      usage: { input_bytes: Buffer.byteLength(stableJson(state), "utf8"), output_bytes: 0 },
-    };
-  }
-
-  async evaluate({ state, questions }) {
-    const supplied = state.context?.supervision?.judgments ?? {};
-    const answers = Object.fromEntries(Object.keys(questions).map((id) => {
-      const value = typeof supplied[id] === "number" ? Math.max(0, Math.min(1, supplied[id])) : 0.5;
-      return [id, { type: "noul", probability: value, confidence: 1 }];
-    }));
-    return {
-      model: "jev-demo",
-      answers,
-      usage: { input_bytes: Buffer.byteLength(stableJson(state), "utf8"), output_bytes: 0 },
-    };
-  }
-}
-
-function tokens(value) {
-  return new Set(value.toLowerCase().match(TOKEN_RE) ?? []);
-}
+import { stableJson } from "../contract.mjs";
+
+const TOKEN_RE = /[\p{L}\p{N}_-]+/gu;
+
+export class DemoProvider {
+  name = "jev-demo";
+
+  async decide({ state, candidates }) {
+    const requestTokens = tokens(`${state.intent} ${stableJson(state.context ?? {})}`);
+    const scored = candidates.map((candidate) => {
+      const candidateTokens = tokens(`${candidate.id} ${candidate.name} ${candidate.description}`);
+      const overlap = [...requestTokens].filter((token) => candidateTokens.has(token)).length;
+      return { id: candidate.id, score: overlap + 0.01 };
+    });
+    const total = scored.reduce((sum, item) => sum + item.score, 0);
+    const probabilities = Object.fromEntries(scored.map(({ id, score }) => [id, score / total]));
+    const choice = [...scored].sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))[0]?.id ?? "";
+    const top = choice ? probabilities[choice] : 0;
+    const confidence = scored.length <= 1
+      ? 1
+      : Math.max(0, Math.min(1, (top - 1 / scored.length) / Math.max(1 - 1 / scored.length, 0.0001)));
+    return {
+      model: "jev-demo",
+      answers: {
+        tool: {
+          type: "choice",
+          choice,
+          probabilities,
+          confidence,
+        },
+      },
+      usage: { input_bytes: Buffer.byteLength(stableJson(state), "utf8"), output_bytes: 0 },
+    };
+  }
+
+  async evaluate({ state, questions }) {
+    const supplied = state.context?.supervision?.judgments ?? {};
+    const answers = Object.fromEntries(Object.keys(questions).map((id) => {
+      const value = typeof supplied[id] === "number" ? Math.max(0, Math.min(1, supplied[id])) : 0.5;
+      return [id, { type: "noul", probability: value, confidence: 1 }];
+    }));
+    return {
+      model: "jev-demo",
+      answers,
+      usage: { input_bytes: Buffer.byteLength(stableJson(state), "utf8"), output_bytes: 0 },
+    };
+  }
+}
+
+function tokens(value) {
+  return new Set(value.toLowerCase().match(TOKEN_RE) ?? []);
+}

package/src/providers/index.mjs

@@ -0,0 +1,12 @@
+import { configuredProviderOptions } from "../config.mjs";
+import { DemoProvider } from "./demo.mjs";
+import { OpenRouterDecisionsProvider, TypeSafeProvider } from "./typesafe.mjs";
+
+export function resolveProvider(provider, options = {}) {
+  if (provider && typeof provider === "object") return provider;
+  if (provider === "demo") return new DemoProvider();
+  const settings = { ...configuredProviderOptions(options.config, provider), ...options[provider] };
+  if (provider === "openrouter") return new OpenRouterDecisionsProvider(settings);
+  if (provider === "typesafe") return new TypeSafeProvider(settings);
+  throw new Error(`unsupported provider: ${provider}`);
+}

package/src/providers/typesafe.mjs

@@ -1,126 +1,206 @@
-import { stableJson } from "../contract.mjs";
-
-export class TypeSafeProvider {
-  name = "typesafe";
-
-  constructor({ apiKey = process.env.TYPESAFE_API_KEY, endpoint = process.env.TYPESAFE_ENDPOINT ?? "https://api.typesafe.ai/v1/systemone", model = process.env.TYPESAFE_MODEL ?? "jev-latest", timeoutMs = 2_000 } = {}) {
-    this.apiKey = apiKey;
-    this.endpoint = endpoint;
-    this.model = model;
-    this.timeoutMs = timeoutMs;
-  }
-
-  async decide({ state, candidates }) {
-    const criteria = Object.fromEntries(candidates.map((candidate) => [candidate.id, {
-      name: candidate.name,
-      kind: candidate.kind,
-      description: candidate.description,
-      risk: candidate.risk,
-    }]));
-    return this.evaluate({
-      state,
-      questions: {
-        tool: {
-          type: "choice",
-          instructions: "Which single capability should handle this request? Choose only from the supplied options.",
-          criteria,
-        },
-      },
-    });
-  }
-
-  async evaluate({ state, questions }) {
-    if (!this.apiKey) throw new Error("TYPESAFE_API_KEY is not configured");
-    const response = await fetch(this.endpoint, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ state, model: this.model, questions }),
-      signal: AbortSignal.timeout(this.timeoutMs),
-    }).catch((error) => {
-      if (error?.name === "TimeoutError") throw new Error(`TypeSafe request timed out after ${this.timeoutMs}ms`);
-      throw error;
-    });
-
-    if (!response.ok) {
-      const body = await response.text();
-      throw new Error(`TypeSafe returned HTTP ${response.status}: ${body.slice(0, 240)}`);
-    }
-    const raw = await response.json();
-    if (!raw || typeof raw !== "object" || !raw.answers || typeof raw.answers !== "object") {
-      throw new Error("TypeSafe response has no answers object");
-    }
-    return raw;
-  }
-}
-
-export class OpenRouterDecisionsProvider {
-  name = "openrouter:typesafe/jev-1.13";
-
-  constructor({
-    apiKey = process.env.OPENROUTER_API_KEY,
-    endpoint = process.env.OPENROUTER_DECISIONS_ENDPOINT ?? "https://openrouter.ai/api/alpha/decisions",
-    model = process.env.OPENROUTER_DECISIONS_MODEL ?? "typesafe/jev-1.13",
-    timeoutMs = 5_000,
-    fetchImpl = globalThis.fetch,
-    httpReferer = process.env.OPENROUTER_HTTP_REFERER,
-    appTitle = process.env.OPENROUTER_APP_TITLE,
-  } = {}) {
-    this.apiKey = apiKey;
-    this.endpoint = endpoint;
-    this.model = model;
-    this.timeoutMs = timeoutMs;
-    this.fetchImpl = fetchImpl;
-    this.httpReferer = httpReferer;
-  }
-  async decide({ state, candidates }) {
-    const criteria = Object.fromEntries(candidates.map((candidate) => [candidate.id, {
-      name: candidate.name,
-      kind: candidate.kind,
-      description: candidate.description,
-      risk: candidate.risk,
-    }]));
-    return this.evaluate({
-      state,
-      questions: {
-        tool: {
-          type: "choice",
-          instructions: "Which single capability should handle this request? Choose only from the supplied options.",
-          criteria,
-        },
-      },
-    });
-  }
-
-  async evaluate({ state, questions }) {
-    if (!this.apiKey) throw new Error("OPENROUTER_API_KEY is not configured");
-    if (typeof this.fetchImpl !== "function") throw new Error("fetch is unavailable");
-
-    const response = await this.fetchImpl(this.endpoint, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json",
-        ...(this.httpReferer ? { "HTTP-Referer": this.httpReferer } : {}),
-        ...(this.appTitle ? { "X-Title": this.appTitle } : {}),
-      },
-      body: JSON.stringify({ model: this.model, questions, state }),
-      signal: AbortSignal.timeout(this.timeoutMs),
-    }).catch((error) => {
-      if (error?.name === "TimeoutError") throw new Error(`OpenRouter Decisions request timed out after ${this.timeoutMs}ms`);
-      throw error;
-    });
-
-    if (!response.ok) {
-      const body = await response.text();
-      throw new Error(`OpenRouter Decisions returned HTTP ${response.status}: ${body.slice(0, 240)}`);
-    }
-    const raw = await response.json();
-    if (!raw || typeof raw !== "object" || !raw.answers || typeof raw.answers !== "object") {
-      throw new Error("OpenRouter Decisions response has no answers object");
-    }
-    return raw;
-  }
-}
+import { normalizeImageAssets } from "../images.mjs";
+
+function containsReference(value, reference) {
+  if (typeof value === "string") return value.includes(reference);
+  return value !== null && typeof value === "object"
+    && Object.values(value).some((child) => containsReference(child, reference));
+}
+
+function openRouterImageInput(state, questions, images) {
+  const parts = Object.fromEntries(Object.entries(images).map(([reference, image]) => [reference, {
+    type: "image_url",
+    image_url: { url: `data:image/${image.format === "png" ? "png" : "jpeg"};base64,${image.data_base64}` },
+  }]));
+  const pattern = new RegExp(Object.keys(parts).sort((a, b) => b.length - a.length).map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "g");
+  const used = new Set();
+  function expand(value) {
+    if (typeof value === "string") {
+      if (Object.hasOwn(parts, value)) {
+        used.add(value);
+        return parts[value];
+      }
+      const content = [];
+      let offset = 0;
+      for (const match of value.matchAll(pattern)) {
+        if (match.index > offset) content.push(value.slice(offset, match.index));
+        content.push(parts[match[0]]);
+        used.add(match[0]);
+        offset = match.index + match[0].length;
+      }
+      if (!content.length) return value;
+      if (offset < value.length) content.push(value.slice(offset));
+      return content;
+    }
+    if (Array.isArray(value)) return value.map(expand);
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, expand(child)]));
+    return value;
+  }
+  const input = {
+    state: expand(state),
+    questions: Object.fromEntries(Object.entries(questions).map(([key, question]) => [key, {
+      ...question,
+      instructions: expand(question.instructions),
+      ...(question.criteria !== undefined ? { criteria: expand(question.criteria) } : {}),
+    }])),
+  };
+  if (used.size !== Object.keys(parts).length) throw new Error("every image asset must be referenced in state, instructions, or criteria");
+  return input;
+}
+
+export class TypeSafeProvider {
+  name = "typesafe";
+  supportsImages = true;
+
+  constructor({ apiKey = process.env.TYPESAFE_API_KEY, endpoint = process.env.TYPESAFE_ENDPOINT ?? "https://api.typesafe.ai/v1/systemone", model = process.env.TYPESAFE_MODEL ?? "jev-1.14.0", timeoutMs = 2_000, fetchImpl = globalThis.fetch } = {}) {
+    this.apiKey = apiKey;
+    this.endpoint = endpoint;
+    this.model = model;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async decide({ state, candidates, assets }) {
+    const criteria = Object.fromEntries(candidates.map((candidate) => [candidate.id, {
+      name: candidate.name,
+      kind: candidate.kind,
+      description: candidate.description,
+      risk: candidate.risk,
+    }]));
+    return this.evaluate({
+      state,
+      assets,
+      questions: {
+        tool: {
+          type: "choice",
+          instructions: "Which single capability should handle this request? Choose only from the supplied options.",
+          criteria,
+        },
+      },
+    });
+  }
+
+  async evaluate({ state, questions, assets }) {
+    if (!this.apiKey) throw new Error("TYPESAFE_API_KEY is not configured");
+    if (typeof this.fetchImpl !== "function") throw new Error("fetch is unavailable");
+    const images = normalizeImageAssets(assets);
+    const hasImages = Object.keys(images).length > 0;
+    const hasBox = Object.values(questions).some((question) => question?.type === "box");
+    for (const reference of Object.keys(images)) {
+      if (!containsReference(state, reference)
+        && !Object.values(questions).some((question) => containsReference(question?.instructions, reference) || containsReference(question?.criteria, reference))) {
+        throw new Error("every image asset must be referenced in state, instructions, or criteria");
+      }
+    }
+    const body = JSON.stringify({ state, model: this.model, questions, ...(hasImages ? { assets: images } : {}) });
+    if (Buffer.byteLength(body) > 32 * 1024 * 1024) throw new Error("TypeSafe request exceeds the 32 MiB body limit");
+    const response = await this.fetchImpl(this.endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...(hasImages || hasBox ? { "TypeSafe-Danger-Zone-Images": "true" } : {}),
+      },
+      body,
+      signal: AbortSignal.timeout(this.timeoutMs),
+    }).catch((error) => {
+      if (error?.name === "TimeoutError") throw new Error(`TypeSafe request timed out after ${this.timeoutMs}ms`);
+      if (hasImages) throw new Error("TypeSafe image request failed");
+      throw error;
+    });
+
+    if (!response.ok) {
+      // Image requests must not copy an upstream echo of image data into receipts.
+      const detail = hasImages ? "" : `: ${(await response.text()).slice(0, 240)}`;
+      throw new Error(`TypeSafe returned HTTP ${response.status}${detail}`);
+    }
+    const raw = await response.json().catch((error) => {
+      if (hasImages) throw new Error("TypeSafe image response is not valid JSON");
+      throw error;
+    });
+    if (!raw || typeof raw !== "object" || !raw.answers || typeof raw.answers !== "object") {
+      throw new Error("TypeSafe response has no answers object");
+    }
+    return raw;
+  }
+}
+
+export class OpenRouterDecisionsProvider {
+  supportsImages = true;
+
+  constructor({
+    apiKey = process.env.OPENROUTER_API_KEY,
+    endpoint = process.env.OPENROUTER_DECISIONS_ENDPOINT ?? "https://openrouter.ai/api/alpha/decisions",
+    model = process.env.OPENROUTER_DECISIONS_MODEL ?? "typesafe/jev-1.14",
+    timeoutMs = 5_000,
+    fetchImpl = globalThis.fetch,
+    httpReferer = process.env.OPENROUTER_HTTP_REFERER,
+    appTitle = process.env.OPENROUTER_APP_TITLE,
+  } = {}) {
+    this.name = `openrouter:${model}`;
+    this.apiKey = apiKey;
+    this.endpoint = endpoint;
+    this.model = model;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+    this.httpReferer = httpReferer;
+    this.appTitle = appTitle;
+  }
+  async decide({ state, candidates, assets }) {
+    const criteria = Object.fromEntries(candidates.map((candidate) => [candidate.id, {
+      name: candidate.name,
+      kind: candidate.kind,
+      description: candidate.description,
+      risk: candidate.risk,
+    }]));
+    return this.evaluate({
+      state,
+      assets,
+      questions: {
+        tool: {
+          type: "choice",
+          instructions: "Which single capability should handle this request? Choose only from the supplied options.",
+          criteria,
+        },
+      },
+    });
+  }
+
+  async evaluate({ state, questions, assets }) {
+    if (!this.apiKey) throw new Error("OPENROUTER_API_KEY is not configured");
+    if (typeof this.fetchImpl !== "function") throw new Error("fetch is unavailable");
+    const images = normalizeImageAssets(assets);
+    const hasImages = Object.keys(images).length > 0;
+    const input = hasImages ? openRouterImageInput(state, questions, images) : { state, questions };
+    const body = JSON.stringify({ model: this.model, ...input });
+    if (Buffer.byteLength(body) > 32 * 1024 * 1024) throw new Error("OpenRouter Decisions request exceeds the 32 MiB body limit");
+
+    const response = await this.fetchImpl(this.endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...(this.httpReferer ? { "HTTP-Referer": this.httpReferer } : {}),
+        ...(this.appTitle ? { "X-Title": this.appTitle } : {}),
+      },
+      body,
+      signal: AbortSignal.timeout(this.timeoutMs),
+    }).catch((error) => {
+      if (error?.name === "TimeoutError") throw new Error(`OpenRouter Decisions request timed out after ${this.timeoutMs}ms`);
+      if (hasImages) throw new Error("OpenRouter Decisions image request failed");
+      throw error;
+    });
+
+    if (!response.ok) {
+      const detail = hasImages ? "" : `: ${(await response.text()).slice(0, 240)}`;
+      throw new Error(`OpenRouter Decisions returned HTTP ${response.status}${detail}`);
+    }
+    const raw = await response.json().catch((error) => {
+      if (hasImages) throw new Error("OpenRouter Decisions image response is not valid JSON");
+      throw error;
+    });
+    if (!raw || typeof raw !== "object" || !raw.answers || typeof raw.answers !== "object") {
+      throw new Error("OpenRouter Decisions response has no answers object");
+    }
+    return raw;
+  }
+}