@opengeni/api-router 2.11.0-canary.0 → 2.11.2-canary.0

package/src/routes/skills.ts

@@ -13,6 +13,7 @@ import {
   portableSkillCapabilityId,
   portableSkillPluginKey,
   requireAccessGrant,
+  requireAccessGrantAuthorization,
   resolveSkillImport,
   type ApiRouteDeps,
   type GitHubSkillSourceClient,
@@ -23,7 +24,9 @@ import {
   listInstalledSkills,
   PortableSkillInstallationVersionConflictError,
   PortableSkillInstallationVersionRequiredError,
+  PortableSkillSourcePathConflictError,
   uninstallPortableSkill,
+  SkillSourceRemovalAuthorityError,
 } from "@opengeni/db";
 import { loadSkillLibrarySkill, skillLibraryRepositoryUrl } from "@opengeni/runtime/skill-library";
 import { createHash } from "node:crypto";
@@ -31,6 +34,8 @@ import { HTTPException } from "hono/http-exception";
 import type { Hono } from "hono";
 
 import { createGitHubSkillSourceClient } from "../integrations/github-skill-source";
+import { registerSkillContentRoutes } from "./skill-content";
+import { skillInstallerActor, skillRemovalActor } from "./skill-install-authority";
 
 export type SkillRouteOverrides = Readonly<{
   github?: GitHubSkillSourceClient;
@@ -41,6 +46,7 @@ export function registerSkillRoutes(
   deps: ApiRouteDeps,
   overrides: SkillRouteOverrides = {},
 ): void {
+  registerSkillContentRoutes(app, deps);
   const github = overrides.github ?? createGitHubSkillSourceClient(deps.settings);
 
   app.get("/v1/workspaces/:workspaceId/skills", async (c) => {
@@ -55,7 +61,14 @@ export function registerSkillRoutes(
 
   app.post("/v1/workspaces/:workspaceId/skills/library/:libraryId/install", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
+    const access = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "capabilities:manage",
+    );
+    const { grant } = access;
+    const skillActor = skillInstallerActor(access);
     const libraryId = decodeURIComponent(c.req.param("libraryId"));
     const payload = InstallLibrarySkillRequest.parse(await c.req.json());
     let loaded: ReturnType<typeof loadSkillLibrarySkill>;
@@ -81,6 +94,7 @@ export function registerSkillRoutes(
     });
     try {
       const installed = await installPortableSkill(deps.db, {
+        skillActor,
         accountId: grant.accountId,
         workspaceId,
         subjectId: grant.subjectId,
@@ -136,7 +150,14 @@ export function registerSkillRoutes(
 
   app.post("/v1/workspaces/:workspaceId/skills/install", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
+    const access = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "capabilities:manage",
+    );
+    const { grant } = access;
+    const skillActor = skillInstallerActor(access);
     const payload = InstallSkillRequest.parse(await c.req.json());
     const resolved = await resolveForRoute(payload.url, github);
     if (
@@ -153,6 +174,7 @@ export function registerSkillRoutes(
     );
     try {
       const installed = await installPortableSkill(deps.db, {
+        skillActor,
         accountId: grant.accountId,
         workspaceId,
         subjectId: grant.subjectId,
@@ -204,13 +226,21 @@ export function registerSkillRoutes(
 
   app.delete("/v1/workspaces/:workspaceId/skills/:capabilityId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
+    const access = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "capabilities:manage",
+    );
+    const { grant } = access;
+    const skillActor = skillRemovalActor(access);
     const capabilityId = decodeURIComponent(c.req.param("capabilityId"));
     const payload = UninstallSkillRequest.parse(await c.req.json());
     try {
       return c.json(
         UninstallSkillResult.parse(
           await uninstallPortableSkill(deps.db, {
+            ...(skillActor ? { skillActor } : {}),
             accountId: grant.accountId,
             workspaceId,
             capabilityId,
@@ -224,12 +254,17 @@ export function registerSkillRoutes(
           message: "The Skill changed after preview. Review uninstall impact again.",
         });
       }
+      if (error instanceof SkillSourceRemovalAuthorityError)
+        throw new HTTPException(403, { message: error.message });
       throw error;
     }
   });
 }
 
 function portableSkillMutationHttpError(error: unknown): Error {
+  if (error instanceof PortableSkillSourcePathConflictError) {
+    return new HTTPException(409, { message: error.message });
+  }
   if (error instanceof PortableSkillInstallationVersionRequiredError) {
     return new HTTPException(400, { message: error.message });
   }

package/src/routes/transcription-recordings.ts

@@ -5,6 +5,7 @@ import {
   resolveWorkspaceVoiceInputEnabled,
   TRANSCRIPTION_RECORDING_PROVIDER_SEGMENT_SECONDS,
   TRANSCRIPTION_RECORDING_RECOVERY_RETRY_AFTER_MILLISECONDS,
+  WorkspaceVoiceInputSettings,
   type TranscriptionRecordingErrorCode,
   type TranscriptionRecordingResponse,
   type UploadTranscriptionRecordingChunkResponse,
@@ -58,6 +59,7 @@ type RecordingAuthority = {
   accountId: string;
   workspaceId: string;
   subjectId: string;
+  voiceInput?: WorkspaceVoiceInputSettings | undefined;
 };
 
 class RecordingProcessingError extends Error {
@@ -357,6 +359,8 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
       let authority: RecordingAuthority | null = null;
       let attemptId: string | null = null;
       let segmentNumber: number | null = null;
+      let attemptedProvider: string | null = null;
+      let fallbackAllowed = false;
       try {
         authority = await requireRecordingAuthority(c, deps, true);
         const service = deps.transcription;
@@ -372,6 +376,8 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
         }
         const selectedProvider = service.selectProvider
           ? await service.selectProvider({
+              preferredProvider: authority.voiceInput?.preferredProvider,
+              fallbackEnabled: authority.voiceInput?.fallbackEnabled,
               workspaceId: authority.workspaceId,
               subjectId: authority.subjectId,
             })
@@ -395,6 +401,8 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           );
         }
         segmentNumber = claim.segment.segmentNumber;
+        attemptedProvider = claim.segment.providerId;
+        fallbackAllowed = claim.fallbackAllowed === true;
         const segmentKey = claim.segment.objectKey;
         const stored = deps.objectStorage
           ? await retryWhileMissing(async () => deps.objectStorage!.getObjectBytes(segmentKey))
@@ -452,12 +460,32 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
       } catch (error) {
         if (authority && attemptId && segmentNumber !== null) {
           const failure = processingFailure(error);
+          // Only an explicit rejection may move an untouched recording to another vendor.
+          // The database fences this against stale attempts and completed segments.
+          const fallbackProviderId =
+            fallbackAllowed &&
+            error instanceof TranscriptionServiceError &&
+            error.fallbackSafe &&
+            authority.voiceInput?.fallbackEnabled !== false &&
+            attemptedProvider &&
+            deps.transcription?.selectProvider
+              ? await Promise.resolve(
+                  deps.transcription.selectProvider({
+                    workspaceId: authority.workspaceId,
+                    subjectId: authority.subjectId,
+                    preferredProvider: authority.voiceInput?.preferredProvider,
+                    excludedProviders: [attemptedProvider],
+                    afterProvider: attemptedProvider,
+                  }),
+                ).catch(() => null)
+              : null;
           const persisted = await failTranscriptionRecordingSegment(deps.db, {
             workspaceId: authority.workspaceId,
             subjectId: authority.subjectId,
             recordingId: uuidParam(c, "recordingId"),
             segmentNumber,
             attemptId,
+            fallbackProviderId,
             errorCode: failure.code,
             retryable: failure.retryable,
           }).catch(() => null);
@@ -505,14 +533,15 @@ async function requireRecordingAuthority(
     throw new TranscriptionRecordingNotFoundError("Workspace not found");
   }
   const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+  const workspace = await getWorkspace(deps.db, workspaceId);
   if (requirePolicy) {
-    const workspace = await getWorkspace(deps.db, workspaceId);
     if (!workspace) throw new TranscriptionRecordingNotFoundError("Workspace not found");
     if (resolveWorkspaceVoiceInputEnabled(workspace.settings) === false) {
       throw new RecordingProcessingError("Voice input is disabled", "policy_blocked", false);
     }
   }
   return {
+    voiceInput: WorkspaceVoiceInputSettings.safeParse(workspace?.settings.voiceInput).data,
     accountId: grant.accountId,
     workspaceId,
     subjectId: grant.subjectId,

package/src/routes/transcriptions.ts

@@ -1,5 +1,6 @@
 import {
   resolveWorkspaceVoiceInputEnabled,
+  WorkspaceVoiceInputSettings,
   type TranscribeAudioResponse,
 } from "@opengeni/contracts";
 import { type ApiRouteDeps, requireAccessGrant, TranscriptionServiceError } from "@opengeni/core";
@@ -17,6 +18,7 @@ export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void
     if (resolveWorkspaceVoiceInputEnabled(workspace.settings) === false) {
       return c.json({ code: "policy_blocked" }, 403);
     }
+    const preferences = WorkspaceVoiceInputSettings.safeParse(workspace.settings.voiceInput).data;
     const service = deps.transcription;
     if (!service || !(await service.available({ workspaceId, subjectId: grant.subjectId }))) {
       return c.json({ code: "unavailable" }, 503);
@@ -24,6 +26,8 @@ export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void
     try {
       const body = await audioRequest(c.req.raw, service.limits().maxSizeBytes);
       const result = await service.transcribe({
+        preferredProvider: preferences?.preferredProvider,
+        fallbackEnabled: preferences?.fallbackEnabled,
         workspaceId,
         accountId: grant.accountId,
         subjectId: grant.subjectId,

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

@@ -45,6 +45,7 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
       );
       if (!account) {
         throw new TranscriptionServiceError({
+          fallbackSafe: true,
           code: "unavailable",
           message: "Transcription is unavailable.",
         });
@@ -55,6 +56,7 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
         token = await resolver.getToken();
       } catch {
         throw new TranscriptionServiceError({
+          fallbackSafe: true,
           code: "unavailable",
           message: "Transcription is unavailable.",
         });

package/src/transcription/providers/openai.ts

@@ -53,6 +53,7 @@ function audioBlob(audio: Uint8Array, mimeType: string): Blob {
 export function responseError(status: number): TranscriptionServiceError {
   if (status === 401 || status === 403) {
     return new TranscriptionServiceError({
+      fallbackSafe: true,
       code: "unavailable",
       message: "Transcription is unavailable.",
     });

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

@@ -62,6 +62,7 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
       } catch {
         throw new TranscriptionServiceError({
           code: "unavailable",
+          fallbackSafe: true,
           message: "Transcription is unavailable.",
         });
       }
@@ -86,16 +87,28 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
           ...(signal ? { signal } : {}),
         });
       };
+      const tokenForRequest = async (refresh: boolean) => {
+        try {
+          return await (refresh ? auth.context.refresh() : auth.context.getToken());
+        } catch {
+          throw new TranscriptionServiceError({
+            code: "unavailable",
+            message: "Reconnect the SuperGrok account to use transcription.",
+            fallbackSafe: true,
+          });
+        }
+      };
       let response: Response;
       try {
-        let token = await auth.context.getToken();
+        let token = await tokenForRequest(false);
         response = await request(token.accessToken);
-        if (response.status === 401) {
+        if (response.status === 401 || (await isXaiInvalidCredentialResponse(response))) {
           await response.body?.cancel().catch(() => undefined);
-          token = await auth.context.refresh();
+          token = await tokenForRequest(true);
           response = await request(token.accessToken);
         }
       } catch (error) {
+        if (error instanceof TranscriptionServiceError) throw error;
         throw fetchError(error);
       }
       if (!response.ok) throw responseError(response.status);
@@ -108,3 +121,36 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
     },
   };
 }
+
+export async function isXaiInvalidCredentialResponse(response: Response): Promise<boolean> {
+  if (response.status !== 403) return false;
+  const reader = response.clone().body?.getReader();
+  if (!reader) return false;
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 16_384) return false;
+      chunks.push(chunk.value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    const body = JSON.parse(new TextDecoder().decode(bytes));
+    return (
+      typeof body?.error === "string" &&
+      body.error.includes("[WKE=unauthenticated:bad-credentials]")
+    );
+  } catch {
+    return false;
+  } finally {
+    void reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}

package/src/transcription/service.ts

@@ -74,7 +74,7 @@ export function createTranscriptionService(input: {
       );
     },
     async selectProvider(context) {
-      return (await firstAvailable(providers, context))?.id ?? null;
+      return (await firstAvailable(orderedProviders(providers, context), context))?.id ?? null;
     },
     async transcribe(request) {
       const mimeType = normalizeMimeType(request.mimeType);
@@ -106,12 +106,10 @@ export function createTranscriptionService(input: {
             workspaceId: request.workspaceId,
             subjectId: request.subjectId,
           })
-        : await firstAvailable(providers, {
-            workspaceId: request.workspaceId,
-            subjectId: request.subjectId,
-          });
+        : await firstAvailable(orderedProviders(providers, request), request);
       if (!provider) {
         throw new TranscriptionServiceError({
+          fallbackSafe: true,
           code: "unavailable",
           message: "Transcription is unavailable.",
         });
@@ -164,6 +162,23 @@ export function createTranscriptionService(input: {
             retryable: true,
           });
         }
+        if (
+          error instanceof TranscriptionServiceError &&
+          error.fallbackSafe &&
+          !request.providerId &&
+          request.fallbackEnabled !== false &&
+          !request.signal?.aborted
+        ) {
+          const excludedProviders = [...(request.excludedProviders ?? []), provider.id];
+          if (
+            await firstAvailable(
+              orderedProviders(providers, { ...request, excludedProviders }),
+              request,
+            )
+          ) {
+            return await this.transcribe({ ...request, excludedProviders });
+          }
+        }
         throw error;
       } finally {
         deadline.dispose();
@@ -217,12 +232,34 @@ function createProviderRequestDeadline(
   };
 }
 
+export function orderedProviders(
+  providers: readonly TranscriptionProvider[],
+  context: TranscriptionAvailabilityContext,
+): TranscriptionProvider[] {
+  const preferred = providers.filter((provider) => provider.id === context.preferredProvider);
+  const ordered = context.preferredProvider
+    ? context.fallbackEnabled === false
+      ? preferred
+      : [...preferred, ...providers.filter((provider) => provider.id !== context.preferredProvider)]
+    : context.fallbackEnabled === false
+      ? providers.slice(0, 1)
+      : [...providers];
+  const remaining = context.afterProvider
+    ? ordered.slice(ordered.findIndex((provider) => provider.id === context.afterProvider) + 1)
+    : ordered;
+  return remaining.filter((provider) => !context.excludedProviders?.includes(provider.id));
+}
+
 async function firstAvailable(
   providers: readonly TranscriptionProvider[],
   context: TranscriptionAvailabilityContext,
 ) {
   for (const provider of providers) {
-    if (await provider.available(context)) return provider;
+    try {
+      if (await provider.available(context)) return provider;
+    } catch {
+      /* No audio sent; another configured provider may be ready. */
+    }
   }
   return null;
 }

package/src/xai-subscription-auth.ts

@@ -77,14 +77,20 @@ export async function buildXaiSubscriptionAuthorization(input: {
       userId: credential.providerAccountId,
     };
   };
-  return {
+  const authorization: XaiSubscriptionAuthorization = {
     credentialId,
     authoritySnapshot,
     rotationEnabled: selected.rotationEnabled,
     context: {
       clientVersion: XAI_CLIENT_VERSION,
       ...(input.sessionId ? { sessionId: input.sessionId } : {}),
-      getToken: async () => tokenSnapshot(),
+      getToken: async () => {
+        const expiresAt = xaiAccessTokenExpiry(credential.secret.accessToken ?? "");
+        if (expiresAt && expiresAt.getTime() <= Date.now() + 60_000) {
+          return await authorization.context.refresh();
+        }
+        return tokenSnapshot();
+      },
       refresh: async () => {
         const observedAccessToken = credential.secret.accessToken;
         const observedRefreshToken = credential.secret.refreshToken;
@@ -129,4 +135,5 @@ export async function buildXaiSubscriptionAuthorization(input: {
       },
     },
   };
+  return authorization;
 }