# AgentSessionManager v0.8.0 - Table of Contents

A comprehensive Elixir library for managing AI agent sessions, state persistence,
conversation context, and multi-agent orchestration workflows.

## Pages

- Introduction
  - [README](readme.md)
  - [Getting Started](getting_started.md)
  - [Live Examples](live_examples.md)
  - [Architecture](architecture.md)
  - [Configuration](configuration.md)
  - [Configuration Reference](configuration_reference.md)
  - [Model Configuration](model_configuration.md)

- Core Concepts
  - [Sessions and Runs](sessions_and_runs.md)
  - [Session Server Runtime (Feature 6)](session_server_runtime.md)
  - [Session Server Subscriptions (Feature 6)](session_server_subscriptions.md)
  - [Session Continuity](session_continuity.md)
  - [Events and Streaming](events_and_streaming.md)
  - [Rendering](rendering.md)
  - [PubSub Integration](pubsub_integration.md)
  - [StreamSession](stream_session.md)
  - [Cursor Streaming and Migration](cursor_streaming_and_migration.md)
  - [Workspace Snapshots](workspace_snapshots.md)
  - [Provider Routing](provider_routing.md)
  - [Policy Enforcement](policy_enforcement.md)
  - [Cost Tracking](cost_tracking.md)
  - [Advanced Patterns](advanced_patterns.md)
  - [Capabilities](capabilities.md)

- Persistence
  - [Persistence Overview](persistence_overview.md)
  - [Migrating to v0.8](migrating_to_v0-8.md)
  - [EctoSessionStore](ecto_session_store.md)
  - [Ash SessionStore](ash_session_store.md)
  - [SQLite with EctoSessionStore](sqlite_session_store.md)
  - [S3ArtifactStore](s3_artifact_store.md)
  - [CompositeSessionStore](composite_store.md)
  - [Event Schema Versioning](event_schema_versioning.md)
  - [Secrets Redaction](secrets_redaction.md)
  - [Custom Persistence Guide](custom_persistence_guide.md)

- Integration
  - [Workflow Bridge](workflow_bridge.md)
  - [Provider Adapters](provider_adapters.md)
  - [Shell Runner](shell_runner.md)
  - [Concurrency](concurrency.md)
  - [Telemetry and Observability](telemetry_and_observability.md)

- Reference
  - [Error Handling](error_handling.md)
  - [Testing](testing.md)
  - [Changelog](changelog.md)
  - [LICENSE](license.md)

## Modules

- [AgentSessionManager.Adapters.EctoMaintenance](AgentSessionManager.Adapters.EctoMaintenance.md): Ecto-based implementation of the `Maintenance` port.
- [AgentSessionManager.Adapters.EctoQueryAPI](AgentSessionManager.Adapters.EctoQueryAPI.md): Ecto-based implementation of the `QueryAPI` port.
- [AgentSessionManager.Adapters.EctoSessionStore.Migration](AgentSessionManager.Adapters.EctoSessionStore.Migration.md): Provides migration functions for the EctoSessionStore adapter.
- [AgentSessionManager.Adapters.EctoSessionStore.Schemas](AgentSessionManager.Adapters.EctoSessionStore.Schemas.md): Ecto schemas for the EctoSessionStore adapter.
- [AgentSessionManager.Adapters.S3ArtifactStore.ExAwsClient](AgentSessionManager.Adapters.S3ArtifactStore.ExAwsClient.md): Default S3 client implementation using ExAws.
- [AgentSessionManager.Adapters.S3ArtifactStore.S3Client](AgentSessionManager.Adapters.S3ArtifactStore.S3Client.md): Behaviour for S3 API operations.
- [AgentSessionManager.Core.ProviderError](AgentSessionManager.Core.ProviderError.md): Shared normalization for provider-specific errors.
- [AgentSessionManager.PermissionMode](AgentSessionManager.PermissionMode.md): Normalized permission modes for agent session execution.
- [AgentSessionManager.Persistence.ArtifactRegistry](AgentSessionManager.Persistence.ArtifactRegistry.md): Tracks artifact metadata in the `asm_artifacts` table.
- [AgentSessionManager.Persistence.EventBuilder](AgentSessionManager.Persistence.EventBuilder.md): Normalizes and validates adapter events without persisting them.

- [AgentSessionManager.Persistence.EventPipeline](AgentSessionManager.Persistence.EventPipeline.md): Validates, enriches, and persists events from provider adapters.
- [AgentSessionManager.Persistence.EventValidator](AgentSessionManager.Persistence.EventValidator.md): Validates event structure and data shapes.
- [AgentSessionManager.Persistence.ExecutionState](AgentSessionManager.Persistence.ExecutionState.md): In-memory execution state used while a run is in progress.

- [AgentSessionManager.Persistence.RetentionPolicy](AgentSessionManager.Persistence.RetentionPolicy.md): Configurable rules for session and event lifecycle management.
- [AgentSessionManager.Ports.Maintenance](AgentSessionManager.Ports.Maintenance.md): Port for database maintenance operations.
- [AgentSessionManager.Ports.QueryAPI](AgentSessionManager.Ports.QueryAPI.md): Read-only query interface for historical session data.

- Core Domain
  - [AgentSessionManager](AgentSessionManager.md): A comprehensive Elixir library for managing AI agent sessions, state persistence,
conversation context, and multi-agent orchestration workflows.
  - [AgentSessionManager.Core.Capability](AgentSessionManager.Core.Capability.md): Represents a capability that can be assigned to an agent.
  - [AgentSessionManager.Core.Error](AgentSessionManager.Core.Error.md): Normalized error taxonomy for Agent Session Manager.
  - [AgentSessionManager.Core.Event](AgentSessionManager.Core.Event.md): Represents an event in the agent session lifecycle.
  - [AgentSessionManager.Core.Manifest](AgentSessionManager.Core.Manifest.md): Represents an agent manifest that defines the agent's configuration and capabilities.
  - [AgentSessionManager.Core.NormalizedEvent](AgentSessionManager.Core.NormalizedEvent.md): Represents a normalized event in the event stream.
  - [AgentSessionManager.Core.Run](AgentSessionManager.Core.Run.md): Represents a single execution run within a session.
  - [AgentSessionManager.Core.Session](AgentSessionManager.Core.Session.md): Represents an AI agent session.
  - [AgentSessionManager.Core.Transcript](AgentSessionManager.Core.Transcript.md): Provider-agnostic transcript reconstructed from persisted session events.

- Event Pipeline
  - [AgentSessionManager.Core.EventNormalizer](AgentSessionManager.Core.EventNormalizer.md): Event normalization pipeline for transforming provider events into normalized events.
  - [AgentSessionManager.Core.EventStream](AgentSessionManager.Core.EventStream.md): Manages incremental consumption of normalized event streams.
  - [AgentSessionManager.Core.TranscriptBuilder](AgentSessionManager.Core.TranscriptBuilder.md): Builds provider-agnostic transcripts from events and store-backed histories.

  - [AgentSessionManager.Persistence.EventRedactor](AgentSessionManager.Persistence.EventRedactor.md): Scans event data for secret patterns and replaces matches with
redacted placeholders before persistence.

- Capability System
  - [AgentSessionManager.Core.CapabilityResolver](AgentSessionManager.Core.CapabilityResolver.md): Negotiates capabilities between required/optional sets and available provider capabilities.
  - [AgentSessionManager.Core.CapabilityResolver.NegotiationResult](AgentSessionManager.Core.CapabilityResolver.NegotiationResult.md): Represents the result of a capability negotiation.
  - [AgentSessionManager.Core.Registry](AgentSessionManager.Core.Registry.md): A thread-safe registry for storing and retrieving provider manifests.

- Orchestration
  - [AgentSessionManager.Routing.ProviderRouter](AgentSessionManager.Routing.ProviderRouter.md): Provider router that implements the `ProviderAdapter` behaviour.
  - [AgentSessionManager.SessionManager](AgentSessionManager.SessionManager.md): Orchestrates session lifecycle, run execution, and event handling.

- Workflow Integration
  - [AgentSessionManager.WorkflowBridge](AgentSessionManager.WorkflowBridge.md): Thin integration layer for calling ASM from workflow/DAG engines.
  - [AgentSessionManager.WorkflowBridge.ErrorClassification](AgentSessionManager.WorkflowBridge.ErrorClassification.md): Classification of an ASM error for workflow routing decisions.

  - [AgentSessionManager.WorkflowBridge.StepResult](AgentSessionManager.WorkflowBridge.StepResult.md): Normalized result from a workflow step execution.

- Routing and Policy
  - [AgentSessionManager.Policy.AdapterCompiler](AgentSessionManager.Policy.AdapterCompiler.md): Compiles an effective policy into adapter-specific options.
  - [AgentSessionManager.Policy.Evaluator](AgentSessionManager.Policy.Evaluator.md): Pure policy checks for event-driven runtime enforcement.

  - [AgentSessionManager.Policy.Policy](AgentSessionManager.Policy.Policy.md): Declarative policy definition for runtime enforcement.
  - [AgentSessionManager.Policy.Preflight](AgentSessionManager.Policy.Preflight.md): Preflight policy checks that run before execution begins.
  - [AgentSessionManager.Policy.Runtime](AgentSessionManager.Policy.Runtime.md): Mutable per-run policy state for real-time enforcement decisions.
  - [AgentSessionManager.Routing.CapabilityMatcher](AgentSessionManager.Routing.CapabilityMatcher.md): Matches provider capabilities against routing requirements.
  - [AgentSessionManager.Routing.CircuitBreaker](AgentSessionManager.Routing.CircuitBreaker.md): Pure-functional circuit breaker for provider health tracking.
  - [AgentSessionManager.Routing.RoutingPolicy](AgentSessionManager.Routing.RoutingPolicy.md): Routing policy for provider selection and failover attempts.

- Cost Tracking
  - [AgentSessionManager.Cost.CostCalculator](AgentSessionManager.Cost.CostCalculator.md): Converts token usage counts into USD cost estimates using
configurable per-model pricing tables.

- Ports (Interfaces)
  - [AgentSessionManager.Ports.ArtifactStore](AgentSessionManager.Ports.ArtifactStore.md): Port (interface) for storing large blobs (patches, snapshot manifests).
  - [AgentSessionManager.Ports.ProviderAdapter](AgentSessionManager.Ports.ProviderAdapter.md): Port (interface) for AI provider adapters.
  - [AgentSessionManager.Ports.SessionStore](AgentSessionManager.Ports.SessionStore.md): Port (interface) for session storage operations.

- Adapters (Implementations)
  - [AgentSessionManager.Adapters.AmpAdapter](AgentSessionManager.Adapters.AmpAdapter.md): Provider adapter for Amp (Sourcegraph) AI agent integration.
  - [AgentSessionManager.Adapters.ClaudeAdapter](AgentSessionManager.Adapters.ClaudeAdapter.md): Provider adapter for Claude (Anthropic) AI models.
  - [AgentSessionManager.Adapters.CodexAdapter](AgentSessionManager.Adapters.CodexAdapter.md): Provider adapter for Codex (Claude Code CLI) integration.
  - [AgentSessionManager.Adapters.CompositeSessionStore](AgentSessionManager.Adapters.CompositeSessionStore.md): Combines a SessionStore and an ArtifactStore into a single unified interface.
  - [AgentSessionManager.Adapters.EctoSessionStore](AgentSessionManager.Adapters.EctoSessionStore.md): An Ecto-based implementation of the `SessionStore` port.
  - [AgentSessionManager.Adapters.FileArtifactStore](AgentSessionManager.Adapters.FileArtifactStore.md): File-backed artifact store for local/dev usage.
  - [AgentSessionManager.Adapters.InMemorySessionStore](AgentSessionManager.Adapters.InMemorySessionStore.md): In-memory implementation of the SessionStore behaviour.
  - [AgentSessionManager.Adapters.S3ArtifactStore](AgentSessionManager.Adapters.S3ArtifactStore.md): An S3-backed implementation of the `ArtifactStore` port.
  - [AgentSessionManager.Adapters.ShellAdapter](AgentSessionManager.Adapters.ShellAdapter.md): Provider adapter for shell command execution.
  - [AgentSessionManager.Ash.Adapters.AshMaintenance](AgentSessionManager.Ash.Adapters.AshMaintenance.md): Ash-based implementation of the `Maintenance` port.

  - [AgentSessionManager.Ash.Adapters.AshQueryAPI](AgentSessionManager.Ash.Adapters.AshQueryAPI.md): Ash-based implementation of the `QueryAPI` port.

  - [AgentSessionManager.Ash.Adapters.AshSessionStore](AgentSessionManager.Ash.Adapters.AshSessionStore.md): Ash-based implementation of the `SessionStore` port.

- Ash Integration
  - [AgentSessionManager.Ash.Domain](AgentSessionManager.Ash.Domain.md): Ash domain for AgentSessionManager persistence resources.

- Concurrency
  - [AgentSessionManager.Concurrency.ConcurrencyLimiter](AgentSessionManager.Concurrency.ConcurrencyLimiter.md): Enforces concurrency limits for sessions and runs.
  - [AgentSessionManager.Concurrency.ControlOperations](AgentSessionManager.Concurrency.ControlOperations.md): Manages control operations (interrupt, cancel, pause, resume) for runs.

- Runtime
  - [AgentSessionManager.Runtime.RunQueue](AgentSessionManager.Runtime.RunQueue.md): Pure FIFO run queue with a configurable maximum size.
  - [AgentSessionManager.Runtime.SessionRegistry](AgentSessionManager.Runtime.SessionRegistry.md): Thin wrapper around Elixir `Registry` for locating per-session runtimes.
  - [AgentSessionManager.Runtime.SessionServer](AgentSessionManager.Runtime.SessionServer.md): Per-session runtime server (GenServer) providing
  - [AgentSessionManager.Runtime.SessionSupervisor](AgentSessionManager.Runtime.SessionSupervisor.md): Supervisor for the session runtime.

- Workspace
  - [AgentSessionManager.Workspace.Diff](AgentSessionManager.Workspace.Diff.md): Represents a diff between two workspace snapshots.

  - [AgentSessionManager.Workspace.Exec](AgentSessionManager.Workspace.Exec.md): Low-level shell command execution with timeout, output capture, and cancellation.
  - [AgentSessionManager.Workspace.GitBackend](AgentSessionManager.Workspace.GitBackend.md): Git-backed workspace snapshots, diffs, and rollback support.

  - [AgentSessionManager.Workspace.HashBackend](AgentSessionManager.Workspace.HashBackend.md): Hash-based workspace backend for non-git directories.

  - [AgentSessionManager.Workspace.Snapshot](AgentSessionManager.Workspace.Snapshot.md): Represents a captured workspace state at a point in time.

  - [AgentSessionManager.Workspace.Workspace](AgentSessionManager.Workspace.Workspace.md): Public workspace service that delegates to git/hash backends.

- Rendering
  - [AgentSessionManager.Rendering](AgentSessionManager.Rendering.md): Renders agent session event streams through a pluggable renderer and sink pipeline.
  - [AgentSessionManager.Rendering.Renderer](AgentSessionManager.Rendering.Renderer.md): Behaviour for rendering agent session events into human-readable output.
  - [AgentSessionManager.Rendering.Renderers.CompactRenderer](AgentSessionManager.Rendering.Renderers.CompactRenderer.md): Compact single-line token renderer for agent session events.
  - [AgentSessionManager.Rendering.Renderers.PassthroughRenderer](AgentSessionManager.Rendering.Renderers.PassthroughRenderer.md): A no-op renderer that passes events through without formatting.
  - [AgentSessionManager.Rendering.Renderers.StudioRenderer](AgentSessionManager.Rendering.Renderers.StudioRenderer.md): CLI-grade interactive renderer for agent session events.
  - [AgentSessionManager.Rendering.Renderers.VerboseRenderer](AgentSessionManager.Rendering.Renderers.VerboseRenderer.md): Verbose line-by-line renderer for agent session events.
  - [AgentSessionManager.Rendering.Sink](AgentSessionManager.Rendering.Sink.md): Behaviour for output destinations that receive rendered text from a renderer.
  - [AgentSessionManager.Rendering.Sinks.CallbackSink](AgentSessionManager.Rendering.Sinks.CallbackSink.md): A sink that forwards events to a callback function.
  - [AgentSessionManager.Rendering.Sinks.FileSink](AgentSessionManager.Rendering.Sinks.FileSink.md): A sink that writes rendered output to a log file with ANSI codes stripped.
  - [AgentSessionManager.Rendering.Sinks.JSONLSink](AgentSessionManager.Rendering.Sinks.JSONLSink.md): A sink that writes events as JSON Lines (one JSON object per line).
  - [AgentSessionManager.Rendering.Sinks.PubSubSink](AgentSessionManager.Rendering.Sinks.PubSubSink.md): A sink that broadcasts events via Phoenix PubSub.
  - [AgentSessionManager.Rendering.Sinks.TTYSink](AgentSessionManager.Rendering.Sinks.TTYSink.md): A sink that writes rendered output to a terminal device.
  - [AgentSessionManager.Rendering.Studio.ANSI](AgentSessionManager.Rendering.Studio.ANSI.md): ANSI terminal utilities for the StudioRenderer pipeline.
  - [AgentSessionManager.Rendering.Studio.ToolSummary](AgentSessionManager.Rendering.Studio.ToolSummary.md): Generates human-readable spinner text and summary lines for tool calls.

- Stream Session
  - [AgentSessionManager.StreamSession](AgentSessionManager.StreamSession.md): One-shot streaming session lifecycle.
  - [AgentSessionManager.StreamSession.Supervisor](AgentSessionManager.StreamSession.Supervisor.md): Convenience supervisor for StreamSession infrastructure.

- PubSub Integration
  - [AgentSessionManager.PubSub](AgentSessionManager.PubSub.md): Convenience functions for PubSub integration with AgentSessionManager.
  - [AgentSessionManager.PubSub.Topic](AgentSessionManager.PubSub.Topic.md): Topic naming conventions for ASM PubSub integration.

- Configuration
  - [AgentSessionManager.Config](AgentSessionManager.Config.md): Centralized configuration with process-local overrides.
  - [AgentSessionManager.Models](AgentSessionManager.Models.md): Central registry of model identifiers, default models, and pricing data.

- Observability
  - [AgentSessionManager.AuditLogger](AgentSessionManager.AuditLogger.md): Audit log persistence for observability and compliance.
  - [AgentSessionManager.Telemetry](AgentSessionManager.Telemetry.md): Telemetry event emission for observability.