@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/tool-policy.test.ts

@@ -0,0 +1,172 @@
+/**
+ * `LiteLLM.ToolPolicy` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-tool-litellm.ts`): the upsert create, no-op, adopt, partial update, replace and reset.
+ *
+ * ★ 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 FakeToolLitellm, startFakeToolLitellm, toolRow } from './fake-tool-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMToolPolicy } from './tool-policy.ts';
+import { resetToolPolicy } from './tool-policy-operations.ts';
+import type { ToolPolicyProps } from './tool-policy-types.ts';
+
+const stack = (fake: FakeToolLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: ToolPolicyProps, name = 'Search') =>
+  Effect.gen(function* () {
+    yield* LiteLLMToolPolicy(name, props);
+  });
+
+const search: ToolPolicyProps = {
+  inputPolicy: 'blocked',
+  outputPolicy: 'untrusted',
+  toolName: 'FAKE_search-query',
+};
+
+test('a tool never seen is created by the upsert, then a second deploy writes nothing', async () => {
+  const fake = startFakeToolLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(search))).toEqual({ Search: 'create' });
+  expect(fake.tools()[0]).toMatchObject({
+    input_policy: 'blocked',
+    output_policy: 'untrusted',
+    tool_name: 'FAKE_search-query',
+  });
+  expect(fake.bodies()[0]).toEqual({
+    input_policy: 'blocked',
+    output_policy: 'untrusted',
+    tool_name: 'FAKE_search-query',
+  });
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(search))).toEqual({ Search: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a tool LiteLLM already discovered is Unowned: refused without --adopt, and a matching row writes nothing', async () => {
+  const seen = toolRow({
+    input_policy: 'blocked',
+    tool_id: 'FAKE-tool-live',
+    tool_name: 'FAKE_search-query',
+  });
+  const fake = startFakeToolLitellm({ seed: [seen] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(search))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(search), { adopt: true }))).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('adopting a tool with another policy sends ONLY the field that differs, and leaves the other alone', async () => {
+  const seen = toolRow({
+    output_policy: 'trusted',
+    tool_id: 'FAKE-tool-live',
+    tool_name: 'FAKE_search-query',
+  });
+  const fake = startFakeToolLitellm({ seed: [seen] });
+  await stack(fake).deploy(declare({ inputPolicy: 'blocked', toolName: 'FAKE_search-query' }), {
+    adopt: true,
+  });
+  expect(fake.bodies()).toEqual([{ input_policy: 'blocked', tool_name: 'FAKE_search-query' }]);
+  // ★ the output policy was never declared, so it is not compared and not sent
+  expect(fake.tools()[0]?.['output_policy']).toBe('trusted');
+});
+
+test('a changed policy is an update that sends only the changed field', async () => {
+  const fake = startFakeToolLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(search));
+  expect(await same.deploy(declare({ ...search, inputPolicy: 'trusted' }))).toEqual({
+    Search: 'update',
+  });
+  expect(fake.bodies().at(-1)).toEqual({ input_policy: 'trusted', tool_name: 'FAKE_search-query' });
+});
+
+test('a different tool name is a replace, create-first, and the old tool is retained', async () => {
+  const fake = startFakeToolLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(search));
+  expect(await same.deploy(declare({ ...search, toolName: 'FAKE_other-tool' }))).toEqual({
+    Search: 'replace',
+  });
+  expect(fake.tools().map((row) => row['tool_name'])).toEqual([
+    'FAKE_search-query',
+    'FAKE_other-tool',
+  ]);
+});
+
+test('a proxy that drops a field fails the deploy instead of claiming success', async () => {
+  // ⚠️ the fake's own model of a route that loses one field — unmeasured at 1.103.0
+  const fake = startFakeToolLitellm({ dropsOutputPolicy: true });
+  await expect(
+    stack(fake).deploy(declare({ ...search, outputPolicy: 'trusted' })),
+  ).rejects.toThrow();
+});
+
+test('a read that 404s for a tool that exists ends in a write that succeeds, not in a wrong "absent"', async () => {
+  // ⛔ measured in the source: db_get_tool swallows every exception into None, which the route makes a 404
+  const seen = toolRow({ tool_id: 'FAKE-tool-live', tool_name: 'FAKE_search-query' });
+  const fake = startFakeToolLitellm({ getSwallowsErrors: true, seed: [seen] });
+  await expect(stack(fake).deploy(declare(search))).rejects.toThrow();
+  // the write reached the proxy (an upsert), and the read back is what refused to call it converged
+  expect(writesOf(fake.requests())).toEqual(['POST /v1/tool/policy']);
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { toolName: 'FAKE_search-query' },
+    { ...search, toolName: ' ' },
+    { ...search, toolName: 'list' },
+    { ...search, toolName: 'spend' },
+    { ...search, toolName: 'policy/options' },
+    { ...search, toolName: 'x/detail' },
+    { ...search, toolName: 'x/logs' },
+    { ...search, inputPolicy: 'dual_llm' as never },
+    { ...search, outputPolicy: 'blocked' as never },
+  ]) {
+    const fake = startFakeToolLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('removing the declaration RETAINS the tool row', async () => {
+  const fake = startFakeToolLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(search));
+  await same.deploy(Effect.void);
+  expect(fake.tools()[0]).toMatchObject({ input_policy: 'blocked' });
+});
+
+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 RESETS only the managed fields that are not already the default, and sends nothing for an unknown tool', async () => {
+  const seen = toolRow({
+    input_policy: 'blocked',
+    output_policy: 'trusted',
+    tool_id: 'FAKE-tool-live',
+    tool_name: 'FAKE_search-query',
+  });
+  const fake = startFakeToolLitellm({ seed: [seen] });
+  await run(fake.fetch, resetToolPolicy({ inputPolicy: 'blocked', toolName: 'FAKE_search-query' }));
+  // ★ only the declared field was reset; the undeclared output policy keeps what it had
+  expect(fake.tools()[0]).toMatchObject({ input_policy: 'untrusted', output_policy: 'trusted' });
+  const before = fake.requests().length;
+  await run(fake.fetch, resetToolPolicy({ inputPolicy: 'blocked', toolName: 'FAKE_search-query' }));
+  await run(fake.fetch, resetToolPolicy({ inputPolicy: 'blocked', toolName: 'FAKE_unknown' }));
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});

package/src/litellm/tool-policy.ts

@@ -0,0 +1,125 @@
+/**
+ * `LiteLLM.ToolPolicy` — the input and output trust policy of one tool in LiteLLM's tool registry
+ * (`LiteLLM_ToolTable`, `POST /v1/tool/policy`). Props, the enforcement precondition and what is left
+ * out: tool-policy-types.ts.
+ *
+ * ⛔ INERT WITHOUT THE `tool_policy` GUARDRAIL in the proxy's own config (tool-policy-types.ts).
+ * ★ ADOPT BY NAME. LiteLLM discovers tools itself, so a tool it has already seen has a live row with no
+ *   state: `Unowned`, which needs `--adopt` (a row at the defaults is adopted the same way). A tool
+ *   never seen has no row, and the write creates it.
+ * ★ `defaultRemovalPolicy: 'retain'` — there is no delete route. `delete` RESETS the managed fields to
+ *   `untrusted` (tool-policy-operations.ts), which for an `input_policy` of `blocked` re-opens a tool.
+ *   Opt in with `.pipe(RemovalPolicy.destroy())`.
+ * ⚠️ NO LICENCE GATE ON THESE ROUTES: `tool_management_endpoints.py` has no `premium_user` check
+ *   (1.103.0). Whether the `tool_policy` guardrail itself is licence-gated is UNVERIFIED (its module
+ *   has no `premium` reference either).
+ * ⛔ 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 {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryNotConvergedError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+import { differing, firstProblem, updateBody } from './tool-policy-form.ts';
+import { readTool, resetToolPolicy, writeToolPolicy } from './tool-policy-operations.ts';
+import type { ToolPolicyAttributes, ToolPolicyProps } from './tool-policy-types.ts';
+
+export type { ToolPolicyAttributes, ToolPolicyProps };
+export type { ToolInputPolicy, ToolOutputPolicy } from './tool-policy-types.ts';
+export type { RegistryError as ToolPolicyError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.ToolPolicy';
+
+export interface LiteLLMToolPolicy extends Resource<
+  'LiteLLM.ToolPolicy',
+  ToolPolicyProps,
+  ToolPolicyAttributes
+> {}
+
+export const LiteLLMToolPolicy = Resource<LiteLLMToolPolicy>('LiteLLM.ToolPolicy', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMToolPolicy = (value: unknown): value is LiteLLMToolPolicy =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.ToolPolicy';
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const toolPolicyHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({ olds, output }: { olds: ToolPolicyProps; output: ToolPolicyAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.toolName), firstProblem(olds));
+      }
+      const live = yield* readTool(output?.toolName ?? olds.toolName);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<ToolPolicyProps>;
+    output: ToolPolicyAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.toolName), firstProblem(news));
+      if (output === undefined) return undefined;
+      // The name is identity: a different tool is a different row.
+      if (news.toolName !== output.toolName) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ news }: { news: ToolPolicyProps }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.toolName), firstProblem(news));
+      // ★ THE TOOL THIS DECLARATION NAMES IS READ BY ITS NAME, never by a recorded one: a create-first
+      //   replace hands reconcile no output, and the name is the whole identity.
+      const before = yield* readTool(news.toolName);
+      if (before === undefined || differing(before, news).length > 0) {
+        yield* writeToolPolicy(updateBody(news, before));
+      }
+      const after = yield* readTool(news.toolName);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({ name: news.toolName, resource: RESOURCE }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.toolName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  /** ⛔ A RESET, not a removal: see tool-policy-operations.ts. */
+  delete: ({ olds }: { olds: ToolPolicyProps }) => resetToolPolicy(olds),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and a discovered tool row has no owner mark. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMToolPolicyProvider = () =>
+  Provider.effect(
+    LiteLLMToolPolicy,
+    Effect.succeed(LiteLLMToolPolicy.Provider.of(toolPolicyHandlers)),
+  );

package/src/litellm/toolset-form.ts

@@ -0,0 +1,104 @@
+/**
+ * Wire bodies, comparison and refusals for `LiteLLM.Toolset`, testable without a server.
+ *
+ * ★ THE EDIT IS A PARTIAL ONE (`update_mcp_toolset`, 1.103.0, read from the live container): an absent
+ *   field keeps its stored value, a `null` clears it, EXCEPT `toolset_name` and `tools`, where `null`
+ *   is a no-op ("a toolset always has a name and a tool list"). So `tools` is sent only as a list, and
+ *   emptying a selection is an explicit `[]`. This resource never sends a `null` name or list.
+ */
+import type * as mcp from '@distilled.cloud/litellm/mcp_management';
+import { asRow, firstBadEntry, isBlank, stringOrNull } from './registry-support.ts';
+import type { ToolsetAttributes, ToolsetProps, ToolsetTool } from './toolset-types.ts';
+
+const pairKey = (tool: ToolsetTool): string => JSON.stringify([tool.serverId, tool.toolName]);
+
+/** Sorted by server, then tool. A set has no order, so this is the form two reads compare in. */
+const canonicalTools = (tools: readonly ToolsetTool[]): readonly ToolsetTool[] =>
+  [...new Map(tools.map((tool) => [pairKey(tool), tool])).values()].sort((a, b) =>
+    pairKey(a).localeCompare(pairKey(b)),
+  );
+
+const sameTools = (left: readonly ToolsetTool[], right: readonly ToolsetTool[]): boolean => {
+  const a = canonicalTools(left).map(pairKey);
+  const b = canonicalTools(right).map(pairKey);
+  return a.length === b.length && a.every((each, index) => each === b[index]);
+};
+
+/** The first reason a declaration is refused, or `undefined`. Runs before any request. */
+export const firstProblem = (props: ToolsetProps): string | undefined => {
+  if (isBlank(props.toolsetName) || props.toolsetName !== props.toolsetName.trim()) {
+    return '`toolsetName` must be a non-blank name with no leading or trailing space';
+  }
+  if (props.toolsetName.includes('/')) {
+    return '`toolsetName` contains `/`: a toolset is served at /toolset/{toolset_name}/mcp, so that name can never be addressed';
+  }
+  if (props.description !== undefined && isBlank(props.description)) {
+    return '`description` is blank; leave it out to keep the live text';
+  }
+  if (!Array.isArray(props.tools)) return '`tools` must be a list (an empty one is `[]`)';
+  const bad =
+    firstBadEntry(props.tools.map((tool) => tool.serverId)) ??
+    firstBadEntry(props.tools.map((tool) => tool.toolName));
+  if (bad !== undefined)
+    return `a tool has a blank or padded serverId or toolName (${JSON.stringify(bad)})`;
+  const keys = props.tools.map(pairKey);
+  const twice = keys.find((key, index) => keys.indexOf(key) !== index);
+  if (twice !== undefined) return `\`tools\` lists ${twice} twice`;
+  return undefined;
+};
+
+/** One toolset row. `undefined` is "not a toolset": the caller refuses the whole answer. */
+export const toAttributes = (value: unknown): ToolsetAttributes | undefined => {
+  const row = asRow(value);
+  if (row === undefined) return undefined;
+  const toolsetId = row['toolset_id'];
+  const toolsetName = row['toolset_name'];
+  if (typeof toolsetId !== 'string' || typeof toolsetName !== 'string') return undefined;
+  const tools: ToolsetTool[] = [];
+  for (const entry of Array.isArray(row['tools']) ? row['tools'] : []) {
+    const pair = asRow(entry);
+    if (typeof pair?.['server_id'] === 'string' && typeof pair['tool_name'] === 'string') {
+      tools.push({ serverId: pair['server_id'], toolName: pair['tool_name'] });
+    }
+  }
+  return {
+    description: stringOrNull(row['description']),
+    toolsetId,
+    toolsetName,
+    tools: canonicalTools(tools),
+  };
+};
+
+/** Wire names of the fields where live and declared disagree. */
+export const differing = (live: ToolsetAttributes, props: ToolsetProps): readonly string[] => {
+  const fields: string[] = [];
+  if (live.toolsetName !== props.toolsetName) fields.push('toolset_name');
+  if (props.description !== undefined && live.description !== props.description) {
+    fields.push('description');
+  }
+  if (!sameTools(live.tools, props.tools)) fields.push('tools');
+  return fields;
+};
+
+const wireTools = (tools: readonly ToolsetTool[]): mcp.MCPToolsetTool[] =>
+  tools.map((tool) => ({ server_id: tool.serverId, tool_name: tool.toolName }));
+
+export const createBody = (props: ToolsetProps): mcp.AddMcpToolsetV1McpToolsetPostRequest => ({
+  toolset_name: props.toolsetName,
+  tools: wireTools(props.tools),
+  ...(props.description === undefined ? {} : { description: props.description }),
+});
+
+/** Only what differs, and never a `null` name or list (LiteLLM ignores those). */
+export const updateBody = (
+  props: ToolsetProps,
+  live: ToolsetAttributes,
+): mcp.EditMcpToolsetV1McpToolsetPutRequest => {
+  const changed = new Set(differing(live, props));
+  return {
+    toolset_id: live.toolsetId,
+    ...(changed.has('toolset_name') ? { toolset_name: props.toolsetName } : {}),
+    ...(changed.has('description') ? { description: props.description ?? null } : {}),
+    ...(changed.has('tools') ? { tools: wireTools(props.tools) } : {}),
+  };
+};

package/src/litellm/toolset-operations.ts

@@ -0,0 +1,90 @@
+/**
+ * The five LiteLLM `/v1/mcp/toolset*` calls `LiteLLM.Toolset` uses, through the SDK's typed operations
+ * in `@distilled.cloud/litellm/mcp_management` (LiteLLM 1.103.0):
+ *
+ *   list    `fetchMcpToolsetsV1McpToolsetGet`             GET    /v1/mcp/toolset
+ *   read    `fetchMcpToolsetV1McpToolsetToolsetIdGet`     GET    /v1/mcp/toolset/{toolset_id}
+ *   create  `addMcpToolsetV1McpToolsetPost`               POST   /v1/mcp/toolset          (201)
+ *   update  `editMcpToolsetV1McpToolsetPut`               PUT    /v1/mcp/toolset
+ *   delete  `removeMcpToolsetV1McpToolsetToolsetIdDelete` DELETE /v1/mcp/toolset/{toolset_id} (202, no body)
+ *
+ * ⛔ THE LIST CANNOT PROVE ABSENCE, THE BY-ID READ CAN (`mcp_management_endpoints.py` and
+ *   `toolset_db.py`, read from the live 1.103.0 container). `list_mcp_toolsets` wraps its query in
+ *   `except Exception: … return []`, so a database error answers an EMPTY LIST with a 200; and the
+ *   route narrows the answer to the caller's granted toolsets unless the caller is an admin. The by-id
+ *   route reads the table (`get_mcp_toolset`, a `find_unique`) and answers 404 only for a missing row.
+ *   So the list is used ONLY to adopt by name, and everything else reads by id. A wrong "absent" from
+ *   the list can only end in a create, which a unique name turns into a 409 that fails the deploy.
+ * ⛔ NO MESSAGE SNIFFING. `readToolset` tests the SDK's `NotFound` CLASS (registry-support.ts) and
+ *   nothing else; a 401, a 403 or a dead network propagates, and is never read as absence.
+ * ★ DELETE IS IDEMPOTENT BY A REAL READ: a failed DELETE is swallowed only when a by-id read says the
+ *   row is gone. A 403 (only PROXY_ADMIN may delete) leaves it live, so it re-raises the original.
+ */
+import * as mcp from '@distilled.cloud/litellm/mcp_management';
+import * as Effect from 'effect/Effect';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+import { LitellmRegistryUnreadableError } from './registry-errors.ts';
+import { bodyOf, isNotFound } from './registry-support.ts';
+import { toAttributes } from './toolset-form.ts';
+import type { ToolsetAttributes } from './toolset-types.ts';
+
+const RESOURCE = 'LiteLLM.Toolset';
+
+/** ⚠️ NOT PROOF OF ABSENCE: see the file header. Adopt-by-name only. */
+export const listToolsets = (): Effect.Effect<
+  readonly ToolsetAttributes[],
+  mcp.FetchMcpToolsetsV1McpToolsetGetError | LitellmRegistryUnreadableError,
+  LitellmOpContext
+> =>
+  throughFetch(mcp.fetchMcpToolsetsV1McpToolsetGet({})).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 ToolsetAttributes[])
+        : Effect.fail(
+            new LitellmRegistryUnreadableError({
+              reason: 'a row has no id or name',
+              resource: RESOURCE,
+            }),
+          );
+    }),
+  );
+
+/**
+ * One toolset BY ID, from the table, or `undefined` when the proxy has no such row. The row must carry
+ * the id asked for; anything else the proxy answers is "no such row".
+ */
+export const readToolset = (toolsetId: string) =>
+  throughFetch(mcp.fetchMcpToolsetV1McpToolsetToolsetIdGet({ toolset_id: toolsetId })).pipe(
+    Effect.map((response) => {
+      const row = toAttributes(bodyOf(response));
+      return row?.toolsetId === toolsetId ? row : undefined;
+    }),
+    Effect.catch((error) => (isNotFound(error) ? Effect.succeed(undefined) : Effect.fail(error))),
+  );
+
+/** The created row, which carries the id LiteLLM issued. `undefined` when the answer is not a toolset. */
+export const createToolset = (body: mcp.AddMcpToolsetV1McpToolsetPostRequest) =>
+  throughFetch(mcp.addMcpToolsetV1McpToolsetPost(body)).pipe(
+    Effect.map((response) => toAttributes(bodyOf(response))),
+  );
+
+export const updateToolset = (body: mcp.EditMcpToolsetV1McpToolsetPutRequest) =>
+  throughFetch(mcp.editMcpToolsetV1McpToolsetPut(body)).pipe(Effect.asVoid);
+
+export const deleteToolset = (toolsetId: string) =>
+  throughFetch(mcp.removeMcpToolsetV1McpToolsetToolsetIdDelete({ toolset_id: toolsetId })).pipe(
+    Effect.asVoid,
+    Effect.catch((original) =>
+      readToolset(toolsetId).pipe(
+        Effect.catch(() => Effect.fail(original)),
+        Effect.flatMap((row) => (row === undefined ? Effect.void : Effect.fail(original))),
+      ),
+    ),
+  );

package/src/litellm/toolset-types.ts

@@ -0,0 +1,47 @@
+/**
+ * What a `LiteLLM.Toolset` declares (props) and what is remembered about it (attributes).
+ *
+ * ★ A TOOLSET IS A NAMED SELECTION OF `{ server_id, tool_name }` PAIRS drawn from one or more MCP
+ *   servers (`LiteLLM_MCPToolsetTable`, `/v1/mcp/toolset`; docs.litellm.ai/docs/mcp_toolsets). A key or
+ *   team is granted one through `object_permission.mcp_toolsets`, which holds the toolset's ID
+ *   (`fetch_mcp_toolsets` filters `list_mcp_toolsets(toolset_ids=…)`), so `LiteLLM.Team` takes
+ *   `toolset.toolsetId`, not the name.
+ * ⚠️ THE ID IS THE PROXY'S. `create_mcp_toolset` sets `toolset_id = str(uuid.uuid4())` and the create
+ *   request has no id field, so nothing here can pick one. The id LiteLLM answers is what is recorded.
+ * ★ THE NAME IS A URL SEGMENT. A toolset is served at `/toolset/{toolset_name}/mcp`
+ *   (`proxy_server.py` line 19346) and `litellm_proxy/mcp/<toolset_name>` (docs), so a name with a `/`
+ *   can never be addressed. LiteLLM itself accepts one; the refusal is this package's.
+ * ⚠️ NOT MODELLED: nothing beyond name, description and tools — the table has no other column that a
+ *   write reaches.
+ */
+export interface ToolsetTool {
+  /** The MCP server's `server_id`. Declare it as `server.serverId` (a `LiteLLM.MCPServer`). */
+  readonly serverId: string;
+  /** The tool's name on that server, as the server lists it. */
+  readonly toolName: string;
+}
+
+export interface ToolsetProps {
+  /**
+   * The toolset's name, and the way an existing row is ADOPTED. `toolset_name` is unique in the table
+   * (a create or rename onto a taken name is a 409), so the match is exact. Changing it is an update of
+   * the same row, never a replace.
+   */
+  readonly toolsetName: string;
+  /** Compared only when declared: adopting a row never clears text a person wrote. Blank is refused. */
+  readonly description?: string;
+  /**
+   * The selection, compared as a SET of pairs and ALWAYS compared: it is what a caller may reach, so an
+   * adopted toolset with more than declared is corrected. `[]` is an explicit empty selection (LiteLLM
+   * keeps an empty list only when it is sent as one). Required, so the declaration always says.
+   */
+  readonly tools: readonly ToolsetTool[];
+}
+
+export interface ToolsetAttributes {
+  readonly toolsetId: string;
+  readonly toolsetName: string;
+  readonly description: string | null;
+  /** Sorted by server, then tool, so two reads of one row are equal. */
+  readonly tools: readonly ToolsetTool[];
+}