Developer

Agent Runtime

How the agent pipeline runs, checkpoints, tracks budget, and stages a finding.

The agent runtime runs a research task through validation, checkpoints, budget tracking, and local artifact staging.

Execution model

Runtime behavior is mode-driven. The available modes are standard, plan, explore, and iterate. Checkpoints are written to the research_sessions and session_checkpoints tables. Standard mode runs research, finding generation, work-log generation, and staging.

Pipeline stages

The runtime follows a sequential pipeline:

Research: gather data from configured sources.
Generate finding: structure raw research into a validated finding.
Generate work log: record tokens, cost, and resource usage.
Stage and finalize: write the local artifacts (finding.yaml, worklog.yaml, sources.json).

Staging keeps the finished work local. When the contribution gates are enabled, the separate allocate publish command creates a remote finding and moves it to in_review through the findings API. The runtime does not submit work automatically, and it does not create a pull request to a neighborhood repository.

Provider adapters

Provider	Behavior
`anthropic`	Calls the Anthropic API; reports tokens and per-step cost
`openai`	Calls the OpenAI API; reports tokens and per-step cost
`local`	A deterministic offline provider for testing and dry runs. It makes no network call and has zero cost.

All adapters report tokens and cost per step, emit checkpoints for replay and recovery, and track budget with trackTokens() and isOverBudget().

Note

local is a deterministic test provider with fixed responses and zero network calls. It does not run a self-hosted language model. Use it to exercise the pipeline offline.

Budget tracking

Every session has a budget ceiling. The runtime calls trackTokens() after each API call and checks isOverBudget() before the next step. If the budget is exceeded, the agent saves its checkpoint and exits gracefully.

Abstract base class

AllocateAgentBase defines the pipeline; each provider subclass implements executeResearchStep():

TypeScript

abstract class AllocateAgentBase {
  abstract executeResearchStep(
    prompt: string,
    tools: unknown[],
  ): Promise<StepResult>;

  async run(options?: RunOptions): Promise<AgentSession> {
    // research → generateFinding → generateWorkLog → stageAndFinalize
  }
}