Agent Setup

Relevant source files

The following files were used as context for generating this wiki page:

• src/agent/setup.ts
• src/agent/prompt.ts
• src/main.ts
• src/agent/events.ts
• src/surface/slack.ts
• CLAUDE.md

The Agent Setup module is the core orchestration layer of pi-digby, responsible for initializing the AI agent, managing its session lifecycle, and wiring together various components such as tools, MCP (Model Context Protocol) extensions, and persistence layers. It transforms raw incoming events from surfaces like Slack or Linear into actionable runs for the underlying LLM.

The setup process ensures that each communication channel has a dedicated, persistent ChannelRunner that maintains context, handles tool execution, and manages the streaming of responses back to the user. Sources: src/agent/setup.ts:1-25, CLAUDE.md:1-20

Core Architecture

The architecture relies on a factory pattern to create and cache ChannelRunner instances. Each runner encapsulates an Agent and an AgentSession, which are configured with specific tools and system prompts tailored to the workspace.

Sources: src/agent/setup.ts:133-210, src/main.ts:100-110

Key Components

Component	Description	Source
ChannelRunner	Interface providing run, abort, and shutdown methods for a specific channel.	src/agent/setup.ts:98-110
Agent	The core execution engine from @mariozechner/pi-agent-core, managing state and tool calls.	src/agent/setup.ts:153-162
AgentSession	Manages the higher-level session logic, including resource loading and extension binding.	src/agent/setup.ts:212-225
ResourceLoader	Handles skills, prompts, and MCP extensions; specifically uses DefaultResourceLoader.	src/agent/setup.ts:187-200
SessionManager	Persists conversation history to context.jsonl within the channel directory.	src/agent/setup.ts:167-175

Initialization Workflow

When a message arrives, the system either retrieves an existing runner or creates a new one via getOrCreateRunner. Creation involves setting up the workspace directory, loading global/channel-specific memory, and initializing the LLM provider (Amazon Bedrock).

Sources: src/agent/setup.ts:133-225, src/main.ts:100-105

Model Configuration

The agent is configured to use Claude Sonnet 3.5 (referenced as claude-sonnet-4-6 in Bedrock) via the Amazon Bedrock provider. Authentication is handled automatically through ECS task roles or local environment variables.
Sources: src/agent/setup.ts:43-61, CLAUDE.md:12-15

Execution Lifecycle

The run method in ChannelRunner executes a single interaction. It follows a strict sequence to ensure the agent has the latest context before processing the user message.

1. Sync Context: Syncs messages from log.jsonl to context.jsonl to catch up on offline activity.
2. Rebuild Prompt: Dynamically rebuilds the system prompt to include the latest user mappings, channel names, and memory state.
3. MCP Check: Checks if .pi/mcp.json has changed; if so, reloads extensions.
4. Process Attachments: Binary sniffing is used to detect image attachments, which are then resized and converted to Base64 for the LLM.
5. Streaming: The AgentSession is prompted, and an event handler bridges session events (tool starts, text chunks) to the AgentSurface.

Sources: src/agent/setup.ts:257-320, src/agent/events.ts:100-150

Event Handling and Surface Updates

The createEventHandler function bridges the internal AgentSessionEvent stream to the AgentSurface (typically Slack). It tracks tool execution status and updates the user interface with progress indicators.

Sources: src/agent/events.ts:110-180, src/surface/slack.ts:100-150

System Prompt Construction

The system prompt is built dynamically for every run. It includes:

• Persona: Defines "digby" as a concise assistant.
• Context: Includes the current date, timezone, and environment details.
• Workspace Layout: Explains the /data structure, including MEMORY.md, skills/, and log.jsonl.
• Mappings: Active lists of users and channels for Slack ID resolution.
• Skill Definitions: Available CLI tools and instructions for creating new ones.

Sources: src/agent/prompt.ts:20-130

Resource and Skill Management

Skills are treated as custom CLI tools. The setup module loads them from both global and channel-specific directories.

Feature	Description
Global Skills	Located in skills/ at the workspace root.
Channel Skills	Located in ${channelId}/skills/.
MCP Adapter	Loads MCP servers defined in .pi/mcp.json using jiti for TypeScript source support.
Memory	Global (MEMORY.md) and per-channel (channel/MEMORY.md) files.

Sources: src/agent/setup.ts:187-210, src/agent/prompt.ts:80-100

Shutdown Procedure

To ensure clean exits, especially for MCP connections, the shutdownAllRunners function iterates through the cache and emits a session_shutdown event to all extensions. This allows subprocesses and network connections to close gracefully.
Sources: src/agent/setup.ts:445-455, src/main.ts:260-270