Skip to main content
back to projects

Starling

event-sourced agent runtime for go. every run is an append-only, hash-chained event log — replayable, tamper-evident, resumable.

GoLLMEvent Sourcing
sourcelive

the starling landing page — every run as a typed, hash-chained event log with replay, divergence, and a merkle root committed at the end

Starling is an event-sourced agent runtime for Go. The pitch: every meaningful action an agent takes — prompts, model chunks, tool calls, budget decisions, terminal state — is committed to an append-only event log. The log is hash-chained as it's written and sealed with a Merkle root over the whole run. The log is the source of truth; RunResult is just a convenience derived from it.

Related writing: event sourcing and why it's perfect for agents.

That one decision is what gives you everything else.

why this matters

Agents fail in production in vague ways. A tool drifts, a model version ships a quiet change, a prompt cascades through a long chain of calls. By the time you notice, all you have is a stack trace and "it worked yesterday."

Treating the run as an event log closes that loop:

  • Replay is reading the log back through the same agent wiring and byte-comparing each re-emitted event. The first mismatch is a structured replay.Divergence pointing at the exact event that didn't reproduce — sequence, kind, expected kind, class, reason.
  • Resume is appending to a chain that didn't reach a terminal event. The hash chain enforces that nothing was lost in the gap.
  • Audit is the Merkle root on the terminal event committing to every leaf — tampering with any earlier event invalidates the commitment.
  • Cost control, observability, the inspector, replay tests — all of them are projections of the same event stream.

If you've worked with event sourcing before, this should sound familiar. If you've shipped LLM agents before, you know what it costs to not have this.

the starling inspector — every event in a recorded run, the run's chain root, and the live/valid status next to a per-event detail panel

what's in the box

  • Event log backends: in-memory, SQLite, and Postgres, with schema migration and validation helpers
  • Provider adapters: OpenAI-compatible APIs, Anthropic, Gemini, Amazon Bedrock, OpenRouter
  • MCP tools: stdio subprocess and streamable HTTP clients, backed by the official Go MCP SDK
  • Tool safety: retries, transient error classification, typed tool errors, max output caps, replay-safe side effects
  • Hermetic tests: starlingtest ships a scripted provider and replay assertions so agent tests run without ever calling an LLM
  • Inspector: a dependency-free browser UI for stepping through a recording and watching the replay diverge live
  • Observability: metrics wrappers, OpenTelemetry-friendly examples, and opt-in structured slog output

the starling docs site — quickstart, concepts, build guides, replay-driven tests, inspector reference

status

Beta. Pinned tags, not main — breaking changes are allowed between beta cuts. v0.1.0-beta.1 is on Go modules. Quickstart and full reference docs live at starling.jerkeyray.com.