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 render;
65mod secret;
66mod store;
67mod task;
68mod webhook;
69
70pub use agent::{
71    AgentBackend, AgentError, AgentProgress, AgentReply, AgentTurn, McpServer, ProgressFn, Resume,
72    TokenUsage,
73};
74pub use caps::{AgentCaps, ChannelCaps, LengthUnit, MarkdownDialect, ToolPolicy};
75pub use channel::{Channel, ChannelError, InboundSink, SinkClosed};
76pub use clock::{Clock, SystemClock};
77pub use id::{ChannelId, ConversationKey, IdError, MessageId, RunId, UserId, UserRef};
78pub use knowledge::{
79    KnowledgeContext, KnowledgeError, KnowledgeProvider, Person, Requester, RunGrant, RunInfo,
80};
81pub use memory::{MemoryEntry, MemoryError, MemoryNote, MemoryScope, MemoryStore};
82pub use message::{
83    Attachment, InboundEvent, OutboundMessage, RenderedMessage, ReplyTarget, SentRef,
84};
85pub use render::Renderer;
86pub use secret::{Redactor, Secret};
87pub use store::{
88    AgentRunRecord, ConversationStore, Fire, FireState, MessageRole, NewMessage,
89    PAIRING_MAX_FAILURES, StoreError, StoredMessage,
90};
91pub use task::{
92    NewTask, Repeat, Task, TaskChange, TaskError, TaskKind, TaskStatus, TaskStore, format_time,
93    parse_time, sort_tasks,
94};
95pub use webhook::{WebhookHandler, WebhookRequest, WebhookResponse};
96
97/// Re-exported so adapters use the same cancellation type as the runtime.
98pub use tokio_util::sync::CancellationToken;
99
100/// Re-exported so adapters implement the async traits with the same macro version.
101pub use async_trait::async_trait;
102
103/// A boxed error from an adapter, kept as the `source` of port errors.
104pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;
okbot_core/lib.rs

okbot_core/
lib.rs
