surplus.ai · migration brief

Parallel Agent Execution

Same agent definitions. Same AgentRun runtime. Parallel orchestration layer on top.

Phase 1 Complete
Section 01

Before vs After Architecture

Before: Sequential

one agent at a time
defineAgent()
↓
AgentSpec
↓
AgentRun
↓
Agent 1 → Agent 2 → Agent 3
✓ Proven runtime (retry + quality)
✓ Partial recovery on failure
✗ Sequential only — N agents = N × time

After: Parallel

same AgentRun + orchestration layer
defineAgent()
↓
AgentSpec
↓
parallelAgents.ts
↓
AgentRun × N (p-limit concurrency)
↓
Promise.allSettled → collect results
✓ Same AgentRun (retry + quality kept)
✓ Concurrent execution with p-limit
✓ Partial failures don't kill batch

Key insight: No runtime replacement. AgentRun stays as the proven execution engine. The parallel layer is purely additive — it spawns multiple AgentRun instances concurrently, controlled by p-limit and collected via Promise.allSettled.

Section 02

Live Test: OTIV Alternative Analysis

Full pipeline test analyzing alternatives to OTIV.ONE (AI-powered shunting camera for rail yards).

PHASE 1 Discovery — 41.1s
🏭 Bosch Rail Safety System
alternative_product
Sensor-based safety and driver assistance for rail vehicles. Radar + camera fusion with obstacle detection.
📹 Fixed Ground-Based CCTV Monitoring
process
Static CCTV cameras installed at fixed points in the rail yard. Lower cost, no AI, requires human monitoring.
🚂 Wabtec Train Sentry
alternative_product
Intelligent locomotive safety system with speed optimization and yard management integration.
PHASE 2 Parallel Enrichment — 83.1s (3 concurrent)
Alternative Duration Tokens Status
Bosch Rail Safety System 63.4s 185,088 ✓ Complete
Fixed Ground-Based CCTV 53.3s 122,461 ✓ Complete
Wabtec Train Sentry 83.1s 215,104 ✓ Complete
⚡ All 3 ran simultaneously. Wall time = slowest task (83s), not sum (200s). 2.4× speedup.
SEQUENTIAL (BEFORE)
~200s
63 + 53 + 83 = sum of all tasks
PARALLEL (AFTER)
83s
max of concurrent batch
Section 03

The Real Win: Parallel Execution

⬤ Sequential — one at a time
Bosch
63s
CCTV
53s
Wabtec
83s
~200s total wall time (sum)
⬤ Parallel — AgentRun + p-limit(3)
Bosch 63s
CCTV 53s
Wabtec 83s
83s total wall time (max of concurrent)
↑ 2.4× speedup (real measurement)
🛡️

Promise.allSettled

Partial failures don't kill the batch. If Alt 3 times out, you still get results for 1, 2, 4, and 5. Each enrichment is independent, failures are logged and skipped gracefully.

Section 04

Files Changed

.ts
lib/ai/parallelAgents.ts
Parallel orchestration: spawns multiple AgentRun instances with p-limit concurrency + Promise.allSettled
160 lines
.ts
scripts/test-parallel-agentrun.ts
Full pipeline test: discovery → parallel enrichment with real OTIV data
215 lines
.ts
lib/ai/TLARunner.ts
ToolLoopAgent adapter (experimental, for future SDK alignment)
162 lines
.ts
scripts/test-tla.ts + test-parallel.ts
Test harnesses for TLA runtime path
382 lines
✓ 0 existing files modified — purely additive
Section 05

What's Next

1

Parallel Orchestration Layer

Complete — parallelAgents.ts with AgentRun, tested with OTIV (2.4× speedup)

2

API Route Integration

Wire parallel execution into existing agent API routes

3

Observability

Parent-child trace IDs, timing waterfall, per-task metrics

4

More Parallel Workflows

Competitor deep-dives, value driver analysis, price model generation — all parallelizable