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

package/dist/bundled-agents/policy-engine-agents/src/agents/constraint-solver/handler.ts

@@ -0,0 +1,276 @@
+/**
+ * Constraint Solver Agent - Edge Function Handler
+ *
+ * This handler is designed for deployment as a Google Cloud Edge Function.
+ * It provides the HTTP interface for the Constraint Solver Agent.
+ *
+ * DEPLOYMENT:
+ * - Stateless execution
+ * - No local persistence
+ * - Deterministic behavior
+ *
+ * EXECUTION SYSTEM:
+ * - All POST endpoints require execution context (x-execution-id, x-parent-span-id)
+ * - Emits repo-level and agent-level spans per the Agentics contract
+ * - Returns ExecutionResult with full span hierarchy
+ */
+import { Request, Response } from 'express';
+import { v4 as uuidv4 } from 'uuid';
+import {
+  ConstraintSolverAgent,
+  AGENT_ID,
+  AGENT_VERSION,
+} from './agent';
+import { ConstraintSolverInput, ConstraintDecisionEvent } from '../contracts/constraint-solver';
+import { PolicyRepository } from '../../db/models/policy-repository';
+import { executeAgent, buildExecutionResult } from '../../execution/executor';
+import { ExecutionSpan } from '../../execution/types';
+import logger from '@utils/logger';
+
+/**
+ * HTTP Request body for resolve endpoint
+ */
+interface ResolveRequest {
+  context: ConstraintSolverInput['context'];
+  constraint_ids?: string[];
+  policy_ids?: string[];
+  dry_run?: boolean;
+  trace?: boolean;
+}
+
+/**
+ * Validate the request body
+ */
+function validateRequest(body: unknown): { valid: boolean; error?: string } {
+  if (!body || typeof body !== 'object') {
+    return { valid: false, error: 'Request body must be a JSON object' };
+  }
+
+  const request = body as ResolveRequest;
+
+  if (!request.context || typeof request.context !== 'object') {
+    return { valid: false, error: 'context is required and must be an object' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Create Constraint Solver Agent instance with loaded policies
+ */
+async function createAgentWithPolicies(): Promise<ConstraintSolverAgent> {
+  const repository = new PolicyRepository();
+  const policies = await repository.findActive();
+  return new ConstraintSolverAgent(policies);
+}
+
+/**
+ * Decision event artifact extractor for span attachment
+ */
+function extractDecisionArtifact(event: ConstraintDecisionEvent) {
+  return {
+    id: event.event_id,
+    type: 'constraint_decision_event',
+    reference: event.event_id,
+  };
+}
+
+/**
+ * Edge Function Handler: POST /constraint-solver/resolve
+ *
+ * Resolve constraint conflicts for a given context.
+ * Requires execution context headers (enforced by middleware).
+ */
+export async function handleResolve(req: Request, res: Response): Promise<void> {
+  const requestId = req.headers['x-request-id']?.toString() || uuidv4();
+  const repoSpan: ExecutionSpan = res.locals.repoSpan;
+
+  logger.info({ requestId, path: '/constraint-solver/resolve' }, 'Handling resolve request');
+
+  try {
+    const validation = validateRequest(req.body);
+    if (!validation.valid) {
+      const result = buildExecutionResult(repoSpan, [], undefined, {
+        code: 'INVALID_REQUEST',
+        message: validation.error!,
+      });
+      res.status(400).json(result);
+      return;
+    }
+
+    const body = req.body as ResolveRequest;
+
+    const input: ConstraintSolverInput = {
+      request_id: requestId,
+      context: body.context,
+      constraint_ids: body.constraint_ids,
+      policy_ids: body.policy_ids,
+      dry_run: body.dry_run,
+      trace: body.trace,
+    };
+
+    const { data: decisionEvent, agentSpan } = await executeAgent(
+      repoSpan,
+      AGENT_ID,
+      async () => {
+        const agent = await createAgentWithPolicies();
+        return agent.resolve(input);
+      },
+      extractDecisionArtifact,
+    );
+
+    const result = buildExecutionResult(repoSpan, [agentSpan], decisionEvent);
+    res.status(200).json(result);
+  } catch (error) {
+    logger.error({ requestId, error }, 'Resolve request failed');
+
+    const result = buildExecutionResult(repoSpan, [], undefined, {
+      code: 'RESOLUTION_ERROR',
+      message: error instanceof Error ? error.message : 'Unknown error',
+      details: process.env.NODE_ENV === 'development' ? error : undefined,
+    });
+    res.status(500).json(result);
+  }
+}
+
+/**
+ * Edge Function Handler: POST /constraint-solver/analyze
+ *
+ * Analyze constraints without resolving.
+ * Requires execution context headers (enforced by middleware).
+ */
+export async function handleAnalyze(req: Request, res: Response): Promise<void> {
+  const requestId = req.headers['x-request-id']?.toString() || uuidv4();
+  const repoSpan: ExecutionSpan = res.locals.repoSpan;
+
+  logger.info({ requestId, path: '/constraint-solver/analyze' }, 'Handling analyze request');
+
+  try {
+    const validation = validateRequest(req.body);
+    if (!validation.valid) {
+      const result = buildExecutionResult(repoSpan, [], undefined, {
+        code: 'INVALID_REQUEST',
+        message: validation.error!,
+      });
+      res.status(400).json(result);
+      return;
+    }
+
+    const body = req.body as ResolveRequest;
+
+    const input: ConstraintSolverInput = {
+      request_id: requestId,
+      context: body.context,
+      constraint_ids: body.constraint_ids,
+      policy_ids: body.policy_ids,
+      dry_run: body.dry_run,
+      trace: body.trace,
+    };
+
+    const { data: decisionEvent, agentSpan } = await executeAgent(
+      repoSpan,
+      AGENT_ID,
+      async () => {
+        const agent = await createAgentWithPolicies();
+        return agent.analyze(input);
+      },
+      extractDecisionArtifact,
+    );
+
+    const result = buildExecutionResult(repoSpan, [agentSpan], decisionEvent);
+    res.status(200).json(result);
+  } catch (error) {
+    logger.error({ requestId, error }, 'Analyze request failed');
+
+    const result = buildExecutionResult(repoSpan, [], undefined, {
+      code: 'ANALYSIS_ERROR',
+      message: error instanceof Error ? error.message : 'Unknown error',
+      details: process.env.NODE_ENV === 'development' ? error : undefined,
+    });
+    res.status(500).json(result);
+  }
+}
+
+/**
+ * Edge Function Handler: POST /constraint-solver/explain
+ *
+ * Explain constraint relationships and conflicts.
+ * Requires execution context headers (enforced by middleware).
+ */
+export async function handleExplain(req: Request, res: Response): Promise<void> {
+  const requestId = req.headers['x-request-id']?.toString() || uuidv4();
+  const repoSpan: ExecutionSpan = res.locals.repoSpan;
+
+  logger.info({ requestId, path: '/constraint-solver/explain' }, 'Handling explain request');
+
+  try {
+    const validation = validateRequest(req.body);
+    if (!validation.valid) {
+      const result = buildExecutionResult(repoSpan, [], undefined, {
+        code: 'INVALID_REQUEST',
+        message: validation.error!,
+      });
+      res.status(400).json(result);
+      return;
+    }
+
+    const body = req.body as ResolveRequest;
+
+    const input: ConstraintSolverInput = {
+      request_id: requestId,
+      context: body.context,
+      constraint_ids: body.constraint_ids,
+      policy_ids: body.policy_ids,
+      dry_run: body.dry_run,
+      trace: true,
+    };
+
+    const { data: decisionEvent, agentSpan } = await executeAgent(
+      repoSpan,
+      AGENT_ID,
+      async () => {
+        const agent = await createAgentWithPolicies();
+        return agent.explain(input);
+      },
+      extractDecisionArtifact,
+    );
+
+    const result = buildExecutionResult(repoSpan, [agentSpan], decisionEvent);
+    res.status(200).json(result);
+  } catch (error) {
+    logger.error({ requestId, error }, 'Explain request failed');
+
+    const result = buildExecutionResult(repoSpan, [], undefined, {
+      code: 'EXPLANATION_ERROR',
+      message: error instanceof Error ? error.message : 'Unknown error',
+      details: process.env.NODE_ENV === 'development' ? error : undefined,
+    });
+    res.status(500).json(result);
+  }
+}
+
+/**
+ * Edge Function Handler: GET /constraint-solver/info
+ *
+ * Get agent registration information.
+ */
+export async function handleInfo(_req: Request, res: Response): Promise<void> {
+  res.status(200).json({
+    success: true,
+    data: ConstraintSolverAgent.getRegistration(),
+  });
+}
+
+/**
+ * Edge Function Handler: GET /constraint-solver/health
+ *
+ * Health check endpoint.
+ */
+export async function handleHealth(_req: Request, res: Response): Promise<void> {
+  res.status(200).json({
+    status: 'healthy',
+    agent_id: AGENT_ID,
+    agent_version: AGENT_VERSION,
+    timestamp: new Date().toISOString(),
+  });
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Constraint Solver Agent
+ *
+ * Exports the Constraint Solver Agent and its handler functions.
+ */
+export {
+  ConstraintSolverAgent,
+  AGENT_ID,
+  AGENT_VERSION,
+  DECISION_TYPE,
+} from './agent';
+
+export {
+  handleResolve,
+  handleAnalyze,
+  handleExplain,
+  handleInfo,
+  handleHealth,
+} from './handler';

package/dist/bundled-agents/policy-engine-agents/src/agents/contracts/approval-routing.ts

@@ -0,0 +1,277 @@
+/**
+ * Approval Routing Agent Contracts
+ *
+ * These schemas define the authoritative contract for ApprovalDecisionEvents
+ * emitted by the Approval Routing Agent.
+ *
+ * IMPORTANT: This follows the LLM-Policy-Engine Agent Infrastructure Constitution
+ * - All agents MUST emit exactly ONE DecisionEvent per invocation
+ * - DecisionEvents are persisted via ruvector-service (never direct SQL)
+ * - Classification: APPROVAL GATING
+ * - decision_type: "approval_routing_decision"
+ */
+
+import { AgentRegistration } from './decision-event';
+
+/**
+ * Decision types for approval routing outcomes
+ */
+export type ApprovalDecisionOutcome =
+  | 'approval_required'
+  | 'auto_approved'
+  | 'escalation_required'
+  | 'approval_bypassed'
+  | 'pending_approval';
+
+/**
+ * Priority levels for approval requests
+ */
+export type ApprovalPriority = 'low' | 'normal' | 'high' | 'critical' | 'emergency';
+
+/**
+ * Approval status
+ */
+export type ApprovalStatus =
+  | 'pending'
+  | 'in_review'
+  | 'approved'
+  | 'denied'
+  | 'escalated'
+  | 'expired'
+  | 'cancelled';
+
+/**
+ * Approver information
+ */
+export interface Approver {
+  id: string;
+  name: string;
+  role: string;
+  email: string;
+  type?: 'user' | 'group' | 'role' | 'system';
+  level?: number;
+  required?: boolean;
+  available?: boolean;
+  delegate_id?: string;
+  decision?: 'approved' | 'denied' | 'pending';
+  decision_at?: string;
+  reason?: string;
+}
+
+/**
+ * Escalation level configuration
+ */
+export interface EscalationLevel {
+  level: number;
+  approvers: Approver[];
+  timeout_seconds: number;
+  notify_all: boolean;
+  message?: string;
+  reached?: boolean;
+  reached_at?: string;
+}
+
+/**
+ * Escalation configuration for approval rules
+ */
+export interface EscalationConfig {
+  enabled: boolean;
+  levels: EscalationLevel[];
+  max_escalations: number;
+  final_action: 'deny' | 'auto_approve' | 'notify_admin';
+}
+
+/**
+ * Condition for triggering approval rules
+ */
+export interface ApprovalCondition {
+  field: string;
+  operator: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than' | 'in' | 'not_in' | 'matches';
+  value: unknown;
+  logic?: 'and' | 'or';
+}
+
+/**
+ * Conditions that allow automatic approval
+ */
+export interface AutoApproveConditions {
+  max_value?: number;
+  allowed_roles?: string[];
+  allowed_resource_types?: string[];
+  allowed_operations?: string[];
+  time_restrictions?: {
+    start_hour: number;
+    end_hour: number;
+    timezone: string;
+    business_days_only: boolean;
+  };
+  custom_conditions?: ApprovalCondition[];
+}
+
+/**
+ * Approval rule definition
+ */
+export interface ApprovalRule {
+  rule_id: string;
+  rule_name: string;
+  description?: string;
+  condition: {
+    match: ApprovalCondition[];
+    operator: 'all' | 'any';
+  };
+  required_approvers: number;
+  approver_pool: Approver[];
+  timeout_seconds: number;
+  escalation_config: EscalationConfig;
+  auto_approve_conditions?: AutoApproveConditions;
+  priority: number;
+  active?: boolean;
+  tags?: string[];
+}
+
+/**
+ * Step types for approval chain workflow
+ */
+export type ApprovalStepType = 'parallel' | 'sequential' | 'any_of';
+
+/**
+ * Single step in an approval workflow chain
+ */
+export interface ApprovalChainStep {
+  step_id: string;
+  step_order: number;
+  step_type: ApprovalStepType;
+  step_name?: string;
+  approvers: Approver[];
+  required_approvals: number;
+  timeout_seconds: number;
+  escalation_on_timeout: boolean;
+  source_rule_id?: string;
+  instructions?: string;
+}
+
+/**
+ * Action context describing the action being requested
+ */
+export interface ActionContext {
+  action_type: string;
+  resource_id: string;
+  resource_type: string;
+  operation: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Requester information for approval routing
+ */
+export interface ApprovalRequester {
+  id: string;
+  email: string;
+  roles: string[];
+  department: string;
+  manager_id?: string;
+  cost_center?: string;
+}
+
+/**
+ * Routing metadata providing details about the routing decision
+ */
+export interface RoutingMetadata {
+  rules_evaluated: string[];
+  rules_matched: string[];
+  auto_approve_reason?: string;
+  escalation_reason?: string;
+  bypass_reason?: string;
+  risk_score?: number;
+  compliance_tags?: string[];
+  audit_ref?: string;
+}
+
+/**
+ * Input for approval routing requests
+ */
+export interface ApprovalRoutingInput {
+  request_id: string;
+  action_context: ActionContext;
+  requester: ApprovalRequester;
+  approval_rules?: string[];
+  priority?: ApprovalPriority;
+  metadata?: Record<string, unknown>;
+  dry_run?: boolean;
+  trace?: boolean;
+}
+
+/**
+ * Output from approval routing evaluation
+ */
+export interface ApprovalRoutingOutput {
+  decision: ApprovalDecisionOutcome;
+  required_approvers: Approver[];
+  approval_chain: ApprovalChainStep[];
+  timeout_seconds: number;
+  escalation_path: EscalationLevel[];
+  justification_required: boolean;
+  routing_metadata: RoutingMetadata;
+  evaluation_time_ms: number;
+}
+
+/**
+ * ApprovalDecisionEvent - Core output contract for Approval Routing Agent
+ *
+ * This schema MUST be emitted exactly ONCE per ApprovalRoutingAgent invocation.
+ * It is persisted to ruvector-service for audit, analytics, and governance.
+ */
+export interface ApprovalDecisionEvent {
+  event_id: string;
+  agent_id: string;
+  agent_version: string;
+  decision_type: 'approval_routing_decision';
+  inputs_hash: string;
+  outputs: ApprovalRoutingOutput;
+  confidence: number;
+  rules_applied: ApprovalRule[];
+  execution_ref: {
+    request_id: string;
+    trace_id?: string;
+    span_id?: string;
+    environment: string;
+    session_id?: string;
+  };
+  timestamp: string;
+  metadata?: {
+    cached?: boolean;
+    engine_version?: string;
+    mode?: 'real-time' | 'batch' | 'dry-run';
+    source?: string;
+    sla_tier?: string;
+  };
+}
+
+/**
+ * Status check response
+ */
+export interface ApprovalStatusResponse {
+  approval_request_id: string;
+  request_id?: string;
+  status: ApprovalStatus;
+  decision: ApprovalDecisionOutcome;
+  approvers: Approver[];
+  escalation_level?: number;
+  time_remaining_seconds?: number;
+  current_step?: number;
+  total_steps?: number;
+  approvals_received?: Array<{
+    approver_id: string;
+    approver_name: string;
+    decision: string;
+    timestamp: string;
+    comments?: string;
+  }>;
+  updated_at: string;
+  created_at: string;
+}
+
+/**
+ * Approval Routing Agent registration
+ */
+export type ApprovalRoutingAgentRegistration = AgentRegistration;