feat: complete DAL scope helper migration and error handling infrastructure

.changeset/sudden-cyan-centipede.md

@@ -0,0 +1,5 @@
+---
+"@inkeep/agents-core": patch
+---
+
+Add defense-in-depth tenant scoping to runtime DAL functions and migrate all DAL files to type-safe scope helpers

AGENTS.md

@@ -17,7 +17,7 @@ This file provides guidance for AI coding agents (Claude Code, Cursor, Codex, Am
 **Pre-push** (run both, in order):
 ```bash
 pnpm format     # auto-fix formatting
-pnpm check      # lint + typecheck + test + format:check + env-descriptions + route-handler-patterns + knip
+pnpm check      # lint + typecheck + test + format:check + env-descriptions + route-handler-patterns + dal-boundary + knip
 ```
 
 **Single-command iteration:** `pnpm typecheck`, `pnpm lint` (`lint:fix`), `pnpm test`, `cd <pkg> && pnpm test --run <file>`

agents-api/src/domains/evals/workflow/functions/runDatasetItem.ts

@@ -11,6 +11,7 @@ import {
   getConversation,
   getEvaluatorById,
   getProjectScopedRef,
+  isForeignKeyViolation,
   resolveRef,
   updateEvaluationResult,
   withRef,
@@ -114,9 +115,8 @@ async function createRelationStep(payload: RunDatasetItemPayload, conversationId
     );
 
     return { relationId, success: true };
-  } catch (error: any) {
-    // If foreign key constraint fails, the conversation doesn't exist
-    if (error?.cause?.code === '23503' || error?.code === '23503') {
+  } catch (error) {
+    if (isForeignKeyViolation(error)) {
       logger.warn(
         { tenantId, projectId, datasetItemId, datasetRunId, conversationId },
         'Conversation does not exist, skipping relation creation'

agents-api/src/domains/manage/routes/apiKeys.ts

@@ -12,6 +12,7 @@ import {
   ErrorResponseSchema,
   generateApiKey,
   getApiKeyById,
+  isForeignKeyViolation,
   listApiKeysPaginated,
   PaginationQueryParamsSchema,
   TenantProjectIdParamsSchema,
@@ -193,9 +194,8 @@ app.openapi(
         },
         201
       );
-    } catch (error: any) {
-      // Handle foreign key constraint violations (PostgreSQL foreign key violation)
-      if (error?.cause?.code === '23503') {
+    } catch (error) {
+      if (isForeignKeyViolation(error)) {
         throw createApiError({
           code: 'bad_request',
           message: 'Invalid agentId - agent does not exist',

agents-api/src/domains/manage/routes/subAgentToolRelations.ts

@@ -9,6 +9,7 @@ import {
   getAgentToolRelationByAgent,
   getAgentToolRelationById,
   getAgentToolRelationByTool,
+  isForeignKeyViolation,
   listAgentToolRelations,
   PaginationQueryParamsSchema,
   SubAgentToolRelationApiInsertSchema,
@@ -254,8 +255,7 @@ app.openapi(
       });
       return c.json({ data: agentToolRelation }, 201);
     } catch (error) {
-      // Handle foreign key constraint violations (PostgreSQL foreign key violation)
-      if ((error as any)?.cause?.code === '23503') {
+      if (isForeignKeyViolation(error)) {
         throw createApiError({
           code: 'bad_request',
           message: 'Invalid subAgent ID or tool ID - referenced entity does not exist',

agents-api/src/domains/run/a2a/handlers.ts

@@ -285,6 +285,7 @@ async function handleMessageSend(
 
     await updateTask(runDbClient)({
       taskId: task.id,
+      scopes: { tenantId: agent.tenantId, projectId: agent.projectId },
       data: {
         status: result.status.state.toLowerCase(),
         metadata: {

agents-api/src/domains/run/artifacts/ArtifactService.ts

@@ -137,11 +137,13 @@ export class ArtifactService {
     try {
       const taskIds = await listTaskIdsByContextId(runDbClient)({
         contextId: contextId,
+        scopes: { tenantId, projectId },
       });
 
       for (const taskId of taskIds) {
         const task = await getTask(runDbClient)({
           id: taskId,
+          scopes: { tenantId, projectId },
         });
         if (!task) {
           logger.warn({ taskId }, 'Task not found when fetching artifacts');

agents-api/src/domains/run/context/contextCache.ts

@@ -65,6 +65,10 @@ export class ContextCache {
         contextConfigId,
         contextVariableKey,
         requestHash,
+        scopes: {
+          tenantId: this.executionContext.tenantId,
+          projectId: this.executionContext.projectId,
+        },
       });
       if (!cacheEntry) {
         return null;

agents-api/src/domains/run/handlers/executionHandler.ts

@@ -205,7 +205,10 @@ export class ExecutionHandler {
             'Task already exists, fetching existing task'
           );
 
-          const existingTask = await getTask(runDbClient)({ id: taskId });
+          const existingTask = await getTask(runDbClient)({
+            id: taskId,
+            scopes: { tenantId, projectId },
+          });
           if (existingTask) {
             task = existingTask;
             logger.info(
@@ -368,6 +371,7 @@ export class ExecutionHandler {
                 if (task) {
                   await updateTask(runDbClient)({
                     taskId: task.id,
+                    scopes: { tenantId, projectId },
                     data: {
                       status: 'failed',
                       metadata: {
@@ -536,6 +540,7 @@ export class ExecutionHandler {
               const updateTaskStart = Date.now();
               await updateTask(runDbClient)({
                 taskId: task.id,
+                scopes: { tenantId, projectId },
                 data: {
                   status: 'completed',
                   metadata: {
@@ -636,6 +641,7 @@ export class ExecutionHandler {
               if (task) {
                 await updateTask(runDbClient)({
                   taskId: task.id,
+                  scopes: { tenantId, projectId },
                   data: {
                     status: 'failed',
                     metadata: {
@@ -699,6 +705,7 @@ export class ExecutionHandler {
           if (task) {
             await updateTask(runDbClient)({
               taskId: task.id,
+              scopes: { tenantId, projectId },
               data: {
                 status: 'failed',
                 metadata: {
@@ -747,6 +754,7 @@ export class ExecutionHandler {
           if (task) {
             await updateTask(runDbClient)({
               taskId: task.id,
+              scopes: { tenantId, projectId },
               data: {
                 status: 'failed',
                 metadata: {

package.json

@@ -33,7 +33,7 @@
     "typecheck": "turbo typecheck --filter='!agents-cookbook-templates'",
     "typecheck:watch": "turbo typecheck:watch",
     "precheck": "pnpm install --frozen-lockfile",
-    "check": "turbo check --filter='!agents-cookbook-templates' && pnpm format:check && pnpm check:env-descriptions && pnpm check:route-handler-patterns && pnpm knip",
+    "check": "turbo check --filter='!agents-cookbook-templates' && pnpm format:check && pnpm check:env-descriptions && pnpm check:route-handler-patterns && pnpm check:dal-boundary && pnpm knip",
     "check:husky": "turbo check:husky --filter='!agents-cookbook-templates' --filter='!@inkeep/agents-docs'",
     "check:prepush": "turbo check:prepush --filter='!agents-cookbook-templates' --filter='!@inkeep/agents-docs'",
     "check:fix": "biome check --write",
@@ -79,6 +79,7 @@
     "spicedb:sync": "bash scripts/sync-spicedb.sh",
     "spicedb:sync:apply": "bash scripts/sync-spicedb.sh --apply",
     "db:auth:init": "pnpm --filter @inkeep/agents-core db:auth:init",
+    "check:dal-boundary": "bash scripts/lint-data-access-boundary.sh",
     "check:env-descriptions": "node scripts/check-env-descriptions.mjs",
     "check:route-handler-patterns": "node scripts/check-route-handler-patterns.mjs",
     "setup-slack-dev": "tsx scripts/setup-slack-dev.ts"

packages/agents-core/src/__tests__/data-access/apiKeys.test.ts

@@ -615,7 +615,10 @@ describe('API Keys Data Access', () => {
         update: mockUpdate,
       } as any;
 
-      await updateApiKeyLastUsed(mockDb)(apiKeyId);
+      await updateApiKeyLastUsed(mockDb)({
+        id: apiKeyId,
+        scopes: { tenantId: 'test-tenant', projectId: 'test-project' },
+      });
 
       expect(mockUpdate).toHaveBeenCalled();
       // Verify the set method was called with lastUsedAt

packages/agents-core/src/__tests__/data-access/contextCache.test.ts

@@ -63,6 +63,7 @@ describe('Context Cache Data Access', () => {
         conversationId: testConversationId,
         contextConfigId: testContextConfigId,
         contextVariableKey: testContextVariableKey,
+        scopes: { tenantId: testTenantId, projectId: testProjectId },
       });
 
       expect(mockQuery.contextCache.findFirst).toHaveBeenCalled();
@@ -85,6 +86,7 @@ describe('Context Cache Data Access', () => {
         conversationId: testConversationId,
         contextConfigId: testContextConfigId,
         contextVariableKey: testContextVariableKey,
+        scopes: { tenantId: testTenantId, projectId: testProjectId },
       });
 
       expect(result).toBeNull();
@@ -124,6 +126,7 @@ describe('Context Cache Data Access', () => {
         contextConfigId: testContextConfigId,
         contextVariableKey: testContextVariableKey,
         requestHash: 'newHash',
+        scopes: { tenantId: testTenantId, projectId: testProjectId },
       });
 
       expect(result).toBeNull();
@@ -163,6 +166,7 @@ describe('Context Cache Data Access', () => {
         contextConfigId: testContextConfigId,
         contextVariableKey: testContextVariableKey,
         requestHash: 'matchingHash',
+        scopes: { tenantId: testTenantId, projectId: testProjectId },
       });
 
       expect(result).not.toBeNull();
@@ -185,6 +189,7 @@ describe('Context Cache Data Access', () => {
         conversationId: testConversationId,
         contextConfigId: testContextConfigId,
         contextVariableKey: testContextVariableKey,
+        scopes: { tenantId: testTenantId, projectId: testProjectId },
       });
 
       expect(result).toBeNull();
@@ -224,6 +229,7 @@ describe('Context Cache Data Access', () => {
         contextConfigId: testContextConfigId,
         contextVariableKey: testContextVariableKey,
         requestHash: 'someHash',
+        scopes: { tenantId: testTenantId, projectId: testProjectId },
       });
 
       expect(result).not.toBeNull();

packages/agents-core/src/__tests__/data-access/scoping/runtime-contextCache-scoping.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { getCacheEntry, setCacheEntry } from '../../../data-access/runtime/contextCache';
+import type { AgentsRunDatabaseClient } from '../../../db/runtime/runtime-client';
+import { contextCache, conversations } from '../../../db/runtime/runtime-schema';
+import { generateId } from '../../../utils/conversations';
+import { testRunDbClient } from '../../setup';
+
+describe('runtime contextCache scoping isolation', () => {
+  let db: AgentsRunDatabaseClient;
+  const tenantA = 'tenant-a';
+  const tenantB = 'tenant-b';
+  const projectA = 'project-a';
+  const projectB = 'project-b';
+  const conversationId = 'conv-1';
+  const contextConfigId = 'config-1';
+  const contextVariableKey = 'var-key';
+
+  beforeEach(async () => {
+    db = testRunDbClient;
+    await db.delete(contextCache);
+    await db.delete(conversations);
+
+    await db.insert(conversations).values({
+      id: conversationId,
+      tenantId: tenantA,
+      projectId: projectA,
+      activeSubAgentId: 'sub-1',
+    });
+  });
+
+  it('getCacheEntry should not return a cache entry belonging to a different tenant', async () => {
+    await setCacheEntry(db)({
+      id: generateId(),
+      tenantId: tenantA,
+      projectId: projectA,
+      conversationId,
+      contextConfigId,
+      contextVariableKey,
+      ref: { type: 'branch', name: 'main', hash: 'abc' },
+      value: { data: 'test' },
+      fetchedAt: new Date().toISOString(),
+    });
+
+    const wrongTenant = await getCacheEntry(db)({
+      conversationId,
+      contextConfigId,
+      contextVariableKey,
+      scopes: { tenantId: tenantB, projectId: projectA },
+    });
+    expect(wrongTenant).toBeNull();
+
+    const correctTenant = await getCacheEntry(db)({
+      conversationId,
+      contextConfigId,
+      contextVariableKey,
+      scopes: { tenantId: tenantA, projectId: projectA },
+    });
+    expect(correctTenant).not.toBeNull();
+    expect(correctTenant?.conversationId).toBe(conversationId);
+  });
+
+  it('getCacheEntry should not return a cache entry belonging to a different project', async () => {
+    await setCacheEntry(db)({
+      id: generateId(),
+      tenantId: tenantA,
+      projectId: projectA,
+      conversationId,
+      contextConfigId,
+      contextVariableKey,
+      ref: { type: 'branch', name: 'main', hash: 'abc' },
+      value: { data: 'test' },
+      fetchedAt: new Date().toISOString(),
+    });
+
+    const wrongProject = await getCacheEntry(db)({
+      conversationId,
+      contextConfigId,
+      contextVariableKey,
+      scopes: { tenantId: tenantA, projectId: projectB },
+    });
+    expect(wrongProject).toBeNull();
+
+    const correctProject = await getCacheEntry(db)({
+      conversationId,
+      contextConfigId,
+      contextVariableKey,
+      scopes: { tenantId: tenantA, projectId: projectA },
+    });
+    expect(correctProject).not.toBeNull();
+    expect(correctProject?.conversationId).toBe(conversationId);
+  });
+});