@evoclock/pi-agentic-driver 0.9.2 → 0.9.4

package/janus/janus/schema.ts

@@ -0,0 +1,344 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Question schema contract v2 enforcement (§6).
+//
+// The request is ATOMIC: any malformed, absent, or contradictory answer fails
+// the entire request with validation_error; the caller applies its failure
+// policy for the whole batch (fail closed for the binding gate, fail open for
+// advisory uses).
+//
+// Question identity: every question carries a REQUIRED caller-supplied
+// `name` — a stable, non-sensitive identifier used for answer keying and
+// audit records. The question TEXT itself is separate and is always sent to
+// the provider verbatim; it never enters the audit log.
+//
+// Provider selection is configuration-only: request-level `model` and
+// `provider` fields are rejected outright (M8).
+
+import {
+  MAX_CHOICES,
+  MAX_INSTRUCTIONS_CHARS,
+  MAX_QUESTIONS,
+  SCORE_LEVELS,
+} from "./config.js";
+import { validationError } from "./errors.js";
+
+export type RawQuestion = {
+  type: unknown;
+  name?: unknown;
+  question?: unknown;
+  choices?: unknown;
+  levels?: unknown;
+  threshold?: unknown;
+  instructions?: unknown;
+  criteria?: unknown;
+};
+
+export interface BooleanQuestion {
+  kind: "boolean";
+  name: string;
+  question: string;
+  threshold: number;
+  instructions: string;
+  sdkCriteria?: { true?: string | null; false?: string | null } | undefined;
+}
+
+export interface ChoiceQuestion {
+  kind: "choice";
+  name: string;
+  question: string;
+  choices: string[];
+  instructions: string;
+}
+
+export interface ScoreQuestion {
+  kind: "score";
+  name: string;
+  question: string;
+  levels: number;
+  instructions: string;
+}
+
+export type EnforcedQuestion = BooleanQuestion | ChoiceQuestion | ScoreQuestion;
+
+export interface EnforcedRequest {
+  state: unknown;
+  timeoutMs?: number | undefined;
+  questions: EnforcedQuestion[];
+}
+
+export const DEFAULT_BOOLEAN_THRESHOLD = 0.9;
+/** Maximum characters for a caller-supplied question name. */
+export const MAX_QUESTION_NAME_CHARS = 256;
+/** Maximum characters for the question text itself. */
+export const MAX_QUESTION_TEXT_CHARS = 20_000;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Enforce the required, non-sensitive question identifier. */
+function enforceQuestionName(raw: RawQuestion, index: number): string {
+  const name = raw.name;
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw validationError(
+      `questions[${index}]: name is required — a nonempty, non-sensitive identifier used for answer keying and audit`,
+    );
+  }
+  if (name.length > MAX_QUESTION_NAME_CHARS) {
+    throw validationError(
+      `questions[${index}]: name exceeds ${MAX_QUESTION_NAME_CHARS} characters`,
+    );
+  }
+  return name;
+}
+
+/** Enforce the required question text. It is always sent to the provider. */
+function enforceQuestionText(raw: RawQuestion, name: string): string {
+  const question = raw.question;
+  if (typeof question !== "string" || question.trim().length === 0) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: question text is required and must be a nonempty string`,
+    );
+  }
+  if (question.length > MAX_QUESTION_TEXT_CHARS) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: question text exceeds ${MAX_QUESTION_TEXT_CHARS} characters`,
+    );
+  }
+  return question;
+}
+
+function enforceInstructions(raw: RawQuestion, name: string): string {
+  const instructions = raw.instructions;
+  if (instructions === undefined) return "";
+  if (typeof instructions !== "string") {
+    throw validationError(
+      `question ${JSON.stringify(name)}: instructions must be a string`,
+    );
+  }
+  if (instructions.length > MAX_INSTRUCTIONS_CHARS) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: instructions exceed ${MAX_INSTRUCTIONS_CHARS} characters`,
+    );
+  }
+  return instructions;
+}
+
+function enforceBoolean(raw: RawQuestion, name: string): BooleanQuestion {
+  let threshold = DEFAULT_BOOLEAN_THRESHOLD;
+  if (raw.threshold !== undefined) {
+    if (
+      typeof raw.threshold !== "number" ||
+      !Number.isFinite(raw.threshold) ||
+      raw.threshold < 0 ||
+      raw.threshold > 1
+    ) {
+      throw validationError(
+        `question ${JSON.stringify(name)}: threshold must be a number in [0, 1]`,
+      );
+    }
+    threshold = raw.threshold;
+  }
+  const instructions = enforceInstructions(raw, name);
+
+  // Optional boolean criteria pair (SDK shape: {true?, false?}).
+  let sdkCriteria: BooleanQuestion["sdkCriteria"];
+  if (raw.criteria !== undefined) {
+    if (!isPlainObject(raw.criteria)) {
+      throw validationError(
+        `question ${JSON.stringify(name)}: criteria must be an object with optional true/false labels`,
+      );
+    }
+    const allowed = new Set(["true", "false"]);
+    for (const key of Object.keys(raw.criteria)) {
+      if (!allowed.has(key)) {
+        throw validationError(
+          `question ${JSON.stringify(name)}: criteria.${key} is unknown; only true/false labels are accepted`,
+        );
+      }
+    }
+    const trueLabel = raw.criteria.true;
+    const falseLabel = raw.criteria.false;
+    if (trueLabel !== undefined && typeof trueLabel !== "string" && trueLabel !== null) {
+      throw validationError(
+        `question ${JSON.stringify(name)}: criteria.true must be a string or null`,
+      );
+    }
+    if (falseLabel !== undefined && typeof falseLabel !== "string" && falseLabel !== null) {
+      throw validationError(
+        `question ${JSON.stringify(name)}: criteria.false must be a string or null`,
+      );
+    }
+    sdkCriteria = {};
+    if (trueLabel !== undefined) sdkCriteria.true = trueLabel;
+    if (falseLabel !== undefined) sdkCriteria.false = falseLabel;
+  }
+
+  return {
+    kind: "boolean",
+    name,
+    question: enforceQuestionText(raw, name),
+    threshold,
+    instructions,
+    sdkCriteria,
+  };
+}
+
+function enforceChoice(raw: RawQuestion, name: string): ChoiceQuestion {
+  const instructions = enforceInstructions(raw, name);
+
+  // §6: the candidate set is REQUIRED in the schema.
+  const choices = raw.choices;
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: choice questions require a nonempty choices array`,
+    );
+  }
+  if (!choices.every((c) => typeof c === "string" && c.length > 0)) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: every choice must be a nonempty string`,
+    );
+  }
+  if (new Set(choices).size !== choices.length) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: choices must be unique`,
+    );
+  }
+  if (choices.length > MAX_CHOICES) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: more than ${MAX_CHOICES} choices`,
+    );
+  }
+  return {
+    kind: "choice",
+    name,
+    question: enforceQuestionText(raw, name),
+    choices,
+    instructions,
+  };
+}
+
+function enforceScore(raw: RawQuestion, name: string): ScoreQuestion {
+  const instructions = enforceInstructions(raw, name);
+
+  // §6: score is numeric 0..5, one decimal. Ordinal vocabularies must be
+  // choice questions, not scores; there is no per-question override.
+  const levels = SCORE_LEVELS;
+  if (raw.levels !== undefined || raw.choices !== undefined) {
+    throw validationError(
+      `question ${JSON.stringify(name)}: score questions have a fixed 0..5 vocabulary; ` +
+        `use a choice question for ordinal labels`,
+    );
+  }
+  return {
+    kind: "score",
+    name,
+    question: enforceQuestionText(raw, name),
+    levels,
+    instructions,
+  };
+}
+
+export function enforceRequest(body: unknown): EnforcedRequest {
+  if (!isPlainObject(body)) {
+    throw validationError("request body must be a JSON object");
+  }
+
+  // Closed request validation: unknown top-level fields are rejected, not
+  // ignored. `model` and `provider` are deliberately absent — provider
+  // selection is configuration-only (M8).
+  const allowed = new Set(["state", "timeoutMs", "questions"]);
+  for (const key of Object.keys(body)) {
+    if (!allowed.has(key)) {
+      throw validationError(
+        `unknown request field ${JSON.stringify(key)}; allowed fields: state, timeoutMs, questions`,
+      );
+    }
+  }
+
+  const state = body.state;
+  if (state === undefined) {
+    throw validationError("state is required");
+  }
+  // Strings, plain objects, and arrays (message histories pass directly).
+  if (
+    typeof state !== "string" &&
+    !isPlainObject(state) &&
+    !Array.isArray(state)
+  ) {
+    throw validationError("state must be a string, object, or array");
+  }
+
+  let timeoutMs: number | undefined;
+  if (body.timeoutMs !== undefined) {
+    if (
+      typeof body.timeoutMs !== "number" ||
+      !Number.isFinite(body.timeoutMs) ||
+      !Number.isInteger(body.timeoutMs) ||
+      body.timeoutMs <= 0
+    ) {
+      throw validationError("timeoutMs must be a positive integer (milliseconds)");
+    }
+    timeoutMs = body.timeoutMs;
+  }
+
+  const rawQuestions = body.questions;
+  if (!Array.isArray(rawQuestions) || rawQuestions.length === 0) {
+    throw validationError("questions must be a nonempty array");
+  }
+  if (rawQuestions.length > MAX_QUESTIONS) {
+    throw validationError(`more than ${MAX_QUESTIONS} questions in one request`);
+  }
+
+  const questions: EnforcedQuestion[] = rawQuestions.map((entry, index) => {
+    if (!isPlainObject(entry)) {
+      throw validationError(`questions[${index}] must be an object`);
+    }
+    const raw = entry as RawQuestion;
+    // Closed per-question validation: unknown fields rejected, never ignored.
+    const allowedQuestionFields = new Set([
+      "type",
+      "name",
+      "question",
+      "choices",
+      "threshold",
+      "instructions",
+      "criteria",
+    ]);
+    for (const key of Object.keys(raw)) {
+      if (!allowedQuestionFields.has(key)) {
+        throw validationError(
+          `questions[${index}]: unknown field ${JSON.stringify(key)}`,
+        );
+      }
+    }
+    const name = enforceQuestionName(raw, index);
+    switch (raw.type) {
+      case "boolean":
+        return enforceBoolean(raw, name);
+      case "choice":
+        return enforceChoice(raw, name);
+      case "score":
+        return enforceScore(raw, name);
+      default:
+        throw validationError(
+          `questions[${index}]: type must be one of "boolean", "choice", "score"`,
+        );
+    }
+  });
+
+  // Duplicate question names would make the answer map ambiguous.
+  const seen = new Set<string>();
+  for (const q of questions) {
+    if (seen.has(q.name)) {
+      throw validationError(
+        `duplicate question name: ${JSON.stringify(q.name)}`,
+      );
+    }
+    seen.add(q.name);
+  }
+
+  return { state, timeoutMs, questions };
+}

package/janus/janus/server.ts

@@ -0,0 +1,267 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// janus HTTP surface (§5): POST /evaluate, GET /healthz, GET /readyz,
+// GET /version. Binds 127.0.0.1 ONLY (H4) — the bind address is not
+// configurable by design. No auth beyond loopback: it is a local tool.
+//
+// Review fixes #5 and #10:
+//   - Content-Type is parsed properly (RFC 9110): `application/json` with
+//     parameters such as `charset=utf-8` is accepted; a missing header,
+//     malformed type, or any non-JSON type is rejected with validation_error.
+//   - An oversized body is drained and answered with a structured JSON
+//     validation_error whenever safely possible.
+//   - Every error body uses a FIXED public message; internal error text
+//     (including `error.message` from unexpected exceptions) never reaches
+//     an HTTP caller.
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { JANUS_VERSION, QUESTION_SCHEMA_VERSION, RESPONSE_SCHEMA_VERSION, type JanusConfig } from "./config.js";
+import { TYPESAFE_SDK_VERSION, ProviderChain } from "./providers.js";
+import { Evaluator, buildProviderChain, type EvaluateResponse } from "./evaluate.js";
+import { SingleFlight } from "./single_flight.js";
+import { DailyBudget } from "./budget_breaker.js";
+import { AuditLog } from "./audit.js";
+
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+
+export interface JanusService {
+  server: Server;
+  port: number;
+  stop: () => Promise<void>;
+}
+
+function sendJson(res: ServerResponse, status: number, payload: unknown): void {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function validationBody(message: string): Record<string, unknown> {
+  return { error: "validation_error", message, request_id: "n/a" };
+}
+
+/**
+ * Parse a Content-Type header per RFC 9110 and decide whether the body is
+ * JSON. Returns the accepted type or a fixed public rejection reason.
+ */
+export function parseJsonContentType(header: string | undefined):
+  | { ok: true }
+  | { ok: false; reason: "missing" | "malformed" | "not-json" } {
+  if (header === undefined) return { ok: false, reason: "missing" };
+  // type = token "/" token *( OWS ";" OWS parameter )
+  const match = /^\s*([!#$%&'*+\-.^_`|~0-9A-Za-z]+)\/([!#$%&'*+\-.^_`|~0-9A-Za-z]+)\s*(?:;.*)?$/.exec(header);
+  if (match === null) return { ok: false, reason: "malformed" };
+  const type = `${match[1]!.toLowerCase()}/${match[2]!.toLowerCase()}`;
+  if (type !== "application/json") return { ok: false, reason: "not-json" };
+  return { ok: true };
+}
+
+function readBody(req: IncomingMessage): Promise<Buffer> {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    let overLimit = false;
+    // Over-limit bodies are DRAINED (chunks discarded, stream consumed) so
+    // the structured 413 JSON response can still be delivered safely
+    // (review fix #10). A hard runaway ceiling destroys the connection.
+    const RUNAWAY_BYTES = 64 * 1024 * 1024;
+    req.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > MAX_BODY_BYTES) {
+        overLimit = true;
+        chunks.length = 0;
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (overLimit) rejectPromise(new BodyTooLargeError());
+      else resolvePromise(Buffer.concat(chunks));
+    });
+    req.on("error", (error) => {
+      if (total > RUNAWAY_BYTES) req.destroy();
+      if (!overLimit) rejectPromise(error);
+    });
+  });
+}
+
+class BodyTooLargeError extends Error {
+  constructor() {
+    super("request body too large");
+    this.name = "BodyTooLargeError";
+  }
+}
+
+export function createJanusService(
+  config: JanusConfig,
+  evaluator: Evaluator,
+  readiness: () => Promise<{ ready: boolean; reason?: string }>,
+): JanusService {
+  const server = createServer((req, res) => {
+    void handleRequest(req, res, config, evaluator, readiness);
+  });
+  // Loopback only, by construction (H4). There is no bind-address option.
+  server.listen(config.port, "127.0.0.1");
+
+  return {
+    server,
+    port: config.port,
+    stop: () =>
+      new Promise((resolvePromise) => {
+        server.close(() => resolvePromise());
+      }),
+  };
+}
+
+async function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  config: JanusConfig,
+  evaluator: Evaluator,
+  readiness: () => Promise<{ ready: boolean; reason?: string }>,
+): Promise<void> {
+  const url = new URL(req.url ?? "/", `http://127.0.0.1:${config.port}`);
+  const route = `${req.method} ${url.pathname}`;
+
+  try {
+    if (route === "GET /healthz") {
+      sendJson(res, 200, { status: "ok", version: JANUS_VERSION });
+      return;
+    }
+
+    if (route === "GET /readyz") {
+      const keyState = await readiness();
+      if (keyState.ready) {
+        sendJson(res, 200, { status: "ready", version: JANUS_VERSION });
+      } else {
+        sendJson(res, 503, {
+          status: "not_ready",
+          version: JANUS_VERSION,
+          // Fixed public reason only (review fix #5).
+          reason: keyState.reason ?? "no provider credential resolvable",
+        });
+      }
+      return;
+    }
+
+    if (route === "GET /version") {
+      sendJson(res, 200, {
+        janus: JANUS_VERSION,
+        typesafeSdk: TYPESAFE_SDK_VERSION,
+        questionSchema: QUESTION_SCHEMA_VERSION,
+        responseSchema: RESPONSE_SCHEMA_VERSION,
+        providers: config.providers.map((p) => p.id),
+        defaultModel: config.defaultModel,
+      });
+      return;
+    }
+
+    if (route === "POST /evaluate") {
+      // Content-Type must be a properly parsed application/json (parameters
+      // such as charset are allowed) — review fix #10.
+      const contentType = parseJsonContentType(req.headers["content-type"]);
+      if (!contentType.ok) {
+        const reason =
+          contentType.reason === "missing"
+            ? "content-type header is required and must be application/json"
+            : contentType.reason === "malformed"
+              ? "content-type header is malformed"
+              : "content-type must be application/json";
+        sendJson(res, 400, validationBody(reason));
+        return;
+      }
+      let body: unknown;
+      try {
+        const raw = await readBody(req);
+        if (raw.length === 0) {
+          sendJson(res, 400, validationBody("request body is required"));
+          return;
+        }
+        body = JSON.parse(raw.toString("utf8"));
+      } catch (error) {
+        if (error instanceof BodyTooLargeError) {
+          // Structured JSON even for oversized bodies, when safely possible.
+          sendJson(res, 413, validationBody(
+            `request body exceeds ${MAX_BODY_BYTES} bytes`,
+          ));
+          return;
+        }
+        // Fixed message: the JSON parse error text is not echoed.
+        sendJson(res, 400, validationBody("request body is not valid JSON"));
+        return;
+      }
+      const outcome: EvaluateResponse = await evaluator.handle(body);
+      sendJson(res, outcome.status, outcome.payload);
+      return;
+    }
+
+    sendJson(res, 404, validationBody(`unknown route ${route}; see GET /version for the endpoint contract`));
+  } catch {
+    // Internal error text never reaches the caller (review fix #5).
+    sendJson(res, 500, {
+      error: "degraded",
+      message: "internal error",
+      request_id: "n/a",
+    });
+  }
+}
+
+/** Wire the default service from a loaded config (production path). */
+export function buildService(config: JanusConfig): JanusService {
+  const audit = new AuditLog(config.audit.path, config.audit.maxBytes, config.audit.retentionDays);
+  audit.start();
+  const chain = buildProviderChain(config);
+  const evaluator = new Evaluator({
+    config,
+    singleFlight: new SingleFlight(config.maxConcurrent),
+    budget: new DailyBudget(
+      config.dailyTokenCeiling,
+      config.dailyCostCeilingUsd,
+      config.costPerMtokenUsd,
+    ),
+    audit,
+    chain,
+  });
+  const service = createJanusService(config, evaluator, () => chain.readiness());
+  const stop = service.stop;
+  return {
+    ...service,
+    stop: () => {
+      audit.stop();
+      return stop();
+    },
+  };
+}
+
+/** Entry point: `npx tsx janus/server.ts` (dev) or launchd (label user.janus). */
+export function main(): void {
+  const configPath = process.env.JANUS_CONFIG_PATH;
+  const { config, warnings } = loadConfig(configPath || undefined);
+  for (const warning of warnings) console.error(`janus: ${warning}`);
+  const service = buildService(config);
+  service.server.on("listening", () => {
+    console.error(`janus: listening on 127.0.0.1:${config.port} (loopback only)`);
+    console.error(`janus: audit log at ${config.audit.path === "stdout" ? "stdout" : `${config.audit.path}.jsonl`}`);
+  });
+  const shutdown = () => {
+    void service.stop().then(() => process.exit(0));
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+import { loadConfig } from "./config.js";
+
+/** Direct-run entrypoint: `npx tsx janus/server.ts`. */
+export function runIfMain(invokedPath: string): void {
+  if (!invokedPath.endsWith("server.ts")) return;
+  main();
+}
+
+if (process.argv[1] && process.argv[1].endsWith("janus/server.ts")) {
+  main();
+}

package/janus/janus/single_flight.ts

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Single-flight and concurrency (§5, M9).
+//
+// One in-flight evaluation per evalInputDigest: identical requests coalesce
+// and share the same eventual result. A global cap (default 4) on DISTINCT
+// in-flight evaluations rejects new distinct requests with `busy`.
+//
+// Coalescing accounting (review fix #11): the number of coalesced waiters is
+// observable per digest (waitersFor) and reported to the flight owner's
+// onSettle callback, so the audit log can mark coalescing accurately — the
+// provider call and its usage are charged exactly once regardless of how
+// many callers shared the flight.
+
+import { busyError } from "./errors.js";
+
+interface Flight<T> {
+  promise: Promise<T>;
+  waiters: number;
+}
+
+export class SingleFlight {
+  private readonly flights = new Map<string, Flight<unknown>>();
+  private inFlight = 0;
+
+  constructor(private readonly maxConcurrent: number) {}
+
+  get size(): number {
+    return this.inFlight;
+  }
+
+  /**
+   * How many callers are currently coalesced onto `digest` (0 = none; the
+   * flight owner is not counted as a waiter).
+   */
+  waitersFor(digest: string): number {
+    return this.flights.get(digest)?.waiters ?? 0;
+  }
+
+  /**
+   * Run `task` keyed by `digest`. Identical concurrent digests coalesce onto
+   * one task. Distinct digests beyond the concurrency cap reject with busy.
+   * `onSettle` (optional) fires exactly once when the flight settles, with
+   * the number of coalesced waiters that joined — used to mark coalescing
+   * accurately in the audit log (review fix #11).
+   */
+  run<T>(
+    digest: string,
+    task: () => Promise<T>,
+    onSettle?: (info: { waiters: number }) => void,
+  ): Promise<T> {
+    const existing = this.flights.get(digest) as Flight<T> | undefined;
+    if (existing) {
+      existing.waiters += 1;
+      return existing.promise;
+    }
+
+    if (this.inFlight >= this.maxConcurrent) {
+      throw busyError(
+        `global concurrency cap of ${this.maxConcurrent} reached; retry later`,
+      );
+    }
+
+    this.inFlight += 1;
+    let settledWaiters = 0;
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      this.inFlight -= 1;
+      this.flights.delete(digest);
+      onSettle?.({ waiters: settledWaiters });
+    };
+
+    const promise: Promise<T> = (async () => {
+      try {
+        return await task();
+      } finally {
+        settle();
+      }
+    })();
+
+    // Proxy so late waiters still bump the count seen at settle time.
+    const flight: Flight<T> = {
+      get promise() {
+        return promise;
+      },
+      get waiters() {
+        return settledWaiters;
+      },
+      set waiters(value: number) {
+        settledWaiters = value;
+      },
+    };
+    this.flights.set(digest, flight as Flight<unknown>);
+    return promise;
+  }
+}