@opengeni/core 3.0.1 → 3.1.2

package/dist/managed-session.d.ts

@@ -1,22 +1,125 @@
 import type { Context } from "hono";
 import type { ManagedAuth } from "./managed-auth-type.js";
-import type { Database } from "@opengeni/db";
+import { type Database } from "@opengeni/db";
 import type { ManagedAuthSessionSetMode } from "@opengeni/contracts/managed-auth-session-sets";
 import { type ManagedAuthSessionAdapter } from "./managed-auth-session-sets.js";
+/** Better Auth `logger.log` sink; a no-op outside a managed-auth session lookup. */
+export declare function recordManagedAuthLoggedFailure(args: readonly unknown[]): void;
+export declare function withManagedAuthSessionLookup<T>(lookup: () => Promise<T>): Promise<T>;
 type ActorMutationLeaseRuntime = {
     monotonicNow: () => number;
     schedule: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
     cancel: (timer: ReturnType<typeof setTimeout>) => void;
     terminate: () => void;
 };
+/** Bind admission to this auth instance, including all session-set modes. */
+export declare function configureManagedUserAdmission(auth: ManagedAuth, emails: readonly string[] | undefined): void;
+export declare function getManagedSession(...args: Parameters<typeof resolveManagedSession>): Promise<import("./managed-auth-session-sets.js").ManagedAuthResolvedSession | {
+    session: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        userId: string;
+        expiresAt: Date;
+        token: string;
+        ipAddress?: string | null | undefined;
+        userAgent?: string | null | undefined;
+    } | {
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        userId: string;
+        expiresAt: Date;
+        token: string;
+        ipAddress?: string | null | undefined;
+        userAgent?: string | null | undefined;
+    };
+    user: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+    } | {
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+    };
+} | null>;
+/**
+ * Bearer prefix of a native app credential. The credential is a dedicated
+ * Better Auth session the person approved from a signed-in browser (see the
+ * native app sign-in route); the prefix only routes it to this resolver.
+ */
+export declare const NATIVE_APP_CREDENTIAL_PREFIX = "ogapp_";
 /**
- * Read a Better Auth session without bypassing its sliding-cookie renewal.
- *
- * Better Auth can refresh the durable session while resolving `getSession`.
- * Programmatic callers must explicitly request and forward the returned cookie
- * headers; the HTTP handler does this automatically, but direct API calls do not.
+ * Resolve a native app credential exactly as the legacy managed cookie path
+ * resolves a browser session: Better Auth validates expiry and renews the
+ * durable session, then the canonical human session must still be valid. A
+ * native credential never reads or selects a browser session set; each app
+ * account holds its own independently revocable session.
  */
-export declare function getManagedSession(c: Context, auth: ManagedAuth, options?: {
+export declare function getNativeAppManagedSession(auth: ManagedAuth, credential: string, db: Database | undefined): Promise<{
+    session: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        userId: string;
+        expiresAt: Date;
+        token: string;
+        ipAddress?: string | null | undefined;
+        userAgent?: string | null | undefined;
+    } | {
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        userId: string;
+        expiresAt: Date;
+        token: string;
+        ipAddress?: string | null | undefined;
+        userAgent?: string | null | undefined;
+    };
+    user: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+    } | {
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+    };
+} | null>;
+export declare function assertManagedUserAdmission(auth: ManagedAuth, user: {
+    email: string;
+    emailVerified: boolean;
+} | null | undefined): void;
+declare function resolveManagedSession(c: Context, auth: ManagedAuth, options?: {
     db?: Database | undefined;
     allowIdentityRecovery?: boolean | undefined;
     sessionSetMode?: ManagedAuthSessionSetMode | undefined;

package/dist/model-call.d.ts

@@ -0,0 +1,58 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import type { SingleModelCallRequest, SingleModelCallResult } from "@opengeni/runtime";
+/**
+ * Stateless single model calls: one request to one workspace model with no
+ * tools, no agent loop and no session. The public chat completions endpoint
+ * is the transport; agentic work uses sessions. The host-owned service picks
+ * the model, credential and subscription account exactly as a turn would,
+ * admits the call against the same funding rules and settles actual usage.
+ */
+export type ModelCallCaller = {
+    grant: AccessGrant;
+    accountId: string;
+    workspaceId: string;
+    /** The authenticated subject whose model and subscription authority apply. */
+    subjectId: string;
+};
+export type ModelCallInput = ModelCallCaller & {
+    /** Product model id or alias; null selects the workspace default model. */
+    model: string | null;
+    request: Omit<SingleModelCallRequest, "signal">;
+    /** Server-generated identity; the settlement idempotency key derives from it. */
+    requestId: string;
+    signal?: AbortSignal;
+    onTextDelta?: (delta: string) => void | Promise<void>;
+};
+export type ModelCallOutput = {
+    /** Canonical product model id that served the call. */
+    model: string;
+    result: SingleModelCallResult;
+};
+export type ModelCallModel = {
+    id: string;
+    label: string;
+    providerLabel: string;
+};
+export interface ModelCallService {
+    /** Models the caller may use for a single call, in catalog order. */
+    listModels(caller: ModelCallCaller): Promise<ModelCallModel[]>;
+    call(input: ModelCallInput): Promise<ModelCallOutput>;
+}
+export type ModelCallErrorType = "invalid_request_error" | "not_found_error" | "insufficient_quota" | "rate_limit_error" | "api_error" | "service_unavailable";
+/**
+ * A refusal or failure with a public status and an OpenAI-style error type.
+ * Messages are safe to return to the caller.
+ */
+export declare class ModelCallError extends Error {
+    readonly status: number;
+    readonly type: ModelCallErrorType;
+    readonly code: string | null;
+    readonly param: string | null;
+    constructor(input: {
+        status: number;
+        type: ModelCallErrorType;
+        message: string;
+        code?: string | null;
+        param?: string | null;
+    });
+}

package/dist/model-catalog.d.ts

@@ -1,7 +1,7 @@
 import { type ConnectionModelRestrictions } from "@opengeni/db";
-import { type ConfiguredModel, type Settings } from "@opengeni/config";
+import { type ClaudeConnectionCatalog, type ConfiguredModel, type Settings } from "@opengeni/config";
 import { type ModelAvailabilityV1, type ModelCredentialReadinessV1, type WorkspaceModelPolicyContract } from "@opengeni/contracts";
-import { type Database } from "@opengeni/db";
+import { type Database, type OrganizationClaudeModelAdmissionAuthority } from "@opengeni/db";
 export type ResolvedCatalogSettings = {
     settings: Settings;
     source: "code" | "database";
@@ -15,9 +15,10 @@ export type ResolvedCatalogSettings = {
  */
 export declare function isWorkspaceGatewayCustomModelId(settings: Settings, modelId: string): boolean;
 export declare function isWorkspaceOpenRouterCustomModelId(settings: Settings, modelId: string): boolean;
+export declare function isWorkspaceOpperCustomModelId(settings: Settings, modelId: string): boolean;
 export type WorkspaceCustomModelReference = {
     scope: "workspace" | "organization";
-    providerKind: "vercel_gateway" | "openrouter";
+    providerKind: "vercel_gateway" | "openrouter" | "anthropic" | "claude_subscription" | "opper";
     upstreamModelId: string;
 };
 export declare function workspaceCustomModelReference(settings: Settings, modelId: string): WorkspaceCustomModelReference | null;
@@ -26,6 +27,12 @@ export declare function lockActiveCustomModelForAdmission(db: Database, input: {
     accountId: string;
     workspaceId: string;
     reference: WorkspaceCustomModelReference;
+    /**
+     * The accepted Claude authority this admission re-reads. Every caller
+     * states it: an organization Claude model is never admitted without it,
+     * so an omitted value would refuse that model silently.
+     */
+    claudeAuthority: OrganizationClaudeModelAdmissionAuthority | null;
 }): Promise<boolean>;
 /**
  * Resolve the deployment catalog without making synchronous env settings read
@@ -70,8 +77,12 @@ export type WorkspaceModelSelectionInput = {
     xaiSubscriptionActive?: boolean;
     workspaceGatewayConnectionActive?: boolean;
     workspaceOpenRouterConnectionActive?: boolean;
+    workspaceOpperConnectionActive?: boolean;
+    claudeConnections?: ClaudeConnectionCatalog;
+    workspaceClaudeConnections?: ClaudeConnectionCatalog;
     organizationGatewayConnectionActive?: boolean;
     organizationOpenRouterConnectionActive?: boolean;
+    organizationOpperConnectionActive?: boolean;
     workspaceGatewayCustomModels?: readonly {
         upstreamModelId: string;
         label?: string | null;
@@ -88,6 +99,14 @@ export type WorkspaceModelSelectionInput = {
         upstreamModelId: string;
         label?: string | null;
     }[];
+    workspaceOpperCustomModels?: readonly {
+        upstreamModelId: string;
+        label?: string | null;
+    }[];
+    organizationOpperCustomModels?: readonly {
+        upstreamModelId: string;
+        label?: string | null;
+    }[];
     credentialReadinessObservations?: Readonly<Record<string, ModelCredentialReadinessObservation>> | undefined;
     observations?: Readonly<Record<string, ModelAvailabilityObservation>> | undefined;
     now?: Date | undefined;
@@ -99,6 +118,13 @@ export type WorkspaceModelSelection = {
     policyAllowed: boolean;
     availability: ModelAvailabilityV1;
 };
+/**
+ * Stable fresh-selection admission, independent of transient observations.
+ * Missing catalog membership is handled by the caller's lookup. Resolver-based
+ * deployment credentials (Azure AD/managed identity) are resolved at execution;
+ * absent, stale or failed observations cannot make their definition uncreatable.
+ */
+export declare function isWorkspaceModelAdmissible(selection: WorkspaceModelSelection): boolean;
 /**
  * One shared picker/tool decision. Catalog membership, credential readiness,
  * workspace policy, and optional provider-health observations are evaluated in

package/dist/model-provider-credentials.d.ts

@@ -0,0 +1,43 @@
+import { type Settings } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+/**
+ * Execution-time provider overlays for one workspace: subscription catalog
+ * providers plus the decrypted workspace and organization provider keys a
+ * model call needs. Agent turns (worker claim) and stateless single model
+ * calls (API) apply the same overlays, so both resolve a model to the same
+ * provider and credential.
+ */
+/**
+ * When the workspace has an active Codex subscription connected and the feature
+ * is enabled, inject a synthetic "codex-subscription" registry provider so a
+ * `codex/<slug>` model id routes through the ChatGPT backend. No secrets touch
+ * this overlay (metadata-only read); the per-request bearer is resolved later via
+ * codexRequestStorage. Idempotent and a no-op when not applicable.
+ */
+export declare function settingsWithCodexCredential(db: Database, workspaceId: string, settings: Settings, activeOverride?: boolean): Promise<Settings>;
+/** Pure: append the synthetic codex-subscription provider, idempotently. */
+export declare function withCodexProvider(settings: Settings): Settings;
+/**
+ * Pure: append the synthetic SuperGrok/xAI subscription provider,
+ * idempotently. The overlay is catalogue metadata only; the exact account,
+ * authority snapshot, and bearer remain frozen later at turn admission.
+ */
+export declare function withXaiSubscriptionProvider(settings: Settings): Settings;
+export declare function settingsWithWorkspaceGatewayCredential(db: Database, accountId: string, workspaceId: string, settings: Settings, retainedProductModelId?: string | null): Promise<Settings>;
+export declare function settingsWithWorkspaceOpenRouterCredential(db: Database, accountId: string, workspaceId: string, settings: Settings, retainedProductModelId?: string | null): Promise<Settings>;
+/** Overlay the workspace Opper catalog and, when active, its decrypted key. */
+export declare function settingsWithWorkspaceOpperCredential(db: Database, accountId: string, workspaceId: string, settings: Settings, retainedProductModelId?: string | null): Promise<Settings>;
+export declare function settingsWithOrganizationProviderCredentials(db: Database, accountId: string, workspaceId: string, settings: Settings, retainedProductModelId?: string | null): Promise<Settings>;
+/**
+ * Apply every execution overlay in the order the worker claim uses, then
+ * install the selected customer direct connection when the model names one.
+ * `codexSubscriptionActive` is the caller's single readiness observation, so
+ * routing and billing decide from the same read.
+ */
+export declare function settingsWithModelProviderCredentials(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    settings: Settings;
+    productModelId: string | null | undefined;
+    codexSubscriptionActive: boolean;
+}): Promise<Settings>;

package/dist/product-usage-metrics.d.ts

@@ -0,0 +1,30 @@
+import { type SessionTurnSurface } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+/**
+ * Live, content-free product usage counters recorded where work is accepted.
+ * Every label is a closed set: the product surface (or `unknown` when no
+ * surface was captured), who created a session (`subject` or `service`), and
+ * whether the session is a root. No workspace, user, model or text value ever
+ * becomes a label.
+ */
+export type ProductUsageMetricsSink = Pick<Observability, "incrementCounter">;
+export declare const PRODUCT_USAGE_SURFACE_LABELS: readonly ["web", "slack", "api_key", "embedded", "scheduled", "agent", "voice", "site", "automation", "mcp", "system", "unknown"];
+export type ProductUsageSurfaceLabel = (typeof PRODUCT_USAGE_SURFACE_LABELS)[number];
+export declare const SESSION_CREATED_BY_KINDS: readonly ["subject", "service"];
+export type SessionCreatedByKind = (typeof SESSION_CREATED_BY_KINDS)[number];
+export declare function productUsageSurfaceLabel(surface: SessionTurnSurface | null | undefined): ProductUsageSurfaceLabel;
+/** Count one newly created session. Never throws; replays must not call it. */
+export declare function recordSessionCreated(sink: ProductUsageMetricsSink | null | undefined, input: {
+    surface: SessionTurnSurface | null | undefined;
+    createdByKind: string | null | undefined;
+    parentSessionId: string | null | undefined;
+}): void;
+/** Count one newly accepted user message. Never throws; replays must not call it. */
+export declare function recordUserMessageAccepted(sink: ProductUsageMetricsSink | null | undefined, input: {
+    surface: SessionTurnSurface | null | undefined;
+}): void;
+/**
+ * Publish every closed series at zero so dashboards can tell a quiet surface
+ * from missing instrumentation. Never throws.
+ */
+export declare function registerProductUsageMetricBaselines(sink: ProductUsageMetricsSink | null | undefined): void;

package/dist/rigs/index.d.ts

@@ -1,18 +1,9 @@
-import type { AccessGrant, CreateRigRequest, RigDefinitionEditPayload, ProposeRigChangeRequest, Rig, RigChange, ResourceAuthorityScope, RigVersion, UpdateRigRequest } from "@opengeni/contracts";
+import type { AccessGrant, CreateRigRequest, RigDefinitionEditPayload, ProposeRigChangeRequest, Rig, RigChange, RigVersion, UpdateRigRequest } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
 export * from "./provider-images.js";
 export declare const MAX_RIGS_PER_WORKSPACE = 50;
 export declare const MAX_CHECKS_PER_RIG = 100;
 export declare const MAX_CREDENTIAL_HOOKS_PER_RIG = 50;
-export declare const MAX_DEFAULT_VARIABLE_SETS_PER_RIG = 25;
-export declare const RIG_DEFAULT_VARIABLE_SET_LOAD_CONCURRENCY = 4;
-type VariableSetEnvironment = {
-    values: Record<string, string>;
-} | null;
-/** Load complete rig defaults concurrently while preserving listed precedence. */
-export declare function loadRigDefaultVariableSetEnvironment(variableSetIds: readonly string[], load: (variableSetId: string) => Promise<VariableSetEnvironment>): Promise<Record<string, string>>;
-/** Rig defaults layer below the session's explicitly selected variable set. */
-export declare function mergeRigDefaultVariableSetEnvironment(rigDefaultValues: Record<string, string>, sessionValues: Record<string, string>): Record<string, string>;
 export type RigServices = {
     db: Database;
 };
@@ -26,9 +17,6 @@ export declare function recordRigAuditEvent(db: Database, input: {
 export declare function rigActorForGrant(grant: AccessGrant): string;
 export declare function requireRigForApi(db: Database, grant: AccessGrant, rigId: string): Promise<Rig>;
 export declare function requireRigChangeForApi(db: Database, workspaceId: string, rigId: string, changeId: string): Promise<RigChange>;
-/** A resource may depend only on Variable Sets whose audience is no narrower
- * than its own. User-owned rigs may use anything visible to their owner. */
-export declare function variableSetScopeAllowedForRig(rigScope: ResourceAuthorityScope, variableSetScope: ResourceAuthorityScope): boolean;
 export declare function createRigForApi(deps: RigServices, grant: AccessGrant, payload: CreateRigRequest, options?: {
     allowOrganization?: boolean;
 }): Promise<Rig>;

package/dist/sandbox/fleet.d.ts

@@ -1,5 +1,6 @@
-import type { Settings } from "@opengeni/config";
-import type { SandboxBackend } from "@opengeni/contracts";
+import type { VaultProviderRegistry } from "@opengeni/vaults";
+import { type Settings } from "@opengeni/config";
+import { type SandboxBackend, type SecretResolver } from "@opengeni/contracts";
 import { type Database, type SandboxRecord } from "@opengeni/db";
 import type { EventBus } from "@opengeni/events";
 import { type BackendUnresolvableCode, type ControlRpc, type SelfhostedRelayConfig, type SelfhostedOpStreamDeps, type SelfhostedOperationAdmission, type SelfhostedOperationResourcePolicy } from "@opengeni/runtime/sandbox";
@@ -68,7 +69,7 @@ export type FleetSandboxEntry = {
     /** The sandbox id used as the attach/swap/run_on `target`. For the session's
      *  own group box this is the group id (a null active pointer == this box). */
     id: string;
-    kind: "modal" | "selfhosted" | "opensandbox";
+    kind: Exclude<SandboxBackend, "none">;
     name: string;
     liveness: FleetLiveness;
     /** True for the session's currently-active sandbox (the routing target). */
@@ -117,8 +118,21 @@ export type FleetSwapResult = {
     activeSandboxId: string | null;
     activeEpoch: number;
     reason?: string;
-    code?: BackendUnresolvableCode | "invalid_working_directory" | "concurrent_swap" | "recovery_in_progress" | "recovery_degraded" | "recovery_unrecoverable";
+    code?: BackendUnresolvableCode | "invalid_working_directory" | "concurrent_swap" | PersonalMachineRefusalCode | "recovery_in_progress" | "recovery_degraded" | "recovery_unrecoverable";
 };
+export type PersonalMachineRefusalCode = "personal_machine_permission_required" | "personal_machine_not_permitted";
+/**
+ * Plain refusal for a personal ("Only me") Connected Machine that the database
+ * admission (`authorize_session_attempt_personal_machine`) turned down. The
+ * function raises SQLSTATE 42501 for policy refusals and P0002 when a required
+ * owner, authority or enrollment row is not current. Only failures of that
+ * admission statement are mapped; anything else is a real failure and stays an
+ * error. The raw database error is never shown.
+ */
+export declare function personalMachineRefusal(error: unknown): {
+    code: PersonalMachineRefusalCode;
+    reason: string;
+} | null;
 /**
  * List the fleet: the session's own group box when it has one (a synthetic
  * entry) + the workspace's first-class selfhosted sandboxes (each probed for
@@ -210,9 +224,31 @@ export type RunOnSelfhostedMachine = {
      * the active attempt that owns the one-off operation.
      */
     transientExecEnvironment?: Readonly<Record<string, string>>;
+    /**
+     * The calling attempt's secret resolver (W1, DL-9). exec splices
+     * `{{secret:…}}` / `{{secretfile:…}}` in the machine's dialect and delivers
+     * values in ExecRequest.env; write resolves its content; read resolves
+     * nothing. Absent: references pass through literally.
+     */
+    secretResolver?: SecretResolver | null;
 };
+/**
+ * The secret resolver for a `run_on` call made by an exact agent attempt (the
+ * MCP claims). Gated by the session's `secrets` capability (default on).
+ */
+export declare function createRunOnSecretResolver(services: Pick<FleetServices, "db" | "settings">, attempt: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+}, 
+/** Connected vaults (1Password, host) for the attempt's acting human. */
+providersForSubject?: (subjectId: string | null) => VaultProviderRegistry): Promise<SecretResolver>;
 export type RunOnOptions = {
     transientExecEnvironment?: Readonly<Record<string, string>>;
+    secretResolver?: SecretResolver | null;
 };
 /**
  * Execute the one-off machine operation once the workspace/enrollment lookup has
@@ -221,6 +257,24 @@ export type RunOnOptions = {
  * the production ownership lookup or requiring a real machine.
  */
 export declare function executeRunOnSelfhostedMachine(machine: RunOnSelfhostedMachine, target: string, op: RunOnOp): Promise<RunOnResult>;
+/**
+ * Run one short command on a specific enrolled machine for an action a person
+ * or agent took outside a session's routing (opening a macOS settings pane).
+ * The caller has already authorized the actor for this enrollment; `access` is
+ * the same scope the caller used to read it. `execTimeoutMs` bounds the command.
+ */
+export declare function runOnEnrollmentDirect(services: Pick<FleetServices, "db" | "settings" | "bus">, input: {
+    access: string | {
+        accountId: string;
+        workspaceId: string;
+        subjectId: string;
+    };
+    enrollmentId: string;
+    /** Display label for results (machine name or sandbox id). */
+    target: string;
+    cmd: string;
+    execTimeoutMs: number;
+}): Promise<RunOnResult>;
 /**
  * Run a ONE-OFF op against a SPECIFIC target WITHOUT changing the active pointer
  * (the design `run_on`). Only selfhosted targets are routable as a one-off here

package/dist/sandbox/routing.d.ts

@@ -1,7 +1,7 @@
 import { type Settings } from "@opengeni/config";
-import { type Database, type SandboxRetainedProcess } from "@opengeni/db";
+import { type Database, type EnrollmentRecord, type SandboxRetainedProcess } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
-import { type EstablishedSandboxSession, type ResolvedActiveBackend, type RoutingRetainedProcess, type RoutingRetainedProcessTerminalProof, 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;
@@ -11,6 +11,12 @@ type DirectRetainedProcessRoute = {
     routeTargetId: string | null;
     routeEpoch: number;
 };
+/** Inline filesystem subprocesses stay durably retained for cancellation and
+ * recovery, but are not model-visible session background commands. */
+export declare function directRetainedProcessBackgroundCommand(process: Pick<RoutingRetainedProcess, "id">, operation: string, purpose?: "synchronous_filesystem"): {
+    commandId: string;
+    command: string;
+} | undefined;
 /** 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;
@@ -24,8 +30,38 @@ export type ChannelARoutingServices = {
     settings: Settings;
     bus?: EventBus;
     onSandboxOperation?: RoutingSandboxOperationObserver;
+    onSandboxCaptureWait?: RoutingSandboxCaptureWaitObserver;
     waitSignal?: AbortSignal;
 };
+/**
+ * Whose access a Channel-A request uses to reach a Connected Machine. A person
+ * uses their own. An agent acts for the person who started its turn, never as
+ * itself, so it reaches the same machines that person can; a personal (Only me)
+ * machine additionally needs that exact running attempt's per-chat permission,
+ * rechecked before every routed operation like the worker's turn path.
+ */
+export type ChannelAMachineAuthority = {
+    subjectId: string;
+    personalMachineAttempt: {
+        turnId: string;
+        attemptId: string;
+        executionGeneration: number;
+    } | null;
+};
+/**
+ * Resolve a Connected Machine's live runner for one Channel-A request. The
+ * machine's audience can change in place, so its current scope is read from the
+ * enrollment itself. An agent attempt reaches a personal machine only through
+ * the same attempt admission as swap and run_on; everything else keeps the
+ * caller-scoped lookup.
+ */
+export declare function resolveChannelAMachineConnection(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    machineWorkspaceId: string;
+    enrollmentId: string;
+}, authority: ChannelAMachineAuthority): Promise<EnrollmentRecord | null>;
 /** Map the deployment relay URL to the leaf's `SelfhostedRelayConfig` shape. The
  *  relay URL (`OPENGENI_SELFHOSTED_RELAY_URL`) may carry a path (the relay's wss
  *  route); a path-less URL defaults to the relay's `/stream` route (M8b). */
@@ -55,6 +91,10 @@ export declare function wrapChannelABoxWithRouting(services: ChannelARoutingServ
     workspaceId: string;
     sessionId: string;
     resourceSubjectId: string;
+    /** Whose access reaches Connected Machines (see ChannelAMachineAuthority).
+     * Resolved lazily, once, only when a request routes to a machine. Omitted,
+     * the request uses `resourceSubjectId`'s own access. */
+    machineAuthority?: () => Promise<ChannelAMachineAuthority>;
     homeLease?: {
         sandboxGroupId: string;
         leaseEpoch: number;

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

@@ -1,5 +1,5 @@
-import type { Settings } from "@opengeni/config";
-import { CapabilityPack, type RigVersion, type Session, type SandboxBackend, type SandboxOs } from "@opengeni/contracts";
+import { type Settings } from "@opengeni/config";
+import { type AccessGrant, 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">;
@@ -14,24 +14,25 @@ export type ManagedSessionGroupBackend = Exclude<SandboxBackend, "none" | "selfh
  * 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;
-/** Pre-V2 Packs are the sole compatibility path where a Pack can still own a
- * sandbox image. V2 installations select a Rig instead. Keep this predicate at
- * the shared runtime boundary so turns, API-direct tools, viewers, Browser and
- * Computer cannot resolve different physical machines for the same session. */
-export declare function packInstallationUsesLegacyRuntime(input: {
-    manifestSnapshot: unknown | null;
-    manifestDigest: string | null;
-}): boolean;
-export declare function resolveWorkspaceLegacyRuntimePacks(db: Database, workspaceId: string): Promise<CapabilityPack[]>;
-export declare function legacySandboxRuntimeFromPacks(packs: readonly CapabilityPack[]): {
-    sandboxImage: string | null;
-    sandboxProviderImages: CapabilityPack["sandboxProviderImages"] | null;
-};
-export declare function settingsWithPackSandboxImage(settings: Settings, sandboxImage: string | null, sandboxProviderImages?: CapabilityPack["sandboxProviderImages"] | null): Settings;
+/**
+ * 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";
@@ -49,7 +50,16 @@ export type SessionSandboxRuntime = {
     image: string | null;
     rigVersion: RigVersion | null;
 };
-export declare function resolveSessionSandboxRuntime(db: Database, settings: Settings, session: Pick<Session, "workspaceId" | "sandboxBackend" | "rigId" | "rigVersionId">): Promise<SessionSandboxRuntime>;
+/** Who a direct attach resolves a session's Sandbox Environment as: an explicit
+ *  subject (null for a service attach), or the authenticated route grant. */
+export type SessionAttachRigAuthority = {
+    subjectId: string | null;
+} | {
+    grant: AccessGrant;
+};
+export declare function resolveSessionSandboxRuntime(db: Database, settings: Settings, session: Pick<Session, "accountId" | "workspaceId" | "sandboxBackend" | "rigId" | "rigVersionId">, 
+/** Who drives the attach; pass the route grant whenever one exists. */
+authority: SessionAttachRigAuthority): 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

@@ -2,6 +2,16 @@ import { SessionAuthorizationActor, SessionAuthorizationListScope, type AccessGr
 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 {