[AI-05] ACP choreography (Team Alpha)

{
  "code": "```typescript\n// src/lib/acp-agents.ts\n// EN: ACP (Agent Communication Protocol) module for buyer/seller marketplace agents\n// VI: Module ACP (Giao thức Giao tiếp Đại lý) cho các đại lý mua/bán trên sàn giao dịch\n// ES: Módulo ACP (Protocolo de Comunicación de Agentes) para agentes comprador/vendedor del mercado\n// SPEC: AI-05 ACP Agent-to-Agent Choreography\n\nimport { z } from 'zod';\nimport { v4 as uuidv4 } from 'uuid';\n\n// ============================================================================\n// SECTION: Core ACP Enums and Schemas\n// EN: Define protocol vocabulary and message types for agent communication\n// VI: Định nghĩa từ vựng giao thức và các loại tin nhắn cho giao tiếp đại lý\n// ES: Definir vocabulario del protocolo y tipos de mensajes para comunicación de agentes\n// ============================================================================\n\n/**\n * EN: ACP Message Types defining the protocol vocabulary\n * VI: Các loại tin nhắn ACP định nghĩa từ vựng giao thức\n * ES: Tipos de mensajes ACP que definen el vocabulario del protocolo\n */\nexport const ACPMessageTypeEnum = z.enum([\n  'DISCOVERY_QUERY',      // EN: Buyer looking for items | VI: Người mua tìm kiếm sản phẩm | ES: Comprador buscando artículos\n  'DISCOVERY_RESPONSE',   // EN: Seller/Marketplace listing items | VI: Người bán/Sàn liệt kê sản phẩm | ES: Vendedor/Mercado listando artículos\n  'NEGOTIATION_OFFER',    // EN: Price/Term proposal | VI: Đề xuất giá/điều khoản | ES: Propuesta de precio/términos\n  'NEGOTIATION_COUNTER',  // EN: Counter-offer | VI: Đề xuất ngược | ES: Contraoferta\n  'AGREEMENT_COMMIT',     // EN: Formal acceptance | VI: Chấp nhận chính thức | ES: Aceptación formal\n  'AGREEMENT_REJECT',     // EN: Formal rejection | VI: Từ chối chính thức | ES: Rechazo formal\n  'TRANSACTION_FINALIZE', // EN: Payment/Escrow trigger | VI: Kích hoạt thanh toán/ký quỹ | ES: Activación de pago/depósito\n]);\n\nexport type ACPMessageType = z.infer<typeof ACPMessageTypeEnum>;\n\n/**\n * EN: Item Condition Enum for GarageSale marketplace\n * VI: Enum tình trạng sản phẩm cho sàn GarageSale\n * ES: Enum de condición del artículo para el mercado GarageSale\n */\nexport const ItemConditionEnum = z.enum([\n  'NEW',              // EN: Brand new, unused | VI: Hoàn toàn mới, chưa sử dụng | ES: Nuevo, sin usar\n  'LIKE_NEW',         // EN: Used but like new | VI: Đã qua sử dụng nhưng như mới | ES: Usado pero como nuevo\n  'GOOD',             // EN: Good condition | VI: Tình trạng tốt | ES: Buena condición\n  'FAIR',             // EN: Fair condition | VI: Tình trạng khá | ES: Condición aceptable\n  'POOR',             // EN: Poor condition | VI: Tình trạng kém | ES: Mala condición\n]);\n\nexport type ItemCondition = z.infer<typeof ItemConditionEnum>;\n\n/**\n * EN: Delivery Method Enum for local pickup vs shipping\n * VI: Enum phương thức giao hàng cho nhận tại chỗ và vận chuyển\n * ES: Enum de método de entrega para recogida local vs envío\n */\nexport const DeliveryMethodEnum = z.enum([\n  'LOCAL_PICKUP',     // EN: Buyer picks up locally | VI: Người mua nhận tại chỗ | ES: Recogida local por el comprador\n  'SHIPPING',         // EN: Seller ships to buyer | VI: Người bán gửi cho người mua | ES: Vendedor envía al comprador\n  'BOTH',             // EN: Either option available | VI: Cả hai tùy chọn | ES: Ambas opciones disponibles\n]);\n\nexport type DeliveryMethod = z.infer<typeof DeliveryMethodEnum>;\n\n/**\n * EN: Payment Method Enum for transaction handling\n * VI: Enum phương thức thanh toán cho xử lý giao dịch\n * ES: Enum de método de pago para manejo de transacciones\n */\nexport const PaymentMethodEnum = z.enum([\n  'CASH',             // EN: Cash payment | VI: Thanh toán tiền mặt | ES: Pago en efectivo\n  'ESCROW',           // EN: Platform escrow | VI: Ký quỹ nền tảng | ES: Depósito de plataforma\n  'CRYPTO',           // EN: Cryptocurrency | VI: Tiền điện tử | ES: Criptomoneda\n  'BANK_TRANSFER',    // EN: Direct bank transfer | VI: Chuyển khoản ngân hàng | ES: Transferencia bancaria\n]);\n\nexport type PaymentMethod = z.infer<typeof PaymentMethodEnum>;\n\n/**\n * EN: Agent State Enums for Buyer and Seller\n * VI: Enum trạng thái đại lý cho Người mua và Người bán\n * ES: Enums de estado del agente para Comprador y Vendedor\n */\nexport const BuyerStateEnum = z.enum([\n  'IDLE',               // EN: Not actively searching | VI: Không tích cực tìm kiếm | ES: No buscando activamente\n  'SEARCHING',          // EN: Looking for items | VI: Đang tìm kiếm sản phẩm | ES: Buscando artículos\n  'NEGOTIATING',        // EN: In negotiation | VI: Đang đàm phán | ES: En negociación\n  'AWAITING_DELIVERY',  // EN: Waiting for fulfillment | VI: Chờ giao hàng | ES: Esperando entrega\n]);\n\nexport const SellerStateEnum = z.enum([\n  'IDLE',       // EN: No active listings | VI: Không có danh sách hoạt động | ES: Sin listados activos\n  'LISTED',     // EN: Items available | VI: Sản phẩm có sẵn | ES: Artículos disponibles\n  'NEGOTIATING',// EN: In negotiation | VI: Đang đàm phán | ES: En negociación\n  'FULFILLING', // EN: Processing order | VI: Đang xử lý đơn hàng | ES: Procesando pedido\n]);\n\nexport const MarketplaceStateEnum = z.enum([\n  'IDLE',       // EN: Waiting for requests | VI: Chờ yêu cầu | ES: Esperando solicitudes\n  'MATCHING',   // EN: Finding matches | VI: Đang tìm kiếm kết quả phù hợp | ES: Buscando coincidencias\n  'ARBITRATING',// EN: Resolving disputes | VI: Giải quyết tranh chấp | ES: Resolviendo disputas\n]);\n\nexport const ChoreographyStateEnum = z.enum([\n  'INIT',                 // EN: Conversation not started | VI: Cuộc hội thoại chưa bắt đầu | ES: Conversación no iniciada\n  'DISCOVERY',            // EN: Discovery phase | VI: Giai đoạn khám phá | ES: Fase de descubrimiento\n  'NEGOTIATION',          // EN: Negotiation phase | VI: Giai đoạn đàm phán | ES: Fase de negociación\n  'AGREEMENT_PENDING',    // EN: Awaiting agreement | VI: Chờ thỏa thuận | ES: Esperando acuerdo\n  'AGREED',               // EN: Agreement reached | VI: Đã đạt thỏa thuận | ES: Acuerdo alcanzado\n  'REJECTED',             // EN: Agreement rejected | VI: Thỏa thuận bị từ chối | ES: Acuerdo rechazado\n  'FINALIZED',            // EN: Transaction complete | VI: Giao dịch hoàn tất | ES: Transacción completada\n  'EXPIRED',              // EN: Conversation timed out | VI: Cuộc hội thoại đã hết hạn | ES: Conversación expirada\n]);\n\nexport type BuyerState = z.infer<typeof BuyerStateEnum>;\nexport type SellerState = z.infer<typeof SellerStateEnum>;\nexport type MarketplaceState = z.infer<typeof MarketplaceStateEnum>;\nexport type ChoreographyState = z.infer<typeof ChoreographyStateEnum>;\n\n// ============================================================================\n// SECTION: Constants and Limits\n// EN: Define safe limits for numeric values to prevent overflow\n// VI: Định nghĩa giới hạn an toàn cho giá trị số để ngăn tràn số\n// ES: Definir límites seguros para valores numéricos para prevenir desbordamiento\n// ============================================================================\n\nconst MAX_PRICE = 1_000_000_000; // EN: 1 billion max | VI: Tối đa 1 tỷ | ES: Máximo 1 billón\nconst MAX_QUANTITY = 1_000_000;  // EN: 1 million max | VI: Tối đa 1 triệu | ES: Máximo 1 millón\nconst MAX_RATING = 5;            // EN: 5-star rating | VI: Đánh giá 5 sao | ES: Calificación de 5 estrellas\nconst MIN_RATING = 0;            // EN: Minimum rating | VI: Đánh giá tối thiểu | ES: Calificación mínima\n\n/**\n * EN: ACP Header Schema - metadata for every message\n * VI: Schema Header ACP - siêu dữ liệu cho mọi tin nhắn\n * ES: Esquema de encabezado ACP - metadatos para cada mensaje\n */\nexport const ACPHeaderSchema = z.object({\n  messageId: z.string().uuid(),\n  conversationId: z.string().uuid(),\n  senderId: z.string().trim().min(1),\n  receiverId: z.string().trim().min(1),\n  timestamp: z.number().positive().max(Number.MAX_SAFE_INTEGER),\n  type: ACPMessageTypeEnum,\n});\n\nexport type ACPHeader = z.infer<typeof ACPHeaderSchema>;\n\n// ============================================================================\n// SECTION: Payload Schemas for Different Message Types\n// EN: Type-specific payload validation for each message type\n// VI: Xác thực payload theo loại cho từng loại tin nhắn\n// ES: Validación de carga útil específica por tipo para cada tipo de mensaje\n// ============================================================================\n\n/**\n * EN: Discovery Query Payload - buyer search criteria\n * VI: Payload truy vấn khám phá - tiêu chí tìm kiếm của người mua\n * ES: Carga útil de consulta de descubrimiento - criterios de búsqueda del comprador\n */\nexport const DiscoveryQueryPayloadSchema = z.object({\n  keywords: z.array(z.string().trim().min(1)).min(1),\n  maxPrice: z.number().positive().max(MAX_PRICE).optional(),\n  minCondition: ItemConditionEnum.optional(),\n  preferredDelivery: DeliveryMethodEnum.optional(),\n  location: z.string().trim().min(1).optional(),\n});\n\nexport type DiscoveryQueryPayload = z.infer<typeof DiscoveryQueryPayloadSchema>;\n\n/**\n * EN: Discovery Response Payload - matching items from seller/marketplace\n * VI: Payload phản hồi khám phá - sản phẩm phù hợp từ người bán/sàn giao dịch\n * ES: Carga útil de respuesta de descubrimiento - artículos coincidentes del vendedor/mercado\n */\nexport const DiscoveryResponsePayloadSchema = z.object({\n  items: z.array(z.object({\n    itemId: z.string().trim().min(1),\n    name: z.string().trim().min(1),\n    price: z.number().positive().max(MAX_PRICE),\n    condition: ItemConditionEnum,\n    sellerId: z.string().trim().min(1),\n    sellerRating: z.number().min(MIN_RATING).max(MAX_RATING).optional(),\n  })),\n  totalMatches: z.number().int().nonnegative(),\n});\n\nexport type DiscoveryResponsePayload = z.infer<typeof DiscoveryResponsePayloadSchema>;\n\n/**\n * EN: Negotiation Offer/Counter Payload - price and terms proposal\n * VI: Payload đề xuất/phản đề đàm phán - đề xuất giá và điều khoản\n * ES: Carga útil de oferta/contraoferta de negociación - propuesta de precio y términos\n */\nexport const NegotiationPayloadSchema = z.object({\n  itemId: z.string().trim().min(1),\n  offeredPrice: z.number().positive().max(MAX_PRICE),\n  quantity: z.number().int().positive().max(MAX_QUANTITY),\n  deliveryMethod: DeliveryMethodEnum,\n  paymentMethod: PaymentMethodEnum,\n  roundNumber: z.number().int().positive().max(100), // EN: Max 100 rounds | VI: Tối đa 100 vòng | ES: Máximo 100 rondas\n  expiresAt: z.number().positive().max(Number.MAX_SAFE_INTEGER),\n  message: z.string().max(1000).optional(),\n});\n\nexport type NegotiationPayload = z.infer<typeof NegotiationPayloadSchema>;\n\n/**\n * EN: Agreement Payload - final terms of agreement or rejection reason\n * VI: Payload thỏa thuận - điều khoản cuối cùng hoặc lý do từ chối\n * ES: Carga útil de acuerdo - términos finales del acuerdo o razón de rechazo\n */\nexport const AgreementPayloadSchema = z.object({\n  itemId: z.string().trim().min(1),\n  finalPrice: z.number().positive().max(MAX_PRICE),\n  quantity: z.number().int().positive().max(MAX_QUANTITY),\n  deliveryMethod: DeliveryMethodEnum,\n  paymentMethod: PaymentMethodEnum,\n  rejectionReason: z.string().max(500).optional(),\n});\n\nexport type AgreementPayload = z.infer<typeof AgreementPayloadSchema>;\n\n/**\n * EN: Transaction Finalize Payload - payment and escrow details\n * VI: Payload hoàn tất giao dịch - chi tiết thanh toán và ký quỹ\n * ES: Carga útil de finalización de transacción - detalles de pago y depósito\n */\nexport const TransactionFinalizePayloadSchema = z.object({\n  itemId: z.string().trim().min(1),\n  transactionId: z.string().uuid(),\n  totalAmount: z.number().positive().max(MAX_PRICE),\n  paymentMethod: PaymentMethodEnum,\n  escrowAddress: z.string().trim().min(1).optional(),\n  paymentReference: z.string().trim().min(1).optional(),\n});\n\nexport type TransactionFinalizePayload = z.infer<typeof TransactionFinalizePayloadSchema>;\n\n/**\n * EN: Generic Payloa",
  "spec_id": "AI-05"
}