AgentSession

Core class for managing agent lifecycle, events, and session state

The AgentSession class is the central abstraction for agent lifecycle and session management. It provides access to agent state, event subscription with automatic persistence, model management, compaction, and session operations.

Import

import { AgentSession } from "@mariozechner/pi-coding-agent";

Constructor

new AgentSession(config: AgentSessionConfig)

config · AgentSessionConfig · required

Configuration object for the agent session

Show properties

agent · Agent · required

The underlying agent instance from @mariozechner/pi-agent-core

sessionManager · SessionManager · required

Manager for session persistence and history

settingsManager · SettingsManager · required

Manager for user settings (compaction, images, etc.)

cwd · string · required

Current working directory for tool operations

scopedModels · Array<{ model: Model; thinkingLevel: ThinkingLevel }>

Models to cycle through with keyboard shortcuts

resourceLoader · ResourceLoader · required

Loader for skills, prompts, themes, and context files

customTools · ToolDefinition[]

Custom tools registered outside extensions

modelRegistry · ModelRegistry · required

Registry for API key resolution and model discovery

initialActiveToolNames · string[]

Initial active tool names. Default: ["read", "bash", "edit", "write"]

Properties

agent · Agent

Access to the underlying agent instance

sessionManager · SessionManager

Access to the session manager

cwd · string

Current working directory

Methods

addEventListener

Subscribe to agent session events.

addEventListener(listener: AgentSessionEventListener): void

listener · (event: AgentSessionEvent) => void · required

Callback function that receives session events

Events:

• agent_start - Agent turn begins
• agent_end - Agent turn completes
• tool_execution_start - Tool execution begins
• tool_execution_end - Tool execution completes
• auto_compaction_start - Automatic compaction triggered
• auto_compaction_end - Automatic compaction finished
• And more (see AgentSessionEvent type)

prompt

Send a user message to the agent.

prompt(text: string, options?: PromptOptions): Promise<ModelCycleResult>

text · string · required

The user’s message text

options · PromptOptions

Show properties

attachments · Attachment[]

File attachments to include with the message

autoCompact · boolean

Whether to auto-compact context if needed. Default: true

executeBash

Execute a bash command.

executeBash(command: string, description?: string): Promise<BashResult>

command · string · required

The bash command to execute

description · string

Optional description of the command

compact

Manually trigger context compaction.

compact(options?: CompactOptions): Promise<CompactionResult>

options · CompactOptions

Show properties

targetTokens · number

Target token count after compaction

switchSession

Switch to a different session.

switchSession(sessionId: string): Promise<void>

sessionId · string · required

The ID of the session to switch to

getState

Get current agent state.

getState(): AgentState

Returns the current agent state including messages, model, thinking level, and streaming status.

Example

import { createAgentSession } from "@mariozechner/pi-coding-agent";

const { session, extensionRunner } = await createAgentSession({
  cwd: process.cwd(),
  model: getModel("anthropic", "claude-4.5-sonnet-20250514"),
  thinkingLevel: "medium",
});

// Subscribe to events
session.addEventListener((event) => {
  if (event.type === "tool_execution_start") {
    console.log(`Tool: ${event.toolName}`);
  }
});

// Send a message
const result = await session.prompt("List files in the current directory");
console.log(result.messages);

Type Definitions

SessionStats

Statistics about the current session.

interface SessionStats {
  messageCount: number;
  tokenCount: number;
  compactionCount: number;
}

ModelCycleResult

Result from a prompt operation.

interface ModelCycleResult {
  messages: AgentMessage[];
  aborted: boolean;
  error?: string;
}