pi-extension-utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,31 @@
+# pi-extension-utils
+
+Shared utilities for Pi extensions. This package has two faces:
+
+- `index.ts` is the Pi host extension registered through `package.json` `pi.extensions`.
+- `src/index.ts` is the client library surface that other extensions can vendor and import.
+
+## Architecture
+
+The host and clients communicate over Pi's shared in-process `pi.events` bus. Protocol events are namespaced as `pi-extension-utils:*` and every payload carries `protocolVersion` and `clientId`. Payloads may carry live function references because they never leave the process.
+
+Clients emit `hello` and listen for `ready`. Before a host is ready, widget calls fall back to the consumer extension's own `ctx.ui.setWidget`. If a host arrives later, fallback widgets are cleared and re-registered through the coordinator.
+
+The host owns one real widget per placement and composes registered sub-widgets sorted by `(order, insertion)`. Fullscreen leases blank coordinated widgets until all leases are released or the owning client disposes.
+
+## API sketch
+
+```ts
+import { connect, createLogger } from "pi-extension-utils";
+
+const client = connect(pi, { ctx, clientId: "my-extension" });
+client.widgets.set("belowEditor", "status", (tui, theme) => component, { order: 10 });
+client.widgets.remove("belowEditor", "status");
+
+const lease = client.fullscreen.acquire();
+lease.release();
+client.dispose();
+
+const log = createLogger("my-extension");
+log.info("started");
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,143 @@
+import { basePayload, EVENTS, PROTOCOL_VERSION, } from "./src/protocol.js";
+const HOST_CLIENT_ID = "pi-extension-utils-host";
+const HOST_WIDGET_PREFIX = "pi-extension-utils";
+const PLACEMENTS = ["aboveEditor", "belowEditor"];
+export default function (pi) {
+    const widgets = new Map();
+    const fullscreenStack = [];
+    let seq = 0;
+    let currentCtx;
+    for (const placement of PLACEMENTS)
+        widgets.set(placement, []);
+    function setHostWidget(placement) {
+        if (!currentCtx)
+            return;
+        const records = sortedWidgets(placement);
+        const hidden = fullscreenStack.length > 0;
+        if (records.length === 0 && !hidden) {
+            currentCtx.ui.setWidget(hostKey(placement), undefined, { placement });
+            return;
+        }
+        currentCtx.ui.setWidget(hostKey(placement), (tui, theme) => createHostComponent(tui, theme, records, hidden), { placement });
+    }
+    function rerenderAll() {
+        for (const placement of PLACEMENTS)
+            setHostWidget(placement);
+    }
+    pi.events.on(EVENTS.hello, (data) => {
+        const payload = readPayload(data, "hello");
+        if (!payload)
+            return;
+        pi.events.emit(EVENTS.ready, basePayload(HOST_CLIENT_ID));
+    });
+    pi.events.on(EVENTS.registerWidget, (data) => {
+        const payload = readPayload(data, "register-widget");
+        if (!payload || !isPlacement(payload.placement) || typeof payload.key !== "string" || typeof payload.order !== "number" || typeof payload.factory !== "function") {
+            warnDrop("register-widget", data);
+            return;
+        }
+        const records = widgets.get(payload.placement);
+        const existing = records.find((record) => record.clientId === payload.clientId && record.key === payload.key);
+        if (existing) {
+            existing.order = payload.order;
+            existing.factory = payload.factory;
+        }
+        else {
+            records.push({ clientId: payload.clientId, key: payload.key, order: payload.order, factory: payload.factory, seq: seq++ });
+        }
+        setHostWidget(payload.placement);
+    });
+    pi.events.on(EVENTS.unregisterWidget, (data) => {
+        const payload = readPayload(data, "unregister-widget");
+        if (!payload)
+            return;
+        if (payload.all) {
+            removeClient(payload.clientId);
+            rerenderAll();
+            return;
+        }
+        if (!isPlacement(payload.placement) || typeof payload.key !== "string") {
+            warnDrop("unregister-widget", data);
+            return;
+        }
+        const records = widgets.get(payload.placement);
+        widgets.set(payload.placement, records.filter((record) => record.clientId !== payload.clientId || record.key !== payload.key));
+        setHostWidget(payload.placement);
+    });
+    pi.events.on(EVENTS.fullscreenAcquire, (data) => {
+        const payload = readPayload(data, "fullscreen-acquire");
+        if (!payload || typeof payload.token !== "string") {
+            warnDrop("fullscreen-acquire", data);
+            return;
+        }
+        if (!fullscreenStack.some((lease) => lease.token === payload.token)) {
+            fullscreenStack.push({ clientId: payload.clientId, token: payload.token });
+            rerenderAll();
+        }
+    });
+    pi.events.on(EVENTS.fullscreenRelease, (data) => {
+        const payload = readPayload(data, "fullscreen-release");
+        if (!payload || typeof payload.token !== "string") {
+            warnDrop("fullscreen-release", data);
+            return;
+        }
+        const before = fullscreenStack.length;
+        for (let index = fullscreenStack.length - 1; index >= 0; index--) {
+            if (fullscreenStack[index].token === payload.token)
+                fullscreenStack.splice(index, 1);
+        }
+        if (fullscreenStack.length !== before)
+            rerenderAll();
+    });
+    pi.on("session_start", (_event, ctx) => {
+        currentCtx = ctx;
+        rerenderAll();
+        pi.events.emit(EVENTS.ready, basePayload(HOST_CLIENT_ID));
+    });
+    pi.events.emit(EVENTS.ready, basePayload(HOST_CLIENT_ID));
+    function removeClient(clientId) {
+        for (const placement of PLACEMENTS) {
+            widgets.set(placement, widgets.get(placement).filter((record) => record.clientId !== clientId));
+        }
+        for (let index = fullscreenStack.length - 1; index >= 0; index--) {
+            if (fullscreenStack[index].clientId === clientId)
+                fullscreenStack.splice(index, 1);
+        }
+    }
+    function sortedWidgets(placement) {
+        return [...widgets.get(placement)].sort((a, b) => a.order - b.order || a.seq - b.seq);
+    }
+}
+function createHostComponent(tui, theme, records, hidden) {
+    const components = hidden ? [] : records.map((record) => record.factory(tui, theme));
+    return {
+        render(width) {
+            return components.flatMap((component) => component.render(width));
+        },
+        invalidate() {
+            for (const component of components)
+                component.invalidate();
+        },
+    };
+}
+function hostKey(placement) {
+    return `${HOST_WIDGET_PREFIX}-${placement}`;
+}
+function readPayload(data, eventName) {
+    if (!data || typeof data !== "object") {
+        warnDrop(eventName, data);
+        return undefined;
+    }
+    const payload = data;
+    if (typeof payload.protocolVersion !== "number" || payload.protocolVersion > PROTOCOL_VERSION || typeof payload.clientId !== "string") {
+        warnDrop(eventName, data);
+        return undefined;
+    }
+    return payload;
+}
+function isPlacement(value) {
+    return value === "aboveEditor" || value === "belowEditor";
+}
+function warnDrop(eventName, data) {
+    console.warn(`pi-extension-utils: dropping invalid ${eventName} payload`, data);
+}

package/dist/src/client.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WidgetFactory, WidgetPlacement } from "./protocol.ts";
+export interface UtilsClientOptions {
+    ctx: ExtensionContext;
+    clientId?: string;
+}
+export interface WidgetSetOptions {
+    order?: number;
+}
+export interface FullscreenLease {
+    release(): void;
+}
+export interface UtilsClient {
+    readonly clientId: string;
+    readonly mode: "fallback" | "coordinated";
+    widgets: {
+        set(placement: WidgetPlacement, key: string, factory: WidgetFactory, opts?: WidgetSetOptions): void;
+        remove(placement: WidgetPlacement, key: string): void;
+    };
+    fullscreen: {
+        acquire(): FullscreenLease;
+    };
+    dispose(): void;
+}
+export declare function connect(pi: ExtensionAPI, opts: UtilsClientOptions): UtilsClient;

package/dist/src/client.js

@@ -0,0 +1,132 @@
+import { basePayload, EVENTS, PROTOCOL_VERSION, } from "./protocol.js";
+let nextClientId = 1;
+let nextLeaseId = 1;
+export function connect(pi, opts) {
+    const clientId = opts.clientId ?? `client-${process.pid}-${Date.now()}-${nextClientId++}`;
+    const widgets = new Map();
+    const leases = new Set();
+    let disposed = false;
+    let coordinated = false;
+    const widgetId = (placement, key) => `${placement}:${key}`;
+    function emitRegister(record) {
+        pi.events.emit(EVENTS.registerWidget, {
+            ...basePayload(clientId),
+            placement: record.placement,
+            key: record.key,
+            order: record.order,
+            factory: record.factory,
+        });
+    }
+    function clearFallback(record) {
+        opts.ctx.ui.setWidget(record.key, undefined, { placement: record.placement });
+    }
+    function restoreFallback(record) {
+        opts.ctx.ui.setWidget(record.key, record.factory, { placement: record.placement });
+    }
+    function attach() {
+        if (disposed || coordinated)
+            return;
+        coordinated = true;
+        for (const record of widgets.values()) {
+            clearFallback(record);
+            emitRegister(record);
+        }
+        for (const token of leases) {
+            pi.events.emit(EVENTS.fullscreenAcquire, { ...basePayload(clientId), token });
+        }
+    }
+    const offReady = pi.events.on(EVENTS.ready, (data) => {
+        if (!isReadyPayload(data))
+            return;
+        attach();
+    });
+    pi.events.emit(EVENTS.hello, basePayload(clientId));
+    const client = {
+        clientId,
+        get mode() {
+            return coordinated ? "coordinated" : "fallback";
+        },
+        widgets: {
+            set(placement, key, factory, setOpts = {}) {
+                if (disposed)
+                    return;
+                const record = { placement, key, factory, order: setOpts.order ?? 0 };
+                widgets.set(widgetId(placement, key), record);
+                if (coordinated) {
+                    emitRegister(record);
+                }
+                else if (leases.size === 0) {
+                    opts.ctx.ui.setWidget(key, factory, { placement });
+                }
+            },
+            remove(placement, key) {
+                const id = widgetId(placement, key);
+                const record = widgets.get(id);
+                if (!record)
+                    return;
+                widgets.delete(id);
+                if (coordinated) {
+                    pi.events.emit(EVENTS.unregisterWidget, { ...basePayload(clientId), placement, key });
+                }
+                else {
+                    clearFallback(record);
+                }
+            },
+        },
+        fullscreen: {
+            acquire() {
+                const token = `${clientId}-lease-${nextLeaseId++}`;
+                let released = false;
+                const wasFallbackVisible = !coordinated && leases.size === 0;
+                leases.add(token);
+                if (coordinated) {
+                    pi.events.emit(EVENTS.fullscreenAcquire, { ...basePayload(clientId), token });
+                }
+                else if (wasFallbackVisible) {
+                    for (const record of widgets.values())
+                        clearFallback(record);
+                }
+                return {
+                    release() {
+                        if (released)
+                            return;
+                        released = true;
+                        leases.delete(token);
+                        if (coordinated && !disposed) {
+                            pi.events.emit(EVENTS.fullscreenRelease, { ...basePayload(clientId), token });
+                        }
+                        else if (!disposed && leases.size === 0) {
+                            for (const record of widgets.values())
+                                restoreFallback(record);
+                        }
+                    },
+                };
+            },
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            offReady();
+            if (coordinated) {
+                pi.events.emit(EVENTS.unregisterWidget, { ...basePayload(clientId), all: true });
+                for (const token of leases) {
+                    pi.events.emit(EVENTS.fullscreenRelease, { ...basePayload(clientId), token });
+                }
+            }
+            else {
+                for (const record of widgets.values())
+                    clearFallback(record);
+            }
+            leases.clear();
+            widgets.clear();
+        },
+    };
+    return client;
+}
+function isReadyPayload(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const payload = data;
+    return typeof payload.protocolVersion === "number" && payload.protocolVersion <= PROTOCOL_VERSION && typeof payload.clientId === "string";
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { connect, type FullscreenLease, type UtilsClient, type UtilsClientOptions, type WidgetSetOptions } from "./client.ts";
+export { createLogger, type Logger, type LoggerOptions } from "./logger.ts";
+export * from "./protocol.ts";

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export { connect } from "./client.js";
+export { createLogger } from "./logger.js";
+export * from "./protocol.js";

package/dist/src/logger.d.ts

@@ -0,0 +1,12 @@
+export interface LoggerOptions {
+    dir?: string;
+    maxBytes?: number;
+}
+export interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    log(level: string, message: string): void;
+}
+export declare function createLogger(ns: string, opts?: LoggerOptions): Logger;

package/dist/src/logger.js

@@ -0,0 +1,45 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+export function createLogger(ns, opts = {}) {
+    if (!ns || ns.includes("/") || ns.includes("\\")) {
+        throw new Error("Logger namespace must not contain path separators");
+    }
+    const dir = opts.dir ?? join(homedir(), ".pi", "logs");
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    const file = join(dir, `${ns}.log`);
+    mkdirSync(dirname(file), { recursive: true });
+    function rotateIfNeeded(nextBytes) {
+        if (maxBytes <= 0 || !existsSync(file))
+            return;
+        const size = statSync(file).size;
+        if (size + nextBytes <= maxBytes)
+            return;
+        const rotated = `${file}.1`;
+        if (existsSync(rotated))
+            rmSync(rotated);
+        renameSync(file, rotated);
+    }
+    function log(level, message) {
+        const line = `${new Date().toISOString()} ${level} ${message}\n`;
+        mkdirSync(dirname(file), { recursive: true });
+        rotateIfNeeded(Buffer.byteLength(line));
+        appendFileSync(file, line);
+    }
+    return {
+        debug(message) {
+            log("debug", message);
+        },
+        info(message) {
+            log("info", message);
+        },
+        warn(message) {
+            log("warn", message);
+        },
+        error(message) {
+            log("error", message);
+        },
+        log,
+    };
+}

package/dist/src/protocol.d.ts

@@ -0,0 +1,49 @@
+export declare const PROTOCOL_VERSION = 1;
+export declare const EVENT_PREFIX = "pi-extension-utils";
+export declare const HELLO_EVENT = "pi-extension-utils:hello";
+export declare const READY_EVENT = "pi-extension-utils:ready";
+export declare const REGISTER_WIDGET_EVENT = "pi-extension-utils:register-widget";
+export declare const UNREGISTER_WIDGET_EVENT = "pi-extension-utils:unregister-widget";
+export declare const FULLSCREEN_ACQUIRE_EVENT = "pi-extension-utils:fullscreen-acquire";
+export declare const FULLSCREEN_RELEASE_EVENT = "pi-extension-utils:fullscreen-release";
+export declare const EVENTS: {
+    readonly hello: "pi-extension-utils:hello";
+    readonly ready: "pi-extension-utils:ready";
+    readonly registerWidget: "pi-extension-utils:register-widget";
+    readonly unregisterWidget: "pi-extension-utils:unregister-widget";
+    readonly fullscreenAcquire: "pi-extension-utils:fullscreen-acquire";
+    readonly fullscreenRelease: "pi-extension-utils:fullscreen-release";
+};
+export type WidgetPlacement = "aboveEditor" | "belowEditor";
+export interface WidgetComponent {
+    render(width: number): string[];
+    invalidate(): void;
+    dispose?(): void;
+}
+export type WidgetFactory = (tui: unknown, theme: unknown) => WidgetComponent;
+export interface ProtocolPayload {
+    protocolVersion: number;
+    clientId: string;
+}
+export interface HelloPayload extends ProtocolPayload {
+}
+export interface ReadyPayload extends ProtocolPayload {
+}
+export interface RegisterWidgetPayload extends ProtocolPayload {
+    placement: WidgetPlacement;
+    key: string;
+    order: number;
+    factory: WidgetFactory;
+}
+export interface UnregisterWidgetPayload extends ProtocolPayload {
+    placement?: WidgetPlacement;
+    key?: string;
+    all?: boolean;
+}
+export interface FullscreenAcquirePayload extends ProtocolPayload {
+    token: string;
+}
+export interface FullscreenReleasePayload extends ProtocolPayload {
+    token: string;
+}
+export declare function basePayload(clientId: string): ProtocolPayload;

package/dist/src/protocol.js

@@ -0,0 +1,19 @@
+export const PROTOCOL_VERSION = 1;
+export const EVENT_PREFIX = "pi-extension-utils";
+export const HELLO_EVENT = `${EVENT_PREFIX}:hello`;
+export const READY_EVENT = `${EVENT_PREFIX}:ready`;
+export const REGISTER_WIDGET_EVENT = `${EVENT_PREFIX}:register-widget`;
+export const UNREGISTER_WIDGET_EVENT = `${EVENT_PREFIX}:unregister-widget`;
+export const FULLSCREEN_ACQUIRE_EVENT = `${EVENT_PREFIX}:fullscreen-acquire`;
+export const FULLSCREEN_RELEASE_EVENT = `${EVENT_PREFIX}:fullscreen-release`;
+export const EVENTS = {
+    hello: HELLO_EVENT,
+    ready: READY_EVENT,
+    registerWidget: REGISTER_WIDGET_EVENT,
+    unregisterWidget: UNREGISTER_WIDGET_EVENT,
+    fullscreenAcquire: FULLSCREEN_ACQUIRE_EVENT,
+    fullscreenRelease: FULLSCREEN_RELEASE_EVENT,
+};
+export function basePayload(clientId) {
+    return { protocolVersion: PROTOCOL_VERSION, clientId };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "pi-extension-utils",
+	"version": "0.1.0",
+	"description": "Shared Pi extension utilities for coordinated widgets, fullscreen leases, and logging.",
+	"type": "module",
+	"main": "./dist/src/index.js",
+	"types": "./dist/src/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/src/index.d.ts",
+			"default": "./dist/src/index.js"
+		}
+	},
+	"files": ["dist", "README.md", "LICENSE"],
+	"pi": {
+		"extensions": ["./dist/index.js"]
+	},
+	"scripts": {
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
+		"prepublishOnly": "npm run typecheck && npm test && npm run build",
+		"test": "node --test --experimental-strip-types test/**/*.test.ts",
+		"typecheck": "tsc --noEmit"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "MIT",
+	"peerDependencies": {
+		"@earendil-works/pi-agent-core": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-agent-core": "^0.75.4",
+		"@earendil-works/pi-ai": "^0.75.4",
+		"@earendil-works/pi-coding-agent": "^0.75.4",
+		"@types/node": "^24.0.0",
+		"typescript": "^6.0.3"
+	}
+}