Smith Protocol Library

This crate defines the core message protocols and data structures used throughout the Smith AI-powered execution platform. It provides:

• Intent System: Structured requests for capability execution with security signatures
• Result System: Standardized responses with execution metadata and audit trails
• Event System: Real-time communication protocols for service coordination
• Capability Definitions: Type-safe capability specifications and parameter schemas
• Security Context: Comprehensive audit trails and sandbox isolation metadata

Architecture Overview

Smith follows a strict separation between intelligence (AI agents) and execution (secure runners). All communication flows through NATS JetStream using the protocols defined in this crate:

AI Agent → Intent → NATS → Policy Validation → Secure Executor → Result → AI Agent

Key Design Principles

• Zero-Trust Security: All intents are cryptographically signed and policy-validated
• Comprehensive Auditing: Every action produces detailed audit trails for compliance
• Capability-Based Model: Fine-grained permissions using versioned capability strings
• Type Safety: Strongly typed parameters and results with JSON Schema validation
• Time-Based Ordering: UUIDv7 identifiers provide distributed ordering guarantees

Basic Usage

use smith_protocol::{Intent, Capability, IntentResult, RunnerMetadata};
use serde_json::json;
use std::time::{SystemTime, UNIX_EPOCH};

// Create a file read intent
let intent = Intent::new(
    Capability::FsReadV1,
    "production".to_string(),
    json!({"path": "/etc/hostname", "max_bytes": 1024}),
    30000, // 30 second TTL
    "client-public-key".to_string(),
);

// Results include comprehensive execution metadata
let start_time_ns = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
let end_time_ns = start_time_ns + 1_000_000; // 1ms later
let runner_metadata = RunnerMetadata::empty();

let result = IntentResult::success(
    intent.id.clone(),
    json!({"content": "server.example.com\n"}),
    start_time_ns,
    end_time_ns,
    runner_metadata,
    "audit-12345".to_string(),
);

Security Model

The protocol implements a multi-layer security model:

1. Cryptographic Signatures: All intents are signed with Ed25519 keys
2. Policy Validation: CUE-based policies validate intents before execution
3. Sandbox Isolation: Multiple isolation layers (Landlock, seccomp, cgroups)
4. Resource Limits: CPU, memory, and I/O constraints enforced per capability
5. Audit Trails: Complete execution history for compliance and forensics

For implementation details, see the specific capability modules and the executor documentation.