kennel 0.2.1 → 0.2.2

package/kernel/packages/api/test/entity-folder.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { FolderEntity } from "../src/contracts";
+import { loadEntityWorkspace, rankEntity } from "../src/server/entity-folder";
+
+const cleanup: (() => Promise<unknown>)[] = [];
+
+afterEach(async () => {
+  delete process.env.XDG_CONFIG_HOME;
+  for (const fn of cleanup.splice(0).reverse()) await fn();
+});
+
+async function tempRoot(prefix: string): Promise<string> {
+  const root = await realpath(await mkdtemp(join(tmpdir(), prefix)));
+  cleanup.push(() => rm(root, { recursive: true, force: true }));
+  return root;
+}
+
+async function entityFolder(root: string, name = "alpha") {
+  const folder = join(root, name);
+  await mkdir(folder);
+  await writeFile(
+    join(folder, "index.md"),
+    "---\ntitle: Alpha\n---\n# Alpha\n",
+  );
+  return folder;
+}
+
+const entity: FolderEntity = {
+  aliases: ["Copper Watch", "Apart Book One"],
+  content: "Sam and Naya discover a watch ticking backwards after the Split.",
+  description: "The first manuscript in Apart.",
+  documents: [{ path: "Chapters/1. The Beginning.md", title: "The Beginning" }],
+  folderPath: "/workspace/books/The Copper Watch",
+  relativePath: "books/The Copper Watch",
+  schemaPath: "/workspace/books/The Copper Watch/schema.json",
+  slug: "the-copper-watch",
+  status: "drafting",
+  title: "The Copper Watch",
+  type: "manuscript",
+};
+
+describe("folder entity search", () => {
+  test("ranks title and alias matches above content matches", () => {
+    expect(rankEntity(entity, "Copper Watch")).toBeGreaterThan(
+      rankEntity(entity, "Split"),
+    );
+  });
+
+  test("searches entity metadata and rejects missing terms", () => {
+    expect(rankEntity(entity, "manuscript drafting")).toBeGreaterThan(0);
+    expect(rankEntity(entity, "unrelated phrase")).toBeLessThan(0);
+  });
+
+  test("uses the open workspace root when no user config exists", async () => {
+    const root = await tempRoot("kennel-entities-root-");
+    await entityFolder(root);
+    process.env.XDG_CONFIG_HOME = await tempRoot("kennel-entities-config-");
+
+    const workspace = await loadEntityWorkspace(undefined, "", null, root);
+
+    expect(workspace.rootPath).toBe(root);
+    expect(workspace.entities.map((item) => item.title)).toEqual(["Alpha"]);
+  });
+
+  test("allows configured roots and rejects filesystem escapes", async () => {
+    const allowed = await tempRoot("kennel-entities-allowed-");
+    const outside = await tempRoot("kennel-entities-outside-");
+    const configHome = await tempRoot("kennel-entities-config-");
+    await mkdir(join(configHome, "kennel"));
+    await writeFile(
+      join(configHome, "kennel", "config.json"),
+      JSON.stringify({ allowedRoots: [allowed] }),
+    );
+    await entityFolder(allowed);
+    await entityFolder(outside);
+    process.env.XDG_CONFIG_HOME = configHome;
+
+    await expect(
+      loadEntityWorkspace(allowed, "", null, outside),
+    ).resolves.toMatchObject({
+      rootPath: allowed,
+    });
+    await expect(
+      loadEntityWorkspace(outside, "", null, allowed),
+    ).rejects.toThrow("outside the configured roots");
+  });
+
+  test("invalid config fails closed", async () => {
+    const root = await tempRoot("kennel-entities-root-");
+    const configHome = await tempRoot("kennel-entities-config-");
+    await mkdir(join(configHome, "kennel"));
+    await writeFile(join(configHome, "kennel", "config.json"), "not json");
+    await entityFolder(root);
+    process.env.XDG_CONFIG_HOME = configHome;
+
+    await expect(
+      loadEntityWorkspace(undefined, "", null, root),
+    ).rejects.toThrow("Invalid Kennel entity root config");
+  });
+
+  test("unreadable config fails closed", async () => {
+    const root = await tempRoot("kennel-entities-root-");
+    const configHome = await tempRoot("kennel-entities-config-");
+    await mkdir(join(configHome, "kennel", "config.json"), {
+      recursive: true,
+    });
+    await entityFolder(root);
+    process.env.XDG_CONFIG_HOME = configHome;
+
+    await expect(
+      loadEntityWorkspace(undefined, "", null, root),
+    ).rejects.toThrow();
+  });
+
+  test("empty workspace root asks the UI to choose a root", async () => {
+    process.env.XDG_CONFIG_HOME = await tempRoot("kennel-entities-config-");
+
+    await expect(
+      loadEntityWorkspace(undefined, "", null),
+    ).resolves.toStrictEqual({
+      entities: [],
+      query: "",
+      rootPath: "",
+      selected: null,
+    });
+  });
+});

package/kernel/packages/api/test/linked-folder-discovery.test.ts

@@ -0,0 +1,78 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createLinkedFolderDiscovery, discoverLinkedFolders } from "../src/server/linked-folder-discovery";
+
+test("pending discovery returns local state immediately and coalesces requests", async () => {
+  let complete!: (paths: string[]) => void;
+  let calls = 0;
+  const changed: string[] = [];
+  const cache = createLinkedFolderDiscovery(() => {
+    calls++;
+    return new Promise(resolve => { complete = resolve; });
+  }, folder => changed.push(folder));
+  try {
+    expect(cache.read("/project")).toEqual({ folders: [], status: "pending" });
+    const wait = cache.folders("/project");
+    await Promise.resolve();
+    cache.read("/project");
+    expect(calls).toBe(1);
+    complete(["/notes"]);
+    expect(await wait).toEqual(["/notes"]);
+    expect(cache.read("/project").status).toBe("ready");
+    expect(changed).toEqual(["/project"]);
+    expect(calls).toBe(1);
+  } finally { cache.close(); }
+});
+
+test("failed discovery is explicit and cached instead of retrying on every poll", async () => {
+  let calls = 0;
+  const cache = createLinkedFolderDiscovery(async () => { calls++; throw new Error("unavailable"); });
+  try {
+    await cache.folders("/project");
+    expect(cache.read("/project").status).toBe("error");
+    await cache.folders("/project");
+    expect(calls).toBe(1);
+  } finally { cache.close(); }
+});
+
+test("expired linked notes remain available while discovery refreshes", async () => {
+  const now = Date.now;
+  let complete!: (paths: string[]) => void;
+  let calls = 0;
+  const cache = createLinkedFolderDiscovery(async () => {
+    if (++calls === 1) return ["/notes"];
+    return new Promise(resolve => { complete = resolve; });
+  });
+  try {
+    expect(await cache.folders("/project")).toEqual(["/notes"]);
+    const later = now() + 61_000;
+    Date.now = () => later;
+    const result = cache.folders("/project");
+    expect(await Promise.race([result, new Promise(resolve => setTimeout(() => resolve("blocked"), 30))])).toEqual(["/notes"]);
+    expect(cache.read("/project").status).toBe("pending");
+  } finally {
+    complete?.(["/updated"]);
+    Date.now = now;
+    cache.close();
+  }
+});
+
+test("CPU-heavy discovery runs outside the event loop", async () => {
+  const root = await mkdtemp(join(tmpdir(), "kennel-linked-worker-"));
+  const controller = new AbortController();
+  const notes = join(root, "notes");
+  let ticks = 0;
+  const timer = setInterval(() => { ticks++; }, 20);
+  try {
+    await mkdir(notes);
+    const modulePath = join(root, "fixture.cjs");
+    await writeFile(modulePath, `exports.listConnectedProjects = folder => {
+      const end = Date.now() + 600; while (Date.now() < end) {}
+      return { selectedWorktree: folder, relations: [{ type: 'notes', source: folder, target: ${JSON.stringify(notes)} }] };
+    };`);
+    expect(await discoverLinkedFolders(root, controller.signal, modulePath)).toEqual([notes]);
+    expect(ticks).toBeGreaterThan(10);
+  } finally { clearInterval(timer); controller.abort(); await rm(root, { recursive: true, force: true }); }
+});

package/kernel/packages/api/test/media-endpoint.test.ts

@@ -0,0 +1,83 @@
+import { fetch } from "bun";
+import { afterEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createKennelApi } from "../src/server";
+
+const cleanup: (() => Promise<unknown>)[] = [];
+afterEach(async () => {
+  for (const fn of cleanup.splice(0).reverse()) await fn();
+});
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), "kennel-media-"));
+  cleanup.push(() => rm(root, { recursive: true, force: true }));
+  await mkdir(join(root, "output", "clips"), { recursive: true });
+  await writeFile(join(root, "note.md"), "# Note\n");
+  // A minimal but non-empty fake MP4 payload.
+  await writeFile(
+    join(root, "output", "clips", "clip.mp4"),
+    Buffer.from([0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70]),
+  );
+  await writeFile(join(root, "output", "clips", "sheet.jpg"), "jpeg-bytes");
+  await writeFile(join(root, "output", "clips", "page.html"), "<h1>hi</h1>");
+  const api = createKennelApi({ root });
+  cleanup.push(() => api.close());
+  const address = await api.listen(0);
+  if (!address || typeof address === "string")
+    throw new Error("Missing listener");
+  return { root, baseUrl: `http://127.0.0.1:${address.port}` };
+}
+
+const mediaUrl = (baseUrl: string, root: string, file: string) =>
+  `${baseUrl}/api/media?path=${encodeURIComponent(root)}&file=${encodeURIComponent(file)}`;
+
+test("media endpoint serves contained media files with typed headers", async () => {
+  const { root, baseUrl } = await fixture();
+  const response = await fetch(mediaUrl(baseUrl, root, "output/clips/clip.mp4"));
+  expect(response.status).toBe(200);
+  expect(response.headers.get("content-type")).toBe("video/mp4");
+  expect(response.headers.get("accept-ranges")).toBe("bytes");
+  expect(response.headers.get("x-content-type-options")).toBe("nosniff");
+  const body = await response.arrayBuffer();
+  expect(body.byteLength).toBe(8);
+});
+
+test("media endpoint answers range requests with 206 slices", async () => {
+  const { root, baseUrl } = await fixture();
+  const response = await fetch(mediaUrl(baseUrl, root, "output/clips/clip.mp4"), {
+    headers: { Range: "bytes=2-5" },
+  });
+  expect(response.status).toBe(206);
+  expect(response.headers.get("content-range")).toBe("bytes 2-5/8");
+  const slice = new Uint8Array(await response.arrayBuffer());
+  expect(slice).toEqual(new Uint8Array([0x00, 0x18, 0x66, 0x74]));
+});
+
+test("media endpoint revalidates with ETag", async () => {
+  const { root, baseUrl } = await fixture();
+  const url = mediaUrl(baseUrl, root, "output/clips/clip.mp4");
+  const first = await fetch(url);
+  const etag = first.headers.get("etag");
+  expect(etag).toBeTruthy();
+  const cached = await fetch(url, { headers: { "If-None-Match": etag! } });
+  expect(cached.status).toBe(304);
+});
+
+test("media endpoint rejects escaping, missing, and non-media files", async () => {
+  const { root, baseUrl } = await fixture();
+  expect(
+    (await fetch(mediaUrl(baseUrl, root, "../outside/clip.mp4"))).status,
+  ).toBe(404);
+  expect(
+    (await fetch(mediaUrl(baseUrl, root, "output/clips/missing.mp4"))).status,
+  ).toBe(404);
+  // Active content is never served as media.
+  expect(
+    (await fetch(mediaUrl(baseUrl, root, "output/clips/page.html"))).status,
+  ).toBe(404);
+  expect((await fetch(`${baseUrl}/api/media?path=${encodeURIComponent(root)}`)).status).toBe(
+    404,
+  );
+});

package/kernel/packages/api/test/partial-loading.test.ts

@@ -0,0 +1,43 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createKennelApi } from "../src/server";
+
+test("navigation and Calendar don't start linked discovery; Tasks render before it finishes and retry failure", async () => {
+  const root = await mkdtemp(join(tmpdir(), "kennel-partial-"));
+  await writeFile(join(root, "todo.json"), JSON.stringify({ id: "todo", title: "Local tasks", tasks: [{ id: "1", name: "Local task", done: false }] }));
+  let fail!: (error: Error) => void;
+  let calls = 0;
+  const api = createKennelApi({ root, linkedFolderLoader: async () => {
+    calls++;
+    if (calls === 1) return new Promise((_resolve, reject) => { fail = reject; });
+    return [];
+  } });
+  try {
+    const address = await api.listen(0);
+    if (!address || typeof address === "string") throw new Error("No server");
+    const base = `http://127.0.0.1:${address.port}`;
+    const get = async (url: string, retry = false) => {
+      const response = await fetch(base + url, { signal: AbortSignal.timeout(2000), headers: retry ? { "x-kennel-retry-linked": "1" } : {} });
+      expect(response.ok).toBe(true);
+      return response.json();
+    };
+    await get("/api/metadata?part=plugins");
+    await get("/api/plugins/calendar");
+    expect(calls).toBe(0);
+    const local = await get("/api/plugins/tasks");
+    expect(local.linkedStatus).toBe("pending");
+    expect(local.dataset.tasks.length).toBe(1);
+    expect((await get("/api/health")).viewer).toBe("kennel-core");
+    fail(new Error("Offline"));
+    await new Promise(resolve => setTimeout(resolve, 0));
+    const failed = await get("/api/plugins/tasks");
+    expect(failed.linkedStatus).toBe("error");
+    expect(failed.dataset.tasks.length).toBe(1);
+    await get("/api/plugins/tasks", true);
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect((await get("/api/plugins/tasks")).linkedStatus).toBe("ready");
+    expect(calls).toBe(2);
+  } finally { fail?.(new Error("Closing")); await api.close(); await rm(root, { recursive: true, force: true }); }
+});

package/kernel/packages/api/test/project-discovery.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { createProjectDiscovery } from "../src/server/project-discovery";
+
+test("project scans coalesce and keep running for remaining subscribers", async () => {
+  let finish!: (value: []) => void;
+  let workerSignal!: AbortSignal;
+  let calls = 0;
+  const scan = createProjectDiscovery(async (_folder, signal) => {
+    calls++; workerSignal = signal;
+    return new Promise<[]>(resolve => { finish = resolve; });
+  });
+  const first = new AbortController();
+  const second = new AbortController();
+  const a = scan.read("/one", first.signal).catch(error => error.message);
+  const b = scan.read("/one", second.signal);
+  await Promise.resolve();
+  first.abort();
+  expect(await a).toBe("Discovery cancelled");
+  expect(workerSignal.aborted).toBe(false);
+  expect(calls).toBe(1);
+  finish([]);
+  expect(await b).toEqual([]);
+  scan.close();
+});
+
+test("obsolete queued scans never start", async () => {
+  let finish!: (value: []) => void;
+  const calls: string[] = [];
+  const scan = createProjectDiscovery(async folder => {
+    calls.push(folder);
+    return new Promise<[]>(resolve => { finish = resolve; });
+  });
+  const a = scan.read("/active", new AbortController().signal);
+  const controller = new AbortController();
+  const b = scan.read("/obsolete", controller.signal).catch(error => error.message);
+  await Promise.resolve();
+  controller.abort();
+  expect(await b).toBe("Discovery cancelled");
+  finish([]);
+  await a;
+  await new Promise(resolve => setTimeout(resolve, 0));
+  expect(calls).toEqual(["/active"]);
+  scan.close();
+});

package/kernel/packages/api/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler",
+    "strict": true, "skipLibCheck": true, "noEmit": true,
+    "allowImportingTsExtensions": true, "esModuleInterop": true, "jsx": "react-jsx", "types": ["node"],
+    "paths": {
+      "~/*": ["${configDir}/../../packages/*/src"]
+    }
+  },
+  "include": ["src"]
+}

package/kernel/packages/api-client/README.md

@@ -0,0 +1,72 @@
+# Kennel client
+
+Local workspace package `kennel-client`. The web app maps `~/*` to package source
+entry points in TypeScript and Vite, so it uses:
+
+```ts
+import { api } from "~/api-client"
+
+const notes = await api.notes({ path: folder, notesScope: "local", signal })
+const workspace = await api.metadata(href, "workspace", { signal })
+await api.documentEdit({ folder, path, original, start, end, replacement })
+```
+
+The CLI build bundles this client into `cli/dist/core/api-client.js` for published
+Node installs. Its build-time declaration derives response types from generated
+OpenAPI; client typechecks verify that declaration matches the real factory.
+Vite config-time code imports the source by relative path because application
+aliases are not active while Vite loads its configuration.
+
+Other workspace consumers can depend on `"kennel-client": "workspace:*"` and
+import `createKennelClient` from `kennel-client`. Node callers supply `baseUrl`;
+tests can also inject `fetch`. The web singleton uses the current browser origin.
+The `@/*` app-source alias remains unchanged; `~/api-client` is a package shortcut,
+not an npm scope or a package.json import alias.
+
+## Contract pipeline
+
+1. Edit browser-safe Zod schemas and route definitions in
+   `packages/api/src/contracts/schemas.ts`. Public DTOs are inferred from them.
+2. Server handlers validate queries and core successful JSON responses. Existing
+   host/origin authorization stays ahead of mutation parsing. Document edits use
+   the shared body schema after authorization.
+3. Run `bun run --cwd packages/api-client generate`. This produces
+   `packages/api/openapi.json` and `src/generated.d.ts` using openapi-typescript.
+4. The shared client uses openapi-fetch with generated paths for HTTP requests,
+   and the same schemas for runtime response validation. Metadata selectors infer
+   specific response types; callers cannot assert an arbitrary `metadata<T>`.
+5. CI checks generated artifacts, client/core tests, and workspace typechecking.
+   Add operations here instead of adding fetch calls to screens.
+
+Generated files are checked in. Do not edit them manually. This is a **local source
+workspace package**, not a standalone published SDK: its schema imports refer to
+its sibling API package. A published SDK would need bundled schemas and JS output.
+
+## Ownership and compatibility
+
+- This package owns core HTTP actions, encoding, errors, response validation and
+  cancellation. React Query cache keys/hooks and presentation stay in web.
+- Web URL helpers remain for actual links; they do not make HTTP requests.
+- Old API client entry points and `apps/web/src/api/client.ts` are re-exports,
+  not alternative implementations.
+- Raw files and dynamically registered plugins have dedicated escape hatches;
+  plugin payloads are honestly `unknown`, not caller-asserted types.
+- ACP commands, session transcripts and SSE remain separate legacy protocols.
+  They are not represented by this core JSON OpenAPI document. The web lint rule
+  has an explicit four-file allowlist for the remaining session/ACP fetch calls.
+- Errors may still be structured JSON or plain text. `ApiClientError` preserves
+  status, message and structured code. No automatic retries for mutations.
+
+## Verification
+
+```sh
+bun run --cwd packages/api-client generate:check
+bun run --cwd packages/api-client typecheck
+bun test packages/api-client/test packages/api/test
+bun run --cwd apps/web typecheck
+# linked-notes test lives in https://github.com/raggle-ai/kennel-tests
+```
+
+The linked-notes test uses a real fixture server and the same client as consumers.
+Its subprocesses isolate Scout's process-global settings/cache. Browser tests
+mock the standard Fetch `Request` input, including its abort signal.

package/kernel/packages/api-client/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "kennel-client",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./errors": "./src/errors.ts",
+    "./generated": "./src/generated.d.ts"
+  },
+  "scripts": {
+    "generate": "bun scripts/generate.ts",
+    "generate:check": "bun scripts/generate.ts --check",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test test"
+  },
+  "dependencies": {
+    "openapi-fetch": "0.17.0",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/bun": "catalog:",
+    "openapi-typescript": "7.13.0",
+    "typescript": "catalog:"
+  }
+}

package/kernel/packages/api-client/scripts/generate.ts

@@ -0,0 +1,68 @@
+import { readFile, writeFile } from "node:fs/promises";
+import openapiTS, { astToString } from "openapi-typescript";
+import { z } from "zod";
+import { routes } from "../../api/src/contracts/schemas";
+
+const paths: Record<string, unknown> = {};
+const schema = (value: z.ZodType) => {
+  const { $schema, ...json } = z.toJSONSchema(value, {
+    target: "draft-2020-12",
+  });
+  return json;
+};
+for (const [operationId, route] of Object.entries(routes)) {
+  const query = schema(route.query);
+  paths[route.path] = {
+    [route.method]: {
+      operationId,
+      parameters: Object.entries(query.properties ?? {}).map(
+        ([name, value]) => ({
+          name,
+          in: "query",
+          required: query.required?.includes(name) ?? false,
+          schema: value,
+        }),
+      ),
+      ...("body" in route
+        ? {
+            requestBody: {
+              required: true,
+              content: { "application/json": { schema: schema(route.body) } },
+            },
+          }
+        : {}),
+      responses: {
+        ["response" in route ? "200" : "204"]: {
+          description: "Success",
+          ...("response" in route
+            ? {
+                content: {
+                  "application/json": { schema: schema(route.response) },
+                },
+              }
+            : {}),
+        },
+        default: { description: "Request rejected; JSON or plain-text error" },
+      },
+    },
+  };
+}
+const document = {
+  openapi: "3.1.0",
+  info: { title: "Kennel core API", version: "1.0.0" },
+  paths,
+};
+const json = JSON.stringify(document, null, 2) + "\n";
+const declarations = astToString(await openapiTS(json));
+for (const [path, content] of [
+  [new URL("../../api/openapi.json", import.meta.url), json],
+  [new URL("../src/generated.d.ts", import.meta.url), declarations],
+] as const) {
+  if (process.argv.includes("--check")) {
+    if ((await readFile(path, "utf8").catch(() => "")) !== content) {
+      throw new Error(
+        `Stale generated contract: ${path.pathname}. Run bun run --cwd packages/api-client generate`,
+      );
+    }
+  } else await writeFile(path, content);
+}

package/kernel/packages/api-client/src/errors.ts

@@ -0,0 +1,59 @@
+/**
+ * Error raised by the viewer API client when the server rejects a request.
+ * Carries the structured code/status from the endpoint when available so the
+ * UI can adapt (403 remote host actions, 409 stale edits, ...).
+ */
+type ErrorBody =
+  { error?: { code?: string; message?: string } | string } | undefined;
+
+export class ApiClientError extends Error {
+  readonly code?: string;
+  readonly status?: number;
+
+  constructor(
+    message: string,
+    options: { code?: string; status?: number } = {},
+  ) {
+    super(message);
+    this.name = "ApiClientError";
+    this.code = options.code;
+    this.status = options.status;
+  }
+}
+
+/**
+ * Turns a failed fetch Response into an ApiClientError. Server endpoints
+ * agree on `{ error: { code, message } }` JSON, but plain-text errors (older
+ * middleware, Vite plugin fallbacks) are preserved too. The body is read
+ * exactly once and parsed as JSON only when the content type suggests it.
+ */
+export async function expectedError(
+  response: Response,
+): Promise<ApiClientError> {
+  const body = await response.text().catch(() => "");
+  const structured = response.headers
+    .get("content-type")
+    ?.includes("application/json");
+  if (structured) {
+    try {
+      const value = JSON.parse(body) as ErrorBody;
+      const error = value?.error;
+      if (error && typeof error === "object" && error.message) {
+        return new ApiClientError(error.message, {
+          code: error.code,
+          status: response.status,
+        });
+      }
+      if (typeof error === "string" && error)
+        return new ApiClientError(error, { status: response.status });
+    } catch {
+      // Not JSON despite the header; fall through to the raw text.
+    }
+  }
+  return new ApiClientError(
+    body.trim() || `Request failed with status ${response.status}`,
+    {
+      status: response.status,
+    },
+  );
+}