@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/team-members.test.ts

@@ -0,0 +1,150 @@
+/**
+ * `LiteLLM.Team`'s roster (additive only) and its delete (which deletes the team's keys), over the fake
+ * proxy (`fake-team-litellm.ts`).
+ *
+ * ★ 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 { FAKE_BASE } from './fake-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import { type FakeTeamLitellm, startFakeTeamLitellm, teamRow } from './fake-team-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMTeam } from './team.ts';
+import { deleteTeam } from './team-operations.ts';
+import type { TeamProps } from './team-types.ts';
+
+const stack = (fake: FakeTeamLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: TeamProps, name = 'Estate') =>
+  Effect.gen(function* () {
+    yield* LiteLLMTeam(name, props);
+  });
+
+const seats: TeamProps = {
+  members: [{ userId: 'FAKE-user-a' }, { userId: 'FAKE-user-b' }],
+  teamAlias: 'FAKE-seats',
+  teamId: 'FAKE-team-seats',
+};
+
+const roster = (fake: FakeTeamLitellm) => {
+  const members = (fake.teams()[0]?.['members_with_roles'] ?? []) as {
+    user_id: string;
+    role: string;
+  }[];
+  return members.map((member) => `${member.user_id}:${member.role}`);
+};
+
+test('adds the declared members in ONE call, and the caller LiteLLM auto-adds as admin is not drift', async () => {
+  const fake = startFakeTeamLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(seats))).toEqual({ Estate: 'create' });
+  expect(roster(fake)).toEqual(['default_user_id:admin', 'FAKE-user-a:user', 'FAKE-user-b:user']);
+  expect(fake.requests().filter((each) => each.path === '/team/member_add')).toHaveLength(1);
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(seats))).toEqual({ Estate: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a new member on an existing roster is added alone, and nobody is ever removed', async () => {
+  const fake = startFakeTeamLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(seats));
+  await same.deploy(declare({ ...seats, members: [{ userId: 'FAKE-user-c' }] }));
+  // ★ user-a and user-b are not declared any more and are still there
+  expect(roster(fake)).toEqual([
+    'default_user_id:admin',
+    'FAKE-user-a:user',
+    'FAKE-user-b:user',
+    'FAKE-user-c:user',
+  ]);
+  expect(fake.requests().some((each) => each.path === '/team/member_delete')).toBe(false);
+});
+
+test('a member with another role is updated through member_update, not re-added', async () => {
+  const live = teamRow({
+    members_with_roles: [{ role: 'admin', user_email: null, user_id: 'FAKE-user-a' }],
+    team_alias: 'FAKE-seats',
+    team_id: 'FAKE-team-seats',
+  });
+  const fake = startFakeTeamLitellm({ seed: [live] });
+  await stack(fake).deploy(
+    declare({ ...seats, members: [{ role: 'user', userId: 'FAKE-user-a' }] }),
+    {
+      adopt: true,
+    },
+  );
+  expect(fake.requests().some((each) => each.path === '/team/member_add')).toBe(false);
+  expect(fake.requests().filter((each) => each.path === '/team/member_update')).toHaveLength(1);
+  expect(roster(fake)).toEqual(['FAKE-user-a:user']);
+});
+
+test('an admin member on a proxy without a licence fails the deploy and leaves the roster as it was', async () => {
+  // ⛔ measured in the source: team_endpoints.py lines 2713-2723 and 3806-3810 (Enterprise)
+  const fake = startFakeTeamLitellm({ community: true });
+  await expect(
+    stack(fake).deploy(declare({ ...seats, members: [{ role: 'admin', userId: 'FAKE-user-a' }] })),
+  ).rejects.toThrow();
+  expect(roster(fake)).toEqual(['default_user_id:admin']);
+});
+
+test('the same declaration on a licensed proxy adds the admin', async () => {
+  const fake = startFakeTeamLitellm({ community: false });
+  await stack(fake).deploy(
+    declare({ ...seats, members: [{ role: 'admin', userId: 'FAKE-user-a' }] }),
+  );
+  expect(roster(fake)).toContain('FAKE-user-a:admin');
+});
+
+test('undeclared members leave the roster alone: no member_add and no read-back drift', async () => {
+  const fake = startFakeTeamLitellm();
+  await stack(fake).deploy(declare({ teamAlias: 'FAKE-seats', teamId: 'FAKE-team-seats' }));
+  expect(fake.requests().some((each) => each.path === '/team/member_add')).toBe(false);
+});
+
+test('removing the declaration RETAINS the team and its keys', async () => {
+  const fake = startFakeTeamLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(seats));
+  await same.deploy(Effect.void);
+  expect(fake.teams()).toHaveLength(1);
+  expect(fake.deletedKeys()).toEqual([]);
+});
+
+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 removes the team AND records that LiteLLM deleted its keys', async () => {
+  const fake = startFakeTeamLitellm({
+    seed: [teamRow({ team_alias: 'FAKE-seats', team_id: 'FAKE-team-seats' })],
+  });
+  await run(fake.fetch, deleteTeam('FAKE-team-seats'));
+  expect(fake.teams()).toEqual([]);
+  expect(fake.deletedKeys()).toEqual(['FAKE-team-seats']);
+});
+
+test('delete of a team that is gone is swallowed only because /team/list confirms it', async () => {
+  const fake = startFakeTeamLitellm();
+  await run(fake.fetch, deleteTeam('FAKE-team-gone'));
+  expect(fake.requests().map((each) => each.path)).toEqual(['/team/delete', '/team/list']);
+});
+
+test('a 404 for a team that is still listed (a swallowed database error) re-raises the ORIGINAL error', async () => {
+  // ⛔ measured in the source: /team/delete answers 404 for any exception on its lookup
+  const fake = startFakeTeamLitellm({
+    deleteLies: true,
+    seed: [teamRow({ team_alias: 'FAKE-seats', team_id: 'FAKE-team-seats' })],
+  });
+  await expect(run(fake.fetch, deleteTeam('FAKE-team-seats'))).rejects.toThrow();
+  expect(fake.teams()).toHaveLength(1);
+});

package/src/litellm/team-members.ts

@@ -0,0 +1,58 @@
+/**
+ * The member roster half of `LiteLLM.Team`: reading it, and what a declared roster still needs.
+ *
+ * ⛔ ADDITIVE ONLY, AND THAT IS A SAFETY RULE, NOT A SHORTCUT. `/team/member_delete` does not only take a
+ *   user off the roster: it also DELETES every virtual key that user created for the team
+ *   (`litellm_verificationtoken.delete_many` where `user_id` and `team_id`, `team_endpoints.py`
+ *   lines 3701-3748, 1.103.0). A seat's key would vanish with a roster edit. So a live member the declaration does not
+ *   list is never removed and never an error; `delete` on the team is the only removal, and it too
+ *   deletes the team's keys (team.ts).
+ * ★ A ROLE IS CHANGED THROUGH `/team/member_update`, which rewrites the roster entry under the team's
+ *   advisory lock. `admin` is Enterprise on both routes (`team_endpoints.py` lines 2713-2723 and
+ *   3806-3810): a proxy without a licence answers 400, the deploy fails with it, and the roster stays
+ *   as it was.
+ * ⚠️ A NEW USER ID CREATES A USER ROW (`add_new_member`), and only PROXY_ADMIN may name an id that has no
+ *   user yet (`_validate_member_user_id_provisioning`, 403 otherwise).
+ */
+import { asRow } from './registry-support.ts';
+import type { TeamMember, TeamMemberAttributes } from './team-types.ts';
+
+/** The roster of a `team_info` row. An entry with no `user_id` (an email-only invite) is skipped. */
+export const toMemberAttributes = (value: unknown): readonly TeamMemberAttributes[] => {
+  if (!Array.isArray(value)) return [];
+  const members: TeamMemberAttributes[] = [];
+  for (const entry of value) {
+    const row = asRow(entry);
+    if (typeof row?.['user_id'] === 'string' && row['user_id'] !== '') {
+      members.push({
+        role: typeof row['role'] === 'string' ? row['role'] : 'user',
+        userId: row['user_id'],
+      });
+    }
+  }
+  return members.sort((a, b) => a.userId.localeCompare(b.userId));
+};
+
+const roleOf = (member: TeamMember): string => member.role ?? 'user';
+
+/** Declared members that are not on the live roster at all. */
+export const membersToAdd = (
+  live: readonly TeamMemberAttributes[],
+  declared: readonly TeamMember[] | undefined,
+): readonly TeamMember[] =>
+  (declared ?? []).filter((member) => !live.some((each) => each.userId === member.userId));
+
+/** Declared members that are on the roster with another role. */
+export const roleChanges = (
+  live: readonly TeamMemberAttributes[],
+  declared: readonly TeamMember[] | undefined,
+): readonly TeamMember[] =>
+  (declared ?? []).filter((member) =>
+    live.some((each) => each.userId === member.userId && each.role !== roleOf(member)),
+  );
+
+/** Whether the declared roster is fully present. Extra live members do not count. */
+export const rosterPending = (
+  live: readonly TeamMemberAttributes[],
+  declared: readonly TeamMember[] | undefined,
+): boolean => membersToAdd(live, declared).length + roleChanges(live, declared).length > 0;

package/src/litellm/team-operations.ts

@@ -0,0 +1,90 @@
+/**
+ * The seven LiteLLM `/team/*` calls `LiteLLM.Team` uses, through the SDK's typed operations in
+ * `@distilled.cloud/litellm/team_management` (LiteLLM 1.103.0):
+ *
+ *   read    `getTeamInfoTeamInfo`                  GET  /team/info?team_id=
+ *   list    `listTeamTeamListGet`                  GET  /team/list            (only to confirm a delete)
+ *   create  `postNewTeamTeamNew`                   POST /team/new
+ *   update  `updateTeamTeamUpdatePost`             POST /team/update
+ *   add     `teamMemberAddTeamMemberAddPost`       POST /team/member_add
+ *   role    `teamMemberUpdateTeamMemberUpdatePost` POST /team/member_update
+ *   delete  `deleteTeamTeamDeletePost`             POST /team/delete
+ *
+ * ⛔ A "NOT FOUND" FROM `/team/info` IS NOT PROOF OF ABSENCE. Its lookup sits in `try … except Exception:
+ *   raise HTTPException(404)` (`team_endpoints.py`, 1.103.0), so a database error answers exactly like a
+ *   missing team, and `/team/delete` does the same. The SDK declares no 404 for `/team/info`; a 404
+ *   decodes at run time as its `NotFound` class, which `readTeam` tests by CLASS (registry-support.ts,
+ *   never a message). A wrong "absent" can only end in a `create`, which a duplicate team id turns into a
+ *   400 that fails the deploy; nothing is written on a guess.
+ * ⛔ DELETE DELETES THE TEAM'S KEYS (`delete_team`, `team_endpoints.py` line 4258: "delete team and associated team
+ *   keys", and `prisma_client.delete_data(team_id_list=…, table_name="key")` at line 4374). It is the single most destructive
+ *   call in this family, and the reason the resource defaults to `retain`.
+ * ★ DELETE IS IDEMPOTENT ONLY AFTER A REAL READ THAT CANNOT LIE. The SDK types `NotFound` for
+ *   `/team/delete` (a distilled patch), so it is caught with `catchTag`; but the route's own 404 also
+ *   covers a database error, so success is reported only when `/team/list` (a `find_many`, whose
+ *   failures are not swallowed) no longer has the id. A team still listed re-raises the ORIGINAL error.
+ */
+import * as team from '@distilled.cloud/litellm/team_management';
+import * as Effect from 'effect/Effect';
+import { throughFetch } from './operations.ts';
+import { asRow, bodyOf, isNotFound } from './registry-support.ts';
+import { toAttributes } from './team-form.ts';
+import type { TeamMember } from './team-types.ts';
+
+/** One team BY ID, or `undefined` when the proxy has no such team (see the file header). */
+export const readTeam = (teamId: string) =>
+  throughFetch(team.getTeamInfoTeamInfo({ team_id: teamId })).pipe(
+    Effect.map((response) => {
+      const row = toAttributes(bodyOf(response));
+      return row?.teamId === teamId ? row : undefined;
+    }),
+    Effect.catch((error) => (isNotFound(error) ? Effect.succeed(undefined) : Effect.fail(error))),
+  );
+
+export const createTeam = (body: team.PostNewTeamTeamNewRequest) =>
+  throughFetch(team.postNewTeamTeamNew(body)).pipe(Effect.asVoid);
+
+export const updateTeam = (body: team.UpdateTeamTeamUpdatePostRequest) =>
+  throughFetch(team.updateTeamTeamUpdatePost(body)).pipe(Effect.asVoid);
+
+/** One call adds every missing member; LiteLLM skips a user already on the roster. */
+export const addMembers = (teamId: string, members: readonly TeamMember[]) =>
+  throughFetch(
+    team.teamMemberAddTeamMemberAddPost({
+      member: members.map((member) => ({ role: member.role ?? 'user', user_id: member.userId })),
+      team_id: teamId,
+    }),
+  ).pipe(Effect.asVoid);
+
+export const setMemberRole = (teamId: string, member: TeamMember) =>
+  throughFetch(
+    team.teamMemberUpdateTeamMemberUpdatePost({
+      role: member.role ?? 'user',
+      team_id: teamId,
+      user_id: member.userId,
+    }),
+  ).pipe(Effect.asVoid);
+
+/** Every team id on the proxy. ⚠️ HEAVY: `/team/list` also loads each team's keys. Used only on the delete path. */
+const listTeamIds = () =>
+  throughFetch(team.listTeamTeamListGet({})).pipe(
+    Effect.map((response) => {
+      const rows: unknown = bodyOf(response);
+      return Array.isArray(rows)
+        ? rows.flatMap((row) => {
+            const id = asRow(row)?.['team_id'];
+            return typeof id === 'string' ? [id] : [];
+          })
+        : [];
+    }),
+  );
+
+export const deleteTeam = (teamId: string) =>
+  throughFetch(team.deleteTeamTeamDeletePost({ team_ids: [teamId] })).pipe(
+    Effect.asVoid,
+    Effect.catchTag('NotFound', (original) =>
+      listTeamIds().pipe(
+        Effect.flatMap((ids) => (ids.includes(teamId) ? Effect.fail(original) : Effect.void)),
+      ),
+    ),
+  );

package/src/litellm/team-permission.ts

@@ -0,0 +1,159 @@
+/**
+ * The `object_permission` half of `LiteLLM.Team`: reading it, comparing it, and the body that writes it.
+ *
+ * ★ THE WRITE IS A MERGE BY TOP-LEVEL FIELD (measured, `object_permission_utils.py` lines 114-118,
+ *   1.103.0, read from the live container): `prepare_object_permission_upsert` builds
+ *   `{**existing_fields, **new_object_permission}`, so a field the request leaves out KEEPS its stored
+ *   value, and a field sent as `[]` (or `{}`) REPLACES it with an empty one. That is what lets this
+ *   resource manage five fields and leave the other seven of an adopted team alone. docs.litellm.ai/docs/
+ *   mcp_grant_access says the same: "unset fields are left unchanged on update".
+ * ★ NULL AND `[]` ARE THE SAME "NOTHING GRANTED". A team that never had a grant reads `null` or `[]`
+ *   (`LiteLLM_ObjectPermissionTable` defaults), so both normalise to an empty list before comparing.
+ * ⚠️ `mcp_tool_permissions` CAN COME BACK AS A JSON STRING (it is stored through `safe_dumps` "for
+ *   GraphQL compatibility", and `_resolve_team_allowed_mcp_servers` itself handles both), so the read
+ *   accepts an object or a string.
+ * ⚠️ THE SERVER REFUSES, AND THIS FILE DOES NOT REPEAT IT: a name or alias that matches several MCP
+ *   servers cannot key `mcp_tool_permissions` (400, `reject_ambiguous_mcp_tool_permission_keys`), and a
+ *   non-admin caller cannot grant `all-proxy-mcpservers` (403). The one refusal made here is that
+ *   sentinel, because it silently grants every server on the proxy and is not something a declaration
+ *   should carry by accident.
+ */
+import type * as team from '@distilled.cloud/litellm/team_management';
+import {
+  asRow,
+  canonical,
+  firstBadEntry,
+  firstDuplicate,
+  isBlank,
+  sameSet,
+  stringsOf,
+} from './registry-support.ts';
+import type { TeamObjectPermission, TeamObjectPermissionAttributes } from './team-types.ts';
+
+/** The grant that reaches every MCP server on the proxy (`SpecialMCPServerName.all_proxy_servers`). */
+const ALL_PROXY_SERVERS = 'all-proxy-mcpservers';
+
+const LISTS = [
+  ['mcpServers', 'mcp_servers'],
+  ['mcpAccessGroups', 'mcp_access_groups'],
+  ['mcpToolsets', 'mcp_toolsets'],
+  ['blockedTools', 'blocked_tools'],
+] as const;
+
+const parseToolPermissions = (value: unknown): Readonly<Record<string, readonly string[]>> => {
+  const parsed: unknown = typeof value === 'string' ? safeJson(value) : value;
+  const row = asRow(parsed);
+  if (row === undefined) return {};
+  return Object.fromEntries(
+    Object.keys(row)
+      .sort()
+      .map((server) => [server, canonical(stringsOf(row[server]))]),
+  );
+};
+
+const safeJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+/** A live `object_permission` (or `null`) as this resource compares it. */
+export const toPermissionAttributes = (value: unknown): TeamObjectPermissionAttributes => {
+  const row = asRow(value);
+  return {
+    blockedTools: canonical(stringsOf(row?.['blocked_tools'])),
+    mcpAccessGroups: canonical(stringsOf(row?.['mcp_access_groups'])),
+    mcpServers: canonical(stringsOf(row?.['mcp_servers'])),
+    mcpToolPermissions: parseToolPermissions(row?.['mcp_tool_permissions']),
+    mcpToolsets: canonical(stringsOf(row?.['mcp_toolsets'])),
+  };
+};
+
+const sameToolPermissions = (
+  live: Readonly<Record<string, readonly string[]>>,
+  declared: Readonly<Record<string, readonly string[]>>,
+): boolean => {
+  const servers = Object.keys(declared).sort();
+  return (
+    sameSet(Object.keys(live), servers) &&
+    servers.every((server) => sameSet(live[server] ?? [], declared[server] ?? []))
+  );
+};
+
+/** Wire names of the DECLARED fields where live and declared disagree. An undeclared field never counts. */
+export const permissionDiffers = (
+  live: TeamObjectPermissionAttributes,
+  declared: TeamObjectPermission | undefined,
+): readonly string[] => {
+  if (declared === undefined) return [];
+  const fields: string[] = [];
+  for (const [prop, wire] of LISTS) {
+    const wanted = declared[prop];
+    if (wanted !== undefined && !sameSet(live[prop], wanted)) fields.push(wire);
+  }
+  if (
+    declared.mcpToolPermissions !== undefined &&
+    !sameToolPermissions(live.mcpToolPermissions, declared.mcpToolPermissions)
+  ) {
+    fields.push('mcp_tool_permissions');
+  }
+  return fields;
+};
+
+/**
+ * The `object_permission` body: the declared fields named in `only` (all of them when `only` is
+ * absent, for a create). ⛔ Never a `null`: a merge would read it as "clear", and the declaration said
+ * a list.
+ */
+export const permissionBody = (
+  declared: TeamObjectPermission,
+  only?: ReadonlySet<string>,
+): team.LiteLLMObjectPermissionBase => {
+  const body: Record<string, unknown> = {};
+  for (const [prop, wire] of LISTS) {
+    const wanted = declared[prop];
+    if (wanted !== undefined && (only === undefined || only.has(wire))) body[wire] = [...wanted];
+  }
+  if (
+    declared.mcpToolPermissions !== undefined &&
+    (only === undefined || only.has('mcp_tool_permissions'))
+  ) {
+    body['mcp_tool_permissions'] = Object.fromEntries(
+      Object.entries(declared.mcpToolPermissions).map(([server, tools]) => [server, [...tools]]),
+    );
+  }
+  return body as team.LiteLLMObjectPermissionBase;
+};
+
+/** The first reason a declared object permission is refused, or `undefined`. */
+export const permissionProblem = (
+  declared: TeamObjectPermission | undefined,
+): string | undefined => {
+  if (declared === undefined) return undefined;
+  for (const [prop] of LISTS) {
+    const values = declared[prop] ?? [];
+    const bad = firstBadEntry(values);
+    if (bad !== undefined)
+      return `\`objectPermission.${prop}\` has a blank or padded entry (${JSON.stringify(bad)})`;
+    const twice = firstDuplicate(values);
+    if (twice !== undefined)
+      return `\`objectPermission.${prop}\` lists ${JSON.stringify(twice)} twice`;
+  }
+  if ((declared.mcpServers ?? []).includes(ALL_PROXY_SERVERS)) {
+    return `\`objectPermission.mcpServers\` carries \`${ALL_PROXY_SERVERS}\`, which grants EVERY MCP server on the proxy; list the servers instead`;
+  }
+  for (const [server, tools] of Object.entries(declared.mcpToolPermissions ?? {})) {
+    if (isBlank(server) || server !== server.trim()) {
+      return '`objectPermission.mcpToolPermissions` has a blank or padded server key';
+    }
+    const bad = firstBadEntry(tools);
+    if (bad !== undefined)
+      return `\`objectPermission.mcpToolPermissions\` lists a blank or padded tool for ${server}`;
+    const twice = firstDuplicate(tools);
+    if (twice !== undefined)
+      return `\`objectPermission.mcpToolPermissions\` lists ${JSON.stringify(twice)} twice for ${server}`;
+  }
+  return undefined;
+};

package/src/litellm/team-read.test.ts

@@ -0,0 +1,89 @@
+/**
+ * `LiteLLM.Team`'s READ: what a lying `/team/info` and a proxy that drops an edit do to a deploy, and what
+ * the read must never copy. Over the fake proxy (`fake-team-litellm.ts`).
+ *
+ * ★ 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 { FAKE_BASE } from './fake-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import { type FakeTeamLitellm, startFakeTeamLitellm, teamRow } from './fake-team-litellm.ts';
+import { fakeStack } from './fake-stack.ts';
+import { LiteLLMTeam, teamHandlers } from './team.ts';
+import type { TeamProps } from './team-types.ts';
+
+const stack = (fake: FakeTeamLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: TeamProps, name = 'Estate') =>
+  Effect.gen(function* () {
+    yield* LiteLLMTeam(name, props);
+  });
+
+const estate: TeamProps = {
+  models: ['fake-code'],
+  teamAlias: 'FAKE-estate',
+  teamId: 'FAKE-team-estate',
+};
+
+test('a /team/info that lies 404 for an existing team ends in a loud 400 on the create, never a second team', async () => {
+  // ⛔ measured in the source: the lookup swallows every exception into a 404
+  const live = teamRow({ team_alias: 'FAKE-estate', team_id: 'FAKE-team-estate' });
+  const fake = startFakeTeamLitellm({ infoLies: true, seed: [live] });
+  await expect(stack(fake).deploy(declare(estate))).rejects.toThrow();
+  expect(fake.teams()).toHaveLength(1);
+});
+
+test('a proxy that keeps a stale field fails the deploy instead of claiming convergence', async () => {
+  const live = teamRow({ team_alias: 'FAKE-estate', team_id: 'FAKE-team-estate' });
+  // the fake has no update that drops a field, so declare one it cannot store: a blocked flag it ignores
+  const fake = startFakeTeamLitellm({ seed: [live] });
+  const original = fake.fetch;
+  const dropping = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    if (new URL(request.url).pathname === '/team/update') {
+      return new Response(JSON.stringify({ data: {} }), {
+        headers: { 'content-type': 'application/json' },
+        status: 200,
+      });
+    }
+    return original(input, init);
+  }) as typeof globalThis.fetch;
+  await expect(
+    fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, dropping).deploy(
+      declare({ blocked: true, teamAlias: 'FAKE-estate', teamId: 'FAKE-team-estate' }),
+      { adopt: true },
+    ),
+  ).rejects.toThrow();
+});
+
+test('nothing /team/info carries beyond the team itself can reach an attribute: keys, memberships, metadata', async () => {
+  // ⚠️ measured in the source: /team/info returns the team's keys (hashed tokens), its memberships and its
+  //   metadata, and this resource copies none of them
+  const live = teamRow({ team_alias: 'FAKE-estate', team_id: 'FAKE-team-estate' });
+  const fake = startFakeTeamLitellm({ leaky: true, seed: [live] });
+  const read = await Effect.runPromise(
+    teamHandlers
+      .read({ id: 'Estate', instanceId: 'i', olds: estate, output: undefined })
+      .pipe(
+        Effect.provide(FetchHttpClient.layer),
+        Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fake.fetch)),
+        Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+      ) as Effect.Effect<unknown, unknown, never>,
+  );
+  const text = JSON.stringify(read);
+  expect(text).toContain('FAKE-team-estate');
+  for (const secret of [
+    'FAKE-hashed-key',
+    'FAKE-callback-secret',
+    'FAKE-budget-secret',
+    'FAKE-membership-secret',
+  ]) {
+    expect(text).not.toContain(secret);
+  }
+});

package/src/litellm/team-types.ts

@@ -0,0 +1,106 @@
+/**
+ * What a `LiteLLM.Team` declares (props) and what is remembered about it (attributes).
+ *
+ * ★ A TEAM (`LiteLLM_TeamTable`, `/team/*`) owns keys, a member roster and an ACCESS CEILING: the
+ *   models it may use, and an `object_permission` that says which MCP servers, MCP access groups,
+ *   toolsets and tools its keys may reach. This resource manages exactly those, plus the team's
+ *   attachment to unified access groups. Nothing else about a team is touched.
+ * ⛔ THE TEAM'S `mcpServers` LIST IS A CEILING THAT INTERSECTS EVERY KEY'S OWN GRANTS. Where both a team
+ *   and a key list servers, the key reaches only the intersection
+ *   (`user_api_key_auth_mcp.py` lines 1482-1503, 1.103.0; docs.litellm.ai/docs/mcp_grant_access). A
+ *   NON-EMPTY team list therefore silently removes access from any key that was granted a server the
+ *   team does not list, and `[]` is "this level does not restrict". Grant servers on keys, toolsets
+ *   (`mcpToolsets`) or unified access groups, and leave the team's list `[]`, unless a ceiling is meant.
+ * ⛔ `models: []` MEANS EVERY MODEL, not none (LiteLLM's own field doc: "If empty, assumes all models
+ *   are allowed"). Compared only when declared.
+ * ⚠️ NOT MODELLED, on purpose, so an adopted team keeps them and none is ever sent: budgets and rate
+ *   limits (a team's `max_budget` is a HARD cap that 429s every key, the 2026-09-28 incident), the
+ *   metadata-backed fields (`guardrails`, `policies`, `tags`, `prompts`, `logging`,
+ *   `secret_manager_settings`, `allowed_passthrough_routes`, `team_member_key_duration`,
+ *   `disable_global_guardrails` — Enterprise, each a 403 when set on a proxy without a licence,
+ *   `common_utils.py` line 463 and `_types.py` lines 4843-4853), `model_max_budget` (Enterprise, 403,
+ *   `common_utils.py` lines 73-86), `metadata`, `router_settings`, `model_aliases`, organisation and the
+ *   other `object_permission` fields (vector stores, agents, models, search tools, skills).
+ */
+
+/** The object permission fields this resource manages. Each one is compared and sent ONLY WHEN DECLARED. */
+export interface TeamObjectPermission {
+  /**
+   * MCP servers the team's keys may reach, by `server_id`, alias or name. ⛔ A ceiling: see above.
+   * `[]` clears the list. The sentinel `all-proxy-mcpservers` is refused (Proxy admin only,
+   * `object_permission_utils.py` line 480, and it grants every server).
+   */
+  readonly mcpServers?: readonly string[];
+  /** MCP access group NAMES (the bare names on MCP server rows), not unified access group ids. */
+  readonly mcpAccessGroups?: readonly string[];
+  /** Toolset IDS (`toolset.toolsetId` of a `LiteLLM.Toolset`), not names. */
+  readonly mcpToolsets?: readonly string[];
+  /** Per-server tool allowlist: `server_id` (or alias or name) to the tools it may call. */
+  readonly mcpToolPermissions?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Tool names blocked for this team. ⚠️ The same list `POST /v1/tool/policy` writes for a team override,
+   * which is why `LiteLLM.ToolPolicy` does not model overrides.
+   */
+  readonly blockedTools?: readonly string[];
+}
+
+export interface TeamMember {
+  /** The user's `user_id`. A member is added by id only: an email would make LiteLLM allocate the id. */
+  readonly userId: string;
+  /** Default `user`. `admin` is an ENTERPRISE feature (400 on a proxy without a licence). */
+  readonly role?: 'user' | 'admin';
+}
+
+export interface TeamProps {
+  /** The team's alias. Not unique in LiteLLM (a policy attachment matches it as a pattern). Always compared. */
+  readonly teamAlias: string;
+  /**
+   * The team's id. Set it to ADOPT an existing team (it needs `--adopt`); without it a deterministic
+   * physical name is used for a create. ⛔ A DIFFERENT DECLARED ID IS A REPLACE (create-first, so the old
+   * team is only removed by an opt-in `RemovalPolicy.destroy()`, which also deletes its keys).
+   */
+  readonly teamId?: string;
+  /** Models the team's keys may use, compared as a set, only when declared. `[]` means every model. */
+  readonly models?: readonly string[];
+  /** Whether the team is blocked (every key stops). Compared only when declared. */
+  readonly blocked?: boolean;
+  /**
+   * Unified access group ids the team is attached to (`accessGroup.accessGroupId`), compared as a set,
+   * only when declared. LiteLLM mirrors it into each group's `assigned_team_ids` in the same transaction,
+   * so `LiteLLM.AccessGroup` does not declare teams.
+   */
+  readonly accessGroupIds?: readonly string[];
+  readonly objectPermission?: TeamObjectPermission;
+  /**
+   * Members that must exist, compared only when declared. ⛔ ADDITIVE ONLY: a live member the declaration
+   * does not list is left alone, because `/team/member_delete` also DELETES the keys that user created
+   * for the team (`team_endpoints.py` lines 3701-3748). A declared member with another role is updated.
+   * Adding a member creates its user row when the id is new. `/team/new` itself adds the caller as an
+   * `admin` member unless the proxy sets `disable_auto_add_proxy_admin_to_teams`.
+   */
+  readonly members?: readonly TeamMember[];
+}
+
+/** The object permission as a read returns it: every managed field, `[]` where LiteLLM holds none. */
+export interface TeamObjectPermissionAttributes {
+  readonly mcpServers: readonly string[];
+  readonly mcpAccessGroups: readonly string[];
+  readonly mcpToolsets: readonly string[];
+  readonly mcpToolPermissions: Readonly<Record<string, readonly string[]>>;
+  readonly blockedTools: readonly string[];
+}
+
+export interface TeamMemberAttributes {
+  readonly userId: string;
+  readonly role: string;
+}
+
+export interface TeamAttributes {
+  readonly teamId: string;
+  readonly teamAlias: string;
+  readonly models: readonly string[];
+  readonly blocked: boolean;
+  readonly accessGroupIds: readonly string[];
+  readonly objectPermission: TeamObjectPermissionAttributes;
+  readonly members: readonly TeamMemberAttributes[];
+}