cap-rs 0.0.1

Rust reference implementation of the CAP (CLI Agent Protocol).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

//! Core protocol types — events, frames, content blocks, usage.
//!
//! These types are defined in the spec at <https://github.com/rsclaw-ai/cap-protocol/blob/main/docs/cap-v1.md>
//! sections §7 (events) and §10 (lifecycle).
//!
//! All enums are marked `#[non_exhaustive]` during v0.x so new variants can
//! be added without a semver-breaking change.

use std::time::Duration;

// ---------------------------------------------------------------------------
// ClientFrame — what the orchestrator sends to the agent.
// ---------------------------------------------------------------------------

/// A frame sent by the client (orchestrator) to the agent during a session.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum ClientFrame {
    /// A user prompt with one or more content parts.
    Prompt { content: Vec<Content> },

    /// An answer to a previously emitted [`AgentEvent::AskUser`].
    AskUserAnswer { ask_id: String, value: serde_json::Value },

    /// An answer to a previously emitted [`AgentEvent::PermissionRequest`].
    PermissionResponse { req_id: String, decision: PermissionDecision },

    /// Cancel the current turn (graceful).
    Cancel,
}

/// A content part of a user prompt.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum Content {
    Text(String),
    Image { mime: String, data: Vec<u8> },
    // File / ToolResult etc. land later
}

// ---------------------------------------------------------------------------
// AgentEvent — what the agent streams back to the client.
// ---------------------------------------------------------------------------

/// A streaming event from the agent. Subset of spec §7.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum AgentEvent {
    /// Session has been initialized and is ready to accept prompts.
    Ready { session_id: String, model: Option<String> },

    /// Streaming text chunk from the assistant.
    TextChunk { msg_id: String, text: String, channel: TextChannel },

    /// Agent's internal reasoning (when exposed by the model).
    Thought { msg_id: String, text: String },

    /// Agent started a tool call.
    ToolCallStart { call_id: String, name: String, input: serde_json::Value },

    /// Agent's tool call returned a result.
    ToolCallEnd { call_id: String, output: String, is_error: bool },

    /// Agent published an updated plan (full state, replaces previous).
    Plan { entries: Vec<PlanEntry> },

    /// Agent asks the user a structured question.
    AskUser { ask_id: String, prompt: String, kind: AskKind, options: Vec<AskOption> },

    /// Agent requests permission for a security-sensitive action.
    PermissionRequest {
        req_id: String,
        tool: String,
        intent: serde_json::Value,
        scope: PermissionScope,
    },

    /// Turn complete. Usage stats included.
    Done { stop_reason: StopReason, usage: Usage },

    /// Non-fatal error during the turn.
    Error { code: String, message: String },
}

/// Channel hint for [`AgentEvent::TextChunk`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum TextChannel {
    Assistant,
    System,
}

/// Plan entry from spec §7.3.
#[derive(Debug, Clone)]
pub struct PlanEntry {
    pub id: String,
    pub content: String,
    pub status: PlanStatus,
    pub priority: PlanPriority,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PlanStatus { Pending, InProgress, Completed, Cancelled, Blocked }

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PlanPriority { High, Medium, Low }

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum AskKind { YesNo, Options, FreeText }

#[derive(Debug, Clone)]
pub struct AskOption {
    pub id: String,
    pub label: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PermissionScope { Read, Write, Execute, Network }

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PermissionDecision { AllowOnce, AllowAlways, Deny }

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum StopReason {
    EndTurn,
    MaxTokens,
    ToolUse,
    StopSequence,
    Cancelled,
    Error,
}

/// Token / cost accounting for a completed turn.
#[derive(Debug, Clone, Default)]
pub struct Usage {
    pub input_tokens: u64,
    pub output_tokens: u64,
    pub cache_read_tokens: u64,
    pub cache_creation_tokens: u64,
    pub cost_usd_estimate: Option<f64>,
    pub duration: Option<Duration>,
    pub model_id: Option<String>,
}