Logging Package in PrimeAgent: Structured Observability for AI Agents

The logging package in PrimeAgent centralizes runtime diagnostics through a JSON-Lines file sink that captures structured events from the agent core and integrated libraries at ~/.prime/agent/logs/agent.jsonl.

PrimeAgent, developed by PrimeIntellect-ai, implements a unified observability layer through its dedicated logging module. This system ensures that every component—from the interactive client to the background daemon—emits structured, context-rich diagnostics to a single, rotating log file.

Core Logging Architecture

The Central Module in logging.ts

The logging package lives in packages/coding-agent/src/core/logging.ts and exposes two primary public helpers that handle all runtime diagnostics. This module acts as the single integration point for both internal PrimeAgent components and the underlying @earendil-works/pi-ai library.

The module provides:

• installFileLogSink([fields]) – Installs a global log sink that writes every structured log entry to a single JSON-Lines file
• setLogContext(fields) – Merges additional context (such as mode or sessionId) into the log entry context object for all subsequent writes

Configuration and Path Resolution

Log file paths are resolved by getAgentLogPath() in packages/coding-agent/src/config.ts, which targets the user’s home directory at ~/.prime/agent/logs/. This configuration module also implements the appendRotatingLog utility that guarantees writes never throw exceptions, even when encountering read-only directories.

File Management and Rotation Strategy

Automatic Size-Bounded Rotation

The logging package implements a single-generation rotation strategy via appendRotatingLog in packages/coding-agent/src/config.ts. When the log file reaches approximately 20 MiB, the system automatically drops the oldest generation to prevent unbounded disk growth.

This rotation mechanism ensures that the JSON-Lines file at ~/.prime/agent/logs/agent.jsonl remains manageable while preserving recent diagnostic history. If the log directory becomes read-only, the sink silently handles the error without crashing the agent process.

Path Resolution Implementation

The getAgentLogPath() function constructs the canonical log location under the user’s home directory. This centralized path management ensures that both the daemon and client processes write to the same physical file, enabling unified debugging across process boundaries.

Runtime Integration and Bootstrap

Startup Sequence in main.ts

PrimeAgent installs the logging sink early in its startup sequence to capture all initialization events. In packages/coding-agent/src/main.ts, the bootstrap code imports and invokes the logging helpers before any other subsystem initializes:

// src/main.ts – bootstrap logging for every run
import { installFileLogSink, setLogContext } from "./core/logging.js";

installFileLogSink();               // Create the JSONL sink at ~/.prime/agent/logs/agent.jsonl
setLogContext({ mode: "interactive" }); // Add runtime mode to all subsequent entries

This early installation ensures that all components—including the daemon, client, and provider diagnostics—share the same structured log output.

External Library Integration

The logging package integrates with the @earendil-works/pi-ai library to capture its structured diagnostics in the same JSON-Lines stream. This integration happens transparently through the global sink installed by installFileLogSink(), allowing PrimeAgent to monitor AI provider interactions alongside native agent events:

// Example of emitting a structured log (from @earendil‑works/pi‑ai)
import { log } from "@earendil-works/pi-ai";

log.info({ event: "tool_call", tool: "search", query: "prime agent logging" });

Context Enrichment with setLogContext

The setLogContext function enables dynamic augmentation of log entries with runtime metadata. After calling this function, every subsequent log line automatically includes the specified fields in its context object:

// In any module that needs extra context
import { setLogContext } from "./core/logging.js";

setLogContext({ sessionId: "abcd1234" });

This capability supports unified observability by injecting persistent identifiers such as PID, session ID, or execution mode into every log record without requiring manual passing of context objects through the call stack.

Summary

• The logging package in PrimeAgent centralizes diagnostics through packages/coding-agent/src/core/logging.ts, providing installFileLogSink() and setLogContext() as the primary public API.
• Log files are written to ~/.prime/agent/logs/agent.jsonl as JSON-Lines, with paths resolved by getAgentLogPath() in packages/coding-agent/src/config.ts.
• The appendRotatingLog utility enforces a ~20 MiB size limit through single-generation rotation that silently drops old entries when bounds are exceeded.
• Bootstrap initialization occurs in packages/coding-agent/src/main.ts, ensuring the sink captures events from the daemon, client, and @earendil-works/pi-ai library from startup.

Frequently Asked Questions

Where does PrimeAgent store its log files?

PrimeAgent writes structured logs to ~/.prime/agent/logs/agent.jsonl, a JSON-Lines file located in the user’s home directory. The getAgentLogPath() function in packages/coding-agent/src/config.ts resolves this canonical path to ensure both client and daemon processes write to the same location.

How does PrimeAgent prevent log files from consuming too much disk space?

The logging package implements size-bounded storage through the appendRotatingLog utility in packages/coding-agent/src/config.ts. When the log file approaches 20 MiB, the system automatically drops the oldest generation to maintain the size limit, ensuring logs never grow unbounded even during extended runtime.

Can I add custom context to PrimeAgent logs?

Yes. The setLogContext(fields) function in packages/coding-agent/src/core/logging.ts merges custom fields into the context object for all subsequent log entries. This allows injection of session IDs, execution modes, or other metadata that persists across asynchronous operations without manual context threading.

How does PrimeAgent capture logs from external libraries?

PrimeAgent captures diagnostics from @earendil-works/pi-ai by installing a global file sink via installFileLogSink() during bootstrap. This sink intercepts structured log events from the external library and writes them to the same JSON-Lines file as native agent events, creating a unified observability stream for debugging AI provider interactions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}