Bullets

Bullets are the atomic units of the Bullet Protocol. Every piece of agent capability (whether it's code to execute, advice on how to behave, knowledge to reference, or a workflow to orchestrate) is packaged as a self-contained, versioned, discoverable bullet.

The Four Primitives

The bullet system defines exactly four types of bullets, each serving a distinct purpose:

Guidance: Instructions in natural language. Operational advice that captures tactics, heuristics, and strategies like retry patterns, parsing tips, error handling, and stylistic preferences.
Script: Executable code. Implementations in Python, JavaScript, SQL, or any other language that a runtime can execute. Scripts are the only bullet type that accepts inputs.
Data: Immutable information with clear provenance, including facts fetched from external systems, deterministic transformations, cached results, uploaded files, and curated collections.
Plan: Declarative workflows that orchestrate multi-step processes. Plans are the only bullet type that references other bullets - they compose scripts, data, guidance, and other plans into workflows.

This is intended to be a minimal complete basis for expressing agent capabilities.

Anatomy of a Bullet

Every bullet, regardless of its type, follows a common structure with metadata and payload. The metadata enables discovery, quality ranking, and trust. The payload contains the actual implementation.

Here's a simplified example of a Guidance bullet:

# ====================
# .bullet.yaml - The bullet definition
# ====================
 
# Unique identifier following bullet:// URI scheme
# Format: bullet://namespace/uuid@semver
# UUID is 16 hex chars (64 bits) - sufficient for 100B+ bullets
id: bullet://example/a7f3c8e4d2b1f6a9@3.2.1
 
# Metadata: everything about the bullet
metadata:
  # One of: intent, script, guidance, data, plan
  type: guidance
  
  # Human-readable title for display and search
  title: Gmail API retry and backoff strategy
  
  # Version and provenance information
  version: 3.2.1
  created: 2025-11-10T12:00:00Z
 
  # Permissions: controls visibility and access
  permissions:
    visibility: public                # public | organization | private
    indexed: true                     # Include in global search index
    pii_risk: none                    # none | low | medium | high
    sensitivity: none                 # none | internal | confidential | restricted
    destructive_actions: none         # none | reversible | irreversible
    required_capabilities: []         # e.g., [network_access, file_write]
  
  # Contract: immutable guarantees that never change
  # Breaking these = create new bullet ID entirely, not new version
  contract:
    guarantees:
      - "Always uses exponential backoff for retries"
      - "Respects Retry-After headers"
      - "Fails fast on quota exhaustion"
      - "Never exceeds 5 retry attempts"
  
  # Discovery: everything needed to find, rank, and select bullets
  # Only applies if permissions.indexed = true
  
  # Discovery metadata enables finding this bullet
  discovery:
    # Semantic search inputs (concatenated to generate vector embeddings)
    embedding_hints:
      primary: "Gmail API exponential backoff and retry strategy"
      context: "Operational guidance for handling rate limits and errors when calling Gmail API"
      keywords: [gmail, api, retry, backoff, rate-limiting, error-handling]
    
    # Quality scores - THE KEY SELECTION CRITERIA
    # When 1000 bullets match your query, this is how you rank them
    quality:
      execution_count: 15234          # Times successfully executed in production
      success_rate: 0.98              # 98% success rate
      plan_references: 142            # How many plans reference this bullet
      
      # Evaluation: fuzzy assessment of quality and testing
      # Evaluations are approximate and evolving, not precise guarantees
      evaluation:
        score: 0.92                   # 0.0 to 1.0, approximate quality indicator
        confidence: high              # high | medium | low | untested
        notes: |
          Comprehensive guidance with correct distinction between retriable and 
          non-retriable errors. Exponential backoff strategy is sound. Minor: could 
          mention jitter to prevent thundering herd.
    
    # Freshness: real-world staleness and validity information
    freshness:
      # Validity window
      valid_from: 2025-11-10T00:00:00Z
      valid_until: 2026-01-01T00:00:00Z
      confidence: high                  # high | medium | low
      
      # What makes this stale/invalid
      invalidation: |
        May become stale when dependencies update, Gmail API changes, or security 
        advisories are published for underlying libraries.
 
# ====================
# Payload: the actual content (structure varies by type)
# ====================
 
# The payload structure is type-specific:
# - Guidance: natural language instructions (shown here)
# - Script: executable code
# - Data: the data itself
# - Plan: workflow steps that REFERENCE other bullets (the ONLY type that does)
 
payload:
  content: |
    When calling Gmail API endpoints, use exponential backoff starting at 1 second, 
    doubling on each retry, with a maximum of 5 attempts.
    
    On 429 rate limit responses, check for the Retry-After header and wait that 
    duration. If no header is present, use the exponential backoff schedule.
    
    For 403 quota exceeded errors, do NOT retry. Fail immediately with a clear 
    error message.

This structure separates the bullet into two logical parts:

Metadata: Everything about the bullet—discovery hints for search, quality scores for ranking, versioning, permissions, and composition information (for plans that reference other bullets).

Payload: The actual content. Structure varies by type.

This architecture enables bullets to be discovered at scale, composed into workflows, and continuously improved through evidence-based quality metrics.

Ephemeral Bullets

Most bullets created during execution are transient artifacts, not long-lived published packages. When the router resolves a placeholder, captures intermediate outputs, or fetches external data, it automatically creates ephemeral bullets with full metadata and payload structure. These are published immediately with visibility: private in the user's namespace, making them discoverable and reusable within that scope. Unlike curated bullets that are intentionally maintained for long-term ecosystem use, ephemeral bullets exist to satisfy immediate execution needs and may be garbage collected when no longer referenced.

Introduction Guidance