system-integration

/**
 * System Integration Agent - Production Reference Agent
 *
 * Canon alignment: KB 105
 * Demonstrates: ctx.credentials, ctx.queue, error recovery, ctx.files.delete()
 *
 * Real use case: Sync data between CRM, billing, support systems.
 * Uses secrets for API keys, queue for async jobs, handles errors.
 */

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

export const AGENT_ID = 'system-integration';
export const VERSION = '1.0.0';
export const CAPABILITIES = ['integration/sync'];

export interface SystemIntegrationInput {
  source_system: string;
  target_system: string;
  sync_type: 'full' | 'incremental';
}

export interface SystemIntegrationOutput {
  success: boolean;
  records_synced: number;
  errors: string[];
  job_id: string;
  provenance_id: string;
}

const execute = async (
  ctx: ExecutionContext,
  input: SystemIntegrationInput
): Promise<SystemIntegrationOutput> => {
  ctx.log.info('Starting system integration', {
    source: input.source_system,
    target: input.target_system,
  });

  const errors: string[] = [];

  // Get API credentials (ctx.credentials)
  let sourceKey: string;
  let targetKey: string;
  try {
    sourceKey = await ctx.credentials.get(`${input.source_system}_API_KEY`);
  } catch {
    sourceKey = '';
    errors.push(`Missing secret: ${input.source_system}_API_KEY`);
  }
  try {
    targetKey = await ctx.credentials.get(`${input.target_system}_API_KEY`);
  } catch {
    targetKey = '';
    errors.push(`Missing secret: ${input.target_system}_API_KEY`);
  }

  // Enqueue sync job (ctx.queue)
  const jobId = await ctx.queue.enqueue('integration:sync', {
    source_system: input.source_system,
    target_system: input.target_system,
    sync_type: input.sync_type,
    has_source_key: !!sourceKey,
    has_target_key: !!targetKey,
  });

  // Check job status (ctx.queue.status)
  const status = await ctx.queue.status(jobId);

  // Clean up temp files (ctx.files.delete)
  try {
    await ctx.files.delete(`temp/sync-${input.source_system}-${input.target_system}.json`);
  } catch {
    // File may not exist, that's fine
  }

  // Simulate record sync count
  const recordsSynced = errors.length === 0 ? 42 : 0;

  const provenanceId = await ctx.provenance.log(
    withProvenanceContext(ctx, {
      type: 'integration:sync_complete',
      status: 'success',
      metadata: {
        input: { source: input.source_system, target: input.target_system },
        output: { records_synced: recordsSynced, error_count: errors.length, job_state: status.state },
      },
    })
  );

  return {
    success: errors.length === 0,
    records_synced: recordsSynced,
    errors,
    job_id: jobId,
    provenance_id: provenanceId,
  };
};

export default handler({
  name: AGENT_ID,
  id: AGENT_ID,
  version: VERSION,
  capabilities: CAPABILITIES,
  manifest: {
    operations: [
      {
        name: 'sync',
        description: 'Sync data between source and target systems (full or incremental)',
        paramsSchema: {
          source_system: { type: 'string', required: true, description: 'Source system identifier' },
          target_system: { type: 'string', required: true, description: 'Target system identifier' },
          sync_type: { type: 'string', required: true, description: 'full | incremental' },
        },
        resultKind: 'agent.system-integration.result',
      },
    ],
  },
  execute,
});