@opengeni/api-router 0.12.7 → 0.14.3

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,
+  });
+}

package/src/transcription/service.ts

@@ -0,0 +1,121 @@
+import { resolveVoiceInputProviderRegistry, type Settings } from "@opengeni/config";
+import { VOICE_INPUT_ACCEPTED_MIME_TYPES } from "@opengeni/contracts";
+import {
+  filenameForMimeType,
+  isAcceptedMimeType,
+  normalizeMimeType,
+  type TranscriptionAvailabilityContext,
+  type TranscriptionProvider,
+  type TranscriptionService,
+  TranscriptionServiceError,
+} from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import { createAzureOpenAiTranscriptionProvider } from "./providers/azure-openai";
+import { createCodexSubscriptionTranscriptionProvider } from "./providers/codex-subscription";
+import { createOpenAiTranscriptionProvider } from "./providers/openai";
+
+export function createTranscriptionService(input: {
+  settings: Settings;
+  db: Database;
+  fetch?: typeof fetch;
+  codexFetch?: typeof fetch;
+  probeCodex?: (context?: TranscriptionAvailabilityContext) => boolean | Promise<boolean>;
+}): TranscriptionService {
+  const providers: TranscriptionProvider[] = resolveVoiceInputProviderRegistry(input.settings).map(
+    (config) => {
+      switch (config.kind) {
+        case "openai":
+          return createOpenAiTranscriptionProvider({
+            ...config,
+            ...(input.fetch ? { fetch: input.fetch } : {}),
+          });
+        case "azure-openai":
+          return createAzureOpenAiTranscriptionProvider({
+            ...config,
+            ...(input.fetch ? { fetch: input.fetch } : {}),
+          });
+        case "codex-subscription":
+          return createCodexSubscriptionTranscriptionProvider({
+            settings: input.settings,
+            db: input.db,
+            ...(input.codexFetch ? { fetch: input.codexFetch } : {}),
+            ...(input.probeCodex ? { probe: input.probeCodex } : {}),
+          });
+        default:
+          throw new Error("Unsupported voice-input provider.");
+      }
+    },
+  );
+  const limits = {
+    maxDurationSeconds: input.settings.voiceInputMaxDurationSeconds,
+    maxSizeBytes: input.settings.voiceInputMaxSizeBytes,
+    acceptedMimeTypes: [...VOICE_INPUT_ACCEPTED_MIME_TYPES],
+  };
+  return {
+    limits: () => limits,
+    async available(context) {
+      return (await Promise.all(providers.map((provider) => provider.available(context)))).some(
+        Boolean,
+      );
+    },
+    async transcribe(request) {
+      const mimeType = normalizeMimeType(request.mimeType);
+      if (!isAcceptedMimeType(mimeType, limits.acceptedMimeTypes)) {
+        throw new TranscriptionServiceError({
+          code: "not_supported",
+          message: "Unsupported audio format.",
+        });
+      }
+      if (request.audio.byteLength > limits.maxSizeBytes) {
+        throw new TranscriptionServiceError({
+          code: "too_large",
+          message: "Audio is too large.",
+        });
+      }
+      if (
+        request.durationSeconds !== undefined &&
+        (!Number.isFinite(request.durationSeconds) ||
+          request.durationSeconds < 0 ||
+          request.durationSeconds > limits.maxDurationSeconds)
+      ) {
+        throw new TranscriptionServiceError({
+          code: "invalid_audio",
+          message: "Invalid audio duration.",
+        });
+      }
+      const provider = await firstAvailable(providers, {
+        workspaceId: request.workspaceId,
+      });
+      if (!provider) {
+        throw new TranscriptionServiceError({
+          code: "unavailable",
+          message: "Transcription is unavailable.",
+        });
+      }
+      const startedAt = performance.now();
+      const result = await provider.transcribe({
+        audio: request.audio,
+        mimeType,
+        filename: filenameForMimeType(mimeType),
+        workspaceId: request.workspaceId,
+        signal: request.signal,
+      });
+      return {
+        ...result,
+        providerId: provider.id,
+        audioSeconds: request.durationSeconds ?? 0,
+        latencyMs: Math.round(performance.now() - startedAt),
+      };
+    },
+  };
+}
+
+async function firstAvailable(
+  providers: readonly TranscriptionProvider[],
+  context: TranscriptionAvailabilityContext,
+) {
+  for (const provider of providers) {
+    if (await provider.available(context)) return provider;
+  }
+  return null;
+}

package/src/workspace-state-projection.ts

@@ -0,0 +1,244 @@
+import {
+  KnowledgeMemoryKind,
+  KnowledgeMemoryStatus,
+  WORKSPACE_STATE_BASE_NAME_MAX_CHARS,
+  WORKSPACE_STATE_MAX_ACTIVE_POLICY_HEADS,
+  WORKSPACE_STATE_MAX_BASES,
+  WORKSPACE_STATE_MAX_GAPS,
+  WORKSPACE_STATE_MAX_TOPICS,
+  WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT,
+  WORKSPACE_STATE_TOPIC_MAX_CHARS,
+  WorkspaceStateResponse,
+  type WorkspaceInstructionPolicyListResponse,
+  type WorkspaceStateGap,
+  type WorkspaceStateMemoryKindCounts,
+  type WorkspaceStateMemoryStatusCounts,
+  type WorkspaceStateResponse as WorkspaceStateResponseType,
+} from "@opengeni/contracts";
+import type { WorkspaceStateMemoryRecord } from "@opengeni/db";
+import type { DocumentInventory } from "@opengeni/documents";
+
+type KnowledgeProjectionInput = {
+  documents: DocumentInventory;
+  memories: WorkspaceStateMemoryRecord[];
+};
+
+export type WorkspaceStateProjectionInput = {
+  workspaceId: string;
+  generatedAt: string;
+  workspaceAgentInstructions: string | null;
+  policies: WorkspaceInstructionPolicyListResponse;
+  knowledge: KnowledgeProjectionInput | null;
+};
+
+function emptyMemoryStatusCounts(): WorkspaceStateMemoryStatusCounts {
+  return Object.fromEntries(
+    KnowledgeMemoryStatus.options.map((status) => [status, 0]),
+  ) as WorkspaceStateMemoryStatusCounts;
+}
+
+function emptyMemoryKindCounts(): WorkspaceStateMemoryKindCounts {
+  return Object.fromEntries(
+    KnowledgeMemoryKind.options.map((kind) => [kind, 0]),
+  ) as WorkspaceStateMemoryKindCounts;
+}
+
+function boundedLabel(value: string, maxChars: number, fallback: string): string {
+  const normalized = value.normalize("NFKC").trim().replace(/\s+/gu, " ");
+  return (normalized || fallback).slice(0, maxChars);
+}
+
+function newestTimestamp(values: Array<string | null>): string | null {
+  return values.reduce<string | null>((latest, value) => {
+    if (!value) return latest;
+    return latest === null || value > latest ? value : latest;
+  }, null);
+}
+
+function comparePolicyTargets(
+  left: WorkspaceInstructionPolicyListResponse["activeHeads"][number],
+  right: WorkspaceInstructionPolicyListResponse["activeHeads"][number],
+): number {
+  return `${left.kind}:${left.scope}:${left.roleKey ?? ""}`.localeCompare(
+    `${right.kind}:${right.scope}:${right.roleKey ?? ""}`,
+  );
+}
+
+function policyProjection(input: WorkspaceStateProjectionInput) {
+  const sortedHeads = [...input.policies.activeHeads].sort(comparePolicyTargets);
+  const activeHeads = sortedHeads.slice(0, WORKSPACE_STATE_MAX_ACTIVE_POLICY_HEADS).map((head) => ({
+    kind: head.kind,
+    scope: head.scope,
+    roleKey: head.roleKey,
+    revisionId: head.revisionId,
+    revision: head.revision,
+    contentHash: head.contentHash,
+    activationVersion: head.activationVersion,
+    activatedAt: head.activatedAt,
+  }));
+  const newestRevision = input.policies.revisions[0] ?? null;
+  return {
+    authority: "workspace_instruction_policy_heads" as const,
+    activeHeads,
+    activeHeadsTruncated: sortedHeads.length > activeHeads.length,
+    latestRevision: newestRevision
+      ? {
+          kind: newestRevision.kind,
+          scope: newestRevision.scope,
+          roleKey: newestRevision.roleKey,
+          revisionId: newestRevision.id,
+          revision: newestRevision.revision,
+          contentHash: newestRevision.contentHash,
+          provenanceSource: newestRevision.provenance.source,
+          state: input.policies.activeHeads.some((head) => head.revisionId === newestRevision.id)
+            ? ("active" as const)
+            : ("inactive" as const),
+          createdAt: newestRevision.createdAt,
+        }
+      : null,
+    legacyRuntime: {
+      source: input.workspaceAgentInstructions
+        ? ("workspace_override" as const)
+        : ("deployment_default" as const),
+      workspaceOverrideConfigured: Boolean(input.workspaceAgentInstructions),
+    },
+    runtimeComposition: { status: "not_implemented" as const },
+  };
+}
+
+function availableKnowledgeProjection(knowledge: KnowledgeProjectionInput) {
+  const inventory = knowledge.documents;
+  const selectedBases = inventory.bases.slice(0, WORKSPACE_STATE_MAX_BASES);
+  const aggregateStatuses = { ...inventory.statusCounts };
+  const aggregateSources = { ...inventory.sourceKindCounts };
+  const topicCounts = new Map<string, number>();
+  const projectedBases = selectedBases.map((base) => {
+    return {
+      id: base.id,
+      name: boundedLabel(base.name, WORKSPACE_STATE_BASE_NAME_MAX_CHARS, "Untitled base"),
+      visibleDocumentCount: base.visibleDocumentCount,
+      statusCounts: base.statusCounts,
+      latestUpdatedAt: base.latestUpdatedAt,
+    };
+  });
+
+  for (const topic of inventory.topics) {
+    const name = boundedLabel(topic.name, WORKSPACE_STATE_TOPIC_MAX_CHARS, "Unlabeled topic");
+    topicCounts.set(name, (topicCounts.get(name) ?? 0) + topic.documentCount);
+  }
+
+  const sortedTopics = [...topicCounts.entries()]
+    .sort(
+      ([leftName, leftCount], [rightName, rightCount]) =>
+        rightCount - leftCount || leftName.localeCompare(rightName),
+    )
+    .map(([name, documentCount]) => ({ name, documentCount }));
+  const topics = sortedTopics.slice(0, WORKSPACE_STATE_MAX_TOPICS);
+  const memories = knowledge.memories.slice(0, WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT);
+  const memoryStatuses = emptyMemoryStatusCounts();
+  const memoryKinds = emptyMemoryKindCounts();
+  for (const memory of memories) {
+    memoryStatuses[memory.status] += 1;
+    memoryKinds[memory.kind] += 1;
+  }
+
+  const inspectedVisibleDocumentCount = inventory.visibleDocumentCount;
+  const basesTruncated = inventory.baseCount > projectedBases.length;
+  const memoryLimitReached = memories.length === WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT;
+  const inventoryPartial = basesTruncated || inventory.topicsTruncated || memoryLimitReached;
+  const gaps: WorkspaceStateGap[] = [];
+  const addGap = (gap: WorkspaceStateGap): void => {
+    if (gaps.length < WORKSPACE_STATE_MAX_GAPS) gaps.push(gap);
+  };
+  if (inventory.baseCount === 0) {
+    addGap({ code: "no_document_bases", severity: "info", relatedCount: 0 });
+  } else if (inspectedVisibleDocumentCount === 0) {
+    addGap({ code: "no_visible_documents", severity: "info", relatedCount: 0 });
+  }
+  if (aggregateStatuses.failed > 0) {
+    addGap({
+      code: "failed_documents",
+      severity: "warning",
+      relatedCount: aggregateStatuses.failed,
+    });
+  }
+  const processingCount = aggregateStatuses.queued + aggregateStatuses.indexing;
+  if (processingCount > 0) {
+    addGap({
+      code: "processing_documents",
+      severity: "info",
+      relatedCount: processingCount,
+    });
+  }
+  if (aggregateStatuses.ready > 0 && sortedTopics.length === 0) {
+    addGap({
+      code: "missing_topic_coverage",
+      severity: "info",
+      relatedCount: aggregateStatuses.ready,
+    });
+  }
+  if (memories.length === 0) {
+    addGap({ code: "no_memory_records", severity: "info", relatedCount: 0 });
+  }
+  if (memoryStatuses.proposed > 0) {
+    addGap({
+      code: "pending_memory_review",
+      severity: "info",
+      relatedCount: memoryStatuses.proposed,
+    });
+  }
+  if (inventoryPartial) {
+    addGap({ code: "partial_inventory", severity: "info", relatedCount: null });
+  }
+
+  return {
+    availability: "available" as const,
+    coverage: inventoryPartial ? ("partial" as const) : ("complete" as const),
+    baseCount: inventory.baseCount,
+    bases: projectedBases,
+    basesTruncated,
+    inspectedVisibleDocumentCount,
+    documentStatusCounts: aggregateStatuses,
+    sourceKindCounts: aggregateSources,
+    topics,
+    topicsTruncated: inventory.topicsTruncated || sortedTopics.length > topics.length,
+    latestDocumentUpdatedAt: inventory.latestUpdatedAt,
+    memorySample: {
+      recordCount: memories.length,
+      sampleLimit: WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT,
+      limitReached: memoryLimitReached,
+      statusCounts: memoryStatuses,
+      kindCounts: memoryKinds,
+      preferenceAuthority: {
+        kindCountSource: "knowledge_memories_legacy_observations" as const,
+        activeAuthority: "structured_preference_registry" as const,
+      },
+      latestUpdatedAt: newestTimestamp(memories.map((memory) => memory.updatedAt)),
+    },
+    gaps,
+  };
+}
+
+export function projectWorkspaceState(
+  input: WorkspaceStateProjectionInput,
+): WorkspaceStateResponseType {
+  return WorkspaceStateResponse.parse({
+    workspaceId: input.workspaceId,
+    generatedAt: input.generatedAt,
+    truth: {
+      current: { source: "read_time_projection", capturedAt: input.generatedAt },
+      policySnapshot: {
+        status: "not_captured",
+        reason: "workspace_instruction_policy_snapshot_not_implemented",
+      },
+    },
+    policy: policyProjection(input),
+    knowledge: input.knowledge
+      ? availableKnowledgeProjection(input.knowledge)
+      : {
+          availability: "unavailable",
+          reason: "missing_permission",
+          requiredPermission: "documents:search",
+        },
+  });
+}