Module session 

Session — state container and lifecycle interface for a single conversation.

Abstraction layers

• AgentCore: process-level “agent instance”, holds the built-in tool set and global configuration; it is the root object assembled by defect-cli and injected into defect-acp::serve
• Session: lifecycle unit for a single conversation; holds history, per-session tool table (including MCP), cancel token, and event stream
• History: wrapper around message history, with hooks reserved for compression, token counting, and resume

All three are exposed as traits; concrete implementations live in the session/ submodule within this crate and at the assembly point in defect-cli; defect-acp interacts with them only through the traits.

Structs

AllowlistMatch

The result of matching a profile tool allowlist against a tool pool.

BackgroundOutcome

The outcome produced after a background task completes.

BackgroundProgressConfig

Configuration for the background task progress view.

BackgroundTasks

Session-level background task table. Clone is cheap (inner Arc) — DefaultSession holds one copy, cloned to tools via ToolContext.

BasePromptConfig

CompactionReport

Compaction report. The token counts before and after compaction are wrapped into AgentEvent::ContextCompressed by the main loop.

CompactionSlot

A session-level background compaction slot. Clone is cheap (internally an Arc).

CompositeRegistry

A “composite” view of the process-level and session-level registries.

ContextStatus

Snapshot of the session’s context usage, returned by Session::context_status. Powers the /context slash command (and any client-side context gauge).

DefaultAgentCore

Default AgentCore.

DefaultAgentCoreBuilder

DefaultSession

EventEmitter

Event bus. One instance per session.

GoalState

Shared state for one goal-driven loop.

LoadedSession

Minimal session data restored from persistent storage.

ModeDescriptor

A public description of an optional permission mode. Used by defect-acp to construct an ACP SessionMode.

ModelSelection

Model selection key: a (provider vendor, model id) pair.

PermissionGate

A registry of pending permission requests.

ProgressBlock

A single progress block returned by peek: kind + text summary (truncated per configuration).

PromptConfig

ResolvedSessionCapabilities

Runtime capabilities resolved at session startup.

RunningContext

Injects runtime environment context into the system prompt.

SessionCapabilitiesConfig

Entry point for session-level capability configuration.

SessionCreateInfo

Stable information provided to SessionObserver after successful creation.

StaticToolRegistry

An immutable mapping from names to tools.

StaticToolRegistryBuilder

A builder for StaticToolRegistry.

TaskHandle

A handle given to a background task, allowing it to share its history Arc into the task table so the control plane can peek at the message chunks it submits to the LLM. Clone is cheap (inner Arc + small string).

TaskSnapshot

A snapshot of a task in the control plane (returned by list / peek).

TurnConfig

Configuration for a turn.

TurnRunner

All dependencies and accumulated state for a single turn execution.

VecHistory

A History implementation backed by Vec<Message> + Mutex, with token accounting.

WebSearchCapabilityConfig

Configuration for a single capability. Reserved for future capabilities of the same form, such as image_generation / code_execution.

Enums

AgentError

Process-level agent error.

BackgroundResult

The final result of a background task.

BlockKind

The role/category of a progress block. Directly corresponds to the content of a crate::llm::Message submitted to the LLM.

Frontend

How the agent is connected — determines its understanding of the file and command execution environment.

SessionInitError

A one-time adjudication failure during session startup.

TaskStatus

Lifecycle status of a background task, exposed via the inspect_background_task control plane.

TurnError

Reasons why a turn fails.

TurnRequestLimit

Strategy for capping LLM calls.

WebSearchCapabilityMode

Toggle for hosted web search capability.

Traits

AgentCore

Process-level agent root object.

History

Abstraction over message history — pure storage + token accounting.

Session

A single session.

SessionLoader

Abstraction for restoring a session from persistent storage.

SessionObserver

Observer for when AgentCore::create_session succeeds.

SessionToolFactory

Abstraction for building an additional tool registry for a single session.

ToolRegistry

Abstraction for a tool registry.

Functions

filter_registry_by_allowlist

Restricts a base registry to the subset allowed by allow (glob patterns; see match_tool_allowlist), producing a new static registry. Used by the top-level --profile path, which is a leaf agent: a matched spawn_agent is intentionally dropped (a top-level profile does not dispatch sub-agents).

format_background_outcome

Formats a background task outcome into a text block that is fed back into the conversation.

load_project_prompt

Load only the project instruction layer (AGENTS.md, collected up the directory tree) as a single rendered string, or None if there is none.

match_tool_allowlist

Match a profile’s allow list against the names in base plus the virtual spawn_agent member. Each entry in allow is a glob pattern (via globset, the same engine as hook tool_glob / skill triggers); a bare tool name is the degenerate case of a glob with no wildcards, so exact allowlists keep working unchanged.

new_session_id

Generates a session ID as a random UUID v4.

resolve_system_prompt

Errors

Type Aliases

EventStream

Event stream. Type-erased to support trait object return.