mirror-mind 0.0.1 → 0.33.0

package/ts/src/providers/openrouter.ts

@@ -0,0 +1,244 @@
+/**
+ * The live OpenRouter HTTP transport (AI-18, CV22.DS8.US1).
+ *
+ * Python reaches OpenRouter through the OpenAI SDK and inherits its retry
+ * policy; TypeScript ports the POLICY, not the package. Node >= 24 ships a
+ * global `fetch`, so the only thing an SDK would add here is a dependency with
+ * its own release cadence sitting on the path of every paid call.
+ *
+ * Every side effect is injectable (`fetch`, `sleep`) so no test in this repo
+ * can reach the network by accident. The client itself logs NOTHING:
+ * observability belongs to `logLlmCall` (metadata mode) and the front-door
+ * log, both of which are already redacted by contract.
+ */
+
+import type { ProviderConfig } from "./config.ts";
+import { redactString } from "./redaction.ts";
+
+/**
+ * The AI-18 failure taxonomy. Closed on purpose: a caller that switches on
+ * `kind` must break at compile time when a class is added, rather than
+ * silently funnelling a new failure into `provider_error`.
+ */
+export type LlmTransportErrorKind =
+  | "timeout"
+  | "auth"
+  | "rate_limit"
+  | "malformed_output"
+  | "provider_error";
+
+/**
+ * A provider failure, carrying the classification and NOTHING else.
+ *
+ * The fields are deliberately minimal. Error objects get serialized whole by
+ * loggers, test reporters, and crash handlers, so a `Response`, a body, or a
+ * `cause` chain kept "just for debugging" is a leak path for both the API key
+ * and the request content (a query, a transcript, an identity document). The
+ * message is redacted; the enumerable surface is `kind`, `status`, `retryable`.
+ */
+export class LlmTransportError extends Error {
+  readonly kind: LlmTransportErrorKind;
+  readonly status: number | null;
+  readonly retryable: boolean;
+
+  constructor(
+    kind: LlmTransportErrorKind,
+    message: string,
+    options: { status?: number | null; retryable?: boolean } = {},
+  ) {
+    // No `cause`: it would carry the original error's message and, through it,
+    // whatever the provider echoed back.
+    super(message);
+    this.name = "LlmTransportError";
+    this.kind = kind;
+    this.status = options.status ?? null;
+    this.retryable = options.retryable ?? false;
+  }
+}
+
+export interface OpenRouterClientOptions {
+  fetch?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface ProviderRequestOptions {
+  /** Hard bound for one attempt, from the per-role pins in config.ts. */
+  timeoutMs: number;
+  /** Additional attempts after the first. Defaults to Python's ceiling of 2. */
+  maxRetries?: number;
+}
+
+export interface OpenRouterClient {
+  postJson(path: string, body: unknown, options: ProviderRequestOptions): Promise<unknown>;
+  /**
+   * A bounded GET, for OpenRouter's read endpoints (`/credits`,
+   * `/generation`).
+   *
+   * Python reaches those two through bare `urllib.request.urlopen` with **no
+   * timeout at all**, so a hung connection there parks the command forever.
+   * TypeScript bounds every attempt instead -- a deliberate divergence, at the
+   * embedding tier Python itself uses for its other cheap GET (`/models`).
+   * Recorded in `docs/project/decisions.md` (CV22.DS8.US3).
+   */
+  getJson(path: string, options: ProviderRequestOptions): Promise<unknown>;
+}
+
+/** Base backoff; doubles per attempt (0.5s, 1s, 2s, ...). */
+const BASE_BACKOFF_MS = 500;
+/** Ceiling for computed backoff and for an honored `retry-after`. */
+const MAX_BACKOFF_MS = 60_000;
+const DEFAULT_MAX_RETRIES = 2;
+
+/**
+ * One attempt's outcome. The retry hint travels HERE rather than on the error,
+ * so the error's serialized shape stays minimal and the loop keeps the whole
+ * retry decision in one place.
+ */
+type AttemptOutcome =
+  | { ok: true; body: unknown }
+  | { ok: false; error: LlmTransportError; retryAfterMs: number | null };
+
+/**
+ * Statuses the OpenAI SDK retries, which is what Python's behavior is made of:
+ * request timeout, conflict, rate limit, and any server-side failure. Every
+ * other 4xx is a deterministic client error -- retrying it spends money to get
+ * the same answer.
+ */
+function isRetryableStatus(status: number): boolean {
+  return status === 408 || status === 409 || status === 429 || status >= 500;
+}
+
+function classifyStatus(status: number): LlmTransportErrorKind {
+  if (status === 401 || status === 403) return "auth";
+  if (status === 429) return "rate_limit";
+  return "provider_error";
+}
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Honor `retry-after` when the provider states one, capped so a hostile or
+ * confused header cannot park a session hook for an hour.
+ */
+function retryAfterMs(response: Response): number | null {
+  const raw = response.headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw.trim());
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(seconds * 1000, MAX_BACKOFF_MS);
+}
+
+function backoffMs(attemptIndex: number): number {
+  return Math.min(BASE_BACKOFF_MS * 2 ** attemptIndex, MAX_BACKOFF_MS);
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+
+export function createOpenRouterClient(
+  config: ProviderConfig,
+  options: OpenRouterClientOptions = {},
+): OpenRouterClient {
+  const fetchImpl = options.fetch ?? fetch;
+  const sleep = options.sleep ?? defaultSleep;
+  // Every message leaving this client passes through here. The key is the only
+  // secret the client holds, so it is the only needle redaction needs.
+  const redact = (message: string): string => redactString(message, { secrets: [config.apiKey] });
+
+  async function attempt(
+    method: "GET" | "POST",
+    path: string,
+    body: unknown,
+    timeoutMs: number,
+  ): Promise<AttemptOutcome> {
+    let response: Response;
+    try {
+      response = await fetchImpl(`${config.baseUrl}${path}`, {
+        method,
+        headers:
+          method === "POST"
+            ? { "content-type": "application/json", authorization: `Bearer ${config.apiKey}` }
+            : { authorization: `Bearer ${config.apiKey}` },
+        body: method === "POST" ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeoutMs),
+        // The base URL is a module constant; there is no legitimate redirect.
+        // Refusing is explicit, rather than trusting the spec to strip the
+        // Authorization header on a cross-origin hop (RS005).
+        redirect: "error",
+      });
+    } catch (error) {
+      if (isAbortError(error)) {
+        return {
+          ok: false,
+          retryAfterMs: null,
+          error: new LlmTransportError("timeout", `provider call timed out after ${timeoutMs}ms`, {
+            retryable: true,
+          }),
+        };
+      }
+      // Transport-level failure (DNS, TLS, connection reset, refused redirect).
+      // The underlying message can echo request details, so it is not carried.
+      return {
+        ok: false,
+        retryAfterMs: null,
+        error: new LlmTransportError("provider_error", "provider connection failed", {
+          retryable: true,
+        }),
+      };
+    }
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        retryAfterMs: retryAfterMs(response),
+        error: new LlmTransportError(
+          classifyStatus(response.status),
+          redact(`provider returned HTTP ${response.status}`),
+          { status: response.status, retryable: isRetryableStatus(response.status) },
+        ),
+      };
+    }
+
+    try {
+      return { ok: true, body: await response.json() };
+    } catch {
+      // A 200 that is not JSON is deterministic -- a gateway page, a truncated
+      // body. Retrying pays for the same answer, so it is terminal.
+      return {
+        ok: false,
+        retryAfterMs: null,
+        error: new LlmTransportError("malformed_output", "provider returned a non-JSON body", {
+          status: response.status,
+          retryable: false,
+        }),
+      };
+    }
+  }
+
+  // One retry loop for both verbs: the taxonomy, the retryable-status set, the
+  // `retry-after` handling, and the backoff are properties of the TRANSPORT,
+  // not of the method. A second loop for GET would be a second place for the
+  // policy to drift.
+  async function send(
+    method: "GET" | "POST",
+    path: string,
+    body: unknown,
+    requestOptions: ProviderRequestOptions,
+  ): Promise<unknown> {
+    const maxRetries = requestOptions.maxRetries ?? DEFAULT_MAX_RETRIES;
+
+    for (let index = 0; ; index += 1) {
+      const outcome = await attempt(method, path, body, requestOptions.timeoutMs);
+      if (outcome.ok) return outcome.body;
+      if (!outcome.error.retryable || index === maxRetries) throw outcome.error;
+      await sleep(outcome.retryAfterMs ?? backoffMs(index));
+    }
+  }
+
+  return {
+    postJson: (path, body, requestOptions) => send("POST", path, body, requestOptions),
+    getJson: (path, requestOptions) => send("GET", path, undefined, requestOptions),
+  };
+}

package/ts/src/providers/redaction.ts

@@ -0,0 +1,110 @@
+const REDACTION_MARKER = "[REDACTED]";
+
+const SECRET_KEY_PATTERN = /(?:api[_-]?key|apikey|authorization|token|secret|password|credential)/i;
+const BEARER_TOKEN_PATTERN = /\bBearer\s+[^\s,;"'}\]]+/gi;
+
+export interface RedactionOptions {
+  secrets?: readonly string[];
+}
+
+export class UnsafeFixtureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsafeFixtureError";
+  }
+}
+
+export function redactString(value: string, options: RedactionOptions = {}): string {
+  let redacted = value.replace(BEARER_TOKEN_PATTERN, `Bearer ${REDACTION_MARKER}`);
+  for (const secret of normalizedSecrets(options.secrets ?? [])) {
+    redacted = redacted.split(secret).join(REDACTION_MARKER);
+  }
+  return redacted;
+}
+
+export function redactJson(value: unknown, options: RedactionOptions = {}): unknown {
+  return redactJsonValue(value, options, undefined);
+}
+
+export function assertFixtureSafe(value: unknown, options: RedactionOptions = {}): void {
+  const leaks = findFixtureLeaks(value, options);
+  if (leaks.length > 0) {
+    throw new UnsafeFixtureError(
+      `unsafe fixture contains unsanitized secret material: ${leaks.join(", ")}`,
+    );
+  }
+}
+
+function redactJsonValue(
+  value: unknown,
+  options: RedactionOptions,
+  key: string | undefined,
+): unknown {
+  if (SECRET_KEY_PATTERN.test(key ?? "")) {
+    return REDACTION_MARKER;
+  }
+  if (typeof value === "string") {
+    return redactString(value, options);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactJsonValue(item, options, undefined));
+  }
+  if (isRecord(value)) {
+    const entries = Object.entries(value).map(([childKey, childValue]) => [
+      childKey,
+      redactJsonValue(childValue, options, childKey),
+    ]);
+    return Object.fromEntries(entries);
+  }
+  return value;
+}
+
+function findFixtureLeaks(value: unknown, options: RedactionOptions): string[] {
+  const leaks: string[] = [];
+  walk(value, [], (path, current, key) => {
+    if (typeof current !== "string") {
+      return;
+    }
+    const pathText = path.join(".") || "<root>";
+    if (SECRET_KEY_PATTERN.test(key ?? "") && current !== REDACTION_MARKER) {
+      leaks.push(`${pathText} uses secret-looking key without redaction`);
+      return;
+    }
+    if (BEARER_TOKEN_PATTERN.test(current) && !current.includes(REDACTION_MARKER)) {
+      leaks.push(`${pathText} contains bearer token`);
+    }
+    for (const secret of normalizedSecrets(options.secrets ?? [])) {
+      if (current.includes(secret)) {
+        leaks.push(`${pathText} contains configured secret`);
+      }
+    }
+  });
+  return leaks;
+}
+
+function walk(
+  value: unknown,
+  path: readonly string[],
+  visit: (path: readonly string[], value: unknown, key: string | undefined) => void,
+): void {
+  visit(path, value, path.at(-1));
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      walk(item, [...path, String(index)], visit);
+    });
+    return;
+  }
+  if (isRecord(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      walk(child, [...path, key], visit);
+    }
+  }
+}
+
+function normalizedSecrets(secrets: readonly string[]): string[] {
+  return secrets.map((secret) => secret.trim()).filter((secret) => secret.length > 0);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/ts/src/providers/replay.ts

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+
+import { assertFixtureSafe, type RedactionOptions } from "./redaction.ts";
+
+export type ReplayFixture = unknown;
+
+export async function loadReplayFixture(
+  path: string,
+  options: RedactionOptions = {},
+): Promise<ReplayFixture> {
+  const raw = await readFile(path, "utf8");
+  const fixture = JSON.parse(raw) as ReplayFixture;
+  assertFixtureSafe(fixture, options);
+  return fixture;
+}