@opengeni/core 0.8.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.8.0",
+  "version": "0.11.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": {
@@ -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.7.0",
+    "@opengeni/contracts": "^0.19.0",
+    "@opengeni/db": "^0.12.0",
+    "@opengeni/documents": "^0.2.30",
+    "@opengeni/events": "^0.3.21",
     "@opengeni/observability": "^0.3.0",
-    "@opengeni/runtime": "^0.11.0",
-    "@opengeni/storage": "^0.2.15",
+    "@opengeni/runtime": "^0.13.3",
+    "@opengeni/storage": "^0.2.24",
     "hono": "^4.12.18"
   },
   "engines": {

package/src/application/new-session-drafts.ts

@@ -0,0 +1,126 @@
+import {
+  NewSessionDraft,
+  SaveNewSessionDraftRequest,
+  type AccessGrant,
+  type NewSessionDraft as NewSessionDraftValue,
+} from "@opengeni/contracts";
+import {
+  getNewSessionDraftInTransaction,
+  NewSessionDraftAccessError,
+  saveNewSessionDraftInTransaction,
+  withWorkspaceSubjectRls,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import type { AppDependencies } from "../dependencies";
+import { settingsWithEnabledCapabilityMcpServers } from "../domain/capabilities";
+import {
+  normalizeResources,
+  validateFileResources,
+  validateGitHubRepositorySelection,
+  validateToolRefs,
+} from "../domain/resources";
+import { assertConfiguredModel, assertWorkspaceModelPolicyAllows } from "../domain/sessions";
+
+type NewSessionDraftDependencies = Pick<AppDependencies, "settings" | "db" | "objectStorage">;
+
+function mapNewSessionDraft(
+  row: Awaited<ReturnType<typeof getNewSessionDraftInTransaction>>,
+): NewSessionDraftValue | null {
+  if (!row) return null;
+  return NewSessionDraft.parse({
+    revision: row.revision,
+    text: row.text,
+    resources: row.resources,
+    tools: row.tools,
+    model: row.model,
+    reasoningEffort: row.reasoningEffort,
+    options: row.sessionOptions,
+    updatedAt: row.updatedAt.toISOString(),
+  });
+}
+
+/** Read the authenticated actor's server-authoritative pre-session composer state. */
+export async function getActorNewSessionDraft(
+  deps: Pick<NewSessionDraftDependencies, "settings" | "db">,
+  grant: AccessGrant,
+  workspaceId: string,
+): Promise<NewSessionDraftValue> {
+  const row = await withWorkspaceSubjectRls(deps.db, workspaceId, grant.subjectId, (scoped) =>
+    getNewSessionDraftInTransaction(scoped, {
+      workspaceId,
+      subjectId: grant.subjectId,
+    }),
+  );
+  return (
+    mapNewSessionDraft(row) ?? {
+      revision: 0,
+      text: "",
+      resources: [],
+      tools: [],
+      model: deps.settings.openaiModel,
+      reasoningEffort: deps.settings.openaiReasoningEffort,
+      options: {},
+      updatedAt: null,
+    }
+  );
+}
+
+/**
+ * Validate and save one exact actor-private draft revision. Create-time-only
+ * checks (live machine target, rig/variable-set state, and permission
+ * delegation) intentionally remain in createSessionForRequest: a recoverable
+ * draft may represent incomplete options, while no invalid option can become a
+ * session without passing that single canonical create boundary.
+ */
+export async function saveActorNewSessionDraft(
+  deps: NewSessionDraftDependencies,
+  grant: AccessGrant,
+  workspaceId: string,
+  rawInput: unknown,
+): Promise<NewSessionDraftValue> {
+  const input = SaveNewSessionDraftRequest.parse(rawInput);
+  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(
+    deps.db,
+    workspaceId,
+    deps.settings,
+  );
+  const resources = normalizeResources(input.resources);
+  const tools = validateToolRefs(input.tools, runtimeSettings);
+  await validateGitHubRepositorySelection(deps.db, workspaceId, resources);
+  if (resources.some((resource) => resource.kind === "file") && !deps.objectStorage) {
+    throw new HTTPException(503, { message: "object storage is not configured" });
+  }
+  await validateFileResources(deps.db, workspaceId, resources);
+  assertConfiguredModel(deps.settings, input.model);
+  await assertWorkspaceModelPolicyAllows(deps.db, deps.settings, workspaceId, input.model);
+
+  try {
+    const saved = await withWorkspaceSubjectRls(deps.db, workspaceId, grant.subjectId, (scoped) =>
+      scoped.transaction((tx) =>
+        saveNewSessionDraftInTransaction(tx as unknown as typeof scoped, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          expectedRevision: input.expectedRevision,
+          text: input.text,
+          resources,
+          tools,
+          model: input.model,
+          reasoningEffort: input.reasoningEffort,
+          options: input.options,
+          // Only managed people are removed through removeWorkspaceMember().
+          // API keys and delegated service actors (for example the first-party
+          // worker MCP principal) legitimately have no workspace_memberships
+          // row, so they must not be rejected by the human-removal fence.
+          requireWorkspaceMembership: grant.subjectId.startsWith("user:"),
+        }),
+      ),
+    );
+    return mapNewSessionDraft(saved)!;
+  } catch (error) {
+    if (error instanceof NewSessionDraftAccessError) {
+      throw new HTTPException(403, { message: error.message });
+    }
+    throw error;
+  }
+}

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

@@ -9,19 +9,21 @@ import type {
 import {
   createScheduledTask,
   deleteScheduledTask,
+  getNestedAgentDepthDeploymentPolicy,
   getRig,
   getScheduledTask,
+  requireWorkspace,
   updateScheduledTask,
   type Database,
   type UpdateScheduledTaskInput,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
-import { requirePermission } from "../access";
+import { hasPermission, requirePermission } from "../access";
 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,
@@ -199,6 +201,7 @@ export async function validatedScheduledTaskUpdate(input: {
       settings: input.settings,
       db: input.db,
       objectStorage: input.objectStorage,
+      grant: input.grant,
       workspaceId: input.existing.workspaceId,
       payload: { agentConfig: input.payload.agentConfig },
       ...(input.toolsProvided !== undefined ? { toolsProvided: input.toolsProvided } : {}),
@@ -318,6 +321,7 @@ async function validateScheduledTaskAgentConfig(input: {
   settings: Settings;
   db: Database;
   objectStorage: ObjectStorageDependency;
+  grant: AccessGrant;
   payload: { agentConfig: ScheduledTaskAgentConfig };
   workspaceId: string;
   toolsProvided?: boolean;
@@ -327,15 +331,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,
@@ -361,8 +360,27 @@ async function validateScheduledTaskAgentConfig(input: {
     throw new HTTPException(503, { message: "object storage is not configured" });
   }
   await validateFileResources(input.db, input.workspaceId, resources);
+  const requestedMaxDepth = input.payload.agentConfig.maxNestedAgentDepth;
+  if (requestedMaxDepth !== undefined) {
+    const workspace = await requireWorkspace(input.db, input.workspaceId);
+    const workspaceMaxDepth = workspace.settings.maxNestedAgentDepth;
+    const deploymentPolicy = await getNestedAgentDepthDeploymentPolicy(input.db);
+    const inheritedMaxDepth =
+      typeof workspaceMaxDepth === "number"
+        ? workspaceMaxDepth
+        : deploymentPolicy.maxNestedAgentDepth;
+    if (
+      requestedMaxDepth > inheritedMaxDepth &&
+      !hasPermission(input.grant.permissions, "workspace:admin")
+    ) {
+      throw new HTTPException(403, {
+        message: `scheduled task maxNestedAgentDepth ${requestedMaxDepth} exceeds inherited limit ${inheritedMaxDepth}; workspace:admin is required to increase it`,
+      });
+    }
+  }
   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,
+  };
+}