Crate smith_protocol 

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.

Modules

benchmark

Benchmark event protocol for Smith agent optimization

capabilities

Capability strings for handshake negotiation

client

IPC client for connecting to Smith service

idempotency

Idempotency Key System for Smith Platform

negotiation

params

Capability-specific parameter types

policy

policy_abi

Policy ABI Version Management for Smith Platform

reasoning

Reasoning session types for client-facing APIs These are minimal types for Phase 1 cleanup - full reasoning logic stays in service

result_schema

Result Schema v1 - Locked Contract for Smith Platform

Structs

AllowlistHit

Allow-list access record

AuditEntry

Audit log entry for compliance and debugging

AuditEvent

Enhanced audit event (replaces AuditEntry for better compatibility)

AuditRef

Reference to an audit log entry

CapabilitySpec

Capability specification for discovery and documentation

ExecutionError

Error details for failed executions

ExecutionLimits

Resource limits enforced during intent execution

GraphEdge

Graph edge for DAG visualization

GraphNode

Graph node for DAG visualization

Intent

Intent sent to executors via JetStream

IntentResult

Result of intent execution

PolicyDecision

Policy decision made during admission

ResourceRequirements

Resource requirements for a capability

ResourceUsage

Resource usage metrics for audit

RunnerMetadata

Runtime metadata from executor

SecurityContext

Security context for audit trail

Enums

Capability

Intent capabilities enum for JetStream execution

Command

Command sent to the core service

Event

Event emitted by the core service

ExecutionStatus

Execution status enum

HookAction

Hook action result from script execution

LogLevel

Log levels matching standard conventions

PolicyResult

Policy evaluation result

SandboxMode

Sandbox execution modes

ServiceState

Service operational state

Constants

PROTOCOL_VERSION

Protocol version for capability negotiation and compatibility checking.