Skip to main content

Agent runner starter kit

This page is the practical starter kit for building a public-surface agent runner.

Product goal​

Ship a runner that can:

  • create or receive a session
  • inspect the tree
  • mutate paths and files
  • store workflow state
  • checkpoint before risk
  • request approval
  • commit or promote on success

Minimum architecture​

Use these layers:

  • your runner or orchestrator
  • the public HTTP API as control plane
  • optional Aether CLI only if local filesystem semantics are truly required

Core execution phases​

Phase 1: session acquisition​

Routes:

  • POST /v1/sessions
  • GET /v1/sessions/{sessionId}

Phase 2: discovery​

Route:

  • GET /v1/sessions/{sessionId}/manifest

Phase 3: mutation​

Routes you will likely need first:

  • POST /v1/sessions/{sessionId}/dirs
  • POST /v1/sessions/{sessionId}:rename
  • DELETE /v1/sessions/{sessionId}/files
  • POST /v1/sessions/{sessionId}/batch
  • POST /v1/sessions/{sessionId}/patchSegments

Phase 4: workflow state​

Routes:

  • session cache routes
  • bus publish route
  • annotations if reviewer-visible notes matter

Phase 5: recoverability​

Route:

  • POST /v1/sessions/{sessionId}/checkpoints

Phase 6: approval​

Routes:

  • POST /v1/sessions/{sessionId}/request-approval
  • approval grant/deny routes for the reviewer side

Phase 7: persistence​

Routes:

  • POST /v1/sessions/{sessionId}/commit
  • POST /v1/sources/{sourceId}/promoteSession

Suggested control loop​

  1. create or acquire session
  2. fetch manifest
  3. decide next mutation
  4. perform mutation
  5. publish progress or store derived state
  6. checkpoint if risk increased
  7. request approval if the next action needs it
  8. commit or promote only after the workflow allows it

Suggested route choices​

Start with:

  • simple path operations
  • batch for grouped actions
  • cache for structured state
  • bus for live progress

Only add:

  • patchSegments
  • POSIX locks
  • CAS extents

when the workflow really requires them.

Failure handling checklist​

Handle:

  • stale expected hash
  • approval denied
  • approval no longer pending
  • source job failure after promotion/import
  • missing session or missing source

First release checklist​

  • session create works
  • manifest read works
  • at least one mutation route works
  • cache or bus state works
  • checkpoint works
  • approval request works
  • commit works