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//! | [`Clock`] | [`SystemClock`], test clocks | everything that reads time |
17//!
18//! # Writing a channel
19//!
20//! A platform adapter implements [`Channel`]: receive events and hand them to the [`InboundSink`],
21//! send rendered replies. Everything else (policy, agents, knowledge) is the runtime's job.
22//!
23//! ```
24//! use std::sync::Arc;
25//! use okbot_core::{
26//!     async_trait, CancellationToken, Channel, ChannelCaps, ChannelError, ChannelId, InboundSink,
27//!     MessageId, RenderedMessage, ReplyTarget, SentRef,
28//! };
29//!
30//! struct EchoChannel { id: ChannelId, caps: ChannelCaps }
31//!
32//! #[async_trait]
33//! impl Channel for EchoChannel {
34//!     fn id(&self) -> &ChannelId { &self.id }
35//!     fn caps(&self) -> &ChannelCaps { &self.caps }
36//!
37//!     async fn run(&self, _sink: Arc<dyn InboundSink>, shutdown: CancellationToken)
38//!         -> Result<(), ChannelError> {
39//!         // Connect to the platform and call `sink.deliver(event)` for each message.
40//!         shutdown.cancelled().await;
41//!         Ok(())
42//!     }
43//!
44//!     async fn send(&self, to: &ReplyTarget, message: &RenderedMessage)
45//!         -> Result<SentRef, ChannelError> {
46//!         println!("{}", message.text);
47//!         Ok(SentRef { target: to.clone(), message_id: MessageId::new("1") })
48//!     }
49//! }
50//!
51//! let channel = EchoChannel { id: "echo:demo".parse().unwrap(), caps: ChannelCaps::basic() };
52//! assert_eq!(channel.id().to_string(), "echo:demo");
53//! ```
54#![deny(missing_docs)]
55
56mod agent;
57mod caps;
58mod channel;
59mod clock;
60mod id;
61mod knowledge;
62mod memory;
63mod message;
64mod notify;
65mod prompt;
66mod render;
67mod secret;
68mod store;
69mod task;
70mod webhook;
71
72pub use agent::{
73    AgentBackend, AgentError, AgentProgress, AgentReply, AgentTurn, McpServer, ProgressFn, Resume,
74    TokenUsage,
75};
76pub use caps::{AgentCaps, ChannelCaps, LengthUnit, MarkdownDialect, ToolPolicy};
77pub use channel::{Channel, ChannelError, CommandInfo, CommandParam, InboundSink, SinkClosed};
78pub use clock::{Clock, SystemClock};
79pub use id::{ChannelId, ConversationKey, IdError, MessageId, RunId, UserId, UserRef};
80pub use knowledge::{
81    KnowledgeContext, KnowledgeError, KnowledgeProvider, Person, Requester, RunGrant, RunInfo,
82};
83pub use memory::{MemoryEntry, MemoryError, MemoryNote, MemoryScope, MemoryStore};
84pub use message::{
85    Attachment, InboundEvent, OutboundMessage, RenderedMessage, ReplyTarget, SentRef,
86};
87pub use notify::NotifyTo;
88pub use prompt::{
89    ButtonStyle, FieldStyle, Form, FormField, MAX_BUTTONS, MAX_FIELDS, Prompt, PromptAnswer,
90    PromptButton,
91};
92pub use render::Renderer;
93pub use secret::{Redactor, Secret};
94pub use store::{
95    AgentRunRecord, ConversationStore, Fire, FireState, MessageRole, NewMessage,
96    PAIRING_MAX_FAILURES, RoleGrant, StoreError, StoredMessage, ToolCallRecord, ToolDecision,
97    Usage, person_key,
98};
99pub use task::{
100    NewTask, Repeat, Task, TaskChange, TaskError, TaskKind, TaskStatus, TaskStore, format_time,
101    parse_time, sort_tasks,
102};
103pub use webhook::{WebhookHandler, WebhookRequest, WebhookResponse};
104
105/// Re-exported so adapters use the same cancellation type as the runtime.
106pub use tokio_util::sync::CancellationToken;
107
108/// Re-exported so adapters implement the async traits with the same macro version.
109pub use async_trait::async_trait;
110
111/// A boxed error from an adapter, kept as the `source` of port errors.
112pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;
okbot_core/lib.rs

okbot_core/
lib.rs
