@homeflare/alchemy 0.42.0 → 0.44.0

package/src/litellm/access-group-operations.ts

@@ -0,0 +1,92 @@
+/**
+ * The four LiteLLM `/v1/unified_access_group*` calls `LiteLLM.AccessGroup` uses, through the SDK's
+ * typed operations in `@distilled.cloud/litellm/access_groups` (LiteLLM 1.103.0):
+ *
+ *   list    `listAccessGroupsV1UnifiedAccessGroupGet`                     GET    /v1/unified_access_group
+ *   create  `createAccessGroupV1UnifiedAccessGroupPost`                   POST   /v1/unified_access_group
+ *   update  `updateAccessGroupV1UnifiedAccessGroupAccessGroupIdPut`       PUT    /v1/unified_access_group/{id}
+ *   delete  `deleteAccessGroupV1UnifiedAccessGroupAccessGroupIdDelete`    DELETE /v1/unified_access_group/{id}
+ *
+ * `/v1/unified_access_group` is registered as an alias of `/v1/access_group` on the same handlers
+ * (`access_group_endpoints.py`, the "Alias routes" block), so the two answer identically.
+ * The by-id `GET` is not used: a missing id is a 404 this tag does not declare, and the list decides
+ * absence without depending on it.
+ *
+ * ⛔ WRITES NEED PROXY_ADMIN (`_require_proxy_admin`, 403 otherwise) and READS need admin or admin-view
+ *   (`_require_admin_view`). A key that can only read sees every group and can change none.
+ * ⛔ NO MESSAGE SNIFFING. Nothing here reads a status or message. `create` of a name that exists is a
+ *   409 LiteLLM raises itself; the SDK does not declare it for this tag, so it reaches the caller as
+ *   the SDK's own error, unchanged. `create` runs only after a list showed the name absent, so a 409
+ *   means a concurrent create, which is a failure to report, not to paper over.
+ * ★ DELETE IS IDEMPOTENT BY A REAL READ (the budget and pass-through rule): a failed DELETE is
+ *   swallowed only when the list no longer has the id. A 403 for lack of rights leaves the row
+ *   live, so it re-raises the ORIGINAL error.
+ * ⚠️ DELETING A GROUP DETACHES IT FROM EVERY TEAM AND KEY (`delete_access_group` rewrites their
+ *   `access_group_ids`), which is why the resource defaults to `retain`.
+ */
+import * as ag from '@distilled.cloud/litellm/access_groups';
+import * as Effect from 'effect/Effect';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+import { LitellmRegistryUnreadableError } from './registry-errors.ts';
+import { bodyOf } from './registry-support.ts';
+import { type AccessGroupAttributes } from './access-group-types.ts';
+import { toAttributes } from './access-group-form.ts';
+
+const RESOURCE = 'LiteLLM.AccessGroup';
+
+/** Every group. The list is the table (`AccessGroupRepository(...).table.find_many`), not a registry. */
+export const listAccessGroups = (): Effect.Effect<
+  readonly AccessGroupAttributes[],
+  ag.ListAccessGroupsV1UnifiedAccessGroupGetError | LitellmRegistryUnreadableError,
+  LitellmOpContext
+> =>
+  throughFetch(ag.listAccessGroupsV1UnifiedAccessGroupGet({})).pipe(
+    Effect.flatMap((response) => {
+      const rows: unknown = bodyOf(response);
+      if (!Array.isArray(rows)) {
+        return Effect.fail(
+          new LitellmRegistryUnreadableError({ reason: 'not an array', resource: RESOURCE }),
+        );
+      }
+      const parsed = rows.map(toAttributes);
+      return parsed.every((row) => row !== undefined)
+        ? Effect.succeed(parsed as readonly AccessGroupAttributes[])
+        : Effect.fail(
+            new LitellmRegistryUnreadableError({
+              reason: 'a row has no id or name',
+              resource: RESOURCE,
+            }),
+          );
+    }),
+  );
+
+export const createAccessGroup = (body: ag.CreateAccessGroupV1UnifiedAccessGroupPostRequest) =>
+  throughFetch(ag.createAccessGroupV1UnifiedAccessGroupPost(body)).pipe(Effect.asVoid);
+
+export const updateAccessGroup = (
+  accessGroupId: string,
+  body: Omit<ag.UpdateAccessGroupV1UnifiedAccessGroupAccessGroupIdPutRequest, 'access_group_id'>,
+) =>
+  throughFetch(
+    ag.updateAccessGroupV1UnifiedAccessGroupAccessGroupIdPut({
+      ...body,
+      access_group_id: accessGroupId,
+    }),
+  ).pipe(Effect.asVoid);
+
+export const deleteAccessGroup = (accessGroupId: string) =>
+  throughFetch(
+    ag.deleteAccessGroupV1UnifiedAccessGroupAccessGroupIdDelete({ access_group_id: accessGroupId }),
+  ).pipe(
+    Effect.asVoid,
+    Effect.catch((original) =>
+      listAccessGroups().pipe(
+        Effect.catch(() => Effect.fail(original)),
+        Effect.flatMap((rows) =>
+          rows.some((row) => row.accessGroupId === accessGroupId)
+            ? Effect.fail(original)
+            : Effect.void,
+        ),
+      ),
+    ),
+  );

package/src/litellm/access-group-types.ts

@@ -0,0 +1,49 @@
+/**
+ * What a `LiteLLM.AccessGroup` declares (props) and what is remembered about it (attributes).
+ *
+ * ★ THIS IS THE UNIFIED ACCESS GROUP, `LiteLLM_AccessGroupTable` (`/v1/unified_access_group`), not
+ *   the two other things LiteLLM calls an "access group": a MODEL access group (`access_groups` in a
+ *   model's `model_info`) and an MCP access group (a bare name on an MCP server row, referenced by
+ *   `object_permission.mcp_access_groups`). A unified group bundles models, MCP servers and agents
+ *   under one name and attaches to teams and keys (docs.litellm.ai/docs/proxy/access_groups).
+ * ⚠️ TOOLSETS ARE NOT IN IT. `AccessGroupCreateRequest` (`litellm/types/access_group.py`, 1.103.0)
+ *   has `access_model_names`, `access_mcp_server_ids`, `access_agent_ids`, `assigned_team_ids` and
+ *   `assigned_key_ids` and no toolset field. A toolset is granted through `object_permission.mcp_toolsets`
+ *   on a team or key (`LiteLLM.Team`), not through a group.
+ * ★ MODELS ARE MODEL NAMES, MCP SERVERS ARE SERVER IDS. `access_model_names` holds the `model_name`
+ *   a caller sends (`cf-code`), and `access_mcp_server_ids` holds `server_id`s. Declare a server's id
+ *   with `server.serverId` (a `LiteLLM.MCPServer`) so the dependency edge exists.
+ * ⚠️ NOT MODELLED, on purpose: `assigned_team_ids`, `assigned_key_ids` and `access_agent_ids`. A
+ *   team's group membership is declared on the TEAM (`accessGroupIds`), and LiteLLM mirrors it into
+ *   `assigned_team_ids` in the same transaction; two resources writing one edge would fight. Agents
+ *   are not managed here. None of the three is ever sent, and the update is a partial one, so an
+ *   adopted group keeps whatever it has there.
+ */
+export interface AccessGroupProps {
+  /**
+   * The group's name, and the way an existing row is ADOPTED: `access_group_name` is UNIQUE in the
+   * table (`access_group_endpoints.py` finds it with `find_unique`), so the match is exact. Changing
+   * it is an update of the same row, never a replace: the id does not change.
+   */
+  readonly accessGroupName: string;
+  /** Compared only when declared: adopting a row never clears text a person wrote. Blank is refused. */
+  readonly description?: string;
+  /**
+   * `model_name`s the group grants, compared as a SET and ALWAYS compared (default `[]`): it is an
+   * access grant, so an adopted group that grants more than declared is corrected, never left open.
+   * ⚠️ LiteLLM prunes a name itself when its last deployment is deleted
+   * (`management_helpers/access_group_model_sync.py`), so a plan can show an update for a model that
+   * was removed elsewhere.
+   */
+  readonly modelNames?: readonly string[];
+  /** MCP `server_id`s the group grants, compared as a set and always compared (default `[]`). */
+  readonly mcpServerIds?: readonly string[];
+}
+
+export interface AccessGroupAttributes {
+  readonly accessGroupId: string;
+  readonly accessGroupName: string;
+  readonly description: string | null;
+  readonly modelNames: readonly string[];
+  readonly mcpServerIds: readonly string[];
+}

package/src/litellm/access-group.test.ts

@@ -0,0 +1,197 @@
+/**
+ * `LiteLLM.AccessGroup` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-access-group-litellm.ts`): create, no-op, adopt, update, rename, drift and delete.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`.
+ * ⚠️ WHAT THE FAKE MODELS IS READ FROM THE 1.103.0 SOURCE, NOT MEASURED ON A LIVE PROXY (its header).
+ */
+import { 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 { LiteLLMAccessGroup } from './access-group.ts';
+import { deleteAccessGroup } from './access-group-operations.ts';
+import type { AccessGroupProps } from './access-group-types.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import {
+  type FakeAccessGroupLitellm,
+  groupRow,
+  startFakeAccessGroupLitellm,
+} from './fake-access-group-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+
+const stack = (fake: FakeAccessGroupLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: AccessGroupProps, name = 'Estate') =>
+  Effect.gen(function* () {
+    yield* LiteLLMAccessGroup(name, props);
+  });
+
+const estate: AccessGroupProps = {
+  accessGroupName: 'FAKE-estate',
+  description: 'FAKE estate group',
+  mcpServerIds: ['FAKE-server-a'],
+  modelNames: ['fake-code', 'fake-flash'],
+};
+
+test('creates a group with both grant lists, then a second deploy writes nothing', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'create' });
+  expect(fake.groups()[0]).toMatchObject({
+    access_group_name: 'FAKE-estate',
+    access_mcp_server_ids: ['FAKE-server-a'],
+    access_model_names: ['fake-code', 'fake-flash'],
+    description: 'FAKE estate group',
+  });
+  // ★ the id is the proxy's, and it is what the state remembers
+  expect(String(fake.groups()[0]?.['access_group_id'])).toStartWith('FAKE-group-');
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('an undeclared grant list means "grants nothing": it is sent as an empty list on create', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  await stack(fake).deploy(declare({ accessGroupName: 'FAKE-empty' }));
+  expect(fake.bodies()[0]).toMatchObject({ access_mcp_server_ids: [], access_model_names: [] });
+  expect(fake.bodies()[0]).not.toHaveProperty('description');
+});
+
+test('a changed model set is an update that sends ONLY the field that changed', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  const planned = await same.deploy(declare({ ...estate, modelNames: ['fake-code'] }));
+  expect(planned).toEqual({ Estate: 'update' });
+  expect(fake.bodies().at(-1)).toEqual({ access_model_names: ['fake-code'] });
+  expect(fake.groups()[0]?.['access_mcp_server_ids']).toEqual(['FAKE-server-a']);
+});
+
+test('a rename is an update of the SAME row: the id does not change', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  const id = fake.groups()[0]?.['access_group_id'];
+  expect(await same.deploy(declare({ ...estate, accessGroupName: 'FAKE-renamed' }))).toEqual({
+    Estate: 'update',
+  });
+  expect(fake.groups()).toHaveLength(1);
+  expect(fake.groups()[0]).toMatchObject({
+    access_group_id: id,
+    access_group_name: 'FAKE-renamed',
+  });
+});
+
+test('a live row is Unowned: refused without --adopt, taken by name with it, and a matching row writes nothing', async () => {
+  const live = groupRow({
+    access_group_id: 'FAKE-live-1',
+    access_group_name: 'FAKE-estate',
+    access_mcp_server_ids: ['FAKE-server-a'],
+    access_model_names: ['fake-code', 'fake-flash'],
+    description: 'FAKE estate group',
+  });
+  const fake = startFakeAccessGroupLitellm({ seed: [live] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(estate))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(estate), { adopt: true }))).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('adopting a group that grants MORE than declared corrects it, and leaves undeclared text and teams alone', async () => {
+  const wide = groupRow({
+    access_group_id: 'FAKE-live-2',
+    access_group_name: 'FAKE-estate',
+    access_mcp_server_ids: ['FAKE-server-a', 'FAKE-server-extra'],
+    access_model_names: ['fake-code', 'fake-flash', 'fake-extra'],
+    assigned_team_ids: ['FAKE-team-1'],
+    description: 'written by a person',
+  });
+  const fake = startFakeAccessGroupLitellm({ seed: [wide] });
+  const { description: _kept, ...withoutDescription } = estate;
+  await stack(fake).deploy(declare(withoutDescription), { adopt: true });
+  expect(fake.groups()[0]).toMatchObject({
+    access_mcp_server_ids: ['FAKE-server-a'],
+    access_model_names: ['fake-code', 'fake-flash'],
+    assigned_team_ids: ['FAKE-team-1'],
+    description: 'written by a person',
+  });
+  // ★ a partial update: the team edge is not in the body at all
+  expect(fake.bodies()[0]).not.toHaveProperty('assigned_team_ids');
+  expect(fake.bodies()[0]).not.toHaveProperty('description');
+});
+
+test('reconcile compares the LIVE row: after LiteLLM prunes a model name itself, the next update puts it back', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  fake.dropModel('fake-flash'); // ⚠️ access_group_model_sync.py: a deleted last deployment
+  // ★ Alchemy plans from state, so an unchanged declaration is a no-op even now (beta.79 reads live
+  //   state only to adopt); a declaration that changes anything reaches reconcile, which reads live
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'noop' });
+  expect(await same.deploy(declare({ ...estate, description: 'FAKE changed' }))).toEqual({
+    Estate: 'update',
+  });
+  expect(fake.bodies().at(-1)).toEqual({
+    access_model_names: ['fake-code', 'fake-flash'],
+    description: 'FAKE changed',
+  });
+});
+
+test('a proxy that drops an empty-list edit fails the deploy instead of claiming success', async () => {
+  // ⚠️ the fake's own model of a truthiness check on the edit route — unmeasured at 1.103.0
+  const fake = startFakeAccessGroupLitellm({ editIgnoresEmpty: true });
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  await expect(same.deploy(declare({ ...estate, mcpServerIds: [] }))).rejects.toThrow();
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { ...estate, accessGroupName: ' ' },
+    { ...estate, accessGroupName: ' padded' },
+    { ...estate, description: '  ' },
+    { ...estate, modelNames: ['fake-code', 'fake-code'] },
+    { ...estate, mcpServerIds: ['FAKE-server-a', ''] },
+  ]) {
+    const fake = startFakeAccessGroupLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('removing the declaration RETAINS the row: nothing deletes a group unless the stack opts in', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  await same.deploy(Effect.void);
+  expect(fake.groups()).toHaveLength(1);
+});
+
+const run = <A, E>(fetchFn: typeof globalThis.fetch, effect: Effect.Effect<A, E, unknown>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+test('delete answers 204 with no body, and a missing id is swallowed only because a real read says so', async () => {
+  const live = groupRow({ access_group_id: 'FAKE-live-3', access_group_name: 'FAKE-estate' });
+  const fake = startFakeAccessGroupLitellm({ seed: [live] });
+  await run(fake.fetch, deleteAccessGroup('FAKE-live-3'));
+  expect(fake.groups()).toEqual([]);
+  // already gone: the DELETE 404s, the re-list confirms absence, so it is success
+  await run(fake.fetch, deleteAccessGroup('FAKE-live-3'));
+});
+
+test('a delete refused for lack of rights re-raises the ORIGINAL error and the row stays', async () => {
+  const live = groupRow({ access_group_id: 'FAKE-live-4', access_group_name: 'FAKE-estate' });
+  const fake = startFakeAccessGroupLitellm({ forbidWrites: true, seed: [live] });
+  await expect(run(fake.fetch, deleteAccessGroup('FAKE-live-4'))).rejects.toThrow();
+  expect(fake.groups()).toHaveLength(1);
+});

package/src/litellm/access-group.ts

@@ -0,0 +1,151 @@
+/**
+ * `LiteLLM.AccessGroup` — one row of LiteLLM's unified access group table
+ * (`LiteLLM_AccessGroupTable`, `/v1/unified_access_group`): a named bundle of models and MCP servers
+ * that teams and keys are attached to. Types and what is left out: access-group-types.ts.
+ *
+ * ★ ADOPT BY NAME. `access_group_name` is unique in the table, so `accessGroupName` finds the one
+ *   live row that carries it. A live row with no state is `Unowned`, so it needs `--adopt`.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a group detaches it from every team and key that
+ *   holds it (`delete_access_group` rewrites their `access_group_ids`), and those callers lose the
+ *   models and servers it granted. Opt in with `.pipe(RemovalPolicy.destroy())`.
+ * ★ THE GRANTS ARE THE DECLARATION. `modelNames` and `mcpServerIds` are always compared (an
+ *   undeclared list means "grants nothing"), so an adopted group that grants more is corrected.
+ * ⚠️ NO LICENCE GATE ON THESE ROUTES: `access_group_endpoints.py` has no `premium_user` check
+ *   (grep, 1.103.0), and docs.litellm.ai/docs/proxy/access_groups makes no Enterprise statement.
+ * ⛔ NO LITELLM CREDENTIAL IS A PROP; `litellmProviders`' layer supplies `Credentials`.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import { createBody, differing, firstProblem, updateBody } from './access-group-form.ts';
+import {
+  createAccessGroup,
+  deleteAccessGroup,
+  listAccessGroups,
+  updateAccessGroup,
+} from './access-group-operations.ts';
+import type { AccessGroupAttributes, AccessGroupProps } from './access-group-types.ts';
+import {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryNotConvergedError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+
+export type { AccessGroupAttributes, AccessGroupProps };
+export type { RegistryError as AccessGroupError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.AccessGroup';
+
+export interface LiteLLMAccessGroup extends Resource<
+  'LiteLLM.AccessGroup',
+  AccessGroupProps,
+  AccessGroupAttributes
+> {}
+
+export const LiteLLMAccessGroup = Resource<LiteLLMAccessGroup>('LiteLLM.AccessGroup', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMAccessGroup = (value: unknown): value is LiteLLMAccessGroup =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.AccessGroup';
+
+/**
+ * The live row this declaration means. A RECORDED id wins and is matched by id alone: a row that
+ * vanished and was recreated by hand under the same name is not silently taken over (the create
+ * would then fail on the unique name, loudly). With no state, the name decides.
+ */
+const locate = (
+  rows: readonly AccessGroupAttributes[],
+  props: AccessGroupProps,
+  output: AccessGroupAttributes | undefined,
+) =>
+  output !== undefined
+    ? rows.find((row) => row.accessGroupId === output.accessGroupId)
+    : rows.find((row) => row.accessGroupName === props.accessGroupName);
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const accessGroupHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({ olds, output }: { olds: AccessGroupProps; output: AccessGroupAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.accessGroupName), firstProblem(olds));
+      }
+      const live = locate(yield* listAccessGroups(), olds, output);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<AccessGroupProps>;
+    output: AccessGroupAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.accessGroupName), firstProblem(news));
+      if (output === undefined) return undefined;
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: AccessGroupProps;
+    output: AccessGroupAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.accessGroupName), firstProblem(news));
+      const before = locate(yield* listAccessGroups(), news, output);
+      if (before === undefined) yield* createAccessGroup(createBody(news));
+      else if (differing(before, news).length > 0) {
+        yield* updateAccessGroup(before.accessGroupId, updateBody(news, before));
+      }
+
+      const rows = yield* listAccessGroups();
+      const after =
+        before === undefined
+          ? rows.find((row) => row.accessGroupName === news.accessGroupName)
+          : rows.find((row) => row.accessGroupId === before.accessGroupId);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({
+            name: news.accessGroupName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.accessGroupName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: AccessGroupAttributes }) =>
+    deleteAccessGroup(output.accessGroupId),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMAccessGroupProvider = () =>
+  Provider.effect(
+    LiteLLMAccessGroup,
+    Effect.succeed(LiteLLMAccessGroup.Provider.of(accessGroupHandlers)),
+  );

package/src/litellm/budget-errors.ts

@@ -0,0 +1,38 @@
+/**
+ * The typed refusals `LiteLLM.Budget` raises on top of `@distilled.cloud/litellm`'s own SDK errors.
+ */
+import type * as budgets from '@distilled.cloud/litellm/budget_management';
+import * as Data from 'effect/Data';
+
+/** A `maxBudget` (a HARD cap: LiteLLM answers 429 once it is spent) declared with no reason. */
+export class LitellmBudgetHardCapUnjustifiedError extends Data.TaggedError(
+  'LitellmBudgetHardCapUnjustifiedError',
+)<{
+  readonly budgetId: string | undefined;
+}> {}
+
+/**
+ * The write returned no error but the row still carries a limit the declaration does not.
+ * `/budget/update` may merge with `exclude_none` (the way `/config/pass_through_endpoint` does),
+ * in which case a limit can never be cleared by an update. Refused, never claimed as done.
+ */
+export class LitellmBudgetFieldNotClearedError extends Data.TaggedError(
+  'LitellmBudgetFieldNotClearedError',
+)<{
+  readonly budgetId: string;
+  readonly fields: readonly string[];
+}> {}
+
+/** `/budget/info` answered something that is not a list of budget rows. */
+export class LitellmBudgetUnreadableError extends Data.TaggedError('LitellmBudgetUnreadableError')<{
+  readonly budgetId: string;
+}> {}
+
+export type BudgetError =
+  | budgets.PostInfoBudgetBudgetInfoError
+  | budgets.PostNewBudgetBudgetNewError
+  | budgets.UpdateBudgetBudgetUpdatePostError
+  | budgets.DeleteBudgetBudgetDeletePostError
+  | LitellmBudgetHardCapUnjustifiedError
+  | LitellmBudgetFieldNotClearedError
+  | LitellmBudgetUnreadableError;

package/src/litellm/budget-form.ts

@@ -0,0 +1,94 @@
+/**
+ * Props, wire bodies and comparison for `LiteLLM.Budget`, testable without a server.
+ *
+ * ⛔ NO SILENT `max_budget`. LiteLLM's own field doc: "Requests will fail if this budget (in USD)
+ *   is exceeded" — a hard cap. On 2026-09-28 an undeclared $60/day `max_budget` on
+ *   `hf-tier-interactive` 429'd the whole claude2 fleet. So `maxBudget` is never defaulted and is
+ *   refused unless `maxBudgetReason` says why; `softBudget` is the monitoring field (it "will NOT
+ *   fail if this is exceeded", it fires the alert).
+ * ⚠️ NOT MODELLED: `max_parallel_requests`, `model_max_budget`, `budget_reset_at`. The row read
+ *   back (`BudgetListItem`, generated at LiteLLM 1.100.0) has none of them, so a declaration of
+ *   them could never be diffed. Add them when a read that returns them is measured.
+ */
+import type * as budgets from '@distilled.cloud/litellm/budget_management';
+
+export interface BudgetProps {
+  /** Live budget id. Set it to adopt an existing row (`hf-tier-agent`); default is a deterministic physical name. */
+  readonly budgetId?: string;
+  /** Alert threshold in USD. Requests keep flowing when exceeded. The monitoring field. */
+  readonly softBudget?: number;
+  /** HARD cap in USD: requests fail (429) once spent. Refused unless `maxBudgetReason` is set. */
+  readonly maxBudget?: number;
+  /** Why a hard cap is wanted. Required with `maxBudget`; recorded in the declaration only. */
+  readonly maxBudgetReason?: string;
+  /** Reset period, e.g. `'1d'`, `'28d'`. */
+  readonly budgetDuration?: string;
+  /** Requests per minute. */
+  readonly rpmLimit?: number;
+  /** Tokens per minute. */
+  readonly tpmLimit?: number;
+}
+
+export interface BudgetAttributes {
+  readonly budgetId: string;
+  readonly softBudget: number | null;
+  readonly maxBudget: number | null;
+  readonly budgetDuration: string | null;
+  readonly rpmLimit: number | null;
+  readonly tpmLimit: number | null;
+}
+
+/** Declared field → wire field. The single list every comparison and body walks. */
+const FIELDS = [
+  ['softBudget', 'soft_budget'],
+  ['maxBudget', 'max_budget'],
+  ['budgetDuration', 'budget_duration'],
+  ['rpmLimit', 'rpm_limit'],
+  ['tpmLimit', 'tpm_limit'],
+] as const;
+
+export const isHardCapUnjustified = (props: BudgetProps): boolean =>
+  props.maxBudget !== undefined && (props.maxBudgetReason ?? '').trim() === '';
+
+/** Create body: only what is declared. */
+export const createBody = (
+  props: BudgetProps,
+  budgetId: string,
+): budgets.PostNewBudgetBudgetNewRequest => {
+  const body: Record<string, unknown> = { budget_id: budgetId };
+  for (const [prop, wire] of FIELDS) if (props[prop] !== undefined) body[wire] = props[prop];
+  return body as budgets.PostNewBudgetBudgetNewRequest;
+};
+
+/** Update body: declared fields, plus an explicit `null` for a live limit the declaration dropped. */
+export const updateBody = (
+  props: BudgetProps,
+  live: BudgetAttributes,
+): budgets.UpdateBudgetBudgetUpdatePostRequest => {
+  const body: Record<string, unknown> = { budget_id: live.budgetId };
+  for (const [prop, wire] of FIELDS) {
+    if (props[prop] !== undefined) body[wire] = props[prop];
+    else if (live[prop] !== null) body[wire] = null;
+  }
+  return body as budgets.UpdateBudgetBudgetUpdatePostRequest;
+};
+
+/** Wire names of the fields where live and declared disagree. */
+export const differing = (live: BudgetAttributes, props: BudgetProps): readonly string[] =>
+  FIELDS.filter(([prop]) => live[prop] !== (props[prop] ?? null)).map(([, wire]) => wire);
+
+const numberOrNull = (value: unknown): number | null =>
+  value === null || value === undefined || value === '' ? null : Number(value);
+
+/**
+ * One row of `/budget/info`. `tpm_limit`/`rpm_limit` are `BigInt?` in LiteLLM's schema and come
+ * back as decimal strings (the generated `BudgetListItem` says so), hence `Number()`.
+ */
+export const toAttributes = (row: Record<string, unknown>): BudgetAttributes => ({
+  budgetDuration: typeof row['budget_duration'] === 'string' ? row['budget_duration'] : null,
+  budgetId: String(row['budget_id']),
+  maxBudget: numberOrNull(row['max_budget']),
+  rpmLimit: numberOrNull(row['rpm_limit']),
+  softBudget: numberOrNull(row['soft_budget']),
+  tpmLimit: numberOrNull(row['tpm_limit']),
+});

package/src/litellm/budget-operations.ts

@@ -0,0 +1,51 @@
+/**
+ * The four LiteLLM `/budget/*` calls `LiteLLM.Budget` uses, through the SDK's typed operations.
+ *
+ * ★ READS GO THROUGH `/budget/list` (the whole table, a bare array), not `/budget/info`. Both
+ *   answer `body: unknown` in the generated schema, and what `/budget/info` does for an id that is
+ *   not there is unmeasured; a list answers absence unambiguously.
+ * ⚠️ Unlike pass-through endpoints, each budget is its own DB row, so no semaphore.
+ * ⚠️ DELETE is idempotent BY THIS FUNCTION: a `BadRequest` re-lists and is swallowed only when the
+ *   id is genuinely absent, never on message text (pass-through `operations.ts`' rule).
+ */
+import * as budgets from '@distilled.cloud/litellm/budget_management';
+import * as Effect from 'effect/Effect';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+import { type BudgetAttributes, toAttributes } from './budget-form.ts';
+import { LitellmBudgetUnreadableError } from './budget-errors.ts';
+
+export const listBudgets = (): Effect.Effect<
+  readonly BudgetAttributes[],
+  budgets.ListBudgetBudgetListGetError | LitellmBudgetUnreadableError,
+  LitellmOpContext
+> =>
+  throughFetch(budgets.listBudgetBudgetListGet({})).pipe(
+    // ⚠️ MEASURED with the fake: the SDK types this `{ body: unknown }` but hands a bare JSON array
+    //   back as the array itself, so accept both shapes and refuse anything else.
+    Effect.flatMap((response) => {
+      const rows: unknown = Array.isArray(response)
+        ? response
+        : (response as { body?: unknown }).body;
+      return Array.isArray(rows)
+        ? Effect.succeed(rows.map((row) => toAttributes(row as Record<string, unknown>)))
+        : Effect.fail(new LitellmBudgetUnreadableError({ budgetId: '*' }));
+    }),
+  );
+
+export const createBudget = (body: budgets.PostNewBudgetBudgetNewRequest) =>
+  throughFetch(budgets.postNewBudgetBudgetNew(body)).pipe(Effect.asVoid);
+
+export const updateBudget = (body: budgets.UpdateBudgetBudgetUpdatePostRequest) =>
+  throughFetch(budgets.updateBudgetBudgetUpdatePost(body)).pipe(Effect.asVoid);
+
+export const deleteBudget = (id: string) =>
+  throughFetch(budgets.deleteBudgetBudgetDeletePost({ id })).pipe(
+    Effect.asVoid,
+    Effect.catchTag('BadRequest', (original) =>
+      listBudgets().pipe(
+        Effect.flatMap((rows) =>
+          rows.some((row) => row.budgetId === id) ? Effect.fail(original) : Effect.void,
+        ),
+      ),
+    ),
+  );