Returns Processor

An e-commerce returns processing pipeline that handles inbound return requests end-to-end: validates against order data and return policy, inspects product condition, decides disposition, processes refunds, updates inventory, and analyzes return patterns for product quality improvement.

• Multi-agent pipeline — 6 specialized agents with distinct roles
• Decision contracts — Structured disposition decisions with condition grade and fraud score
• Fraud detection — Weighted signal scoring with configurable escalation threshold
• Idempotent inventory — Safe to re-run; duplicate returns are skipped automatically
• Scheduled batch processing — Daily batch runs + weekly quality analytics
• Model variety — Haiku for fast I/O tasks, Sonnet for analysis, Opus for high-stakes decisions

# 1. Start the AO daemon
ao daemon start --autonomous

# 2. Process a single return request
ao queue enqueue \
  --title "Process Return RET-2026-0001" \
  --description "Process return request RET-2026-0001 from data/return-requests/" \
  --workflow-ref process-return

# 3. Watch it run
ao daemon stream --pretty

# 4. Check results
ls output/refunds/
ls output/inventory-adjustments/
ls output/reports/

Processes a single return request end-to-end.

validate-return-request (script)
  → intake-assessment (intake-validator)
  → inspect-condition (condition-inspector)
  → decide-disposition (disposition-decider) ──rework──→ inspect-condition
       │                                      ──fail───→ escalate-to-human
       ↓ advance
  → calculate-refund (refund-calculator)
  → update-inventory (script)
  → generate-return-report (pattern-analyst)

Scans all pending returns, validates in batch, processes dispositions, generates daily KPIs. Runs daily at 06:00 UTC.

Aggregates weekly return data, analyzes patterns, generates quality improvement report. Runs every Monday at 07:00 UTC.

returns-processor/
├── config/
│   ├── return-policy.yaml        # Return windows, restocking fees, condition grades
│   ├── refund-rules.yaml         # Refund types (full/partial/store_credit/deny)
│   ├── fraud-signals.yaml        # Fraud signal weights and escalation threshold
│   └── product-categories.yaml  # Category-specific rules by SKU prefix
├── data/
│   ├── orders/                   # Order records for validation
│   ├── return-requests/          # Pending return request JSONs
│   ├── inventory/                # Current inventory state
│   ├── inspection-notes/         # Agent-written intake and condition assessments
│   └── processed/                # Completed return records
├── output/
│   ├── refunds/                  # Refund records with exact amounts
│   ├── inventory-adjustments/   # Per-return inventory change records
│   ├── reports/                  # Daily KPI and weekly quality reports
│   ├── escalations/              # Fraud/ambiguous cases for human review
│   └── quality-feedback/         # Product improvement recommendations
└── scripts/
    ├── validate-return-request.sh
    ├── update-inventory.sh
    └── scan-pending-returns.sh

The disposition-decider scores each return against weighted fraud signals:

Returns with a combined fraud score > 0.7 are escalated to human review.

This example uses only:

• @modelcontextprotocol/server-filesystem — local file access
• @modelcontextprotocol/server-sequential-thinking — structured reasoning

No external API keys needed.

• Decision contracts with structured required fields (disposition, condition_grade, fraud_score)
• Phase routing with rework loops (re-inspect on ambiguous condition) and fail paths (fraud escalation)
• Command phases for shell-based validation, inventory updates, and batch scanning
• Scheduled workflows via cron (daily batch + weekly analytics)
• Model selection — right-sizing: Haiku for deterministic tasks, Sonnet for analysis, Opus for high-stakes judgment
• Sequential-thinking MCP for fraud signal reasoning in the disposition phase