@opengeni/core 0.12.7 → 0.12.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.12.7",
+  "version": "0.12.10",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -35,14 +35,14 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/codex": "^0.2.7",
-    "@opengeni/config": "^0.7.11",
-    "@opengeni/contracts": "^0.22.0",
-    "@opengeni/db": "^0.14.0",
-    "@opengeni/documents": "^0.2.42",
-    "@opengeni/events": "^0.3.33",
+    "@opengeni/config": "^0.7.13",
+    "@opengeni/contracts": "^0.23.0",
+    "@opengeni/db": "^0.14.3",
+    "@opengeni/documents": "^0.2.45",
+    "@opengeni/events": "^0.3.36",
     "@opengeni/observability": "^0.3.0",
-    "@opengeni/runtime": "^0.14.1",
-    "@opengeni/storage": "^0.2.35",
+    "@opengeni/runtime": "^0.14.3",
+    "@opengeni/storage": "^0.2.37",
     "hono": "^4.12.18"
   },
   "engines": {

package/src/application/session-commands.ts

@@ -7,6 +7,7 @@ import type {
   AccessGrant,
   SessionAuthorizationOperation,
   SessionAuthorizationPort,
+  SessionAuthorizationSurface,
   SessionCommandReceipt,
   SessionControlRequest,
   SessionControlResponse,
@@ -55,6 +56,8 @@ export type HumanSessionCommandContext = {
   workspaceId: string;
   sessionId: string;
   subjectId: string;
+  /** See AgentSessionCommandContext.authorizationSurface. */
+  authorizationSurface?: SessionAuthorizationSurface;
 };
 
 export type AgentSessionCommandContext = {
@@ -65,6 +68,13 @@ export type AgentSessionCommandContext = {
   callerTurnId: string;
   callerAttemptId: string;
   callerExecutionGeneration: number;
+  /**
+   * The trusted adapter surface that owns this command's one authorization
+   * decision. Direct core callers omit it and retain the canonical `core`
+   * surface; adapters that delegate the complete command set it explicitly so
+   * they do not authorize once at the edge and then repeat the host call here.
+   */
+  authorizationSurface?: SessionAuthorizationSurface;
 };
 
 type SessionAuthorizationCommandDeps = {
@@ -104,7 +114,7 @@ async function authorizeHumanSessionCommand(
   return await requireSessionAuthorization(deps, humanAccessGrant(context), {
     sessionId: context.sessionId,
     operation,
-    surface: "core",
+    surface: context.authorizationSurface ?? "core",
   });
 }
 
@@ -117,7 +127,7 @@ async function authorizeAgentSessionCommand(
   return await requireSessionAuthorization(deps, agentAccessGrant(context), {
     sessionId: targetSessionId,
     operation,
-    surface: "core",
+    surface: context.authorizationSurface ?? "core",
   });
 }
 
@@ -339,7 +349,12 @@ export async function controlAgentSessionWorkstream(
     reason?: string | null;
   },
 ) {
-  await authorizeAgentSessionCommand(deps, context, input.targetSessionId, "session.control");
+  const authorization = await authorizeAgentSessionCommand(
+    deps,
+    context,
+    input.targetSessionId,
+    "session.control",
+  );
   const result = await withWorkspaceRls(deps.db, context.workspaceId, (scoped) =>
     scoped.transaction((tx) =>
       mutateSessionControlInTransaction(tx as unknown as Database, {
@@ -358,7 +373,7 @@ export async function controlAgentSessionWorkstream(
   ]);
   await publishWorkspaceControlEvent(deps, context.workspaceId, result.workspaceControlEventId);
   await requestControlWakeDispatch(deps, result.wakeCount);
-  return result;
+  return { ...result, authorization };
 }
 
 function receipt(row: SessionCommandReceiptRow): SessionCommandReceipt {
@@ -384,8 +399,6 @@ function composerDraft(
     revision: row.revision,
     text: row.text,
     resources: row.resources as ComposerDraft["resources"],
-    tools: row.tools as ComposerDraft["tools"],
-    toolsProvided: row.toolsProvided,
     model: row.model,
     reasoningEffort: row.reasoningEffort as ComposerDraft["reasoningEffort"],
     sourceTurnId: row.sourceTurnId,
@@ -648,8 +661,6 @@ export async function getHumanComposerDraft(
     revision: 0,
     text: "",
     resources: [],
-    tools: [],
-    toolsProvided: false,
     model: session.model,
     reasoningEffort: reasoningEffortForMetadata(session.metadata, "medium"),
     sourceTurnId: null,

package/src/domain/session-tool-policy.ts

@@ -21,11 +21,8 @@ export type ResolvedSessionToolPolicy = {
 };
 
 export type SessionToolPolicyInput = {
-  toolPolicy?: SessionToolPolicy | null;
+  toolPolicy: SessionToolPolicy;
   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>;
@@ -55,7 +52,7 @@ function projectIds(ids: readonly string[]): { ids: string[]; truncated: boolean
  * `defaultMcpServerIds` is the capability-only omitted-tools set.
  */
 export function resolveSessionToolPolicy(input: SessionToolPolicyInput): ResolvedSessionToolPolicy {
-  const policy = input.toolPolicy ?? { mode: "legacy" as const, inheritedFromSessionId: null };
+  const policy = input.toolPolicy;
   const availableIds = new Set(input.availableMcpServerIds);
   // Never infer omitted-tools defaults from the full runtime registry: static
   // MCPs are explicit-only unless they are capability-derived defaults.
@@ -64,14 +61,8 @@ export function resolveSessionToolPolicy(input: SessionToolPolicyInput): Resolve
     availableIds.has(id),
   );
   const mandatoryIdSet = new Set<string>(mandatoryIds);
-  const selectedRefs =
-    input.turnToolsProvided === true
-      ? mergeToolRefs([], input.turnTools ?? [])
-      : input.turnToolsProvided === false
-        ? mergeToolRefs([], input.sessionTools)
-        : mergeToolRefs(input.sessionTools, input.turnTools ?? []);
-  const tracksWorkspaceDefaults =
-    policy.mode === "workspace_default" && input.turnToolsProvided !== true;
+  const selectedRefs = mergeToolRefs([], input.sessionTools);
+  const tracksWorkspaceDefaults = policy.mode === "workspace_default";
 
   // Optional capability refs are a historical materialization of a
   // workspace-default selection. They may outlive an installation or its
@@ -214,7 +205,7 @@ export function sessionWithEffectiveToolPolicy(
   return {
     ...session,
     effectiveToolPolicy: resolveSessionToolPolicy({
-      ...(session.toolPolicy ? { toolPolicy: session.toolPolicy } : {}),
+      toolPolicy: session.toolPolicy,
       sessionTools: session.tools,
       availableMcpServerIds: availableIds,
       defaultMcpServerIds: workspaceDefaultServerIds,

package/src/domain/sessions.ts

@@ -10,6 +10,7 @@ import {
   CreateSessionRequest,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   DEFAULT_FIRST_PARTY_MCP_TOOLS,
+  FIRST_PARTY_MCP_TOOL_NAMES,
   OPENGENI_SLACK_BOT_SESSION_METADATA_KEY,
   SessionSpawnDenial,
   ServiceTurnInitiator,
@@ -105,7 +106,6 @@ import {
   validateFileResources,
   validateGitHubRepositorySelection,
   validateToolRefs,
-  validateToolRefsForSessionPolicy,
   withDefaultEnabledCapabilityMcpTools,
 } from "./resources";
 
@@ -138,9 +138,9 @@ export class SessionSpawnDeniedError extends Error {
 export function resolveFirstPartyMcpToolsForCreate(
   requested: FirstPartyMcpToolName[] | undefined,
   parentStored: FirstPartyMcpToolName[] | null | undefined,
-): FirstPartyMcpToolName[] | null {
+): FirstPartyMcpToolName[] {
   if (requested !== undefined) return [...requested];
-  if (parentStored === undefined) return null;
+  if (parentStored === undefined) return [...DEFAULT_FIRST_PARTY_MCP_TOOLS];
   return [...(parentStored ?? DEFAULT_FIRST_PARTY_MCP_TOOLS)];
 }
 
@@ -514,7 +514,7 @@ export async function createAndStartSession(input: {
   // Public admission always supplies provenance; optional keeps internal
   // callers that predate durable tool-policy provenance source-compatible
   // during the rolling deploy.
-  toolPolicy?: SessionToolPolicy;
+  toolPolicy: SessionToolPolicy;
   clientEventId?: string;
   model: string;
   reasoningEffort: Settings["openaiReasoningEffort"];
@@ -541,7 +541,7 @@ export async function createAndStartSession(input: {
   firstPartyMcpPermissions?: Permission[] | null;
   // Model-visible first-party tool names. Authorization remains controlled by
   // firstPartyMcpPermissions and the target resource checks.
-  firstPartyMcpTools?: FirstPartyMcpToolName[] | null;
+  firstPartyMcpTools: FirstPartyMcpToolName[];
   // Encrypted DB rows plus matching safe metadata for create-time per-session
   // MCP servers. Metadata is the only shape emitted in events/responses.
   mcpServers?: CreateSessionMcpServerInput[];
@@ -602,7 +602,7 @@ export async function createAndStartSession(input: {
       resources: input.resources,
       skills: input.skills ?? [],
       tools: input.tools,
-      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
+      toolPolicy: input.toolPolicy,
       metadata: sessionMetadata,
       ...(input.createdBy ? { createdBy: input.createdBy } : {}),
       ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
@@ -613,7 +613,7 @@ export async function createAndStartSession(input: {
       rigId: input.rigId ?? null,
       rigVersionId: input.rigVersionId ?? null,
       firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
-      firstPartyMcpTools: input.firstPartyMcpTools ?? null,
+      firstPartyMcpTools: input.firstPartyMcpTools,
       instructions: input.instructions ?? null,
       parentSessionId: input.parentSessionId ?? null,
       createIdempotencyKey: input.createIdempotencyKey,
@@ -647,7 +647,7 @@ export async function createAndStartSession(input: {
       resources: input.resources,
       skills: input.skills ?? [],
       tools: input.tools,
-      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
+      toolPolicy: input.toolPolicy,
       metadata: sessionMetadata,
       ...(input.createdBy ? { createdBy: input.createdBy } : {}),
       ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
@@ -658,7 +658,7 @@ export async function createAndStartSession(input: {
       rigId: input.rigId ?? null,
       rigVersionId: input.rigVersionId ?? null,
       firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
-      firstPartyMcpTools: input.firstPartyMcpTools ?? null,
+      firstPartyMcpTools: input.firstPartyMcpTools,
       instructions: input.instructions ?? null,
       parentSessionId: input.parentSessionId ?? null,
       sandboxGroupId: input.sandboxGroupId ?? null,
@@ -692,7 +692,7 @@ async function finishStartSession(
     turnInstructions?: string | null;
     resources: ResourceRef[];
     tools: ToolRef[];
-    toolPolicy?: SessionToolPolicy;
+    toolPolicy: SessionToolPolicy;
     clientEventId?: string;
     model: string;
     reasoningEffort: Settings["openaiReasoningEffort"];
@@ -750,7 +750,7 @@ async function finishStartSession(
     reasoningEffortFallback: input.reasoningEffort,
     turnExecutionPolicy: input.turnExecutionPolicy,
     createdEventPayload: {
-      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
+      toolPolicy: input.toolPolicy,
       ...(input.variableSet
         ? { variableSetId: input.variableSet.id, variableSetName: input.variableSet.name }
         : {}),
@@ -920,8 +920,6 @@ export async function postUserMessageTurn(input: {
   text: string;
   turnInstructions?: string | null;
   resources: ResourceRef[];
-  tools: ToolRef[];
-  toolsProvided: boolean;
   model?: string | null;
   reasoningEffort?: Settings["openaiReasoningEffort"] | null;
   clientEventId?: string;
@@ -965,8 +963,6 @@ export async function postUserMessageTurn(input: {
           text: input.text,
           turnInstructions: input.turnInstructions ?? null,
           resources: input.resources,
-          tools: input.tools,
-          toolsProvided: input.toolsProvided,
           model: requestedModel,
           reasoningEffort: requestedReasoningEffort,
           reasoningEffortFallback: input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
@@ -1298,15 +1294,14 @@ export async function createSessionForRequest(
   }
   // Tool visibility is independent from permission authority. A child that
   // omits the field inherits the parent's exact effective selection; a
-  // top-level omission resolves to the fixed minimal default at execution.
+  // top-level omission selects the complete catalog.
   const firstPartyMcpTools = resolveFirstPartyMcpToolsForCreate(
     payload.firstPartyMcpTools,
     parentSession ? parentSession.firstPartyMcpTools : undefined,
   );
   if (payload.goal) {
-    const effectiveTools = firstPartyMcpTools ?? [...DEFAULT_FIRST_PARTY_MCP_TOOLS];
     const missingGoalTools = ["goal_update", "goal_complete", "goal_pause"].filter(
-      (name) => !effectiveTools.includes(name as FirstPartyMcpToolName),
+      (name) => !firstPartyMcpTools.includes(name as FirstPartyMcpToolName),
     );
     if (missingGoalTools.length > 0) {
       throw new HTTPException(422, {
@@ -1636,8 +1631,7 @@ export async function createSessionForRequest(
  * `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` durably preserves an
- * absent `tools` key so execution inherits the session policy; an explicit
- * empty array is a deliberate per-turn narrowing.
+ * Tool selection is durable session state and never rides a follow-up prompt.
  */
 export async function acceptSessionUserMessage(
   deps: AcceptSessionUserMessageDependencies,
@@ -1648,8 +1642,6 @@ export async function acceptSessionUserMessage(
     text: string;
     turnInstructions?: string | null;
     resources?: ResourceRef[];
-    tools?: ToolRef[];
-    toolsProvided: boolean;
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
     clientEventId?: string;
@@ -1660,23 +1652,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,
     operation: input.delivery === "steer" ? "session.steer" : "session.append",
     surface: "core",
   });
-  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
-    db,
-    workspaceId,
-    settings,
-  );
   // Hoisted above requireLimit so the codex-billed predicate can resolve the
   // turn's effective model (a follow-up turn inherits the session's model). A
   // pure read with no side effects.
@@ -1699,31 +1680,7 @@ export async function acceptSessionUserMessage(
     reasoningEffort: effectiveReasoningEffort,
     reasoningSource: input.reasoningEffort == null ? "session" : "explicit",
   });
-  const runtimeSettings = settingsWithSessionMcpServerMetadata(
-    capabilityRuntimeSettings,
-    existingSession.mcpServers,
-  );
   const requestedResources = normalizeResources(input.resources ?? []);
-  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,
@@ -1757,8 +1714,6 @@ export async function acceptSessionUserMessage(
     text: input.text,
     turnInstructions: input.turnInstructions ?? null,
     resources: requestedResources,
-    tools: requestedTools,
-    toolsProvided: input.toolsProvided,
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
     reasoningEffortFallback: sessionReasoningEffort,
@@ -1919,7 +1874,8 @@ export async function updateSessionMcpApprovalPolicy(
 function toolPolicyAuditSnapshot(
   session: Session,
   tools: ToolRef[],
-  policy = session.toolPolicy ?? { mode: "legacy" as const, inheritedFromSessionId: null },
+  firstPartyMcpTools: FirstPartyMcpToolName[],
+  policy = session.toolPolicy,
 ) {
   // Tool policy refs contain only public server ids and the optional/strict
   // execution mode; they never carry URLs, names, headers, credentials,
@@ -1951,6 +1907,8 @@ function toolPolicyAuditSnapshot(
       .map((tool) => tool.id),
     toolRefs,
     toolCount: allToolRefs.length,
+    firstPartyMcpTools: [...firstPartyMcpTools].sort(),
+    firstPartyMcpToolCount: firstPartyMcpTools.length,
     truncated: allToolRefs.length > toolRefs.length,
   };
 }
@@ -2004,10 +1962,14 @@ export async function updateSessionToolPolicy(
         return withFirstPartyTools(validatedTools, runtimeSettings);
       })()
     : null;
+  const explicitRequestedFirstPartyTools = explicitRequest
+    ? [...explicitRequest.firstPartyMcpTools]
+    : null;
   const workspaceDefaultTools = withFirstPartyTools(
     withDefaultEnabledCapabilityMcpTools([], deps.settings, capabilityRuntimeSettings),
     runtimeSettings,
   );
+  const workspaceDefaultFirstPartyTools = [...FIRST_PARTY_MCP_TOOL_NAMES];
   const events = await appendSessionEventsWithLockedSessionUpdate(
     deps.db,
     grant.workspaceId,
@@ -2019,6 +1981,7 @@ export async function updateSessionToolPolicy(
       }
 
       let nextTools: ToolRef[];
+      let nextFirstPartyMcpTools: FirstPartyMcpToolName[];
       let nextPolicy: SessionToolPolicy;
       if (session.parentSessionId) {
         const parent = await context.getLockedSession(session.parentSessionId);
@@ -2036,6 +1999,9 @@ export async function updateSessionToolPolicy(
             : parent.tools,
           runtimeSettings,
         );
+        const parentFirstPartyMcpTools = [
+          ...(parent.firstPartyMcpTools ?? DEFAULT_FIRST_PARTY_MCP_TOOLS),
+        ];
         if (requestedMode === "workspace_default") {
           if (!parentTracksWorkspaceDefaults) {
             throw new HTTPException(403, {
@@ -2044,6 +2010,7 @@ export async function updateSessionToolPolicy(
             });
           }
           nextTools = parentEffective;
+          nextFirstPartyMcpTools = parentFirstPartyMcpTools;
           nextPolicy = {
             mode: "workspace_default",
             inheritedFromSessionId: parent.id,
@@ -2055,6 +2022,16 @@ export async function updateSessionToolPolicy(
             parentEffective,
             "session tools may only narrow the parent session tool policy",
           );
+          const parentFirstPartySet = new Set(parentFirstPartyMcpTools);
+          const widenedFirstPartyTool = explicitRequestedFirstPartyTools!.find(
+            (tool) => !parentFirstPartySet.has(tool),
+          );
+          if (widenedFirstPartyTool) {
+            throw new HTTPException(403, {
+              message: `session OpenGeni tools may only narrow the parent policy: ${widenedFirstPartyTool}`,
+            });
+          }
+          nextFirstPartyMcpTools = explicitRequestedFirstPartyTools!;
           nextPolicy = {
             mode: "explicit",
             inheritedFromSessionId: parent.id,
@@ -2063,20 +2040,29 @@ export async function updateSessionToolPolicy(
       } else {
         nextTools =
           requestedMode === "workspace_default" ? workspaceDefaultTools : explicitRequestedTools!;
+        nextFirstPartyMcpTools =
+          requestedMode === "workspace_default"
+            ? workspaceDefaultFirstPartyTools
+            : explicitRequestedFirstPartyTools!;
         nextPolicy = { mode: requestedMode, inheritedFromSessionId: null };
       }
 
-      const currentPolicy = session.toolPolicy ?? {
-        mode: "legacy" as const,
-        inheritedFromSessionId: null,
-      };
+      const currentPolicy = session.toolPolicy;
       // JSONB normalizes object-key order on the round trip, so plain
       // JSON.stringify would turn an identical retry into a second mutation
       // (and version bump) merely because the persisted key order differs from
       // the request object. Compare canonical JSON instead.
       const unchanged =
-        stableJson({ tools: session.tools, policy: currentPolicy }) ===
-        stableJson({ tools: nextTools, policy: nextPolicy });
+        stableJson({
+          tools: session.tools,
+          firstPartyMcpTools: session.firstPartyMcpTools ?? DEFAULT_FIRST_PARTY_MCP_TOOLS,
+          policy: currentPolicy,
+        }) ===
+        stableJson({
+          tools: nextTools,
+          firstPartyMcpTools: nextFirstPartyMcpTools,
+          policy: nextPolicy,
+        });
       if (unchanged) {
         return { events: [] };
       }
@@ -2087,8 +2073,18 @@ export async function updateSessionToolPolicy(
           {
             type: "session.tool_policy.updated" as const,
             payload: {
-              before: toolPolicyAuditSnapshot(session, session.tools, currentPolicy),
-              after: toolPolicyAuditSnapshot(session, nextTools, nextPolicy),
+              before: toolPolicyAuditSnapshot(
+                session,
+                session.tools,
+                [...(session.firstPartyMcpTools ?? DEFAULT_FIRST_PARTY_MCP_TOOLS)],
+                currentPolicy,
+              ),
+              after: toolPolicyAuditSnapshot(
+                session,
+                nextTools,
+                nextFirstPartyMcpTools,
+                nextPolicy,
+              ),
               version: nextVersion,
               effectiveFrom: "next_attempt",
             },
@@ -2096,6 +2092,7 @@ export async function updateSessionToolPolicy(
         ],
         update: {
           tools: nextTools,
+          firstPartyMcpTools: nextFirstPartyMcpTools,
           toolPolicy: nextPolicy,
           toolPolicyVersion: nextVersion,
           expectedToolPolicyVersion: request.expectedVersion,