@homeflare/alchemy 0.23.0 → 0.25.0

package/src/litellm/client.ts

@@ -0,0 +1,195 @@
+/**
+ * The four LiteLLM proxy calls a `LiteLLM.PassThroughEndpoint` needs, and nothing else reaches
+ * LiteLLM's `/config/pass_through_endpoint` routes.
+ *
+ * ⛔ WRAPPED IN A PER-BASE-URL SEMAPHORE. LiteLLM stores every pass-through endpoint in ONE
+ *   `general_settings.pass_through_endpoints` list (pass_through_endpoints.py at tag v1.100.0),
+ *   so create/update/delete are each a read-modify-write of the WHOLE list through
+ *   `update_config_general_settings`. Two of this package's own calls racing each other — two
+ *   endpoints created in the same deploy — would each read the list, add their own row and write
+ *   it back, and the second write would silently drop the first row. One permit per proxy
+ *   serialises this package's own writes; it cannot serialise against the LiteLLM UI or a second
+ *   deploy process, which is why `reconcile` reads back after writing rather than trusting the
+ *   call that just returned (docs/litellm.md).
+ * ★ `Authorization: Bearer <key>` — LiteLLM's own client uses it (litellm/proxy/client/cli, and
+ *   every `/config/*` route decorator at the tag takes `user_api_key_dict = Depends(user_api_key_auth)`,
+ *   which accepts a bearer token). Every mutation additionally requires the caller be
+ *   PROXY_ADMIN (`update_config_general_settings`, proxy_server.py:16411 at the tag) — an
+ *   ordinary virtual key gets `LitellmUnauthorizedError`, not a clearer 403 body naming the role.
+ * ⛔ NO MESSAGE SNIFFING (S21). Every status this file maps becomes a typed tag; nothing here or
+ *   above it matches an error body's text. Deleting an id LiteLLM does not have answers 400
+ *   (measured against the tag's `pass_through_endpoint_delete` — the id is looked up in the list
+ *   and a miss raises `HTTPException(400)`, not 404) — but so does a genuinely-live row when the
+ *   caller isn't PROXY_ADMIN, or the DB is disconnected (`update_config_general_settings`,
+ *   proxy_server.py:16389-16416 at the tag): the SAME status, for a delete that did NOT happen.
+ *   `deletePassThroughEndpoint` tells them apart by re-listing (a GET, which needs no PROXY_ADMIN —
+ *   proxy_server.py:3245-3251) rather than by the 400's body text — see its own comment.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import * as Semaphore from 'effect/Semaphore';
+import { LitellmCredentials, type LitellmCredentialsError } from './credentials.ts';
+import type {
+  PassThroughEndpointResponse,
+  PassThroughGenericEndpoint,
+} from './generated/pass-through.ts';
+
+export type LitellmRequirements = HttpClient.HttpClient | LitellmCredentials;
+
+/**
+ * The `litellm:<METHOD> <path>` operations this package writes to and reads from.
+ *
+ * ★ `codegen/litellm.ts` scans this FILE's text for these exact literals to pick which of
+ *   LiteLLM 1.100.0's 696 paths to generate types from (codegen/litellm.ts header). Keep each one
+ *   a literal string on one line; the generator matches text, it does not evaluate the object.
+ */
+export const LITELLM_OPERATIONS = {
+  create: 'litellm:POST /config/pass_through_endpoint',
+  delete: 'litellm:DELETE /config/pass_through_endpoint',
+  list: 'litellm:GET /config/pass_through_endpoint',
+  update: 'litellm:POST /config/pass_through_endpoint/{endpoint_id}',
+} as const;
+
+export class LitellmUnauthorizedError extends Data.TaggedError('LitellmUnauthorizedError')<{
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+}> {}
+export class LitellmBadRequestError extends Data.TaggedError('LitellmBadRequestError')<{
+  readonly method: string;
+  readonly path: string;
+  readonly detail: string;
+}> {}
+export class LitellmHttpError extends Data.TaggedError('LitellmHttpError')<{
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+  readonly detail: string;
+}> {}
+export class LitellmTransportError extends Data.TaggedError('LitellmTransportError')<{
+  readonly method: string;
+  readonly path: string;
+  readonly cause: string;
+}> {}
+
+export type LitellmError =
+  | LitellmUnauthorizedError
+  | LitellmBadRequestError
+  | LitellmHttpError
+  | LitellmTransportError
+  | LitellmCredentialsError;
+
+const semaphores = new Map<string, Semaphore.Semaphore>();
+
+/** One semaphore per base URL, created on first use. Never `Hash.structure` (S18) — a plain Map key. */
+const semaphoreFor = (baseUrl: string): Effect.Effect<Semaphore.Semaphore> =>
+  Effect.sync(() => {
+    const existing = semaphores.get(baseUrl);
+    if (existing !== undefined) return existing;
+    const created = Semaphore.makeUnsafe(1);
+    semaphores.set(baseUrl, created);
+    return created;
+  });
+
+const call = <T>(method: 'GET' | 'POST' | 'DELETE', path: string, body?: unknown) =>
+  Effect.gen(function* () {
+    const creds = yield* yield* LitellmCredentials;
+    const client = yield* HttpClient.HttpClient;
+    const url = `${creds.baseUrl}${path}`;
+    const request = HttpClientRequest.make(method)(url).pipe(
+      HttpClientRequest.setHeaders({
+        Accept: 'application/json',
+        Authorization: `Bearer ${creds.apiKey}`,
+      }),
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    const response = yield* client
+      .execute(request)
+      .pipe(
+        Effect.mapError(
+          (cause) => new LitellmTransportError({ cause: String(cause), method, path }),
+        ),
+      );
+    const text = yield* response.text.pipe(
+      Effect.mapError((cause) => new LitellmTransportError({ cause: String(cause), method, path })),
+    );
+    if (response.status === 401 || response.status === 403) {
+      return yield* Effect.fail(
+        new LitellmUnauthorizedError({ method, path, status: response.status }),
+      );
+    }
+    if (response.status === 400) {
+      return yield* Effect.fail(
+        new LitellmBadRequestError({ detail: text.slice(0, 300), method, path }),
+      );
+    }
+    if (response.status < 200 || response.status >= 300) {
+      return yield* Effect.fail(
+        new LitellmHttpError({ detail: text.slice(0, 300), method, path, status: response.status }),
+      );
+    }
+    return (text === '' ? undefined : JSON.parse(text)) as T;
+  });
+
+/** GET /config/pass_through_endpoint — every row, config-file and DB alike. Not under the semaphore: reads don't race the field. */
+export const listPassThroughEndpoints = (): Effect.Effect<
+  readonly PassThroughGenericEndpoint[],
+  LitellmError,
+  LitellmRequirements
+> =>
+  call<PassThroughEndpointResponse>('GET', '/config/pass_through_endpoint').pipe(
+    Effect.map((body) => body.endpoints),
+  );
+
+const mutate = <T>(io: Effect.Effect<T, LitellmError, LitellmRequirements>) =>
+  Effect.gen(function* () {
+    const creds = yield* yield* LitellmCredentials;
+    const semaphore = yield* semaphoreFor(creds.baseUrl);
+    return yield* semaphore.withPermits(1)(io);
+  });
+
+/** POST /config/pass_through_endpoint. `body` carries `id` — see pass-through-endpoint.ts. */
+export const createPassThroughEndpoint = (
+  body: PassThroughGenericEndpoint,
+): Effect.Effect<void, LitellmError, LitellmRequirements> =>
+  mutate(call('POST', '/config/pass_through_endpoint', body));
+
+/** POST /config/pass_through_endpoint/{endpoint_id}. Merges with `exclude_none` — see pass-through-form.ts. */
+export const updatePassThroughEndpoint = (
+  endpointId: string,
+  body: Partial<PassThroughGenericEndpoint>,
+): Effect.Effect<void, LitellmError, LitellmRequirements> =>
+  mutate(call('POST', `/config/pass_through_endpoint/${encodeURIComponent(endpointId)}`, body));
+
+/**
+ * DELETE /config/pass_through_endpoint?endpoint_id=… — idempotent BY THIS FUNCTION, not by the
+ * vendor. ⚠️ Measured at v1.100.0: deleting an id the list does not have raises `HTTPException(400)`
+ * from `pass_through_endpoint_delete` — but the SAME route also 400s `not_allowed_access` for a
+ * non-PROXY_ADMIN caller or a disconnected DB (`update_config_general_settings`,
+ * proxy_server.py:16389-16416), on a row that never got deleted. A 400 alone cannot tell the two
+ * apart, so THIS FUNCTION DOESN'T GUESS FROM THE STATUS ALONE: on 400 it re-lists (a GET — no
+ * PROXY_ADMIN required, proxy_server.py:3245-3251) and only treats the delete as already-done if
+ * `endpointId` is genuinely absent; otherwise the delete failed and this re-fails with the ORIGINAL
+ * error, not a message match (S21 — a status-and-a-real-read decision, never body text).
+ */
+export const deletePassThroughEndpoint = (
+  endpointId: string,
+): Effect.Effect<void, LitellmError, LitellmRequirements> =>
+  mutate(
+    call(
+      'DELETE',
+      `/config/pass_through_endpoint?endpoint_id=${encodeURIComponent(endpointId)}`,
+    ).pipe(
+      Effect.catchTag('LitellmBadRequestError', (original) =>
+        Effect.gen(function* () {
+          const rows = yield* listPassThroughEndpoints();
+          if (rows.some((row) => row.id === endpointId)) return yield* Effect.fail(original);
+        }),
+      ),
+      Effect.asVoid,
+    ),
+  );

package/src/litellm/credentials.ts

@@ -0,0 +1,73 @@
+/**
+ * The lazy Auth service every LiteLLM call reads from, and nothing else reads the environment.
+ *
+ * ★ LITELLM'S OWN VARIABLE NAMES, NOT A HOUSE CHOICE. `LITELLM_PROXY_URL` and
+ *   `LITELLM_PROXY_API_KEY` are what LiteLLM's own CLI client reads
+ *   (litellm/proxy/client/cli/main.py:70,78 at tag v1.100.0) — using the vendor's own names means
+ *   a consumer who already has a `.env` for the `litellm` CLI needs nothing new for this package.
+ * ⛔ NO DEFAULT URL. A published package that fell back to a loopback address would let a
+ *   consumer who forgot the variable watch every call fail against a proxy that is not theirs,
+ *   instead of being told which variable is missing (S24/S25 — the house rule, not a vendor one).
+ * ⛔ THE KEY IS NEVER A PROP. Alchemy persists attributes unencrypted (S25); the master key that
+ *   `update_config_general_settings` requires (PROXY_ADMIN only, proxy_server.py:16411 at the
+ *   tag) is read fresh from the environment on every call, never stored in state.
+ * ★ LAZY: the service's VALUE is an `Effect` that resolves the credential, not the credential
+ *   itself — so a layer built once still reads the environment inside each operation
+ *   (`yield* yield* LitellmCredentials`), the idiom `alchemy/Auth`'s custom-auth-provider guide
+ *   describes for a credential a layer must not capture at build time.
+ */
+import * as Context from 'effect/Context';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+export const LITELLM_PROXY_URL_ENV = 'LITELLM_PROXY_URL';
+export const LITELLM_PROXY_API_KEY_ENV = 'LITELLM_PROXY_API_KEY';
+
+export interface LitellmCreds {
+  /** Trailing slash stripped. No default — see the header. */
+  readonly baseUrl: string;
+  /** LiteLLM's master (or a PROXY_ADMIN) key. Never logged, never an attribute. */
+  readonly apiKey: string;
+}
+
+export class LitellmCredentialsError extends Data.TaggedError('LitellmCredentialsError')<{
+  readonly message: string;
+}> {}
+
+const missing = (name: string): LitellmCredentialsError =>
+  new LitellmCredentialsError({
+    message:
+      `${name} is not set. Export it — the same variable LiteLLM's own \`litellm\` CLI ` +
+      'reads — before running a stack that declares a LiteLLM.PassThroughEndpoint.',
+  });
+
+/** Read at call time. Exported so a test can call it directly against `process.env`. */
+export const resolveCreds: Effect.Effect<LitellmCreds, LitellmCredentialsError> = Effect.gen(
+  function* () {
+    const rawUrl = process.env[LITELLM_PROXY_URL_ENV];
+    if (rawUrl === undefined || rawUrl.trim() === '')
+      return yield* Effect.fail(missing(LITELLM_PROXY_URL_ENV));
+    const rawKey = process.env[LITELLM_PROXY_API_KEY_ENV];
+    if (rawKey === undefined || rawKey.trim() === '') {
+      return yield* Effect.fail(missing(LITELLM_PROXY_API_KEY_ENV));
+    }
+    return { baseUrl: rawUrl.trim().replace(/\/$/, ''), apiKey: rawKey.trim() };
+  },
+);
+
+/** The Effect service a LiteLLM operation reads: `yield* yield* LitellmCredentials`. */
+export class LitellmCredentials extends Context.Service<
+  LitellmCredentials,
+  Effect.Effect<LitellmCreds, LitellmCredentialsError>
+>()('homeflare/litellm/Credentials') {}
+
+/** The default layer: resolves from the environment, fresh, on every `yield*`. */
+export const litellmCredentialsLayer: Layer.Layer<LitellmCredentials> = Layer.succeed(
+  LitellmCredentials,
+  resolveCreds,
+);
+
+/** For a test: a fixed credential, never touching the environment. */
+export const litellmCredentialsLayerFor = (creds: LitellmCreds): Layer.Layer<LitellmCredentials> =>
+  Layer.succeed(LitellmCredentials, Effect.succeed(creds));

package/src/litellm/fake-litellm.ts

@@ -0,0 +1,114 @@
+/**
+ * A loopback `Bun.serve` fake of LiteLLM's `/config/pass_through_endpoint` routes — TEST ONLY,
+ * never imported by `index.ts` (the netbox/proxmox house convention for test-only helpers).
+ *
+ * ★ MODELS THE WHOLE-FIELD READ-MODIFY-WRITE ON PURPOSE. `general_settings.pass_through_endpoints`
+ *   is ONE field (client.ts's header), so every mutation here reads the CURRENT row list, waits
+ *   (so two concurrent requests can interleave), then writes back what it captured — not what is
+ *   there by the time it writes. Two `create` calls that race lose one row, exactly like the
+ *   vendor field would without the client's per-base-URL semaphore serialising them.
+ * ⚠️ WHAT THIS FAKE DOES NOT MODEL: PROXY_ADMIN vs. a lesser role for most routes (any correct
+ *   bearer token is accepted); and update-of-a-missing-id, which is not measured at the tag — this
+ *   fake 400s it, the same status a missing delete gets, as a documented TEST SIMPLIFICATION, not a
+ *   vendor fact (docs/litellm.md says so too). `forbidDelete` is the one exception: it models the
+ *   real asymmetry client.ts's header describes — `DELETE` routes through
+ *   `update_config_general_settings`, which 400s `not_allowed_access` for a non-PROXY_ADMIN caller
+ *   (or a disconnected DB) on a row that is genuinely still live, the SAME status a missing-id
+ *   delete gets (proxy_server.py:16389-16416 at v1.100.0).
+ */
+import type { PassThroughGenericEndpoint } from './generated/pass-through.ts';
+
+export interface FakeRequest {
+  readonly method: string;
+  readonly path: string;
+}
+
+export interface FakeLitellm {
+  readonly url: string;
+  readonly rows: () => readonly PassThroughGenericEndpoint[];
+  readonly requests: () => readonly FakeRequest[];
+  readonly stop: () => void;
+}
+
+const RACE_WINDOW_MS = 15;
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export const startFakeLitellm = (options?: {
+  readonly masterKey?: string;
+  readonly seed?: readonly PassThroughGenericEndpoint[];
+  /** Every `DELETE` 400s `not_allowed_access`, whether or not the row exists — see the file header. */
+  readonly forbidDelete?: boolean;
+}): FakeLitellm => {
+  const masterKey = options?.masterKey ?? 'sk-test-master';
+  const forbidDelete = options?.forbidDelete ?? false;
+  let rows: PassThroughGenericEndpoint[] = [...(options?.seed ?? [])];
+  const requests: FakeRequest[] = [];
+
+  const json = (status: number, body: unknown) =>
+    new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
+  const server = Bun.serve({
+    port: 0,
+    fetch: async (req) => {
+      const url = new URL(req.url);
+      requests.push({ method: req.method, path: url.pathname });
+      const auth = req.headers.get('authorization');
+      if (auth !== `Bearer ${masterKey}`) return json(401, { detail: 'invalid api key' });
+      if (
+        url.pathname !== '/config/pass_through_endpoint' &&
+        !url.pathname.startsWith('/config/pass_through_endpoint/')
+      ) {
+        return json(404, { detail: 'not found' });
+      }
+
+      if (req.method === 'GET') {
+        const endpointId = url.searchParams.get('endpoint_id');
+        const filtered = endpointId === null ? rows : rows.filter((row) => row.id === endpointId);
+        return json(200, { endpoints: filtered });
+      }
+
+      if (req.method === 'POST' && url.pathname === '/config/pass_through_endpoint') {
+        const body = (await req.json()) as PassThroughGenericEndpoint;
+        const before = rows; // ★ captured before the window — the race the semaphore prevents
+        await sleep(RACE_WINDOW_MS);
+        rows = [...before, { ...body, is_from_config: false }];
+        return json(200, {});
+      }
+
+      if (req.method === 'POST' && url.pathname.startsWith('/config/pass_through_endpoint/')) {
+        const id = decodeURIComponent(url.pathname.slice('/config/pass_through_endpoint/'.length));
+        const patch = (await req.json()) as Partial<PassThroughGenericEndpoint>;
+        const before = rows;
+        await sleep(RACE_WINDOW_MS);
+        const index = before.findIndex((row) => row.id === id);
+        if (index === -1) return json(400, { detail: `No pass-through endpoint with id=${id}` });
+        // ⚠️ `exclude_none`-shaped: only keys the patch actually carries are merged, matching
+        //   client.ts's `updateBody` never sending an unset/null field (pass-through-form.ts).
+        const merged = { ...before[index], ...patch };
+        rows = before.map((row, i) => (i === index ? (merged as PassThroughGenericEndpoint) : row));
+        return json(200, {});
+      }
+
+      if (req.method === 'DELETE' && url.pathname === '/config/pass_through_endpoint') {
+        const id = url.searchParams.get('endpoint_id');
+        if (forbidDelete) return json(400, { error: 'not_allowed_access' });
+        const before = rows;
+        await sleep(RACE_WINDOW_MS);
+        if (!before.some((row) => row.id === id)) {
+          return json(400, { detail: `No pass-through endpoint with id=${String(id)}` });
+        }
+        rows = before.filter((row) => row.id !== id);
+        return json(200, { endpoints: rows });
+      }
+
+      return json(405, { detail: `unhandled ${req.method} ${url.pathname}` });
+    },
+  });
+
+  return {
+    requests: () => [...requests],
+    rows: () => [...rows],
+    stop: () => server.stop(true),
+    url: server.url.toString().replace(/\/$/, ''),
+  };
+};

package/src/litellm/fake-stack.ts

@@ -0,0 +1,100 @@
+/**
+ * Alchemy's own Plan and Apply, run in-process over an in-memory state store, so a test can deploy a
+ * `LiteLLM.PassThroughEndpoint` declaration, change it, deploy again, and see what the ENGINE did
+ * with the provider's answers: which action it planned, and which calls reached the fake proxy.
+ *
+ * ★ WHY THE ENGINE AND NOT THE HANDLERS ALONE (openbao/fake-stack.ts's own reasoning, copied here
+ *   because a `diff` answer proves nothing by itself). `Apply.ts` mints a FRESH `instanceId` for a
+ *   create-first `replace` and calls `reconcile` with `output: undefined, olds: undefined` — a call
+ *   shape `pass-through-endpoint.test.ts`'s handler-only tests never produce (see the file's own
+ *   test that reuses the OLD instanceId and output, which is why it passed while the engine path
+ *   was broken). This harness drives the real `Plan.make`/`apply` instead of restating the claim.
+ * ★ NOT alchemy/Test/Bun — same reasoning as openbao/fake-stack.ts: no CLI profile/credentials
+ *   files, no file logger. Just the provider, an in-memory state store, and the stack's services.
+ */
+import * as Alchemy from 'alchemy';
+import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import { provideFreshArtifactStore } from 'alchemy/Artifacts';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { type LitellmCreds, litellmCredentialsLayerFor } from './credentials.ts';
+import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
+
+/** The planned action for each resource, deletions included, keyed by FQN. */
+export type Planned = Readonly<Record<string, string>>;
+
+/** A stack body: resource declarations, as an `alchemy.run.ts` would write them. */
+export type StackBody = Effect.Effect<unknown, unknown, unknown>;
+
+/** What the CLI would set for one deploy: `adopt` is `--adopt` (the AdoptPolicy service). */
+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>;
+}
+
+type Node = { readonly action: string };
+type PlanView = {
+  readonly resources: Readonly<Record<string, Node>>;
+  readonly deletions: Readonly<Record<string, Node | undefined>>;
+};
+
+const actionsOf = (plan: PlanView): Planned => {
+  const out: Record<string, string> = {};
+  for (const [fqn, node] of Object.entries(plan.resources)) out[fqn] = node.action;
+  for (const [fqn, node] of Object.entries(plan.deletions)) {
+    if (node !== undefined) out[fqn] = node.action;
+  }
+  return out;
+};
+
+/**
+ * ⚠️ CREDENTIALS/HTTPCLIENT ARE PROVIDED AROUND `deploy`, NOT BAKED INTO THE PROVIDER LAYER.
+ *   `Provider.effect`'s own construction effect is `Effect.succeed(...)` (pass-through-endpoint.ts)
+ *   — it never actually reads `LitellmCredentials`/`HttpClient`; only the HANDLERS it returns do,
+ *   and those run later, whenever `Apply.ts` calls `provider.reconcile`/`read`/`delete`. Effect
+ *   resolves a `yield*`'s service from whatever ambient context wraps the CALL SITE, so the layers
+ *   those handlers need must wrap the whole plan+apply pipeline below, exactly where openbao's
+ *   fake-stack.ts wraps `BaoEnv` around its own `deploy`.
+ */
+export const fakeStack = (creds: LitellmCreds, name = 'PassThroughStack'): FakeStack => {
+  const state = Alchemy.inMemoryState();
+  const providers = LiteLLMPassThroughEndpointProvider();
+  const stack = Alchemy.Stack as unknown as (
+    stackName: string,
+    options: { providers: typeof providers; state: typeof state },
+    body: StackBody,
+  ) => Effect.Effect<{ readonly services: never }, unknown, never>;
+  const plan = Alchemy.Plan.make as unknown as (
+    compiled: unknown,
+  ) => Effect.Effect<PlanView, unknown, never>;
+  const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+
+  const deploy = (body: StackBody, options: DeployOptions = {}) =>
+    Effect.gen(function* () {
+      const compiled = yield* stack(name, { providers, state }, body);
+      return yield* Effect.gen(function* () {
+        const planned = yield* plan(compiled);
+        yield* apply(planned);
+        return actionsOf(planned);
+      }).pipe(provideFreshArtifactStore, Effect.provide(Layer.succeedContext(compiled.services)));
+    }).pipe(
+      options.adopt === undefined ? (e) => e : Effect.provideService(AdoptPolicy, options.adopt),
+      Effect.provideService(Alchemy.Stage, 'test'),
+      Effect.provide(litellmCredentialsLayerFor(creds)),
+      Effect.provide(FetchHttpClient.layer),
+      Effect.scoped,
+    );
+
+  return {
+    deploy: (body, options) => Effect.runPromise(deploy(body, options) as Effect.Effect<Planned>),
+  };
+};
+
+/** Every call that changed something, as `METHOD path`, in order. */
+export const writesOf = (
+  requests: readonly { readonly method: string; readonly path: string }[],
+): string[] =>
+  requests.filter((each) => each.method !== 'GET').map((each) => `${each.method} ${each.path}`);

package/src/litellm/generated/pass-through.ts

@@ -0,0 +1,73 @@
+/**
+ * Generated from LiteLLM 1.100.0's OpenAPI document -- DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/litellm.ts    (`--check` compares without writing)
+ * Manifest entry: `litellm-openapi` -- LiteLLM Proxy (app.openapi()) 1.100.0
+ *   sha256 1b3e4d23da6aea92..., read from codegen/manifest.json's own note on how this document
+ *   was produced (the vendor's own generator, cross-checked byte-identically — not a live read).
+ *
+ * Covers the 4 pass-through operations this package writes to:
+ *   litellm:DELETE /config/pass_through_endpoint
+ *   litellm:GET /config/pass_through_endpoint
+ *   litellm:POST /config/pass_through_endpoint
+ *   litellm:POST /config/pass_through_endpoint/{endpoint_id}
+ *
+ * Does NOT cover the other 692 paths LiteLLM 1.100.0 publishes — this generator is
+ * consumer-driven (codegen/litellm.ts), not exhaustive. See codegen/README.md.
+ */
+
+export interface PassThroughEndpointResponse {
+  readonly endpoints: readonly PassThroughGenericEndpoint[];
+}
+
+export interface PassThroughGenericEndpoint {
+  /**
+   * Whether authentication is required for the pass-through endpoint. Defaults to True so a pass-through silently created without an explicit value still requires a valid LiteLLM API key — set to False only if the endpoint is meant to be a public forwarder (e.g. an unauthenticated webhook target).
+   * @default true
+   */
+  readonly auth?: boolean;
+  /**
+   * The USD cost per request to the target endpoint. This is used to calculate the cost of the request to the target endpoint.
+   * @default 0
+   */
+  readonly cost_per_request?: number;
+  /**
+   * Key-value pairs of default query parameters to be sent with every request to this endpoint. These can be overridden by client-provided query parameters. For example: {'key': 'default_value', 'api_version': '2023-01'}
+   * @default {}
+   */
+  readonly default_query_params?: Record<string, unknown>;
+  /** Guardrails configuration for this passthrough endpoint. Dict keys are guardrail names, values are optional settings for field targeting. When set, all org/team/key level guardrails will also execute. Defaults to None (no guardrails execute). */
+  readonly guardrails?: Record<string, PassThroughGuardrailSettings | null> | null;
+  /**
+   * Key-value pairs of headers to be forwarded with the request. You can set any key value pair here and it will be forwarded to your target endpoint
+   * @default {}
+   */
+  readonly headers?: Record<string, unknown>;
+  /** Optional unique identifier for the pass-through endpoint. If not provided, endpoints will be identified by path for backwards compatibility. */
+  readonly id?: string | null;
+  /**
+   * If True, requests to subpaths of the path will be forwarded to the target endpoint. For example, if the path is /bria and include_subpath is True, requests to /bria/v1/text-to-image/base/2.3 will be forwarded to the target endpoint.
+   * @default false
+   */
+  readonly include_subpath?: boolean;
+  /**
+   * True if this endpoint is defined in the config file, False if from DB. Config-defined endpoints cannot be edited via the UI.
+   * @default false
+   */
+  readonly is_from_config?: boolean;
+  /** List of HTTP methods this endpoint handles (e.g., ['GET', 'POST']). If None or empty, all methods (GET, POST, PUT, DELETE, PATCH) are supported for backward compatibility. This allows the same path to have different targets for different HTTP methods. */
+  readonly methods?: readonly string[] | null;
+  /** The route to be added to the LiteLLM Proxy Server. */
+  readonly path: string;
+  /** The URL to which requests for this path should be forwarded. */
+  readonly target: string;
+  /** Upstream request timeout in seconds for this pass-through endpoint. If unset, uses general_settings.pass_through_request_timeout (default 600). */
+  readonly timeout?: number | null;
+}
+
+export interface PassThroughGuardrailSettings {
+  /** JSONPath expressions for input field targeting (pre_call). Examples: 'query', 'documents[*].text', 'messages[*].content'. If not specified, guardrail runs on entire request payload. */
+  readonly request_fields?: readonly string[] | null;
+  /** JSONPath expressions for output field targeting (post_call). Examples: 'results[*].text', 'output'. If not specified, guardrail runs on entire response payload. */
+  readonly response_fields?: readonly string[] | null;
+}

package/src/litellm/index.ts

@@ -0,0 +1,42 @@
+/**
+ * LiteLLM providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory — `fake-litellm.ts`
+ *   and the internals `pass-through-form.ts`/`client.ts` need but a consumer should not depend on
+ *   directly are not re-exported here (netbox/index.ts's own rule).
+ */
+export {
+  LITELLM_PROXY_API_KEY_ENV,
+  LITELLM_PROXY_URL_ENV,
+  LitellmCredentials,
+  type LitellmCreds,
+  LitellmCredentialsError,
+  litellmCredentialsLayer,
+  litellmCredentialsLayerFor,
+} from './credentials.ts';
+export {
+  LITELLM_OPERATIONS,
+  LitellmBadRequestError,
+  type LitellmError,
+  LitellmHttpError,
+  type LitellmRequirements,
+  LitellmTransportError,
+  LitellmUnauthorizedError,
+} from './client.ts';
+export type {
+  PassThroughEndpointResponse,
+  PassThroughGenericEndpoint,
+  PassThroughGuardrailSettings,
+} from './generated/pass-through.ts';
+export {
+  LiteLLMPassThroughEndpoint,
+  LiteLLMPassThroughEndpointProvider,
+  LitellmConfigPathConflictError,
+  LitellmLiteralSecretHeaderError,
+  LitellmUnaddressableRowError,
+  isLiteLLMPassThroughEndpoint,
+  type PassThroughEndpointAttributes,
+  type PassThroughEndpointError,
+  type PassThroughEndpointProps,
+} from './pass-through-endpoint.ts';
+export { litellmProviders } from './providers.ts';

package/src/litellm/pass-through-endpoint-delete-swallow.test.ts

@@ -0,0 +1,66 @@
+/**
+ * `deletePassThroughEndpoint` treats ANY HTTP 400 as "already deleted" — but the vendor's real
+ * `DELETE /config/pass_through_endpoint` route also 400s `not_allowed_access` for a non-PROXY_ADMIN
+ * caller (or a disconnected DB), on a row that is genuinely still live: `update_config_general_settings`
+ * (proxy_server.py:16389-16416 at v1.100.0), the SAME status a missing-id delete gets. Before this
+ * file's fix, `client.ts` swallowed that too, silently reporting success while the row stayed live.
+ *
+ * ⛔ NO MESSAGE SNIFFING (S21): the fix cannot tell the two 400 reasons apart by body text either —
+ *   `fake-litellm.ts`'s `forbidDelete` deliberately sends the SAME status the vendor does. It tells
+ *   them apart the way `reconcile` already does elsewhere in this file (client.ts's own header:
+ *   "read back after writing rather than trusting the call that just returned"): re-list (a GET,
+ *   which needs no PROXY_ADMIN — pass_through_endpoints.py:3245-3251) and treat the 400 as
+ *   "already gone" only if the row is actually absent.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import {
+  type LitellmRequirements,
+  deletePassThroughEndpoint,
+  listPassThroughEndpoints,
+} from './client.ts';
+import { litellmCredentialsLayerFor } from './credentials.ts';
+import { startFakeLitellm } from './fake-litellm.ts';
+
+const MASTER_KEY = 'sk-test-master';
+const PROPS = {
+  auth: true,
+  id: 'live-1',
+  is_from_config: false,
+  path: '/bria',
+  target: 'https://api.bria.ai',
+};
+
+const run = <A, E>(baseUrl: string, effect: Effect.Effect<A, E, LitellmRequirements>): Promise<A> =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(litellmCredentialsLayerFor({ apiKey: MASTER_KEY, baseUrl })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+describe('a delete forbidden for a reason other than "already gone"', () => {
+  test('is not swallowed: it fails, and the row is still live', async () => {
+    const fake = startFakeLitellm({ forbidDelete: true, masterKey: MASTER_KEY, seed: [PROPS] });
+    try {
+      const result = run(fake.url, deletePassThroughEndpoint('live-1'));
+      await expect(result).rejects.toThrow();
+      const rows = await run(fake.url, listPassThroughEndpoints());
+      expect(rows.some((r) => r.id === 'live-1')).toBe(true);
+    } finally {
+      fake.stop();
+    }
+  });
+
+  test('a genuinely-gone id still succeeds with no error (idempotent delete preserved)', async () => {
+    const fake = startFakeLitellm({ forbidDelete: true, masterKey: MASTER_KEY });
+    try {
+      await expect(
+        run(fake.url, deletePassThroughEndpoint('never-existed')),
+      ).resolves.toBeUndefined();
+    } finally {
+      fake.stop();
+    }
+  });
+});