pi-package-references

@aefree/pi-package-references provides the single read_package_reference Pi tool for bounded text owned by independently installed packages.

Installation

Install it in the package that owns the public reference files:

npm install @aefree/pi-package-references

The package has a normal runtime dependency on @aefree/pi-capability-registry; npm resolves it transitively once that prerequisite is publicly available.

Use it from an owner package

1. Add @aefree/pi-package-references as a normal runtime dependency of the package that owns the reference files.
2. Ensure both that package's extension and this package's extensions/index.ts are active in Pi. The reader extension registers the single read_package_reference tool; importing contracts/v1 or runtime/v1 has no Pi-resource registration side effects.
3. During each session_start, register only the directory prefixes the owner intends to publish. During the matching session_shutdown, unregister that registration.
4. In prompts or agents, call the tool with an exact package name and public path. Do not use project-relative file reads as a substitute.

For example, an extension whose package contains references/review/delivery-policy.md can register that directory as follows:

import { readFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import type { RegistrationToken } from "@aefree/pi-capability-registry";
import {
  registerPackageReferenceOwnerV1,
  unregisterPackageReferenceOwnerV1,
} from "@aefree/pi-package-references/runtime/v1";

export default function registerOwner(pi: ExtensionAPI): void {
  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
  const manifest = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")) as {
    name: string;
    version: string;
  };
  let activeScope: object | undefined;
  let token: RegistrationToken | undefined;

  pi.on("session_start", async (_event, ctx) => {
    unregisterPackageReferenceOwnerV1(token);
    activeScope = ctx.sessionManager;
    token = await registerPackageReferenceOwnerV1(ctx.sessionManager, {
      contractVersion: 1,
      packageName: manifest.name,
      packageVersion: manifest.version,
      packageRoot,
      registeredBy: "extensions/index.ts",
      publicMounts: [{
        prefix: "references/review/",
        directory: "references/review",
        extensions: [".md"],
      }],
    });
  });

  pi.on("session_shutdown", async (_event, ctx) => {
    if (ctx.sessionManager !== activeScope) return; // stale shutdown
    unregisterPackageReferenceOwnerV1(token);
    token = undefined;
    activeScope = undefined;
  });
}

A prompt or agent then reads an exact package-qualified reference:

{"packageName":"@aefree/pi-workflow","path":"references/compound/guidance.md"}

The result is tool output, so callers should handle a failed read explicitly: state that mandatory guidance is unavailable and do not claim to have applied unread guidance.

Paths are normalized POSIX-relative, mounts and extensions are explicit, reads are capped at 50 KiB and 2,000 lines, and results expose package/version/mount provenance without installation paths. Missing, private, malformed, ambiguous, incompatible, escaping, changed, and oversized resources fail with sanitized codes.

This is a correctness boundary for trusted installed packages, not a filesystem sandbox. On Windows Node runtimes without O_NOFOLLOW, guarantees are canonical containment plus post-open identity/change detection; adversarial race prevention is not claimed.

The reader must be installed and active as a Pi resource package in addition to any owner package's code dependency. pi-configurator selects it transitively for declared owners and preserves explicit disable/filter intent until the user approves a settings repair.