@opengeni/core 0.28.0 → 1.0.0

package/dist/sandbox/routing.d.ts

@@ -1,12 +1,30 @@
 import { type Settings } from "@opengeni/config";
-import { type Database } from "@opengeni/db";
+import { type Database, type SandboxRetainedProcess } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
-import { type EstablishedSandboxSession, type RoutingSandboxOperationObserver, type SelfhostedRelayConfig } from "@opengeni/runtime/sandbox";
+import { type EstablishedSandboxSession, type ResolvedActiveBackend, type RoutingRetainedProcess, type RoutingRetainedProcessTerminalProof, type RoutingSandboxOperationObserver, type RoutingSandboxCaptureWaitObserver, type SelfhostedRelayConfig } from "@opengeni/runtime/sandbox";
+type DirectRetainedProcessRoute = {
+    providerSessionId: number;
+    providerBackend: string;
+    providerInstanceId: string;
+    leaseEpoch: number;
+    routeKind: "home" | "active";
+    routeTargetId: string | null;
+    routeEpoch: number;
+};
+/** API-direct requests always use active-route authority. The default active
+ * pointer is represented by a null target id; it is not a home-route write. */
+export declare function directRetainedProcessMatchesBackend(durable: DirectRetainedProcessRoute, process: RoutingRetainedProcess, backend: ResolvedActiveBackend): boolean;
+export declare function retainedProcessBackgroundSettlement(process: Pick<SandboxRetainedProcess, "state" | "exitCode" | "settlementReason">, fallback: RoutingRetainedProcessTerminalProof): {
+    outcome: "exited" | "lost";
+    exitCode: number | null;
+    reason: string;
+};
 export type ChannelARoutingServices = {
     db: Database;
     settings: Settings;
     bus?: EventBus;
     onSandboxOperation?: RoutingSandboxOperationObserver;
+    onSandboxCaptureWait?: RoutingSandboxCaptureWaitObserver;
     waitSignal?: AbortSignal;
 };
 /** Map the deployment relay URL to the leaf's `SelfhostedRelayConfig` shape. The
@@ -37,6 +55,7 @@ export declare function wrapChannelABoxWithRouting(services: ChannelARoutingServ
     accountId: string;
     workspaceId: string;
     sessionId: string;
+    resourceSubjectId: string;
     homeLease?: {
         sandboxGroupId: string;
         leaseEpoch: number;
@@ -55,3 +74,4 @@ export declare function wrapChannelABoxWithRouting(services: ChannelARoutingServ
         holderId: string;
     };
 }, established: EstablishedSandboxSession): EstablishedSandboxSession;
+export {};

package/dist/sandbox/runtime-settings.d.ts

@@ -0,0 +1,56 @@
+import { type Settings } from "@opengeni/config";
+import { type RigVersion, type Session, type SandboxBackend, type SandboxOs } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+import { resolveModalCheckpointProviderBinding } from "@opengeni/runtime/sandbox";
+export type ManagedSessionGroupBackend = Exclude<SandboxBackend, "none" | "selfhosted">;
+/**
+ * Resolve the provider backend behind a session's synthetic managed group.
+ *
+ * A machine-home session keeps `selfhosted` as its durable policy while a
+ * non-null active pointer selects the enrolled machine. Clearing that pointer
+ * is an explicit switch to the deployment's managed group, so API readiness,
+ * viewer attachment, Channel-A, and worker turns must all select the same
+ * provider. Deployments configured with `none` or `selfhosted` have no managed
+ * fallback to expose.
+ */
+export declare function managedSessionGroupBackend(deploymentBackend: SandboxBackend, sessionBackend: SandboxBackend): ManagedSessionGroupBackend | null;
+/** Display name and kind for the session's own managed box. The kind is the
+ * real provider. Callers must not collapse local, Docker, or other providers
+ * into Modal. */
+export declare function sessionGroupMachinePresentation(backend: ManagedSessionGroupBackend): {
+    name: string;
+    kind: ManagedSessionGroupBackend;
+};
+/** A machine-home row carries the machine's host OS; its managed group uses the
+ * platform's canonical managed-sandbox OS instead. Ordinary sessions preserve
+ * their explicitly selected OS. */
+export declare function managedSessionGroupOs(sessionBackend: SandboxBackend, sessionOs: SandboxOs): SandboxOs;
+/**
+ * Apply a workspace's selected sandbox image. The deployment keeps authority:
+ * only an image that is on its allowlist right now is used, so removing an
+ * entry returns every workspace that chose it to the deployment image. The
+ * lease treats the image as shared state, so a change rotates a live box
+ * through the normal capture-and-restore path instead of reusing it.
+ */
+export declare function settingsWithWorkspaceSandboxImage(settings: Settings, workspaceSettings: unknown, backend: SandboxBackend): Settings;
+export declare function settingsWithRigImage(settings: Settings, rigImage: string | null): Settings;
+export declare function rigProviderImageSourceImage(settings: Settings, backend: SandboxBackend): string | null;
+export type RigProviderImageSelectionReason = "selected" | "missing" | "provider_unsupported" | "not_ready" | "not_cold_boot_validated" | "content_mismatch" | "provider_binding_unavailable" | "provider_binding_mismatch";
+export declare function resolveRigProviderImageSelection(settings: Settings, version: RigVersion | null, backend: SandboxBackend, currentProviderBindingKeyHash: string | null): {
+    settings: Settings;
+    reason: RigProviderImageSelectionReason;
+    contentHash: string | null;
+    imageId: string | null;
+};
+export declare function resolveRigProviderImageForRun(settings: Settings, version: RigVersion | null, backend: SandboxBackend, resolveBinding?: typeof resolveModalCheckpointProviderBinding): Promise<ReturnType<typeof resolveRigProviderImageSelection>>;
+export declare function settingsWithRigProviderImage(settings: Settings, version: RigVersion | null, backend: SandboxBackend, resolveBinding?: typeof resolveModalCheckpointProviderBinding): Promise<Settings>;
+export type SessionSandboxRuntime = {
+    /** Exact logical image/rig settings used to fence the durable group lease. */
+    settings: Settings;
+    image: string | null;
+    rigVersion: RigVersion | null;
+};
+export declare function resolveSessionSandboxRuntime(db: Database, settings: Settings, session: Pick<Session, "workspaceId" | "sandboxBackend" | "rigId" | "rigVersionId">): Promise<SessionSandboxRuntime>;
+/** Resolve provider-native cold-create optimization only for the single CAS
+ * winner. Ordinary API calls never perform provider identity I/O. */
+export declare function providerSettingsForSessionSandboxRuntime(runtime: SessionSandboxRuntime, backend: SandboxBackend): Promise<Settings>;

package/dist/session-authorization.d.ts

@@ -1,7 +1,17 @@
-import { SessionAuthorizationActor, SessionAuthorizationListScope, type AccessGrant, type SessionAuthorizationOperation, type SessionAuthorizationSurface, type SessionAuthorizationTarget } from "@opengeni/contracts";
+import { SessionAuthorizationActor, SessionAuthorizationListScope, type AccessGrant, type SessionAgentAccess, type SessionAgentAccessViewer, type SessionAuthorizationOperation, type SessionAuthorizationSurface, type SessionAuthorizationTarget, type SessionScopeSubjectId } from "@opengeni/contracts";
 import { type Database, type SessionRlsActorContext } from "@opengeni/db";
 import type { AppDependencies } from "./dependencies.js";
 export type SessionAuthorizationDependencies = Pick<AppDependencies, "db" | "sessionAuthorization">;
+/** Scope read reuse to one request; it never outlives `fn`. */
+export declare function withSessionAuthorizationReadReuse<T>(fn: (reuse: {
+    handOffToToolDispatch(): void;
+}) => Promise<T>): Promise<T>;
+/**
+ * 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 declare function dispatchWithSessionAuthorizationReadReuse<T>(handler: () => T): T;
 /** Maximum time an omitted host hint leaves a live session stream unchecked. */
 export declare const SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS = 15000;
 export declare class SessionAuthorizationDeniedError extends Error {
@@ -19,6 +29,33 @@ export type ResolvedSessionAuthorization = {
     relatedSessionAccess: "target" | "root";
     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;
+};
+/**
+ * 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 declare function agentAccessPermitsCrossTreeAccess(caller: SessionAgentAccessFacts, target: SessionAgentAccessFacts): boolean;
+/**
+ * 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 declare function agentAccessListScopeForViewer(viewer: SessionAgentAccessViewer, hostScope?: SessionAuthorizationListScope | null): SessionAuthorizationListScope;
+/**
+ * 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 declare function grantHasAgentAttemptAuthority(grant: AccessGrant): boolean;
 export declare function sessionRlsActorForAuthorization(authorization: ResolvedSessionAuthorization): SessionRlsActorContext;
 export declare function withResolvedSessionAuthorization<T>(authorization: ResolvedSessionAuthorization, fn: () => Promise<T>): Promise<T>;
 /**

package/dist/site-session-origin.d.ts

@@ -0,0 +1,9 @@
+export type SiteSessionOrigin = {
+    siteId: string;
+    title: string;
+};
+/** Request-local provenance, set only after the API validates a published Site version. */
+export declare function withSiteSessionOrigin<T>(origin: SiteSessionOrigin, run: () => T): T;
+export declare function sessionCreationMetadata(metadata: Record<string, unknown>): Record<string, unknown>;
+/** The validated Site origin of the current request, if any. Provenance only. */
+export declare function currentSiteSessionOrigin(): SiteSessionOrigin | undefined;

package/dist/transcription.d.ts

@@ -28,6 +28,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 & {
     /** Server-private provider id for operational metrics only. Never returned to clients. */
@@ -39,23 +42,31 @@ export declare 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;
     });
 }
 export declare 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;
 };
 /**
  * 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/dist/turn-surface.d.ts

@@ -0,0 +1,18 @@
+import type { AccessGrant, SessionTurnSurface } from "@opengeni/contracts";
+import type { AccessGrantAuthorization } from "./access/index.js";
+/**
+ * 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 declare 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;

package/dist/user-presence.d.ts

@@ -0,0 +1,32 @@
+import { type Database } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+/**
+ * Throttled, batched server-side presence for managed humans.
+ *
+ * `touch` is called on the request path, so it only does an in-memory map
+ * check: each person is queued at most once per throttle window per process,
+ * and queued people are written in one batched database call after a short
+ * delay, never awaited by the request. API keys, services and embedded-host
+ * subjects are never passed here; anything outside the opaque `user:` shape is
+ * ignored. The database turns a new UTC day into the `user.active` lifecycle
+ * fact, and control workers read windowed counts for `opengeni_active_users`.
+ */
+export type UserPresenceRecorder = {
+    /** Note authenticated activity for one managed human. Never throws. */
+    touch(subjectId: string): void;
+    /** Write everything queued now. Resolves even when the write fails. */
+    flush(): Promise<void>;
+    /** Flush and stop scheduling further writes. */
+    close(): Promise<void>;
+};
+export declare const USER_PRESENCE_THROTTLE_MS = 60000;
+export declare const USER_PRESENCE_FLUSH_DELAY_MS = 5000;
+export declare function createUserPresenceRecorder(options: {
+    db: Database;
+    observability?: Pick<Observability, "incrementCounter" | "warn"> | undefined;
+    throttleMs?: number;
+    flushDelayMs?: number;
+    maxTracked?: number;
+    now?: () => number;
+    record?: (db: Database, subjectIds: readonly string[]) => Promise<number>;
+}): UserPresenceRecorder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.28.0",
+  "version": "1.0.0",
   "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": {
@@ -33,6 +33,10 @@
     "./canonical-human-identities": {
       "types": "./dist/canonical-human-identities.d.ts",
       "import": "./dist/canonical-human-identities.js"
+    },
+    "./managed-auth-session-sets": {
+      "types": "./dist/managed-auth-session-sets.d.ts",
+      "import": "./dist/managed-auth-session-sets.js"
     }
   },
   "publishConfig": {
@@ -46,16 +50,19 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/codex": "^0.2.16",
-    "@opengeni/config": "^0.16.1",
-    "@opengeni/contracts": "^0.50.0",
-    "@opengeni/db": "^0.36.0",
-    "@opengeni/documents": "^0.5.38",
-    "@opengeni/events": "^0.3.109",
-    "@opengeni/observability": "^0.7.5",
-    "@opengeni/runtime": "^0.23.0",
-    "@opengeni/storage": "^0.2.93",
-    "hono": "^4.12.18"
+    "@opengeni/capabilities": "1.0.0",
+    "@opengeni/codex": "1.0.0",
+    "@opengeni/config": "1.0.0",
+    "@opengeni/contracts": "1.0.0",
+    "@opengeni/db": "1.0.0",
+    "@opengeni/documents": "1.0.0",
+    "@opengeni/events": "1.0.0",
+    "@opengeni/network": "1.0.0",
+    "@opengeni/observability": "1.0.0",
+    "@opengeni/runtime": "1.0.0",
+    "@opengeni/storage": "1.0.0",
+    "hono": "^4.12.18",
+    "zod": "^4.2.1"
   },
   "engines": {
     "node": ">=18"

package/src/access/external-actor-authority.ts

@@ -0,0 +1,94 @@
+import type { Permission } from "@opengeni/contracts";
+
+export type ExternalAuthoritySnapshot = Readonly<{
+  accountId: string;
+  externalIdentityId: string;
+  identityStatus: "active" | "disabled" | "revoked";
+  identityRevision: number;
+  membershipStatus: "active" | "provisioning" | "suspended" | "revoked";
+  workspaceId: string;
+  permissions: readonly Permission[];
+}>;
+
+export type ExternalLinkAuthoritySnapshot = Readonly<{
+  id: string;
+  accountId: string;
+  externalIdentityId: string;
+  revision: number;
+  nativeSubjectId: string;
+  status: "pending" | "active" | "revoked" | "expired";
+  expiresAt: number | null;
+  permissions: readonly Permission[];
+  nativeAuthority: Readonly<{
+    subjectId: string;
+    accountId: string;
+    workspaceId: string;
+    active: boolean;
+    permissions: readonly Permission[];
+  }>;
+}>;
+
+/** Pure permission calculation over already authenticated, live snapshots.
+ * This does not authenticate assertions or establish provenance. Callers must
+ * read snapshots under their authorization fence, never from request JSON.
+ * Linked mode uses the native lane alone: external workspace permissions must
+ * not be unioned into that lane, nor must old external resources change owner.
+ */
+export function externalActorPermissions(input: {
+  accountId: string;
+  workspaceId: string;
+  keyActive: boolean;
+  keyAccountId: string;
+  keyPermissions: readonly Permission[];
+  external: ExternalAuthoritySnapshot;
+  linked?: {
+    expectedId: string;
+    expectedRevision: number;
+    authority: ExternalLinkAuthoritySnapshot;
+  };
+  now: number;
+}): Permission[] {
+  const external = input.external;
+  if (
+    !input.keyActive ||
+    input.keyAccountId !== input.accountId ||
+    external.accountId !== input.accountId ||
+    external.identityStatus !== "active" ||
+    external.membershipStatus !== "active" ||
+    !Number.isSafeInteger(external.identityRevision) ||
+    external.identityRevision < 1 ||
+    !Number.isFinite(input.now)
+  )
+    return [];
+  let ceiling: readonly Permission[];
+  if (input.linked) {
+    const { authority: link, expectedId, expectedRevision } = input.linked;
+    const native = link.nativeAuthority;
+    if (
+      !expectedId ||
+      link.id !== expectedId ||
+      link.accountId !== input.accountId ||
+      link.externalIdentityId !== external.externalIdentityId ||
+      link.status !== "active" ||
+      !Number.isSafeInteger(expectedRevision) ||
+      expectedRevision < 1 ||
+      link.revision !== expectedRevision ||
+      (link.expiresAt !== null &&
+        (!Number.isFinite(link.expiresAt) || link.expiresAt <= input.now)) ||
+      !native.active ||
+      link.nativeSubjectId.length > 1024 ||
+      !/^user:[^\r\n]+$(?![\s\S])/.test(link.nativeSubjectId) ||
+      native.subjectId !== link.nativeSubjectId ||
+      native.accountId !== input.accountId ||
+      native.workspaceId !== input.workspaceId
+    )
+      return [];
+    const delegation = new Set(link.permissions);
+    ceiling = native.permissions.filter((permission) => delegation.has(permission));
+  } else {
+    if (external.workspaceId !== input.workspaceId) return [];
+    ceiling = external.permissions;
+  }
+  const allowed = new Set(ceiling);
+  return [...new Set(input.keyPermissions)].filter((permission) => allowed.has(permission));
+}