@k2b/cloud 0.31.0 → 0.32.0

package/src/ai/malformed-tool-call-repair.ts

@@ -0,0 +1,144 @@
+import type { NessiIssue, Provider, SessionStore, ToolCallBlock, ToolStreamIssue } from "@k2b/nessi";
+import { AiTurnFailure } from "./turn-failure";
+import type { AiStoredMessage } from "./types";
+
+/** At most two automatic repairs per chat turn; user steering does not reset this budget. */
+export const AI_MALFORMED_TOOL_CALL_REPAIR_ATTEMPTS = 2;
+
+const excerpt = (text: string, maxChars: number): string => (text.length <= maxChars ? text : `${text.slice(0, maxChars - 1)}…`);
+
+/** Never include argsText: code and other tool arguments can be very large. */
+export const malformedToolCallMessage = (issue: ToolStreamIssue): string =>
+  `The tool call${issue.name ? ` to ${excerpt(issue.name, 120)}` : ""} could not be used: ${excerpt(issue.message, 512)} (${issue.reason}).`;
+
+const REPAIR_REQUEST = "Re-send the call with its exact tool name and complete, valid, properly escaped JSON arguments.";
+
+const buildStoredMalformedToolCallRepairText = (name: string): string => `The tool call to ${name} could not be used. ${REPAIR_REQUEST}`;
+
+export const buildMalformedToolCallRepairText = (issue: ToolStreamIssue): string => `${malformedToolCallMessage(issue)} ${REPAIR_REQUEST}`;
+
+// The prefix lets resumed turns count repairs independently of ordinary tool calls. The id is 34 characters of [a-z0-9_],
+// within OpenAI's 40- and Anthropic's 64-character limits; stricter providers (Mistral's nine alphanumeric characters)
+// map ids at the transport boundary (see provider.ts).
+export const newMalformedToolCallId = (): string => `malformed_${crypto.randomUUID().replaceAll("-", "").slice(0, 24)}`;
+
+export const isMalformedToolCallId = (id: string): boolean => /^malformed_[0-9a-f]{24}$/.test(id);
+
+export const malformedToolCallName = (issue: ToolStreamIssue): string =>
+  issue.name && /^[A-Za-z0-9_-]{1,64}$/.test(issue.name) ? issue.name : "unknown_tool";
+
+// Partial responses (error/interrupted) count too: their stored error result requests the repair on resume, so each
+// saved response with a malformed call spends one repair, as in the live run.
+export const countMalformedToolCallRepairs = (messages: readonly Pick<AiStoredMessage, "message">[]): number =>
+  messages.filter(
+    ({ message }) =>
+      message.role === "assistant" && message.content.some((block) => block.type === "tool_call" && isMalformedToolCallId(block.id)),
+  ).length;
+
+// Since 0.17.1, nessi also repairs malformed calls with its own user message and counter. Cloud's session store
+// drops user messages nessi appends, and applying Cloud's repair through steering resets nessi's counter.
+// Only Cloud's repair reaches the model and user. Executor unit tests pin Cloud's exhaustion; live integration tests
+// pin the repair results sent to the model, absence of nessi's message in storage and requests, and Cloud's logged failure.
+export const createMalformedToolCallRepair = (previousAttempts: number) => {
+  let attempts = previousAttempts;
+  let lastIssue: ToolStreamIssue | undefined;
+  // Malformed calls of the provider response in flight; pending marks a stored response that still awaits its repair.
+  let issues: (ToolStreamIssue & { callId: string })[] = [];
+  // A stored response beyond the budget means the run stopped before it could fail the turn.
+  let pending = previousAttempts > AI_MALFORMED_TOOL_CALL_REPAIR_ATTEMPTS;
+  return {
+    startProviderTurn: () => {
+      issues = [];
+    },
+    noteIssue: (issue: NessiIssue): NessiIssue => {
+      if (issue.kind !== "malformed_tool_call") return issue;
+      const rewritten = { ...issue, callId: newMalformedToolCallId() };
+      issues.push(rewritten);
+      lastIssue = rewritten;
+      return rewritten;
+    },
+    /** Hands the response's malformed calls to the store once and marks the repair as due. */
+    takeResponseIssues: () => {
+      const taken = issues;
+      issues = [];
+      if (taken.length > 0) pending = true;
+      return taken;
+    },
+    takeSteering: (): string | undefined => {
+      if (!pending) return undefined;
+      pending = false;
+      if (attempts >= AI_MALFORMED_TOOL_CALL_REPAIR_ATTEMPTS || !lastIssue) {
+        throw new AiTurnFailure(
+          "failed",
+          lastIssue
+            ? malformedToolCallMessage(lastIssue)
+            : "A stored response held a tool call that could not be used after the turn's repairs were spent.",
+        );
+      }
+      attempts++;
+      return buildMalformedToolCallRepairText(lastIssue);
+    },
+  };
+};
+
+export const withMalformedToolCallRepair = (provider: Provider, repair: ReturnType<typeof createMalformedToolCallRepair>): Provider => ({
+  ...provider,
+  stream: async function* (request) {
+    repair.startProviderTurn();
+    for await (const event of provider.stream(request)) {
+      yield event.type === "issue" ? { ...event, issue: repair.noteIssue(event.issue) } : event;
+    }
+  },
+});
+
+export const withMalformedToolCallResults = (
+  store: SessionStore,
+  repair: ReturnType<typeof createMalformedToolCallRepair>,
+): SessionStore => ({
+  ...store,
+  load: async () => {
+    const entries = await store.load();
+    const assistantIndex = entries.findLastIndex(({ message, kind }) => message.role === "assistant" && kind === "message");
+    const assistant = entries[assistantIndex]?.message;
+    const following = entries.slice(assistantIndex + 1);
+    if (assistant?.role !== "assistant" || following.some(({ message }) => message.role === "user")) return entries;
+    const resolved = new Set(following.flatMap(({ message }) => (message.role === "tool_result" ? [message.callId] : [])));
+    const missing = assistant.content.filter(
+      (block): block is ToolCallBlock => block.type === "tool_call" && isMalformedToolCallId(block.id) && !resolved.has(block.id),
+    );
+    if (missing.length === 0) return entries;
+    for (const call of missing) {
+      await store.append({
+        role: "tool_result",
+        callId: call.id,
+        name: call.name,
+        isError: true,
+        result: buildStoredMalformedToolCallRepairText(call.name),
+      });
+    }
+    return store.load();
+  },
+  append: async (message, opts) => {
+    const issues = message.role === "assistant" && opts?.kind !== "summary" ? repair.takeResponseIssues() : [];
+    if (message.role !== "assistant" || issues.length === 0) {
+      await store.append(message, opts);
+      return;
+    }
+    const calls: ToolCallBlock[] = issues.map((issue) => ({
+      type: "tool_call",
+      id: issue.callId,
+      name: malformedToolCallName(issue),
+      args: {},
+    }));
+    await store.append({ ...message, content: [...message.content, ...calls] }, opts);
+    for (const issue of issues) {
+      await store.append({
+        role: "tool_result",
+        callId: issue.callId,
+        name: malformedToolCallName(issue),
+        result: buildMalformedToolCallRepairText(issue),
+        isError: true,
+      });
+    }
+  },
+});

package/src/ai/markdown-pdf-tool.ts

@@ -7,6 +7,7 @@ import {
   type RenderMarkdownToPdfOptions,
   renderMarkdownToPdf,
 } from "../services/pdf";
+import { aiMissingChatFileError } from "./file-error";
 import { aiProjectFilePathFromMount } from "./file-mount";
 import { type AiFileContent, aiFileStore, normalizeAiFilePath } from "./files-store";
 import { withAiPdfConversionSlot } from "./pdf-conversions";
@@ -65,7 +66,7 @@ export const createCloudAiMarkdownToPdfTool = (dependencies: MarkdownPdfToolDepe
     if (!ctx.conversationId) throw new Error("The markdown_to_pdf tool needs a conversation context.");
     const sourcePath = conversationPath(input.path);
     const source = await read({ conversationId: ctx.conversationId, path: sourcePath });
-    if (!source) throw new Error(`No such file: ${sourcePath}`);
+    if (!source) throw aiMissingChatFileError(sourcePath, ctx.localToolsEnabled);
     if (source.origin !== "assistant") {
       throw new Error(`Create an assistant-owned Markdown file with write_file before converting ${sourcePath}.`);
     }

package/src/ai/migrate.ts

@@ -649,6 +649,7 @@ export const migrateCloudAi = async (): Promise<void> => {
   // A code run asks for its nested HTTP requests and Actions; their remembered approval names a website or Action, not the run.
   await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS remember_tool_name TEXT`.simple();
   await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS allow_chat BOOLEAN NOT NULL DEFAULT FALSE`.simple();
+  await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS consumed_inline BOOLEAN NOT NULL DEFAULT FALSE`.simple();
 
   await sql`
     CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_pending_actions_turn_call
@@ -661,6 +662,12 @@ export const migrateCloudAi = async (): Promise<void> => {
     WHERE status = 'pending'
   `.simple();
 
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_ai_pending_actions_approval
+    ON ai.pending_actions(approval_id)
+    WHERE approval_id IS NOT NULL
+  `.simple();
+
   await sql`
     DO $$
     BEGIN

package/src/ai/openai-api-messages.ts

@@ -0,0 +1,53 @@
+import { i18n } from "@k2b/stdlib";
+
+const catalog = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      openai_api_disabled: "The OpenAI-compatible API is turned off. Contact an administrator.",
+      invalid_api_key: "Use an active API key with the access “AI models only”. Create one in your Cloud profile.",
+      model_not_found: "This model is unavailable or you do not have access to it.",
+      invalid_request: "The request does not match the supported chat completion format.",
+      unsupported_content:
+        "Only text messages with system, developer, user or assistant roles are supported. Tool calls are not supported.",
+      unsupported_parameter: "This parameter is not supported. This API gives access to the models only.",
+      context_length_exceeded: "Your messages exceed this model's context window. Shorten them and try again.",
+      request_too_large: "The request body exceeds the limit derived from your available models' context windows.",
+      ai_disabled: "AI is turned off. Contact an administrator.",
+      model_access_denied: "You do not have access to this model. Contact an administrator.",
+      missing_provider_credential: "This model's provider is not configured. Contact an administrator.",
+      insufficient_quota:
+        "Your Assistant usage limit is reached, or your usage could not be measured. Wait for the reset or contact an administrator.",
+      too_many_concurrent_requests: "You have too many simultaneous requests. Wait for a request to finish and try again.",
+      rate_limit_exceeded: "Too many requests. Wait and try again.",
+      upstream_error: "The model provider could not complete your request. Try again later.",
+      internal_error: "Cloud could not process your request. Try again later.",
+      not_found: "This OpenAI-compatible API route does not exist.",
+    },
+    de: {
+      openai_api_disabled: "Die OpenAI-kompatible API ist ausgeschaltet. Wende dich an einen Administrator.",
+      invalid_api_key: "Verwende einen aktiven API-Schlüssel mit dem Zugriff „Nur KI-Modelle“. Du erstellst ihn in deinem Cloud-Profil.",
+      model_not_found: "Dieses Modell ist nicht verfügbar oder nicht für dich freigegeben.",
+      invalid_request: "Deine Anfrage entspricht nicht dem unterstützten Format für Chat-Vervollständigungen.",
+      unsupported_content:
+        "Nur Textnachrichten mit den Rollen system, developer, user oder assistant werden unterstützt. Werkzeugaufrufe werden nicht unterstützt.",
+      unsupported_parameter: "Dieser Parameter wird nicht unterstützt. Diese API gibt nur Zugriff auf die Modelle.",
+      context_length_exceeded: "Deine Nachrichten überschreiten das Kontextfenster dieses Modells. Kürze sie und versuche es erneut.",
+      request_too_large: "Deine Anfrage überschreitet die aus den Kontextfenstern deiner verfügbaren Modelle abgeleitete Größenbegrenzung.",
+      ai_disabled: "KI ist ausgeschaltet. Wende dich an einen Administrator.",
+      model_access_denied: "Dieses Modell ist nicht für dich freigegeben. Wende dich an einen Administrator.",
+      missing_provider_credential: "Der Anbieter dieses Modells ist nicht eingerichtet. Wende dich an einen Administrator.",
+      insufficient_quota:
+        "Dein Nutzungslimit im Assistenten ist erreicht, oder deine Nutzung konnte nicht gemessen werden. Warte auf das Zurücksetzen oder wende dich an einen Administrator.",
+      too_many_concurrent_requests: "Du hast zu viele gleichzeitige Anfragen. Warte, bis eine Anfrage beendet ist, und versuche es erneut.",
+      rate_limit_exceeded: "Zu viele Anfragen. Warte kurz und versuche es erneut.",
+      upstream_error: "Der Modellanbieter konnte deine Anfrage nicht abschließen. Versuche es später erneut.",
+      internal_error: "Cloud konnte deine Anfrage nicht verarbeiten. Versuche es später erneut.",
+      not_found: "Diese Route der OpenAI-kompatiblen API existiert nicht.",
+    },
+  },
+});
+
+export type OpenAiErrorCode = keyof ReturnType<typeof catalog.resolve>["t"];
+export const openAiApiMessages = (locale: string) => catalog.resolve([locale]).t;
+export const checkOpenAiApiMessages = () => catalog.check();

package/src/ai/openai-api-slots.ts

@@ -0,0 +1,40 @@
+import { redis } from "bun";
+import { logger } from "../services/logging";
+
+const LEASE_MS = 120_000;
+const log = logger("ai:openai-api");
+const SLOT_SCRIPT = `
+  local time = redis.call("TIME")
+  local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+  local key = KEYS[1]
+  local slot = ARGV[1]
+  local leaseMs = tonumber(ARGV[2])
+  redis.call("ZREMRANGEBYSCORE", key, "-inf", now)
+  if ARGV[3] == "refresh" then
+    if not redis.call("ZSCORE", key, slot) then return 0 end
+  elseif redis.call("ZCARD", key) >= tonumber(ARGV[3]) then
+    return 0
+  end
+  redis.call("ZADD", key, now + leaseMs, slot)
+  redis.call("PEXPIRE", key, leaseMs)
+  return 1
+`;
+
+export const acquire = async ({ userId, limit }: { userId: string; limit: number }): Promise<{ release(): Promise<void> } | null> => {
+  const key = `cloud:ai:openai-api:slots:${userId}`;
+  const slot = crypto.randomUUID();
+  const granted = await redis.send("EVAL", [SLOT_SCRIPT, "1", key, slot, String(LEASE_MS), String(limit)]);
+  if (granted !== 1) return null;
+  const heartbeat = setInterval(() => {
+    void redis
+      .send("EVAL", [SLOT_SCRIPT, "1", key, slot, String(LEASE_MS), "refresh"])
+      .catch(() => log.warn("OpenAI API slot heartbeat failed"));
+  }, 30_000);
+  heartbeat.unref();
+  return {
+    async release() {
+      clearInterval(heartbeat);
+      await redis.send("ZREM", [key, slot]);
+    },
+  };
+};

package/src/ai/openai-api.ts

@@ -0,0 +1,383 @@
+import { estimateTokens, type Message, type Provider } from "@k2b/nessi";
+import type { GenerateRequest, StreamEvent, Usage } from "@k2b/nessi/ai";
+import { type Context, Hono, type MiddlewareHandler } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { streamSSE } from "hono/streaming";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { type AuthContext, getLocale, rateLimit } from "../server";
+import { REQUEST_IDLE_TIMEOUT_SECONDS, setRequestTimeout } from "../server/request-timeout";
+import { authenticateModelsOnlyCredential } from "../services/identity/models-only-auth";
+import { coreSettings } from "../services/settings/api";
+import { listAssistantAiModels } from "./assistant-models";
+import { type OpenAiErrorCode, openAiApiMessages } from "./openai-api-messages";
+import { acquire } from "./openai-api-slots";
+import { personalAiModelPolicy } from "./personal-agent";
+import { PROVIDER_TIMEOUTS } from "./provider";
+import { inferenceProvider } from "./quota-provider";
+import { AiQuotaError } from "./quotas";
+import { resolveAiModel } from "./settings";
+
+// Leave time for the provider's silence timeout to reach the client as a 502 JSON error.
+const PROVIDER_WAIT_SECONDS = Math.ceil(Math.max(PROVIDER_TIMEOUTS.firstByteMs, PROVIDER_TIMEOUTS.idleMs) / 1000) + 10;
+
+type ErrorType =
+  | "invalid_request_error"
+  | "authentication_error"
+  | "permission_error"
+  | "insufficient_quota"
+  | "rate_limit_error"
+  | "api_error";
+type ErrorStatus = 400 | 401 | 403 | 404 | 413 | 429 | 500 | 502;
+const errorBody = (c: Context<AuthContext>, code: OpenAiErrorCode, type: ErrorType, param: string | null = null) => ({
+  error: { message: openAiApiMessages(getLocale(c))[code], type, param, code },
+});
+const errorResponse = (c: Context<AuthContext>, status: ErrorStatus, code: OpenAiErrorCode, type: ErrorType, param: string | null = null) =>
+  c.json(errorBody(c, code, type, param), status);
+
+// OpenAI clients often send `null` for fields they leave unset, so every optional field accepts it as absent.
+const completionSchema = z.object({
+  model: z.string().min(1),
+  messages: z
+    .array(
+      z.object({
+        role: z.string(),
+        content: z.unknown(),
+        tool_calls: z.array(z.unknown()).nullish(),
+        function_call: z.unknown().nullish(),
+      }),
+    )
+    .min(1),
+  temperature: z.number().min(0).max(2).nullish(),
+  top_p: z.number().min(0).max(1).nullish(),
+  max_tokens: z.number().int().positive().nullish(),
+  max_completion_tokens: z.number().int().positive().nullish(),
+  stream: z.boolean().nullish(),
+  stream_options: z.object({ include_usage: z.boolean().nullish() }).nullish(),
+  tools: z.array(z.unknown()).nullish(),
+  functions: z.array(z.unknown()).nullish(),
+  n: z.number().nullish(),
+  response_format: z.object({ type: z.string() }).nullish(),
+  audio: z.unknown().nullish(),
+  modalities: z.array(z.string()).nullish(),
+});
+const textContent = z.union([z.string(), z.array(z.object({ type: z.literal("text"), text: z.string() }))]);
+const failedFinish = (reason: string | undefined) => reason === "error" || reason === "aborted" || reason === "interrupted";
+const finishReason = (reason: string | undefined) => (reason === "max_tokens" ? "length" : "stop");
+const usageBody = (usage: Usage) => ({
+  prompt_tokens: usage.input,
+  completion_tokens: usage.output,
+  total_tokens: usage.input + usage.output,
+});
+
+type Dependencies = {
+  limit?: MiddlewareHandler<AuthContext>;
+  settings?: Pick<typeof coreSettings, "get">;
+  authenticate?: typeof authenticateModelsOnlyCredential;
+  listModels?: typeof listAssistantAiModels;
+  resolveModel?: typeof resolveAiModel;
+  acquire?: typeof acquire;
+  inferenceProvider?: typeof inferenceProvider;
+  keepaliveMs?: number;
+};
+
+export const createAiOpenAiRoutes = (dependencies: Dependencies = {}) => {
+  const settings = dependencies.settings ?? coreSettings;
+  const authenticate = dependencies.authenticate ?? authenticateModelsOnlyCredential;
+  const listModels = dependencies.listModels ?? listAssistantAiModels;
+  const resolveModel = dependencies.resolveModel ?? resolveAiModel;
+  const acquireSlot = dependencies.acquire ?? acquire;
+  const wrapProvider = dependencies.inferenceProvider ?? inferenceProvider;
+  const limit = dependencies.limit ?? rateLimit();
+  const app = new Hono<AuthContext>();
+  app.onError((error, c) => {
+    if (error instanceof AiQuotaError && error.code !== "quota_conflict")
+      return errorResponse(c, 429, "insufficient_quota", "insufficient_quota");
+    if (error instanceof Error && "aiError" in error) {
+      const parsed = z.object({ code: z.string() }).safeParse(error.aiError);
+      if (parsed.success) {
+        if (parsed.data.code === "ai_disabled") return errorResponse(c, 403, "ai_disabled", "permission_error");
+        if (parsed.data.code === "model_access_denied") return errorResponse(c, 403, "model_access_denied", "permission_error", "model");
+        if (parsed.data.code === "model_policy_mismatch") return errorResponse(c, 404, "model_not_found", "invalid_request_error", "model");
+        if (parsed.data.code === "missing_provider_credential") return errorResponse(c, 502, "missing_provider_credential", "api_error");
+      }
+    }
+    return errorResponse(c, 500, "internal_error", "api_error");
+  });
+  return app
+    .use("*", async (c, next) => {
+      const response = await limit(c, next);
+      if (response?.status === 429) return errorResponse(c, 429, "rate_limit_exceeded", "rate_limit_error");
+      return response;
+    })
+    .use("*", async (c, next) => {
+      if (!(await settings.get<boolean>("ai.openai_api_enabled"))) return errorResponse(c, 403, "openai_api_disabled", "permission_error");
+      const token = c.req.header("Authorization")?.match(/^Bearer\s+(\S+)$/i)?.[1];
+      const credential = await authenticate(token);
+      if (!credential) return errorResponse(c, 401, "invalid_api_key", "authentication_error");
+      c.set("user", credential.user);
+      c.set("accessSubject", { type: "user", userId: credential.user.id });
+      c.header("Cache-Control", "no-store");
+      await next();
+    })
+    .get(
+      "/models",
+      describeRoute({
+        tags: ["AI"],
+        summary: "List OpenAI-compatible models",
+        description: "Models-only OpenAI-compatible surface: lists the Assistant chat models this person may use.",
+      }),
+      async (c) => {
+        const models = await listModels(c.get("accessSubject"));
+        return c.json({
+          object: "list",
+          data: models
+            .filter((model) => !model.capabilities.includes("transcription"))
+            .map((model) => ({ id: model.id, object: "model", created: 0, owned_by: "cloud" })),
+        });
+      },
+    )
+    .post(
+      "/chat/completions",
+      describeRoute({
+        tags: ["AI"],
+        summary: "Create an OpenAI-compatible chat completion",
+        description:
+          "Models-only OpenAI-compatible text inference using only client messages, without Cloud tools or conversation context. Unknown fields are ignored.",
+      }),
+      async (c) => {
+        const subject = c.get("accessSubject");
+        const models = (await listModels(subject)).filter((model) => !model.capabilities.includes("transcription"));
+        if (models.length === 0) return errorResponse(c, 404, "model_not_found", "invalid_request_error", "model");
+        const slot = await acquireSlot({
+          userId: c.get("user").id,
+          limit: await settings.get<number>("ai.openai_api_max_concurrent_requests"),
+        });
+        if (!slot) {
+          c.header("Retry-After", "1");
+          return errorResponse(c, 429, "too_many_concurrent_requests", "rate_limit_error");
+        }
+        let ownsSlot = true;
+        try {
+          // estimateTokens assumes ~4 characters/token, each up to 4 UTF-8 bytes.
+          // An unspecified context counts as Gemini's 1,000,000-token adapter default, the largest supported default.
+          const maxSize = 16 * Math.max(0, ...models.map((model) => model.contextWindow ?? 1_000_000));
+          let body: unknown;
+          const tooLarge = await bodyLimit({
+            maxSize,
+            onError: () => errorResponse(c, 413, "request_too_large", "invalid_request_error"),
+          })(c, async () => {
+            body = await c.req.json().catch(() => undefined);
+          });
+          if (tooLarge) return tooLarge;
+          const parsed = completionSchema.safeParse(body);
+          if (!parsed.success)
+            return errorResponse(c, 400, "invalid_request", "invalid_request_error", String(parsed.error.issues[0]?.path[0] ?? "") || null);
+          const data = parsed.data;
+          for (const [param, unsupported] of [
+            ["tools", Boolean(data.tools?.length)],
+            ["functions", Boolean(data.functions?.length)],
+            ["n", data.n != null && data.n !== 1],
+            ["response_format", data.response_format != null && data.response_format.type !== "text"],
+            ["audio", data.audio != null],
+            ["modalities", Boolean(data.modalities?.includes("audio"))],
+          ] as const) {
+            if (unsupported) return errorResponse(c, 400, "unsupported_parameter", "invalid_request_error", param);
+          }
+          const messages: Message[] = [];
+          const system: string[] = [];
+          for (const message of data.messages) {
+            const content = textContent.safeParse(message.content);
+            if (
+              !content.success ||
+              !["system", "developer", "user", "assistant"].includes(message.role) ||
+              (message.role === "assistant" && (Boolean(message.tool_calls?.length) || message.function_call != null))
+            )
+              return errorResponse(c, 400, "unsupported_content", "invalid_request_error", "messages");
+            const text = typeof content.data === "string" ? content.data : content.data.map((part) => part.text).join("");
+            if (message.role === "system" || message.role === "developer") system.push(text);
+            else if (message.role === "user") messages.push({ role: "user", content: [text] });
+            else messages.push({ role: "assistant", content: [{ type: "text", text }] });
+          }
+          if (!models.some((model) => model.id === data.model))
+            return errorResponse(c, 404, "model_not_found", "invalid_request_error", "model");
+          const resolved = await resolveModel(personalAiModelPolicy, data.model);
+          const systemPrompt = system.join("\n\n");
+          const inputTokens = estimateTokens(messages) + Math.ceil(systemPrompt.length / 4);
+          if (resolved.provider.contextWindow !== undefined && inputTokens > resolved.provider.contextWindow)
+            return errorResponse(c, 400, "context_length_exceeded", "invalid_request_error", "messages");
+          const requested = data.max_completion_tokens ?? data.max_tokens ?? undefined;
+          const maxOutputTokens =
+            requested === undefined
+              ? resolved.profile.maxOutputTokens
+              : resolved.profile.maxOutputTokens === undefined
+                ? requested
+                : Math.min(requested, resolved.profile.maxOutputTokens);
+          const controller = new AbortController();
+          const request: GenerateRequest = {
+            messages,
+            systemPrompt,
+            temperature: data.temperature ?? undefined,
+            maxOutputTokens,
+            reasoningEffort: resolved.profile.reasoningEffort,
+            signal: AbortSignal.any([c.req.raw.signal, controller.signal]),
+            extraBody:
+              data.top_p == null
+                ? undefined
+                : resolved.provider.family === "ollama"
+                  ? { options: { top_p: data.top_p } }
+                  : resolved.provider.family === "gemini"
+                    ? { generationConfig: { topP: data.top_p } }
+                    : { top_p: data.top_p },
+          };
+          const provider: Provider = wrapProvider(resolved.provider, resolved.profile, { kind: "chat", task: "openai-api", subject });
+          const id = `chatcmpl-${crypto.randomUUID()}`;
+          const created = Math.floor(Date.now() / 1000);
+          let events: AsyncIterator<StreamEvent> | undefined;
+          const kinds = new Map<string, string>();
+          let usage: Usage | undefined;
+          let reason: string | undefined;
+          const readEvent = (event: StreamEvent): string | undefined => {
+            if (event.type === "block_start") kinds.set(event.blockId, event.kind);
+            if (event.type === "issue" && (event.issue.kind === "provider_error" || event.issue.kind === "timeout"))
+              throw new Error("Upstream stream failed");
+            if (event.type === "usage") {
+              const { input, output } = event.usage;
+              if (Number.isSafeInteger(input) && Number.isSafeInteger(output) && input >= 0 && output >= 0 && input + output > 0)
+                usage = event.usage;
+              reason = event.finishReason;
+              if (failedFinish(reason)) throw new Error("Upstream stream failed");
+            }
+            if (event.type === "block_delta" && kinds.get(event.blockId) === "text" && event.delta) return event.delta;
+          };
+          if (!data.stream) {
+            try {
+              request.signal?.throwIfAborted();
+              setRequestTimeout(c, PROVIDER_WAIT_SECONDS);
+              events = provider.stream(request)[Symbol.asyncIterator]();
+              try {
+                const text: string[] = [];
+                for (;;) {
+                  request.signal?.throwIfAborted();
+                  const step = await events.next();
+                  if (step.done) break;
+                  setRequestTimeout(c, PROVIDER_WAIT_SECONDS);
+                  const delta = readEvent(step.value);
+                  if (delta !== undefined) text.push(delta);
+                }
+                return c.json({
+                  id,
+                  object: "chat.completion",
+                  created,
+                  model: resolved.profile.id,
+                  choices: [
+                    {
+                      index: 0,
+                      message: { role: "assistant", content: text.join("") },
+                      logprobs: null,
+                      finish_reason: finishReason(reason),
+                    },
+                  ],
+                  ...(usage ? { usage: usageBody(usage) } : {}),
+                });
+              } finally {
+                await events.return?.();
+              }
+            } catch (error) {
+              if (error instanceof AiQuotaError) throw error;
+              return errorResponse(c, 502, "upstream_error", "api_error");
+            } finally {
+              controller.abort();
+            }
+          }
+          let first: string | undefined;
+          let ended = false;
+          try {
+            request.signal?.throwIfAborted();
+            setRequestTimeout(c, PROVIDER_WAIT_SECONDS);
+            events = provider.stream(request)[Symbol.asyncIterator]();
+            // Admission and failures before text still get an HTTP JSON error, before SSE commits headers.
+            while (first === undefined) {
+              const step = await events.next();
+              if (step.done) {
+                ended = true;
+                break;
+              }
+              setRequestTimeout(c, PROVIDER_WAIT_SECONDS);
+              first = readEvent(step.value);
+            }
+          } catch (error) {
+            try {
+              await events?.return?.();
+            } finally {
+              controller.abort();
+            }
+            if (error instanceof AiQuotaError) throw error;
+            return errorResponse(c, 502, "upstream_error", "api_error");
+          }
+          const streamEvents = events;
+          // From here the SSE callback releases the slot when the stream ends.
+          ownsSlot = false;
+          return streamSSE(c, async (stream) => {
+            stream.onAbort(() => controller.abort());
+            const chunk = (delta: { role?: string; content?: string }, finish: string | null = null) => ({
+              id,
+              object: "chat.completion.chunk",
+              created,
+              model: resolved.profile.id,
+              choices: [{ index: 0, delta, finish_reason: finish, logprobs: null }],
+            });
+            let pendingWrites = 0;
+            const write = async (value: string) => {
+              pendingWrites++;
+              try {
+                await stream.write(value);
+              } finally {
+                pendingWrites--;
+              }
+            };
+            const send = (value: unknown) => write(`data: ${JSON.stringify(value)}\n\n`);
+            const keepalive = setInterval(() => {
+              if (pendingWrites === 0) void write(": keepalive\n\n").catch(() => undefined);
+            }, dependencies.keepaliveMs ?? 5_000);
+            try {
+              await send(chunk({ role: "assistant", content: "" }));
+              if (first !== undefined) await send(chunk({ content: first }));
+              while (!ended) {
+                request.signal?.throwIfAborted();
+                const step = await streamEvents.next();
+                if (step.done) break;
+                const text = readEvent(step.value);
+                if (text !== undefined) await send(chunk({ content: text }));
+              }
+              await send(chunk({}, finishReason(reason)));
+              if (data.stream_options?.include_usage && usage)
+                await send({
+                  id,
+                  object: "chat.completion.chunk",
+                  created,
+                  model: resolved.profile.id,
+                  choices: [],
+                  usage: usageBody(usage),
+                });
+              await write("data: [DONE]\n\n");
+            } catch {
+              if (!request.signal?.aborted) await send(errorBody(c, "upstream_error", "api_error"));
+            } finally {
+              clearInterval(keepalive);
+              try {
+                await streamEvents.return?.();
+              } finally {
+                controller.abort();
+                await slot.release();
+              }
+            }
+          });
+        } finally {
+          setRequestTimeout(c, REQUEST_IDLE_TIMEOUT_SECONDS);
+          if (ownsSlot) await slot.release();
+        }
+      },
+    )
+    .all("*", (c) => errorResponse(c, 404, "not_found", "invalid_request_error"));
+};