arcp 2.0.0

Reference implementation of the Agent Runtime Control Protocol (ARCP) v1.1 — umbrella crate that re-exports arcp-core, arcp-client, and arcp-runtime.
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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

//! Integration tests for the job lifecycle (RFC §10.1–§10.2).
//!
//! Phase 3 covers tool invocation that runs to completion, tool errors
//! that surface as `job.failed`, and routing for unknown tools.

#![allow(
    clippy::expect_used,
    clippy::unwrap_used,
    clippy::panic,
    clippy::missing_panics_doc
)]

mod common;

use std::sync::Arc;

use arcp::auth::BearerAuthenticator;
use arcp::error::ARCPError;
use arcp::messages::{Capabilities, ClientIdentity, Credentials};
use arcp::runtime::{ARCPRuntime, ToolContext, ToolHandler, ToolRegistryBuilder};
use arcp::transport::paired;
use arcp::ARCPClient;
use async_trait::async_trait;

struct EchoTool;

#[async_trait]
impl ToolHandler for EchoTool {
    fn name(&self) -> &'static str {
        "echo"
    }

    async fn invoke(
        &self,
        arguments: serde_json::Value,
        _ctx: ToolContext,
    ) -> Result<serde_json::Value, ARCPError> {
        Ok(arguments)
    }
}

struct FailingTool;

#[async_trait]
impl ToolHandler for FailingTool {
    fn name(&self) -> &'static str {
        "fail"
    }

    async fn invoke(
        &self,
        _arguments: serde_json::Value,
        _ctx: ToolContext,
    ) -> Result<serde_json::Value, ARCPError> {
        Err(ARCPError::InvalidArgument {
            detail: "deliberate failure".into(),
        })
    }
}

async fn spawn_with_tools() -> ARCPClient<arcp::transport::MemoryTransport> {
    let tools = ToolRegistryBuilder::new()
        .with(Arc::new(EchoTool))
        .with(Arc::new(FailingTool))
        .build();
    let runtime = ARCPRuntime::builder()
        .with_authenticator(Box::new(BearerAuthenticator::new().with_token("t", "p")))
        .with_capabilities(Capabilities {
            streaming: Some(true),
            durable_jobs: Some(true),
            ..Default::default()
        })
        .with_tools(tools)
        .build()
        .await
        .expect("build");
    let (server_t, client_t) = paired();
    let _h = runtime.serve_connection(server_t);
    ARCPClient::new(client_t)
}

fn ident() -> ClientIdentity {
    ClientIdentity {
        kind: "test".into(),
        version: "0".into(),
        fingerprint: None,
        principal: None,
    }
}

#[tokio::test]
async fn happy_path_invoke_returns_value() {
    let client = spawn_with_tools().await;
    let session = client
        .open()
        .expect("open")
        .authenticate(
            Credentials {
                scheme: arcp::messages::AuthScheme::Bearer,
                token: Some("t".into()),
            },
            ident(),
            Capabilities::default(),
        )
        .await
        .expect("auth");

    let job = session
        .invoke("echo", serde_json::json!({"hello": "world"}))
        .await
        .expect("invoke");
    assert!(job.job_id.as_str().starts_with("job_"));

    let result = job.join().await.expect("complete");
    assert_eq!(result, serde_json::json!({"hello": "world"}));
}

#[tokio::test]
async fn failing_tool_surfaces_as_job_failed() {
    let client = spawn_with_tools().await;
    let session = client
        .open()
        .expect("open")
        .authenticate(
            Credentials {
                scheme: arcp::messages::AuthScheme::Bearer,
                token: Some("t".into()),
            },
            ident(),
            Capabilities::default(),
        )
        .await
        .expect("auth");

    let job = session
        .invoke("fail", serde_json::json!({}))
        .await
        .expect("invoke");
    let err = job.join().await.expect_err("must fail");
    assert!(err.to_string().contains("deliberate failure"), "got: {err}");
}

#[tokio::test]
async fn unknown_tool_surfaces_as_not_found() {
    let client = spawn_with_tools().await;
    let session = client
        .open()
        .expect("open")
        .authenticate(
            Credentials {
                scheme: arcp::messages::AuthScheme::Bearer,
                token: Some("t".into()),
            },
            ident(),
            Capabilities::default(),
        )
        .await
        .expect("auth");

    let job = session
        .invoke("never-registered", serde_json::json!({}))
        .await
        .expect("invoke");
    let err = job.join().await.expect_err("must fail");
    assert!(
        err.to_string().contains("not registered")
            || err.to_string().contains("NOT_FOUND")
            || err.to_string().contains("not_found"),
        "got: {err}"
    );
}