@opengeni/api-router 0.7.3 → 0.9.0

package/src/routes/files.ts

@@ -4,6 +4,13 @@ import {
   CreateFileUploadResponse,
   FileAsset,
   FileDownloadUrlResponse,
+  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
+  RetainedArtifactMetadataSchema,
+  retainedArtifactReferenceFromFile,
+  resolveRetainedOutputRange,
+  type RetainedArtifactMetadata,
+  type RetainedOutputUnavailableReason,
 } from "@opengeni/contracts";
 import {
   claimFileUploadCleanup,
@@ -11,7 +18,9 @@ import {
   completeFileUpload,
   createFileUpload,
   getFileUpload,
+  getRetainedFileArtifact,
   requireFile,
+  type RetainedFileArtifact,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -235,6 +244,90 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(FileAsset.parse(file));
   });
 
+  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const artifactId = retainedArtifactId(c.req.param("artifactId"));
+    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    if (!artifact) {
+      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
+    }
+    return c.json(retainedArtifactMetadata(artifact));
+  });
+
+  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId/content", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const artifactId = retainedArtifactId(c.req.param("artifactId"));
+    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    if (!artifact) {
+      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
+    }
+
+    const metadata = retainedArtifactMetadata(artifact);
+    if (!metadata.available) {
+      return c.json(metadata, retainedArtifactUnavailableStatus(metadata.reason));
+    }
+    if (!objectStorage) {
+      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 503);
+    }
+
+    const rangeHeader = c.req.header("range");
+    const range = resolveRetainedOutputRange(
+      rangeHeader,
+      metadata.originalBytes,
+      rangeHeader ? RETAINED_OUTPUT_MAX_PAGE_BYTES : RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+    );
+    if (range.kind === "invalid") {
+      return c.json(
+        {
+          message: "invalid retained artifact byte range",
+          reason: range.reason,
+          maxRangeBytes: RETAINED_OUTPUT_MAX_PAGE_BYTES,
+        },
+        400,
+      );
+    }
+    if (range.kind === "unsatisfiable") {
+      return c.json(
+        { message: "retained artifact byte range is not satisfiable", reason: range.reason },
+        416,
+        {
+          "Accept-Ranges": "bytes",
+          "Content-Range": range.contentRange,
+          "Cache-Control": "private, no-store",
+        },
+      );
+    }
+
+    const headers = {
+      "Accept-Ranges": range.acceptRanges,
+      "Cache-Control": "private, no-store",
+      "Content-Length": String(range.length),
+      "Content-Type": metadata.contentType,
+      "X-Content-Type-Options": "nosniff",
+      ...(range.contentRange ? { "Content-Range": range.contentRange } : {}),
+    };
+    if (range.kind === "empty") {
+      if (!(await objectStorage.fileExists(artifact.file))) {
+        return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
+      }
+      return c.body(null, 200, headers);
+    }
+
+    const bytes = await objectStorage.getFileRange(artifact.file, {
+      start: range.start,
+      end: range.end,
+    });
+    if (!bytes) {
+      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
+    }
+    if (bytes.byteLength !== range.length) {
+      throw new HTTPException(502, { message: "object storage returned an invalid byte range" });
+    }
+    return c.body(new Uint8Array(bytes), range.status, headers);
+  });
+
   app.post("/v1/workspaces/:workspaceId/files/:fileId/download-url", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "files:read");
@@ -271,3 +364,63 @@ function sanitizeFilename(filename: string): string {
 function publicFileUploadStatus(status: string): string {
   return status === "cleanup_pending" ? "failed" : status;
 }
+
+function retainedArtifactId(value: string): string {
+  const parsed = FileAsset.shape.id.safeParse(value);
+  if (!parsed.success) {
+    throw new HTTPException(404, { message: "artifact not found" });
+  }
+  return parsed.data;
+}
+
+function retainedArtifactUnavailable(
+  artifactId: string,
+  reason: RetainedOutputUnavailableReason,
+): RetainedArtifactMetadata {
+  return RetainedArtifactMetadataSchema.parse({ available: false, artifactId, reason });
+}
+
+function retainedArtifactMetadata(artifact: RetainedFileArtifact): RetainedArtifactMetadata {
+  const reference = retainedArtifactReferenceFromFile(artifact.file);
+  if (reference) return reference;
+
+  const { file, uploadStatus, uploadExpiresAt } = artifact;
+  if (file.status === "deleted") {
+    return retainedArtifactUnavailable(file.id, "deleted");
+  }
+  if (
+    file.status === "expired" ||
+    uploadStatus === "expired" ||
+    (uploadStatus === "pending" &&
+      uploadExpiresAt !== null &&
+      uploadExpiresAt.getTime() < Date.now())
+  ) {
+    return retainedArtifactUnavailable(file.id, "expired");
+  }
+  if (file.status === "failed" || uploadStatus === "failed" || uploadStatus === "cleanup_pending") {
+    return retainedArtifactUnavailable(file.id, "failed");
+  }
+  if (file.status === "pending_upload" || uploadStatus === "pending") {
+    return retainedArtifactUnavailable(file.id, "pending");
+  }
+  return retainedArtifactUnavailable(file.id, "unsupported");
+}
+
+function retainedArtifactUnavailableStatus(
+  reason: RetainedOutputUnavailableReason,
+): 404 | 409 | 410 | 422 {
+  switch (reason) {
+    case "deleted":
+      return 404;
+    case "expired":
+    case "missing_storage":
+      return 410;
+    case "unsupported":
+    case "not_retained":
+    case "storage_write_failed":
+      return 422;
+    case "pending":
+    case "failed":
+      return 409;
+  }
+}

package/src/routes/sessions.ts

@@ -27,19 +27,26 @@ import {
   SessionEventPayloadMode,
   SessionEventReadDirection,
   SessionEventReadMode,
+  SessionEventLatestClass,
+  SessionEventResultMode,
   SessionEventSemanticClass,
   SessionEventType,
+  SessionMcpServerId,
+  compactSessionEventResult,
+  sessionEventLatestClassToSemanticClass,
   SaveComposerDraftRequest,
   SteerSessionQueueItemRequest,
   SteerSessionMessageRequest,
   TerminalExecRequest,
   UpdateSessionPinRequest,
   UpdateSessionGoalRequest,
+  UpdateSessionMcpApprovalPolicyRequest,
   UpdateSessionRequest,
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
   workspaceControlUtf8Bytes,
   type SandboxBackend,
+  type LineageNode,
   type Session,
   type SessionAuthorizationOperation,
   type SessionQueueSnapshot,
@@ -136,8 +143,12 @@ import {
   readSessionLineage,
   saveHumanComposerDraft,
   steerHumanQueuePrompt,
+  updateSessionMcpApprovalPolicy,
   updateSessionTitle,
   workflowIdForSession,
+  sessionWithEffectiveToolPolicy,
+  workspaceSessionToolPolicyDefaultServerIds,
+  workspaceSessionToolPolicyServerIds,
 } from "@opengeni/core";
 import { assertSessionExists, boundedLimit } from "../http/common";
 import { sseSessionStream } from "../http/sse";
@@ -204,7 +215,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");
     const session = await createSessionForRequest(deps, grant, workspaceId, await c.req.json());
-    return c.json(session, 202);
+    return c.json(await withEffectivePolicy(deps, workspaceId, session), 202);
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions", async (c) => {
@@ -241,15 +252,26 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // body for older clients while still making its older-pin omission visible
     // to raw HTTP consumers without changing that response shape.
     c.header("x-opengeni-pinned-truncated", page.pinnedTruncated === true ? "true" : "false");
+    const policy = await loadEffectivePolicyContext(deps, workspaceId);
+    const decorate = (session: Session): Session =>
+      sessionWithEffectiveToolPolicy(
+        session,
+        policy.workspaceServerIds,
+        policy.workspaceDefaultServerIds,
+      );
     if (pageView) {
-      return c.json(page);
+      return c.json({
+        ...page,
+        pinned: page.pinned.map(decorate),
+        sessions: page.sessions.map(decorate),
+      });
     }
     // Same-major compatibility: listSessions() has historically returned an
     // array. Preserve that wire shape while adding personal pin metadata/order;
     // cursor consumers opt into the additive page view. A query flag rather
     // than a /sessions/page path is deliberate: an older API safely ignores it
     // and returns its historical array instead of treating "page" as a UUID.
-    return c.json([...page.pinned, ...page.sessions]);
+    return c.json([...page.pinned, ...page.sessions].map(decorate));
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
@@ -269,7 +291,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    return c.json(session);
+    return c.json(await withEffectivePolicy(deps, workspaceId, session));
   });
 
   // Personal pin only: this is organization state for the authenticated member,
@@ -296,7 +318,13 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       if (!session) {
         throw new HTTPException(404, { message: "session not found" });
       }
-      return c.json(projectSessionForRelatedAccess(session, relatedSessionAccessFor(c)));
+      return c.json(
+        await withEffectivePolicy(
+          deps,
+          workspaceId,
+          projectSessionForRelatedAccess(session, relatedSessionAccessFor(c)),
+        ),
+      );
     } catch (error) {
       if (error instanceof SessionPinAccessError) {
         throw new HTTPException(403, { message: error.message });
@@ -317,7 +345,19 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/lineage", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
-    return c.json(await readSessionLineage(deps, grant, c.req.param("sessionId")));
+    const lineage = await readSessionLineage(deps, grant, c.req.param("sessionId"));
+    const policy = await loadEffectivePolicyContext(deps, workspaceId);
+    return c.json({
+      ...lineage,
+      ancestors: lineage.ancestors.map((session) =>
+        sessionWithEffectiveToolPolicy(
+          session,
+          policy.workspaceServerIds,
+          policy.workspaceDefaultServerIds,
+        ),
+      ),
+      children: mapLineageNodes(lineage.children, policy),
+    });
   });
 
   // Pin (or unpin) the session's Codex account. body { target: "auto" | "<id>" }:
@@ -397,9 +437,35 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    return c.json(session);
+    return c.json(await withEffectivePolicy(deps, workspaceId, session));
   });
 
+  app.patch(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/mcp-servers/:serverId/approval-policy",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+      const sessionId = c.req.param("sessionId");
+      const parsedServerId = SessionMcpServerId.safeParse(c.req.param("serverId"));
+      const payload = UpdateSessionMcpApprovalPolicyRequest.safeParse(
+        await c.req.json().catch(() => null),
+      );
+      if (!parsedServerId.success || !payload.success) {
+        throw new HTTPException(400, { message: "invalid MCP approval-policy request" });
+      }
+      await assertSessionExists(db, workspaceId, sessionId);
+      return c.json(
+        await updateSessionMcpApprovalPolicy(
+          deps,
+          grant,
+          sessionId,
+          parsedServerId.data,
+          payload.data.requireApproval,
+        ),
+      );
+    },
+  );
+
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/goal", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
@@ -597,12 +663,27 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       "mode",
       explicitReplay ? "forensic" : "monitoring",
     );
-    const latestClass = eventEnumValue(
+    const latestRequested = eventEnumValue(
       c.req.query("latest"),
-      SessionEventSemanticClass,
+      SessionEventLatestClass,
       "latest",
       undefined,
     );
+    const latestClass =
+      latestRequested === undefined
+        ? undefined
+        : sessionEventLatestClassToSemanticClass(latestRequested);
+    const resultMode = eventEnumValue(
+      c.req.query("resultMode") ?? c.req.query("result"),
+      SessionEventResultMode,
+      "resultMode",
+      "events",
+    );
+    if (resultMode === "compact" && latestClass === undefined) {
+      throw new HTTPException(400, {
+        message: "resultMode=compact requires latest",
+      });
+    }
     if (
       latestClass &&
       ["includeTypes", "excludeTypes", "includeClasses", "excludeClasses"].some(
@@ -660,19 +741,39 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
           compact ? 5000 : mode === "monitoring" ? 250 : 2000,
           mode === "monitoring" ? 40 : 500,
         );
+    const dbPayloadMode = resultMode === "compact" ? ("full" as const) : payloadMode;
     const dbPage = await listSessionEventPage(db, workspaceId, sessionId, {
       after,
       ...(before !== undefined ? { before } : {}),
       limit,
       direction,
-      payloadMode,
+      payloadMode: dbPayloadMode,
       includeTypes,
       excludeTypes,
       includeClasses: latestClass ? [latestClass] : includeClasses,
       excludeClasses,
       ...(mode === "monitoring" ? { defaultExcludeTypes: SESSION_EVENT_RAW_DELTA_TYPES } : {}),
+      ...(latestClass ? { authoritativeLatest: true } : {}),
     });
     const events = dbPage.events;
+    if (resultMode === "compact") {
+      const event = events[0];
+      c.header("X-OpenGeni-Event-Result-Mode", "compact");
+      c.header("X-OpenGeni-Event-Result", event ? "found" : "not_found");
+      c.header("X-OpenGeni-Event-Mode", mode);
+      c.header("X-OpenGeni-Event-Direction", direction);
+      c.header("X-OpenGeni-Payload-Mode", "full");
+      c.header("X-OpenGeni-Forensic-Exact", "false");
+      if (!event) return c.json(null, 200);
+      const result = compactSessionEventResult(
+        event,
+        latestClass!,
+        dbPage.coveredSequence ?? { first: event.sequence, last: event.sequence },
+      );
+      c.header("X-OpenGeni-Covered-First", String(result.coveredSequence.first));
+      c.header("X-OpenGeni-Covered-Last", String(result.coveredSequence.last));
+      return c.json(result);
+    }
     const projected = compact ? coalesceSessionEventDeltas(events) : events;
     const page = boundSessionEventHttpPage(projected, {
       direction,
@@ -2022,6 +2123,9 @@ export function sessionAuthorizationOperationForHttp(
     return null;
   }
   if (suffix === "/pin" && verb === "PUT") return "session.pin.write";
+  if (/^\/mcp-servers\/[^/]+\/approval-policy$/.test(suffix) && verb === "PATCH") {
+    return "session.mcp.approval_policy.write";
+  }
   if (suffix === "/lineage" && verb === "GET") return "session.lineage.read";
   if (suffix === "/codex-account" && verb === "POST") {
     return "session.codex_account.write";
@@ -2238,3 +2342,44 @@ function commandConflictResponse(c: Context, error: unknown): Response {
   }
   throw error;
 }
+
+type EffectivePolicyContext = {
+  workspaceServerIds: string[];
+  workspaceDefaultServerIds: string[];
+};
+
+async function loadEffectivePolicyContext(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+): Promise<EffectivePolicyContext> {
+  const [workspaceServerIds, workspaceDefaultServerIds] = await Promise.all([
+    workspaceSessionToolPolicyServerIds(deps.db, workspaceId, deps.settings),
+    workspaceSessionToolPolicyDefaultServerIds(deps.db, workspaceId, deps.settings),
+  ]);
+  return { workspaceServerIds, workspaceDefaultServerIds };
+}
+
+async function withEffectivePolicy(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  session: Session,
+): Promise<Session> {
+  const policy = await loadEffectivePolicyContext(deps, workspaceId);
+  return sessionWithEffectiveToolPolicy(
+    session,
+    policy.workspaceServerIds,
+    policy.workspaceDefaultServerIds,
+  );
+}
+
+function mapLineageNodes(nodes: LineageNode[], policy: EffectivePolicyContext): LineageNode[] {
+  return nodes.map((node) => ({
+    ...node,
+    session: sessionWithEffectiveToolPolicy(
+      node.session as Session,
+      policy.workspaceServerIds,
+      policy.workspaceDefaultServerIds,
+    ),
+    children: mapLineageNodes(node.children, policy),
+  }));
+}

package/src/routes/workspaces.ts

@@ -8,6 +8,7 @@ import {
   UpdateWorkspaceRequest,
   UpdateWorkspaceSettingsRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
+  WorkspaceModelCatalogResponse,
   WorkspaceInferenceControlRequest,
   Workspace,
   WorkspaceMember,
@@ -35,6 +36,7 @@ import {
   updateWorkspace,
   updateWorkspaceSettings,
   upsertWorkspaceModelPolicy,
+  workspaceCodexSubscriptionActive,
 } from "@opengeni/db";
 import { boundWorkspaceControlHttpPage } from "@opengeni/events";
 import type { Hono } from "hono";
@@ -50,6 +52,18 @@ import {
 } from "@opengeni/core";
 import { boundedLimit } from "../http/common";
 import { sseWorkspaceControlStream } from "../http/sse";
+import { buildWorkspaceModelCatalog } from "../model-catalog";
+import { canonicalizeConfiguredModelId, type Settings } from "@opengeni/config";
+
+export function canonicalWorkspacePolicyModelIds(
+  settings: Settings,
+  modelIds: string[] | null | undefined,
+): string[] | null {
+  if (modelIds === null || modelIds === undefined) {
+    return null;
+  }
+  return [...new Set(modelIds.map((modelId) => canonicalizeConfiguredModelId(settings, modelId)))];
+}
 
 export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/access/me", async (c) => {
@@ -143,7 +157,27 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   // Per-workspace model/provider availability policy (the HARD blocker over
   // which providers/models may serve a turn at all). Absent row reads as
-  // unrestricted {null, null}.
+  // unrestricted {null, null}. No Azure AD credential resolver is wired here,
+  // so bearer/federated definitions intentionally fail closed as not ready.
+  app.get("/v1/workspaces/:workspaceId/model-catalog", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const [policy, codexSubscriptionActive] = await Promise.all([
+      getWorkspaceModelPolicy(deps.db, workspaceId),
+      workspaceCodexSubscriptionActive(deps.db, deps.settings, workspaceId),
+    ]);
+    c.header("cache-control", "private, no-store");
+    return c.json(
+      WorkspaceModelCatalogResponse.parse(
+        buildWorkspaceModelCatalog({
+          settings: deps.settings,
+          policy,
+          codexSubscriptionActive,
+        }),
+      ),
+    );
+  });
+
   app.get("/v1/workspaces/:workspaceId/model-policy", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "workspace:read");
@@ -166,7 +200,7 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       accountId: grant.accountId,
       workspaceId,
       allowedProviders: payload.allowedProviders ?? null,
-      allowedModels: payload.allowedModels ?? null,
+      allowedModels: canonicalWorkspacePolicyModelIds(deps.settings, payload.allowedModels),
     });
     return c.json(policy);
   });

package/src/sandbox/viewer.ts

@@ -648,7 +648,13 @@ export async function mintDesktopStream(
     // Idempotent display stack (flock-guarded; a no-op when already up). A box
     // that genuinely can't run the stack degrades to transport:null, not a throw.
     try {
-      await ensureDisplayStack(established.session);
+      await ensureDisplayStack(established.session, {
+        telemetryContext: {
+          callerKind: "viewer",
+          ...(lease.instanceId ? { sandboxId: lease.instanceId } : {}),
+          leaseEpoch: lease.leaseEpoch,
+        },
+      });
     } catch (error) {
       if (error instanceof DisplayStackUnsupportedError) {
         return null;