@opengeni/core 0.16.3 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.16.3",
+  "version": "0.17.1",
   "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.9",
-    "@opengeni/config": "^0.9.1",
-    "@opengeni/contracts": "^0.28.1",
-    "@opengeni/db": "^0.19.0",
-    "@opengeni/documents": "^0.2.64",
-    "@opengeni/events": "^0.3.55",
-    "@opengeni/observability": "^0.4.0",
-    "@opengeni/runtime": "^0.16.0",
-    "@opengeni/storage": "^0.2.50",
+    "@opengeni/config": "^0.9.3",
+    "@opengeni/contracts": "^0.30.0",
+    "@opengeni/db": "^0.21.0",
+    "@opengeni/documents": "^0.2.66",
+    "@opengeni/events": "^0.3.57",
+    "@opengeni/observability": "^0.4.2",
+    "@opengeni/runtime": "^0.16.2",
+    "@opengeni/storage": "^0.2.52",
     "hono": "^4.12.18"
   },
   "engines": {

package/src/domain/personal-connection-delegations.ts

@@ -0,0 +1,247 @@
+import type { McpServerConfig, Settings } from "@opengeni/config";
+import type {
+  AccessGrant,
+  ConnectionMetadata,
+  McpPersonalConnectionDelegation,
+  SessionTurn,
+  ToolRef,
+} from "@opengeni/contracts";
+import {
+  getSessionTurnPersonalConnectionDelegations,
+  getWorkspaceGrant,
+  listConnectionsMetadata,
+  type Database,
+  type ResolveConnectionCredentialInput,
+  type ResolveConnectionCredentialResult,
+} from "@opengeni/db";
+
+export type PersonalConnectionDelegationSource =
+  | { kind: "subject"; subjectId: string }
+  | { kind: "turn"; sessionId: string; turnId: string }
+  | { kind: "none" };
+
+export function directPersonalConnectionSubjectId(
+  turn: Pick<SessionTurn, "source" | "initiator" | "initiatorContext">,
+): string | undefined {
+  if ((turn.source !== "user" && turn.source !== "api") || turn.initiator.kind !== "subject") {
+    return undefined;
+  }
+  return ["via", "viaTruncated", "provenanceError", "backfill"].some((key) =>
+    Object.prototype.hasOwnProperty.call(turn.initiatorContext, key),
+  )
+    ? undefined
+    : turn.initiator.subjectId;
+}
+
+export function personalConnectionDelegationSourceForGrant(
+  grant: AccessGrant,
+): PersonalConnectionDelegationSource {
+  const callerSessionId = grant.metadata?.["sessionId"];
+  const callerTurnId = grant.metadata?.["turnId"];
+  if (typeof callerSessionId === "string" && typeof callerTurnId === "string") {
+    return { kind: "turn", sessionId: callerSessionId, turnId: callerTurnId };
+  }
+  if (
+    grant.principalKind === "agent_attempt" ||
+    grant.principalKind === "service" ||
+    grant.serviceInitiator
+  ) {
+    return { kind: "none" };
+  }
+  return { kind: "subject", subjectId: grant.subjectId };
+}
+
+export function selectedPersonalConnectionServers(
+  settings: Pick<Settings, "mcpServers">,
+  tools: ToolRef[],
+): McpServerConfig[] {
+  const selected = new Set(tools.map((tool) => tool.id));
+  return settings.mcpServers.filter(
+    (server) => selected.has(server.id) && server.connectionRef?.subjectScope === "subject",
+  );
+}
+
+function canonicalPersonalConnections(connections: ConnectionMetadata[]): ConnectionMetadata[] {
+  return [...connections].sort((left, right) => {
+    const active = Number(right.status === "active") - Number(left.status === "active");
+    if (active !== 0) return active;
+    const updated = Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
+    if (updated !== 0) return updated;
+    const created = Date.parse(right.createdAt) - Date.parse(left.createdAt);
+    if (created !== 0) return created;
+    return right.id.localeCompare(left.id);
+  });
+}
+
+function sameProviderDomain(left: string, right: string): boolean {
+  return left.toLowerCase() === right.toLowerCase();
+}
+
+export function personalConnectionDelegationsFromVisibleConnections(input: {
+  servers: McpServerConfig[];
+  subjectId: string;
+  connections: ConnectionMetadata[];
+}): McpPersonalConnectionDelegation[] {
+  const delegations: McpPersonalConnectionDelegation[] = [];
+  const connections = canonicalPersonalConnections(input.connections);
+  for (const server of input.servers) {
+    const ref = server.connectionRef;
+    if (!ref || ref.subjectScope !== "subject") continue;
+    const connection = connections.find(
+      (candidate) =>
+        candidate.subjectId === input.subjectId &&
+        candidate.status === "active" &&
+        sameProviderDomain(candidate.providerDomain, ref.providerDomain) &&
+        (!ref.kind || candidate.kind === ref.kind) &&
+        (!ref.connectionId || candidate.id === ref.connectionId),
+    );
+    if (!connection) continue;
+    delegations.push({
+      serverId: server.id,
+      connectionId: connection.id,
+      ownerSubjectId: input.subjectId,
+      providerDomain: connection.providerDomain,
+      kind: connection.kind,
+    });
+  }
+  return delegations;
+}
+
+export function personalConnectionDelegationsFromParent(input: {
+  servers: McpServerConfig[];
+  parentDelegations: McpPersonalConnectionDelegation[];
+}): McpPersonalConnectionDelegation[] {
+  return input.servers.flatMap((server) => {
+    const ref = server.connectionRef;
+    if (!ref || ref.subjectScope !== "subject") return [];
+    const delegation = input.parentDelegations.find(
+      (candidate) =>
+        candidate.serverId === server.id &&
+        sameProviderDomain(candidate.providerDomain, ref.providerDomain) &&
+        (!ref.kind || !candidate.kind || candidate.kind === ref.kind),
+    );
+    return delegation ? [{ ...delegation }] : [];
+  });
+}
+
+export function personalConnectionDelegationsEqual(
+  left: McpPersonalConnectionDelegation[],
+  right: McpPersonalConnectionDelegation[],
+): boolean {
+  if (left.length !== right.length) return false;
+  const byServer = new Map(right.map((delegation) => [delegation.serverId, delegation]));
+  return left.every((delegation) => {
+    const other = byServer.get(delegation.serverId);
+    return (
+      other?.connectionId === delegation.connectionId &&
+      other.ownerSubjectId === delegation.ownerSubjectId &&
+      sameProviderDomain(other.providerDomain, delegation.providerDomain) &&
+      other.kind === delegation.kind
+    );
+  });
+}
+
+export function personalConnectionDelegationForServer(
+  delegations: McpPersonalConnectionDelegation[],
+  server: Pick<McpServerConfig, "id" | "connectionRef">,
+): McpPersonalConnectionDelegation | null {
+  const ref = server.connectionRef;
+  if (!ref || ref.subjectScope !== "subject") return null;
+  return (
+    delegations.find(
+      (delegation) =>
+        delegation.serverId === server.id &&
+        sameProviderDomain(delegation.providerDomain, ref.providerDomain) &&
+        (!ref.kind || !delegation.kind || delegation.kind === ref.kind),
+    ) ?? null
+  );
+}
+
+type ConnectionCredentialResolver = (
+  request: ResolveConnectionCredentialInput,
+) => Promise<ResolveConnectionCredentialResult>;
+
+function personalAuthorityUnavailable(
+  request: ResolveConnectionCredentialInput,
+): ResolveConnectionCredentialResult {
+  const ref = request.connectionRef;
+  return {
+    status: "auth_needed",
+    reason: "personal_authority_unavailable",
+    providerDomain: ref.providerDomain,
+    ...(ref.provider ? { provider: ref.provider } : {}),
+    ...(ref.scopes ? { scopes: ref.scopes } : {}),
+    ...(ref.resource ? { resource: ref.resource } : {}),
+    ...(ref.selectedResources ? { selectedResources: ref.selectedResources } : {}),
+  };
+}
+
+/**
+ * Resolves subject-owned MCP credentials only through the exact authority
+ * frozen on the causal turn. A direct human subject, worker Toolspace caller,
+ * retry, or recovery can identify the caller, but none may widen or replace
+ * the persisted connection UUID.
+ */
+export function withFrozenPersonalConnectionDelegations(input: {
+  resolveCredential: ConnectionCredentialResolver;
+  settings: Pick<Settings, "mcpServers">;
+  personalConnectionDelegations: McpPersonalConnectionDelegation[];
+  ownerHasWorkspaceMembership: (subjectId: string) => Promise<boolean>;
+}): ConnectionCredentialResolver {
+  return async (request) => {
+    let effectiveRequest = request;
+    if (request.connectionRef.subjectScope === "subject") {
+      const config = input.settings.mcpServers.find((server) => server.id === request.serverId);
+      const delegation = config
+        ? personalConnectionDelegationForServer(input.personalConnectionDelegations, config)
+        : null;
+      if (!delegation || !(await input.ownerHasWorkspaceMembership(delegation.ownerSubjectId))) {
+        return personalAuthorityUnavailable(request);
+      }
+      effectiveRequest = {
+        ...request,
+        subjectId: delegation.ownerSubjectId,
+        connectionRef: {
+          ...request.connectionRef,
+          providerDomain: delegation.providerDomain,
+          connectionId: delegation.connectionId,
+          ...(delegation.kind ? { kind: delegation.kind } : {}),
+        },
+      };
+    }
+    const result = await input.resolveCredential(effectiveRequest);
+    if (result.status === "ok" || request.connectionRef.subjectScope !== "subject") {
+      return result;
+    }
+    return personalAuthorityUnavailable(request);
+  };
+}
+
+export async function freezePersonalConnectionDelegations(input: {
+  db: Database;
+  workspaceId: string;
+  settings: Pick<Settings, "mcpServers">;
+  tools: ToolRef[];
+  source: PersonalConnectionDelegationSource;
+}): Promise<McpPersonalConnectionDelegation[]> {
+  const servers = selectedPersonalConnectionServers(input.settings, input.tools);
+  if (servers.length === 0 || input.source.kind === "none") return [];
+  if (input.source.kind === "turn") {
+    return personalConnectionDelegationsFromParent({
+      servers,
+      parentDelegations: await getSessionTurnPersonalConnectionDelegations(
+        input.db,
+        input.workspaceId,
+        input.source.sessionId,
+        input.source.turnId,
+      ),
+    });
+  }
+  const membership = await getWorkspaceGrant(input.db, input.source.subjectId, input.workspaceId);
+  if (!membership) return [];
+  return personalConnectionDelegationsFromVisibleConnections({
+    servers,
+    subjectId: input.source.subjectId,
+    connections: await listConnectionsMetadata(input.db, input.workspaceId, input.source.subjectId),
+  });
+}

package/src/domain/scheduled-tasks.ts

@@ -1,6 +1,7 @@
 import type { Settings } from "@opengeni/config";
 import type {
   AccessGrant,
+  McpPersonalConnectionDelegation,
   ScheduledTask,
   ScheduledTaskAgentConfig,
   CreateScheduledTaskRequest as CreateScheduledTaskPayload,
@@ -13,6 +14,7 @@ import {
   getNestedAgentDepthDeploymentPolicy,
   getRig,
   getScheduledTask,
+  getScheduledTaskPersonalConnectionDelegations,
   requireWorkspace,
   updateScheduledTask,
   type Database,
@@ -24,7 +26,16 @@ import type { SessionWorkflowClient } from "../dependencies";
 import type { ObjectStorageDependency } from "../dependencies";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
 import { validateVariableSetAttachment } from "./environments";
-import { assertWorkspaceModelPolicyAllows, canonicalConfiguredModel } from "./sessions";
+import {
+  freezePersonalConnectionDelegations,
+  personalConnectionDelegationSourceForGrant,
+  personalConnectionDelegationsEqual,
+} from "./personal-connection-delegations";
+import {
+  assertWorkspaceModelPolicyAllows,
+  canonicalConfiguredModel,
+  creationInitiatorForGrant,
+} from "./sessions";
 import {
   hasReservedOpenGeniSlackBotSessionMetadata,
   validateOpenGeniSlackBotConnectionSelection,
@@ -93,6 +104,19 @@ export async function createValidatedScheduledTask(input: {
   if (input.payload.rigId) {
     await requireScheduledTaskRig(input.db, input.grant.workspaceId, input.payload.rigId);
   }
+  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(
+    input.db,
+    input.grant.workspaceId,
+    input.settings,
+  );
+  const personalConnectionDelegations = await freezePersonalConnectionDelegations({
+    db: input.db,
+    workspaceId: input.grant.workspaceId,
+    settings: runtimeSettings,
+    tools: agentConfig.tools,
+    source: personalConnectionDelegationSourceForGrant(input.grant),
+  });
+  const creationInitiator = creationInitiatorForGrant(input.grant);
   return await createScheduledTask(input.db, {
     id,
     accountId: input.grant.accountId,
@@ -104,6 +128,10 @@ export async function createValidatedScheduledTask(input: {
     runMode: input.payload.runMode,
     overlapPolicy: input.payload.overlapPolicy,
     agentConfig,
+    ...(creationInitiator.initiator ? { createdBy: creationInitiator.initiator } : {}),
+    ...(creationInitiator.context ? { createdByContext: creationInitiator.context } : {}),
+    createdByActor: creationInitiator.actor ?? null,
+    personalConnectionDelegations,
     variableSetId: input.payload.variableSetId ?? null,
     rigId: input.payload.rigId ?? null,
     metadata: input.payload.metadata,
@@ -223,6 +251,32 @@ export async function validatedScheduledTaskUpdate(input: {
       });
     }
     update.agentConfig = nextAgentConfig;
+    const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(
+      input.db,
+      input.existing.workspaceId,
+      input.settings,
+    );
+    const personalConnectionDelegations = await freezePersonalConnectionDelegations({
+      db: input.db,
+      workspaceId: input.existing.workspaceId,
+      settings: runtimeSettings,
+      tools: nextAgentConfig.tools,
+      source: personalConnectionDelegationSourceForGrant(input.grant),
+    });
+    if (input.existing.reusableSessionId && input.existing.runMode === "reusable_session") {
+      const existingDelegations = await getScheduledTaskPersonalConnectionDelegations(
+        input.db,
+        input.existing.workspaceId,
+        input.existing.id,
+      );
+      if (!personalConnectionDelegationsEqual(existingDelegations, personalConnectionDelegations)) {
+        throw new HTTPException(409, {
+          message:
+            "cannot change personal MCP connections of a task with a live reusable session; recreate the task",
+        });
+      }
+    }
+    update.personalConnectionDelegations = personalConnectionDelegations;
   }
   return update;
 }
@@ -239,10 +293,30 @@ export async function requireScheduledTaskForApi(
   return task;
 }
 
-export async function restoreScheduledTask(
+export type ScheduledTaskRestoreState = {
+  task: ScheduledTask;
+  personalConnectionDelegations: McpPersonalConnectionDelegation[];
+};
+
+export async function captureScheduledTaskRestoreState(
   db: Database,
   task: ScheduledTask,
+): Promise<ScheduledTaskRestoreState> {
+  return {
+    task,
+    personalConnectionDelegations: await getScheduledTaskPersonalConnectionDelegations(
+      db,
+      task.workspaceId,
+      task.id,
+    ),
+  };
+}
+
+export async function restoreScheduledTask(
+  db: Database,
+  previous: ScheduledTaskRestoreState,
 ): Promise<ScheduledTask> {
+  const { task } = previous;
   return await updateScheduledTask(db, task.workspaceId, task.id, {
     name: task.name,
     status: task.status,
@@ -250,8 +324,10 @@ export async function restoreScheduledTask(
     runMode: task.runMode,
     overlapPolicy: task.overlapPolicy,
     agentConfig: task.agentConfig,
+    personalConnectionDelegations: previous.personalConnectionDelegations,
     reusableSessionId: task.reusableSessionId,
     variableSetId: task.variableSetId,
+    rigId: task.rigId,
     metadata: task.metadata,
   });
 }
@@ -274,7 +350,7 @@ export async function syncCreatedScheduledTask(input: {
 export async function syncUpdatedScheduledTask(input: {
   db: Database;
   workflowClient: SessionWorkflowClient;
-  previous: ScheduledTask;
+  previous: ScheduledTaskRestoreState;
   task: ScheduledTask;
 }): Promise<void> {
   try {

package/src/domain/sessions.ts

@@ -23,6 +23,7 @@ import {
   type CreateSessionResponse,
   type GoalSpec,
   type FirstPartyMcpToolName,
+  type McpPersonalConnectionDelegation,
   type Permission,
   type ReasoningEffort,
   type ResourceRef,
@@ -98,6 +99,10 @@ import { requireSessionAuthorization } from "../session-authorization";
 import { swapActiveSandbox, type FleetContext } from "../sandbox/fleet";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
 import { requireVariableSetEncryption, validateVariableSetAttachment } from "./environments";
+import {
+  freezePersonalConnectionDelegations,
+  personalConnectionDelegationSourceForGrant,
+} from "./personal-connection-delegations";
 import { hasReservedOpenGeniSlackBotSessionMetadata } from "./slack-bot";
 import {
   assertToolRefsSubset,
@@ -168,7 +173,7 @@ type ValidatedSessionMcpServers = {
   metadata: SessionMcpServerMetadata[];
 };
 
-type FrozenCreationInitiator = {
+export type FrozenCreationInitiator = {
   initiator?: TurnInitiator;
   context?: TurnInitiatorContext;
   actor?: Extract<SessionCommandActor, { type: "agent_attempt" }>;
@@ -216,7 +221,7 @@ function serviceInitiatorForGrant(grant: AccessGrant): {
   };
 }
 
-function creationInitiatorForGrant(grant: AccessGrant): FrozenCreationInitiator {
+export function creationInitiatorForGrant(grant: AccessGrant): FrozenCreationInitiator {
   const serviceInitiator = serviceInitiatorForGrant(grant);
   const callerSessionId = grant.metadata?.["sessionId"];
   const callerTurnId = grant.metadata?.["turnId"];
@@ -549,6 +554,7 @@ export async function createAndStartSession(input: {
   // MCP servers. Metadata is the only shape emitted in events/responses.
   mcpServers?: CreateSessionMcpServerInput[];
   sessionMcpServers?: SessionMcpServerMetadata[];
+  personalConnectionDelegations?: McpPersonalConnectionDelegation[];
   // 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.
@@ -624,6 +630,7 @@ export async function createAndStartSession(input: {
       sandboxGroupId: input.sandboxGroupId ?? null,
       ...(input.sandboxOs ? { sandboxOs: input.sandboxOs } : {}),
       mcpServers: input.mcpServers ?? [],
+      personalConnectionDelegations: input.personalConnectionDelegations ?? [],
       maxNestedAgentDepthOverride: input.maxNestedAgentDepthOverride ?? null,
       allowNestedAgentDepthIncrease: input.allowNestedAgentDepthIncrease ?? false,
       subjectId: input.subjectId ?? null,
@@ -668,6 +675,7 @@ export async function createAndStartSession(input: {
       sandboxGroupId: input.sandboxGroupId ?? null,
       ...(input.sandboxOs ? { sandboxOs: input.sandboxOs } : {}),
       mcpServers: input.mcpServers ?? [],
+      personalConnectionDelegations: input.personalConnectionDelegations ?? [],
       maxNestedAgentDepthOverride: input.maxNestedAgentDepthOverride ?? null,
       allowNestedAgentDepthIncrease: input.allowNestedAgentDepthIncrease ?? false,
       subjectId: input.subjectId ?? null,
@@ -966,6 +974,7 @@ export async function postUserMessageTurn(input: {
   latencyMode?: "standard" | "priority" | "fast" | null;
   clientEventId?: string;
   mcpCredentialUpdates?: UpdateSessionMcpServerCredentialsInput[];
+  personalConnectionDelegations?: McpPersonalConnectionDelegation[];
   delivery?: "send" | "steer";
   origin?: "human" | "operator";
   actor?: string;
@@ -1021,6 +1030,7 @@ export async function postUserMessageTurn(input: {
           reasoningEffortFallback: input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
           turnExecutionPolicy: input.turnExecutionPolicy,
           source: input.origin === "operator" ? "api" : "user",
+          personalConnectionDelegations: input.personalConnectionDelegations ?? [],
           mcpCredentialUpdates: input.mcpCredentialUpdates ?? [],
         }),
       ),
@@ -1218,6 +1228,13 @@ export async function createSessionForRequest(
   // tool's permission/target authorization predicate, so attachment alone
   // exposes nothing.
   const tools = withFirstPartyTools(selectedTools, runtimeSettings);
+  const personalConnectionDelegations = await freezePersonalConnectionDelegations({
+    db,
+    workspaceId,
+    settings: runtimeSettings,
+    tools,
+    source: personalConnectionDelegationSourceForGrant(grant),
+  });
   await validateGitHubRepositorySelection(db, workspaceId, resources);
   if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
     throw new HTTPException(503, { message: "object storage is not configured" });
@@ -1634,6 +1651,7 @@ export async function createSessionForRequest(
       firstPartyMcpTools,
       mcpServers: sessionMcpServers.dbServers,
       sessionMcpServers: sessionMcpServers.metadata,
+      personalConnectionDelegations,
       parentSessionId,
       createIdempotencyKey: payload.idempotencyKey ?? null,
       maxNestedAgentDepthOverride: payload.maxNestedAgentDepth ?? null,
@@ -1772,6 +1790,14 @@ export async function acceptSessionUserMessage(
     session: existingSession,
     updates: input.mcpCredentialUpdates ?? [],
   });
+  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+  const personalConnectionDelegations = await freezePersonalConnectionDelegations({
+    db,
+    workspaceId,
+    settings: runtimeSettings,
+    tools: existingSession.tools,
+    source: personalConnectionDelegationSourceForGrant(grant),
+  });
   const delegatedServiceInitiator = serviceInitiatorForGrant(grant);
   const { accepted, turn } = await postUserMessageTurn({
     db,
@@ -1790,6 +1816,7 @@ export async function acceptSessionUserMessage(
     reasoningEffortFallback: sessionReasoningEffort,
     turnExecutionPolicy,
     mcpCredentialUpdates,
+    personalConnectionDelegations,
     delivery: input.delivery ?? "send",
     origin: delegatedServiceInitiator ? "operator" : (input.origin ?? "human"),
     actor: grant.subjectId,

package/src/index.ts

@@ -57,6 +57,7 @@ export * from "./domain/capabilities";
 export * from "./domain/environments";
 export * from "./rigs";
 export * from "./domain/packs";
+export * from "./domain/personal-connection-delegations";
 export * from "./domain/resources";
 export * from "./domain/session-tool-policy";
 export * from "./domain/scheduled-tasks";