@workos/quickstudy 0.0.1

package/src/isolation/proxy/allowlist.ts

@@ -0,0 +1,148 @@
+/**
+ * Egress allowlist: composition and matching.
+ *
+ * The allowlist composes from two layers, both recorded into the run's
+ * config_json for auditability:
+ *   (1) harness defaults — each container agent adapter declares the LLM
+ *       endpoints its CLI needs (`egressHosts` on the adapter);
+ *   (2) runtime contribution — the experiment runtime's
+ *       `egressHosts(metadata)` (product endpoints, package registries).
+ *
+ * Matching is deliberately narrow: exact hostnames and `*.domain` subdomain
+ * wildcards only — no path rules, no IP rules, no CIDR. Raw-IP CONNECT
+ * targets are refused outright (closing the resolve-then-dial DNS bypass),
+ * so IP literals in the allowlist itself are rejected at compose time.
+ */
+
+/** An allowlist entry is invalid (IP literal, port, scheme, path, bad wildcard). */
+export class AllowlistEntryError extends Error {
+  constructor(entry: string, problem: string) {
+    super(`invalid egress allowlist entry "${entry}": ${problem}`);
+    this.name = "AllowlistEntryError";
+  }
+}
+
+const LABEL = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+/**
+ * Normalize one host for matching: lowercase, strip a single trailing dot
+ * (DNS absolute form — `evil.com.` resolves identically to `evil.com` and
+ * must match the same allowlist entries, never bypass them).
+ */
+export function normalizeHost(host: string): string {
+  const lowered = host.toLowerCase();
+  return lowered.endsWith(".") ? lowered.slice(0, -1) : lowered;
+}
+
+/**
+ * Is this host an IP literal (any form)? The proxy refuses raw-IP CONNECTs
+ * regardless of allowlist, so this is deliberately over-broad: dotted quads,
+ * anything with a colon (IPv6), bracketed literals, all-digit decimal forms
+ * (`http://2130706433/`), and 0x-prefixed hex forms all count.
+ */
+export function isRawIpHost(host: string): boolean {
+  const h = normalizeHost(host);
+  if (h.length === 0) return true;
+  if (h.includes(":") || h.startsWith("[")) return true; // IPv6 / bracketed
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(h)) return true; // dotted quad
+  if (/^\d+$/.test(h)) return true; // decimal int form
+  if (/^0x[0-9a-f]+$/.test(h)) return true; // hex int form
+  if (/^[\d.]+$/.test(h)) return true; // partial numeric forms (1.2.3, 1.2)
+  return false;
+}
+
+/** Validate one entry (exact host or `*.domain`); returns its normalized form. */
+export function validateAllowlistEntry(entry: string): string {
+  const normalized = normalizeHost(entry.trim());
+  if (normalized.length === 0) throw new AllowlistEntryError(entry, "empty");
+  if (/[/?#\s]/.test(normalized) || normalized.includes("://")) {
+    throw new AllowlistEntryError(entry, "must be a bare hostname (no scheme, path, or spaces)");
+  }
+  if (normalized.includes(":")) {
+    throw new AllowlistEntryError(entry, "must not carry a port (allowlisting is hostname-granularity)");
+  }
+  const body = normalized.startsWith("*.") ? normalized.slice(2) : normalized;
+  if (body.includes("*")) {
+    throw new AllowlistEntryError(entry, "wildcards are subdomain-only: a single leading `*.` label");
+  }
+  if (isRawIpHost(body)) {
+    throw new AllowlistEntryError(entry, "IP literals are refused by the proxy — allowlist hostnames only");
+  }
+  // Single-label hosts are legal: Docker-network service names ("origin")
+  // and localhost matter for tests and runtime-provisioned local services.
+  const labels = body.split(".");
+  if (!labels.every((label) => LABEL.test(label))) {
+    throw new AllowlistEntryError(entry, "not a valid hostname");
+  }
+  return normalized;
+}
+
+/**
+ * Does `host` match the allowlist? Exact entries match the whole hostname
+ * (case-insensitively, trailing dot stripped); `*.domain` entries match any
+ * subdomain of `domain` — at least one extra label, never `domain` itself
+ * (which is why runtimes list both `example.com` and `*.example.com`).
+ * IP literals never match anything.
+ */
+export function hostAllowed(host: string, allowlist: readonly string[]): boolean {
+  const h = normalizeHost(host);
+  if (isRawIpHost(h)) return false;
+  for (const entry of allowlist) {
+    const e = normalizeHost(entry);
+    if (e.startsWith("*.")) {
+      const suffix = e.slice(1); // ".domain"
+      if (h.endsWith(suffix) && h.length > suffix.length) return true;
+    } else if (h === e) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Parse a CONNECT authority-form target (`host:port`, `[v6]:port`) or a bare
+ * host. Returns undefined for garbage. The port defaults to 443 — CONNECT
+ * targets are overwhelmingly TLS.
+ */
+export function parseHostPort(target: string): { host: string; port: number } | undefined {
+  const trimmed = target.trim();
+  if (trimmed.length === 0) return undefined;
+  let host: string;
+  let portText: string | undefined;
+  if (trimmed.startsWith("[")) {
+    // Bracketed IPv6 literal: [::1]:443 — kept intact so isRawIpHost sees it.
+    const end = trimmed.indexOf("]");
+    if (end === -1) return undefined;
+    host = trimmed.slice(0, end + 1);
+    const rest = trimmed.slice(end + 1);
+    if (rest.startsWith(":")) portText = rest.slice(1);
+    else if (rest !== "") return undefined;
+  } else {
+    const colon = trimmed.lastIndexOf(":");
+    // A second colon means an unbracketed IPv6 literal: keep whole as host.
+    if (colon !== -1 && trimmed.indexOf(":") === colon) {
+      host = trimmed.slice(0, colon);
+      portText = trimmed.slice(colon + 1);
+    } else {
+      host = trimmed;
+    }
+  }
+  if (host.length === 0) return undefined;
+  if (portText === undefined) return { host, port: 443 };
+  if (!/^\d{1,5}$/.test(portText)) return undefined;
+  const port = Number(portText);
+  if (port < 1 || port > 65535) return undefined;
+  return { host, port };
+}
+
+/**
+ * Compose a validated allowlist from an explicit host list (the runner
+ * unions runtime- and adapter-declared hosts before calling). Validated,
+ * normalized, deduplicated, sorted — the sorted list is what lands in
+ * config_json, so two identical runs record identical allowlists.
+ */
+export function composeAllowlistFromHosts(hosts: readonly string[]): string[] {
+  const entries = new Set<string>();
+  for (const host of hosts) entries.add(validateAllowlistEntry(host));
+  return [...entries].sort();
+}

package/src/isolation/proxy/server.ts

@@ -0,0 +1,382 @@
+/**
+ * The egress allowlist proxy: a small HTTP CONNECT / absolute-form forward
+ * proxy (no squid dependency, no TLS interception).
+ *
+ * Attempt containers sit on an internal Docker network with no default
+ * route; this proxy straddles that network and the bridge, and the attempt
+ * env carries HTTP_PROXY/HTTPS_PROXY pointing here. For HTTPS the proxy sees
+ * only the CONNECT `host:port` — allowlist enforcement is hostname-granular,
+ * traffic is never decrypted. Deny-by-default; denials answer 403 naming the
+ * host; raw-IP CONNECT targets are refused outright (no DNS-bypass hole).
+ *
+ * Every decision (allowed AND denied) is emitted as one stable JSON event —
+ * to `onEvent` in-process, and as a JSON line on stdout when run as the
+ * sidecar entrypoint. Denials become the attempt's `egress-denials.log`
+ * artifact; zero allowed connections from an errored attempt is the
+ * `egress_no_route` signal (an agent whose HTTP stack ignored proxy env).
+ *
+ * Threat model (also in README): a MISBEHAVING agent, not a determined
+ * adversary — a hostile workload could still tunnel over an allowlisted
+ * host.
+ */
+
+import { connect, createServer, type Server, type Socket } from "node:net";
+import { hostAllowed, isRawIpHost, normalizeHost, parseHostPort, validateAllowlistEntry } from "./allowlist.ts";
+
+/** One proxy decision. The line shape is stable — consumers parse it. */
+export interface EgressEvent {
+  type: "egress";
+  /** ISO-8601 timestamp. */
+  ts: string;
+  /** Client IP (the attempt container's internal-network address). */
+  client: string;
+  /** "CONNECT" for tunnels, the HTTP method for plain forwards. */
+  method: string;
+  host: string;
+  port: number;
+  decision: "allowed" | "denied";
+  /** Present on denials only. */
+  reason?: "not_allowlisted" | "raw_ip" | "bad_request";
+}
+
+export interface EgressProxyOptions {
+  /** Validated at start; entries are exact hosts or `*.domain` wildcards. */
+  allowlist: readonly string[];
+  /** 0 (default) picks a random free port. Sidecar runs pass a fixed one. */
+  port?: number;
+  /** Bind address. Default 0.0.0.0 (the sidecar must accept from the internal network). */
+  hostname?: string;
+  /** Decision sink (both allowed and denied). */
+  onEvent?: (event: EgressEvent) => void;
+}
+
+export interface EgressProxyHandle {
+  port: number;
+  close(): Promise<void>;
+}
+
+/** How long a client may take to send its request head. */
+const HEAD_TIMEOUT_MS = 30_000;
+/** How long an upstream TCP connect may take. */
+const CONNECT_TIMEOUT_MS = 20_000;
+/** Request heads larger than this are dropped (nothing legitimate is close). */
+const MAX_HEAD_BYTES = 32 * 1024;
+
+/** Hop-by-hop headers never forwarded upstream on plain-HTTP forwards. */
+const DROPPED_HEADERS = /^(proxy-connection|proxy-authorization|connection|keep-alive|te|upgrade|transfer-encoding)$/i;
+
+function writeAndClose(socket: Socket, response: string): void {
+  socket.write(response, () => socket.end());
+}
+
+function httpError(status: number, statusText: string, body: string): string {
+  return (
+    `HTTP/1.1 ${status} ${statusText}\r\n` +
+    "Content-Type: text/plain; charset=utf-8\r\n" +
+    `Content-Length: ${Buffer.byteLength(body)}\r\n` +
+    "Connection: close\r\n\r\n" +
+    body
+  );
+}
+
+/** Start the proxy. Resolves once listening. */
+export function startEgressProxy(options: EgressProxyOptions): Promise<EgressProxyHandle> {
+  // Fail fast on a malformed allowlist — a sidecar that silently allowed
+  // nothing (or crashed per-request) would fail every attempt wholesale.
+  const allowlist = options.allowlist.map(validateAllowlistEntry);
+  const onEvent = options.onEvent ?? (() => {});
+
+  const server: Server = createServer((client) => {
+    client.on("error", () => client.destroy());
+    const clientIp = client.remoteAddress ?? "unknown";
+    let buffered = Buffer.alloc(0);
+    let done = false;
+
+    const headTimer = setTimeout(() => {
+      if (!done) client.destroy();
+    }, HEAD_TIMEOUT_MS);
+
+    const emit = (
+      method: string,
+      host: string,
+      port: number,
+      decision: EgressEvent["decision"],
+      reason?: EgressEvent["reason"],
+    ): void => {
+      onEvent({
+        type: "egress",
+        ts: new Date().toISOString(),
+        client: clientIp,
+        method,
+        host,
+        port,
+        decision,
+        ...(reason ? { reason } : {}),
+      });
+    };
+
+    const onData = (chunk: Buffer): void => {
+      buffered = Buffer.concat([buffered, chunk]);
+      const headEnd = buffered.indexOf("\r\n\r\n");
+      if (headEnd === -1) {
+        if (buffered.length > MAX_HEAD_BYTES) {
+          done = true;
+          clearTimeout(headTimer);
+          writeAndClose(client, httpError(400, "Bad Request", "request head too large\n"));
+        }
+        return;
+      }
+      done = true;
+      clearTimeout(headTimer);
+      client.removeListener("data", onData);
+      client.pause();
+
+      const head = buffered.subarray(0, headEnd).toString("latin1");
+      const remainder = buffered.subarray(headEnd + 4);
+      buffered = Buffer.alloc(0);
+      handleRequest(client, head, remainder, emit, allowlist);
+    };
+    client.on("data", onData);
+  });
+
+  // Track live client sockets so close() can sever open tunnels — a
+  // long-lived CONNECT tunnel would otherwise keep the server open forever.
+  const open = new Set<Socket>();
+  server.on("connection", (socket) => {
+    open.add(socket);
+    socket.on("close", () => open.delete(socket));
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? 0, options.hostname ?? "0.0.0.0", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      resolve({
+        port,
+        close: () =>
+          new Promise<void>((done) => {
+            for (const socket of open) socket.destroy();
+            server.close(() => done());
+          }),
+      });
+    });
+  });
+}
+
+function handleRequest(
+  client: Socket,
+  head: string,
+  remainder: Buffer,
+  emit: (
+    method: string,
+    host: string,
+    port: number,
+    decision: EgressEvent["decision"],
+    reason?: EgressEvent["reason"],
+  ) => void,
+  allowlist: readonly string[],
+): void {
+  const lines = head.split("\r\n");
+  const requestLine = lines[0] ?? "";
+  const parts = requestLine.split(" ");
+  if (parts.length !== 3) {
+    emit(parts[0] ?? "?", "", 0, "denied", "bad_request");
+    writeAndClose(client, httpError(400, "Bad Request", `malformed request line: "${requestLine}"\n`));
+    return;
+  }
+  const [method, target] = parts as [string, string, string];
+
+  if (method === "CONNECT") {
+    handleConnect(client, target, remainder, emit, allowlist);
+  } else {
+    handleForward(client, method, target, lines.slice(1), remainder, emit, allowlist);
+  }
+}
+
+/** Shared allow/deny gate. Writes the 403 (naming the host) on denial. */
+function gate(
+  client: Socket,
+  method: string,
+  host: string,
+  port: number,
+  emit: (
+    method: string,
+    host: string,
+    port: number,
+    decision: EgressEvent["decision"],
+    reason?: EgressEvent["reason"],
+  ) => void,
+  allowlist: readonly string[],
+): boolean {
+  const normalized = normalizeHost(host);
+  if (isRawIpHost(normalized)) {
+    emit(method, normalized, port, "denied", "raw_ip");
+    writeAndClose(
+      client,
+      httpError(403, "Forbidden", `egress blocked: raw-IP targets are refused ("${normalized}") — use a hostname\n`),
+    );
+    return false;
+  }
+  if (!hostAllowed(normalized, allowlist)) {
+    emit(method, normalized, port, "denied", "not_allowlisted");
+    writeAndClose(
+      client,
+      httpError(403, "Forbidden", `egress blocked: "${normalized}" is not on this run's egress allowlist\n`),
+    );
+    return false;
+  }
+  emit(method, normalized, port, "allowed");
+  return true;
+}
+
+/** Dial upstream with a connect timeout; invoke ready exactly once on success. */
+function dialUpstream(client: Socket, host: string, port: number, ready: (upstream: Socket) => void): void {
+  const upstream = connect(port, host);
+  let established = false;
+  const connectTimer = setTimeout(() => {
+    if (!established) upstream.destroy(new Error("connect timeout"));
+  }, CONNECT_TIMEOUT_MS);
+  upstream.once("connect", () => {
+    established = true;
+    clearTimeout(connectTimer);
+    ready(upstream);
+  });
+  upstream.on("error", (err) => {
+    clearTimeout(connectTimer);
+    if (!established) {
+      writeAndClose(client, httpError(502, "Bad Gateway", `upstream connect to ${host}:${port} failed: ${err.message}\n`));
+    } else {
+      client.destroy();
+    }
+  });
+}
+
+/** Bidirectional tunnel wiring shared by CONNECT and plain forwards. */
+function pipeBoth(client: Socket, upstream: Socket): void {
+  client.pipe(upstream);
+  upstream.pipe(client);
+  client.on("close", () => upstream.destroy());
+  upstream.on("close", () => client.destroy());
+  client.on("error", () => upstream.destroy());
+}
+
+/** CONNECT host:port — the HTTPS path. The tunnel is opaque to the proxy. */
+function handleConnect(
+  client: Socket,
+  target: string,
+  remainder: Buffer,
+  emit: (
+    method: string,
+    host: string,
+    port: number,
+    decision: EgressEvent["decision"],
+    reason?: EgressEvent["reason"],
+  ) => void,
+  allowlist: readonly string[],
+): void {
+  const parsed = parseHostPort(target);
+  if (!parsed) {
+    emit("CONNECT", target, 0, "denied", "bad_request");
+    writeAndClose(client, httpError(400, "Bad Request", `malformed CONNECT target: "${target}"\n`));
+    return;
+  }
+  if (!gate(client, "CONNECT", parsed.host, parsed.port, emit, allowlist)) return;
+
+  dialUpstream(client, normalizeHost(parsed.host), parsed.port, (upstream) => {
+    client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+    // Bytes the client sent eagerly after its head (e.g. an early TLS hello).
+    if (remainder.length > 0) upstream.write(remainder);
+    pipeBoth(client, upstream);
+    client.resume();
+  });
+}
+
+/**
+ * Plain-HTTP forward: proxy clients send absolute-form URIs
+ * (`GET http://host/path HTTP/1.1`). The request is rewritten to origin form
+ * with `Connection: close` (one exchange per connection — simple beats
+ * keep-alive bookkeeping in a harness proxy).
+ */
+function handleForward(
+  client: Socket,
+  method: string,
+  target: string,
+  headerLines: string[],
+  remainder: Buffer,
+  emit: (
+    method: string,
+    host: string,
+    port: number,
+    decision: EgressEvent["decision"],
+    reason?: EgressEvent["reason"],
+  ) => void,
+  allowlist: readonly string[],
+): void {
+  let url: URL;
+  try {
+    url = new URL(target);
+  } catch {
+    emit(method, target, 0, "denied", "bad_request");
+    writeAndClose(
+      client,
+      httpError(400, "Bad Request", `expected an absolute-form proxy request URI, got "${target}"\n`),
+    );
+    return;
+  }
+  if (url.protocol !== "http:") {
+    emit(method, url.hostname, 0, "denied", "bad_request");
+    writeAndClose(client, httpError(400, "Bad Request", `unsupported scheme "${url.protocol}" (https uses CONNECT)\n`));
+    return;
+  }
+  const host = url.hostname;
+  const port = url.port === "" ? 80 : Number(url.port);
+  if (!gate(client, method, host, port, emit, allowlist)) return;
+
+  const kept = headerLines.filter((line) => !DROPPED_HEADERS.test(line.split(":")[0] ?? ""));
+  const originForm = `${url.pathname}${url.search}`;
+  // Head assembled as lines and joined ONCE: an empty `kept` must not leave
+  // a blank line after the request line (that would end the header block
+  // early and push "Connection: close" into the body).
+  const rewritten = [`${method} ${originForm === "" ? "/" : originForm} HTTP/1.1`, ...kept, "Connection: close", "", ""].join(
+    "\r\n",
+  );
+
+  dialUpstream(client, normalizeHost(host), port, (upstream) => {
+    upstream.write(rewritten);
+    if (remainder.length > 0) upstream.write(remainder);
+    pipeBoth(client, upstream);
+    client.resume();
+  });
+}
+
+/**
+ * Sidecar entrypoint (images/egress-proxy). Config via env:
+ *   QUICKSTUDY_EGRESS_ALLOWLIST  comma-separated entries (required)
+ *   QUICKSTUDY_EGRESS_PORT       listen port (default 3128)
+ * Every decision prints as one JSON line on stdout; the harness reads them
+ * back with `docker logs` for per-attempt denial artifacts.
+ */
+if (import.meta.main) {
+  const rawList = process.env["QUICKSTUDY_EGRESS_ALLOWLIST"] ?? "";
+  const allowlist = rawList
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "");
+  const port = Number(process.env["QUICKSTUDY_EGRESS_PORT"] ?? "3128");
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    console.error(`egress-proxy: invalid QUICKSTUDY_EGRESS_PORT "${process.env["QUICKSTUDY_EGRESS_PORT"]}"`);
+    process.exit(1);
+  }
+  try {
+    const handle = await startEgressProxy({
+      allowlist,
+      port,
+      onEvent: (event) => console.log(JSON.stringify(event)),
+    });
+    console.log(JSON.stringify({ type: "listening", port: handle.port, allowlist }));
+  } catch (err) {
+    console.error(`egress-proxy: failed to start: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}

package/src/llm.ts

@@ -0,0 +1,132 @@
+/**
+ * The one seam between quickstudy and the model provider: a tiny
+ * structured-output client interface, an Anthropic-backed implementation,
+ * and a validate-with-one-re-ask helper.
+ *
+ * Every host-side LLM call goes through this seam, so tests mock a single
+ * interface and never touch the network. Design rules:
+ *   - The provider client owns transport retries (3x on 429/5xx/connection).
+ *   - Structured output is requested via `output_config.format` json_schema,
+ *     so parsing never fails silently; a schema-invalid response gets exactly
+ *     ONE re-ask with the error appended, then becomes a hard
+ *     `ModelOutputError` the caller handles per its own error contract.
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+import type { z } from "zod";
+
+/** One structured-output request. `schema` is a JSON Schema object. */
+export interface StructuredRequest {
+  model: string;
+  system: string;
+  user: string;
+  maxTokens: number;
+  /** JSON Schema the response must satisfy (objects need additionalProperties:false). */
+  schema: Record<string, unknown>;
+}
+
+/** The seam tests mock. Returns the model's raw text response. */
+export interface StructuredModelClient {
+  requestStructured(request: StructuredRequest): Promise<string>;
+  /**
+   * The model id the provider reported for the most recent response, when
+   * known — provenance for artifacts (a pinned alias may resolve elsewhere).
+   */
+  resolvedModel?(): string | null;
+}
+
+/** The model responded, but not with schema-valid output (after one re-ask). */
+export class ModelOutputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ModelOutputError";
+  }
+}
+
+/** Spec: retry API failures 3x before surfacing them. */
+const API_MAX_RETRIES = 3;
+
+/**
+ * Anthropic-backed client. Reuses ANTHROPIC_API_KEY from the environment;
+ * transport-level retries are the SDK's (429/5xx/connection errors).
+ */
+export class AnthropicModelClient implements StructuredModelClient {
+  private readonly client: Anthropic;
+  private lastResolvedModel: string | null = null;
+
+  constructor(options: { apiKey?: string } = {}) {
+    this.client = new Anthropic({
+      ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+      maxRetries: API_MAX_RETRIES,
+    });
+  }
+
+  resolvedModel(): string | null {
+    return this.lastResolvedModel;
+  }
+
+  async requestStructured(request: StructuredRequest): Promise<string> {
+    const response = await this.client.messages.create({
+      model: request.model,
+      max_tokens: request.maxTokens,
+      system: request.system,
+      messages: [{ role: "user", content: request.user }],
+      output_config: { format: { type: "json_schema", schema: request.schema } },
+    });
+    this.lastResolvedModel = response.model;
+
+    if (response.stop_reason === "refusal") {
+      throw new ModelOutputError(`model refused the request (model: ${request.model})`);
+    }
+    if (response.stop_reason === "max_tokens") {
+      throw new ModelOutputError(
+        `model output truncated at ${request.maxTokens} tokens (model: ${request.model})`,
+      );
+    }
+
+    const text = response.content.find((block) => block.type === "text")?.text;
+    if (text === undefined) {
+      throw new ModelOutputError(`model returned no text content (model: ${request.model})`);
+    }
+    return text;
+  }
+}
+
+/**
+ * Request + parse + zod-validate, with exactly one re-ask on invalid output:
+ * the retry prompt appends the previous (bad) response and the validation
+ * error. A second failure is a hard ModelOutputError — never a silent skip.
+ */
+export async function requestValidated<T>(
+  client: StructuredModelClient,
+  request: StructuredRequest,
+  schema: z.ZodType<T>,
+): Promise<T> {
+  const attempt = (raw: string): { ok: true; value: T } | { ok: false; error: string } => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      return { ok: false, error: `response is not valid JSON: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const result = schema.safeParse(parsed);
+    if (result.success) return { ok: true, value: result.data };
+    return { ok: false, error: `response does not match the schema: ${result.error.message}` };
+  };
+
+  const first = attempt(await client.requestStructured(request));
+  if (first.ok) return first.value;
+
+  const reasked = attempt(
+    await client.requestStructured({
+      ...request,
+      user:
+        `${request.user}\n\n` +
+        `Your previous response was invalid — ${first.error}\n` +
+        `Respond again with ONLY a JSON object that matches the required schema exactly.`,
+    }),
+  );
+  if (reasked.ok) return reasked.value;
+
+  throw new ModelOutputError(`model output invalid after one re-ask: ${reasked.error}`);
+}