okbot_core/
lib.rs

1//! Domain model and ports (traits) of okbot; the SDK for third-party adapters.
2//!
3//! okbot follows a ports-and-adapters architecture (ADR 0001). This crate holds the types every
4//! other crate speaks and the traits adapters implement. It performs no I/O.
5//!
6//! | Port | Implemented by | Used by |
7//! |---|---|---|
8//! | [`Channel`] | one crate per chat platform | the runtime |
9//! | [`InboundSink`] | the runtime | channels, to deliver events |
10//! | [`AgentBackend`] | agent CLIs, fallback chains | the runtime |
11//! | [`ConversationStore`] | SQLite store | the runtime |
12//! | [`KnowledgeProvider`] | okbase integration | the runtime |
13//! | [`MemoryStore`] | okbase integration | the runtime (chat commands) |
14//! | [`TaskStore`] | okbase integration | the runtime (chat commands, scheduler) |
15//! | [`Renderer`] | Markdown dialect renderer | the runtime |
16//! | [`Peers`] | the peer adapter (ADR 0014) | the runtime (delegation) |
17//! | [`Clock`] | [`SystemClock`], test clocks | everything that reads time |
18//!
19//! # Writing a channel
20//!
21//! A platform adapter implements [`Channel`]: receive events and hand them to the [`InboundSink`],
22//! send rendered replies. Everything else (policy, agents, knowledge) is the runtime's job.
23//!
24//! ```
25//! use std::sync::Arc;
26//! use okbot_core::{
27//!     async_trait, CancellationToken, Channel, ChannelCaps, ChannelError, ChannelId, InboundSink,
28//!     MessageId, RenderedMessage, ReplyTarget, SentRef,
29//! };
30//!
31//! struct EchoChannel { id: ChannelId, caps: ChannelCaps }
32//!
33//! #[async_trait]
34//! impl Channel for EchoChannel {
35//!     fn id(&self) -> &ChannelId { &self.id }
36//!     fn caps(&self) -> &ChannelCaps { &self.caps }
37//!
38//!     async fn run(&self, _sink: Arc<dyn InboundSink>, shutdown: CancellationToken)
39//!         -> Result<(), ChannelError> {
40//!         // Connect to the platform and call `sink.deliver(event)` for each message.
41//!         shutdown.cancelled().await;
42//!         Ok(())
43//!     }
44//!
45//!     async fn send(&self, to: &ReplyTarget, message: &RenderedMessage)
46//!         -> Result<SentRef, ChannelError> {
47//!         println!("{}", message.text);
48//!         Ok(SentRef { target: to.clone(), message_id: MessageId::new("1") })
49//!     }
50//! }
51//!
52//! let channel = EchoChannel { id: "echo:demo".parse().unwrap(), caps: ChannelCaps::basic() };
53//! assert_eq!(channel.id().to_string(), "echo:demo");
54//! ```
55#![deny(missing_docs)]
56
57mod agent;
58mod caps;
59mod channel;
60mod clock;
61mod id;
62mod knowledge;
63mod memory;
64mod message;
65mod notify;
66mod peer;
67mod prompt;
68mod render;
69mod secret;
70mod store;
71mod task;
72mod webhook;
73
74pub use agent::{
75    AgentBackend, AgentError, AgentProgress, AgentReply, AgentTurn, McpServer, ProgressFn, Resume,
76    TokenUsage,
77};
78pub use caps::{AgentCaps, ChannelCaps, LengthUnit, MarkdownDialect, ToolPolicy};
79pub use channel::{Channel, ChannelError, CommandInfo, CommandParam, InboundSink, SinkClosed};
80pub use clock::{Clock, SystemClock};
81pub use id::{ChannelId, ConversationKey, IdError, MessageId, RunId, UserId, UserRef};
82pub use knowledge::{
83    KnowledgeContext, KnowledgeError, KnowledgeProvider, Person, Requester, RunGrant, RunInfo,
84};
85pub use memory::{MemoryEntry, MemoryError, MemoryNote, MemoryScope, MemoryStore};
86pub use message::{
87    Attachment, InboundEvent, OutboundMessage, RenderedMessage, ReplyTarget, SentRef,
88};
89pub use notify::NotifyTo;
90pub use peer::{
91    Budget, Delegation, DelegationContext, Origin, PEER_CANCEL_PREFIX, PEER_PLATFORM, PeerCaller,
92    PeerError, PeerInfo, PeerPrompt, PeerTarget, PeerTask, PeerTaskRecord, PeerTaskState, Peers,
93};
94pub use prompt::{
95    ButtonStyle, FieldStyle, Form, FormField, MAX_BUTTONS, MAX_FIELDS, Prompt, PromptAnswer,
96    PromptButton,
97};
98pub use render::Renderer;
99pub use secret::{Redactor, Secret};
100pub use store::{
101    AgentRunRecord, AutomationRun, ConversationStore, Fire, FireState, MessageRole, NewMessage,
102    PAIRING_MAX_FAILURES, RoleGrant, SealedEntry, StoreError, StoredMessage, ToolCallRecord,
103    ToolDecision, Usage, person_key,
104};
105pub use task::{
106    NewTask, Repeat, Task, TaskChange, TaskError, TaskKind, TaskStatus, TaskStore, format_time,
107    parse_time, sort_tasks,
108};
109pub use webhook::{WebhookHandler, WebhookRequest, WebhookResponse};
110
111/// Re-exported so adapters use the same cancellation type as the runtime.
112pub use tokio_util::sync::CancellationToken;
113
114/// Re-exported so adapters implement the async traits with the same macro version.
115pub use async_trait::async_trait;
116
117/// A boxed error from an adapter, kept as the `source` of port errors.
118pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;
okbot_core/lib.rs

okbot_core/
lib.rs
