@opengeni/core 0.10.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.10.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": {
@@ -35,14 +35,14 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@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/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.13.0",
-    "@opengeni/storage": "^0.2.22",
+    "@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/domain/scheduled-tasks.ts

@@ -9,14 +9,16 @@ 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";
@@ -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;
@@ -356,6 +360,24 @@ 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 }),

package/src/domain/sessions.ts

@@ -9,6 +9,7 @@ import {
 import {
   CreateSessionRequest,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
+  SessionSpawnDenial,
   ServiceTurnInitiator,
   ServiceTurnInitiatorContext,
   evaluateWorkspaceModelPolicy,
@@ -36,7 +37,7 @@ import {
 } from "@opengeni/contracts";
 import {
   createSession,
-  createSessionWithIdempotencyKey,
+  createSessionWithIdempotencyKeyResult,
   encryptVariableSetValue,
   getAnySessionInGroup,
   getEnrollment,
@@ -47,7 +48,7 @@ import {
   getSandbox,
   getSession,
   SessionIdConflictError,
-  getSessionByCreateIdempotencyKey,
+  getSessionSpawnDenialByIdempotencyKey,
   getSessionEvent,
   getWorkspaceControlEvent,
   getSessionLineage,
@@ -66,6 +67,7 @@ import {
   type UpdateSessionMcpServerCredentialsInput,
   QueueCommandConflictError,
   AgentCommandAuthorityError,
+  SessionSpawnDeniedDbError,
   SessionControlConflictError,
   type SessionCommandActor,
 } from "@opengeni/db";
@@ -105,6 +107,34 @@ const maxSessionMcpCredentialHeaderValueLength = 4096;
 // RFC 9110 field-name token characters.
 const sessionMcpCredentialHeaderName = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
 
+/** Transport-neutral typed denial raised only after its audit row committed. */
+export class SessionSpawnDeniedError extends Error {
+  readonly denial: SessionSpawnDenial;
+
+  constructor(denial: SessionSpawnDenial) {
+    super(sessionSpawnDeniedMessage(denial));
+    this.name = "SessionSpawnDeniedError";
+    this.denial = denial;
+  }
+}
+
+function sessionSpawnDeniedMessage(denial: SessionSpawnDenial): string {
+  if (denial.code === "nested_agent_depth_override_forbidden") {
+    return `requested nested-agent depth limit ${denial.requestedMaxNestedAgentDepthOverride ?? "unknown"} exceeds inherited limit ${denial.effectiveMaxNestedAgentDepth}; workspace:admin is required to increase it`;
+  }
+  return `nested-agent depth ${denial.attemptedDepth} exceeds effective limit ${denial.effectiveMaxNestedAgentDepth} (current parent depth ${denial.currentDepth})`;
+}
+
+export function sessionSpawnDenialEnvelope(error: SessionSpawnDeniedError) {
+  return {
+    error: {
+      code: error.denial.code,
+      message: error.message,
+      details: { denial: error.denial },
+    },
+  } as const;
+}
+
 type ValidatedSessionMcpServers = {
   runtimeServers: Settings["mcpServers"];
   dbServers: CreateSessionMcpServerInput[];
@@ -513,36 +543,27 @@ export async function createAndStartSession(input: {
   // `workingDir` (optional) is the path/cwd base the chosen machine runs under,
   // seeded alongside the pointer through the epoch-fenced CAS.
   seedTargetSandbox?: { sandboxId: string; settings: Settings; workingDir?: string | null } | null;
+  // Exact actor-private pre-session draft represented by this create. The
+  // initializer consumes it only after the first durable runnable unit commits.
+  consumeNewSessionDraft?: { subjectId: string; expectedRevision: number } | null;
+  // A child may lower its inherited nested-agent depth limit freely; increases
+  // are authorized by the caller's workspace:admin grant and checked again by
+  // the database admission transaction.
+  maxNestedAgentDepthOverride?: number | null;
+  allowNestedAgentDepthIncrease?: boolean;
+  subjectId?: string | null;
 }): Promise<CreateSessionResponse> {
   const sessionMetadata = {
     ...input.metadata,
     model: input.model,
     reasoningEffort: input.reasoningEffort,
   };
-  // Fast path with a key: return a session already created under this key
-  // (the sequential retry / double-submit case) without inserting again.
+  // Keyed creation is intentionally handled only by the database admission
+  // transaction below. Its workspace/key lock replays either the successful
+  // session or the committed denial atomically; an application-side lookup
+  // cannot serialize those two source tables against an older writer.
   if (input.createIdempotencyKey) {
-    const existing = await getSessionByCreateIdempotencyKey(
-      input.db,
-      input.workspaceId,
-      input.createIdempotencyKey,
-    );
-    if (existing) {
-      if (input.requestedSessionId && existing.id !== input.requestedSessionId) {
-        throw new SessionIdConflictError(input.requestedSessionId);
-      }
-      return await finishStartSession(
-        existing.temporalWorkflowId ? { ...input, seedTargetSandbox: null } : input,
-        existing,
-      );
-    }
-    // No prior session: insert under the key, racing concurrent creates. The
-    // partial unique index lets exactly one insert win; a loser gets back the
-    // winner's row with created=false. Both callers may enter the idempotent
-    // initializer; exactly one creates the first events/turn. Each retry
-    // advances the coalesced wake revision so an in-flight stale delivery can
-    // never acknowledge work committed by the other caller.
-    const { session: keyed, created } = await createSessionWithIdempotencyKey(input.db, {
+    const keyedResult = await createSessionWithIdempotencyKeyResult(input.db, {
       ...(input.requestedSessionId ? { requestedSessionId: input.requestedSessionId } : {}),
       accountId: input.accountId,
       workspaceId: input.workspaceId,
@@ -567,7 +588,14 @@ export async function createAndStartSession(input: {
       sandboxGroupId: input.sandboxGroupId ?? null,
       ...(input.sandboxOs ? { sandboxOs: input.sandboxOs } : {}),
       mcpServers: input.mcpServers ?? [],
+      maxNestedAgentDepthOverride: input.maxNestedAgentDepthOverride ?? null,
+      allowNestedAgentDepthIncrease: input.allowNestedAgentDepthIncrease ?? false,
+      subjectId: input.subjectId ?? null,
     });
+    if (keyedResult.denied) {
+      throw new SessionSpawnDeniedError(SessionSpawnDenial.parse(keyedResult.denial));
+    }
+    const { session: keyed, created } = keyedResult;
     if (!created) {
       return await finishStartSession(
         keyed.temporalWorkflowId ? { ...input, seedTargetSandbox: null } : input,
@@ -576,31 +604,42 @@ export async function createAndStartSession(input: {
     }
     return await finishStartSession(input, keyed);
   }
-  const session = await createSession(input.db, {
-    ...(input.requestedSessionId ? { requestedSessionId: input.requestedSessionId } : {}),
-    accountId: input.accountId,
-    workspaceId: input.workspaceId,
-    initialMessage: input.initialMessage,
-    initialTurnInstructions: input.turnInstructions ?? null,
-    resources: input.resources,
-    tools: input.tools,
-    ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
-    metadata: sessionMetadata,
-    ...(input.createdBy ? { createdBy: input.createdBy } : {}),
-    ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
-    createdByActor: input.createdByActor ?? null,
-    model: input.model,
-    sandboxBackend: input.sandboxBackend,
-    variableSetId: input.variableSet?.id ?? null,
-    rigId: input.rigId ?? null,
-    rigVersionId: input.rigVersionId ?? null,
-    firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
-    instructions: input.instructions ?? null,
-    parentSessionId: input.parentSessionId ?? null,
-    sandboxGroupId: input.sandboxGroupId ?? null,
-    ...(input.sandboxOs ? { sandboxOs: input.sandboxOs } : {}),
-    mcpServers: input.mcpServers ?? [],
-  });
+  let session: Session;
+  try {
+    session = await createSession(input.db, {
+      ...(input.requestedSessionId ? { requestedSessionId: input.requestedSessionId } : {}),
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      initialMessage: input.initialMessage,
+      initialTurnInstructions: input.turnInstructions ?? null,
+      resources: input.resources,
+      tools: input.tools,
+      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
+      metadata: sessionMetadata,
+      ...(input.createdBy ? { createdBy: input.createdBy } : {}),
+      ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
+      createdByActor: input.createdByActor ?? null,
+      model: input.model,
+      sandboxBackend: input.sandboxBackend,
+      variableSetId: input.variableSet?.id ?? null,
+      rigId: input.rigId ?? null,
+      rigVersionId: input.rigVersionId ?? null,
+      firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
+      instructions: input.instructions ?? null,
+      parentSessionId: input.parentSessionId ?? null,
+      sandboxGroupId: input.sandboxGroupId ?? null,
+      ...(input.sandboxOs ? { sandboxOs: input.sandboxOs } : {}),
+      mcpServers: input.mcpServers ?? [],
+      maxNestedAgentDepthOverride: input.maxNestedAgentDepthOverride ?? null,
+      allowNestedAgentDepthIncrease: input.allowNestedAgentDepthIncrease ?? false,
+      subjectId: input.subjectId ?? null,
+    });
+  } catch (error) {
+    if (error instanceof SessionSpawnDeniedDbError) {
+      throw new SessionSpawnDeniedError(SessionSpawnDenial.parse(error.denial));
+    }
+    throw error;
+  }
   return await finishStartSession(input, session);
 }
 
@@ -633,6 +672,7 @@ async function finishStartSession(
       settings: Settings;
       workingDir?: string | null;
     } | null;
+    consumeNewSessionDraft?: { subjectId: string; expectedRevision: number } | null;
   },
   session: Session,
 ): Promise<CreateSessionResponse> {
@@ -693,6 +733,7 @@ async function finishStartSession(
             : {}),
         }
       : null,
+    consumeNewSessionDraft: input.consumeNewSessionDraft ?? null,
   });
   await publishDurableSessionEvents(input.bus, session.workspaceId, session.id, started.events);
   if (started.workflowWakeRevision !== null) {
@@ -980,6 +1021,20 @@ export async function createSessionForRequest(
 ): Promise<Session> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   const payload = CreateSessionRequest.parse(rawPayload);
+  // A committed keyed denial is the idempotent outcome even if mutable
+  // resources, policy, authorization, or budget have changed since the first
+  // attempt. Replay it before any of those checks, just as a keyed successful
+  // session is returned rather than recreated later in createAndStartSession.
+  if (payload.idempotencyKey) {
+    const denial = await getSessionSpawnDenialByIdempotencyKey(
+      db,
+      workspaceId,
+      payload.idempotencyKey,
+    );
+    if (denial) {
+      throw new SessionSpawnDeniedError(SessionSpawnDenial.parse(denial));
+    }
+  }
   // Parent linkage and execution-context inheritance come ONLY from the
   // worker-signed sessionId claim. A caller cannot nominate a parent in the
   // payload, so inheriting an existing repository/tool/credential snapshot does
@@ -1469,6 +1524,9 @@ export async function createSessionForRequest(
       sessionMcpServers: sessionMcpServers.metadata,
       parentSessionId,
       createIdempotencyKey: payload.idempotencyKey ?? null,
+      maxNestedAgentDepthOverride: payload.maxNestedAgentDepth ?? null,
+      allowNestedAgentDepthIncrease: hasPermission(grant.permissions, "workspace:admin"),
+      subjectId: grant.subjectId,
       // Create-time machine targeting (A-2a): when a target sandbox is named, the
       // active-sandbox pointer is seeded race-free inside createAndStartSession
       // (after the row exists, before the first turn dispatches). Validation
@@ -1476,6 +1534,13 @@ export async function createSessionForRequest(
       seedTargetSandbox: payload.targetSandboxId
         ? { sandboxId: payload.targetSandboxId, settings, workingDir: payload.workingDir ?? null }
         : null,
+      consumeNewSessionDraft:
+        payload.expectedNewSessionDraftRevision !== undefined
+          ? {
+              subjectId: grant.subjectId,
+              expectedRevision: payload.expectedNewSessionDraftRevision,
+            }
+          : null,
     });
   } catch (error) {
     if (error instanceof AgentCommandAuthorityError) {

package/src/index.ts

@@ -61,4 +61,5 @@ export * from "./domain/session-tool-policy";
 export * from "./domain/scheduled-tasks";
 export * from "./domain/sessions";
 export * from "./domain/workspace-members";
+export * from "./application/new-session-drafts";
 export * from "./application/session-commands";