witnora 0.13.8 → 0.13.9

package/README.md

@@ -1,5 +1,14 @@
 # Witnora CLI
 
+## Customer Evaluator Kit
+
+`witnora/evaluator-kit` exports `createBusinessTaskEvaluatorServer()` for the customer-side
+Replay and Shadow evaluator consumed by the managed Workflow Harness. It listens only on a
+literal loopback address, requires a pinned bearer credential and contract digest, validates
+the exact Business Task binding, and returns only the structured evaluation report. Customer
+scenario inputs and candidate callbacks stay in the customer process. Replay can execute only
+through the supplied synthetic sandbox harness; Shadow exposes no write interface.
+
 Unified release assurance, evidence, corpus, monitor, and lab CLI for Witnora.
 
 Witnora checks what an agent may do, whether it passed pre-release evidence,

package/dist/gateway.js

@@ -578,7 +578,8 @@ export async function createConfiguredWorkflowHarness(input) {
     const healthBody = await health.json().catch(() => ({}));
     if (!health.ok
         || healthBody.schemaVersion !== "witnora.business_task_evaluator.v0.1"
-        || healthBody.contractSha256 !== input.config.evaluatorContractSha256) {
+        || healthBody.contractSha256 !== input.config.evaluatorContractSha256
+        || healthBody.ready !== true) {
         throw new Error("Managed Workflow evaluator health did not match its pinned local contract.");
     }
     const hosted = input.managed.createManagedWorkflowHostedClient({

package/dist/vendor/onegent-runtime/business-task-evaluator.d.ts

@@ -0,0 +1,49 @@
+import type { SandboxCertificationHarness } from "./sandbox-harness.js";
+import { type ShadowCandidateEvaluation, type TaskCandidateEvaluation, type TaskEvaluationContract, type TaskEvaluationScenario } from "./task-evaluation.js";
+export declare const BUSINESS_TASK_EVALUATOR_SCHEMA_VERSION: "witnora.business_task_evaluator.v0.1";
+export declare const BUSINESS_TASK_EVALUATION_REQUEST_SCHEMA_VERSION: "witnora.business_task_evaluation_request.v0.1";
+export interface BusinessTaskEvaluationBinding {
+    nodeId: string;
+    taskContractId: string;
+    taskContractDigestSha256: string;
+    taskKey: string;
+    agentId: string;
+    agentVersion: string;
+    mode: "REPLAY" | "SHADOW";
+}
+export interface BusinessTaskEvaluatorServerOptions {
+    credential: string;
+    contractSha256: string;
+    host?: "127.0.0.1" | "::1";
+    port?: number;
+    maxBodyBytes?: number;
+    maxConcurrency?: number;
+    evaluationTimeoutMs?: number;
+    loadReplayScenarios?(task: TaskEvaluationContract, binding: BusinessTaskEvaluationBinding, signal: AbortSignal): Promise<TaskEvaluationScenario[]>;
+    createReplayHarness?(task: TaskEvaluationContract, binding: BusinessTaskEvaluationBinding, signal: AbortSignal): Promise<{
+        harness: SandboxCertificationHarness;
+        tenantId: string;
+    }>;
+    evaluateReplayCandidate?(scenario: {
+        id: string;
+        source: TaskEvaluationScenario["source"];
+        input: unknown;
+    }, task: TaskEvaluationContract, binding: BusinessTaskEvaluationBinding, signal: AbortSignal): Promise<TaskCandidateEvaluation>;
+    loadShadowObservations?(task: TaskEvaluationContract, binding: BusinessTaskEvaluationBinding, signal: AbortSignal): Promise<TaskEvaluationScenario[]>;
+    evaluateShadowCandidate?(context: {
+        id: string;
+        source: "LIVE_SHADOW";
+        input: unknown;
+        propose: (intent: {
+            pathId: string;
+            parametersDigestSha256: string;
+        }) => void;
+    }, task: TaskEvaluationContract, binding: BusinessTaskEvaluationBinding, signal: AbortSignal): Promise<ShadowCandidateEvaluation>;
+}
+export declare function createBusinessTaskEvaluatorServer(options: BusinessTaskEvaluatorServerOptions): {
+    start(): Promise<{
+        origin: string;
+    }>;
+    close(): Promise<void>;
+};
+//# sourceMappingURL=business-task-evaluator.d.ts.map

package/dist/vendor/onegent-runtime/business-task-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"business-task-evaluator.d.ts","sourceRoot":"","sources":["../../../../onegent-runtime/src/business-task-evaluator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAE3B,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,sCAAsC,EAAG,sCAA+C,CAAC;AACtG,eAAO,MAAM,+CAA+C,EAAG,+CAAwD,CAAC;AAExH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB,EAAE,MAAM,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC3B;AAED,MAAM,WAAW,kCAAkC;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,CAAC,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,6BAA6B,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;IACnJ,mBAAmB,CAAC,CAAC,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,6BAA6B,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,2BAA2B,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrL,uBAAuB,CAAC,CAAC,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,6BAA6B,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC1O,sBAAsB,CAAC,CAAC,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,6BAA6B,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;IACtJ,uBAAuB,CAAC,CAAC,OAAO,EAAE;QAChC,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,aAAa,CAAC;QACtB,KAAK,EAAE,OAAO,CAAC;QACf,OAAO,EAAE,CAAC,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,sBAAsB,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,CAAC;KAC/E,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,6BAA6B,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACnI;AAED,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,kCAAkC;aA+C1E,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;aAQ3B,OAAO,CAAC,IAAI,CAAC;EAK/B"}

package/dist/vendor/onegent-runtime/business-task-evaluator.js

@@ -0,0 +1,185 @@
+import { timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { runReplayEvaluation, runShadowEvaluation, } from "./task-evaluation.js";
+export const BUSINESS_TASK_EVALUATOR_SCHEMA_VERSION = "witnora.business_task_evaluator.v0.1";
+export const BUSINESS_TASK_EVALUATION_REQUEST_SCHEMA_VERSION = "witnora.business_task_evaluation_request.v0.1";
+export function createBusinessTaskEvaluatorServer(options) {
+    const host = options.host ?? "127.0.0.1";
+    if (host !== "127.0.0.1" && host !== "::1")
+        throw new Error("Business Task Evaluator accepts only a literal loopback host.");
+    const credential = required(options.credential, "credential");
+    const contractSha256 = digest(options.contractSha256, "contractSha256");
+    const port = bounded(options.port ?? 0, 0, 65_535, "port");
+    const maxBodyBytes = bounded(options.maxBodyBytes ?? 1_048_576, 1_024, 4_194_304, "maxBodyBytes");
+    const maxConcurrency = bounded(options.maxConcurrency ?? 4, 1, 16, "maxConcurrency");
+    const evaluationTimeoutMs = bounded(options.evaluationTimeoutMs ?? 120_000, 1_000, 600_000, "evaluationTimeoutMs");
+    const modes = [
+        ...(options.loadReplayScenarios && options.createReplayHarness && options.evaluateReplayCandidate ? ["REPLAY"] : []),
+        ...(options.loadShadowObservations && options.evaluateShadowCandidate ? ["SHADOW"] : []),
+    ];
+    let active = 0;
+    const server = createServer(async (request, response) => {
+        response.setHeader("cache-control", "no-store");
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        try {
+            if (!authorized(request, credential))
+                return send(response, 401, { error: "unauthorized" });
+            if (request.method === "GET" && request.url === "/healthz") {
+                return send(response, 200, {
+                    schemaVersion: BUSINESS_TASK_EVALUATOR_SCHEMA_VERSION,
+                    contractSha256,
+                    ready: modes.length > 0,
+                    modes,
+                    boundary: { host, productionWrites: 0, rawInputsRetainedByCustomer: true },
+                });
+            }
+            if (request.method !== "POST" || request.url !== "/v1/evaluate")
+                return send(response, 404, { error: "not_found" });
+            if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) {
+                return send(response, 415, { error: "json_required" });
+            }
+            if (active >= maxConcurrency)
+                return send(response, 429, { error: "evaluator_busy" });
+            const body = await readJson(request, maxBodyBytes);
+            const parsed = parseRequest(body);
+            validateBinding(parsed.task, parsed.evaluation);
+            active += 1;
+            try {
+                const report = await withTimeout((signal) => evaluate(options, parsed.task, parsed.evaluation, signal), evaluationTimeoutMs);
+                return send(response, 200, { schemaVersion: BUSINESS_TASK_EVALUATOR_SCHEMA_VERSION, report });
+            }
+            finally {
+                active -= 1;
+            }
+        }
+        catch (error) {
+            const status = error instanceof EvaluatorError ? error.status : 422;
+            return send(response, status, { error: error instanceof EvaluatorError ? error.code : "evaluation_failed" });
+        }
+    });
+    return {
+        async start() {
+            if (!server.listening)
+                await new Promise((resolve, reject) => {
+                    server.once("error", reject);
+                    server.listen(port, host, () => { server.off("error", reject); resolve(); });
+                });
+            const address = server.address();
+            return { origin: `http://${host === "::1" ? "[::1]" : host}:${address.port}` };
+        },
+        async close() {
+            if (!server.listening)
+                return;
+            await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+        },
+    };
+}
+async function evaluate(options, task, binding, signal) {
+    if (binding.mode === "REPLAY") {
+        if (!options.loadReplayScenarios || !options.createReplayHarness || !options.evaluateReplayCandidate) {
+            throw new EvaluatorError(409, "replay_not_configured");
+        }
+        const [{ harness, tenantId }, scenarios] = await Promise.all([
+            options.createReplayHarness(task, binding, signal), options.loadReplayScenarios(task, binding, signal),
+        ]);
+        return runReplayEvaluation({
+            task, harness, tenantId, scenarios,
+            evaluateCandidate: (scenario) => options.evaluateReplayCandidate(scenario, task, binding, signal),
+        });
+    }
+    if (!options.loadShadowObservations || !options.evaluateShadowCandidate)
+        throw new EvaluatorError(409, "shadow_not_configured");
+    return runShadowEvaluation({
+        task,
+        observations: await options.loadShadowObservations(task, binding, signal),
+        evaluateCandidate: (context) => options.evaluateShadowCandidate(context, task, binding, signal),
+    });
+}
+function parseRequest(input) {
+    const body = object(input, "request");
+    exactKeys(body, ["schemaVersion", "task", "evaluation"], "request");
+    if (body.schemaVersion !== BUSINESS_TASK_EVALUATION_REQUEST_SCHEMA_VERSION)
+        throw new EvaluatorError(422, "invalid_schema");
+    const evaluation = object(body.evaluation, "evaluation");
+    exactKeys(evaluation, ["nodeId", "taskContractId", "taskContractDigestSha256", "taskKey", "agentId", "agentVersion", "mode"], "evaluation");
+    if (evaluation.mode !== "REPLAY" && evaluation.mode !== "SHADOW")
+        throw new EvaluatorError(422, "invalid_mode");
+    const binding = {
+        nodeId: requiredString(evaluation.nodeId), taskContractId: requiredString(evaluation.taskContractId),
+        taskContractDigestSha256: digest(String(evaluation.taskContractDigestSha256 ?? ""), "taskContractDigestSha256"),
+        taskKey: requiredString(evaluation.taskKey), agentId: requiredString(evaluation.agentId),
+        agentVersion: requiredString(evaluation.agentVersion), mode: evaluation.mode,
+    };
+    return { task: object(body.task, "task"), evaluation: binding };
+}
+function validateBinding(task, binding) {
+    if (task.id !== binding.taskContractId || task.digestSha256 !== binding.taskContractDigestSha256
+        || task.taskKey !== binding.taskKey || task.subject?.agentId !== binding.agentId
+        || task.subject?.agentVersion !== binding.agentVersion)
+        throw new EvaluatorError(409, "task_binding_mismatch");
+}
+function authorized(request, credential) {
+    const supplied = String(request.headers.authorization ?? "").replace(/^Bearer\s+/i, "");
+    const left = Buffer.from(supplied);
+    const right = Buffer.from(credential);
+    return left.length === right.length && left.length > 0 && timingSafeEqual(left, right);
+}
+async function readJson(request, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += value.length;
+        if (size > limit)
+            throw new EvaluatorError(413, "body_too_large");
+        chunks.push(value);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new EvaluatorError(400, "invalid_json");
+    }
+}
+async function withTimeout(execute, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    try {
+        return await Promise.race([execute(controller.signal), new Promise((_, reject) => {
+                timer = setTimeout(() => { controller.abort(); reject(new EvaluatorError(504, "evaluation_timeout")); }, timeoutMs);
+                timer.unref?.();
+            })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function send(response, status, body) { response.statusCode = status; response.end(JSON.stringify(body)); }
+function object(value, name) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new EvaluatorError(422, `invalid_${name}`);
+    return value;
+}
+function exactKeys(value, allowed, name) {
+    const keys = new Set(allowed);
+    if (Object.keys(value).some((key) => !keys.has(key)))
+        throw new EvaluatorError(422, `unexpected_${name}_field`);
+}
+function required(value, name) { const result = value.trim(); if (!result)
+    throw new Error(`${name} is required.`); return result; }
+function requiredString(value) { if (typeof value !== "string" || !value.trim())
+    throw new EvaluatorError(422, "invalid_binding"); return value.trim(); }
+function digest(value, name) { if (!/^[a-f0-9]{64}$/.test(value))
+    throw new Error(`${name} must be a lowercase SHA-256 digest.`); return value; }
+function bounded(value, min, max, name) { if (!Number.isInteger(value) || value < min || value > max)
+    throw new Error(`${name} must be between ${min} and ${max}.`); return value; }
+class EvaluatorError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.13.8",
+  "version": "0.13.9",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "Apache-2.0",
@@ -40,6 +40,10 @@
       "types": "./dist/vendor/onegent-runtime/browser-adapter-kit.d.ts",
       "import": "./dist/vendor/onegent-runtime/browser-adapter-kit.js"
     },
+    "./evaluator-kit": {
+      "types": "./dist/vendor/onegent-runtime/business-task-evaluator.d.ts",
+      "import": "./dist/vendor/onegent-runtime/business-task-evaluator.js"
+    },
     "./deployment-enforcement": {
       "types": "./dist/internal/control-client/deployment-enforcement.d.ts",
       "import": "./dist/internal/control-client/deployment-enforcement.js"