Lightweight coding agent that runs in your terminal
Rust
Add template setup for local agent message boards (#52621)
jif47b80571f0d6
diff --git a/codex-rs/ext/agent-message-board/README.md b/codex-rs/ext/agent-message-board/README.mdnew file mode 100644index 0000000000..ca36ab393e--- /dev/null+++ b/codex-rs/ext/agent-message-board/README.md@@ -0,0 +1,27 @@+# Load a local board template++Create an empty chat, then load its initial channels before starting the agents:++```sh+just agent-board-config ~/.codex <root-session-id> /absolute/path/setup.json+```++Use the same SQLite home as Codex (`sqlite_home`, normally `$CODEX_HOME` or+`~/.codex`). Example `setup.json`:++```json+{+ "template": {+ "version": 1,+ "channels": { "policy": { "description": "Shared policies" } }+ }+}+```++The template and channels are saved atomically. Repeating the same setup is safe;+a different template or an already-used board is rejected. The pinned setup+survives reopen. An optional top-level `timestamp` sets the initial creation time;+otherwise it uses UTC now.++This loads channels and descriptions only. ACLs and roles are not accepted by+this version; existing agent access stays unchanged.diff --git a/codex-rs/ext/agent-message-board/examples/configure_board.rs b/codex-rs/ext/agent-message-board/examples/configure_board.rsnew file mode 100644index 0000000000..5f042d420b--- /dev/null+++ b/codex-rs/ext/agent-message-board/examples/configure_board.rs@@ -0,0 +1,27 @@+//! Operator-only setup for local experiments; no administrative agent tools.++use codex_agent_message_board_extension::LocalBoardSetup;+use codex_agent_message_board_extension::configure_local_board;+use codex_protocol::SessionId;+use codex_state::SqliteConfig;+use std::path::PathBuf;++#[tokio::main]+async fn main() -> Result<(), Box<dyn std::error::Error>> {+ let args: Vec<_> = std::env::args_os().collect();+ let [_, sqlite_home, board, input] = args.as_slice() else {+ return Err("Usage: configure_board <sqlite-home> <board-session-id> <setup.json>".into());+ };+ let sqlite = SqliteConfig::from_sqlite_home(+ std::path::absolute(PathBuf::from(sqlite_home))?.try_into()?,+ );+ let board = SessionId::from_string(board.to_str().ok_or("invalid board ID")?)?;+ let input = tokio::fs::read(input).await?;+ if input.len() > 64 * 1024 {+ return Err("setup file exceeds 64 KiB".into());+ }+ let setup: LocalBoardSetup = serde_json::from_slice(&input)?;+ configure_local_board(&sqlite, board, setup).await?;+ println!("Configured local board {board}");+ Ok(())+}diff --git a/codex-rs/ext/agent-message-board/src/lib.rs b/codex-rs/ext/agent-message-board/src/lib.rsindex 78e0e0d09b..d4221d4b63 100644--- a/codex-rs/ext/agent-message-board/src/lib.rs+++ b/codex-rs/ext/agent-message-board/src/lib.rs@@ -34,6 +34,8 @@ pub use host::NotificationDelivery;pub use in_memory::InMemoryAgentMessageBoard;pub use in_memory::InMemoryMessageBoards;pub use local::LocalAgentMessageBoard;+pub use local::setup::LocalBoardSetup;+pub use local::setup::configure_local_board;pub use permissions::BoardPermissions;pub use permissions::ChannelPermissions;pub use permissions::PermissionDenied;diff --git a/codex-rs/ext/agent-message-board/src/local.rs b/codex-rs/ext/agent-message-board/src/local.rsindex 56f90b81eb..7e817861a2 100644--- a/codex-rs/ext/agent-message-board/src/local.rs+++ b/codex-rs/ext/agent-message-board/src/local.rs@@ -45,7 +45,9 @@ use uuid::Uuid;mod lifecycle;mod paging;+mod pool;mod queries;+pub(crate) mod setup;#[cfg(test)]#[path = "local/pools_tests.rs"]@@ -61,6 +63,7 @@ const DATABASE_FILE: &str = "agent_message_board_1.sqlite";static POOLS: LazyLock<Mutex<HashMap<PathBuf, Weak<SqlitePool>>>> = LazyLock::new(Mutex::default);const SCHEMA: &str = "+CREATE TABLE IF NOT EXISTS board_templates (board TEXT PRIMARY KEY NOT NULL, template TEXT NOT NULL);CREATE TABLE IF NOT EXISTS deleted_boards (board TEXT PRIMARY KEY NOT NULL);CREATE TABLE IF NOT EXISTS channels (board TEXT NOT NULL, name TEXT NOT NULL, name_search TEXT NOT NULL, created_at TEXT NOT NULL, timestamp INTEGER NOT NULL, author TEXT NOT NULL, description TEXT,@@ -104,60 +107,14 @@ struct StoredPost {impl LocalAgentMessageBoard {/// Reopens the same board for a root, child or resumed runtime. The shared/// SQLite configuration preserves the host's connection and journal policy.- #[expect(- clippy::await_holding_invalid_type,- reason = "pool creation and schema initialization stay serialized to avoid duplicate pools"- )]pub async fn open(sqlite: &SqliteConfig,identity: SessionId,host: Arc<dyn MessageBoardHost>,) -> Result<Self> {- tokio::fs::create_dir_all(sqlite.home()).await?;- let path = tokio::fs::canonicalize(sqlite.home())- .await?- .join(DATABASE_FILE);- let mut pools = POOLS.lock().await;- pools.retain(|_, pool| pool.strong_count() > 0);- let pool = if let Some(pool) = pools- .get(&path)- .and_then(Weak::upgrade)- .filter(|pool| !pool.is_closed())- {- pool- } else {- let pool = sqlite- .open_read_write_pool(&path)- .await- .map_err(storage_error)?;- let mut tx = pool- .begin_with("BEGIN IMMEDIATE")- .await- .map_err(storage_error)?;- sqlx::raw_sql(SCHEMA)- .execute(&mut *tx)- .await- .map_err(storage_error)?;- let has_description: bool = sqlx::query_scalar(- "SELECT EXISTS(SELECT 1 FROM pragma_table_info('channels') WHERE name='description')",- )- .fetch_one(&mut *tx)- .await- .map_err(storage_error)?;- if !has_description {- sqlx::query("ALTER TABLE channels ADD COLUMN description TEXT")- .execute(&mut *tx)- .await- .map_err(storage_error)?;- }- tx.commit().await.map_err(storage_error)?;- let pool = Arc::new(pool);- pools.insert(path, Arc::downgrade(&pool));- pool- };Ok(Self {identity,- pool,+ pool: pool::open(sqlite).await?,host,})}diff --git a/codex-rs/ext/agent-message-board/src/local/lifecycle.rs b/codex-rs/ext/agent-message-board/src/local/lifecycle.rsindex d44109de9c..f60fd65d5c 100644--- a/codex-rs/ext/agent-message-board/src/local/lifecycle.rs+++ b/codex-rs/ext/agent-message-board/src/local/lifecycle.rs@@ -77,6 +77,7 @@ impl LocalAgentMessageBoard {"DELETE FROM subscription_opt_outs WHERE board=?","DELETE FROM posts WHERE board=?","DELETE FROM channels WHERE board=?",+ "DELETE FROM board_templates WHERE board=?",] {sqlx::query(statement).bind(root.to_string())diff --git a/codex-rs/ext/agent-message-board/src/local/pool.rs b/codex-rs/ext/agent-message-board/src/local/pool.rsnew file mode 100644index 0000000000..ba4d978a2d--- /dev/null+++ b/codex-rs/ext/agent-message-board/src/local/pool.rs@@ -0,0 +1,61 @@+//! Shared SQLite initialization used by runtime handles and local experiment setup.++use super::DATABASE_FILE;+use super::POOLS;+use super::SCHEMA;+use super::storage_error;+use codex_protocol::error::Result;+use codex_state::SqliteConfig;+use sqlx::SqlitePool;+use std::sync::Arc;+use std::sync::Weak;++#[expect(+ clippy::await_holding_invalid_type,+ reason = "serialize shared pool initialization"+)]+pub(super) async fn open(sqlite: &SqliteConfig) -> Result<Arc<SqlitePool>> {+ tokio::fs::create_dir_all(sqlite.home()).await?;+ let path = tokio::fs::canonicalize(sqlite.home())+ .await?+ .join(DATABASE_FILE);+ let mut pools = POOLS.lock().await;+ pools.retain(|_, pool| pool.strong_count() > 0);+ let pool = if let Some(pool) = pools+ .get(&path)+ .and_then(Weak::upgrade)+ .filter(|pool| !pool.is_closed())+ {+ pool+ } else {+ let pool = sqlite+ .open_read_write_pool(&path)+ .await+ .map_err(storage_error)?;+ let mut tx = pool+ .begin_with("BEGIN IMMEDIATE")+ .await+ .map_err(storage_error)?;+ sqlx::raw_sql(SCHEMA)+ .execute(&mut *tx)+ .await+ .map_err(storage_error)?;+ let has_description: bool = sqlx::query_scalar(+ "SELECT EXISTS(SELECT 1 FROM pragma_table_info('channels') WHERE name='description')",+ )+ .fetch_one(&mut *tx)+ .await+ .map_err(storage_error)?;+ if !has_description {+ sqlx::query("ALTER TABLE channels ADD COLUMN description TEXT")+ .execute(&mut *tx)+ .await+ .map_err(storage_error)?;+ }+ tx.commit().await.map_err(storage_error)?;+ let pool = Arc::new(pool);+ pools.insert(path, Arc::downgrade(&pool));+ pool+ };+ Ok(pool)+}diff --git a/codex-rs/ext/agent-message-board/src/local/setup.rs b/codex-rs/ext/agent-message-board/src/local/setup.rsnew file mode 100644index 0000000000..eca2410978--- /dev/null+++ b/codex-rs/ext/agent-message-board/src/local/setup.rs@@ -0,0 +1,109 @@+//! Loads initial channels into an empty local board and pins their source template.++use super::invalid;+use super::storage_error;+use super::validate_channel;+use crate::ChannelDescription;+use chrono::DateTime;+use chrono::Utc;+use codex_protocol::SessionId;+use codex_protocol::error::Result;+use codex_state::SqliteConfig;+use serde::Deserialize;+use serde::Serialize;+use std::collections::BTreeMap;++#[derive(Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+struct Channel {+ #[serde(default, skip_serializing_if = "Option::is_none")]+ description: Option<ChannelDescription>,+}++#[derive(Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+struct Template {+ version: u32,+ #[serde(default)]+ channels: BTreeMap<String, Channel>,+}++/// Operator input for loading an empty board. This is not an agent tool.+#[derive(Deserialize)]+#[serde(deny_unknown_fields)]+pub struct LocalBoardSetup {+ #[serde(default)]+ timestamp: Option<DateTime<Utc>>,+ template: Template,+}++/// Saves the template and its initial channels atomically. The same template is+/// safe to retry; replacing it or initializing an already-used board is rejected.+pub async fn configure_local_board(+ sqlite: &SqliteConfig,+ board: SessionId,+ setup: LocalBoardSetup,+) -> Result<()> {+ let template = setup.template;+ let encoded = serde_json::to_string(&template).map_err(storage_error)?;+ if template.version != 1 || encoded.len() > 64 * 1024 || template.channels.len() > 64 {+ return Err(invalid(+ "board templates require version 1 and at most 64 KiB / 64 channels",+ ));+ }+ for name in template.channels.keys() {+ validate_channel(name)?;+ }+ let pool = super::pool::open(sqlite).await?;+ let mut tx = pool+ .begin_with("BEGIN IMMEDIATE")+ .await+ .map_err(storage_error)?;+ let board = board.to_string();+ let deleted: bool =+ sqlx::query_scalar("SELECT EXISTS(SELECT 1 FROM deleted_boards WHERE board=?)")+ .bind(&board)+ .fetch_one(&mut *tx)+ .await+ .map_err(storage_error)?;+ if deleted {+ return Err(invalid("the board has been permanently deleted"));+ }+ let pinned: Option<String> =+ sqlx::query_scalar("SELECT template FROM board_templates WHERE board=?")+ .bind(&board)+ .fetch_optional(&mut *tx)+ .await+ .map_err(storage_error)?;+ if let Some(pinned) = pinned {+ if pinned != encoded {+ return Err(invalid("the board template is already pinned"));+ }+ } else {+ let used: bool = sqlx::query_scalar("SELECT EXISTS(SELECT 1 FROM channels WHERE board=?)")+ .bind(&board)+ .fetch_one(&mut *tx)+ .await+ .map_err(storage_error)?;+ if used {+ return Err(invalid(+ "pin the template before creating channels or posts",+ ));+ }+ sqlx::query("INSERT INTO board_templates(board,template) VALUES(?,?)")+ .bind(&board)+ .bind(encoded)+ .execute(&mut *tx)+ .await+ .map_err(storage_error)?;+ let now = setup.timestamp.unwrap_or_else(Utc::now);+ for (name, channel) in &template.channels {+ sqlx::query("INSERT INTO channels(board,name,name_search,created_at,timestamp,author,description) VALUES(?,?,?,?,?,'/root',?)")+ .bind(&board).bind(name).bind(caseless::default_case_fold_str(name))+ .bind(now.to_rfc3339()).bind(now.timestamp_micros())+ .bind(channel.description.as_ref().map(ChannelDescription::as_str))+ .execute(&mut *tx).await.map_err(storage_error)?;+ }+ }+ tx.commit().await.map_err(storage_error)+}diff --git a/codex-rs/ext/agent-message-board/tests/local_board.rs b/codex-rs/ext/agent-message-board/tests/local_board.rsindex 002bb7df49..f68c2feba4 100644--- a/codex-rs/ext/agent-message-board/tests/local_board.rs+++ b/codex-rs/ext/agent-message-board/tests/local_board.rs@@ -1498,3 +1498,72 @@ async fn channel_descriptions_migrate_legacy_storage_and_survive_reopen() {});}++#[tokio::test]+async fn local_board_setup_survives_reopen() -> Result<()> {+ use serde_json::json;+ let dir = tempfile::tempdir()?;+ let sqlite = SqliteConfig::new_for_testing(dir.path().to_path_buf().try_into().unwrap());+ let root = ThreadId::new();+ let host = Arc::new(Host {+ clock: AtomicI64::default(),+ agent_path_calls: AtomicUsize::default(),+ members: [(root, AgentPath::root())].into(),+ active: AtomicBool::new(true),+ fail_notifications: AtomicBool::new(false),+ notifications: Mutex::default(),+ });+ let setup = json!({"timestamp":"2026-09-18T12:00:00Z","template":{"version":1,"channels":{"policy":{"description":"Shared policies"}}}});+ configure_local_board(&sqlite, root.into(), serde_json::from_value(setup.clone())?).await?;+ configure_local_board(&sqlite, root.into(), serde_json::from_value(setup.clone())?).await?;+ let board = LocalAgentMessageBoard::open(&sqlite, root.into(), host.clone()).await?;+ drop(board);+ let board = LocalAgentMessageBoard::open(&sqlite, root.into(), host.clone()).await?;+ let query = ChannelQuery {+ query: None,+ direction: SortDirection::NewestFirst,+ page: PageRequest::default(),+ };+ let channels = board.list_channels(root, query.clone()).await?;+ assert_eq!(+ serde_json::to_value(channels)?,+ json!({"results":[{+ "channel_name":"policy", "description":"Shared policies", "created_at":"2026-09-18T12:00:00Z",+ "created_by":"/root", "message_count":0, "last_message_id":null+ }],"n_returned":1,"has_more":false,"next_cursor":null})+ );+ let mut changed = setup.clone();+ changed["template"]["channels"]["policy"]["description"] = json!("Changed");+ assert!(+ configure_local_board(&sqlite, root.into(), serde_json::from_value(changed)?)+ .await+ .is_err()+ );+ board+ .create_channel(+ root,+ CreateChannelRequest {+ channel_name: "new".into(),+ description: None,+ subscription: SubscriptionChange::Unsubscribe,+ },+ )+ .await?;+ configure_local_board(&sqlite, root.into(), serde_json::from_value(setup.clone())?).await?;+ assert_eq!(+ board+ .list_channels(root, query)+ .await?+ .channels+ .results+ .len(),+ 2+ );+ LocalAgentMessageBoard::delete_boards(&sqlite, &[root.into()]).await?;+ assert!(+ configure_local_board(&sqlite, root.into(), serde_json::from_value(setup)?)+ .await+ .is_err()+ );+ Ok(())+}