//#region src/agent-surface.d.ts
/**
 * The agent-facing surface contract shared by the CLI (`@stll/anonymize-cli`)
 * and the MCP server (`@stll/anonymize-mcp`).
 *
 * Both surfaces are driven mostly by AI agents. To stay legible to them, every
 * tool/command failure carries one of a closed set of machine-readable `code`s
 * alongside a human `message` and an actionable `hint`; the MCP server returns
 * the `{ error: { code, message, hint, retryable } }` envelope with `isError`,
 * and the CLI maps the same `code` to a distinct process exit code. The two
 * surfaces do not talk to each other (the CLI drives the WASM engine directly),
 * so they share the taxonomy through this runtime-free module rather than a
 * call path.
 *
 * The set is closed: a new failure mode must reuse a code here or add one
 * deliberately (and pick a fresh exit code). This module must stay runtime-free
 * (no wasm, no node built-ins) so any consumer can import it cheaply.
 */
export declare const ANONYMIZE_ERROR_CODES: readonly [
/** Input failed validation at the boundary (shape, type, size, arguments). */
"validation_error",
/** A path resolved outside the configured roots, or was not absolute. */
"path_not_allowed",
/** The named input path or session key does not exist. */
"not_found",
/** The input's extension or content is not a supported document type. */
"unsupported_format",
/** The output path already exists; anonymize never overwrites. */
"output_exists",
/** A restore needs a durable session store that is not configured. */
"session_unavailable",
/** An external tool (pdftoppm, tesseract) was missing or not executable. */
"dependency_missing",
/** An unexpected internal failure; detail is not leaked to the caller. */
"internal_error"];
export type AnonymizeErrorCode = (typeof ANONYMIZE_ERROR_CODES)[number];
/**
 * The structured tool-error envelope the MCP surface returns (alongside
 * `isError: true`). `hint` states the next step for the agent; `retryable`
 * says whether retrying the same call unchanged could plausibly succeed.
 */
export type AnonymizeErrorEnvelope = {
  error: {
    code: AnonymizeErrorCode;
    message: string;
    hint: string;
    retryable: boolean;
  };
};
/**
 * Process exit codes for the CLI. `ok`/`unexpected`/`usage` are the pre-existing
 * classes (0/1/2); the remaining classes are keyed off the error codes above so
 * an agent can branch on the exit code without parsing stderr. Every error code
 * maps to a distinct exit code (asserted in `agent-surface.test.ts`).
 */
export declare const EXIT_CODES: {
  readonly ok: 0;
  readonly unexpected: 1;
  readonly usage: 2;
  readonly pathNotAllowed: 3;
  readonly notFound: 4;
  readonly unsupportedFormat: 5;
  readonly outputExists: 6;
  readonly sessionUnavailable: 7;
  readonly dependencyMissing: 8;
};
export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
/**
 * Map every error code to its CLI exit class. `validation_error` shares the
 * `usage` class (2) with the CLI's own `UsageError`: both mean "the invocation
 * was malformed, fix the input". `internal_error` maps to the generic
 * `unexpected` class (1).
 */
export declare const ERROR_CODE_EXIT_MAP: Readonly<Record<AnonymizeErrorCode, ExitCode>>;
type SurfaceErrorOptions = {
  hint: string;
  retryable?: boolean;
  cause?: unknown;
};
/**
 * A failure carrying a stable agent-surface `code`, a `hint`, and a `retryable`
 * flag. Service and engine code throws this instead of a plain `Error` so both
 * surfaces can classify it: the MCP boundary renders it as the error envelope,
 * the CLI maps it to an exit code. Messages must stay content-free (never echo
 * raw input text or detected entities).
 */
export declare class AnonymizeSurfaceError extends Error {
  readonly code: AnonymizeErrorCode;
  readonly hint: string;
  readonly retryable: boolean;
  constructor(code: AnonymizeErrorCode, message: string, { hint, retryable, cause }: SurfaceErrorOptions);
}
export declare const isAnonymizeSurfaceError: (value: unknown) => value is AnonymizeSurfaceError;
/** Build the wire error envelope from a surface error. */
export declare const toErrorEnvelope: (error: AnonymizeSurfaceError) => AnonymizeErrorEnvelope;
/**
 * Classify an arbitrary thrown value into the error envelope. A
 * `AnonymizeSurfaceError` keeps its code; anything else collapses to
 * `internal_error` with its detail withheld, so unexpected failures never leak
 * raw text or stack detail to the caller.
 */
export declare const classifyToEnvelope: (error: unknown) => AnonymizeErrorEnvelope;
/** The CLI exit code for a thrown value (non-surface errors are `unexpected`). */
export declare const exitCodeForError: (error: unknown) => ExitCode;
//#endregion
//# sourceMappingURL=agent-surface.d.mts.map