Module context 

AI Context Snapshot Definition

A ContextSnapshot is an optional static capture of the codebase and external resources that an agent observed when a Run began. Unlike the dynamic ContextPipeline (which accumulates frames during execution), a ContextSnapshot is a point-in-time record that does not change after creation.

Position in Lifecycle

 ⑤  Run ──snapshot──▶ ContextSnapshot (optional, static)
      │
      ├──▶ ContextPipeline (dynamic, via Plan.pipeline)
      │
      ▼
 ⑥  ToolInvocations ...

A ContextSnapshot is created at step ⑤ when the Run is initialized. It complements the ContextPipeline: the snapshot captures the initial state (what files, URLs, snippets the agent sees at start), while the pipeline tracks incremental context changes during execution.

Items

Each ContextItem has three layers:

• path — human-readable locator (repo path, URL, command, label).
• blob — Git blob hash pointing to the full content at capture time.
• preview — truncated text for quick display without reading the blob.

All item kinds use blob as the unified content reference:

Kind	path example	blob content
File	src/main.rs	Same blob in git tree (zero extra storage)
Url	https://docs.rs/...	Fetched page content stored as blob
Snippet	"design notes"	Snippet text stored as blob
Command	cargo test	Command output stored as blob
Image	screenshot.png	Image binary stored as blob

blob is Option because it may be None during the draft/collection phase; by the time the snapshot is finalized, items should have their blob set.

Blob Retention

Standard git gc only considers objects reachable from refs → commits → trees → blobs. A blob referenced solely by an AI object’s JSON payload is not reachable in git’s graph and will be pruned after gc.pruneExpire (default 2 weeks).

For File items this is not a concern — the blob is already reachable through the commit tree. For all other kinds, applications must choose a retention strategy:

Strategy	Pros	Cons
Ref anchoring (refs/ai/blobs/<hex>)	Simple, works with stock git	Ref namespace pollution
Orphan commit (refs/ai/uploads)	Standard reachability; packable	Extra commit/tree overhead
Keep pack (.keep marker)	Zero ref management	Must repack manually
Custom GC mark (scan AI objects)	Cleanest long-term	Requires custom gc

This library does not enforce any particular strategy — the consuming application is responsible for ensuring referenced blobs remain reachable.

Purpose

• Reproducibility: Given the same ContextSnapshot and Plan, an agent should produce equivalent results.
• Auditing: Reviewers can inspect exactly what context the agent had access to when making decisions.
• Content Deduplication: Using Git blob hashes means identical file content is stored only once, regardless of how many snapshots reference it.

Structs

ContextItem

A single input item within a ContextSnapshot.

ContextSnapshot

A static capture of the context an agent observed at Run start.

Enums

ContextItemKind

The kind of content a ContextItem represents.

SelectionStrategy

How the items in a ContextSnapshot were selected.