@llm-dev-ops/agentics-cli 1.4.26 → 1.4.29

package/dist/bundled-agents/policy-engine-agents/src/db/models/policy-repository.ts

@@ -0,0 +1,204 @@
+/**
+ * Policy Repository - Database operations for policies
+ */
+import { db } from '../client';
+import { Policy, PolicyStatus } from '../../types/policy';
+import { DatabaseError, PolicyNotFoundError } from '@utils/errors';
+import logger from '@utils/logger';
+
+export class PolicyRepository {
+  /**
+   * Create a new policy
+   */
+  async create(policy: Policy, createdBy?: string): Promise<Policy> {
+    try {
+      const result = await db.query(
+        `INSERT INTO policies (
+          id, name, description, version, namespace, tags, priority, status, rules, created_by
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+        RETURNING *`,
+        [
+          policy.metadata.id,
+          policy.metadata.name,
+          policy.metadata.description,
+          policy.metadata.version,
+          policy.metadata.namespace,
+          policy.metadata.tags || [],
+          policy.metadata.priority || 0,
+          policy.status,
+          JSON.stringify(policy.rules),
+          createdBy,
+        ],
+      );
+
+      logger.info({ policyId: policy.metadata.id }, 'Policy created in database');
+
+      return this.mapRowToPolicy(result.rows[0]);
+    } catch (error) {
+      throw new DatabaseError(
+        `Failed to create policy: ${error instanceof Error ? error.message : String(error)}`,
+        { policyId: policy.metadata.id },
+      );
+    }
+  }
+
+  /**
+   * Get policy by ID
+   */
+  async findById(id: string): Promise<Policy | null> {
+    try {
+      const result = await db.query(
+        'SELECT * FROM policies WHERE id = $1',
+        [id],
+      );
+
+      if (result.rows.length === 0) {
+        return null;
+      }
+
+      return this.mapRowToPolicy(result.rows[0]);
+    } catch (error) {
+      throw new DatabaseError(
+        `Failed to find policy: ${error instanceof Error ? error.message : String(error)}`,
+        { policyId: id },
+      );
+    }
+  }
+
+  /**
+   * Get all active policies
+   */
+  async findActive(): Promise<Policy[]> {
+    try {
+      const result = await db.query(
+        'SELECT * FROM policies WHERE status = $1 ORDER BY priority DESC, created_at DESC',
+        ['active'],
+      );
+
+      return result.rows.map((row) => this.mapRowToPolicy(row));
+    } catch (error) {
+      throw new DatabaseError(
+        `Failed to find active policies: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  /**
+   * Get policies by namespace
+   */
+  async findByNamespace(namespace: string): Promise<Policy[]> {
+    try {
+      const result = await db.query(
+        'SELECT * FROM policies WHERE namespace = $1 ORDER BY priority DESC, created_at DESC',
+        [namespace],
+      );
+
+      return result.rows.map((row) => this.mapRowToPolicy(row));
+    } catch (error) {
+      throw new DatabaseError(
+        `Failed to find policies by namespace: ${error instanceof Error ? error.message : String(error)}`,
+        { namespace },
+      );
+    }
+  }
+
+  /**
+   * Update policy
+   */
+  async update(id: string, updates: Partial<Policy>): Promise<Policy> {
+    try {
+      const existing = await this.findById(id);
+      if (!existing) {
+        throw new PolicyNotFoundError(id);
+      }
+
+      const updatedPolicy = {
+        ...existing,
+        ...updates,
+        metadata: {
+          ...existing.metadata,
+          ...updates.metadata,
+        },
+      };
+
+      const result = await db.query(
+        `UPDATE policies SET
+          name = $1, description = $2, version = $3, namespace = $4,
+          tags = $5, priority = $6, status = $7, rules = $8
+        WHERE id = $9
+        RETURNING *`,
+        [
+          updatedPolicy.metadata.name,
+          updatedPolicy.metadata.description,
+          updatedPolicy.metadata.version,
+          updatedPolicy.metadata.namespace,
+          updatedPolicy.metadata.tags || [],
+          updatedPolicy.metadata.priority || 0,
+          updatedPolicy.status,
+          JSON.stringify(updatedPolicy.rules),
+          id,
+        ],
+      );
+
+      logger.info({ policyId: id }, 'Policy updated in database');
+
+      return this.mapRowToPolicy(result.rows[0]);
+    } catch (error) {
+      if (error instanceof PolicyNotFoundError) {
+        throw error;
+      }
+      throw new DatabaseError(
+        `Failed to update policy: ${error instanceof Error ? error.message : String(error)}`,
+        { policyId: id },
+      );
+    }
+  }
+
+  /**
+   * Delete policy
+   */
+  async delete(id: string): Promise<void> {
+    try {
+      const result = await db.query(
+        'DELETE FROM policies WHERE id = $1',
+        [id],
+      );
+
+      if (result.rowCount === 0) {
+        throw new PolicyNotFoundError(id);
+      }
+
+      logger.info({ policyId: id }, 'Policy deleted from database');
+    } catch (error) {
+      if (error instanceof PolicyNotFoundError) {
+        throw error;
+      }
+      throw new DatabaseError(
+        `Failed to delete policy: ${error instanceof Error ? error.message : String(error)}`,
+        { policyId: id },
+      );
+    }
+  }
+
+  /**
+   * Map database row to Policy object
+   */
+  private mapRowToPolicy(row: any): Policy {
+    return {
+      metadata: {
+        id: row.id,
+        name: row.name,
+        description: row.description,
+        version: row.version,
+        namespace: row.namespace,
+        tags: row.tags || [],
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        createdBy: row.created_by,
+        priority: row.priority,
+      },
+      rules: row.rules,
+      status: row.status as PolicyStatus,
+    };
+  }
+}

package/dist/bundled-agents/policy-engine-agents/src/db/schema.sql

@@ -0,0 +1,164 @@
+-- LLM Policy Engine Database Schema
+-- PostgreSQL 15+
+
+-- Enable UUID extension
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- Policies table
+CREATE TABLE IF NOT EXISTS policies (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    version VARCHAR(50) NOT NULL,
+    namespace VARCHAR(255) NOT NULL DEFAULT 'default',
+    tags TEXT[] DEFAULT '{}',
+    priority INTEGER DEFAULT 0,
+    status VARCHAR(20) NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'draft', 'deprecated')),
+    rules JSONB NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    created_by VARCHAR(255),
+    UNIQUE(namespace, name, version)
+);
+
+-- Create indexes for policies
+CREATE INDEX IF NOT EXISTS idx_policies_namespace ON policies(namespace);
+CREATE INDEX IF NOT EXISTS idx_policies_status ON policies(status);
+CREATE INDEX IF NOT EXISTS idx_policies_priority ON policies(priority DESC);
+CREATE INDEX IF NOT EXISTS idx_policies_tags ON policies USING GIN(tags);
+CREATE INDEX IF NOT EXISTS idx_policies_created_at ON policies(created_at DESC);
+
+-- Policy evaluations (audit log)
+CREATE TABLE IF NOT EXISTS policy_evaluations (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    request_id VARCHAR(255) NOT NULL,
+    policy_ids TEXT[] DEFAULT '{}',
+    matched_policy_ids TEXT[] DEFAULT '{}',
+    matched_rule_ids TEXT[] DEFAULT '{}',
+    decision VARCHAR(20) NOT NULL CHECK (decision IN ('allow', 'deny', 'warn', 'modify')),
+    allowed BOOLEAN NOT NULL,
+    reason TEXT,
+    context JSONB NOT NULL,
+    modifications JSONB,
+    evaluation_time_ms NUMERIC(10, 2),
+    trace JSONB,
+    cached BOOLEAN DEFAULT false,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    user_id VARCHAR(255),
+    team_id VARCHAR(255),
+    project_id VARCHAR(255)
+);
+
+-- Create indexes for policy_evaluations
+CREATE INDEX IF NOT EXISTS idx_evaluations_request_id ON policy_evaluations(request_id);
+CREATE INDEX IF NOT EXISTS idx_evaluations_created_at ON policy_evaluations(created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_evaluations_decision ON policy_evaluations(decision);
+CREATE INDEX IF NOT EXISTS idx_evaluations_user_id ON policy_evaluations(user_id);
+CREATE INDEX IF NOT EXISTS idx_evaluations_team_id ON policy_evaluations(team_id);
+CREATE INDEX IF NOT EXISTS idx_evaluations_project_id ON policy_evaluations(project_id);
+CREATE INDEX IF NOT EXISTS idx_evaluations_matched_policies ON policy_evaluations USING GIN(matched_policy_ids);
+
+-- API Keys table
+CREATE TABLE IF NOT EXISTS api_keys (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    name VARCHAR(255) NOT NULL,
+    key_hash VARCHAR(255) NOT NULL UNIQUE,
+    key_prefix VARCHAR(20) NOT NULL,
+    permissions TEXT[] DEFAULT '{}',
+    rate_limit INTEGER DEFAULT 100,
+    expires_at TIMESTAMP WITH TIME ZONE,
+    last_used_at TIMESTAMP WITH TIME ZONE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    created_by VARCHAR(255),
+    revoked BOOLEAN DEFAULT false
+);
+
+-- Create indexes for api_keys
+CREATE INDEX IF NOT EXISTS idx_api_keys_key_hash ON api_keys(key_hash);
+CREATE INDEX IF NOT EXISTS idx_api_keys_revoked ON api_keys(revoked);
+
+-- Users table (for RBAC)
+CREATE TABLE IF NOT EXISTS users (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    email VARCHAR(255) NOT NULL UNIQUE,
+    password_hash VARCHAR(255),
+    roles TEXT[] DEFAULT '{}',
+    permissions TEXT[] DEFAULT '{}',
+    metadata JSONB DEFAULT '{}',
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    last_login_at TIMESTAMP WITH TIME ZONE
+);
+
+-- Create indexes for users
+CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
+CREATE INDEX IF NOT EXISTS idx_users_roles ON users USING GIN(roles);
+
+-- Teams table
+CREATE TABLE IF NOT EXISTS teams (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    name VARCHAR(255) NOT NULL UNIQUE,
+    tier VARCHAR(50) DEFAULT 'free',
+    monthly_budget NUMERIC(10, 2),
+    current_spend NUMERIC(10, 2) DEFAULT 0,
+    metadata JSONB DEFAULT '{}',
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Create indexes for teams
+CREATE INDEX IF NOT EXISTS idx_teams_name ON teams(name);
+CREATE INDEX IF NOT EXISTS idx_teams_tier ON teams(tier);
+
+-- Team members table
+CREATE TABLE IF NOT EXISTS team_members (
+    team_id UUID REFERENCES teams(id) ON DELETE CASCADE,
+    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+    role VARCHAR(50) DEFAULT 'member',
+    joined_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    PRIMARY KEY (team_id, user_id)
+);
+
+-- Policy versions table (for versioning and rollback)
+CREATE TABLE IF NOT EXISTS policy_versions (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    policy_id UUID REFERENCES policies(id) ON DELETE CASCADE,
+    version VARCHAR(50) NOT NULL,
+    content JSONB NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    created_by VARCHAR(255),
+    UNIQUE(policy_id, version)
+);
+
+-- Create indexes for policy_versions
+CREATE INDEX IF NOT EXISTS idx_policy_versions_policy_id ON policy_versions(policy_id);
+CREATE INDEX IF NOT EXISTS idx_policy_versions_created_at ON policy_versions(created_at DESC);
+
+-- Function to update updated_at timestamp
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ language 'plpgsql';
+
+-- Create triggers for updated_at
+CREATE TRIGGER update_policies_updated_at BEFORE UPDATE ON policies
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_users_updated_at BEFORE UPDATE ON users
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_teams_updated_at BEFORE UPDATE ON teams
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- Create views
+CREATE OR REPLACE VIEW active_policies AS
+SELECT * FROM policies WHERE status = 'active'
+ORDER BY priority DESC, created_at DESC;
+
+CREATE OR REPLACE VIEW recent_evaluations AS
+SELECT * FROM policy_evaluations
+ORDER BY created_at DESC
+LIMIT 1000;

package/dist/bundled-agents/policy-engine-agents/src/execution/context.ts

@@ -0,0 +1,63 @@
+/**
+ * Agentics Execution System - Context Validation
+ *
+ * Validates and extracts execution context from incoming requests.
+ * The Core MUST provide execution_id and parent_span_id on every call.
+ */
+import { Request } from 'express';
+import { ExecutionContext } from './types';
+import { ExecutionContextError } from './errors';
+
+/**
+ * Header names for execution context propagation.
+ */
+export const EXECUTION_ID_HEADER = 'x-execution-id';
+export const PARENT_SPAN_ID_HEADER = 'x-parent-span-id';
+
+/**
+ * Validate that an execution context object has all required fields.
+ *
+ * @throws ExecutionContextError if context is missing or invalid
+ */
+export function validateExecutionContext(ctx: unknown): asserts ctx is ExecutionContext {
+  if (!ctx || typeof ctx !== 'object') {
+    throw new ExecutionContextError('Execution context is required');
+  }
+
+  const context = ctx as Record<string, unknown>;
+
+  if (!context.execution_id || typeof context.execution_id !== 'string') {
+    throw new ExecutionContextError(
+      'execution_id is required and must be a non-empty string',
+      { received: context.execution_id },
+    );
+  }
+
+  if (!context.parent_span_id || typeof context.parent_span_id !== 'string') {
+    throw new ExecutionContextError(
+      'parent_span_id is required and must be a non-empty string',
+      { received: context.parent_span_id },
+    );
+  }
+}
+
+/**
+ * Extract execution context from Express request headers.
+ *
+ * @param req - Express request object
+ * @returns Validated ExecutionContext
+ * @throws ExecutionContextError if headers are missing or invalid
+ */
+export function extractExecutionContext(req: Request): ExecutionContext {
+  const executionId = req.headers[EXECUTION_ID_HEADER]?.toString();
+  const parentSpanId = req.headers[PARENT_SPAN_ID_HEADER]?.toString();
+
+  const context = {
+    execution_id: executionId,
+    parent_span_id: parentSpanId,
+  };
+
+  validateExecutionContext(context);
+
+  return context as ExecutionContext;
+}

package/dist/bundled-agents/policy-engine-agents/src/execution/errors.ts

@@ -0,0 +1,28 @@
+/**
+ * Agentics Execution System - Error Classes
+ *
+ * Execution-specific errors for context validation and invariant enforcement.
+ */
+import { PolicyEngineError } from '../utils/errors';
+
+/**
+ * Thrown when execution context is missing or invalid.
+ * Maps to HTTP 400 — the caller (Core) must provide valid context.
+ */
+export class ExecutionContextError extends PolicyEngineError {
+  constructor(message: string, details?: unknown) {
+    super(message, 'EXECUTION_CONTEXT_ERROR', 400, details);
+    this.name = 'ExecutionContextError';
+  }
+}
+
+/**
+ * Thrown when an execution invariant is violated.
+ * Maps to HTTP 500 — indicates a bug in the execution layer.
+ */
+export class ExecutionInvariantError extends PolicyEngineError {
+  constructor(message: string, details?: unknown) {
+    super(message, 'EXECUTION_INVARIANT_ERROR', 500, details);
+    this.name = 'ExecutionInvariantError';
+  }
+}

package/dist/bundled-agents/policy-engine-agents/src/execution/executor.ts

@@ -0,0 +1,135 @@
+/**
+ * Agentics Execution System - Agent Execution Wrapper
+ *
+ * Wraps agent invocations to create proper span hierarchy, attach
+ * artifacts, and enforce execution invariants.
+ */
+import { ExecutionSpan, ExecutionResult, Artifact } from './types';
+import { createAgentSpan, finalizeSpan, attachArtifact } from './spans';
+import logger from '../utils/logger';
+
+/**
+ * Result of a single agent execution, including the span and data.
+ */
+export interface AgentExecutionResult<T> {
+  data: T;
+  agentSpan: ExecutionSpan;
+}
+
+/**
+ * Execute an agent within the execution span hierarchy.
+ *
+ * Creates an agent-level span, runs the provided function,
+ * finalizes the span, and attaches the result as an artifact.
+ *
+ * @param repoSpan - The repo-level parent span
+ * @param agentName - Name of the agent being executed
+ * @param fn - The agent function to execute
+ * @param artifactExtractor - Optional function to extract artifact info from the result
+ */
+export async function executeAgent<T>(
+  repoSpan: ExecutionSpan,
+  agentName: string,
+  fn: () => Promise<T>,
+  artifactExtractor?: (result: T) => Omit<Artifact, 'producer_span_id'>,
+): Promise<AgentExecutionResult<T>> {
+  const agentSpan = createAgentSpan(repoSpan.span_id, agentName);
+
+  logger.info(
+    {
+      agent_name: agentName,
+      agent_span_id: agentSpan.span_id,
+      repo_span_id: repoSpan.span_id,
+    },
+    'Agent execution started',
+  );
+
+  try {
+    const data = await fn();
+
+    finalizeSpan(agentSpan, 'completed');
+
+    if (artifactExtractor) {
+      attachArtifact(agentSpan, artifactExtractor(data));
+    }
+
+    logger.info(
+      {
+        agent_name: agentName,
+        agent_span_id: agentSpan.span_id,
+        status: 'completed',
+      },
+      'Agent execution completed',
+    );
+
+    return { data, agentSpan };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    finalizeSpan(agentSpan, 'failed', errorMessage);
+
+    logger.error(
+      {
+        agent_name: agentName,
+        agent_span_id: agentSpan.span_id,
+        error: errorMessage,
+      },
+      'Agent execution failed',
+    );
+
+    throw error;
+  }
+}
+
+/**
+ * Build the final ExecutionResult, enforcing all invariants.
+ *
+ * Invariants enforced:
+ * - At least one agent span MUST exist (otherwise execution is INVALID)
+ * - Repo span is finalized with appropriate status
+ * - All spans are included in the output
+ *
+ * @param repoSpan - The repo-level span
+ * @param agentSpans - All agent-level spans from this execution
+ * @param data - The primary data payload (if successful)
+ * @param error - Error info (if execution failed)
+ */
+export function buildExecutionResult<T>(
+  repoSpan: ExecutionSpan,
+  agentSpans: ExecutionSpan[],
+  data?: T,
+  error?: { code: string; message: string; details?: unknown },
+): ExecutionResult<T> {
+  // Invariant: at least one agent span must exist
+  if (agentSpans.length === 0) {
+    finalizeSpan(repoSpan, 'failed', 'No agent-level spans were emitted — execution is INVALID');
+
+    return {
+      success: false,
+      error: {
+        code: 'EXECUTION_INVARIANT_ERROR',
+        message: 'No agent-level spans were emitted. This repository MUST NOT execute silently.',
+      },
+      execution: {
+        repo_span: repoSpan,
+        agent_spans: [],
+      },
+    };
+  }
+
+  // Determine repo span status from agent spans
+  const anyFailed = agentSpans.some((s) => s.status === 'failed');
+  const repoStatus = error || anyFailed ? 'failed' : 'completed';
+  const repoError = error?.message || (anyFailed ? 'One or more agent spans failed' : undefined);
+
+  finalizeSpan(repoSpan, repoStatus, repoError);
+
+  return {
+    success: !error && !anyFailed,
+    data,
+    error,
+    execution: {
+      repo_span: repoSpan,
+      agent_spans: agentSpans,
+    },
+  };
+}

package/dist/bundled-agents/policy-engine-agents/src/execution/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Agentics Execution System
+ *
+ * This module instruments the policy-engine repository as a Foundational
+ * Execution Unit within the Agentics execution system. It provides:
+ *
+ * - Execution context validation and propagation
+ * - Repo-level and agent-level span creation
+ * - Artifact attachment to spans
+ * - Express middleware for context enforcement
+ * - Agent execution wrappers with span management
+ * - Invariant enforcement (no silent execution)
+ */
+
+// Types
+export {
+  ExecutionContext,
+  SpanStatus,
+  ExecutionSpan,
+  Artifact,
+  ExecutionResult,
+} from './types';
+
+// Errors
+export { ExecutionContextError, ExecutionInvariantError } from './errors';
+
+// Span management
+export {
+  createRepoSpan,
+  createAgentSpan,
+  finalizeSpan,
+  attachArtifact,
+} from './spans';
+
+// Context validation
+export {
+  validateExecutionContext,
+  extractExecutionContext,
+  EXECUTION_ID_HEADER,
+  PARENT_SPAN_ID_HEADER,
+} from './context';
+
+// Middleware
+export { executionContextMiddleware } from './middleware';
+
+// Executor
+export { executeAgent, buildExecutionResult } from './executor';
+export type { AgentExecutionResult } from './executor';

package/dist/bundled-agents/policy-engine-agents/src/execution/middleware.ts

@@ -0,0 +1,63 @@
+/**
+ * Agentics Execution System - Express Middleware
+ *
+ * Validates execution context on incoming requests, creates the
+ * repo-level span, and attaches both to the request for downstream handlers.
+ *
+ * This middleware MUST be applied to all externally-invoked execution
+ * endpoints (POST routes that trigger agent logic).
+ */
+import { Request, Response, NextFunction } from 'express';
+import { extractExecutionContext } from './context';
+import { createRepoSpan } from './spans';
+import { ExecutionContextError } from './errors';
+import logger from '../utils/logger';
+
+/**
+ * Express middleware that enforces execution context requirements.
+ *
+ * On success:
+ * - Sets res.locals.executionContext (ExecutionContext)
+ * - Sets res.locals.repoSpan (ExecutionSpan)
+ *
+ * On failure:
+ * - Returns 400 with explicit error if parent_span_id is missing/invalid
+ */
+export function executionContextMiddleware(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  try {
+    const executionContext = extractExecutionContext(req);
+
+    const repoSpan = createRepoSpan(executionContext.parent_span_id);
+
+    res.locals.executionContext = executionContext;
+    res.locals.repoSpan = repoSpan;
+
+    logger.info(
+      {
+        execution_id: executionContext.execution_id,
+        parent_span_id: executionContext.parent_span_id,
+        repo_span_id: repoSpan.span_id,
+      },
+      'Execution context established',
+    );
+
+    next();
+  } catch (error) {
+    if (error instanceof ExecutionContextError) {
+      res.status(400).json({
+        success: false,
+        error: {
+          code: error.code,
+          message: error.message,
+          details: error.details,
+        },
+      });
+      return;
+    }
+    next(error);
+  }
+}