@opengeni/core 0.8.0 → 0.10.0

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, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, ReasoningEffort, SessionMcpCredentialUpdateInput, SessionEvent, SessionTurn, GoalSpec, SessionMcpServerMetadata, Session, CreateSessionResponse, 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, 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';
 export { mergeToolRefs, stableJson } from '@opengeni/contracts';
 import * as _opengeni_db from '@opengeni/db';
 import { Database, SandboxRecord, EnabledMcpCapabilityServer, UpdateScheduledTaskInput, SessionCommandActor, CreateSessionMcpServerInput, UpdateSessionMcpServerCredentialsInput } from '@opengeni/db';
@@ -155,6 +155,8 @@ type AppDependencies = {
      */
     sessionAuthorization?: SessionAuthorizationPort | null;
     managedAuth?: ManagedAuth | null;
+    /** Injectable Codex HTTP transport for deterministic API/provider tests. */
+    codexFetch?: typeof fetch;
     sandboxClient?: ApiSandboxClient;
     /**
      * Resume a box by id from a serialized resume_state envelope (the lease's
@@ -613,10 +615,21 @@ declare function buildMarketingDailyAnalysisAgentConfig(input: {
     promptInstructions?: string;
 }): ScheduledTaskAgentConfig;
 
-declare function validateToolRefs(tools: ToolRef[], settings: Settings): ToolRef[];
+declare function validateToolRefs(tools: ToolRef[], settings: McpSettings): ToolRef[];
 type McpSettings = Pick<Settings, "mcpServers">;
 declare function enabledCapabilityMcpToolRefs(settings: McpSettings, runtimeSettings: McpSettings): ToolRef[];
 declare function withDefaultEnabledCapabilityMcpTools(tools: ToolRef[], settings: McpSettings, runtimeSettings: McpSettings): ToolRef[];
+/** Drop stored refs that are no longer present in the current runtime registry. */
+declare function availableToolRefs(tools: ToolRef[], settings: McpSettings): ToolRef[];
+/** A child or fixed-policy follow-up may narrow its allow-list, never widen it. */
+declare function assertToolRefsSubset(requested: ToolRef[], allowed: ToolRef[], message?: string): void;
+/** Validate runtime availability and then enforce the durable policy fence. */
+declare function validateToolRefsForSessionPolicy(input: {
+    requested: ToolRef[];
+    settings: McpSettings;
+    allowedTools: ToolRef[];
+    message: string;
+}): ToolRef[];
 declare function normalizeResources(resources: ResourceRef[]): ResourceRef[];
 declare function mergeResourceRefs(existing: ResourceRef[], additions: ResourceRef[]): ResourceRef[];
 declare function validateGitHubRepositorySelectionShapes(resources: ResourceRef[]): number[];
@@ -625,6 +638,34 @@ declare function validateGitHubRepositorySelectionShape(resources: ResourceRef[]
 declare function validateGitHubRepositorySelection(db: Database, workspaceId: string, resources: ResourceRef[]): Promise<void>;
 declare function validateFileResources(db: Database, workspaceId: string, resources: ResourceRef[]): Promise<void>;
 
+type ResolvedSessionToolPolicy = {
+    toolRefs: ToolRef[];
+    effectivePolicy: SessionEffectiveToolPolicy;
+};
+type SessionToolPolicyInput = {
+    toolPolicy?: SessionToolPolicy | null;
+    sessionTools: ToolRef[];
+    turnTools?: ToolRef[];
+    /** Undefined preserves the legacy merge path for pre-provenance callers. */
+    turnToolsProvided?: boolean;
+    availableMcpServerIds: Iterable<string>;
+    /** Current omitted-tools defaults, intentionally narrower than all servers. */
+    defaultMcpServerIds?: Iterable<string>;
+};
+/**
+ * Resolve the same ID-only policy used by API projections and worker turns.
+ * This function never receives endpoint URLs, credentials, schemas, or live
+ * probe results. `availableMcpServerIds` is the resolved runtime registry;
+ * `defaultMcpServerIds` is the capability-only omitted-tools set.
+ */
+declare function resolveSessionToolPolicy(input: SessionToolPolicyInput): ResolvedSessionToolPolicy;
+/** Current full runtime registry IDs, including configured static servers. */
+declare function workspaceSessionToolPolicyServerIds(db: Database, workspaceId: string, settings: Settings): Promise<string[]>;
+/** Current omitted-tools defaults; this preserves capability-first behavior. */
+declare function workspaceSessionToolPolicyDefaultServerIds(db: Database, workspaceId: string, settings: Settings): Promise<string[]>;
+/** Add a bounded, secret-safe effective projection to a session response. */
+declare function sessionWithEffectiveToolPolicy(session: Session, workspaceServerIds: Iterable<string>, workspaceDefaultServerIds?: Iterable<string>): Session;
+
 /**
  * Whether a raw scheduled-task payload explicitly set agentConfig.tools.
  * Zod's `.default([])` erases the distinction between "absent" and
@@ -705,9 +746,11 @@ declare function createAndStartSession(input: {
     turnInstructions?: string | null;
     resources: ResourceRef[];
     tools: ToolRef[];
+    toolPolicy?: SessionToolPolicy;
     clientEventId?: string;
     model: string;
     reasoningEffort: Settings["openaiReasoningEffort"];
+    turnExecutionPolicy: TurnExecutionPolicyV1;
     sandboxBackend: Settings["sandboxBackend"];
     metadata: Record<string, unknown>;
     createdBy?: TurnInitiator;
@@ -753,6 +796,7 @@ declare function workflowIdForSession(sessionId: string): string;
  * later) and the MCP surfaces that share them validate identically and cannot
  * drift.
  */
+declare function canonicalConfiguredModel(settings: Settings, model: string | null | undefined): string | null | undefined;
 declare function assertConfiguredModel(settings: Settings, model: string | null | undefined): void;
 /**
  * Reject a model the WORKSPACE's model policy blocks, at the same choke points
@@ -787,6 +831,7 @@ declare function postUserMessageTurn(input: {
     turnInstructions?: string | null;
     resources: ResourceRef[];
     tools: ToolRef[];
+    toolsProvided: boolean;
     model?: string | null;
     reasoningEffort?: Settings["openaiReasoningEffort"] | null;
     clientEventId?: string;
@@ -798,6 +843,8 @@ declare function postUserMessageTurn(input: {
     commandActor?: SessionCommandActor;
     controlEtag?: string | null;
     expectedDraftRevision?: number | null;
+    reasoningEffortFallback?: Settings["openaiReasoningEffort"];
+    turnExecutionPolicy: TurnExecutionPolicyV1;
 }): Promise<{
     accepted: SessionEvent;
     turn: SessionTurn;
@@ -816,8 +863,9 @@ declare function createSessionForRequest(deps: ApiRouteDeps, grant: AccessGrant,
  * Full accept-user-message flow shared by the `user.message` branch of
  * `POST /sessions/:id/events` and the first-party MCP `session_send_message`
  * tool: resource/tool validation, usage limits, the locked append + turn
- * enqueue, and usage recording. `toolsProvided: false` applies the
- * workspace's default capability MCP tools, matching an absent `tools` key.
+ * enqueue, and usage recording. `toolsProvided: false` durably preserves an
+ * absent `tools` key so execution inherits the session policy; an explicit
+ * empty array is a deliberate per-turn narrowing.
  */
 declare function acceptSessionUserMessage(deps: AcceptSessionUserMessageDependencies, grant: AccessGrant, workspaceId: string, sessionId: string, input: {
     text: string;
@@ -855,6 +903,17 @@ declare function updateSessionTitle(deps: {
     title: string | null;
     relatedSessionAccess: "target" | "root";
 }>;
+/**
+ * Update one existing session MCP server's approval policy. The database
+ * serializes this write with attempt claim under the session lock: an already
+ * claimed attempt retains its immutable snapshot, while the next claim captures
+ * this value. No attempt is cancelled, restarted, or reinterpreted.
+ */
+declare function updateSessionMcpApprovalPolicy(deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+}, grant: AccessGrant, sessionId: string, serverId: string, requireApproval: SessionMcpApprovalPolicy): Promise<UpdateSessionMcpApprovalPolicyResponse>;
 declare function readSessionLineage(deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">, grant: AccessGrant, sessionId: string): Promise<_opengeni_db.SessionLineage>;
 
 /** A member can manage other members (directly or via the admin wildcard). */
@@ -975,4 +1034,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 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 SessionWorkflowClient, acceptSessionUserMessage, activateRigVersionForApi, appendRigSetupCommand, applyCapabilityEnablement, assertAllowedEnvironmentVariableName, assertAllowedVariableSetVariableName, assertConfiguredModel, assertPackSandboxImageCompatible, assertWorkspaceDeletable, assertWorkspaceMemberRemovable, assertWorkspaceModelPolicyAllows, buildCapabilityCatalog, buildFleetContextForSession, buildMarketingDailyAnalysisAgentConfig, 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, restoreScheduledTask, rigActorForGrant, routingEnabled, runOnSandbox, saveHumanComposerDraft, scheduledTaskTemporalScheduleId, scheduledTaskToolsProvided, scheduledTaskTriggerToken, sendAgentSessionMessage, settingsWithEnabledCapabilityMcpServers, settingsWithMcpCapabilityServers, settingsWithSessionMcpServerMetadata, steerAgentSession, steerHumanQueuePrompt, swapActiveSandbox, syncCreatedScheduledTask, syncUpdatedScheduledTask, updateRigForApi, updateSessionTitle, validateFileResources, validateGitHubRepositorySelection, validateGitHubRepositorySelectionShape, validateGitHubRepositorySelectionShapes, validateMcpCapabilityConnection, validateToolRefs, validateVariableSetAttachment, validatedScheduledTaskUpdate, withDefaultEnabledCapabilityMcpTools, workflowIdForSession, 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 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 };