@pyric/cli 0.1.0-alpha.19 → 0.1.0-alpha.21

package/src/remote/index.ts

@@ -5,7 +5,7 @@
  * Server-side Node code (ultimately `pyric-admin`'s remote dispatch arm)
  * reaches the ONE sandbox the app + Studio + agent share:
  *
- *   Node process ──ws──> `pyric dev --bridge` ──ws──> browser tab
+ *   Node process -> `pyric sandbox --bridge` -> browser tab
  *                 (attach/consumer leg)        (peer leg)
  *                                        ──MessagePort──> SharedWorker
  *
@@ -320,7 +320,7 @@ export function createRemoteSandboxCore(
           reject(
             remoteError(
               'deadline-exceeded',
-              `remote sandbox op timed out after ${opTimeoutMs}ms (op: ${payload.method}) — is pyric dev still running?` +
+              `remote sandbox op timed out after ${opTimeoutMs}ms (op: ${payload.method}). Is pyric sandbox still running?` +
                 // A version-skewed old worker accepts frames it cannot
                 // handle and never responds — a timeout is its signature.
                 (versionSkewGuidance ? ` ${versionSkewGuidance}` : ''),
@@ -379,8 +379,8 @@ export function createRemoteSandboxCore(
           msg.serveVersion !== cliVersion()
         ) {
           versionSkewGuidance =
-            `pyric dev is running version ${msg.serveVersion}, this client is ` +
-            `${cliVersion()} — restart pyric dev and reload the browser tab.`;
+            `pyric sandbox is running version ${msg.serveVersion}, this client is ` +
+            `${cliVersion()}. Restart pyric sandbox and reload the browser tab.`;
           process.stderr.write(`pyric: ${versionSkewGuidance}\n`);
         }
         if (msg.peerConnected) readyResolve();
@@ -405,7 +405,7 @@ export function createRemoteSandboxCore(
             // Version skew: a live tab whose SharedWorker predates this op.
             // Other open pages of this origin keep the old worker alive.
             message +=
-              ' — the running sandbox may predate this feature; restart pyric dev ' +
+              '. The running sandbox may predate this feature. Restart pyric sandbox ' +
               'and close other open pages of this origin, then reload.';
           }
           call.reject(remoteError(code, message, msg.error?.denialContext, (msg.error as any)?.envelope));
@@ -721,7 +721,7 @@ export function createRemoteSandboxHandle(opts: {
     enablePersistence: () =>
       throwMember(
         'enablePersistence',
-        'the browser worker owns persistence; it is already enabled by `pyric dev`',
+        'the browser worker owns persistence; it is already enabled by `pyric sandbox`',
       ),
     flush: () =>
       throwMember('flush()', 'the browser worker owns persistence and flushes itself'),
@@ -742,7 +742,7 @@ export function createRemoteSandboxHandle(opts: {
 // ─── connect ───────────────────────────────────────────────────────────────
 
 /**
- * Discover the running `pyric dev --bridge`, attach to its bridge WS as a
+ * Discover the running `pyric sandbox --bridge`, attach to its bridge WS as a
  * worker-relay CONSUMER (never a peer — attaching cannot kick the browser
  * tab out of last-connection-wins), and return the typed remote handle.
  *
@@ -770,7 +770,7 @@ export async function connectRemoteSandbox(
     if (!found) {
       throw remoteError(
         'not-found',
-        'no running `pyric dev --bridge` found (looked for .pyric/serve.json in ' +
+        'no running `pyric sandbox --bridge` found (looked for .pyric/serve.json in ' +
           `${cwd} and the default ports) — start your dev server with the bridge enabled and retry.`,
       );
     }
@@ -953,7 +953,7 @@ export function createLazyRemoteSandbox(
     // Before discovery the URL is unknown; op-level errors always carry the
     // real URL (they come from the inner connect), and `serveUrl` is patched
     // to the discovered value as soon as the first connect succeeds.
-    serveUrl: options.url?.replace(/\/$/, '') ?? '<pyric dev url (pending discovery)>',
+    serveUrl: options.url?.replace(/\/$/, '') ?? '<pyric sandbox url (pending discovery)>',
     close() {
       if (closed) return;
       closed = true;

package/src/serve/ai-diagnostics-relay.ts

@@ -0,0 +1,243 @@
+import type { SandboxEvent } from 'pyric/sandbox';
+import { capTerminalText } from './ai-terminal-text.js';
+
+/**
+ * AI diagnostics relay: headless dev visibility for the three things the
+ * broker does that no app-level signal reports.
+ *
+ * The broker lands `service_mutation` events (`service: 'ai'`) on the
+ * sandbox's unified stream. That stream is browser-side: the worker host fans
+ * it out over the port for Studio, and it never reaches the dev server. An
+ * agent driving `pyric dev` headlessly therefore saw NOTHING.
+ *
+ *   - `request_rejected`: a bad role, empty `contents`, a missing thought
+ *     signature, or an engine that answered an error envelope.
+ *   - `response_blocked`: the SILENT refusal. A safety / recitation /
+ *     blocklist filter answers HTTP 200 with an empty candidate, so nothing
+ *     throws anywhere and the app simply renders nothing.
+ *   - `model_substituted`: not a refusal at all. The answer arrives, from a
+ *     model the developer never asked for (an openai `modelMap` entry or
+ *     catch-all `model`, a gemini experimental alias). Same shape of problem:
+ *     the sandbox quietly did something other than what the code said, and
+ *     only the terminal can say so.
+ *
+ * One record per kind in {@link AI_DIAGNOSTIC_RELAYS} pairs the sandbox `op`
+ * with the narrower that turns it into a wire payload. The terminal formatter
+ * and throttle key for each kind live in `ai-terminal-blocks.ts`, keyed by the
+ * same {@link AiDiagnosticKind} union, so the compiler flags a kind that is
+ * relayed but never rendered.
+ *
+ * This is the AI twin of the Firebase Activity Guard reporter next door
+ * (`activity-guard.ts`): a browser-safe subscriber shared by the SharedWorker
+ * and in-page planes, which fire-and-forget POSTs to the dev server. It rides
+ * the DENIAL relay's existing channel (`POST /__pyric/denials`, see the denial
+ * relay section of `namespace.ts`) rather than opening a new one: a broker
+ * refusal is the same category of thing as a rules denial, it wants the same
+ * terminal treatment, and it wants that endpoint's per-(target, reason)
+ * throttle, because an agent retry loop re-sends the same request over and
+ * over.
+ *
+ * Best-effort, exactly like the activity reporter and the denial relay: never
+ * throws, never awaited into app flow, and a relay failure (dev server gone,
+ * no `fetch`, non-pyric host) is swallowed. Diagnostics, not a correctness
+ * path.
+ */
+
+/** The slice of the sandbox this relay needs. Live events only: replaying
+ *  `history()` on boot would re-announce refusals the terminal already
+ *  printed (and the activity feed's reason for taking history does not apply,
+ *  since nothing here correlates across events). */
+export interface AiDiagnosticsFeed {
+  subscribe(listener: (event: SandboxEvent) => void): unknown;
+}
+
+/** The `kind` discriminator on every payload this relay POSTs. It is also the
+ *  key of the formatter table in `ai-terminal-blocks.ts`. */
+export type AiDiagnosticKind = 'ai-rejection' | 'ai-blocked' | 'ai-model-substituted';
+
+/** The sandbox events this relay reads. */
+type ServiceMutation = Extract<SandboxEvent, { kind: 'service_mutation' }>;
+
+/** Shape POSTed for a `request_rejected` event. `namespace.ts` reads it back
+ *  loosely (`AiRejectionPayload` in `ai-terminal-blocks.ts`): the body is JSON
+ *  from the served page, and nothing on the far side enforces this type. */
+interface AiRejectionRelayPayload {
+  kind: 'ai-rejection';
+  /** Model resource the rejected op targeted (the event's `path`). */
+  model?: string;
+  /** Which engine the broker resolved to (`scripted` | `openai` | `gemini` |
+   *  `custom`); a rejection reads very differently for each. */
+  engine?: string;
+  /** Wire error status (e.g. `INVALID_ARGUMENT`) and HTTP-ish code. */
+  status?: string;
+  code?: number;
+  /** The rejection reason: production's own message for shape errors. */
+  message: string;
+}
+
+/** Shape POSTed for a `response_blocked` event. Carries the wire's own
+ *  vocabulary, `finishReason` (a candidate was withheld) or `blockReason`
+ *  (the prompt was refused), rather than a pre-rendered sentence, so the
+ *  terminal formatter owns the phrasing exactly the way it does for a
+ *  rejection. */
+interface AiBlockedRelayPayload {
+  kind: 'ai-blocked';
+  /** Model resource the blocked op targeted (the event's `path`). */
+  model?: string;
+  /** Which engine the broker resolved to. */
+  engine?: string;
+  /** Candidate-level block: `SAFETY`, `RECITATION`, `BLOCKLIST`, and so on. */
+  finishReason?: string;
+  /** Production's own explanatory text for the block, when it sent one. */
+  finishMessage?: string;
+  /** Prompt-level block: `promptFeedback.blockReason`. */
+  blockReason?: string;
+}
+
+/** Shape POSTed for a `model_substituted` event. Not a refusal: the answer
+ *  arrives normally, just from a model the developer never named. */
+interface AiModelSubstitutionRelayPayload {
+  kind: 'ai-model-substituted';
+  /** The model the request asked for (the event's `path`). */
+  requestedModel: string;
+  /** The model the engine actually calls (bare, no `models/` prefix). */
+  effectiveModel: string;
+  /** Which engine substituted (`openai` | `gemini` | ...). */
+  engine?: string;
+  /** Why it differs, e.g. `engine modelMap`, `experimental alias`. */
+  reason?: string;
+}
+
+type AiDiagnosticRelayPayload =
+  | AiRejectionRelayPayload
+  | AiBlockedRelayPayload
+  | AiModelSubstitutionRelayPayload;
+
+/**
+ * A string field off the event's free-form `detail` record, or `undefined`
+ * when the emitter did not set it. `detail` is a public contract anyone can
+ * post onto, so every field is re-checked, and every value is length-capped
+ * here rather than on the far side: a model server that answers with a
+ * megabyte in its `finishMessage` must not push a megabyte through the
+ * fire-and-forget POST just to have the terminal cut it.
+ */
+function detailText(detail: Record<string, unknown>, field: string): string | undefined {
+  const value = detail[field];
+  if (typeof value !== 'string') return undefined;
+  return capTerminalText(value);
+}
+
+/** The event's `path` when it names a model, or `undefined`. */
+function eventModel(event: ServiceMutation): string | undefined {
+  if (typeof event.path !== 'string' || event.path === '') return undefined;
+  return capTerminalText(event.path);
+}
+
+function detailOf(event: ServiceMutation): Record<string, unknown> {
+  return (event.detail ?? {}) as Record<string, unknown>;
+}
+
+/** Narrow a `request_rejected` event to its relay payload. */
+function toRejectionPayload(event: ServiceMutation): AiRejectionRelayPayload | null {
+  const detail = detailOf(event);
+  const payload: AiRejectionRelayPayload = {
+    kind: 'ai-rejection',
+    message: detailText(detail, 'message') ?? 'request rejected',
+  };
+  payload.model = eventModel(event);
+  payload.engine = detailText(detail, 'engine');
+  payload.status = detailText(detail, 'status');
+  if (typeof detail.code === 'number') payload.code = detail.code;
+  return payload;
+}
+
+/** Narrow a `response_blocked` event to its relay payload. */
+function toBlockedPayload(event: ServiceMutation): AiBlockedRelayPayload | null {
+  const detail = detailOf(event);
+  const payload: AiBlockedRelayPayload = { kind: 'ai-blocked' };
+  payload.model = eventModel(event);
+  payload.engine = detailText(detail, 'engine');
+  payload.finishReason = detailText(detail, 'finishReason');
+  payload.finishMessage = detailText(detail, 'finishMessage');
+  payload.blockReason = detailText(detail, 'blockReason');
+  return payload;
+}
+
+/**
+ * Narrow a `model_substituted` event to its relay payload, and enforce the
+ * invariant the terminal line depends on: an effective model equal to the
+ * requested one is NOT a substitution and never relays. The broker already
+ * compares before emitting; this re-checks because the event stream is a
+ * public contract anyone can post onto.
+ */
+function toModelSubstitutionPayload(
+  event: ServiceMutation,
+): AiModelSubstitutionRelayPayload | null {
+  const detail = detailOf(event);
+  const requestedModel = detailText(detail, 'requestedModel') ?? eventModel(event) ?? '';
+  const effectiveModel = detailText(detail, 'effectiveModel') ?? '';
+  if (requestedModel === '' || effectiveModel === '') return null;
+  let requestedBare = requestedModel;
+  if (requestedModel.startsWith('models/')) requestedBare = requestedModel.slice('models/'.length);
+  if (effectiveModel === requestedBare || effectiveModel === requestedModel) return null;
+  const payload: AiModelSubstitutionRelayPayload = {
+    kind: 'ai-model-substituted',
+    requestedModel,
+    effectiveModel,
+  };
+  payload.engine = detailText(detail, 'engine');
+  payload.reason = detailText(detail, 'reason');
+  return payload;
+}
+
+/** One record per relayed kind: the sandbox `op` that produces it, and the
+ *  narrower that turns that event into a wire payload. */
+interface AiDiagnosticRelay {
+  op: string;
+  fromEvent(event: ServiceMutation): AiDiagnosticRelayPayload | null;
+}
+
+const AI_DIAGNOSTIC_RELAYS: { [K in AiDiagnosticKind]: AiDiagnosticRelay } = {
+  'ai-rejection': { op: 'request_rejected', fromEvent: toRejectionPayload },
+  'ai-blocked': { op: 'response_blocked', fromEvent: toBlockedPayload },
+  'ai-model-substituted': { op: 'model_substituted', fromEvent: toModelSubstitutionPayload },
+};
+
+/** The relay record for a sandbox `op`, or `null` for an op nothing relays. */
+function relayForOp(op: string): AiDiagnosticRelay | null {
+  for (const relay of Object.values(AI_DIAGNOSTIC_RELAYS)) {
+    if (relay.op === op) return relay;
+  }
+  return null;
+}
+
+/**
+ * Subscribe to the sandbox event stream and relay every broker refusal,
+ * rejected request or blocked response, plus every silent model substitution,
+ * to the dev server for terminal visibility.
+ *
+ * Browser-safe (shared by the SharedWorker host and the in-page runtime);
+ * returns nothing to unsubscribe with, mirroring the guard next door, since
+ * the subscription is observational and lives for the plane's lifetime.
+ */
+export function setupAiDiagnosticsRelay(feed: AiDiagnosticsFeed, fetchFn: typeof fetch): void {
+  feed.subscribe((event) => {
+    if (event.kind !== 'service_mutation') return;
+    if (event.service !== 'ai') return;
+    const relay = relayForOp(event.op);
+    if (relay === null) return;
+    const payload = relay.fromEvent(event);
+    if (payload === null) return;
+    try {
+      void fetchFn('/__pyric/denials', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+      }).catch(() => {
+        /* Diagnostics are best-effort and must never affect app behavior. */
+      });
+    } catch {
+      /* An injected or unavailable fetch must never affect app behavior. */
+    }
+  });
+}

package/src/serve/ai-proxy.ts

@@ -0,0 +1,327 @@
+/**
+ * `/__pyric/ai-proxy`: the same-origin passthrough to an OpenAI-compatible
+ * upstream, plus the terminal diagnostics that make an upstream failure
+ * visible to a developer with no browser console open.
+ *
+ * The route is always mounted; it only touches the network when a request
+ * arrives. Everything about WHERE it forwards is resolved by
+ * {@link resolveAiProxyUpstream}, which the startup banner (`ai-status.ts`)
+ * shares so the two can never disagree.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ServeLogger } from './server.js';
+import { redactUrl } from 'pyric/ai/internal';
+import { sanitizeForTerminal } from './ai-terminal-text.js';
+
+/** The dev server's diagnostics throttle, as this module needs it: the
+ *  denials route owns the instance, and the proxy shares it so a failing
+ *  upstream cannot out-shout a denied listener. */
+export interface AiDiagnosticThrottle {
+  shouldPrint(key: string, now: number): boolean;
+}
+
+/** Default upstream: local Ollama's OpenAI-compatible endpoint. */
+export const AI_PROXY_DEFAULT_UPSTREAM = 'http://localhost:11434/v1';
+
+/** The route the dev server mounts for OpenAI-compatible traffic. */
+export const AI_PROXY_ROUTE = '/__pyric/ai-proxy';
+
+/**
+ * Request headers that must NOT be forwarded upstream: origin-sensitive
+ * browser context (`origin`/`referer`/`cookie`, since the upstream is a
+ * different origin and must never see the page's), hop-by-hop headers, and
+ * the two the proxy re-derives (`host`, `content-length`). `accept-encoding`
+ * is dropped so fetch negotiates its own compression and the streamed body
+ * needs no length fixups.
+ */
+const AI_PROXY_STRIPPED_HEADERS = new Set([
+  'host',
+  'origin',
+  'referer',
+  'cookie',
+  'connection',
+  'content-length',
+  'accept-encoding',
+  'keep-alive',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+/** The upstream-failure shapes the proxy surfaces to the terminal. */
+type AiProxyFailure =
+  | { kind: 'unreachable'; target: string; latencyMs: number; cause: string }
+  | {
+      kind: 'status';
+      target: string;
+      latencyMs: number;
+      status: number;
+      /** The upstream's raw `Retry-After` header, when it sent one. */
+      retryAfter?: string;
+    }
+  | { kind: 'stream-abort'; target: string; latencyMs: number; cause: string };
+
+/** Longest `Retry-After` value echoed to the terminal (delta-seconds and
+ *  HTTP-dates are both far shorter; anything longer is upstream noise). */
+const AI_PROXY_RETRY_AFTER_MAX = 64;
+
+/**
+ * Render a `Retry-After` value for the terminal, or `null` when there is
+ * nothing worth printing.
+ *
+ * The header is remote-authored, so it is sanitized and length-capped like
+ * every other upstream string that reaches the terminal. Delta-seconds (the
+ * common form) get an `s` suffix so the wait reads as a duration; the
+ * HTTP-date form is echoed verbatim, since `Wed, 21 Oct 2026 07:28:00 GMTs`
+ * would be nonsense.
+ */
+function formatRetryAfter(raw: string): string | null {
+  const clean = sanitizeForTerminal(raw).slice(0, AI_PROXY_RETRY_AFTER_MAX).trim();
+  if (clean === '') return null;
+  if (/^\d+$/.test(clean)) return `${clean}s`;
+  return clean;
+}
+
+/**
+ * Mask credentials, then flatten and cap, in that order. Both the target and
+ * a raw fetch error message are remote-influenced: the URL carries whatever
+ * the page put in the query string, and an error message can quote it back.
+ */
+function safeUpstreamText(text: string): string {
+  return sanitizeForTerminal(redactUrl(text));
+}
+
+/**
+ * The throttle key for one upstream failure. A failing upstream fails on
+ * every request, so the key is the failure itself (kind, status, and the
+ * redacted target) rather than anything per-request: one line per window,
+ * exactly like a denied listener that re-fires.
+ */
+function aiProxyThrottleKey(failure: AiProxyFailure): string {
+  const target = redactUrl(failure.target);
+  if (failure.kind === 'status') return `ai-proxy status ${failure.status} ${target}`;
+  return `ai-proxy ${failure.kind} ${target}`;
+}
+
+/** Print one upstream failure, unless the throttle already printed it. */
+function noteAiProxyFailure(
+  failure: AiProxyFailure,
+  throttle: AiDiagnosticThrottle,
+  logger?: ServeLogger,
+): void {
+  if (logger === undefined) return;
+  if (!throttle.shouldPrint(aiProxyThrottleKey(failure), Date.now())) return;
+  logger.note(formatAiProxyWarning(failure));
+}
+
+/**
+ * Format an upstream failure into the compact terminal block, the same
+ * `  [pyric] ...` idiom the denial relay prints, so ai-proxy trouble reads
+ * like every other dev-server diagnostic. Two lines: what went wrong, then
+ * the (redacted) upstream URL with the elapsed time. Exported for unit tests.
+ *
+ * A 429 says so in words (`rate limited`): the bare number reads as one more
+ * failed request, when it actually means the upstream is shedding load or the
+ * key is out of quota. When the upstream sent a `Retry-After`, a third line
+ * prints the wait it asked for, and states that NOTHING here waits on the
+ * developer's behalf. The proxy has no retry loop (the status rides straight
+ * through to the caller), so the backoff is the app's decision, not pyric's.
+ */
+export function formatAiProxyWarning(failure: AiProxyFailure): string {
+  const target = safeUpstreamText(failure.target);
+  let headline: string;
+  if (failure.kind === 'unreachable') {
+    headline = `upstream unreachable: ${safeUpstreamText(failure.cause)}`;
+  } else if (failure.kind === 'status') {
+    const rateLimited = failure.status === 429;
+    headline = `upstream returned ${failure.status}${rateLimited ? ' (rate limited / quota exhausted)' : ''}`;
+  } else {
+    headline = `upstream stream aborted mid-response: ${safeUpstreamText(failure.cause)}`;
+  }
+  const lines = [
+    `  ⚠ [pyric] ai-proxy: ${headline}`,
+    `      POST ${target} (${failure.latencyMs}ms)`,
+  ];
+  if (failure.kind === 'unreachable') {
+    lines.push(
+      `      set PYRIC_AI_PROXY_UPSTREAM to an OpenAI-compatible base URL (default ${AI_PROXY_DEFAULT_UPSTREAM})`,
+    );
+  }
+  if (failure.kind === 'status' && failure.retryAfter !== undefined) {
+    const wait = formatRetryAfter(failure.retryAfter);
+    if (wait !== null) {
+      lines.push(`      Retry-After: ${wait}, no automatic retry; the status went to the caller`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Resolve the upstream `/__pyric/ai-proxy` forwards to, and say WHERE that
+ * value came from. One resolution shared by the proxy handler (which needs
+ * the target) and the startup line (which needs the provenance, so a
+ * developer can tell a deliberate `PYRIC_AI_PROXY_UPSTREAM` from the Ollama
+ * default nobody chose).
+ */
+export function resolveAiProxyUpstream(
+  configured: string | undefined,
+): { target: string; source: 'option' | 'env' | 'default' } {
+  const envUpstream = process.env.PYRIC_AI_PROXY_UPSTREAM;
+  let raw = AI_PROXY_DEFAULT_UPSTREAM;
+  let source: 'option' | 'env' | 'default' = 'default';
+  if (configured !== undefined) {
+    raw = configured;
+    source = 'option';
+  } else if (envUpstream !== undefined) {
+    raw = envUpstream;
+    source = 'env';
+  }
+  return { target: raw.replace(/\/$/, ''), source };
+}
+
+/**
+ * Handle `POST /__pyric/ai-proxy/<suffix>`: a same-origin passthrough to the
+ * configured OpenAI-compatible upstream, so the browser openai engine
+ * (running in the served page or the SharedWorker host) reaches a localhost
+ * upstream like Ollama with ZERO CORS setup (no `OLLAMA_ORIGINS`, ever).
+ *
+ * Behavior:
+ *   - POST only (the OpenAI chat-completions surface is POST); 405 otherwise.
+ *   - the path suffix + query ride through verbatim
+ *     (`/__pyric/ai-proxy/chat/completions` becomes `<upstream>/chat/completions`).
+ *   - the request body is forwarded verbatim; headers minus the
+ *     origin-sensitive/hop-by-hop set above (`authorization` DOES forward,
+ *     since upstreams may require a key).
+ *   - the response body is STREAMED through chunk-by-chunk. SSE passthrough
+ *     must never buffer, or `stream: true` completions would arrive all at
+ *     once at the end.
+ *   - an unreachable upstream answers 502 with a plain-text explanation.
+ *   - every upstream failure (unreachable/timeout, non-2xx status, mid-stream
+ *     abort) ALSO prints a structured warning on the dev server's terminal
+ *     logger; a stopped Ollama used to fail in total silence. Diagnostics
+ *     only: nothing here changes what the caller receives. No logger wired
+ *     means dropped silently (same opt-out contract as the denial relay).
+ */
+export async function handleAiProxy(
+  configuredUpstream: string | undefined,
+  throttle: AiDiagnosticThrottle,
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  logger?: ServeLogger,
+): Promise<void> {
+  if (req.method !== 'POST') {
+    res.writeHead(405, { allow: 'POST' }).end('method not allowed');
+    return;
+  }
+  const upstreamBase = resolveAiProxyUpstream(configuredUpstream).target;
+  const suffix = url.pathname.slice(AI_PROXY_ROUTE.length);
+  const target = `${upstreamBase}${suffix}${url.search}`;
+
+  // Buffer the REQUEST body (small JSON payloads); the RESPONSE streams.
+  const raw = await new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c: Buffer) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+  // Copy into a plain-ArrayBuffer view; fetch's BodyInit typing rejects
+  // Buffer's ArrayBufferLike backing.
+  const body = new Uint8Array(raw.byteLength);
+  body.set(raw);
+
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    if (AI_PROXY_STRIPPED_HEADERS.has(key.toLowerCase())) continue;
+    headers[key] = Array.isArray(value) ? value.join(', ') : value;
+  }
+
+  const startedAt = Date.now();
+  let upstream: Response;
+  try {
+    upstream = await fetch(target, { method: 'POST', headers, body });
+  } catch (e) {
+    const cause = e instanceof Error ? e.message : String(e);
+    noteAiProxyFailure(
+      { kind: 'unreachable', target, latencyMs: Date.now() - startedAt, cause },
+      throttle,
+      logger,
+    );
+    // The 502 body quotes the same two strings the terminal block does, so it
+    // gets the same masking: the target carries the page's own query string,
+    // and a fetch error routinely echoes the URL back.
+    res.writeHead(502, { 'content-type': 'text/plain' });
+    res.end(
+      `pyric dev ai-proxy: upstream ${redactUrl(target)} unreachable: ${redactUrl(cause)}\n` +
+        'Set PYRIC_AI_PROXY_UPSTREAM to an OpenAI-compatible base URL ' +
+        `(default ${AI_PROXY_DEFAULT_UPSTREAM}).`,
+    );
+    return;
+  }
+
+  // A refusal from a reachable upstream (bad model, missing key, rate limit)
+  // is just as invisible to a headless developer as a dead socket: the
+  // status rides through to the caller untouched, and is ALSO announced here.
+  // `Retry-After` rides along when the upstream sent one (429s and 503s carry
+  // it): it is the only place the requested backoff appears, since nothing in
+  // this path retries or sleeps.
+  if (!upstream.ok) {
+    const retryAfter = upstream.headers.get('retry-after');
+    const failure: AiProxyFailure = {
+      kind: 'status',
+      target,
+      latencyMs: Date.now() - startedAt,
+      status: upstream.status,
+    };
+    if (retryAfter !== null) failure.retryAfter = retryAfter;
+    noteAiProxyFailure(failure, throttle, logger);
+  }
+
+  const responseHeaders: Record<string, string> = { 'cache-control': 'no-store' };
+  const contentType = upstream.headers.get('content-type');
+  if (contentType) responseHeaders['content-type'] = contentType;
+  res.writeHead(upstream.status, responseHeaders);
+  if (!upstream.body) {
+    res.end();
+    return;
+  }
+  (res as ServerResponse & { flushHeaders?: () => void }).flushHeaders?.();
+
+  // Chunk-by-chunk passthrough. A dropped client cancels the upstream read
+  // so an abandoned SSE stream doesn't keep the upstream generating.
+  const reader = upstream.body.getReader();
+  let clientGone = false;
+  res.on('close', () => {
+    clientGone = true;
+    void reader.cancel().catch(() => {});
+  });
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(value);
+    }
+  } catch (e) {
+    // Nothing to salvage for the caller: the response is already committed
+    // with the upstream's status, so a truncated body is all it gets. But a
+    // half-delivered completion is exactly the failure that used to vanish,
+    // so announce it, unless the CLIENT is the one who walked away (a closed
+    // tab cancelling an SSE stream is normal, not a fault worth a warning).
+    if (!clientGone) {
+      noteAiProxyFailure(
+        {
+          kind: 'stream-abort',
+          target,
+          latencyMs: Date.now() - startedAt,
+          cause: e instanceof Error ? e.message : String(e),
+        },
+        throttle,
+        logger,
+      );
+    }
+  }
+  res.end();
+}