myapikey 0.40.2 → 0.42.0

package/README.md

@@ -124,7 +124,6 @@ npm run build:web      # build the Vue UI into packages/web/dist
 npm run dev            # gateway with watch reload
 npm run dev:web        # vite dev server (proxies API calls to :7800)
 npm test               # vitest unit + integration
-npm run test:e2e       # playwright against a real gateway process
 npm run typecheck      # tsc + vue-tsc
 ```
 

package/README.zh-CN.md

@@ -124,7 +124,6 @@ npm run build:web      # 把 Vue 界面构建到 packages/web/dist
 npm run dev            # 网关,带 watch 热重载
 npm run dev:web        # vite 开发服务器(API 代理到 :7800)
 npm test               # vitest 单测 + 集成
-npm run test:e2e       # playwright 打真实网关进程
 npm run typecheck      # tsc + vue-tsc
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myapikey",
-  "version": "0.40.2",
+  "version": "0.42.0",
   "type": "module",
   "description": "Personal LLM API gateway & proxy — one address + one API key for all your models. Forwards OpenAI & Anthropic calls to your backends with failover and a circuit breaker. Pure passthrough, no format translation. Self-hosted (CLI + web UI).",
   "keywords": [
@@ -52,7 +52,7 @@
     "packages/*"
   ],
   "scripts": {
-    "dev": "tsx watch packages/core/src/cli/index.ts serve",
+    "dev": "NODE_ENV=development tsx watch packages/core/src/cli/index.ts serve",
     "dev:web": "npm run dev -w @myapikey/web",
     "start": "npm run build:web && npm run serve",
     "serve": "tsx packages/core/src/cli/index.ts serve",
@@ -60,8 +60,7 @@
     "build:web": "npm run build -w @myapikey/web",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "playwright test"
+    "test:coverage": "vitest run --coverage"
   },
   "engines": {
     "node": ">=18"
@@ -76,7 +75,6 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@playwright/test": "^1.62.1",
     "@types/node": "^22.7.0",
     "@vitest/coverage-v8": "^2.1.9",
     "jsdom": "^30.0.1",

package/packages/core/src/cli/index.ts

@@ -181,7 +181,7 @@ model.command("list").action(async () => {
     console.log(m.name);
     for (const f of fmts) {
       const fe = m[f];
-      const chain = fe.providers.map((p: any) => `${p.model ? `${p.name}→${p.model}` : p.name}${p.thinking ? ` thinking=${p.thinking}` : ""}`).join(" → ") || "(none)";
+      const chain = fe.providers.map((p: any) => `${p.model ? `${p.name}→${p.model}` : p.name}${p.thinking ? ` thinking=${p.thinking}` : ""}${p.sampling ? ` sampling=${JSON.stringify(p.sampling)}` : ""}`).join(" → ") || "(none)";
       console.log(`  ${f.padEnd(9)} ${fe.enabled ? "✓" : "·"} ${chain}`);
     }
     if (m.paceRpm) console.log(`  pace      ${m.paceRpm}/min (one every ${Math.round(60 / m.paceRpm)}s)`);
@@ -278,6 +278,28 @@ model
     );
   });
 
+model
+  .command("sampling <name> <index> [json]")
+  .description(`set/clear the default sampling parameters of one chain slot as a JSON object (e.g. '{"temperature":0.2,"top_p":0.9}'; each field overrides the request's own value; empty = clear)`)
+  .addOption(fmtOption())
+  .action(async (name: string, indexRaw: string, value: string | undefined, opts: { format: "openai" | "anthropic" | "responses" }) => {
+    const index = Number(indexRaw);
+    let sampling: Record<string, unknown> | undefined;
+    if (value !== undefined && value.trim()) {
+      try {
+        sampling = JSON.parse(value) as Record<string, unknown>;
+      } catch {
+        throw new Error(`sampling must be a JSON object, e.g. '{"temperature":0.2}'`);
+      }
+    }
+    const r = (await api(ctx(), "PUT", `/admin/models/${encodeURIComponent(name)}/sampling`, { format: opts.format, index, sampling })) as { sampling?: Record<string, unknown> };
+    console.log(
+      r.sampling
+        ? `Default sampling for ${name} [${opts.format}] slot ${index}: ${JSON.stringify(r.sampling)}.`
+        : `Default sampling cleared for ${name} [${opts.format}] slot ${index}.`,
+    );
+  });
+
 model.command("remove <name>").description("remove a model entirely (both formats)").action(async (name: string) => {
   await api(ctx(), "DELETE", `/admin/models/${encodeURIComponent(name)}`);
   console.log(`Removed ${name}.`);

package/packages/core/src/server/admin.ts

@@ -44,6 +44,31 @@ function providerSpeaks(p: Provider, key: RouteKey): boolean {
   return key === "responses" ? !!p.supportsResponses : p.formats.includes(key);
 }
 
+/** The body fields a chain slot's sampling default may set — the wire-agnostic
+ *  names, identical on all three routes (see applySlotSampling in proxy.ts). */
+const SAMPLING_KEYS = ["temperature", "top_p", "top_k", "presence_penalty", "frequency_penalty", "seed"] as const;
+
+/** Validate a slot's sampling default: whitelisted keys only, every value a
+ *  finite number (`seed` an integer). Numeric strings are coerced (form fields
+ *  send strings). Returns the cleaned record; undefined when absent/empty
+ *  (clear); null = invalid (unknown key, non-numeric value, fractional seed). */
+function sanitizeSampling(v: unknown): Record<string, number> | undefined | null {
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "object" || Array.isArray(v)) return null;
+  const out: Record<string, number> = {};
+  for (const [k, raw] of Object.entries(v as Record<string, unknown>)) {
+    if (!(SAMPLING_KEYS as readonly string[]).includes(k)) return null;
+    const n = typeof raw === "string" ? Number(raw.trim()) : raw;
+    if (typeof n !== "number" || !Number.isFinite(n)) return null;
+    if (k === "seed" && !Number.isInteger(n)) return null;
+    out[k] = n;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+const SAMPLING_ERR =
+  "sampling: keys must be temperature/top_p/top_k/presence_penalty/frequency_penalty/seed with finite numeric values (seed an integer)";
+
 /** Inverse of proxy's encodeTag: the probe's x-myapikey-provider header carries
  *  a %-encoded provider name (HTTP headers are Latin-1, so a name like "商汤"
  *  can't travel raw). Decode it back for display; fall back to the raw value if
@@ -155,6 +180,8 @@ function projectModel(name: string, e: ModelEntry, byId: Map<string, Provider>)
       model: s.model,
       // Default thinking level for this slot (undefined = pure passthrough).
       thinking: s.thinking,
+      // Default sampling parameters for this slot (undefined = pure passthrough).
+      sampling: s.sampling,
     })),
   });
   return {
@@ -514,7 +541,7 @@ export function adminApi(store: Store, auth: MiddlewareHandler, openai: Hono, an
       if (!raw) continue;
       const chain: ChainSlot[] = [];
       for (const s of Array.isArray(raw.slots) ? raw.slots : []) {
-        const slot = s as { id?: unknown; model?: unknown; thinking?: unknown };
+        const slot = s as { id?: unknown; model?: unknown; thinking?: unknown; sampling?: unknown };
         const pid = typeof slot?.id === "string" ? slot.id : "";
         const p = cfg.providers.find((x) => x.id === pid);
         if (!p) return c.json({ error: { message: `provider not found: ${pid || "(empty)"}` } }, 400);
@@ -526,9 +553,12 @@ export function adminApi(store: Store, auth: MiddlewareHandler, openai: Hono, an
           return c.json({ error: { message: "anthropic thinking default must be a positive integer (thinking budget tokens, e.g. 8192)" } }, 400);
         if (thinkRaw && key !== "anthropic" && thinkRaw.length > 32)
           return c.json({ error: { message: "thinking default too long (max 32 chars)" } }, 400);
+        const sampling = sanitizeSampling(slot.sampling);
+        if (sampling === null) return c.json({ error: { message: SAMPLING_ERR } }, 400);
         const cs: ChainSlot = { id: pid };
         if (model) cs.model = model;
         if (thinkRaw) cs.thinking = key === "anthropic" ? String(Number(thinkRaw)) : thinkRaw;
+        if (sampling) cs.sampling = sampling;
         chain.push(cs);
       }
       parsed[key] = { enabled: raw.enabled !== false, providers: chain };
@@ -827,6 +857,45 @@ app.delete("/models/:name/debug/fails", (c) => {
     return c.json({ ok: true, thinking: value || undefined });
   });
 
+  // Set (or clear) the default sampling parameters for ONE chain slot (addressed
+  // by `index`, like /thinking above). The value is a JSON object of wire-agnostic
+  // sampling fields — temperature/top_p/top_k/presence_penalty/frequency_penalty/
+  // seed, each a finite number (seed an integer). On dispatch each configured
+  // field REPLACES the request's own same-named parameter; unconfigured fields
+  // pass through. An absent or empty object clears it (pure passthrough).
+  app.put("/models/:name/sampling", async (c) => {
+    const name = c.req.param("name");
+    const body = await readJson<{ format?: RouteKey; index?: number; sampling?: unknown }>(c.req.raw);
+    if (!body?.format) return c.json({ error: { message: "format is required" } }, 400);
+    if (!Number.isInteger(body?.index) || (body?.index ?? -1) < 0)
+      return c.json({ error: { message: "index (non-negative integer) is required" } }, 400);
+    const value = sanitizeSampling(body.sampling);
+    if (value === null) return c.json({ error: { message: SAMPLING_ERR } }, 400);
+    const format = body.format;
+    const index = body.index!;
+    let errStatus = 0;
+    let errMsg = "";
+    await store.update((d) => {
+      const entry = d.models[name];
+      if (!entry) {
+        errStatus = 404;
+        errMsg = "model not found";
+        return;
+      }
+      const fe = entry[format];
+      if (index >= fe.providers.length) {
+        errStatus = 400;
+        errMsg = "index out of range for this model's chain";
+        return;
+      }
+      if (value) fe.providers[index].sampling = value;
+      else delete fe.providers[index].sampling;
+    });
+    if (errStatus === 404) return c.json({ error: { message: errMsg } }, 404);
+    if (errStatus === 400) return c.json({ error: { message: errMsg } }, 400);
+    return c.json({ ok: true, sampling: value ?? undefined });
+  });
+
   app.post("/models/:name/disable", async (c) => {
     const name = c.req.param("name");
     const body = await readJson<{ format?: RouteKey }>(c.req.raw);

package/packages/core/src/server/auth.ts

@@ -38,6 +38,10 @@ export function extractSecret(c: Context): { password: string; username?: string
 /** Hono middleware: require the single account/password. */
 export function authMiddleware(getUser: () => string, getPass: () => string, logger?: Logger): MiddlewareHandler {
   return async (c, next) => {
+    // Dev convenience: `npm run dev` sets NODE_ENV=development, and iterating on
+    // the UI/CLI against scratch data dirs shouldn't fight a fresh random
+    // password on every run. Production (`serve`) never sees this.
+    if (process.env.NODE_ENV === "development") return next();
     const cred = extractSecret(c);
     const ok =
       !!cred &&

package/packages/core/src/server/proxy.ts

@@ -97,14 +97,15 @@ function parseResetFromBody(text: string): number | undefined {
 }
 
 /** One resolved routing slot: the provider to forward to plus THIS slot's
- *  optional upstream model name (absent = send the public model name) and
- *  default thinking level. The same provider may occupy several slots in a
- *  chain — each is an independent failover slot carrying its own upstream
- *  model. */
+ *  optional upstream model name (absent = send the public model name), default
+ *  thinking level and default sampling parameters. The same provider may occupy
+ *  several slots in a chain — each is an independent failover slot carrying its
+ *  own overrides. */
 interface CandidateSlot {
   provider: Provider;
   model?: string;
   thinking?: string;
+  sampling?: Record<string, unknown>;
 }
 
 /** Resolve the ordered, compatible provider slots for a model on a routing slot. */
@@ -120,7 +121,7 @@ function candidates(store: Store, model: string, key: RouteKey): CandidateSlot[]
   return fe.providers
     .map((s): CandidateSlot | null => {
       const p = byId.get(s.id);
-      return p ? { provider: p, model: s.model, thinking: s.thinking } : null;
+      return p ? { provider: p, model: s.model, thinking: s.thinking, sampling: s.sampling } : null;
     })
     .filter((slot): slot is CandidateSlot => {
       if (!slot) return false;
@@ -244,6 +245,54 @@ function applySlotThinking(
   return { value: def, from: "default" };
 }
 
+// --- per-slot default sampling parameters -------------------------------------
+// Like the thinking level, each routing slot can carry default sampling
+// parameters — but the override semantics differ where the wires differ.
+// Thinking owns EVERY thinking switch (a forced level alongside a stale client
+// switch would contradict itself), while sampling overrides ONLY the fields it
+// configures: temperature=0.2 with the client's own top_p intact is coherent.
+// A configured field replaces the request's value; an unconfigured field — and
+// everything on a slot without defaults — passes through, restored verbatim
+// when an earlier failover slot overrode it. The names are identical on all
+// three wires (openai chat/completions, /responses, anthropic messages), so
+// there is no per-format dialect and no translation.
+
+/** The body fields a slot's sampling default may set — the wire-agnostic names,
+ *  the same set on every route. */
+const SAMPLING_FIELDS = ["temperature", "top_p", "top_k", "presence_penalty", "frequency_penalty", "seed"] as const;
+
+/** Apply THIS slot's sampling defaults to the body (mutating it), and return
+ *  the log row's `sampling` field: the fields the gateway injected. Undefined =
+ *  nothing injected (no default configured, or none of the fields set). A slot
+ *  WITH defaults overrides exactly those fields; all others restore the
+ *  request's originals — same recompute-per-attempt discipline as the model
+ *  rewrite and the thinking level, so slot A's values never leak into slot B. */
+function applySlotSampling(
+  body: Record<string, unknown>,
+  def: Record<string, unknown> | undefined,
+  orig: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  if (!def) {
+    for (const f of SAMPLING_FIELDS) {
+      if (orig[f] === undefined) delete body[f];
+      else body[f] = orig[f];
+    }
+    return undefined;
+  }
+  const applied: Record<string, unknown> = {};
+  for (const f of SAMPLING_FIELDS) {
+    const v = def[f];
+    if (v === undefined) {
+      if (orig[f] === undefined) delete body[f];
+      else body[f] = orig[f];
+    } else {
+      body[f] = v;
+      applied[f] = v;
+    }
+  }
+  return Object.keys(applied).length ? applied : undefined;
+}
+
 /** Auth headers for the Anthropic wire format. Sends BOTH x-api-key and
  *  Authorization: Bearer (same key). Native Anthropic (api.anthropic.com)
  *  accepts either; anthropic- COMPATIBLE surfaces (sensenova, Volcengine Ark,
@@ -502,6 +551,10 @@ export function proxyApi(
       fields: Object.fromEntries(thinkingFields(key).map((f) => [f, body[f]])),
       maxTokens: body.max_tokens,
     };
+    // The request's own sampling parameters, snapshotted alongside the thinking
+    // switches (same reason: each attempt mutates the shared body, and a slot
+    // without defaults must restore these originals).
+    const samplingOrig: Record<string, unknown> = Object.fromEntries(SAMPLING_FIELDS.map((f) => [f, body[f]]));
     // The model-page "test" button drives dispatch via an in-process loopback
     // (adminApi calls v1.request). The probe is a real call in every respect —
     // including being logged — so we only tag it to report WHICH provider
@@ -545,6 +598,9 @@ export function proxyApi(
     // Thinking level of the most recent attempt (for the all-failed row after
     // the rounds loop; per-attempt rows capture the loop's own `think` const).
     let lastThink: { value: string; from: "client" | "default" } | undefined;
+    // Sampling fields the most recent attempt injected (for the all-failed row
+    // after the rounds loop; per-attempt rows capture the loop's own `sampling`).
+    let lastSampling: Record<string, unknown> | undefined;
     // Runtime log (console + server.log). Errors and notable events only — the
     // per-call history these lines summarize goes to pushLog/logs.jsonl anyway.
     // UI-triggered probes are excluded: their outcome is shown inline already.
@@ -640,6 +696,11 @@ export function proxyApi(
         // applySlotThinking), so slot A's level never leaks into slot B.
         const think = applySlotThinking(body, key, slot.thinking, thinkOrig);
         lastThink = think;
+        // Per-slot sampling defaults: same recompute-per-attempt discipline as
+        // the model rewrite and the thinking level (see applySlotSampling). A
+        // configured field overrides the request's own; the rest pass through.
+        const sampling = applySlotSampling(body, slot.sampling, samplingOrig);
+        lastSampling = sampling;
         // Count this attempt toward the source's RPM window — but not for a pinned
         // probe, which (like circuit state) takes no routing side-effects.
         if (pinIndex == null) store.recordDispatch(provider.id);
@@ -668,6 +729,7 @@ export function proxyApi(
             request: reqText,
             ...(upstreamModel ? { upstreamModel } : {}),
             ...(think ? { thinking: think } : {}),
+            ...(sampling ? { sampling } : {}),
             ...(response ? { response } : {}),
             ...(truncated ? { truncated: true } : {}),
             ...(error ? { error } : {}),
@@ -690,7 +752,7 @@ export function proxyApi(
           sayFailover(provider, "network error");
           const r = store.recordCircuitFailure(provider.id, lastStatus, lastErr);
           if (r.entered) {
-            store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, thinking: think, kind: "cooldown", cooldownMs: r.cooldownMs, fails: r.fails, error: lastErr });
+            store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, thinking: think, sampling, kind: "cooldown", cooldownMs: r.cooldownMs, fails: r.fails, error: lastErr });
             sayCooldown(provider, r);
           }
           continue;
@@ -728,14 +790,14 @@ export function proxyApi(
             onSettle: (info) => {
               if (info.ok) {
                 store.recordCircuitSuccess(provider.id);
-                store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: 200, ms: ttfb, stream, thinking: think, usage: info.usage });
+                store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: 200, ms: ttfb, stream, thinking: think, sampling, usage: info.usage });
                 capture(200, capAcc.text, capAcc.truncated);
               } else {
                 // A pinned per-source probe takes no circuit side-effects (a manual
                 // test must not trip the breaker) — mirrors the retryable branch.
                 if (pinIndex == null) store.recordCircuitFailure(provider.id, info.status, info.error || "stream failed");
                 if (!isProbe) rt.warn(`proxy stream failed: provider '${provider.name}' status=${info.status} (${info.error || "stream failed"})`);
-                store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: info.status, ms: ttfb, stream, thinking: think, error: info.error });
+                store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: info.status, ms: ttfb, stream, thinking: think, sampling, error: info.error });
                 capture(info.status, capAcc.text, capAcc.truncated, info.error);
               }
             },
@@ -765,13 +827,13 @@ export function proxyApi(
           const resetInMs = retryAfterMs ? undefined : parseResetFromBody(txt);
           const r = store.recordCircuitFailure(provider.id, lastStatus, lastErr, retryAfterMs ?? resetInMs, !!resetInMs);
           if (r.entered) {
-            store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, thinking: think, kind: "cooldown", cooldownMs: r.cooldownMs, fails: r.fails, error: lastErr });
+            store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, thinking: think, sampling, kind: "cooldown", cooldownMs: r.cooldownMs, fails: r.fails, error: lastErr });
             sayCooldown(provider, r);
           }
           continue;
         }
         // Non-retryable client error: return it to the caller as-is.
-        store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: upstream.status, ms: Date.now() - start, stream, thinking: think, error: lastErr });
+        store.pushLog({ ts: Date.now(), model, upstreamModel, provider: provider.name, providerId: provider.id, format: wire, status: upstream.status, ms: Date.now() - start, stream, thinking: think, sampling, error: lastErr });
         return new Response(txt, { status: upstream.status, headers: downHeaders(upstream, isProbe ? provider.name : undefined) });
       }
 
@@ -784,7 +846,7 @@ export function proxyApi(
         return new Response(null, { status: 499 });
       }
       if (!isProbe) rt.error(`proxy all providers failed model=${model} (last status ${lastStatus})`);
-      store.pushLog({ ts: Date.now(), model, upstreamModel: lastUpstreamModel, provider: last.provider.name, providerId: last.provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, thinking: lastThink, error: lastErr || `all providers failed (last status ${lastStatus})` });
+      store.pushLog({ ts: Date.now(), model, upstreamModel: lastUpstreamModel, provider: last.provider.name, providerId: last.provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, thinking: lastThink, sampling: lastSampling, error: lastErr || `all providers failed (last status ${lastStatus})` });
       // A pinned (per-source) probe failed: surface the REAL upstream status the
       // one slot returned (429/500/…), not a collapsed 502, and tag it with
       // x-myapikey-provider so the source-row badge names the tested source.

package/packages/core/src/shared/types.ts

@@ -81,6 +81,15 @@ export interface ChainSlot {
    *  ("low"/"medium"/"high"/…) on openai/responses slots, a thinking budget
    *  in tokens (positive integer) on anthropic slots. */
   thinking?: string;
+  /** Default sampling parameters for this slot. Unlike thinking (which owns
+   *  EVERY thinking switch, since a forced level plus a stale client switch
+   *  would contradict), each configured field here replaces ONLY the request's
+   *  same-named value — an unconfigured field passes through untouched.
+   *  temperature=0.2 with the client's own top_p intact is coherent, so the
+   *  override is per-field. Keys are the wire-agnostic names (temperature,
+   *  top_p, top_k, presence_penalty, frequency_penalty, seed) — identical on
+   *  all three wires, so no per-format dialect. Absent = pure passthrough. */
+  sampling?: Record<string, unknown>;
 }
 
 /** A model's routing dimensions — one per forwarding endpoint. /chat/completions
@@ -180,6 +189,12 @@ export interface LogEntry {
    *  ran, OVERRIDING whatever the request carried. Absent when neither
    *  applied (no default configured, request carried nothing). */
   thinking?: { value: string; from: "client" | "default" };
+  /** The sampling parameters the gateway injected on this call (the answering
+   *  slot's configured `sampling` defaults). Absent when the slot had none —
+   *  the request's own parameters then ran untouched. (Deliberately no
+   *  "client" variant: logging every passthrough call's sampling values would
+   *  be noise; the debug capture holds the exact forwarded body anyway.) */
+  sampling?: Record<string, unknown>;
   /** Row kind. Absent on legacy lines → treated as a normal call. "cooldown"
    *  marks a circuit-breaker event (a provider just entered cooldown), shown
    *  distinctly in the timeline alongside the failures that caused it. */
@@ -194,7 +209,7 @@ export interface LogEntry {
  *  persisted to logs.jsonl or data.json; see ModelEntry.debugCapture). One
  *  client call that fails over produces several entries, one per attempt,
  *  because each attempt's forwarded body can differ (per-slot model rewrite +
- *  thinking injection). Bodies are captured VERBATIM: `request` is the exact
+ *  thinking/sampling injection). Bodies are captured VERBATIM: `request` is the exact
  *  JSON string sent upstream, `response` the upstream body as it flowed (raw
  *  SSE text for streams). Headers are never captured — provider api keys stay
  *  out of the buffer. */
@@ -223,4 +238,6 @@ export interface DebugCapture {
   error?: string;
   /** The thinking level this attempt ran with (same shape as LogEntry.thinking). */
   thinking?: { value: string; from: "client" | "default" };
+  /** The sampling parameters injected this attempt (same shape as LogEntry.sampling). */
+  sampling?: Record<string, unknown>;
 }