@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/fake-policy-litellm.ts

@@ -0,0 +1,186 @@
+/**
+ * A fake of LiteLLM's `/policies` routes for tests — TEST ONLY. Skeleton and the rules every fake
+ * follows: fake-registry-base.ts. (The attachment routes are `fake-policy-attachment-litellm.ts`.)
+ *
+ * ★ MEASURED FROM THE LIVE 1.103.0 CONTAINER'S SOURCE (2026-09-30, `policy_endpoints.py` and
+ *   `policy_registry.py`, read, not called): a create makes version 1 AS PRODUCTION, and a second create
+ *   of the name is a 400; the version list is a `find_many` by name (an unknown name is an empty list,
+ *   200); a new version is a DRAFT cloned from production (404 when there is no production) with the
+ *   next version number; `PUT /policies/{id}` edits a DRAFT only (400 otherwise, 404 missing) and writes
+ *   only fields that are not null; `draft → published` and `published → production` (which demotes the
+ *   old production to `published`) are the only promotions, and `draft → production` is a 400;
+ *   `DELETE …/all-versions` answers 200 whether or not anything existed; the list merges in
+ *   config.yaml policies (`definition_location: "config"`).
+ * ⚠️ NOT MODELLED: `pipeline`, the in-memory registry, `is_latest` bookkeeping beyond what a test reads.
+ */
+import { FAKE_KEY, type FakeRecord, json, recordingFetch } from './fake-registry-base.ts';
+import type { Row } from './registry-support.ts';
+
+export interface FakePolicyLitellm extends FakeRecord {
+  /** Every stored version, exactly as the proxy holds it. */
+  readonly versions: () => readonly Row[];
+}
+
+export interface FakePolicyOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** Policies defined in config.yaml: they appear in `/policies/list` with `definition_location: config`. */
+  readonly configPolicies?: readonly string[];
+  /** A `PUT /policies/{id}` drops an empty list instead of writing it. */
+  readonly editIgnoresEmpty?: boolean;
+}
+
+export const policyRow = (fields: Row): Row => ({
+  condition: null,
+  description: null,
+  guardrails_add: [],
+  guardrails_remove: [],
+  inherit: null,
+  is_latest: true,
+  pipeline: null,
+  version_number: 1,
+  version_status: 'production',
+  ...fields,
+});
+
+export const startFakePolicyLitellm = (options: FakePolicyOptions = {}): FakePolicyLitellm => {
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  let issued = 0;
+  const nextId = () => `FAKE-policy-${String((issued += 1)).padStart(4, '0')}`;
+
+  const record = recordingFetch(options.masterKey ?? FAKE_KEY, ({ body, request, url }) => {
+    const versionsOf = /^\/policies\/name\/([^/]+)\/versions$/.exec(url.pathname);
+    const allOf = /^\/policies\/name\/([^/]+)\/all-versions$/.exec(url.pathname);
+    const statusOf = /^\/policies\/([^/]+)\/status$/.exec(url.pathname);
+    const byId = /^\/policies\/([^/]+)$/.exec(url.pathname);
+
+    if (versionsOf !== null && request.method === 'GET') {
+      const name = decodeURIComponent(versionsOf[1] ?? '');
+      const found = rows.filter((row) => row['policy_name'] === name);
+      return json(200, { policy_name: name, total_count: found.length, versions: found });
+    }
+    if (url.pathname === '/policies/list' && request.method === 'GET') {
+      const only = url.searchParams.get('version_status');
+      const db = rows.filter((row) => only === null || row['version_status'] === only);
+      const held = new Set(
+        rows
+          .filter((row) => row['version_status'] === 'production')
+          .map((row) => row['policy_name']),
+      );
+      const config = (options.configPolicies ?? [])
+        .filter((name) => !held.has(name))
+        .map((name) =>
+          policyRow({ definition_location: 'config', policy_id: name, policy_name: name }),
+        );
+      return json(200, { policies: [...db, ...config], total_count: db.length + config.length });
+    }
+    if (url.pathname === '/policies' && request.method === 'POST') {
+      if (
+        rows.some(
+          (row) => row['policy_name'] === body['policy_name'] && row['version_number'] === 1,
+        )
+      ) {
+        return json(400, {
+          detail: `Policy with name '${String(body['policy_name'])}' already exists`,
+        });
+      }
+      const created = policyRow({
+        condition: body['condition'] ?? null,
+        description: body['description'] ?? null,
+        guardrails_add: body['guardrails_add'] ?? [],
+        guardrails_remove: body['guardrails_remove'] ?? [],
+        inherit: body['inherit'] ?? null,
+        policy_id: nextId(),
+        policy_name: body['policy_name'],
+      });
+      rows = [...rows, created];
+      return json(200, created);
+    }
+    if (versionsOf !== null && request.method === 'POST') {
+      const name = decodeURIComponent(versionsOf[1] ?? '');
+      const source = rows.find(
+        (row) => row['policy_name'] === name && row['version_status'] === 'production',
+      );
+      if (source === undefined) {
+        return json(404, { detail: `No production version found for policy '${name}'` });
+      }
+      const latest = Math.max(
+        ...rows
+          .filter((row) => row['policy_name'] === name)
+          .map((row) => Number(row['version_number'])),
+      );
+      const draft = {
+        ...source,
+        is_latest: true,
+        parent_version_id: source['policy_id'],
+        policy_id: nextId(),
+        version_number: latest + 1,
+        version_status: 'draft',
+      };
+      rows = [
+        ...rows.map((row) => (row['policy_name'] === name ? { ...row, is_latest: false } : row)),
+        draft,
+      ];
+      return json(200, draft);
+    }
+    if (statusOf !== null && request.method === 'PUT') {
+      const id = decodeURIComponent(statusOf[1] ?? '');
+      const row = rows.find((each) => each['policy_id'] === id);
+      if (row === undefined) return json(404, { detail: `Policy with ID ${id} not found` });
+      const target = body['version_status'];
+      if (target === 'published' && row['version_status'] !== 'draft') {
+        return json(400, { detail: 'Only draft versions can be published.' });
+      }
+      if (target === 'production' && row['version_status'] !== 'published') {
+        return json(400, {
+          detail: 'Cannot promote draft directly to production. Publish the version first.',
+        });
+      }
+      if (target !== 'published' && target !== 'production')
+        return json(400, { detail: 'Invalid status' });
+      rows = rows.map((each) => {
+        if (each['policy_id'] === id) return { ...each, version_status: target };
+        return target === 'production' &&
+          each['policy_name'] === row['policy_name'] &&
+          each['version_status'] === 'production'
+          ? { ...each, version_status: 'published' }
+          : each;
+      });
+      return json(
+        200,
+        rows.find((each) => each['policy_id'] === id),
+      );
+    }
+    if (byId !== null && request.method === 'PUT') {
+      const id = decodeURIComponent(byId[1] ?? '');
+      const row = rows.find((each) => each['policy_id'] === id);
+      if (row === undefined) return json(404, { detail: `Policy with ID ${id} not found` });
+      if (row['version_status'] !== 'draft') {
+        return json(400, {
+          detail:
+            'Only draft versions can be updated. Publish or create a new version to change published/production.',
+        });
+      }
+      const patch = Object.fromEntries(
+        Object.entries(body).filter(
+          ([, value]) =>
+            value !== null &&
+            !(options.editIgnoresEmpty === true && Array.isArray(value) && value.length === 0),
+        ),
+      );
+      rows = rows.map((each) => (each['policy_id'] === id ? { ...each, ...patch } : each));
+      return json(
+        200,
+        rows.find((each) => each['policy_id'] === id),
+      );
+    }
+    if (allOf !== null && request.method === 'DELETE') {
+      const name = decodeURIComponent(allOf[1] ?? '');
+      rows = rows.filter((row) => row['policy_name'] !== name);
+      return json(200, { message: `All versions of policy '${name}' deleted successfully` });
+    }
+    return json(404, { detail: 'not found' });
+  });
+
+  return { ...record, versions: () => rows.map((row) => ({ ...row })) };
+};

package/src/litellm/fake-registry-base.ts

@@ -0,0 +1,69 @@
+/**
+ * The shared skeleton of the registry fakes (`fake-team-litellm.ts`, `fake-access-group-litellm.ts`,
+ * `fake-toolset-litellm.ts`, `fake-policy-litellm.ts`, `fake-tool-litellm.ts`) — TEST ONLY, never
+ * imported by `index.ts`.
+ *
+ * ★ Like `fake-litellm.ts` this is a `fetch` function handed to Effect's real `FetchHttpClient`
+ *   through its `Fetch` reference, so a test exercises distilled's REAL path assembly, JSON encoding
+ *   and status-to-error matching. Only the wire responses a scenario needs are written by each fake.
+ * ★ ONE FAKE PER ROUTE FAMILY, each small, and this file is the part they would otherwise repeat:
+ *   the bearer check, the request log, and the body log a test reads to see what was SENT.
+ * ⚠️ EVERY FAKE'S ANSWERS ARE ITS OWN CHOICE UNLESS ITS HEADER SAYS "MEASURED": shapes come from the
+ *   generated 1.103.0 schema and from reading the 1.103.0 source, never from a live proxy. A test that
+ *   leans on a choice says so.
+ * ⚠️ NEVER ANSWER 5xx. The SDK retries 5xx with backoff, which would cost a test tens of seconds for
+ *   nothing; a failing write is a 400/403/409 here.
+ * ★ `FAKE-*` VALUES ONLY.
+ */
+import type { Row } from './registry-support.ts';
+
+/** One request that reached a fake. */
+export interface FakeRequest {
+  readonly method: string;
+  readonly path: string;
+}
+
+/** What every registry fake exposes besides its own rows. */
+export interface FakeRecord {
+  readonly fetch: typeof globalThis.fetch;
+  readonly requests: () => readonly FakeRequest[];
+  /** The JSON bodies of every request that carried one, in order (`POST`/`PUT`/`PATCH`/`DELETE`). */
+  readonly bodies: () => readonly Row[];
+}
+
+export const FAKE_KEY = 'sk-test-master';
+
+export const json = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
+/** A success with no body, as `DELETE` answers 202/204 on several routes. */
+export const empty = (status: number): Response => new Response(null, { status });
+
+export interface Call {
+  readonly request: Request;
+  readonly url: URL;
+  /** The parsed JSON body, or `{}` when the request had none. */
+  readonly body: Row;
+}
+
+export const recordingFetch = (
+  masterKey: string,
+  route: (call: Call) => Response | Promise<Response>,
+): FakeRecord => {
+  const requests: FakeRequest[] = [];
+  const bodies: Row[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    requests.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    if (request.headers.get('authorization') !== `Bearer ${masterKey}`) {
+      return json(401, { detail: 'invalid api key' });
+    }
+    const text = request.method === 'GET' ? '' : await request.text();
+    const body = text.trim() === '' ? {} : (JSON.parse(text) as Row);
+    if (text.trim() !== '') bodies.push(body);
+    return route({ body, request, url });
+  }) as typeof globalThis.fetch;
+  return { bodies: () => [...bodies], fetch, requests: () => [...requests] };
+};

package/src/litellm/fake-stack.ts

@@ -13,9 +13,11 @@
  *   files, no file logger. Just the provider, an in-memory state store, and the stack's services.
  */
 import { credentials } from '@distilled.cloud/litellm/Credentials';
+import { Retry } from '@distilled.cloud/litellm/Retry';
 import * as Alchemy from 'alchemy';
 import { AdoptPolicy } from 'alchemy/AdoptPolicy';
 import { provideFreshArtifactStore } from 'alchemy/Artifacts';
+import { encodeState } from 'alchemy/State/StateEncoding';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
@@ -33,6 +35,11 @@ export type DeployOptions = { readonly adopt?: boolean };
 export interface FakeStack {
   /** Plan, then apply, `body`. Resolves to the plan; rejects with the apply's failure. */
   readonly deploy: (body: StackBody, options?: DeployOptions) => Promise<Planned>;
+  /**
+   * Everything the state store holds, as JSON, `Redacted` values REVEALED the way Alchemy persists
+   * them (`encodeState`). A test asserts a secret is nowhere in it.
+   */
+  readonly snapshot: () => string;
 }
 
 type Node = { readonly action: string };
@@ -66,8 +73,10 @@ export const fakeStack = (
   creds: { readonly apiKey: string; readonly baseUrl: string },
   fetchFn: typeof globalThis.fetch,
   name = 'PassThroughStack',
+  settings: { readonly noRetry?: boolean } = {},
 ): FakeStack => {
-  const state = Alchemy.inMemoryState();
+  const backing: Parameters<typeof Alchemy.inMemoryState>[0] = {};
+  const state = Alchemy.inMemoryState(backing);
   const providers = litellmProviders(credentials(creds));
   // ⚠️ THE CAST STAYS. `StackBody` is `Effect<unknown, unknown, unknown>` so a test can pass any
   //   declaration, and that channel is not a legal `Alchemy.Stack` body. The uncast construction
@@ -83,6 +92,11 @@ export const fakeStack = (
   ) => Effect.Effect<PlanView, unknown, never>;
   const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
 
+  // ★ `noRetry` IS FOR A TEST OF A TRANSIENT FAILURE: the SDK's default policy would sit out its
+  //   backoff before the failure the test wants to see propagates.
+  const retrying: <A, E, R>(io: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R> =
+    settings.noRetry === true ? Effect.provideService(Retry, { while: () => false }) : (io) => io;
+
   const deploy = (body: StackBody, options: DeployOptions = {}) =>
     Effect.gen(function* () {
       const compiled = yield* stack(name, { providers, state }, body);
@@ -94,6 +108,7 @@ export const fakeStack = (
     }).pipe(
       options.adopt === undefined ? (e) => e : Effect.provideService(AdoptPolicy, options.adopt),
       Effect.provideService(Alchemy.Stage, 'test'),
+      retrying,
       Effect.provide(FetchHttpClient.layer),
       Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
       Effect.scoped,
@@ -101,6 +116,7 @@ export const fakeStack = (
 
   return {
     deploy: (body, options) => Effect.runPromise(deploy(body, options) as Effect.Effect<Planned>),
+    snapshot: () => JSON.stringify(encodeState(backing)),
   };
 };
 

package/src/litellm/fake-team-litellm.ts

@@ -0,0 +1,229 @@
+/**
+ * A fake of LiteLLM's `/team/*` routes for tests — TEST ONLY. Skeleton and the rules every fake
+ * follows: fake-registry-base.ts.
+ *
+ * ★ MEASURED FROM THE LIVE 1.103.0 CONTAINER'S SOURCE (2026-09-30, `team_endpoints.py`,
+ *   `object_permission_utils.py`, read, not called): `/team/new` refuses a taken id (400) and ADDS THE
+ *   CALLER AS AN `admin` MEMBER (`_should_auto_add_team_creator`), which `autoAddsCreator` models;
+ *   `/team/update` is partial (`exclude_unset`) and merges `object_permission` BY TOP-LEVEL FIELD (a
+ *   field left out keeps its value, `[]` replaces it); `/team/info` answers a missing team 404 in the
+ *   `ProxyException` envelope; `member_add` and `member_update` refuse an `admin` role on a proxy
+ *   without a licence (400, `community`, the default); `/team/delete` 404s a missing team and DELETES THE
+ *   TEAM'S KEYS (`deletedKeys` records that); `/team/member_delete` is not modelled because nothing here
+ *   may call it, and any request to it is recorded so a test can assert none was made.
+ * ★ ALSO MEASURED: `/team/info` and `/team/delete` answer 404 for ANY exception on the lookup, database
+ *   errors included, which `infoLies` and `deleteLies` model (the team exists and the answer is 404).
+ * ⚠️ NOT MODELLED: budgets, metadata, the Enterprise fields, `access_group` mirroring into groups.
+ */
+import { FAKE_KEY, type FakeRecord, json, recordingFetch } from './fake-registry-base.ts';
+import type { Row } from './registry-support.ts';
+
+export interface FakeTeamLitellm extends FakeRecord {
+  /** Every stored team, exactly as the proxy holds it (`object_permission` included). */
+  readonly teams: () => readonly Row[];
+  /** Team ids whose keys a `/team/delete` removed, in order. */
+  readonly deletedKeys: () => readonly string[];
+}
+
+export interface FakeTeamOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** No licence: an `admin` role is a 400. Default `true`. */
+  readonly community?: boolean;
+  /** `/team/new` adds the caller as an admin member. Default `true` (measured). */
+  readonly autoAddsCreator?: boolean;
+  /** `/team/info` answers 404 whether or not the team exists (a swallowed database error). */
+  readonly infoLies?: boolean;
+  /** `/team/delete` answers 404 whether or not the team exists. */
+  readonly deleteLies?: boolean;
+  /** `mcp_tool_permissions` comes back as a JSON string, as the source says it can. */
+  readonly toolPermissionsAsString?: boolean;
+  /**
+   * `/team/info` also carries what a real one does and a resource must never copy: the team's KEYS
+   * (`FAKE-hashed-key`), its memberships, and metadata that can hold callback variables.
+   */
+  readonly leaky?: boolean;
+}
+
+export const teamRow = (fields: Row): Row => ({
+  access_group_ids: [],
+  blocked: false,
+  members_with_roles: [],
+  models: [],
+  object_permission: null,
+  ...fields,
+});
+
+const CALLER = 'default_user_id';
+
+const notFound = (id: string) =>
+  json(404, {
+    error: {
+      code: '404',
+      message: `Team not found, passed team id: ${id}.`,
+      param: 'None',
+      type: 'auth_error',
+    },
+  });
+
+/** `{**existing, **sent}`: the merge by top-level field `prepare_object_permission_upsert` does. */
+const mergePermission = (existing: unknown, sent: unknown): Row => ({
+  ...(existing as Row | null),
+  ...(sent as Row | null),
+});
+
+export const startFakeTeamLitellm = (options: FakeTeamOptions = {}): FakeTeamLitellm => {
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  const deletedKeys: string[] = [];
+  const community = options.community ?? true;
+
+  const info = (row: Row): Row => {
+    const permission = row['object_permission'] as Row | null;
+    const shown =
+      permission !== null &&
+      options.toolPermissionsAsString === true &&
+      permission['mcp_tool_permissions'] !== undefined
+        ? {
+            ...permission,
+            mcp_tool_permissions: JSON.stringify(permission['mcp_tool_permissions']),
+          }
+        : permission;
+    return {
+      keys: [],
+      team_id: row['team_id'],
+      team_info: { ...row, object_permission: shown },
+      team_memberships: [],
+    };
+  };
+
+  const record = recordingFetch(options.masterKey ?? FAKE_KEY, ({ body, request, url }) => {
+    if (url.pathname === '/team/info' && request.method === 'GET') {
+      const id = url.searchParams.get('team_id') ?? '';
+      const row = rows.find((each) => each['team_id'] === id);
+      return row === undefined || options.infoLies === true ? notFound(id) : json(200, info(row));
+    }
+    if (url.pathname === '/team/list' && request.method === 'GET') return json(200, rows);
+    if (url.pathname === '/team/new' && request.method === 'POST') {
+      const id = String(body['team_id']);
+      if (rows.some((row) => row['team_id'] === id)) {
+        return json(400, {
+          detail: { error: `Team id = ${id} already exists. Please use a different team id.` },
+        });
+      }
+      const members =
+        options.autoAddsCreator === false
+          ? []
+          : [{ role: 'admin', user_email: null, user_id: CALLER }];
+      const { object_permission: permission, ...rest } = body;
+      rows = [
+        ...rows,
+        teamRow({
+          ...rest,
+          members_with_roles: members,
+          object_permission: permission === undefined ? null : mergePermission(null, permission),
+        }),
+      ];
+      return json(200, rows.at(-1));
+    }
+    if (url.pathname === '/team/update' && request.method === 'POST') {
+      const at = rows.findIndex((row) => row['team_id'] === body['team_id']);
+      if (at === -1)
+        return json(404, {
+          detail: { error: `Team not found, passed team_id=${String(body['team_id'])}` },
+        });
+      const { object_permission: permission, team_id: _id, ...rest } = body;
+      rows = rows.map((row, i) =>
+        i === at
+          ? {
+              ...row,
+              ...rest,
+              ...(permission === undefined
+                ? {}
+                : { object_permission: mergePermission(row['object_permission'], permission) }),
+            }
+          : row,
+      );
+      return json(200, { data: rows[at], team_id: body['team_id'] });
+    }
+    if (url.pathname === '/team/member_add' && request.method === 'POST') {
+      const at = rows.findIndex((row) => row['team_id'] === body['team_id']);
+      if (at === -1) return json(404, { detail: { error: 'Team not found' } });
+      const wanted = (Array.isArray(body['member']) ? body['member'] : [body['member']]) as Row[];
+      if (community && wanted.some((member) => member['role'] === 'admin')) {
+        return json(400, {
+          detail: {
+            error:
+              'Assigning team admins is a premium feature. You must be a LiteLLM Enterprise user',
+          },
+        });
+      }
+      const roster = rows[at]?.['members_with_roles'] as Row[];
+      const fresh = wanted.filter(
+        (member) => !roster.some((each) => each['user_id'] === member['user_id']),
+      );
+      if (fresh.length === 0)
+        return json(400, { error: { message: 'All users are already in team.' } });
+      rows = rows.map((row, i) =>
+        i === at
+          ? {
+              ...row,
+              members_with_roles: [
+                ...roster,
+                ...fresh.map((member) => ({
+                  role: member['role'],
+                  user_email: null,
+                  user_id: member['user_id'],
+                })),
+              ],
+            }
+          : row,
+      );
+      return json(200, rows[at]);
+    }
+    if (url.pathname === '/team/member_update' && request.method === 'POST') {
+      const at = rows.findIndex((row) => row['team_id'] === body['team_id']);
+      if (community && body['role'] === 'admin') {
+        return json(
+          400,
+          'Assigning team admins is a premium feature. You must be a LiteLLM Enterprise user',
+        );
+      }
+      const roster = (rows[at]?.['members_with_roles'] as Row[] | undefined) ?? [];
+      if (at === -1 || !roster.some((each) => each['user_id'] === body['user_id'])) {
+        return json(404, {
+          detail: { error: `User ${String(body['user_id'])} is not a member of team` },
+        });
+      }
+      rows = rows.map((row, i) =>
+        i === at
+          ? {
+              ...row,
+              members_with_roles: roster.map((each) =>
+                each['user_id'] === body['user_id'] ? { ...each, role: body['role'] } : each,
+              ),
+            }
+          : row,
+      );
+      return json(200, { team_id: body['team_id'] });
+    }
+    if (url.pathname === '/team/delete' && request.method === 'POST') {
+      const ids = (body['team_ids'] as string[] | undefined) ?? [];
+      const missing = ids.find((id) => !rows.some((row) => row['team_id'] === id));
+      if (missing !== undefined || options.deleteLies === true) {
+        return json(404, {
+          detail: { error: `Team not found, passed team_id=${missing ?? ids[0] ?? ''}` },
+        });
+      }
+      deletedKeys.push(...ids);
+      rows = rows.filter((row) => !ids.includes(String(row['team_id'])));
+      return json(200, {});
+    }
+    return json(404, { detail: 'not found' });
+  });
+
+  return {
+    ...record,
+    deletedKeys: () => [...deletedKeys],
+    teams: () => rows.map((row) => ({ ...row })),
+  };
+};

package/src/litellm/fake-tool-litellm.ts

@@ -0,0 +1,88 @@
+/**
+ * A fake of LiteLLM's `/v1/tool/{tool_name}` and `/v1/tool/policy` routes for tests — TEST ONLY.
+ * Skeleton and the rules every fake follows: fake-registry-base.ts.
+ *
+ * ★ MEASURED FROM THE LIVE 1.103.0 CONTAINER'S SOURCE (2026-09-30, `tool_management_endpoints.py` and
+ *   `db/tool_registry_writer.py`, read, not called): the write is an UPSERT on `tool_name` (a new row
+ *   takes a sent field, else `untrusted`; an existing row takes only the fields sent); neither field
+ *   sent is a 400; a team or key id turns the write into an override of `blocked_tools`, which this
+ *   fake does not model and answers 400 to (nothing here sends one); the read of an unknown tool is a
+ *   404; there is NO delete route for a row. `getSwallowsErrors` models `db_get_tool` catching every
+ *   exception and answering `None`, which the route turns into a 404 for a tool that exists.
+ */
+import { FAKE_KEY, type FakeRecord, json, recordingFetch } from './fake-registry-base.ts';
+import type { Row } from './registry-support.ts';
+
+export interface FakeToolLitellm extends FakeRecord {
+  readonly tools: () => readonly Row[];
+}
+
+export interface FakeToolOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** The by-name `GET` answers 404 whatever exists (a swallowed database error). */
+  readonly getSwallowsErrors?: boolean;
+  /** `POST /v1/tool/policy` ignores an `output_policy` (a proxy that drops one field). */
+  readonly dropsOutputPolicy?: boolean;
+}
+
+export const toolRow = (fields: Row): Row => ({
+  call_count: 0,
+  input_policy: 'untrusted',
+  output_policy: 'untrusted',
+  ...fields,
+});
+
+export const startFakeToolLitellm = (options: FakeToolOptions = {}): FakeToolLitellm => {
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  let issued = 0;
+
+  const record = recordingFetch(options.masterKey ?? FAKE_KEY, ({ body, request, url }) => {
+    if (url.pathname === '/v1/tool/policy' && request.method === 'POST') {
+      if (body['team_id'] !== undefined || body['key_hash'] !== undefined) {
+        return json(400, { detail: 'overrides are not modelled by this fake' });
+      }
+      if (body['input_policy'] === undefined && body['output_policy'] === undefined) {
+        return json(400, {
+          detail: 'At least one of input_policy or output_policy must be provided',
+        });
+      }
+      const name = String(body['tool_name']);
+      const sent = Object.fromEntries(
+        Object.entries({
+          input_policy: body['input_policy'],
+          output_policy: body['output_policy'],
+        }).filter(
+          ([key, value]) =>
+            value !== undefined && !(options.dropsOutputPolicy === true && key === 'output_policy'),
+        ),
+      );
+      const at = rows.findIndex((row) => row['tool_name'] === name);
+      if (at === -1) {
+        issued += 1;
+        rows = [
+          ...rows,
+          toolRow({
+            tool_id: `FAKE-tool-${String(issued).padStart(4, '0')}`,
+            tool_name: name,
+            ...sent,
+          }),
+        ];
+      } else {
+        rows = rows.map((row, i) => (i === at ? { ...row, ...sent } : row));
+      }
+      return json(200, { tool_name: name, updated: true, ...sent });
+    }
+    const byName = /^\/v1\/tool\/(.+)$/.exec(url.pathname);
+    if (byName !== null && request.method === 'GET') {
+      const name = decodeURIComponent(byName[1] ?? '');
+      const found = rows.find((row) => row['tool_name'] === name);
+      return found === undefined || options.getSwallowsErrors === true
+        ? json(404, { detail: `Tool '${name}' not found` })
+        : json(200, found);
+    }
+    return json(404, { detail: 'not found' });
+  });
+
+  return { ...record, tools: () => rows.map((row) => ({ ...row })) };
+};