Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

52.6 KB
Raw Blame
import type { TeamChange } from "../../teams/teams.ts";
import { decisionsResource } from "./decisions-resource.ts";
import { parseAckEmoji } from "../../slack/config.ts";
import { orgId as configOrgId } from "../../config.ts";
import type { ServerDeps } from "../deps.ts";
import type { ApiCtx } from "./route.ts";
import { parseCommandPolicy } from "../../policy/command-policy.ts";
import { parseScopeId, scopeId, type CommandPolicy, type Grant, type ScopeId } from "../../types.ts";
import {
  defaultModelForHarness,
  fastModeModelIds,
  harnessSupportsFastMode,
  HARNESS_IDS,
  harnessIdOrPi,
  isHarnessId,
  modelSupportedByHarness,
  modelServiceable,
  modelProviderAvailabilityFor,
  resolveModel,
  resolveEmbeddingModel,
  embeddingModelCatalog,
  thinkingLevelsForHarness,
  selectableBaseModels,
  ALL_PROVIDERS_AVAILABLE,
  type HarnessId,
} from "../../model/pi-models.ts";
import { resolveRuntimeChoiceDurable } from "../../harness/harness-router.ts";
import { sanitizeBranding } from "../../resolution/branding.ts";
import {
  credentialInjectionError,
  isValidCredentialSlug,
  isValidServiceCredentialEnvKey,
  isValidBrokerHost,
  isValidBrokerMethod,
  isValidBrokerPathPrefix,
  type CredentialInjection,
  type DecryptedServiceCredential,
  type PublicServiceCredential,
  type ServiceCredentialInput,
} from "../../credentials/keychain.ts";
import { parseBotLedger } from "../../surface-cache/channel-policy-store.ts";
import { authorizeUrl, PROVIDERS, type ConsentMode } from "../../connectors/oauth.ts";
import { resolverFor } from "./connectors.ts";
import { encodeRef, serviceCredRef } from "../../acl/resource-ref.ts";
import { audit } from "./shared.ts";
import { errMessage, reportFailure, swallowAs } from "../../util/errors.ts";
import {
  DEFAULT_SECURITY_SCREEN_RUBRIC,
  parseSecurityPosture,
  SECURITY_POSTURES,
  type SecurityPosture,
} from "../../security/security-posture.ts";
import type { ApprovalGrantModes } from "../../types.ts";
import { parseEgressPolicy } from "../../resolution/egress-policy.ts";
import { FEATURE_NAMES, FEATURES, type FeatureName } from "../../feature-flags.ts";
import { parseSharingPosture, SHARING_POSTURES, type SharingPosture } from "../../resolution/sharing-posture.ts";

export interface AutoFlaggerDraft {
  harnessId: HarnessId;
  modelId: string;
  rubric: string;
}

const AUTO_FLAGGER_MAX_RUBRIC_CHARS = 20_000;

/** The flagger a deployment falls back to when nothing is configured. */
export function defaultAutoFlaggerConfig(deps: Pick<ServerDeps, "harnessId" | "baseModelDefault">): AutoFlaggerDraft {
  const harnessId = harnessIdOrPi(deps.harnessId);
  return {
    harnessId,
    modelId: defaultModelForHarness(harnessId, deps.baseModelDefault),
    rubric: DEFAULT_SECURITY_SCREEN_RUBRIC,
  };
}

/**
 * Validate an Auto flagger configuration — shared by the governance save and the test run, so a
 * rubric that tests cleanly is exactly the one that can be applied.
 */
export async function parseAutoFlaggerDraft(
  deps: Pick<ServerDeps, "providerKeys" | "modelCredentials">,
  body: { harnessId?: unknown; modelId?: unknown; rubric?: unknown },
): Promise<{ value: AutoFlaggerDraft } | { error: string }> {
  if (typeof body.harnessId !== "string" || !isHarnessId(body.harnessId)) {
    return { error: "auto-flagger requires a valid harnessId" };
  }
  if (typeof body.modelId !== "string" || !body.modelId.trim()) {
    return { error: "auto-flagger requires a modelId" };
  }
  const modelId = body.modelId.trim();
  if (!modelSupportedByHarness(modelId, body.harnessId)) {
    return { error: `model ${modelId} is not supported by ${body.harnessId}` };
  }
  if (typeof body.rubric !== "string" || !body.rubric.trim() || body.rubric.length > AUTO_FLAGGER_MAX_RUBRIC_CHARS) {
    return {
      error: `auto-flagger requires a non-empty rubric of at most ${AUTO_FLAGGER_MAX_RUBRIC_CHARS} characters`,
    };
  }
  const configuredKeys = deps.providerKeys ?? ALL_PROVIDERS_AVAILABLE;
  const managedKeys = deps.modelCredentials ? await deps.modelCredentials.availability() : configuredKeys;
  if (!modelServiceable(modelId, modelProviderAvailabilityFor(body.harnessId, configuredKeys, managedKeys))) {
    return { error: `model ${modelId} isn't serviceable on this deployment` };
  }
  return { value: { harnessId: body.harnessId, modelId, rubric: body.rubric.trim() } };
}

type Actor = { id: string };

type AdminResourceKind = "boolean" | "string" | "text" | "string-list" | "enum" | "secret" | "custom";

type ApplyResult = { ok: true } | { error: string; code?: string; status?: number };

export interface AdminResource {
  id: string;
  kind: AdminResourceKind;
  readKey?: string;
  get?: (deps: ServerDeps, scope: string) => unknown | Promise<unknown>;
  apply: (ctx: ApiCtx, actor: Actor, scope: string) => Promise<ApplyResult>;
  target?: "org" | "any";
  secret?: boolean;
  clearable?: boolean;
  authz?: "scope-admin" | "org-admin";
  label?: string;
  enumValues?: readonly unknown[];
  refreshesModels?: true;
}

function generic<V>(
  parse: (
    body: unknown,
    ctx: { scope: string; deps: ServerDeps },
  ) => { value: V } | { error: string; code?: string; status?: number },
  set: (deps: ServerDeps, scope: string, value: V) => Promise<void>,
): AdminResource["apply"] {
  return async (ctx, _actor, scope) => {
    const parsed = parse(ctx.body, { scope, deps: ctx.deps });
    if ("error" in parsed) return parsed;
    await set(ctx.deps, scope, parsed.value);
    return { ok: true };
  };
}

const orgOnly = (scope: string, label: string): { error: string } | null =>
  parseScopeId(scope).kind === "org" ? null : { error: `${label}; target an org scope` };

const boolBody = (body: unknown): { value: boolean } => ({ value: !!(body as { on?: unknown }).on });

const MAX_ORDERS_CHARS = 20_000;
const MAX_SOUL_CHARS = 100_000;

function channelContainer(scope: string): string | undefined {
  const { kind, ref } = parseScopeId(scope);
  return ref && (kind === "channel" || kind === "group") ? ref : undefined;
}

export const ADMIN_RESOURCES: readonly AdminResource[] = [
  {
    id: "security-posture",
    kind: "enum",
    target: "any",
    label: "Harness security posture. The org value is a minimum; narrower scopes may tighten it but cannot weaken it.",
    readKey: "securityPosture",
    enumValues: SECURITY_POSTURES,
    get: (deps, scope) => deps.config!.getSecurityPostureDurable(scope),
    apply: generic<SecurityPosture>(
      (body) => {
        const posture = parseSecurityPosture((body as { posture?: unknown }).posture);
        return posture
          ? { value: posture }
          : { error: `security-posture requires { posture: ${SECURITY_POSTURES.join(" | ")} }` };
      },
      (deps, scope, posture) => deps.config!.setSecurityPosture(scope, posture),
    ),
  },
  {
    id: "sharing-posture",
    kind: "enum",
    target: "any",
    label:
      "Cross-context read posture. The organization is a ceiling; personal and room scopes may opt out. Isolated wins.",
    readKey: "sharingPosture",
    enumValues: SHARING_POSTURES,
    get: (deps, scope) => deps.config!.getSharingPostureDurable(scope),
    apply: generic<SharingPosture | null>(
      (body) => {
        if ((body as { inherit?: unknown }).inherit === true) return { value: null };
        const posture = parseSharingPosture((body as { posture?: unknown }).posture);
        return posture
          ? { value: posture }
          : { error: `sharing-posture requires { posture: ${SHARING_POSTURES.join(" | ")} }` };
      },
      (deps, scope, posture) =>
        posture === null ? deps.config!.clearSharingPosture(scope) : deps.config!.setSharingPosture(scope, posture),
    ),
  },
  {
    id: "auto-flagger",
    refreshesModels: true,
    kind: "custom",
    target: "org",
    clearable: true,
    label:
      "The model and classification rubric used to screen external content when the deployment enables model screening.",
    readKey: "autoFlagger",
    get: (deps) => deps.config!.getAutoFlaggerConfig(),
    apply: async (ctx, _actor, scope) => {
      const bad = orgOnly(scope, "the Auto flagger is org-wide");
      if (bad) return bad;
      const body = ctx.body as { reset?: unknown };
      if (body.reset === true) {
        await ctx.deps.config!.setAutoFlaggerConfig(null);
        return { ok: true };
      }
      const parsed = await parseAutoFlaggerDraft(ctx.deps, ctx.body as Record<string, unknown>);
      if ("error" in parsed) return parsed;
      await ctx.deps.config!.setAutoFlaggerConfig(parsed.value);
      return { ok: true };
    },
  },
  decisionsResource,
  {
    id: "approval-grant-modes",
    kind: "custom",
    target: "any",
    label:
      'Which standing HiLO approval options are offered: "Allow session" and "Allow always". Composes tighten-only with the org value; disabling a mode also suspends existing grants of that mode until re-enabled.',
    readKey: "approvalGrantModes",
    get: (deps, scope) => deps.config!.getApprovalGrantModesDurable(scope),
    apply: generic<ApprovalGrantModes>(
      (body) => {
        const b = body as { session?: unknown; always?: unknown };
        if (typeof b.session !== "boolean" || typeof b.always !== "boolean") {
          return { error: "approval-grant-modes requires { session: boolean, always: boolean }" };
        }
        return { value: { session: b.session, always: b.always } };
      },
      (deps, scope, modes) => deps.config!.setApprovalGrantModes(scope, modes),
    ),
  },
  {
    id: "command-policy",
    kind: "custom",
    readKey: "commandPolicy",
    get: (deps, scope) => deps.config!.getCommandPolicy(scope),
    apply: generic<CommandPolicy>(
      (body) => {
        const p = parseCommandPolicy(body);
        return "error" in p ? { error: p.error } : { value: p.policy };
      },
      (deps, scope, policy) => deps.config!.setCommandPolicy(scope, policy),
    ),
  },
  {
    id: "soul",
    kind: "text",
    readKey: "soul",
    get: (deps, scope) => deps.config!.getSoul(scope),
    apply: async (ctx, actor, scope) => {
      const body = ctx.body as { content?: unknown; expectedVersion?: unknown };
      if (typeof body.content !== "string") return { error: "soul requires { content: string }" };
      if (body.content.length > MAX_SOUL_CHARS) return { error: `SOUL must be at most ${MAX_SOUL_CHARS} characters` };
      if (body.expectedVersion === undefined) {
        await ctx.deps.config!.setSoul(scope, body.content, actor.id);
        return { ok: true };
      }
      if (typeof body.expectedVersion !== "number")
        return { error: "expectedVersion must be a number", code: "bad_version" };
      const version = await ctx.deps.config!.setSoulIfVersion(scope, body.expectedVersion, body.content, actor.id);
      if (version === null) {
        return {
          error: "SOUL changed after this draft was loaded. Reload before saving.",
          code: "version_conflict",
          status: 409,
        };
      }
      return { ok: true };
    },
  },
  {
    id: "ambient-policy",
    kind: "custom",
    readKey: "ambientPolicy",
    get: async (deps, scope) => {
      const ref = channelContainer(scope);
      if (!deps.channelPolicy || !ref) return undefined;
      const p = await deps.channelPolicy.get(ref).catch(swallowAs("admin: read channel ambient policy", undefined));
      if (p === undefined) return undefined;
      return {
        orders: p?.orders ?? "",
        bots: p?.bots ?? {},
        ambientEnabled: p?.ambientEnabled ?? null,
        updatedAt: p?.updatedAt ?? 0,
      };
    },
    apply: async (ctx, actor, scope) => {
      const deps = ctx.deps;
      if (!deps.channelPolicy) return { error: "not available on this deployment", status: 404 };
      const ref = channelContainer(scope);
      if (!ref) return { error: "ambient policy applies to channel and group scopes only" };
      const b = (ctx.body ?? {}) as {
        orders?: unknown;
        bots?: unknown;
        ambientEnabled?: unknown;
        baseUpdatedAt?: unknown;
      };
      if (typeof b.orders !== "string") return { error: "ambient-policy requires { orders: string }" };
      if (b.orders.length > MAX_ORDERS_CHARS)
        return {
          error: `standing order is capped at ${MAX_ORDERS_CHARS} characters — it is rendered into every ambient judgment`,
        };
      const parsed = parseBotLedger(b.bots);
      if ("error" in parsed) return { error: parsed.error };
      if (b.ambientEnabled !== undefined && b.ambientEnabled !== null && typeof b.ambientEnabled !== "boolean")
        return { error: "ambientEnabled must be a boolean or null (null = default rule)" };
      const current = await deps.channelPolicy.get(ref);
      if (typeof b.baseUpdatedAt === "number" && (current?.updatedAt ?? 0) !== b.baseUpdatedAt) {
        return {
          error: "this channel's policy changed since you loaded it — reload and re-apply your edit",
          code: "conflict",
          status: 409,
        };
      }
      await deps.channelPolicy.set(ref, b.orders, {
        setBy: actor.id,
        bots: parsed.bots,
        ambientEnabled: b.ambientEnabled as boolean | null | undefined,
      });
      audit(ctx.deps, { principalId: actor.id, action: "surface.policy.set", resource: ref, scopeLabel: scope });
      return { ok: true };
    },
  },
  {
    id: "egress",
    kind: "custom",
    readKey: "egress",
    get: (deps, scope) => deps.config!.getEgress(scope),
    apply: generic(
      (body) => {
        const parsed = parseEgressPolicy(body);
        return "error" in parsed ? parsed : { value: parsed.policy };
      },
      (deps, scope, v) => deps.config!.setEgress(scope, v),
    ),
  },
  {
    id: "feature-flags",
    kind: "custom",
    target: "org",
    readKey: "featureFlags",
    label: "Live feature rollout table. Each feature maps to the scopes where it is enabled.",
    get: async (deps) => {
      if (!deps.featureFlags) return undefined;
      const rows = await deps.featureFlags.list();
      return FEATURE_NAMES.map((featureName) => ({
        ...FEATURES[featureName],
        ...(rows.find((row) => row.featureName === featureName) ?? { featureName, enabledScopes: [] }),
      }));
    },
    apply: async (ctx, actor, scope) => {
      if (!ctx.deps.featureFlags) return { error: "not available on this deployment", status: 404 };
      const body = (ctx.body ?? {}) as { featureName?: unknown; scopeId?: unknown; on?: unknown };
      if (typeof body.featureName !== "string" || !(FEATURE_NAMES as readonly string[]).includes(body.featureName)) {
        return { error: `feature-flags requires featureName: ${FEATURE_NAMES.join(" | ")}` };
      }
      if (typeof body.scopeId !== "string" || !body.scopeId.trim()) {
        return { error: "feature-flags requires scopeId" };
      }
      const before = await ctx.deps.featureFlags.enabled(body.featureName as FeatureName, body.scopeId as ScopeId);
      await ctx.deps.featureFlags.setEnabled(
        body.featureName as FeatureName,
        body.scopeId as ScopeId,
        body.on === true,
        actor.id,
      );
      audit(ctx.deps, {
        principalId: actor.id,
        action: "feature-flag.update",
        resource: `${body.featureName}:${body.scopeId}:${before}->${body.on === true}`,
        scopeLabel: scope,
      });
      return { ok: true };
    },
  },
  {
    id: "teams",
    kind: "custom",
    target: "org",
    readKey: "teams",
    label:
      "Teams. Each team is a team:<id> scope shared by its members. Send { id, name?, isolatedInOpen?, addMembers?, addAdmins?, drop?, addRooms?, dropRooms? } or { id, remove: true }. Rooms are channel or group scopes where the team stays available; isolatedInOpen keeps it isolated when the org posture is Open.",
    get: (deps) => deps.teams?.list(),
    apply: async (ctx, actor, scope) => {
      if (!ctx.deps.teams) return { error: "not available on this deployment", status: 404 };
      const change = parseTeamChange(ctx.body);
      if ("error" in change) return change;
      await ctx.deps.teams.apply(change, actor.id);
      audit(ctx.deps, {
        principalId: actor.id,
        action: change.remove ? "team.remove" : "team.update",
        resource: `team:${change.id}`,
        scopeLabel: scope,
      });
      return { ok: true };
    },
  },
  {
    id: "unfulfilled-insights",
    kind: "boolean",
    readKey: "unfulfilledInsights",
    get: (deps, scope) => deps.config!.getUnfulfilledInsights(scope),
    apply: generic(boolBody, (deps, scope, on) => deps.config!.setUnfulfilledInsights(scope, on)),
  },
  {
    id: "external-slack-participants",
    kind: "boolean",
    target: "org",
    label:
      "Supports external Slack participants: internal members may chat with the agent in Slack rooms whose audience includes an external user (Connect member or guest). Externals themselves still can't interact.",
    readKey: "externalSlackParticipants",
    get: (deps, scope) => deps.config!.getExternalSlackParticipants(scope),
    apply: generic<boolean>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the external-Slack-participants toggle is org-wide");
        if (bad) return bad;
        return boolBody(body);
      },
      (deps, scope, on) => deps.config!.setExternalSlackParticipants(scope, on),
    ),
  },
  {
    id: "channel-header-pin-default",
    kind: "boolean",
    target: "org",
    label:
      "Channel pinned-header default: on means the agent posts and pins its header message (naming the model in use) in every Slack channel unless a channel explicitly turns it off.",
    readKey: "channelHeaderPinDefault",
    get: (deps, scope) => (parseScopeId(scope).kind === "org" ? deps.config!.getChannelHeaderPin(scope) : undefined),
    apply: generic<boolean>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the channel pinned-header default is org-wide");
        if (bad) return bad;
        return boolBody(body);
      },
      (deps, scope, on) => deps.config!.setChannelHeaderPin(scope, on),
    ),
  },
  {
    id: "org-ambient",
    kind: "boolean",
    target: "org",
    label:
      "Ambient behavior org-wide: off means the agent never acts on overheard messages anywhere, regardless of per-channel settings.",
    readKey: "orgAmbient",
    get: (deps, scope) => (parseScopeId(scope).kind === "org" ? deps.config!.getOrgAmbient() : undefined),
    apply: generic<boolean>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the ambient switch here is org-wide");
        if (bad) return bad;
        return boolBody(body);
      },
      (deps, _scope, on) => deps.config!.setOrgAmbient(on),
    ),
  },
  {
    id: "interactive-fast-mode",
    kind: "boolean",
    target: "org",
    label:
      "Fast mode for interactive turns org-wide: on means human turns run in fast mode on fast-capable models unless the turn asks otherwise. Requires fast-mode quota with the provider.",
    readKey: "interactiveFastMode",
    get: (deps, scope) => (parseScopeId(scope).kind === "org" ? deps.config!.getInteractiveFastMode() : undefined),
    apply: generic<boolean>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the interactive fast-mode switch is org-wide");
        if (bad) return bad;
        return boolBody(body);
      },
      (deps, _scope, on) => deps.config!.setInteractiveFastMode(on),
    ),
  },
  {
    id: "individual-model-auth",
    kind: "boolean",
    target: "org",
    label:
      "Individual authorization for AI usage org-wide: on means each user must connect their own Claude or Codex account (API key or subscription login) before using the assistant; the org's shared model credentials are not used for their turns.",
    readKey: "individualModelAuth",
    get: (deps, scope) => (parseScopeId(scope).kind === "org" ? deps.config!.getIndividualModelAuth() : undefined),
    apply: generic<boolean>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the individual-authorization switch is org-wide");
        if (bad) return bad;
        return boolBody(body);
      },
      (deps, _scope, on) => deps.config!.setIndividualModelAuth(on),
    ),
  },
  {
    id: "memory-embedding-model",
    refreshesModels: true,
    kind: "enum",
    target: "org",
    clearable: true,
    readKey: "memoryEmbeddingModel",
    get enumValues() {
      return embeddingModelCatalog();
    },
    get: (deps) => deps.config!.getEmbeddingModelDurable(),
    apply: async (ctx, _actor, scope) => {
      const bad = orgOnly(scope, "the memory embedding model is org-wide");
      if (bad) return bad;
      const { modelId } = ctx.body as { modelId?: unknown };
      if (modelId !== null && (typeof modelId !== "string" || !modelId.trim()))
        return { error: "Provide an embedding modelId, or null to disable semantic recall" };
      if (modelId !== null && !resolveEmbeddingModel(modelId))
        return { error: "Unknown or unverified embedding model" };
      await ctx.deps.config!.setEmbeddingModel(modelId as string | null);
      return { ok: true };
    },
  },
  {
    id: "base-model",
    refreshesModels: true,
    kind: "enum",
    target: "any",
    clearable: true,
    readKey: "baseModel",
    get enumValues() {
      return selectableBaseModels();
    },
    get: (deps, scope) => deps.config!.getBaseModel(scope),
    apply: async (ctx, _actor, scope) => {
      const raw = (ctx.body as { modelId?: unknown }).modelId;
      if (raw !== undefined && raw !== null && typeof raw !== "string")
        return { error: "base-model requires { modelId: string } (empty string clears the override)" };
      const modelId = typeof raw === "string" ? raw.trim() : "";
      if (modelId && !resolveModel(modelId)) return { error: `unknown model id: ${modelId}` };
      const configuredKeys = ctx.deps.providerKeys ?? ALL_PROVIDERS_AVAILABLE;
      const managedKeys = ctx.deps.modelCredentials ? await ctx.deps.modelCredentials.availability() : configuredKeys;
      const unserviceable = (harness: string): { error: string } | null =>
        modelId && !modelServiceable(modelId, modelProviderAvailabilityFor(harness, configuredKeys, managedKeys))
          ? {
              error: `model ${modelId} isn't serviceable on this deployment: its provider key is not configured for the ${harness} harness`,
            }
          : null;
      const runtime = await ctx.deps.config!.getRuntimeSelectionDurable(scope);
      if (!modelId) await ctx.deps.config!.setRuntimeSelection(scope, null);
      else if (runtime) {
        if (!isHarnessId(runtime.harnessId) || !modelSupportedByHarness(modelId, runtime.harnessId))
          return { error: `model ${modelId} is not supported by ${runtime.harnessId}` };
        const bad = unserviceable(runtime.harnessId);
        if (bad) return bad;
        await ctx.deps.config!.setRuntimeSelection(scope, {
          harnessId: runtime.harnessId,
          modelId,
          ...(runtime.effortLevel ? { effortLevel: runtime.effortLevel } : {}),
          ...(typeof runtime.fastMode === "boolean"
            ? {
                fastMode:
                  runtime.fastMode &&
                  harnessSupportsFastMode(runtime.harnessId) &&
                  fastModeModelIds().includes(modelId),
              }
            : {}),
        });
      } else {
        const harnessId = harnessIdOrPi(ctx.deps.harnessId);
        const effective = await resolveRuntimeChoiceDurable(ctx.deps.config!, scopeId("org", configOrgId()), scope, {
          harnessId,
          modelId: defaultModelForHarness(harnessId, ctx.deps.baseModelDefault),
        });
        if (!modelSupportedByHarness(modelId, effective.harnessId))
          return { error: `model ${modelId} is not supported by ${effective.harnessId}` };
        const bad = unserviceable(effective.harnessId);
        if (bad) return bad;
        await ctx.deps.config!.setRuntimeSelection(scope, {
          harnessId: effective.harnessId,
          modelId,
          ...(effective.effortLevel ? { effortLevel: effective.effortLevel } : {}),
          ...(typeof effective.fastMode === "boolean"
            ? {
                fastMode:
                  effective.fastMode &&
                  harnessSupportsFastMode(effective.harnessId) &&
                  fastModeModelIds().includes(modelId),
              }
            : {}),
        });
      }
      return { ok: true };
    },
  },
  ...([undefined, "cron", "subagent", "fallback"] as const).map((purpose): AdminResource => ({
    id: purpose ? `${purpose}-runtime` : "runtime",
    refreshesModels: true,
    kind: "custom",
    target: purpose ? "org" : "any",
    clearable: true,
    readKey: purpose ? `${purpose}Runtime` : "runtime",
    get: async (deps, scope) =>
      purpose
        ? ((await deps.config!.getPurposeRuntimeDurable(purpose)) ?? null)
        : deps.config!.getRuntimeSelection(scope),
    apply: async (ctx, _actor, scope) => {
      if (purpose) {
        const bad = orgOnly(scope, `${purpose} runtime defaults are org-wide`);
        if (bad) return bad;
      }
      if ((ctx.body as { inherit?: unknown } | null)?.inherit === true || (purpose && ctx.body === null)) {
        if (purpose) await ctx.deps.config!.clearPurposeRuntime(purpose);
        else await ctx.deps.config!.setRuntimeSelection(scope, null);
        return { ok: true };
      }
      const harnessId = (ctx.body as { harnessId?: unknown }).harnessId;
      const modelId = (ctx.body as { modelId?: unknown }).modelId;
      const effortLevel = (ctx.body as { effortLevel?: unknown }).effortLevel ?? (purpose ? undefined : "auto");
      const fastMode = (ctx.body as { fastMode?: unknown }).fastMode ?? (purpose ? undefined : false);
      if (!isHarnessId(harnessId)) return { error: `runtime requires harnessId (${HARNESS_IDS.join(" | ")})` };
      const approved = (await ctx.deps.config!.getApprovedHarnessesDurable()) ?? [ctx.deps.harnessId ?? "pi"];
      if (!approved.includes(harnessId)) return { error: `harness ${harnessId} is not approved` };
      if (typeof modelId !== "string" || !modelSupportedByHarness(modelId, harnessId))
        return { error: `model ${String(modelId)} is not supported by ${harnessId}` };
      const thinkingLevels = thinkingLevelsForHarness(harnessId, modelId);
      if (effortLevel !== undefined && (typeof effortLevel !== "string" || !thinkingLevels.includes(effortLevel)))
        return { error: `runtime requires effortLevel (${thinkingLevels.join(" | ")}) for ${harnessId}` };
      if (fastMode !== undefined && typeof fastMode !== "boolean")
        return { error: "runtime requires fastMode (boolean)" };
      if (
        purpose &&
        fastMode === true &&
        (!harnessSupportsFastMode(harnessId) || !fastModeModelIds().includes(modelId))
      )
        return { error: `fast mode is not supported by ${harnessId} with ${modelId}` };
      const configuredKeys = ctx.deps.providerKeys ?? ALL_PROVIDERS_AVAILABLE;
      const managedKeys = ctx.deps.modelCredentials ? await ctx.deps.modelCredentials.availability() : configuredKeys;
      if (!modelServiceable(modelId, modelProviderAvailabilityFor(harnessId, configuredKeys, managedKeys)))
        return {
          error: `model ${modelId} isn't serviceable on this deployment: its provider key is not configured for the ${harnessId} harness`,
        };
      const choice = {
        harnessId,
        modelId,
        ...(typeof effortLevel === "string" ? { effortLevel } : {}),
        ...(typeof fastMode === "boolean"
          ? { fastMode: fastMode && harnessSupportsFastMode(harnessId) && fastModeModelIds().includes(modelId) }
          : {}),
      };
      if (purpose) await ctx.deps.config!.setPurposeRuntime(purpose, choice);
      else await ctx.deps.config!.setRuntimeSelection(scope, choice);
      return { ok: true };
    },
  })),
  {
    id: "approved-harnesses",
    kind: "string-list",
    target: "org",
    clearable: true,
    readKey: "approvedHarnesses",
    enumValues: HARNESS_IDS,
    get: (deps) => deps.config!.getApprovedHarnesses(),
    apply: generic(
      (body, { scope }) => {
        const bad = orgOnly(scope, "approved harnesses are org-wide");
        if (bad) return bad;
        const raw = (body as { ids?: unknown }).ids;
        if (!Array.isArray(raw)) return { error: "approved-harnesses requires { ids: string[] }" };
        if (raw.some((id) => !isHarnessId(id)))
          return { error: `unknown harness (expected ${HARNESS_IDS.join(" | ")})` };
        const ids = [...new Set(raw.filter(isHarnessId))];
        return { value: ids.length ? ids : null };
      },
      (deps, _scope, ids) => deps.config!.setApprovedHarnesses(ids),
    ),
  },
  {
    id: "webui-models",
    refreshesModels: true,
    kind: "string-list",
    target: "org",
    clearable: true,
    label:
      "Web UI model picker (ordered list of model ids; the org base model is the default selection, else the first). Empty restores the built-in set.",
    readKey: "webuiModels",
    get enumValues() {
      return selectableBaseModels();
    },
    get: (deps, scope) => deps.config!.getWebuiModels(scope),
    apply: generic<string[] | null>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the web UI model picker is org-wide");
        if (bad) return bad;
        const raw = (body as { ids?: unknown }).ids;
        if (raw !== undefined && raw !== null && !Array.isArray(raw)) {
          return { error: "webui-models requires { ids: string[] } (empty list restores the default picker)" };
        }
        const ids = Array.isArray(raw) ? raw.map((v) => (typeof v === "string" ? v.trim() : "")).filter(Boolean) : [];
        for (const id of ids) if (!resolveModel(id)) return { error: `unknown model id: ${id}` };
        const seen = new Set<string>();
        const unique = ids.filter((id) => (seen.has(id) ? false : (seen.add(id), true)));
        return { value: unique.length ? unique : null };
      },
      (deps, scope, ids) => deps.config!.setWebuiModels(scope, ids),
    ),
  },
  {
    id: "ack-emoji",
    kind: "string-list",
    target: "org",
    clearable: true,
    label:
      "Slack ack emoji (names the bot may react with to acknowledge a message). Empty restores the built-in rotation.",
    readKey: "ackEmoji",
    get: (deps, scope) => deps.config!.getAckEmoji(scope),
    apply: generic<string[] | null>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the ack emoji set is org-wide");
        if (bad) return bad;
        const raw = (body as { names?: unknown }).names;
        if (raw !== undefined && raw !== null && !Array.isArray(raw)) {
          return { error: "ack-emoji requires { names: string[] } (empty list restores the default rotation)" };
        }
        const input = Array.isArray(raw) ? raw.map((v) => (typeof v === "string" ? v : "")).join(",") : "";
        const names = parseAckEmoji(input);
        const supplied = Array.isArray(raw) ? raw.filter((v) => typeof v === "string" && v.trim()).length : 0;
        if (supplied && names.length !== supplied) {
          return { error: "ack-emoji names must be Slack emoji names (lowercase letters, digits, _ + -)" };
        }
        return { value: names.length ? names : null };
      },
      (deps, scope, names) => deps.config!.setAckEmoji(scope, names),
    ),
  },
  {
    id: "branding",
    kind: "custom",
    target: "org",
    clearable: true,
    readKey: "branding",
    get: (deps, scope) => deps.config!.getBranding(scope),
    apply: async (ctx, _actor, scope) => {
      const bad = orgOnly(scope, "branding is org-wide");
      if (bad) return bad;
      const body = (ctx.body ?? {}) as {
        accent?: unknown;
        mark?: unknown;
        markUrl?: unknown;
        selfLabel?: unknown;
        orgName?: unknown;
      };
      const accentInput = typeof body.accent === "string" ? body.accent.trim() : "";
      const markUrlInput = typeof body.markUrl === "string" ? body.markUrl.trim() : "";
      const value = sanitizeBranding(body);
      if (accentInput && !value?.accent) {
        return { error: "branding accent must be a hex color (e.g. #4f46e5)" };
      }
      if (markUrlInput && !value?.markUrl) {
        return { error: "branding mark image must be an https URL" };
      }
      await ctx.deps.config!.setBranding(scope, value ?? null);
      return { ok: true };
    },
  },
  {
    id: "browse-model",
    refreshesModels: true,
    kind: "enum",
    target: "org",
    clearable: true,
    label:
      "The model driving the browser agent in the browse skill, org-wide (empty follows the deployment's base model; fast mode applies only on Opus models).",
    readKey: "browseModel",
    get enumValues() {
      return selectableBaseModels();
    },
    get: (deps, scope) => deps.config!.getBrowseModel(scope),
    apply: async (ctx, _actor, scope) => {
      const bad = orgOnly(scope, "the browse model is org-wide");
      if (bad) return bad;
      const raw = (ctx.body as { modelId?: unknown }).modelId;
      if (raw !== undefined && raw !== null && typeof raw !== "string") {
        return { error: "browse-model requires { modelId: string } (empty string clears the override)" };
      }
      const modelId = typeof raw === "string" ? raw.trim() : "";
      if (modelId && !resolveModel(modelId)) return { error: `unknown model id: ${modelId}` };
      const configuredKeys = ctx.deps.providerKeys ?? ALL_PROVIDERS_AVAILABLE;
      const managedKeys = ctx.deps.modelCredentials ? await ctx.deps.modelCredentials.availability() : configuredKeys;
      const providers = modelProviderAvailabilityFor(ctx.deps.harnessId ?? "pi", configuredKeys, managedKeys);
      if (modelId && !modelServiceable(modelId, providers)) {
        return { error: `model ${modelId} isn't serviceable on this deployment: its provider key is not configured` };
      }
      await ctx.deps.config!.setBrowseModel(scope, modelId || null);
      return { ok: true };
    },
  },
  {
    id: "browse-max-steps",
    kind: "string",
    target: "org",
    clearable: true,
    label: "Max browser steps per browse task (empty restores the default of 50).",
    readKey: "browseMaxSteps",
    get: (deps, scope) => deps.config!.getBrowseMaxSteps(scope),
    apply: generic<number | null>(
      (body, { scope }) => {
        const bad = orgOnly(scope, "the browse step limit is org-wide");
        if (bad) return bad;
        const raw = (body as { steps?: unknown }).steps;
        if (raw === undefined || raw === null || raw === "") return { value: null };
        let steps = NaN;
        if (typeof raw === "number") steps = raw;
        else if (typeof raw === "string") steps = Number(raw.trim());
        if (!Number.isInteger(steps) || steps < 1 || steps > 500) {
          return { error: "browse-max-steps requires { steps: integer 1-500 } (empty clears to the default of 50)" };
        }
        return { value: steps };
      },
      (deps, scope, steps) => deps.config!.setBrowseMaxSteps(scope, steps),
    ),
  },
  {
    id: "connectors",
    kind: "custom",
    readKey: "connectors",
    get: (deps, scope) => deps.config!.listConnectorClients(scope),
    apply: async (ctx, actor, scope) => {
      const { deps } = ctx;
      const b = ctx.body as {
        provider?: unknown;
        clientId?: unknown;
        clientSecret?: unknown;
        scopes?: unknown;
        redirectAllowlist?: unknown;
        consentMode?: unknown;
        hostedDomain?: unknown;
        enabled?: unknown;
        delete?: unknown;
      };
      const provider = typeof b.provider === "string" ? b.provider : "";
      if (!PROVIDERS[provider]) return { error: `unknown OAuth provider: ${provider}` };
      if (b.delete === true) {
        await deps.config!.deleteConnectorClient(scope, provider);
        return { ok: true };
      }
      if (typeof b.clientId !== "string" || typeof b.clientSecret !== "string") {
        return { error: "connectors requires { provider, clientId, clientSecret }" };
      }
      await deps.config!.setConnectorClient(scope, provider, {
        clientId: b.clientId,
        clientSecret: b.clientSecret,
        ...(Array.isArray(b.scopes) ? { scopes: b.scopes.map(String) } : {}),
        ...(Array.isArray(b.redirectAllowlist) ? { redirectAllowlist: b.redirectAllowlist.map(String) } : {}),
        ...(typeof b.consentMode === "string" ? { consentMode: b.consentMode as ConsentMode } : {}),
        ...(typeof b.hostedDomain === "string" ? { hostedDomain: b.hostedDomain } : {}),
        ...(typeof b.enabled === "boolean" ? { enabled: b.enabled } : {}),
        updatedBy: actor.id,
      });
      try {
        const client = await resolverFor(deps)(provider, {});
        authorizeUrl(provider, {
          redirectUri: client.redirectAllowlist?.[0] ?? "https://example.invalid/cb",
          state: "dry-run",
          client,
        });
      } catch (e) {
        return { error: errMessage(e), code: "connector_invalid" };
      }
      return { ok: true };
    },
  },
  {
    id: "service-credentials",
    kind: "custom",
    target: "org",
    secret: true,
    apply: async (ctx, actor, scope) => {
      const { deps } = ctx;
      if (!deps.acl) return { error: "ACL store not wired", code: "not_found", status: 404 };
      if (!deps.serviceCreds) return { error: "credential store not wired", code: "not_found", status: 404 };
      const bad = orgOnly(scope, "service credentials are org-scoped");
      if (bad) return bad;
      const b = ctx.body as {
        slug?: unknown;
        name?: unknown;
        secret?: unknown;
        delivery?: unknown;
        envKey?: unknown;
        host?: unknown;
        injection?: unknown;
        allowedMethods?: unknown;
        allowedPathPrefixes?: unknown;
        deployments?: unknown;
        enabled?: unknown;
        grantees?: unknown;
        delete?: unknown;
        expectedUpdatedAt?: unknown;
      };
      const slug = typeof b.slug === "string" ? b.slug : "";
      if (!isValidCredentialSlug(slug)) return { error: "slug must be lowercase kebab-case (a-z, 0-9, -)" };
      const ref = encodeRef(serviceCredRef(slug));
      const allCreds = await deps.serviceCreds.listServiceCredentials(scope);
      const existing = allCreds.find((c) => c.slug === slug);
      if (existing?.source === "deployment")
        return {
          error: `"${slug}" is supplied by this deployment's configuration and can't be edited, deleted or reused here.`,
          code: "deployment_credential",
          status: 409,
        };
      const conflict = () => ({
        error: "Credential changed after this editor was loaded. Reload it before continuing.",
        code: "version_conflict",
        status: 409,
      });
      if ((existing || b.delete === true) && typeof b.expectedUpdatedAt !== "number") {
        return {
          error: "Existing credential edits and deletes require the version you loaded.",
          code: "version_required",
        };
      }
      if (!existing && typeof b.expectedUpdatedAt === "number") return conflict();
      const grantsBefore = await deps.acl.grantsFor(scope, ref);
      const secretBefore = existing ? await deps.serviceCreds.getServiceCredentialSecret(scope, slug) : null;
      const desiredGrants = (desired: string[]): Grant[] => {
        const desiredSet = new Set(desired);
        const replacement = grantsBefore.filter((grant) => desiredSet.has(grant.granteeScopeId));
        const currentSet = new Set(replacement.map((grant) => grant.granteeScopeId));
        for (const granteeScopeId of desired) {
          if (!currentSet.has(granteeScopeId))
            replacement.push({ ownerScopeId: scope, ref, granteeScopeId, permission: "read", grantedBy: actor.id });
        }
        return replacement;
      };
      const grantChanges = (replacement: readonly Grant[]): Array<{ action: "share" | "unshare"; grantee: string }> => {
        const changes: Array<{ action: "share" | "unshare"; grantee: string }> = [];
        const before = new Set(grantsBefore.map((grant) => grant.granteeScopeId));
        const after = new Set(replacement.map((grant) => grant.granteeScopeId));
        for (const grantee of before) if (!after.has(grantee)) changes.push({ action: "unshare", grantee });
        for (const grantee of after) if (!before.has(grantee)) changes.push({ action: "share", grantee });
        return changes;
      };
      const restoreInput = (
        credential: PublicServiceCredential,
        secret: DecryptedServiceCredential | null,
      ): ServiceCredentialInput => ({
        slug: credential.slug,
        name: credential.name,
        delivery: credential.delivery,
        ...(credential.envKey ? { envKey: credential.envKey } : {}),
        host: credential.host,
        ...(secret?.secret ? { secret: secret.secret } : {}),
        ...(credential.injection ? { injection: credential.injection } : {}),
        ...(credential.allowedMethods ? { allowedMethods: credential.allowedMethods } : {}),
        ...(credential.allowedPathPrefixes ? { allowedPathPrefixes: credential.allowedPathPrefixes } : {}),
        deployments: credential.deployments,
        enabled: credential.enabled,
        ...(credential.updatedBy ? { updatedBy: credential.updatedBy } : {}),
      });
      const publicShape = (credential: PublicServiceCredential | undefined) =>
        credential &&
        JSON.stringify({
          slug: credential.slug,
          name: credential.name,
          delivery: credential.delivery,
          envKey: credential.envKey ?? null,
          host: credential.host,
          injection: credential.injection ?? null,
          allowedMethods: credential.allowedMethods ?? null,
          allowedPathPrefixes: credential.allowedPathPrefixes ?? null,
          deployments: credential.deployments,
          enabled: credential.enabled,
          hasSecret: credential.hasSecret,
          updatedBy: credential.updatedBy ?? null,
        });
      const grantShape = (grants: readonly Grant[]) =>
        JSON.stringify(
          grants
            .map((grant) => ({
              ownerScopeId: grant.ownerScopeId,
              ref: grant.ref,
              granteeScopeId: grant.granteeScopeId,
              permission: grant.permission,
              grantedBy: grant.grantedBy,
            }))
            .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
        );
      let mutationVersion: number | null = null;
      let deletedCredential = false;
      let grantsWritten = grantsBefore;
      const rollback = async (): Promise<boolean> => {
        try {
          let credentialRestored: boolean;
          if (!existing) {
            credentialRestored =
              mutationVersion !== null &&
              (await deps.serviceCreds!.deleteServiceCredentialIfCurrent(scope, slug, mutationVersion));
          } else if (deletedCredential) {
            credentialRestored =
              (await deps.serviceCreds!.setServiceCredentialIfAbsent(scope, restoreInput(existing, secretBefore))) !==
              null;
          } else {
            credentialRestored =
              mutationVersion !== null &&
              (await deps.serviceCreds!.setServiceCredentialIfCurrent(
                scope,
                restoreInput(existing, secretBefore),
                mutationVersion,
              )) !== null;
          }
          if (!credentialRestored) return false;
          const grantsRestored =
            (await deps.acl!.replaceGrantsIfCurrent(scope, ref, grantsWritten, grantsBefore, actor.id)) ||
            grantShape(await deps.acl!.grantsFor(scope, ref)) === grantShape(grantsBefore);
          if (!grantsRestored) return false;
          const restored = (await deps.serviceCreds!.listServiceCredentials(scope)).find(
            (credential) => credential.slug === slug,
          );
          const restoredSecret = restored ? await deps.serviceCreds!.getServiceCredentialSecret(scope, slug) : null;
          const restoredGrants = await deps.acl!.grantsFor(scope, ref);
          return (
            publicShape(restored) === publicShape(existing) &&
            (restoredSecret?.secret ?? null) === (secretBefore?.secret ?? null) &&
            grantShape(restoredGrants) === grantShape(grantsBefore)
          );
        } catch {
          return false;
        }
      };
      const mutationFailed = async (operation: string): Promise<ApplyResult> => {
        const rolledBack = await rollback();
        return {
          error: rolledBack
            ? `Credential ${operation} failed; the previous credential and grants were restored.`
            : `Credential ${operation} failed and rollback could not be verified. Review this credential before retrying.`,
          code: rolledBack ? "credential_mutation_rolled_back" : "credential_mutation_inconsistent",
          status: 500,
        };
      };
      const auditGrantChanges = (changes: Array<{ action: "share" | "unshare"; grantee: string }>) => {
        for (const change of changes)
          audit(deps, {
            principalId: actor.id,
            action: `service_credential.${change.action}`,
            resource: ref,
            scopeLabel: change.grantee,
          });
      };
      if (b.delete === true) {
        if (
          !existing ||
          !(await deps.serviceCreds.deleteServiceCredentialIfCurrent(scope, slug, b.expectedUpdatedAt as number))
        )
          return conflict();
        deletedCredential = true;
        const replacement: Grant[] = [];
        grantsWritten = replacement;
        try {
          if (!(await deps.acl.replaceGrantsIfCurrent(scope, ref, grantsBefore, replacement, actor.id)))
            return mutationFailed("delete");
          auditGrantChanges(grantChanges(replacement));
          return { ok: true };
        } catch (e) {
          reportFailure("admin: credential delete after conditional mutation", e);
          return mutationFailed("delete");
        }
      }
      const name = typeof b.name === "string" && b.name.trim() ? b.name.trim() : "";
      const deliveryRaw = b.delivery === undefined ? (existing?.delivery ?? "broker") : b.delivery;
      if (deliveryRaw !== "broker" && deliveryRaw !== "env") return { error: 'delivery must be "broker" or "env"' };
      const delivery: "broker" | "env" = deliveryRaw;
      const envKey = typeof b.envKey === "string" && b.envKey.trim() ? b.envKey.trim() : undefined;
      if (delivery === "env") {
        if (!envKey || !isValidServiceCredentialEnvKey(envKey)) {
          return {
            error: "env delivery requires an UPPER_SNAKE_CASE env var name outside the reserved AGENT_* namespace",
          };
        }
        const clash = allCreds.find((c) => c.slug !== slug && c.delivery === "env" && c.envKey === envKey);
        if (clash) return { error: `env var ${envKey} is already delivered by credential "${clash.slug}"` };
      } else if (envKey) {
        return { error: "an env var name only applies to env delivery" };
      }
      const host = typeof b.host === "string" ? b.host.trim().toLowerCase() : "";
      if (!name) return { error: "service-credentials requires { slug, name }" };
      if (delivery === "broker" && !isValidBrokerHost(host)) {
        return { error: "broker delivery requires { host } (a bare hostname)" };
      }
      if (delivery === "env" && host) return { error: "a pinned host only applies to broker delivery" };
      if (!existing && (typeof b.secret !== "string" || !b.secret)) {
        return { error: "a new credential requires a secret" };
      }
      const methods = Array.isArray(b.allowedMethods)
        ? b.allowedMethods
            .map(String)
            .map((method) => method.trim().toUpperCase())
            .filter(Boolean)
        : undefined;
      if (methods?.some((method) => !isValidBrokerMethod(method)))
        return { error: "allowed methods must be comma-separated HTTP method names" };
      const paths = Array.isArray(b.allowedPathPrefixes)
        ? b.allowedPathPrefixes
            .map(String)
            .map((path) => path.trim())
            .filter(Boolean)
        : undefined;
      if (paths?.some((path) => !isValidBrokerPathPrefix(path)))
        return { error: "each allowed path prefix must be one line starting with /" };
      const desired = Array.isArray(b.grantees) ? [...new Set(b.grantees.map(String))] : undefined;
      const badGrantee = desired?.find((g) => {
        const parsed = parseScopeId(g);
        return (
          !["org", "personal", "team", "channel"].includes(parsed.kind ?? "") ||
          !parsed.ref ||
          parsed.ref.includes(":") ||
          (parsed.kind === "org" && g !== scope)
        );
      });
      if (badGrantee !== undefined)
        return { error: `grantee must be this org or a valid personal:/team:/channel: scope (got ${badGrantee})` };
      if (b.deployments !== undefined && typeof b.deployments !== "boolean")
        return { error: "deployments must be true or false" };
      const injectionError = credentialInjectionError(b.injection);
      if (injectionError) return { error: injectionError };
      const injection = b.injection as CredentialInjection | undefined;
      const effectiveInjection = b.injection === undefined ? existing?.injection : injection;
      let brokerMethods: { allowedMethods?: string[] } = {};
      if (methods) brokerMethods = { allowedMethods: methods };
      else if (existing?.allowedMethods) brokerMethods = { allowedMethods: existing.allowedMethods };
      let brokerPaths: { allowedPathPrefixes?: string[] } = {};
      if (paths) brokerPaths = { allowedPathPrefixes: paths };
      else if (existing?.allowedPathPrefixes) brokerPaths = { allowedPathPrefixes: existing.allowedPathPrefixes };
      const input = {
        slug,
        name,
        delivery,
        ...(delivery === "env" ? { envKey } : {}),
        host: delivery === "env" ? "" : host,
        ...(typeof b.secret === "string" && b.secret ? { secret: b.secret } : {}),
        ...(delivery === "broker" && effectiveInjection && Object.keys(effectiveInjection).length
          ? { injection: effectiveInjection }
          : {}),
        ...(delivery === "broker" ? brokerMethods : {}),
        ...(delivery === "broker" ? brokerPaths : {}),
        deployments: typeof b.deployments === "boolean" ? b.deployments : (existing?.deployments ?? true),
        enabled: typeof b.enabled === "boolean" ? b.enabled : (existing?.enabled ?? true),
        updatedBy: actor.id,
      };
      if (existing) {
        mutationVersion = await deps.serviceCreds.setServiceCredentialIfCurrent(
          scope,
          input,
          b.expectedUpdatedAt as number,
        );
        if (mutationVersion === null) return conflict();
      } else {
        mutationVersion = await deps.serviceCreds.setServiceCredentialIfAbsent(scope, input);
        if (mutationVersion === null) return conflict();
      }
      const replacement = desiredGrants(
        desired ?? (existing ? grantsBefore.map((grant) => grant.granteeScopeId) : [scope]),
      );
      grantsWritten = replacement;
      try {
        if (!(await deps.acl.replaceGrantsIfCurrent(scope, ref, grantsBefore, replacement, actor.id)))
          return mutationFailed(existing ? "update" : "create");
        auditGrantChanges(grantChanges(replacement));
        return { ok: true };
      } catch (e) {
        reportFailure("admin: credential update after conditional mutation", e);
        return mutationFailed(existing ? "update" : "create");
      }
    },
  },
];

export const ADMIN_RESOURCE_BY_ID = new Map(ADMIN_RESOURCES.map((r) => [r.id, r]));

export interface AdminResourceManifestEntry {
  id: string;
  kind: AdminResourceKind;
  target?: "org" | "any";
  secret?: boolean;
  clearable?: boolean;
  authz?: "scope-admin" | "org-admin";
  label?: string;
  enumValues?: readonly unknown[];
}

export function adminResourceManifest(): AdminResourceManifestEntry[] {
  return ADMIN_RESOURCES.map((r) => ({
    id: r.id,
    kind: r.kind,
    ...(r.target ? { target: r.target } : {}),
    ...(r.secret ? { secret: true } : {}),
    ...(r.clearable ? { clearable: true } : {}),
    ...(r.authz ? { authz: r.authz } : {}),
    ...(r.label ? { label: r.label } : {}),
    ...(r.enumValues ? { enumValues: r.enumValues } : {}),
  }));
}

const TEAM_ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
const TEAM_LISTS = ["addMembers", "addAdmins", "drop", "addRooms", "dropRooms"] as const;

function parseTeamChange(body: unknown): TeamChange | { error: string } {
  const b = (body ?? {}) as Record<string, unknown>;
  if (typeof b.id !== "string" || !TEAM_ID.test(b.id))
    return { error: "teams requires id: lowercase letters, digits, -" };
  if (b.remove === true) return { id: b.id, remove: true };
  const lists: Partial<Record<(typeof TEAM_LISTS)[number], string[]>> = {};
  for (const key of TEAM_LISTS) {
    const v = b[key] ?? [];
    if (!Array.isArray(v) || !v.every((x) => typeof x === "string" && x.trim()))
      return { error: `${key} must be an array of non-empty strings` };
    lists[key] = [...new Set(v as string[])];
  }
  const isRoom = (r: string) => {
    const { kind, ref } = parseScopeId(r as ScopeId);
    return (kind === "channel" || kind === "group") && !!ref;
  };
  if (![...lists.addRooms!, ...lists.dropRooms!].every(isRoom))
    return { error: "rooms must be channel:<id> or group:<id> scopes" };
  return {
    id: b.id,
    ...(typeof b.name === "string" && b.name.trim() ? { name: b.name.trim() } : {}),
    ...(typeof b.isolatedInOpen === "boolean" ? { isolatedInOpen: b.isolatedInOpen } : {}),
    ...lists,
    addRooms: lists.addRooms as ScopeId[],
    dropRooms: lists.dropRooms as ScopeId[],
  };
}