@cygnuxlabs/tracekit 1.2.3 → 1.4.0

package/README.md

@@ -1,5 +1,9 @@
 # @cygnuxlabs/tracekit
 
+> **Experimental:** the client and its Vercel AI SDK integration work and are tested, but may change and get less
+> hardening than the [stable core](https://github.com/Cygnux-Labs/Tracekit/wiki/Support). Its verifier
+> (`src/verify/`) is stable.
+
 Tracekit for TypeScript and JavaScript agents: every tool call is decided by the Tracekit signer before it runs and
 recorded after, and model responses become signed evidence. The client talks to the signer directly; it needs no Python
 at runtime (the same-user dev signer is started with Python when none is running).
@@ -14,7 +18,7 @@ npm install @cygnuxlabs/tracekit
 
 npm also installs the signer package for your platform (`@cygnuxlabs/tracekit-signer-<platform>`: Apple Silicon
 macOS, Linux x64 and arm64 with glibc, Windows x64), which bundles a Python, so `npx @cygnuxlabs/tracekit up` starts a
-dev signer without one. On an Intel Mac or Alpine there is none: `pip install 'tracekit-ai[signer]'`.
+dev signer without one. On an Intel Mac or Alpine there is none: `pip install tracekit-ai`.
 
 Or build it from a checkout and install the file it makes:
 
@@ -91,6 +95,14 @@ It does not check SLH-DSA checkpoint lines, Rekor anchors or certified record ke
 `UNVERIFIABLE (not checked by this verifier: ...)`, never `VERIFIED`. Monitor reports, revocations and the v1 format
 bridge need the Python verifier.
 
+`verify(bundle, null)`, with no trust config, runs every check that needs no pinned key and is never `VERIFIED`: a
+changed record still fails, an intact bundle is `UNVERIFIABLE (no trust config: ...)`.
+
+In a browser: `dist/verify.html` in this package (and a release asset) is this verifier as one self-contained page.
+Drop in a bundle and its trust config; its Content Security Policy lets it load and send nothing, so neither file
+leaves the browser ([verify in your browser](../../docs/verdicts.md#verify-in-your-browser)). `make verify-page` builds
+it from a checkout.
+
 ## v2 framework adapters
 
 One call registers a run (the dev signer is started if none answers), closes it when the process is about to exit,

package/bin/tracekit.mjs

@@ -15,16 +15,18 @@ if (args[0] === "verify" && args.includes("--trust") && !args.some((a) => PYTHON
     process.exit(2);
   }
   const { main } = await import("../dist/verify/cli.js");
-  process.exit(await main(args.slice(1)));
-}
-const cmd = signerCommand();
-if (!cmd) {
-  console.error(`tracekit: ${INSTALL_HINT}`);
-  process.exit(1);
-}
-const r = spawnSync(cmd[0], [...cmd.slice(1), ...args], { stdio: "inherit", env: signerEnv(cmd) });
-if (r.error) {
-  console.error(`tracekit: ${cmd[0]}: ${r.error.message}`);
-  process.exit(1);
+  // not process.exit(): it would cut off a report still being written to a pipe (past 64 KiB)
+  process.exitCode = await main(args.slice(1));
+} else {
+  const cmd = signerCommand();
+  if (!cmd) {
+    console.error(`tracekit: ${INSTALL_HINT}`);
+    process.exit(1);
+  }
+  const r = spawnSync(cmd[0], [...cmd.slice(1), ...args], { stdio: "inherit", env: signerEnv(cmd) });
+  if (r.error) {
+    console.error(`tracekit: ${cmd[0]}: ${r.error.message}`);
+    process.exit(1);
+  }
+  process.exit(r.status ?? 1);
 }
-process.exit(r.status ?? 1);

package/dist/v2/client.d.ts

@@ -11,7 +11,10 @@ export declare class SignerUnavailable extends Error {
 }
 /** The signer answered but does not speak this client's protocol version. It is left running. */
 export declare class Incompatible extends Error {
+    readonly older: boolean;
     name: string;
+    /** Its protocol range ends below this client's: a signer from before an upgrade. */
+    constructor(message: string, older?: boolean);
 }
 /** A refusal from the signer (or of a request that fails the contract before it is sent). */
 export declare class RPCError extends Error {

package/dist/v2/client.js

@@ -43,7 +43,13 @@ export class SignerUnavailable extends Error {
 }
 /** The signer answered but does not speak this client's protocol version. It is left running. */
 export class Incompatible extends Error {
+    older;
     name = "Incompatible";
+    /** Its protocol range ends below this client's: a signer from before an upgrade. */
+    constructor(message, older = false) {
+        super(message);
+        this.older = older;
+    }
 }
 /** A refusal from the signer (or of a request that fails the contract before it is sent). */
 export class RPCError extends Error {
@@ -139,7 +145,7 @@ function check(hello, where) {
     if (!(Array.isArray(proto) && proto.length === 2 && proto[0] <= RPC_VERSION && RPC_VERSION <= proto[1]))
         throw new Incompatible(`the Tracekit signer ${hello?.version ?? "?"} (pid ${hello?.pid ?? "?"}, protocol ` +
             `${JSON.stringify(proto)}) at ${where} cannot serve this client (protocol ${RPC_VERSION}). It was left running. ` +
-            "Stop it with `tracekit down`, or replace it with `tracekit up --replace`");
+            "Stop it with `tracekit down`, or replace it with `tracekit up --replace`", Array.isArray(proto) && proto.length === 2 && typeof proto[1] === "number" && proto[1] < RPC_VERSION);
 }
 /** A connection to the signer at `path` (a Unix socket or tcp://host:port) and its hello, after the version check. */
 export async function connect(path, token) {
@@ -516,9 +522,9 @@ export class Client {
                 c = await connect(...devAddress(d));
             }
             catch (e) {
-                if (!(e instanceof SignerUnavailable))
+                if (!(e instanceof SignerUnavailable || e instanceof Incompatible && e.older))
                     throw e;
-                await startDevSigner();
+                await startDevSigner(); // `tracekit up` replaces a dev signer from before an upgrade
                 c = await connect(...devAddress(d));
             }
         }

package/dist/v2/launcher.js

@@ -6,7 +6,7 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { delimiter, dirname, join } from "node:path";
-export const INSTALL_HINT = "no Tracekit signer found. Install one: `pip install 'tracekit-ai[signer]'` (puts `tracekit` " +
+export const INSTALL_HINT = "no Tracekit signer found. Install one: `pip install tracekit-ai` (puts `tracekit` " +
     "on PATH), or reinstall @cygnuxlabs/tracekit without --omit=optional so npm adds the signer package for this platform";
 /** This platform's signer package suffix, as the optionalDependencies name them; null where none is built. */
 export function platformKey() {

package/dist/v2/rpc_schema.d.ts

@@ -1,3 +1,3 @@
 import type { Schema } from "./validate.js";
-export declare const RPC_VERSION = 16;
+export declare const RPC_VERSION = 19;
 export declare const REQUESTS: Record<string, Schema>;

package/dist/v2/rpc_schema.js

@@ -1,11 +1,11 @@
-export const RPC_VERSION = 16;
+export const RPC_VERSION = 19;
 export const REQUESTS = {
-    "register_run": { "type": "object", "additionalProperties": false, "required": ["request_id", "agent"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "tenant": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "principal": { "type": "string", "maxLength": 256 }, "principal_token": { "type": "string", "maxLength": 16384 }, "source": { "const": "migrated" }, "analyzes": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "replay_of": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "investigation": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "parent": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } }, "agent": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1 }, "version": { "type": "string", "maxLength": 64 } } } } },
+    "register_run": { "type": "object", "additionalProperties": false, "required": ["request_id", "agent"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "tenant": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "principal": { "type": "string", "maxLength": 256 }, "principal_token": { "type": "string", "maxLength": 16384 }, "source": { "const": "migrated" }, "analyzes": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "replay_of": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "investigation": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "parent": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "agent": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1 }, "version": { "type": "string", "maxLength": 64 } } } } },
     "decide": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "tool_call_id", "tool", "args_source", "args"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "attempt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tool": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_class_hint": { "type": "string", "maxLength": 64 }, "args_source": { "enum": ["raw", "parsed", "coerced"] }, "args": {} }, "if": { "properties": { "args_source": { "const": "raw" } } }, "then": { "properties": { "args": { "type": "string", "maxLength": 1048576 } } } },
     "complete": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "tool_call_id", "decision_id", "args_digest", "status"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "attempt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "decision_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "status": { "enum": ["ok", "error"] }, "result": {}, "error": { "type": "string", "maxLength": 4096 }, "redacted": { "const": true }, "redaction": { "type": "object", "additionalProperties": false, "required": [], "properties": { "rules": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 64 } }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } },
     "observe": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "source", "trust", "value"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "source": { "type": "string", "maxLength": 256, "minLength": 1 }, "trust": { "enum": ["trusted", "untrusted"] }, "value": {} } },
     "state_write": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "key", "value_digest"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "key": { "type": "string", "maxLength": 256, "minLength": 1 }, "value_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "prev_digest": { "oneOf": [{ "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, { "type": "null" }] } } },
-    "model_event": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "provider", "model", "phase"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "type": "string", "maxLength": 64 }, "model": { "type": "string", "maxLength": 128 }, "phase": { "enum": ["request", "response"] }, "content_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "exchange_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "streamed": { "type": "boolean" }, "stop_reason": { "type": "string", "maxLength": 100 }, "error": { "type": "string", "maxLength": 1024 }, "usage": { "type": "object", "additionalProperties": false, "required": [], "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_read_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_write_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasoning_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "tool_uses": { "type": "array", "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "executed_by"], "properties": { "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "name": { "type": "string", "maxLength": 256, "minLength": 1 }, "executed_by": { "enum": ["client", "provider"] }, "args_source": { "enum": ["raw", "parsed", "coerced"] }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "args_unparseable": { "const": true }, "id_synthetic": { "const": true } }, "oneOf": [{ "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {} } }, { "required": ["args_source", "args_digest"], "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {}, "args_source": {}, "args_digest": {} } }, { "required": ["args_source", "args_digest"], "properties": { "executed_by": { "const": "client" } } }, { "required": ["args_source", "args_unparseable"], "properties": { "executed_by": { "const": "client" } } }] } }, "tool_results_sent": { "type": "array", "maxItems": 1024, "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "body": {} } },
+    "model_event": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "provider", "model", "phase"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "type": "string", "maxLength": 64 }, "model": { "type": "string", "maxLength": 128 }, "phase": { "enum": ["request", "response"] }, "content_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "exchange_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "streamed": { "type": "boolean" }, "stop_reason": { "type": "string", "maxLength": 100 }, "error": { "type": "string", "maxLength": 1024 }, "usage": { "type": "object", "additionalProperties": false, "required": [], "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_read_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_write_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasoning_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "tool_uses": { "type": "array", "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "executed_by"], "properties": { "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "name": { "type": "string", "maxLength": 256, "minLength": 1 }, "executed_by": { "enum": ["client", "provider"] }, "args_source": { "enum": ["raw", "parsed", "coerced"] }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "args_unparseable": { "const": true }, "id_synthetic": { "const": true } }, "oneOf": [{ "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {} } }, { "required": ["args_source", "args_digest"], "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {}, "args_source": {}, "args_digest": {} } }, { "required": ["args_source", "args_digest"], "properties": { "executed_by": { "const": "client" } } }, { "required": ["args_source", "args_unparseable"], "properties": { "executed_by": { "const": "client" } } }] } }, "said_only": { "const": true }, "tool_results_sent": { "type": "array", "maxItems": 1024, "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } }, "tool_results": { "type": "array", "maxItems": 1024, "items": { "type": "object", "additionalProperties": false, "required": ["id", "forms"], "properties": { "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "forms": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "additionalProperties": false, "required": ["digest", "result_digest"], "properties": { "digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "result_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } } } } } }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "amended": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "maxLength": 256, "pattern": "^(/([^~/]|~[01])*)+(?![\\s\\S])" } }, "body": {} } },
     "approval_request": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "tool_call_id"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "attempt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "maxLength": 1024 } } },
     "approval_decide": { "type": "object", "additionalProperties": false, "required": ["request_id", "approval_id", "decision"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "approval_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "decision": { "enum": ["approve", "reject", "escalate"] }, "reason": { "type": "string", "maxLength": 1024 }, "on_behalf": { "type": "object", "additionalProperties": false, "required": ["subject", "person"], "properties": { "subject": { "type": "string", "maxLength": 256, "minLength": 1 }, "person": { "type": "string", "maxLength": 256, "minLength": 1 }, "groups": { "type": "array", "maxItems": 64, "items": { "type": "string", "maxLength": 256 } }, "tenant": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } } }, "passkey": { "type": "object", "additionalProperties": false, "required": ["credential_id", "client_data_json", "authenticator_data", "signature"], "properties": { "credential_id": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" }, "client_data_json": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" }, "authenticator_data": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" }, "signature": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" } } }, "asserted": { "type": "object", "additionalProperties": false, "required": [], "properties": { "model": { "type": "string", "maxLength": 128 }, "version": { "type": "string", "maxLength": 64 }, "prompt_hash": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } } } },
     "approval_decide_on_behalf": { "type": "object", "additionalProperties": false, "required": ["request_id", "approval_id", "decision", "approver"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "approval_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "decision": { "enum": ["approve", "reject"] }, "approver": { "type": "string", "maxLength": 64, "pattern": "^slack:[A-Z0-9]+/[A-Z0-9]+(?![\\s\\S])" }, "groups": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 64, "pattern": "^slack:[A-Z0-9]+/[A-Z0-9]+(?![\\s\\S])" } } } },
@@ -21,7 +21,7 @@ export const REQUESTS = {
     "delegate_run": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token", "identity"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "identity": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } } },
     "tailer_lost": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "reason", "offset"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "reason": { "type": "string", "maxLength": 1024 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } },
     "tailer_heartbeat": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } },
-    "observe_effect": { "type": "object", "additionalProperties": false, "required": ["request_id", "instance", "effects"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "instance": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "effects": { "type": "array", "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": ["kind", "host", "port", "bytes_out", "bytes_in", "connections", "first_ts", "last_ts"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "kind": { "const": "net" }, "host": { "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9._:-]+(?![\\s\\S])" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "bytes_out": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "bytes_in": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "first_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "last_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" } } } }, "check": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } } } },
+    "observe_effect": { "type": "object", "additionalProperties": false, "required": ["request_id", "instance", "effects"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "instance": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "effects": { "type": "array", "maxItems": 256, "items": { "oneOf": [{ "type": "object", "additionalProperties": false, "required": ["kind", "host", "port", "bytes_out", "bytes_in", "connections", "first_ts", "last_ts"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "kind": { "const": "net" }, "host": { "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9._:-]+(?![\\s\\S])" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "bytes_out": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "bytes_in": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "first_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "last_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary"], "properties": { "kind": { "const": "exec" }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "parent_exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary"], "properties": { "kind": { "const": "exit" }, "status": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "signal": { "type": "string", "maxLength": 32 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary", "host", "port"], "properties": { "kind": { "const": "connect" }, "host": { "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9._:-]+(?![\\s\\S])" }, "port": { "type": "integer", "minimum": 0, "maximum": 65535 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary", "path"], "properties": { "kind": { "const": "file" }, "path": { "type": "string", "maxLength": 4096, "minLength": 1 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "change"], "properties": { "kind": { "const": "policy" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "change": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_.-]+(?![\\s\\S])" }, "policy_hash": { "type": "string", "maxLength": 128, "minLength": 1 }, "by": { "type": "string", "maxLength": 256, "minLength": 1 }, "detail_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "reason"], "properties": { "kind": { "const": "lost" }, "reason": { "type": "string", "maxLength": 1024, "minLength": 1 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } } }] } }, "check": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } }, "sensor": { "enum": ["tetragon", "falco", "openshell"] }, "callers": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } }, "lost": { "type": "string", "maxLength": 1024 } } },
     "status": { "type": "object", "additionalProperties": false, "required": [], "properties": {} },
     "read": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "from_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } } },
     "checkpoint_nudge": { "type": "object", "additionalProperties": false, "required": [], "properties": {} },
@@ -30,6 +30,8 @@ export const REQUESTS = {
     "content_get": { "type": "object", "additionalProperties": false, "required": ["run_id", "seqs", "purpose"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "seqs": { "type": "array", "maxItems": 1000, "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "purpose": { "type": "string", "maxLength": 512, "minLength": 1 } } },
     "content_erase": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "reason": { "type": "string", "maxLength": 1024 } } },
     "why_finding": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "finding"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "finding": { "type": "object", "additionalProperties": false, "required": ["target", "intervention", "n", "p_with", "p_without", "effect", "interval", "verdict", "replay_runs", "models", "rung", "off_tape", "investigation", "looks", "family", "min_effect", "applied", "stopped"], "properties": { "target": { "type": "string", "maxLength": 1024 }, "intervention": { "type": "string", "maxLength": 1024 }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "p_with": { "type": "number", "minimum": 0, "maximum": 1 }, "p_without": { "type": "number", "minimum": 0, "maximum": 1 }, "effect": { "type": "number", "minimum": -1, "maximum": 1 }, "interval": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": -1, "maximum": 1 } }, "verdict": { "enum": ["causal", "suppressive", "ruled-out", "inconclusive", "not-applied"] }, "replay_runs": { "type": "array", "maxItems": 4096, "items": { "type": "object", "additionalProperties": false, "required": ["run_id", "arm", "hit"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "arm": { "enum": ["control", "ablated"] }, "hit": { "type": "boolean" } } } }, "models": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 128 } }, "rung": { "enum": [1, 2] }, "off_tape": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "investigation": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "looks": { "type": "integer", "minimum": 1, "maximum": 4096 }, "family": { "type": "integer", "minimum": 1, "maximum": 4096 }, "min_effect": { "type": "number", "minimum": 0, "maximum": 1 }, "applied": { "type": "boolean" }, "stopped": { "enum": ["decisive", "futility", "n_max", "budget"] }, "uncounted": { "type": "array", "maxItems": 4096, "items": { "type": "object", "additionalProperties": false, "required": ["run_id", "reason"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "reason": { "enum": ["ranking", "budget"] } } } } } } } },
+    "review_finding": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "review"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "review": { "type": "object", "additionalProperties": false, "required": ["reviewer", "verdict", "cites"], "properties": { "reviewer": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._/+-]+(?![\\s\\S])" }, "cites": { "type": "array", "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": ["run_seq", "hash"], "properties": { "run_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hash": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } } }, "verdict": { "oneOf": [{ "type": "object", "additionalProperties": false, "required": ["kind", "rule", "severity"], "properties": { "kind": { "const": "finding" }, "rule": { "enum": ["TK-X201", "TK-X202", "TK-X203", "TK-X204", "TK-X205", "TK-X206", "TK-X207", "TK-X208", "TK-X210", "TK-X101", "TK-X102", "TK-X103", "TK-X104", "TK-X111", "TK-X112", "TK-X113", "TK-X114", "TK-X120", "TK-X211"] }, "severity": { "enum": ["info", "low", "medium", "high", "critical"] }, "tier": { "enum": ["gateway", "harness", "transcript", "sdk"] }, "order": { "enum": ["signed_before", "transcript_order", "after"] }, "redacted": { "type": "boolean" }, "lifted": { "type": "boolean" }, "digests": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } }, "alignment": { "enum": ["ok", "drift", "misaligned"] }, "reason": { "enum": ["none", "unrequested_action", "unexplained_action", "contradicted_reasoning", "scope_creep", "workaround", "false_success", "followed_tool_output", "injection", "other"] }, "asserted": { "type": "object", "additionalProperties": false, "required": ["model", "version", "prompt_hash"], "properties": { "model": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:/@+-]+(?![\\s\\S])" }, "version": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:/@+-]+(?![\\s\\S])" }, "prompt_hash": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } }, "families": { "type": "object", "additionalProperties": false, "required": ["reviewer", "agent"], "properties": { "reviewer": { "enum": ["anthropic", "openai", "google", "meta", "mistral", "deepseek", "qwen", "xai", null] }, "agent": { "type": "array", "maxItems": 8, "items": { "enum": ["anthropic", "openai", "google", "meta", "mistral", "deepseek", "qwen", "xai"] } } } }, "window": { "type": "object", "additionalProperties": false, "required": ["grace_s", "skew_s"], "properties": { "grace_s": { "type": "number", "minimum": 0, "maximum": 86400 }, "skew_s": { "type": "number", "minimum": 0, "maximum": 86400 } } } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "rule", "severity", "checks"], "properties": { "kind": { "const": "coverage" }, "rule": { "const": "TK-X200" }, "severity": { "const": "info" }, "checks": { "type": "object", "additionalProperties": false, "required": [], "properties": { "TK-X201": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X202": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X203": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X204": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X205": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X206": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X207": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X208": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X210": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X101": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X102": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X103": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X104": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X111": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X112": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X113": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X114": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X120": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X211": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } } } }, "partial": { "type": "boolean" }, "reasoning": { "type": "object", "additionalProperties": false, "required": [], "properties": { "full": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "summary": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "withheld": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "none": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } }] } } } } },
+    "constraint_add": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "constraint"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "constraint": { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "enum": ["keep_away", "only_change", "read_only", "no_push", "no_network"] }, "object": { "type": "string", "maxLength": 256, "minLength": 1 } } } } },
     "incident_list": { "type": "object", "additionalProperties": false, "required": [], "properties": { "state": { "enum": ["open", "resolved"] }, "cursor": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } } },
     "incident_show": { "type": "object", "additionalProperties": false, "required": ["incident_id"], "properties": { "incident_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } } },
     "incident_resolve": { "type": "object", "additionalProperties": false, "required": ["request_id", "incident_id"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "incident_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "reason": { "type": "string", "maxLength": 1024 } } },

package/dist/verify/cli.js

@@ -3,6 +3,7 @@
  * CLI's report and exit codes (0 verified, 1 failed, 2 unusable or unverifiable, 3 a warning under --strict).
  */
 import { readFile } from "node:fs/promises";
+import { asJson } from "./explain.js";
 import { EXIT_BAD, EXIT_OK, EXIT_WARN, formatReport, verify } from "./index.js";
 const USAGE = "usage: tracekit verify BUNDLE --trust TRUST.json [--json] [--strict]";
 export async function main(argv) {
@@ -19,7 +20,7 @@ export async function main(argv) {
             bundle = a;
         else {
             console.error(`tracekit verify: ${a} is not supported by the TypeScript verifier (the format bridge, monitor reports `
-                + `and revocations need the reference verifier: pip install tracekit)\n${USAGE}`);
+                + `and revocations need the reference verifier: pip install tracekit-ai)\n${USAGE}`);
             return EXIT_BAD;
         }
     }
@@ -35,11 +36,10 @@ export async function main(argv) {
         console.error(`tracekit verify: ${e.message}`);
         return EXIT_BAD;
     }
-    const { report, code: verdict } = await verify(...data);
+    const { report, code: verdict } = await verify(...data, { bundle, trust });
     const code = verdict === EXIT_OK && strict && report.warnings.length ? EXIT_WARN : verdict;
     if (json)
-        console.log(JSON.stringify({ exit_code: code, checks: report.checks, failures: report.failures,
-            warnings: report.warnings, integrity: report.integrity, assurance: report.assurance, notes: report.notes }, null, 2));
+        console.log(JSON.stringify(asJson(report, code), null, 2));
     else
         process.stdout.write(formatReport(report));
     return code;

package/dist/verify/explain.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What the browser verifier (web.ts) says about a report, in plain words: the verdict and what it does and doesn't
+ * mean, what to do next, a line per check on what it means (docs/verdicts.md, shortened), and a summary of the bundle's
+ * runs. The report itself is the CLI's, unchanged: this module only reads it. No DOM, so Node tests it.
+ */
+import { type Report } from "./index.js";
+export type Names = {
+    bundle: string;
+    trust: string | null;
+};
+export type Verdict = {
+    word: "VERIFIED" | "FAILED" | "UNVERIFIABLE";
+    means: string;
+    notMeans: string;
+};
+/** A step: what to do, and the command to run for it, if any. */
+export type Step = {
+    text: string;
+    command?: string;
+};
+/** `s` as one shell argument (POSIX shells; the page doesn't know the reader's). */
+export declare const sh: (s: string) => string;
+/** The report as `tracekit verify --json` prints it (cli.ts prints this). */
+export declare const asJson: (rep: Report, code: number) => {
+    findings?: string | undefined;
+    exit_code: number;
+    checks: import("./index.js").Check[];
+    failures: string[];
+    warnings: string[];
+    integrity: string;
+    assurance: string;
+    notes: string[];
+};
+/** The report as `tracekit verify` prints it, then its exit code. */
+export declare const asText: (rep: Report, code: number) => string;
+/** What the command-line verifiers exit with for the same files, where that is known: they refuse a v2 bundle without a
+ * trust file, and the Python one checks what this verifier doesn't (and v1 bundles, against signer.pub). */
+export declare function cliExit(rep: Report): string;
+export declare function verdict(rep: Report, code: number): Verdict;
+/** What to do after a result that isn't plainly VERIFIED: what to check or ask for, with the commands that do it. */
+export declare function nextSteps(rep: Report, code: number, names: Names): Step[];
+/** One line per check: what it means (docs/verdicts.md#lines). */
+export declare const MEANING: Record<string, string>;
+/** A few plain facts about the bundle's runs, from their records ({name: bytes}, the runs/ files, a run's parts read as
+ * one), cleaned as the report is; names an agent chose are quoted, so they can't read as the signer's words around them. */
+export declare function summarize(files: Map<string, Uint8Array>, rep: Report): [string, string][];