@opengeni/api-router 0.30.1 → 1.0.0

package/dist/routes/sessions.d.ts

@@ -1,5 +1,5 @@
-import { ClientSessionEvent, SteerSessionMessageRequest, type SessionGoalRevision, type SessionAuthorizationOperation } from "@opengeni/contracts";
-import { type SessionDiscoveryCursor } from "@opengeni/db";
+import { ClientSessionEvent, SessionScopeSubjectId, SteerSessionMessageRequest, type SessionStatus, type WorkClaimSubjectFilter, type SessionGoalRevision, type SessionAuthorizationOperation } from "@opengeni/contracts";
+import { decodeSessionListCursor, type SessionDiscoveryCursor } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { type ViewerServices } from "../sandbox/viewer.js";
@@ -12,16 +12,54 @@ export declare function goalProposalMatchesExpectedRevision(revision: Pick<Sessi
  * host-managed mode; standalone deployments never consult this classifier.
  */
 export declare function sessionAuthorizationOperationForHttp(method: string, pathname: string, sessionId: string): SessionAuthorizationOperation | null;
+export declare function sessionTenancyHttpError(error: unknown): Error;
+export declare function sessionListQuery(query: Record<string, string>, allowCursor?: boolean): {
+    originSiteId: string | undefined;
+    limit: string | undefined;
+    parentSessionId: string | null | undefined;
+    cursor: ReturnType<typeof decodeSessionListCursor> | undefined;
+    search: string | undefined;
+    pinsOnly: boolean;
+    includePinned: boolean;
+    includeTotals: boolean;
+    needsYouOnly: boolean;
+    archivedOnly: boolean;
+    sortBy: "updatedAt" | "createdAt" | "name" | undefined;
+    archiveStatus: "active" | "archived" | "all" | undefined;
+    channelId: string | null | undefined;
+    createdBy: {
+        kind: "subject" | "service";
+        subjectId: string;
+    } | undefined;
+    updatedFrom: Date | undefined;
+    updatedBefore: Date | undefined;
+    createdFrom: Date | undefined;
+    createdBefore: Date | undefined;
+    scopeSubjectId: SessionScopeSubjectId | undefined;
+    hasPageFilters: boolean;
+};
 export type AgentTopologyCursorEnvelope = {
     cursor: SessionDiscoveryCursor;
-    parentSessionId: string | null;
-    search: string | null;
+    parentSessionId: string | null | "all";
+    rootSessionId: string | null;
+    query: string | null;
+    statuses: SessionStatus[];
+    activeOnly: boolean;
+    recentHours: number | null;
+    subject: WorkClaimSubjectFilter | null;
+    claimLimit: number | null;
 };
 export declare function encodeAgentTopologyCursor(value: AgentTopologyCursorEnvelope): string;
 export declare function agentTopologyQuery(query: Record<string, string>): {
     limit: number;
-    parentSessionId: string | null;
-    search: string | undefined;
+    parentSessionId: string | null | undefined;
+    rootSessionId: string | undefined;
+    query: string | undefined;
+    statuses: SessionStatus[] | undefined;
+    activeOnly: boolean;
+    recentHours: number | undefined;
+    subject: WorkClaimSubjectFilter | undefined;
+    claimLimit: number | undefined;
     cursor: SessionDiscoveryCursor | undefined;
 };
 /** Stable, value-free JSON errors for only the create-session boundary. */

package/dist/routes/skill-content.d.ts

@@ -0,0 +1,4 @@
+import type { Hono } from "hono";
+import { type ApiRouteDeps } from "@opengeni/core";
+/** Human folder editing and the legacy Skill admin share scope authorization. */
+export declare function registerSkillContentRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/skill-install-authority.d.ts

@@ -0,0 +1,6 @@
+import { type SkillActor as SkillActorType } from "@opengeni/contracts";
+import { type AccessGrantAuthorization } from "@opengeni/core";
+/** Use authenticated request provenance, never a caller-supplied actor or subject alone. */
+export declare function skillInstallerActor(access: AccessGrantAuthorization): SkillActorType;
+/** Non-Skill component removals remain available to their existing callers. */
+export declare function skillRemovalActor(access: AccessGrantAuthorization): SkillActorType | undefined;

package/dist/routes/subscription-account-pools.d.ts

@@ -0,0 +1,34 @@
+import type { listOrganizationXaiSubscriptions, updateOrganizationXaiSubscription, updateOrganizationXaiRotation, listXaiSubscriptionAccountsMetadata, getXaiRotationSettings, ensureXaiRotationSettings, getXaiSubscriptionAccountAuthoritySnapshot, resolveXaiProviderAccountAuthoritySnapshotForAcceptance, setActiveXaiCredential, updateXaiRotationSettings, updateXaiAllocatorEligibility, renameXaiSubscriptionAccount, disconnectXaiSubscriptionCredentialAndRepick, wakeXaiCapacityWaiters, XaiSubscriptionAccountMetadata } from "@opengeni/db";
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+type PoolRepository = {
+    listOrganizationSubscriptions: typeof listOrganizationXaiSubscriptions;
+    updateOrganizationSubscription: typeof updateOrganizationXaiSubscription;
+    updateOrganizationSubscriptionRotation: typeof updateOrganizationXaiRotation;
+    listSubscriptionAccountsMetadata: typeof listXaiSubscriptionAccountsMetadata;
+    getSubscriptionRotationSettings: typeof getXaiRotationSettings;
+    ensureSubscriptionRotationSettings: typeof ensureXaiRotationSettings;
+    getSubscriptionAccountAuthoritySnapshot: typeof getXaiSubscriptionAccountAuthoritySnapshot;
+    resolveSubscriptionProviderAccountAuthoritySnapshotForAcceptance: typeof resolveXaiProviderAccountAuthoritySnapshotForAcceptance;
+    setActiveSubscriptionCredential: typeof setActiveXaiCredential;
+    updateSubscriptionRotationSettings: typeof updateXaiRotationSettings;
+    updateSubscriptionAllocatorEligibility: typeof updateXaiAllocatorEligibility;
+    renameSubscriptionAccount: typeof renameXaiSubscriptionAccount;
+    disconnectSubscriptionCredentialAndRepick: typeof disconnectXaiSubscriptionCredentialAndRepick;
+    wakeSubscriptionCapacityWaiters: typeof wakeXaiCapacityWaiters;
+};
+/** Account CRUD uses one authority, allocator and wake contract for every pool. */
+export declare function registerSubscriptionAccountPoolRoutes(app: Hono, deps: ApiRouteDeps, options: {
+    provider: "xai" | "claude";
+    route: "supergrok" | "claude";
+    displayName: "SuperGrok" | "Claude";
+    enabled: () => boolean;
+    repository: PoolRepository;
+    accountJson: (account: XaiSubscriptionAccountMetadata, activeId: string | null) => Record<string, unknown>;
+    projectAccounts?: (accounts: XaiSubscriptionAccountMetadata[], activeId: string | null, authority: {
+        accountId: string;
+        workspaceId: string | null;
+        subjectId: string;
+    }) => Promise<Record<string, unknown>[]>;
+}): void;
+export {};

package/dist/routes/subscription-pool-access.d.ts

@@ -0,0 +1,16 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Context } from "hono";
+type ManagedCookieHuman = {
+    subjectId: string;
+};
+export declare function managedCookieHuman(c: Context, deps: ApiRouteDeps): Promise<ManagedCookieHuman | null>;
+export declare function requireSameOriginBrowserMutation(c: Context, deps: ApiRouteDeps): void;
+export declare function requirePrivateSubscriptionHuman(c: Context, deps: ApiRouteDeps, workspaceId: string, displayName: string): Promise<{
+    accountId: string;
+    subjectId: string;
+}>;
+export declare function requireSubscriptionScopeMutation(c: Context, deps: ApiRouteDeps, workspaceId: string, scope: "workspace" | "user" | "organization", displayName: string): Promise<{
+    accountId: string;
+    subjectId: string;
+}>;
+export {};

package/dist/routes/supergrok.d.ts

@@ -1,3 +1,8 @@
+export { managedCookieHuman } from "./subscription-pool-access.js";
 import { type ApiRouteDeps } from "@opengeni/core";
-import type { Hono } from "hono";
+import type { Context, Hono } from "hono";
+export declare const requireScopeMutation: (c: Context, deps: ApiRouteDeps, workspaceId: string, scope: "workspace" | "user" | "organization") => Promise<{
+    accountId: string;
+    subjectId: string;
+}>;
 export declare function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/usage-allowances.d.ts

@@ -0,0 +1,12 @@
+import type { Hono } from "hono";
+import { type AccessContext } from "@opengeni/contracts";
+import { type AccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
+type Authority = {
+    authorization: AccessGrantAuthorization;
+    context: AccessContext;
+};
+type Operation = "read" | "budget-read" | "workspace-write" | "member-write" | "own";
+/** No workspace wildcard, service initiator, or actor label can confer budget authority. */
+export declare function requireAllowanceAuthority({ authorization, context }: Authority, operation: Operation): void;
+export declare function registerUsageAllowanceRoutes(app: Hono, deps: ApiRouteDeps): void;
+export {};

package/dist/routes/user-resource-authorities.d.ts

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerUserResourceAuthorityRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/workspace-artifacts.d.ts

@@ -1,3 +1,4 @@
 import { type ApiRouteDeps } from "@opengeni/core";
-import type { Hono } from "hono";
+import type { Context, Hono } from "hono";
+export declare function workspaceArtifactErrorResponse(context: Context, error: unknown): Response;
 export declare function registerWorkspaceArtifactRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/workspace-capture.d.ts

@@ -46,7 +46,15 @@ export declare class WorkspaceCaptureManifestCache {
  * manifest blob has been GC'd (all graceful cold-fallback states — never errors).
  * Inline manifest for ≤2MB, signed URL above.
  */
-export declare function serveWorkspaceCapture(row: WorkspaceCaptureRow | null, storage: CaptureStoragePort, cache?: WorkspaceCaptureManifestCache): Promise<GetWorkspaceCaptureResponse>;
+/** Awaited before a signed capture URL is returned to the caller: the route
+ *  records the metadata-only issuance audit fact. A throwing recorder fails
+ *  the serve closed - no recorded fact, no bearer capability. */
+export type CaptureSignedUrlIssuanceRecorder = (fact: {
+    kind: "capture_manifest" | "capture_file";
+    revision: number;
+    expiresAt: string;
+}) => Promise<void>;
+export declare function serveWorkspaceCapture(row: WorkspaceCaptureRow | null, storage: CaptureStoragePort, cache?: WorkspaceCaptureManifestCache, onSignedUrlIssued?: CaptureSignedUrlIssuanceRecorder): Promise<GetWorkspaceCaptureResponse>;
 /**
  * Shape the GET …/workspace/capture/file response from a loaded row (the row
  * already resolved to the requested revision, or the latest). Throws
@@ -55,5 +63,5 @@ export declare function serveWorkspaceCapture(row: WorkspaceCaptureRow | null, s
  * a captured file whose after-image blob is missing). Inline content for ≤256KB,
  * signed URL above.
  */
-export declare function serveWorkspaceCaptureFile(row: WorkspaceCaptureRow | null, path: string, storage: CaptureStoragePort): Promise<GetWorkspaceCaptureFileResponse>;
+export declare function serveWorkspaceCaptureFile(row: WorkspaceCaptureRow | null, path: string, storage: CaptureStoragePort, onSignedUrlIssued?: CaptureSignedUrlIssuanceRecorder): Promise<GetWorkspaceCaptureFileResponse>;
 export {};

package/dist/routes/workspace-integrations.d.ts

@@ -0,0 +1,35 @@
+import { WorkspaceWebhookDelivery, type AccessGrant } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+import { type WorkspaceCredentialProviderRow, type WorkspaceWebhookDeliveryRow, type WorkspaceWebhookRow } from "@opengeni/db";
+import { type pinnedFetch } from "@opengeni/network";
+import type { Context, Hono } from "hono";
+import { z } from "zod";
+export declare function newIntegrationSecret(prefix: string): string;
+export declare function integrationWebhookFields(row: Omit<WorkspaceWebhookRow, "workspaceId">): {
+    id: string;
+    url: string;
+    eventTypes: string[];
+    enabled: boolean;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare function integrationDeliveryProjection(row: WorkspaceWebhookDeliveryRow): WorkspaceWebhookDelivery;
+export declare function integrationProviderFields(row: Omit<WorkspaceCredentialProviderRow, "workspaceId">): {
+    url: string;
+    enabled: boolean;
+    timeoutMs: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare function integrationBody<T extends z.ZodTypeAny>(c: Context, schema: T, invalidStatus?: 400 | 422): Promise<z.output<T>>;
+export declare function integrationRouteConfiguration(deps: ApiRouteDeps, scope: "workspace" | "organization"): {
+    requireKey(): Uint8Array;
+    requireDeployableUrl(url: string): void;
+};
+export declare function isIntegrationAgent(grant: Pick<AccessGrant, "principalKind" | "metadata">): boolean;
+export type WorkspaceIntegrationRouteOptions = {
+    /** Tests inject a fetch; production uses the pinned outbound client. */
+    fetch?: typeof pinnedFetch;
+};
+export declare function registerWorkspaceIntegrationRoutes(app: Hono, deps: ApiRouteDeps, options?: WorkspaceIntegrationRouteOptions): void;

package/dist/routes/workspace-learning.d.ts

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerWorkspaceLearningRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/workspace-model-providers.d.ts

@@ -0,0 +1,4 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+/** Workspace-owned Claude models use the same immutable-generation protocol as gateway models. */
+export declare function registerWorkspaceModelProviderRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/workspaces.d.ts

@@ -1,5 +1,34 @@
+import { type AccessContext, type WorkspaceMember as WorkspaceMemberValue } from "@opengeni/contracts";
 import type { Hono } from "hono";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { type Settings } from "@opengeni/config";
 export declare function canonicalWorkspacePolicyModelIds(settings: Settings, modelIds: string[] | null | undefined): string[] | null;
+type WorkspaceMemberProjectionInput = Omit<WorkspaceMemberValue, "permissions"> & {
+    permissions: unknown;
+};
+/**
+ * Keep the roster readable across stored-permission contract changes. Unknown
+ * values are never re-authorized: they are omitted from the public projection,
+ * while every currently recognized permission is preserved in stored order.
+ */
+export declare function workspaceMembersResponse(members: readonly WorkspaceMemberProjectionInput[]): {
+    members: {
+        subjectId: string;
+        subjectLabel: string | null;
+        role: string;
+        permissions: ("account:admin" | "account:read" | "api_keys:manage" | "artifacts:publish" | "artifacts:read" | "billing:manage" | "billing:read" | "capabilities:manage" | "codemode:call" | "connections:read" | "connections:write" | "documents:manage" | "documents:search" | "enrollments:manage" | "enrollments:read" | "environments:manage" | "environments:use" | "files:read" | "files:upload" | "files:write" | "github:manage" | "github:use" | "goals:manage" | "mcp_servers:attach" | "members:manage" | "rigs:manage" | "rigs:use" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "secrets:list" | "secrets:read" | "secrets:write" | "sessions:control" | "sessions:create" | "sessions:read" | "stream:acknowledge" | "stream:control" | "stream:view" | "terminal:attach" | "usage_allowances:manage" | "variable-sets:attach" | "variable-sets:list" | "variable-sets:manage" | "variable-sets:read" | "variable-sets:use" | "variable-sets:write" | "workspace:admin" | "workspace:create" | "workspace:read")[];
+        createdAt: string;
+    }[];
+};
+export declare function workspaceUpdateRequestsSettings(value: unknown): boolean;
+export declare function workspaceUpdateRequestsAccountTransfer(value: unknown): boolean;
+/**
+ * Owning organization for `PUT /v1/workspaces/external`. An organization API
+ * key can only ever create workspaces in its own organization, so an omitted
+ * `accountId` resolves to that organization. Every other caller - notably a
+ * human who may belong to several organizations - must name it explicitly;
+ * guessing a default there could create the workspace in the wrong tenant.
+ */
+export declare function externalWorkspaceAccountId(context: AccessContext, requested: string | undefined): string;
 export declare function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void;
+export {};

package/dist/sandbox/auth-callout.d.ts

@@ -1,3 +1,4 @@
+import { type LogThrottle } from "@opengeni/observability";
 import { type NatsCalloutConfig, type Settings } from "@opengeni/config";
 import { type Database } from "@opengeni/db";
 import { type ResponderConnection } from "@opengeni/events";
@@ -11,7 +12,14 @@ export interface AuthCalloutDeps {
     settings: Settings;
     callout: NatsCalloutConfig;
     observability?: Observability;
+    /** Bounds repeated denial warnings; defaults to one process-wide throttle. */
+    denialWarningThrottle?: LogThrottle;
 }
+/** A stale or revoked machine re-dials on its reconnect backoff forever, so an
+ * unthrottled denial warning repeats every few seconds per machine. Log each
+ * distinct machine's first denial, then at most once per interval with the
+ * count of denials it hid. The denial decision itself is never throttled. */
+export declare const AUTH_CALLOUT_DENIAL_WARNING_INTERVAL_MS = 60000;
 /**
  * The pure validate→scoped-JWT decision, isolated from the NATS transport so it is
  * unit-testable. Given the raw authorization-request JWT bytes, returns the signed

package/dist/sandbox/channel-a.d.ts

@@ -3,14 +3,16 @@ import type { Session } from "@opengeni/contracts";
 import { type Database, type LeaseSnapshot } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
 import { type Observability } from "@opengeni/observability";
+import type { ObjectStorage } from "@opengeni/storage";
 import { SandboxChannelAService, type ChannelASession, type EstablishedSandboxSession, type RoutingSandboxSession } from "@opengeni/runtime/sandbox";
 export type ChannelAServices = {
     db: Database;
     settings: Settings;
     bus: EventBus;
+    objectStorage?: ObjectStorage | null;
     observability?: Observability | undefined;
 };
-export type ChannelAOperation = "fs.list" | "fs.list-batch" | "fs.read" | "fs.write" | "fs.delete" | "fs.move" | "fs.mkdir" | "git.status" | "git.diff" | "git.read-batch" | "git.log" | "git.show" | "terminal.exec" | "terminal.pty.open" | "terminal.pty.write" | "terminal.pty.resize" | "terminal.pty.close" | "browser.create" | "browser.resume" | "browser.suspend" | "browser.end" | "browser.read" | "browser.action" | "browser.control" | "browser.download.save" | "browser.attach" | "computer.create" | "computer.end" | "computer.read" | "computer.action" | "computer.control" | "computer.attach";
+export type ChannelAOperation = "fs.list" | "fs.list-batch" | "fs.read" | "artifact.publish" | "fs.write" | "fs.delete" | "fs.move" | "fs.mkdir" | "git.status" | "git.diff" | "git.read-batch" | "git.log" | "git.show" | "terminal.exec" | "terminal.pty.open" | "terminal.pty.write" | "terminal.pty.resize" | "terminal.pty.close" | "browser.create" | "browser.resume" | "browser.suspend" | "browser.end" | "browser.read" | "browser.action" | "browser.control" | "browser.download.save" | "browser.attach" | "computer.create" | "computer.end" | "computer.read" | "computer.action" | "computer.control" | "computer.attach";
 export type ChannelAContext = {
     accountId: string;
     workspaceId: string;
@@ -25,6 +27,10 @@ export type ChannelAContext = {
      * provider handle and replay the request. Tab/lifecycle mutations that lack
      * a controller operation id must never opt into this recovery. */
     retryControllerTransport?: boolean | undefined;
+    /** Ephemeral browser callbacks must never replay after an ambiguous result. */
+    allowOperationReplay?: boolean | undefined;
+    /** Exact existing interaction provider; may not spawn/rotate on image drift. */
+    retainedInstanceId?: string | undefined;
 };
 export type ChannelAOperationFailureReason = "request_cancelled" | "provider_read_busy" | "provider_unavailable" | "lifecycle_conflict" | "request_rejected" | "unexpected";
 export type ChannelAOperationFailureDiagnostic = {
@@ -63,6 +69,8 @@ type ChannelAReadRecoveryOptions = {
     /** Modal may expose one more stale command-router route after the first
      * successful handle rebuild. Keep this closed and statically bounded. */
     maxFreshHandleRetries?: 1 | 2;
+    /** Explicit opt-out overrides every transport/provider retry classification. */
+    allowOperationReplay?: boolean | undefined;
     /** Never start another provider attempt after the originating request ends. */
     waitSignal?: AbortSignal | undefined;
     /** Additional callback-specific failure that is safe to replay. */
@@ -100,4 +108,14 @@ export declare function isChannelARequestCancellation(error: unknown, waitSignal
 /** Structural classification only: exact provider exception text, codes, URLs,
  * and identifiers never cross the telemetry boundary. */
 export declare function channelAOperationFailureDiagnostic(error: unknown, waitSignal?: AbortSignal): ChannelAOperationFailureDiagnostic;
+/** Exported for the telemetry contract tests; not a route surface. */
+export declare function observeChannelAOperationFailure(services: ChannelAServices, input: {
+    workspaceId: string;
+    sandboxGroupId: string;
+    backend: string;
+    operation: string;
+    durationMs: number;
+    error: unknown;
+    waitSignal?: AbortSignal | undefined;
+}): void;
 export {};

package/dist/sandbox/connection-authority.d.ts

@@ -0,0 +1,3 @@
+/** Five-second heartbeats get four missed intervals before another daemon may
+ * claim the enrollment. Server time is authoritative. */
+export declare const AGENT_CONNECTION_LEASE_MS = 20000;

package/dist/sandbox/enrollment.d.ts

@@ -1,10 +1,16 @@
 import { type Settings } from "@opengeni/config";
-import { type DeviceEnrollmentLookupResponse, type DeviceEnrollmentPollResponse, type DeviceEnrollmentStartResponse, type EnrollTokenExchangeResponse, type MintEnrollTokenResponse } from "@opengeni/contracts";
+import { type RenewEnrollmentRequest, type DeviceEnrollmentLookupResponse, type DeviceEnrollmentPollResponse, type DeviceEnrollmentStartResponse, type EnrollmentCredentialsResponse, type EnrollTokenExchangeResponse, type MintEnrollTokenResponse } from "@opengeni/contracts";
 import { type Database, type DeviceEnrollmentRequestRecord, type EnrollmentOs } from "@opengeni/db";
 export declare const DEVICE_CODE_TTL_SECONDS = 600;
 export declare const DEVICE_POLL_INTERVAL_SECONDS = 5;
 export declare const ENROLLMENT_BEARER_TTL_SECONDS: number;
 export declare const RELAY_TOKEN_TTL_SECONDS: number;
+/** Renew an existing grant, including after a long offline interval. The expired
+ * bearer is only an authenticated enrollment/generation locator here: current
+ * install-key possession and live enrollment authority are both required. Normal
+ * NATS/relay authentication continues to reject expired transport credentials.
+ * Nothing creates/reactivates an enrollment or changes its consent or scope. */
+export declare function renewEnrollmentCredentials(services: EnrollmentServices, input: RenewEnrollmentRequest, nowSeconds?: number): Promise<EnrollmentCredentialsResponse | null>;
 export declare const ENROLL_TOKEN_TTL_SECONDS = 3600;
 export type EnrollmentServices = {
     db: Database;
@@ -35,6 +41,8 @@ export declare function startDeviceEnrollment(services: EnrollmentServices, inpu
 export declare function approveDeviceEnrollment(services: EnrollmentServices, input: {
     accountId: string;
     workspaceId: string;
+    scope?: "organization" | "workspace" | "user";
+    allowOrganization?: boolean;
     userCode: string;
     allowScreenControl: boolean;
     approvedBySubjectId: string;

package/dist/sandbox/machines.d.ts

@@ -1,12 +1,13 @@
 import type { Settings } from "@opengeni/config";
 import { type Database, type MachineMetricsRow } from "@opengeni/db";
-import type { EventBus } from "@opengeni/events";
 import { MetricSample, type MachinesResponse } from "@opengeni/contracts";
 export type MachinesServices = {
     db: Database;
     settings: Settings;
-    bus?: EventBus;
 };
+/** Older Mac updaters replace a single file inside a sealed app. They must
+ * bootstrap once through the official whole-app installer, never an RPC swap. */
+export declare function machineUpdateBlockedReason(os: string, version: string | null): string | null;
 /**
  * Project a stored `machine_metrics_latest` row to the contract `MetricSample`.
  * The DB carries `gpuUtilPercent` + `gpuMemUsedBytes`/`gpuMemTotalBytes`; the wire
@@ -24,6 +25,8 @@ export declare function metricRowToSample(row: MachineMetricsRow): MetricSample;
  * the enrolled machines are listed.
  */
 export declare function listMachines(services: MachinesServices, input: {
+    accountId?: string;
     workspaceId: string;
+    subjectId?: string;
     sessionId?: string | null;
 }): Promise<MachinesResponse>;

package/dist/sandbox/metrics-ingestion.d.ts

@@ -4,18 +4,36 @@ import { type EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
 import { Hello, type AttachedBrowserInventorySnapshot as WireAttachedBrowserInventorySnapshot, type MetricsSample } from "@opengeni/agent-proto";
 /** The wildcard subject the agent event plane publishes heartbeats on. */
-export declare const AGENT_EVENTS_SUBJECT = "agent.*.*.events";
+export declare const AGENT_EVENTS_SUBJECT = "agent.*.*.connection.*.events";
 /** The wildcard subject the agent publishes its connect Hello on. */
-export declare const AGENT_HELLO_SUBJECT = "agent.*.*.hello";
-/** Parse `agent.<ws>.<id>.events` → `{ workspaceId, agentId }` (heartbeat plane). */
+export declare const AGENT_HELLO_SUBJECT = "agent.*.*.connection.*.hello";
+export type AgentEventIngestionScheduler = {
+    enqueue: (payload: Uint8Array, subject: string) => void;
+    whenIdle: () => Promise<void>;
+    close: () => void;
+};
+/**
+ * Drain agent events without making every Connected Machine wait behind one
+ * deployment-wide serial DB queue. Each exact process subject retains FIFO order;
+ * separate subjects drain concurrently. Consecutive pending heartbeats for one
+ * subject are latest-wins because they are point-in-time liveness/metrics samples,
+ * while GoingOffline and update-progress events remain ordered barriers.
+ */
+export declare function createAgentEventIngestionScheduler(handler: (payload: Uint8Array, subject: string) => void | Promise<void>, options?: {
+    maxConcurrentSubjects?: number;
+    onHeartbeatCoalesced?: () => void;
+}): AgentEventIngestionScheduler;
+/** Parse the exact process events subject (heartbeat plane). */
 export declare function parseAgentEventSubject(subject: string): {
     workspaceId: string;
     agentId: string;
+    connectionInstanceId: string;
 } | null;
-/** Parse `agent.<ws>.<id>.hello` → `{ workspaceId, agentId }` (connect plane). */
+/** Parse the exact process hello subject (connect plane). */
 export declare function parseAgentHelloSubject(subject: string): {
     workspaceId: string;
     agentId: string;
+    connectionInstanceId: string;
 } | null;
 /**
  * Project a wire `MetricsSample` (proto, ms-stamped, GPU as a repeated list) to
@@ -32,20 +50,6 @@ export declare function wireSampleToDbSample(wire: MetricsSample): MachineMetric
  *  discovery. Unknown enum values and unsafe uint64 counters reject the whole
  *  authoritative snapshot instead of partially disconnecting good endpoints. */
 export declare function wireAttachedBrowserInventoryToContract(wire: WireAttachedBrowserInventorySnapshot): AttachedBrowserInventoryContractValue;
-/**
- * Ingest ONE decoded heartbeat for an enrolled machine. Resolves the enrollment's
- * accountId (needed for the RLS-scoped writes) from the enrollment row; an
- * unknown/cross-workspace agentId is ignored (no row → no write). Touches
- * last-seen + upserts latest + downsamples the series.
- */
-export declare function ingestHeartbeat(db: Database, input: {
-    workspaceId: string;
-    agentId: string;
-    sample: MetricsSample;
-}): Promise<{
-    ingested: boolean;
-    seriesAppended: boolean;
-}>;
 /**
  * Decode a raw `AgentEvent` payload + ingest it (the per-message handler). A
  * heartbeat carrying a metrics sample is ingested; a going-offline records the
@@ -55,7 +59,7 @@ export declare function ingestHeartbeat(db: Database, input: {
  */
 export declare function handleAgentEventPayload(db: Database, observability: Observability | undefined, payload: Uint8Array, subject: string, bus?: EventBus): Promise<void>;
 /**
- * Start the metrics-ingestion consumer: subscribe `agent.*.*.events` and ingest
+ * Start the metrics-ingestion consumer: subscribe exact process events and ingest
  * every heartbeat. Gated by sandboxSelfhostedEnabled (the caller checks the flag;
  * a disabled deployment never starts the consumer). Returns the unsubscribe fn.
  */
@@ -82,6 +86,7 @@ export declare function helloReportsDisplay(hello: Hello): boolean;
 export declare function helloDesktopUnavailableReason(hello: Hello): string | null;
 /** Whether the runner's current Hello advertises the op-stream engine. */
 export declare function helloReportsOpStream(hello: Hello): boolean;
+export declare function helloRuntimeCapabilities(hello: Hello): Record<string, boolean>;
 /**
  * Reconcile `enrollments.has_display` (+ the capture-blocked reason) to what a Hello
  * reports. Resolves the enrollment (the accountId is the RLS principal + the
@@ -95,6 +100,8 @@ export declare function refreshEnrollmentDisplay(db: Database, input: {
     agentId: string;
     hasDisplay: boolean;
     desktopUnavailableReason?: string | null;
+    runtimeDesktop?: boolean;
+    connectionInstanceId?: string;
 }): Promise<{
     updated: boolean;
 }>;
@@ -108,6 +115,7 @@ export declare function refreshEnrollmentOpStream(db: Database, input: {
     workspaceId: string;
     agentId: string;
     opStream: boolean;
+    connectionInstanceId?: string;
 }): Promise<{
     updated: boolean;
 }>;
@@ -121,7 +129,7 @@ export declare function refreshEnrollmentOpStream(db: Database, input: {
  */
 export declare function handleHelloPayload(db: Database, observability: Observability | undefined, payload: Uint8Array, subject: string, bus?: EventBus): Promise<void>;
 /**
- * Start the Hello display-refresh consumer: subscribe `agent.*.*.hello` and
+ * Start the Hello display-refresh consumer: subscribe exact process hellos and
  * reconcile `has_display` to the live capability the agent reports on every
  * connect. Gated by sandboxSelfhostedEnabled (the caller checks the flag). Returns
  * the unsubscribe fn.

package/dist/sandbox/rematerialize.d.ts

@@ -1,6 +1,7 @@
 import type { Settings } from "@opengeni/config";
 import { type Database, type LeaseSnapshot } from "@opengeni/db";
 import { type EstablishedSandboxSession } from "@opengeni/runtime/sandbox";
+import { type ObjectStorage } from "@opengeni/storage";
 /** The sole API-direct cold->warming owner path used by Channel A and viewer
  * attach. It never publishes warm until archive identity, hydrated tree, command
  * routing, provider identity, and the selected rematerialization attempt all
@@ -18,6 +19,7 @@ export declare function establishApiSandboxSpawner(input: {
     acquiredLease: LeaseSnapshot;
     fallbackEnvelope: Record<string, unknown> | null;
     dataPlaneUrl: string | null;
+    objectStorage?: ObjectStorage | null;
 }): Promise<{
     established: EstablishedSandboxSession;
     lease: LeaseSnapshot;

package/dist/sandbox/session-attach-variable-sets.d.ts

@@ -0,0 +1,30 @@
+import type { Settings } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+export type SessionAttachVariableSetSession = {
+    id: string;
+    rigId?: string | null | undefined;
+    rigVersionId?: string | null | undefined;
+    variableSetIds?: readonly string[] | null | undefined;
+    /** Legacy final-entry alias for projections that predate the plural field. */
+    variableSetId?: string | null | undefined;
+};
+/**
+ * Decrypted Variable Set values for a direct session attach (terminal, Files,
+ * Git, desktop viewer), in the same order and precedence as the worker turn:
+ * the frozen Sandbox Environment version defaults first, then the session's
+ * own selection, so a box first warmed by an attach declares exactly the
+ * environment the next turn declares.
+ *
+ * A Variable Set the session can no longer use (the database seam answers
+ * 42501 and records a `variable_set.materialize.denied` fact) becomes a 403
+ * instead of a bare 500. Every failure is logged with the session, set, source
+ * and SQLSTATE, never a value.
+ */
+export declare function loadSessionAttachVariableSetValues(db: Database, settings: Settings, input: {
+    accountId: string;
+    workspaceId: string;
+    session: SessionAttachVariableSetSession;
+    /** The authenticated route subject driving the attach; null records the
+     *  legacy service sentinel on the materialization audit fact. */
+    subjectId: string | null;
+}): Promise<Record<string, string>>;