@opengeni/core 0.8.0 → 0.10.0

package/src/domain/sessions.ts

@@ -1,7 +1,14 @@
 import { CODEX_MODEL_ID_PREFIX } from "@opengeni/codex";
-import { configuredAllowedModels, policyProviderIdForModel, type Settings } from "@opengeni/config";
+import {
+  canonicalizeConfiguredModelId,
+  configuredAllowedModels,
+  policyProviderIdForModel,
+  resolveTurnExecutionPolicyV1,
+  type Settings,
+} from "@opengeni/config";
 import {
   CreateSessionRequest,
+  DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   ServiceTurnInitiator,
   ServiceTurnInitiatorContext,
   evaluateWorkspaceModelPolicy,
@@ -14,14 +21,18 @@ import {
   type ResourceRef,
   type Session,
   type SessionEvent,
+  SessionMcpApprovalPolicy,
   type SessionMcpCredentialUpdateInput,
   type SessionMcpServerInput,
   type SessionMcpServerMetadata,
+  type UpdateSessionMcpApprovalPolicyResponse,
   type SessionAuthorizationPort,
+  type SessionToolPolicy,
   type SessionTurn,
   type ToolRef,
   type TurnInitiator,
   type TurnInitiatorContext,
+  type TurnExecutionPolicyV1,
 } from "@opengeni/contracts";
 import {
   createSession,
@@ -47,6 +58,7 @@ import {
   listSessionMcpServersForChildInheritance,
   requireSession,
   submitHumanPromptInTransaction,
+  appendSessionEventsWithLockedSessionUpdate,
   updateSessionTitle as updateSessionTitleRow,
   withWorkspaceSubjectRls,
   type CreateSessionMcpServerInput,
@@ -76,11 +88,14 @@ import { swapActiveSandbox, type FleetContext } from "../sandbox/fleet";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
 import { requireVariableSetEncryption, validateVariableSetAttachment } from "./environments";
 import {
+  assertToolRefsSubset,
+  availableToolRefs,
   mergeToolRefs,
   normalizeResources,
   validateFileResources,
   validateGitHubRepositorySelection,
   validateToolRefs,
+  validateToolRefsForSessionPolicy,
   withDefaultEnabledCapabilityMcpTools,
 } from "./resources";
 
@@ -265,6 +280,7 @@ function mcpServerConfigFromMetadata(
     ...(server.name ? { name: server.name } : {}),
     url: server.url,
     cacheToolsList: false,
+    requireApproval: server.requireApproval,
     ...(server.connectionRef ? { connectionRef: server.connectionRef } : {}),
   };
 }
@@ -340,6 +356,7 @@ function validateSessionMcpServersForCreate(
       url: server.url,
       headerNames: Object.keys(headersEncrypted).sort(),
       credentialVersion: 1,
+      requireApproval: server.requireApproval ?? false,
       connectionRef: server.connectionRef ?? null,
     });
   }
@@ -383,6 +400,7 @@ function validateInheritedSessionMcpServersForCreate(
       url: server.url,
       headerNames: Object.keys(server.headersEncrypted ?? {}).sort(),
       credentialVersion: 1,
+      requireApproval: server.requireApproval ?? false,
       connectionRef: server.connectionRef ?? null,
     })),
   };
@@ -436,9 +454,14 @@ export async function createAndStartSession(input: {
   turnInstructions?: string | null;
   resources: ResourceRef[];
   tools: ToolRef[];
+  // Public admission always supplies provenance; optional keeps internal
+  // callers that predate durable tool-policy provenance source-compatible
+  // during the rolling deploy.
+  toolPolicy?: SessionToolPolicy;
   clientEventId?: string;
   model: string;
   reasoningEffort: Settings["openaiReasoningEffort"];
+  turnExecutionPolicy: TurnExecutionPolicyV1;
   sandboxBackend: Settings["sandboxBackend"];
   metadata: Record<string, unknown>;
   createdBy?: TurnInitiator;
@@ -527,6 +550,7 @@ export async function createAndStartSession(input: {
       initialTurnInstructions: input.turnInstructions ?? null,
       resources: input.resources,
       tools: input.tools,
+      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
       metadata: sessionMetadata,
       ...(input.createdBy ? { createdBy: input.createdBy } : {}),
       ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
@@ -560,6 +584,7 @@ export async function createAndStartSession(input: {
     initialTurnInstructions: input.turnInstructions ?? null,
     resources: input.resources,
     tools: input.tools,
+    ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
     metadata: sessionMetadata,
     ...(input.createdBy ? { createdBy: input.createdBy } : {}),
     ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
@@ -594,9 +619,11 @@ async function finishStartSession(
     turnInstructions?: string | null;
     resources: ResourceRef[];
     tools: ToolRef[];
+    toolPolicy?: SessionToolPolicy;
     clientEventId?: string;
     model: string;
     reasoningEffort: Settings["openaiReasoningEffort"];
+    turnExecutionPolicy: TurnExecutionPolicyV1;
     sandboxBackend: Settings["sandboxBackend"];
     variableSet?: { id: string; name: string } | null;
     goal?: GoalSpec | null;
@@ -647,7 +674,9 @@ async function finishStartSession(
     sessionId: session.id,
     ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
     reasoningEffortFallback: input.reasoningEffort,
+    turnExecutionPolicy: input.turnExecutionPolicy,
     createdEventPayload: {
+      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
       ...(input.variableSet
         ? { variableSetId: input.variableSet.id, variableSetName: input.variableSet.name }
         : {}),
@@ -703,12 +732,16 @@ export function workflowIdForSession(sessionId: string): string {
  * later) and the MCP surfaces that share them validate identically and cannot
  * drift.
  */
-export function assertConfiguredModel(settings: Settings, model: string | null | undefined): void {
+export function canonicalConfiguredModel(
+  settings: Settings,
+  model: string | null | undefined,
+): string | null | undefined {
   if (model === null || model === undefined) {
-    return;
+    return model;
   }
-  if (configuredAllowedModels(settings).includes(model)) {
-    return;
+  const canonicalModel = canonicalizeConfiguredModelId(settings, model);
+  if (configuredAllowedModels(settings).includes(canonicalModel)) {
+    return canonicalModel;
   }
   // Codex subscription models (codex/<slug>) are injected per-workspace by the
   // worker overlay at turn time, so they are never in the deployment-global
@@ -716,12 +749,16 @@ export function assertConfiguredModel(settings: Settings, model: string | null |
   // only surfaces them for a connected workspace, and the worker enforces the
   // actual connection (an unconnected workspace fails the turn with a clear
   // "no Codex subscription connected" error rather than a misleading 422 here).
-  if (settings.codexSubscriptionEnabled && model.startsWith(CODEX_MODEL_ID_PREFIX)) {
-    return;
+  if (settings.codexSubscriptionEnabled && canonicalModel.startsWith(CODEX_MODEL_ID_PREFIX)) {
+    return canonicalModel;
   }
   throw new HTTPException(422, { message: `model is not available: ${model}` });
 }
 
+export function assertConfiguredModel(settings: Settings, model: string | null | undefined): void {
+  canonicalConfiguredModel(settings, model);
+}
+
 /**
  * Reject a model the WORKSPACE's model policy blocks, at the same choke points
  * as assertConfiguredModel — a 422 at the edge instead of a queued turn the
@@ -742,18 +779,25 @@ export async function assertWorkspaceModelPolicyAllows(
   if (model === null || model === undefined) {
     return;
   }
+  const canonicalModel = canonicalConfiguredModel(settings, model);
+  if (canonicalModel === null || canonicalModel === undefined) {
+    return;
+  }
   const policy = await getWorkspaceModelPolicy(db, workspaceId);
   if (!policy) {
     return;
   }
-  const providerId = policyProviderIdForModel(settings, model);
-  const verdict = evaluateWorkspaceModelPolicy(policy, { providerId, modelId: model });
+  const providerId = policyProviderIdForModel(settings, canonicalModel);
+  const verdict = evaluateWorkspaceModelPolicy(policy, {
+    providerId,
+    modelId: canonicalModel,
+  });
   if (!verdict.allowed) {
     throw new HTTPException(422, {
       message:
         verdict.reason === "provider"
-          ? `model "${model}" is not allowed by this workspace's model policy: provider "${providerId}" is not in the allowed providers`
-          : `model "${model}" is not allowed by this workspace's model policy`,
+          ? `model "${canonicalModel}" is not allowed by this workspace's model policy: provider "${providerId}" is not in the allowed providers`
+          : `model "${canonicalModel}" is not allowed by this workspace's model policy`,
     });
   }
 }
@@ -802,6 +846,7 @@ export async function postUserMessageTurn(input: {
   turnInstructions?: string | null;
   resources: ResourceRef[];
   tools: ToolRef[];
+  toolsProvided: boolean;
   model?: string | null;
   reasoningEffort?: Settings["openaiReasoningEffort"] | null;
   clientEventId?: string;
@@ -813,9 +858,11 @@ export async function postUserMessageTurn(input: {
   commandActor?: SessionCommandActor;
   controlEtag?: string | null;
   expectedDraftRevision?: number | null;
+  reasoningEffortFallback?: Settings["openaiReasoningEffort"];
+  turnExecutionPolicy: TurnExecutionPolicyV1;
 }): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
   const { db, bus, workflowClient, settings, accountId, workspaceId, sessionId } = input;
-  const requestedModel = input.model ?? null;
+  const requestedModel = canonicalConfiguredModel(settings, input.model ?? null) ?? null;
   const requestedReasoningEffort = input.reasoningEffort ?? null;
   // Reject an explicit per-message model the host does not expose; an omitted
   // model inherits the session's model downstream (always a configured id).
@@ -844,9 +891,11 @@ export async function postUserMessageTurn(input: {
           turnInstructions: input.turnInstructions ?? null,
           resources: input.resources,
           tools: input.tools,
+          toolsProvided: input.toolsProvided,
           model: requestedModel,
           reasoningEffort: requestedReasoningEffort,
-          reasoningEffortFallback: settings.openaiReasoningEffort,
+          reasoningEffortFallback: input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
+          turnExecutionPolicy: input.turnExecutionPolicy,
           source: input.origin === "operator" ? "api" : "user",
           mcpCredentialUpdates: input.mcpCredentialUpdates ?? [],
         }),
@@ -973,21 +1022,58 @@ export async function createSessionForRequest(
       ? payload.resources
       : (parentSession?.resources ?? payload.resources),
   );
+  const toolsProvided = hasOwnProperty(rawPayload, "tools");
   const requestedTools = validateToolRefs(
-    hasOwnProperty(rawPayload, "tools") ? payload.tools : (parentSession?.tools ?? payload.tools),
+    toolsProvided ? payload.tools : (parentSession?.tools ?? payload.tools),
     runtimeSettings,
   );
-  const defaultedTools =
-    hasOwnProperty(rawPayload, "tools") || parentSession
-      ? requestedTools
-      : withDefaultEnabledCapabilityMcpTools(requestedTools, settings, capabilityRuntimeSettings);
+  let selectedTools: ToolRef[];
+  let toolPolicy: SessionToolPolicy;
+  if (parentSession) {
+    const parentTracksWorkspaceDefaults = parentSession.toolPolicy?.mode === "workspace_default";
+    const parentEffective = withFirstPartyTools(
+      parentTracksWorkspaceDefaults
+        ? withDefaultEnabledCapabilityMcpTools(
+            availableToolRefs(parentSession.tools, runtimeSettings),
+            settings,
+            runtimeSettings,
+          )
+        : parentSession.tools,
+      runtimeSettings,
+    );
+    if (toolsProvided) {
+      assertToolRefsSubset(
+        requestedTools,
+        parentEffective,
+        "child tools may only narrow the parent session tool policy",
+      );
+      selectedTools = requestedTools;
+      toolPolicy = { mode: "explicit", inheritedFromSessionId: parentSession.id };
+    } else {
+      selectedTools = parentEffective;
+      toolPolicy = {
+        mode: parentTracksWorkspaceDefaults ? "workspace_default" : "inherited",
+        inheritedFromSessionId: parentSession.id,
+      };
+    }
+  } else if (toolsProvided) {
+    selectedTools = requestedTools;
+    toolPolicy = { mode: "explicit", inheritedFromSessionId: null };
+  } else {
+    selectedTools = withDefaultEnabledCapabilityMcpTools(
+      requestedTools,
+      settings,
+      capabilityRuntimeSettings,
+    );
+    toolPolicy = { mode: "workspace_default", inheritedFromSessionId: null };
+  }
   // The first-party MCP server is attached to EVERY session. It hosts the
   // session's own metadata tool (set_session_title) + goal tools, and — only
   // when the grant carries the permission — the orchestration/variableSet/
   // github tools. Capability is gated per-tool by permission, never by whether
   // the server is attached, so a bare chat still gets titling while the
   // dangerous tools stay off by default.
-  const tools = withFirstPartyTools(defaultedTools, runtimeSettings);
+  const tools = withFirstPartyTools(selectedTools, runtimeSettings);
   await validateGitHubRepositorySelection(db, workspaceId, resources);
   if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
     throw new HTTPException(503, { message: "object storage is not configured" });
@@ -1033,19 +1119,23 @@ export async function createSessionForRequest(
       frozenRigVersionId = rig.activeVersion.id;
     }
   }
-  assertConfiguredModel(settings, payload.model);
+  const model = canonicalConfiguredModel(settings, payload.model ?? settings.openaiModel);
+  if (model === null || model === undefined) {
+    throw new Error("effective session model unexpectedly resolved to null");
+  }
   // Session creation persists the EFFECTIVE model — an omitted payload.model
   // stamps the deployment default onto the session — so the policy must vet
   // that effective value, not just explicit ones (a restricted workspace's
   // default-model session would otherwise be born blocked).
-  await assertWorkspaceModelPolicyAllows(
-    db,
-    settings,
-    workspaceId,
-    payload.model ?? settings.openaiModel,
-  );
-  const model = payload.model ?? settings.openaiModel;
+  await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, model);
   const reasoningEffort = payload.reasoningEffort ?? settings.openaiReasoningEffort;
+  const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
+    modelId: model,
+    requestedModelId: payload.model ?? null,
+    modelSource: payload.model === undefined ? "deployment" : "explicit",
+    reasoningEffort,
+    reasoningSource: payload.reasoningEffort === undefined ? "deployment" : "explicit",
+  });
   // Parent linkage was resolved above, before context validation. A child with
   // no explicit permission override inherits the creating session's effective
   // grant instead of silently expanding to standalone worker defaults.
@@ -1056,8 +1146,30 @@ export async function createSessionForRequest(
   // normal worker defaults. A child omission inherits its creator's exact
   // effective grant, preserving a host/operator's narrowed capability boundary
   // through the whole session tree.
+  const parentFirstPartyMcpPermissions = parentSession
+    ? [...(parentSession.firstPartyMcpPermissions ?? DEFAULT_FIRST_PARTY_MCP_PERMISSIONS)]
+    : null;
+  if (
+    parentFirstPartyMcpPermissions &&
+    payload.firstPartyMcpPermissions?.some(
+      (permission) => !hasPermission(parentFirstPartyMcpPermissions, permission),
+    )
+  ) {
+    throw new HTTPException(403, {
+      message: "child first-party MCP permissions may only narrow the parent session grant",
+    });
+  }
+  // A worker-signed creator may itself carry less authority than its parent
+  // session (for example a narrowly delegated spawn token). Inherit the
+  // intersection in the shared canonical default order so null/default parent
+  // policies cannot expand when runtime signing resolves them.
   let firstPartyMcpPermissions =
-    payload.firstPartyMcpPermissions ?? (parentSessionId ? [...new Set(grant.permissions)] : null);
+    payload.firstPartyMcpPermissions ??
+    (parentFirstPartyMcpPermissions
+      ? parentFirstPartyMcpPermissions.filter((permission) =>
+          hasPermission(grant.permissions, permission),
+        )
+      : null);
   if (firstPartyMcpPermissions && firstPartyMcpPermissions.length === 0) {
     // An empty set would sign an unusable zero-permission token; the default
     // worker set is expressed by omitting the field.
@@ -1322,9 +1434,11 @@ export async function createSessionForRequest(
       turnInstructions: payload.turnInstructions ?? null,
       resources,
       tools,
+      toolPolicy,
       ...(payload.clientEventId ? { clientEventId: payload.clientEventId } : {}),
       model,
       reasoningEffort,
+      turnExecutionPolicy,
       // A shared spawn inherits the box's backend; a caller-supplied
       // sandboxBackend on a shared spawn is ignored (it is the same box). A
       // machine-targeted top-level create labels the home "selfhosted"
@@ -1396,8 +1510,9 @@ export async function createSessionForRequest(
  * 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.
  */
 export async function acceptSessionUserMessage(
   deps: AcceptSessionUserMessageDependencies,
@@ -1420,6 +1535,12 @@ export async function acceptSessionUserMessage(
     expectedDraftRevision?: number | null;
   },
 ): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
+  if (input.toolsProvided && !deps.settings.sessionTurnToolReplacementEnabled) {
+    throw new HTTPException(503, {
+      message:
+        "explicit follow-up tool replacement is temporarily unavailable until provenance-aware turn workers finish rolling out; omit tools to inherit the session policy and retry",
+    });
+  }
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   await requireSessionAuthorization(deps, grant, {
     sessionId,
@@ -1435,21 +1556,55 @@ export async function acceptSessionUserMessage(
   // turn's effective model (a follow-up turn inherits the session's model). A
   // pure read with no side effects.
   const existingSession = await requireSession(db, workspaceId, sessionId);
+  const requestedModel = canonicalConfiguredModel(settings, input.model ?? null) ?? null;
+  const effectiveModel =
+    canonicalConfiguredModel(settings, requestedModel ?? existingSession.model) ?? null;
+  if (effectiveModel === null) {
+    throw new Error("effective follow-up model unexpectedly resolved to null");
+  }
+  const sessionReasoningEffort = reasoningEffortForSession(
+    existingSession.metadata,
+    settings.openaiReasoningEffort,
+  );
+  const effectiveReasoningEffort = input.reasoningEffort ?? sessionReasoningEffort;
+  const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
+    modelId: effectiveModel,
+    requestedModelId: input.model ?? null,
+    modelSource: input.model == null ? "session" : "explicit",
+    reasoningEffort: effectiveReasoningEffort,
+    reasoningSource: input.reasoningEffort == null ? "session" : "explicit",
+  });
   const runtimeSettings = settingsWithSessionMcpServerMetadata(
     capabilityRuntimeSettings,
     existingSession.mcpServers,
   );
   const requestedResources = normalizeResources(input.resources ?? []);
-  const validatedTools = validateToolRefs(input.tools ?? [], runtimeSettings);
-  const requestedTools = input.toolsProvided
-    ? validatedTools
-    : withDefaultEnabledCapabilityMcpTools(validatedTools, settings, capabilityRuntimeSettings);
+  const tracksWorkspaceDefaults = existingSession.toolPolicy?.mode === "workspace_default";
+  const sessionPolicyTools = withFirstPartyTools(
+    tracksWorkspaceDefaults
+      ? withDefaultEnabledCapabilityMcpTools(
+          availableToolRefs(existingSession.tools, runtimeSettings),
+          settings,
+          capabilityRuntimeSettings,
+        )
+      : existingSession.tools,
+    runtimeSettings,
+  );
+  const validatedTools = input.toolsProvided
+    ? validateToolRefsForSessionPolicy({
+        requested: input.tools ?? [],
+        settings: runtimeSettings,
+        allowedTools: sessionPolicyTools,
+        message: "message tools may only narrow the session tool policy",
+      })
+    : [];
+  const requestedTools = input.toolsProvided ? validatedTools : [];
   await requireLimit(deps, {
     accountId: grant.accountId,
     workspaceId,
     action: "agent_run:create",
     quantity: 1,
-    model: input.model ?? existingSession.model,
+    model: effectiveModel,
   });
   if (requestedResources.some((resource) => resource.kind === "file") && !objectStorage) {
     throw new HTTPException(503, { message: "object storage is not configured" });
@@ -1478,8 +1633,11 @@ export async function acceptSessionUserMessage(
     turnInstructions: input.turnInstructions ?? null,
     resources: requestedResources,
     tools: requestedTools,
+    toolsProvided: input.toolsProvided,
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
+    reasoningEffortFallback: sessionReasoningEffort,
+    turnExecutionPolicy,
     mcpCredentialUpdates,
     delivery: input.delivery ?? "send",
     origin: delegatedServiceInitiator ? "operator" : (input.origin ?? "human"),
@@ -1571,6 +1729,68 @@ export async function updateSessionTitle(
   };
 }
 
+/**
+ * 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.
+ */
+export async function updateSessionMcpApprovalPolicy(
+  deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+  },
+  grant: AccessGrant,
+  sessionId: string,
+  serverId: string,
+  requireApproval: SessionMcpApprovalPolicy,
+): Promise<UpdateSessionMcpApprovalPolicyResponse> {
+  const normalizedPolicy = SessionMcpApprovalPolicy.parse(requireApproval);
+  await requireSessionAuthorization(deps, grant, {
+    sessionId,
+    operation: "session.mcp.approval_policy.write",
+    surface: "core",
+  });
+  requirePermission(grant, "sessions:control");
+
+  const outcome: { server?: SessionMcpServerMetadata } = {};
+  const events = await appendSessionEventsWithLockedSessionUpdate(
+    deps.db,
+    grant.workspaceId,
+    sessionId,
+    async (_session, context) => {
+      const result = await context.updateSessionMcpApprovalPolicy(serverId, normalizedPolicy);
+      if (!result.server) {
+        throw new HTTPException(404, { message: "session MCP server not found" });
+      }
+      outcome.server = result.server;
+      return {
+        events: result.changed
+          ? [
+              {
+                type: "session.mcp.approval_policy.updated" as const,
+                payload: {
+                  serverId,
+                  effectiveFrom: "next_attempt",
+                },
+              },
+            ]
+          : [],
+      };
+    },
+  );
+  const updatedServer = outcome.server;
+  if (!updatedServer) {
+    throw new Error("session MCP approval policy update returned no server");
+  }
+  await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, events);
+  return {
+    server: updatedServer,
+    effectiveFrom: "next_attempt",
+  };
+}
+
 export async function readSessionLineage(
   deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">,
   grant: AccessGrant,

package/src/index.ts

@@ -57,6 +57,7 @@ export * from "./domain/environments";
 export * from "./rigs";
 export * from "./domain/packs";
 export * from "./domain/resources";
+export * from "./domain/session-tool-policy";
 export * from "./domain/scheduled-tasks";
 export * from "./domain/sessions";
 export * from "./domain/workspace-members";