@agimon-ai/po-read

Snapshot-bound hashline read tool for Po.

Part of the Po distribution.

Writable text reads attach an exact file tag and a stable three-letter anchor to every returned line. Non-writable files retain Pi's native output, which avoids spending model context on anchors that cannot be edited. The full hashline protocol remains available to the model, while Po's renderer hides the protocol tags and anchors from people and preserves syntax highlighting. Image reads retain Pi's native attachment behavior.

Alpha: tool and protocol contracts may change between releases.

Requirements

• Node.js 24 or newer

Tool protocol

A writable text result starts with one file header, followed by tagged lines:

@file src/example.ts#A1b2C3d4
1#abc|const value = 1;

The eight-character file tag is the base64url SHA-256 prefix of the exact file bytes. The three-letter line anchor is a whitespace-insensitive FNV-1a64 tag. Large reads retain Pi's output limits and include an offset hint when more lines are available.

Files over 8 MiB are refused before decoding or preparing edits, including reads with a small limit. Use runner log tools for logs. Factories require an injected FileSystem or getter; execution functions take a FileSystem after the abort signal.

Attribution

The hashline protocol and FNV anchor approach are adapted from Phi's writetool, licensed under MIT by pulseaiclub. Po uses an exact-byte SHA-256 file tag as an intentional compatibility boundary.

Public API

import { ReadParamsSchema, createHeadlessReadTool } from '@agimon-ai/po-read';
import type { ReadParams } from '@agimon-ai/po-read';

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Maintained by Agimon.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

The server entry declares the native tool. Tool declarations consume logic from named service folders; flat src/exports files expose reusable factories and schemas.