@opengeni/core 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "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": {
@@ -8,6 +8,10 @@
     "url": "git+https://github.com/Cloudgeni-ai/opengeni.git",
     "directory": "packages/core"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -19,33 +23,29 @@
       "import": "./dist/index.js"
     }
   },
-  "files": [
-    "dist",
-    "src"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "build": "tsup",
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/codex": "^0.2.1",
-    "@opengeni/config": "^0.4.0",
-    "@opengeni/contracts": "^0.9.0",
-    "@opengeni/db": "^0.6.1",
-    "@opengeni/documents": "^0.2.8",
-    "@opengeni/events": "^0.2.8",
-    "@opengeni/observability": "^0.2.1",
-    "@opengeni/runtime": "^0.6.0",
-    "@opengeni/storage": "^0.2.8",
+    "@opengeni/codex": "^0.2.2",
+    "@opengeni/config": "^0.5.0",
+    "@opengeni/contracts": "^0.10.0",
+    "@opengeni/db": "^0.7.0",
+    "@opengeni/documents": "^0.2.9",
+    "@opengeni/events": "^0.3.0",
+    "@opengeni/observability": "^0.3.0",
+    "@opengeni/runtime": "^0.7.0",
+    "@opengeni/storage": "^0.2.9",
     "hono": "^4.12.18"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }

package/src/access/index.ts

@@ -1,5 +1,10 @@
 import type { Settings } from "@opengeni/config";
-import { verifyDelegatedAccessToken, type AccessContext, type AccessGrant, type Permission } from "@opengeni/contracts";
+import {
+  verifyDelegatedAccessToken,
+  type AccessContext,
+  type AccessGrant,
+  type Permission,
+} from "@opengeni/contracts";
 import {
   bootstrapWorkspace,
   ensureManagedAccessForUser,
@@ -28,10 +33,16 @@ export async function requireAccessContext(c: Context, deps: AccessDeps): Promis
   return context;
 }
 
-export async function requireAccessGrant(c: Context, deps: AccessDeps, workspaceId: string, permission?: Permission): Promise<AccessGrant> {
+export async function requireAccessGrant(
+  c: Context,
+  deps: AccessDeps,
+  workspaceId: string,
+  permission?: Permission,
+): Promise<AccessGrant> {
   const context = await requireAccessContext(c, deps);
-  const grant = context.workspaceGrants.find((candidate) => candidate.workspaceId === workspaceId)
-    ?? await getWorkspaceGrant(deps.db, context.subjectId, workspaceId);
+  const grant =
+    context.workspaceGrants.find((candidate) => candidate.workspaceId === workspaceId) ??
+    (await getWorkspaceGrant(deps.db, context.subjectId, workspaceId));
   if (!grant) {
     const workspace = await requireWorkspace(deps.db, workspaceId).catch(() => null);
     if (!workspace) {
@@ -47,12 +58,30 @@ export async function requireAccessGrant(c: Context, deps: AccessDeps, workspace
 
 export function requirePermission(grant: AccessGrant, permission: Permission): void {
   if (!hasPermission(grant.permissions, permission)) {
+    if (permission === "variable-sets:use") {
+      throw new HTTPException(403, {
+        message: "missing permission: variable-sets:use (deprecated alias: environments:use)",
+      });
+    }
+    if (permission === "variable-sets:manage") {
+      throw new HTTPException(403, {
+        message: "missing permission: variable-sets:manage (deprecated alias: environments:manage)",
+      });
+    }
     throw new HTTPException(403, { message: `missing permission: ${permission}` });
   }
 }
 
 export function hasPermission(permissions: Permission[], permission: Permission): boolean {
-  return permissions.includes(permission) || permissions.includes("workspace:admin");
+  const aliases: Partial<Record<Permission, Permission[]>> = {
+    "variable-sets:use": ["environments:use" as Permission],
+    "variable-sets:manage": ["environments:manage" as Permission],
+  };
+  return (
+    permissions.includes(permission) ||
+    (aliases[permission]?.some((alias) => permissions.includes(alias)) ?? false) ||
+    permissions.includes("workspace:admin")
+  );
 }
 
 async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<AccessContext | null> {
@@ -69,16 +98,20 @@ async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<Acces
     });
   }
 
-	  if (deps.settings.productAccessMode === "configured") {
-	    const delegated = await delegatedAccessContext(c, deps, "configured");
-	    if (delegated) {
-	      return delegated;
-	    }
-	    if (deps.settings.delegationSecret) {
-	      return null;
-	    }
-	    return await bootstrapWorkspace(deps.db, {
-	      accountExternalSource: "opengeni:configured",
+  if (deps.settings.productAccessMode === "configured") {
+    const delegated = await delegatedAccessContext(c, deps, "configured");
+    if (delegated) {
+      return delegated;
+    }
+    const apiKey = await apiKeyAccessContext(c, deps, "configured");
+    if (apiKey) {
+      return apiKey;
+    }
+    if (deps.settings.delegationSecret) {
+      return null;
+    }
+    return await bootstrapWorkspace(deps.db, {
+      accountExternalSource: "opengeni:configured",
       accountExternalId: "default",
       accountName: "Configured",
       workspaceExternalSource: "opengeni:configured",
@@ -95,31 +128,9 @@ async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<Acces
     if (delegated) {
       return delegated;
     }
-    const apiKey = await findActiveApiKeyByHash(deps.db, await sha256Hex(bearer));
+    const apiKey = await apiKeyAccessContext(c, deps, "managed");
     if (apiKey) {
-      const accountPermissions = apiKey.workspaceId
-        ? apiKey.permissions.filter((permission) => permission === "billing:read" || permission === "billing:manage")
-        : apiKey.permissions;
-      return {
-        mode: "managed",
-        subjectId: `api_key:${apiKey.id}`,
-        subjectLabel: apiKey.name,
-        accountGrants: [{
-          accountId: apiKey.accountId,
-          subjectId: `api_key:${apiKey.id}`,
-          subjectLabel: apiKey.name,
-          permissions: accountPermissions,
-        }],
-        workspaceGrants: apiKey.workspaceId ? [{
-          workspaceId: apiKey.workspaceId,
-          accountId: apiKey.accountId,
-          subjectId: `api_key:${apiKey.id}`,
-          subjectLabel: apiKey.name,
-          permissions: apiKey.permissions,
-        }] : [],
-        defaultAccountId: apiKey.accountId,
-        defaultWorkspaceId: apiKey.workspaceId,
-      } satisfies AccessContext;
+      return apiKey;
     }
   }
 
@@ -137,7 +148,59 @@ async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<Acces
   return null;
 }
 
-async function delegatedAccessContext(c: Context, deps: AccessDeps, mode: "configured" | "managed", token = bearerToken(c)): Promise<AccessContext | null> {
+async function apiKeyAccessContext(
+  c: Context,
+  deps: AccessDeps,
+  mode: "configured" | "managed",
+): Promise<AccessContext | null> {
+  const bearer = bearerToken(c);
+  if (!bearer) {
+    return null;
+  }
+  const apiKey = await findActiveApiKeyByHash(deps.db, await sha256Hex(bearer));
+  if (!apiKey) {
+    return null;
+  }
+  const subjectId = `api_key:${apiKey.id}`;
+  const accountPermissions = apiKey.workspaceId
+    ? apiKey.permissions.filter(
+        (permission) => permission === "billing:read" || permission === "billing:manage",
+      )
+    : apiKey.permissions;
+  return {
+    mode,
+    subjectId,
+    subjectLabel: apiKey.name,
+    accountGrants: [
+      {
+        accountId: apiKey.accountId,
+        subjectId,
+        subjectLabel: apiKey.name,
+        permissions: accountPermissions,
+      },
+    ],
+    workspaceGrants: apiKey.workspaceId
+      ? [
+          {
+            workspaceId: apiKey.workspaceId,
+            accountId: apiKey.accountId,
+            subjectId,
+            subjectLabel: apiKey.name,
+            permissions: apiKey.permissions,
+          },
+        ]
+      : [],
+    defaultAccountId: apiKey.accountId,
+    defaultWorkspaceId: apiKey.workspaceId,
+  } satisfies AccessContext;
+}
+
+async function delegatedAccessContext(
+  c: Context,
+  deps: AccessDeps,
+  mode: "configured" | "managed",
+  token = bearerToken(c),
+): Promise<AccessContext | null> {
   if (!token || !deps.settings.delegationSecret) {
     return null;
   }
@@ -149,22 +212,32 @@ async function delegatedAccessContext(c: Context, deps: AccessDeps, mode: "confi
     mode,
     subjectId: payload.subjectId,
     ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
-    accountGrants: [{
-      accountId: payload.accountId,
-      subjectId: payload.subjectId,
-      ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
-      permissions: payload.permissions,
-    }],
-    workspaceGrants: [{
-      workspaceId: payload.workspaceId,
-      accountId: payload.accountId,
-      subjectId: payload.subjectId,
-      ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
-      permissions: payload.permissions,
-      // sessionId is worker-asserted (HMAC-signed token claim), not agent
-      // controlled; it scopes session-bound MCP tools such as goal management.
-      metadata: { delegated: true, ...(payload.sessionId ? { sessionId: payload.sessionId } : {}) },
-    }],
+    accountGrants: [
+      {
+        accountId: payload.accountId,
+        subjectId: payload.subjectId,
+        ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
+        permissions: payload.permissions,
+      },
+    ],
+    workspaceGrants: [
+      {
+        workspaceId: payload.workspaceId,
+        accountId: payload.accountId,
+        subjectId: payload.subjectId,
+        ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
+        permissions: payload.permissions,
+        // sessionId is worker-asserted (HMAC-signed token claim), not agent
+        // controlled; it scopes session-bound MCP tools such as goal management.
+        metadata: {
+          delegated: true,
+          ...(payload.sessionId ? { sessionId: payload.sessionId } : {}),
+          // Caller identity: the turn that minted this token. Tools classify the
+          // CALLER from this instead of re-reading the live active pointer.
+          ...(payload.turnId ? { turnId: payload.turnId } : {}),
+        },
+      },
+    ],
     defaultAccountId: payload.accountId,
     defaultWorkspaceId: payload.workspaceId,
   };
@@ -182,5 +255,7 @@ function bearerToken(c: Context): string | null {
 
 async function sha256Hex(value: string): Promise<string> {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
-  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return Array.from(new Uint8Array(digest))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
 }

package/src/billing/limits.ts

@@ -12,6 +12,8 @@ import {
 import { HTTPException } from "hono/http-exception";
 import type { ApiRouteDeps } from "../dependencies";
 
+export type LimitDependencies = Pick<ApiRouteDeps, "db" | "settings">;
+
 export type LimitCheckInput = {
   accountId: string;
   workspaceId?: string;
@@ -26,20 +28,30 @@ export type LimitCheckInput = {
   model?: string | null;
 };
 
-export async function requireLimit(deps: ApiRouteDeps, input: LimitCheckInput): Promise<void> {
+export async function requireLimit(deps: LimitDependencies, input: LimitCheckInput): Promise<void> {
   const decision = await checkLimit(deps, input);
   if (decision.allowed) {
     return;
   }
-  throw new HTTPException(decision.code === "insufficient_credits" ? 402 : 429, { message: decision.message });
+  throw new HTTPException(decision.code === "insufficient_credits" ? 402 : 429, {
+    message: decision.message,
+  });
 }
 
-export async function checkLimit(deps: ApiRouteDeps, input: LimitCheckInput): Promise<LimitDecision> {
+export async function checkLimit(
+  deps: LimitDependencies,
+  input: LimitCheckInput,
+): Promise<LimitDecision> {
   // Resolve the canonical codex-billed predicate ONCE. Returns false for any
   // action that carries no model (infra caps) or any codex/<slug> model without
   // an active credential — so the bypass never triggers on the prefix alone.
   const codexBilled = input.workspaceId
-    ? await isCodexBilledTurn({ db: deps.db, settings: deps.settings, workspaceId: input.workspaceId, model: input.model })
+    ? await isCodexBilledTurn({
+        db: deps.db,
+        settings: deps.settings,
+        workspaceId: input.workspaceId,
+        model: input.model,
+      })
     : false;
   const creditDecision = await checkCreditBalance(deps, input, codexBilled);
   if (!creditDecision.allowed) {
@@ -51,7 +63,11 @@ export async function checkLimit(deps: ApiRouteDeps, input: LimitCheckInput): Pr
   return await checkStaticCaps(deps, input, codexBilled);
 }
 
-async function checkCreditBalance(deps: ApiRouteDeps, input: LimitCheckInput, codexBilled: boolean): Promise<LimitDecision> {
+async function checkCreditBalance(
+  deps: LimitDependencies,
+  input: LimitCheckInput,
+  codexBilled: boolean,
+): Promise<LimitDecision> {
   if (codexBilled) {
     return { allowed: true }; // paid by the user's ChatGPT/Codex plan — zero OpenGeni credits
   }
@@ -65,7 +81,11 @@ async function checkCreditBalance(deps: ApiRouteDeps, input: LimitCheckInput, co
   return { allowed: false, code: "insufficient_credits", message: "insufficient OpenGeni credits" };
 }
 
-async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codexBilled: boolean): Promise<LimitDecision> {
+async function checkStaticCaps(
+  deps: LimitDependencies,
+  input: LimitCheckInput,
+  codexBilled: boolean,
+): Promise<LimitDecision> {
   const limits = configuredStaticUsageLimits(deps.settings);
   if (limits.maxMonthlyCostMicrosPerAccount && isCostlyAction(input.action) && !codexBilled) {
     const used = await sumUsageQuantity(deps.db, {
@@ -74,7 +94,10 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       since: startOfUtcMonth(),
     });
     if (used >= limits.maxMonthlyCostMicrosPerAccount) {
-      return blocked("max_monthly_cost_micros_per_account", `monthly model cost limit reached (${limits.maxMonthlyCostMicrosPerAccount} micros)`);
+      return blocked(
+        "max_monthly_cost_micros_per_account",
+        `monthly model cost limit reached (${limits.maxMonthlyCostMicrosPerAccount} micros)`,
+      );
     }
   }
   switch (input.action) {
@@ -85,7 +108,10 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       const count = await countWorkspacesForAccount(deps.db, input.accountId);
       return count < limits.maxWorkspacesPerAccount
         ? { allowed: true }
-        : blocked("max_workspaces_per_account", `workspace limit reached (${limits.maxWorkspacesPerAccount})`);
+        : blocked(
+            "max_workspaces_per_account",
+            `workspace limit reached (${limits.maxWorkspacesPerAccount})`,
+          );
     }
     case "api_key:create": {
       if (!limits.maxApiKeysPerWorkspace || !input.workspaceId) {
@@ -94,7 +120,10 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       const count = await countActiveApiKeysForWorkspace(deps.db, input.workspaceId);
       return count < limits.maxApiKeysPerWorkspace
         ? { allowed: true }
-        : blocked("max_api_keys_per_workspace", `API key limit reached (${limits.maxApiKeysPerWorkspace})`);
+        : blocked(
+            "max_api_keys_per_workspace",
+            `API key limit reached (${limits.maxApiKeysPerWorkspace})`,
+          );
     }
     case "schedule:create": {
       if (!limits.maxSchedulesPerWorkspace || !input.workspaceId) {
@@ -103,7 +132,10 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       const count = await countScheduledTasksForWorkspace(deps.db, input.workspaceId);
       return count < limits.maxSchedulesPerWorkspace
         ? { allowed: true }
-        : blocked("max_schedules_per_workspace", `scheduled task limit reached (${limits.maxSchedulesPerWorkspace})`);
+        : blocked(
+            "max_schedules_per_workspace",
+            `scheduled task limit reached (${limits.maxSchedulesPerWorkspace})`,
+          );
     }
     case "file:upload": {
       if (!limits.maxFileUploadBytes || !input.quantity) {
@@ -111,7 +143,10 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       }
       return input.quantity <= limits.maxFileUploadBytes
         ? { allowed: true }
-        : blocked("max_file_upload_bytes", `file upload exceeds static limit of ${limits.maxFileUploadBytes} bytes`);
+        : blocked(
+            "max_file_upload_bytes",
+            `file upload exceeds static limit of ${limits.maxFileUploadBytes} bytes`,
+          );
     }
     case "agent_run:create": {
       if (!limits.maxMonthlyAgentRunsPerWorkspace || !input.workspaceId) {
@@ -125,7 +160,10 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       const requested = input.quantity ?? 0;
       return used + requested <= limits.maxMonthlyAgentRunsPerWorkspace
         ? { allowed: true }
-        : blocked("max_monthly_agent_runs_per_workspace", `monthly agent run limit reached (${limits.maxMonthlyAgentRunsPerWorkspace})`);
+        : blocked(
+            "max_monthly_agent_runs_per_workspace",
+            `monthly agent run limit reached (${limits.maxMonthlyAgentRunsPerWorkspace})`,
+          );
     }
     case "tokens:consume": {
       if (codexBilled || !limits.maxMonthlyTokensPerWorkspace || !input.workspaceId) {
@@ -139,7 +177,10 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       const requested = input.quantity ?? 0;
       return used + requested <= limits.maxMonthlyTokensPerWorkspace
         ? { allowed: true }
-        : blocked("max_monthly_tokens_per_workspace", `monthly token limit reached (${limits.maxMonthlyTokensPerWorkspace})`);
+        : blocked(
+            "max_monthly_tokens_per_workspace",
+            `monthly token limit reached (${limits.maxMonthlyTokensPerWorkspace})`,
+          );
     }
     case "document:index": {
       if (!limits.maxDocumentIndexedChunksPerWorkspace || !input.workspaceId) {
@@ -153,26 +194,28 @@ async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codex
       const requested = input.quantity ?? 0;
       return used + requested <= limits.maxDocumentIndexedChunksPerWorkspace
         ? { allowed: true }
-        : blocked("max_document_indexed_chunks_per_workspace", `monthly document indexing limit reached (${limits.maxDocumentIndexedChunksPerWorkspace} chunks)`);
+        : blocked(
+            "max_document_indexed_chunks_per_workspace",
+            `monthly document indexing limit reached (${limits.maxDocumentIndexedChunksPerWorkspace} chunks)`,
+          );
     }
   }
 }
 
-export async function recordWorkspaceUsage(deps: ApiRouteDeps, input: {
-  accountId: string;
-  workspaceId: string;
-  subjectId?: string | null;
-  eventType:
-    | "agent_run.created"
-    | "file.uploaded"
-    | "document.indexed"
-    | "scheduled_task.fired";
-  quantity: number;
-  unit: string;
-  sourceResourceType: string;
-  sourceResourceId: string;
-  idempotencyKey: string;
-}): Promise<void> {
+export async function recordWorkspaceUsage(
+  deps: LimitDependencies,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId?: string | null;
+    eventType: "agent_run.created" | "file.uploaded" | "document.indexed" | "scheduled_task.fired";
+    quantity: number;
+    unit: string;
+    sourceResourceType: string;
+    sourceResourceId: string;
+    idempotencyKey: string;
+  },
+): Promise<void> {
   await recordUsageEvent(deps.db, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -186,15 +229,14 @@ export async function recordWorkspaceUsage(deps: ApiRouteDeps, input: {
   });
 }
 
-function usesCreditLimits(deps: ApiRouteDeps): boolean {
+function usesCreditLimits(deps: LimitDependencies): boolean {
   return deps.settings.billingMode === "stripe" || deps.settings.usageLimitsMode === "managed";
 }
 
 function isCostlyAction(action: LimitAction): boolean {
-  return action === "agent_run:create"
-    || action === "tokens:consume"
-    || action === "file:upload"
-    || action === "document:index";
+  return (
+    action === "agent_run:create" || action === "tokens:consume" || action === "document:index"
+  );
 }
 
 function blocked(code: string, message: string): LimitDecision {

package/src/dependencies.ts

@@ -9,26 +9,71 @@ import type { ManagedAuth } from "./managed-auth-type";
 import type { ApiSandboxClient, ResumeBoxByIdInput, ResumedSandboxSession } from "./sandbox-types";
 
 export type SessionWorkflowClient = {
-  signalUserMessage: (input: { sessionId: string; eventId: string; workflowId: string }) => Promise<void>;
-  wakeSessionWorkflow: (input: { accountId: string; workspaceId: string; sessionId: string; workflowId: string }) => Promise<void>;
-  signalApprovalDecision: (input: { sessionId: string; eventId: string; workflowId: string }) => Promise<void>;
-  // Interrupt must reach the workflow whether or not an execution is currently
-  // running: a long-lived session that has gone idle (its workflow returned
-  // after markSessionIdle) has NO running execution, so a plain
-  // getHandle().signal() throws WorkflowNotFoundError -> a 500 that leaves an
-  // operator unable to stop a session. signalWithStart start-or-signals, so it
-  // needs the session-workflow args (accountId/workspaceId) to start a fresh
-  // run when none is live; the buffered `interrupt` signal is then honored by
-  // the workflow's idle-interrupt path (pause goal + mark idle).
-  signalInterrupt: (input: { accountId: string; workspaceId: string; sessionId: string; eventId: string; workflowId: string }) => Promise<void>;
+  signalUserMessage: (input: {
+    sessionId: string;
+    eventId: string;
+    workflowId: string;
+  }) => Promise<void>;
+  wakeSessionWorkflow: (input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    workflowId: string;
+    wakeRevision: number;
+    controlEventId?: string;
+  }) => Promise<void>;
+  // Dedicated, revision-carrying nudge for a durable Codex capacity waiter.
+  // Optional for embedded/back-compat clients: callers may fall back to the
+  // generic queueChanged wake because Postgres wakeRevision is authoritative.
+  signalCodexCapacity?: (input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    workflowId: string;
+    wakeRevision: number;
+    workflowWakeRevision: number;
+  }) => Promise<void>;
+  signalApprovalDecision: (input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    eventId: string;
+    workflowId: string;
+    workflowWakeRevision: number;
+  }) => Promise<void>;
+  // A durable Pause/Steer control must reach the workflow even when its previous
+  // run returned idle. signalWithStart either delivers to the live workflow or
+  // starts the session workflow with the control already buffered.
+  signalSessionControl: (input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    eventId: string;
+    workflowId: string;
+    workflowWakeRevision: number;
+  }) => Promise<void>;
   syncScheduledTask: (input: { task: ScheduledTask }) => Promise<void>;
   deleteScheduledTaskSchedule: (input: { temporalScheduleId: string }) => Promise<void>;
-  triggerScheduledTask: (input: { task: ScheduledTask; agentRunUsageIdempotencyKey?: string; triggerWorkflowId?: string }) => Promise<void>;
+  triggerScheduledTask: (input: {
+    task: ScheduledTask;
+    agentRunUsageIdempotencyKey?: string;
+    triggerWorkflowId?: string;
+  }) => Promise<void>;
+  startRigVerification: (input: {
+    workspaceId: string;
+    changeId?: string;
+    versionId?: string;
+    workflowId?: string;
+  }) => Promise<void>;
   check?: () => Promise<void>;
 };
 
 export type DocumentIndexClient = {
-  indexDocument: (input: { accountId: string; workspaceId: string; documentId: string }) => Promise<Document | void>;
+  indexDocument: (input: {
+    accountId: string;
+    workspaceId: string;
+    documentId: string;
+  }) => Promise<Document | void>;
 };
 
 export type AppDependencies = {
@@ -36,6 +81,8 @@ export type AppDependencies = {
   db: Database;
   bus: EventBus;
   workflowClient: SessionWorkflowClient;
+  /** Optional provider override for deterministic API/object-storage tests. */
+  objectStorage?: ObjectStorageDependency;
   documentIndexer?: DocumentIndexClient;
   documentServices?: DocumentServices;
   observability?: Observability;
@@ -70,3 +117,18 @@ export type ApiRouteDeps = AppDependencies & {
   // resumeBoxById (it throws SandboxResumeError when sandboxBackend=none).
   resumeBoxById: (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession>;
 };
+
+/**
+ * The exact dependency slice used by `acceptSessionUserMessage`.
+ *
+ * Keeping this narrower than `ApiRouteDeps` lets control-plane callers reuse
+ * the canonical admission path without constructing unrelated HTTP, document,
+ * or sandbox services. The public API still passes its `ApiRouteDeps` superset.
+ */
+export type AcceptSessionUserMessageDependencies = Pick<
+  AppDependencies,
+  "settings" | "db" | "bus"
+> & {
+  workflowClient: Pick<SessionWorkflowClient, "wakeSessionWorkflow" | "signalSessionControl">;
+  objectStorage: ObjectStorageDependency;
+};