Skip to content
← all systems

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

Research Agent Runtime is an execution platform for research agents built around a tick-based state machine. You give it a question; a deterministic planner turns it into an ordered plan - clarify, research, analyze, synthesize, review, report - and the runtime advances one step per tick, recording status, duration, retries, token usage, and estimated cost at every step. Runs halt at a human review gate before the final report, and the whole engine runs as a keyless local demo or against real Claude and Supabase by swapping two adapters.

// 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

▸ tick-based runtime · one step per tick

  1. Question

    The research question to answer

  2. Plan

    Deterministic planner orders the run

  3. Research

    Gather sources per the plan

  4. Analyze

    Assess and structure the findings

  5. Synthesize

    Draft summary, findings, and risks

  6. Human reviewcontrol point

    Approve to report; reject with notes to fail the run

  7. Report

    Summary, findings, risks, recommendations, open questions

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