@opengeni/core 3.0.1 → 3.1.2

package/src/site-agent-clamp.ts

@@ -0,0 +1,226 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import {
+  getSession,
+  getSiteDataAgentSession,
+  SITE_DATA_AGENT_LINEAGE_MAX_DEPTH,
+  type Database,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import { siteSessionOriginFromMetadata } from "./site-session-origin";
+
+/**
+ * Whether an agent acts for a Site page: its session, a spawning ancestor or
+ * its root session was started from a Site (a published Site or an inline or
+ * preview frame), or its current or a spawning ancestor turn arrived from one.
+ * The same evidence the Site Data agent clamp uses
+ * (apps/api/src/site-data/service.ts), plus frame origins without a
+ * published Site id.
+ */
+export type SiteAgentClamp = {
+  clamped: boolean;
+  /** Published Sites in the lineage; empty for frames without a published Site. */
+  originSiteIds: string[];
+};
+
+function agentSessionIds(grant: AccessGrant): { sessionId: string; turnId: string | null } | null {
+  if (grant.principalKind !== "agent_attempt" && grant.metadata?.delegated !== true) return null;
+  const sessionId = grant.metadata?.sessionId;
+  if (typeof sessionId !== "string" || sessionId.length === 0) return null;
+  const turnId = grant.metadata?.turnId;
+  return { sessionId, turnId: typeof turnId === "string" && turnId.length > 0 ? turnId : null };
+}
+
+/** Null when the grant is not an agent session. */
+export async function siteAgentClamp(
+  db: Database,
+  grant: AccessGrant,
+): Promise<SiteAgentClamp | null> {
+  const ids = agentSessionIds(grant);
+  if (!ids) return null;
+  return await siteSessionClamp(
+    db,
+    { accountId: grant.accountId, workspaceId: grant.workspaceId },
+    ids.sessionId,
+    ids.turnId,
+  );
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+/** How long an agent turn's clamp is reused (per process). */
+const CLAMP_CACHE_MS = 60_000;
+const CLAMP_CACHE_LIMIT = 5_000;
+const clampCache = new Map<string, { clamp: SiteAgentClamp; at: number }>();
+
+/**
+ * The Site clamp of an agent running in `sessionId` (and `turnId`, when
+ * known). A turn's clamp is computed once a minute at most per process: the
+ * evidence it reads (where the session, its ancestors and that turn came
+ * from) does not change during the turn. Without a turn id it is always
+ * read fresh.
+ */
+export async function siteSessionClamp(
+  db: Database,
+  scope: { accountId: string; workspaceId: string },
+  sessionId: string,
+  turnId: string | null,
+): Promise<SiteAgentClamp> {
+  if (turnId === null) return (await readSiteSessionClamp(db, scope, sessionId, null)).clamp;
+  const key = `${scope.workspaceId}:${sessionId}:${turnId}`;
+  const now = Date.now();
+  const cached = clampCache.get(key);
+  if (cached && cached.at > now - CLAMP_CACHE_MS) return cached.clamp;
+  const { clamp, cacheable } = await readSiteSessionClamp(db, scope, sessionId, turnId);
+  if (cacheable) {
+    if (clampCache.size >= CLAMP_CACHE_LIMIT) clampCache.clear();
+    clampCache.set(key, { clamp, at: now });
+  }
+  return clamp;
+}
+
+async function readSiteSessionClamp(
+  db: Database,
+  scope: { accountId: string; workspaceId: string },
+  sessionId: string,
+  turnId: string | null,
+): Promise<{ clamp: SiteAgentClamp; cacheable: boolean }> {
+  // A session id that is not a UUID names no session.
+  const own = UUID.test(sessionId)
+    ? await getSession(db, scope.workspaceId, sessionId).catch(() => undefined)
+    : null;
+  // A read that failed fails closed, as a partial lineage does. Never cached:
+  // it may have failed only for now.
+  if (own === undefined) return { clamp: { clamped: true, originSiteIds: [] }, cacheable: false };
+  // No such session: other checks refuse a caller whose session is gone.
+  if (!own) return { clamp: { clamped: false, originSiteIds: [] }, cacheable: false };
+  const lineage = await getSiteDataAgentSession(db, scope, sessionId, turnId);
+  let frameOrigin = siteSessionOriginFromMetadata(own.metadata) !== null;
+  // Frames without a published Site record no Site id; find their origin by walking up.
+  let parentId = own.parentSessionId;
+  let unread = false;
+  const read = (id: string) =>
+    getSession(db, scope.workspaceId, id).catch(() => {
+      unread = true;
+      return null;
+    });
+  for (let depth = 0; !frameOrigin && parentId && depth < SITE_DATA_AGENT_LINEAGE_MAX_DEPTH;) {
+    const parent = await read(parentId);
+    if (!parent) break;
+    frameOrigin = siteSessionOriginFromMetadata(parent.metadata) !== null;
+    parentId = parent.parentSessionId;
+    depth += 1;
+  }
+  if (!frameOrigin && own.rootSessionId && own.rootSessionId !== own.id) {
+    const root = await read(own.rootSessionId);
+    frameOrigin = siteSessionOriginFromMetadata(root?.metadata) !== null;
+  }
+  return {
+    clamp: {
+      // A lineage that cannot be read in full fails closed, as for Site Data.
+      clamped:
+        frameOrigin || lineage.originSiteIds.length > 0 || lineage.siteTurn || !lineage.complete,
+      originSiteIds: lineage.originSiteIds,
+    },
+    // A partial read (failed closed) is read again next time.
+    cacheable: lineage.complete && !unread,
+  };
+}
+
+/** What a Site-clamped agent may not create or change. */
+export type SiteClampedResource =
+  | "schedules"
+  | "automations"
+  | "Site publications"
+  | "workspace instructions"
+  | "Skills"
+  | "Knowledge"
+  | "secrets"
+  | "workspace members, connections or settings"
+  | "the organization profile"
+  | "Connected Machines"
+  | "sandbox environments"
+  | "browser or computer sessions"
+  | "documents, spreadsheets or presentations the Site did not declare"
+  | "workspace settings";
+
+/** The refusal message for a Site-clamped agent. */
+export function siteClampedAgentMessage(what: SiteClampedResource): string {
+  return `An agent started from a Site page cannot create or change ${what}`;
+}
+
+/**
+ * The refusal when a Site-clamped agent reaches for compute beyond its own
+ * session's: `run_on`, attaching, swapping or provisioning a sandbox, or
+ * starting a worker on a chosen machine or another session's sandbox.
+ */
+export const SITE_AGENT_COMPUTE_MESSAGE =
+  "An agent started from a Site page cannot run on, attach, provision or choose sandboxes or Connected Machines";
+
+/** Fields of a session create that choose its compute, which a Site-clamped agent may not send. */
+const SITE_AGENT_COMPUTE_FIELDS = ["targetSandboxId", "workingDir"] as const;
+
+/**
+ * Refuse a Site-clamped agent's session create that chooses compute: a
+ * machine target, a self-hosted backend or another session's sandbox group.
+ * Its workers run in its own sandbox (shared) or a new managed one.
+ */
+export async function assertSiteAgentMayChooseCompute(
+  db: Database,
+  grant: AccessGrant,
+  payload: {
+    sandbox?: unknown;
+    sandboxBackend?: unknown;
+    targetSandboxId?: unknown;
+    workingDir?: unknown;
+  },
+): Promise<void> {
+  const choosesCompute =
+    SITE_AGENT_COMPUTE_FIELDS.some(
+      (field) => payload[field] !== undefined && payload[field] !== null,
+    ) ||
+    payload.sandboxBackend === "selfhosted" ||
+    (payload.sandbox !== undefined &&
+      payload.sandbox !== null &&
+      typeof payload.sandbox === "object");
+  if (!choosesCompute) return;
+  if (!(await siteAgentClamp(db, grant))?.clamped) return;
+  throw new HTTPException(403, { message: SITE_AGENT_COMPUTE_MESSAGE });
+}
+
+/**
+ * Refuse a Site-clamped agent: an agent started from a Site page acts with
+ * that page's reach and cannot create or change schedules, automations, Site
+ * publications, workspace instructions, Skills, Knowledge, secrets,
+ * workspace members, connections and settings, the organization profile,
+ * Connected Machines, sandbox environments or other workspace settings.
+ */
+export async function assertNotSiteClampedAgent(
+  db: Database,
+  grant: AccessGrant,
+  what: SiteClampedResource,
+): Promise<void> {
+  const clamp = await siteAgentClamp(db, grant);
+  if (!clamp?.clamped) return;
+  throw new HTTPException(403, { message: siteClampedAgentMessage(what) });
+}
+
+/**
+ * Whether an agent running in `caller` may message, steer or control
+ * `targetSessionId`. An unclamped agent is not limited here. A Site-clamped
+ * agent reaches only sessions that act for the same Site: clamped themselves
+ * (its own lineage, or another session the Site started) and naming no
+ * published Site the caller does not.
+ */
+export async function siteAgentMayReachSession(
+  db: Database,
+  scope: { accountId: string; workspaceId: string },
+  caller: { sessionId: string; turnId: string | null },
+  targetSessionId: string,
+): Promise<boolean> {
+  if (targetSessionId === caller.sessionId) return true;
+  const callerClamp = await siteSessionClamp(db, scope, caller.sessionId, caller.turnId);
+  if (!callerClamp.clamped) return true;
+  const target = await siteSessionClamp(db, scope, targetSessionId, null);
+  const callerSites = new Set(callerClamp.originSiteIds);
+  return target.clamped && target.originSiteIds.every((siteId) => callerSites.has(siteId));
+}

package/src/site-session-origin.ts

@@ -1,9 +1,31 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 
-export type SiteSessionOrigin = { siteId: string; title: string };
+/**
+ * Which Site page a request came from. Provenance, plus the key the API uses
+ * to keep one Site's pages away from another Site's sessions.
+ *
+ * A published Site has a `siteId` (and `versionId` when the host pinned one).
+ * Inline HTML and Codemode preview frames have no published id: they record
+ * `siteId: null`, the `frame` kind and the host-minted `frameId` of the
+ * mounted page, so a frame reaches only the sessions it started itself.
+ */
+export type SiteSessionOrigin = {
+  siteId: string | null;
+  title: string;
+  versionId?: string;
+  frame?: "inline" | "preview";
+  frameId?: string;
+};
+
+export const SITE_ORIGIN_METADATA_KEY = "_opengeniSiteOrigin";
+
 const origins = new AsyncLocalStorage<SiteSessionOrigin>();
 
-/** Request-local provenance, set only after the API validates a published Site version. */
+/**
+ * Request-local provenance, set only after the API validated the Site the
+ * request came from (a published Site version the caller can see, or a
+ * host-marked inline or preview frame).
+ */
 export function withSiteSessionOrigin<T>(origin: SiteSessionOrigin, run: () => T): T {
   return origins.run(origin, run);
 }
@@ -11,7 +33,64 @@ export function withSiteSessionOrigin<T>(origin: SiteSessionOrigin, run: () => T
 export function sessionCreationMetadata(
   metadata: Record<string, unknown>,
 ): Record<string, unknown> {
-  const { _opengeniSiteOrigin: _ignored, ...rest } = metadata;
-  const origin = origins.getStore();
-  return origin ? { ...rest, _opengeniSiteOrigin: origin } : rest;
+  return withSiteOriginMetadata(metadata, origins.getStore() ?? null);
+}
+
+/** The validated Site origin of the current request, if any. Provenance only. */
+export function currentSiteSessionOrigin(): SiteSessionOrigin | undefined {
+  return origins.getStore();
+}
+
+/**
+ * Replace any caller-supplied Site origin in `metadata` with `origin` (or drop
+ * it). Callers never choose their own provenance.
+ */
+export function withSiteOriginMetadata(
+  metadata: Record<string, unknown>,
+  origin: SiteSessionOrigin | null | undefined,
+): Record<string, unknown> {
+  const { [SITE_ORIGIN_METADATA_KEY]: _ignored, ...rest } = metadata;
+  return origin ? { ...rest, [SITE_ORIGIN_METADATA_KEY]: origin } : rest;
+}
+
+/**
+ * Read the recorded Site origin from session (or schedule agent config)
+ * metadata. Any object under the key counts as a Site origin, so a malformed
+ * record still marks the session as Site-started (fail closed).
+ */
+export function siteSessionOriginFromMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+): SiteSessionOrigin | null {
+  const raw = metadata?.[SITE_ORIGIN_METADATA_KEY];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  return {
+    siteId: typeof value.siteId === "string" && value.siteId.length > 0 ? value.siteId : null,
+    title: typeof value.title === "string" ? value.title : "",
+    ...(typeof value.versionId === "string" ? { versionId: value.versionId } : {}),
+    ...(value.frame === "inline" || value.frame === "preview" ? { frame: value.frame } : {}),
+    ...(typeof value.frameId === "string" && value.frameId.length > 0
+      ? { frameId: value.frameId }
+      : {}),
+  };
+}
+
+/**
+ * Whether a request from the `requester` Site page may reach a session (or
+ * schedule) whose recorded origin is `target`. Same published Site, or, for
+ * frames without a published id, the same mounted frame. Anything without a
+ * Site origin is out of reach for a Site page.
+ */
+export function siteOriginsMatch(
+  requester: SiteSessionOrigin,
+  target: SiteSessionOrigin | null | undefined,
+): boolean {
+  if (!target) return false;
+  if (requester.siteId !== null) return target.siteId === requester.siteId;
+  return (
+    target.siteId === null &&
+    requester.frameId !== undefined &&
+    target.frameId !== undefined &&
+    target.frameId === requester.frameId
+  );
 }

package/src/transcription.ts

@@ -1,10 +1,12 @@
+import type { VoiceInputPricing, VoiceInputUsage } from "@opengeni/config";
 import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
+import type { CreditDebitAttribution } from "@opengeni/db";
 
 /**
  * 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
+ * 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.
  */
@@ -34,6 +36,39 @@ export type TranscriptionRequest = {
   preferredProvider?: string | null | undefined;
   fallbackEnabled?: boolean | undefined;
   excludedProviders?: readonly string[] | undefined;
+  /**
+   * Credit settlement facts for a deployment-funded provider. Required when
+   * the selected provider is deployment-funded and credit billing is active;
+   * the service fails closed without it.
+   */
+  billing?: TranscriptionBillingContext | undefined;
+  /**
+   * Internal: return `settleBilling` instead of settling before returning, so
+   * a resumable segment's transcript commits before any billing write.
+   */
+  deferBillingSettlement?: boolean;
+};
+
+/**
+ * Trusted, server-built settlement identity for one transcription unit. The
+ * usage receipt and debit idempotency keys derive from `workspaceId` +
+ * `sourceId` (see `voiceInputSettlementKeys`), so a retry or a later
+ * reconciliation settles the same unit exactly once.
+ */
+export type TranscriptionBillingContext = {
+  /**
+   * Server-derived unit identity. Never a client-chosen value: a reused id
+   * settles once, so a client-controlled id would make later calls free.
+   */
+  sourceId: string;
+  /** Trusted payer facts from the authenticated request boundary. */
+  attribution: CreditDebitAttribution;
+  /**
+   * Audio duration measured by the server from WAV bytes it produced (the
+   * resumable segment, or the normalized one-shot upload). Bills whenever the
+   * provider reports no usage this deployment has a price for.
+   */
+  trustedDurationSeconds?: number | undefined;
 };
 
 export type TranscriptionResult = TranscribeAudioResponse & {
@@ -41,17 +76,79 @@ export type TranscriptionResult = TranscribeAudioResponse & {
   providerId: string;
   audioSeconds: number;
   latencyMs: number;
+  /** Opengeni credits charged for this call (0 for subscription/free providers). */
+  creditCostMicros?: number | undefined;
+  /**
+   * Server-only settlement callback; never serialized into a public response.
+   * Never rejects: a settlement failure after provider success is logged and
+   * retried, and the transcript is still delivered.
+   */
+  settleBilling?: () => Promise<void>;
+};
+
+export type TranscriptionBillingRefusalCode =
+  | "insufficient_credits"
+  | "allowance_exhausted"
+  | "monthly_model_cost_limit";
+
+/**
+ * Pre-use refusal for deployment-funded transcription: 402 for credits and
+ * allowances (same codes as session admission), 429 for a static monthly cap.
+ */
+export class TranscriptionBillingRefusedError extends Error {
+  readonly status: 402 | 429;
+  readonly code: TranscriptionBillingRefusalCode;
+  readonly details: { scope?: string; resetsAt?: string | null; subjectId?: string };
+
+  constructor(input: {
+    code: TranscriptionBillingRefusalCode;
+    message: string;
+    details?: { scope?: string; resetsAt?: string | null; subjectId?: string };
+  }) {
+    super(input.message);
+    this.name = "TranscriptionBillingRefusedError";
+    this.code = input.code;
+    this.status = input.code === "monthly_model_cost_limit" ? 429 : 402;
+    this.details = input.details ?? {};
+  }
+}
+
+/**
+ * Credit admission and settlement for deployment-funded transcription.
+ * Subscription providers (Codex, SuperGrok) never reach this port.
+ */
+export type TranscriptionBilling = {
+  /** Refuse before any audio is sent when the payer cannot fund the call. */
+  admit(input: {
+    accountId: string;
+    workspaceId: string;
+    attribution: CreditDebitAttribution;
+  }): Promise<void>;
+  /**
+   * Record usage and debit credits once per unit, after use. The usage receipt
+   * commits before the debit, so a failed debit leaves a durable receipt that
+   * `admit` reconciles on the workspace's next voice request.
+   */
+  settle(input: {
+    accountId: string;
+    workspaceId: string;
+    providerId: string;
+    model: string;
+    pricing: VoiceInputPricing;
+    usage: VoiceInputUsage | null;
+    billing: TranscriptionBillingContext;
+  }): Promise<{ creditCostMicros: number }>;
 };
 
 export class TranscriptionServiceError extends Error {
-  readonly code: VoiceInputErrorCode;
+  readonly code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
   readonly status: number;
   readonly retryable: boolean;
   /** Explicit rejection before any transcription result; safe to try another provider. */
   readonly fallbackSafe: boolean;
 
   constructor(input: {
-    code: VoiceInputErrorCode;
+    code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
     message: string;
     status?: number;
     retryable?: boolean;
@@ -114,6 +211,14 @@ export type TranscriptionProvider = {
   /** The adapter guarantees that its upstream transport honors AbortSignal. */
   readonly supportsServerDeadline: true;
   readonly experimental?: boolean | undefined;
+  /**
+   * Present when the deployment pays the upstream provider (OpenAI/Azure):
+   * the call is admitted against and settled in Opengeni credits. Absent for
+   * the workspace's own subscriptions, which are never charged.
+   */
+  readonly deploymentFunded?:
+    | { readonly model: string; readonly pricing: VoiceInputPricing | null }
+    | undefined;
   /**
    * Deployment readiness when called without a workspace. When `workspaceId` is
    * provided, providers may require a workspace-attached credential (e.g. Codex).
@@ -128,17 +233,29 @@ export type TranscriptionProvider = {
     subjectId: string;
     requestId: string;
     signal?: AbortSignal | undefined;
-  }): Promise<{ text: string; languages: string[] }>;
+  }): Promise<{ text: string; languages: string[]; usage?: VoiceInputUsage | null | undefined }>;
 };
 
 export type TranscriptionService = {
   limits(): TranscriptionLimits;
   /** True when at least one ready provider can serve requests. */
   available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  availableProviderIds?(context: TranscriptionAvailabilityContext): Promise<string[]>;
   /** Select one provider before a durable segment attempt; retries pin this id. */
   selectProvider?(
     context: TranscriptionAvailabilityContext,
   ): string | null | Promise<string | null>;
+  /**
+   * Credit admission for an exact provider before durable work is claimed.
+   * Resolves for subscription providers; throws TranscriptionBillingRefusedError
+   * when a deployment-funded provider cannot be paid for.
+   */
+  admit?(input: {
+    providerId: string;
+    accountId: string;
+    workspaceId: string;
+    attribution: CreditDebitAttribution;
+  }): Promise<void>;
   transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
 };
 
@@ -156,6 +273,8 @@ export type TranscriptionSegmenter = {
     sourceMimeType: string;
     totalDurationMilliseconds: number;
     providerSegmentSeconds: number;
+    /** Hard decode ceiling (`ffmpeg -t`); audio past it is never decoded. */
+    maxDecodeSeconds?: number | undefined;
     chunks: AsyncIterable<Uint8Array>;
     signal?: AbortSignal | undefined;
   }): AsyncIterable<PreparedTranscriptionSegment>;

package/src/turn-surface.ts

@@ -0,0 +1,47 @@
+import type { AccessGrant, SessionTurnSurface } from "@opengeni/contracts";
+import type { AccessGrantAuthorization } from "./access";
+import { currentSiteSessionOrigin } from "./site-session-origin";
+
+/**
+ * Resolve the content-free product surface a request entered through.
+ *
+ * The result is a label frozen on the accepted turn, mainly for analytics. It
+ * never grants access; the one place it affects authority is Site Data, where a
+ * `site` surface only narrows an agent to viewer reach
+ * (apps/api/src/site-data/service.ts). It reads trusted provenance only where
+ * it already exists: an explicit entry-point choice (Slack, automations, maintenance), the
+ * API-validated Site scope, and the access path the grant was resolved from.
+ * A grant whose path this function cannot place yields null rather than a
+ * guess.
+ */
+export function resolveTurnSurface(input: {
+  grant: AccessGrant;
+  authorization?: AccessGrantAuthorization | null | undefined;
+  /** An entry point that knows its surface (for example Slack) passes it here. */
+  requested?: SessionTurnSurface | null | undefined;
+}): SessionTurnSurface | null {
+  if (input.requested) return input.requested;
+  if (currentSiteSessionOrigin()) return "site";
+  const { grant } = input;
+  const metadata = grant.metadata ?? {};
+  if (
+    grant.principalKind === "agent_attempt" ||
+    metadata.turnId !== undefined ||
+    metadata.attemptId !== undefined
+  ) {
+    return "agent";
+  }
+  if (metadata.externalActor !== undefined) return "embedded";
+  if (metadata.mcpOAuth === true) return "mcp";
+  if (grant.principalKind === "api_key" || grant.principalKind === "configured_key") {
+    return "api_key";
+  }
+  if (metadata.delegated === true || grant.serviceInitiator) return "embedded";
+  if (
+    input.authorization?.canonicalManagedHumanSession ||
+    input.authorization?.canonicalLocalHumanSession
+  ) {
+    return "web";
+  }
+  return grant.principalKind === "human_session" ? "web" : null;
+}