@tinoy/pi-ext-lib 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tinoy Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @tinoy/pi-ext-lib
+
+Shared helpers for pi extensions. This package registers nothing with pi — it has
+no `pi` manifest and no extension entry — and is consumed as a dependency by
+extension packages.
+
+```bash
+pi install npm:@tinoy/pi-ext-lib   # installs it; nothing is registered with pi
+```
+
+An extension package depends on it through npm:
+
+```json
+{ "dependencies": { "@tinoy/pi-ext-lib": "^0.1.0" } }
+```
+
+## API
+
+| Export | Module | Purpose |
+| --- | --- | --- |
+| `hookLog(source, kind, detail?)` | `hook-log.ts` | the one diagnostics envelope: `{ts, proc, sid, source, kind, detail}` per line, JSONL in `~/.local/share/pi-hooks/log.jsonl`. Fail-open — a logging failure never breaks the call that emitted it |
+| `HOOK_LOG_PATH` | `hook-log.ts` | that file's path |
+| `clip(text, max?)` | `tool-header.ts` | flatten whitespace and clip to `max` characters with an ellipsis |
+| `argText(args, key)` / `argNumber(args, key)` | `tool-header.ts` | a non-empty trimmed string argument / a finite numeric argument, else `undefined` |
+| `renderToolHeader(theme, name, parts?)` | `tool-header.ts` | the duck-typed one-line header component (`render(width)` + `invalidate()`) a tool's `renderCall` returns |
+| `safeToolHeader(theme, name, build)` | `tool-header.ts` | `renderToolHeader` behind a guard: a throwing `build` degrades to the name alone |
+| `HeaderTheme`, `HeaderComponent`, `HeaderPart` | `tool-header.ts` | the header types |
+| `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 |
+
+## What is deliberately not here
+
+Anything that carries one extension's policy stays in that extension. From the
+prompt seam in `packages/canon`, the tail-section registry (`setTailSection`,
+`registeredSectionIds`) was left out: it owns canon's `canon:section` /
+`canon:sections` event contract, logs under the `canon` source, and its 16 KiB
+section cap is canon's. `canonicalSystemPrompt`, `systemPromptSlot`,
+`PROMPT_APPEND_SEP` are policy-free and live here.
+
+## Dependencies
+
+Node builtins only (`node:fs`, `node:os`, `node:path`). No pi package is
+imported, so this package declares no peer dependency.
+
+## Licence
+
+MIT — see the repository [LICENSE](../../LICENSE).

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@tinoy/pi-ext-lib",
+	"version": "0.1.0",
+	"description": "Shared helpers for pi extensions: the hook log envelope, TUI tool headers, and the system-prompt block seam.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tinoy1336/pi-extensions.git",
+		"directory": "packages/ext-lib"
+	},
+	"homepage": "https://github.com/tinoy1336/pi-extensions/tree/main/packages/ext-lib#readme",
+	"bugs": {
+		"url": "https://github.com/tinoy1336/pi-extensions/issues"
+	},
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"pi-package"
+	],
+	"engines": {
+		"node": ">=22"
+	}
+}

package/src/hook-log.ts

@@ -0,0 +1,47 @@
+/**
+ * hook-log: the ONE diagnostics envelope every extension writes.
+ *
+ * Each extension grew its own log file, its own line shape and its own path,
+ * so answering "what did my extensions actually do this session" meant reading
+ * four formats in four places. Every diagnostic line now lands here as
+ * `{ts, source, kind, detail}`, one JSON object per line.
+ *
+ * This file is OBSERVABILITY ONLY — nothing reads it back to make a decision.
+ * Functional ledgers keep their own files (focus-gate's ledger is read by the
+ * gate itself to queue deferred actions; no-subagent-fork's rewrites are its
+ * own audit trail). Diagnostics here, state there.
+ *
+ * Fail-open: a logging failure must never break the tool call that emitted it.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const LOG_DIR = join(homedir(), ".local/share/pi-hooks");
+
+export const HOOK_LOG_PATH = join(LOG_DIR, "log.jsonl");
+
+export function hookLog(source: string, kind: string, detail: Record<string, unknown> = {}): void {
+  try {
+    mkdirSync(LOG_DIR, { recursive: true });
+    // Identity for readers has two parts, because neither alone is enough:
+    //   `proc` — the pi process that emitted this (unique per running session,
+    //            immune to environment inheritance). Footer counters filter on it.
+    //   `sid`  — PI_SESSION_ID. Useful for cross-session analytics, but it is an
+    //            INHERITED env var: a pi started from inside another pi session
+    //            keeps the parent's id, so it can NOT be trusted as identity.
+    appendFileSync(
+      HOOK_LOG_PATH,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        proc: process.pid,
+        sid: process.env.PI_SESSION_ID ?? "",
+        source,
+        kind,
+        detail,
+      }) + "\n",
+    );
+  } catch {
+    /* never break a tool call over logging */
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @tinoy/pi-ext-lib — the shared helpers pi extensions in this monorepo import.
+ *
+ * This is the package's whole public API. Every module here is host-agnostic:
+ * no extension's policy, no extension's store path, no extension's tool schema.
+ *
+ * `hook-log.ts` and `tool-header.ts` are verbatim copies of the live extension
+ * sources (a single `cp`, never edited in place here) — the second consumer of
+ * each was already in the tree, so the copy is the one canonical file for any
+ * package that depends on this one.
+ */
+export { HOOK_LOG_PATH, hookLog } from "./hook-log.ts";
+export {
+	canonicalSystemPrompt,
+	PROMPT_APPEND_SEP,
+	systemPromptSlot,
+} from "./system-prompt.ts";
+export {
+	argNumber,
+	argText,
+	clip,
+	type HeaderComponent,
+	type HeaderPart,
+	type HeaderTheme,
+	renderToolHeader,
+	safeToolHeader,
+} from "./tool-header.ts";

package/src/system-prompt.ts

@@ -0,0 +1,112 @@
+/**
+ * system-prompt — the shared seam for appending a block to the system prompt of
+ * every provider request.
+ *
+ * An extension that appends to the system prompt faces two pi behaviours this
+ * module exists to absorb:
+ *
+ *   - `before_agent_start` fires ONLY from the interactive `prompt()` path. A run
+ *     started by an injected message (`pi.sendMessage(msg, {triggerTurn:true})`
+ *     while idle) calls `agent.prompt()` directly, so an append made there never
+ *     lands on that request.
+ *   - The provider prefix is `[system, tools, messages]`, so a system prompt that
+ *     differs between two requests of one session re-bills every byte after it as
+ *     a cache miss.
+ *
+ * The pair below is the fix for both: `before_agent_start` builds the text, and
+ * `before_provider_request` re-normalizes the payload through
+ * `canonicalSystemPrompt` so every request leaves with identical bytes whatever
+ * path produced it.
+ *
+ * Nothing here is policy: the block's content, its scope rules and what happens
+ * when the payload cannot be rewritten belong to the extension that calls this.
+ */
+
+/** Separator between the base system prompt and the appended block. */
+export const PROMPT_APPEND_SEP = "\n\n";
+
+/** The line that opens the appended block; also the strip marker. Derived from
+ *  the block, never a second literal, so the strip/append rule cannot drift from
+ *  the renderer that produced the block. */
+function blockMarker(block: string): string {
+	const nl = block.indexOf("\n");
+	return `${PROMPT_APPEND_SEP}${nl === -1 ? block : block.slice(0, nl)}`;
+}
+
+/** The ONE canonical form of the system prompt: base + separator + block, the
+ *  block appended exactly once at the end. Whatever arrives is mapped to it, so
+ *  the bytes cannot depend on which run-start path built the request:
+ *    - base only (a run that never fired before_agent_start) -> base + block;
+ *    - base + block (the normal path) -> unchanged;
+ *    - a fork that inherited a block rendered for another scope, or a request
+ *      that was appended twice -> stripped back to base, then the ONE current
+ *      block is appended.
+ *  Stripping takes the FIRST marker: a duplicated block is delimited there. */
+export function canonicalSystemPrompt(
+	systemPrompt: string,
+	block: string,
+): { text: string; hadBlock: boolean } {
+	const marker = blockMarker(block);
+	const at = systemPrompt.indexOf(marker);
+	const base = at === -1 ? systemPrompt : systemPrompt.slice(0, at);
+	return { text: `${base}${PROMPT_APPEND_SEP}${block}`, hadBlock: at !== -1 };
+}
+
+/** The system-prompt slot of a provider payload, or null when the payload shape
+ * carries none we can rewrite. Provider shapes covered: openai-completions /
+ * openai-responses / codex (first message, role "system" or "developer"), a
+ * top-level `system` string, OpenAI Responses `instructions`, and the
+ * anthropic-messages `system` block list when it holds a single text block. */
+export function systemPromptSlot(
+	payload: unknown,
+): { get: () => string; set: (text: string) => void } | null {
+	if (!payload || typeof payload !== "object") return null;
+	const p = payload as Record<string, unknown>;
+	if (Array.isArray(p.messages) && p.messages.length > 0) {
+		const first = p.messages[0] as { role?: unknown; content?: unknown };
+		if (
+			first &&
+			typeof first === "object" &&
+			(first.role === "system" || first.role === "developer") &&
+			typeof first.content === "string"
+		) {
+			return {
+				get: () => first.content as string,
+				set: (text) => {
+					first.content = text;
+				},
+			};
+		}
+	}
+	if (typeof p.system === "string") {
+		return {
+			get: () => p.system as string,
+			set: (text) => {
+				p.system = text;
+			},
+		};
+	}
+	if (Array.isArray(p.system)) {
+		const textBlocks = (p.system as Array<{ text?: unknown }>).filter(
+			(b) => b && typeof b === "object" && typeof b.text === "string",
+		);
+		if (textBlocks.length === 1) {
+			const block = textBlocks[0] as { text: string };
+			return {
+				get: () => block.text,
+				set: (text) => {
+					block.text = text;
+				},
+			};
+		}
+	}
+	if (typeof p.instructions === "string") {
+		return {
+			get: () => p.instructions as string,
+			set: (text) => {
+				p.instructions = text;
+			},
+		};
+	}
+	return null;
+}

package/src/tool-header.ts

@@ -0,0 +1,121 @@
+/**
+ * tool-header — the shared `renderCall` header builder for the local extensions.
+ *
+ * pi bundles its TUI inside the agent and does not expose `@earendil-works/pi-tui`
+ * to extensions, so a header cannot be a `Text`; it must be a duck-typed
+ * component (`render(width)` + `invalidate()`), the shape
+ * extensions/deepseek-cost.ts uses for its entry renderer.
+ *
+ * A header is ONE line: the tool name plus the few fields a reader needs to
+ * follow the transcript. Free text is flattened and clipped before theming, so
+ * no ANSI sequence is ever cut; a narrower terminal wraps the line without
+ * losing the color in force.
+ */
+
+export interface HeaderTheme {
+	// `any` on the color keeps pi's richer Theme assignable to this narrow shape
+	fg?: (color: any, text: string) => string;
+	bold?: (text: string) => string;
+}
+
+export interface HeaderComponent {
+	render(width: number): string[];
+	invalidate(): void;
+}
+
+/** One colored run of a header line: [theme color, text]. */
+export type HeaderPart = readonly [string, string];
+
+const SGR_RE = /^\x1b\[[0-9;]*m/;
+
+/** Flatten whitespace and clip to `max` characters with an ellipsis. */
+export function clip(text: string, max = 80): string {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length > max ? `${flat.slice(0, Math.max(1, max - 1))}…` : flat;
+}
+
+/** A non-empty trimmed string argument, or undefined. */
+export function argText(args: unknown, key: string): string | undefined {
+	const value = (args as Record<string, unknown> | null | undefined)?.[key];
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+
+/** A finite numeric argument, or undefined. */
+export function argNumber(args: unknown, key: string): number | undefined {
+	const value = (args as Record<string, unknown> | null | undefined)?.[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/** Visible width (SGR sequences are zero-width). */
+function visibleWidth(text: string): number {
+	return text.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+/** Break an over-long segment at `width`, re-applying the color in force. */
+function splitSegment(segment: string, width: number, lines: string[]): string {
+	let current = "";
+	let color = "";
+	let visible = 0;
+	for (let i = 0; i < segment.length; ) {
+		const escape = SGR_RE.exec(segment.slice(i, i + 16));
+		if (escape) {
+			color = escape[0];
+			current += escape[0];
+			i += escape[0].length;
+			continue;
+		}
+		if (visible >= width) {
+			lines.push(current);
+			current = color;
+			visible = 0;
+		}
+		current += segment[i];
+		visible += 1;
+		i += 1;
+	}
+	return current;
+}
+
+/** Wrap the header's colored segments at `width`, never cutting an escape. */
+function wrapSegments(segments: string[], width: number): string[] {
+	const lines: string[] = [];
+	let line = "";
+	for (const segment of segments) {
+		if (!segment) continue;
+		if (line && visibleWidth(line) + visibleWidth(segment) > width) {
+			lines.push(line.replace(/\s+$/, ""));
+			line = "";
+		}
+		if (!line && visibleWidth(segment) > width) {
+			line = splitSegment(segment, width, lines);
+			continue;
+		}
+		line += segment;
+	}
+	lines.push(line);
+	return lines;
+}
+
+/** Build the header component: the tool name bold, then one run per part. */
+export function renderToolHeader(theme: HeaderTheme | undefined, name: string, parts: HeaderPart[] = []): HeaderComponent {
+	const fg = (color: string, text: string): string => (theme?.fg ? theme.fg(color, text) : text);
+	const bold = (text: string): string => (theme?.bold ? theme.bold(text) : text);
+	const segments = [fg("toolTitle", bold(name))];
+	for (const [color, text] of parts) {
+		if (!text) continue;
+		segments.push(color ? fg(color, text) : text);
+	}
+	return {
+		render: (width: number) => wrapSegments(segments, Math.max(1, Math.floor(width))),
+		invalidate: () => {},
+	};
+}
+
+/** `renderToolHeader` behind a guard: an odd argument set degrades to the name alone. */
+export function safeToolHeader(theme: HeaderTheme | undefined, name: string, build: () => HeaderPart[]): HeaderComponent {
+	try {
+		return renderToolHeader(theme, name, build());
+	} catch {
+		return renderToolHeader(theme, name);
+	}
+}