@opengeni/core 0.20.16 → 0.21.2

package/dist/transcription.d.ts

@@ -1,4 +1,13 @@
 import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
+/**
+ * Server-owned upstream budget for one provider attempt. Resumable recording
+ * claims remain fenced for longer than this budget before another worker may
+ * reclaim them. Provider adapters must honor the supplied AbortSignal and must
+ * not return while their upstream request is still live; OpenGeni does not
+ * claim remote-side idempotency or cancellation for vendors that cannot meet
+ * that adapter contract.
+ */
+export declare const TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS: number;
 export type TranscriptionLimits = {
     maxDurationSeconds: number;
     maxSizeBytes: number;
@@ -13,6 +22,10 @@ export type TranscriptionRequest = {
     durationSeconds?: number | undefined;
     signal?: AbortSignal | undefined;
     requestId: string;
+    /** Absolute server-owned provider deadline persisted for resumable attempts. */
+    providerDeadlineAt?: Date | undefined;
+    /** Exact provider selected before a resumable segment is first sent upstream. */
+    providerId?: string | undefined;
 };
 export type TranscriptionResult = TranscribeAudioResponse & {
     /** Server-private provider id for operational metrics only. Never returned to clients. */
@@ -43,6 +56,8 @@ export type TranscriptionAvailabilityContext = {
  */
 export type TranscriptionProvider = {
     readonly id: string;
+    /** The adapter guarantees that its upstream transport honors AbortSignal. */
+    readonly supportsServerDeadline: true;
     readonly experimental?: boolean | undefined;
     /**
      * Deployment readiness when called without a workspace. When `workspaceId` is
@@ -54,6 +69,7 @@ export type TranscriptionProvider = {
         mimeType: string;
         filename: string;
         workspaceId: string;
+        requestId: string;
         signal?: AbortSignal | undefined;
     }): Promise<{
         text: string;
@@ -64,8 +80,27 @@ export type TranscriptionService = {
     limits(): TranscriptionLimits;
     /** True when at least one ready provider can serve requests. */
     available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+    /** Select one provider before a durable segment attempt; retries pin this id. */
+    selectProvider?(context: TranscriptionAvailabilityContext): string | null | Promise<string | null>;
     transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
 };
+export type PreparedTranscriptionSegment = {
+    segmentNumber: number;
+    startMilliseconds: number;
+    durationMilliseconds: number;
+    mimeType: "audio/wav";
+    bytes: Uint8Array;
+};
+export type TranscriptionSegmenter = {
+    available(): boolean | Promise<boolean>;
+    segment(input: {
+        sourceMimeType: string;
+        totalDurationMilliseconds: number;
+        providerSegmentSeconds: number;
+        chunks: AsyncIterable<Uint8Array>;
+        signal?: AbortSignal | undefined;
+    }): AsyncIterable<PreparedTranscriptionSegment>;
+};
 export declare function normalizeMimeType(mimeType: string): string;
 export declare function isAcceptedMimeType(mimeType: string, accepted: readonly string[]): boolean;
 export declare function filenameForMimeType(mimeType: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.20.16",
+  "version": "0.21.2",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -35,14 +35,14 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/codex": "^0.2.11",
-    "@opengeni/config": "^0.10.14",
-    "@opengeni/contracts": "^0.38.3",
-    "@opengeni/db": "^0.27.11",
-    "@opengeni/documents": "^0.5.7",
-    "@opengeni/events": "^0.3.77",
-    "@opengeni/observability": "^0.4.16",
-    "@opengeni/runtime": "^0.18.15",
-    "@opengeni/storage": "^0.2.67",
+    "@opengeni/config": "^0.11.0",
+    "@opengeni/contracts": "^0.39.0",
+    "@opengeni/db": "^0.28.1",
+    "@opengeni/documents": "^0.5.10",
+    "@opengeni/events": "^0.3.80",
+    "@opengeni/observability": "^0.5.0",
+    "@opengeni/runtime": "^0.18.17",
+    "@opengeni/storage": "^0.2.68",
     "hono": "^4.12.18"
   },
   "engines": {

package/src/dependencies.ts

@@ -15,7 +15,7 @@ import type { Observability } from "@opengeni/observability";
 import type { createObjectStorage } from "@opengeni/storage";
 import type { ManagedAuth } from "./managed-auth-type";
 import type { ApiSandboxClient, ResumeBoxByIdInput, ResumedSandboxSession } from "./sandbox-types";
-import type { TranscriptionService } from "./transcription";
+import type { TranscriptionSegmenter, TranscriptionService } from "./transcription";
 
 export type SessionWorkflowClient = {
   signalUserMessage: (input: {
@@ -123,6 +123,8 @@ export type AppDependencies = {
   oauthCallbackDeadlineMs?: number;
   /** Optional host-owned voice-input transcription service. */
   transcription?: TranscriptionService | null;
+  /** Optional host-owned long-form audio normalization/segmentation service. */
+  transcriptionSegmenter?: TranscriptionSegmenter | null;
   // The API process's OWN agent-loop-free sandbox client (constructed from
   // settings via @opengeni/runtime/sandbox). Undefined when sandboxBackend=none.
   // This is the foundation of the API-direct control plane: the API resumes

package/src/transcription.ts

@@ -1,5 +1,15 @@
 import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
 
+/**
+ * Server-owned upstream budget for one provider attempt. Resumable recording
+ * claims remain fenced for longer than this budget before another worker may
+ * reclaim them. Provider adapters must honor the supplied AbortSignal and must
+ * not return while their upstream request is still live; OpenGeni does not
+ * claim remote-side idempotency or cancellation for vendors that cannot meet
+ * that adapter contract.
+ */
+export const TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS = 10 * 60 * 1_000;
+
 export type TranscriptionLimits = {
   maxDurationSeconds: number;
   maxSizeBytes: number;
@@ -15,6 +25,10 @@ export type TranscriptionRequest = {
   durationSeconds?: number | undefined;
   signal?: AbortSignal | undefined;
   requestId: string;
+  /** Absolute server-owned provider deadline persisted for resumable attempts. */
+  providerDeadlineAt?: Date | undefined;
+  /** Exact provider selected before a resumable segment is first sent upstream. */
+  providerId?: string | undefined;
 };
 
 export type TranscriptionResult = TranscribeAudioResponse & {
@@ -82,6 +96,8 @@ export type TranscriptionAvailabilityContext = {
  */
 export type TranscriptionProvider = {
   readonly id: string;
+  /** The adapter guarantees that its upstream transport honors AbortSignal. */
+  readonly supportsServerDeadline: true;
   readonly experimental?: boolean | undefined;
   /**
    * Deployment readiness when called without a workspace. When `workspaceId` is
@@ -93,6 +109,7 @@ export type TranscriptionProvider = {
     mimeType: string;
     filename: string;
     workspaceId: string;
+    requestId: string;
     signal?: AbortSignal | undefined;
   }): Promise<{ text: string; languages: string[] }>;
 };
@@ -101,9 +118,32 @@ export type TranscriptionService = {
   limits(): TranscriptionLimits;
   /** True when at least one ready provider can serve requests. */
   available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  /** Select one provider before a durable segment attempt; retries pin this id. */
+  selectProvider?(
+    context: TranscriptionAvailabilityContext,
+  ): string | null | Promise<string | null>;
   transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
 };
 
+export type PreparedTranscriptionSegment = {
+  segmentNumber: number;
+  startMilliseconds: number;
+  durationMilliseconds: number;
+  mimeType: "audio/wav";
+  bytes: Uint8Array;
+};
+
+export type TranscriptionSegmenter = {
+  available(): boolean | Promise<boolean>;
+  segment(input: {
+    sourceMimeType: string;
+    totalDurationMilliseconds: number;
+    providerSegmentSeconds: number;
+    chunks: AsyncIterable<Uint8Array>;
+    signal?: AbortSignal | undefined;
+  }): AsyncIterable<PreparedTranscriptionSegment>;
+};
+
 export function normalizeMimeType(mimeType: string): string {
   return mimeType.trim().toLowerCase();
 }