avtc-pi-logger

File-based logging library for pi extensions — date-partitioned with rotation.

Features

• Date-partitioned logs — one file per day (YYYY-MM-DD.log, UTC); automatically starts a new file at midnight
• Size roll-over — when today's file exceeds maxFileBytes (default 5 MB), it is renamed to .log.1 and a fresh file starts
• Age-based retention — day-files older than retentionDays (default 2; 0 = keep all) are pruned automatically
• Message truncation — messages over maxMessageBytes (default 10 KB) are truncated with a marker
• Scoped child loggers — log.child("scope") derives a child that tags lines with [scope]; nested children compose into dot-paths ([agents.discovery])
• Best-effort I/O — any failure is swallowed after a single stderr warning; logging never crashes the host
• Directory override — PI_LOGGER_DIR environment variable or explicit baseDir option relocates all logs
• Test seam — inject a custom clock function for deterministic tests

API

| Export | Description | |--------|-------------| | createLogger(name, options \| null) | Returns a Logger { info, warn, error, debug, child } writing to <baseDir>/<name>/<date>.log | | Logger.child(scope) | Derives a scoped child that tags lines [scope] and shares the root's sink (dot-paths when nested) | | resolveLogPath(name, baseDir, date) | Pure path resolver (<baseDir>/<name>/<YYYY-MM-DD>.log) | | Logger, LogLevel, LoggerOptions | Types | | NO_ERROR | Sentinel for error(msg, NO_ERROR) when no error object is available |

LoggerOptions

| Key | Type | Default | Description | |-----|------|---------|-------------| | baseDir | string | ~/.pi/logs | Root directory for all extension logs | | debug | boolean | false | Enable debug-level logging | | maxFileBytes | number | 5_242_880 (5 MB) | Max log file size before roll-over | | retentionDays | number | 2 | Days to keep old log files (0 = keep all) | | maxMessageBytes | number | 10_240 (10 KB) | Max message length before truncation | | clock | () → Date | () => new Date() | Test seam for deterministic timestamps | | homeDir | string | os.homedir() | Home directory for default base path resolution |

Log directory override

Base-directory resolution precedence: an explicit options.baseDir > the PI_LOGGER_DIR environment variable > the default ~/.pi/logs. Setting PI_LOGGER_DIR relocates all logs (for tests, point it at a temp dir; for users, a custom log root) with no code changes.

Installation

Add it as a dependency of your extension:

npm install avtc-pi-logger

Usage

import { createLogger, NO_ERROR } from "avtc-pi-logger";

const log = createLogger("my-extension");
log.info("started");
log.warn("slow query");
log.error("request failed", new Error("timeout"));
log.error("no error object", NO_ERROR);
log.debug("only when debug enabled"); // suppressed unless { debug: true }

// Scoped child loggers tag each line with a `[scope]` and share the root's sink:
const agentsLog = log.child("agents");
agentsLog.info("discovered agent");

Writes land at ~/.pi/logs/my-extension/2026-06-20.log as:

2026-06-20T13:37:45 [INFO] started
2026-06-20T13:37:45 [WARN] slow query
2026-06-20T13:37:45 [ERROR] request failed — Error: timeout
2026-06-20T13:37:45 [INFO] [agents] discovered agent

Nested children compose into a dot-path scope (log.child("agents").child("discovery") → [agents.discovery]).

Full suite

Check out the full suite of related extensions, avtc-pi — deterministic feature development, subagent delegation, working-memory, behavioral learning, parallel-work guardrails, durable decisions, notifications, and more.

Developed with Z.ai — get 10% off your subscription via this referral link.

License

MIT