/**
* Tool Registration Example - Demonstrates an audited file reader
*
* Extensions can register custom tools for workflows such as:
* - Adding logging or auditing to tool calls
* - Implementing access control or sandboxing
* - Routing tool calls to remote systems (e.g., pi-ssh-remote)
* - Modifying tool behavior for specific workflows
*
* This example registers a `file_reader` tool to:
* 1. Log all file access to a log file
* 2. Block access to sensitive paths (e.g., .env files)
* 3. Read allowed files with basic truncation
*
* Usage:
* pi -e ./tool-override.ts
*/
import type { TextContent } from "@earendil-works/pi-ai";
import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
import { constants, readFileSync } from "fs";
import { access, appendFile, readFile } from "fs/promises";
import { join, resolve } from "path";
import { Type } from "typebox";
const LOG_FILE = join(getAgentDir(), "file-reader-access.log");
// Paths that are blocked from reading
const BLOCKED_PATTERNS = [
/\.env$/,
/\.env\..+$/,
/secrets?\.(json|yaml|yml|toml)$/i,
/credentials?\.(json|yaml|yml|toml)$/i,
/\/\.ssh\//,
/\/\.aws\//,
/\/\.gnupg\//,
];
function isBlockedPath(path: string): boolean {
return BLOCKED_PATTERNS.some((pattern) => pattern.test(path));
}
async function logAccess(path: string, allowed: boolean, reason?: string) {
const timestamp = new Date().toISOString();
const status = allowed ? "ALLOWED" : "BLOCKED";
const msg = reason ? ` (${reason})` : "";
const line = `[${timestamp}] ${status}: ${path}${msg}\n`;
try {
await withFileMutationQueue(LOG_FILE, async () => {
await appendFile(LOG_FILE, line);
});
} catch {
// Ignore logging errors
}
}
const readSchema = Type.Object({
path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
});
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "file_reader",
label: "file reader (audited)",
description:
"Read the contents of a file with access logging. Some sensitive paths (.env, secrets, credentials) are blocked.",
parameters: readSchema,
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
const { path, offset, limit } = params;
const absolutePath = resolve(ctx.cwd, path);
// Check if path is blocked
if (isBlockedPath(absolutePath)) {
await logAccess(absolutePath, false, "matches blocked pattern");
return {
content: [
{
type: "text",
text: `Access denied: "${path}" matches a blocked pattern (sensitive file). This tool blocks access to .env files, secrets, credentials, and SSH/AWS/GPG directories.`,
},
],
details: { blocked: true },
};
}
// Log allowed access
await logAccess(absolutePath, true);
// Perform the actual read (simplified implementation)
try {
await access(absolutePath, constants.R_OK);
const content = await readFile(absolutePath, "utf-8");
const lines = content.split("\n");
// Apply offset and limit
const startLine = offset ? Math.max(0, offset - 1) : 0;
const endLine = limit ? startLine + limit : lines.length;
const selectedLines = lines.slice(startLine, endLine);
// Basic truncation (50KB limit)
let text = selectedLines.join("\n");
const maxBytes = 50 * 1024;
if (Buffer.byteLength(text, "utf-8") > maxBytes) {
text = `${text.slice(0, maxBytes)}\n\n[Output truncated at 50KB]`;
}
return {
content: [{ type: "text", text }] as TextContent[],
details: { lines: lines.length },
};
} catch (error: any) {
return {
content: [{ type: "text", text: `Error reading file: ${error.message}` }] as TextContent[],
details: { error: true },
};
}
},
// No renderCall/renderResult - uses the generic tool renderer.
});
// Also register a command to view the access log
pi.registerCommand("file-reader-log", {
description: "View the file access log",
handler: async (_args, ctx) => {
try {
const log = readFileSync(LOG_FILE, "utf-8");
const lines = log.trim().split("\n").slice(-20); // Last 20 entries
ctx.ui.notify(`Recent file access:\n${lines.join("\n")}`, "info");
} catch {
ctx.ui.notify("No access log found", "info");
}
},
});
}