failproofai 1.0.12-beta.0 → 1.0.12-beta.2

package/src/hooks/semantic/combine.ts

@@ -236,7 +236,7 @@ import type { PolicyAuthority } from "../policy-types";
 // shape check the row's own `jevModel` does. Importing them makes a rename a
 // compile error here. `jev-activity.ts` is pure (no node imports, no semantic
 // modules), so this costs the hook path nothing.
-import { JEV_MODEL_RE, JEV_REASON_REQUEST_CUT } from "../jev-activity";
+import { JEV_MODEL_RE, JEV_REASON_REQUEST_CUT, type JevCheckRecord } from "../jev-activity";
 
 export type Decision = "allow" | "deny" | "instruct";
 export type JevMode = "observe" | "enforce";
@@ -287,6 +287,11 @@ export type JevReview =
       origin?: { packId: string; packVersion?: string };
       /** Semantic policies whose questions were in the request that was answered. */
       asked: readonly string[];
+      /**
+       * What each asked check concluded (`jevChecks` on the activity row).
+       * Recorded only; nothing here decides from it. Absent: not recorded.
+       */
+      checks?: readonly JevCheckRecord[];
       /**
        * Of `asked`, the ones whose answer lets a reviewable regex verdict be
        * cleared: `none`, `overridden`, or a deny the human's task softened to
@@ -330,6 +335,14 @@ export type JevReview =
        * / `request-cut`.
        */
       requestCut: boolean;
+      /**
+       * What the checks of an `observe` FailproofAI Cloud assignment would have
+       * done. Recorded on the row's `observed` list, never applied: they are in
+       * neither `asked` nor `notDenied`, so they clear nothing either.
+       */
+      observedCloud?: ReadonlyArray<ObservedCloudVerdict>;
+      /** The `observe` Cloud assignments' checks that were asked (names); never in `asked`. */
+      observedAsked?: readonly string[];
       /**
        * Null when nothing had to be sent (no semantic policy applied), or when
        * the answer came from the throttle's cache: a hit's ~0 ms is not a
@@ -358,6 +371,8 @@ export interface TwoTierReview {
    * network instead of holding every hook on the machine behind it.
    */
   releaseRegistry?: () => void;
+  /** The review goes to FailproofAI Cloud (its Jev mode asked), not a local `jev.json`. */
+  cloud?: boolean;
   /** Effective authority + the reviewing semantic policies (empty unless reviewable). */
   authorityOf(p: { name: string; authority?: PolicyAuthority; reviewedBy?: string[] }): {
     authority: PolicyAuthority;
@@ -380,6 +395,7 @@ export interface JevActivityFields {
   jevLatencyMs?: number;
   jevModel?: string;
   jevMode: JevMode;
+  jevChecks?: JevCheckRecord[];
 }
 
 /**
@@ -389,6 +405,14 @@ export interface JevActivityFields {
  * and pack policies already use, so FailproofAI Cloud's policy page counts it
  * with no change on its side.
  */
+/** One observe Cloud assignment's would-have (see `JevReview.observedCloud`). */
+export interface ObservedCloudVerdict {
+  cloudPolicyId: string;
+  cloudVersion: number;
+  decision: "deny" | "instruct";
+  reason: string;
+}
+
 export interface ObserveVerdict {
   /** `semantic/<check>` — the name enforce mode would have attributed it to. */
   policyName: string;
@@ -518,6 +542,7 @@ export function combineTwoTier(
     ...(review.latencyMs !== null ? { jevLatencyMs: review.latencyMs } : {}),
     ...(review.model ? { jevModel: review.model } : {}),
     jevMode: mode,
+    ...(review.checks ? { jevChecks: [...review.checks] } : {}),
   };
 
   if (mode === "observe") {

package/src/hooks/semantic/jev-client.ts

@@ -469,7 +469,7 @@ async function postJson(url: string, bearer: string, body: unknown, signal: Abor
       body: JSON.stringify(body),
       signal,
       // Never followed. The configured URL is the one `validateBaseUrl` checked
-      // (https, or loopback http in observe mode only); a redirect would hand the
+      // (https, or loopback http); a redirect would hand the
       // answer — the thing that can clear a deny — to an origin nobody checked,
       // plain http included. No provider redirects this POST.
       redirect: "manual",
@@ -536,6 +536,14 @@ export interface NativeTransportOptions {
   allowUnreported?: boolean;
   /** The base URL came from a connection, not from the person (FailproofAI Cloud). */
   derivedBase?: boolean;
+  /**
+   * FailproofAI Cloud: the reply's `cloud` block (its verdict for the Cloud
+   * checks deployed to this machine, CONTRACT C10.4) is carried through as
+   * `JevResponse.cloud`, unvalidated — `parseCloudReply` in `cloud-jev.ts`
+   * validates it field by field. A reply that carries one may come without
+   * `answers` (Cloud's short-circuit asked nothing), which reads as none.
+   */
+  cloudReply?: boolean;
 }
 
 /**
@@ -545,7 +553,12 @@ export interface NativeTransportOptions {
  */
 function normalizeNative(body: unknown, sentModel: string, opts: NativeTransportOptions): JevResponse {
   if (!body || typeof body !== "object" || Array.isArray(body)) throw new JevError("malformed", "Jev returned no object");
-  const b = body as { model?: unknown; answers?: unknown; usage?: unknown; error?: unknown };
+  const b = body as { model?: unknown; answers?: unknown; usage?: unknown; error?: unknown; cloud?: unknown };
+  const cloud = opts.cloudReply && b.cloud !== undefined ? { cloud: b.cloud } : {};
+  if ((typeof b.answers !== "object" || b.answers === null) && "cloud" in cloud && b.error === undefined) {
+    // Cloud's short-circuit: nothing was asked, so there is nothing to answer.
+    return { model: typeof b.model === "string" ? scrubSecret(b.model, opts.apiKey) : "", answers: {}, ...cloud };
+  }
   if (typeof b.answers !== "object" || b.answers === null) {
     // Gateways sometimes report an upstream failure inside a 200.
     if (b.error !== undefined) {
@@ -576,6 +589,7 @@ function normalizeNative(body: unknown, sentModel: string, opts: NativeTransport
     answers: b.answers as JevResponse["answers"],
     ...(usage ? { usage } : {}),
     ...(unverified ? { modelUnverified: true } : {}),
+    ...cloud,
   };
 }
 
@@ -1146,6 +1160,9 @@ export function transportForConfig(input: JevConfig): { transport: JevTransport;
             // `readAnswers` then holds the reported id to the 1.13 family.
             allowUnreported: false,
             derivedBase: true,
+            // Cloud's verdict for its own checks, when the request asked for
+            // it (a `cloud` block, CONTRACT C10.3).
+            cloudReply: true,
           }),
         ),
         via: "failproofai",

package/src/hooks/semantic/jev-config.ts

@@ -89,8 +89,8 @@
  */
 import { closeSync, constants as fsConstants, fstatSync, openSync, readSync, statSync } from "node:fs";
 import { dirname } from "node:path";
-import { readJevCloudCredential, type JevCloudCredential } from "../fp-config";
-import { jevConfigFile } from "../fp-home";
+import { readConfig, readCredentials, readJevCloudCredential, type JevCloudCredential } from "../fp-config";
+import { configFile, credentialsFile, jevConfigFile } from "../fp-home";
 
 export type { JevCloudCredential } from "../fp-config";
 
@@ -179,6 +179,15 @@ export const JEV_API_KEY_ENV = "FAILPROOFAI_JEV_API_KEY";
  * the evaluator; the two are pinned equal by a test.
  */
 export const JEV_CONFIG_DEFAULT_TIMEOUT_MS = 3_000;
+/**
+ * How long one call waits for FailproofAI Cloud when Cloud's Jev mode asks
+ * (CONTRACT C10.2). Longer than the local default above: the call makes one
+ * more hop (Cloud selects this machine's checks, forwards to Jev, and decides
+ * them) before it answers. A local BYOK `jev.json` keeps its own `timeoutMs`
+ * or the default; this one is fixed, because under a Cloud mode `jev.json` is
+ * not read at all. Past it, the regex decides alone, as for any fallback.
+ */
+export const CLOUD_JEV_TIMEOUT_MS = 5_000;
 /** Bounds on `timeoutMs`. Every millisecond of it can be added to a tool call. */
 export const MIN_JEV_TIMEOUT_MS = 100;
 export const MAX_JEV_TIMEOUT_MS = 10_000;
@@ -318,8 +327,7 @@ function credentialQueryProblem(url: URL): string | null {
  * An endpoint base URL: https, or http to a loopback host only (a local proxy).
  * No credentials in the URL — not as userinfo, not as a query parameter — and no
  * fragment, because a key belongs in the key field, where it is sent as a bearer
- * and never printed. `validateJevConfig` further accepts the loopback http form
- * only in observe mode.
+ * and never printed. Loopback http is accepted in every mode.
  */
 export function validateBaseUrl(raw: unknown): ValidationResult<string> {
   if (typeof raw !== "string" || raw.trim() === "") return { ok: false, problem: "baseUrl must be a non-empty string" };
@@ -474,14 +482,6 @@ export function providerHostConflict(provider: string, url: string): string | nu
     : null;
 }
 
-function isPlainHttp(url: string): boolean {
-  try {
-    return new URL(url).protocol === "http:";
-  } catch {
-    return false;
-  }
-}
-
 /**
  * The origin a bearer token would be sent to: https, or http to a loopback host
  * — the same schemes `validateBaseUrl` admits. Null for anything else, so a
@@ -618,7 +618,15 @@ export function validateJevConfig(
     };
   }
 
-  const cfg: JevConfig = { provider: kind, apiKey, mode: DEFAULT_JEV_MODE, timeoutMs: JEV_CONFIG_DEFAULT_TIMEOUT_MS };
+  // The FailproofAI Cloud provider waits as long as a Cloud Jev mode does (B9):
+  // the same extra hop, and `jev setup --provider failproofai` printing 3000 ms
+  // misstated what FailproofAI Cloud is given.
+  const cfg: JevConfig = {
+    provider: kind,
+    apiKey,
+    mode: DEFAULT_JEV_MODE,
+    timeoutMs: kind === JEV_CLOUD_PROVIDER ? CLOUD_JEV_TIMEOUT_MS : JEV_CONFIG_DEFAULT_TIMEOUT_MS,
+  };
 
   if (o.baseUrl !== undefined) {
     const r = validateBaseUrl(o.baseUrl);
@@ -680,23 +688,11 @@ export function validateJevConfig(
     cfg.mode = mode;
   }
 
-  // Plain http reaches only a loopback host (`validateBaseUrl`), and nothing
-  // authenticates the server there: while the local proxy is down, any process
-  // of this user — the agent being judged included — can bind its port and
-  // answer "none" to every question. In enforce mode that answer clears
-  // reviewable denies; in observe mode it changes nothing, and `off` sends
-  // nothing at all, so enforce is the one mode it is refused in.
-  if (cfg.baseUrl !== undefined && isPlainHttp(cfg.baseUrl) && cfg.mode === "enforce") {
-    return {
-      ok: false,
-      problem:
-        "plain http (to localhost) is accepted only with mode observe: in enforce mode Jev's answers can clear a deny, " +
-        "and while the local proxy is down any process on this machine could take its port and answer. " +
-        (cfg.provider === JEV_CLOUD_PROVIDER
-          ? "Reconnect to an https FailproofAI Cloud URL (failproofai config --token <key> --url https://…), or keep mode observe"
-          : "Use https, or mode observe"),
-    };
-  }
+  // Plain http reaches only a loopback host (`validateBaseUrl`) and is
+  // accepted in every mode, enforce included, so a local stack can be tested
+  // as it runs in production. Risk: nothing authenticates a loopback server,
+  // so while it is down any process of this user could bind its port and
+  // answer; use https wherever that matters.
 
   return { ok: true, value: cfg };
 }
@@ -1090,6 +1086,159 @@ export function loadJevConfig(): JevConfig | null {
   }
 }
 
+// ── FailproofAI Cloud sets the mode ──────────────────────────────────────────
+
+export interface CloudModeJevConfig {
+  /**
+   * The config to run with: provider `failproofai` on the Cloud Jev
+   * credential, with Cloud's mode — or null: Jev does not run.
+   */
+  config: JevConfig | null;
+  /**
+   * This machine's FailproofAI Cloud machine id (`credentials.json`
+   * `cloud.machine_id`), sent in the request's `cloud` block so Cloud can find
+   * the checks deployed to this machine. Null when there is none.
+   */
+  machineId: string | null;
+  /**
+   * Why Jev cannot run in Cloud's mode, for `errors.json` — null when it runs,
+   * and null for `off`, which is not a problem:
+   * - `transcripts_disabled`: connected for decisions only (`--no-transcripts`);
+   * - `jev_unconfigured`: no Cloud Jev credential at all;
+   * - `jev_unconfigured: <detail>`: one exists and cannot be used.
+   */
+  problem: string | null;
+}
+
+/** The contract's message for "Cloud set a Jev mode and this machine has no Cloud Jev credential". */
+export const JEV_UNCONFIGURED_PROBLEM = "jev_unconfigured";
+/** The contract's message for "Cloud set a Jev mode on a decisions-only connection" (CONTRACT C10.2). */
+export const TRANSCRIPTS_DISABLED_PROBLEM = "transcripts_disabled";
+
+/**
+ * The config to run when FailproofAI Cloud sets this machine's Jev mode
+ * (`active.json` `jevMode`) to `observe` or `enforce` (CONTRACT C10.2).
+ *
+ * The provider is ALWAYS FailproofAI Cloud, on the Cloud Jev credential
+ * (`credentials.json` `jev {url,key}`, only while its connection is still on
+ * this machine), at `<cloud base>/enforcement/v1/jev` — the checks Cloud
+ * deployed to this machine live there, and the verdict for them is computed
+ * there. A local `jev.json` is NOT used while Cloud sets a mode, BYOK provider
+ * or not: Cloud wins, a local `off` included.
+ *
+ * Jev does not run, and `problem` says why, when:
+ * 1. the machine was connected for decisions only (`collector.sessions` is not
+ *    `true` in `config.json` — what `--no-transcripts` writes): the standing
+ *    rule is that such a connection never switches Jev on, because a Jev call
+ *    sends the tool call and the recent prompt;
+ * 2. there is no Cloud Jev credential, or it cannot be used;
+ * 3. there is no FailproofAI Cloud machine id to name.
+ *
+ * Asked twice per gate event on a machine whose Cloud mode asks — once for the
+ * review, once for `errors.json` — and on every event in the warm worker, so
+ * the answer is kept until an input changes (see `jevInputsVersion`).
+ *
+ * Never throws.
+ */
+export function loadJevConfigForCloudMode(mode: JevConfigMode): CloudModeJevConfig {
+  if (mode === "off") return { config: null, machineId: null, problem: null };
+  const key = `${mode}\u0000${jevInputsVersion()}`;
+  if (cloudModeMemo?.key === key) return cloudModeMemo.value;
+  const value = computeCloudModeConfig(mode);
+  cloudModeMemo = { key, value };
+  return value;
+}
+
+let cloudModeMemo: { key: string; value: CloudModeJevConfig } | null = null;
+
+/** Forget the memoised answer. Tests only. */
+export function _resetJevConfigMemoForTest(): void {
+  cloudModeMemo = null;
+}
+
+/**
+ * Everything a Cloud-mode config load reads, as one version string: the
+ * credentials file and its directory (whose modes the loader checks), and
+ * `config.json` (the decisions-only switch), plus where those paths point. A
+ * file's version is its device, inode, mode, size and modification and change
+ * times to the nanosecond — an edit, a chmod and a replace-by-rename all move
+ * it, and the change time cannot be set back by the user.
+ */
+function jevInputsVersion(): string {
+  const credentials = credentialsFile();
+  const config = configFile();
+  return [
+    process.platform,
+    credentials,
+    statVersion(credentials),
+    statVersion(dirname(credentials)),
+    config,
+    statVersion(config),
+  ].join("\u0000");
+}
+
+function statVersion(path: string): string {
+  try {
+    const st = statSync(path, { bigint: true });
+    return `${st.dev}:${st.ino}:${st.mode}:${st.size}:${st.mtimeNs}:${st.ctimeNs}`;
+  } catch (err) {
+    return `-${(err as NodeJS.ErrnoException).code ?? "error"}`;
+  }
+}
+
+function computeCloudModeConfig(mode: JevConfigMode): CloudModeJevConfig {
+  try {
+    // Decisions only: checked first, because no credential would change it.
+    if (readConfig().collector.sessions !== true) {
+      return { config: null, machineId: null, problem: TRANSCRIPTS_DISABLED_PROBLEM };
+    }
+    const credential = readJevCloudCredential();
+    if (credential.status === "absent") return { config: null, machineId: null, problem: JEV_UNCONFIGURED_PROBLEM };
+    if (credential.status === "refused") {
+      return {
+        config: null,
+        machineId: null,
+        problem: `${JEV_UNCONFIGURED_PROBLEM}: the FailproofAI Cloud Jev credential is refused — ${credential.problem}`,
+      };
+    }
+    const machineId = readCredentials().cloud?.machineId || null;
+    if (!machineId) {
+      return {
+        config: null,
+        machineId: null,
+        problem: `${JEV_UNCONFIGURED_PROBLEM}: this machine has no FailproofAI Cloud machine id (no policy connection in credentials.json)`,
+      };
+    }
+    const raw = {
+      provider: JEV_CLOUD_PROVIDER,
+      baseUrl: jevCloudBaseUrl(cloudBaseFor(credential.credential)),
+      mode,
+      timeoutMs: CLOUD_JEV_TIMEOUT_MS,
+    };
+    const r = validateJevConfig(raw, null, credential.credential);
+    return r.ok
+      ? { config: r.value, machineId, problem: null }
+      : { config: null, machineId, problem: `${JEV_UNCONFIGURED_PROBLEM}: the FailproofAI Cloud Jev credential — ${r.problem}` };
+  } catch (err) {
+    return { config: null, machineId: null, problem: `${JEV_UNCONFIGURED_PROBLEM}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/**
+ * The Cloud base URL the Jev route hangs off: the connection's own URL when it
+ * is on the credential's origin (so a Cloud served under a path prefix keeps
+ * it, as `config --token` writes it), else the credential's origin.
+ */
+function cloudBaseFor(credential: JevCloudCredential): string {
+  try {
+    const cloud = readCredentials().cloud;
+    if (cloud?.url && new URL(cloud.url).origin === new URL(credential.url).origin) return cloud.url;
+  } catch {
+    // Fall through to the origin.
+  }
+  return credential.url;
+}
+
 export interface JevConfigFileForUpdate {
   raw: Record<string, unknown>;
   /** The file's permission bits (null where they mean nothing). */