@opengeni/core 0.10.0 → 0.11.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Settings } from '@opengeni/config';
-import { ScheduledTask, Document, GitHubAppApiPort, ConnectionCredentialsPort, SessionAuthorizationPort, Permission, AccessContext, AccessGrant, SessionAuthorizationActor, SessionAuthorizationTarget, SessionAuthorizationOperation, SessionAuthorizationSurface, SessionAuthorizationListScope, LimitAction, LimitDecision, TurnInitiator, TurnInitiatorContext, SessionTurnSource, CapabilityCatalogItem, CapabilityInstallation, CapabilityCatalogResponse, CreateCapabilityCatalogItemRequest, EnableCapabilityRequest, VariableSet, Rig, RigVersion, CreateRigRequest, RigDefinitionEditPayload, RigChange, ProposeRigChangeRequest, UpdateRigRequest, CapabilityPack, SocialConnection, ScheduledTaskAgentConfig, ToolRef, ResourceRef, SessionEffectiveToolPolicy, SessionToolPolicy, Session, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, ReasoningEffort, SessionMcpCredentialUpdateInput, SessionEvent, SessionTurn, TurnExecutionPolicyV1, GoalSpec, SessionMcpServerMetadata, CreateSessionResponse, SessionMcpApprovalPolicy, UpdateSessionMcpApprovalPolicyResponse, WorkspaceMember, SessionControlRequest, SessionControlResponse, WorkspaceInferenceControlRequest, WorkspaceInferenceControlResponse, DeleteSessionQueueItemRequest, SessionQueueMutationResponse, EditSessionQueueItemRequest, ComposerDraft, MoveSessionQueueItemRequest, SaveComposerDraftRequest, SteerSessionQueueItemRequest } from '@opengeni/contracts';
+import { ScheduledTask, Document, GitHubAppApiPort, ConnectionCredentialsPort, SessionAuthorizationPort, Permission, AccessContext, AccessGrant, SessionAuthorizationActor, SessionAuthorizationTarget, SessionAuthorizationOperation, SessionAuthorizationSurface, SessionAuthorizationListScope, LimitAction, LimitDecision, TurnInitiator, TurnInitiatorContext, SessionTurnSource, CapabilityCatalogItem, CapabilityInstallation, CapabilityCatalogResponse, CreateCapabilityCatalogItemRequest, EnableCapabilityRequest, VariableSet, Rig, RigVersion, CreateRigRequest, RigDefinitionEditPayload, RigChange, ProposeRigChangeRequest, UpdateRigRequest, CapabilityPack, SocialConnection, ScheduledTaskAgentConfig, ToolRef, ResourceRef, SessionEffectiveToolPolicy, SessionToolPolicy, Session, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, SessionSpawnDenial, ReasoningEffort, SessionMcpCredentialUpdateInput, SessionEvent, SessionTurn, TurnExecutionPolicyV1, GoalSpec, SessionMcpServerMetadata, CreateSessionResponse, SessionMcpApprovalPolicy, UpdateSessionMcpApprovalPolicyResponse, WorkspaceMember, NewSessionDraft, SessionControlRequest, SessionControlResponse, WorkspaceInferenceControlRequest, WorkspaceInferenceControlResponse, DeleteSessionQueueItemRequest, SessionQueueMutationResponse, EditSessionQueueItemRequest, ComposerDraft, MoveSessionQueueItemRequest, SaveComposerDraftRequest, SteerSessionQueueItemRequest } from '@opengeni/contracts';
 export { mergeToolRefs, stableJson } from '@opengeni/contracts';
 import * as _opengeni_db from '@opengeni/db';
 import { Database, SandboxRecord, EnabledMcpCapabilityServer, UpdateScheduledTaskInput, SessionCommandActor, CreateSessionMcpServerInput, UpdateSessionMcpServerCredentialsInput } from '@opengeni/db';
@@ -196,6 +196,14 @@ type FleetServices = {
     db: Database;
     settings: Settings;
     bus?: EventBus;
+    /** API-direct readiness owner for the session's home group. Production wires
+     * this to the same viewer/provider verification + rematerialization path; core
+     * tests may omit it when exercising pointer mechanics only. */
+    ensureSessionGroupReady?: (ctx: FleetContext) => Promise<FleetReadinessHold>;
+};
+type FleetReadinessHold = {
+    /** Release target liveness only after route publication settles. */
+    release: () => Promise<void>;
 };
 type FleetContext = {
     accountId: string;
@@ -252,6 +260,21 @@ type FleetSandboxEntry = {
     /** Selfhosted only: whether a display (real/Xvfb) is present. */
     hasDisplay?: boolean;
     lastSeenAt?: string | null;
+    /** Orthogonal truth dimensions. `liveness` is only their conservative UI
+     * projection and is never evidence for a specific dimension. */
+    providerStatus: "not_created" | "creating" | "exists" | "missing" | "unknown";
+    leaseLiveness: "cold" | "warming" | "warm" | "draining" | null;
+    routeStatus: "attached" | "detached";
+    archiveStatus: "none" | "available" | "unverified" | "invalid";
+    restoreStatus: "not_required" | "pending" | "restoring" | "verifying" | "ready" | "degraded" | "unrecoverable";
+    workspaceStatus: "unknown" | "not_ready" | "ready" | "degraded" | "unrecoverable";
+    leaseEpoch: number | null;
+    routeEpoch: number;
+    /** Numeric/boolean persistence truth only. Archive locations, content hashes,
+     * provider identities, and storage handles are intentionally not projected. */
+    workspaceGeneration: number | null;
+    archiveGeneration: number | null;
+    archiveComplete: boolean;
 };
 type FleetListResult = {
     /** The session's currently-active sandbox id, or null == the group box. */
@@ -266,7 +289,7 @@ type FleetSwapResult = {
     activeSandboxId: string | null;
     activeEpoch: number;
     reason?: string;
-    code?: BackendUnresolvableCode | "concurrent_swap";
+    code?: BackendUnresolvableCode | "concurrent_swap" | "recovery_in_progress" | "recovery_degraded" | "recovery_unrecoverable";
 };
 /**
  * List the fleet: the session's own Modal group box (a synthetic entry) + the
@@ -373,8 +396,19 @@ declare function routingEnabled(settings: Settings): boolean;
  * unchanged; a selfhosted active pointer routes the op to the machine.
  */
 declare function wrapChannelABoxWithRouting(services: ChannelARoutingServices, ids: {
+    accountId: string;
     workspaceId: string;
     sessionId: string;
+    homeLease: {
+        sandboxGroupId: string;
+        leaseEpoch: number;
+        instanceId: string;
+        backend: string;
+    };
+    directRequest: {
+        requestId: string;
+        holderId: string;
+    };
 }, established: EstablishedSandboxSession): EstablishedSandboxSession;
 
 type AccessDeps = {
@@ -734,6 +768,36 @@ declare function manualScheduledTaskTriggerWorkflowId(taskId: string, triggerTok
  */
 declare function manualScheduledTaskTriggerUsageKey(workspaceId: string, taskId: string, triggerToken: string): string;
 
+/** Transport-neutral typed denial raised only after its audit row committed. */
+declare class SessionSpawnDeniedError extends Error {
+    readonly denial: SessionSpawnDenial;
+    constructor(denial: SessionSpawnDenial);
+}
+declare function sessionSpawnDenialEnvelope(error: SessionSpawnDeniedError): {
+    readonly error: {
+        readonly code: "nested_agent_depth_exceeded" | "nested_agent_depth_override_forbidden";
+        readonly message: string;
+        readonly details: {
+            readonly denial: {
+                id: string;
+                accountId: string;
+                workspaceId: string;
+                parentSessionId: string | null;
+                rootSessionId: string | null;
+                currentDepth: number;
+                attemptedDepth: number;
+                effectiveMaxNestedAgentDepth: number;
+                requestedMaxNestedAgentDepthOverride: number | null;
+                policySource: "default" | "session" | "workspace" | "deployment";
+                policySessionId: string | null;
+                subjectId: string | null;
+                code: "nested_agent_depth_exceeded" | "nested_agent_depth_override_forbidden";
+                idempotencyKey: string | null;
+                createdAt: string;
+            };
+        };
+    };
+};
 declare function settingsWithSessionMcpServerMetadata(settings: Settings, servers: SessionMcpServerMetadata[]): Settings;
 declare function createAndStartSession(input: {
     requestedSessionId?: string;
@@ -778,6 +842,13 @@ declare function createAndStartSession(input: {
         settings: Settings;
         workingDir?: string | null;
     } | null;
+    consumeNewSessionDraft?: {
+        subjectId: string;
+        expectedRevision: number;
+    } | null;
+    maxNestedAgentDepthOverride?: number | null;
+    allowNestedAgentDepthIncrease?: boolean;
+    subjectId?: string | null;
 }): Promise<CreateSessionResponse>;
 declare function workflowIdForSession(sessionId: string): string;
 /**
@@ -950,6 +1021,18 @@ declare function assertWorkspaceDeletable(input: {
     activeSessionCount: number;
 }): void;
 
+type NewSessionDraftDependencies = Pick<AppDependencies, "settings" | "db" | "objectStorage">;
+/** Read the authenticated actor's server-authoritative pre-session composer state. */
+declare function getActorNewSessionDraft(deps: Pick<NewSessionDraftDependencies, "settings" | "db">, grant: AccessGrant, workspaceId: string): Promise<NewSessionDraft>;
+/**
+ * Validate and save one exact actor-private draft revision. Create-time-only
+ * checks (live machine target, rig/variable-set state, and permission
+ * delegation) intentionally remain in createSessionForRequest: a recoverable
+ * draft may represent incomplete options, while no invalid option can become a
+ * session without passing that single canonical create boundary.
+ */
+declare function saveActorNewSessionDraft(deps: NewSessionDraftDependencies, grant: AccessGrant, workspaceId: string, rawInput: unknown): Promise<NewSessionDraft>;
+
 type HumanSessionCommandContext = {
     accountId: string;
     workspaceId: string;
@@ -1034,4 +1117,4 @@ declare function controlHumanWorkspace(deps: {
 declare function getHumanComposerDraft(deps: SessionAuthorizationCommandDeps, context: HumanSessionCommandContext): Promise<ComposerDraft>;
 declare function saveHumanComposerDraft(deps: SessionAuthorizationCommandDeps, context: HumanSessionCommandContext, input: SaveComposerDraftRequest): Promise<ComposerDraft>;
 
-export { type AcceptSessionUserMessageDependencies, type AccessDeps, type AgentSessionCommandContext, type ApiRouteDeps, type ApiSandboxClient, type ApiSandboxSession, type AppDependencies, type ChannelARoutingServices, type DocumentIndexClient, type FleetContext, type FleetListResult, type FleetLiveness, type FleetSandboxEntry, type FleetServices, type FleetSwapResult, type HumanSessionCommandContext, type LimitCheckInput, type LimitDependencies, MARKETING_SOCIAL_PACK_ID, MAX_CHECKS_PER_RIG, MAX_CREDENTIAL_HOOKS_PER_RIG, MAX_DEFAULT_VARIABLE_SETS_PER_RIG, MAX_ENVIRONMENTS_PER_WORKSPACE, MAX_RIGS_PER_WORKSPACE, MAX_VARIABLES_PER_ENVIRONMENT, type ManagedAuth, type McpCapabilityProbe, type McpCapabilityProbeInput, type McpCapabilityProbeResult, type ObjectStorageDependency, type ProvisionResult, type ResolvedSessionAuthorization, type ResolvedSessionToolPolicy, type ResumeBoxByIdInput, type ResumedSandboxSession, type RigServices, type RigVerificationClassification, type RunOnOp, type RunOnResult, SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS, SESSION_WORKFLOW_WAKE_DISPATCHER_PERIOD_MS, SESSION_WORKFLOW_WAKE_DISPATCHER_SCHEDULE_ID, SESSION_WORKFLOW_WAKE_DISPATCHER_WORKFLOW_TYPE, SessionAuthorizationDeniedError, type SessionAuthorizationDependencies, SessionAuthorizationUnavailableError, type SessionToolPolicyInput, type SessionWorkflowClient, acceptSessionUserMessage, activateRigVersionForApi, appendRigSetupCommand, applyCapabilityEnablement, assertAllowedEnvironmentVariableName, assertAllowedVariableSetVariableName, assertConfiguredModel, assertPackSandboxImageCompatible, assertToolRefsSubset, assertWorkspaceDeletable, assertWorkspaceMemberRemovable, assertWorkspaceModelPolicyAllows, availableToolRefs, buildCapabilityCatalog, buildFleetContextForSession, buildMarketingDailyAnalysisAgentConfig, canonicalConfiguredModel, checkLimit, classifyRigVerificationOutcome, controlAgentSessionWorkstream, controlHumanSessionWorkstream, controlHumanWorkspace, createAndStartSession, createCatalogItem, createRigForApi, createRigVersionForApi, createSessionForRequest, createValidatedScheduledTask, deleteHumanQueuePrompt, deleteRigForApi, disableCapability, discoverMcpRegistryCapabilities, editHumanQueuePrompt, enableCapability, enabledCapabilityMcpToolRefs, getCapabilityPack, getHumanComposerDraft, hasPermission, isBuiltInCapabilityPack, isUserMember, listCapabilityPacks, listFleet, listRigChangesForApi, listRigVersionsForApi, listWorkspaceCapabilityPacks, manualScheduledTaskTriggerUsageKey, manualScheduledTaskTriggerWorkflowId, memberCanAdminister, mergeResourceRefs, moveHumanQueuePrompt, normalizeResources, officialMcpRegistryUrl, postUserMessageTurn, promoteSetupAppendChange, promoteVerifiedDefinitionEditChangeForApi, proposeRigChangeForApi, provisionSandbox, readSessionLineage, reasoningEffortForSession, recordRigAuditEvent, recordVariableSetAuditEvent, recordWorkspaceUsage, relayConfigFromSettings, relayDialBaseFromSettings, requireAccessContext, requireAccessGrant, requireEnvironmentEncryption, requireLimit, requirePermission, requireQueuedTurnForApi, requireRigChangeForApi, requireRigForApi, requireScheduledTaskForApi, requireSessionAuthorization, requireSessionAuthorizationListScope, requireVariableSetEncryption, requireVariableSetForApi, resolveCapabilityPack, resolveMemberSubjectId, resolveSessionToolPolicy, restoreScheduledTask, rigActorForGrant, routingEnabled, runOnSandbox, saveHumanComposerDraft, scheduledTaskTemporalScheduleId, scheduledTaskToolsProvided, scheduledTaskTriggerToken, sendAgentSessionMessage, sessionWithEffectiveToolPolicy, settingsWithEnabledCapabilityMcpServers, settingsWithMcpCapabilityServers, settingsWithSessionMcpServerMetadata, steerAgentSession, steerHumanQueuePrompt, swapActiveSandbox, syncCreatedScheduledTask, syncUpdatedScheduledTask, updateRigForApi, updateSessionMcpApprovalPolicy, updateSessionTitle, validateFileResources, validateGitHubRepositorySelection, validateGitHubRepositorySelectionShape, validateGitHubRepositorySelectionShapes, validateMcpCapabilityConnection, validateToolRefs, validateToolRefsForSessionPolicy, validateVariableSetAttachment, validatedScheduledTaskUpdate, withDefaultEnabledCapabilityMcpTools, workflowIdForSession, workspaceSessionToolPolicyDefaultServerIds, workspaceSessionToolPolicyServerIds, wrapChannelABoxWithRouting };
+export { type AcceptSessionUserMessageDependencies, type AccessDeps, type AgentSessionCommandContext, type ApiRouteDeps, type ApiSandboxClient, type ApiSandboxSession, type AppDependencies, type ChannelARoutingServices, type DocumentIndexClient, type FleetContext, type FleetListResult, type FleetLiveness, type FleetReadinessHold, type FleetSandboxEntry, type FleetServices, type FleetSwapResult, type HumanSessionCommandContext, type LimitCheckInput, type LimitDependencies, MARKETING_SOCIAL_PACK_ID, MAX_CHECKS_PER_RIG, MAX_CREDENTIAL_HOOKS_PER_RIG, MAX_DEFAULT_VARIABLE_SETS_PER_RIG, MAX_ENVIRONMENTS_PER_WORKSPACE, MAX_RIGS_PER_WORKSPACE, MAX_VARIABLES_PER_ENVIRONMENT, type ManagedAuth, type McpCapabilityProbe, type McpCapabilityProbeInput, type McpCapabilityProbeResult, type ObjectStorageDependency, type ProvisionResult, type ResolvedSessionAuthorization, type ResolvedSessionToolPolicy, type ResumeBoxByIdInput, type ResumedSandboxSession, type RigServices, type RigVerificationClassification, type RunOnOp, type RunOnResult, SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS, SESSION_WORKFLOW_WAKE_DISPATCHER_PERIOD_MS, SESSION_WORKFLOW_WAKE_DISPATCHER_SCHEDULE_ID, SESSION_WORKFLOW_WAKE_DISPATCHER_WORKFLOW_TYPE, SessionAuthorizationDeniedError, type SessionAuthorizationDependencies, SessionAuthorizationUnavailableError, SessionSpawnDeniedError, type SessionToolPolicyInput, type SessionWorkflowClient, acceptSessionUserMessage, activateRigVersionForApi, appendRigSetupCommand, applyCapabilityEnablement, assertAllowedEnvironmentVariableName, assertAllowedVariableSetVariableName, assertConfiguredModel, assertPackSandboxImageCompatible, assertToolRefsSubset, assertWorkspaceDeletable, assertWorkspaceMemberRemovable, assertWorkspaceModelPolicyAllows, availableToolRefs, buildCapabilityCatalog, buildFleetContextForSession, buildMarketingDailyAnalysisAgentConfig, canonicalConfiguredModel, checkLimit, classifyRigVerificationOutcome, controlAgentSessionWorkstream, controlHumanSessionWorkstream, controlHumanWorkspace, createAndStartSession, createCatalogItem, createRigForApi, createRigVersionForApi, createSessionForRequest, createValidatedScheduledTask, deleteHumanQueuePrompt, deleteRigForApi, disableCapability, discoverMcpRegistryCapabilities, editHumanQueuePrompt, enableCapability, enabledCapabilityMcpToolRefs, getActorNewSessionDraft, getCapabilityPack, getHumanComposerDraft, hasPermission, isBuiltInCapabilityPack, isUserMember, listCapabilityPacks, listFleet, listRigChangesForApi, listRigVersionsForApi, listWorkspaceCapabilityPacks, manualScheduledTaskTriggerUsageKey, manualScheduledTaskTriggerWorkflowId, memberCanAdminister, mergeResourceRefs, moveHumanQueuePrompt, normalizeResources, officialMcpRegistryUrl, postUserMessageTurn, promoteSetupAppendChange, promoteVerifiedDefinitionEditChangeForApi, proposeRigChangeForApi, provisionSandbox, readSessionLineage, reasoningEffortForSession, recordRigAuditEvent, recordVariableSetAuditEvent, recordWorkspaceUsage, relayConfigFromSettings, relayDialBaseFromSettings, requireAccessContext, requireAccessGrant, requireEnvironmentEncryption, requireLimit, requirePermission, requireQueuedTurnForApi, requireRigChangeForApi, requireRigForApi, requireScheduledTaskForApi, requireSessionAuthorization, requireSessionAuthorizationListScope, requireVariableSetEncryption, requireVariableSetForApi, resolveCapabilityPack, resolveMemberSubjectId, resolveSessionToolPolicy, restoreScheduledTask, rigActorForGrant, routingEnabled, runOnSandbox, saveActorNewSessionDraft, saveHumanComposerDraft, scheduledTaskTemporalScheduleId, scheduledTaskToolsProvided, scheduledTaskTriggerToken, sendAgentSessionMessage, sessionSpawnDenialEnvelope, sessionWithEffectiveToolPolicy, settingsWithEnabledCapabilityMcpServers, settingsWithMcpCapabilityServers, settingsWithSessionMcpServerMetadata, steerAgentSession, steerHumanQueuePrompt, swapActiveSandbox, syncCreatedScheduledTask, syncUpdatedScheduledTask, updateRigForApi, updateSessionMcpApprovalPolicy, updateSessionTitle, validateFileResources, validateGitHubRepositorySelection, validateGitHubRepositorySelectionShape, validateGitHubRepositorySelectionShapes, validateMcpCapabilityConnection, validateToolRefs, validateToolRefsForSessionPolicy, validateVariableSetAttachment, validatedScheduledTaskUpdate, withDefaultEnabledCapabilityMcpTools, workflowIdForSession, workspaceSessionToolPolicyDefaultServerIds, workspaceSessionToolPolicyServerIds, wrapChannelABoxWithRouting };