paseo-prompt-kit 0.5.2

package/server/transports/api/cloudflare.ts

@@ -0,0 +1,52 @@
+import { at, authHeaders, joinUrl, stringFieldAt, type ApiCall, type ApiHttpRequest, type ApiModelsCall, type ApiProtocol } from "./protocol.js";
+
+/**
+ * Cloudflare Workers AI `ai/run`. Base URL `https://api.cloudflare.com/client/v4`; the account
+ * id and the model are path segments (`/accounts/<id>/ai/run/@cf/...`, model slashes kept),
+ * and the answer is `result.response`.
+ * `max_tokens` is sent because the service default (256) would cut a rewrite short.
+ */
+const MAX_TOKENS = 2048;
+
+function accountPath(accountId: string): string {
+  return `/accounts/${encodeURIComponent(accountId)}/ai`;
+}
+
+function bearer(key: string): Record<string, string> {
+  return { authorization: `Bearer ${key}` };
+}
+
+export const cloudflareProtocol: ApiProtocol = {
+  id: "cloudflare",
+  buildRequest(call: ApiCall): ApiHttpRequest {
+    return {
+      url: joinUrl(call.baseUrl, `${accountPath(call.accountId)}/run/${encodeURI(call.model.replace(/^\/+/, ""))}`),
+      headers: { "content-type": "application/json", ...authHeaders(call.apiKey, bearer) },
+      body: JSON.stringify({
+        messages: [
+          { role: "system", content: call.systemPrompt },
+          { role: "user", content: call.taskPrompt },
+        ],
+        temperature: 0,
+        max_tokens: MAX_TOKENS,
+      }),
+    };
+  },
+  parseResponse(payload: unknown): string | null {
+    const response = at(payload, "result", "response");
+    if (typeof response === "string") return response;
+    // Some newer models answer in the OpenAI shape inside `result`.
+    const content = at(payload, "result", "choices", 0, "message", "content");
+    return typeof content === "string" ? content : null;
+  },
+  buildModelsRequest(call: ApiModelsCall): ApiHttpRequest {
+    return {
+      url: joinUrl(call.baseUrl, `${accountPath(call.accountId)}/models/search?task=Text%20Generation&per_page=100`),
+      headers: { ...authHeaders(call.apiKey, bearer) },
+      body: "",
+    };
+  },
+  parseModelsResponse(payload: unknown): string[] {
+    return stringFieldAt(payload, ["result"], "name");
+  },
+};

package/server/transports/api/gemini.ts

@@ -0,0 +1,62 @@
+import { at, authHeaders, joinUrl, stringFieldAt, type ApiCall, type ApiHttpRequest, type ApiModelsCall, type ApiProtocol } from "./protocol.js";
+
+/**
+ * The Google Gemini `generateContent` protocol.
+ *
+ * Gemini is the one protocol that differs structurally rather than cosmetically:
+ * the model is a path segment, not a body field; the instruction goes in
+ * `systemInstruction`; roles are `user`/`model`; and the answer arrives as
+ * `candidates[0].content.parts[].text`. It also has no `temperature: 0` default
+ * equivalent worth sending, so temperature is set explicitly for the same
+ * transformation-not-creation reason as the other two.
+ *
+ * A base URL of `https://generativelanguage.googleapis.com` yields
+ * `/v1beta/models/<model>:generateContent`, the documented stable path.
+ */
+export const geminiProtocol: ApiProtocol = {
+  id: "gemini",
+  buildRequest(call: ApiCall): ApiHttpRequest {
+    const model = encodeURIComponent(call.model);
+    return {
+      url: joinUrl(call.baseUrl, `/v1beta/models/${model}:generateContent`),
+      headers: {
+        "content-type": "application/json",
+        ...authHeaders(call.apiKey, (key) => ({ "x-goog-api-key": key })),
+      },
+      body: JSON.stringify({
+        systemInstruction: { parts: [{ text: call.systemPrompt }] },
+        contents: [{ role: "user", parts: [{ text: call.taskPrompt }] }],
+        generationConfig: { temperature: 0 },
+      }),
+    };
+  },
+  parseResponse(payload: unknown): string | null {
+    const parts = at(payload, "candidates", 0, "content", "parts");
+    if (!Array.isArray(parts)) return null;
+    const text: string[] = [];
+    for (const part of parts) {
+      if (part === null || typeof part !== "object") continue;
+      const value = (part as { text?: unknown }).text;
+      if (typeof value === "string") text.push(value);
+    }
+    return text.length === 0 ? null : text.join("");
+  },
+  buildModelsRequest(call: ApiModelsCall): ApiHttpRequest {
+    // Google's model list is large, so only the fields the picker needs are asked
+    // for; the page size keeps a long catalogue from being pulled in one call.
+    return {
+      url: joinUrl(call.baseUrl, "/v1beta/models?pageSize=200"),
+      headers: {
+        ...authHeaders(call.apiKey, (key) => ({ "x-goog-api-key": key })),
+      },
+      body: "",
+    };
+  },
+  parseModelsResponse(payload: unknown): string[] {
+    // `models/gemini-2.5-flash` is the wire name; the path segment is the id a
+    // request takes, so the prefix is stripped here rather than by every caller.
+    return stringFieldAt(payload, ["models"], "name").map((name) =>
+      name.startsWith("models/") ? name.slice("models/".length) : name,
+    );
+  },
+};

package/server/transports/api/key.ts

@@ -0,0 +1,95 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { ApiKeySource } from "../../../shared/api-protocol.js";
+
+/**
+ * Resolves an endpoint's key from the one source it names. No source falls back to
+ * another: a key missing where the user said it is, is an error.
+ *
+ * The settings document never holds a key, because it travels to the client. Nothing
+ * here logs, throws with, or returns a key except `resolveApiKey`.
+ */
+
+export type ApiKeyLookupFailure =
+  | "missing_env"
+  | "missing_secrets_file"
+  | "missing_secrets_entry"
+  | "unreadable_secrets"
+  | "invalid_secrets_dir"
+  | "no_key_name";
+
+export type ApiKeyLookup =
+  | { readonly ok: true; readonly key: string; readonly source: ApiKeySource }
+  | { readonly ok: false; readonly reason: ApiKeyLookupFailure };
+
+type SecretsRead =
+  | { readonly ok: true; readonly apiKeys: Readonly<Record<string, string>> }
+  | { readonly ok: false; readonly reason: "missing_secrets_file" | "unreadable_secrets" };
+
+/** `$PASEO_HOME/plugin-settings/prompt-kit`, the directory the daemon stores settings in. */
+export function defaultSecretsDir(env: NodeJS.ProcessEnv = process.env): string {
+  const home = env.PASEO_HOME?.trim();
+  const root = home === undefined || home === "" ? path.join(homedir(), ".paseo") : home;
+  return path.join(root, "plugin-settings", "prompt-kit");
+}
+
+/** Absolute directory for `secretsDir`, `~/` expanded; null when the value is relative. */
+export function resolveSecretsDir(
+  secretsDir: string | null,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  if (secretsDir === null) return defaultSecretsDir(env);
+  const value = secretsDir.trim();
+  if (value === "~" || value.startsWith("~/")) return path.join(homedir(), value.slice(1));
+  return path.isAbsolute(value) ? value : null;
+}
+
+/** Missing and malformed files are distinct reasons, so the message points at the right fix. */
+export async function readSecretsFile(filePath: string): Promise<SecretsRead> {
+  let raw: string;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return { ok: false, reason: code === "ENOENT" ? "missing_secrets_file" : "unreadable_secrets" };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "unreadable_secrets" };
+  }
+  const apiKeys = (parsed as { apiKeys?: unknown } | null)?.apiKeys;
+  if (apiKeys === null || typeof apiKeys !== "object") return { ok: false, reason: "unreadable_secrets" };
+  const entries: Record<string, string> = {};
+  for (const [name, value] of Object.entries(apiKeys as Record<string, unknown>)) {
+    if (typeof value === "string") entries[name] = value;
+  }
+  return { ok: true, apiKeys: entries };
+}
+
+/** The key for one endpoint from its own `keySource`, or the reason it is absent. */
+export async function resolveApiKey(input: {
+  readonly keySource: ApiKeySource;
+  readonly apiKeyEnv: string;
+  readonly secretsDir: string | null;
+  readonly env?: NodeJS.ProcessEnv;
+}): Promise<ApiKeyLookup> {
+  if (input.keySource === "none") return { ok: true, key: "", source: "none" };
+  const name = input.apiKeyEnv.trim();
+  if (name === "") return { ok: false, reason: "no_key_name" };
+  const env = input.env ?? process.env;
+
+  if (input.keySource === "env") {
+    const value = env[name]?.trim();
+    return value ? { ok: true, key: value, source: "env" } : { ok: false, reason: "missing_env" };
+  }
+
+  const dir = resolveSecretsDir(input.secretsDir, env);
+  if (dir === null) return { ok: false, reason: "invalid_secrets_dir" };
+  const secrets = await readSecretsFile(path.join(dir, "secrets.json"));
+  if (!secrets.ok) return secrets;
+  const value = secrets.apiKeys[name]?.trim();
+  return value ? { ok: true, key: value, source: "secrets_file" } : { ok: false, reason: "missing_secrets_entry" };
+}

package/server/transports/api/openai.ts

@@ -0,0 +1,52 @@
+import { at, authHeaders, joinUrl, stringFieldAt, type ApiCall, type ApiHttpRequest, type ApiModelsCall, type ApiProtocol } from "./protocol.js";
+
+/**
+ * The OpenAI Chat Completions protocol.
+ *
+ * One entry covers far more than OpenAI: OpenRouter, LiteLLM, vLLM,
+ * llama.cpp, LM Studio, Together, Fireworks and most internal gateways all speak
+ * this shape, so each of them is a `baseUrl` in settings rather than a module.
+ *
+ * No token limit is sent. OpenAI's newer models require `max_completion_tokens`
+ * and reject `max_tokens`, while older compatible endpoints only understand
+ * `max_tokens`; omitting the field entirely is the one form every endpoint
+ * accepts, and a rewrite is short enough not to need it.
+ */
+export const openAiProtocol: ApiProtocol = {
+  id: "openai",
+  buildRequest(call: ApiCall): ApiHttpRequest {
+    return {
+      url: joinUrl(call.baseUrl, "/chat/completions"),
+      headers: {
+        "content-type": "application/json",
+        ...authHeaders(call.apiKey, (key) => ({ authorization: `Bearer ${key}` })),
+      },
+      body: JSON.stringify({
+        model: call.model,
+        messages: [
+          { role: "system", content: call.systemPrompt },
+          { role: "user", content: call.taskPrompt },
+        ],
+        // A rewrite is a transformation, not a creative task.
+        temperature: 0,
+        stream: false,
+      }),
+    };
+  },
+  parseResponse(payload: unknown): string | null {
+    const content = at(payload, "choices", 0, "message", "content");
+    return typeof content === "string" ? content : null;
+  },
+  buildModelsRequest(call: ApiModelsCall): ApiHttpRequest {
+    return {
+      url: joinUrl(call.baseUrl, "/models"),
+      headers: {
+        ...authHeaders(call.apiKey, (key) => ({ authorization: `Bearer ${key}` })),
+      },
+      body: "",
+    };
+  },
+  parseModelsResponse(payload: unknown): string[] {
+    return stringFieldAt(payload, ["data"], "id");
+  },
+};

package/server/transports/api/protocol.ts

@@ -0,0 +1,96 @@
+import type { ApiProtocolId } from "../../../shared/api-protocol.js";
+
+/**
+ * What a protocol module must do: turn one prompt into one HTTP request, and pull
+ * the answer text out of the response.
+ *
+ * Nothing else is shared. Each vendor differs in headers, in where the system
+ * prompt goes, and in the shape of the answer, so a protocol module owns those
+ * three things and nothing more. Adding a vendor is a settings entry; adding a
+ * *protocol* is one file next to these.
+ */
+
+export interface ApiCall {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  /** Empty unless the protocol needs an account id. */
+  readonly accountId: string;
+  readonly model: string;
+  /** The rewrite instruction. */
+  readonly systemPrompt: string;
+  readonly taskPrompt: string;
+}
+
+export interface ApiHttpRequest {
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+
+/** Everything a protocol needs to ask an endpoint what models it offers. */
+export interface ApiModelsCall {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly accountId: string;
+}
+
+export interface ApiProtocol {
+  readonly id: ApiProtocolId;
+  /** `null` means the answer could not be read; the runner maps that to a code. */
+  buildRequest(call: ApiCall): ApiHttpRequest;
+  parseResponse(payload: unknown): string | null;
+  /**
+   * The request that lists the models this endpoint offers. Used by the settings
+   * screen's test button, which is the only way a user learns whether a key and a
+   * base URL are right before a rewrite fails on them.
+   */
+  buildModelsRequest(input: ApiModelsCall): ApiHttpRequest;
+  parseModelsResponse(payload: unknown): string[];
+}
+
+/** Strips a trailing slash so a base URL and a path cannot produce a double slash. */
+export function joinUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}${path}`;
+}
+
+/**
+ * An endpoint with no `apiKeyEnv` needs no key — a local server is legitimate —
+ * so an empty key means "send no credential header" rather than an error.
+ */
+export function authHeaders(
+  apiKey: string,
+  build: (key: string) => Record<string, string>,
+): Record<string, string> {
+  return apiKey === "" ? {} : build(apiKey);
+}
+
+/**
+ * Reads a nested value by path, so each parser stays a flat description of the
+ * response shape instead of a chain of casts.
+ */
+export function at(payload: unknown, ...path: readonly (string | number)[]): unknown {
+  let current: unknown = payload;
+  for (const step of path) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string | number, unknown>)[step];
+  }
+  return current;
+}
+
+/**
+ * Collects the string values at `path` into a de-duplicated list.
+ *
+ * Every protocol lists models as an array of objects with one identifying field,
+ * so this is the shared half of `parseModelsResponse` for all three.
+ */
+export function stringFieldAt(payload: unknown, path: readonly (string | number)[], field: string): string[] {
+  const list = at(payload, ...path);
+  if (!Array.isArray(list)) return [];
+  const seen = new Set<string>();
+  for (const entry of list) {
+    if (entry === null || typeof entry !== "object") continue;
+    const value = (entry as Record<string, unknown>)[field];
+    if (typeof value === "string" && value.trim() !== "") seen.add(value.trim());
+  }
+  return [...seen];
+}

package/server/transports/api/runner.ts

@@ -0,0 +1,284 @@
+import { protocolNeedsAccountId, type ApiEndpoint, type ApiProtocolId } from "../../../shared/api-protocol.js";
+import { anthropicProtocol } from "./anthropic.js";
+import { cloudflareProtocol } from "./cloudflare.js";
+import { geminiProtocol } from "./gemini.js";
+import { resolveApiKey, type ApiKeyLookupFailure } from "./key.js";
+import { openAiProtocol } from "./openai.js";
+import type { ApiProtocol } from "./protocol.js";
+
+/**
+ * The rewrite path that talks to an API directly.
+ *
+ * It is the counterpart of `server/transports/cli/runner.ts` and shares its contract: given
+ * a model and a prompt, return text or a typed reason there is none. Everything
+ * else — the protected-literal validator, the Composer write, the RPC shape — is
+ * unchanged, so the two transports cannot drift apart in behaviour.
+ *
+ * Fail closed throughout. An unknown endpoint, a missing key, a non-2xx status,
+ * an unreadable body and an unparseable answer are all distinct failures, and
+ * none of them falls back to another endpoint, another model, or the CLI path.
+ */
+
+const PROTOCOLS: Readonly<Record<ApiProtocolId, ApiProtocol>> = {
+  openai: openAiProtocol,
+  anthropic: anthropicProtocol,
+  gemini: geminiProtocol,
+  cloudflare: cloudflareProtocol,
+};
+
+/** Names the variable and where it was looked for, never the value. */
+function describeMissing(what: "key" | "account ID", name: string, endpointId: string, reason: ApiKeyLookupFailure): string {
+  switch (reason) {
+    case "no_key_name":
+      return what === "key"
+        ? `Endpoint "${endpointId}" has no key variable. Enter one, or set Key source to No key.`
+        : `Endpoint "${endpointId}" has no account ID variable.`;
+    case "missing_env":
+      return `The environment variable "${name}" (${what}) is not set for the Paseo daemon. Paseo reads shell variables once, when it starts: if you added it since, quit and reopen Paseo.`;
+    case "missing_secrets_file":
+      return `secrets.json was not found in the secrets directory, so "${name}" (${what}) cannot be read.`;
+    case "missing_secrets_entry":
+      return `secrets.json has no value for "${name}" (${what}).`;
+    case "unreadable_secrets":
+      return `secrets.json exists but could not be read as { "apiKeys": { ... } }; fix the file before "${name}" can be looked up.`;
+    case "invalid_secrets_dir":
+      return "The secrets directory must be an absolute path or start with ~/.";
+  }
+}
+
+type Credentials =
+  | { readonly ok: true; readonly apiKey: string; readonly accountId: string }
+  | { readonly ok: false; readonly code: "missing_api_key"; readonly message: string };
+
+/** The key, and the account id when the protocol needs one, each from the endpoint's own source. */
+async function resolveCredentials(
+  endpoint: ApiEndpoint,
+  secretsDir: string | null,
+  env: NodeJS.ProcessEnv | undefined,
+): Promise<Credentials> {
+  const shared = { secretsDir, ...(env === undefined ? {} : { env }) };
+  const key = await resolveApiKey({ keySource: endpoint.keySource, apiKeyEnv: endpoint.apiKeyEnv, ...shared });
+  if (!key.ok) {
+    return { ok: false, code: "missing_api_key", message: describeMissing("key", endpoint.apiKeyEnv.trim(), endpoint.id, key.reason) };
+  }
+  if (!protocolNeedsAccountId(endpoint.protocol)) return { ok: true, apiKey: key.key, accountId: "" };
+  const account = await resolveApiKey({
+    keySource: endpoint.keySource === "none" ? "env" : endpoint.keySource,
+    apiKeyEnv: endpoint.accountIdVar,
+    ...shared,
+  });
+  if (!account.ok) {
+    return {
+      ok: false,
+      code: "missing_api_key",
+      message: describeMissing("account ID", endpoint.accountIdVar.trim(), endpoint.id, account.reason),
+    };
+  }
+  return { ok: true, apiKey: key.key, accountId: account.key };
+}
+
+export type ApiRewriteFailureCode =
+  | "api_endpoint_unknown"
+  | "missing_api_key"
+  | "api_http_error"
+  | "api_bad_response"
+  | "timeout";
+
+export interface ApiRewriteInput {
+  readonly endpoint: ApiEndpoint;
+  readonly model: string;
+  readonly systemPrompt: string;
+  readonly taskPrompt: string;
+  readonly timeoutMs: number;
+  /** Directory holding `secrets.json`; null means the default under `PASEO_HOME`. */
+  readonly secretsDir: string | null;
+}
+
+export interface ApiRewriteDependencies {
+  /** Test seam: replaces the HTTP call. */
+  fetch?: typeof globalThis.fetch;
+  /** Test seam: replaces the environment the key is read from. */
+  env?: NodeJS.ProcessEnv;
+}
+
+export type ApiRewriteResult =
+  | { readonly ok: true; readonly text: string }
+  | { readonly ok: false; readonly code: ApiRewriteFailureCode; readonly message: string };
+
+export type ApiTestResult =
+  | { readonly ok: true; readonly models: readonly string[] }
+  | { readonly ok: false; readonly code: ApiRewriteFailureCode; readonly message: string };
+
+export function findProtocol(protocol: string): ApiProtocol | null {
+  return Object.prototype.hasOwnProperty.call(PROTOCOLS, protocol)
+    ? PROTOCOLS[protocol as ApiProtocolId]
+    : null;
+}
+
+/**
+ * Turns a non-2xx answer into a message safe to show a user.
+ *
+ * The provider's own error text is the most useful thing to surface, but it is
+ * untrusted and can echo the request, so it is truncated and stripped of newlines
+ * before it reaches a message or a log.
+ */
+function describeHttpError(status: number, body: string): string {
+  const trimmed = body.trim().replace(/\s+/g, " ").slice(0, 300);
+  return trimmed === ""
+    ? `The endpoint answered HTTP ${status}.`
+    : `The endpoint answered HTTP ${status}: ${trimmed}`;
+}
+
+/**
+ * Tests one endpoint: resolves the key, lists its models, and reports either the
+ * list or the exact reason there is none. Never throws, and never echoes a key.
+ *
+ * This is what the settings screen's test button calls, so a wrong base URL or a
+ * missing key is discovered while the user is still on the settings screen
+ * instead of on the next rewrite.
+ */
+export async function testApiEndpoint(
+  input: {
+    readonly endpoint: ApiEndpoint;
+    readonly secretsDir: string | null;
+    readonly timeoutMs: number;
+  },
+  dependencies: ApiRewriteDependencies = {},
+): Promise<ApiTestResult> {
+  const protocol = findProtocol(input.endpoint.protocol);
+  if (protocol === null) {
+    return {
+      ok: false,
+      code: "api_endpoint_unknown",
+      message: `No protocol implementation for "${input.endpoint.protocol}".`,
+    };
+  }
+
+  const credentials = await resolveCredentials(input.endpoint, input.secretsDir, dependencies.env);
+  if (!credentials.ok) return credentials;
+
+  const request = protocol.buildModelsRequest({
+    baseUrl: input.endpoint.baseUrl,
+    apiKey: credentials.apiKey,
+    accountId: credentials.accountId,
+  });
+  const doFetch = dependencies.fetch ?? globalThis.fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), input.timeoutMs);
+
+  let response: Response;
+  try {
+    response = await doFetch(request.url, {
+      method: "GET",
+      headers: request.headers,
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const aborted = controller.signal.aborted;
+    return {
+      ok: false,
+      code: aborted ? "timeout" : "api_http_error",
+      message: aborted
+        ? "The endpoint did not answer in time."
+        : `Could not reach the endpoint: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const body = await response.text().catch(() => "");
+  if (!response.ok) {
+    return { ok: false, code: "api_http_error", message: describeHttpError(response.status, body) };
+  }
+  let payload: unknown;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    return {
+      ok: false,
+      code: "api_bad_response",
+      message: "The endpoint answered with something that is not JSON.",
+    };
+  }
+  // An empty list is not a failure: a local server may expose none, and the key
+  // and URL still proved correct, which is the whole point of the test.
+  return { ok: true, models: protocol.parseModelsResponse(payload) };
+}
+
+export async function runApiRewrite(
+  input: ApiRewriteInput,
+  dependencies: ApiRewriteDependencies = {},
+): Promise<ApiRewriteResult> {
+  const protocol = findProtocol(input.endpoint.protocol);
+  if (protocol === null) {
+    return {
+      ok: false,
+      code: "api_endpoint_unknown",
+      message: `No protocol implementation for "${input.endpoint.protocol}".`,
+    };
+  }
+
+  // Messages name the variable, never a value.
+  const credentials = await resolveCredentials(input.endpoint, input.secretsDir, dependencies.env);
+  if (!credentials.ok) return credentials;
+
+  const request = protocol.buildRequest({
+    baseUrl: input.endpoint.baseUrl,
+    apiKey: credentials.apiKey,
+    accountId: credentials.accountId,
+    model: input.model,
+    systemPrompt: input.systemPrompt,
+    taskPrompt: input.taskPrompt,
+  });
+
+  const doFetch = dependencies.fetch ?? globalThis.fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), input.timeoutMs);
+
+  let response: Response;
+  try {
+    response = await doFetch(request.url, {
+      method: "POST",
+      headers: request.headers,
+      body: request.body,
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const aborted = controller.signal.aborted;
+    return {
+      ok: false,
+      code: aborted ? "timeout" : "api_http_error",
+      message: aborted
+        ? "The rewrite timed out."
+        : `Could not reach the endpoint: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const body = await response.text().catch(() => "");
+  if (!response.ok) {
+    return { ok: false, code: "api_http_error", message: describeHttpError(response.status, body) };
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    return {
+      ok: false,
+      code: "api_bad_response",
+      message: "The endpoint answered with something that is not JSON.",
+    };
+  }
+
+  const text = protocol.parseResponse(payload);
+  if (text === null || text.trim() === "") {
+    return {
+      ok: false,
+      code: "api_bad_response",
+      message: "The endpoint answered without any text to use.",
+    };
+  }
+  return { ok: true, text };
+}