@opengeni/api-router 0.12.12 → 0.14.3

package/src/routes/workspace-state.ts

@@ -0,0 +1,61 @@
+import {
+  WORKSPACE_STATE_MAX_BASES,
+  WORKSPACE_STATE_MAX_TOPICS,
+  WORKSPACE_STATE_TOPIC_MAX_CHARS,
+  WorkspaceStateResponse,
+} from "@opengeni/contracts";
+import { hasPermission, requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  getWorkspace,
+  listWorkspaceStateMemoryRecords,
+  listWorkspaceInstructionPolicyRevisions,
+} from "@opengeni/db";
+import { getDocumentInventory } from "@opengeni/documents";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+import { projectWorkspaceState } from "../workspace-state-projection";
+
+export function registerWorkspaceStateRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get("/v1/workspaces/:workspaceId/workspace-state", async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const generatedAt = new Date().toISOString();
+    const canInspectKnowledge = hasPermission(grant.permissions, "documents:search");
+
+    const [workspace, policies, knowledge] = await Promise.all([
+      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 };
+          })()
+        : Promise.resolve(null),
+    ]);
+
+    if (!workspace) {
+      throw new HTTPException(404, { message: "workspace not found" });
+    }
+    context.header("cache-control", "private, no-store");
+    return context.json(
+      WorkspaceStateResponse.parse(
+        projectWorkspaceState({
+          workspaceId,
+          generatedAt,
+          workspaceAgentInstructions: workspace.agentInstructions,
+          policies,
+          knowledge,
+        }),
+      ),
+    );
+  });
+}

package/src/sandbox/channel-a.ts

@@ -21,6 +21,7 @@ import {
   applyGitAuthPointerEnvironment,
   hasGitCredentialRepositorySelection,
   hasGitHubRepositorySelection,
+  sandboxArchiveCaptureTimeoutMs,
   stableSandboxEnvironmentForRun,
   type Settings,
 } from "@opengeni/config";
@@ -247,6 +248,7 @@ export async function withChannelA<T>(
     os: session.sandboxOs,
     leaseTtlMs,
     warmingLeaseTtlMs: settings.sandboxWarmingTimeoutMs,
+    captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
   });
 
   if (acquired.role === "blocked") {

package/src/sandbox/rematerialize.ts

@@ -1,5 +1,6 @@
 import type { Settings } from "@opengeni/config";
 import {
+  adoptLegacyModalCheckpointArtifact,
   beginSandboxRematerialization,
   commitWarmingToWarm,
   failSandboxRematerialization,
@@ -12,9 +13,13 @@ import {
   type LeaseSnapshot,
 } from "@opengeni/db";
 import {
+  describeLegacyNativeSnapshotArchive,
   establishSandboxSessionFromEnvelope,
   isProviderSandboxNotFoundError,
+  modalSessionMatchesCheckpointProviderBinding,
+  parseWorkspaceArchiveDescriptor,
   requirePersistableReplacementSandboxEnvelope,
+  resolveModalCheckpointProviderBindingForSession,
   serializeReplacementSandboxEnvelope,
   tagModalSandbox,
   verifySandboxExecReadiness,
@@ -33,6 +38,20 @@ function hasWorkspaceArchive(envelope: Record<string, unknown> | null): boolean
   );
 }
 
+function legacyNativeArchiveFromEnvelope(envelope: Record<string, unknown> | null) {
+  const sessionState =
+    envelope?.sessionState && typeof envelope.sessionState === "object"
+      ? (envelope.sessionState as Record<string, unknown>)
+      : null;
+  if (!sessionState) return null;
+  const existing = parseWorkspaceArchiveDescriptor(sessionState.workspaceArchiveMeta);
+  if (existing?.version === 2) return null;
+  return describeLegacyNativeSnapshotArchive(
+    sessionState.workspaceArchive,
+    existing?.version === 1 ? Date.parse(existing.capturedAt) : Date.now(),
+  );
+}
+
 function withoutProviderIdentity(
   envelope: Record<string, unknown> | null,
 ): Record<string, unknown> | null {
@@ -48,7 +67,9 @@ function withoutProviderIdentity(
 
 async function terminateCreated(established: EstablishedSandboxSession | null): Promise<boolean> {
   if (!established) return true;
-  const client = established.client as { delete?: (state: unknown) => Promise<unknown> };
+  const client = established.client as {
+    delete?: (state: unknown) => Promise<unknown>;
+  };
   try {
     if (typeof client.delete === "function" && established.sessionState !== undefined) {
       await client.delete(established.sessionState);
@@ -93,20 +114,30 @@ export async function establishApiSandboxSpawner(input: {
     hasWorkspaceArchive(input.fallbackEnvelope)
       ? withoutProviderIdentity(input.fallbackEnvelope)
       : null;
-  const spawnEnvelope =
+  let spawnEnvelope =
     fallbackArchiveEnvelope ?? input.acquiredLease.resumeState ?? input.fallbackEnvelope;
   const archiveSource =
     input.acquiredLease.recovery.archive.status === "none"
       ? fallbackArchiveEnvelope
       : input.acquiredLease.resumeState;
   let established: EstablishedSandboxSession | null = null;
-  let rematerialization: { id: string; selectedRevision: string } | null = null;
+  let rematerialization: {
+    id: string;
+    selectedRevision: string;
+    workspaceGeneration: number;
+    providerBindingKey: string | null;
+    legacyCheckpoint: ReturnType<typeof legacyNativeArchiveFromEnvelope>;
+    legacyProviderBinding: Awaited<
+      ReturnType<typeof resolveModalCheckpointProviderBindingForSession>
+    > | null;
+  } | null = null;
   try {
     if (
       input.acquiredLease.recovery.archive.status === "available" ||
       hasWorkspaceArchive(archiveSource)
     ) {
       const id = crypto.randomUUID();
+      const legacyNativeArchive = legacyNativeArchiveFromEnvelope(archiveSource);
       const begun = await beginSandboxRematerialization(input.db, {
         accountId: input.accountId,
         workspaceId: input.workspaceId,
@@ -114,6 +145,7 @@ export async function establishApiSandboxSpawner(input: {
         expectedEpoch: input.expectedEpoch,
         rematerializationId: id,
         archiveSource,
+        legacyNativeArchive,
       });
       if (begun.status !== "started") {
         if (begun.code === "stale_epoch" || begun.code === "attempt_conflict") {
@@ -129,6 +161,7 @@ export async function establishApiSandboxSpawner(input: {
           begun.lease?.recovery ?? input.acquiredLease.recovery,
         );
       }
+      spawnEnvelope = begun.lease.resumeState ?? spawnEnvelope;
       const selectedRevision = begun.lease.recovery.restore.selectedRevision;
       if (!selectedRevision) {
         throw new WorkspaceArchiveIntegrityError(
@@ -136,7 +169,14 @@ export async function establishApiSandboxSpawner(input: {
           "sandbox rematerialization selected no durable archive revision",
         );
       }
-      rematerialization = { id, selectedRevision };
+      rematerialization = {
+        id,
+        selectedRevision,
+        workspaceGeneration: begun.lease.workspaceGeneration,
+        providerBindingKey: begun.checkpointArtifact?.providerBindingKey ?? null,
+        legacyCheckpoint: begun.checkpointArtifact === null ? legacyNativeArchive : null,
+        legacyProviderBinding: null,
+      };
     } else if (input.acquiredLease.recovery.archive.status !== "none") {
       throw new SandboxLeaseRecoveryBlockedError(
         input.sandboxGroupId,
@@ -146,6 +186,7 @@ export async function establishApiSandboxSpawner(input: {
       );
     }
 
+    const providerCreateStartedAt = new Date();
     established = await establishSandboxSessionFromEnvelope(input.settings, spawnEnvelope, {
       sessionId: input.sessionId,
       recovery: "create-or-restore",
@@ -153,6 +194,37 @@ export async function establishApiSandboxSpawner(input: {
       environment: input.environment,
       onSandboxCreated: async (created) => {
         established = created;
+        if (
+          rematerialization &&
+          (rematerialization.providerBindingKey || rematerialization.legacyCheckpoint)
+        ) {
+          if (created.backendId !== "modal") {
+            throw new WorkspaceArchiveIntegrityError(
+              "native_snapshot_reference_invalid",
+              "Modal checkpoint restore resolved a non-Modal sandbox backend",
+            );
+          }
+          if (rematerialization.providerBindingKey) {
+            if (
+              !(await modalSessionMatchesCheckpointProviderBinding(
+                input.settings,
+                created.session,
+                rematerialization.providerBindingKey,
+              ))
+            ) {
+              throw new WorkspaceArchiveIntegrityError(
+                "native_snapshot_reference_invalid",
+                "Modal checkpoint restore refused because the authenticated provider workspace changed",
+              );
+            }
+          } else {
+            rematerialization.legacyProviderBinding =
+              await resolveModalCheckpointProviderBindingForSession(
+                input.settings,
+                created.session,
+              );
+          }
+        }
         const resumeState = requirePersistableReplacementSandboxEnvelope(
           await serializeReplacementSandboxEnvelope(created, spawnEnvelope),
           created.backendId,
@@ -166,6 +238,14 @@ export async function establishApiSandboxSpawner(input: {
           instanceId: created.instanceId,
           resumeBackendId: created.backendId,
           resumeState,
+          ...(created.backendId === "modal"
+            ? {
+                providerCreatedAt: providerCreateStartedAt,
+                providerDeadlineAt: new Date(
+                  providerCreateStartedAt.getTime() + input.settings.modalTimeoutSeconds * 1000,
+                ),
+              }
+            : {}),
           leaseTtlMs: input.settings.sandboxLeaseTtlMs,
           warmingLeaseTtlMs: input.settings.sandboxWarmingTimeoutMs,
         });
@@ -187,6 +267,33 @@ export async function establishApiSandboxSpawner(input: {
             `hydrated archive revision ${descriptor.revision} does not match the selected rematerialization revision`,
           );
         }
+        if (rematerialization.legacyCheckpoint) {
+          const binding = rematerialization.legacyProviderBinding;
+          if (!binding) {
+            throw new WorkspaceArchiveIntegrityError(
+              "native_snapshot_reference_invalid",
+              "Legacy Modal checkpoint restore produced no authenticated provider identity",
+            );
+          }
+          const adopted = await adoptLegacyModalCheckpointArtifact(input.db, {
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sandboxGroupId: input.sandboxGroupId,
+            leaseId: input.acquiredLease.id,
+            leaseEpoch: input.expectedEpoch,
+            workspaceGeneration: rematerialization.workspaceGeneration,
+            slot: "current",
+            archiveBase64: rematerialization.legacyCheckpoint.archiveBase64,
+            descriptor: rematerialization.legacyCheckpoint.descriptor,
+            providerBindingKey: binding.key,
+            providerBinding: binding.binding,
+            rematerializationId: rematerialization.id,
+          });
+          if (!adopted) {
+            throw new SandboxLeaseSupersededError(input.sandboxGroupId, input.expectedEpoch);
+          }
+          rematerialization.providerBindingKey = binding.key;
+        }
         const verifying = await markSandboxRestoreVerifying(input.db, {
           accountId: input.accountId,
           workspaceId: input.workspaceId,

package/src/sandbox/viewer.ts

@@ -24,6 +24,7 @@ import {
   hasGitCredentialRepositorySelection,
   hasGitHubRepositorySelection,
   resolveStreamTokenSecret,
+  sandboxArchiveCaptureTimeoutMs,
   stableSandboxEnvironmentForRun,
 } from "@opengeni/config";
 import type { Settings } from "@opengeni/config";
@@ -42,6 +43,7 @@ import {
   recordLeaseTerminalDataPlaneUrl,
   releaseLeaseHolder,
   SandboxLeaseSupersededError,
+  SandboxViewerAdmissionBlockedError,
   type Database,
   type LeaseSnapshot,
   type SandboxRecord,
@@ -195,18 +197,33 @@ export async function attachViewer(
     });
   };
 
-  const acquired = await acquireLease(db, {
-    accountId,
-    workspaceId,
-    sandboxGroupId,
-    kind: "viewer",
-    holderId: viewerId,
-    subjectId: session.id,
-    backend: session.sandboxBackend,
-    os: session.sandboxOs,
-    leaseTtlMs,
-    warmingLeaseTtlMs: settings.sandboxWarmingTimeoutMs,
-  });
+  let acquired: Awaited<ReturnType<typeof acquireLease>>;
+  try {
+    acquired = await acquireLease(db, {
+      accountId,
+      workspaceId,
+      sandboxGroupId,
+      kind: "viewer",
+      holderId: viewerId,
+      subjectId: session.id,
+      backend: session.sandboxBackend,
+      os: session.sandboxOs,
+      leaseTtlMs,
+      warmingLeaseTtlMs: settings.sandboxWarmingTimeoutMs,
+      captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
+    });
+  } catch (error) {
+    if (error instanceof SandboxViewerAdmissionBlockedError) {
+      throw new HTTPException(error.reason === "balance" ? 402 : 429, {
+        message:
+          error.reason === "balance"
+            ? "insufficient OpenGeni credits for an idle sandbox viewer"
+            : "workspace sandbox warm allowance exhausted",
+        cause: error,
+      });
+    }
+    throw error;
+  }
 
   // FENCED: a newer epoch re-established the box. Release our just-registered
   // holder and surface a 409 — the client re-reads capabilities and re-attaches.

package/src/transcription/providers/azure-openai.ts

@@ -0,0 +1,45 @@
+import type { TranscriptionProvider } from "@opengeni/core";
+import { fetchError, responseError } from "./openai";
+
+export function createAzureOpenAiTranscriptionProvider(input: {
+  endpoint: string;
+  deployment: string;
+  apiVersion: string;
+  apiKey: string | null;
+  adToken: string | null;
+  fetch?: typeof fetch;
+}): TranscriptionProvider {
+  const fetchImpl = input.fetch ?? fetch;
+  const url = `${input.endpoint}/openai/deployments/${encodeURIComponent(input.deployment)}/audio/transcriptions?api-version=${encodeURIComponent(input.apiVersion)}`;
+  return {
+    id: "azure-openai",
+    available: () => Boolean(input.apiKey || input.adToken),
+    async transcribe({ audio, mimeType, filename, signal }) {
+      const form = new FormData();
+      form.append("file", new Blob([Uint8Array.from(audio).buffer], { type: mimeType }), filename);
+      const headers: Record<string, string> = input.apiKey
+        ? { "api-key": input.apiKey }
+        : { Authorization: `Bearer ${input.adToken}` };
+      let response: Response;
+      try {
+        response = await fetchImpl(url, {
+          method: "POST",
+          headers,
+          body: form,
+          ...(signal ? { signal } : {}),
+        });
+      } catch (error) {
+        throw fetchError(error);
+      }
+      if (!response.ok) throw responseError(response.status);
+      const body = await response.json().catch(() => null);
+      if (!body || typeof body.text !== "string") {
+        throw responseError(502);
+      }
+      return {
+        text: body.text,
+        languages: typeof body.language === "string" && body.language ? [body.language] : [],
+      };
+    },
+  };
+}

package/src/transcription/providers/codex-subscription.ts

@@ -0,0 +1,100 @@
+import { CODEX_CLIENT_VERSION, CODEX_ORIGINATOR } from "@opengeni/codex/constants";
+import type { Settings } from "@opengeni/config";
+import {
+  type TranscriptionAvailabilityContext,
+  type TranscriptionProvider,
+  TranscriptionServiceError,
+} from "@opengeni/core";
+import { buildCodexTokenResolver, type Database, listCodexAccountStatuses } from "@opengeni/db";
+import { fetchError, responseError } from "./openai";
+
+const TRANSCRIBE_URL = "https://chatgpt.com/backend-api/transcribe";
+
+async function workspaceHasActiveCodexAccount(db: Database, workspaceId: string): Promise<boolean> {
+  const account = (await listCodexAccountStatuses(db, workspaceId)).find(
+    (candidate) => candidate.isActive && candidate.status === "active",
+  );
+  return account != null;
+}
+
+export function createCodexSubscriptionTranscriptionProvider(input: {
+  settings: Settings;
+  db: Database;
+  fetch?: typeof fetch;
+  probe?: (context?: TranscriptionAvailabilityContext) => boolean | Promise<boolean>;
+}): TranscriptionProvider {
+  const fetchImpl = input.fetch ?? fetch;
+  const probe =
+    input.probe ??
+    (async (context?: TranscriptionAvailabilityContext) => {
+      // Deployment-level readiness: registry construction already gated this
+      // provider on OPENGENI_CODEX_SUBSCRIPTION_ENABLED. Request selection
+      // passes workspaceId so we only claim Codex when a subscription is
+      // attached; otherwise OpenAI/Azure remain eligible.
+      if (!context?.workspaceId) return true;
+      return await workspaceHasActiveCodexAccount(input.db, context.workspaceId);
+    });
+  return {
+    id: "codex-subscription",
+    experimental: true,
+    available: probe,
+    async transcribe({ audio, mimeType, filename, workspaceId, signal }) {
+      const account = (await listCodexAccountStatuses(input.db, workspaceId)).find(
+        (candidate) => candidate.isActive && candidate.status === "active",
+      );
+      if (!account) {
+        throw new TranscriptionServiceError({
+          code: "unavailable",
+          message: "Transcription is unavailable.",
+        });
+      }
+      const resolver = buildCodexTokenResolver(input.db, input.settings, workspaceId, account.id);
+      let token: Awaited<ReturnType<typeof resolver.getToken>>;
+      try {
+        token = await resolver.getToken();
+      } catch {
+        throw new TranscriptionServiceError({
+          code: "unavailable",
+          message: "Transcription is unavailable.",
+        });
+      }
+      const request = async (accessToken: string, accountId: string | null) => {
+        const form = new FormData();
+        form.append(
+          "file",
+          new Blob([Uint8Array.from(audio).buffer], { type: mimeType }),
+          filename,
+        );
+        return await fetchImpl(TRANSCRIBE_URL, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            ...(accountId ? { "ChatGPT-Account-ID": accountId } : {}),
+            originator: CODEX_ORIGINATOR,
+            "User-Agent": `${CODEX_ORIGINATOR}/${CODEX_CLIENT_VERSION}`,
+            version: CODEX_CLIENT_VERSION,
+          },
+          body: form,
+          ...(signal ? { signal } : {}),
+        });
+      };
+      let response: Response;
+      try {
+        response = await request(token.accessToken, token.chatgptAccountId);
+        if (response.status === 401) {
+          token = await resolver.refresh();
+          response = await request(token.accessToken, token.chatgptAccountId);
+        }
+      } catch (error) {
+        throw fetchError(error);
+      }
+      if (!response.ok) throw responseError(response.status);
+      const body = await response.json().catch(() => null);
+      if (!body || typeof body.text !== "string") throw responseError(502);
+      return {
+        text: body.text,
+        languages: typeof body.language === "string" && body.language ? [body.language] : [],
+      };
+    },
+  };
+}

package/src/transcription/providers/openai.ts

@@ -0,0 +1,93 @@
+import { type TranscriptionProvider, TranscriptionServiceError } from "@opengeni/core";
+
+export function createOpenAiTranscriptionProvider(input: {
+  apiKey: string;
+  baseUrl: string;
+  model: string;
+  fetch?: typeof fetch;
+}): TranscriptionProvider {
+  const fetchImpl = input.fetch ?? fetch;
+  return {
+    id: "openai",
+    available: () => true,
+    async transcribe({ audio, mimeType, filename, signal }) {
+      const form = new FormData();
+      form.append("file", audioBlob(audio, mimeType), filename);
+      form.append("model", input.model);
+      let response: Response;
+      try {
+        response = await fetchImpl(`${input.baseUrl}/audio/transcriptions`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${input.apiKey}` },
+          body: form,
+          ...(signal ? { signal } : {}),
+        });
+      } catch (error) {
+        throw fetchError(error);
+      }
+      if (!response.ok) throw responseError(response.status);
+      const body = await response.json().catch(() => null);
+      if (!body || typeof body.text !== "string") {
+        throw new TranscriptionServiceError({
+          code: "provider",
+          message: "Invalid transcription response.",
+        });
+      }
+      return {
+        text: body.text,
+        languages: typeof body.language === "string" && body.language ? [body.language] : [],
+      };
+    },
+  };
+}
+
+function audioBlob(audio: Uint8Array, mimeType: string): Blob {
+  return new Blob([Uint8Array.from(audio).buffer], { type: mimeType });
+}
+
+export function responseError(status: number): TranscriptionServiceError {
+  if (status === 401 || status === 403) {
+    return new TranscriptionServiceError({
+      code: "unavailable",
+      message: "Transcription is unavailable.",
+    });
+  }
+  if (status === 413) {
+    return new TranscriptionServiceError({
+      code: "too_large",
+      message: "Audio is too large.",
+    });
+  }
+  if (status === 400 || status === 422) {
+    return new TranscriptionServiceError({
+      code: "invalid_audio",
+      message: "Audio could not be transcribed.",
+    });
+  }
+  if (status === 408 || status === 504) {
+    return new TranscriptionServiceError({
+      code: "timeout",
+      message: "Transcription timed out.",
+      retryable: true,
+    });
+  }
+  return new TranscriptionServiceError({
+    code: status >= 500 ? "unavailable" : "provider",
+    message: "Transcription provider failed.",
+    retryable: status >= 500,
+  });
+}
+
+export function fetchError(error: unknown): TranscriptionServiceError {
+  if (error instanceof DOMException && error.name === "AbortError") {
+    return new TranscriptionServiceError({
+      code: "cancelled",
+      message: "Transcription was cancelled.",
+    });
+  }
+  return new TranscriptionServiceError({
+    code: "network",
+    message: "Transcription provider is unreachable.",
+    retryable: true,
+  });
+}