@opengeni/api-router 2.5.0 → 2.6.4-canary.0

package/src/routes/workspaces.ts

@@ -1,73 +1,119 @@
+import { createHash } from "node:crypto";
 import {
   AddWorkspaceMemberRequest,
   CreateWorkspaceRequest,
+  EnsureWorkspaceRequest,
+  EnsureWorkspaceResponse,
+  ListWorkspaceMemberCandidatesResponse,
   ListWorkspaceMembersResponse,
   SetWorkspaceDefaultRigRequest,
   UpdateWorkspaceMemberRequest,
+  CreateWorkspaceGatewayCustomModelRequest,
+  CreateWorkspaceOpenRouterCustomModelRequest,
+  DeleteWorkspaceGatewayCustomModelRequest,
+  DeleteWorkspaceOpenRouterCustomModelRequest,
   UpdateWorkspaceModelPolicyRequest,
   UpdateWorkspaceRequest,
   UpdateWorkspaceSettingsRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
   WorkspaceModelCatalogResponse,
+  WorkspaceGatewayCustomModel,
+  WorkspaceGatewayCustomModelsResponse,
+  WorkspaceOpenRouterCustomModel,
+  WorkspaceOpenRouterCustomModelsResponse,
   WorkspaceRealtimeModelCatalogResponse,
   WorkspaceInferenceControlRequest,
   Workspace,
   WorkspaceMember,
   workspaceControlUtf8Bytes,
+  stableJson,
   type AccessContext,
   type Permission,
+  type WorkspaceMemberCandidate,
   type WorkspaceMember as WorkspaceMemberValue,
 } from "@opengeni/contracts";
 import {
   allWorkspacePermissions,
   createWorkspace,
   deleteWorkspaceIfQuiescent,
-  getManagedUserByEmail,
+  ensureWorkspaceByExternalIdentity,
+  findWorkspaceByExternalIdentity,
+  getManagedUserProfilesByIds,
   getWorkspaceModelPolicy,
   grantWorkspaceAccess,
   listWorkspaceMembers,
+  listWorkspaceMemberManagementCandidates,
   normalizeWorkspaceMembershipPermissions,
   listWorkspaceControlEvents,
+  listSharedWorkspacesForAccount,
+  listWorkspaceGatewayCustomModels,
+  listWorkspaceOpenRouterCustomModels,
+  createWorkspaceGatewayCustomModel,
+  createWorkspaceOpenRouterCustomModel,
+  deleteWorkspaceGatewayCustomModel,
+  deleteWorkspaceOpenRouterCustomModel,
+  replayWorkspaceGatewayCustomModelCreate,
+  replayWorkspaceOpenRouterCustomModelCreate,
   listWorkspacesForSubject,
+  nestedPostgresSqlState,
   removeWorkspaceMember,
   requireWorkspace,
   getRig,
   setWorkspaceDefaultRig,
   updateWorkspace,
   updateWorkspaceSettings,
+  upsertWorkspaceMemberAsWorkspaceManager,
   upsertWorkspaceModelPolicy,
   workspaceCodexSubscriptionActive,
   workspaceControlRequestLockTimeoutMs,
   workspaceXaiSubscriptionActive,
   workspaceVercelAiGatewayConnectionActive,
+  workspaceOpenRouterConnectionActive,
+  WorkspaceGatewayCustomModelHistoryLimitError,
+  WorkspaceOpenRouterCustomModelHistoryLimitError,
+  WorkspaceExternalIdentityConflictError,
+  WorkspaceGatewayCustomModelLimitError,
+  WorkspaceOpenRouterCustomModelLimitError,
+  WorkspaceLimitExceededError,
 } from "@opengeni/db";
 import { boundWorkspaceControlHttpPage } from "@opengeni/events";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import {
   getManagedAuthRequestActorEpoch,
+  accountScopedApiKeyWorkspaceAuthority,
   hasPermission,
   requireAccessContext,
   requireAccessGrant,
   requireFreshAccessGrant,
+  resolveWorkspaceCatalogSettings,
 } from "@opengeni/core";
 import { requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   assertWorkspaceMemberRemovable,
+  assertWorkspaceMemberUpdateAllowed,
   controlHumanWorkspace,
-  resolveMemberSubjectId,
 } from "@opengeni/core";
 import { boundedLimit } from "../http/common";
 import { ApiHttpError } from "../http/api-error";
-import { sseWorkspaceControlStream } from "../http/sse";
+import { browserSseDeliveryOptions, sseWorkspaceControlStream } from "../http/sse";
 import { buildWorkspaceModelCatalog } from "../model-catalog";
 import { processTemporalScheduleCleanupClaims } from "../temporal-schedule-cleanup";
+import { workspaceDeleteObserver } from "../workspace-delete-observability";
 import {
   AI_GATEWAY_REALTIME_MODELS,
   CODEX_REALTIME_MODEL_ID,
   SUPERGROK_REALTIME_MODEL_ID,
   canonicalizeConfiguredModelId,
+  configuredStaticUsageLimits,
+  configuredGatewayUpstreamModelIds,
+  configuredGatewayWorkspaceProductModelIds,
+  configuredModelInputIdentities,
+  configuredOpenRouterUpstreamModelIds,
+  configuredOpenRouterWorkspaceProductModelIds,
+  WORKSPACE_GATEWAY_MODEL_ID_PREFIX,
+  WORKSPACE_OPENROUTER_MODEL_ID_PREFIX,
   type Settings,
 } from "@opengeni/config";
 
@@ -81,6 +127,46 @@ export function canonicalWorkspacePolicyModelIds(
   return [...new Set(modelIds.map((modelId) => canonicalizeConfiguredModelId(settings, modelId)))];
 }
 
+function projectWorkspaceGatewayCustomModel(model: {
+  id: string;
+  upstreamModelId: string;
+  label: string | null;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+}) {
+  return WorkspaceGatewayCustomModel.parse({
+    id: model.id,
+    upstreamModelId: model.upstreamModelId,
+    label: model.label,
+    version: model.version,
+    createdAt: model.createdAt.toISOString(),
+    updatedAt: model.updatedAt.toISOString(),
+  });
+}
+
+function projectWorkspaceOpenRouterCustomModel(model: {
+  id: string;
+  upstreamModelId: string;
+  label: string | null;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+}) {
+  return WorkspaceOpenRouterCustomModel.parse({
+    id: model.id,
+    upstreamModelId: model.upstreamModelId,
+    label: model.label,
+    version: model.version,
+    createdAt: model.createdAt.toISOString(),
+    updatedAt: model.updatedAt.toISOString(),
+  });
+}
+
+function workspaceCustomModelRequestHash(value: unknown): string {
+  return createHash("sha256").update(stableJson(value), "utf8").digest("hex");
+}
+
 type WorkspaceMemberProjectionInput = Omit<WorkspaceMemberValue, "permissions"> & {
   permissions: unknown;
 };
@@ -114,6 +200,17 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces", async (c) => {
     const context = await requireAccessContext(c, deps);
+    const accountScopedAuthority = accountScopedApiKeyWorkspaceAuthority(context);
+    if (
+      accountScopedAuthority &&
+      hasPermission(accountScopedAuthority.permissions, "workspace:read")
+    ) {
+      return c.json(
+        (await listSharedWorkspacesForAccount(deps.db, accountScopedAuthority.accountId)).map(
+          (workspace) => Workspace.parse(workspace),
+        ),
+      );
+    }
     const readableWorkspaceIds = [
       ...new Set(
         context.workspaceGrants
@@ -134,34 +231,103 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  app.put("/v1/workspaces/external", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const payload = EnsureWorkspaceRequest.parse(await c.req.json());
+    requireAccountPermission(context, payload.accountId, "workspace:create");
+    try {
+      const existing = await findWorkspaceByExternalIdentity(deps.db, {
+        externalSource: payload.externalSource,
+        externalId: payload.externalId,
+      });
+      if (existing) {
+        if (existing.accountId !== payload.accountId || existing.kind !== "shared") {
+          throw new WorkspaceExternalIdentityConflictError();
+        }
+        return c.json(
+          EnsureWorkspaceResponse.parse({
+            workspace: existing,
+            created: false,
+          }),
+        );
+      }
+      await requireLimit(deps, {
+        accountId: payload.accountId,
+        action: "workspace:create",
+        quantity: 1,
+      });
+      const result = await ensureWorkspaceByExternalIdentity(deps.db, {
+        accountId: payload.accountId,
+        externalSource: payload.externalSource,
+        externalId: payload.externalId,
+        name: payload.name,
+        slug: payload.slug ?? null,
+        ...(payload.agentInstructions !== undefined
+          ? {
+              agentInstructions: normalizeAgentInstructions(payload.agentInstructions),
+            }
+          : {}),
+        maxWorkspacesPerAccount: workspaceLimit(deps),
+      });
+      const response = EnsureWorkspaceResponse.parse(result);
+      return result.created ? c.json(response, 201) : c.json(response);
+    } catch (error) {
+      if (error instanceof WorkspaceExternalIdentityConflictError) {
+        throw new HTTPException(409, {
+          message: "external workspace identity is already in use",
+        });
+      }
+      if (error instanceof WorkspaceLimitExceededError) {
+        throw new HTTPException(429, { message: error.message });
+      }
+      throw error;
+    }
+  });
+
   app.post("/v1/workspaces", async (c) => {
     const context = await requireAccessContext(c, deps);
     const payload = CreateWorkspaceRequest.parse(await c.req.json());
     const accountId = payload.accountId ?? context.defaultAccountId;
     if (!accountId) {
-      throw new HTTPException(409, { message: "account selection is required" });
+      throw new HTTPException(409, {
+        message: "account selection is required",
+      });
     }
     requireAccountPermission(context, accountId, "workspace:create");
-    await requireLimit(deps, { accountId, action: "workspace:create", quantity: 1 });
-    const workspace = await createWorkspace(deps.db, {
-      accountId,
-      name: payload.name.trim(),
-      slug: payload.slug?.trim() || null,
-      externalSource: payload.externalSource ?? null,
-      externalId: payload.externalId ?? null,
-      ...(payload.agentInstructions !== undefined
-        ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) }
-        : {}),
-    });
-    await grantWorkspaceAccess(deps.db, {
+    await requireLimit(deps, {
       accountId,
-      workspaceId: workspace.id,
-      subjectId: context.subjectId,
-      role: "owner",
-      permissions: allWorkspacePermissions,
-      ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
+      action: "workspace:create",
+      quantity: 1,
     });
-    return c.json(Workspace.parse(workspace), 201);
+    try {
+      const workspace = await createWorkspace(deps.db, {
+        accountId,
+        name: payload.name.trim(),
+        slug: payload.slug?.trim() || null,
+        externalSource: payload.externalSource ?? null,
+        externalId: payload.externalId ?? null,
+        ...(payload.agentInstructions !== undefined
+          ? {
+              agentInstructions: normalizeAgentInstructions(payload.agentInstructions),
+            }
+          : {}),
+        maxWorkspacesPerAccount: workspaceLimit(deps),
+      });
+      await grantWorkspaceAccess(deps.db, {
+        accountId,
+        workspaceId: workspace.id,
+        subjectId: context.subjectId,
+        role: "owner",
+        permissions: allWorkspacePermissions,
+        ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
+      });
+      return c.json(Workspace.parse(workspace), 201);
+    } catch (error) {
+      if (error instanceof WorkspaceLimitExceededError) {
+        throw new HTTPException(429, { message: error.message });
+      }
+      throw error;
+    }
   });
 
   app.get("/v1/workspaces/:workspaceId", async (c) => {
@@ -189,7 +355,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       ...(payload.name !== undefined ? { name: payload.name.trim() } : {}),
       ...(payload.slug !== undefined ? { slug: payload.slug?.trim() || null } : {}),
       ...(payload.agentInstructions !== undefined
-        ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) }
+        ? {
+            agentInstructions: normalizeAgentInstructions(payload.agentInstructions),
+          }
         : {}),
     });
     return c.json(Workspace.parse(workspace));
@@ -202,7 +370,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     const parsed = UpdateWorkspaceSettingsRequest.safeParse(await c.req.json());
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid workspace settings patch" });
+      throw new HTTPException(400, {
+        message: "invalid workspace settings patch",
+      });
     }
     // Request-scoped: bound the exclusive control-prefix wait so a busy
     // workspace yields the retryable 503 instead of parking this request.
@@ -220,30 +390,323 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
     const [
+      resolvedCatalog,
       policy,
       codexSubscriptionActive,
       xaiSubscriptionActive,
       workspaceGatewayConnectionActive,
+      workspaceGatewayCustomModels,
+      openRouterConnectionActive,
+      workspaceOpenRouterCustomModels,
     ] = await Promise.all([
+      deps.resolveCatalogSettings(),
       getWorkspaceModelPolicy(deps.db, workspaceId),
       workspaceCodexSubscriptionActive(deps.db, deps.settings, workspaceId),
       workspaceXaiSubscriptionActive(deps.db, deps.settings, workspaceId, grant.subjectId),
       workspaceVercelAiGatewayConnectionActive(deps.db, workspaceId),
+      listWorkspaceGatewayCustomModels(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+      }),
+      workspaceOpenRouterConnectionActive(deps.db, workspaceId),
+      listWorkspaceOpenRouterCustomModels(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+      }),
     ]);
     c.header("cache-control", "private, no-store");
     return c.json(
       WorkspaceModelCatalogResponse.parse(
         buildWorkspaceModelCatalog({
-          settings: deps.settings,
+          settings: resolvedCatalog.settings,
           policy,
           codexSubscriptionActive,
           xaiSubscriptionActive,
           workspaceGatewayConnectionActive,
+          workspaceGatewayCustomModels,
+          workspaceOpenRouterConnectionActive: openRouterConnectionActive,
+          workspaceOpenRouterCustomModels,
         }),
       ),
     );
   });
 
+  app.get("/v1/workspaces/:workspaceId/gateway-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const models = await listWorkspaceGatewayCustomModels(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
+    c.header("cache-control", "private, no-store");
+    return c.json(
+      WorkspaceGatewayCustomModelsResponse.parse({
+        models: models.map(projectWorkspaceGatewayCustomModel),
+      }),
+    );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/gateway-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const parsed = CreateWorkspaceGatewayCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "invalid Gateway custom model" });
+    }
+    const requestHash = workspaceCustomModelRequestHash({
+      action: "create",
+      upstreamModelId: parsed.data.upstreamModelId,
+      label: parsed.data.label ?? null,
+    });
+    const replay = await replayWorkspaceGatewayCustomModelCreate(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      operationId: parsed.data.operationId,
+      requestHash,
+    });
+    if (replay.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "Gateway custom model operation conflicts with current state",
+      });
+    }
+    if (replay.outcome === "success") {
+      return c.json(projectWorkspaceGatewayCustomModel(replay.model), 201);
+    }
+    const catalog = await deps.resolveCatalogSettings();
+    if (configuredGatewayUpstreamModelIds(catalog.settings).includes(parsed.data.upstreamModelId)) {
+      throw new HTTPException(422, {
+        message: "Gateway model is already included in the deployment catalog",
+      });
+    }
+    const customProductId = `${WORKSPACE_GATEWAY_MODEL_ID_PREFIX}${parsed.data.upstreamModelId}`;
+    const deploymentProductIds = new Set([
+      ...configuredModelInputIdentities(catalog.settings),
+      ...configuredGatewayWorkspaceProductModelIds(catalog.settings),
+    ]);
+    if (deploymentProductIds.has(customProductId)) {
+      throw new HTTPException(422, {
+        message: "Gateway model product id conflicts with the deployment catalog",
+      });
+    }
+    try {
+      const model = await createWorkspaceGatewayCustomModel(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        upstreamModelId: parsed.data.upstreamModelId,
+        label: parsed.data.label ?? null,
+        operationId: parsed.data.operationId,
+        requestHash,
+        createdBySubjectId: grant.subjectId,
+      });
+      if (!model || model.retiredAt) {
+        throw new HTTPException(409, {
+          message: "Gateway custom model operation conflicts with current state",
+        });
+      }
+      return c.json(projectWorkspaceGatewayCustomModel(model), 201);
+    } catch (error) {
+      if (
+        error instanceof WorkspaceGatewayCustomModelLimitError ||
+        error instanceof WorkspaceGatewayCustomModelHistoryLimitError
+      ) {
+        throw new HTTPException(422, { message: error.message });
+      }
+      if (nestedPostgresSqlState(error) === "23505") {
+        throw new HTTPException(422, {
+          message: "Gateway custom model already exists",
+        });
+      }
+      throw error;
+    }
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/gateway-custom-models/:customModelId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const customModelId = c.req.param("customModelId");
+    if (
+      !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(
+        customModelId,
+      )
+    ) {
+      throw new HTTPException(422, {
+        message: "invalid Gateway custom model id",
+      });
+    }
+    const parsed = DeleteWorkspaceGatewayCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, {
+        message: "invalid Gateway custom model deletion",
+      });
+    }
+    const removed = await deleteWorkspaceGatewayCustomModel(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      customModelId,
+      expectedVersion: parsed.data.expectedVersion,
+      operationId: parsed.data.operationId,
+      requestHash: workspaceCustomModelRequestHash({
+        action: "delete",
+        customModelId,
+        expectedVersion: parsed.data.expectedVersion,
+      }),
+    });
+    if (removed.outcome === "not_found") {
+      throw new HTTPException(404, {
+        message: "Gateway custom model not found",
+      });
+    }
+    if (removed.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "Gateway custom model changed; reload and retry",
+      });
+    }
+    return c.body(null, 204);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/openrouter-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const models = await listWorkspaceOpenRouterCustomModels(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
+    c.header("cache-control", "private, no-store");
+    return c.json(
+      WorkspaceOpenRouterCustomModelsResponse.parse({
+        models: models.map(projectWorkspaceOpenRouterCustomModel),
+      }),
+    );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/openrouter-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const parsed = CreateWorkspaceOpenRouterCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "invalid OpenRouter custom model" });
+    }
+    const requestHash = workspaceCustomModelRequestHash({
+      action: "create",
+      upstreamModelId: parsed.data.upstreamModelId,
+      label: parsed.data.label ?? null,
+    });
+    const replay = await replayWorkspaceOpenRouterCustomModelCreate(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      operationId: parsed.data.operationId,
+      requestHash,
+    });
+    if (replay.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "OpenRouter custom model operation conflicts with current state",
+      });
+    }
+    if (replay.outcome === "success") {
+      return c.json(projectWorkspaceOpenRouterCustomModel(replay.model), 201);
+    }
+    const catalog = await deps.resolveCatalogSettings();
+    if (
+      configuredOpenRouterUpstreamModelIds(catalog.settings).includes(parsed.data.upstreamModelId)
+    ) {
+      throw new HTTPException(422, {
+        message: "OpenRouter model is already included in the deployment catalog",
+      });
+    }
+    const customProductId = `${WORKSPACE_OPENROUTER_MODEL_ID_PREFIX}${parsed.data.upstreamModelId}`;
+    const deploymentProductIds = new Set([
+      ...configuredModelInputIdentities(catalog.settings),
+      ...configuredOpenRouterWorkspaceProductModelIds(catalog.settings),
+    ]);
+    if (deploymentProductIds.has(customProductId)) {
+      throw new HTTPException(422, {
+        message: "OpenRouter model product id conflicts with the deployment catalog",
+      });
+    }
+    try {
+      const model = await createWorkspaceOpenRouterCustomModel(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        upstreamModelId: parsed.data.upstreamModelId,
+        label: parsed.data.label ?? null,
+        operationId: parsed.data.operationId,
+        requestHash,
+        createdBySubjectId: grant.subjectId,
+      });
+      if (!model || model.retiredAt) {
+        throw new HTTPException(409, {
+          message: "OpenRouter custom model operation conflicts with current state",
+        });
+      }
+      return c.json(projectWorkspaceOpenRouterCustomModel(model), 201);
+    } catch (error) {
+      if (
+        error instanceof WorkspaceOpenRouterCustomModelLimitError ||
+        error instanceof WorkspaceOpenRouterCustomModelHistoryLimitError
+      ) {
+        throw new HTTPException(422, { message: error.message });
+      }
+      if (nestedPostgresSqlState(error) === "23505") {
+        throw new HTTPException(422, {
+          message: "OpenRouter custom model already exists",
+        });
+      }
+      throw error;
+    }
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/openrouter-custom-models/:customModelId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const customModelId = c.req.param("customModelId");
+    if (
+      !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(
+        customModelId,
+      )
+    ) {
+      throw new HTTPException(422, {
+        message: "invalid OpenRouter custom model id",
+      });
+    }
+    const parsed = DeleteWorkspaceOpenRouterCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, {
+        message: "invalid OpenRouter custom model deletion",
+      });
+    }
+    const removed = await deleteWorkspaceOpenRouterCustomModel(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      customModelId,
+      expectedVersion: parsed.data.expectedVersion,
+      operationId: parsed.data.operationId,
+      requestHash: workspaceCustomModelRequestHash({
+        action: "delete",
+        customModelId,
+        expectedVersion: parsed.data.expectedVersion,
+      }),
+    });
+    if (removed.outcome === "not_found") {
+      throw new HTTPException(404, {
+        message: "OpenRouter custom model not found",
+      });
+    }
+    if (removed.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "OpenRouter custom model changed; reload and retry",
+      });
+    }
+    return c.body(null, 204);
+  });
+
   app.get("/v1/workspaces/:workspaceId/realtime-model-catalog", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
@@ -320,11 +783,15 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     const payload = UpdateWorkspaceModelPolicyRequest.parse(await c.req.json());
+    const catalog = await resolveWorkspaceCatalogSettings(deps.db, deps.settings, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
     const policy = await upsertWorkspaceModelPolicy(deps.db, {
       accountId: grant.accountId,
       workspaceId,
       allowedProviders: payload.allowedProviders ?? null,
-      allowedModels: canonicalWorkspacePolicyModelIds(deps.settings, payload.allowedModels),
+      allowedModels: canonicalWorkspacePolicyModelIds(catalog.settings, payload.allowedModels),
     });
     return c.json(policy);
   });
@@ -333,11 +800,15 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     if (workspaceControlUtf8Bytes(grant.subjectId) > WORKSPACE_CONTROL_ACTOR_MAX_BYTES) {
-      throw new HTTPException(400, { message: "workspace-control actor is too large" });
+      throw new HTTPException(400, {
+        message: "workspace-control actor is too large",
+      });
     }
     const parsed = WorkspaceInferenceControlRequest.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid workspace inference-control request" });
+      throw new HTTPException(400, {
+        message: "invalid workspace inference-control request",
+      });
     }
     return c.json(
       await controlHumanWorkspace(
@@ -383,6 +854,7 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       after,
       c.req.raw.signal,
       {
+        ...browserSseDeliveryOptions(c.req.query("transport")),
         observability: deps.observability,
         actorEpoch: getManagedAuthRequestActorEpoch(c.req.raw) ?? undefined,
         reauthorize: async () => {
@@ -399,7 +871,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (payload.rigId) {
       const rig = await getRig(deps.db, workspaceId, payload.rigId);
       if (!rig) {
-        throw new HTTPException(422, { message: `unknown rigId: ${payload.rigId}` });
+        throw new HTTPException(422, {
+          message: `unknown rigId: ${payload.rigId}`,
+        });
       }
     }
     const workspace = await setWorkspaceDefaultRig(deps.db, workspaceId, payload.rigId);
@@ -413,15 +887,22 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     // session/lease before checking runtime quiescence, then returns the exact
     // external schedules removed by the cascade. A racing cold->warm transition
     // can therefore never erase the only provider/capture ownership receipt.
+    const deleteObserver = workspaceDeleteObserver(deps.observability, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
     const deleted = await deleteWorkspaceIfQuiescent(deps.db, {
       accountId: grant.accountId,
       workspaceId,
+      ...(deleteObserver ? { observer: deleteObserver } : {}),
     });
     if (deleted.status === "not_found") {
       throw new HTTPException(404, { message: "workspace not found" });
     }
     if (deleted.status === "only_workspace") {
-      throw new HTTPException(409, { message: "cannot delete the account's only workspace" });
+      throw new HTTPException(409, {
+        message: "cannot delete the account's only workspace",
+      });
     }
     if (deleted.status === "active_sessions") {
       throw new HTTPException(409, {
@@ -453,7 +934,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       {
         db: deps.db,
         deleteSchedule: async (temporalScheduleId) => {
-          await deps.workflowClient.deleteScheduledTaskSchedule({ temporalScheduleId });
+          await deps.workflowClient.deleteScheduledTaskSchedule({
+            temporalScheduleId,
+          });
         },
         ...(deps.observability ? { observability: deps.observability } : {}),
       },
@@ -467,28 +950,73 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/members", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "workspace:read");
-    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    const members = await listWorkspacePeople(deps, workspaceId);
     return c.json(workspaceMembersResponse(members));
   });
 
+  app.get("/v1/workspaces/:workspaceId/member-candidates", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
+    try {
+      return c.json(
+        ListWorkspaceMemberCandidatesResponse.parse({
+          members: await listWorkspaceMemberManagementCandidates(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+          }),
+        }),
+      );
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+  });
+
   app.post("/v1/workspaces/:workspaceId/members", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
     const payload = AddWorkspaceMemberRequest.parse(await c.req.json());
-    const email = payload.email.trim();
-    // Email invites for not-yet-registered users are deferred: an unknown email
-    // resolves to null, which resolveMemberSubjectId turns into a 404.
-    const subjectId = resolveMemberSubjectId(await getManagedUserByEmail(deps.db, email));
-    await grantWorkspaceAccess(deps.db, {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId,
-      subjectLabel: email,
-      ...(payload.role !== undefined ? { role: payload.role } : {}),
-      permissions: payload.permissions,
-    });
-    const members = await listWorkspaceMembers(deps.db, workspaceId);
-    const member = members.find((candidate) => candidate.subjectId === subjectId);
+    let candidates: WorkspaceMemberCandidate[];
+    try {
+      candidates = await listWorkspaceMemberManagementCandidates(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        actorSubjectId: grant.subjectId,
+      });
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+    const candidate = candidates.find(
+      (entry) => entry.organizationMembershipId === payload.organizationMembershipId,
+    );
+    if (!candidate) {
+      throw new HTTPException(404, {
+        message: "this organization member is not available to add",
+      });
+    }
+    const subjectId = candidate.subjectId;
+    const existing = await listWorkspaceMembers(deps.db, workspaceId);
+    if (existing.some((member) => member.subjectId === subjectId)) {
+      throw new HTTPException(409, {
+        message: "this person already has access to the workspace",
+      });
+    }
+    try {
+      await upsertWorkspaceMemberAsWorkspaceManager(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        actorSubjectId: grant.subjectId,
+        targetSubjectId: subjectId,
+        mode: "add",
+        subjectLabel: candidate.name?.trim() || candidate.email || subjectId,
+        role: payload.role ?? "member",
+        permissions: payload.permissions,
+      });
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+    const members = await listWorkspacePeople(deps, workspaceId);
+    const member = members.find((addedMember) => addedMember.subjectId === subjectId);
     if (!member) {
       throw new HTTPException(500, { message: "failed to add member" });
     }
@@ -500,20 +1028,32 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
     const subjectId = decodeURIComponent(c.req.param("subjectId"));
     const payload = UpdateWorkspaceMemberRequest.parse(await c.req.json());
-    const existing = await listWorkspaceMembers(deps.db, workspaceId);
+    const existing = await listWorkspacePeople(deps, workspaceId);
     const current = existing.find((member) => member.subjectId === subjectId);
     if (!current) {
       throw new HTTPException(404, { message: "member not found" });
     }
-    await grantWorkspaceAccess(deps.db, {
-      accountId: grant.accountId,
-      workspaceId,
+    assertWorkspaceMemberUpdateAllowed({
+      members: existing,
       subjectId,
-      ...(current.subjectLabel ? { subjectLabel: current.subjectLabel } : {}),
-      role: payload.role ?? current.role,
-      permissions: payload.permissions,
+      callerSubjectId: grant.subjectId,
+      nextPermissions: payload.permissions,
     });
-    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    try {
+      await upsertWorkspaceMemberAsWorkspaceManager(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        actorSubjectId: grant.subjectId,
+        targetSubjectId: subjectId,
+        mode: "update",
+        ...(current.subjectLabel ? { subjectLabel: current.subjectLabel } : {}),
+        role: payload.role ?? current.role,
+        permissions: payload.permissions,
+      });
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+    const members = await listWorkspacePeople(deps, workspaceId);
     const member = members.find((candidate) => candidate.subjectId === subjectId);
     if (!member) {
       throw new HTTPException(500, { message: "failed to update member" });
@@ -528,7 +1068,11 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const members = await listWorkspaceMembers(deps.db, workspaceId);
     // Never remove yourself, and never remove the last administering member.
     // The fenced removal command re-enforces both guards fail-closed.
-    assertWorkspaceMemberRemovable({ members, subjectId, callerSubjectId: grant.subjectId });
+    assertWorkspaceMemberRemovable({
+      members,
+      subjectId,
+      callerSubjectId: grant.subjectId,
+    });
     await removeWorkspaceMember(deps.db, {
       accountId: grant.accountId,
       workspaceId,
@@ -539,6 +1083,69 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 }
 
+function workspaceLimit(deps: ApiRouteDeps): number | null {
+  if (deps.settings.usageLimitsMode !== "static" && deps.settings.usageLimitsMode !== "managed") {
+    return null;
+  }
+  return configuredStaticUsageLimits(deps.settings).maxWorkspacesPerAccount ?? null;
+}
+
+async function listWorkspacePeople(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+): Promise<WorkspaceMemberValue[]> {
+  const members = await listWorkspaceMembers(deps.db, workspaceId);
+  const userIds = members.flatMap((member) =>
+    member.subjectId.startsWith("user:") ? [member.subjectId.slice("user:".length)] : [],
+  );
+  const profiles = await getManagedUserProfilesByIds(deps.db, userIds);
+  const profileBySubject = new Map(
+    profiles.map((profile) => [`user:${profile.id}`, profile.name?.trim() || profile.email]),
+  );
+  return members.map((member) => ({
+    ...member,
+    subjectLabel: profileBySubject.get(member.subjectId) ?? member.subjectLabel,
+  }));
+}
+
+function rethrowWorkspaceMemberCandidateError(error: unknown): never {
+  const managementCode =
+    error && typeof error === "object" && "code" in error ? error.code : undefined;
+  if (managementCode === "WORKSPACE_MEMBER_ALREADY_EXISTS") {
+    throw new HTTPException(409, {
+      message: "this person already has access to the workspace",
+    });
+  }
+  if (managementCode === "WORKSPACE_MEMBER_NOT_FOUND") {
+    throw new HTTPException(404, { message: "member not found" });
+  }
+  if (managementCode === "WORKSPACE_MEMBER_SELF_UPDATE") {
+    throw new HTTPException(409, {
+      message: "you cannot change your own workspace access",
+    });
+  }
+  if (managementCode === "WORKSPACE_MEMBER_LAST_ADMIN") {
+    throw new HTTPException(409, {
+      message: "the workspace must keep at least one administrator",
+    });
+  }
+  const sqlState = nestedPostgresSqlState(error);
+  if (sqlState === "P0002") {
+    throw new HTTPException(404, { message: "workspace not found" });
+  }
+  if (sqlState === "42501") {
+    throw new HTTPException(403, {
+      message: "workspace member management is not allowed",
+    });
+  }
+  if (sqlState === "54000") {
+    throw new HTTPException(409, {
+      message: "this organization has too many members to show here",
+    });
+  }
+  throw error;
+}
+
 // A persona override that is null or trims to empty collapses to null (use the
 // deployment default). Otherwise the template is stored verbatim so the runtime
 // can substitute the non-bypassable CORE at its {{core}} marker.
@@ -560,6 +1167,8 @@ function requireAccountPermission(
     !grant ||
     (!grant.permissions.includes(permission) && !grant.permissions.includes("account:admin"))
   ) {
-    throw new HTTPException(403, { message: `missing permission: ${permission}` });
+    throw new HTTPException(403, {
+      message: `missing permission: ${permission}`,
+    });
   }
 }