@opengeni/api-router 0.21.14 → 0.23.1

package/src/routes/transcriptions.ts

@@ -5,8 +5,10 @@ import {
 import { type ApiRouteDeps, requireAccessGrant, TranscriptionServiceError } from "@opengeni/core";
 import { getWorkspace } from "@opengeni/db";
 import type { Hono } from "hono";
+import { registerResumableTranscriptionRoutes } from "./transcription-recordings";
 
 export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void {
+  registerResumableTranscriptionRoutes(app, deps);
   app.post("/v1/workspaces/:workspaceId/transcriptions", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");

package/src/sandbox/auth-callout.ts

@@ -10,8 +10,8 @@
 //      to, the `server_id` for the response `aud`, and the presented `auth_token`);
 //   2. VALIDATES the bearer with verifyEnrollmentBearer (HMAC, via
 //      resolveEnrollmentSigningSecret) — an invalid/expired/forged bearer is denied;
-//   3. confirms the enrollment is still ACTIVE in the DB (a revoked machine is
-//      denied even with a still-unexpired bearer);
+//   3. confirms the enrollment is still ACTIVE in the DB at the exact credential
+//      generation (a revoked or re-enrolled machine denies an old bearer);
 //   4. signs a NATS user JWT granting pub/sub ONLY `agent.<ws>.>` + `_INBOX.>`
 //      (deny-all-else by an allow-list) and returns it inside a signed
 //      authorization-response JWT.
@@ -48,6 +48,8 @@ import { observabilityEventLogger } from "../observability";
 
 /** The NATS subject nats-server publishes authorization requests on (ADR-26). */
 export const AUTH_CALLOUT_SUBJECT = "$SYS.REQ.USER.AUTH";
+/** Keep live NATS credentials short-lived while never outliving the bearer. */
+export const NATS_USER_JWT_TTL_SECONDS = 5 * 60;
 
 export interface AuthCalloutDeps {
   db: Database;
@@ -123,13 +125,23 @@ export async function handleAuthorizationRequest(
   // Belt-and-braces: the bearer's agentId/enrollmentId must match the row we found.
   // (verifyEnrollmentBearer already binds them; this guards a future schema where
   // agentId != enrollmentId.)
-  if (enrollment.id !== claims.enrollmentId) {
+  if (
+    enrollment.workspaceId !== claims.workspaceId ||
+    enrollment.id !== claims.enrollmentId ||
+    enrollment.id !== claims.agentId ||
+    claims.agentId !== claims.enrollmentId ||
+    claims.subjectPrefix !== `agent.${claims.workspaceId}.${claims.agentId}`
+  ) {
     return deny("enrollment identity mismatch");
   }
+  if (enrollment.credentialGeneration !== claims.credentialGeneration) {
+    return deny("enrollment credential generation mismatch");
+  }
 
   // GRANT: a user JWT scoped to ONLY this workspace's agent subtree + the reply
   // inbox. This allow-list IS the per-workspace isolation boundary.
   const permissions = workspaceAgentPermissions(claims.workspaceId);
+  const nowSeconds = Math.floor(Date.now() / 1000);
   const userJwt = mintUserJwt({
     userPublicKey: decoded.userNkey,
     accountSeed: deps.callout.accountSeed,
@@ -142,7 +154,7 @@ export async function handleAuthorizationRequest(
     audienceAccount: deps.callout.accountName,
     // Tie the credential's life to the bearer's remaining life: a revoked/expired
     // enrollment cannot outlive its bearer at the NATS layer either.
-    expiresAtSeconds: claims.exp,
+    expiresAtSeconds: Math.min(claims.exp, nowSeconds + NATS_USER_JWT_TTL_SECONDS),
   });
   const response = mintAuthResponse({
     userPublicKey: decoded.userNkey,

package/src/sandbox/channel-a.ts

@@ -30,6 +30,7 @@ import type { Session } from "@opengeni/contracts";
 import {
   acquireLease,
   getSandboxSessionEnvelope,
+  getEnrollment,
   getSandbox,
   loadWorkspaceEnvironmentForRun,
   markWarmLeaseInstanceLost,
@@ -49,6 +50,7 @@ import {
   isProviderSandboxNotFoundError,
   SandboxChannelAService,
   NatsControlRpc,
+  NatsOpStreamTransport,
   ChannelAConflictError,
   ChannelANotFoundError,
   ChannelAUnsupportedError,
@@ -90,6 +92,97 @@ export type ChannelAHandle = {
   requestId: string;
 };
 
+/**
+ * Provider handles are lightweight references to a lease-owned sandbox, but
+ * reconstructing one is not free: Modal resume-by-id plus its first command can
+ * dominate a small Git/files read. Workspace panels issue several independent
+ * Channel-A requests together, so reuse the exact fenced handle briefly instead
+ * of making every request reattach to the same warm instance.
+ *
+ * The key includes the session, lease epoch, and immutable provider instance id.
+ * A rotation can therefore never inherit an old handle. Entries are bounded and
+ * expire opportunistically; eviction only drops local references and never
+ * terminates the lease-owned sandbox.
+ */
+const CHANNEL_A_HANDLE_CACHE_TTL_MS = 300_000;
+const CHANNEL_A_HANDLE_CACHE_MAX_ENTRIES = 64;
+type CachedEstablishedHandle = {
+  promise: Promise<EstablishedSandboxSession>;
+  lastUsedAt: number;
+};
+const establishedHandleCache = new Map<string, CachedEstablishedHandle>();
+
+function establishedHandleCacheKey(
+  workspaceId: string,
+  sessionId: string,
+  lease: LeaseSnapshot,
+): string {
+  return [workspaceId, sessionId, lease.leaseEpoch, lease.instanceId ?? ""].join("\u0000");
+}
+
+function pruneEstablishedHandleCache(now: number): void {
+  for (const [key, entry] of establishedHandleCache) {
+    if (now - entry.lastUsedAt > CHANNEL_A_HANDLE_CACHE_TTL_MS) {
+      establishedHandleCache.delete(key);
+    }
+  }
+  while (establishedHandleCache.size >= CHANNEL_A_HANDLE_CACHE_MAX_ENTRIES) {
+    const oldestKey = establishedHandleCache.keys().next().value as string | undefined;
+    if (oldestKey === undefined) break;
+    establishedHandleCache.delete(oldestKey);
+  }
+}
+
+async function establishCachedHandle(
+  key: string,
+  establish: () => Promise<EstablishedSandboxSession>,
+): Promise<EstablishedSandboxSession> {
+  const now = Date.now();
+  pruneEstablishedHandleCache(now);
+  const cached = establishedHandleCache.get(key);
+  if (cached) {
+    cached.lastUsedAt = now;
+    // Refresh insertion order so the bounded map evicts the least-recently used
+    // exact lease identity first.
+    establishedHandleCache.delete(key);
+    establishedHandleCache.set(key, cached);
+    return await cached.promise;
+  }
+
+  const promise = establish();
+  const entry: CachedEstablishedHandle = { promise, lastUsedAt: now };
+  establishedHandleCache.set(key, entry);
+  try {
+    return await promise;
+  } catch (error) {
+    if (establishedHandleCache.get(key) === entry) establishedHandleCache.delete(key);
+    throw error;
+  }
+}
+
+/** Reuse the exact lease-fenced provider handle across API-direct surfaces.
+ * Stream capability negotiation and the first Files/Changes reads commonly run
+ * back-to-back; sharing this handle avoids paying the same Modal resume twice. */
+export async function establishCachedChannelAHandle(
+  workspaceId: string,
+  sessionId: string,
+  lease: LeaseSnapshot,
+  establish: () => Promise<EstablishedSandboxSession>,
+): Promise<EstablishedSandboxSession> {
+  return await establishCachedHandle(
+    establishedHandleCacheKey(workspaceId, sessionId, lease),
+    establish,
+  );
+}
+
+function rememberEstablishedHandle(key: string, established: EstablishedSandboxSession): void {
+  pruneEstablishedHandleCache(Date.now());
+  establishedHandleCache.set(key, {
+    promise: Promise.resolve(established),
+    lastUsedAt: Date.now(),
+  });
+}
+
 /**
  * Run a Channel-A op against a live box, API-direct. Acquires an exact direct holder
  * (warming the box when cold), resumes by id, builds the service, runs `fn`, and
@@ -169,7 +262,12 @@ export async function withChannelA<T>(
       leaseEpoch: lease?.leaseEpoch ?? session.activeEpoch,
       emit,
     });
-    return await fn({ service, lease, routingSession, requestId });
+    const result = await fn({ service, lease, routingSession, requestId });
+    // The direct request has accepted the result in memory. Finalize every
+    // Connected Machine backend the routing proxy reached so a mid-request
+    // route transition cannot leave completed output retained until TTL.
+    await routingSession.finalizeOpStreamOps().catch(() => undefined);
+    return result;
   };
 
   // A machine-targeted top-level session has an honest selfhosted HOME label.
@@ -190,6 +288,7 @@ export async function withChannelA<T>(
           message: "machine-home session points to an unavailable Connected Machine",
         });
       }
+      const enrollment = await getEnrollment(db, workspaceId, sandbox.enrollmentId);
       const built = await buildSelfhostedBackendSession({
         workspaceId,
         agentId: sandbox.enrollmentId,
@@ -200,6 +299,17 @@ export async function withChannelA<T>(
         workingDir: pointer.workingDir,
         timeoutMs: settings.sandboxSelfhostedControlTimeoutMs,
         execTimeoutMs: settings.sandboxSelfhostedExecTimeoutMs,
+        ...(settings.agentOpStreamEnabled === true &&
+        enrollment?.opStream === true &&
+        bus.getOpStreamConnection
+          ? {
+              opStream: {
+                transport: new NatsOpStreamTransport(
+                  async () => bus.getOpStreamConnection?.() ?? null,
+                ),
+              },
+            }
+          : {}),
       });
       established = {
         client: built.client,
@@ -271,6 +381,7 @@ export async function withChannelA<T>(
 
   let established: EstablishedSandboxSession | undefined;
   let leaseSnapshot: LeaseSnapshot = acquired.lease;
+  let establishedCacheKey: string | null = null;
 
   try {
     const envelope = await getSandboxSessionEnvelope(db, workspaceId, session.id);
@@ -303,6 +414,8 @@ export async function withChannelA<T>(
         });
         established = result.established;
         leaseSnapshot = result.lease;
+        establishedCacheKey = establishedHandleCacheKey(workspaceId, session.id, leaseSnapshot);
+        rememberEstablishedHandle(establishedCacheKey, established);
       } catch (error) {
         throw new HTTPException(409, {
           message: `sandbox not available (${error instanceof Error ? error.message : "spawn failed"})`,
@@ -323,17 +436,21 @@ export async function withChannelA<T>(
         });
       }
       leaseSnapshot = live;
+      establishedCacheKey = establishedHandleCacheKey(workspaceId, session.id, live);
       try {
-        established = await establishSandboxSessionFromEnvelope(settings, live.resumeState, {
-          sessionId: session.id,
-          recovery: "resume-only",
-          backendOverride: session.sandboxBackend,
-          environment,
-        });
+        established = await establishCachedChannelAHandle(workspaceId, session.id, live, () =>
+          establishSandboxSessionFromEnvelope(settings, live.resumeState, {
+            sessionId: session.id,
+            recovery: "resume-only",
+            backendOverride: session.sandboxBackend,
+            environment,
+          }),
+        );
       } catch (error) {
         if (!isProviderSandboxNotFoundError(session.sandboxBackend, error)) {
           throw error;
         }
+        establishedHandleCache.delete(establishedCacheKey);
         const marked = await markWarmLeaseInstanceLost(db, {
           accountId,
           workspaceId,

package/src/sandbox/enrollment.ts

@@ -75,8 +75,9 @@ export const DEVICE_POLL_INTERVAL_SECONDS = 5;
 // box) caused a self-hosted agent to drop PERMANENTLY one hour after connecting: the
 // bearer expired and the auth-callout rejected every reconnect ("re-enroll may be
 // required"). A long-lived bearer is safe because the auth-callout RE-CHECKS the
-// enrollment status on every (re)connect (auth-callout.ts) — a revoked machine is
-// denied regardless of bearer life — exactly as the long-lived relay token relies on.
+// enrollment status AND credential generation on every (re)connect
+// (auth-callout.ts) — a revoked machine or an old pre-re-enrollment bearer is denied
+// regardless of bearer life. The short NATS user-JWT cap bounds already-live access.
 export const ENROLLMENT_BEARER_TTL_SECONDS = 30 * 24 * 3600;
 // The relay PRODUCER token (the `ogr_` token; M8b) is ENROLLMENT-scoped,
 // NOT per-stream: the agent presents it on every channel registration for the life
@@ -370,6 +371,7 @@ export async function exchangeEnrollToken(
     secret,
     workspaceId: claims.workspaceId,
     agentId: enrollment.id,
+    credentialGeneration: enrollment.credentialGeneration,
     consentedScreenControl: enrollment.allowScreenControl,
   });
   return { ok: true, credentials };
@@ -430,6 +432,7 @@ export async function pollDeviceEnrollment(
     secret,
     workspaceId: request.workspaceId,
     agentId: enrollment.id,
+    credentialGeneration: enrollment.credentialGeneration,
     consentedScreenControl: enrollment.allowScreenControl,
   });
 
@@ -455,7 +458,13 @@ export async function pollDeviceEnrollment(
  *  bearer so an agent using it as the connect-token credential works uniformly. */
 async function buildEnrollmentCredentials(
   services: EnrollmentServices,
-  input: { secret: string; workspaceId: string; agentId: string; consentedScreenControl: boolean },
+  input: {
+    secret: string;
+    workspaceId: string;
+    agentId: string;
+    credentialGeneration: number;
+    consentedScreenControl: boolean;
+  },
 ): Promise<EnrollmentCredentialsResponse> {
   const { settings } = services;
   // The control-plane subject prefix the agent subscribes to: agent.<ws>.<id>.
@@ -466,6 +475,7 @@ async function buildEnrollmentCredentials(
     workspaceId: input.workspaceId,
     agentId: input.agentId,
     enrollmentId: input.agentId,
+    credentialGeneration: input.credentialGeneration,
     subjectPrefix,
     exp,
   });

package/src/sandbox/machines.ts

@@ -219,7 +219,7 @@ export async function listMachines(
   // onto the machines (no N+1). Each machine is probed for liveness.
   const [sandboxes, enrollments, metricsByEnrollment] = await Promise.all([
     listSandboxes(db, workspaceId),
-    listEnrollments(db, workspaceId),
+    listEnrollments(db, workspaceId, { status: "active" }),
     readMachineMetricsLatestForWorkspace(db, workspaceId),
   ]);
   const enrollmentById = new Map(enrollments.map((e) => [e.id, e]));

package/src/sandbox/viewer.ts

@@ -74,6 +74,7 @@ import {
 } from "@opengeni/runtime/sandbox";
 import { relayConfigFromSettings } from "@opengeni/core";
 import { establishApiSandboxSpawner } from "./rematerialize";
+import { establishCachedChannelAHandle } from "./channel-a";
 
 /** The minimal services a viewer op needs: the DB + settings (lease cadence +
  *  the sandbox client construction the leaf reads from settings). The bus is
@@ -730,18 +731,22 @@ export async function mintDesktopStream(
     // SAME stable run-env the turn declares, so a later turn finds no env delta.
     const environment = await sessionAttachEnvironment(services, workspaceId, session);
     try {
+      const establish = () =>
+        (services.establishSandboxSession ?? establishSandboxSessionFromEnvelope)(
+          settings,
+          envelope,
+          {
+            sessionId: session.id,
+            recovery: "resume-only",
+            backendOverride: session.sandboxBackend,
+            environment,
+          },
+        );
       established = input.establish
         ? await input.establish(envelope)
-        : await (services.establishSandboxSession ?? establishSandboxSessionFromEnvelope)(
-            settings,
-            envelope,
-            {
-              sessionId: session.id,
-              recovery: "resume-only",
-              backendOverride: session.sandboxBackend,
-              environment,
-            },
-          );
+        : services.establishSandboxSession
+          ? await establish()
+          : await establishCachedChannelAHandle(workspaceId, session.id, lease, establish);
     } catch (error) {
       await retireMissingWarmLease(services, { accountId, workspaceId, session, lease }, error);
       return null;
@@ -955,18 +960,22 @@ export async function mintTerminalStream(
     // declares, so a later turn finds no manifest-env delta.
     const environment = await sessionAttachEnvironment(services, workspaceId, session);
     try {
+      const establish = () =>
+        (services.establishSandboxSession ?? establishSandboxSessionFromEnvelope)(
+          settings,
+          envelope,
+          {
+            sessionId: session.id,
+            recovery: "resume-only",
+            backendOverride: session.sandboxBackend,
+            environment,
+          },
+        );
       established = input.establish
         ? await input.establish(envelope)
-        : await (services.establishSandboxSession ?? establishSandboxSessionFromEnvelope)(
-            settings,
-            envelope,
-            {
-              sessionId: session.id,
-              recovery: "resume-only",
-              backendOverride: session.sandboxBackend,
-              environment,
-            },
-          );
+        : services.establishSandboxSession
+          ? await establish()
+          : await establishCachedChannelAHandle(workspaceId, session.id, lease, establish);
     } catch (error) {
       await retireMissingWarmLease(services, { accountId, workspaceId, session, lease }, error);
       return null;

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

@@ -13,13 +13,14 @@ export function createAzureOpenAiTranscriptionProvider(input: {
   const url = `${input.endpoint}/openai/deployments/${encodeURIComponent(input.deployment)}/audio/transcriptions?api-version=${encodeURIComponent(input.apiVersion)}`;
   return {
     id: "azure-openai",
+    supportsServerDeadline: true,
     available: () => Boolean(input.apiKey || input.adToken),
-    async transcribe({ audio, mimeType, filename, signal }) {
+    async transcribe({ audio, mimeType, filename, requestId, 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}` };
+        ? { "api-key": input.apiKey, "x-opengeni-request-id": requestId }
+        : { Authorization: `Bearer ${input.adToken}`, "x-opengeni-request-id": requestId };
       let response: Response;
       try {
         response = await fetchImpl(url, {

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

@@ -36,9 +36,10 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
     });
   return {
     id: "codex-subscription",
+    supportsServerDeadline: true,
     experimental: true,
     available: probe,
-    async transcribe({ audio, mimeType, filename, workspaceId, signal }) {
+    async transcribe({ audio, mimeType, filename, workspaceId, requestId, signal }) {
       const account = (await listCodexAccountStatuses(input.db, workspaceId)).find(
         (candidate) => candidate.isActive && candidate.status === "active",
       );
@@ -73,6 +74,8 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
             originator: CODEX_ORIGINATOR,
             "User-Agent": `${CODEX_ORIGINATOR}/${CODEX_CLIENT_VERSION}`,
             version: CODEX_CLIENT_VERSION,
+            // Observability only; the upstream API is not treated as idempotent.
+            "x-opengeni-request-id": requestId,
           },
           body: form,
           ...(signal ? { signal } : {}),

package/src/transcription/providers/openai.ts

@@ -9,8 +9,9 @@ export function createOpenAiTranscriptionProvider(input: {
   const fetchImpl = input.fetch ?? fetch;
   return {
     id: "openai",
+    supportsServerDeadline: true,
     available: () => true,
-    async transcribe({ audio, mimeType, filename, signal }) {
+    async transcribe({ audio, mimeType, filename, requestId, signal }) {
       const form = new FormData();
       form.append("file", audioBlob(audio, mimeType), filename);
       form.append("model", input.model);
@@ -18,7 +19,11 @@ export function createOpenAiTranscriptionProvider(input: {
       try {
         response = await fetchImpl(`${input.baseUrl}/audio/transcriptions`, {
           method: "POST",
-          headers: { Authorization: `Bearer ${input.apiKey}` },
+          headers: {
+            Authorization: `Bearer ${input.apiKey}`,
+            // Observability only; the upstream API is not treated as idempotent.
+            "x-opengeni-request-id": requestId,
+          },
           body: form,
           ...(signal ? { signal } : {}),
         });