---

id: agent-runtime kind: architecture title: Agent Runtime status: active depends_on:

• consumer-agents
• work-queue
• data-model

---

Agent Runtime #

Agents should consume Charter's Jazz project graph, not scrape the filesystem independently in every conversation.

The runtime turns registered consumers and project events into bounded packets and inspectable runs.

Context graph #

Each consumer can maintain an attention graph over the spec database:

• document nodes.
• document version nodes.
• heading nodes.
• span and comment nodes.
• dependency edges.
• prompt-document edges.
• project event feed edges.
• durable work-item edges.
• prior packet/request/report edges.

The graph is not the coordination surface. It is an agent-specific attention structure over the Jazz-backed project graph.

Consumer cursors #

Agents need per-consumer cursors:

• last seen event feed entry id or timestamp.
• last seen document hash per subscribed document.
• prompt document versions used for the last packet.
• invalidated assumptions.
• buffered work items waiting for next active ping.
• recent failure/block reasons.

Immediate triggers should be reserved for high-priority events. Most spec deltas should accumulate as queued work items until the next active turn, heartbeat, or explicit work request.

Context packets #

When a consumer wakes for spec work, the runtime should hand it a packet:

• queued or claimed work items.
• source event ids.
• changed documents.
• affected spans/comments.
• prompt documents and versions.
• relevant prior documents.
• relevant prior packets/reports when requested.
• invalidated assumptions.
• authority class of each change.
• requested action, if any.
• output contract.

This prevents the old failure mode where chat history becomes the de facto requirements store and every agent gets a different ghost version of the project.

Prompt composition #

Prompts are spec documents. A consumer can be composed from one or more prompt documents plus runner configuration.

When a prompt document changes, the runtime should be able to:

• record the prompt document event.
• identify consumers that depend on it.
• invalidate cached packets or cursors.
• create review work if the change is actionable.
• include prompt version ids in future packets.

This makes agent behavior versioned and inspectable.

Agent write path #

Agent outputs should separate:

1. observation: what changed or what is inconsistent.
2. proposal: a concrete patch, plan, comment, or follow-up work item.
3. application: accepted write to Markdown, database rows, code, or another target.

Proposal and application are different authority classes. Collapsing them is how helpful systems become tiny bureaucratic coups.

Outcome contract #

A consumer run must report one of:

• seen: observed and chose no action.
• done: completed the requested work.
• failed: tried and failed.
• blocked: needs external input or missing authority.
• ignored: intentionally not relevant.

The outcome updates the request, linked work items, and event stream when the outcome matters to future consumers.

Reasoning and activity traces #

The runtime may capture selected agent activity or reasoning traces, but only as explicit activity records.

Useful examples:

• a consumer chose no-op because the document change was formatting only.
• a consumer blocked because the packet lacked required context.
• a consumer stopped itself because a reasoning trace matched a rule.
• a consumer created a follow-up work item from an internal diagnostic.

The goal is not to stream every thought into the database. The goal is to preserve enough activity for debugging, provenance, and future consumers.