Research Agent Runtime
Research-agent execution platform built around a tick-based state machine with a human review gate.
tick-based runtime · HITL review gate
- role
- Architect and sole engineer
- stack
- Next.js 16 · TypeScript strict · Zod · Claude SDK · Supabase
- status
- oss
// 01 - PROBLEM
Agent runtimes fail in the unglamorous parts: partial failure, retries, cost accounting, and knowing where a run died. This platform is built to show those parts working - a runtime that survives failure and answers what a run cost, how long it took, and where it stopped.
// 02 - APPROACH
- A deterministic planner decomposes a question into an ordered plan: clarify, research, analyze, synthesize, review, report.
- A tick-based state machine advances runs one step at a time with per-step retries and timestamps.
- Runs halt at a review gate: approve to generate the report, reject with notes to fail the run.
- Structured final report: summary, findings, risks, recommendations, open questions.
// 03 - ARCHITECTURE
questionplanresearchanalyzesynthesizehuman reviewreport
- Two adapter seams: Model and Storage
- The same engine runs a keyless local demo (mock model + JSON file) or real Claude + Supabase, selected by environment variables. Nothing above the seams changes.
- Tick-based advancement over long-running jobs
- One step per tick makes every state transition observable and resumable - a run can crash mid-flight and continue where it stopped.
// 04 - PRODUCTION-GRADE
- Per-step status, duration, retries, token usage, and estimated cost
- Structured logging with a live log console
- Human-in-the-loop gate before irreversible output
- Zero-configuration demo mode; production mode is a config change
// 05 - ARTIFACTS