@agimon-ai/po-edit

Snapshot-bound hashline edit tool for Po.

Part of the Po distribution.

The native edit tool consumes the exact file tags and stable three-letter anchors produced by @agimon-ai/po-read, @agimon-ai/po-grep, or another compatible hashline producer. Stale or ambiguous mutations fail before any file is changed.

Alpha: tool and protocol contracts may change between releases.

Requirements

• Node.js 24 or newer

Tool protocol

Compatible read and grep results start with a file header followed by tagged lines:

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

The shared protocol is implemented by @agimon-ai/po-hashline. 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.

edit accepts:

{
  "path": "src/example.ts",
  "hash": "A1b2C3d4",
  "edits": [
    {
      "from": "1#abc",
      "to": "1#abc",
      "content": "const value = 2;"
    }
  ]
}

All anchors refer to the original snapshot. Ranges are inclusive. Omit content to delete a range. Exact duplicate edits are applied once, but any other overlapping ranges are rejected before mutation.

Pass exactly one anchor in each from and to value, for example 5#abc. Anchors copied with a >, +, or - display prefix are accepted, as are uppercase anchor letters, whitespace around the separator, and the legacy 5:abc separator. Pasted multiline blocks are rejected.

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 { EditParamsSchema, executeHashlineEdit, createHashlineEditTool } from '@agimon-ai/po-edit';
import type { EditParams, HashlineRange } from '@agimon-ai/po-edit';

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 native tool declaration consumes services/editTool, and reusable factories and schemas are exposed through flat src/exports.