@evoclock/pi-agentic-driver 0.9.2 → 0.9.3

package/janus/tests/single_flight.test.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Unit tests: single-flight per evalInputDigest (M9) and the global
+// concurrency cap with busy rejection.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SingleFlight } from "../janus/single_flight.js";
+import { JanusError } from "../janus/errors.js";
+
+test("identical digests coalesce onto one task", async () => {
+  const sf = new SingleFlight(4);
+  let runs = 0;
+  const task = () =>
+    sf.run("digest-a", async () => {
+      runs += 1;
+      await new Promise((r) => setTimeout(r, 50));
+      return "result";
+    });
+
+  const [a, b, c] = await Promise.all([task(), task(), task()]);
+  assert.equal(runs, 1);
+  assert.equal(a, "result");
+  assert.equal(b, "result");
+  assert.equal(c, "result");
+});
+
+test("distinct digests run as separate tasks", async () => {
+  const sf = new SingleFlight(4);
+  let runs = 0;
+  const make = (digest: string) =>
+    sf.run(digest, async () => {
+      runs += 1;
+      return digest;
+    });
+  await Promise.all([make("d1"), make("d2"), make("d3")]);
+  assert.equal(runs, 3);
+});
+
+test("global cap rejects distinct digests with busy", async () => {
+  const sf = new SingleFlight(2);
+  const release: (() => void)[] = [];
+  const make = (digest: string) =>
+    sf.run(digest, () => new Promise<string>((resolvePromise) => release.push(() => resolvePromise(digest))));
+
+  void make("d1");
+  void make("d2");
+  assert.throws(() => make("d3"), (error: unknown) => {
+    return error instanceof JanusError && error.code === "busy";
+  });
+  for (const r of release) r();
+});
+
+test("digests are released after completion", async () => {
+  const sf = new SingleFlight(1);
+  await sf.run("d1", async () => "x");
+  // Cap of 1 must allow the next request after the first completes.
+  assert.equal(await sf.run("d2", async () => "y"), "y");
+  assert.equal(await sf.run("d1", async () => "z"), "z");
+});
+
+test("failed flights release their digest", async () => {
+  const sf = new SingleFlight(1);
+  await assert.rejects(
+    sf.run("d1", async () => {
+      throw new Error("boom");
+    }),
+    /boom/,
+  );
+  assert.equal(await sf.run("d1", async () => "recovered"), "recovered");
+});
+
+test("coalesced waiters share a failed flight's rejection", async () => {
+  const sf = new SingleFlight(4);
+  const task = () =>
+    sf.run("digest-fail", async () => {
+      await new Promise((r) => setTimeout(r, 20));
+      throw new Error("gateway down");
+    });
+  const results = await Promise.allSettled([task(), task()]);
+  assert.equal(results[0]?.status, "rejected");
+  assert.equal(results[1]?.status, "rejected");
+});

package/janus/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["janus/**/*.ts", "tests/**/*.ts"]
+}

package/janus/user.janus.plist

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  janus launchd template — a STARTING POINT, not a finished service file.
+  Everything marked ADJUST below is user-specific by design; the template
+  ships with placeholders because the label, paths, and log locations belong
+  to the user's machine, not to this repository.
+
+  Install:
+    1. Copy the template somewhere out of the repo:
+         cp janus/user.janus.plist ~/Library/LaunchAgents/user.janus.plist
+    2. ADJUST the values marked below (Label, WorkingDirectory, log paths).
+    3. Load it:
+         launchctl load ~/Library/LaunchAgents/user.janus.plist
+
+  The service binds 127.0.0.1 only and reads the gateway key from the
+  Keychain at runtime; no environment variables are required.
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <!-- ADJUST: any label you like; the file name should match it. -->
+    <string>user.janus</string>
+    <key>ProgramArguments</key>
+    <array>
+        <!-- ADJUST if your tooling lives elsewhere (e.g. /usr/local/bin/npx). -->
+        <string>/opt/homebrew/bin/npx</string>
+        <string>tsx</string>
+        <string>janus/server.ts</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <!-- ADJUST: the janus/ directory of your checkout. -->
+    <string>/path/to/pi-agentic-driver/janus</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <!-- ADJUST: where stdout goes. -->
+    <string>/tmp/janus.stdout.log</string>
+    <key>StandardErrorPath</key>
+    <!-- ADJUST: where stderr goes. -->
+    <string>/tmp/janus.stderr.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <!-- ADJUST if your npx lives on a different PATH. -->
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+</dict>
+</plist>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -80,7 +80,8 @@
     "scripts/enforcement/router_replacement_pi.js",
     "scripts/enforcement/router_runtime_pi.js",
     ".agentic-driver/router.defaults.json",
-    "skills/pulse/SKILL.md"
+    "skills/pulse/SKILL.md",
+    "janus"
   ],
   "pi": {
     "extensions": [

package/scripts/enforcement/router_schemas_pi.js

@@ -28,9 +28,16 @@ export const QUOTA_OBSERVATION_SCHEMA = "agentic-driver.quota-observation.v1";
 // ---------------------------------------------------------------------------
 
 export const SEAT_KINDS = Object.freeze(["local", "hosted-api", "subscription"]);
-export const PROVIDERS = Object.freeze([
-  "llama-server", "merge-gateway", "vercel-ai-gateway", "anthropic", "openai",
+// Built-in provider registry: the most common API routers plus the local
+// serving adapter. Users extend this list through the config's
+// `providers` section — the registry is OPEN by configuration, closed by
+// default. Nothing in the code branches on specific provider names.
+export const BUILTIN_PROVIDERS = Object.freeze([
+  "openrouter", "vercel-ai-gateway", "opencode", "fireworks-ai", "baseten",
+  "particle-ai", "cerebras", "together-ai", "merge-gateway", "anthropic",
+  "openai", "llama-server",
 ]);
+export const PROVIDERS = BUILTIN_PROVIDERS;
 export const CAPABILITIES = Object.freeze([
   "implement", "review", "final-verification", "design", "research",
 ]);
@@ -73,7 +80,7 @@ function isPosInt(value) {
 // §2 Seat record: agentic-driver.seat.v1
 // ---------------------------------------------------------------------------
 
-export function wellFormedSeat(seat, { endpoints = null } = {}) {
+export function wellFormedSeat(seat, { endpoints = null, providerRegistry = BUILTIN_PROVIDERS } = {}) {
   if (!isPlainObject(seat) || !exactKeys(seat, [
     "schema", "seatId", "kind", "provider", "accountId", "endpointRef",
     "model", "capabilities", "containmentTier", "maxConcurrency",
@@ -88,8 +95,8 @@ export function wellFormedSeat(seat, { endpoints = null } = {}) {
   if (!SEAT_KINDS.includes(seat.kind)) {
     return { ok: false, reason: `seat kind "${seat.kind}" is not one of ${SEAT_KINDS.join(", ")}` };
   }
-  if (!PROVIDERS.includes(seat.provider)) {
-    return { ok: false, reason: `seat provider "${seat.provider}" is not in the closed provider registry` };
+  if (!providerRegistry.includes(seat.provider)) {
+    return { ok: false, reason: `seat provider "${seat.provider}" is not in the provider registry (built-ins plus configured extensions)` };
   }
   // accountId is REQUIRED iff kind is subscription (§2).
   if (seat.kind === "subscription") {
@@ -191,11 +198,24 @@ export const ELIGIBILITY_RULES = Object.freeze([
 
 export function validateRouterConfig(config) {
   if (!isPlainObject(config)) return { ok: false, errors: ["router config must be an object"] };
-  if (!exactKeys(config, [
+  // exactKeys closed, with one governed extension point: the optional
+  // "providers" section (user-added provider ids). Built-ins always apply;
+  // extensions add to them, never remove.
+  const requiredKeys = [
     "schema", "revision", "endpoints", "seats", "models", "collectors",
     "eligibility", "preferences", "ranking", "localHealth", "secrets",
-  ])) {
-    return { ok: false, errors: ["router config has unknown or missing fields (exactKeys closed)"] };
+  ];
+  const optionalKeys = ["providers"];
+  const actualKeys = Object.keys(config).sort();
+  const allowed = [...requiredKeys, ...optionalKeys].sort();
+  const missing = requiredKeys.filter((key) => !actualKeys.includes(key));
+  const unknown = actualKeys.filter((key) => !allowed.includes(key));
+  if (missing.length || unknown.length) {
+    return { ok: false, errors: [
+      `router config has unknown or missing fields (exactKeys closed)` +
+      (missing.length ? `; missing: ${missing.join(", ")}` : "") +
+      (unknown.length ? `; unknown: ${unknown.join(", ")}` : ""),
+    ] };
   }
   const errors = [];
   if (config.schema !== ROUTER_CONFIG_SCHEMA) {
@@ -204,6 +224,36 @@ export function validateRouterConfig(config) {
   if (!isPosInt(config.revision)) {
     errors.push("config revision must be a positive integer");
   }
+  // providers{}: optional user extension of the registry. Each entry is a
+  // slug; entries add to the built-ins, never shadow or remove them.
+  let providerRegistry = BUILTIN_PROVIDERS;
+  if (config.providers !== undefined) {
+    if (!isPlainObject(config.providers) || Object.keys(config.providers).length === 0) {
+      errors.push("providers must be a non-empty object keyed by provider slug when present");
+    } else {
+      const extended = [];
+      for (const [name, entry] of Object.entries(config.providers)) {
+        if (!SLUG_RE.test(name) || name.length > 64) {
+          errors.push(`provider "${name}" must be a slug (max 64 chars)`);
+          continue;
+        }
+        if (BUILTIN_PROVIDERS.includes(name)) {
+          errors.push(`provider "${name}" shadows a built-in provider`);
+          continue;
+        }
+        // Entry shape is closed: {auth} — how the provider authenticates.
+        // "keychain" (default posture) is the only supported auth kind at
+        // launch; the entry exists so provider addition needs no code change.
+        if (!isPlainObject(entry) || !exactKeys(entry, ["auth"])
+          || entry.auth !== "keychain") {
+          errors.push(`provider "${name}" must have exactly {auth: "keychain"}`);
+          continue;
+        }
+        extended.push(name);
+      }
+      providerRegistry = Object.freeze([...BUILTIN_PROVIDERS, ...extended]);
+    }
+  }
   // endpoints{}: named, closed-shape endpoint records. URLs are validated
   // structurally (http/https); there is no unrestricted-URL escape hatch.
   if (!isPlainObject(config.endpoints)) {
@@ -222,8 +272,8 @@ export function validateRouterConfig(config) {
         || !/^https?:\/\/[A-Za-z0-9._~:/?#[\]@!$&'()*+,;=%-]+$/.test(endpoint.url)) {
         errors.push(`endpoint "${name}" url must be an http(s) URL`);
       }
-      if (!PROVIDERS.includes(endpoint.kind)) {
-        errors.push(`endpoint "${name}" kind "${endpoint.kind}" is not in the closed provider registry`);
+      if (!providerRegistry.includes(endpoint.kind)) {
+        errors.push(`endpoint "${name}" kind "${endpoint.kind}" is not in the provider registry (built-ins plus configured extensions)`);
       }
     }
   }
@@ -233,7 +283,7 @@ export function validateRouterConfig(config) {
   } else {
     const seen = new Set();
     for (const seat of config.seats) {
-      const check = wellFormedSeat(seat, { endpoints: config.endpoints });
+      const check = wellFormedSeat(seat, { endpoints: config.endpoints, providerRegistry });
       if (!check.ok) {
         errors.push(`seat ${seat?.seatId ?? "(unidentified)"}: ${check.reason}`);
         continue;
@@ -408,8 +458,8 @@ export function validateRouterConfig(config) {
     errors.push("secrets must be an object keyed by provider id");
   } else {
     for (const [provider, ref] of Object.entries(config.secrets)) {
-      if (!PROVIDERS.includes(provider)) {
-        errors.push(`secrets key "${provider}" is not in the closed provider registry`);
+      if (!providerRegistry.includes(provider)) {
+        errors.push(`secrets key "${provider}" is not in the provider registry (built-ins plus configured extensions)`);
         continue;
       }
       if (!isPlainObject(ref) || !exactKeys(ref, SECRET_REF_FIELDS)