omnigateway 0.14.1 → 0.15.0

package/bin/omni.js

@@ -7751,6 +7751,17 @@ var _006_model_window_index_default = `-- The per-model long-window reads behind
 CREATE INDEX idx_request_logs_key_model_at ON request_logs (api_key_id, requested_model, at);
 `;
 
+// packages/store/src/postgres/migrations/007_key_guardrail.sql
+var _007_key_guardrail_default = `-- The Postgres half of the sqlite migration \`019_key_guardrail.sql\`: an
+-- optional usage policy on a gateway API key, NULL meaning no guardrail.
+--
+-- No backfill: every existing key was minted without a policy. Safe under a
+-- rolling deploy \u2014 a nullable column and nothing dropped, so a replica on the
+-- previous image keeps serving, ignoring the field (and therefore not judging
+-- that key's requests until it is replaced, which README's upgrade notes say).
+ALTER TABLE api_keys ADD COLUMN guardrail_policy TEXT;
+`;
+
 // packages/store/src/postgres/db.ts
 var num = (v) => Number(v);
 var numOrNull = (v) => v === null ? null : Number(v);
@@ -7761,7 +7772,8 @@ var MIGRATIONS = [
   { id: 3, sql: _003_key_expiry_default },
   { id: 4, sql: _004_log_keyset_default },
   { id: 5, sql: _005_log_filter_indexes_default },
-  { id: 6, sql: _006_model_window_index_default }
+  { id: 6, sql: _006_model_window_index_default },
+  { id: 7, sql: _007_key_guardrail_default }
 ];
 async function openPg(url) {
   const sql = new SQL({ url });
@@ -7962,6 +7974,9 @@ function resolvePin(target, accounts) {
     return;
   return accounts.find((account) => servesTarget(target, account));
 }
+var GUARDRAIL_POLICY_MAX_CHARS = 4000;
+var GUARDRAIL_TIMEOUT_MAX_MS = 60000;
+var GUARDRAIL_HISTORY_TURNS_MAX = 10;
 var keyUsable = (key, now) => key.revokedAt === null && (key.expiresAt === null || key.expiresAt > now);
 var credentialPastExpiry = (credential, now) => credential.authType === "oauth" && credential.expiresAt !== null && credential.expiresAt <= now;
 var credentialExpired = (credential, now) => credentialPastExpiry(credential, now) && !credential.hasRefreshToken;
@@ -7981,8 +7996,22 @@ var DEFAULT_SETTINGS = {
   bodyLoggingEnabled: false,
   bodyLoggingCaptureStreamChunks: false,
   snapshotKeepLatest: 5,
-  snapshotMaxAgeDays: 30
+  snapshotMaxAgeDays: 30,
+  guardrailModel: null,
+  guardrailTimeoutMs: 1e4,
+  guardrailHistoryTurns: 3
 };
+var inRange = (value, max) => typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= max;
+function readGuardrailSettings(stored) {
+  const model = stored.guardrailModel;
+  const timeout = stored.guardrailTimeoutMs;
+  const turns = stored.guardrailHistoryTurns;
+  return {
+    guardrailModel: typeof model === "string" && model.trim() !== "" ? model : null,
+    guardrailTimeoutMs: inRange(timeout, GUARDRAIL_TIMEOUT_MAX_MS) ? timeout : DEFAULT_SETTINGS.guardrailTimeoutMs,
+    guardrailHistoryTurns: inRange(turns, GUARDRAIL_HISTORY_TURNS_MAX) ? turns : DEFAULT_SETTINGS.guardrailHistoryTurns
+  };
+}
 
 // packages/store/src/postgres/config.ts
 var SETTINGS_KEY = "settings";
@@ -8046,7 +8075,8 @@ function createConfigRepo(sql, emit) {
           bodyRetentionDays: Number.isInteger(stored.bodyRetentionDays) && (stored.bodyRetentionDays ?? 0) >= 1 && (stored.bodyRetentionDays ?? 0) <= 3650 ? stored.bodyRetentionDays : DEFAULT_SETTINGS.bodyRetentionDays,
           bodyLoggingEnabled: stored.bodyLoggingEnabled === true,
           bodyLoggingCaptureStreamChunks: stored.bodyLoggingCaptureStreamChunks === true,
-          weights: knownWeights(stored.weights)
+          weights: knownWeights(stored.weights),
+          ...readGuardrailSettings(stored)
         };
       } catch {
         return DEFAULT_SETTINGS;
@@ -8447,7 +8477,8 @@ var toKey = (r, logger) => ({
   bodyLoggingOptOut: r.body_logging_opt_out,
   createdAt: num(r.created_at),
   revokedAt: numOrNull(r.revoked_at),
-  expiresAt: numOrNull(r.expires_at)
+  expiresAt: numOrNull(r.expires_at),
+  guardrailPolicy: r.guardrail_policy
 });
 function createKeyRepo(sql, logger) {
   const one = async (where, arg) => {
@@ -8465,8 +8496,9 @@ function createKeyRepo(sql, logger) {
     async create(input) {
       const now = Date.now();
       await sql.unsafe(`INSERT INTO api_keys (id, label, prefix, hash, model_allowlist, limits,
-                               body_logging_opt_out, created_at, revoked_at, expires_at)
-         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,NULL,$9)`, [
+                               body_logging_opt_out, created_at, revoked_at, expires_at,
+                               guardrail_policy)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,NULL,$9,$10)`, [
         input.id,
         input.label,
         input.prefix,
@@ -8475,7 +8507,8 @@ function createKeyRepo(sql, logger) {
         JSON.stringify(parseLimitConfig(input.limits)),
         input.bodyLoggingOptOut,
         now,
-        input.expiresAt
+        input.expiresAt,
+        input.guardrailPolicy
       ]);
       return { ...input, createdAt: now, revokedAt: null };
     },
@@ -8483,8 +8516,9 @@ function createKeyRepo(sql, logger) {
       if (row.limits === null)
         throw new Error(`api key ${row.id} has unreadable limits`);
       await sql.unsafe(`INSERT INTO api_keys (id, label, prefix, hash, model_allowlist, limits,
-                               body_logging_opt_out, created_at, revoked_at, expires_at)
-         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)`, [
+                               body_logging_opt_out, created_at, revoked_at, expires_at,
+                               guardrail_policy)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)`, [
         row.id,
         row.label,
         row.prefix,
@@ -8494,7 +8528,8 @@ function createKeyRepo(sql, logger) {
         row.bodyLoggingOptOut,
         row.createdAt,
         row.revokedAt,
-        row.expiresAt
+        row.expiresAt,
+        row.guardrailPolicy
       ]);
     },
     async setLimits(id, limits) {
@@ -8512,6 +8547,9 @@ function createKeyRepo(sql, logger) {
     async setExpiry(id, expiresAt) {
       await sql.unsafe("UPDATE api_keys SET expires_at = $1 WHERE id = $2", [expiresAt, id]);
     },
+    async setGuardrailPolicy(id, policy) {
+      await sql.unsafe("UPDATE api_keys SET guardrail_policy = $1 WHERE id = $2", [policy, id]);
+    },
     async revoke(id) {
       await sql.unsafe("UPDATE api_keys SET revoked_at = $1 WHERE id = $2", [Date.now(), id]);
     }
@@ -9281,8 +9319,16 @@ function createUsageRepo(sql, nodeId, dayOffsetMinutes) {
       const since = daily ? startOfDay(q.since, dayOffsetMinutes) : q.since;
       const until = q.until ?? Number.MAX_SAFE_INTEGER;
       const timeColumn = daily ? "day" : "at";
-      const scope = q.apiKeyId;
-      const bindings = scope === undefined ? [since, until] : [since, until, scope];
+      const bindings = [since, until];
+      let filters = "";
+      if (q.apiKeyId !== undefined) {
+        bindings.push(q.apiKeyId);
+        filters += ` AND api_key_id = $${bindings.length}`;
+      }
+      if (q.credentialId !== undefined) {
+        bindings.push(q.credentialId);
+        filters += ` AND credential_id = $${bindings.length}`;
+      }
       const rows = await sql.unsafe(`SELECT ${key} AS key,
                 ${split ?? "NULL"} AS split,
                 ${MEASURES[grain]},
@@ -9294,7 +9340,7 @@ function createUsageRepo(sql, nodeId, dayOffsetMinutes) {
                 COALESCE(SUM(${daily ? "rtk_applied_requests" : "CASE WHEN rtk_applied THEN 1 ELSE 0 END"}), 0) AS rtk_applied_requests,
                 COALESCE(SUM(cost_usd), 0) AS cost_usd
            FROM ${daily ? "usage_daily" : "request_logs"}
-          WHERE ${daily ? "" : "state = 'done' AND "}${timeColumn} >= $1 AND ${timeColumn} <= $2${scope === undefined ? "" : " AND api_key_id = $3"}
+          WHERE ${daily ? "" : "state = 'done' AND "}${timeColumn} >= $1 AND ${timeColumn} <= $2${filters}
           GROUP BY 1${split === null ? "" : ", 2"}
           ORDER BY requests DESC`, bindings);
       return rows.map((r) => {
@@ -9577,7 +9623,8 @@ function createConfigRepo2(db, emit = () => {}) {
           bodyRetentionDays: Number.isInteger(stored.bodyRetentionDays) && (stored.bodyRetentionDays ?? 0) >= 1 && (stored.bodyRetentionDays ?? 0) <= 3650 ? stored.bodyRetentionDays : DEFAULT_SETTINGS.bodyRetentionDays,
           bodyLoggingEnabled: stored.bodyLoggingEnabled === true,
           bodyLoggingCaptureStreamChunks: stored.bodyLoggingCaptureStreamChunks === true,
-          weights: knownWeights2(stored.weights)
+          weights: knownWeights2(stored.weights),
+          ...readGuardrailSettings(stored)
         };
       } catch {
         return DEFAULT_SETTINGS;
@@ -10588,6 +10635,24 @@ var _018_model_window_index_default = `-- An index for the per-model long-window
 CREATE INDEX idx_request_logs_key_model_at ON request_logs (api_key_id, requested_model, at);
 `;
 
+// packages/store/src/sqlite/migrations/019_key_guardrail.sql
+var _019_key_guardrail_default = `-- An optional usage policy on a gateway API key: free text the operator wrote
+-- about what the key may be used for, judged by a classifier model before each
+-- inference request (\`apps/gateway/src/guardrail/\`).
+--
+-- Nullable, and NULL is the only spelling of "no guardrail". No backfill, for
+-- the reason migration 14 has none: every existing key was minted without a
+-- policy, and inventing one would start refusing its client on an upgrade the
+-- operator never connected to it.
+--
+-- Its own column rather than a member of \`limits\`. A policy is not a limit, and
+-- nesting it there would bind it to the \`@omni/ratelimit/catalog\` storage
+-- contract, which fails closed on any name it does not know. The cost is
+-- accepted and documented: a rollback to a build without this column ignores
+-- it and stops judging \u2014 the guardrail fails open across a downgrade.
+ALTER TABLE api_keys ADD COLUMN guardrail_policy TEXT;
+`;
+
 // packages/store/src/sqlite/db.ts
 var MIGRATIONS2 = [
   { id: 1, sql: _001_init_default2 },
@@ -10607,7 +10672,8 @@ var MIGRATIONS2 = [
   { id: 15, sql: _015_log_keyset_default },
   { id: 16, sql: _016_log_filter_indexes_default },
   { id: 17, sql: _017_log_text_search_default },
-  { id: 18, sql: _018_model_window_index_default }
+  { id: 18, sql: _018_model_window_index_default },
+  { id: 19, sql: _019_key_guardrail_default }
 ];
 function statements(sql) {
   return sql.split(`
@@ -10664,7 +10730,8 @@ var toKey2 = (r, logger) => ({
   bodyLoggingOptOut: r.body_logging_opt_out === 1,
   createdAt: r.created_at,
   revokedAt: r.revoked_at,
-  expiresAt: r.expires_at
+  expiresAt: r.expires_at,
+  guardrailPolicy: r.guardrail_policy
 });
 function createKeyRepo2(db, logger = noopLogger) {
   return {
@@ -10682,8 +10749,9 @@ function createKeyRepo2(db, logger = noopLogger) {
     async create(input) {
       const now = Date.now();
       db.run(`INSERT INTO api_keys (id, label, prefix, hash, model_allowlist, limits,
-                               body_logging_opt_out, created_at, revoked_at, expires_at)
-         VALUES (?,?,?,?,?,?,?,?,NULL,?)`, [
+                               body_logging_opt_out, created_at, revoked_at, expires_at,
+                               guardrail_policy)
+         VALUES (?,?,?,?,?,?,?,?,NULL,?,?)`, [
         input.id,
         input.label,
         input.prefix,
@@ -10692,7 +10760,8 @@ function createKeyRepo2(db, logger = noopLogger) {
         JSON.stringify(parseLimitConfig(input.limits)),
         input.bodyLoggingOptOut ? 1 : 0,
         now,
-        input.expiresAt
+        input.expiresAt,
+        input.guardrailPolicy
       ]);
       return { ...input, createdAt: now, revokedAt: null };
     },
@@ -10700,8 +10769,9 @@ function createKeyRepo2(db, logger = noopLogger) {
       if (row.limits === null)
         throw new Error(`api key ${row.id} has unreadable limits`);
       db.run(`INSERT INTO api_keys (id, label, prefix, hash, model_allowlist, limits,
-                               body_logging_opt_out, created_at, revoked_at, expires_at)
-         VALUES (?,?,?,?,?,?,?,?,?,?)`, [
+                               body_logging_opt_out, created_at, revoked_at, expires_at,
+                               guardrail_policy)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?)`, [
         row.id,
         row.label,
         row.prefix,
@@ -10711,7 +10781,8 @@ function createKeyRepo2(db, logger = noopLogger) {
         row.bodyLoggingOptOut ? 1 : 0,
         row.createdAt,
         row.revokedAt,
-        row.expiresAt
+        row.expiresAt,
+        row.guardrailPolicy
       ]);
     },
     async setLimits(id, limits) {
@@ -10729,6 +10800,9 @@ function createKeyRepo2(db, logger = noopLogger) {
     async setExpiry(id, expiresAt) {
       db.run("UPDATE api_keys SET expires_at = ? WHERE id = ?", [expiresAt, id]);
     },
+    async setGuardrailPolicy(id, policy) {
+      db.run("UPDATE api_keys SET guardrail_policy = ? WHERE id = ?", [policy, id]);
+    },
     async revoke(id) {
       db.run("UPDATE api_keys SET revoked_at = ? WHERE id = ?", [Date.now(), id]);
     }
@@ -11215,9 +11289,16 @@ function createUsageRepo2(db, nodeId, dayOffsetMinutes = hostDayOffsetMinutes())
       const since = daily ? startOfDay(q.since, dayOffsetMinutes) : q.since;
       const until = q.until ?? Number.MAX_SAFE_INTEGER;
       const timeColumn = daily ? "day" : "at";
-      const scope = q.apiKeyId;
-      const scoped = scope !== undefined;
-      const bindings = scope === undefined ? [since, until] : [since, until, scope];
+      const bindings = [since, until];
+      let filters = "";
+      if (q.apiKeyId !== undefined) {
+        filters += " AND api_key_id = ?";
+        bindings.push(q.apiKeyId);
+      }
+      if (q.credentialId !== undefined) {
+        filters += " AND credential_id = ?";
+        bindings.push(q.credentialId);
+      }
       const rows = db.query(`SELECT ${key} AS key,
                   ${split ?? "NULL"} AS split,
                   ${MEASURES2[grain]},
@@ -11229,7 +11310,7 @@ function createUsageRepo2(db, nodeId, dayOffsetMinutes = hostDayOffsetMinutes())
                   COALESCE(SUM(${daily ? "rtk_applied_requests" : "CASE WHEN rtk_applied = 1 THEN 1 ELSE 0 END"}), 0) AS rtk_applied_requests,
                   COALESCE(SUM(cost_usd), 0) AS cost_usd
              FROM ${daily ? "usage_daily" : "request_logs"}
-            WHERE ${daily ? "" : "state = 'done' AND "}${timeColumn} >= ? AND ${timeColumn} <= ?${scoped ? " AND api_key_id = ?" : ""}
+            WHERE ${daily ? "" : "state = 'done' AND "}${timeColumn} >= ? AND ${timeColumn} <= ?${filters}
             GROUP BY key${split === null ? "" : ", split"}
             ORDER BY requests DESC`).all(...bindings);
       return rows.map((r) => {
@@ -11333,6 +11414,7 @@ async function createStore(opts) {
       setLimits: (id, limits) => handle.keys.setLimits(id, limits),
       setModelAllowlist: (id, modelAllowlist) => handle.keys.setModelAllowlist(id, modelAllowlist),
       setExpiry: (id, expiresAt) => handle.keys.setExpiry(id, expiresAt),
+      setGuardrailPolicy: (id, policy) => handle.keys.setGuardrailPolicy(id, policy),
       revoke: (id) => handle.keys.revoke(id)
     },
     usage: {
@@ -20376,18 +20458,21 @@ var modelSchema = object({
   targets: array(targetSchema).min(1, "a virtual model needs at least one target")
 });
 var MAX_INSTANT = 8640000000000000;
+var guardrailPolicySchema = string2().trim().min(1).max(GUARDRAIL_POLICY_MAX_CHARS);
 var keyCreateSchema = object({
   label: string2().min(1).default("api key"),
   modelAllowlist: array(string2().min(1)).nullable().default(null),
   limits: limitConfigSchema.default({}),
   bodyLoggingOptOut: boolean2().default(false),
-  expiresAt: number2().int().positive().max(MAX_INSTANT).nullable().default(null)
+  expiresAt: number2().int().positive().max(MAX_INSTANT).nullable().default(null),
+  guardrailPolicy: guardrailPolicySchema.nullable().default(null)
 }).strict();
 var keyLimitsSchema = object({ limits: limitConfigSchema }).strict();
 var keyModelsSchema = object({
   modelAllowlist: array(string2().min(1)).nullable()
 }).strict();
 var keyExpirySchema = object({ expiresAt: number2().int().positive().max(MAX_INSTANT).nullable() }).strict();
+var keyGuardrailSchema = object({ policy: guardrailPolicySchema.nullable() }).strict();
 var retentionSchema = object({
   keepLatest: number2().int().min(1).max(100),
   maxAgeDays: number2().int().min(1).max(3650)
@@ -20414,7 +20499,10 @@ var settingsSchema = object({
   bodyLoggingEnabled: boolean2(),
   bodyLoggingCaptureStreamChunks: boolean2(),
   snapshotKeepLatest: retentionSchema.shape.keepLatest.optional(),
-  snapshotMaxAgeDays: retentionSchema.shape.maxAgeDays.optional()
+  snapshotMaxAgeDays: retentionSchema.shape.maxAgeDays.optional(),
+  guardrailModel: string2().trim().min(1).max(256).nullable().optional(),
+  guardrailTimeoutMs: number2().int().min(1).max(GUARDRAIL_TIMEOUT_MAX_MS).optional(),
+  guardrailHistoryTurns: number2().int().min(1).max(GUARDRAIL_HISTORY_TURNS_MAX).optional()
 });
 var credentialPatchSchema = object({
   label: string2().min(1).optional(),
@@ -20429,7 +20517,9 @@ var quotaRefreshSchema = discriminatedUnion("kind", [
   }).strict(),
   object({ kind: literal("all") }).strict()
 ]);
-var accountIdSchema = string2().trim().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/, "credentialId must be an account id");
+var opaqueIdSchema = (message) => string2().trim().min(1, message).max(64, message).regex(/^[A-Za-z0-9_-]+$/, message);
+var accountIdSchema = opaqueIdSchema("credentialId must be an account id");
+var keyIdSchema = opaqueIdSchema("apiKeyId must be a key id");
 var redeemResetSchema = object({
   credentialId: accountIdSchema,
   creditId: string2().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/).optional()
@@ -20841,6 +20931,50 @@ function score(pairs, input) {
     };
   });
 }
+// packages/router/src/resolve.ts
+function prefixProviders(providers) {
+  return Object.entries(providers).flatMap(([id, descriptor]) => descriptor.modelPrefixes.map((prefix) => [prefix, id, descriptor])).sort(([a], [b]) => b.length - a.length);
+}
+function synthesize(provider, model, descriptor) {
+  const listed = entryPricing(descriptor.catalog, model);
+  const limits = entryLimits(descriptor.catalog, model);
+  const target = {
+    provider,
+    model,
+    tier: 1,
+    weight: 1,
+    costPerMTok: listed === null ? { input: 0, output: 0 } : {
+      input: listed.input,
+      output: listed.output,
+      cacheRead: listed.cacheRead,
+      cacheWrite5m: listed.cacheWrite5m,
+      cacheWrite1h: listed.cacheWrite1h
+    },
+    ...limits === null ? {} : { contextWindow: limits.contextWindow, maxOutputTokens: limits.maxOutputTokens },
+    capabilities: descriptor.capabilities
+  };
+  return { id: `${provider}/${model}`, targets: [target], strategy: "score", isAlias: true };
+}
+function resolveModel(name, snapshot, providers = PROVIDER_DESCRIPTORS) {
+  const configured = snapshot.models.get(name);
+  if (configured !== undefined)
+    return configured;
+  const sep = name.search(/[/:]/);
+  if (sep > 0) {
+    const prefix = name.slice(0, sep);
+    const rest = name.slice(sep + 1);
+    const descriptor = Object.hasOwn(providers, prefix) ? providers[prefix] : undefined;
+    if (descriptor !== undefined && prefix !== "custom" && rest.length > 0) {
+      return synthesize(prefix, rest, descriptor);
+    }
+    throw new GatewayError("NO_CANDIDATES", `unknown provider "${safeToken(prefix)}" in model "${safeToken(name)}"`);
+  }
+  for (const [prefix, provider, descriptor] of prefixProviders(providers)) {
+    if (name.startsWith(prefix))
+      return synthesize(provider, name, descriptor);
+  }
+  throw new GatewayError("NO_CANDIDATES", `model "${safeToken(name)}" is not a configured virtual model and its provider could not be inferred`);
+}
 
 // packages/router/src/index.ts
 function weightedShuffle(candidates, rand, headroom, health) {
@@ -21449,6 +21583,22 @@ async function dryRun(deps, modelId, input) {
     }))
   };
 }
+// packages/control/src/guardrail.ts
+async function guardrailReadiness(store, providers, now = Date.now()) {
+  const keysWithPolicy = (await store.keys.list()).filter((key) => key.revokedAt === null && key.guardrailPolicy !== null).length;
+  const snapshot = await buildSnapshot(store, now);
+  const model = snapshot.settings.guardrailModel;
+  if (keysWithPolicy === 0)
+    return { keysWithPolicy, model, problem: null };
+  if (model === null)
+    return { keysWithPolicy, model, problem: "unconfigured" };
+  try {
+    resolveModel(model, snapshot, providers);
+    return { keysWithPolicy, model, problem: null };
+  } catch {
+    return { keysWithPolicy, model, problem: "unresolved" };
+  }
+}
 // packages/control/src/keys.ts
 function configuredWindows(limits) {
   const needed = new Set;
@@ -21518,7 +21668,8 @@ async function toSummary(store, key, now) {
     bodyLoggingOptOut: key.bodyLoggingOptOut,
     createdAt: key.createdAt,
     revokedAt: key.revokedAt,
-    expiresAt: key.expiresAt
+    expiresAt: key.expiresAt,
+    guardrailPolicy: key.guardrailPolicy
   };
 }
 async function listKeys(store, now = Date.now()) {
@@ -21536,7 +21687,8 @@ async function createKey(store, input) {
     modelAllowlist: body.modelAllowlist,
     limits: body.limits,
     bodyLoggingOptOut: body.bodyLoggingOptOut,
-    expiresAt: body.expiresAt
+    expiresAt: body.expiresAt,
+    guardrailPolicy: body.guardrailPolicy
   });
   return { id: created.id, label: created.label, prefix: created.prefix, key: raw };
 }
@@ -21564,6 +21716,14 @@ async function setKeyExpiry(store, id, input, now = Date.now()) {
   await store.keys.setExpiry(id, body.expiresAt);
   return toSummary(store, { ...key, expiresAt: body.expiresAt }, now);
 }
+async function setKeyGuardrail(store, id, input, now = Date.now()) {
+  const body = parseOrThrow(keyGuardrailSchema, input);
+  const key = await store.keys.get(id);
+  if (key === null)
+    throw new GatewayError("BAD_REQUEST", "no such api key");
+  await store.keys.setGuardrailPolicy(id, body.policy);
+  return toSummary(store, { ...key, guardrailPolicy: body.policy }, now);
+}
 async function revokeKey(store, id) {
   await store.keys.revoke(id);
 }
@@ -21589,15 +21749,21 @@ async function queryUsage(deps, input, scope = ALL) {
         throw new GatewayError("BAD_REQUEST", "this dimension is not available on this surface");
       }
     }
+    if (input.credentialId !== undefined || input.apiKeyId !== undefined) {
+      throw new GatewayError("BAD_REQUEST", "this filter is not available on this surface");
+    }
   }
+  const credentialId = input.credentialId === undefined ? undefined : parseOrThrow(accountIdSchema, input.credentialId);
+  const keyFilter = input.apiKeyId === undefined ? undefined : parseOrThrow(keyIdSchema, input.apiKeyId);
   if (readsNothing(scope))
     return [];
-  const apiKeyId = scopeKey(scope);
+  const apiKeyId = scope.kind === "all" ? keyFilter : scopeKey(scope);
   return deps.store.usage.aggregate({
     grain,
     groupBy,
     ...splitBy === undefined ? {} : { splitBy },
     ...apiKeyId === undefined ? {} : { apiKeyId },
+    ...credentialId === undefined ? {} : { credentialId },
     since: optionalNumber(input.since, 0),
     until: optionalNumber(input.until, deps.now())
   });
@@ -23598,12 +23764,23 @@ async function getSettings(store) {
   return store.config.getSettings();
 }
 async function putSettings(store, input) {
-  const { bodyRetentionDays, snapshotKeepLatest, snapshotMaxAgeDays, ...rest } = parseOrThrow(settingsSchema, input);
+  const {
+    bodyRetentionDays,
+    snapshotKeepLatest,
+    snapshotMaxAgeDays,
+    guardrailModel,
+    guardrailTimeoutMs,
+    guardrailHistoryTurns,
+    ...rest
+  } = parseOrThrow(settingsSchema, input);
   const patch = {
     ...rest,
     ...bodyRetentionDays === undefined ? {} : { bodyRetentionDays },
     ...snapshotKeepLatest === undefined ? {} : { snapshotKeepLatest },
-    ...snapshotMaxAgeDays === undefined ? {} : { snapshotMaxAgeDays }
+    ...snapshotMaxAgeDays === undefined ? {} : { snapshotMaxAgeDays },
+    ...guardrailModel === undefined ? {} : { guardrailModel },
+    ...guardrailTimeoutMs === undefined ? {} : { guardrailTimeoutMs },
+    ...guardrailHistoryTurns === undefined ? {} : { guardrailHistoryTurns }
   };
   return store.config.putSettings(patch);
 }
@@ -25327,6 +25504,7 @@ var keysList = {
         { header: "MODELS" },
         { header: "LIMITS" },
         { header: "BODY CAPTURE" },
+        { header: "POLICY" },
         { header: "STATE" },
         { header: "EXPIRES" },
         { header: "CREATED" }
@@ -25337,6 +25515,7 @@ var keysList = {
         key.modelAllowlist === null ? "all" : key.modelAllowlist.length === 0 ? "none" : key.modelAllowlist.join(","),
         key.limits === null ? paint(ctx, "red", "unreadable") : summarizeLimits(key.limits),
         key.bodyLoggingOptOut ? "no bodies" : "\u2014",
+        key.guardrailPolicy === null ? "no" : "yes",
         ((verdict) => state(ctx, verdict === "active", verdict))(keyState(key, now)),
         formatTime(key.expiresAt),
         formatTime(key.createdAt)
@@ -25345,7 +25524,7 @@ var keysList = {
   }
 };
 var keysCreate = {
-  usage: "keys create [--label L] [--allow <model> ...] [--limit <d>:<w>=N ...] [--model-limit <model>:<d>:<w>=N ...] [--expires <when>] [--no-bodies]",
+  usage: "keys create [--label L] [--allow <model> ...] [--limit <d>:<w>=N ...] [--model-limit <model>:<d>:<w>=N ...] [--expires <when>] [--policy <text>] [--no-bodies]",
   summary: "Mint a gateway API key, printed once",
   options: {
     label: { type: "string" },
@@ -25353,10 +25532,12 @@ var keysCreate = {
     limit: { type: "string", multiple: true },
     "model-limit": { type: "string", multiple: true },
     expires: { type: "string" },
+    policy: { type: "string" },
     "no-bodies": { type: "boolean" }
   },
   async run(args, { ctx, writer }) {
     const allow = listFlag(args.values, "allow");
+    const policy = stringFlag(args.values, "policy");
     const expires = stringFlag(args.values, "expires");
     const limits = emptyLimits();
     parseLimitFlags(listFlag(args.values, "limit") ?? [], "--limit", limits.scope);
@@ -25366,7 +25547,8 @@ var keysCreate = {
       modelAllowlist: allow ?? null,
       limits: toWire2(limits),
       bodyLoggingOptOut: boolFlag(args.values, "no-bodies"),
-      expiresAt: expires === undefined ? null : parseWhen("--expires", expires)
+      expiresAt: expires === undefined ? null : parseWhen("--expires", expires),
+      guardrailPolicy: policy ?? null
     });
     emit(ctx, writer, created, () => {
       note(ctx, writer, paint(ctx, "yellow", "this key is shown once and stored only as a hash"));
@@ -25482,6 +25664,49 @@ expires: ${formatTime(key.expiresAt)}${verdict === "expired" ? ` ${paint(ctx, "r
     });
   }
 };
+var keysGuardrail = {
+  usage: "keys guardrail <id> [--policy <text> | --policy-file <path> | --clear]",
+  summary: "Show or replace one key's usage policy",
+  options: {
+    policy: { type: "string" },
+    "policy-file": { type: "string" },
+    clear: { type: "boolean" }
+  },
+  async run(args, { ctx, writer }) {
+    const id = requirePositional(args, 0, "key id");
+    const text = stringFlag(args.values, "policy");
+    const file = stringFlag(args.values, "policy-file");
+    const clear = boolFlag(args.values, "clear");
+    const given = [text !== undefined, file !== undefined, clear].filter(Boolean).length;
+    if (given > 1) {
+      throw new UsageError("pass one of --policy, --policy-file or --clear");
+    }
+    const store = await ctx.store();
+    const existing = (await listKeys(store)).find((entry) => entry.id === id);
+    if (existing === undefined)
+      throw new CliError(`no api key "${id}"`);
+    let key = existing;
+    if (given === 1) {
+      const policy = clear ? null : file !== undefined ? await Bun.file(file).text().catch(() => {
+        throw new CliError(`could not read ${file}`);
+      }) : text;
+      key = await setKeyGuardrail(store, id, { policy });
+    }
+    emit(ctx, writer, key, () => {
+      const head = fields([
+        ["id", key.id],
+        ["label", key.label],
+        ["prefix", `${key.prefix}\u2026`]
+      ]);
+      if (key.guardrailPolicy === null)
+        return `${head}
+policy: none; requests are not judged`;
+      return `${head}
+policy:
+${key.guardrailPolicy}`;
+    });
+  }
+};
 var keysRevoke = {
   usage: "keys revoke <id>",
   summary: "Revoke a gateway API key, keeping its usage history",
@@ -26081,7 +26306,7 @@ function createServiceDeps(input) {
 }
 
 // apps/cli/src/version.ts
-var VERSION = "0.14.1";
+var VERSION = "0.15.0";
 
 // apps/cli/src/commands/service.ts
 function gatewayArgv(root) {
@@ -26236,6 +26461,30 @@ async function danglingCredentials(ctx, plugins) {
     return null;
   }
 }
+async function guardrailState(ctx) {
+  if (ctx.configError !== null || !existsSync5(ctx.databasePath))
+    return null;
+  try {
+    return await guardrailReadiness(await ctx.store(), PROVIDER_DESCRIPTORS);
+  } catch {
+    return null;
+  }
+}
+function guardrailLine(ctx, readiness, plugins) {
+  if (readiness === null)
+    return paint(ctx, "dim", "not checked");
+  const { keysWithPolicy: n, model, problem } = readiness;
+  if (n === 0)
+    return paint(ctx, "dim", "no key carries one");
+  const keys = `${n} key${n === 1 ? "" : "s"}`;
+  if (problem === "unconfigured") {
+    return paint(ctx, "yellow", `${keys} carry a policy and no classifier is set (guardrailModel); their requests are refused`);
+  }
+  if (problem === "unresolved") {
+    return plugins.length > 0 ? paint(ctx, "yellow", `${keys} carry a policy; classifier "${model}" is not a built-in model (plugin providers not checked)`) : paint(ctx, "yellow", `${keys} carry a policy and classifier "${model}" does not resolve; their requests are refused`);
+  }
+  return state(ctx, true, `${keys}, judged by ${model}`);
+}
 var doctor = {
   usage: "doctor",
   summary: "Check what this CLI resolved, and whether it can do anything with it",
@@ -26251,6 +26500,7 @@ var doctor = {
     const pins = await danglingPins(ctx);
     const uninstalled = await missingProviders(ctx, plugins);
     const strandedKeys = await danglingCredentials(ctx, plugins);
+    const guardrail = await guardrailState(ctx);
     const checks = {
       version: VERSION,
       root: deps.root,
@@ -26272,6 +26522,7 @@ var doctor = {
       danglingPins: pins,
       missingProviders: uninstalled,
       danglingCredentials: strandedKeys,
+      guardrail,
       warnings: ctx.warnings
     };
     emit(ctx, writer, checks, () => {
@@ -26311,6 +26562,7 @@ ${fields([
           "stranded credentials",
           strandedKeys === null ? paint(ctx, "dim", "not checked") : strandedKeys.length === 0 ? ok(true, "none") : paint(ctx, "yellow", `${strandedKeys.length}: ${strandedKeys.join(", ")}`)
         ],
+        ["usage policies", guardrailLine(ctx, guardrail, plugins)],
         ...checks.warnings.map((warning) => ["ignored", paint(ctx, "yellow", warning)])
       ])}`;
     });
@@ -26374,9 +26626,15 @@ function asString2(path, raw) {
     throw new UsageError(`${path} must not be blank`);
   return value;
 }
+function asNullableString(path, raw) {
+  return raw.trim() === "null" ? null : asString2(path, raw);
+}
+function nullable2(head) {
+  return has(DEFAULT_SETTINGS, head) && DEFAULT_SETTINGS[head] === null;
+}
 var settingsSet = {
   usage: "settings set <path> <value>",
-  summary: "Change one setting, e.g. weights.cost 0.4 or rtkEnabled true",
+  summary: "Change one setting, e.g. weights.cost 0.4, rtkEnabled true, or guardrailModel null",
   async run(args, { ctx, writer }) {
     const path = requirePositional(args, 0, "setting path");
     const raw = requirePositional(args, 1, "value");
@@ -26389,7 +26647,7 @@ var settingsSet = {
       throw new UsageError(`"${head}" has no sub-settings`);
     }
     const existing = currentValue(current, head, tail);
-    const value = typeof existing === "boolean" ? asBoolean(path, raw) : typeof existing === "string" ? asString2(path, raw) : asNumber(path, raw);
+    const value = tail === undefined && nullable2(head) ? asNullableString(path, raw) : typeof existing === "boolean" ? asBoolean(path, raw) : typeof existing === "string" ? asString2(path, raw) : asNumber(path, raw);
     const next = tail === undefined ? { ...current, [head]: value } : { ...current, weights: { ...current.weights, [tail]: value } };
     const saved = await putSettings(store, next);
     emit(ctx, writer, { settings: saved }, () => `${path} = ${value}`);
@@ -26607,7 +26865,9 @@ var usage = {
     by: { type: "string" },
     split: { type: "string" },
     since: { type: "string" },
-    until: { type: "string" }
+    until: { type: "string" },
+    account: { type: "string" },
+    key: { type: "string" }
   },
   async run(args, { ctx, writer }) {
     const until = instant(stringFlag(args.values, "until"), ctx.now());
@@ -26617,7 +26877,9 @@ var usage = {
       groupBy: stringFlag(args.values, "by"),
       splitBy: stringFlag(args.values, "split"),
       since,
-      until
+      until,
+      credentialId: stringFlag(args.values, "account"),
+      apiKeyId: stringFlag(args.values, "key")
     });
     emit(ctx, writer, { rows }, () => {
       if (rows.length === 0)
@@ -26811,6 +27073,7 @@ var COMMANDS = {
   "keys limits": keysLimits,
   "keys models": keysModels,
   "keys expiry": keysExpiry,
+  "keys guardrail": keysGuardrail,
   "keys revoke": keysRevoke,
   "plugin list": pluginList,
   "plugin verify": pluginVerify,