@opengeni/core 0.12.7 → 0.14.3

package/src/index.ts

@@ -35,6 +35,7 @@ export * from "./workflow-wake-contract";
 // structural TYPES live here.
 export * from "./sandbox-types";
 export * from "./managed-auth-type";
+export * from "./transcription";
 
 // Sandbox fleet/routing service — the closure of `domain/sessions.ts`
 // (`swapActiveSandbox` + `FleetContext`). apps/api re-imports these for its MCP
@@ -60,6 +61,7 @@ export * from "./domain/resources";
 export * from "./domain/session-tool-policy";
 export * from "./domain/scheduled-tasks";
 export * from "./domain/sessions";
+export * from "./domain/insights";
 export * from "./domain/slack-bot";
 export * from "./domain/workspace-members";
 export * from "./application/new-session-drafts";

package/src/sandbox/fleet.ts

@@ -33,6 +33,7 @@ import {
   type BackendUnresolvableCode,
   type ControlRpc,
   type NatsRequestConnection,
+  type SelfhostedRelayConfig,
 } from "@opengeni/runtime/sandbox";
 import { HTTPException } from "hono/http-exception";
 import { relayConfigFromSettings } from "./routing";
@@ -512,11 +513,94 @@ export type RunOnResult = {
   stdout?: string;
   stderr?: string;
   exitCode?: number | null;
+  /** Exec only: whether the machine killed the child at its process deadline. */
+  timedOut?: boolean;
+  /** Exec only: the effective clamped process deadline enforced by the machine. */
+  deadlineMs?: number;
   content?: string;
   bytesWritten?: number;
   reason?: string;
 };
 
+export type RunOnSelfhostedMachine = {
+  workspaceId: string;
+  agentId: string;
+  controlRpc: ControlRpc;
+  relay: SelfhostedRelayConfig;
+  /** Short request/reply deadline for read/write and other control operations. */
+  controlTimeoutMs: number;
+  /** Longer agent-side process deadline for exec. */
+  execTimeoutMs: number;
+};
+
+/**
+ * Execute the one-off machine operation once the workspace/enrollment lookup has
+ * succeeded. Kept separate from {@link runOnSandbox} so the command/deadline
+ * contract is deterministic against an in-memory ControlRpc without weakening
+ * the production ownership lookup or requiring a real machine.
+ */
+export async function executeRunOnSelfhostedMachine(
+  machine: RunOnSelfhostedMachine,
+  target: string,
+  op: RunOnOp,
+): Promise<RunOnResult> {
+  const session = new SelfhostedSession({
+    workspaceId: machine.workspaceId,
+    agentId: machine.agentId,
+    controlRpc: machine.controlRpc,
+    relay: machine.relay,
+    timeoutMs: machine.controlTimeoutMs,
+    execTimeoutMs: machine.execTimeoutMs,
+  });
+
+  try {
+    if (op.kind === "exec") {
+      const deadlineMs = session.effectiveExecDeadlineMs;
+      const res = await session.exec({
+        cmd: op.cmd,
+        ...(op.workdir ? { workdir: op.workdir } : {}),
+      });
+      const timedOut = res.timedOut === true;
+      const hasTerminalExit = res.exitCode !== null;
+      return {
+        target,
+        kind: "exec",
+        // `ok` means the one-off operation reached a terminal response. Preserve
+        // the established non-zero-exit behavior, but never claim success when
+        // the machine killed the child or returned no terminal exit proof.
+        ok: !timedOut && hasTerminalExit,
+        stdout: res.stdout,
+        stderr: res.stderr,
+        exitCode: res.exitCode,
+        timedOut,
+        deadlineMs,
+        ...(timedOut
+          ? { reason: `command exceeded the ${deadlineMs} ms execution deadline` }
+          : !hasTerminalExit
+            ? { reason: "machine returned no terminal exit code" }
+            : {}),
+      };
+    }
+    if (op.kind === "read") {
+      const bytes = await session.readFile({ path: op.path });
+      return { target, kind: "read", ok: true, content: new TextDecoder().decode(bytes) };
+    }
+    const bytesWritten = await session.writeFile({ path: op.path, content: op.content });
+    return { target, kind: "write", ok: true, bytesWritten };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      target,
+      kind: op.kind,
+      ok: false,
+      reason,
+      // A transport failure is not evidence that the process itself timed out,
+      // so leave `timedOut` absent while still reporting the enforced deadline.
+      ...(op.kind === "exec" ? { deadlineMs: session.effectiveExecDeadlineMs } : {}),
+    };
+  }
+}
+
 /**
  * Run a ONE-OFF op against a SPECIFIC target WITHOUT changing the active pointer
  * (the design `run_on`). Only selfhosted targets are routable as a one-off here
@@ -554,39 +638,18 @@ export async function runOnSandbox(
     return { target, kind: op.kind, ok: false, reason: `sandbox ${target} is not enrolled/active` };
   }
 
-  const session = new SelfhostedSession({
-    workspaceId: ctx.workspaceId,
-    agentId: sandbox.enrollmentId,
-    controlRpc: controlRpc(services.bus),
-    relay: relayConfigFromSettings(services.settings),
-  });
-
-  try {
-    if (op.kind === "exec") {
-      const res = await session.exec({
-        cmd: op.cmd,
-        ...(op.workdir ? { workdir: op.workdir } : {}),
-      });
-      return {
-        target,
-        kind: "exec",
-        ok: true,
-        stdout: res.stdout,
-        stderr: res.stderr,
-        exitCode: res.exitCode,
-      };
-    }
-    if (op.kind === "read") {
-      const bytes = await session.readFile({ path: op.path });
-      return { target, kind: "read", ok: true, content: new TextDecoder().decode(bytes) };
-    }
-    // write
-    const bytesWritten = await session.writeFile({ path: op.path, content: op.content });
-    return { target, kind: "write", ok: true, bytesWritten };
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    return { target, kind: op.kind, ok: false, reason };
-  }
+  return executeRunOnSelfhostedMachine(
+    {
+      workspaceId: ctx.workspaceId,
+      agentId: sandbox.enrollmentId,
+      controlRpc: controlRpc(services.bus),
+      relay: relayConfigFromSettings(services.settings),
+      controlTimeoutMs: services.settings.sandboxSelfhostedControlTimeoutMs,
+      execTimeoutMs: services.settings.sandboxSelfhostedExecTimeoutMs,
+    },
+    target,
+    op,
+  );
 }
 
 export type ProvisionResult =

package/src/sandbox/routing.ts

@@ -11,7 +11,7 @@
 // The DB-coupled glue (readActiveSandbox / getSandbox / the selfhosted ControlRpc
 // over the events bus) lives here, not in the leaf (which stays db-free).
 
-import type { Settings } from "@opengeni/config";
+import { sandboxArchiveCaptureTimeoutMs, type Settings } from "@opengeni/config";
 import {
   advanceWorkspaceGenerationForDirectRequest,
   advanceWorkspaceGenerationForRetainedProcess,
@@ -33,6 +33,7 @@ import {
   makeActiveBackendResolver,
   NatsControlRpc,
   RoutingSandboxSession,
+  resolveModalCheckpointProviderBindingForSession,
   type ControlRpc,
   type EstablishedSandboxSession,
   type NatsRequestConnection,
@@ -44,6 +45,13 @@ import {
   type SelfhostedRelayConfig,
 } from "@opengeni/runtime/sandbox";
 
+type PersistableMutationAdmission = {
+  admission: SandboxWorkspaceMutationAdmission;
+  providerBinding: Awaited<
+    ReturnType<typeof resolveModalCheckpointProviderBindingForSession>
+  > | null;
+};
+
 export type ChannelARoutingServices = {
   db: Database;
   settings: Settings;
@@ -151,7 +159,7 @@ export function wrapChannelABoxWithRouting(
       }: {
         op: string;
         backend: ResolvedActiveBackend;
-      }): Promise<SandboxWorkspaceMutationAdmission | null> => {
+      }): Promise<PersistableMutationAdmission | null> => {
         // Connected Machines and other non-persistable targets intentionally do
         // not dirty or advance the cloud-home archive generation.
         if (
@@ -164,7 +172,11 @@ export function wrapChannelABoxWithRouting(
         if (backend.activeEpoch === undefined) {
           throw new Error("API-direct workspace mutation resolved without an active route epoch");
         }
-        return await advanceWorkspaceGenerationForDirectRequest(db, {
+        const providerBinding =
+          homeLease.backend === "modal"
+            ? await resolveModalCheckpointProviderBindingForSession(settings, backend.session)
+            : null;
+        const admission = await advanceWorkspaceGenerationForDirectRequest(db, {
           accountId: ids.accountId,
           workspaceId: ids.workspaceId,
           sessionId: ids.sessionId,
@@ -176,7 +188,9 @@ export function wrapChannelABoxWithRouting(
           routeTargetId: backend.sandboxId,
           routeEpoch: backend.activeEpoch,
           operation: op,
+          captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
         });
+        return { admission, providerBinding };
       }
     : undefined;
   const afterMutation = homeLease
@@ -198,16 +212,22 @@ export function wrapChannelABoxWithRouting(
         if (
           !admission ||
           typeof admission !== "object" ||
-          typeof (admission as Partial<SandboxWorkspaceMutationAdmission>).id !== "string" ||
-          typeof (admission as Partial<SandboxWorkspaceMutationAdmission>).workspaceGeneration !==
-            "number" ||
           backend.leaseEpoch === undefined ||
           backend.providerInstanceId === undefined ||
           backend.activeEpoch === undefined
         ) {
           throw new Error("API-direct workspace mutation settlement lacked its exact admission");
         }
-        const exactAdmission = admission as SandboxWorkspaceMutationAdmission;
+        const boundAdmission = admission as Partial<PersistableMutationAdmission>;
+        const exactAdmission = boundAdmission.admission;
+        if (
+          !exactAdmission ||
+          typeof exactAdmission.id !== "string" ||
+          typeof exactAdmission.workspaceGeneration !== "number" ||
+          !("providerBinding" in boundAdmission)
+        ) {
+          throw new Error("API-direct workspace mutation settlement lacked its bound admission");
+        }
         if (outcome === "resolved" && retainedProcess) {
           await retainWorkspaceMutationProcess(db, {
             accountId: ids.accountId,
@@ -218,6 +238,7 @@ export function wrapChannelABoxWithRouting(
             admissionId: exactAdmission.id,
             admittedWorkspaceGeneration: exactAdmission.workspaceGeneration,
             operation: op,
+            providerBinding: boundAdmission.providerBinding ?? null,
             owner: {
               kind: "direct",
               requestId: ids.directRequest.requestId,
@@ -263,6 +284,7 @@ export function wrapChannelABoxWithRouting(
           sessionId: ids.sessionId,
           processId: process.id,
           operation: op,
+          captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
         })
     : undefined;
   const afterProcessMutation = homeLease

package/src/transcription.ts

@@ -0,0 +1,142 @@
+import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
+
+export type TranscriptionLimits = {
+  maxDurationSeconds: number;
+  maxSizeBytes: number;
+  acceptedMimeTypes: readonly string[];
+};
+
+export type TranscriptionRequest = {
+  workspaceId: string;
+  accountId: string;
+  audio: Uint8Array;
+  mimeType: string;
+  /** Optional client-reported duration; enforced as a soft ceiling before upstream. */
+  durationSeconds?: number | undefined;
+  signal?: AbortSignal | undefined;
+  requestId: string;
+};
+
+export type TranscriptionResult = TranscribeAudioResponse & {
+  /** Server-private provider id for operational metrics only. Never returned to clients. */
+  providerId: string;
+  audioSeconds: number;
+  latencyMs: number;
+};
+
+export class TranscriptionServiceError extends Error {
+  readonly code: VoiceInputErrorCode;
+  readonly status: number;
+  readonly retryable: boolean;
+
+  constructor(input: {
+    code: VoiceInputErrorCode;
+    message: string;
+    status?: number;
+    retryable?: boolean;
+  }) {
+    super(input.message);
+    this.name = "TranscriptionServiceError";
+    this.code = input.code;
+    this.status = input.status ?? statusForVoiceInputError(input.code);
+    this.retryable = input.retryable ?? false;
+  }
+}
+
+export function statusForVoiceInputError(code: VoiceInputErrorCode): number {
+  switch (code) {
+    case "permission_denied":
+      return 403;
+    case "policy_blocked":
+      return 403;
+    case "not_supported":
+      return 415;
+    case "unavailable":
+      return 503;
+    case "too_large":
+      return 413;
+    case "invalid_audio":
+      return 400;
+    case "timeout":
+      return 504;
+    case "cancelled":
+      return 499;
+    case "network":
+    case "provider":
+      return 502;
+    case "unknown":
+    default:
+      return 500;
+  }
+}
+
+/** Optional workspace scope for readiness checks during provider selection. */
+export type TranscriptionAvailabilityContext = {
+  workspaceId?: string | undefined;
+};
+
+/**
+ * Extensible transcription provider port. Implementations own credentials and
+ * upstream request shape. Selection happens before audio is sent; providers must
+ * not fall back to another vendor after an upstream request may have started.
+ */
+export type TranscriptionProvider = {
+  readonly id: string;
+  readonly experimental?: boolean | undefined;
+  /**
+   * Deployment readiness when called without a workspace. When `workspaceId` is
+   * provided, providers may require a workspace-attached credential (e.g. Codex).
+   */
+  available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  transcribe(input: {
+    audio: Uint8Array;
+    mimeType: string;
+    filename: string;
+    workspaceId: string;
+    signal?: AbortSignal | undefined;
+  }): Promise<{ text: string; languages: string[] }>;
+};
+
+export type TranscriptionService = {
+  limits(): TranscriptionLimits;
+  /** True when at least one ready provider can serve requests. */
+  available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+};
+
+export function normalizeMimeType(mimeType: string): string {
+  return mimeType.trim().toLowerCase();
+}
+
+export function isAcceptedMimeType(mimeType: string, accepted: readonly string[]): boolean {
+  const normalized = normalizeMimeType(mimeType);
+  if (accepted.some((candidate) => normalizeMimeType(candidate) === normalized)) {
+    return true;
+  }
+  // Allow bare type matches against codec-qualified allowlist entries.
+  const bare = normalized.split(";")[0]?.trim() ?? normalized;
+  return accepted.some((candidate) => {
+    const allowed = normalizeMimeType(candidate);
+    return allowed === bare || allowed.split(";")[0]?.trim() === bare;
+  });
+}
+
+export function filenameForMimeType(mimeType: string): string {
+  const bare = normalizeMimeType(mimeType).split(";")[0] ?? "audio/webm";
+  switch (bare) {
+    case "audio/mp4":
+    case "audio/m4a":
+      return "audio.mp4";
+    case "audio/ogg":
+      return "audio.ogg";
+    case "audio/mpeg":
+    case "audio/mp3":
+      return "audio.mp3";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "audio.wav";
+    case "audio/webm":
+    default:
+      return "audio.webm";
+  }
+}