@hienlh/ppm 0.19.2 → 0.19.4

package/src/services/provider-usage/usage-registry.ts

@@ -0,0 +1,157 @@
+import type { UsageInfo } from "../../types/chat.ts";
+import {
+  AMBIENT_ACCOUNT_KEY,
+  FETCH_TIMEOUT_MS,
+  type ProviderUsageSource,
+} from "./usage-source.ts";
+import {
+  getCachedUsageEntry,
+  isRecentlyFailed,
+  setCachedFailure,
+  setCachedUsage,
+  invalidateCachedUsage,
+} from "./usage-memory-cache.ts";
+import { readStoredUsage, writeStoredUsage } from "./usage-snapshot-store.ts";
+
+/**
+ * Registry of provider usage sources, and the read/refresh path over them.
+ *
+ * The rule the whole layer exists to enforce: **reads never wait on a provider.**
+ * `getUsage` is synchronous and answers from memory, falling back to the stored
+ * snapshot. Anything that talks to a provider happens on the background sweep or
+ * behind an explicit refresh, both of which are bounded by a timeout.
+ */
+
+const sources = new Map<string, ProviderUsageSource>();
+
+export function registerUsageSource(source: ProviderUsageSource): void {
+  sources.set(source.providerId, source);
+}
+
+export function getUsageSource(providerId: string): ProviderUsageSource | undefined {
+  return sources.get(providerId);
+}
+
+export function listUsageSources(): ProviderUsageSource[] {
+  return [...sources.values()];
+}
+
+/** Test seam: drop every registered source. */
+export function _clearUsageSources(): void {
+  sources.clear();
+}
+
+/**
+ * Latest known usage for one account, without ever touching the provider.
+ *
+ * Memory first, then the stored snapshot — which is what makes a percentage
+ * appear immediately after a restart, before the first sweep lands. Returns an
+ * empty object when nothing has ever been recorded; the caller cannot tell that
+ * apart from "no limits reported", and does not need to.
+ */
+export function getUsage(providerId: string, accountId = AMBIENT_ACCOUNT_KEY): UsageInfo {
+  const cached = getCachedUsageEntry(providerId, accountId);
+  if (cached) return cached;
+  const stored = readStoredUsage(providerId, accountId);
+  if (stored) {
+    // Promote into memory so the next read skips the query, but keep the
+    // provider's own freshness clock: this value is as old as it ever was.
+    setCachedUsage(providerId, accountId, stored);
+    return stored;
+  }
+  return {};
+}
+
+/** Reject if `promise` has not settled within `ms`, naming what timed out. */
+function withTimeout<T>(promise: Promise<T>, ms: number, what: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms);
+    promise.then(
+      (v) => { clearTimeout(timer); resolve(v); },
+      (e) => { clearTimeout(timer); reject(e); },
+    );
+  });
+}
+
+/**
+ * Concurrent refreshes of the same account share one in-flight fetch.
+ *
+ * Each attempt carries a token so its cleanup can tell "I am still the current
+ * attempt" from "I was abandoned and something newer took my place".
+ */
+const inflight = new Map<string, { token: object; promise: Promise<UsageInfo> }>();
+
+/**
+ * Fetch one account live, then cache and store it.
+ *
+ * Failures are swallowed into the last known value rather than propagated: the
+ * callers are a background sweep and a toolbar refresh, and neither has anything
+ * useful to do with the error beyond showing what it already had. The failure is
+ * still remembered so it does not turn into a retry per request.
+ */
+export async function refreshUsage(
+  providerId: string,
+  accountId = AMBIENT_ACCOUNT_KEY,
+): Promise<UsageInfo> {
+  const source = sources.get(providerId);
+  if (!source) return {};
+
+  const key = `${providerId}\0${accountId}`;
+  const existing = inflight.get(key);
+  if (existing) return existing.promise;
+
+  // Identity for this attempt. Comparing tokens rather than the promise avoids
+  // the closure having to reference the very promise it is producing.
+  const token = {};
+  const run = (async () => {
+    try {
+      const usage = await withTimeout(
+        source.fetch(accountId),
+        source.fetchTimeoutMs ?? FETCH_TIMEOUT_MS,
+        `${providerId} usage fetch`,
+      );
+      setCachedUsage(providerId, accountId, usage);
+      writeStoredUsage(providerId, accountId, usage);
+      return usage;
+    } catch (e) {
+      setCachedFailure(providerId, accountId);
+      console.error(`[usage] ${providerId}/${accountId || "ambient"}:`, (e as Error).message);
+      return readStoredUsage(providerId, accountId) ?? {};
+    } finally {
+      // Only clear if this is still the current attempt. An abandoned fetch
+      // that finishes late must not evict the entry a newer one just installed,
+      // or that newer caller would be silently un-deduped.
+      if (inflight.get(key)?.token === token) inflight.delete(key);
+    }
+  })();
+
+  inflight.set(key, { token, promise: run });
+  return run;
+}
+
+/** Test seam: forget every in-flight fetch so the next call starts a fresh one. */
+export function _clearInflightUsage(): void {
+  inflight.clear();
+}
+
+/**
+ * Read, fetching only if nothing usable is known yet.
+ *
+ * Used by the request path so a cold start still produces a number, while a
+ * remembered failure short-circuits to the stored value instead of re-attempting
+ * a fetch on every request.
+ */
+export async function getOrFetchUsage(
+  providerId: string,
+  accountId = AMBIENT_ACCOUNT_KEY,
+): Promise<UsageInfo> {
+  const known = getUsage(providerId, accountId);
+  if (Object.keys(known).length > 0) return known;
+  if (isRecentlyFailed(providerId, accountId)) return known;
+  return refreshUsage(providerId, accountId);
+}
+
+/** Force the next read of this provider (or one account) to go back to the source. */
+export function invalidateUsage(providerId: string, accountId?: string): void {
+  invalidateCachedUsage(providerId, accountId);
+}

package/src/services/provider-usage/usage-scheduler.ts

@@ -0,0 +1,117 @@
+import {
+  ACCOUNT_STAGGER_MS,
+  AMBIENT_ACCOUNT_KEY,
+  DEFAULT_POLL_INTERVAL_MS,
+  type ProviderUsageSource,
+} from "./usage-source.ts";
+import { listUsageSources, refreshUsage } from "./usage-registry.ts";
+
+/**
+ * The one background loop that keeps every provider's quota warm.
+ *
+ * Sweeping in the background is what makes reads instant: by the time the
+ * toolbar asks, the value is already in memory. Both providers run on the same
+ * cadence and through the same code, so a new provider gets this by registering
+ * a source — there is no second timer to write.
+ *
+ * Survives `bun --hot` reloads through globalThis: module state resets on
+ * reload, so a module-level timer would leak a new interval per reload while
+ * the old one kept firing.
+ */
+
+const HOT_KEY = "__PPM_PROVIDER_USAGE_POLL__" as const;
+
+interface HotState {
+  timers: Map<string, ReturnType<typeof setTimeout>>;
+  inflight: Map<string, Promise<void>>;
+}
+
+const hot: HotState = ((globalThis as Record<string, unknown>)[HOT_KEY] ??= {
+  timers: new Map(),
+  inflight: new Map(),
+}) as HotState;
+
+/**
+ * One pass over a source's accounts.
+ *
+ * Accounts are walked in series with a gap between them: a sweep is maintenance,
+ * not something worth spending a burst of subprocesses or API calls on. Each
+ * account is independent — `refreshUsage` never rejects, so a failing account
+ * does not cut the sweep short for the ones after it.
+ */
+async function sweepSource(source: ProviderUsageSource): Promise<void> {
+  const accountIds = source.listAccountIds();
+  // No account store configured: the provider reads one ambient login instead.
+  const targets = accountIds.length > 0 ? accountIds : [AMBIENT_ACCOUNT_KEY];
+
+  for (let i = 0; i < targets.length; i++) {
+    const accountId = targets[i]!;
+    try {
+      if (await source.shouldSkip?.(accountId)) continue;
+    } catch {
+      continue; // A source that cannot decide is treated as "skip", not "fetch".
+    }
+    await refreshUsage(source.providerId, accountId);
+    if (i < targets.length - 1) await new Promise((r) => setTimeout(r, ACCOUNT_STAGGER_MS));
+  }
+}
+
+/** Sweep one source now; concurrent callers share the in-flight pass. */
+export function sweepUsageSource(source: ProviderUsageSource): Promise<void> {
+  const existing = hot.inflight.get(source.providerId);
+  if (existing) return existing;
+
+  const pass = sweepSource(source)
+    .catch((e) => console.error(`[usage] sweep ${source.providerId}:`, (e as Error).message))
+    .finally(() => {
+      // Only clear if still the current pass, so a stale finally cannot drop a newer one.
+      if (hot.inflight.get(source.providerId) === pass) hot.inflight.delete(source.providerId);
+    });
+
+  hot.inflight.set(source.providerId, pass);
+  return pass;
+}
+
+/**
+ * Start the background loop for every registered source.
+ *
+ * Each source is swept once immediately — a fresh server should not show blank
+ * percentages for a whole interval — and then rescheduled after each pass
+ * completes rather than on a fixed interval, so a slow sweep cannot overlap the
+ * next one.
+ */
+export function startProviderUsagePolling(): void {
+  stopProviderUsagePolling();
+  for (const source of listUsageSources()) {
+    const interval = source.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const scheduleNext = () => {
+      hot.timers.set(source.providerId, setTimeout(async () => {
+        await sweepUsageSource(source);
+        scheduleNext();
+      }, interval));
+    };
+    sweepUsageSource(source).then(scheduleNext, scheduleNext);
+  }
+}
+
+export function stopProviderUsagePolling(): void {
+  for (const timer of hot.timers.values()) clearTimeout(timer);
+  hot.timers.clear();
+}
+
+/**
+ * Abandon any in-flight sweep so the next one starts fresh.
+ *
+ * Needed when a sweep is known to be stuck: without it the hung pass is handed
+ * to every later caller, and a provider that stops answering blocks its own
+ * refresh indefinitely. The guard in {@link sweepUsageSource} means the
+ * abandoned pass cannot evict its replacement when it eventually settles.
+ */
+export function _clearInflightSweeps(): void {
+  hot.inflight.clear();
+}
+
+/** Test seam: true while any source has a scheduled pass. */
+export function _isUsagePollingActive(): boolean {
+  return hot.timers.size > 0;
+}

package/src/services/provider-usage/usage-snapshot-store.ts

@@ -0,0 +1,126 @@
+import type { UsageInfo, LimitBucket } from "../../types/chat.ts";
+import {
+  insertLimitSnapshot,
+  getLatestLimitSnapshot,
+  getLatestSnapshotForAccount,
+  touchSnapshotTimestamp,
+  cleanupOldLimitSnapshots,
+  type LimitSnapshotRow,
+} from "../db.service.ts";
+import { AMBIENT_ACCOUNT_KEY } from "./usage-source.ts";
+
+/**
+ * The durable half of the usage layer: turning a provider's `UsageInfo` into a
+ * snapshot row and back, for any provider.
+ *
+ * Persistence is what lets the toolbar show a number the moment the server comes
+ * back up, before the first background sweep has finished. Without it a restart
+ * blanks every percentage for as long as the first fetch takes.
+ *
+ * A row is only written when something actually moved. Otherwise the newest row
+ * has its timestamp touched, so "last fetched" stays honest without growing a
+ * row per account per sweep forever.
+ */
+
+/** Recompute a bucket's countdown against the current clock. */
+function toBucket(util: number, resetsAt: string, windowHours: number): LimitBucket {
+  const diff = resetsAt ? new Date(resetsAt).getTime() - Date.now() : 0;
+  const totalMins = diff > 0 ? Math.ceil(diff / 60_000) : 0;
+  return {
+    utilization: util,
+    resetsAt,
+    resetsInMinutes: windowHours <= 5 ? totalMins : null,
+    resetsInHours: windowHours > 5 ? Math.round((totalMins / 60) * 100) / 100 : null,
+    windowHours,
+  };
+}
+
+/** Snapshot row → UsageInfo, with the flat mirror fields the chat toolbar reads. */
+export function snapshotToUsage(row: LimitSnapshotRow): UsageInfo & { lastFetchedAt?: string } {
+  // SQLite's datetime('now') is UTC but carries no Z, which JS would read as local time.
+  const iso = row.recorded_at.endsWith("Z")
+    ? row.recorded_at
+    : row.recorded_at.replace(" ", "T") + "Z";
+  const usage: UsageInfo & { lastFetchedAt?: string } = { lastFetchedAt: iso };
+  if (row.five_hour_util != null) {
+    usage.session = toBucket(row.five_hour_util, row.five_hour_resets_at ?? "", 5);
+    usage.fiveHour = row.five_hour_util;
+    if (row.five_hour_resets_at) usage.fiveHourResetsAt = row.five_hour_resets_at;
+  }
+  if (row.weekly_util != null) {
+    usage.weekly = toBucket(row.weekly_util, row.weekly_resets_at ?? "", 168);
+    usage.sevenDay = row.weekly_util;
+    if (row.weekly_resets_at) usage.sevenDayResetsAt = row.weekly_resets_at;
+  }
+  if (row.weekly_opus_util != null) {
+    usage.weeklyOpus = toBucket(row.weekly_opus_util, row.weekly_opus_resets_at ?? "", 168);
+  }
+  if (row.weekly_sonnet_util != null) {
+    usage.weeklySonnet = toBucket(row.weekly_sonnet_util, row.weekly_sonnet_resets_at ?? "", 168);
+  }
+  return usage;
+}
+
+/** Read the newest stored snapshot for one provider account, or undefined. */
+export function readStoredUsage(
+  providerId: string,
+  accountId: string,
+): (UsageInfo & { lastFetchedAt?: string }) | undefined {
+  const row = accountId === AMBIENT_ACCOUNT_KEY
+    ? getLatestLimitSnapshot(providerId)
+    : getLatestSnapshotForAccount(accountId, providerId);
+  return row ? snapshotToUsage(row) : undefined;
+}
+
+/**
+ * True when any stored bucket differs from the freshly fetched one.
+ *
+ * Utilizations compare with a tolerance rather than exactly: they are floats
+ * that round-trip through SQLite, and treating a last-digit wobble as a change
+ * would write a row on every single sweep.
+ */
+function hasChanged(usage: UsageInfo, last: LimitSnapshotRow | null): boolean {
+  if (!last) return true;
+  const moved = (fresh: number | null | undefined, stored: number | null) =>
+    fresh != null && (stored == null || Math.abs(fresh - stored) > 0.001);
+  if (moved(usage.session?.utilization, last.five_hour_util)) return true;
+  if (moved(usage.weekly?.utilization, last.weekly_util)) return true;
+  if (moved(usage.weeklyOpus?.utilization, last.weekly_opus_util)) return true;
+  if (moved(usage.weeklySonnet?.utilization, last.weekly_sonnet_util)) return true;
+  if (usage.session?.resetsAt && usage.session.resetsAt !== (last.five_hour_resets_at ?? "")) return true;
+  if (usage.weekly?.resetsAt && usage.weekly.resetsAt !== (last.weekly_resets_at ?? "")) return true;
+  return false;
+}
+
+/**
+ * Persist a freshly fetched value, writing a row only when a bucket moved.
+ *
+ * An account with nothing to report (every bucket absent) is not written at all:
+ * a row of nulls is indistinguishable from "never fetched" on read, so storing
+ * one buys nothing and only makes the history noisier.
+ */
+export function writeStoredUsage(providerId: string, accountId: string, usage: UsageInfo): void {
+  const hasAnyBucket = usage.session != null || usage.weekly != null
+    || usage.weeklyOpus != null || usage.weeklySonnet != null;
+  if (!hasAnyBucket) return;
+
+  const id = accountId === AMBIENT_ACCOUNT_KEY ? null : accountId;
+  const last = id ? getLatestSnapshotForAccount(id, providerId) : getLatestLimitSnapshot(providerId);
+  if (!hasChanged(usage, last)) {
+    if (id) touchSnapshotTimestamp(id, providerId);
+    return;
+  }
+  insertLimitSnapshot({
+    provider: providerId,
+    account_id: id,
+    five_hour_util: usage.session?.utilization ?? null,
+    five_hour_resets_at: usage.session?.resetsAt ?? null,
+    weekly_util: usage.weekly?.utilization ?? null,
+    weekly_resets_at: usage.weekly?.resetsAt ?? null,
+    weekly_opus_util: usage.weeklyOpus?.utilization ?? null,
+    weekly_opus_resets_at: usage.weeklyOpus?.resetsAt ?? null,
+    weekly_sonnet_util: usage.weeklySonnet?.utilization ?? null,
+    weekly_sonnet_resets_at: usage.weeklySonnet?.resetsAt ?? null,
+  });
+  cleanupOldLimitSnapshots();
+}

package/src/services/provider-usage/usage-source.ts

@@ -0,0 +1,82 @@
+import type { UsageInfo } from "../../types/chat.ts";
+
+/**
+ * What one provider must supply for its quota to be polled, cached, and stored
+ * by the shared usage layer.
+ *
+ * Everything scheduling-shaped — the background timer, the fetch timeout, the
+ * per-account cache, negative caching, staggering, in-flight de-duplication,
+ * writing to and reading back from the snapshot store — belongs to that layer,
+ * not here. A new provider implements the two required methods and inherits all
+ * of it; nothing in this interface knows about HTTP, JSON-RPC, or subprocesses.
+ */
+export interface ProviderUsageSource {
+  /** Matches the AIProvider id, and is what a snapshot row is scoped by. */
+  readonly providerId: string;
+
+  /**
+   * Accounts whose quota should be kept warm.
+   *
+   * An empty array is meaningful: it means this provider has no account store
+   * configured and reads a single ambient login instead, which the layer keys
+   * under {@link AMBIENT_ACCOUNT_KEY}.
+   */
+  listAccountIds(): string[];
+
+  /**
+   * Read one account's quota from the provider, live.
+   *
+   * Throw or reject on failure; do NOT return an empty object to signal one.
+   * The layer distinguishes the two: a rejection is cached briefly so a broken
+   * account cannot be retried on every request, while a resolved empty object
+   * is stored as a genuine "this account has no limits to report".
+   *
+   * `accountId` is {@link AMBIENT_ACCOUNT_KEY} when the provider has no
+   * account store.
+   */
+  fetch(accountId: string): Promise<UsageInfo>;
+
+  /**
+   * Skip this account on a background sweep without treating it as a failure —
+   * an expired token, a cooldown after a rate-limit, a login that cannot
+   * refresh. The last stored value stays readable.
+   */
+  shouldSkip?(accountId: string): boolean | Promise<boolean>;
+
+  /** Poll period override. Defaults to {@link DEFAULT_POLL_INTERVAL_MS}. */
+  readonly pollIntervalMs?: number;
+
+  /** Per-fetch ceiling override. Defaults to {@link FETCH_TIMEOUT_MS}. */
+  readonly fetchTimeoutMs?: number;
+}
+
+/** Cache/store key for a provider that reads one ambient login, not an account list. */
+export const AMBIENT_ACCOUNT_KEY = "";
+
+/** Both providers refresh on the same cadence; a source may override it. */
+export const DEFAULT_POLL_INTERVAL_MS = 300_000; // 5 min
+
+/** Gap between accounts inside one sweep, so a sweep is not a burst. */
+export const ACCOUNT_STAGGER_MS = 1_000;
+
+/**
+ * Ceiling on a single `fetch`. Codex spawns an app-server to answer, and that
+ * subprocess has been observed to accept the spawn and then never reply — with
+ * no ceiling the sweep waits forever, the HTTP route behind it never answers,
+ * and the subprocess is never closed. Claude's HTTP call has its own timeout
+ * but is covered here too, so one hung account cannot stall the whole sweep.
+ */
+export const FETCH_TIMEOUT_MS = 20_000;
+
+/** How long a resolved value is served from memory before a re-read. */
+export const USAGE_CACHE_TTL_MS = 300_000; // 5 min — matches the poll period
+
+/**
+ * How long a FAILURE is remembered.
+ *
+ * Short, because the cause is usually transient (a login being refreshed, a
+ * subprocess losing a race). Non-zero, because without it every request that
+ * misses re-attempts a fetch: for codex that meant spawning another app-server
+ * per request, and the ones that hung were never reaped.
+ */
+export const USAGE_FAILURE_TTL_MS = 30_000;

package/src/services/proxy-agent-anthropic-bridge.ts

@@ -0,0 +1,93 @@
+/**
+ * Agent → Anthropic Messages, for `POST /proxy/<provider>/v1/messages`.
+ *
+ * The mirror of `proxy-agent-bridge.ts`: same agent turn (`proxy-agent-turn.ts`),
+ * same ephemeral-session and sandbox rules, rendered in Anthropic's dialect so a
+ * client already pointed at `ANTHROPIC_BASE_URL` can reach any PPM provider by
+ * setting that base to `…/proxy/<provider>`.
+ */
+import {
+  startAgentTurn, usageOf, resolveProvider, proxyableProviderIds,
+} from "./proxy-agent-turn.ts";
+import {
+  buildPromptFromAnthropicMessages, messageResponse, anthropicError,
+  MessageStreamWriter, ANTHROPIC_SSE_HEADERS, type AnthropicMessagesBody,
+} from "./proxy-anthropic-format.ts";
+
+/** Open the turn described by an Anthropic-format body. */
+function startTurn(providerId: string, body: AnthropicMessagesBody) {
+  const { prompt, systemPrompt } = buildPromptFromAnthropicMessages(body);
+  return startAgentTurn(providerId, { prompt, systemPrompt, model: body.model });
+}
+
+/** Non-streaming: drain the turn, return one `message`. */
+async function runNonStreaming(providerId: string, body: AnthropicMessagesBody): Promise<Response> {
+  const { events, cleanup } = await startTurn(providerId, body);
+  try {
+    let text = "";
+    let usage: ReturnType<typeof usageOf>;
+    for await (const ev of events) {
+      if (ev.type === "text") text += ev.content;
+      else if (ev.type === "error") throw new Error(ev.message);
+      else if (ev.type === "done") usage = usageOf(ev);
+    }
+    return messageResponse(text, body.model || providerId, usage);
+  } finally {
+    await cleanup();
+  }
+}
+
+/** Streaming: map assistant text onto the Anthropic SSE event sequence. */
+async function runStreaming(providerId: string, body: AnthropicMessagesBody): Promise<Response> {
+  // Started before the stream so a setup failure is still a JSON error the
+  // client can read, rather than an SSE stream that opens and immediately dies.
+  const { events, cleanup } = await startTurn(providerId, body);
+  const model = body.model || providerId;
+
+  const readable = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const stream = new MessageStreamWriter(controller, model);
+      stream.open();
+      let usage: ReturnType<typeof usageOf>;
+      try {
+        for await (const ev of events) {
+          if (ev.type === "text") stream.text(ev.content);
+          else if (ev.type === "error") throw new Error(ev.message);
+          else if (ev.type === "done") usage = usageOf(ev);
+        }
+        stream.close(usage);
+      } catch (e) {
+        // The stream already carries a 200, so the error has to ride inside it.
+        stream.text(`\n\nError: ${(e as Error).message}`);
+        stream.close(usage);
+      } finally {
+        await cleanup();
+      }
+    },
+    async cancel() {
+      await cleanup();
+    },
+  });
+
+  return new Response(readable, { headers: ANTHROPIC_SSE_HEADERS });
+}
+
+/**
+ * Entry point for `POST /proxy/<provider>/v1/messages`.
+ * Never throws: every failure becomes an Anthropic-shaped error response.
+ */
+export async function forwardAgentMessages(
+  providerId: string,
+  body: AnthropicMessagesBody,
+): Promise<Response> {
+  if (!resolveProvider(providerId)) {
+    return anthropicError(404, `Unknown provider "${providerId}". Available: ${proxyableProviderIds().join(", ") || "none"}`);
+  }
+  try {
+    return body.stream
+      ? await runStreaming(providerId, body)
+      : await runNonStreaming(providerId, body);
+  } catch (e) {
+    return anthropicError(502, (e as Error).message);
+  }
+}

package/src/services/proxy-agent-bridge.ts

@@ -0,0 +1,100 @@
+/**
+ * Agent → OpenAI Chat Completions, for `POST /proxy/<provider>/v1/chat/completions`.
+ *
+ * An OpenAI client points its `baseURL` at `…/proxy/codex/v1`; the provider comes
+ * from the URL and the model from the request body. Session lifetime, sandboxing
+ * and timeouts live in `proxy-agent-turn.ts`, shared with the Anthropic-format
+ * endpoint so the two cannot drift apart.
+ *
+ * Unlike the Claude-only bridge (`proxy-openai-bridge.ts`, a single SDK query),
+ * this drives a real agent session: a turn may run the provider's own tools
+ * before answering. Tool traffic has no place in the OpenAI wire format, so only
+ * assistant text reaches the caller.
+ */
+import {
+  startAgentTurn, usageOf, resolveProvider, proxyableProviderIds,
+} from "./proxy-agent-turn.ts";
+import {
+  buildPromptFromOpenAiMessages, completionResponse, openAiError,
+  ChunkWriter, SSE_HEADERS, type OpenAiChatBody,
+} from "./proxy-openai-format.ts";
+
+/** Open the turn described by an OpenAI-format body. */
+function startTurn(providerId: string, body: OpenAiChatBody) {
+  const { prompt, systemPrompt } = buildPromptFromOpenAiMessages(body);
+  return startAgentTurn(providerId, { prompt, systemPrompt, model: body.model });
+}
+
+/** Non-streaming: drain the turn, return one `chat.completion`. */
+async function runNonStreaming(providerId: string, body: OpenAiChatBody): Promise<Response> {
+  const { events, cleanup } = await startTurn(providerId, body);
+  try {
+    let content = "";
+    let usage: ReturnType<typeof usageOf>;
+    for await (const ev of events) {
+      if (ev.type === "text") content += ev.content;
+      else if (ev.type === "error") throw new Error(ev.message);
+      else if (ev.type === "done") usage = usageOf(ev);
+    }
+    return completionResponse(content, body.model || providerId, usage && {
+      promptTokens: usage.inputTokens, completionTokens: usage.outputTokens,
+    });
+  } finally {
+    await cleanup();
+  }
+}
+
+/** Streaming: map assistant text onto `chat.completion.chunk` frames. */
+async function runStreaming(providerId: string, body: OpenAiChatBody): Promise<Response> {
+  // Started before the stream so a setup failure is still a JSON error the
+  // client can read, rather than an SSE stream that opens and immediately dies.
+  const { events, cleanup } = await startTurn(providerId, body);
+  const model = body.model || providerId;
+
+  const readable = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const chunks = new ChunkWriter(controller, model);
+      chunks.open();
+      try {
+        for await (const ev of events) {
+          if (ev.type === "text") chunks.text(ev.content);
+          else if (ev.type === "error") throw new Error(ev.message);
+        }
+        chunks.close();
+      } catch (e) {
+        // The stream already carries a 200, so the error has to ride inside it.
+        chunks.text(`\n\nError: ${(e as Error).message}`);
+        chunks.close();
+      } finally {
+        await cleanup();
+      }
+    },
+    async cancel() {
+      await cleanup();
+    },
+  });
+
+  return new Response(readable, { headers: SSE_HEADERS });
+}
+
+/**
+ * Entry point for `POST /proxy/<provider>/v1/chat/completions`.
+ * Never throws: every failure becomes an OpenAI-shaped error response.
+ */
+export async function forwardAgentChatCompletions(
+  providerId: string,
+  body: OpenAiChatBody,
+): Promise<Response> {
+  if (!resolveProvider(providerId)) {
+    return openAiError(404, `Unknown provider "${providerId}". Available: ${proxyableProviderIds().join(", ") || "none"}`);
+  }
+  try {
+    return body.stream
+      ? await runStreaming(providerId, body)
+      : await runNonStreaming(providerId, body);
+  } catch (e) {
+    return openAiError(502, (e as Error).message);
+  }
+}
+
+export { listProviderModels } from "./proxy-agent-turn.ts";