@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/team.test.ts

@@ -0,0 +1,206 @@
+/**
+ * `LiteLLM.Team` through Alchemy's real Plan and Apply over the fake proxy (`fake-team-litellm.ts`):
+ * create, no-op, adopt, the partial update, the object-permission merge and the refusals. The roster
+ * and delete are `team-members.test.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 * as Effect from 'effect/Effect';
+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 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 = {
+  blocked: false,
+  models: ['fake-code', 'fake-flash'],
+  objectPermission: {
+    mcpServers: [],
+    mcpToolsets: ['FAKE-toolset-1'],
+    mcpToolPermissions: { FAKE_docs: ['search'] },
+  },
+  teamAlias: 'FAKE-estate',
+  teamId: 'FAKE-team-estate',
+};
+
+test('creates a team with its ceiling, then a second deploy writes nothing', async () => {
+  const fake = startFakeTeamLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'create' });
+  expect(fake.teams()[0]).toMatchObject({
+    blocked: false,
+    models: ['fake-code', 'fake-flash'],
+    object_permission: {
+      mcp_servers: [],
+      mcp_tool_permissions: { FAKE_docs: ['search'] },
+      mcp_toolsets: ['FAKE-toolset-1'],
+    },
+    team_alias: 'FAKE-estate',
+    team_id: 'FAKE-team-estate',
+  });
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('an undeclared team id is a deterministic physical name, never a proxy uuid', async () => {
+  const fake = startFakeTeamLitellm();
+  await stack(fake).deploy(declare({ teamAlias: 'FAKE-named' }));
+  expect(String(fake.teams()[0]?.['team_id'])).toMatch(/^[a-z0-9-]+$/);
+});
+
+test('an undeclared field is never sent: a create with only an alias sends no models, no block, no permission', async () => {
+  const fake = startFakeTeamLitellm();
+  await stack(fake).deploy(declare({ teamAlias: 'FAKE-bare', teamId: 'FAKE-team-bare' }));
+  expect(fake.bodies()[0]).toEqual({ team_alias: 'FAKE-bare', team_id: 'FAKE-team-bare' });
+});
+
+test('`models: []` is sent as an empty list (it means EVERY model), not dropped', async () => {
+  const fake = startFakeTeamLitellm();
+  await stack(fake).deploy(
+    declare({ models: [], teamAlias: 'FAKE-open', teamId: 'FAKE-team-open' }),
+  );
+  expect(fake.bodies()[0]).toMatchObject({ models: [] });
+});
+
+test('a live team is Unowned: refused without --adopt, adopted by id with it, and a match writes nothing', async () => {
+  const live = teamRow({
+    blocked: false,
+    models: ['fake-flash', 'fake-code'],
+    object_permission: {
+      mcp_servers: [],
+      mcp_tool_permissions: { FAKE_docs: ['search'] },
+      mcp_toolsets: ['FAKE-toolset-1'],
+    },
+    team_alias: 'FAKE-estate',
+    team_id: 'FAKE-team-estate',
+  });
+  const fake = startFakeTeamLitellm({ 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('the object permission is a MERGE: adopting a team corrects the declared field and leaves the others', async () => {
+  const live = teamRow({
+    models: ['fake-code'],
+    object_permission: {
+      mcp_servers: ['FAKE-server-a'],
+      mcp_toolsets: ['FAKE-toolset-1'],
+      vector_stores: ['FAKE-vector'],
+    },
+    team_alias: 'FAKE-estate',
+    team_id: 'FAKE-team-estate',
+  });
+  const fake = startFakeTeamLitellm({ seed: [live] });
+  await stack(fake).deploy(
+    declare({
+      objectPermission: { mcpServers: [] },
+      teamAlias: 'FAKE-estate',
+      teamId: 'FAKE-team-estate',
+    }),
+    { adopt: true },
+  );
+  // ★ the red-team fact: a non-empty team `mcp_servers` intersects every key's grants, so it is cleared
+  expect(fake.bodies()[0]).toEqual({
+    object_permission: { mcp_servers: [] },
+    team_id: 'FAKE-team-estate',
+  });
+  expect(fake.teams()[0]?.['object_permission']).toEqual({
+    mcp_servers: [],
+    mcp_toolsets: ['FAKE-toolset-1'],
+    vector_stores: ['FAKE-vector'],
+  });
+  expect(fake.teams()[0]?.['models']).toEqual(['fake-code']);
+});
+
+test('a changed field is an update that sends the id and ONLY what changed', async () => {
+  const fake = startFakeTeamLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  const planned = await same.deploy(
+    declare({
+      ...estate,
+      blocked: true,
+      objectPermission: { ...estate.objectPermission, blockedTools: ['FAKE_docs-danger'] },
+    }),
+  );
+  expect(planned).toEqual({ Estate: 'update' });
+  expect(fake.bodies().at(-1)).toEqual({
+    blocked: true,
+    object_permission: { blocked_tools: ['FAKE_docs-danger'] },
+    team_id: 'FAKE-team-estate',
+  });
+});
+
+test('a proxy that hands mcp_tool_permissions back as a JSON string is still a no-op', async () => {
+  const fake = startFakeTeamLitellm({ toolPermissionsAsString: true });
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('access group ids are compared as a set, and only when declared', async () => {
+  const fake = startFakeTeamLitellm();
+  const same = stack(fake);
+  await same.deploy(declare({ ...estate, accessGroupIds: ['FAKE-group-b', 'FAKE-group-a'] }));
+  expect(
+    await same.deploy(declare({ ...estate, accessGroupIds: ['FAKE-group-a', 'FAKE-group-b'] })),
+  ).toEqual({
+    Estate: 'noop',
+  });
+  expect(await same.deploy(declare({ ...estate, accessGroupIds: ['FAKE-group-a'] }))).toEqual({
+    Estate: 'update',
+  });
+  expect(fake.bodies().at(-1)).toEqual({
+    access_group_ids: ['FAKE-group-a'],
+    team_id: 'FAKE-team-estate',
+  });
+});
+
+test('a changed declared team id is a replace, create-first, and the old team is retained', async () => {
+  const fake = startFakeTeamLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  expect(await same.deploy(declare({ ...estate, teamId: 'FAKE-team-other' }))).toEqual({
+    Estate: 'replace',
+  });
+  expect(fake.teams().map((row) => row['team_id'])).toEqual([
+    'FAKE-team-estate',
+    'FAKE-team-other',
+  ]);
+  expect(fake.deletedKeys()).toEqual([]);
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { ...estate, teamAlias: ' ' },
+    { ...estate, teamId: ' padded' },
+    { ...estate, models: ['a', 'a'] },
+    { ...estate, accessGroupIds: [''] },
+    { ...estate, objectPermission: { mcpServers: ['all-proxy-mcpservers'] } },
+    { ...estate, objectPermission: { mcpToolsets: ['x', 'x'] } },
+    { ...estate, objectPermission: { mcpToolPermissions: { ' ': ['a'] } } },
+    { ...estate, members: [{ userId: 'a' }, { userId: 'a' }] },
+    { ...estate, members: [{ role: 'owner' as never, userId: 'a' }] },
+  ]) {
+    const fake = startFakeTeamLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});

package/src/litellm/team.ts

@@ -0,0 +1,159 @@
+/**
+ * `LiteLLM.Team` — one row of LiteLLM's team table (`/team/*`): the models, MCP grants and roster that
+ * bound every key of a team. Props, the MCP ceiling and everything left out: team-types.ts.
+ *
+ * ★ ADOPT BY ID. `teamId` names the live team; without it a deterministic physical name is used. A
+ *   team with that id and no state is `Unowned`, so it needs `--adopt`. (`team_alias` is not unique, so
+ *   it cannot identify a team.)
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a team DELETES EVERY KEY OF THE TEAM (team-operations.ts).
+ *   Opt in with `.pipe(RemovalPolicy.destroy())`, knowing that.
+ * ★ A DECLARED FIELD IS THE TRUTH, AN UNDECLARED ONE IS LEFT ALONE. `models`, `blocked`,
+ *   `accessGroupIds`, each object-permission field and the roster are compared and sent only when
+ *   declared; the update is a partial one, and the object permission a merge by field (team-permission.ts),
+ *   so an adopted team keeps everything this resource does not manage.
+ * ⛔ THE ROSTER IS ADDITIVE ONLY (team-members.ts): removing a member would delete that user's keys.
+ * ⚠️ NO LICENCE GATE ON THE FIELDS IT MANAGES except a member's `admin` role (Enterprise, 400 without a
+ *   licence: `team_endpoints.py` lines 2713-2723, 3806-3810). Every other Enterprise team field is one
+ *   this resource never sends (team-types.ts lists them).
+ * ⛔ 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 { createPhysicalName } from 'alchemy/PhysicalName';
+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 { createBody, differing, firstProblem, updateBody } from './team-form.ts';
+import { membersToAdd, roleChanges } from './team-members.ts';
+import {
+  addMembers,
+  createTeam,
+  deleteTeam,
+  readTeam,
+  setMemberRole,
+  updateTeam,
+} from './team-operations.ts';
+import type { TeamAttributes, TeamProps } from './team-types.ts';
+
+export type { TeamAttributes, TeamProps };
+export type {
+  TeamMember,
+  TeamMemberAttributes,
+  TeamObjectPermission,
+  TeamObjectPermissionAttributes,
+} from './team-types.ts';
+export type { RegistryError as TeamError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.Team';
+
+export interface LiteLLMTeam extends Resource<'LiteLLM.Team', TeamProps, TeamAttributes> {}
+
+export const LiteLLMTeam = Resource<LiteLLMTeam>('LiteLLM.Team', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMTeam = (value: unknown): value is LiteLLMTeam =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Team';
+
+/** The team id: the recorded one, else the declared one, else a deterministic physical name. */
+const idOf = (
+  id: string,
+  instanceId: string,
+  props: TeamProps,
+  output: TeamAttributes | undefined,
+) =>
+  output?.teamId !== undefined
+    ? Effect.succeed(output.teamId)
+    : props.teamId !== undefined
+      ? Effect.succeed(props.teamId)
+      : createPhysicalName({ id, instanceId, lowercase: true, maxLength: 64 });
+
+type Args<P> = { id: string; instanceId: string; output: TeamAttributes | undefined } & P;
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const teamHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({ id, instanceId, olds, output }: Args<{ olds: TeamProps }>) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.teamAlias), firstProblem(olds));
+      }
+      const live = yield* readTeam(yield* idOf(id, instanceId, olds, output));
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({ news, output }: { news: Input<TeamProps>; output: TeamAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.teamAlias), firstProblem(news));
+      if (output === undefined) return undefined;
+      // The id is identity: a different declared id is a different team.
+      if (news.teamId !== undefined && news.teamId !== output.teamId) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ id, instanceId, news, output }: Args<{ news: TeamProps }>) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.teamAlias), firstProblem(news));
+      const teamId = yield* idOf(id, instanceId, news, output);
+      const before = yield* readTeam(teamId);
+      if (before === undefined) yield* createTeam(createBody(news, teamId));
+      else {
+        const body = updateBody(news, before);
+        if (body !== undefined) yield* updateTeam(body);
+      }
+
+      // The roster, additively (team-members.ts). Read after the team write so a fresh team is seen.
+      if (news.members !== undefined) {
+        const live = yield* readTeam(teamId);
+        if (live === undefined) {
+          return yield* Effect.fail(
+            new LitellmRegistryAbsentAfterWriteError({ name: news.teamAlias, resource: RESOURCE }),
+          );
+        }
+        const missing = membersToAdd(live.members, news.members);
+        if (missing.length > 0) yield* addMembers(teamId, missing);
+        for (const member of roleChanges(live.members, news.members)) {
+          yield* setMemberRole(teamId, member);
+        }
+      }
+
+      const after = yield* readTeam(teamId);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({ name: news.teamAlias, resource: RESOURCE }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.teamAlias,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: TeamAttributes }) => deleteTeam(output.teamId),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMTeamProvider = () =>
+  Provider.effect(LiteLLMTeam, Effect.succeed(LiteLLMTeam.Provider.of(teamHandlers)));

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

@@ -0,0 +1,94 @@
+/**
+ * Wire bodies, comparison and refusals for `LiteLLM.ToolPolicy`, testable without a server.
+ *
+ * ★ THE WRITE IS AN UPSERT. `update_tool_policy` (`db/tool_registry_writer.py`, 1.103.0) upserts on
+ *   `tool_name`: it CREATES the row when the tool has not been seen (a sent field, else `untrusted`),
+ *   and on an existing row updates only the fields that are sent. So there is no separate create.
+ */
+import type * as tools from '@distilled.cloud/litellm/tools';
+import { asRow, isBlank } from './registry-support.ts';
+import {
+  INPUT_POLICIES,
+  OUTPUT_POLICIES,
+  type ToolPolicyAttributes,
+  type ToolPolicyProps,
+} from './tool-policy-types.ts';
+
+/** Names the route table hands to another route before `GET /v1/tool/{tool_name:path}` sees them. */
+const shadowed = (name: string): boolean =>
+  name === 'list' ||
+  name === 'spend' ||
+  name === 'policy/options' ||
+  ['/detail', '/logs'].some((suffix) => name.endsWith(suffix));
+
+/** The first reason a declaration is refused, or `undefined`. Runs before any request. */
+export const firstProblem = (props: ToolPolicyProps): string | undefined => {
+  if (isBlank(props.toolName) || props.toolName !== props.toolName.trim()) {
+    return '`toolName` must be a non-blank name with no leading or trailing space';
+  }
+  if (shadowed(props.toolName)) {
+    return '`toolName` is one the /v1/tool route table answers itself (list, spend, policy/options, …/detail, …/logs), so it could never be read back';
+  }
+  if (props.inputPolicy === undefined && props.outputPolicy === undefined) {
+    return 'declare `inputPolicy`, `outputPolicy` or both (LiteLLM answers 400 to neither)';
+  }
+  if (props.inputPolicy !== undefined && !INPUT_POLICIES.includes(props.inputPolicy)) {
+    return `\`inputPolicy\` must be one of ${INPUT_POLICIES.join(', ')}`;
+  }
+  if (props.outputPolicy !== undefined && !OUTPUT_POLICIES.includes(props.outputPolicy)) {
+    return `\`outputPolicy\` must be one of ${OUTPUT_POLICIES.join(', ')}`;
+  }
+  return undefined;
+};
+
+/** One tool row. `undefined` is "not a tool row". A missing policy reads as LiteLLM's default. */
+export const toAttributes = (value: unknown): ToolPolicyAttributes | undefined => {
+  const row = asRow(value);
+  if (row === undefined) return undefined;
+  const toolId = row['tool_id'];
+  const toolName = row['tool_name'];
+  if (typeof toolId !== 'string' || typeof toolName !== 'string') return undefined;
+  const policy = (field: string): string =>
+    typeof row[field] === 'string' && row[field] !== '' ? row[field] : 'untrusted';
+  return {
+    inputPolicy: policy('input_policy'),
+    outputPolicy: policy('output_policy'),
+    toolId,
+    toolName,
+  };
+};
+
+/** Wire names of the DECLARED fields where live and declared disagree. */
+export const differing = (
+  live: ToolPolicyAttributes,
+  props: ToolPolicyProps,
+): readonly string[] => {
+  const fields: string[] = [];
+  if (props.inputPolicy !== undefined && live.inputPolicy !== props.inputPolicy) {
+    fields.push('input_policy');
+  }
+  if (props.outputPolicy !== undefined && live.outputPolicy !== props.outputPolicy) {
+    fields.push('output_policy');
+  }
+  return fields;
+};
+
+/**
+ * The write: the declared fields that differ (all declared ones when the tool row is new). ⚠️ NEVER a
+ * `team_id` or `key_hash` — those turn the call into an override of another object's `blocked_tools`.
+ */
+export const updateBody = (
+  props: ToolPolicyProps,
+  live: ToolPolicyAttributes | undefined,
+): tools.UpdateToolPolicyV1ToolPolicyPostRequest => {
+  const changed = live === undefined ? undefined : new Set(differing(live, props));
+  return {
+    tool_name: props.toolName,
+    ...(props.inputPolicy !== undefined && (changed === undefined || changed.has('input_policy'))
+      ? { input_policy: props.inputPolicy }
+      : {}),
+    ...(props.outputPolicy !== undefined && (changed === undefined || changed.has('output_policy'))
+      ? { output_policy: props.outputPolicy }
+      : {}),
+  };
+};

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

@@ -0,0 +1,58 @@
+/**
+ * The two LiteLLM `/v1/tool*` calls `LiteLLM.ToolPolicy` uses, through the SDK's typed operations in
+ * `@distilled.cloud/litellm/tools` (LiteLLM 1.103.0):
+ *
+ *   read   `getToolV1ToolToolNameGet`       GET  /v1/tool/{tool_name:path}
+ *   write  `updateToolPolicyV1ToolPolicyPost`  POST /v1/tool/policy   (an UPSERT on tool_name)
+ *
+ * ⛔ A READ THAT SAYS "NOT FOUND" IS NOT PROOF OF ABSENCE. `db_get_tool` (`db/tool_registry_writer.py`)
+ *   wraps its query in `except Exception: log; return None`, and the route turns `None` into a 404, so a
+ *   database error reads exactly like a tool that was never seen. Nothing here depends on it: the write
+ *   is an upsert, so a wrong "absent" ends in a write that succeeds or fails loudly, and the read back
+ *   after it is what the deploy reports.
+ * ⛔ THERE IS NO DELETE ROUTE for a tool row or for its global policy: `DELETE /v1/tool/{name}/overrides`
+ *   removes only a team or key override. So this resource's delete RESETS the fields it managed to
+ *   LiteLLM's default (`untrusted`), it does not remove a row. It is a write, so it runs only when the
+ *   stack opts in (`retain` is the default), and only for a field that is not already the default.
+ * ⛔ NO MESSAGE SNIFFING: absence is the SDK's `NotFound` CLASS (registry-support.ts) and nothing else.
+ */
+import * as tools from '@distilled.cloud/litellm/tools';
+import * as Effect from 'effect/Effect';
+import { throughFetch } from './operations.ts';
+import { bodyOf, isNotFound } from './registry-support.ts';
+import { toAttributes } from './tool-policy-form.ts';
+import { DEFAULT_TOOL_POLICY, type ToolPolicyProps } from './tool-policy-types.ts';
+
+/** One tool by name, or `undefined` when the proxy has no such row (see the file header). */
+export const readTool = (toolName: string) =>
+  throughFetch(tools.getToolV1ToolToolNameGet({ tool_name: toolName })).pipe(
+    Effect.map((response) => {
+      const row = toAttributes(bodyOf(response));
+      return row?.toolName === toolName ? row : undefined;
+    }),
+    Effect.catch((error) => (isNotFound(error) ? Effect.succeed(undefined) : Effect.fail(error))),
+  );
+
+export const writeToolPolicy = (body: tools.UpdateToolPolicyV1ToolPolicyPostRequest) =>
+  throughFetch(tools.updateToolPolicyV1ToolPolicyPost(body)).pipe(Effect.asVoid);
+
+/**
+ * The delete: reset each managed field that is not already the default, and nothing else. A tool the
+ * proxy does not know, or one already at the defaults, sends no request (an empty body would be a 400).
+ */
+export const resetToolPolicy = (props: ToolPolicyProps) =>
+  readTool(props.toolName).pipe(
+    Effect.flatMap((live) => {
+      if (live === undefined) return Effect.void;
+      const inputStale =
+        props.inputPolicy !== undefined && live.inputPolicy !== DEFAULT_TOOL_POLICY;
+      const outputStale =
+        props.outputPolicy !== undefined && live.outputPolicy !== DEFAULT_TOOL_POLICY;
+      if (!inputStale && !outputStale) return Effect.void;
+      return writeToolPolicy({
+        tool_name: props.toolName,
+        ...(inputStale ? { input_policy: DEFAULT_TOOL_POLICY } : {}),
+        ...(outputStale ? { output_policy: DEFAULT_TOOL_POLICY } : {}),
+      });
+    }),
+  );

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

@@ -0,0 +1,48 @@
+/**
+ * What a `LiteLLM.ToolPolicy` declares (props) and what is remembered about it (attributes).
+ *
+ * ★ A TOOL POLICY IS THE TRUST SETTING OF ONE TOOL in `LiteLLM_ToolTable` (`/v1/tool/policy`): an
+ *   input policy (`untrusted`, `trusted`, `blocked`) and an output policy (`untrusted`, `trusted`).
+ *   LiteLLM DISCOVERS tools as requests use them and gives each `untrusted`/`untrusted`
+ *   (`TOOL_POLICY_OPTIONS`, `tool_management_endpoints.py`, 1.103.0); this resource sets them.
+ * ⛔ IT DOES NOTHING UNTIL THE `tool_policy` GUARDRAIL IS CONFIGURED. The rows are data; only
+ *   `guardrails/guardrail_hooks/tool_policy/tool_policy_guardrail.py` reads them, and it is a guardrail
+ *   the proxy's own config must enable (`guardrails: - guardrail_name: tool_policy, litellm_params:
+ *   { guardrail: tool_policy, mode: post_call }`, its module docstring). Declaring a policy without it
+ *   is an inert row, not a control. Measured 2026-09-30: the rendered CT100 config has no
+ *   `tool_policy` guardrail (count 0), so on that proxy today these rows are not enforced.
+ * ⚠️ NOT MODELLED: the team and key OVERRIDES of `POST /v1/tool/policy` (`team_id`, `key_hash`). An
+ *   override is stored as an entry of that team's or key's `object_permission.blocked_tools`
+ *   (`add_tool_to_object_permission_blocked`), the same list `LiteLLM.Team` manages through
+ *   `objectPermission.blockedTools`; two resources writing one list would fight. Block a tool for a
+ *   team there, and for a key on the key.
+ */
+export type ToolInputPolicy = 'untrusted' | 'trusted' | 'blocked';
+export type ToolOutputPolicy = 'untrusted' | 'trusted';
+
+export interface ToolPolicyProps {
+  /**
+   * The tool's name as LiteLLM records it (for an MCP tool, `<server prefix>-<tool>`). Changing it is
+   * a DIFFERENT tool, so it is a replace. Refused if it is one of the names the route table shadows
+   * (`list`, `spend`, `policy/options`) or ends in `/detail` or `/logs`: the read is
+   * `GET /v1/tool/{tool_name:path}`, which those routes are registered before.
+   */
+  readonly toolName: string;
+  /** Compared and sent only when declared. Declare at least one of the two. */
+  readonly inputPolicy?: ToolInputPolicy;
+  /** Compared and sent only when declared. Declare at least one of the two. */
+  readonly outputPolicy?: ToolOutputPolicy;
+}
+
+export interface ToolPolicyAttributes {
+  readonly toolName: string;
+  readonly toolId: string;
+  /** What the row carries, as a string: a later LiteLLM may add a value this package does not know. */
+  readonly inputPolicy: string;
+  readonly outputPolicy: string;
+}
+
+/** What LiteLLM gives a newly discovered tool, and what `delete` resets a managed field to. */
+export const DEFAULT_TOOL_POLICY = 'untrusted';
+export const INPUT_POLICIES: readonly ToolInputPolicy[] = ['untrusted', 'trusted', 'blocked'];
+export const OUTPUT_POLICIES: readonly ToolOutputPolicy[] = ['untrusted', 'trusted'];