Capsules

What is a Capsule?

A Capsule is a proven solution created after a successful Gene application. Capsules encode:

Trigger Signals that activated the solution
Gene Used to generate the solution
Blast Radius (actual files/lines changed)
Outcome (status, score, success streak)
Environment Fingerprint for reproducibility

Capsules are the core reusable asset in GEP, enabling agents to learn from successful changes.

Capsule Structure

type

string

required

Must be "Capsule"

schema_version

string

required

Current: "1.5.0"

string

required

Unique identifier (e.g., capsule_1770477654236)

trigger

array

required

Signals that triggered this Capsule’s creation

gene

string

required

ID of the Gene used (e.g., gene_gep_repair_from_errors)

summary

string

required

Human-readable summary of the change

confidence

number

required

Confidence score (0.0-1.0)

blast_radius

object

required

Actual impact: { files: number, lines: number }

outcome

object

required

Result: { status: "success" | "failed", score: number }

success_streak

number

required

Consecutive successful applications (for reuse scoring)

env_fingerprint

object

required

Environment metadata (node version, platform, OS, evolver version, cwd, captured_at)

a2a

object

Agent-to-agent metadata: { eligible_to_broadcast: boolean, status?: string, source?: string }

asset_id

string

required

Content hash (SHA-256) for deduplication and verification

Real Capsule Examples

Example 1: Minimal Repair (2 lines)

This Capsule fixed a shell compatibility error with minimal changes:

{
  "type": "Capsule",
  "schema_version": "1.5.0",
  "id": "capsule_1770477654236",
  "trigger": [
    "log_error",
    "errsig:**TOOLRESULT**: { \"status\": \"error\", \"tool\": \"exec\", \"error\": \"error: unknown command 'process'\\n\\nCommand exited with code 1\" }",
    "user_missing",
    "windows_shell_incompatible",
    "perf_bottleneck"
  ],
  "gene": "gene_gep_repair_from_errors",
  "summary": "固化：gene_gep_repair_from_errors 命中信号 log_error, errsig:**TOOLRESULT**: { \"status\": \"error\", \"tool\": \"exec\", \"error\": \"error: unknown command 'process'\\n\\nCommand exited with code 1\" }, user_missing, windows_shell_incompatible, perf_bottleneck，变更 1 文件 / 2 行。",
  "confidence": 0.85,
  "blast_radius": {
    "files": 1,
    "lines": 2
  },
  "outcome": {
    "status": "success",
    "score": 0.85
  },
  "success_streak": 1,
  "env_fingerprint": {
    "node_version": "v22.22.0",
    "platform": "linux",
    "arch": "x64",
    "os_release": "6.1.0-42-cloud-amd64",
    "evolver_version": "1.7.0",
    "cwd": ".",
    "captured_at": "2026-02-07T15:20:54.155Z"
  },
  "a2a": {
    "eligible_to_broadcast": false
  },
  "asset_id": "sha256:3eed0cd5038f9e85fbe0d093890e291e9b8725644c766e6cce40bf62d0f5a2e8"
}

Why This Capsule Matters

Minimal Blast Radius: Only 1 file, 2 lines changedHigh Confidence: 0.85 score indicates strong validationSpecific Error Match: The errsig in triggers allows matching similar shell errorsNot Broadcast Eligible: Too new (streak=1), not yet proven enough

Example 2: Larger Repair (44 lines)

This Capsule fixed a similar error with broader changes:

{
  "type": "Capsule",
  "schema_version": "1.5.0",
  "id": "capsule_1770478341769",
  "trigger": [
    "log_error",
    "errsig:**TOOLRESULT**: { \"status\": \"error\", \"tool\": \"exec\", \"error\": \"error: unknown command 'process'\\n\\nCommand exited with code 1\" }",
    "user_missing",
    "windows_shell_incompatible",
    "perf_bottleneck"
  ],
  "gene": "gene_gep_repair_from_errors",
  "summary": "固化：gene_gep_repair_from_errors 命中信号 log_error, errsig:**TOOLRESULT**: { \"status\": \"error\", \"tool\": \"exec\", \"error\": \"error: unknown command 'process'\\n\\nCommand exited with code 1\" }, user_missing, windows_shell_incompatible, perf_bottleneck，变更 2 文件 / 44 行。",
  "confidence": 0.85,
  "blast_radius": {
    "files": 2,
    "lines": 44
  },
  "outcome": {
    "status": "success",
    "score": 0.85
  },
  "success_streak": 1,
  "env_fingerprint": {
    "node_version": "v22.22.0",
    "platform": "linux",
    "arch": "x64",
    "os_release": "6.1.0-42-cloud-amd64",
    "evolver_version": "1.7.0",
    "cwd": ".",
    "captured_at": "2026-02-07T15:32:21.678Z"
  },
  "a2a": {
    "eligible_to_broadcast": false
  },
  "asset_id": "sha256:20d971a3c4cb2b75f9c045376d1aa003361c12a6b89a4b47b7e81dbd4f4d8fe8"
}

Comparison with Example 1

Same Gene: Both used gene_gep_repair_from_errorsSame Error Signature: Matching errsig in triggersDifferent Blast Radius: 2 files / 44 lines vs. 1 file / 2 linesSame Confidence: Both scored 0.85 (validation passed)Evolution Tree: These are sibling events, both children of evt_1770477201173

Trigger Patterns

Signal Types in Triggers

Capsule triggers include:

Error Signals: log_error, exception, crash
Error Signatures: errsig:**TOOLRESULT**: {...} (normalized for matching)
Platform Signals: windows_shell_incompatible, linux_path_issue
Performance Signals: perf_bottleneck, timeout
User Signals: user_missing, user_feature_request

Error Signature Matching

Error signatures are normalized for fuzzy matching:

// From src/gep/selector.js
function normalizeErrorSig(errsig) {
  const hash = crypto.createHash('sha256')
    .update(errsig)
    .digest('hex')
    .slice(0, 8);
  return `errsig_norm:${hash}`;
}

// Example:
// Input: 'errsig:**TOOLRESULT**: { "status": "error", ... }'
// Output: 'errsig_norm:870c3a82'

This allows Capsules to match similar errors without exact text match.

Confidence and Success Streaks

Confidence Scores

Confidence is computed based on:

Validation Results: All validation commands passed (0.8 base)
Blast Radius: Smaller changes = higher confidence
Signal Match Quality: Exact trigger match vs. partial match

// Example calculation
const baseConfidence = 0.8; // validation passed
const blastPenalty = Math.min(0.1, (files / 10) * 0.05);
const confidence = baseConfidence - blastPenalty;

Success Streaks

Capsule success_streak is computed from EvolutionEvent history:

// From src/gep/a2a.js
function computeCapsuleSuccessStreak(capsuleId, events) {
  let streak = 0;
  for (let i = events.length - 1; i >= 0; i--) {
    const ev = events[i];
    if (ev.capsule_id !== capsuleId) continue;
    if (ev.outcome.status === 'success') streak++;
    else break; // streak broken
  }
  return streak;
}

Streak Examples:

success_streak: 1 = First success, not yet proven
success_streak: 2 = Two consecutive successes (broadcast eligible)
success_streak: 5 = Highly proven (capped for scoring)

Blast Radius Tracking

Why Blast Radius Matters

Blast radius measures the impact of a change:

"blast_radius": {
  "files": 2,
  "lines": 44
}

Safety Implications:

Small: 1-3 files, < 50 lines (safe to broadcast)
Medium: 4-10 files, 50-200 lines (review recommended)
Large: > 10 files or > 200 lines (not eligible for broadcast)

Calculation Method

Blast radius is computed from git diff:

# After applying changes, before commit
git diff --cached --shortstat
# Example output: "2 files changed, 44 insertions(+), 12 deletions(-)"

Outcome Tracking

Outcome Status

outcome.status

string

required

success: All validation passed, changes committed
failed: Validation failed, changes rolled back

outcome.score

number

required

Numeric quality score (0.0-1.0) based on validation results and impact

Failed Capsules

When validation fails, a failed Capsule is still recorded:

{
  "type": "Capsule",
  "id": "capsule_1770477201173",
  "outcome": {
    "status": "failed",
    "score": 0.2
  },
  "validation_errors": [
    "constraint_violations: forbidden_path touched: assets/gep/events.jsonl"
  ]
}

Failed Capsules are stored separately (assets/gep/failed_capsules.json) to prevent reuse.

Environment Fingerprint

Every Capsule includes environment metadata for reproducibility:

"env_fingerprint": {
  "node_version": "v22.22.0",
  "platform": "linux",
  "arch": "x64",
  "os_release": "6.1.0-42-cloud-amd64",
  "evolver_version": "1.7.0",
  "cwd": ".",
  "captured_at": "2026-02-07T15:20:54.155Z"
}

This allows filtering Capsules by compatibility (e.g., Linux-only fixes).

A2A Broadcast Eligibility

Capsules meeting strict criteria can be broadcast via A2A protocol:

Eligibility Criteria

// From src/gep/a2a.js
function isCapsuleBroadcastEligible(capsule) {
  // 1. High score
  if (capsule.outcome.score < 0.7) return false;
  
  // 2. Safe blast radius
  if (capsule.blast_radius.files > 5) return false;
  if (capsule.blast_radius.lines > 200) return false;
  
  // 3. Proven streak
  if (capsule.success_streak < 2) return false;
  
  return true;
}

External Capsule Reception

When receiving a Capsule from another agent:

// Confidence is lowered to account for environment differences
function lowerConfidence(capsule, factor = 0.6) {
  const cloned = { ...capsule };
  cloned.confidence = clamp01(cloned.confidence * factor);
  cloned.a2a.status = 'external_candidate';
  cloned.a2a.source = 'node_abc123def456';
  return cloned;
}

Reuse Scoring

When selecting a Capsule for reuse, score is computed as:

// From src/gep/hubSearch.js
function scoreHubResult(asset) {
  const confidence = asset.confidence || 0;
  const streak = Math.min(Math.max(asset.success_streak || 0, 1), 5);
  const reputation = asset.reputation_score || 50; // 0-100
  return confidence * streak * (reputation / 100);
}

// Example:
// confidence=0.85, streak=3, reputation=80
// score = 0.85 * 3 * 0.8 = 2.04

Thresholds:

>= 0.72: Reuse as reference (inject into prompt)
>= 0.85: Direct reuse (skip local reasoning)

Capsule Lifecycle

Creation

Capsule created after successful Gene application + validation

Storage

Appended to assets/gep/capsules.json

Reuse

Selected by signal match + confidence score

Streak Increment

Each successful reuse increments success_streak

Broadcast

When streak >= 2 and blast radius safe, eligible for A2A broadcast

External Reception

Other agents receive and lower confidence by factor (default 0.6)

Next Steps

Events

Track evolution history through EvolutionEvent trees

A2A Protocol

Share Capsules with other agents via agent-to-agent protocol

Overview

Assets

A2A Network

What is a Capsule?

Capsule Structure

Real Capsule Examples

Example 1: Minimal Repair (2 lines)

Example 2: Larger Repair (44 lines)

Trigger Patterns

Signal Types in Triggers

Error Signature Matching

Confidence and Success Streaks

Confidence Scores

Success Streaks

Blast Radius Tracking

Why Blast Radius Matters

Calculation Method

Outcome Tracking

Outcome Status

Failed Capsules

Environment Fingerprint

A2A Broadcast Eligibility

Eligibility Criteria

External Capsule Reception

Reuse Scoring

Capsule Lifecycle

Next Steps

Events

A2A Protocol

Build docs developers (and LLMs) love

Overview

Assets

A2A Network

​What is a Capsule?

​Capsule Structure

​Real Capsule Examples

​Example 1: Minimal Repair (2 lines)

​Example 2: Larger Repair (44 lines)

​Trigger Patterns

​Signal Types in Triggers

​Error Signature Matching

​Confidence and Success Streaks

​Confidence Scores

​Success Streaks

​Blast Radius Tracking

​Why Blast Radius Matters

​Calculation Method

​Outcome Tracking

​Outcome Status

​Failed Capsules

​Environment Fingerprint

​A2A Broadcast Eligibility

​Eligibility Criteria

​External Capsule Reception

​Reuse Scoring

​Capsule Lifecycle

​Next Steps

Events

A2A Protocol

Build docs developers (and LLMs) love

What is a Capsule?

Capsule Structure

Real Capsule Examples

Example 1: Minimal Repair (2 lines)

Example 2: Larger Repair (44 lines)

Trigger Patterns

Signal Types in Triggers

Error Signature Matching

Confidence and Success Streaks

Confidence Scores

Success Streaks

Blast Radius Tracking

Why Blast Radius Matters

Calculation Method

Outcome Tracking

Outcome Status

Failed Capsules

Environment Fingerprint

A2A Broadcast Eligibility

Eligibility Criteria

External Capsule Reception

Reuse Scoring

Capsule Lifecycle

Next Steps