Crate agent_engine 

agent-engine — streaming runtime, tools, MCP, skills, extensions, sidecar, events. Depends on agent-core + external crates only. Never depends on tui or bin.

Re-exports

pub use runtime::Runtime;

pub use tools::Tool;

pub use tools::ToolContext;

pub use tools::ToolRegistry;

Modules

auth

OAuth 2.0 Authorization Code + PKCE flow for Anthropic (Claude Pro/Max).

chain

Chain pointer management — named bookmarks that auto-advance on compaction.

config

core

Core infrastructure — config, session, auth, logging, error types, protocol.

engine

Engine — shared business logic for both TUI and headless modes.

error

events

Event Bus — universal message ingestion for agent sessions.

extensions

Extension system for SynapsCLI.

help

logging

mcp

MCP (Model Context Protocol) integration — JSON-RPC client, tool bridging, lazy loading.

memory

Local-first memory store.

models

Curated list of Claude models known to work with this CLI. Centralized so the settings dropdown, defaults, and subagent hints agree.

orchestration

pricing

Centralised pricing logic for Anthropic models.

protocol

runtime

session

sidecar

Sidecar plugin support: long-running plugin processes that stream events into the host over a JSONL line protocol.

skills

Skills and plugins subsystem.

tools

Tool system — trait, registry, and built-in tool implementations.

watcher_types

Structs

AgentConfig

Agent configuration parsed from config.toml

AgentStatusInfo

Runtime info for a single agent (for status display)

BoundedText

A byte-bounded, char-boundary-safe view of a string, with exact accounting of what was kept and what was cut.

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.

HandoffState

What the agent writes for its next self

Session

SessionInfo

Lightweight info for listing sessions without loading full message history

SessionLimits

SessionStats

Stats tracked per agent session

SynapsConfig

Parsed configuration from the config file.

TurnError

Typed terminal failure carried by SessionEvent::Error: the human-readable message plus the spec §5.2 TurnOutcome.

Enums

AgentEvent

BudgetDimension

Budget dimension placeholder (spec §5.2). The full turn-budget system is later work (spec §8.1); only the typed surface lands here so TurnOutcome::BudgetExceeded is representable without re-plumbing.

ExitReason

Why an agent session ended

LlmEvent

RuntimeError

SessionEvent

StreamEvent

Top-level stream event — grouped into concern-specific sub-enums.

TurnOutcome

Typed terminal outcome of a model turn (spec §5.2). Produced ONCE by the engine; every frontend (chat, TUI, RPC, server, watcher, subagents) receives the same value and must never re-derive it from message text.

Value

Represents any valid JSON value.

WatcherCommand

Commands sent from CLI to supervisor

WatcherResponse

Responses from supervisor to CLI

Functions

epoch_millis

Current time as Unix epoch milliseconds. Panics only if system clock is before 1970.

find_session

Find a session by full or partial ID match

find_session_by_name

Find a session by its assigned name (not partial ID). Iterates session headers one file at a time and returns on first match, avoiding a full directory scan when the named session appears early.

latest_session

Load the most recently updated session

list_recent_sessions

The limit most-recently-modified sessions (by file mtime), most-recent first. Sorts the directory entries by mtime WITHOUT parsing, then reads only the top limit headers — so /sessions is O(limit) reads instead of O(#sessions). mtime is an exact proxy for updated_at (the file is rewritten on every save).

list_sessions

List all sessions, sorted by most recently updated.

load_config

Parse the config file at ~/.synaps-cli/config (or profile variant). Returns default config if file doesn’t exist or can’t be read.

next_turn_correlation_id

Process-unique correlation ID for one engine turn. Ties the typed terminal outcome to metadata-only trace/log lines for the same turn.

resolve_session

Resolve a query string to a Session. Resolution order:

resolve_system_prompt

Resolve the system prompt from CLI flag, config file, or default. Priority: explicit value > ~/.synaps-cli/system.md > built-in default.

truncate_str

Truncate a string to at most max bytes at a valid UTF-8 boundary.

validate_name

Validate a session or chain name: [a-z0-9-]{1,40}.

Type Aliases

Result

SharedMessage

Reference-counted shared message payload. Introduced at the runtime’s inner boundary (T128 Slice 2) to enable clone-free fan-out of message history through the stream loop and SessionEvent::MessageHistory. Outer state (App/Session/ConversationState) remains Vec<Value> and shims at the boundary — see Slice 5 for full conversion.