@opengeni/api-router 0.12.7 → 0.14.3

package/src/routes/preference-registry.ts

@@ -0,0 +1,482 @@
+import {
+  ActivatePreferenceRegistryRevisionRequest,
+  ChangePreferenceRegistryScopeRequest,
+  CorrectPreferenceRegistryRequest,
+  CreatePreferenceRegistryProposalRequest,
+  DeactivatePreferenceRegistryRequest,
+  PreferenceRegistryConflictResponse,
+  PreferenceRegistryDetailResponse,
+  PreferenceRegistryFullContentRequest,
+  PreferenceRegistryFullContent,
+  PreferenceRegistryListQuery,
+  PreferenceRegistryListResponse,
+  PreferenceRegistryMutationResponse,
+  PreferenceRegistryRecord,
+  PreferenceRegistrySnapshot,
+  RejectPreferenceRegistryProposalRequest,
+  SupersedePreferenceRegistryRequest,
+  type AccessGrant,
+  type PreferenceRegistryScope,
+} from "@opengeni/contracts";
+import {
+  hasPermission,
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  activatePreferenceRegistryRevision,
+  changePreferenceRegistryScope,
+  correctPreferenceRegistry,
+  createPreferenceRegistryProposal,
+  deactivatePreferenceRegistry,
+  getOrCreatePreferenceRegistrySnapshot,
+  getPreferenceRegistryDetail,
+  getPreferenceRegistryDetailForAttempt,
+  getPreferenceRegistryFullContent,
+  listPreferenceRegistry,
+  listPreferenceRegistryForAttempt,
+  PreferenceRegistryConflictError,
+  PreferenceRegistryInitiatorError,
+  PreferenceRegistryInvalidOperationError,
+  PreferenceRegistryNotFoundError,
+  PreferenceRegistryStableKeyConflictError,
+  rejectPreferenceRegistryProposal,
+  supersedePreferenceRegistry,
+  type PreferenceRegistryAttemptClaims,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const Id = z.string().uuid();
+
+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 preference registry request" });
+  return parsed.data;
+}
+
+function exactAttemptClaims(grant: AccessGrant) {
+  const metadata = grant.metadata ?? {};
+  const values = {
+    sessionId: metadata["sessionId"],
+    turnId: metadata["turnId"],
+    attemptId: metadata["attemptId"],
+    executionGeneration: metadata["executionGeneration"],
+  };
+  const present = Object.values(values).filter((value) => value !== undefined).length;
+  if (present === 0) return null;
+  if (
+    typeof values.sessionId !== "string" ||
+    typeof values.turnId !== "string" ||
+    typeof values.attemptId !== "string" ||
+    typeof values.executionGeneration !== "number" ||
+    !Number.isSafeInteger(values.executionGeneration) ||
+    values.executionGeneration < 1 ||
+    values.executionGeneration > 2_147_483_647
+  ) {
+    throw new HTTPException(403, { message: "Incomplete signed preference attempt authority" });
+  }
+  return values as {
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+  };
+}
+
+function requiredAttemptClaims(grant: AccessGrant): PreferenceRegistryAttemptClaims {
+  const claims = exactAttemptClaims(grant);
+  if (!claims) {
+    throw new HTTPException(403, {
+      message: "Preference snapshot retrieval requires a signed session, turn, and attempt",
+    });
+  }
+  return {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    ...claims,
+  };
+}
+
+function requireHumanMutation(access: AccessGrantAuthorization): void {
+  const { grant } = access;
+  if (
+    !access.contextIntegrity ||
+    access.authenticatedSubjectId !== grant.subjectId ||
+    grant.principalKind !== "human_session" ||
+    exactAttemptClaims(grant) !== null ||
+    grant.serviceInitiator ||
+    grant.serviceInitiatorContext ||
+    grant.subjectId.startsWith("api_key:")
+  ) {
+    throw new HTTPException(403, {
+      message: "Preference activation and scope mutation require a direct human-authorized request",
+    });
+  }
+}
+
+export function authorizePreferenceRegistryScopeMutation(
+  access: AccessGrantAuthorization,
+  scope: PreferenceRegistryScope,
+): void {
+  const { grant } = access;
+  requireHumanMutation(access);
+  if (scope === "organization") {
+    // Deliberately do not use hasPermission: workspace:admin must not expand to
+    // account:admin for an organization-wide preference. Account authority is
+    // carried separately from the authenticated context and must match this
+    // exact workspace grant's account and subject.
+    if (!access.accountGrant?.permissions.includes("account:admin")) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    return;
+  }
+  if (scope === "workspace" && !hasPermission(grant.permissions, "workspace:admin")) {
+    throw new HTTPException(403, { message: "missing permission: workspace:admin" });
+  }
+  // User scope is always self-only: the route derives the target from the
+  // authenticated actor and never accepts a subject selector.
+}
+
+function preferenceError(context: Context, error: unknown): Response {
+  if (error instanceof PreferenceRegistryConflictError) {
+    return context.json(
+      PreferenceRegistryConflictResponse.parse({
+        code: error.code,
+        message: error.message,
+        currentRevisionId: error.currentRevisionId,
+        scopeVersion: error.scopeVersion,
+      }),
+      409,
+    );
+  }
+  if (error instanceof PreferenceRegistryNotFoundError) {
+    return context.json({ code: "PREFERENCE_REGISTRY_NOT_FOUND", message: error.message }, 404);
+  }
+  if (error instanceof PreferenceRegistryStableKeyConflictError) {
+    return context.json({ code: error.code, message: error.message }, 409);
+  }
+  if (error instanceof PreferenceRegistryInvalidOperationError) {
+    return context.json(
+      { code: "INVALID_PREFERENCE_REGISTRY_OPERATION", message: error.message },
+      422,
+    );
+  }
+  if (error instanceof PreferenceRegistryInitiatorError) {
+    return context.json(
+      { code: "PREFERENCE_REGISTRY_ATTEMPT_REJECTED", message: error.message },
+      403,
+    );
+  }
+  throw error;
+}
+
+function preferenceId(context: Context): string {
+  const parsed = Id.safeParse(context.req.param("preferenceId"));
+  if (!parsed.success) throw new HTTPException(422, { message: "Invalid preference id" });
+  return parsed.data;
+}
+
+export function registerPreferenceRegistryRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/preferences";
+
+  app.get(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const query = PreferenceRegistryListQuery.safeParse({
+      scope: context.req.query("scope"),
+      status: context.req.query("status"),
+      limit: context.req.query("limit"),
+    });
+    if (!query.success)
+      throw new HTTPException(422, { message: "Invalid preference registry query" });
+    try {
+      const claims = exactAttemptClaims(grant);
+      const result = claims
+        ? await listPreferenceRegistryForAttempt(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            ...claims,
+            ...query.data,
+          })
+        : await listPreferenceRegistry(deps.db, {
+            workspaceId,
+            subjectId: grant.subjectId,
+            ...query.data,
+          });
+      return context.json(PreferenceRegistryListResponse.parse(result));
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/proposals`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const request = await parseBody(context, CreatePreferenceRegistryProposalRequest);
+    authorizePreferenceRegistryScopeMutation(access, request.scope);
+    try {
+      return context.json(
+        PreferenceRegistryRecord.parse(
+          await createPreferenceRegistryProposal(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+          }),
+        ),
+        201,
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.get(`${base}/summary`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    try {
+      return context.json(
+        PreferenceRegistrySnapshot.parse(
+          await getOrCreatePreferenceRegistrySnapshot(deps.db, requiredAttemptClaims(grant)),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/full-content`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const request = await parseBody(context, PreferenceRegistryFullContentRequest);
+    try {
+      return context.json(
+        PreferenceRegistryFullContent.parse(
+          await getPreferenceRegistryFullContent(
+            deps.db,
+            requiredAttemptClaims(grant),
+            request.retrievalHandle,
+          ),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.get(`${base}/:preferenceId`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    try {
+      const claims = exactAttemptClaims(grant);
+      const id = preferenceId(context);
+      const detail = claims
+        ? await getPreferenceRegistryDetailForAttempt(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            ...claims,
+            preferenceId: id,
+          })
+        : await getPreferenceRegistryDetail(deps.db, {
+            workspaceId,
+            subjectId: grant.subjectId,
+            preferenceId: id,
+          });
+      return context.json(PreferenceRegistryDetailResponse.parse(detail));
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/activate`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, ActivatePreferenceRegistryRevisionRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await activatePreferenceRegistryRevision(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+            ...request,
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/correct`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, CorrectPreferenceRegistryRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await correctPreferenceRegistry(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/scope`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, ChangePreferenceRegistryScopeRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await changePreferenceRegistryScope(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/deactivate`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, DeactivatePreferenceRegistryRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await deactivatePreferenceRegistry(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/supersede`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, SupersedePreferenceRegistryRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await supersedePreferenceRegistry(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/reject`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, RejectPreferenceRegistryProposalRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await rejectPreferenceRegistryProposal(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+}

package/src/routes/sessions.ts

@@ -76,6 +76,7 @@ import {
   listSessionHumanInputRequests,
   listSessionIdsInGroup,
   listSessionsForSubject,
+  getLatestStartedSessionTurn,
   listSessionTurns,
   projectEffectiveControlForRelatedAccess,
   projectSessionForRelatedAccess,
@@ -102,6 +103,7 @@ import {
   SessionContextBusyError,
   HumanInputResponseValidationError,
   latestWorkspaceCapture,
+  sessionLatestWorkspaceCapture,
   workspaceCaptureAtRevision,
   type AppendEventInput,
   type SandboxOpenPtySessionRow,
@@ -167,12 +169,17 @@ import {
 } from "@opengeni/core";
 import { assertSessionExists, boundedLimit } from "../http/common";
 import { sseSessionStream } from "../http/sse";
-import { serveWorkspaceCapture, serveWorkspaceCaptureFile } from "./workspace-capture";
+import {
+  serveWorkspaceCapture,
+  serveWorkspaceCaptureFile,
+  WorkspaceCaptureManifestCache,
+} from "./workspace-capture";
 
 type SessionRouteDeps = ApiRouteDeps & Pick<ViewerServices, "establishSandboxSession">;
 
 export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
+  const workspaceCaptureManifestCache = new WorkspaceCaptureManifestCache();
   const ptyIdentity = (pty: SandboxOpenPtySessionRow): SandboxPtyProcessIdentity => ({
     leaseId: pty.leaseId,
     sandboxGroupId: pty.sandboxGroupId,
@@ -1071,6 +1078,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
+    // Exact turn that most recently emitted durable `turn.started` — the same
+    // boundary goal continuations use for inherited model/effort. Queued-only
+    // or preflight-rejected turns are deliberately excluded.
+    if (c.req.query("latestStarted") === "1" || c.req.query("latestStarted") === "true") {
+      const latest = await getLatestStartedSessionTurn(db, workspaceId, sessionId);
+      return c.json(latest ? [latest] : []);
+    }
     return c.json(
       await listSessionTurns(db, workspaceId, sessionId, boundedLimit(c.req.query("limit"))),
     );
@@ -1276,10 +1290,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       text: payload.text,
       turnInstructions: payload.turnInstructions ?? null,
       resources: payload.resources,
-      tools: payload.tools,
-      toolsProvided: userMessagePayloadHasOwnProperty({ payload: raw }, "tools"),
       model: payload.model ?? null,
       reasoningEffort: payload.reasoningEffort ?? null,
+      latencyMode: payload.latencyMode ?? null,
       mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
       delivery: "steer",
       origin: "human",
@@ -1320,10 +1333,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         text: event.payload.text,
         turnInstructions: event.payload.turnInstructions ?? null,
         resources: event.payload.resources ?? [],
-        tools: event.payload.tools ?? [],
-        toolsProvided: userMessagePayloadHasOwnProperty(rawEvent, "tools"),
         model: event.payload.model ?? null,
         reasoningEffort: event.payload.reasoningEffort ?? null,
+        latencyMode: event.payload.latencyMode ?? null,
         mcpCredentialUpdates: event.payload.mcpCredentialUpdates ?? [],
         ...(event.payload.controlEtag !== undefined
           ? { controlEtag: event.payload.controlEtag }
@@ -2120,16 +2132,17 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     const workspaceId = c.req.param("workspaceId") ?? "";
     await requireAccessGrant(c, deps, workspaceId, "files:read");
     const sessionId = c.req.param("sessionId") ?? "";
-    const session = await getSession(db, workspaceId, sessionId);
-    if (!session) {
+    const lookup = await sessionLatestWorkspaceCapture(db, workspaceId, sessionId);
+    if (!lookup.sessionExists) {
       throw new HTTPException(404, { message: "session not found" });
     }
     if (!objectStorage) {
       // No storage configured → no captures can exist. Cold-fallback, not an error.
       return c.json({ available: false });
     }
-    const row = await latestWorkspaceCapture(db, workspaceId, sessionId);
-    return c.json(await serveWorkspaceCapture(row, objectStorage));
+    return c.json(
+      await serveWorkspaceCapture(lookup.capture, objectStorage, workspaceCaptureManifestCache),
+    );
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/workspace/capture/file", async (c) => {
@@ -2650,20 +2663,6 @@ function optionalEventSequence(raw: string | undefined): number | undefined {
   return Math.floor(sequence);
 }
 
-function hasOwnProperty(value: unknown, key: string): boolean {
-  return Boolean(
-    value && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, key),
-  );
-}
-
-function userMessagePayloadHasOwnProperty(value: unknown, key: string): boolean {
-  if (!value || typeof value !== "object") {
-    return false;
-  }
-  const payload = (value as { payload?: unknown }).payload;
-  return hasOwnProperty(payload, key);
-}
-
 /** Stable, value-free JSON errors for only the create-session boundary. */
 export function sessionCreateErrorResponse(c: Context, error: unknown): Response {
   if (error instanceof SessionSpawnDeniedError) {