@attest-ai/core 1.0.0-rc.4 → 1.0.0-rc.5

package/dist/esm/index.js

@@ -219,8 +219,8 @@ function extractId(response) {
 }
 
 // src/version.ts
-var VERSION = "1.0.0-rc.4";
-var ENGINE_VERSION = "1.0.0-rc.4";
+var VERSION = "1.0.0-rc.5";
+var ENGINE_VERSION = "1.0.0-rc.5";
 
 // src/engine-manager.ts
 import { spawn, spawnSync } from "child_process";
@@ -288,7 +288,7 @@ function httpsGet(url, redirectCount = 0) {
       new Error(`Too many redirects (>${MAX_REDIRECTS}) following ${url}`)
     );
   }
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const client = url.startsWith("https:") ? https : http;
     client.get(url, (res) => {
       const status = res.statusCode ?? 0;
@@ -299,7 +299,7 @@ function httpsGet(url, redirectCount = 0) {
           return;
         }
         res.resume();
-        resolve4(httpsGet(location, redirectCount + 1));
+        resolve5(httpsGet(location, redirectCount + 1));
         return;
       }
       if (status < 200 || status >= 300) {
@@ -309,7 +309,7 @@ function httpsGet(url, redirectCount = 0) {
       }
       const chunks = [];
       res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => resolve4(Buffer.concat(chunks)));
+      res.on("end", () => resolve5(Buffer.concat(chunks)));
       res.on("error", reject);
     }).on("error", reject);
   });
@@ -536,11 +536,11 @@ var EngineManager = class {
     }
     this.requestId += 1;
     const requestStr = encodeRequest(this.requestId, method, params);
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve5, reject) => {
       const onLine = (line) => {
         try {
           const response = decodeResponse(line);
-          resolve4(extractResult(response));
+          resolve5(extractResult(response));
         } catch (err) {
           reject(err);
         }
@@ -907,12 +907,12 @@ var AttestClient = class {
       throw new Error("Engine process not started.");
     }
     let capturedReqId;
-    const requestPromise = new Promise((resolve4, reject) => {
+    const requestPromise = new Promise((resolve5, reject) => {
       this.writeChain = this.writeChain.then(() => {
         this.requestId += 1;
         const reqId = this.requestId;
         capturedReqId = reqId;
-        this.pending.set(reqId, { resolve: resolve4, reject });
+        this.pending.set(reqId, { resolve: resolve5, reject });
         const requestStr = encodeRequest(reqId, method, params);
         cp.stdin.write(requestStr, (err) => {
           if (err) {
@@ -1027,6 +1027,26 @@ function requireSimulationCapability(init) {
 
 // src/trace.ts
 import { randomUUID } from "crypto";
+
+// src/simulation/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var activeMockRegistry = new AsyncLocalStorage();
+function createRng(seed) {
+  if (seed === void 0) return Math.random;
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
+}
+
+// src/trace.ts
 var TraceBuilder = class {
   traceId;
   agentId;
@@ -1058,11 +1078,22 @@ var TraceBuilder = class {
     return this;
   }
   addToolCall(name, options2) {
+    const mock = activeMockRegistry.getStore()?.get(name);
+    let result = options2?.result;
+    if (mock !== void 0) {
+      const mocked = mock(options2?.args ?? {});
+      if (typeof mocked?.then === "function") {
+        throw new Error(`mock for tool '${name}' returned a Promise; mock tools must be synchronous`);
+      }
+      if (typeof mocked === "object" && mocked !== null && !Array.isArray(mocked)) {
+        result = mocked;
+      }
+    }
     this.steps.push({
       type: STEP_TOOL_CALL,
       name,
       args: options2?.args,
-      result: options2?.result,
+      result,
       metadata: options2?.metadata
     });
     return this;
@@ -2717,18 +2748,18 @@ function serve(engine, args) {
   let stdout = "";
   let stderr = "";
   let resolveReady = () => void 0;
-  const ready = new Promise((resolve4) => {
-    resolveReady = resolve4;
+  const ready = new Promise((resolve5) => {
+    resolveReady = resolve5;
   });
-  const exited = new Promise((resolve4) => {
+  const exited = new Promise((resolve5) => {
     child.on("close", (code, signal) => {
       resolveReady(null);
-      resolve4({ code, signal });
+      resolve5({ code, signal });
     });
     child.on("error", (err) => {
       stderr += err.message;
       resolveReady(null);
-      resolve4({ code: null, signal: null });
+      resolve5({ code: null, signal: null });
     });
   });
   child.stdout.setEncoding("utf8").on("data", (chunk) => {
@@ -2985,18 +3016,18 @@ async function start(name, mode, opts) {
   let stdout = "";
   let stderr = "";
   let resolveReady = () => void 0;
-  const ready = new Promise((resolve4) => {
-    resolveReady = resolve4;
+  const ready = new Promise((resolve5) => {
+    resolveReady = resolve5;
   });
-  const exited = new Promise((resolve4) => {
+  const exited = new Promise((resolve5) => {
     child.on("close", (code) => {
       resolveReady(null);
-      resolve4(code);
+      resolve5(code);
     });
     child.on("error", (err) => {
       stderr += err.message;
       resolveReady(null);
-      resolve4(null);
+      resolve5(null);
     });
   });
   child.stdout.setEncoding("utf8").on("data", (chunk) => {
@@ -3121,18 +3152,18 @@ async function start2(file, opts) {
   let stdout = "";
   let stderr = "";
   let resolveReady = () => void 0;
-  const ready = new Promise((resolve4) => {
-    resolveReady = resolve4;
+  const ready = new Promise((resolve5) => {
+    resolveReady = resolve5;
   });
-  const exited = new Promise((resolve4) => {
+  const exited = new Promise((resolve5) => {
     child.on("close", (code) => {
       resolveReady(null);
-      resolve4(code);
+      resolve5(code);
     });
     child.on("error", (err) => {
       stderr += err.message;
       resolveReady(null);
-      resolve4(null);
+      resolve5(null);
     });
   });
   child.stdout.setEncoding("utf8").on("data", (chunk) => {
@@ -3213,8 +3244,8 @@ function parseFinal(out) {
 }
 
 // src/context.ts
-import { AsyncLocalStorage } from "async_hooks";
-var activeBuilder = new AsyncLocalStorage();
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+var activeBuilder = new AsyncLocalStorage2();
 
 // src/agent.ts
 var Agent = class {
@@ -3301,6 +3332,9 @@ function tier(level) {
 }
 
 // src/plugins.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "fs";
+import { dirname as dirname2, join as join4, relative as relative2, resolve as resolve4, isAbsolute, sep as sep2 } from "path";
+import { pathToFileURL } from "url";
 var PluginRegistry = class {
   plugins = /* @__PURE__ */ new Map();
   register(name, plugin) {
@@ -3331,10 +3365,19 @@ var PluginRegistry = class {
 };
 async function executePluginAssertion(plugin, trace, spec, client, traceId2, assertionId2, timeoutMs = 3e4) {
   const resultPromise = Promise.resolve(plugin.execute(trace, spec));
+  let timer;
   const timeoutPromise = new Promise((_, reject) => {
-    setTimeout(() => reject(new Error(`Plugin '${plugin.name}' timed out after ${timeoutMs}ms`)), timeoutMs);
+    timer = setTimeout(
+      () => reject(new Error(`Plugin '${plugin.name}' timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    );
   });
-  const result = await Promise.race([resultPromise, timeoutPromise]);
+  let result;
+  try {
+    result = await Promise.race([resultPromise, timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
   await client.submitPluginResult(
     traceId2,
     plugin.name,
@@ -3345,6 +3388,100 @@ async function executePluginAssertion(plugin, trace, spec, client, traceId2, ass
   );
   return result;
 }
+function registerPlugin(registry, name, plugin) {
+  registry.register(name, plugin);
+}
+function isAttestPlugin(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v["name"] === "string" && typeof v["pluginType"] === "string" && typeof v["execute"] === "function";
+}
+function readJson(path5) {
+  return JSON.parse(readFileSync2(path5, "utf8"));
+}
+function findInstalledPackage(projectRoot, name) {
+  let dir = resolve4(projectRoot);
+  for (; ; ) {
+    const candidate = join4(dir, "node_modules", name);
+    if (existsSync2(join4(candidate, "package.json"))) return candidate;
+    const parent = dirname2(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function declaredPluginPaths(pkgJson, dep) {
+  const attest = pkgJson["attest"];
+  if (attest === void 0) return [];
+  const plugins = typeof attest === "object" && attest !== null ? attest["plugins"] : void 0;
+  if (plugins === void 0) return [];
+  if (!Array.isArray(plugins) || !plugins.every((p) => typeof p === "string")) {
+    throw new Error(`'${dep}': "attest.plugins" must be an array of strings`);
+  }
+  return plugins;
+}
+function pluginsOf(mod) {
+  const def = mod["default"];
+  const nested = typeof def === "object" && def !== null ? def : void 0;
+  for (const candidate of [def, nested?.["default"]]) {
+    if (isAttestPlugin(candidate)) return [candidate];
+  }
+  return [.../* @__PURE__ */ new Set([...Object.values(mod), ...Object.values(nested ?? {})])].filter(isAttestPlugin);
+}
+function isInside(root, file) {
+  const within = (r, f) => {
+    const rel = relative2(r, f);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep2}`) && !isAbsolute(rel);
+  };
+  return within(root, file) && within(realpathSync(root), realpathSync(file));
+}
+async function loadPackagePlugins(registry, projectRoot = process.cwd()) {
+  let project;
+  try {
+    project = readJson(join4(projectRoot, "package.json"));
+  } catch (err) {
+    console.error(`attest: cannot read ${join4(projectRoot, "package.json")}; no plugins loaded:`, err);
+    return 0;
+  }
+  const depNames = /* @__PURE__ */ new Set();
+  for (const field of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const deps = project[field];
+    if (typeof deps === "object" && deps !== null) {
+      for (const dep of Object.keys(deps)) depNames.add(dep);
+    }
+  }
+  let loaded = 0;
+  for (const dep of depNames) {
+    const pkgDir = findInstalledPackage(projectRoot, dep);
+    if (pkgDir === void 0) continue;
+    let entries;
+    try {
+      entries = declaredPluginPaths(readJson(join4(pkgDir, "package.json")), dep);
+    } catch (err) {
+      console.error(`attest: failed to read plugins declared by '${dep}':`, err);
+      continue;
+    }
+    for (const entry of entries) {
+      try {
+        const file = resolve4(pkgDir, entry);
+        if (!isInside(pkgDir, file)) {
+          throw new Error(`plugin path '${entry}' escapes package '${dep}'`);
+        }
+        const mod = await import(pathToFileURL(file).href);
+        const plugins = pluginsOf(mod);
+        if (plugins.length === 0) {
+          throw new Error(`'${entry}' exports no plugin (name, pluginType, execute)`);
+        }
+        for (const plugin of plugins) {
+          registry.register(plugin.name, plugin);
+          loaded++;
+        }
+      } catch (err) {
+        console.error(`attest: failed to load plugin '${entry}' from '${dep}':`, err);
+      }
+    }
+  }
+  return loaded;
+}
 
 // src/continuous.ts
 import { EventEmitter } from "events";
@@ -3724,6 +3861,172 @@ the assistant's response meets your needs. Keep responses concise (1-3 sentences
   max_tokens: 200
 };
 
+// src/simulation/mock-tools.ts
+var MockToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  register(name, fn) {
+    this.tools.set(name, fn);
+  }
+  /**
+   * Run `fn` with the registered mocks active. `TraceBuilder.addToolCall`
+   * returns the mock's result for a registered tool name. Scopes are
+   * isolated per async call chain (AsyncLocalStorage).
+   */
+  run(fn) {
+    return activeMockRegistry.run(new Map(this.tools), fn);
+  }
+};
+function mockTool(name, fn) {
+  const wrapper = ((args) => fn(args));
+  return Object.assign(wrapper, { mockToolName: name });
+}
+
+// src/simulation/fault-inject.ts
+function faultInject(options2, fn) {
+  const errorRate = options2.errorRate ?? 0;
+  const latencyJitterMs = options2.latencyJitterMs ?? 0;
+  const rng = createRng(options2.seed);
+  return async (...args) => {
+    if (errorRate > 0 && rng() < errorRate) {
+      throw new Error(`Injected fault in ${fn.name || "anonymous"}`);
+    }
+    if (latencyJitterMs > 0) {
+      await sleep(rng() * latencyJitterMs);
+    }
+    return fn(...args);
+  };
+}
+
+// src/simulation/verdict.ts
+function aggregateOutcomes(outcomes) {
+  if (outcomes.includes(OUTCOME_FAIL)) return OUTCOME_FAIL;
+  if (outcomes.includes(OUTCOME_SKIP)) return OUTCOME_SKIP;
+  return OUTCOME_PASS;
+}
+function sumNotEvaluatedReasons(results) {
+  const counts = {};
+  for (const r of results) {
+    for (const [reason, n] of Object.entries(r.notEvaluatedReasons)) {
+      counts[reason] = (counts[reason] ?? 0) + n;
+    }
+  }
+  return counts;
+}
+function formatSkipReason(counts) {
+  const parts = Object.entries(counts).map(([reason, n]) => n === 1 ? reason : `${reason} \xD7${n}`);
+  return `not evaluated: ${parts.join(", ")}`;
+}
+function renderVerdictDiagnostics(verdict, color = false) {
+  return verdict instanceof AgentResult ? renderDiagnostics(verdict, { color }) : verdict.renderDiagnostics?.({ color }) ?? "";
+}
+function verdictsDiagnostics(results, label, color = false) {
+  const blocks = results.flatMap(
+    (r, i) => r.outcome() === OUTCOME_PASS ? [] : [`${label} ${i + 1}/${results.length}:${renderVerdictDiagnostics(r, color)}`]
+  );
+  return blocks.length > 0 ? blocks.join("\n") : `  (no failing ${label}s)
+`;
+}
+
+// src/simulation/repeat.ts
+var RepeatResult = class {
+  results;
+  constructor(results = []) {
+    this.results = results;
+  }
+  get count() {
+    return this.results.length;
+  }
+  /** Trials skipped because an assertion was not evaluated. */
+  get notEvaluated() {
+    return this.results.filter((r) => r.outcome() === OUTCOME_SKIP).length;
+  }
+  /** Passing / evaluated trials; null when no trial was evaluated. */
+  get passRate() {
+    const evaluated = this.count - this.notEvaluated;
+    if (evaluated === 0) return null;
+    return this.results.filter((r) => r.outcome() === OUTCOME_PASS).length / evaluated;
+  }
+  /** True when every trial's outcome is pass (soft failures included). */
+  get allPassed() {
+    return this.results.every((r) => r.outcome() === OUTCOME_PASS);
+  }
+  outcome(options2) {
+    return aggregateOutcomes(this.results.map((r) => r.outcome(options2)));
+  }
+  get notEvaluatedReasons() {
+    return sumNotEvaluatedReasons(this.results);
+  }
+  skipReason() {
+    return formatSkipReason(this.notEvaluatedReasons);
+  }
+  renderDiagnostics(options2) {
+    return verdictsDiagnostics(this.results, "trial", options2?.color);
+  }
+};
+function repeat(n, fn) {
+  return async (...args) => {
+    const results = [];
+    for (let i = 0; i < n; i++) {
+      results.push(await fn(...args));
+    }
+    return new RepeatResult(results);
+  };
+}
+
+// src/simulation/scenario.ts
+var ScenarioResult = class {
+  config;
+  results;
+  constructor(config2, results = []) {
+    this.config = config2;
+    this.results = results;
+  }
+  /** True when the aggregate `outcome()` is pass. */
+  get passed() {
+    return this.outcome() === OUTCOME_PASS;
+  }
+  outcome(options2) {
+    return aggregateOutcomes(this.results.map((r) => r.outcome(options2)));
+  }
+  get notEvaluatedReasons() {
+    return sumNotEvaluatedReasons(this.results);
+  }
+  skipReason() {
+    return formatSkipReason(this.notEvaluatedReasons);
+  }
+  renderDiagnostics(options2) {
+    return verdictsDiagnostics(this.results, "turn", options2?.color);
+  }
+};
+function scenario(options2, fn) {
+  const config2 = {
+    persona: options2.persona,
+    mockTools: { ...options2.mockTools },
+    faultErrorRate: options2.faultErrorRate ?? 0,
+    faultLatencyJitterMs: options2.faultLatencyJitterMs ?? 0,
+    maxTurns: options2.maxTurns ?? 1,
+    seed: options2.seed
+  };
+  return async (...args) => {
+    const run = async () => {
+      const results = [];
+      const rng = createRng(config2.seed);
+      for (let turn = 0; turn < config2.maxTurns; turn++) {
+        if (config2.faultErrorRate > 0 && rng() < config2.faultErrorRate) {
+          throw new Error(`Injected fault at turn ${turn}`);
+        }
+        if (config2.faultLatencyJitterMs > 0) {
+          await sleep(rng() * config2.faultLatencyJitterMs);
+        }
+        results.push(await fn({ persona: config2.persona, turn }, ...args));
+      }
+      return new ScenarioResult(config2, results);
+    };
+    const mocks = new Map(Object.entries(config2.mockTools));
+    return mocks.size > 0 ? activeMockRegistry.run(mocks, run) : run();
+  };
+}
+
 // src/adapters/manual.ts
 var ManualAdapter = class {
   agentId;
@@ -3935,7 +4238,7 @@ var OTelAdapter = class _OTelAdapter {
   }
 };
 function runConvert(engine, args, payload) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const child = spawn5(engine, args, { stdio: ["pipe", "pipe", "pipe"] });
     let timer;
     child.on("error", (e) => {
@@ -3988,7 +4291,7 @@ function runConvert(engine, args, payload) {
         );
         return;
       }
-      resolve4(Buffer.concat(out).toString("utf8"));
+      resolve5(Buffer.concat(out).toString("utf8"));
     });
     stdin.end(payload);
   });
@@ -4155,6 +4458,7 @@ export {
   GeminiAdapter,
   LangChainAdapter,
   ManualAdapter,
+  MockToolRegistry,
   OTLPConversionError,
   OTelAdapter,
   OUTCOME_FAIL,
@@ -4174,6 +4478,7 @@ export {
   REASON_REPLAY_MISS,
   REASON_SHORT_CIRCUITED,
   REASON_SIMULATION,
+  RepeatResult,
   ReplayError,
   ReplayMissError,
   ReplayNotEvaluatedError,
@@ -4186,6 +4491,7 @@ export {
   STEP_RETRIEVAL,
   STEP_TOOL_CALL,
   Sampler,
+  ScenarioResult,
   TIER_1,
   TIER_2,
   TIER_3,
@@ -4220,6 +4526,7 @@ export {
   executePluginAssertion,
   extractId,
   extractResult,
+  faultInject,
   firstMiss,
   formatUsage,
   getSampleRate,
@@ -4231,17 +4538,23 @@ export {
   loadFixture,
   loadLabelsCSV,
   loadLabelsJSONL,
+  loadPackagePlugins,
+  mockTool,
   parseUsage,
   previewLine,
   promptHash,
   record,
+  registerPlugin,
   renderAssertionFailure,
   renderDiagnostics,
   renderSummary,
+  renderVerdictDiagnostics,
   renderVitest,
+  repeat,
   requireSimulationCapability,
   resetConfig,
   resolveMode,
+  scenario,
   simulationEnvEnabled,
   startReplay,
   startWorld,