Expand description
motosan-agent-org — an embeddable control plane for organizations of AI agents.
A host embeds this library to run a company of AI agents that pick up
issues, execute them through a pluggable runtime, and report back. Budgets,
approval gates, retries, recurring schedules, observability, and a dead-letter
inbox are handled by the control plane — not the host.
§Architecture
Store— the persistence contract (companies, agents, projects, goals, issues, schedules, runs, wakeups, costs, approvals, activity). ShipsInMemoryStore; behindsqlite-store, the durableSqliteStore.Orchestrator— the engine. The host drives it by callingOrchestrator::tickon a cadence; each tick recovers orphaned runs, fires due schedules, dispatches agents concurrently, and finalizes runs.runtime::AgentRuntime— how an agent actually executes (loop-runtimeandcli-runtimebridge real LLM backends; tests use a mock).OrgObserver— a synchronous telemetry hook for run/tick/failure signals.Orchestrator::dead_letters— paginated inbox of unacked permanently-failed issues, attributed to an escalation owner (the failed agent’s manager, or the operator).- Multi-tenancy & integrity — one store hosts many companies; store mutations reject
cross-company links (
StoreError::Conflict) and dangling references (StoreError::NotFound), so an agent only ever touches its own company’s entities. - Session resume — a run’s session is keyed by
session_key(agent, issue)(recorded asHeartbeatRun.session_ref); a run re-dispatched on the same issue (heartbeat, retry, or orphan recovery) resumes the same conversation. Cross-process resume needs a persistent session store (the defaults are in-memory).
§Quickstart
ⓘ
let orch = Orchestrator::builder().store(store).runtime("mock", rt).build()?;
let company = orch.create_company(NewCompany { name: "ACME".into(), mission: None }).await?;
let agent = orch.hire(new_agent).await?;
let issue = orch.create_issue(new_issue_assigned_to(agent.id)).await?;
loop { orch.tick(clock.now()).await?; } // until the issue is terminalSee examples/lifecycle.rs for a runnable end-to-end scenario (a recurring
schedule fires an issue, an observer watches the run, the run fails, and the
issue lands in the dead-letter inbox).
§Feature flags
memory-store(default) — the in-memoryStore.sqlite-store— the durableSqliteStore(WAL, single-writer pool).loop-runtime(+backend-anthropic/backend-openai) — LoopRuntime over a real LLM.cli-runtime— drive CLI agents (claude / codex / gemini) directly.cron— cron-expression schedule recurrence (RecurrenceRule::Cron) with a per-schedule IANA timezone (DST-aware).testing— mock clock / id-gen / runtime + the trait-generic conformance suite.
The default build pulls in no LLM backend (invariant I-10).
Re-exports§
pub use ids::ActivityId;pub use ids::AgentId;pub use ids::CompanyId;pub use ids::GoalId;pub use ids::IssueId;pub use ids::ProjectId;pub use ids::RunId;pub use ids::ScheduleId;pub use ids::Timestamp;pub use ids::WakeupId;pub use actor::Actor;pub use clock::Clock;pub use clock::IdGen;pub use clock::RandomIdGen;pub use clock::SystemClock;pub use error::StoreError;pub use observe::IssueFailed;pub use observe::NoopObserver;pub use observe::OrgObserver;pub use observe::RunFinished;pub use observe::RunStarted;pub use store::ActivityStore;pub use store::AgentStore;pub use store::ApprovalStore;pub use store::CompanyStore;pub use store::CostStore;pub use store::DeadLetterStore;pub use store::GoalStore;pub use store::IssueStore;pub use store::ProjectStore;pub use store::RunStore;pub use store::Store;pub use store::WakeupStore;pub use store::InMemoryStore;pub use store::SqliteStore;pub use runtime::session_key;pub use runtime::AgentRuntime;pub use runtime::CancellationToken;pub use runtime::RunContext;pub use runtime::RunEventSink;pub use runtime::RuntimeError;pub use runtime::SecretBundle;pub use runtime::SecretString;pub use runtime::loop_runtime::EngineFactory;pub use runtime::loop_runtime::LlmFactory;pub use runtime::loop_runtime::LoopRuntime;pub use runtime::loop_runtime::LoopRuntimeBuilder;pub use runtime::cli_runtime::CliRuntime;pub use runtime::cli_runtime::CliRuntimeBuilder;pub use runtime::cli_runtime::CliSessionStore;pub use runtime::cli_runtime::FileCliSessionStore;pub use runtime::cli_runtime::MemoryCliSessionStore;pub use org_error::OrgError;pub use org_error::OrgResult;pub use context::assemble_context;pub use context::AssembledContext;pub use context::LineageItem;pub use context::LineageKind;pub use runtime::mock::MockCall;pub use runtime::mock::MockReply;pub use runtime::mock::MockRuntime;pub use policy::ApprovalGate;pub use policy::BudgetPolicy;pub use policy::DefaultApprovalGate;pub use policy::EnvSecretResolver;pub use policy::GateOutcome;pub use policy::NoBudgetPolicy;pub use policy::PricingTable;pub use policy::SecretResolver;pub use policy::ZeroPricingTable;pub use orchestrator::OrchestratorConfig;pub use orchestrator::RetrySchedule;pub use orchestrator::AgentView;pub use orchestrator::BuildError;pub use orchestrator::DeadLetter;pub use orchestrator::DeadLetterPage;pub use orchestrator::Orchestrator;pub use orchestrator::OrchestratorBuilder;pub use orchestrator::PendingApproval;pub use orchestrator::RecoverReport;pub use orchestrator::SkipReason;pub use orchestrator::TickReport;
Modules§
- actor
- The operator/agent/system actor attributed to every mutation (§3).
- clock
- Injectable time and id sources (§3).
- conformance
- Trait-generic store conformance suite (§11.1). Both
InMemoryStoreand (Plan C)SqliteStoreMUST passrun_store_conformance— so every invariant we care about lives HERE, not in store-specific unit tests. - context
- Context assembly (§8). Produces the system-prompt fragment + structured lineage (nearest-first) injected into a run.
- error
- Persistence-layer error (§9). Orchestrator-level
OrgErroris Plan B. - ids
- Strongly-typed IDs (newtype
Uuid) andTimestamp(epoch millis). - model
- Domain models and their state machines (§4).
- observe
- Operational telemetry hook (§). The host implements
OrgObserverto forward orchestrator signals (run lifecycle, tick, failures) to a metrics/log/trace backend. The crate ships only aNoopObserver; an embedder writes the adapter. - orchestrator
- The orchestrator (§7): builder, public operations, and the
tickstate machine. Pure core — no runtime/LLM/HTTP deps (I-10).tick(now)is the single advancement primitive; the embedder drives it. - org_
error - Orchestrator-level error (§9).
StoreError(Plan A) andRuntimeError(Task 2) remain independent enums;OrgErrorunifies them for the public API. - policy
- Pluggable policy hooks (§7.1). Defaults:
CapBudgetPolicy(calendar-month cap vs. accumulated spend;NoBudgetPolicyis the allow-all opt-out),DefaultApprovalGate(None→pass, Operator→consult records),EnvSecretResolver(readsANTHROPIC_API_KEY/OPENAI_API_KEYfrom env),ZeroPricingTable(record tokens, amount 0). - runtime
- Agent runtime adapter contract (§6). Plan B ships the trait + support types
and the
testingMockRuntime;LoopRuntime(§6.1) is Plan D. - store
- Persistence contract (§5). Embedders implement the whole
Storeor compose the officialInMemoryStore. All methods are async and returnStoreError. - testing
- Deterministic test doubles. Available under
#[cfg(test)]and thetestingfeature so integration tests and Plan C can reuse them.
Structs§
- File
Session Store - The loop runtime’s session-store API (from
motosan-agent-loop), re-exported so embedders can persistLoopRuntimesessions across restarts without a direct dependency on the loop crate. - Memory
Session Store - The loop runtime’s session-store API (from
motosan-agent-loop), re-exported so embedders can persistLoopRuntimesessions across restarts without a direct dependency on the loop crate.
Traits§
- Session
Store - The loop runtime’s session-store API (from
motosan-agent-loop), re-exported so embedders can persistLoopRuntimesessions across restarts without a direct dependency on the loop crate. Pluggable persistence backend forAgentSessionhistory.