agentic-contracts

Shared contracts for the AgenticOS ecosystem.

This crate defines the traits, types, and standards that ALL sisters must implement. It serves as the single source of truth for the ecosystem.

The Promise

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   ANY sister can be consumed by Hydra uniformly.              ║
║   ANY sister can work with ANY other sister.                  ║
║   ANY file format will be readable in 20 years.               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Installation

[dependencies]
agentic-contracts = "0.2"

Core Traits

Sister Trait

The foundation that all sisters implement:

use agentic_contracts::prelude::*;

pub struct MyNewSister { /* ... */ }

impl Sister for MyNewSister {
    const SISTER_TYPE: SisterType = SisterType::Memory;
    const FILE_EXTENSION: &'static str = "amem";

    fn init(config: SisterConfig) -> SisterResult<Self> { /* ... */ }
    fn health(&self) -> HealthStatus { /* ... */ }
    fn version(&self) -> Version { /* ... */ }
    fn shutdown(&mut self) -> SisterResult<()> { /* ... */ }
    fn capabilities(&self) -> Vec<Capability> { /* ... */ }
}

SessionManagement Trait

Append-only sequential sessions (Memory, Vision, Identity):

impl SessionManagement for MyNewSister {
    fn start_session(&mut self, name: &str) -> SisterResult<ContextId> { /* ... */ }
    fn end_session(&mut self) -> SisterResult<()> { /* ... */ }
    fn current_session(&self) -> Option<ContextId> { /* ... */ }
    fn export_session(&self, id: ContextId) -> SisterResult<ContextSnapshot> { /* ... */ }
    fn import_session(&mut self, snapshot: ContextSnapshot) -> SisterResult<ContextId> { /* ... */ }
}

WorkspaceManagement Trait

Switchable named workspaces (Codebase):

impl WorkspaceManagement for MyNewSister {
    fn create_workspace(&mut self, name: &str) -> SisterResult<ContextId> { /* ... */ }
    fn switch_workspace(&mut self, id: ContextId) -> SisterResult<()> { /* ... */ }
    fn current_workspace(&self) -> Option<ContextId> { /* ... */ }
    fn delete_workspace(&mut self, id: ContextId) -> SisterResult<()> { /* ... */ }
}

Grounding Trait

Search-based claim verification:

impl Grounding for MyNewSister {
    fn ground(&self, claim: &str) -> SisterResult<GroundingResult> { /* ... */ }
    fn evidence(&self, query: &str, max_results: usize) -> SisterResult<Vec<EvidenceDetail>> { /* ... */ }
    fn suggest(&self, query: &str, limit: usize) -> SisterResult<Vec<GroundingSuggestion>> { /* ... */ }
}

Queryable Trait

Standard query interface:

impl Queryable for MyNewSister {
    fn query(&self, query: Query) -> SisterResult<QueryResult> { /* ... */ }
    fn supports_query(&self, query_type: &str) -> bool { /* ... */ }
    fn query_types(&self) -> Vec<QueryTypeInfo> { /* ... */ }
}

EventEmitter Trait

Observability events:

impl EventEmitter for MyNewSister {
    fn subscribe(&self, filter: EventFilter) -> EventReceiver { /* ... */ }
    fn recent_events(&self, limit: usize) -> Vec<SisterEvent> { /* ... */ }
    fn emit(&self, event: SisterEvent) { /* ... */ }
}

File Format

Each sister uses its own binary header format. The contracts provide FileFormatReader and FileFormatWriter traits for unified access:

use agentic_contracts::file_format::*;

impl FileFormatReader for MyNewSister {
    fn can_read(&self, path: &Path) -> bool { /* check magic bytes */ }
    fn file_info(&self, path: &Path) -> SisterResult<FileInfo> { /* ... */ }
    fn file_version(&self, path: &Path) -> SisterResult<Version> { /* ... */ }
}

impl FileFormatWriter for MyNewSister {
    fn write_file(&self, path: &Path) -> SisterResult<()> { /* ... */ }
    fn export_bytes(&self) -> SisterResult<Vec<u8>> { /* ... */ }
}

Error Handling

Two-layer error model across all sisters:

use agentic_contracts::errors::*;

// Domain errors (tool execution failures -> isError: true in MCP)
let err = SisterError::not_found("node_123");
let err = SisterError::invalid_input("name cannot be empty");
let err = SisterError::storage("Failed to write file");

// Protocol errors (routing failures -> JSON-RPC error response)
let err = ProtocolError::tool_not_found("unknown_tool");
let err = ProtocolError::invalid_params("missing required field 'name'");

Sisters Covered

License

MIT