Crate telos_agent 

Core Rust runtime for telos.

telos_agent is a provider-agnostic agent runtime for applications that need the loop:

user intent -> model sampling -> tool execution -> result injection -> final answer

The crate is intended to be embedded by CLIs, desktop apps, servers, and workflow tools. The terminal client (telos-cli) and desktop prototype are hosts built on top of this library.

Primary API

Most consumers only need these types:

• AgentRuntime — owns the provider, tools, and runtime configuration.
• AgentSession — concurrency-safe conversation state created by the runtime.
• AgentConfig — configures cwd, env, storage, approvals, compaction, token budgets, policies, and cancellation.
• ModelProvider — trait implemented by LLM backends.
• DeepSeekProvider, RoutedProvider, and MockProvider — built-in provider implementations.
• Tool and ToolRegistry — define and register callable tools.
• TurnEvent — streaming UI/API event surface for assistant deltas, thinking deltas, tool lifecycle, retries, usage, approvals, and turn completion.
• Storage, JsonlStorage, and NoopStorage — session persistence.

Quick Start

Build an AgentConfig, create a ToolRegistry, pick a ModelProvider, then drive turns through AgentRuntime::run_turn or AgentRuntime::start_turn for a UI-friendly event stream.

use telos_agent::{
    AgentConfig, AgentError, AgentRuntime, CompletionResponse, Message,
    MockProvider, StopReason, ToolRegistry,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), AgentError> {
    let provider = Arc::new(MockProvider::new(vec![CompletionResponse {
        message: Message::assistant("done"),
        stop_reason: StopReason::EndTurn,
        usage: None,
        model: None,
    }]));

    let tools = ToolRegistry::new();
    let runtime = AgentRuntime::new(AgentConfig {
        base_system_prompt: Some("You are concise.".into()),
        ..Default::default()
    }, provider, tools)?;
    let session = runtime.create_session().await?;

    let result = runtime.run_turn(&session, "hello").await?;
    assert_eq!(result.final_message.text_content(), "done");
    Ok(())
}

Streaming Turns

Hosts that render live UI should use AgentRuntime::start_turn. Its TurnHandle yields TurnEvent values in order, so the host can update assistant text, thinking text, tool activity, approval prompts, token usage, and completion state without parsing model messages directly.

Extension Points

• Implement ModelProvider to add a new model backend.
• Implement Tool to expose a new capability.
• Implement ApprovalHandler for host-specific approval UI.
• Implement Policy to enforce semantic session, model, turn, or tool rules.
• Implement Storage for a custom persistence backend.
• Use McpManager and McpToolBridge to bridge MCP servers into the tool registry.

Public Module Map

The crate root re-exports the supported high-level API. Public modules are also available for advanced callers that need lower-level types.

Module	Purpose
agent	Runtime, sessions, turns, context, prompts, policies, and compaction.
model	Provider APIs, model messages, token counting, and test doubles.
tools	Tool APIs, execution, built-ins, approvals, permissions, and command safety.
knowledge	Memory, skills, tasks, and repository indexing.
integrations	MCP, plugins, and external event channels.
orchestration	Subagents and multi-agent teams.
diagnostics / metrics	Sanitized tool failure records and session counters.

Re-exports

pub use tools::approval::ApprovalDecision;

pub use tools::approval::ApprovalHandler;

pub use tools::approval::ApprovalRequest;

pub use tools::approval::AutoDenyHandler;

pub use tools::approval::FixedDecisionHandler;

pub use agent::compaction::HistoryCompactionStrategy;

pub use agent::compaction::SummaryHistoryCompaction;

pub use config::AgentConfig;

pub use config::TaskPath;

pub use config::TokenBudget;

pub use config::platform_base_env;

pub use diagnostics::JsonlToolDiagnosticsSink;

pub use diagnostics::NoopToolDiagnosticsSink;

pub use diagnostics::SanitizedToolFailure;

pub use diagnostics::ToolDiagnosticsSink;

pub use diagnostics::ToolFailureEvent;

pub use diagnostics::ToolFailureKind;

pub use diagnostics::ToolFailureSanitizer;

pub use error::AgentError;

pub use error::ProviderError;

pub use integrations::event_channel::EventChannel;

pub use integrations::event_channel::EventChannelConfig;

pub use integrations::event_channel::ExternalEvent;

pub use integrations::event_channel::Subscription;

pub use tools::executor::ToolExecutionEvent;

pub use tools::executor::ToolExecutionOutput;

pub use tools::executor::ToolExecutionStreamItem;

pub use tools::executor::execute_tool_calls_stream;

pub use agent::policies::Policy;

pub use agent::policies::PolicyContext;

pub use agent::policies::PolicyDecision;

pub use agent::policies::PolicyEntry;

pub use agent::policies::PolicyOutcome;

pub use agent::policies::PolicyPoint;

pub use agent::policies::PolicyRegistry;

pub use agent::policies::SessionMode;

pub use model::message::ContentBlock;

pub use model::message::Message;

pub use model::message::Role;

pub use model::message::TextBlock;

pub use model::message::ThinkingBlock;

pub use model::message::ToolCall;

pub use model::message::ToolResult;

pub use knowledge::memory::ProfileManager;

pub use knowledge::memory::MemoryCategory;

pub use knowledge::memory::MemoryEntry;

pub use knowledge::memory::MemoryFormat;

pub use knowledge::memory::MemoryMaintenanceAction;

pub use knowledge::memory::MemoryMaintenanceActionKind;

pub use knowledge::memory::MemoryMaintenancePolicy;

pub use knowledge::memory::MemoryMaintenanceReport;

pub use knowledge::memory::MemoryQuery;

pub use knowledge::memory::MemorySort;

pub use knowledge::memory::MemoryStatus;

pub use knowledge::memory::MemoryStore;

pub use knowledge::memory::UpsertOutcome;

pub use knowledge::memory::unix_timestamp;

pub use tools::builtin::MemoryEditTool;

pub use tools::builtin::MemoryGrepTool;

pub use tools::builtin::MemoryReadTool;

pub use tools::builtin::MemoryStatusTool;

pub use tools::builtin::MemoryWriteTool;

pub use knowledge::code_index::CodeContextLine;

pub use knowledge::code_index::CodeIndex;

pub use knowledge::code_index::CodeSearchMatch;

pub use knowledge::code_index::IndexedFile;

pub use config::CancellationState;

pub use metrics::SessionMetrics;

pub use model::mock::MockProvider;

pub use tools::permissions::PermissionEngine;

pub use tools::permissions::PermissionRule;

pub use tools::permissions::RuleDecision;

pub use model::provider::CompletionRequest;

pub use model::provider::CompletionResponse;

pub use model::provider::DeepSeekBalance;

pub use model::provider::DeepSeekBalanceInfo;

pub use model::provider::DeepSeekChatOptions;

pub use model::provider::DeepSeekConfig;

pub use model::provider::DeepSeekFimChoice;

pub use model::provider::DeepSeekFimRequest;

pub use model::provider::DeepSeekFimResponse;

pub use model::provider::DeepSeekModel;

pub use model::provider::DeepSeekModelList;

pub use model::provider::DeepSeekProvider;

pub use model::provider::DeepSeekResponseFormat;

pub use model::provider::ErasedProvider;

pub use model::provider::ModelHint;

pub use model::provider::ModelProvider;

pub use model::provider::ProviderEvent;

pub use model::provider::RoutedModelConfig;

pub use model::provider::RoutedProvider;

pub use model::provider::StopReason;

pub use model::provider::TokenUsage;

pub use agent::runtime::AgentRuntime;

pub use agent::runtime::AgentSession;

pub use agent::runtime::TurnHandle;

pub use agent::context::MemoryInjector;

pub use agent::context::SkillInjector;

pub use agent::turn::TurnEvent;

pub use agent::turn::TurnInputReceiver;

pub use agent::turn::TurnInputSender;

pub use agent::turn::TurnResult;

pub use agent::turn::turn_input_channel;

pub use knowledge::skills::Skill;

pub use knowledge::skills::SkillArg;

pub use knowledge::skills::SkillLoader;

pub use knowledge::skills::SkillRegistry;

pub use knowledge::skills::SkillSource;

pub use storage::JsonlStorage;

pub use storage::NoopStorage;

pub use storage::Storage;

pub use orchestration::subagent::AgentDefinition;

pub use orchestration::subagent::AgentIsolation;

pub use orchestration::subagent::AgentSource;

pub use orchestration::subagent::ForkExecution;

pub use orchestration::subagent::ForkLens;

pub use orchestration::subagent::ForkResult;

pub use orchestration::subagent::ForkShared;

pub use orchestration::subagent::SubagentRegistry;

pub use orchestration::subagent::SubagentTool;

pub use orchestration::subagent::Synapse;

pub use orchestration::subagent::register_subagent_tool;

pub use knowledge::tasks::Task;

pub use knowledge::tasks::TaskManager;

pub use knowledge::tasks::TaskStatus;

pub use orchestration::team::TeamConfig;

pub use orchestration::team::TeamMember;

pub use orchestration::team::cleanup_team;

pub use orchestration::team::has_active_members;

pub use orchestration::team::lead_agent_id;

pub use orchestration::team::load_team_config;

pub use orchestration::team::save_team_config;

pub use orchestration::team::team_config_path;

pub use orchestration::team::team_tasks_dir;

pub use orchestration::team::teams_root;

pub use integrations::mcp::McpClient;

pub use integrations::mcp::McpManager;

pub use integrations::mcp::McpTool;

pub use integrations::mcp::McpToolBridge;

pub use integrations::plugin::BUILTIN_MARKETPLACE;

pub use integrations::plugin::PluginError;

pub use integrations::plugin::PluginId;

pub use integrations::plugin::PluginPromptSection;

pub use integrations::plugin::PluginRegistry;

pub use agent::prompt::CwdSection;

pub use agent::prompt::DateSection;

pub use agent::prompt::GitStatusSection;

pub use agent::prompt::IdentitySection;

pub use agent::prompt::McpSection;

pub use agent::prompt::MemorySection;

pub use agent::prompt::ProfileSection;

pub use agent::prompt::PromptAssembly;

pub use agent::prompt::PromptProfile;

pub use agent::prompt::PromptSection;

pub use agent::prompt::PromptSectionStat;

pub use agent::prompt::PromptStability;

pub use agent::prompt::PromptStats;

pub use agent::prompt::SafetySection;

pub use agent::prompt::ShellAwareToolUsageSection;

pub use agent::prompt::SkillsSection;

pub use agent::prompt::TaskGuidanceSection;

pub use agent::prompt::ToneStyleSection;

pub use agent::prompt::ToolUsageSection;

pub use agent::prompt::ToolsSection;

pub use tools::api::validate::ValidationError;

pub use tools::api::validate::ValidationResult;

pub use tools::api::validate::validate_arguments;

pub use tools::api::InterruptBehavior;

pub use tools::api::PermissionDecision;

pub use tools::api::Tool;

pub use tools::api::ToolContext;

pub use tools::api::ToolDefinition;

pub use tools::api::ToolOutput;

pub use tools::api::ToolProgress;

pub use tools::api::ToolRegistry;

pub use tools::builtin::AskUserQuestionTool;

pub use tools::builtin::BrowserBackTool;

pub use tools::builtin::BrowserClickTool;

pub use tools::builtin::BrowserCloseTool;

pub use tools::builtin::BrowserFindUrlTool;

pub use tools::builtin::BrowserManager;

pub use tools::builtin::BrowserNavigateTool;

pub use tools::builtin::BrowserScreenshotTool;

pub use tools::builtin::BrowserScrollTool;

pub use tools::builtin::BrowserSelectTool;

pub use tools::builtin::BrowserStartTool;

pub use tools::builtin::BrowserStateTool;

pub use tools::builtin::BrowserTypeTool;

pub use tools::builtin::CodeContextTool;

pub use tools::builtin::CodeIndexRefreshTool;

pub use tools::builtin::CodeSearchTool;

pub use tools::builtin::DefaultShell;

pub use tools::builtin::EnterPlanModeTool;

pub use tools::builtin::ExitPlanModeTool;

pub use tools::builtin::FileEditTool;

pub use tools::builtin::FileReadTool;

pub use tools::builtin::FileWriteTool;

pub use tools::builtin::GlobTool;

pub use tools::builtin::GrepTool;

pub use tools::builtin::PowerShellTool;

pub use tools::builtin::SendUserMessageTool;

pub use tools::builtin::ShellTool;

pub use tools::builtin::SkillTool;

pub use tools::builtin::TaskCreateTool;

pub use tools::builtin::TaskGetTool;

pub use tools::builtin::TaskListTool;

pub use tools::builtin::TaskOutputTool;

pub use tools::builtin::TaskStopTool;

pub use tools::builtin::TaskUpdateTool;

pub use tools::builtin::TeamCreateTool;

pub use tools::builtin::TeamDeleteTool;

pub use tools::builtin::TodoWriteTool;

pub use tools::builtin::WebFetchTool;

pub use tools::builtin::WebSearchTool;

pub use tools::builtin::register_core_tools;

pub use tools::builtin::register_core_tools_with_shell;

pub use tools::builtin::register_memory_tools;

pub use tools::builtin::register_task_tools;

Modules

agent

Agent lifecycle, context, prompting, policies, and turn execution. Agent lifecycle, context management, prompting, policies, and turn execution.

config

Runtime configuration and cancellation state. Configuration types for an AgentSession.

diagnostics

Sanitized tool failure diagnostics. Structured diagnostics for tool execution failures.

error

Error types shared across runtime, tools, and providers. Unified error type for the crate.

integrations

External event, protocol, and plugin integrations. External event, protocol, and plugin integrations.

knowledge

Persistent knowledge, skills, tasks, and repository indexing. Persistent knowledge, skills, tasks, and repository indexing.

metrics

Runtime metrics accumulated by sessions. Session-level metrics — lightweight counters updated by the runtime.

model

Model messages, providers, token accounting, and test doubles. Model-facing messages, providers, token accounting, and test doubles.

orchestration

Nested-agent and multi-agent orchestration. Nested-agent and multi-agent orchestration.

storage

Session persistence backends. Session storage for persisting and resuming agent conversations.

tools

Tool APIs, execution, built-ins, approvals, permissions, and command safety. Tool APIs, execution, built-ins, approvals, permissions, and command safety.