Capability marketplace protocol: cross-agent capability sharing

[dgenio]

Milestone: v0.3.0 | Tier: Creative Bet | Effort: Large

Problem

Each kernel instance has its own isolated registry. In multi-agent systems, there's no way for agents to:

• Discover capabilities offered by other agents/kernels
• Delegate tool execution to a remote kernel that has the right driver
• Share tool access securely across organizational boundaries

Multi-agent architectures (A2A protocol, agent swarms, microservice-based agents) need federated capability discovery without abandoning per-kernel security boundaries.

Proposed Change

1. Capability advertisement protocol

@dataclass
class CapabilityManifest:
    """Serializable advertisement of a kernel's available capabilities."""
    
    kernel_id: str
    version: str
    capabilities: list[CapabilityDescriptor]  # Simplified -- no impl details exposed
    endpoint: str                              # How to reach this kernel
    trust_level: Literal["verified", "unverified"]

# Publishing side
manifest = kernel.advertise()  # Returns CapabilityManifest

2. Remote capability import

# Consuming side
remote_caps = kernel.import_remote(
    manifest=remote_manifest,
    driver=HTTPDriver(base_url=remote_manifest.endpoint),
    trust_policy="most_restrictive",  # Local + remote policy both must allow
)

• Imported capabilities are registered with impl pointing to the remote kernel via HTTP/MCP driver.
• CapabilityDescriptor omits sensitive implementation details (driver config, internal operations).

3. Trust model

• most_restrictive (default): Both local and remote policy must allow the request. Sensitivity tags are the union (if remote says PII, local treats it as PII even if local policy says NONE).
• local_only: Remote policy is ignored; local policy alone decides. Use when you own both kernels.
• remote_deferred: Remote policy is checked first; local policy adds constraints. For delegation.

4. Security boundaries maintained

• Remote capabilities go through the full local pipeline: local policy → local token → local firewall.
• No direct driver access is exposed — the remote kernel's internal driver IDs are opaque.
• HMAC tokens are kernel-scoped — a token from Kernel A cannot be used on Kernel B.

5. Discovery protocol

# Periodic or on-demand discovery
manifests = await kernel.discover_peers(
    registry_url="https://registry.example.com/manifests",
    # or
    peer_urls=["https://agent-b.internal/kernel/manifest"],
)
for manifest in manifests:
    kernel.import_remote(manifest, ...)

Acceptance Criteria

• kernel.advertise() produces serializable CapabilityManifest (JSON-compatible)
• kernel.import_remote() registers remote capabilities in local registry
• Invoking an imported capability routes through HTTP/MCP driver to remote kernel
• most_restrictive trust: both local and remote policy must allow
• Remote kernel's internal implementation details are not exposed in manifest
• HMAC tokens are kernel-scoped (cross-kernel token reuse is rejected)
• End-to-end test: Kernel A imports from Kernel B → invokes → gets result through both firewalls

Affected Files

• src/agent_kernel/federation.py (new — CapabilityManifest, advertise, import_remote)
• src/agent_kernel/kernel.py (add advertise() and import_remote() methods)
• src/agent_kernel/models.py (add CapabilityManifest, CapabilityDescriptor)
• tests/test_federation.py (new — federation tests)
• docs/federation.md (new — architecture and trust model documentation)

Dependencies

• Requires HTTP Driver (existing) or MCP Driver (OpenTelemetry integration: spans, metrics, and trace export #38) for remote invocation
• Optionally pairs with namespace support (Capability namespaces & hierarchical discovery #45) for federated namespace resolution

Risk

High — protocol design needs careful security review. Consider writing a security design doc before implementation.

[dgenio]

Backlog review: split into sub-issues\n\nThis issue has been split into two focused sub-issues:\n- #52 — Capability marketplace part 1: manifest format & local registry\n- #51 — Capability marketplace part 2: federated cross-agent discovery\n\nThis parent issue is kept open as a tracking issue for the overall marketplace protocol work.