jev-layer 0.1.0

package/src/context-filter.mjs

@@ -0,0 +1,56 @@
+import { byteLength, stableJson } from "./contract.mjs";
+import { filterContext, normalizeRelevanceMode } from "./relevance-filter.mjs";
+const SECRET_KEY = /(token|secret|password|passwd|api[_-]?key|authorization|cookie|credential|private[_-]?key|session)/i;
+const MAX_STRING = 2_000;
+const MAX_DEPTH = 4;
+
+export function sanitizeContext(value, depth = 0, key = "") {
+  if (SECRET_KEY.test(key)) return "[REDACTED]";
+  if (depth > MAX_DEPTH) return "[DEPTH_LIMIT]";
+  if (typeof value === "string") return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…` : value;
+  if (value === null || typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return value.slice(0, 32).map((item) => sanitizeContext(item, depth + 1, key));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).slice(0, 64).map(([childKey, childValue]) => [childKey, sanitizeContext(childValue, depth + 1, childKey)]));
+  }
+  return String(value);
+}
+
+export function projectState(request, capabilities, maxBytes = 6_000, options = {}) {
+  const configuredMode = options.mode ?? request.policy?.context_filter_mode ?? process.env.JEV_CONTEXT_FILTER;
+  const relevanceMode = normalizeRelevanceMode(configuredMode);
+  const relevance = filterContext(request.context, { mode: configuredMode, recent: options.recent });
+  const state = {
+    intent: request.intent.length > MAX_STRING ? `${request.intent.slice(0, MAX_STRING)}…` : request.intent,
+    context: sanitizeContext(relevance.context),
+    capabilities: capabilities.map((capability) => ({
+      id: capability.id,
+      kind: capability.kind,
+      name: capability.name,
+      description: capability.description,
+      risk: capability.risk,
+    })),
+  };
+  if (relevanceMode) state.context_filter = relevance.report;
+
+  let encoded = stableJson(state);
+  if (byteLength(encoded) <= maxBytes) return { state, context_bytes: byteLength(encoded), truncated: false };
+  if (relevanceMode) {
+    state.context_filter = { ...state.context_filter, over_budget: true };
+    return { state, context_bytes: byteLength(encoded), truncated: true };
+  }
+
+  state.context = {};
+  state.context_truncated = true;
+  encoded = stableJson(state);
+  if (byteLength(encoded) <= maxBytes) return { state, context_bytes: byteLength(encoded), truncated: true };
+
+  state.capabilities = state.capabilities.map(({ id, kind, name, risk }) => ({ id, kind, name, risk }));
+  encoded = stableJson(state);
+  if (byteLength(encoded) <= maxBytes) return { state, context_bytes: byteLength(encoded), truncated: true };
+
+  state.capabilities = state.capabilities.slice(0, 32);
+  state.capabilities_truncated = true;
+  state.intent = state.intent.slice(0, Math.max(128, maxBytes - byteLength(stableJson(state))));
+  return { state, context_bytes: byteLength(stableJson(state)), truncated: true };
+}

package/src/contract.mjs

@@ -0,0 +1,72 @@
+import { createHash, randomUUID } from "node:crypto";
+
+export const RISK_ORDER = Object.freeze({ low: 0, medium: 1, high: 2, critical: 3 });
+export const CAPABILITY_KINDS = new Set(["skill", "tool", "mcp", "cli", "dsh", "subagent", "model"]);
+
+export function stableJson(value) {
+  return JSON.stringify(sortJson(value));
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+  }
+  return value;
+}
+
+export function sha256(value) {
+  return `sha256:${createHash("sha256").update(typeof value === "string" ? value : stableJson(value)).digest("hex")}`;
+}
+
+export function byteLength(value) {
+  return Buffer.byteLength(typeof value === "string" ? value : stableJson(value), "utf8");
+}
+
+export function normalizeRequest(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("route request must be an object");
+  }
+  const intent = typeof input.intent === "string" ? input.intent : input.request;
+  if (typeof intent !== "string" || intent.trim() === "") {
+    throw new TypeError("route request requires a non-empty intent");
+  }
+  if (!Array.isArray(input.capabilities)) {
+    throw new TypeError("route request requires capabilities[]");
+  }
+  return {
+    schema_version: input.schema_version ?? 1,
+    harness: typeof input.harness === "string" ? input.harness : "unknown",
+    intent: intent.trim(),
+    context: input.context && typeof input.context === "object" ? input.context : {},
+    actor: typeof input.actor === "string" ? input.actor : undefined,
+    actor_permissions: Array.isArray(input.actor_permissions) ? input.actor_permissions.filter((value) => typeof value === "string") : undefined,
+    capabilities: input.capabilities,
+    policy: input.policy && typeof input.policy === "object" ? input.policy : {},
+  };
+}
+
+export function decisionEnvelope({ status, selected, reason, provider, latencyMs, candidateCount, contextBytes, candidates = [], probabilities = {}, confidence = null, rawJev = null, fallback = null, requestId = randomUUID(), correlationId = requestId, costUsd = rawJev?.usage?.cost ?? null }) {
+  return {
+    schema_version: 1,
+    correlation_id: correlationId,
+    status,
+    selected: selected ?? null,
+    confidence,
+    probabilities,
+    reason,
+    candidates,
+    fallback,
+    execution: { enabled: false, status: "not_started" },
+    raw_jev: rawJev,
+    receipt: {
+      correlation_id: correlationId,
+      request_id: requestId,
+      provider,
+      latency_ms: latencyMs,
+      cost_usd: costUsd,
+      candidate_count: candidateCount,
+      context_bytes: contextBytes,
+    },
+  };
+}

package/src/discovery.mjs

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+
+const DISCOVERY_SOURCES = Object.freeze([
+  ["skills", "skill"],
+  ["mcp", "mcp"],
+  ["cli", "cli"],
+  ["dsh", "dsh"],
+  ["tools", "tool"],
+  ["subagents", "subagent"],
+  ["models", "model"],
+]);
+
+export function discoverCapabilities(input = {}) {
+  const entries = [];
+  for (const [field, kind] of DISCOVERY_SOURCES) {
+    const values = Array.isArray(input[field]) ? input[field] : [];
+    for (const value of values) entries.push(normalizeDiscovered(value, kind, input.source ?? `${kind}-discovery`));
+  }
+  const manifests = Array.isArray(input.manifests) ? input.manifests : [];
+  for (const manifest of manifests) {
+    const values = Array.isArray(manifest?.capabilities) ? manifest.capabilities : [manifest];
+    for (const value of values) {
+      const kind = value?.kind ?? value?.type ?? manifest?.kind ?? "tool";
+      entries.push(normalizeDiscovered(value, kind, value?.source ?? manifest?.source ?? "manifest"));
+    }
+  }
+  const seen = new Set();
+  return entries.filter((entry) => {
+    if (seen.has(entry.id)) return false;
+    seen.add(entry.id);
+    return true;
+  });
+}
+
+export async function loadCapabilityManifest(path, options = {}) {
+  const parsed = JSON.parse(await readFile(path, "utf8"));
+  const manifest = Array.isArray(parsed) ? { capabilities: parsed } : parsed;
+  return discoverCapabilities({ manifests: [{ ...manifest, source: options.source ?? manifest.source ?? "manifest" }] });
+}
+
+function normalizeDiscovered(value, kind, source) {
+  if (!value || typeof value !== "object") throw new TypeError("discovered capability must be an object");
+  const id = stringValue(value.id ?? value.name, `${kind}-capability`);
+  const name = stringValue(value.name ?? value.id, id);
+  const description = stringValue(value.description ?? value.summary, `${kind} capability ${name}`);
+  const metadata = {
+    ...(value.metadata && typeof value.metadata === "object" ? value.metadata : {}),
+    [kind]: stringValue(value.target ?? value.command ?? value.name, name),
+  };
+  return {
+    ...value,
+    id,
+    kind,
+    name,
+    description,
+    source: stringValue(value.source, source),
+    verified: value.verified === true,
+    metadata,
+    available: value.available !== false && value.availability?.available !== false,
+  };
+}
+
+function stringValue(value, fallback) {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}

package/src/mcp-server.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline";
+import { appendExecutionReceipt, appendRoutingCase, buildExecutionReceipt, replayCasePath } from "./receipts.mjs";
+import { configuredProvider, configuredReplayPath, loadConfig } from "./config.mjs";
+import { decideBrowserStep } from "./browser.mjs";
+import { superviseWork } from "./supervision.mjs";
+import { routeRequest } from "./route.mjs";
+
+const { config } = await loadConfig();
+const serverInfo = { name: "jev-layer", version: "0.1.0" };
+const CASES_PATH = replayCasePath(configuredReplayPath(config));
+const pendingDecisions = new Map();
+const tools = [
+  {
+    name: "jev_route",
+    description: "Return one bounded Jev capability decision. The host executes the selected capability; this tool never executes it.",
+    inputSchema: {
+      type: "object",
+      required: ["intent", "capabilities"],
+      properties: {
+        intent: { type: "string" },
+        harness: { type: "string" },
+        context: { type: "object" },
+        actor_permissions: { type: "array", items: { type: "string" } },
+        capabilities: { type: "array", items: { type: "object" } },
+        policy: { type: "object" },
+        provider: { type: "string", enum: ["demo", "typesafe", "openrouter"] },
+        engine: { type: "string", enum: ["native", "jevrouter"] },
+      },
+    },
+  },
+  {
+    name: "jev_browser_step",
+    description: "Choose one bounded browser action from the host's visible observation. The host executes it or hands control back; this tool never drives a browser.",
+    inputSchema: {
+      type: "object",
+      required: ["goal", "observation"],
+      properties: {
+        goal: { type: "string" },
+        harness: { type: "string" },
+        start_url: { type: ["string", "null"] },
+        observation: { type: "object" },
+        policy: { type: "object" },
+        provider: { type: "string", enum: ["demo", "typesafe", "openrouter"] },
+        enabled: { type: "boolean" },
+      },
+    },
+  },
+  {
+    name: "jev_supervise",
+    description: "Judge bounded work-state dimensions; deterministic host policy returns continue, verify, retry, finish, or escalate.",
+    inputSchema: {
+      type: "object",
+      required: ["job", "observation"],
+      properties: {
+        job: { type: "object" },
+        observation: { type: "object" },
+        evidence: { type: "object" },
+        harness: { type: "string" },
+        actor_permissions: { type: "array", items: { type: "string" } },
+        policy: { type: "object" },
+        attempts: { type: "integer", minimum: 0 },
+        provider: { type: "string", enum: ["demo", "typesafe", "openrouter"] },
+        enabled: { type: "boolean" },
+      },
+    },
+  },
+  {
+    name: "jev_record_execution",
+    description: "Attach a host execution result to a Jev decision and persist the unified execution receipt.",
+    inputSchema: {
+      type: "object",
+      required: ["correlation_id", "status"],
+      properties: {
+        correlation_id: { type: "string" },
+        harness: { type: "string" },
+        capability_id: { type: "string" },
+        status: { type: "string", enum: ["completed", "failed", "not_started"] },
+        result: {},
+        error: {},
+        browser: { type: "object" },
+        exit_status: { type: ["integer", "null"] },
+        duration_ms: { type: ["number", "null"] },
+        started_at: { type: ["string", "null"] },
+        completed_at: { type: ["string", "null"] },
+      },
+    },
+  },
+];
+
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+for await (const line of input) {
+  if (!line.trim()) continue;
+  let message;
+  try {
+    message = JSON.parse(line);
+    const response = await handle(message);
+    if (response) process.stdout.write(`${JSON.stringify(response)}\n`);
+  } catch (error) {
+    const id = message?.id ?? null;
+    process.stdout.write(`${JSON.stringify(jsonRpcError(id, -32603, error instanceof Error ? error.message : String(error)))}\n`);
+  }
+}
+
+async function handle(message) {
+  const { id, method, params = {} } = message;
+  if (method === "initialize") {
+    return { jsonrpc: "2.0", id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo } };
+  }
+  if (method === "notifications/initialized") return null;
+  if (method === "tools/list") return { jsonrpc: "2.0", id, result: { tools } };
+  if (method !== "tools/call") return jsonRpcError(id, -32601, `method not found: ${method}`);
+
+  const args = params.arguments && typeof params.arguments === "object" ? params.arguments : {};
+  if (params.name === "jev_route") return route(args, id);
+  if (params.name === "jev_browser_step") return browserStep(args, id);
+  if (params.name === "jev_supervise") return supervise(args, id);
+  if (params.name === "jev_record_execution") return recordExecution(args, id);
+  return jsonRpcError(id, -32602, `unknown tool: ${params.name}`);
+}
+
+async function route(args, id) {
+  const { provider: requestedProvider, engine = "native", ...request } = args;
+  const provider = configuredProvider(config, requestedProvider);
+  const decision = await routeRequest(request, {
+    provider,
+    engine,
+    contextFilterMode: request.policy?.context_filter_mode ?? config.features?.context_filter,
+  });
+  return persistDecision(request, decision, id);
+}
+
+async function browserStep(args, id) {
+  const { provider: requestedProvider, enabled, ...input } = args;
+  const routed = await decideBrowserStep(input, {
+    enabled: enabled ?? config.features?.browser_fast_path,
+    provider: configuredProvider(config, requestedProvider),
+  });
+  routed.decision.browser_action = routed.action
+    ? {
+        id: routed.action.id,
+        operation: routed.action.operation,
+        target_id: routed.action.target_id ?? null,
+        option_id: routed.action.option_id ?? null,
+        consequential: routed.action.consequential,
+      }
+    : null;
+  return persistDecision(routed.request, routed.decision, id);
+}
+
+async function supervise(args, id) {
+  const { provider: requestedProvider, enabled, ...input } = args;
+  const result = await superviseWork({
+    ...input,
+    enabled: enabled ?? config.features?.supervision,
+    provider: configuredProvider(config, requestedProvider),
+    receiptPath: CASES_PATH,
+  });
+  return toolResult(id, result, false);
+}
+
+async function persistDecision(request, decision, id) {
+  pendingDecisions.set(decision.correlation_id, { request, decision });
+  try {
+    await appendRoutingCase({ path: CASES_PATH, request, decision });
+    decision.receipt = { ...decision.receipt, replay_case_id: decision.correlation_id, replay_persisted: true };
+  } catch (error) {
+    decision.receipt = {
+      ...decision.receipt,
+      replay_persisted: false,
+      replay_error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  return toolResult(id, decision, decision.status === "error");
+}
+
+async function recordExecution(args, id) {
+  const correlationId = typeof args.correlation_id === "string" ? args.correlation_id : null;
+  const pending = correlationId ? pendingDecisions.get(correlationId) : null;
+  if (!pending) return jsonRpcError(id, -32004, `unknown Jev correlation_id: ${correlationId ?? "missing"}`);
+  const { request, decision } = pending;
+  let record;
+  try {
+    ({ record } = await appendExecutionReceipt({ path: CASES_PATH, request, decision, host: args }));
+  } catch (error) {
+    record = buildExecutionReceipt({ request, decision, host: args });
+    record.persistence = {
+      persisted: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  pendingDecisions.delete(correlationId);
+  return toolResult(id, record, false);
+}
+
+function toolResult(id, value, isError) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [{ type: "text", text: JSON.stringify(value) }],
+      structuredContent: value,
+      isError,
+    },
+  };
+}
+
+function jsonRpcError(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}

package/src/providers/demo.mjs

@@ -0,0 +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) ?? []);
+}

package/src/providers/typesafe.mjs

@@ -0,0 +1,126 @@
+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;
+  }
+}