@homeflare/alchemy 0.28.0 → 0.29.0

package/src/litellm/index.ts

@@ -2,32 +2,18 @@
  * 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).
+ *   and the internals `pass-through-form.ts`/`operations.ts` need but a consumer should not depend
+ *   on directly are not re-exported here (netbox/index.ts's own rule).
+ * ★ CREDENTIALS AND TYPES NOW COME FROM `@distilled.cloud/litellm` ITSELF (2026-09-24, moved off a
+ *   hand-rolled `client.ts`/`credentials.ts` the same way `/netbox` and `/forgejo` did) — a
+ *   consumer building its own credentials layer imports `Credentials`/`CredentialsFromEnv`/
+ *   `credentials` from `@distilled.cloud/litellm/Credentials` directly, not through this barrel.
  */
-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';
+} from '@distilled.cloud/litellm/misc';
 export {
   LiteLLMPassThroughEndpoint,
   LiteLLMPassThroughEndpointProvider,

package/src/litellm/operations.ts

@@ -0,0 +1,149 @@
+/**
+ * The four LiteLLM `/config/pass_through_endpoint*` calls this package writes to and reads from —
+ * now through `@distilled.cloud/litellm`'s typed operations (S23), not a hand-rolled `HttpClient`
+ * client. `client.ts` is retired; nothing else in this package imported it.
+ *
+ * ⛔ STILL WRAPPED IN A PER-BASE-URL SEMAPHORE, UNCHANGED FROM `client.ts`. LiteLLM stores every
+ *   pass-through endpoint in ONE `general_settings.pass_through_endpoints` list
+ *   (`pass_through_endpoints.py` at tag v1.100.0, mirrored in the SDK's own `misc.ts` docstrings),
+ *   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. The SDK has no opinion on
+ *   this: it is a quirk of how THIS vendor stores the resource, not a distilled protocol concern,
+ *   so it stays here, one layer above the typed calls. 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 `pass-through-endpoint.ts`'s `reconcile` reads back after writing rather than
+ *   trusting the call that just returned (docs/litellm.md).
+ * ⛔ NO STATUS SNIFFING (S21). Every failure the SDK's own typed operations declare — `BadRequest`
+ *   (400), `NotFound` (404 on update only), `UnprocessableEntity` (422) plus the shared
+ *   `Unauthorized`/`TooManyRequests`/`InternalServerError`/`BadGateway`/`ServiceUnavailable`/
+ *   `GatewayTimeout` every operation carries — is a distilled patch's doing
+ *   (`@distilled.cloud/litellm`'s own `patches/misc/*.json`, applied at generation time), never a
+ *   status check here or in `pass-through-endpoint.ts`. Deleting an id LiteLLM does not have
+ *   answers `BadRequest` (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. Telling those
+ *   apart by re-listing, not by the `BadRequest`'s message text, is `pass-through-endpoint.ts`'s
+ *   `deletePassThroughEndpoint`'s own job (S21 — a status-and-a-real-read decision, never body
+ *   text) — this file only forwards the typed error.
+ */
+import * as misc from '@distilled.cloud/litellm/misc';
+import { Credentials } from '@distilled.cloud/litellm/Credentials';
+import type { LitellmOpContext } from '@distilled.cloud/litellm/Protocol';
+import type { ConfigError } from '@distilled.cloud/litellm/Errors';
+import * as Effect from 'effect/Effect';
+import * as Semaphore from 'effect/Semaphore';
+
+export type { LitellmOpContext } from '@distilled.cloud/litellm/Protocol';
+export type LitellmRequirements = LitellmOpContext;
+export type {
+  PassThroughEndpointResponse,
+  PassThroughGenericEndpoint,
+  PassThroughGuardrailSettings,
+} from '@distilled.cloud/litellm/misc';
+
+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;
+  });
+
+/**
+ * Serialises a write against this call's own base URL — see the file header.
+ *
+ * Resolving `Credentials` can itself fail typed (`ConfigError` — S20/S24, credentials.ts), so
+ * the return type carries that alongside the wrapped operation's own error `E`; every call
+ * site's declared error type already includes `ConfigError` as a member of the SDK's shared
+ * `LitellmOpError` (protocol.ts), so this widening is a no-op for callers.
+ */
+const mutate = <A, E>(
+  io: Effect.Effect<A, E, LitellmOpContext>,
+): Effect.Effect<A, E | ConfigError, LitellmOpContext> =>
+  Effect.gen(function* () {
+    const resolve = yield* Credentials;
+    const creds = yield* resolve;
+    const semaphore = yield* semaphoreFor(creds.apiBaseUrl);
+    return yield* semaphore.withPermits(1)(io);
+  });
+
+/** 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 misc.PassThroughGenericEndpoint[],
+  misc.GetPassThroughEndpointsConfigPassThroughEndpointGetError,
+  LitellmOpContext
+> =>
+  misc
+    .getPassThroughEndpointsConfigPassThroughEndpointGet({})
+    .pipe(Effect.map((response) => response.endpoints));
+
+/** POST /config/pass_through_endpoint. `body` carries `id` — see pass-through-form.ts. */
+export const createPassThroughEndpoint = (
+  body: misc.PassThroughGenericEndpoint,
+): Effect.Effect<
+  void,
+  misc.CreatePassThroughEndpointsConfigPassThroughEndpointPostError,
+  LitellmOpContext
+> => mutate(misc.createPassThroughEndpointsConfigPassThroughEndpointPost(body).pipe(Effect.asVoid));
+
+/**
+ * POST /config/pass_through_endpoint/{endpoint_id}. Merges with `exclude_none` — see
+ * pass-through-form.ts. `body` is `pass-through-form.ts`'s own `UpdateBody`, not a blanket
+ * `Partial<>` — `path`/`target` are the two fields the SDK's request type still requires
+ * non-optionally on an update.
+ */
+export const updatePassThroughEndpoint = (
+  endpointId: string,
+  body: Partial<Omit<misc.PassThroughGenericEndpoint, 'path' | 'target'>> &
+    Pick<misc.PassThroughGenericEndpoint, 'path' | 'target'>,
+): Effect.Effect<
+  void,
+  misc.UpdatePassThroughEndpointsConfigPassThroughEndpointEndpointIdPostError,
+  LitellmOpContext
+> =>
+  mutate(
+    misc
+      .updatePassThroughEndpointsConfigPassThroughEndpointEndpointIdPost({
+        ...body,
+        endpoint_id: endpointId,
+      })
+      .pipe(Effect.asVoid),
+  );
+
+/**
+ * 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`, which the SDK decodes as a typed `BadRequest` — but the SAME
+ * route also raises the SAME `BadRequest` for `not_allowed_access` (a non-PROXY_ADMIN caller) or a
+ * disconnected DB, on a row that never got deleted. A `BadRequest` alone cannot tell the two apart,
+ * so THIS FUNCTION DOESN'T GUESS FROM THE TAG ALONE: on `BadRequest` it re-lists (a GET — no
+ * PROXY_ADMIN required) 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,
+  misc.DeletePassThroughEndpointsConfigPassThroughEndpointDeleteError,
+  LitellmOpContext
+> =>
+  mutate(
+    misc
+      .deletePassThroughEndpointsConfigPassThroughEndpointDelete({ endpoint_id: endpointId })
+      .pipe(
+        Effect.asVoid,
+        Effect.catchTag('BadRequest', (original) =>
+          Effect.gen(function* () {
+            const rows = yield* listPassThroughEndpoints();
+            if (rows.some((row) => row.id === endpointId)) return yield* Effect.fail(original);
+          }),
+        ),
+      ),
+  );

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

@@ -13,15 +13,16 @@
  *   "already gone" only if the row is actually absent.
  */
 import { describe, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
 import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE, startFakeLitellm } from './fake-litellm.ts';
 import {
   type LitellmRequirements,
   deletePassThroughEndpoint,
   listPassThroughEndpoints,
-} from './client.ts';
-import { litellmCredentialsLayerFor } from './credentials.ts';
-import { startFakeLitellm } from './fake-litellm.ts';
+} from './operations.ts';
 
 const MASTER_KEY = 'sk-test-master';
 const PROPS = {
@@ -32,35 +33,31 @@ const PROPS = {
   target: 'https://api.bria.ai',
 };
 
-const run = <A, E>(baseUrl: string, effect: Effect.Effect<A, E, LitellmRequirements>): Promise<A> =>
+const run = <A, E>(
+  fetchFn: typeof globalThis.fetch,
+  effect: Effect.Effect<A, E, LitellmRequirements>,
+): Promise<A> =>
   Effect.runPromise(
     effect.pipe(
       Effect.provide(FetchHttpClient.layer),
-      Effect.provide(litellmCredentialsLayerFor({ apiKey: MASTER_KEY, baseUrl })),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE })),
     ) 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();
-    }
+    const result = run(fake.fetch, deletePassThroughEndpoint('live-1'));
+    await expect(result).rejects.toThrow();
+    const rows = await run(fake.fetch, listPassThroughEndpoints());
+    expect(rows.some((r) => r.id === 'live-1')).toBe(true);
   });
 
   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();
-    }
+    await expect(
+      run(fake.fetch, deletePassThroughEndpoint('never-existed')),
+    ).resolves.toBeUndefined();
   });
 });

package/src/litellm/pass-through-endpoint-replace.test.ts

@@ -15,11 +15,11 @@
  *   caught this: it calls `h.reconcile` directly with the SAME instanceId and the OLD output, a
  *   call shape the real engine never produces for a `replace`.
  */
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { beforeEach, describe, expect, test } from 'bun:test';
 import * as RemovalPolicy from 'alchemy/RemovalPolicy';
 import * as Effect from 'effect/Effect';
+import { FAKE_BASE, type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
 import { type FakeStack, fakeStack, writesOf } from './fake-stack.ts';
-import { type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
 import { LiteLLMPassThroughEndpoint } from './pass-through-endpoint.ts';
 import type { PassThroughEndpointProps } from './pass-through-form.ts';
 
@@ -29,9 +29,8 @@ let fake: FakeLitellm;
 let stack: FakeStack;
 beforeEach(() => {
   fake = startFakeLitellm({ masterKey: MASTER_KEY });
-  stack = fakeStack({ apiKey: MASTER_KEY, baseUrl: fake.url });
+  stack = fakeStack({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE }, fake.fetch);
 });
-afterEach(() => fake.stop());
 
 /** ★ `RemovalPolicy.destroy()`, deliberately: under the (non-default) `retain`, `deleteFirst`'s own
  *   old-generation delete is skipped by the engine (Apply.ts's `deleteOldGenerations`), so a path

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

@@ -2,15 +2,16 @@
  * `LiteLLM.PassThroughEndpoint`'s lifecycle handlers, called directly against `fake-litellm.ts` —
  * the loopback-fake pattern this kit uses in place of `alchemy/Test/*` (H12, no live writes).
  */
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { Stack } from 'alchemy/Stack';
 import { Stage } from 'alchemy/Stage';
 import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
-import { litellmCredentialsLayerFor } from './credentials.ts';
-import { type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
-import { createPassThroughEndpoint } from './client.ts';
+import { FAKE_BASE, type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
+import { createPassThroughEndpoint } from './operations.ts';
 import {
   LitellmConfigPathConflictError,
   LitellmLiteralSecretHeaderError,
@@ -22,11 +23,11 @@ const MASTER_KEY = 'sk-test-master';
 const INSTANCE_ID = 'a'.repeat(32);
 const FAKE_STACK = { actions: {}, bindings: {}, name: 's', resources: {}, stage: 'test' } as never;
 
+/** No `.stop()` any more — `fake.fetch` is a plain function, no real socket to close. */
 let fake: FakeLitellm;
 beforeEach(() => {
   fake = startFakeLitellm({ masterKey: MASTER_KEY });
 });
-afterEach(() => fake.stop());
 
 const run = <A, E>(effect: Effect.Effect<A, E, never>): Promise<A> =>
   Effect.runPromise(effect as Effect.Effect<A, E, never>);
@@ -34,7 +35,8 @@ const run = <A, E>(effect: Effect.Effect<A, E, never>): Promise<A> =>
 const withServices = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   effect.pipe(
     Effect.provide(FetchHttpClient.layer),
-    Effect.provide(litellmCredentialsLayerFor({ apiKey: MASTER_KEY, baseUrl: fake.url })),
+    Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fake.fetch)),
+    Effect.provide(credentials({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE })),
     Effect.provideService(Stage, 'test'),
     Effect.provideService(Stack, FAKE_STACK),
   ) as Effect.Effect<A, E, never>;
@@ -150,7 +152,6 @@ describe('two endpoints created in one deploy', () => {
 
 describe('a path held by an is_from_config row', () => {
   test('is refused at read, before any write', async () => {
-    fake.stop();
     fake = startFakeLitellm({
       masterKey: MASTER_KEY,
       seed: [{ ...PROPS, id: 'cfg-1', is_from_config: true }],
@@ -167,7 +168,6 @@ describe('a path held by an is_from_config row', () => {
 
 describe('a foreign DB row on the same path', () => {
   test('is Unowned, and read works with output undefined', async () => {
-    fake.stop();
     fake = startFakeLitellm({
       masterKey: MASTER_KEY,
       seed: [{ ...PROPS, id: 'foreign-1', is_from_config: false }],

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

@@ -18,7 +18,8 @@
  *   ADDRESSED by the id-keyed update/delete calls this provider uses, so it is refused rather than
  *   silently adopted into an id-based lifecycle it cannot actually manage — see docs/litellm.md.
  * ⛔ NO CREDENTIAL IS A PROP (S25). `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` are read at call
- *   time by credentials.ts.
+ *   time by `@distilled.cloud/litellm`'s own `CredentialsFromEnv` (providers.ts) — the same two
+ *   variable names the retired hand-rolled `credentials.ts` read.
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
@@ -28,18 +29,21 @@ import { createPhysicalName } from 'alchemy/PhysicalName';
 import * as Provider from 'alchemy/Provider';
 import type { Stack } from 'alchemy/Stack';
 import type { Stage } from 'alchemy/Stage';
-import * as Data from 'effect/Data';
+import type * as misc from '@distilled.cloud/litellm/misc';
 import * as Effect from 'effect/Effect';
 import * as Predicate from 'effect/Predicate';
 import {
-  type LitellmError,
   type LitellmRequirements,
   createPassThroughEndpoint,
   deletePassThroughEndpoint,
   listPassThroughEndpoints,
   updatePassThroughEndpoint,
-} from './client.ts';
-import type { PassThroughGenericEndpoint } from './generated/pass-through.ts';
+} from './operations.ts';
+import {
+  LitellmConfigPathConflictError,
+  LitellmLiteralSecretHeaderError,
+  LitellmUnaddressableRowError,
+} from './pass-through-errors.ts';
 import {
   type PassThroughEndpointAttributes,
   type PassThroughEndpointProps,
@@ -51,26 +55,12 @@ import {
 } from './pass-through-form.ts';
 
 export type { PassThroughEndpointAttributes, PassThroughEndpointProps };
-
-export class LitellmConfigPathConflictError extends Data.TaggedError(
-  'LitellmConfigPathConflictError',
-)<{
-  readonly path: string;
-}> {}
-export class LitellmUnaddressableRowError extends Data.TaggedError('LitellmUnaddressableRowError')<{
-  readonly path: string;
-}> {}
-export class LitellmLiteralSecretHeaderError extends Data.TaggedError(
-  'LitellmLiteralSecretHeaderError',
-)<{
-  readonly headers: readonly string[];
-}> {}
-
-export type PassThroughEndpointError =
-  | LitellmError
-  | LitellmConfigPathConflictError
-  | LitellmUnaddressableRowError
-  | LitellmLiteralSecretHeaderError;
+export {
+  LitellmConfigPathConflictError,
+  LitellmLiteralSecretHeaderError,
+  LitellmUnaddressableRowError,
+  type PassThroughEndpointError,
+} from './pass-through-errors.ts';
 
 export interface LiteLLMPassThroughEndpoint extends Resource<
   'LiteLLM.PassThroughEndpoint',
@@ -88,7 +78,7 @@ export const isLiteLLMPassThroughEndpoint = (value: unknown): value is LiteLLMPa
   Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.PassThroughEndpoint';
 
 const toAttributes = (
-  row: PassThroughGenericEndpoint,
+  row: misc.PassThroughGenericEndpoint,
   fallbackId: string,
 ): PassThroughEndpointAttributes => ({
   ...row,
@@ -104,12 +94,12 @@ const physicalIdOf = (logicalId: string, instanceId: string) =>
  * file header — or a genuine foreign DB row to hand back `Unowned`).
  */
 const locate = (
-  rows: readonly PassThroughGenericEndpoint[],
+  rows: readonly misc.PassThroughGenericEndpoint[],
   objectId: string,
   path: string,
 ): {
-  readonly mine: PassThroughGenericEndpoint | undefined;
-  readonly conflict: PassThroughGenericEndpoint | undefined;
+  readonly mine: misc.PassThroughGenericEndpoint | undefined;
+  readonly conflict: misc.PassThroughGenericEndpoint | undefined;
 } => {
   const mine = rows.find((row) => row.id === objectId);
   const conflict = mine === undefined ? rows.find((row) => row.path === path) : undefined;
@@ -117,13 +107,13 @@ const locate = (
 };
 
 /** The typed refusal for a `path` conflict that cannot ever be adopted (config row, or no id). */
-const conflictRefusal = (conflict: PassThroughGenericEndpoint, path: string) =>
+const conflictRefusal = (conflict: misc.PassThroughGenericEndpoint, path: string) =>
   conflict.is_from_config === true
     ? new LitellmConfigPathConflictError({ path })
     : new LitellmUnaddressableRowError({ path });
 
 /** `read`'s answer for a path conflict: `Unowned` when it is a real, addressable DB row — a typed refusal otherwise. */
-const readConflict = (conflict: PassThroughGenericEndpoint, path: string) =>
+const readConflict = (conflict: misc.PassThroughGenericEndpoint, path: string) =>
   conflict.is_from_config !== true && conflict.id !== undefined && conflict.id !== null
     ? Effect.succeed(Unowned(toAttributes(conflict, conflict.id)))
     : Effect.fail(conflictRefusal(conflict, path));

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

@@ -0,0 +1,37 @@
+/**
+ * The typed refusals `LiteLLM.PassThroughEndpoint` raises on top of `@distilled.cloud/litellm`'s
+ * own SDK errors — split out of pass-through-endpoint.ts to keep that file under the house's
+ * 250-line cap once this migration added the four named SDK error-union re-exports.
+ */
+import type * as misc from '@distilled.cloud/litellm/misc';
+import * as Data from 'effect/Data';
+
+export class LitellmConfigPathConflictError extends Data.TaggedError(
+  'LitellmConfigPathConflictError',
+)<{
+  readonly path: string;
+}> {}
+export class LitellmUnaddressableRowError extends Data.TaggedError('LitellmUnaddressableRowError')<{
+  readonly path: string;
+}> {}
+export class LitellmLiteralSecretHeaderError extends Data.TaggedError(
+  'LitellmLiteralSecretHeaderError',
+)<{
+  readonly headers: readonly string[];
+}> {}
+
+/**
+ * ⛔ THE FOUR SDK ERROR UNIONS, NAMED, NOT `LitellmOpError` ALONE. `catchTag`'s tag-literal
+ *   inference needs a concrete union to resolve `"BadRequest"`/`"NotFound"` against (the same
+ *   reason `netbox/resource.ts` leaves `NotFound` folding to each resource file, not its shared
+ *   engine) — `operations.ts` already returns each call's own precise per-operation error type, so
+ *   this is just their union, not a re-widening.
+ */
+export type PassThroughEndpointError =
+  | misc.GetPassThroughEndpointsConfigPassThroughEndpointGetError
+  | misc.CreatePassThroughEndpointsConfigPassThroughEndpointPostError
+  | misc.UpdatePassThroughEndpointsConfigPassThroughEndpointEndpointIdPostError
+  | misc.DeletePassThroughEndpointsConfigPassThroughEndpointDeleteError
+  | LitellmConfigPathConflictError
+  | LitellmUnaddressableRowError
+  | LitellmLiteralSecretHeaderError;

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

@@ -5,14 +5,17 @@
  * ★ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER — the same reason netbox keeps `prefix-form.ts`
  *   beside `prefix.ts` (S32/testing-and-docs.md).
  *
- * ⛔ PROPS ARE THE GENERATED TYPE, MINUS THE TWO FIELDS THIS RESOURCE OWNS ITSELF: `id` (a
- *   deterministic physical name — pass-through-endpoint.ts) and `is_from_config` (response-only;
- *   the vendor sets it, a declaration never does). Deriving `Props` with `Omit<>` rather than
- *   hand-typing it means a vendor schema change that adds, removes or narrows a field is felt here
- *   as a compiler error, not silently ignored.
+ * ⛔ PROPS ARE `@distilled.cloud/litellm`'s OWN GENERATED TYPE, MINUS THE TWO FIELDS THIS RESOURCE
+ *   OWNS ITSELF: `id` (a deterministic physical name — pass-through-endpoint.ts) and
+ *   `is_from_config` (response-only; the vendor sets it, a declaration never does). Deriving
+ *   `Props` with `Omit<>` rather than hand-typing it means a vendor schema change the SDK's own
+ *   next regeneration picks up is felt here as a compiler error, not silently ignored — the same
+ *   reason this used to derive from the kit's own hand-generated `./generated/pass-through.ts`
+ *   (retired by this migration: the SDK's type is the same shape, generated from the same LiteLLM
+ *   1.100.0 OpenAPI document, and keeping a second copy would only drift).
  */
 import { deepEqual } from 'alchemy/Diff';
-import type * as Generated from './generated/pass-through.ts';
+import type * as Generated from '@distilled.cloud/litellm/misc';
 
 export type PassThroughEndpointProps = Omit<
   Generated.PassThroughGenericEndpoint,
@@ -71,10 +74,17 @@ export const createBody = (
  * `undefined` OR an explicit `null` here would be dropped by the server anyway; sending neither is
  * the same outcome with no request made when nothing changed (`Object.keys(body).length === 0`
  * checked by the caller in pass-through-endpoint.ts).
+ *
+ * ⛔ `path`/`target` ARE NOT `Partial` HERE, UNLIKE EVERY OTHER FIELD. The SDK's own update
+ *   request type requires both non-optionally (the vendor's PATCH route still wants the full
+ *   route/target pair on every call, unlike the other fields' `exclude_none` merge) — typing them
+ *   as always-present here is what lets `operations.ts`'s `updatePassThroughEndpoint` pass this
+ *   straight to the SDK without an unsafe cast.
  */
-export const updateBody = (
-  props: PassThroughEndpointProps,
-): Partial<Generated.PassThroughGenericEndpoint> =>
+export type UpdateBody = Partial<Omit<Generated.PassThroughGenericEndpoint, 'path' | 'target'>> &
+  Pick<Generated.PassThroughGenericEndpoint, 'path' | 'target'>;
+
+export const updateBody = (props: PassThroughEndpointProps): UpdateBody =>
   prune({
     ...settled(props),
     guardrails: isUnset(props.guardrails) ? undefined : props.guardrails,
@@ -82,7 +92,7 @@ export const updateBody = (
     path: props.path,
     target: props.target,
     timeout: isUnset(props.timeout) ? undefined : props.timeout,
-  }) as Partial<Generated.PassThroughGenericEndpoint>;
+  }) as UpdateBody;
 
 /**
  * Whether ANY of the three nullable fields went from set (in `live`) to unset (in `props`) — the

package/src/litellm/providers.ts

@@ -3,17 +3,18 @@
  *
  *     Layer.mergeAll(litellmProviders(), …the stack's other providers)
  *
- * ★ THE DEFAULT READS `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` AT CALL TIME (credentials.ts),
- *   never at layer build — pass another `Layer.Layer<LitellmCredentials>` (see
- *   `litellmCredentialsLayerFor` in a test) to source them another way.
+ * ★ THE DEFAULT READS `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` AT CALL TIME, through
+ *   `@distilled.cloud/litellm`'s own `CredentialsFromEnv` — the same two variable names the
+ *   retired hand-rolled `credentials.ts` read — never at layer build. Pass another
+ *   `Layer.Layer<Credentials>` (see the SDK's own `credentials({ apiKey, baseUrl })` in a test) to
+ *   source them another way.
  * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime the same way it is
  *   for `netboxProviders`-style families in this kit; a stack that already deploys anything over
  *   HTTP already has one.
  */
+import { type Credentials, CredentialsFromEnv } from '@distilled.cloud/litellm/Credentials';
 import * as Layer from 'effect/Layer';
-import { type LitellmCredentials, litellmCredentialsLayer } from './credentials.ts';
 import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
 
-export const litellmProviders = (
-  creds: Layer.Layer<LitellmCredentials> = litellmCredentialsLayer,
-) => LiteLLMPassThroughEndpointProvider().pipe(Layer.provide(creds));
+export const litellmProviders = (creds: Layer.Layer<Credentials> = CredentialsFromEnv) =>
+  LiteLLMPassThroughEndpointProvider().pipe(Layer.provide(creds));