@alumnium/test 0.0.0-stage → 0.24.0

package/src/masker/ToolCallMasker.d.ts

@@ -0,0 +1,177 @@
+import type { Recording } from "../Recording.ts";
+export declare namespace ToolCallMasker {
+  interface Props {
+    /** @see Masker.Props.verbatimTools */
+    verbatimTools?: string[] | undefined;
+    /** @see Masker.Props.wholeValueOnlyTools */
+    wholeValueOnlyTools?: string[] | undefined;
+    /** @see `Masker.Props.maskResponsePaths`. */
+    maskResponsePaths?: Record<string, string[]> | undefined;
+    /** @see `Masker.Props.registerResponsePaths`. */
+    registerResponsePaths?: Record<string, string[]> | undefined;
+  }
+  /**
+   * Which strings a mask can take the place of.
+   * - whole: a tool call value in full (e.g. `{"id": "a1"}`).
+   * - embedded: a quote-delimited value inside a larger string (e.g. `echo '{"id": "a1"}'`).
+   */
+  type Scope = "whole" | "embedded";
+  interface Leaf {
+    path: string[];
+    value: string;
+  }
+  interface RegisterOptions {
+    /** Registers only the leaves at `maskResponsePaths`, e.g. of a failed call. */
+    secretsOnly?: boolean | undefined;
+  }
+  interface Registered {
+    mask: string;
+    value: string;
+  }
+}
+/**
+ * Masks values tool calls produced, and substitutes the values the replay's
+ * fresh calls produce. Masks are derived from the JSON path of each output
+ * leaf, so the same leaf yields the same mask in both phases:
+ *
+ * - `<tool-call.id.path>` - an ordinary value, masked only where a later tool
+ *   input uses it as a whole value (or a quoted one, in the `embedded` scope),
+ *   since it can be short or common;
+ * - `<secret.id.path>` - a value at one of the tool's `maskResponsePaths`,
+ *   masked like an ordinary one and also wherever else it occurs, results and
+ *   narration included, since it must never be stored in clear (see
+ *   `SecretMasker`).
+ */
+export declare class ToolCallMasker {
+  #private;
+  constructor(props?: ToolCallMasker.Props);
+  /**
+   * Tells whether tool call values are masked in a tool's input at all.
+   *
+   * Every tool but a verbatim one qualifies, including one replay cannot
+   * execute: the point of masking such an input is that the value a run
+   * produced does not end up persisted in the recording, not that it gets
+   * substituted again.
+   *
+   * @param toolKey - Tool key, see `Recording.toolKey`.
+   * @returns `false` when the tool's input is prose that must stay verbatim.
+   */
+  masksInputOf(toolKey: string): boolean;
+  /**
+   * Scope tool call values are masked in for a tool's input: `whole` for one
+   * of `wholeValueOnlyTools`, `embedded` for any other.
+   *
+   * @param toolKey - Tool key, see `Recording.toolKey`.
+   */
+  scopeOf(toolKey: string): ToolCallMasker.Scope;
+  /**
+   * Masks a tool's input in the tool's scope (see `scopeOf`), or only its
+   * secrets when the tool's input must stay verbatim.
+   *
+   * @param toolKey - Tool key, see `Recording.toolKey`.
+   * @param input - Tool input, masked in place.
+   * @returns The same input.
+   */
+  maskInput(toolKey: string, input: Recording.Input): Recording.Input;
+  /**
+   * Substitutes fresh values back into a tool's input, in the tool's scope.
+   *
+   * @param toolKey - Tool key, see `Recording.toolKey`.
+   * @param input - Masked tool input, unmasked in place.
+   * @returns The same input.
+   */
+  unmaskInput(toolKey: string, input: Recording.Input): Recording.Input;
+  /**
+   * Finds masks unmasking could not resolve: a `<tool-call...>` one that
+   * takes up a whole value, a `<secret...>` one anywhere.
+   *
+   * An ordinary mask inside a quoted token does not count. An unresolved
+   * one there just replays the command as recorded rather than failing the
+   * replay, whereas a secret replayed as its mask is never right.
+   *
+   * @param input - Unmasked tool input.
+   * @returns Masks, in order of appearance.
+   */
+  static findUnresolved(input: Recording.Input): string[];
+  /**
+   * Finds secrets that survived masking anywhere in a value, see
+   * `SecretMasker.findLeaks`.
+   *
+   * @param value - Value to scan.
+   * @returns Masks of the leaked secrets, never the secrets themselves.
+   */
+  findLeaks(value: unknown): string[];
+  /**
+   * Registers the values of a tool call result. Only JSON output is
+   * considered, so the same leaf yields the same mask in both phases even
+   * when a fresh output reorders its keys or adds new ones.
+   *
+   * @param callId - Id of the tool call, as the host agent assigned it.
+   * @param content - Tool call result content.
+   * @param toolKey - Tool key (see `Recording.toolKey`) for the response paths.
+   * @returns Leaves registered, with their masks.
+   */
+  registerContent(
+    callId: string,
+    content: Recording.Content,
+    toolKey?: string,
+    options?: ToolCallMasker.RegisterOptions,
+  ): ToolCallMasker.Registered[];
+  /**
+   * Registers the scalar leaves of a tool call's JSON output, so that they
+   * can be masked in the tool inputs that follow it (recording) or
+   * substituted back into them (replay).
+   *
+   * A tool with `registerResponsePaths` registers only the leaves they cover,
+   * any other tool every leaf. A leaf at one of the tool's
+   * `maskResponsePaths` becomes a secret, and is registered regardless, since
+   * it must be kept out of the recording either way.
+   *
+   * @param callId - Id of the tool call, as the host agent assigned it.
+   * @param json - Parsed JSON output of the call.
+   * @param toolKey - Tool key (see `Recording.toolKey`) for the response paths.
+   * @returns Leaves registered, with their masks.
+   */
+  registerOutput(
+    callId: string,
+    json: object,
+    toolKey?: string,
+    options?: ToolCallMasker.RegisterOptions,
+  ): ToolCallMasker.Registered[];
+  /**
+   * Replaces values produced by tool calls with masks, so that replay can
+   * substitute freshly produced ones.
+   *
+   * In the `whole` scope only a leaf that equals a tool call value in full is
+   * replaced. A value quoted inside free-form prose is left alone: there is no
+   * way to tell a value apart from the prose around it without guessing, and
+   * every Alumnium tool that takes prose takes such values through `params`.
+   *
+   * Secrets are then masked wherever else they occur, see `maskSecrets`.
+   *
+   * @param input - Tool input, masked in place.
+   * @param scope - Which strings a mask can take the place of.
+   * @returns The same input.
+   */
+  mask(input: Recording.Input, scope: ToolCallMasker.Scope): Recording.Input;
+  /**
+   * Masks secrets wherever they occur in every string leaf of a value, e.g. a
+   * tool result, narration, or the input of a tool that must stay verbatim.
+   *
+   * @param value - Value to mask in place, or a string to mask.
+   * @returns The same value, or the masked string.
+   */
+  maskSecrets<Type>(value: Type): Type;
+  /**
+   * Substitutes fresh tool call values back into a tool input, secrets
+   * wherever they occur.
+   *
+   * A mask with no registered value is left in place, so that
+   * `findUnresolved` can name the input it was needed for.
+   *
+   * @param input - Masked tool input, unmasked in place.
+   * @param scope - Which strings a mask can have taken the place of.
+   * @returns The same input.
+   */
+  unmask(input: Recording.Input, scope: ToolCallMasker.Scope): Recording.Input;
+}

package/src/masker/maskerUtils.d.ts

@@ -0,0 +1,83 @@
+import { Recording } from "../Recording.ts";
+/** Replacement for a string leaf, `undefined` to keep it. */
+export type LeafFn = (value: string, path: string) => string | undefined;
+/**
+ * Visits every string leaf of a value, at any nesting depth, so that the
+ * values inside e.g. `do`'s `params` are covered too.
+ *
+ * Only string leaves are visited. Substituting a mask into a number or a
+ * boolean leaf would change its type and can break the tool input schema.
+ *
+ * @param container - Value to walk, only objects and arrays are descended into.
+ * @param mapLeaf - Called with each string leaf and its path, returning the
+ *   replacement for it or `undefined` to leave it alone.
+ * @param path - Path of `container` itself, used for logging.
+ */
+export declare function eachStringLeaf(
+  container: unknown,
+  mapLeaf: LeafFn,
+  path?: string,
+): void;
+/**
+ * Finds every match of a global mask pattern in the string leaves of a value.
+ *
+ * @param value - Value to scan.
+ * @param pattern - Global mask pattern.
+ * @returns Matched masks, in order of appearance.
+ */
+export declare function findMasks(value: unknown, pattern: RegExp): string[];
+/**
+ * Parses a tool input, cloning it so that masking never touches the caller's
+ * own object.
+ *
+ * @param value - Tool input.
+ * @returns Cloned tool input.
+ */
+export declare function parseInput(value: unknown): Recording.Input;
+export declare function parseJson(text: string): unknown;
+/**
+ * Parses a tool output as JSON, accepting only an object or an array.
+ *
+ * `JSON.parse` also accepts a bare scalar, so `echo 9` would otherwise
+ * register a value with no key to name it, inconsistent with `echo nine`,
+ * which is not JSON at all.
+ *
+ * @param text - Tool output text.
+ * @returns Parsed JSON structure, `null` when the output is not one.
+ */
+export declare function parseJsonStructure(text: string): object | null;
+/** Text of a tool result: the string itself, or every text block. */
+export declare function contentTexts(content: Recording.Content): string[];
+/** Maps the text of a tool result, keeping every other block as it was. */
+export declare function mapTexts(
+  content: Recording.Content,
+  map: (text: string) => string,
+): Recording.Content;
+/**
+ * Tells whether a tool key is one of a set, by its own key or its server's
+ * `<server>/*` key.
+ *
+ * @param keys - Tool keys, see `Recording.toolKey`.
+ * @param toolKey - Tool key to look up.
+ */
+export declare function hasToolKey(keys: Set<string>, toolKey: string): boolean;
+/**
+ * Sanitizes a segment of a mask - a tool call id or a JSON path segment - to
+ * word characters, so that a mask stays matchable by its pattern.
+ *
+ * @param segment - Segment to sanitize.
+ */
+export declare function maskSegment(segment: string): string;
+/**
+ * Maps the parts of a string outside any mask, of any family, leaving the
+ * masks themselves intact.
+ *
+ * @param value - String to map.
+ * @param map - Called with each part between masks.
+ */
+export declare function mapOutsideMasks(
+  value: string,
+  map: (text: string) => string,
+): string;
+/** Escapes a string for use as a literal in a `RegExp`. */
+export declare function escapeRegExp(value: string): string;