P1 backend: chat persistence, tc-llm providers, runtime loop, gateway SSE

- tc-db: sessions/messages/steps/runs/run_events repos (atomic seq assignment,
  history with ordered step traces, journal replay-from-offset); migration 0003
- tc-llm: provider-neutral ChatRequest/LlmEvent; ScriptedProvider (scenario
  TOML, word-level deltas, multi-turn tool legs — ships in production for
  e2e/air-gap smoke), AnthropicProvider (Messages SSE), OpenAiCompatProvider
  (vLLM/Ollama/llama.cpp); opt-in live tests via TC_LIVE_LLM=1
- tc-runtime: run loop with persist-before-emit event journal, real built-in
  clock.now tool, step rows on the reply message, tool-error resilience,
  broadcast channels for live attach
- tc-api: agent CRUD + settings/full (tenant-isolated, RBAC'd, audited),
  sessions create/list/history?tools=true, POST /api/gateway SSE with
  monotonic ids and exact resumeFrom journal replay (tested equal to live)
- teamclaw-server: config-driven provider factory

83 Rust tests green, all against real Postgres / real TCP.

Co-Authored-By: Claude Fable 5 <[email protected]>
This commit is contained in:
Omar Sobh
2026-06-09 23:16:06 -05:00
co-authored by Claude Fable 5
parent fc173f170d
commit 32008c9ef0
58 changed files with 4378 additions and 11 deletions
+175
View File
@@ -0,0 +1,175 @@
//! Anthropic Messages API provider (cloud target).
use async_stream::try_stream;
use eventsource_stream::Eventsource;
use futures::StreamExt;
use serde_json::{json, Value};
use crate::provider::{
ChatRequest, ChatRole, ContentPart, EventStream, LlmError, LlmEvent, LlmProvider, StopReason,
};
pub struct AnthropicProvider {
client: reqwest::Client,
base_url: String,
api_key: String,
}
impl AnthropicProvider {
pub fn new(api_key: String) -> AnthropicProvider {
AnthropicProvider::with_base_url(api_key, "https://api.anthropic.com".into())
}
/// Base URL override exists for self-hosted proxies and tests.
pub fn with_base_url(api_key: String, base_url: String) -> AnthropicProvider {
AnthropicProvider {
client: reqwest::Client::new(),
base_url,
api_key,
}
}
fn wire_messages(request: &ChatRequest) -> Vec<Value> {
request
.messages
.iter()
.map(|message| {
let role = match message.role {
ChatRole::User => "user",
ChatRole::Assistant => "assistant",
};
let content: Vec<Value> = message
.parts
.iter()
.map(|part| match part {
ContentPart::Text(text) => json!({"type": "text", "text": text}),
ContentPart::ToolUse { id, name, input } => {
json!({"type": "tool_use", "id": id, "name": name, "input": input})
}
ContentPart::ToolResult {
tool_use_id,
content,
} => json!({
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": content.to_string(),
}),
})
.collect();
json!({"role": role, "content": content})
})
.collect()
}
}
fn stop_reason(wire: &str) -> StopReason {
match wire {
"tool_use" => StopReason::ToolUse,
"max_tokens" => StopReason::MaxTokens,
_ => StopReason::EndTurn,
}
}
#[async_trait::async_trait]
impl LlmProvider for AnthropicProvider {
async fn stream(&self, request: ChatRequest) -> Result<EventStream, LlmError> {
let tools: Vec<Value> = request
.tools
.iter()
.map(|t| {
json!({
"name": t.name,
"description": t.description,
"input_schema": t.input_schema,
})
})
.collect();
let body = json!({
"model": request.model,
"max_tokens": request.max_tokens,
"system": request.system,
"messages": AnthropicProvider::wire_messages(&request),
"tools": tools,
"stream": true,
});
let response = self
.client
.post(format!("{}/v1/messages", self.base_url))
.header("x-api-key", &self.api_key)
.header("anthropic-version", "2023-06-01")
.json(&body)
.send()
.await
.map_err(|e| LlmError::Transport(e.to_string()))?;
if !response.status().is_success() {
let status = response.status();
let detail = response.text().await.unwrap_or_default();
return Err(LlmError::Api(format!("{status}: {detail}")));
}
let mut sse = response.bytes_stream().eventsource();
let stream = try_stream! {
// tool_use input arrives as accumulated partial JSON between
// content_block_start and content_block_stop.
let mut pending_tool: Option<(String, String, String)> = None; // id, name, json
while let Some(event) = sse.next().await {
let event = event.map_err(|e| LlmError::Transport(e.to_string()))?;
let data: Value = serde_json::from_str(&event.data)
.map_err(|e| LlmError::Wire(format!("{e}: {}", event.data)))?;
match data["type"].as_str().unwrap_or_default() {
"content_block_start" => {
let block = &data["content_block"];
if block["type"] == "tool_use" {
pending_tool = Some((
block["id"].as_str().unwrap_or_default().to_owned(),
block["name"].as_str().unwrap_or_default().to_owned(),
String::new(),
));
}
}
"content_block_delta" => {
let delta = &data["delta"];
match delta["type"].as_str().unwrap_or_default() {
"text_delta" => {
if let Some(text) = delta["text"].as_str() {
yield LlmEvent::TextDelta(text.to_owned());
}
}
"input_json_delta" => {
if let Some((_, _, buf)) = pending_tool.as_mut() {
buf.push_str(delta["partial_json"].as_str().unwrap_or_default());
}
}
_ => {}
}
}
"content_block_stop" => {
if let Some((id, name, buf)) = pending_tool.take() {
let input: Value = if buf.is_empty() {
json!({})
} else {
serde_json::from_str(&buf)
.map_err(|e| LlmError::Wire(format!("tool input: {e}")))?
};
yield LlmEvent::ToolUse { id, name, input };
}
}
"message_delta" => {
if let Some(reason) = data["delta"]["stop_reason"].as_str() {
yield LlmEvent::Stop(stop_reason(reason));
}
}
"error" => {
Err(LlmError::Api(data["error"]["message"]
.as_str()
.unwrap_or("unknown")
.to_owned()))?;
}
_ => {}
}
}
};
Ok(Box::pin(stream))
}
}
+24
View File
@@ -0,0 +1,24 @@
//! LLM access for TeamClaw. One provider trait, three shipping
//! implementations selected by configuration:
//!
//! - `anthropic` — Anthropic Messages API (cloud target)
//! - `openai_compat` — any OpenAI-compatible endpoint (air-gapped vLLM /
//! Ollama / llama.cpp)
//! - `scripted` — deterministic scenario engine; the test/e2e/smoke-test
//! provider that exercises the exact production seam
//!
//! Everything upstream (runtime, gateway, UI) speaks only the
//! provider-neutral types in `provider.rs`.
mod anthropic;
mod openai_compat;
mod provider;
mod scripted;
pub use anthropic::AnthropicProvider;
pub use openai_compat::OpenAiCompatProvider;
pub use provider::{
ChatMessage, ChatRequest, ChatRole, ContentPart, EventStream, LlmError, LlmEvent, LlmProvider,
StopReason, ToolDescriptor,
};
pub use scripted::ScriptedProvider;
+179
View File
@@ -0,0 +1,179 @@
//! OpenAI-compatible chat/completions provider — the air-gapped inference
//! path (vLLM, Ollama, llama.cpp all speak this protocol).
use async_stream::try_stream;
use eventsource_stream::Eventsource;
use futures::StreamExt;
use serde_json::{json, Value};
use crate::provider::{
ChatRequest, ChatRole, ContentPart, EventStream, LlmError, LlmEvent, LlmProvider, StopReason,
};
pub struct OpenAiCompatProvider {
client: reqwest::Client,
base_url: String,
api_key: Option<String>,
}
impl OpenAiCompatProvider {
/// `base_url` includes the version prefix, e.g. `http://local-llm:8000/v1`.
pub fn new(base_url: String, api_key: Option<String>) -> OpenAiCompatProvider {
OpenAiCompatProvider {
client: reqwest::Client::new(),
base_url,
api_key,
}
}
/// Maps provider-neutral messages to the OpenAI wire shape: tool calls
/// ride on assistant messages, tool results become `role: "tool"`.
fn wire_messages(request: &ChatRequest) -> Vec<Value> {
let mut wire = vec![json!({"role": "system", "content": request.system})];
for message in &request.messages {
let mut text = String::new();
let mut tool_calls: Vec<Value> = Vec::new();
for part in &message.parts {
match part {
ContentPart::Text(t) => text.push_str(t),
ContentPart::ToolUse { id, name, input } => tool_calls.push(json!({
"id": id,
"type": "function",
"function": {"name": name, "arguments": input.to_string()},
})),
ContentPart::ToolResult {
tool_use_id,
content,
} => wire.push(json!({
"role": "tool",
"tool_call_id": tool_use_id,
"content": content.to_string(),
})),
}
}
if !text.is_empty() || !tool_calls.is_empty() {
let role = match message.role {
ChatRole::User => "user",
ChatRole::Assistant => "assistant",
};
let mut entry = json!({"role": role, "content": text});
if !tool_calls.is_empty() {
entry["tool_calls"] = Value::Array(tool_calls);
}
wire.push(entry);
}
}
wire
}
}
fn stop_reason(wire: &str) -> StopReason {
match wire {
"tool_calls" => StopReason::ToolUse,
"length" => StopReason::MaxTokens,
_ => StopReason::EndTurn,
}
}
#[async_trait::async_trait]
impl LlmProvider for OpenAiCompatProvider {
async fn stream(&self, request: ChatRequest) -> Result<EventStream, LlmError> {
let tools: Vec<Value> = request
.tools
.iter()
.map(|t| {
json!({
"type": "function",
"function": {
"name": t.name,
"description": t.description,
"parameters": t.input_schema,
},
})
})
.collect();
let mut body = json!({
"model": request.model,
"max_tokens": request.max_tokens,
"messages": OpenAiCompatProvider::wire_messages(&request),
"stream": true,
});
if !tools.is_empty() {
body["tools"] = Value::Array(tools);
}
let mut http = self
.client
.post(format!("{}/chat/completions", self.base_url))
.json(&body);
if let Some(key) = &self.api_key {
http = http.bearer_auth(key);
}
let response = http
.send()
.await
.map_err(|e| LlmError::Transport(e.to_string()))?;
if !response.status().is_success() {
let status = response.status();
let detail = response.text().await.unwrap_or_default();
return Err(LlmError::Api(format!("{status}: {detail}")));
}
let mut sse = response.bytes_stream().eventsource();
let stream = try_stream! {
// Tool-call arguments stream as partial JSON keyed by index.
let mut pending: Vec<(String, String, String)> = Vec::new(); // id, name, args
let mut finish: Option<StopReason> = None;
while let Some(event) = sse.next().await {
let event = event.map_err(|e| LlmError::Transport(e.to_string()))?;
if event.data.trim() == "[DONE]" {
break;
}
let data: Value = serde_json::from_str(&event.data)
.map_err(|e| LlmError::Wire(format!("{e}: {}", event.data)))?;
let choice = &data["choices"][0];
let delta = &choice["delta"];
if let Some(text) = delta["content"].as_str() {
if !text.is_empty() {
yield LlmEvent::TextDelta(text.to_owned());
}
}
if let Some(calls) = delta["tool_calls"].as_array() {
for call in calls {
let index = call["index"].as_u64().unwrap_or(0) as usize;
while pending.len() <= index {
pending.push((String::new(), String::new(), String::new()));
}
let slot = &mut pending[index];
if let Some(id) = call["id"].as_str() {
slot.0 = id.to_owned();
}
if let Some(name) = call["function"]["name"].as_str() {
slot.1.push_str(name);
}
if let Some(args) = call["function"]["arguments"].as_str() {
slot.2.push_str(args);
}
}
}
if let Some(reason) = choice["finish_reason"].as_str() {
finish = Some(stop_reason(reason));
}
}
for (id, name, args) in pending.drain(..) {
if name.is_empty() {
continue;
}
let input: Value = if args.trim().is_empty() {
json!({})
} else {
serde_json::from_str(&args)
.map_err(|e| LlmError::Wire(format!("tool arguments: {e}")))?
};
yield LlmEvent::ToolUse { id, name, input };
}
yield LlmEvent::Stop(finish.unwrap_or(StopReason::EndTurn));
};
Ok(Box::pin(stream))
}
}
+94
View File
@@ -0,0 +1,94 @@
use futures::stream::BoxStream;
use serde::{Deserialize, Serialize};
use serde_json::Value;
/// Provider-neutral conversation role.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ChatRole {
User,
Assistant,
}
/// Provider-neutral message content. Tool results travel as user-role parts,
/// matching both wire formats' conventions.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContentPart {
Text(String),
ToolUse {
id: String,
name: String,
input: Value,
},
ToolResult {
tool_use_id: String,
content: Value,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChatMessage {
pub role: ChatRole,
pub parts: Vec<ContentPart>,
}
/// A tool offered to the model. `input_schema` is JSON Schema.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ToolDescriptor {
pub name: String,
pub description: String,
pub input_schema: Value,
}
/// The checkpointable, provider-neutral request. This struct is what gets
/// serialized into `agent_runs.checkpoint`, so resume works identically
/// across providers.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChatRequest {
pub system: String,
pub messages: Vec<ChatMessage>,
pub tools: Vec<ToolDescriptor>,
pub model: String,
pub max_tokens: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StopReason {
EndTurn,
ToolUse,
MaxTokens,
}
/// Streaming events every provider normalizes to.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum LlmEvent {
TextDelta(String),
ToolUse {
id: String,
name: String,
input: Value,
},
Stop(StopReason),
}
#[derive(Debug, thiserror::Error)]
pub enum LlmError {
#[error("scenario error: {0}")]
Scenario(String),
#[error("transport error: {0}")]
Transport(String),
#[error("provider returned an error: {0}")]
Api(String),
#[error("malformed provider response: {0}")]
Wire(String),
}
pub type EventStream = BoxStream<'static, Result<LlmEvent, LlmError>>;
#[async_trait::async_trait]
pub trait LlmProvider: Send + Sync {
async fn stream(&self, request: ChatRequest) -> Result<EventStream, LlmError>;
}
+163
View File
@@ -0,0 +1,163 @@
//! The deterministic scenario provider.
//!
//! A real, config-selectable production provider (`provider = "scripted"`):
//! it powers TDD, Playwright E2E, and the air-gapped smoke-test mode, so
//! tests exercise the exact seam production uses. Scenarios are TOML; a
//! prompt that contains a scenario's `marker` plays that scenario's turns,
//! anything else gets a deterministic echo.
use futures::stream;
use serde::Deserialize;
use serde_json::Value;
use crate::provider::{
ChatRequest, ContentPart, EventStream, LlmError, LlmEvent, LlmProvider, StopReason,
};
#[derive(Debug, Deserialize)]
struct ScenarioFile {
#[serde(default)]
scenario: Vec<Scenario>,
}
#[derive(Debug, Deserialize)]
struct Scenario {
marker: String,
#[serde(default)]
turns: Vec<Turn>,
}
#[derive(Debug, Deserialize)]
struct Turn {
#[serde(default)]
events: Vec<ScriptedEvent>,
}
#[derive(Debug, Clone, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
enum ScriptedEvent {
Text {
text: String,
},
ToolUse {
name: String,
#[serde(default)]
input: Value,
},
}
#[derive(Debug)]
pub struct ScriptedProvider {
scenarios: Vec<Scenario>,
}
impl ScriptedProvider {
pub fn from_toml(toml_source: &str) -> Result<ScriptedProvider, LlmError> {
let file: ScenarioFile =
toml::from_str(toml_source).map_err(|e| LlmError::Scenario(e.to_string()))?;
Ok(ScriptedProvider {
scenarios: file.scenario,
})
}
pub fn from_path(path: &std::path::Path) -> Result<ScriptedProvider, LlmError> {
let source = std::fs::read_to_string(path)
.map_err(|e| LlmError::Scenario(format!("read {}: {e}", path.display())))?;
ScriptedProvider::from_toml(&source)
}
/// Streams a fixed text as word-level deltas to exercise real streaming
/// behavior in every consumer.
fn text_deltas(text: &str, out: &mut Vec<Result<LlmEvent, LlmError>>) {
let mut rest = text;
while !rest.is_empty() {
let cut = rest
.char_indices()
.skip_while(|(_, c)| *c == ' ')
.find(|(_, c)| *c == ' ')
.map(|(i, _)| i)
.unwrap_or(rest.len());
let (chunk, tail) = rest.split_at(cut.max(1));
out.push(Ok(LlmEvent::TextDelta(chunk.to_owned())));
rest = tail;
}
}
}
#[async_trait::async_trait]
impl LlmProvider for ScriptedProvider {
async fn stream(&self, request: ChatRequest) -> Result<EventStream, LlmError> {
let prompt_text: String = request
.messages
.iter()
.flat_map(|m| m.parts.iter())
.filter_map(|p| match p {
ContentPart::Text(t) => Some(t.as_str()),
_ => None,
})
.collect::<Vec<_>>()
.join("\n");
// Which leg of a multi-tool conversation is this? One ToolResult in
// the request means turn 0 already played; play turn 1, and so on.
let turn_index = request
.messages
.iter()
.flat_map(|m| m.parts.iter())
.filter(|p| matches!(p, ContentPart::ToolResult { .. }))
.count();
let mut events: Vec<Result<LlmEvent, LlmError>> = Vec::new();
let scenario = self
.scenarios
.iter()
.find(|s| prompt_text.contains(&s.marker));
match scenario {
Some(scenario) => {
match scenario.turns.get(turn_index) {
Some(turn) => {
let mut stopped_for_tool = false;
for (i, event) in turn.events.iter().enumerate() {
match event {
ScriptedEvent::Text { text } => {
Self::text_deltas(text, &mut events);
}
ScriptedEvent::ToolUse { name, input } => {
events.push(Ok(LlmEvent::ToolUse {
id: format!("scripted-tool-{turn_index}-{i}"),
name: name.clone(),
input: input.clone(),
}));
stopped_for_tool = true;
}
}
}
events.push(Ok(LlmEvent::Stop(if stopped_for_tool {
StopReason::ToolUse
} else {
StopReason::EndTurn
})));
}
// More tool round-trips than scripted turns: end cleanly.
None => events.push(Ok(LlmEvent::Stop(StopReason::EndTurn))),
}
}
None => {
let last_user_text = request
.messages
.iter()
.rev()
.flat_map(|m| m.parts.iter())
.find_map(|p| match p {
ContentPart::Text(t) => Some(t.clone()),
_ => None,
})
.unwrap_or_default();
Self::text_deltas(&format!("I received: {last_user_text}"), &mut events);
events.push(Ok(LlmEvent::Stop(StopReason::EndTurn)));
}
}
Ok(Box::pin(stream::iter(events)))
}
}