@opengeni/core 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.8.0",
+  "version": "0.10.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": {
@@ -34,15 +34,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/codex": "^0.2.5",
-    "@opengeni/config": "^0.6.2",
-    "@opengeni/contracts": "^0.15.0",
-    "@opengeni/db": "^0.9.3",
-    "@opengeni/documents": "^0.2.19",
-    "@opengeni/events": "^0.3.10",
+    "@opengeni/codex": "^0.2.7",
+    "@opengeni/config": "^0.6.9",
+    "@opengeni/contracts": "^0.18.0",
+    "@opengeni/db": "^0.10.7",
+    "@opengeni/documents": "^0.2.28",
+    "@opengeni/events": "^0.3.19",
     "@opengeni/observability": "^0.3.0",
-    "@opengeni/runtime": "^0.11.0",
-    "@opengeni/storage": "^0.2.15",
+    "@opengeni/runtime": "^0.13.0",
+    "@opengeni/storage": "^0.2.22",
     "hono": "^4.12.18"
   },
   "engines": {

package/src/application/session-commands.ts

@@ -385,6 +385,7 @@ function composerDraft(
     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,6 +649,7 @@ export async function getHumanComposerDraft(
     text: "",
     resources: [],
     tools: [],
+    toolsProvided: false,
     model: session.model,
     reasoningEffort: reasoningEffortForMetadata(session.metadata, "medium"),
     sourceTurnId: null,

package/src/dependencies.ts

@@ -104,6 +104,8 @@ export type AppDependencies = {
    */
   sessionAuthorization?: SessionAuthorizationPort | null;
   managedAuth?: ManagedAuth | null;
+  /** Injectable Codex HTTP transport for deterministic API/provider tests. */
+  codexFetch?: typeof fetch;
   // The API process's OWN agent-loop-free sandbox client (constructed from
   // settings via @opengeni/runtime/sandbox). Undefined when sandboxBackend=none.
   // This is the foundation of the API-direct control plane: the API resumes

package/src/domain/resources.ts

@@ -18,7 +18,7 @@ import {
 import { areGitHubRepositoriesAllowedForWorkspace, requireFile, type Database } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
 
-export function validateToolRefs(tools: ToolRef[], settings: Settings): ToolRef[] {
+export function validateToolRefs(tools: ToolRef[], settings: McpSettings): ToolRef[] {
   const mcpServerIds = new Set(settings.mcpServers.map((server) => server.id));
   const out: ToolRef[] = [];
   for (const tool of tools) {
@@ -75,6 +75,37 @@ export function withDefaultEnabledCapabilityMcpTools(
   return mergeToolRefs(tools, enabledCapabilityMcpToolRefs(settings, runtimeSettings));
 }
 
+/** Drop stored refs that are no longer present in the current runtime registry. */
+export function availableToolRefs(tools: ToolRef[], settings: McpSettings): ToolRef[] {
+  const available = new Set(settings.mcpServers.map((server) => server.id));
+  return tools.filter((tool) => available.has(tool.id));
+}
+
+/** A child or fixed-policy follow-up may narrow its allow-list, never widen it. */
+export function assertToolRefsSubset(
+  requested: ToolRef[],
+  allowed: ToolRef[],
+  message = "requested tools exceed the session tool policy",
+): void {
+  const allowedIds = new Set(allowed.map((tool) => `${tool.kind}:${tool.id}`));
+  const widened = requested.find((tool) => !allowedIds.has(`${tool.kind}:${tool.id}`));
+  if (widened) {
+    throw new HTTPException(403, { message: `${message}: ${widened.id}` });
+  }
+}
+
+/** Validate runtime availability and then enforce the durable policy fence. */
+export function validateToolRefsForSessionPolicy(input: {
+  requested: ToolRef[];
+  settings: McpSettings;
+  allowedTools: ToolRef[];
+  message: string;
+}): ToolRef[] {
+  const validated = validateToolRefs(input.requested, input.settings);
+  assertToolRefsSubset(validated, input.allowedTools, input.message);
+  return validated;
+}
+
 export function normalizeResources(resources: ResourceRef[]): ResourceRef[] {
   const mountPaths = new Map<string, string>();
   const identities = new Map<string, string>();

package/src/domain/scheduled-tasks.ts

@@ -21,7 +21,7 @@ import type { SessionWorkflowClient } from "../dependencies";
 import type { ObjectStorageDependency } from "../dependencies";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
 import { validateVariableSetAttachment } from "./environments";
-import { assertConfiguredModel, assertWorkspaceModelPolicyAllows } from "./sessions";
+import { assertWorkspaceModelPolicyAllows, canonicalConfiguredModel } from "./sessions";
 import {
   normalizeResources,
   validateFileResources,
@@ -327,15 +327,10 @@ async function validateScheduledTaskAgentConfig(input: {
   // session choke points (a `scheduled_tasks:manage` holder could otherwise set
   // a model the host does not expose). An omitted model inherits the host
   // default downstream, which is always configured.
-  assertConfiguredModel(input.settings, input.payload.agentConfig.model);
+  const model = canonicalConfiguredModel(input.settings, input.payload.agentConfig.model);
   // Same policy vetting as the session choke points; an omitted model flows
   // through session creation later, where the effective default is vetted.
-  await assertWorkspaceModelPolicyAllows(
-    input.db,
-    input.settings,
-    input.workspaceId,
-    input.payload.agentConfig.model,
-  );
+  await assertWorkspaceModelPolicyAllows(input.db, input.settings, input.workspaceId, model);
   const resources = normalizeResources(input.payload.agentConfig.resources ?? []);
   const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(
     input.db,
@@ -363,6 +358,7 @@ async function validateScheduledTaskAgentConfig(input: {
   await validateFileResources(input.db, input.workspaceId, resources);
   return {
     ...input.payload.agentConfig,
+    ...(model === undefined || model === null ? {} : { model }),
     prompt,
     resources,
     tools,

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

@@ -0,0 +1,211 @@
+import type { Settings } from "@opengeni/config";
+import {
+  SESSION_EFFECTIVE_TOOL_POLICY_ID_LIMIT,
+  SESSION_EFFECTIVE_TOOL_POLICY_ID_MAX_LENGTH,
+  mergeToolRefs,
+  type Session,
+  type SessionEffectiveToolPolicy,
+  type SessionToolPolicy,
+  type ToolRef,
+} from "@opengeni/contracts";
+import type { Database } from "@opengeni/db";
+import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
+import { enabledCapabilityMcpToolRefs } from "./resources";
+
+const MANDATORY_SESSION_MCP_SERVER_IDS = ["opengeni"] as const;
+const PROJECTABLE_REGISTRY_ID = /^[A-Za-z0-9_-]+$/;
+
+export type ResolvedSessionToolPolicy = {
+  toolRefs: ToolRef[];
+  effectivePolicy: SessionEffectiveToolPolicy;
+};
+
+export 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>;
+};
+
+function sortedIds(ids: Iterable<string>): string[] {
+  return [...new Set(ids)].sort();
+}
+
+function projectIds(ids: readonly string[]): { ids: string[]; truncated: boolean } {
+  const projectable = ids.filter(
+    (id) =>
+      id.length <= SESSION_EFFECTIVE_TOOL_POLICY_ID_MAX_LENGTH && PROJECTABLE_REGISTRY_ID.test(id),
+  );
+  return {
+    ids: projectable.slice(0, SESSION_EFFECTIVE_TOOL_POLICY_ID_LIMIT),
+    truncated:
+      projectable.length !== ids.length ||
+      projectable.length > SESSION_EFFECTIVE_TOOL_POLICY_ID_LIMIT,
+  };
+}
+
+/**
+ * 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.
+ */
+export function resolveSessionToolPolicy(input: SessionToolPolicyInput): ResolvedSessionToolPolicy {
+  const policy = input.toolPolicy ?? { mode: "legacy" as const, inheritedFromSessionId: null };
+  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.
+  const defaultIds = new Set(input.defaultMcpServerIds ?? []);
+  const mandatoryIds: string[] = MANDATORY_SESSION_MCP_SERVER_IDS.filter((id) =>
+    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;
+
+  // Optional capability refs are a historical materialization of a
+  // workspace-default selection. They may outlive an installation or its
+  // credentials; do not hand an unavailable optional ref to runtime, where it
+  // would otherwise be an unknown MCP id. Strict historical refs intentionally
+  // remain so their fail-loud compatibility contract is preserved.
+  let toolRefs = selectedRefs.filter((tool) => tool.optional !== true || availableIds.has(tool.id));
+  if (tracksWorkspaceDefaults) {
+    toolRefs = mergeToolRefs(
+      toolRefs,
+      sortedIds(defaultIds)
+        .filter((id) => availableIds.has(id))
+        .map((id) => ({ kind: "mcp" as const, id, optional: true as const })),
+    );
+  }
+  toolRefs = mergeToolRefs(
+    toolRefs,
+    mandatoryIds.map((id) => ({ kind: "mcp" as const, id })),
+  );
+
+  // `effectiveIds` is the requested policy truth, including unavailable
+  // optional refs retained in the persisted selection. `toolRefs` above is
+  // the runtime-safe materialization, so projections can distinguish dropped
+  // history from what is actually handed to the MCP router.
+  const requestedEffectiveRefs = mergeToolRefs(
+    selectedRefs,
+    tracksWorkspaceDefaults
+      ? sortedIds(defaultIds)
+          .filter((id) => availableIds.has(id))
+          .map((id) => ({ kind: "mcp" as const, id, optional: true as const }))
+      : [],
+  );
+  const effectiveIds = sortedIds(
+    mergeToolRefs(
+      requestedEffectiveRefs,
+      mandatoryIds.map((id) => ({ kind: "mcp" as const, id })),
+    ).map((tool) => tool.id),
+  );
+  const configuredIds = effectiveIds.filter((id) => availableIds.has(id));
+  const configuredIdSet = new Set(configuredIds);
+  const droppedIds = effectiveIds.filter((id) => !configuredIdSet.has(id));
+  const deferredIds = tracksWorkspaceDefaults
+    ? sortedIds(
+        toolRefs
+          .filter(
+            (tool) =>
+              tool.optional === true &&
+              configuredIdSet.has(tool.id) &&
+              !mandatoryIdSet.has(tool.id),
+          )
+          .map((tool) => tool.id),
+      )
+    : [];
+  const selectedIds = sortedIds(
+    selectedRefs
+      .filter(
+        (tool) =>
+          !mandatoryIdSet.has(tool.id) && !(tracksWorkspaceDefaults && tool.optional === true),
+      )
+      .map((tool) => tool.id),
+  );
+  const projections = {
+    selected: projectIds(selectedIds),
+    effective: projectIds(effectiveIds),
+    mandatory: projectIds(sortedIds(mandatoryIds)),
+    deferred: projectIds(deferredIds),
+    configured: projectIds(configuredIds),
+    dropped: projectIds(droppedIds),
+  };
+
+  return {
+    toolRefs,
+    effectivePolicy: {
+      mode: policy.mode,
+      inheritedFromSessionId: policy.inheritedFromSessionId,
+      selectedIds: projections.selected.ids,
+      effectiveIds: projections.effective.ids,
+      mandatoryIds: projections.mandatory.ids,
+      lazyRouter: {
+        state: tracksWorkspaceDefaults ? "required" : "disabled",
+        deferredIds: projections.deferred.ids,
+      },
+      configuredIds: projections.configured.ids,
+      droppedIds: projections.dropped.ids,
+      counts: {
+        selected: selectedIds.length,
+        effective: effectiveIds.length,
+        mandatory: mandatoryIds.length,
+        deferred: deferredIds.length,
+        configured: configuredIds.length,
+        dropped: droppedIds.length,
+      },
+      idsTruncated: Object.values(projections).some((projection) => projection.truncated),
+    },
+  };
+}
+
+/** Current full runtime registry IDs, including configured static servers. */
+export async function workspaceSessionToolPolicyServerIds(
+  db: Database,
+  workspaceId: string,
+  settings: Settings,
+): Promise<string[]> {
+  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+  return sortedIds(runtimeSettings.mcpServers.map((server) => server.id));
+}
+
+/** Current omitted-tools defaults; this preserves capability-first behavior. */
+export async function workspaceSessionToolPolicyDefaultServerIds(
+  db: Database,
+  workspaceId: string,
+  settings: Settings,
+): Promise<string[]> {
+  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+  return sortedIds(enabledCapabilityMcpToolRefs(settings, runtimeSettings).map((tool) => tool.id));
+}
+
+/** Add a bounded, secret-safe effective projection to a session response. */
+export function sessionWithEffectiveToolPolicy(
+  session: Session,
+  workspaceServerIds: Iterable<string>,
+  workspaceDefaultServerIds: Iterable<string> = [],
+): Session {
+  const availableIds = new Set(workspaceServerIds);
+  for (const server of session.mcpServers) {
+    availableIds.add(server.id);
+  }
+  return {
+    ...session,
+    effectiveToolPolicy: resolveSessionToolPolicy({
+      ...(session.toolPolicy ? { toolPolicy: session.toolPolicy } : {}),
+      sessionTools: session.tools,
+      availableMcpServerIds: availableIds,
+      defaultMcpServerIds: workspaceDefaultServerIds,
+    }).effectivePolicy,
+  };
+}