Packing Agent Executions

The core of ContextSubstrate is the Context Pack: an immutable, content-addressed snapshot of an AI agent's work. To move from a transient agent run to a reproducible record, you use the ctx pack command.

Overview

Packing takes a standard JSON execution log and formalizes it. During this process, ctx:

1. Deconstructs the log into granular components (prompts, inputs, tool outputs, and artifacts).
2. Deduplicates content by storing it in a local blob store (.ctx/objects).
3. Generates a canonical manifest that defines the execution's identity via a cryptographic hash.
4. Indexes the pack for future debugging, diffing, and replaying.

The Execution Log Format

To pack an execution, you must provide a JSON file following the ExecutionLog schema. This format captures the intent (prompts), the process (steps), and the results (outputs).

Sample execution.json

{
  "model": {
    "identifier": "gpt-4-turbo",
    "parameters": { "temperature": 0.7 }
  },
  "system_prompt": "You are a coding assistant.",
  "prompts": [
    { "role": "user", "content": "Refactor the main.go file to use interfaces." }
  ],
  "inputs": [
    { "name": "main.go", "content": "package main\n\nfunc main() { ... }" }
  ],
  "steps": [
    {
      "index": 0,
      "type": "tool_call",
      "tool": "read_file",
      "parameters": { "path": "main.go" },
      "output": "package main...",
      "deterministic": true
    }
  ],
  "outputs": [
    { "name": "refactored_main.go", "content": "package main\n\ntype Runner interface { ... }" }
  ],
  "environment": {
    "os": "linux",
    "runtime": "go1.22",
    "tool_versions": { "compiler": "v1.5.2" }
  }
}

Creating a Pack

Once you have your execution log, run the pack command:

ctx pack execution.json

Output:

ctx://8f3a2b1c4d5e...

The command returns a ctx:// URI. This hash is derived from the content of the manifest; if a single byte in the prompts or outputs changes, the hash will change, ensuring perfect provenance.

What happens during packing?

• Immutability: Once the pack is created and registered in .ctx/packs/, it cannot be modified.
• Content Addressing: If two different agent runs use the same 10MB input file, ctx only stores that file once in the object store.
• Environment Capture: The environment block ensures that when you or a teammate revisits this pack, you know the exact context in which the agent operated.

Viewing Packed Executions

After packing, you can verify the contents of the pack using the hash:

ctx show <hash>

This provides a human-readable summary of the model, the system prompts, and the sequence of steps taken. To see a chronological list of all packs in your current substrate, use:

ctx log

Best Practices for Packing

• Granular Steps: Ensure every tool call is recorded as a separate entry in the steps array. This allows ctx diff to pinpoint exactly where two agent runs diverged.
• Deterministic Flags: Mark tool outputs as deterministic: true only if they are guaranteed to return the same result (e.g., reading a static file). This helps the replay engine validate execution fidelity.
• Metadata: Use the model.parameters and environment.tool_versions fields liberally. They are critical for diagnosing "drift" when an agent's behavior changes despite identical prompts.