@tinoy/pi-ext-lib 0.1.0 → 0.2.0

package/CONTRACT.md

@@ -0,0 +1,226 @@
+# Degradation contract
+
+What every package in this monorepo must do so that a consumer can install ANY SUBSET
+and get no fatal error from what they did NOT install. Working extensions are documented
+as caveats (see "Declaring a caveat"); a missing extension is never a hard dependency, a
+thrown error, or a silent no-op.
+
+This file is normative. It refines the planning document's contract section in two
+places, both recorded here so the lanes implement one shape:
+
+- the neighbour cache is keyed by `(source, neighbour)` — a resolution per reporting
+  package and neighbour, not one slot per module, so one package's absent neighbour can
+  never mask another's present one;
+- a caveat is a **table row with four fixed columns** ("Declaring a caveat"), not free
+  prose, so the checker can enforce it.
+
+Check your package against it with:
+
+```bash
+node --experimental-strip-types packages/ext-lib/src/neighbour.probe.ts   # the helper's own probe
+node scripts/check-caveats.mjs                                            # caveat declarations
+```
+
+## R1 — A module body does no work and cannot throw
+
+No I/O, no spawning, no network, no environment mutation at module scope. Constants,
+types and function declarations only; every side effect happens inside the extension
+factory, in `try/catch`, once.
+
+```ts
+// module scope: declarations only
+const TOOL_NAME = "example";
+const REFUSAL = "example: unavailable"; // a string, not a computation
+
+// the factory does the work
+export default function (pi: ExtensionAPI): void {
+	try {
+		register(pi);
+	} catch (error) {
+		hookLog("example", "register-failed", { reason: messageOf(error) });
+	}
+}
+```
+
+A read at load is permitted only when it cannot be deferred behind an accessor, and even then
+always behind a `try` that produces a refusal value, never a throw. Prefer the accessor: the
+read runs on its first call and is memoized to one read per process, so importing the package
+performs no I/O and a consumer that never uses the value never touches the store —
+`loadTariff()` in `@tinoy/pi-tariff` reads the configured table on its first call and answers
+`{ ok: false, reason }` when the file is missing or shaped wrong, while the module body stays
+declarations only.
+
+## R2 — Static imports only for what is guaranteed
+
+Guaranteed, and therefore imported statically: node builtins, the package's own modules,
+`@tinoy/pi-ext-lib`, `@tinoy/pi-focus-state` / `@tinoy/pi-tariff` where used, and the
+pi-supplied packages declared as `"*"` peers.
+
+Optional, and therefore resolved with `optionalNeighbour`: any third-party pi package,
+any external binary, any store that may not exist.
+
+```ts
+import { optionalNeighbour } from "@tinoy/pi-ext-lib";
+
+const rpiv = await optionalNeighbour(
+	"@juicesharp/rpiv-todo",
+	() => import("@juicesharp/rpiv-todo/state/state-reducer.js"),
+	{
+		source: "todo-parent",
+		effect: "the child-to-parent todo relay cannot apply a mutation",
+		hint: "pi install npm:@juicesharp/rpiv-todo",
+	},
+);
+if (!rpiv) return refusal("todo_parent: the rpiv-todo state reducer is not installed");
+```
+
+`optionalNeighbour(neighbour, load, report)` never throws, resolves each
+`(source, neighbour)` pair once per process, and emits exactly one `neighbour-absent`
+line per absent pair. `report.source` is the reporting package as it appears in the
+diagnostics log; `report.effect` is what is lost, in one clause; `report.hint` is the
+install command or setting that restores it.
+
+Declare the neighbour in `package.json` as an optional peer:
+
+```json
+{
+	"peerDependencies": { "@juicesharp/rpiv-todo": "*" },
+	"peerDependenciesMeta": { "@juicesharp/rpiv-todo": { "optional": true } }
+}
+```
+
+Do not bundle it: a bundled copy would ship a second extension registration, and the
+subset rule needs absence to be survivable rather than impossible.
+
+## R3 — A missing neighbour is reported by name; it is never thrown
+
+One line per distinct condition per process, on the shared diagnostics envelope:
+
+```ts
+hookLog("fleet", "neighbour-absent", {
+	neighbour: "@tinoy/pi-canon",
+	effect: "the foreman discipline section is not appended to the system prompt",
+	hint: "pi install npm:@tinoy/pi-canon",
+});
+```
+
+`optionalNeighbour` emits that line for you; call `hookLog` directly only for a condition
+the helper cannot see (a capability probed at call time, an unavailable service).
+
+A surface the model can call says the same thing in prose and marks failure explicitly —
+it never returns an empty success and never a bare `null`:
+
+```ts
+return {
+	content: [{ type: "text", text: `${TOOL_NAME}: unavailable — ${reason}` }],
+	details: { ok: false },
+};
+```
+
+Silent-by-design cases are only these: an extension that is inert without its marker
+(a child-only extension in a parent session), and a pure enrichment listener that
+subscribes to an event a package may never emit.
+
+## R4 — Register only tool names you own
+
+A duplicate tool name is a loader error row for the later registrant, and the first owner
+keeps the name. Therefore:
+
+- register no name another package could own (audit the suite's names before adding one);
+- when a feature cannot work without an absent neighbour, register **nothing** for it and
+  answer its refusal at call time — preferred — or register the tool and refuse; never
+  register a name that shadows a neighbour's;
+- if two packages must legitimately offer the same name, the pairing is documented as a
+  conflict caveat in both READMEs, because installing both is a user error the loader
+  reports.
+
+## R5 — Touch the active tool set only through your own name
+
+```ts
+const active = pi.getActiveTools();
+if (!active.includes(TOOL_NAME)) return; // nothing to do
+pi.setActiveTools(active.filter((name) => name !== TOOL_NAME));
+```
+
+Never `setActiveTools([...fixedList])`: a foreign list reaches the provider, activates
+names no extension registered, and changes the cached prompt prefix. A session-level tool
+set that genuinely must be narrowed is filtered against the registered set first, and
+every dropped name is reported once by name.
+
+## R6 — Shared state, locks and claims have ONE owner that exports the paths
+
+Paths under a shared store (claims, locks, rosters, ledgers) are computed only inside the
+package that owns the store, and exported as a helper. Consumers import the helper, never
+a path literal, so relocating the store is one edit.
+
+Absence of the store means "this process is not a member": report it and skip the write.
+Never create the tree, never fall back to a second location, never take a lock you cannot
+name. A declared degraded location chosen by the owner and logged is acceptable; an
+implicit one is not.
+
+## R7 — Event and hook seams are one-way and order-free
+
+- Publishers never require a subscriber: emitting an event no package listens to changes
+  nothing.
+- Subscribers are idempotent and tolerate a publisher that never appears.
+- Where ordering could change bytes, mutate the payload in place and return `undefined`:
+  two handlers that each strip and re-append produce order-dependent prompt bytes.
+- Cross-extension handoff crosses the event bus, never a module import. Extensions are
+  evaluated in separate module instances, so an imported registry would be a second,
+  empty instance with no error and no log.
+
+## R8 — Machine-bound capability is a call-time refusal, always by name
+
+A capability that depends on this machine (a desktop bus, a vault, a notification daemon,
+a systemd unit, an external binary, a dataset) is probed when it is used, never at load,
+and its absence answers a refusal carrying the reason and the fix.
+
+```ts
+const capability = probeCapability();
+if (!capability.ok) return refusal(`${TOOL_NAME}: ${capability.reason}`);
+```
+
+Nothing refuses at load time: a missing capability costs the one action, not the
+extension.
+
+## R9 — Declaring a caveat
+
+A caveat is a neighbour that makes a package better without being required. Two carriers,
+one source of truth.
+
+**README, mandatory when the package has any caveat.** A `## Works better with` section
+holding exactly one table with these four columns, in this order and spelling:
+
+```markdown
+## Works better with
+
+| Neighbour | You gain | You lose without it | Install |
+| --- | --- | --- | --- |
+| `@tinoy/pi-command-guard` | the blocked-call counter in the footer | the counter stays at zero and no row is rendered | `pi install npm:@tinoy/pi-command-guard` |
+```
+
+One row per caveat; the neighbour cell names exactly one package; the gain and loss cells
+are non-empty; the install cell is a `pi install npm:<name>` command or the literal
+`not a package` when the neighbour is a setting rather than a package. A package with no
+caveat states none — no empty table, no section.
+
+**Machine-readable mirror, gated.** A `caveats` array inside the `pi` object
+(`[{ "neighbour": "@tinoy/pi-canon", "gains": "the discipline section reaches the system
+prompt" }]`) may be declared only once an unknown key inside `pi` is known to be ignored
+by the loader rather than rejected (matrix case M10). Until then `scripts/check-caveats.mjs`
+validates the README half only and reports the gated half as pending.
+
+## Checking a package before it lands
+
+```bash
+npm run typecheck                                    # the workspace program
+npm run lint                                         # biome
+node scripts/check-caveats.mjs                       # the caveat declarations
+node --experimental-strip-types packages/ext-lib/src/neighbour.probe.ts
+```
+
+Load the package through pi's own loader in a scratch prefix (no install, no session):
+point `PI_CODING_AGENT_DIR` at a scratch directory and pass the package's `pi.extensions`
+entry to `DefaultResourceLoader` — the shape `docker/smoke.mjs` uses. A clean package
+loads with zero loader errors, and a missing neighbour appears only as a
+`neighbour-absent` line.

package/README.md

@@ -28,6 +28,19 @@ An extension package depends on it through npm:
 | `PROMPT_APPEND_SEP` | `system-prompt.ts` | the separator between a base system prompt and an appended block |
 | `canonicalSystemPrompt(systemPrompt, block)` | `system-prompt.ts` | the one canonical form of the system prompt — base + separator + block, appended exactly once at the end, whatever run-start path built it |
 | `systemPromptSlot(payload)` | `system-prompt.ts` | read/write access to a provider payload's system-prompt slot, or `null` for a payload shape that carries none |
+| `optionalNeighbour(neighbour, load, report)` | `neighbour.ts` | resolve an optional neighbour with a guarded dynamic import: never throws, resolves each `(source, neighbour)` pair once per process, and emits one `neighbour-absent` line per absent pair |
+| `NeighbourReport` | `neighbour.ts` | what that line carries: the reporting `source`, the lost `effect`, and an install `hint` |
+
+## Degradation contract
+
+[CONTRACT.md](CONTRACT.md) is the normative text every package in this repository
+implements: no work and no throw at module scope, optional neighbours resolved through
+`optionalNeighbour`, a named `neighbour-absent` line instead of an error, tool names owned
+outright, the active tool set touched only through a package's own name, one owner per
+shared path, order-free event seams, machine-bound capability refused at call time, and
+caveats declared as a README table row (machine-readable mirror gated on the loader
+ignoring an unknown `pi` key). Check a package with `node scripts/check-caveats.mjs` and
+`node --experimental-strip-types packages/ext-lib/src/neighbour.probe.ts`.
 
 ## What is deliberately not here
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tinoy/pi-ext-lib",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Shared helpers for pi extensions: the hook log envelope, TUI tool headers, and the system-prompt block seam.",
 	"license": "MIT",
 	"repository": {
@@ -17,13 +17,21 @@
 		".": "./src/index.ts"
 	},
 	"files": [
-		"src",
+		"src/hook-log.ts",
+		"src/index.ts",
+		"src/neighbour.ts",
+		"src/system-prompt.ts",
+		"src/tool-header.ts",
+		"CONTRACT.md",
 		"README.md",
 		"LICENSE"
 	],
 	"keywords": [
 		"pi-package"
 	],
+	"pi": {
+		"extensions": []
+	},
 	"engines": {
 		"node": ">=22"
 	}

package/src/index.ts

@@ -10,6 +10,7 @@
  * package that depends on this one.
  */
 export { HOOK_LOG_PATH, hookLog } from "./hook-log.ts";
+export { type NeighbourReport, optionalNeighbour } from "./neighbour.ts";
 export {
 	canonicalSystemPrompt,
 	PROMPT_APPEND_SEP,

package/src/neighbour.ts

@@ -0,0 +1,91 @@
+/**
+ * neighbour — the guarded, cached dynamic import for anything a user may not
+ * have installed.
+ *
+ * An extension that needs a package the user did not install must not fail to
+ * load: a static import of an absent module is a loader error row, the whole
+ * extension is dropped, and every feature it carried goes with it. Resolving the
+ * neighbour here keeps the extension loaded, reports the absence once by name,
+ * and lets the caller refuse only the capability that needed it.
+ *
+ * Guarantees, in the order they matter:
+ *   - it never throws: a rejected import and a throw inside `load` both answer
+ *     null;
+ *   - each `(source, neighbour)` pair resolves ONCE per process, so a hot path
+ *     cannot re-attempt an absent import on every call;
+ *   - exactly one `neighbour-absent` diagnostics line is emitted per absent pair
+ *     per process, carrying the neighbour, the lost capability and the fix.
+ *
+ * The cache is keyed by reporting package AND neighbour. One extension's absent
+ * neighbour therefore never masks another's present one, two packages reaching
+ * the same absent neighbour each report it under their own source (their effects
+ * differ), and a second call site in one package reuses the first resolution.
+ */
+import { hookLog } from "./hook-log.ts";
+
+/** What a call site states so an absence is actionable rather than merely visible. */
+export interface NeighbourReport {
+	/** The reporting package, as it appears in the diagnostics log. */
+	source: string;
+	/** What is lost while the neighbour is absent, in one clause. */
+	effect: string;
+	/** The install command or setting that restores the capability. */
+	hint?: string;
+}
+
+/** One resolution per reporting package and neighbour, per process. */
+const resolutions = new Map<string, Promise<unknown>>();
+
+/** One report per absent pair, per process: repeated calls never repeat the line. */
+const reported = new Set<string>();
+
+function keyOf(source: string, neighbour: string): string {
+	return `${source}\u0000${neighbour}`;
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Resolve an optional neighbour, or answer null when it cannot be loaded.
+ *
+ * ```ts
+ * const rpiv = await optionalNeighbour(
+ *   "@juicesharp/rpiv-todo",
+ *   () => import("@juicesharp/rpiv-todo/state/state-reducer.js"),
+ *   {
+ *     source: "todo-parent",
+ *     effect: "the child-to-parent todo relay cannot apply a mutation",
+ *     hint: "pi install npm:@juicesharp/rpiv-todo",
+ *   },
+ * );
+ * if (!rpiv) return refusal("todo_parent: the rpiv-todo state reducer is not installed");
+ * ```
+ */
+export function optionalNeighbour<T>(
+	neighbour: string,
+	load: () => Promise<T>,
+	report: NeighbourReport,
+): Promise<T | null> {
+	const key = keyOf(report.source, neighbour);
+	const cached = resolutions.get(key);
+	if (cached) return cached as Promise<T | null>;
+	// Promise.resolve().then(load) also catches a `load` that throws synchronously.
+	const pending: Promise<T | null> = Promise.resolve()
+		.then(load)
+		.catch((error: unknown) => {
+			if (!reported.has(key)) {
+				reported.add(key);
+				hookLog(report.source, "neighbour-absent", {
+					neighbour,
+					effect: report.effect,
+					...(report.hint ? { hint: report.hint } : {}),
+					reason: messageOf(error),
+				});
+			}
+			return null;
+		});
+	resolutions.set(key, pending);
+	return pending;
+}