multi-level-approval

/**
 * Multi-Level Approval - Production Reference Agent
 *
 * Canon alignment: KB 55 (MARA), KB 22 (HumanOS)
 * Demonstrates: ctx.escalate(), delegation chains, delegation narrowing
 *
 * Real use case: Request -> Manager -> VP -> CFO approval flow.
 * Each level narrows the delegation scope.
 */

import { handler, withProvenanceContext } from '@human/agent-sdk';
import type { ExecutionContext } from '@human/agent-sdk';
import { WORKFLOW_APPROVAL_ROUTING_MANIFEST } from './manifest.js';

export const AGENT_ID = 'multi-level-approval';
export const VERSION = '1.0.0';
export const CAPABILITIES = ['workflow/approval/multi_level'];

export interface MultiLevelApprovalInput {
  request_type: string;
  amount: number;
  description: string;
  requester_id?: string;
}

export interface ApprovalStep {
  level: string;
  approved: boolean;
  reason?: string;
}

export interface MultiLevelApprovalOutput {
  success: boolean;
  final_approved: boolean;
  steps: ApprovalStep[];
  provenance_id: string;
  /** Workflow manifest id when running as elevated workflow package */
  workflow_manifest_id?: string;
}

const APPROVAL_THRESHOLDS = {
  manager: 1000,
  vp: 10000,
  cfo: Infinity,
};

const execute = async (
  ctx: ExecutionContext,
  input: MultiLevelApprovalInput
): Promise<MultiLevelApprovalOutput> => {
  ctx.log.info('Starting multi-level approval', {
    type: input.request_type,
    amount: input.amount,
  });

  const steps: ApprovalStep[] = [];

  // Level 1: Manager approval (ctx.escalate)
  const managerDecision = await ctx.escalate({
    reason: `Approval request: ${input.request_type} - $${input.amount}`,
    context: {
      request_type: input.request_type,
      amount: input.amount,
      description: input.description,
      level: 'manager',
    },
    requiredCapability: 'approval/manager',
    priority: input.amount > 5000 ? 'high' : 'medium',
  });

  steps.push({
    level: 'manager',
    approved: managerDecision.approved,
    reason: managerDecision.reason,
  });

  if (!managerDecision.approved) {
    const provenanceId = await ctx.provenance.log(
      withProvenanceContext(ctx, {
        type: 'approval:rejected',
        status: 'success',
        metadata: {
          input: { request_type: input.request_type, amount: input.amount },
          output: { rejected_at: 'manager', steps },
        },
      })
    );
    return { workflow_manifest_id: WORKFLOW_APPROVAL_ROUTING_MANIFEST.id, success: true, final_approved: false, steps, provenance_id: provenanceId };
  }

  // Level 2: VP approval (if amount > $1000)
  if (input.amount > APPROVAL_THRESHOLDS.manager) {
    const vpDecision = await ctx.escalate({
      reason: `VP approval needed: ${input.request_type} - $${input.amount} (manager approved)`,
      context: {
        request_type: input.request_type,
        amount: input.amount,
        description: input.description,
        level: 'vp',
        prior_approvals: steps,
      },
      requiredCapability: 'approval/vp',
      priority: input.amount > 5000 ? 'high' : 'medium',
    });

    steps.push({
      level: 'vp',
      approved: vpDecision.approved,
      reason: vpDecision.reason,
    });

    if (!vpDecision.approved) {
      const provenanceId = await ctx.provenance.log(
        withProvenanceContext(ctx, {
          type: 'approval:rejected',
          status: 'success',
          metadata: {
            input: { request_type: input.request_type, amount: input.amount },
            output: { rejected_at: 'vp', steps },
          },
        })
      );
      return { workflow_manifest_id: WORKFLOW_APPROVAL_ROUTING_MANIFEST.id, success: true, final_approved: false, steps, provenance_id: provenanceId };
    }

    // Level 3: CFO approval (if amount > $10000)
    if (input.amount > APPROVAL_THRESHOLDS.vp) {
      const cfoDecision = await ctx.escalate({
        reason: `CFO approval needed: ${input.request_type} - $${input.amount} (manager + VP approved)`,
        context: {
          request_type: input.request_type,
          amount: input.amount,
          description: input.description,
          level: 'cfo',
          prior_approvals: steps,
        },
        requiredCapability: 'approval/cfo',
        priority: 'high',
      });

      steps.push({
        level: 'cfo',
        approved: cfoDecision.approved,
        reason: cfoDecision.reason,
      });

      if (!cfoDecision.approved) {
        const provenanceId = await ctx.provenance.log(
          withProvenanceContext(ctx, {
            type: 'approval:rejected',
            status: 'success',
            metadata: {
              input: { request_type: input.request_type, amount: input.amount },
              output: { rejected_at: 'cfo', steps },
            },
          })
        );
        return { workflow_manifest_id: WORKFLOW_APPROVAL_ROUTING_MANIFEST.id, success: true, final_approved: false, steps, provenance_id: provenanceId };
      }
    }
  }

  // All required approvals obtained
  const provenanceId = await ctx.provenance.log(
    withProvenanceContext(ctx, {
      type: 'approval:approved',
      status: 'success',
      metadata: {
        input: { request_type: input.request_type, amount: input.amount },
        output: { steps, levels_required: steps.length },
      },
    })
  );

  return {
    workflow_manifest_id: WORKFLOW_APPROVAL_ROUTING_MANIFEST.id,
    success: true,
    final_approved: true,
    steps,
    provenance_id: provenanceId,
  };
};

export default handler({
  name: AGENT_ID,
  id: AGENT_ID,
  version: VERSION,
  capabilities: CAPABILITIES,
  manifest: {
    operations: [
      {
        name: 'request',
        description: 'Run multi-level approval flow: Manager -> VP -> CFO',
        paramsSchema: {
          request_type: { type: 'string', required: true, description: 'Type of request' },
          amount: { type: 'number', required: true, description: 'Amount' },
          description: { type: 'string', required: true, description: 'Request description' },
          requester_id: { type: 'string', description: 'Requester identifier' },
        },
        resultKind: 'agent.multi-level-approval.result',
      },
    ],
  },
  execute,
});