Utility Modules
Relevant source files
The following files were used as context for generating this wiki page:
Utility modules in the pi-digby project provide essential cross-cutting concerns, including structured logging, file manipulation, and advanced image processing. These modules ensure that the agent can interact with the host file system safely, process user-uploaded media for LLM consumption, and provide human-readable feedback during complex task execution.
The primary scope of these utilities covers image resizing and MIME type detection to meet LLM token and format constraints, surgical file editing using unified diffs, and centralized logging for monitoring agent performance and tool execution.
Image Processing Utilities
The image processing pipeline is responsible for preparing visual data for the LLM. It includes detecting supported formats and resizing high-resolution images to fit within API constraints.
MIME Type Detection
The system uses binary header sniffing to detect image types, supporting standard web formats such as JPEG, PNG, GIF, and WebP. This is a critical first step in the read tool to decide whether to treat a file as text or an image.
Sources: src/utils/mime.ts:1-20, src/tools/read.ts:25-30
Resizing Logic
Images are resized using the @silvia-odwyer/photon-node library. The logic targets a specific resolution (typically 1024x1024) while maintaining the original aspect ratio. If an image already fits within these dimensions, it is returned as-is.
Sources: src/utils/image-resize.ts:1-50, package.json:23
Image Processing Flow
The following diagram illustrates how a file is processed when the agent attempts to "read" an image for LLM input.
The flow ensures that images are only sent to the LLM if they are in a supported format and within size constraints.
Sources: src/utils/mime.ts, src/utils/image-resize.ts, src/tools/read.ts
File and Text Utilities
These utilities facilitate "surgical" edits and optimized reading of large files to prevent context window exhaustion.
Surgical File Editing
The edit tool utilizes the diff library to perform exact text replacements. It generates a unified diff string to provide the user and the agent with clear feedback on what changed.
| Feature | Description |
|---|---|
| Exact Match | Requires the old_text to appear exactly once in the file to prevent ambiguous edits. |
| Unified Diff | Generates a 4-line context diff showing additions (+) and removals (-). |
| Safety | Throws an error if the target text is missing or appears multiple times. |
Sources: src/tools/edit.ts:10-120
Optimized File Reading
The read utility implements line-based offsets and limits. This allows the agent to scan large files in chunks rather than loading the entire content into the LLM context.
Sources: src/tools/read.ts:60-100
Structured Logging
The logging utility provides a centralized interface for console output, categorized by severity and function. It includes specialized formatters for tool execution and agent usage statistics.
Logging is used throughout the lifecycle of an agent run to track state changes and performance.
Sources: src/log.ts:1-50
Logging Functions
| Function | Purpose | Output Format Example |
|---|---|---|
info | Standard operational messages | [12:00:00] Starting pi-digby... |
toolStart | Marks the beginning of a tool execution | [12:00:01] [C123] → read: Reading config.json |
toolEnd | Reports tool duration and success/failure | [12:00:02] [C123] ✓ read (0.5s): { "key": "val" } |
usage | Tracks token usage and monetary cost | [12:00:05] [C123] 5 steps · $0.05 · 12% context |
Sources: src/log.ts:7-49
Execution Orchestration
The setup.ts module acts as a utility for initializing the agent's environment. It manages the creation of "Channel Runners," which are persistent per-channel instances that handle message lifecycles.
Key Responsibilities
- Authentication: Validates AWS Bedrock credentials (via profile or ECS task role).
- Prompt Building: Rebuilds the system prompt dynamically with fresh memory and user mappings.
- Resource Loading: Initializes the MCP (Model Context Protocol) adapter using
jitito load TypeScript source without pre-compilation.
Sources: src/agent/setup.ts:35-150, src/agent/prompt.ts
Initialization Sequence
The following sequence diagram shows how a channel runner is initialized and tools are prepared.
The orchestration utility ensures that each channel has a dedicated, correctly configured environment.
Sources: src/agent/setup.ts:240-300, src/main.ts:115-130
Summary
The utility modules provide the foundational infrastructure for pi-digby. By abstracting complex tasks like binary image processing, structured logging, and surgical file manipulation, they allow the core agent logic to remain focused on task orchestration. These modules are designed to work within the constraints of LLM context windows and Slack's messaging limitations, ensuring robust and cost-effective operation.