Crate talos_agent 

Talos agent — core orchestration logic and the agent turn loop.

The agent manages a conversation turn with an LLM provider, executing tool calls when the model requests them and feeding results back until a final text response is produced.

Security Pipeline

Every tool call goes through a security pipeline:

1. Permission check — the PermissionEngine evaluates the call
2. Sandbox execution — bash tools run through the sandbox when available
3. Execute — the tool is invoked directly
4. Retry on denial — denied calls return an error result

The Ask decision defaults to Deny at the agent level. Both the CLI layer and an embedded runtime may bridge Ask to an interactive approval handler; with no approval handler configured, Ask still fails closed (Deny).

Support Boundary

This crate owns the turn-loop implementation. It may be published to crates.io only to satisfy the talos-runtime dependency closure under ADR-052 (route A). It is not a recommended or supported SDK entrypoint.

• Embedders should use talos_runtime::RuntimeBuilder (in the talos-runtime facade crate) to construct a safe runtime that wraps permission, approval, and sandbox policy.
• Direct users of talos-agent bypass that wrapping and are themselves responsible for installing equivalent permission rules, an approval handler, and a sandbox policy.
• Its public constructors and configuration methods are NOT covered by the runtime SDK contract and may change more frequently than the facade surface during the pre-1.0 period.

See docs/reference/RUNTIME-SDK-CONTRACT.md for the supported embedding surface.

Re-exports

pub use compression::CompressionMetrics;

pub use compression::RetrievalMetrics;

pub use prompt::ActivatedSkillContext;

pub use prompt::ContextFile;

pub use prompt::SystemPromptBuilder;

pub use prompt::ToolDescription;

Modules

caching

Prompt caching strategy for provider-side caching.

compaction

5-layer context compaction for agent sessions.

compression

Deterministic output compression for tool results entering model context.

context

Context loader for AGENTS.md files.

prompt

System prompt assembly for the Talos agent.

session

AppServerSession actor — bridges SQ→Agent→EQ (ADR-005 L2 seam).

token

Token estimation and usage tracking for agent sessions.

Structs

Agent

The agent orchestrates a conversation turn: takes a user message, calls the LLM provider, streams events, executes tool calls when requested, and feeds results back until a final text response is produced.

PendingSchedulerActor

RequestBudgetSpec

Shared admission contract for one complete Provider request.

SandboxFallbackContext

A redacted, typed request for a sandbox fallback decision.

Enums

AgentError

Errors that can occur during agent execution.

SandboxFallbackDecision

A dedicated sandbox fallback decision. It intentionally has no permanent or reusable approval variant.

SandboxFallbackPolicy

Controls what happens when a configured sandbox is unavailable.

Traits

SandboxFallbackHandler

Resolves typed sandbox fallback requests independently of normal tool permission approval.

Functions

create_delay_tool_and_scheduler

create_scheduler_tools

Type Aliases

AgentResult

Result alias for agent operations.