Skip to main content

Crate motosan_agent_org

Crate motosan_agent_org 

Source
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). Ships InMemoryStore; behind sqlite-store, the durable SqliteStore.
  • Orchestrator — the engine. The host drives it by calling Orchestrator::tick on a cadence; each tick recovers orphaned runs, fires due schedules, dispatches agents concurrently, and finalizes runs.
  • runtime::AgentRuntime — how an agent actually executes (loop-runtime and cli-runtime bridge 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 as HeartbeatRun.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 terminal

See 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-memory Store.
  • sqlite-store — the durable SqliteStore (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 InMemoryStore and (Plan C) SqliteStore MUST pass run_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 OrgError is Plan B.
ids
Strongly-typed IDs (newtype Uuid) and Timestamp (epoch millis).
model
Domain models and their state machines (§4).
observe
Operational telemetry hook (§). The host implements OrgObserver to forward orchestrator signals (run lifecycle, tick, failures) to a metrics/log/trace backend. The crate ships only a NoopObserver; an embedder writes the adapter.
orchestrator
The orchestrator (§7): builder, public operations, and the tick state 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) and RuntimeError (Task 2) remain independent enums; OrgError unifies them for the public API.
policy
Pluggable policy hooks (§7.1). Defaults: CapBudgetPolicy (calendar-month cap vs. accumulated spend; NoBudgetPolicy is the allow-all opt-out), DefaultApprovalGate (None→pass, Operator→consult records), EnvSecretResolver (reads ANTHROPIC_API_KEY/OPENAI_API_KEY from env), ZeroPricingTable (record tokens, amount 0).
runtime
Agent runtime adapter contract (§6). Plan B ships the trait + support types and the testing MockRuntime; LoopRuntime (§6.1) is Plan D.
store
Persistence contract (§5). Embedders implement the whole Store or compose the official InMemoryStore. All methods are async and return StoreError.
testing
Deterministic test doubles. Available under #[cfg(test)] and the testing feature so integration tests and Plan C can reuse them.

Structs§

FileSessionStore
The loop runtime’s session-store API (from motosan-agent-loop), re-exported so embedders can persist LoopRuntime sessions across restarts without a direct dependency on the loop crate.
MemorySessionStore
The loop runtime’s session-store API (from motosan-agent-loop), re-exported so embedders can persist LoopRuntime sessions across restarts without a direct dependency on the loop crate.

Traits§

SessionStore
The loop runtime’s session-store API (from motosan-agent-loop), re-exported so embedders can persist LoopRuntime sessions across restarts without a direct dependency on the loop crate. Pluggable persistence backend for AgentSession history.