@elyracode/jev-tools 0.9.39 → 0.9.40

package/README.md

@@ -14,8 +14,15 @@ elyra install npm:@elyracode/jev-tools
 
 ## Requirements
 
-An OpenRouter API key. Either log in with `/login` and pick OpenRouter, or set `OPENROUTER_API_KEY`.
-The extension reuses whatever key Elyra already has for the `openrouter` provider.
+One of two API keys:
+
+- **TypeSafe direct** (preferred): a key from [typesafe.ai](https://typesafe.ai). Set `TYPESAFE_API_KEY`.
+  Requests go to `https://api.typesafe.ai/v1/systemone` with model `jev-latest`.
+- **OpenRouter**: log in with `/login` and pick OpenRouter, or set `OPENROUTER_API_KEY`. Requests go to
+  OpenRouter's alpha decisions endpoint with model `~typesafe/jev-latest`.
+
+When both are present, TypeSafe direct is used. Force one with `JEV_BACKEND=typesafe|openrouter`.
+The request and response shape is identical on both; only endpoint, model slug, and billing differ.
 
 ## Tools
 
@@ -25,7 +32,7 @@ The extension reuses whatever key Elyra already has for the `openrouter` provide
 
 ## Commands
 
-- `/jev` -- show model, endpoint, key status, and bash gate state
+- `/jev` -- show active backend, key status, and bash gate state
 - `/jev gate on|off` -- toggle the bash gate for the current session
 
 ## Bash gate (opt-in)
@@ -85,15 +92,19 @@ Jev reads criteria literally and does not infer intent beyond what is stated.
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| `OPENROUTER_API_KEY` | -- | API key, if not stored via `/login` |
-| `JEV_MODEL` | `~typesafe/jev-latest` | Model slug sent to the endpoint |
-| `JEV_BASE_URL` | `https://openrouter.ai/api/alpha/decisions` | Override if OpenRouter moves the endpoint out of alpha |
+| `TYPESAFE_API_KEY` | -- | TypeSafe direct API key |
+| `OPENROUTER_API_KEY` | -- | OpenRouter API key, if not stored via `/login` |
+| `JEV_BACKEND` | auto | Force `typesafe` or `openrouter` instead of picking by available key |
+| `JEV_MODEL` | `jev-latest` / `~typesafe/jev-latest` | Override the model slug for the chosen backend |
+| `JEV_BASE_URL` | per backend | Override the endpoint URL (proxies, or if OpenRouter moves out of alpha) |
 | `JEV_BASH_GATE` | off | Set to `1` to enable the bash gate at startup |
 | `JEV_BASH_GATE_THRESHOLD` | `0.7` | Probability (0-1) at or above which the gate intervenes |
 
 ## Notes
 
-- The decisions endpoint is an OpenRouter alpha API. The request contract here is derived from public
-  community clients, not from an official specification, and may change.
-- Retries with backoff on 429/5xx, up to three attempts. Requests time out after 60 seconds.
+- The request contract follows the [TypeSafe API reference](https://docs.typesafe.ai/api). OpenRouter's
+  decisions endpoint is an alpha API mirroring the same shape and may change.
+- Retries with backoff on 429/529/5xx, up to three attempts. Requests time out after 60 seconds.
+- Question design guidance: see the [primitives docs](https://docs.typesafe.ai/primitives). A Noul near 0.5
+  means yes and no are equally likely, not "medium"; use a Score for degree.
 - Unofficial community integration. Not affiliated with TypeSafe or OpenRouter.

package/extensions/index.ts

@@ -1,14 +1,50 @@
 import type { ExtensionAPI, ExtensionContext } from "@elyracode/coding-agent";
 import { type Static, Type } from "typebox";
 
-// TypeSafe Jev is a decision model, not a chat model. It is reached through
-// OpenRouter's decisions endpoint (alpha), which has its own request shape:
-// a `state` to judge plus a map of typed `questions`. It never generates text.
-const DEFAULT_BASE_URL = "https://openrouter.ai/api/alpha/decisions";
-const DEFAULT_MODEL = "~typesafe/jev-latest";
+// TypeSafe Jev is a decision model, not a chat model. It takes a `state` to
+// judge plus a map of typed `questions` and returns probabilities; it never
+// generates text. The same request shape is served by two backends:
+//   - TypeSafe direct:  POST https://api.typesafe.ai/v1/systemone  (model "jev-latest")
+//   - OpenRouter alpha: POST https://openrouter.ai/api/alpha/decisions (model "~typesafe/jev-latest")
+// Direct is preferred when a TypeSafe key is available; OpenRouter is the fallback.
+type BackendId = "typesafe" | "openrouter";
+
+interface Backend {
+	id: BackendId;
+	label: string;
+	baseUrl: string;
+	model: string;
+	apiKey: string;
+}
+
+interface BackendSpec {
+	id: BackendId;
+	label: string;
+	baseUrl: string;
+	model: string;
+	envKey: string;
+}
+
+const BACKENDS: Record<BackendId, BackendSpec> = {
+	typesafe: {
+		id: "typesafe",
+		label: "TypeSafe (direct)",
+		baseUrl: "https://api.typesafe.ai/v1/systemone",
+		model: "jev-latest",
+		envKey: "TYPESAFE_API_KEY",
+	},
+	openrouter: {
+		id: "openrouter",
+		label: "OpenRouter",
+		baseUrl: "https://openrouter.ai/api/alpha/decisions",
+		model: "~typesafe/jev-latest",
+		envKey: "OPENROUTER_API_KEY",
+	},
+};
+
+const ENV_BACKEND = "JEV_BACKEND";
 const ENV_BASE_URL = "JEV_BASE_URL";
 const ENV_MODEL = "JEV_MODEL";
-const PROVIDER = "openrouter";
 const MAX_ATTEMPTS = 3;
 const REQUEST_TIMEOUT_MS = 60_000;
 
@@ -153,11 +189,11 @@ export default function (elyra: ExtensionAPI): void {
 		execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
 			validateQuestions(params.questions);
 
-			const apiKey = await requireApiKey(ctx);
+			const backend = await requireBackend(ctx);
 			const state = parseState(params.state);
 			const questions = toApiQuestions(params.questions);
 			const warning = sizeWarning(state, questions);
-			const response = await requestDecision(apiKey, state, questions, signal);
+			const response = await requestDecision(backend, state, questions, signal);
 			const text = formatResponse(params.questions, response);
 
 			return {
@@ -188,16 +224,16 @@ export default function (elyra: ExtensionAPI): void {
 		const command = event.input.command;
 		if (typeof command !== "string" || !command.trim()) return undefined;
 
-		const apiKey = await ctx.modelRegistry.getApiKeyForProvider(PROVIDER);
-		if (!apiKey) {
-			ctx.ui.notify("Jev bash gate: no OpenRouter API key, skipping check", "warning");
+		const backend = await resolveBackend(ctx);
+		if (!backend) {
+			ctx.ui.notify("Jev bash gate: no TypeSafe or OpenRouter API key, skipping check", "warning");
 			return undefined;
 		}
 
 		let probability: number;
 		try {
 			const response = await requestDecision(
-				apiKey,
+				backend,
 				{ command, cwd: ctx.cwd },
 				{ [GATE_QUESTION_NAME]: GATE_QUESTION },
 				ctx.signal,
@@ -246,14 +282,17 @@ export default function (elyra: ExtensionAPI): void {
 				return;
 			}
 
-			const apiKey = await ctx.modelRegistry.getApiKeyForProvider(PROVIDER);
+			const typesafeKey = await resolveApiKey(ctx, "typesafe");
+			const openrouterKey = await resolveApiKey(ctx, "openrouter");
+			const backend = await resolveBackend(ctx);
 			const lines = [
-				`Model: ${process.env[ENV_MODEL] || DEFAULT_MODEL}`,
-				`Endpoint: ${process.env[ENV_BASE_URL] || DEFAULT_BASE_URL}`,
-				`OpenRouter key: ${apiKey ? "configured" : "missing (run /login or set OPENROUTER_API_KEY)"}`,
+				`Active backend: ${backend ? `${backend.label} (${backend.model} at ${backend.baseUrl})` : "none"}`,
+				`TypeSafe key: ${typesafeKey ? "configured" : "missing (set TYPESAFE_API_KEY)"}`,
+				`OpenRouter key: ${openrouterKey ? "configured" : "missing (run /login or set OPENROUTER_API_KEY)"}`,
+				`Backend override: ${process.env[ENV_BACKEND] || "auto (TypeSafe if keyed, else OpenRouter)"}`,
 				`Bash gate: ${gateEnabled ? "on" : "off"} (threshold ${gateThreshold}, toggle with /jev gate on|off)`,
 			];
-			ctx.ui.notify(lines.join("\n"), apiKey ? "info" : "warning");
+			ctx.ui.notify(lines.join("\n"), backend ? "info" : "warning");
 		},
 	});
 }
@@ -272,12 +311,56 @@ function parseThreshold(value: string | undefined): number {
 	return parsed;
 }
 
-async function requireApiKey(ctx: ExtensionContext): Promise<string> {
-	const apiKey = await ctx.modelRegistry.getApiKeyForProvider(PROVIDER);
-	if (!apiKey) {
-		throw new Error("No OpenRouter API key found. Run /login and pick OpenRouter, or set OPENROUTER_API_KEY.");
+// ── Backend resolution ──
+
+function parseBackendId(value: string | undefined): BackendId | undefined {
+	const normalized = value?.trim().toLowerCase();
+	return normalized === "typesafe" || normalized === "openrouter" ? normalized : undefined;
+}
+
+/** Env var first, then Elyra's auth storage (/login or auth.json entry under the backend id). */
+async function resolveApiKey(ctx: ExtensionContext, id: BackendId): Promise<string | undefined> {
+	const fromEnv = process.env[BACKENDS[id].envKey]?.trim();
+	if (fromEnv) return fromEnv;
+	return ctx.modelRegistry.getApiKeyForProvider(id);
+}
+
+/**
+ * Pick the backend. JEV_BACKEND forces one; otherwise TypeSafe direct is used when
+ * a key exists, falling back to OpenRouter. JEV_BASE_URL / JEV_MODEL override the
+ * chosen backend's endpoint and model slug.
+ */
+async function resolveBackend(ctx: ExtensionContext): Promise<Backend | undefined> {
+	const forced = parseBackendId(process.env[ENV_BACKEND]);
+	const order: BackendId[] = forced ? [forced] : ["typesafe", "openrouter"];
+
+	for (const id of order) {
+		const apiKey = await resolveApiKey(ctx, id);
+		if (!apiKey) continue;
+		const spec = BACKENDS[id];
+		return {
+			id,
+			label: spec.label,
+			apiKey,
+			baseUrl: process.env[ENV_BASE_URL] || spec.baseUrl,
+			model: process.env[ENV_MODEL] || spec.model,
+		};
+	}
+	return undefined;
+}
+
+async function requireBackend(ctx: ExtensionContext): Promise<Backend> {
+	const backend = await resolveBackend(ctx);
+	if (!backend) {
+		const forced = parseBackendId(process.env[ENV_BACKEND]);
+		if (forced) {
+			throw new Error(`JEV_BACKEND=${forced} but no ${BACKENDS[forced].envKey} is set.`);
+		}
+		throw new Error(
+			"No Jev API key found. Set TYPESAFE_API_KEY for direct access, or run /login and pick OpenRouter (or set OPENROUTER_API_KEY).",
+		);
 	}
-	return apiKey;
+	return backend;
 }
 
 // ── Validation ──
@@ -366,27 +449,23 @@ function sizeWarning(state: unknown, questions: Record<string, ApiQuestion>): st
 
 // ── HTTP ──
 
-function requestDecision(
-	apiKey: string,
+async function requestDecision(
+	backend: Backend,
 	state: unknown,
 	questions: Record<string, ApiQuestion>,
 	signal: AbortSignal | undefined,
 ): Promise<DecisionsResponse> {
-	return callDecisions(apiKey, { model: process.env[ENV_MODEL] || DEFAULT_MODEL, state, questions }, signal);
-}
-
-async function callDecisions(
-	apiKey: string,
-	payload: Record<string, unknown>,
-	signal: AbortSignal | undefined,
-): Promise<DecisionsResponse> {
-	const url = process.env[ENV_BASE_URL] || DEFAULT_BASE_URL;
-	const headers = {
-		Authorization: `Bearer ${apiKey}`,
+	const payload = { model: backend.model, state, questions };
+	const url = backend.baseUrl;
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${backend.apiKey}`,
 		"Content-Type": "application/json",
-		"X-Title": "elyra-jev-tools",
-		"HTTP-Referer": "https://github.com/kwhorne/elyra",
 	};
+	if (backend.id === "openrouter") {
+		// OpenRouter attribution headers; not part of the TypeSafe API.
+		headers["X-Title"] = "elyra-jev-tools";
+		headers["HTTP-Referer"] = "https://github.com/kwhorne/elyra";
+	}
 
 	for (let attempt = 1; ; attempt++) {
 		signal?.throwIfAborted();
@@ -485,7 +564,7 @@ function formatResponse(questions: QuestionType[], response: DecisionsResponse):
 	if (usage) {
 		const tokens = (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0);
 		const cost = usage.cost !== undefined ? ` · $${usage.cost.toFixed(6)}` : "";
-		lines.push("", `[${response.model ?? DEFAULT_MODEL} · ${tokens} tok${cost}]`);
+		lines.push("", `[${response.model ?? "jev"} · ${tokens} tok${cost}]`);
 	}
 	return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyracode/jev-tools",
-  "version": "0.9.39",
+  "version": "0.9.40",
   "description": "Elyra extension for TypeSafe Jev decisions via OpenRouter -- calibrated yes/no, choice, and score judgements",
   "type": "module",
   "keywords": [