@opengeni/api-router 0.12.12 → 0.14.4

package/src/routes/insights.ts

@@ -0,0 +1,30 @@
+import { InsightsRange, WorkspaceInsightsResponse } from "@opengeni/contracts";
+import { getWorkspaceInsights, requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+export function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get("/v1/workspaces/:workspaceId/insights", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+
+    const rangeRaw = c.req.query("range") ?? "week";
+    const rangeParsed = InsightsRange.safeParse(rangeRaw);
+    if (!rangeParsed.success) {
+      throw new HTTPException(400, {
+        message: "range must be one of today|week|month|ytd",
+      });
+    }
+    const provider = c.req.query("provider");
+    const model = c.req.query("model");
+
+    const response = await getWorkspaceInsights(deps.db, deps.settings, {
+      workspaceId,
+      range: rangeParsed.data,
+      provider: provider && provider !== "all" ? provider : null,
+      model: model && model !== "all" ? model : null,
+    });
+    c.header("cache-control", "private, no-store");
+    return c.json(WorkspaceInsightsResponse.parse(response));
+  });
+}

package/src/routes/preference-registry.ts

@@ -0,0 +1,482 @@
+import {
+  ActivatePreferenceRegistryRevisionRequest,
+  ChangePreferenceRegistryScopeRequest,
+  CorrectPreferenceRegistryRequest,
+  CreatePreferenceRegistryProposalRequest,
+  DeactivatePreferenceRegistryRequest,
+  PreferenceRegistryConflictResponse,
+  PreferenceRegistryDetailResponse,
+  PreferenceRegistryFullContentRequest,
+  PreferenceRegistryFullContent,
+  PreferenceRegistryListQuery,
+  PreferenceRegistryListResponse,
+  PreferenceRegistryMutationResponse,
+  PreferenceRegistryRecord,
+  PreferenceRegistrySnapshot,
+  RejectPreferenceRegistryProposalRequest,
+  SupersedePreferenceRegistryRequest,
+  type AccessGrant,
+  type PreferenceRegistryScope,
+} from "@opengeni/contracts";
+import {
+  hasPermission,
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  activatePreferenceRegistryRevision,
+  changePreferenceRegistryScope,
+  correctPreferenceRegistry,
+  createPreferenceRegistryProposal,
+  deactivatePreferenceRegistry,
+  getOrCreatePreferenceRegistrySnapshot,
+  getPreferenceRegistryDetail,
+  getPreferenceRegistryDetailForAttempt,
+  getPreferenceRegistryFullContent,
+  listPreferenceRegistry,
+  listPreferenceRegistryForAttempt,
+  PreferenceRegistryConflictError,
+  PreferenceRegistryInitiatorError,
+  PreferenceRegistryInvalidOperationError,
+  PreferenceRegistryNotFoundError,
+  PreferenceRegistryStableKeyConflictError,
+  rejectPreferenceRegistryProposal,
+  supersedePreferenceRegistry,
+  type PreferenceRegistryAttemptClaims,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const Id = z.string().uuid();
+
+async function parseBody<S extends z.ZodType>(context: Context, schema: S): Promise<z.infer<S>> {
+  const parsed = schema.safeParse(await context.req.json().catch(() => null));
+  if (!parsed.success)
+    throw new HTTPException(422, { message: "Invalid preference registry request" });
+  return parsed.data;
+}
+
+function exactAttemptClaims(grant: AccessGrant) {
+  const metadata = grant.metadata ?? {};
+  const values = {
+    sessionId: metadata["sessionId"],
+    turnId: metadata["turnId"],
+    attemptId: metadata["attemptId"],
+    executionGeneration: metadata["executionGeneration"],
+  };
+  const present = Object.values(values).filter((value) => value !== undefined).length;
+  if (present === 0) return null;
+  if (
+    typeof values.sessionId !== "string" ||
+    typeof values.turnId !== "string" ||
+    typeof values.attemptId !== "string" ||
+    typeof values.executionGeneration !== "number" ||
+    !Number.isSafeInteger(values.executionGeneration) ||
+    values.executionGeneration < 1 ||
+    values.executionGeneration > 2_147_483_647
+  ) {
+    throw new HTTPException(403, { message: "Incomplete signed preference attempt authority" });
+  }
+  return values as {
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+  };
+}
+
+function requiredAttemptClaims(grant: AccessGrant): PreferenceRegistryAttemptClaims {
+  const claims = exactAttemptClaims(grant);
+  if (!claims) {
+    throw new HTTPException(403, {
+      message: "Preference snapshot retrieval requires a signed session, turn, and attempt",
+    });
+  }
+  return {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    ...claims,
+  };
+}
+
+function requireHumanMutation(access: AccessGrantAuthorization): void {
+  const { grant } = access;
+  if (
+    !access.contextIntegrity ||
+    access.authenticatedSubjectId !== grant.subjectId ||
+    grant.principalKind !== "human_session" ||
+    exactAttemptClaims(grant) !== null ||
+    grant.serviceInitiator ||
+    grant.serviceInitiatorContext ||
+    grant.subjectId.startsWith("api_key:")
+  ) {
+    throw new HTTPException(403, {
+      message: "Preference activation and scope mutation require a direct human-authorized request",
+    });
+  }
+}
+
+export function authorizePreferenceRegistryScopeMutation(
+  access: AccessGrantAuthorization,
+  scope: PreferenceRegistryScope,
+): void {
+  const { grant } = access;
+  requireHumanMutation(access);
+  if (scope === "organization") {
+    // Deliberately do not use hasPermission: workspace:admin must not expand to
+    // account:admin for an organization-wide preference. Account authority is
+    // carried separately from the authenticated context and must match this
+    // exact workspace grant's account and subject.
+    if (!access.accountGrant?.permissions.includes("account:admin")) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    return;
+  }
+  if (scope === "workspace" && !hasPermission(grant.permissions, "workspace:admin")) {
+    throw new HTTPException(403, { message: "missing permission: workspace:admin" });
+  }
+  // User scope is always self-only: the route derives the target from the
+  // authenticated actor and never accepts a subject selector.
+}
+
+function preferenceError(context: Context, error: unknown): Response {
+  if (error instanceof PreferenceRegistryConflictError) {
+    return context.json(
+      PreferenceRegistryConflictResponse.parse({
+        code: error.code,
+        message: error.message,
+        currentRevisionId: error.currentRevisionId,
+        scopeVersion: error.scopeVersion,
+      }),
+      409,
+    );
+  }
+  if (error instanceof PreferenceRegistryNotFoundError) {
+    return context.json({ code: "PREFERENCE_REGISTRY_NOT_FOUND", message: error.message }, 404);
+  }
+  if (error instanceof PreferenceRegistryStableKeyConflictError) {
+    return context.json({ code: error.code, message: error.message }, 409);
+  }
+  if (error instanceof PreferenceRegistryInvalidOperationError) {
+    return context.json(
+      { code: "INVALID_PREFERENCE_REGISTRY_OPERATION", message: error.message },
+      422,
+    );
+  }
+  if (error instanceof PreferenceRegistryInitiatorError) {
+    return context.json(
+      { code: "PREFERENCE_REGISTRY_ATTEMPT_REJECTED", message: error.message },
+      403,
+    );
+  }
+  throw error;
+}
+
+function preferenceId(context: Context): string {
+  const parsed = Id.safeParse(context.req.param("preferenceId"));
+  if (!parsed.success) throw new HTTPException(422, { message: "Invalid preference id" });
+  return parsed.data;
+}
+
+export function registerPreferenceRegistryRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/preferences";
+
+  app.get(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const query = PreferenceRegistryListQuery.safeParse({
+      scope: context.req.query("scope"),
+      status: context.req.query("status"),
+      limit: context.req.query("limit"),
+    });
+    if (!query.success)
+      throw new HTTPException(422, { message: "Invalid preference registry query" });
+    try {
+      const claims = exactAttemptClaims(grant);
+      const result = claims
+        ? await listPreferenceRegistryForAttempt(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            ...claims,
+            ...query.data,
+          })
+        : await listPreferenceRegistry(deps.db, {
+            workspaceId,
+            subjectId: grant.subjectId,
+            ...query.data,
+          });
+      return context.json(PreferenceRegistryListResponse.parse(result));
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/proposals`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const request = await parseBody(context, CreatePreferenceRegistryProposalRequest);
+    authorizePreferenceRegistryScopeMutation(access, request.scope);
+    try {
+      return context.json(
+        PreferenceRegistryRecord.parse(
+          await createPreferenceRegistryProposal(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+          }),
+        ),
+        201,
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.get(`${base}/summary`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    try {
+      return context.json(
+        PreferenceRegistrySnapshot.parse(
+          await getOrCreatePreferenceRegistrySnapshot(deps.db, requiredAttemptClaims(grant)),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/full-content`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const request = await parseBody(context, PreferenceRegistryFullContentRequest);
+    try {
+      return context.json(
+        PreferenceRegistryFullContent.parse(
+          await getPreferenceRegistryFullContent(
+            deps.db,
+            requiredAttemptClaims(grant),
+            request.retrievalHandle,
+          ),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.get(`${base}/:preferenceId`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    try {
+      const claims = exactAttemptClaims(grant);
+      const id = preferenceId(context);
+      const detail = claims
+        ? await getPreferenceRegistryDetailForAttempt(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            ...claims,
+            preferenceId: id,
+          })
+        : await getPreferenceRegistryDetail(deps.db, {
+            workspaceId,
+            subjectId: grant.subjectId,
+            preferenceId: id,
+          });
+      return context.json(PreferenceRegistryDetailResponse.parse(detail));
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/activate`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, ActivatePreferenceRegistryRevisionRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await activatePreferenceRegistryRevision(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+            ...request,
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/correct`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, CorrectPreferenceRegistryRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await correctPreferenceRegistry(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/scope`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, ChangePreferenceRegistryScopeRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await changePreferenceRegistryScope(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/deactivate`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, DeactivatePreferenceRegistryRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await deactivatePreferenceRegistry(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/supersede`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, SupersedePreferenceRegistryRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await supersedePreferenceRegistry(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+
+  app.post(`${base}/:preferenceId/reject`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    const { grant } = access;
+    const id = preferenceId(context);
+    const request = await parseBody(context, RejectPreferenceRegistryProposalRequest);
+    try {
+      return context.json(
+        PreferenceRegistryMutationResponse.parse(
+          await rejectPreferenceRegistryProposal(deps.db, {
+            ...request,
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            preferenceId: id,
+            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
+          }),
+        ),
+      );
+    } catch (error) {
+      return preferenceError(context, error);
+    }
+  });
+}

package/src/routes/sessions.ts

@@ -76,6 +76,7 @@ import {
   listSessionHumanInputRequests,
   listSessionIdsInGroup,
   listSessionsForSubject,
+  getLatestStartedSessionTurn,
   listSessionTurns,
   projectEffectiveControlForRelatedAccess,
   projectSessionForRelatedAccess,
@@ -1077,6 +1078,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
+    // Exact turn that most recently emitted durable `turn.started` — the same
+    // boundary goal continuations use for inherited model/effort. Queued-only
+    // or preflight-rejected turns are deliberately excluded.
+    if (c.req.query("latestStarted") === "1" || c.req.query("latestStarted") === "true") {
+      const latest = await getLatestStartedSessionTurn(db, workspaceId, sessionId);
+      return c.json(latest ? [latest] : []);
+    }
     return c.json(
       await listSessionTurns(db, workspaceId, sessionId, boundedLimit(c.req.query("limit"))),
     );
@@ -1284,6 +1292,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       resources: payload.resources,
       model: payload.model ?? null,
       reasoningEffort: payload.reasoningEffort ?? null,
+      latencyMode: payload.latencyMode ?? null,
       mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
       delivery: "steer",
       origin: "human",
@@ -1326,6 +1335,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         resources: event.payload.resources ?? [],
         model: event.payload.model ?? null,
         reasoningEffort: event.payload.reasoningEffort ?? null,
+        latencyMode: event.payload.latencyMode ?? null,
         mcpCredentialUpdates: event.payload.mcpCredentialUpdates ?? [],
         ...(event.payload.controlEtag !== undefined
           ? { controlEtag: event.payload.controlEtag }

package/src/routes/transcriptions.ts

@@ -0,0 +1,155 @@
+import {
+  resolveWorkspaceVoiceInputEnabled,
+  type TranscribeAudioResponse,
+} from "@opengeni/contracts";
+import { type ApiRouteDeps, requireAccessGrant, TranscriptionServiceError } from "@opengeni/core";
+import { getWorkspace } from "@opengeni/db";
+import type { Hono } from "hono";
+
+export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.post("/v1/workspaces/:workspaceId/transcriptions", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+    const workspace = await getWorkspace(deps.db, workspaceId);
+    if (!workspace) return c.json({ code: "not_found" }, 404);
+    if (resolveWorkspaceVoiceInputEnabled(workspace.settings) === false) {
+      return c.json({ code: "policy_blocked" }, 403);
+    }
+    const service = deps.transcription;
+    if (!service || !(await service.available())) {
+      return c.json({ code: "unavailable" }, 503);
+    }
+    try {
+      const body = await audioRequest(c.req.raw, service.limits().maxSizeBytes);
+      const result = await service.transcribe({
+        workspaceId,
+        accountId: grant.accountId,
+        audio: body.audio,
+        mimeType: body.mimeType,
+        durationSeconds: body.durationSeconds,
+        signal: c.req.raw.signal,
+        requestId: c.req.header("x-opengeni-correlation-id") ?? crypto.randomUUID(),
+      });
+      const response: TranscribeAudioResponse = {
+        text: result.text,
+        languages: result.languages,
+      };
+      return c.json(response);
+    } catch (error) {
+      if (error instanceof TranscriptionServiceError) {
+        return c.json({ code: error.code }, error.status as never);
+      }
+      if (isAbort(error)) return c.json({ code: "cancelled" }, 499 as never);
+      return c.json({ code: "unknown" }, 500);
+    }
+  });
+}
+
+async function audioRequest(
+  request: Request,
+  maxSizeBytes: number,
+): Promise<{ audio: Uint8Array; mimeType: string; durationSeconds?: number }> {
+  const contentLength = Number(request.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > maxSizeBytes + 64 * 1024) {
+    throw new TranscriptionServiceError({
+      code: "too_large",
+      message: "Audio is too large.",
+    });
+  }
+  const contentType = request.headers.get("content-type") ?? "";
+  if (contentType.toLowerCase().startsWith("multipart/form-data")) {
+    const form = await request.formData();
+    const audio = form.get("audio");
+    if (!(audio instanceof File)) {
+      throw new TranscriptionServiceError({
+        code: "invalid_audio",
+        message: "Audio file is required.",
+      });
+    }
+    if (audio.size > maxSizeBytes) {
+      throw new TranscriptionServiceError({
+        code: "too_large",
+        message: "Audio is too large.",
+      });
+    }
+    const durationSeconds = durationValue(stringValue(form.get("durationSeconds")));
+    return {
+      audio: new Uint8Array(await audio.arrayBuffer()),
+      mimeType: stringValue(form.get("mimeType")) ?? audio.type,
+      ...(durationSeconds === undefined ? {} : { durationSeconds }),
+    };
+  }
+  const mimeType = contentType.split(";", 1)[0]?.trim() ?? "";
+  if (!mimeType.toLowerCase().startsWith("audio/")) {
+    throw new TranscriptionServiceError({
+      code: "not_supported",
+      message: "Unsupported audio format.",
+    });
+  }
+  const durationSeconds = durationValue(request.headers.get("x-opengeni-audio-duration-seconds"));
+  return {
+    audio: await readBounded(request.body, maxSizeBytes, request.signal),
+    mimeType,
+    ...(durationSeconds === undefined ? {} : { durationSeconds }),
+  };
+}
+
+async function readBounded(
+  body: ReadableStream<Uint8Array> | null,
+  maxSizeBytes: number,
+  signal: AbortSignal,
+): Promise<Uint8Array> {
+  if (!body)
+    throw new TranscriptionServiceError({
+      code: "invalid_audio",
+      message: "Audio is required.",
+    });
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+      const next = await reader.read();
+      if (next.done) break;
+      size += next.value.byteLength;
+      if (size > maxSizeBytes) {
+        await reader.cancel();
+        throw new TranscriptionServiceError({
+          code: "too_large",
+          message: "Audio is too large.",
+        });
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const audio = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    audio.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return audio;
+}
+
+function durationValue(value: string | null | undefined): number | undefined {
+  if (value == null || value.trim() === "") return undefined;
+  const duration = Number(value);
+  if (!Number.isFinite(duration)) {
+    throw new TranscriptionServiceError({
+      code: "invalid_audio",
+      message: "Invalid audio duration.",
+    });
+  }
+  return duration;
+}
+
+function stringValue(value: FormDataEntryValue | null): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function isAbort(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}