Execution Ledger
Description
Section titled “Description”The Execution Ledger is a unified system of record for all agent activity. It binds together invocations, actors, artifacts, tool calls, cost signals, and arbitrary metadata into a single queryable store that can answer both operational and governance questions across the entire fleet.
Without a ledger, observability is local and ephemeral you can inspect a single run, but not correlate behavior, audit decisions, trace cost, or reconstruct the full history of a delivery. The ledger closes that gap.
What the Ledger Tracks
Section titled “What the Ledger Tracks”Invocations
Section titled “Invocations”Every agent instantiation produces an invocation record: which agent was spawned, from which pool configuration, under what trigger, at what time, and how it completed. Invocations are the primary nodes in the graph. Subagent spawning creates parent-child edges, making it possible to reconstruct full execution trees for any top-level task.
Actors
Section titled “Actors”An actor is any entity that initiates or participates in work: a human, an agent, an external service, or a webhook trigger. Actors are first-class nodes. Linking invocations to actors makes it possible to attribute behavior, apply policy, and answer questions like which actor authorized a change, which agent produced a given artifact, and which humans reviewed what.
Artifacts
Section titled “Artifacts”Artifacts are the outputs of work: code commits, pull requests, plans, summaries, evaluation results, files, or any other durable product of an invocation. Artifact nodes carry provenance edges back to the invocations that produced them and forward to any invocations that consumed them. This makes the ledger capable of full artifact lineage.
Tool Calls
Section titled “Tool Calls”Each tool call within an invocation is recorded as a timestamped edge: which tool was called, with what parameters (sanitized as appropriate), what it returned, and how long it took. This supports replay analysis, debugging, and identifying tool reliability problems across the fleet.
Cost Accounting
Section titled “Cost Accounting”Token usage, model provider, and model tier are captured per invocation and per tool call. This allows cost to be aggregated along any graph dimension: by actor, by task, by repository, by agent type, or by time window. Cost accountability is a core governance concern and the ledger is the enabling layer.
Arbitrary Metadata
Section titled “Arbitrary Metadata”The graph structure supports dynamically connected properties. Any node or edge can carry additional labels, tags, or key-value metadata without schema migration. This enables ad hoc classification, custom attribution, external system annotations, and experiment tagging. The schema is intentionally open at the edges.
Why a Graph
Section titled “Why a Graph”Relational and document stores model fixed entity shapes well but struggle with the cross-cutting, relationship-heavy queries that observability demands. A graph treats relationships as first-class: parent-child invocation chains, actor-to-artifact attribution, artifact-to-artifact lineage, and tag-to-node associations all become traversals rather than expensive joins or denormalized copies.
A hybrid approach graph for relationships and traversal, columnar or document store for high-volume event streams is an acceptable implementation strategy. The logical model is graph regardless of the physical storage mix.
Progressive Enrichment
Section titled “Progressive Enrichment”Not all systems that feed the ledger will support all data types. A minimal integration writes only invocation start and end events. A richer integration adds tool call edges. A full integration adds cost, actor identity, and artifact provenance.
The ledger is designed to be useful at any level of completeness. Sparse data is accepted. Missing relationships are represented as absent edges, not errors. As integrations mature, additional data is written into the existing graph, enriching the historical record rather than replacing it.
This progressive model also means the ledger can be introduced incrementally. Early runs produce partial records. Later runs fill in the gaps. No single integration partner needs to implement all dimensions before the system has value.
Loose Coupling
Section titled “Loose Coupling”The ledger is not an intrusive SDK that every agent harness must embed. It accepts data through an event interface a structured log stream, a message queue, a webhook endpoint, or a lightweight write API. The underlying storage technology is hidden behind that interface. Harnesses write events; the ledger ingests them.
This design has two benefits. First, the underlying graph store can be replaced or supplemented without changing the agents that produce data. Second, harnesses and tools that cannot integrate at all simply produce no records for that dimension, which the progressive enrichment model accommodates.
Related Concepts
Section titled “Related Concepts”- Agent - The runtime entity whose instantiations the ledger records.
- Agent Pool - Supplies the configuration context that shapes each invocation record.
- Controls - Governance and policy enforcement that the ledger provides evidence for.
- Operations and Governance - Describes the control plane that the ledger directly enables.
- Context - Some context types (user memory, system facts) may be sourced from or written back to the ledger.
- End-to-End Orchestration - The delivery flow whose state the ledger makes inspectable.