@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/workspace-learning.ts

@@ -0,0 +1,159 @@
+import { randomUUID } from "node:crypto";
+import {
+  UndoGovernedLearningActivationHttpRequest,
+  WorkspaceLearningHistoryResponse,
+  WorkspaceLearningPolicyHistoryQuery,
+} from "@opengeni/contracts";
+import {
+  publishGovernedLearningEventToSlack,
+  requireAccessGrant,
+  requireWorkspaceSettingsGrant,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  GovernedLearningActivationAuthorityError,
+  GovernedLearningActivationConflictError,
+  GovernedLearningActivationInvalidOperationError,
+  GovernedLearningEvaluationAuthorityError,
+  listGovernedLearningActivationHistory,
+  listGovernedLearningDecisionReceipts,
+  listWorkspaceLearningPolicyHistory,
+  undoGovernedLearningActivation,
+  WorkspaceLearningPolicyAuthorityError,
+  WorkspaceLearningPolicyConflictError,
+  WorkspaceLearningPolicyInvalidOperationError,
+  WorkspaceLearningPolicyNotFoundError,
+  WorkspaceLearningPolicyOperationReuseError,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+async function parseBody<S extends z.ZodType>(context: Context, schema: S): Promise<z.infer<S>> {
+  const parsed = schema.safeParse(await context.req.json().catch(() => null));
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "Invalid workspace learning request" });
+  }
+  return parsed.data;
+}
+
+function learningError(error: unknown): never {
+  if (
+    error instanceof WorkspaceLearningPolicyAuthorityError ||
+    error instanceof GovernedLearningEvaluationAuthorityError ||
+    error instanceof GovernedLearningActivationAuthorityError
+  ) {
+    throw new HTTPException(403, { message: error.message });
+  }
+  if (error instanceof WorkspaceLearningPolicyNotFoundError) {
+    throw new HTTPException(404, { message: error.message });
+  }
+  if (
+    error instanceof WorkspaceLearningPolicyConflictError ||
+    error instanceof WorkspaceLearningPolicyOperationReuseError ||
+    error instanceof GovernedLearningActivationConflictError
+  ) {
+    throw new HTTPException(409, { message: error.message });
+  }
+  if (
+    error instanceof WorkspaceLearningPolicyInvalidOperationError ||
+    error instanceof GovernedLearningActivationInvalidOperationError
+  ) {
+    throw new HTTPException(422, { message: error.message });
+  }
+  throw error;
+}
+
+export function registerWorkspaceLearningRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/learning";
+
+  app.get(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const query = WorkspaceLearningPolicyHistoryQuery.safeParse({
+      limit: context.req.query("limit"),
+    });
+    if (!query.success) {
+      throw new HTTPException(422, { message: "Invalid workspace learning history query" });
+    }
+    try {
+      const [policy, decisions, lifecycle] = await Promise.all([
+        listWorkspaceLearningPolicyHistory(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          limit: query.data.limit,
+        }),
+        listGovernedLearningDecisionReceipts(deps.db, {
+          workspaceId,
+          subjectId: grant.subjectId,
+          principalKind: grant.principalKind ?? "",
+          limit: query.data.limit,
+        }),
+        listGovernedLearningActivationHistory(deps.db, {
+          workspaceId,
+          subjectId: grant.subjectId,
+          principalKind: grant.principalKind ?? "",
+          limit: query.data.limit,
+        }),
+      ]);
+      return context.json(
+        WorkspaceLearningHistoryResponse.parse({
+          head: policy.head,
+          revisions: policy.revisions,
+          policyEvents: policy.events,
+          decisions: decisions.receipts,
+          activations: lifecycle.activations,
+          undos: lifecycle.undos,
+          truncated: policy.truncated || decisions.truncated || lifecycle.truncated,
+          effectiveBoundary: "next_accepted_attempt",
+        }),
+      );
+    } catch (error) {
+      learningError(error);
+    }
+  });
+
+  for (const path of ["/revisions", "/revisions/:revisionId/activate", "/rollback"]) {
+    app.post(`${base}${path}`, async (context) => {
+      await requireWorkspaceSettingsGrant(context, deps, context.req.param("workspaceId")!);
+      return context.json(
+        {
+          error: {
+            code: "learning_settings_replaced",
+            message: "Configure Knowledge, instructions and Skills in Agent learning settings.",
+          },
+        },
+        410,
+      );
+    });
+  }
+
+  app.post(`${base}/activations/:activationReceiptId/undo`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const activationReceiptId = z
+      .string()
+      .uuid()
+      .safeParse(context.req.param("activationReceiptId"));
+    if (!activationReceiptId.success) {
+      throw new HTTPException(422, { message: "Invalid activation receipt id" });
+    }
+    const grant = await requireWorkspaceSettingsGrant(context, deps, workspaceId);
+    const request = await parseBody(context, UndoGovernedLearningActivationHttpRequest);
+    try {
+      const undo = await undoGovernedLearningActivation(deps.db, {
+        caller: { workspaceId, subjectId: grant.subjectId },
+        request: {
+          operationId: request.operationId ?? randomUUID(),
+          activationReceiptId: activationReceiptId.data,
+        },
+      });
+      // Best-effort notification; the undo receipt is already durable.
+      await publishGovernedLearningEventToSlack(deps.db, { kind: "undone", receipt: undo }).catch(
+        () => undefined,
+      );
+      return context.json(undo);
+    } catch (error) {
+      learningError(error);
+    }
+  });
+}

package/src/routes/workspace-model-providers.ts

@@ -0,0 +1,148 @@
+import { claudeProviderId } from "@opengeni/config";
+import { requireSameOriginBrowserMutation } from "./codex";
+import { createHash } from "node:crypto";
+import {
+  CreateWorkspaceGatewayCustomModelRequest,
+  DeleteWorkspaceGatewayCustomModelRequest,
+  WorkspaceGatewayCustomModel,
+  WorkspaceGatewayCustomModelsResponse,
+} from "@opengeni/contracts";
+import {
+  requireAccessGrant,
+  requireWorkspaceSettingsGrant,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  createWorkspaceProviderCustomModel,
+  deleteWorkspaceProviderCustomModel,
+  listWorkspaceProviderCustomModels,
+  replayWorkspaceProviderCustomModelCreate,
+  nestedPostgresSqlState,
+  WorkspaceClaudeCustomModelLimitError,
+  type WorkspaceProviderCustomModel,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const Kind = z.enum(["anthropic", "claude_subscription"]);
+function requestHash(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function modelJson(model: WorkspaceProviderCustomModel) {
+  return WorkspaceGatewayCustomModel.parse({
+    ...model,
+    createdAt: model.createdAt.toISOString(),
+    updatedAt: model.updatedAt.toISOString(),
+  });
+}
+
+/** Workspace-owned Claude models use the same immutable-generation protocol as gateway models. */
+export function registerWorkspaceModelProviderRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const path = "/v1/workspaces/:workspaceId/model-providers/:providerKind/custom-models";
+  async function scope(c: Context, mutate: boolean) {
+    const parsedKind = Kind.safeParse(c.req.param("providerKind"));
+    if (!parsedKind.success) throw new HTTPException(404, { message: "Model provider not found" });
+    const providerKind = parsedKind.data;
+    if (providerKind === "claude_subscription" && !deps.settings.claudeSubscriptionEnabled)
+      throw new HTTPException(404, { message: "Claude subscriptions are not enabled" });
+    const workspaceId = c.req.param("workspaceId")!;
+    const grant = mutate
+      ? await requireWorkspaceSettingsGrant(c, deps, workspaceId)
+      : await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    c.header("cache-control", "private, no-store");
+    return { accountId: grant.accountId, workspaceId, providerKind, subjectId: grant.subjectId };
+  }
+  app.get(path, async (c) => {
+    const input = await scope(c, false);
+    const models = await listWorkspaceProviderCustomModels(deps.db, input);
+    return c.json(WorkspaceGatewayCustomModelsResponse.parse({ models: models.map(modelJson) }));
+  });
+  const usagePath = "/v1/workspaces/:workspaceId/model-providers/:providerKind/usage";
+  app.get(usagePath, async (c) => {
+    const input = await scope(c, false);
+    if (input.providerKind !== "claude_subscription")
+      throw new HTTPException(404, { message: "Usage not available for this provider" });
+    throw new HTTPException(410, { message: "Check usage on the individual Claude account." });
+  });
+  app.post(`${usagePath}/refresh`, async (c) => {
+    requireSameOriginBrowserMutation(c, deps);
+    const input = await scope(c, false);
+    if (input.providerKind !== "claude_subscription")
+      throw new HTTPException(404, { message: "Usage not available for this provider" });
+    await requireAccessGrant(c, deps, input.workspaceId, "connections:write");
+    throw new HTTPException(410, { message: "Check usage on the individual Claude account." });
+  });
+  app.post(path, async (c) => {
+    const input = await scope(c, true);
+    const parsed = CreateWorkspaceGatewayCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) throw new HTTPException(422, { message: "Invalid custom model" });
+    const payload = parsed.data;
+    if (
+      `${claudeProviderId(input.providerKind, "workspace")}/${payload.upstreamModelId}`.length > 256
+    )
+      throw new HTTPException(422, { message: "Claude model ID is too long" });
+    const hash = requestHash({
+      action: "create",
+      upstreamModelId: payload.upstreamModelId,
+      label: payload.label ?? null,
+    });
+    const replay = await replayWorkspaceProviderCustomModelCreate(deps.db, {
+      ...input,
+      operationId: payload.operationId,
+      requestHash: hash,
+    });
+    if (replay.outcome === "conflict")
+      throw new HTTPException(409, {
+        message: "Custom model operation conflicts with current state",
+      });
+    if (replay.outcome === "success") return c.json(modelJson(replay.model), 201);
+    try {
+      const model = await createWorkspaceProviderCustomModel(deps.db, {
+        ...input,
+        ...payload,
+        label: payload.label ?? null,
+        requestHash: hash,
+        createdBySubjectId: input.subjectId,
+      });
+      if (!model || model.retiredAt)
+        throw new HTTPException(409, {
+          message: "Custom model operation conflicts with current state",
+        });
+      return c.json(modelJson(model), 201);
+    } catch (error) {
+      if (error instanceof WorkspaceClaudeCustomModelLimitError)
+        throw new HTTPException(422, { message: error.message });
+      if (nestedPostgresSqlState(error) === "23505")
+        throw new HTTPException(422, { message: "Custom model already exists" });
+      throw error;
+    }
+  });
+  app.delete(`${path}/:customModelId`, async (c) => {
+    const input = await scope(c, true);
+    const id = z.string().uuid().safeParse(c.req.param("customModelId"));
+    const parsed = DeleteWorkspaceGatewayCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!id.success || !parsed.success)
+      throw new HTTPException(422, { message: "Invalid custom model deletion" });
+    const customModelId = id.data;
+    const removed = await deleteWorkspaceProviderCustomModel(deps.db, {
+      ...input,
+      ...parsed.data,
+      customModelId,
+      requestHash: requestHash({
+        action: "delete",
+        customModelId,
+        expectedVersion: parsed.data.expectedVersion,
+      }),
+    });
+    if (removed.outcome === "not_found")
+      throw new HTTPException(404, { message: "Custom model not found" });
+    if (removed.outcome === "conflict")
+      throw new HTTPException(409, { message: "Custom model changed; reload and retry" });
+    return c.body(null, 204);
+  });
+}

package/src/routes/workspace-state.ts

@@ -1,32 +1,37 @@
+import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
 import {
-  WORKSPACE_STATE_MAX_BASES,
-  WORKSPACE_STATE_MAX_TOPICS,
-  WORKSPACE_STATE_TOPIC_MAX_CHARS,
+  WORKSPACE_STATE_KNOWLEDGE_SAMPLE_LIMIT,
   WorkspaceStateQuery,
   WorkspaceStateResponse,
-  type AccessGrant,
   type WorkspaceStateQuery as WorkspaceStateQueryType,
 } from "@opengeni/contracts";
-import { hasPermission, requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  hasPermission,
+  requireAccessGrantAuthorization,
+  knowledgeContextForAccess,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
 import {
   getWorkspace,
   getCurrentPreferenceRegistryGovernanceMetadata,
   getWorkspaceStateAcceptedAttemptGovernance,
-  listWorkspaceStateMemoryRecords,
+  listKnowledgeEntries,
   listWorkspaceInstructionPolicyRevisions,
 } from "@opengeni/db";
-import { getDocumentInventory } from "@opengeni/documents";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 
 import { serializeWorkspaceStateExport } from "../workspace-state-export";
 import { projectWorkspaceState } from "../workspace-state-projection";
+import { USER_CONTENT_SECURITY_HEADERS } from "../http/user-content";
 
 async function readWorkspaceState(
   deps: ApiRouteDeps,
-  input: { workspaceId: string; query: WorkspaceStateQueryType; grant: AccessGrant },
+  input: { workspaceId: string; query: WorkspaceStateQueryType; access: AccessGrantAuthorization },
 ) {
-  const { workspaceId, query, grant } = input;
+  const { workspaceId, query, access } = input;
+  const { grant } = access;
   const generatedAt = new Date().toISOString();
   const canInspectKnowledge = hasPermission(grant.permissions, "documents:search");
 
@@ -34,18 +39,13 @@ async function readWorkspaceState(
     getWorkspace(deps.db, workspaceId),
     listWorkspaceInstructionPolicyRevisions(deps.db, workspaceId, { limit: 1 }),
     canInspectKnowledge
-      ? (async () => {
-          const [documents, memories] = await Promise.all([
-            getDocumentInventory(deps.db, workspaceId, {
-              baseLimit: WORKSPACE_STATE_MAX_BASES,
-              topicLimit: WORKSPACE_STATE_MAX_TOPICS,
-              topicMaxChars: WORKSPACE_STATE_TOPIC_MAX_CHARS,
-              access: { viewerSubjectId: grant.subjectId },
-            }),
-            listWorkspaceStateMemoryRecords(deps.db, workspaceId),
-          ]);
-          return { documents, memories };
-        })()
+      ? withAccessGrantSessionRlsContext(deps, grant, async () =>
+          listKnowledgeEntries(
+            deps.db,
+            await knowledgeContextForAccess(deps, access, "documents:search"),
+            { limit: WORKSPACE_STATE_KNOWLEDGE_SAMPLE_LIMIT, view: "published" },
+          ),
+        )
       : Promise.resolve(null),
     getCurrentPreferenceRegistryGovernanceMetadata(deps.db, {
       workspaceId,
@@ -109,8 +109,13 @@ export function registerWorkspaceStateRoutes(app: Hono, deps: ApiRouteDeps): voi
   app.get(base, async (context) => {
     const workspaceId = context.req.param("workspaceId");
     const query = WorkspaceStateQuery.parse(context.req.query());
-    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
-    const state = await readWorkspaceState(deps, { workspaceId, query, grant });
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const state = await readWorkspaceState(deps, { workspaceId, query, access });
     context.header("cache-control", "private, no-store");
     return context.json(state);
   });
@@ -118,14 +123,22 @@ export function registerWorkspaceStateRoutes(app: Hono, deps: ApiRouteDeps): voi
   app.get(`${base}/export`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
     const query = WorkspaceStateQuery.parse(context.req.query());
-    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
-    const state = await readWorkspaceState(deps, { workspaceId, query, grant });
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const state = await readWorkspaceState(deps, { workspaceId, query, access });
     context.header("cache-control", "private, no-store");
     context.header("content-type", "application/json; charset=utf-8");
     context.header(
       "content-disposition",
       `attachment; filename="workspace-state-${workspaceId}-sanitized.json"`,
     );
+    for (const [name, value] of Object.entries(USER_CONTENT_SECURITY_HEADERS)) {
+      context.header(name, value);
+    }
     return context.body(serializeWorkspaceStateExport(state));
   });
 }