Session Management

Every interaction with an agent occurs within a session. Sessions maintain conversation context, track tool executions, and preserve state across multiple queries. The Agent automatically manages sessions for you, but understanding how they work is crucial for building sophisticated applications.

Understanding Sessions

Sessions provide continuity between agent interactions, allowing for natural conversation flow and context preservation:

// Each processQuery call continues the same session
const result1 = await agent.processQuery("What files are in this directory?");
const result2 = await agent.processQuery("Show me the contents of the largest file");
// The agent remembers the file listing from result1

Session State

Sessions contain rich state information that tracks the entire conversation and execution context:

interface SessionState {
  id: string;                           // Unique session identifier
  contextWindow: ContextWindow;         // Conversation history
  aborted: boolean;                     // Session abort status
  abortController: AbortController;     // For canceling operations
  executionAdapter?: ExecutionAdapter;  // Runtime environment
  tokenUsage?: TokenUsage;             // Token consumption tracking
  cacheMetrics?: CacheMetricsTracking; // Prompt caching stats
  multiRepoTracking?: MultiRepoInfo;   // Multi-repository support
}

Key Session Components

Context Window: Maintains the conversation history including user messages, assistant responses, and tool execution results. Abort Controller: Provides cancellation capabilities for long-running operations. Execution Adapter: Links the session to the specific execution environment (local, Docker, or remote).

Session Control

The Agent provides comprehensive methods for session management:

Abort Operations

// Abort the current session
agent.abort();

// Check if session is aborted
if (agent.isAborted()) {
  console.log('Session was aborted');
}

// Clear abort status to resume operations (the agent will naturally clear this on next query)
agent.clearAbort();

Rollback Functionality

Rollback allows you to revert the conversation to a previous state:

// Rollback to a specific message (rollbacks environment changes as well)
agent.performRollback(messageId);

// Static rollback with custom session (only influences message history, not environment)
await Agent.performRollback(sessionState, messageId);

Context Windows

Context windows manage the conversation history and determine what information is available to the agent during each interaction.

Creating Custom Context Windows

// Create a custom context window with previous conversation
const contextWindow = await Agent.createContextWindow([
  { role: 'user', content: 'Previous conversation...' },
  { role: 'assistant', content: 'Previous response...' }
]);

// Use it in a query
const result = await agent.processQuery(
  "Continue from where we left off",
  undefined,
  contextWindow
);

Context Window Management

Context windows automatically manage:

Message History: All user queries and assistant responses
Tool Execution Results: Output from tool invocations
Token Limits: Automatic truncation when approaching model limits
Relevance Filtering: Keeping the most relevant context for current tasks

Advanced Session Features

Multi-Repository Support (intended for remote environment use)

Sessions can track operations across multiple repositories:

// Get multi-repo information
const repoInfo = Agent.getMultiRepoInfo(sessionState);
if (repoInfo) {
  console.log(`Tracking ${repoInfo.repoCount} repositories`);
  console.log('Repo paths:', repoInfo.repoPaths);
}

// Get repository count
const count = Agent.getRepositoryCount(sessionState);

// Get repository paths
const paths = Agent.getRepositoryPaths(sessionState);

Token Usage Tracking (Currently unmaintained and broken)

Monitor token consumption for cost optimization:

// Access token usage from session state
if (sessionState.tokenUsage) {
  console.log('Input tokens:', sessionState.tokenUsage.inputTokens);
  console.log('Output tokens:', sessionState.tokenUsage.outputTokens);
  console.log('Total cost:', sessionState.tokenUsage.totalCost);
}

Cache Metrics (Currently unmaintained and broken)

Track prompt caching effectiveness:

// Monitor cache performance
if (sessionState.cacheMetrics) {
  console.log('Cache hits:', sessionState.cacheMetrics.hits);
  console.log('Cache misses:', sessionState.cacheMetrics.misses);
  console.log('Cache efficiency:', sessionState.cacheMetrics.efficiency);
}

Session Lifecycle

Understanding the session lifecycle helps optimize agent performance:

Initialization: Session created with unique ID and empty context
Context Building: Messages and tool results added to context window
State Tracking: Execution state, token usage, and metrics updated
Persistence: Session state maintained across multiple queries
Cleanup: Session resources released when no longer needed

Best Practices