@opengeni/core 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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": {
@@ -36,15 +36,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/codex": "^0.2.0",
-    "@opengeni/config": "^0.2.1",
-    "@opengeni/contracts": "^0.4.0",
-    "@opengeni/db": "^0.2.1",
-    "@opengeni/documents": "^0.2.1",
-    "@opengeni/events": "^0.2.1",
-    "@opengeni/observability": "^0.2.0",
-    "@opengeni/runtime": "^0.2.1",
-    "@opengeni/storage": "^0.2.1",
+    "@opengeni/codex": "^0.2.1",
+    "@opengeni/config": "^0.2.3",
+    "@opengeni/contracts": "^0.5.0",
+    "@opengeni/db": "^0.3.0",
+    "@opengeni/documents": "^0.2.3",
+    "@opengeni/events": "^0.2.3",
+    "@opengeni/observability": "^0.2.1",
+    "@opengeni/runtime": "^0.2.3",
+    "@opengeni/storage": "^0.2.3",
     "hono": "^4.12.18"
   },
   "devDependencies": {

package/src/domain/resources.ts

@@ -17,26 +17,29 @@ import { HTTPException } from "hono/http-exception";
 
 export function validateToolRefs(tools: ToolRef[], settings: Settings): ToolRef[] {
   const mcpServerIds = new Set(settings.mcpServers.map((server) => server.id));
-  const selected = new Set<string>();
   const out: ToolRef[] = [];
   for (const tool of tools) {
     if (tool.kind !== "mcp") {
       throw new HTTPException(422, { message: `unsupported tool kind: ${(tool as { kind?: string }).kind}` });
     }
+    const optional = tool.optional === true;
     if (!mcpServerIds.has(tool.id)) {
+      if (optional) {
+        continue;
+      }
       throw new HTTPException(422, { message: `unknown MCP server id: ${tool.id}` });
     }
-    if (selected.has(tool.id)) {
-      continue;
-    }
-    selected.add(tool.id);
-    // Normalize to a bare, STRICT ref: a client-supplied `optional` flag is
-    // dropped so an EXPLICITLY-requested tool always fails the turn when its
-    // server is unavailable. `optional: true` is set only server-side, at the
-    // default-capability auto-attach seam (enabledCapabilityMcpToolRefs).
-    out.push({ kind: "mcp", id: tool.id });
+    // Tool refs are tri-state for pack portability across deployments:
+    //  - bare / optional:false is STRICT: the id must be configured here and
+    //    runtime connection failure fails the turn.
+    //  - optional:true + known id is preserved: runtime treats it like an
+    //    auto-attached capability MCP and skips connect/list failures.
+    //  - optional:true + unknown id is skipped above: the client explicitly
+    //    opted into graceful degradation for MCPs (for example docs servers
+    //    like context7) that only some deployments configure.
+    out.push(optional ? { kind: "mcp", id: tool.id, optional: true } : { kind: "mcp", id: tool.id });
   }
-  return out;
+  return mergeToolRefs([], out);
 }
 
 type McpSettings = Pick<Settings, "mcpServers">;

package/src/domain/sessions.ts

@@ -10,6 +10,9 @@ import {
   type ResourceRef,
   type Session,
   type SessionEvent,
+  type SessionMcpCredentialUpdateInput,
+  type SessionMcpServerInput,
+  type SessionMcpServerMetadata,
   type SessionTurn,
   type ToolRef,
 } from "@opengeni/contracts";
@@ -19,6 +22,7 @@ import {
   createSessionGoal,
   createSessionWithIdempotencyKey,
   enqueueSessionTurn,
+  encryptEnvironmentValue,
   getAnySessionInGroup,
   getEnrollment,
   listDistinctEnvironmentIdsInGroup,
@@ -29,16 +33,18 @@ import {
   requireSession,
   setTemporalWorkflowId,
   updateSessionTitle as updateSessionTitleRow,
+  type CreateSessionMcpServerInput,
   type Database,
+  type UpdateSessionMcpServerCredentialsInput,
 } from "@opengeni/db";
 import { appendAndPublishEvents, type EventBus } from "@opengeni/events";
 import { HTTPException } from "hono/http-exception";
-import { hasPermission } from "../access";
+import { hasPermission, requirePermission } from "../access";
 import { recordWorkspaceUsage, requireLimit } from "../billing/limits";
 import type { ApiRouteDeps, SessionWorkflowClient } from "../dependencies";
 import { swapActiveSandbox, type FleetContext } from "../sandbox/fleet";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
-import { validateEnvironmentAttachment } from "./environments";
+import { requireEnvironmentEncryption, validateEnvironmentAttachment } from "./environments";
 import {
   mergeResourceRefs,
   mergeToolRefs,
@@ -49,6 +55,166 @@ import {
   withDefaultEnabledCapabilityMcpTools,
 } from "./resources";
 
+const reservedSessionMcpServerIds = new Set(["opengeni", "files", "docs", "codex_apps"]);
+const maxSessionMcpCredentialHeaders = 16;
+const maxSessionMcpCredentialHeaderValueLength = 4096;
+// RFC 9110 field-name token characters.
+const sessionMcpCredentialHeaderName = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+
+type ValidatedSessionMcpServers = {
+  runtimeServers: Settings["mcpServers"];
+  dbServers: CreateSessionMcpServerInput[];
+  metadata: SessionMcpServerMetadata[];
+};
+
+function normalizedSessionMcpCredentialHeaders(headers: Record<string, string> | undefined): Record<string, string> {
+  if (!headers) {
+    return {};
+  }
+  const entries = Object.entries(headers).map(([name, value]) => [name.trim(), value] as const).filter(([name]) => name.length > 0);
+  if (entries.length > maxSessionMcpCredentialHeaders) {
+    throw new HTTPException(422, { message: `a session MCP server supports at most ${maxSessionMcpCredentialHeaders} credential headers` });
+  }
+  const seen = new Set<string>();
+  for (const [name, value] of entries) {
+    if (!sessionMcpCredentialHeaderName.test(name)) {
+      throw new HTTPException(422, { message: `invalid credential header name: ${name}` });
+    }
+    const lower = name.toLowerCase();
+    if (seen.has(lower)) {
+      throw new HTTPException(422, { message: `duplicate credential header name: ${name}` });
+    }
+    seen.add(lower);
+    if (value.length === 0 || value.length > maxSessionMcpCredentialHeaderValueLength) {
+      throw new HTTPException(422, { message: `credential header ${name} must be 1-${maxSessionMcpCredentialHeaderValueLength} characters` });
+    }
+    // RFC 9110 §5.5: field values are HTAB / printable characters.
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u0008\u000A-\u001F\u007F]/.test(value)) {
+      throw new HTTPException(422, { message: `credential header ${name} contains forbidden control characters` });
+    }
+  }
+  return Object.fromEntries(entries);
+}
+
+function mcpServerConfigFromInput(server: SessionMcpServerInput): Settings["mcpServers"][number] {
+  return {
+    id: server.id,
+    ...(server.name ? { name: server.name } : {}),
+    url: server.url,
+    ...(server.allowedTools ? { allowedTools: server.allowedTools } : {}),
+    ...(server.timeoutMs ? { timeoutMs: server.timeoutMs } : {}),
+    cacheToolsList: server.cacheToolsList ?? false,
+  };
+}
+
+function mcpServerConfigFromMetadata(server: SessionMcpServerMetadata): Settings["mcpServers"][number] {
+  return {
+    id: server.id,
+    ...(server.name ? { name: server.name } : {}),
+    url: server.url,
+    cacheToolsList: false,
+  };
+}
+
+function settingsWithSessionMcpServerConfigs(settings: Settings, servers: Settings["mcpServers"]): Settings {
+  if (servers.length === 0) {
+    return settings;
+  }
+  const sessionIds = new Set(servers.map((server) => server.id));
+  return {
+    ...settings,
+    mcpServers: [
+      ...settings.mcpServers.filter((server) => !sessionIds.has(server.id)),
+      ...servers,
+    ],
+  };
+}
+
+export function settingsWithSessionMcpServerMetadata(settings: Settings, servers: SessionMcpServerMetadata[]): Settings {
+  return settingsWithSessionMcpServerConfigs(settings, servers.map(mcpServerConfigFromMetadata));
+}
+
+function validateSessionMcpServersForCreate(
+  settings: Settings,
+  grant: AccessGrant,
+  servers: SessionMcpServerInput[],
+): ValidatedSessionMcpServers {
+  if (servers.length === 0) {
+    return { runtimeServers: [], dbServers: [], metadata: [] };
+  }
+  requirePermission(grant, "mcp_servers:attach");
+  const encryptionKey = requireEnvironmentEncryption(settings);
+  const existingIds = new Set(settings.mcpServers.map((server) => server.id));
+  const seenIds = new Set<string>();
+  const runtimeServers: Settings["mcpServers"] = [];
+  const dbServers: CreateSessionMcpServerInput[] = [];
+  const metadata: SessionMcpServerMetadata[] = [];
+  for (const server of servers) {
+    if (seenIds.has(server.id)) {
+      throw new HTTPException(422, { message: `duplicate session MCP server id: ${server.id}` });
+    }
+    seenIds.add(server.id);
+    if (reservedSessionMcpServerIds.has(server.id) || existingIds.has(server.id)) {
+      throw new HTTPException(422, { message: `MCP server id already exists: ${server.id}` });
+    }
+    const headers = normalizedSessionMcpCredentialHeaders(server.headers);
+    const headersEncrypted = Object.fromEntries(
+      Object.entries(headers).map(([name, value]) => [name, encryptEnvironmentValue(encryptionKey, value)]),
+    );
+    runtimeServers.push(mcpServerConfigFromInput(server));
+    dbServers.push({
+      id: server.id,
+      name: server.name ?? null,
+      url: server.url,
+      allowedTools: server.allowedTools ?? null,
+      timeoutMs: server.timeoutMs ?? null,
+      cacheToolsList: server.cacheToolsList ?? false,
+      headersEncrypted,
+    });
+    metadata.push({
+      id: server.id,
+      name: server.name ?? null,
+      url: server.url,
+      headerNames: Object.keys(headersEncrypted).sort(),
+      credentialVersion: 1,
+    });
+  }
+  return { runtimeServers, dbServers, metadata };
+}
+
+function validateSessionMcpCredentialUpdates(input: {
+  settings: Settings;
+  grant: AccessGrant;
+  session: Session;
+  updates: SessionMcpCredentialUpdateInput[];
+}): UpdateSessionMcpServerCredentialsInput[] {
+  if (input.updates.length === 0) {
+    return [];
+  }
+  requirePermission(input.grant, "mcp_servers:attach");
+  const encryptionKey = requireEnvironmentEncryption(input.settings);
+  const knownIds = new Set(input.session.mcpServers.map((server) => server.id));
+  const seenIds = new Set<string>();
+  const encryptedUpdates = input.updates.map((update) => {
+    if (seenIds.has(update.id)) {
+      throw new HTTPException(422, { message: `duplicate session MCP credential update id: ${update.id}` });
+    }
+    seenIds.add(update.id);
+    if (!knownIds.has(update.id)) {
+      throw new HTTPException(422, { message: `unknown session MCP server id: ${update.id}` });
+    }
+    const headers = normalizedSessionMcpCredentialHeaders(update.headers);
+    return {
+      id: update.id,
+      headersEncrypted: Object.fromEntries(
+        Object.entries(headers).map(([name, value]) => [name, encryptEnvironmentValue(encryptionKey, value)]),
+      ),
+    };
+  });
+  return encryptedUpdates;
+}
+
 export async function createAndStartSession(input: {
   db: Database;
   bus: EventBus;
@@ -68,6 +234,10 @@ export async function createAndStartSession(input: {
   goal?: GoalSpec | null;
   // Validated against the creating grant before this is called.
   firstPartyMcpPermissions?: Permission[] | null;
+  // 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[];
+  sessionMcpServers?: SessionMcpServerMetadata[];
   // The manager session spawning this worker (a worker-signed sessionId claim
   // on the creating grant); null for direct API creates and scheduled runs.
   // When set, the worker's terminal-for-now transitions wake this parent.
@@ -127,6 +297,7 @@ export async function createAndStartSession(input: {
       createIdempotencyKey: input.createIdempotencyKey,
       sandboxGroupId: input.sandboxGroupId ?? null,
       ...(input.sandboxOs ? { sandboxOs: input.sandboxOs } : {}),
+      mcpServers: input.mcpServers ?? [],
     });
     if (!created) {
       return keyed;
@@ -147,6 +318,7 @@ export async function createAndStartSession(input: {
     parentSessionId: input.parentSessionId ?? null,
     sandboxGroupId: input.sandboxGroupId ?? null,
     ...(input.sandboxOs ? { sandboxOs: input.sandboxOs } : {}),
+    mcpServers: input.mcpServers ?? [],
   });
   return await finishStartSession(input, session);
 }
@@ -171,6 +343,7 @@ async function finishStartSession(input: {
   sandboxBackend: Settings["sandboxBackend"];
   environment?: { id: string; name: string } | null;
   goal?: GoalSpec | null;
+  sessionMcpServers?: SessionMcpServerMetadata[];
   seedTargetSandbox?: { sandboxId: string; settings: Settings; workingDir?: string | null } | null;
 }, session: Session): Promise<Session> {
   // The goal row is durable session state; the workflow picks it up from the
@@ -197,6 +370,7 @@ async function finishStartSession(input: {
       payload: {
         status: "queued",
         ...(input.environment ? { environmentId: input.environment.id, environmentName: input.environment.name } : {}),
+        ...(input.sessionMcpServers?.length ? { mcpServers: input.sessionMcpServers } : {}),
       },
     },
     ...(goal ? [{
@@ -355,6 +529,7 @@ export async function postUserMessageTurn(input: {
   model?: string | null;
   reasoningEffort?: Settings["openaiReasoningEffort"] | null;
   clientEventId?: string;
+  mcpCredentialUpdates?: UpdateSessionMcpServerCredentialsInput[];
 }): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
   const { db, bus, workflowClient, settings, accountId, workspaceId, sessionId } = input;
   const requestedModel = input.model ?? null;
@@ -362,7 +537,7 @@ export async function postUserMessageTurn(input: {
   // Reject an explicit per-message model the host does not expose; an omitted
   // model inherits the session's model downstream (always a configured id).
   assertConfiguredModel(settings, requestedModel);
-  const appended = await appendSessionEventsWithLockedSessionUpdate(db, workspaceId, sessionId, (lockedSession) => {
+  const appended = await appendSessionEventsWithLockedSessionUpdate(db, workspaceId, sessionId, async (lockedSession, lockedUpdate) => {
     // Cancelled is the one terminal state: an explicit user act. A FAILED
     // session stays revivable by talking to it — conversation truth lives in
     // session_history_items, so a failed turn does not invalidate history,
@@ -373,6 +548,12 @@ export async function postUserMessageTurn(input: {
     if (lockedSession.status === "cancelled") {
       throw new HTTPException(409, { message: `session is ${lockedSession.status}; cannot accept a new user message` });
     }
+    const mcpCredentialUpdates = input.mcpCredentialUpdates?.length
+      ? await lockedUpdate.updateSessionMcpServerCredentials(input.mcpCredentialUpdates)
+      : { servers: [], missingIds: [] };
+    if (mcpCredentialUpdates.missingIds.length > 0) {
+      throw new HTTPException(422, { message: `unknown session MCP server id: ${mcpCredentialUpdates.missingIds[0]}` });
+    }
     const nextResources = mergeResourceRefs(lockedSession.resources, input.resources);
     const nextTools = mergeToolRefs(lockedSession.tools, input.tools);
     const shouldQueueSession = lockedSession.status === "idle" || lockedSession.status === "failed";
@@ -386,6 +567,7 @@ export async function postUserMessageTurn(input: {
             ...(input.tools.length ? { tools: input.tools } : {}),
             ...(requestedModel ? { model: requestedModel } : {}),
             ...(requestedReasoningEffort ? { reasoningEffort: requestedReasoningEffort } : {}),
+            ...(mcpCredentialUpdates.servers.length ? { mcpCredentialUpdates: mcpCredentialUpdates.servers } : {}),
           },
           ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
         },
@@ -446,12 +628,14 @@ export async function createSessionForRequest(
 ): Promise<Session> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   const payload = CreateSessionRequest.parse(rawPayload);
-  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+  const sessionMcpServers = validateSessionMcpServersForCreate(capabilityRuntimeSettings, grant, payload.mcpServers);
+  const runtimeSettings = settingsWithSessionMcpServerConfigs(capabilityRuntimeSettings, sessionMcpServers.runtimeServers);
   const resources = normalizeResources(payload.resources);
   const requestedTools = validateToolRefs(payload.tools, runtimeSettings);
   const defaultedTools = hasOwnProperty(rawPayload, "tools")
     ? requestedTools
-    : withDefaultEnabledCapabilityMcpTools(requestedTools, settings, runtimeSettings);
+    : withDefaultEnabledCapabilityMcpTools(requestedTools, settings, capabilityRuntimeSettings);
   // 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/environment/
@@ -672,6 +856,8 @@ export async function createSessionForRequest(
     environment: environment ? { id: environment.id, name: environment.name } : null,
     goal: payload.goal ?? null,
     firstPartyMcpPermissions,
+    mcpServers: sessionMcpServers.dbServers,
+    sessionMcpServers: sessionMcpServers.metadata,
     parentSessionId,
     createIdempotencyKey: payload.idempotencyKey ?? null,
     // Create-time machine targeting (A-2a): when a target sandbox is named, the
@@ -716,19 +902,21 @@ export async function acceptSessionUserMessage(
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
     clientEventId?: string;
+    mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
   },
 ): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
-  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
-  const requestedResources = normalizeResources(input.resources ?? []);
-  const validatedTools = validateToolRefs(input.tools ?? [], runtimeSettings);
-  const requestedTools = input.toolsProvided
-    ? validatedTools
-    : withDefaultEnabledCapabilityMcpTools(validatedTools, settings, runtimeSettings);
+  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.
   const existingSession = await requireSession(db, workspaceId, sessionId);
+  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);
   await requireLimit(deps, {
     accountId: grant.accountId,
     workspaceId,
@@ -741,6 +929,12 @@ export async function acceptSessionUserMessage(
   }
   await validateFileResources(db, workspaceId, requestedResources);
   await validateGitHubRepositorySelection(db, workspaceId, [...existingSession.resources, ...requestedResources]);
+  const mcpCredentialUpdates = validateSessionMcpCredentialUpdates({
+    settings,
+    grant,
+    session: existingSession,
+    updates: input.mcpCredentialUpdates ?? [],
+  });
   const { accepted, turn } = await postUserMessageTurn({
     db,
     bus,
@@ -754,6 +948,7 @@ export async function acceptSessionUserMessage(
     tools: requestedTools,
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
+    mcpCredentialUpdates,
     ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
   });
   await recordWorkspaceUsage(deps, {