@alumnium/test 0.0.0-stage → 0.24.0

package/src/index.js

@@ -0,0 +1,880 @@
+// test/src/Recording.ts
+import { xxh64Str } from "@js-fns/xxhash/str";
+import z from "zod";
+// test/src/FileTestCache.ts
+import {
+  Env,
+  FileStore,
+  GlobalFileStorePaths,
+  safePathJoin,
+  Telemetry,
+} from "@alumnium/core/internal";
+
+class Recording {
+  static Id = z.string().brand("Recording.Id");
+  static Input = z.record(z.string(), z.unknown());
+  static Content = z.union([
+    z.string(),
+    z.array(z.looseObject({ type: z.string() })),
+  ]);
+  static ToolCall = z.object({
+    id: z.string(),
+    server: z.string().optional(),
+    tool: z.string(),
+    input: this.Input,
+  });
+  static ToolResult = z.object({
+    content: this.Content,
+    isError: z.boolean(),
+  });
+  static ToolStep = z.object({
+    kind: z.literal("tool-call"),
+    call: this.ToolCall,
+    result: this.ToolResult,
+  });
+  static NarrationStep = z.object({
+    kind: z.literal("narration"),
+    narration: z.enum(["thinking", "assistant"]),
+    text: z.string(),
+  });
+  static Step = z.union([this.ToolStep, this.NarrationStep]);
+  static Verdict = z.object({
+    status: z.enum(["success", "failure"]),
+    details: z.string(),
+  });
+  static DEFAULT_VERSION = 1;
+  static Schema = z.object({
+    id: this.Id,
+    version: z.number().int().positive(),
+    text: z.string(),
+    agent: z.string(),
+    alumnium: z.object({ version: z.string() }),
+    hostVars: z.array(z.string()),
+    steps: z.array(this.Step),
+    verdict: this.Verdict,
+  });
+  static textToId(text) {
+    return xxh64Str(text.trim());
+  }
+  static toolKey(call) {
+    return call.server ? `${call.server}/${call.tool}` : call.tool;
+  }
+  static executableStepsCount(recording) {
+    return recording.steps.filter((step) => step.kind !== "narration").length;
+  }
+}
+
+// test/src/FileTestCache.ts
+var { logger } = Telemetry.get("packages/typescript/test/src/FileTestCache.ts");
+
+class FileTestCache {
+  #store;
+  #staged = new Map();
+  #lookups = { hits: 0, misses: 0 };
+  constructor(props = {}) {
+    this.#store = new FileStore(props.dir ?? FileTestCache.defaultDir());
+  }
+  static defaultDir() {
+    return safePathJoin(
+      Env.ALUMNIUM_CACHE_PATH ?? GlobalFileStorePaths.globalSubDir("cache"),
+      "tests",
+    );
+  }
+  get dir() {
+    return this.#store.dir;
+  }
+  get lookups() {
+    return { ...this.#lookups };
+  }
+  async lookup(text, options = {}) {
+    const { version = Recording.DEFAULT_VERSION } = options;
+    const id = Recording.textToId(text);
+    const found = this.#staged.get(id) ?? (await this.#read(id));
+    if (found?.version === version) {
+      logger.debug(`Test cache hit: ${id}`);
+      this.#lookups.hits++;
+      return structuredClone(found);
+    }
+    logger.debug(
+      found
+        ? `Test cache miss: ${id} is recorded in version ${found.version}, not ${version}`
+        : `Test cache miss: ${id}`,
+    );
+    this.#lookups.misses++;
+    return null;
+  }
+  async update(recording) {
+    this.#staged.set(recording.id, structuredClone(recording));
+  }
+  async save() {
+    const staged = [...this.#staged];
+    if (!staged.length) return;
+    logger.debug(`Saving ${staged.length} test recordings...`);
+    await Promise.all(
+      staged.map(([id, recording]) =>
+        this.#store.writeJson(fileName(id), recording),
+      ),
+    );
+    for (const [id, recording] of staged)
+      if (this.#staged.get(id) === recording) this.#staged.delete(id);
+  }
+  async discard() {
+    this.#staged.clear();
+  }
+  async #read(id) {
+    try {
+      return await this.#store.readJson(fileName(id), Recording.Schema);
+    } catch (error) {
+      logger.warn(`Failed to read test recording ${id}: {error}`, { error });
+      return null;
+    }
+  }
+}
+function fileName(id) {
+  return `${id}.json`;
+}
+// test/src/masker/HostVarMasker.ts
+import { Telemetry as Telemetry2 } from "@alumnium/core/internal";
+
+// test/src/masker/maskerUtils.ts
+function eachStringLeaf(container, mapLeaf, path = "") {
+  if (Array.isArray(container)) {
+    container.forEach((item, index) => {
+      const itemPath = `${path}[${index}]`;
+      if (typeof item !== "string")
+        return eachStringLeaf(item, mapLeaf, itemPath);
+      const mapped = mapLeaf(item, itemPath);
+      if (mapped !== undefined) container[index] = mapped;
+    });
+    return;
+  }
+  if (typeof container !== "object" || container === null) return;
+  for (const [key, value] of Object.entries(container)) {
+    const valuePath = path ? `${path}.${key}` : key;
+    if (typeof value !== "string") {
+      eachStringLeaf(value, mapLeaf, valuePath);
+      continue;
+    }
+    const mapped = mapLeaf(value, valuePath);
+    if (mapped !== undefined) Object.assign(container, { [key]: mapped });
+  }
+}
+function findMasks(value, pattern) {
+  const masks = [];
+  eachStringLeaf({ value }, (leaf) => {
+    masks.push(...(leaf.match(pattern) ?? []));
+    return;
+  });
+  return masks;
+}
+function parseInput(value) {
+  const parseResult = Recording.Input.safeParse(value);
+  if (!parseResult.success)
+    throw new TypeError("Invalid tool input, expected an object");
+  return structuredClone(parseResult.data);
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return;
+  }
+}
+function parseJsonStructure(text) {
+  const parsed = parseJson(text);
+  if (typeof parsed !== "object" || parsed === null) return null;
+  return parsed;
+}
+function contentTexts(content) {
+  if (typeof content === "string") return [content];
+  return content.flatMap((block) =>
+    block.type === "text" && typeof block["text"] === "string"
+      ? [block["text"]]
+      : [],
+  );
+}
+function hasToolKey(keys, toolKey) {
+  if (keys.has(toolKey)) return true;
+  const separatorIndex = toolKey.lastIndexOf("/");
+  return (
+    separatorIndex >= 0 && keys.has(`${toolKey.slice(0, separatorIndex)}/*`)
+  );
+}
+function maskSegment(segment) {
+  return segment.replace(/[^A-Za-z0-9_]+/g, "_");
+}
+var ANY_MASK_PATTERN = /<(?:tool-call|secret|host-var)\.[\w.]+(?::json)?>/g;
+function mapOutsideMasks(value, map) {
+  let result = "";
+  let index = 0;
+  for (const match of value.matchAll(ANY_MASK_PATTERN)) {
+    result += map(value.slice(index, match.index)) + match[0];
+    index = match.index + match[0].length;
+  }
+  return result + map(value.slice(index));
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// test/src/masker/SubstringMasker.ts
+class SubstringMasker {
+  static JSON_SUFFIX = ":json";
+  #pattern;
+  #valueByMask = new Map();
+  #maskByValue = new Map();
+  constructor(pattern) {
+    this.#pattern = pattern;
+  }
+  get size() {
+    return this.#valueByMask.size;
+  }
+  register(mask, value) {
+    this.#valueByMask.set(mask, value);
+    if (!this.#maskByValue.has(value)) this.#maskByValue.set(value, mask);
+  }
+  mask(value) {
+    if (!this.#maskByValue.size) return value;
+    if (typeof value === "string") return this.maskString(value);
+    eachStringLeaf(value, (leaf) => {
+      const masked = this.maskString(leaf);
+      return masked === leaf ? undefined : masked;
+    });
+    return value;
+  }
+  maskString(value) {
+    if (!this.#maskByValue.size) return value;
+    const maskByText = new Map();
+    for (const [secret, mask] of this.#maskByValue) {
+      const escaped = this.#jsonEscaped(secret);
+      maskByText.set(secret, mask);
+      if (escaped !== secret && !maskByText.has(escaped))
+        maskByText.set(escaped, this.#jsonMask(mask));
+    }
+    const pattern = new RegExp(
+      [...maskByText.keys()]
+        .sort((a, b) => b.length - a.length)
+        .map(escapeRegExp)
+        .join("|"),
+      "g",
+    );
+    return mapOutsideMasks(value, (text) =>
+      text.replace(pattern, (match) => maskByText.get(match) ?? match),
+    );
+  }
+  unmask(value) {
+    if (!this.#valueByMask.size) return value;
+    eachStringLeaf(value, (leaf) => {
+      const unmasked = leaf.replace(this.#pattern, (mask) => {
+        const escaped = mask.endsWith(`${SubstringMasker.JSON_SUFFIX}>`);
+        const value = this.#valueByMask.get(
+          escaped
+            ? `${mask.slice(0, -SubstringMasker.JSON_SUFFIX.length - 1)}>`
+            : mask,
+        );
+        if (value === undefined) return mask;
+        return escaped ? this.#jsonEscaped(value) : value;
+      });
+      return unmasked === leaf ? undefined : unmasked;
+    });
+    return value;
+  }
+  findLeaks(value) {
+    const leaks = new Set();
+    eachStringLeaf({ value }, (leaf) => {
+      mapOutsideMasks(leaf, (text) => {
+        for (const [secret, mask] of this.#maskByValue) {
+          if (text.includes(secret) || text.includes(this.#jsonEscaped(secret)))
+            leaks.add(mask);
+        }
+        return text;
+      });
+      return;
+    });
+    return [...leaks];
+  }
+  #jsonEscaped(value) {
+    return JSON.stringify(value).slice(1, -1);
+  }
+  #jsonMask(mask) {
+    return `${mask.slice(0, -1)}${SubstringMasker.JSON_SUFFIX}>`;
+  }
+}
+
+// test/src/masker/HostVarMasker.ts
+var { logger: logger2 } = Telemetry2.get(
+  "packages/typescript/test/src/masker/HostVarMasker.ts",
+);
+var HOST_MASK_PREFIX = "<host-var.";
+var HOST_VAR_NAME_PATTERN = /^\w+$/;
+var HOST_MASK_PATTERN = /<host-var\.\w+(?::json)?>/g;
+var HOST_MASK_NAME_PATTERN = /<host-var\.(\w+)(?::json)?>/g;
+
+class HostVarMasker extends SubstringMasker {
+  constructor(hostVars = {}) {
+    super(HOST_MASK_PATTERN);
+    for (const [name, value] of Object.entries(hostVars)) {
+      if (!HOST_VAR_NAME_PATTERN.test(name))
+        throw new RangeError(
+          `Host variable name '${name}' must only contain word characters`,
+        );
+      if (!value) {
+        logger2.debug(`Host variable ${name} is empty, not masking it`);
+        continue;
+      }
+      this.register(`${HOST_MASK_PREFIX}${name}>`, value);
+    }
+  }
+  static findMasks(value) {
+    return findMasks(value, HOST_MASK_PATTERN);
+  }
+  static findNames(value) {
+    const names = new Set();
+    eachStringLeaf({ value }, (leaf) => {
+      for (const [, name] of leaf.matchAll(HOST_MASK_NAME_PATTERN))
+        if (name) names.add(name);
+      return;
+    });
+    return [...names];
+  }
+}
+
+// test/src/masker/ToolCallMasker.ts
+import { Telemetry as Telemetry4 } from "@alumnium/core/internal";
+
+// test/src/masker/ResponsePaths.ts
+var PATH_SEPARATOR = ".";
+var PATH_WILDCARD = "*";
+var PATH_DEEP_WILDCARD = "**";
+var TOOL_KEY_SEPARATOR = "/";
+
+class ResponsePaths {
+  #patterns;
+  constructor(paths = {}) {
+    this.#patterns = Object.fromEntries(
+      Object.entries(paths).map(([key, keyPaths]) => [
+        key,
+        keyPaths.map((path) => path.split(PATH_SEPARATOR)),
+      ]),
+    );
+  }
+  of(toolKey) {
+    if (!toolKey) return;
+    const patterns = this.#patterns[toolKey];
+    if (patterns) return patterns;
+    const separatorIndex = toolKey.lastIndexOf(TOOL_KEY_SEPARATOR);
+    if (separatorIndex < 0) return;
+    const server = toolKey.slice(0, separatorIndex);
+    return this.#patterns[`${server}${TOOL_KEY_SEPARATOR}${PATH_WILDCARD}`];
+  }
+  has(toolKey) {
+    return !!this.of(toolKey)?.length;
+  }
+  covers(toolKey, path) {
+    return (this.of(toolKey) ?? []).some((pattern) =>
+      this.#matchesStart(pattern, path),
+    );
+  }
+  #matchesStart(pattern, path, patternIndex = 0, pathIndex = 0) {
+    if (patternIndex === pattern.length) return true;
+    const segment = pattern[patternIndex];
+    if (segment === PATH_DEEP_WILDCARD) {
+      for (let index = pathIndex; index <= path.length; index++)
+        if (this.#matchesStart(pattern, path, patternIndex + 1, index))
+          return true;
+      return false;
+    }
+    if (pathIndex === path.length) return false;
+    if (segment !== PATH_WILDCARD && segment !== path[pathIndex]) return false;
+    return this.#matchesStart(pattern, path, patternIndex + 1, pathIndex + 1);
+  }
+}
+
+// test/src/masker/SecretMasker.ts
+import { Telemetry as Telemetry3 } from "@alumnium/core/internal";
+var { logger: logger3 } = Telemetry3.get(
+  "packages/typescript/test/src/masker/SecretMasker.ts",
+);
+var SECRET_MASK_PREFIX = "<secret.";
+var SECRET_MASK_PATTERN = /<secret\.\w+(?:\.\w+)+(?::json)?>/g;
+
+class SecretMasker extends SubstringMasker {
+  static PREFIX = SECRET_MASK_PREFIX;
+  #paths;
+  #unreadOutputs = new Set();
+  static findMasks(value) {
+    return findMasks(value, SECRET_MASK_PATTERN);
+  }
+  constructor(maskResponsePaths = {}) {
+    super(SECRET_MASK_PATTERN);
+    this.#paths = new ResponsePaths(maskResponsePaths);
+  }
+  hasPaths(toolKey) {
+    return this.#paths.has(toolKey);
+  }
+  isSecret(toolKey, path) {
+    return this.#paths.covers(toolKey, path);
+  }
+  registerSecret(mask, value) {
+    this.register(mask, value);
+  }
+  markUnread(callId) {
+    logger3.warn(
+      `Tool call ${callId} has response paths to mask, but its output is not JSON`,
+    );
+    this.#unreadOutputs.add(`${SECRET_MASK_PREFIX}${maskSegment(callId)}>`);
+  }
+  findLeaks(value) {
+    return [...this.#unreadOutputs, ...super.findLeaks(value)];
+  }
+}
+
+// test/src/masker/ToolCallMasker.ts
+var { logger: logger4 } = Telemetry4.get(
+  "packages/typescript/test/src/masker/ToolCallMasker.ts",
+);
+var TOOL_CALL_MASK_PREFIX = "<tool-call.";
+var TOOL_CALL_MASK_PATTERN = /^<tool-call\.\w+(?:\.\w+)+>$/;
+var QUOTED_DELIMITER_SOURCE = String.raw`\\*['"]`;
+var QUOTED_RUN_PATTERN = new RegExp(
+  String.raw`(\\*)(?:'([^'\\]*)\1'|"([^"\\]*)\1")`,
+  "g",
+);
+var QUOTED_TOOL_CALL_MASK_PATTERN = new RegExp(
+  `(${QUOTED_DELIMITER_SOURCE})(<tool-call\\.\\w+(?:\\.\\w+)+>)\\1`,
+  "g",
+);
+var UNMASKED_INPUT_PATHS = new Set(["description"]);
+var DEFAULT_VERBATIM_TOOLS = ["TodoWrite"];
+var PATH_SEPARATOR2 = ".";
+
+class ToolCallMasker {
+  #verbatimTools;
+  #wholeValueOnlyTools;
+  #registerPaths;
+  #secrets;
+  #valueByMask = new Map();
+  #maskByValue = new Map();
+  constructor(props = {}) {
+    this.#verbatimTools = new Set(
+      props.verbatimTools ?? DEFAULT_VERBATIM_TOOLS,
+    );
+    this.#wholeValueOnlyTools = new Set(props.wholeValueOnlyTools);
+    this.#registerPaths = new ResponsePaths(props.registerResponsePaths);
+    this.#secrets = new SecretMasker(props.maskResponsePaths);
+  }
+  masksInputOf(toolKey) {
+    return !hasToolKey(this.#verbatimTools, toolKey);
+  }
+  scopeOf(toolKey) {
+    return hasToolKey(this.#wholeValueOnlyTools, toolKey)
+      ? "whole"
+      : "embedded";
+  }
+  maskInput(toolKey, input) {
+    if (!this.masksInputOf(toolKey)) return this.maskSecrets(input);
+    return this.mask(input, this.scopeOf(toolKey));
+  }
+  unmaskInput(toolKey, input) {
+    return this.unmask(input, this.scopeOf(toolKey));
+  }
+  static findUnresolved(input) {
+    const masks = [];
+    eachStringLeaf(input, (value) => {
+      if (TOOL_CALL_MASK_PATTERN.test(value)) masks.push(value);
+      return;
+    });
+    return [...masks, ...SecretMasker.findMasks(input)];
+  }
+  findLeaks(value) {
+    return this.#secrets.findLeaks(value);
+  }
+  registerContent(callId, content, toolKey, options = {}) {
+    if (this.#registersNothing(toolKey, options)) return [];
+    const text = contentTexts(content)
+      .join(`
+`)
+      .trim();
+    if (!text) {
+      logger4.debug(`Tool call ${callId} produced no text output`);
+      return [];
+    }
+    const json = parseJsonStructure(text);
+    if (!json) {
+      logger4.info(
+        `Tool call ${callId} output is not a JSON object or array, ignoring it for masking. ` +
+          "The values it produced will be replayed as recorded.",
+      );
+      logger4.debug(`-> Output: ${text}`);
+      if (this.#secrets.hasPaths(toolKey)) this.#secrets.markUnread(callId);
+      return [];
+    }
+    return this.registerOutput(callId, json, toolKey, options);
+  }
+  registerOutput(callId, json, toolKey, options = {}) {
+    const registered = [];
+    this.#collectJsonLeaves(json).forEach(({ path, value }) => {
+      const secret = this.#secrets.isSecret(toolKey, path);
+      if (!secret && (options.secretsOnly || !this.#registers(toolKey, path)))
+        return;
+      const prefix = secret ? SecretMasker.PREFIX : TOOL_CALL_MASK_PREFIX;
+      let mask = this.#leafMask(prefix, callId, path);
+      if (this.#valueByMask.has(mask)) {
+        if (!secret) {
+          logger4.warn(
+            `Tool call mask ${mask} is already registered, skipping`,
+          );
+          return;
+        }
+        mask = this.#uniqueMask(mask);
+      }
+      this.#valueByMask.set(mask, value);
+      if (!this.#maskByValue.has(value)) this.#maskByValue.set(value, mask);
+      if (secret) this.#secrets.registerSecret(mask, value);
+      logger4.debug(`Registered tool call value ${mask}`);
+      registered.push({ mask, value });
+    });
+    return registered;
+  }
+  #registers(toolKey, path) {
+    return (
+      !this.#registerPaths.of(toolKey) ||
+      this.#registerPaths.covers(toolKey, path)
+    );
+  }
+  #registersNothing(toolKey, options) {
+    if (this.#secrets.hasPaths(toolKey)) return false;
+    return (
+      !!options.secretsOnly || this.#registerPaths.of(toolKey)?.length === 0
+    );
+  }
+  #collectJsonLeaves(json) {
+    const leaves = [];
+    const walk = (value, path) => {
+      if (Array.isArray(value)) {
+        value.forEach((item, index) => walk(item, [...path, String(index)]));
+        return;
+      }
+      if (typeof value === "object" && value !== null) {
+        for (const [key, nested] of Object.entries(value))
+          walk(nested, [...path, key]);
+        return;
+      }
+      if (typeof value !== "string" && typeof value !== "number") return;
+      const leafValue = String(value);
+      if (!leafValue.trim()) return;
+      leaves.push({ path, value: leafValue });
+    };
+    walk(json, []);
+    return leaves.sort((a, b) => comparePaths(a.path, b.path));
+  }
+  #uniqueMask(mask) {
+    const base = mask.slice(0, -1);
+    let index = 2;
+    while (this.#valueByMask.has(`${base}_${index}>`)) index++;
+    return `${base}_${index}>`;
+  }
+  #leafMask(prefix, callId, path) {
+    return `${prefix}${[callId, ...path].map(maskSegment).join(PATH_SEPARATOR2)}>`;
+  }
+  mask(input, scope) {
+    if (!this.#maskByValue.size) return input;
+    eachStringLeaf(input, (value, path) => {
+      if (scope === "embedded" && UNMASKED_INPUT_PATHS.has(path)) return;
+      const mask = this.#maskByValue.get(value);
+      if (mask) {
+        logger4.debug(
+          `Masked tool call value in '${path}': '${value}' -> '${mask}'`,
+        );
+        return mask;
+      }
+      if (scope !== "embedded") return;
+      return this.#maskQuoted(value, path);
+    });
+    return this.maskSecrets(input);
+  }
+  maskSecrets(value) {
+    return this.#secrets.mask(value);
+  }
+  #maskQuoted(value, path) {
+    const result = this.#maskQuotedRuns(value, path);
+    return result === value ? undefined : result;
+  }
+  #maskQuotedRuns(value, path) {
+    return value.replace(
+      QUOTED_RUN_PATTERN,
+      (match, escapes, single, double) => {
+        const delimiter = `${escapes}${single === undefined ? '"' : "'"}`;
+        const token = single ?? double ?? "";
+        if (token.search(QUOTED_RUN_PATTERN) >= 0)
+          return `${delimiter}${this.#maskQuotedRuns(token, path)}${delimiter}`;
+        const mask = this.#maskByValue.get(token);
+        if (!mask) return match;
+        logger4.debug(
+          `Masked quoted tool call value in '${path}': '${token}' -> '${mask}'`,
+        );
+        return `${delimiter}${mask}${delimiter}`;
+      },
+    );
+  }
+  unmask(input, scope) {
+    if (!this.#valueByMask.size) return input;
+    eachStringLeaf(input, (mask, path) => {
+      const value = this.#valueByMask.get(mask);
+      if (value !== undefined) {
+        logger4.debug(
+          `Unmasked tool call value in '${path}': '${mask}' -> '${value}'`,
+        );
+        return value;
+      }
+      if (scope === "embedded") return this.#unmaskQuoted(mask, path);
+    });
+    return this.#secrets.unmask(input);
+  }
+  #unmaskQuoted(value, path) {
+    let unmasked = false;
+    const result = value.replace(
+      QUOTED_TOOL_CALL_MASK_PATTERN,
+      (match, delimiter, mask) => {
+        const fresh = this.#valueByMask.get(mask);
+        if (fresh === undefined) return match;
+        if (this.#breaksQuoting(fresh, delimiter)) {
+          logger4.warn(
+            `Fresh tool call value for ${mask} cannot be quoted with ${delimiter} in '${path}', leaving the mask in place`,
+          );
+          return match;
+        }
+        logger4.debug(
+          `Unmasked quoted tool call value in '${path}': '${mask}' -> '${fresh}'`,
+        );
+        unmasked = true;
+        return `${delimiter}${fresh}${delimiter}`;
+      },
+    );
+    return unmasked ? result : undefined;
+  }
+  #breaksQuoting(value, delimiter) {
+    const quote = delimiter.slice(-1);
+    if (value.includes(quote)) return true;
+    const interprets = quote === '"' || delimiter.length > 1;
+    return interprets && /[\\$`]/.test(value);
+  }
+}
+function comparePaths(a, b) {
+  for (let index = 0; index < Math.min(a.length, b.length); index++) {
+    const [left = "", right = ""] = [a[index], b[index]];
+    if (left !== right) return left < right ? -1 : 1;
+  }
+  return a.length - b.length;
+}
+
+// test/src/masker/Masker.ts
+class Masker {
+  #toolCalls;
+  #hostVars;
+  constructor(props = {}) {
+    const { hostVars, ...toolCallProps } = props;
+    this.#toolCalls = new ToolCallMasker(toolCallProps);
+    this.#hostVars = new HostVarMasker(hostVars);
+  }
+  masksToolCallValuesOf(toolKey) {
+    return this.#toolCalls.masksInputOf(toolKey);
+  }
+  registerOutput(callId, content, toolKey, options) {
+    this.#toolCalls.registerContent(callId, content, toolKey, options);
+  }
+  static findUnresolvedMasks(input) {
+    return [
+      ...new Set([
+        ...ToolCallMasker.findUnresolved(input),
+        ...HostVarMasker.findMasks(input),
+      ]),
+    ];
+  }
+  static findHostVarNames(value) {
+    return HostVarMasker.findNames(value);
+  }
+  findLeaks(value) {
+    return [
+      ...this.#hostVars.findLeaks(value),
+      ...this.#toolCalls.findLeaks(value),
+    ];
+  }
+  maskInput(toolKey, input) {
+    return this.#hostVars.mask(
+      this.#toolCalls.maskInput(toolKey, parseInput(input)),
+    );
+  }
+  maskResult(content) {
+    return this.#maskSecrets(structuredClone(content));
+  }
+  maskNarration(text) {
+    return this.#maskSecrets(text);
+  }
+  #maskSecrets(value) {
+    return this.#hostVars.mask(this.#toolCalls.maskSecrets(value));
+  }
+  unmaskInput(toolKey, input) {
+    return this.#hostVars.unmask(
+      this.#toolCalls.unmaskInput(toolKey, parseInput(input)),
+    );
+  }
+}
+// test/src/Recorder.ts
+import {
+  ALUMNIUM_VERSION,
+  Telemetry as Telemetry5,
+} from "@alumnium/core/internal";
+
+// test/src/RecordingLeakError.ts
+class RecordingLeakError extends Error {
+  masks;
+  constructor(masks) {
+    super(
+      `Recording would store values in clear: ${masks.join(", ")}. ` +
+        "Check the host variables and response paths configured for it.",
+    );
+    this.name = "RecordingLeakError";
+    this.masks = masks;
+  }
+}
+
+// test/src/Recorder.ts
+var { logger: logger5 } = Telemetry5.get(
+  "packages/typescript/test/src/Recorder.ts",
+);
+var DEFAULT_ALUMNIUM_SERVER = "alumnium";
+var ALUMNIUM_START_TOOL = "start";
+
+class Recorder {
+  #text;
+  #agent;
+  #version;
+  #masker;
+  #steps = [];
+  #pendingCalls = new Map();
+  #recording;
+  constructor(props) {
+    const { text, agent, version, alumniumServer, ...maskerProps } = props;
+    this.#version = version ?? Recording.DEFAULT_VERSION;
+    this.#text = text;
+    this.#agent = agent;
+    const server = alumniumServer ?? DEFAULT_ALUMNIUM_SERVER;
+    this.#masker = new Masker({
+      ...maskerProps,
+      registerResponsePaths: {
+        ...this.#alumniumRegisterResponsePaths(server),
+        ...maskerProps.registerResponsePaths,
+      },
+      wholeValueOnlyTools: [
+        `${server}/*`,
+        ...(maskerProps.wholeValueOnlyTools ?? []),
+      ],
+    });
+  }
+  onToolUse(use) {
+    this.#assertNotFinished();
+    const { id, server, tool, input } = use;
+    const toolKey = Recording.toolKey({ server, tool });
+    logger5.debug(`Recording tool use '${toolKey}' ({id})`, { id });
+    this.#pendingCalls.set(id, {
+      id,
+      ...(server ? { server } : {}),
+      tool,
+      input: this.#masker.maskInput(toolKey, input),
+    });
+  }
+  onToolResult(toolResult) {
+    this.#assertNotFinished();
+    const { id, content } = toolResult;
+    const isError = Boolean(toolResult.isError);
+    const call = this.#pendingCalls.get(id);
+    if (!call) {
+      logger5.debug(`No recorded tool use for result '${id}', ignoring it`);
+      return;
+    }
+    this.#pendingCalls.delete(id);
+    logger5.debug(`Recording '${call.tool}' tool result`);
+    this.#masker.registerOutput(id, content, Recording.toolKey(call), {
+      secretsOnly: isError,
+    });
+    this.#steps.push({
+      kind: "tool-call",
+      call,
+      result: { content: structuredClone(content), isError },
+    });
+  }
+  onNarration(narration) {
+    this.#assertNotFinished();
+    if (!narration.text.trim()) return;
+    this.#steps.push({
+      kind: "narration",
+      narration: narration.narration,
+      text: narration.text,
+    });
+  }
+  finish(verdict) {
+    this.#assertNotFinished();
+    if (this.#pendingCalls.size)
+      logger5.warn(
+        `Dropping ${this.#pendingCalls.size} tool calls with no result: ${[
+          ...this.#pendingCalls.values(),
+        ]
+          .map(({ tool }) => tool)
+          .join(", ")}`,
+      );
+    this.#pendingCalls.clear();
+    const recording = {
+      id: Recording.textToId(this.#text),
+      version: this.#version,
+      text: this.#text,
+      agent: this.#agent,
+      alumnium: { version: ALUMNIUM_VERSION },
+      hostVars: [],
+      steps: this.#steps.map((step) => this.#maskStep(step)),
+      verdict: {
+        status: verdict.status,
+        details: this.#masker.maskNarration(verdict.details),
+      },
+    };
+    const masked = [
+      recording.steps.map((step) =>
+        step.kind === "narration"
+          ? step.text
+          : [step.call.input, step.result.content],
+      ),
+      recording.verdict.details,
+    ];
+    const leaks = this.#masker.findLeaks(masked);
+    if (leaks.length) throw new RecordingLeakError(leaks);
+    recording.hostVars = Masker.findHostVarNames(masked);
+    this.#recording = recording;
+    return recording;
+  }
+  #maskStep(step) {
+    if (step.kind === "narration") {
+      return { ...step, text: this.#masker.maskNarration(step.text) };
+    } else {
+      return {
+        ...step,
+        result: {
+          ...step.result,
+          content: this.#masker.maskResult(step.result.content),
+        },
+      };
+    }
+  }
+  #alumniumRegisterResponsePaths(server = DEFAULT_ALUMNIUM_SERVER) {
+    return {
+      [`${server}/*`]: [],
+      [`${server}/${ALUMNIUM_START_TOOL}`]: ["id"],
+    };
+  }
+  #assertNotFinished() {
+    if (this.#recording) throw new Error("Recording is already finished");
+  }
+}
+export { FileTestCache, Masker, Recorder, Recording, RecordingLeakError };
+
+//# debugId=E1FEB499A312812964756E2164756E21
+//# sourceMappingURL=index.js.map