@opengeni/core 0.28.0 → 1.0.0

package/src/session-authorization.ts

@@ -3,11 +3,16 @@ import {
   SessionAuthorizationDecision,
   SessionAuthorizationListScope,
   type AccessGrant,
+  type SessionAgentAccess,
+  type SessionAgentAccessViewer,
   type SessionAuthorizationOperation,
   type SessionAuthorizationSurface,
   type SessionAuthorizationTarget,
+  type SessionScopeSubjectId,
 } from "@opengeni/contracts";
+import { AsyncLocalStorage } from "node:async_hooks";
 import {
+  currentSessionRlsActorIdentityKey,
   getSessionAuthorityProjection,
   getSession,
   getSessionTurnForAttempt,
@@ -20,6 +25,77 @@ import type { AppDependencies } from "./dependencies";
 
 export type SessionAuthorizationDependencies = Pick<AppDependencies, "db" | "sessionAuthorization">;
 
+/**
+ * Identical caller-session and attempt reads shared by the authorization
+ * checks of one first-party MCP request. Phases bound reuse to checks that run
+ * back to back: the route's own checks, then only checks a tool handler starts
+ * synchronously on entry. Anything later (a re-check after a wait or a write)
+ * reads fresh. Results are keyed by database handle and session RLS actor, so
+ * a read is only reused under the exact visibility it was made with.
+ */
+type SessionAuthorizationReads = {
+  phase: "route" | "handoff" | "dispatch" | "closed";
+  readonly results: WeakMap<Database, Map<string, unknown>>;
+};
+
+const sessionAuthorizationReads = new AsyncLocalStorage<SessionAuthorizationReads>();
+
+/** Scope read reuse to one request; it never outlives `fn`. */
+export async function withSessionAuthorizationReadReuse<T>(
+  fn: (reuse: { handOffToToolDispatch(): void }) => Promise<T>,
+): Promise<T> {
+  const reads: SessionAuthorizationReads = { phase: "route", results: new WeakMap() };
+  const handOffToToolDispatch = () => {
+    if (reads.phase === "route") reads.phase = "handoff";
+  };
+  try {
+    return await sessionAuthorizationReads.run(reads, () => fn({ handOffToToolDispatch }));
+  } finally {
+    reads.phase = "closed";
+  }
+}
+
+/**
+ * Invoke a tool handler so that authorization checks it starts before its
+ * first await reuse the route's reads. Later checks, and every other dispatch
+ * in the same request, read fresh.
+ */
+export function dispatchWithSessionAuthorizationReadReuse<T>(handler: () => T): T {
+  const reads = sessionAuthorizationReads.getStore();
+  if (reads?.phase !== "handoff") return handler();
+  reads.phase = "dispatch";
+  try {
+    return handler();
+  } finally {
+    reads.phase = "closed";
+  }
+}
+
+/** Call before the first await, so the phase is the one the check started in. */
+function claimSessionAuthorizationReads(): SessionAuthorizationReads | null {
+  const reads = sessionAuthorizationReads.getStore();
+  return reads?.phase === "route" || reads?.phase === "dispatch" ? reads : null;
+}
+
+async function reusableAuthorizationRead<T>(
+  reads: SessionAuthorizationReads | null,
+  db: Database,
+  key: readonly string[],
+  read: () => Promise<T>,
+): Promise<T> {
+  if (!reads) return await read();
+  const scopedKey = JSON.stringify([...key, currentSessionRlsActorIdentityKey()]);
+  let results = reads.results.get(db);
+  if (results?.has(scopedKey)) return results.get(scopedKey) as T;
+  const value = await read();
+  if (!results) {
+    results = new Map();
+    reads.results.set(db, results);
+  }
+  results.set(scopedKey, value);
+  return value;
+}
+
 /** Maximum time an omitted host hint leaves a live session stream unchecked. */
 export const SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS = 15_000;
 
@@ -48,17 +124,85 @@ export type ResolvedSessionAuthorization = {
   reauthorizeAfterMs: number | null;
 };
 
+/** The frozen agent-access facts of one session, as the pairwise rule sees them. */
+export type SessionAgentAccessFacts = {
+  agentAccess: SessionAgentAccess;
+  scopeSubjectId: SessionScopeSubjectId | null;
+};
+
 type ResolvedSessionAuthorizationActor = {
   actor: SessionAuthorizationActor;
   callerParentSessionId: string | null;
+  /** The caller session's own access facts; null for non-agent principals. */
+  callerAccess: SessionAgentAccessFacts | null;
 };
 
+function sameScopeSubject(
+  left: SessionScopeSubjectId | null,
+  right: SessionScopeSubjectId | null,
+): boolean {
+  return left !== null && right !== null && left === right;
+}
+
+/**
+ * The agent-to-agent reach rule (migration 0427) for one caller/target pair
+ * that live in DIFFERENT root trees. A caller always keeps its own tree, so
+ * this is never consulted for same-root access. Only the caller's task scope
+ * restricts outgoing reach. The target's visibility and ownership remain
+ * independently enforced; its agent scope does not block incoming access.
+ */
+export function agentAccessPermitsCrossTreeAccess(
+  caller: SessionAgentAccessFacts,
+  target: SessionAgentAccessFacts,
+): boolean {
+  if (caller.agentAccess === "session") return false;
+  if (caller.agentAccess === "user") {
+    return sameScopeSubject(caller.scopeSubjectId, target.scopeSubjectId);
+  }
+  return true;
+}
+
+/**
+ * The in-database list scope for one calling attempt. A `session` caller is
+ * pinned to its own root tree when the host does not narrow it. Every caller
+ * carries the viewer so `sessionAuthorizationScopeFilter` intersects the host
+ * scope with the same pairwise rule in SQL, including for session callers.
+ */
+export function agentAccessListScopeForViewer(
+  viewer: SessionAgentAccessViewer,
+  hostScope: SessionAuthorizationListScope | null = null,
+): SessionAuthorizationListScope {
+  if (viewer.agentAccess === "session" && (!hostScope || hostScope.kind === "all")) {
+    return {
+      kind: "scoped",
+      rootSessionIds: [viewer.callerRootSessionId],
+      sessionIds: [],
+      agentAccessViewer: viewer,
+    };
+  }
+  if (!hostScope || hostScope.kind === "all") {
+    return { kind: "all", agentAccessViewer: viewer };
+  }
+  return {
+    kind: "scoped",
+    rootSessionIds: [...new Set(hostScope.rootSessionIds)],
+    sessionIds: [...new Set(hostScope.sessionIds)],
+    agentAccessViewer: viewer,
+  };
+}
+
 type ResolvedSessionAuthorizationTarget = {
   target: SessionAuthorizationTarget;
   parentSessionId: string | null;
 };
 
-function grantHasAgentAttemptAuthority(grant: AccessGrant): boolean {
+/**
+ * Whether a grant acts with live agent-attempt authority: an explicit
+ * `agent_attempt` principal kind, or (for legacy tokens without one) any
+ * worker-signed exact attempt claim. Shared by the session seam and by the
+ * narrowing fences that let a human widen a session an agent may only narrow.
+ */
+export function grantHasAgentAttemptAuthority(grant: AccessGrant): boolean {
   const hasAgentAttemptClaim =
     grant.metadata?.["turnId"] !== undefined ||
     grant.metadata?.["attemptId"] !== undefined ||
@@ -67,52 +211,16 @@ function grantHasAgentAttemptAuthority(grant: AccessGrant): boolean {
 }
 
 /**
- * Read-only access an immediate child may use against its parent. Upstream
- * mutation is deliberately limited to `session.append`: letting a child Pause,
- * Steer, or otherwise mutate its parent would let it influence siblings through
- * the parent's recursive control and shared state.
+ * Live agent attempts may address any workspace session that later private,
+ * Slack-owner, and optional host checks still allow. Parent/child lineage is
+ * not an access deny. Cross-session projections stay exact-target so a peer
+ * read does not receive another session's derived metadata.
  */
-const AGENT_PARENT_READ_OPERATIONS = new Set<SessionAuthorizationOperation>([
-  "session.read",
-  "session.events.read",
-  "session.stream.read",
-  "session.turns.read",
-  "session.queue.read",
-  "session.composer.read",
-  "session.lineage.read",
-  "session.capture.read",
-  "session.files.read",
-  "session.git.read",
-  "session.terminal.read",
-  "session.viewer.read",
-  "session.goal.read",
-  "session.human_input.read",
-]);
-
-function enforceAgentSessionHierarchy(
+function relatedSessionAccessForAgentAttempt(
   actor: Extract<SessionAuthorizationActor, { kind: "agent_attempt" }>,
-  callerParentSessionId: string | null,
-  target: ResolvedSessionAuthorizationTarget,
-  operation: SessionAuthorizationOperation,
+  targetSessionId: string,
 ): "target" | "root" {
-  if (target.target.sessionId === actor.callerSessionId) return "root";
-
-  // A manager may inspect and operate an immediate child. Existing permission
-  // and host-policy checks still apply; lineage never grants a capability.
-  if (target.parentSessionId === actor.callerSessionId) return "target";
-
-  // A child may report to and inspect its immediate parent, but cannot mutate
-  // the parent except through the canonical machine-input message boundary.
-  if (callerParentSessionId === target.target.sessionId) {
-    if (operation === "session.append" || AGENT_PARENT_READ_OPERATIONS.has(operation)) {
-      return "target";
-    }
-    throw new SessionAuthorizationDeniedError("forbidden");
-  }
-
-  // Siblings, skipped generations, other branches, and unrelated roots are
-  // never cross-session authority for a live agent attempt.
-  throw new SessionAuthorizationDeniedError("forbidden");
+  return targetSessionId === actor.callerSessionId ? "root" : "target";
 }
 
 export function sessionRlsActorForAuthorization(
@@ -143,7 +251,8 @@ export async function requireLiveAgentAttemptAuthorization(
   grant: AccessGrant,
   callerSessionId: string,
 ): Promise<Extract<SessionAuthorizationActor, { kind: "agent_attempt" }>> {
-  const { actor } = await resolveSessionAuthorizationActor(db, grant);
+  const reads = claimSessionAuthorizationReads();
+  const { actor } = await resolveSessionAuthorizationActor(db, grant, reads);
   if (actor.kind !== "agent_attempt" || actor.callerSessionId !== callerSessionId) {
     throw new SessionAuthorizationDeniedError("caller_stale");
   }
@@ -170,16 +279,31 @@ export async function requireSessionAuthorization(
     surface: SessionAuthorizationSurface;
   },
 ): Promise<ResolvedSessionAuthorization | null> {
+  const reads = claimSessionAuthorizationReads();
   const port = deps.sessionAuthorization;
   const isAgentAttempt = grantHasAgentAttemptAuthority(grant);
-  const [slackAccess, authority] = await Promise.all([
-    getSlackInteractionSessionAccessForSession(deps.db, {
-      accountId: grant.accountId,
-      workspaceId: grant.workspaceId,
-      sessionId: input.sessionId,
-    }),
-    getSessionAuthorityProjection(deps.db, grant.workspaceId, input.sessionId),
-  ]);
+  // Callers can supply a transaction handle. Both reads open nested RLS
+  // savepoints, which must not race on the same PostgreSQL connection.
+  const slackAccess = await getSlackInteractionSessionAccessForSession(deps.db, {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    sessionId: input.sessionId,
+  });
+  const authority = await getSessionAuthorityProjection(
+    deps.db,
+    grant.workspaceId,
+    input.sessionId,
+  );
+
+  // The projection is read under the caller's own RLS context, so a missing
+  // session and one the caller may not see (another member's private session)
+  // are the same answer. Every request-facing surface refuses both here,
+  // before a route-specific read can observe the difference or fail on the
+  // absent row. In-process `core` callers keep the standalone null result and
+  // their own not-found handling.
+  if (!authority && input.surface !== "core") {
+    throw new SessionAuthorizationDeniedError("not_found");
+  }
 
   // Preserve the standalone workspace-shared path. Private sessions continue
   // through the durable actor and ownership checks even without a host port.
@@ -193,22 +317,29 @@ export async function requireSessionAuthorization(
   }
   if (!authority) throw new SessionAuthorizationDeniedError("not_found");
 
-  const [resolvedActor, resolvedTarget] = await Promise.all([
-    resolveSessionAuthorizationActor(deps.db, grant),
-    resolveSessionAuthorizationTarget(deps.db, grant, input.sessionId),
-  ]);
+  const resolvedActor = await resolveSessionAuthorizationActor(deps.db, grant, reads);
+  const resolvedTarget = await resolveSessionAuthorizationTarget(
+    deps.db,
+    grant,
+    input.sessionId,
+    reads,
+  );
   const actor = resolvedActor.actor;
   const target = resolvedTarget.target;
   const agentRelatedSessionAccess =
     actor.kind === "agent_attempt"
-      ? enforceAgentSessionHierarchy(
-          actor,
-          resolvedActor.callerParentSessionId,
-          resolvedTarget,
-          input.operation,
-        )
+      ? relatedSessionAccessForAgentAttempt(actor, target.sessionId)
       : null;
 
+  // Tool approvals are a human decision. An agent attempt may answer another
+  // session's structured human-input request (`session.human_input.write`,
+  // through `session_human_input_respond`) but may never approve or reject a
+  // pending tool approval on any session, including a child it spawned; an
+  // embedding-host port cannot widen this.
+  if (actor.kind === "agent_attempt" && input.operation === "session.approval.write") {
+    throw new SessionAuthorizationDeniedError("forbidden");
+  }
+
   if (authority.visibility === "user_private") {
     const allowed =
       authority.ownerSubjectId !== null &&
@@ -224,6 +355,22 @@ export async function requireSessionAuthorization(
         : actor.callerRootSessionId === target.rootSessionId;
     if (!allowed) throw new SessionAuthorizationDeniedError("forbidden");
   }
+  // Agent-access scope (migration 0427): an attempt always keeps its own root
+  // tree; across trees only its own outgoing task scope restricts reach.
+  // User matching reads canonical target identity, not target task scope.
+  // Private ownership above and the host authorization below still apply.
+  if (actor.kind === "agent_attempt" && target.rootSessionId !== actor.callerRootSessionId) {
+    const callerAccess = resolvedActor.callerAccess;
+    if (
+      !callerAccess ||
+      !agentAccessPermitsCrossTreeAccess(callerAccess, {
+        agentAccess: authority.agentAccess,
+        scopeSubjectId: authority.scopeSubjectId,
+      })
+    ) {
+      throw new SessionAuthorizationDeniedError("forbidden");
+    }
+  }
   if (!port) {
     return {
       actor,
@@ -270,13 +417,24 @@ export async function requireSessionAuthorizationListScope(
   grant: AccessGrant,
   surface: SessionAuthorizationSurface,
 ): Promise<SessionAuthorizationListScope | null> {
+  const reads = claimSessionAuthorizationReads();
   const port = deps.sessionAuthorization;
   const isAgentAttempt = grantHasAgentAttemptAuthority(grant);
   if (!port && !isAgentAttempt) return null;
-  const { actor } = await resolveSessionAuthorizationActor(deps.db, grant);
-  // Standalone agents may retain compact workspace discovery, but only while
-  // the signed caller attempt is still the exact live attempt.
-  if (!port) return null;
+  const { actor, callerAccess } = await resolveSessionAuthorizationActor(deps.db, grant, reads);
+  // Standalone agents retain compact workspace discovery only while the signed
+  // caller attempt is still the exact live attempt, and only within their own
+  // declared agent-access reach (migration 0427). The viewer is derived from
+  // the caller session row and applied as one SQL predicate by every list.
+  const viewer: SessionAgentAccessViewer | null =
+    actor.kind === "agent_attempt" && callerAccess
+      ? {
+          callerRootSessionId: actor.callerRootSessionId,
+          agentAccess: callerAccess.agentAccess,
+          scopeSubjectId: callerAccess.scopeSubjectId,
+        }
+      : null;
+  if (!port) return viewer ? agentAccessListScopeForViewer(viewer) : null;
   let rawScope: unknown;
   try {
     rawScope = await port.resolveListScope({
@@ -292,20 +450,31 @@ export async function requireSessionAuthorizationListScope(
   if (!parsed.success) {
     throw new SessionAuthorizationUnavailableError({ cause: parsed.error });
   }
-  if (parsed.data.kind === "all") return parsed.data;
-  return {
-    kind: "scoped",
-    rootSessionIds: [...new Set(parsed.data.rootSessionIds)],
-    sessionIds: [...new Set(parsed.data.sessionIds)],
-  };
+  // A host never supplies the viewer: OpenGeni resolved it above from durable
+  // state, so a host-returned value is dropped before the intersection.
+  const hostScope: SessionAuthorizationListScope =
+    parsed.data.kind === "all"
+      ? { kind: "all" }
+      : {
+          kind: "scoped",
+          rootSessionIds: [...new Set(parsed.data.rootSessionIds)],
+          sessionIds: [...new Set(parsed.data.sessionIds)],
+        };
+  return viewer ? agentAccessListScopeForViewer(viewer, hostScope) : hostScope;
 }
 
 async function resolveSessionAuthorizationTarget(
   db: Database,
   grant: AccessGrant,
   sessionId: string,
+  reads: SessionAuthorizationReads | null,
 ): Promise<ResolvedSessionAuthorizationTarget> {
-  const session = await getSession(db, grant.workspaceId, sessionId);
+  const session = await reusableAuthorizationRead(
+    reads,
+    db,
+    ["session", grant.workspaceId, sessionId],
+    () => getSession(db, grant.workspaceId, sessionId),
+  );
   if (!session || session.accountId !== grant.accountId) {
     throw new SessionAuthorizationDeniedError("not_found");
   }
@@ -317,6 +486,7 @@ async function resolveSessionAuthorizationTarget(
 async function resolveSessionAuthorizationActor(
   db: Database,
   grant: AccessGrant,
+  reads: SessionAuthorizationReads | null,
 ): Promise<ResolvedSessionAuthorizationActor> {
   const callerSessionId = grant.metadata?.["sessionId"];
   const turnId = grant.metadata?.["turnId"];
@@ -331,6 +501,7 @@ async function resolveSessionAuthorizationActor(
         ...(grant.subjectLabel ? { subjectLabel: grant.subjectLabel } : {}),
       }),
       callerParentSessionId: null,
+      callerAccess: null,
     };
   }
   if (
@@ -343,10 +514,19 @@ async function resolveSessionAuthorizationActor(
   ) {
     throw new SessionAuthorizationDeniedError("caller_stale");
   }
-  const [callerSession, turn] = await Promise.all([
-    getSession(db, grant.workspaceId, callerSessionId),
-    getSessionTurnForAttempt(db, grant.workspaceId, callerSessionId, attemptId),
-  ]);
+  // These scoped reads can also open nested savepoints on a transaction handle.
+  const callerSession = await reusableAuthorizationRead(
+    reads,
+    db,
+    ["session", grant.workspaceId, callerSessionId],
+    () => getSession(db, grant.workspaceId, callerSessionId),
+  );
+  const turn = await reusableAuthorizationRead(
+    reads,
+    db,
+    ["turn", grant.workspaceId, callerSessionId, attemptId],
+    () => getSessionTurnForAttempt(db, grant.workspaceId, callerSessionId, attemptId),
+  );
   if (
     !callerSession ||
     callerSession.accountId !== grant.accountId ||
@@ -373,5 +553,9 @@ async function resolveSessionAuthorizationActor(
         (turn.initiator.kind === "subject" ? turn.initiator.subjectId : null),
     }),
     callerParentSessionId: callerSession.parentSessionId,
+    callerAccess: {
+      agentAccess: callerSession.agentAccess,
+      scopeSubjectId: callerSession.scopeSubjectId,
+    },
   };
 }

package/src/site-session-origin.ts

@@ -0,0 +1,22 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type SiteSessionOrigin = { siteId: string; title: string };
+const origins = new AsyncLocalStorage<SiteSessionOrigin>();
+
+/** Request-local provenance, set only after the API validates a published Site version. */
+export function withSiteSessionOrigin<T>(origin: SiteSessionOrigin, run: () => T): T {
+  return origins.run(origin, run);
+}
+
+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;
+}
+
+/** The validated Site origin of the current request, if any. Provenance only. */
+export function currentSiteSessionOrigin(): SiteSessionOrigin | undefined {
+  return origins.getStore();
+}

package/src/transcription.ts

@@ -31,6 +31,9 @@ export type TranscriptionRequest = {
   providerDeadlineAt?: Date | undefined;
   /** Exact provider selected before a resumable segment is first sent upstream. */
   providerId?: string | undefined;
+  preferredProvider?: string | null | undefined;
+  fallbackEnabled?: boolean | undefined;
+  excludedProviders?: readonly string[] | undefined;
 };
 
 export type TranscriptionResult = TranscribeAudioResponse & {
@@ -44,18 +47,22 @@ export class TranscriptionServiceError extends Error {
   readonly code: VoiceInputErrorCode;
   readonly status: number;
   readonly retryable: boolean;
+  /** Explicit rejection before any transcription result; safe to try another provider. */
+  readonly fallbackSafe: boolean;
 
   constructor(input: {
     code: VoiceInputErrorCode;
     message: string;
     status?: number;
     retryable?: boolean;
+    fallbackSafe?: boolean;
   }) {
     super(input.message);
     this.name = "TranscriptionServiceError";
     this.code = input.code;
     this.status = input.status ?? statusForVoiceInputError(input.code);
     this.retryable = input.retryable ?? false;
+    this.fallbackSafe = input.fallbackSafe ?? false;
   }
 }
 
@@ -88,6 +95,10 @@ export function statusForVoiceInputError(code: VoiceInputErrorCode): number {
 
 /** Optional workspace scope for readiness checks during provider selection. */
 export type TranscriptionAvailabilityContext = {
+  afterProvider?: string | undefined;
+  preferredProvider?: string | null | undefined;
+  fallbackEnabled?: boolean | undefined;
+  excludedProviders?: readonly string[] | undefined;
   workspaceId?: string | undefined;
   subjectId?: string | undefined;
 };
@@ -95,7 +106,8 @@ export type TranscriptionAvailabilityContext = {
 /**
  * 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.
+ * only fall back after an explicit rejection and before any successful or
+ * uncertain provider attempt. Recording persistence owns that eligibility.
  */
 export type TranscriptionProvider = {
   readonly id: string;

package/src/turn-surface.ts

@@ -0,0 +1,45 @@
+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 an analytics label frozen on the accepted turn. It never
+ * authorizes anything, so 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;
+}