pi-extension-utils 0.3.1 → 0.3.3

package/dist/src/reminders/index.js

@@ -1,308 +1,3 @@
-import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { loadConfig, saveConfig } from "./config.js";
-import { writeReminderDiagnostic } from "./debug.js";
-import { ReminderManager } from "./manager.js";
-import { REMINDER_ANNOUNCE_NOW_EVENT, REMINDER_CLEAR_SOURCE_EVENT, REMINDER_LIST_EVENT, REMINDER_REMOVE_EVENT, REMINDER_UPSERT_EVENT, } from "./types.js";
-/** Register the pi-reminders extension hooks and event listeners. */
-export function registerReminderHost(pi, manager = new ReminderManager()) {
-    const eventBus = pi.events;
-    const cfg = {};
-    const refreshConfig = (cwd) => {
-        delete cfg.debugShowAllInTui;
-        Object.assign(cfg, loadConfig(cwd));
-    };
-    const debugShowAllInTui = (ctx) => {
-        refreshConfig(resolveCwd(ctx));
-        return isDebugModeEnabled(cfg);
-    };
-    writeReminderDiagnostic({
-        event: "reminder_extension_init",
-    });
-    writeReminderDiagnostic({
-        event: "reminder_extension_register_start",
-    });
-    eventBus.on(REMINDER_UPSERT_EVENT, (payload) => {
-        if (isRecord(payload))
-            manager.upsert(payload);
-    });
-    eventBus.on(REMINDER_REMOVE_EVENT, (payload) => {
-        if (isRecord(payload))
-            manager.remove(payload);
-    });
-    eventBus.on(REMINDER_CLEAR_SOURCE_EVENT, (payload) => {
-        if (isRecord(payload))
-            manager.clearSource(payload);
-    });
-    eventBus.on(REMINDER_ANNOUNCE_NOW_EVENT, (payload) => {
-        manager.forceAnnounce(isRecord(payload) ? payload : {});
-    });
-    eventBus.on(REMINDER_LIST_EVENT, (payload) => {
-        if (isRecord(payload) && typeof payload.resolve === "function") {
-            handleListRequest(manager, payload);
-        }
-    });
-    if (typeof pi.registerMessageRenderer === "function") {
-        pi.registerMessageRenderer("pi-reminders", (message, _options, theme) => {
-            const details = isRecord(message.details) ? message.details : undefined;
-            const content = typeof details?.displayText === "string"
-                ? details.displayText
-                : stripSystemReminderWrapper(extractTextContent(message.content));
-            return new SystemReminderComponent(content, details, theme);
-        });
-    }
-    pi.on("session_start", (_event, ctx) => {
-        manager.clearSession();
-        refreshConfig(resolveCwd(ctx));
-        writeReminderDiagnostic({
-            event: "reminder_session_start",
-            sessionId: getSessionId(ctx),
-            cwd: getCwd(ctx),
-            providerApi: getProviderApi(ctx),
-        });
-    });
-    pi.on("session_shutdown", () => {
-        manager.clearSession();
-    });
-    pi.on("turn_start", () => {
-        manager.advanceTurn();
-    });
-    pi.on("before_agent_start", (_event, ctx) => {
-        const announcement = manager.collectDueAnnouncement({ showHiddenInDisplay: debugShowAllInTui(ctx) });
-        if (!announcement)
-            return;
-        const message = buildReminderMessage(announcement, getContextUsage(ctx));
-        writeAnnouncementDiagnostic("reminder_history_message", message);
-        return { message };
-    });
-    pi.on("context", (_event, ctx) => {
-        const announcement = manager.collectDueAnnouncement({ showHiddenInDisplay: debugShowAllInTui(ctx) });
-        if (!announcement)
-            return;
-        const message = buildReminderMessage(announcement, getContextUsage(ctx));
-        writeAnnouncementDiagnostic("reminder_context_message", message);
-        pi.sendMessage(message, { deliverAs: "steer" });
-    });
-    pi.registerCommand("reminders", {
-        description: "Open pi-reminders settings",
-        handler: async (_args, ctx) => {
-            const cwd = resolveCwd(ctx);
-            refreshConfig(cwd);
-            const current = debugShowAllInTui(ctx) ? "on" : "off";
-            const choice = await ctx.ui.select("Reminders debug: show all in TUI", [`${current === "on" ? "[on]" : "on"}`, `${current === "off" ? "[off]" : "off"}`, "← Back"]);
-            if (!choice || choice === "← Back")
-                return;
-            cfg.debugShowAllInTui = choice.includes("on");
-            saveConfig(cfg, cwd);
-            ctx.ui.notify(`Reminders debug show-all in TUI ${cfg.debugShowAllInTui ? "enabled" : "disabled"}`, "info");
-        },
-    });
-    pi.registerCommand("remind", {
-        description: "Add a debug system reminder",
-        handler: async (args, ctx) => {
-            const text = args.trim();
-            if (!text) {
-                ctx.ui.notify("Usage: /remind <text>", "warning");
-                return;
-            }
-            manager.upsert({
-                source: "pi-reminders",
-                id: "debug-command",
-                label: "Reminder",
-                text,
-                priority: 100,
-                ttl: "once",
-            });
-            ctx.ui.notify("Reminder added", "info");
-        },
-    });
-    writeReminderDiagnostic({
-        event: "reminder_extension_registered",
-        hasEvents: eventBus !== undefined,
-        hasRegisterCommand: typeof pi.registerCommand === "function",
-        hasRegisterMessageRenderer: typeof pi.registerMessageRenderer === "function",
-        hasOn: typeof pi.on === "function",
-    });
-    return manager;
-}
-export default function reminderHost(pi) {
-    try {
-        registerReminderHost(pi);
-    }
-    catch (error) {
-        writeReminderDiagnostic({
-            event: "reminder_extension_register_error",
-            errorName: error instanceof Error ? error.name : undefined,
-            errorMessage: error instanceof Error ? error.message : String(error),
-            errorStack: error instanceof Error ? error.stack : undefined,
-        });
-        throw error;
-    }
-}
-function handleListRequest(manager, request) {
-    try {
-        request.resolve(manager.snapshot(request.source));
-    }
-    catch (error) {
-        request.reject?.(error);
-    }
-}
-function isDebugModeEnabled(config) {
-    const value = process.env.PI_REMINDERS_DEBUG?.trim().toLowerCase();
-    if (value)
-        return value === "1" || value === "true" || value === "yes" || value === "on";
-    return config.debugShowAllInTui === true;
-}
-function buildReminderMessage(announcement, usage) {
-    const sources = [...new Set(announcement.reminders.map((reminder) => reminder.source))].sort();
-    const modelBody = includesDcpReminder(announcement.reminders)
-        ? appendContextUsageLine(stripSystemReminderWrapper(announcement.text), usage)
-        : stripSystemReminderWrapper(announcement.text);
-    const displayText = announcement.displayText && includesDcpReminder(announcement.displayReminders)
-        ? appendContextUsageLine(announcement.displayText, usage)
-        : announcement.displayText;
-    const content = `<system-reminder>\n${modelBody}\n</system-reminder>`;
-    return {
-        customType: "pi-reminders",
-        content,
-        display: displayText !== null,
-        details: {
-            reminderCount: announcement.reminders.length,
-            sources,
-            displayText: displayText ?? undefined,
-        },
-    };
-}
-function writeAnnouncementDiagnostic(event, message) {
-    const details = message.details;
-    writeReminderDiagnostic({
-        event,
-        activeReminderCount: details?.reminderCount,
-        sources: details?.sources,
-        trailerChars: message.content.length,
-    });
-}
-function getContextUsage(ctx) {
-    if (!isRecord(ctx) || typeof ctx.getContextUsage !== "function")
-        return undefined;
-    try {
-        const usage = ctx.getContextUsage();
-        if (!isRecord(usage) || typeof usage.contextWindow !== "number")
-            return undefined;
-        const tokens = typeof usage.tokens === "number" ? usage.tokens : null;
-        return { tokens, contextWindow: usage.contextWindow };
-    }
-    catch {
-        return undefined;
-    }
-}
-function includesDcpReminder(reminders) {
-    return reminders.some((reminder) => {
-        const source = reminder.source.trim().toLowerCase();
-        return source === "dcp" || source === "pi-dynamic-context-pruning";
-    });
-}
-function appendContextUsageLine(displayText, usage) {
-    if (!usage)
-        return displayText;
-    const contextWindow = formatTokenCount(usage.contextWindow);
-    if (usage.tokens === null)
-        return `${displayText}\nContext: unknown / ${contextWindow} tokens.`;
-    const percent = usage.contextWindow > 0 ? Math.round((usage.tokens / usage.contextWindow) * 100) : 0;
-    return `${displayText}\nContext: ${formatTokenCount(usage.tokens)} / ${contextWindow} tokens (${percent}%).`;
-}
-function formatTokenCount(tokens) {
-    if (tokens >= 1_000_000)
-        return `${trimFixed(tokens / 1_000_000)}M`;
-    if (tokens >= 1_000)
-        return `${trimFixed(tokens / 1_000)}k`;
-    return String(tokens);
-}
-function trimFixed(value) {
-    return value.toFixed(value >= 10 ? 0 : 1).replace(/\.0$/, "");
-}
-function getProviderApi(ctx) {
-    return typeof ctx?.model?.api === "string" ? ctx.model.api : undefined;
-}
-function getSessionId(ctx) {
-    try {
-        return ctx?.sessionManager?.getSessionId?.();
-    }
-    catch {
-        return undefined;
-    }
-}
-function getCwd(ctx) {
-    try {
-        return ctx?.sessionManager?.getCwd?.();
-    }
-    catch {
-        return undefined;
-    }
-}
-function resolveCwd(ctx) {
-    if (isRecord(ctx) && typeof ctx.cwd === "string" && ctx.cwd.trim())
-        return ctx.cwd;
-    const sessionCwd = getCwd(ctx);
-    return sessionCwd ?? process.env.PWD ?? process.cwd();
-}
-function extractTextContent(content) {
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    return content
-        .filter((part) => isRecord(part) && part.type === "text" && typeof part.text === "string")
-        .map((part) => part.text)
-        .join("\n");
-}
-function stripSystemReminderWrapper(content) {
-    return content
-        .replace(/^\s*<system-reminder>\s*/i, "")
-        .replace(/\s*<\/system-reminder>\s*$/i, "")
-        .trim();
-}
-function padToWidth(line, width) {
-    return `${line}${" ".repeat(Math.max(0, width - visibleWidth(line)))}`;
-}
-const SYSTEM_REMINDER_MIN_BODY_WIDTH = 76;
-const SYSTEM_REMINDER_BODY_WIDTH_RATIO = 0.9;
-class SystemReminderComponent {
-    content;
-    details;
-    theme;
-    constructor(content, details, theme) {
-        this.content = content;
-        this.details = details;
-        this.theme = theme;
-    }
-    invalidate() { }
-    render(width) {
-        if (width < 3)
-            return [truncateToWidth("System Reminder", width)];
-        const availableBodyWidth = width - 2;
-        const preferredBodyWidth = Math.max(SYSTEM_REMINDER_MIN_BODY_WIDTH, Math.floor(availableBodyWidth * SYSTEM_REMINDER_BODY_WIDTH_RATIO));
-        const bodyWidth = Math.max(1, Math.min(availableBodyWidth, preferredBodyWidth));
-        const title = " System Reminder ";
-        const titleText = truncateToWidth(title, bodyWidth, "");
-        const border = (value) => this.theme.fg("accent", value);
-        const lines = [border(`╭${titleText}${"─".repeat(Math.max(0, bodyWidth - visibleWidth(titleText)))}╮`)];
-        const text = new Text(this.content, 0, 0);
-        for (const line of text.render(bodyWidth)) {
-            const truncated = truncateToWidth(line, bodyWidth, "");
-            lines.push(border("│") + padToWidth(truncated, bodyWidth) + border("│"));
-        }
-        const meta = [
-            this.details?.reminderCount !== undefined ? `${this.details.reminderCount} reminder${this.details.reminderCount === 1 ? "" : "s"}` : undefined,
-            this.details?.sources?.length ? this.details.sources.join(", ") : undefined,
-        ].filter(Boolean).join(" · ");
-        if (meta) {
-            const metaLine = truncateToWidth(this.theme.fg("dim", meta), bodyWidth, "");
-            lines.push(border("│") + padToWidth(metaLine, bodyWidth) + border("│"));
-        }
-        lines.push(border(`╰${"─".repeat(bodyWidth)}╯`));
-        return lines;
-    }
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}
+export { default, registerReminderHost } from "./host.js";
+export { remindersConfigSchema } from "./config.js";
+export * from "./types.js";

package/dist/src/reminders/types.d.ts

@@ -1,3 +1,6 @@
+export declare const REMINDER_MESSAGE_CUSTOM_TYPE = "pi-extension-utils:reminders";
+export declare const LEGACY_REMINDER_MESSAGE_CUSTOM_TYPE = "pi-reminders";
+export declare const DEBUG_REMINDER_SOURCE = "pi-extension-utils";
 export declare const REMINDER_UPSERT_EVENT = "reminder:upsert";
 export declare const REMINDER_REMOVE_EVENT = "reminder:remove";
 export declare const REMINDER_CLEAR_SOURCE_EVENT = "reminder:clear-source";

package/dist/src/reminders/types.js

@@ -1,3 +1,6 @@
+export const REMINDER_MESSAGE_CUSTOM_TYPE = "pi-extension-utils:reminders";
+export const LEGACY_REMINDER_MESSAGE_CUSTOM_TYPE = "pi-reminders";
+export const DEBUG_REMINDER_SOURCE = "pi-extension-utils";
 export const REMINDER_UPSERT_EVENT = "reminder:upsert";
 export const REMINDER_REMOVE_EVENT = "reminder:remove";
 export const REMINDER_CLEAR_SOURCE_EVENT = "reminder:clear-source";

package/dist/src/ui/client.d.ts

@@ -0,0 +1,22 @@
+export interface FullscreenLeaseLike {
+    release(): void;
+}
+export interface FullscreenController {
+    acquire(): FullscreenLeaseLike;
+}
+/**
+ * Factory signature accepted by `ctx.ui.custom`. Typed structurally so the
+ * helper does not depend on pi-tui types directly.
+ */
+export type FullscreenComponentFactory<T> = (tui: unknown, theme: unknown, keybindings: unknown, done: (result: T) => void) => unknown;
+export interface UiClient {
+    /**
+     * Run a full-screen custom UI: acquires a fullscreen lease (blanking
+     * coordinated widgets), shows the component via `ctx.ui.custom`, and
+     * releases the lease in a finally — even if the component throws.
+     */
+    fullscreen<T>(factory: FullscreenComponentFactory<T>): Promise<T>;
+}
+export declare function createUiClient(fullscreen: FullscreenController, ctx: {
+    ui: unknown;
+}): UiClient;

package/dist/src/ui/client.js

@@ -0,0 +1,17 @@
+export function createUiClient(fullscreen, ctx) {
+    return {
+        async fullscreen(factory) {
+            const ui = ctx.ui;
+            if (typeof ui.custom !== "function") {
+                throw new Error("pi-extension-utils: ui.fullscreen requires an interactive UI (ctx.ui.custom is unavailable)");
+            }
+            const lease = fullscreen.acquire();
+            try {
+                return await ui.custom(factory);
+            }
+            finally {
+                lease.release();
+            }
+        },
+    };
+}

package/dist/src/utils-config.d.ts

@@ -0,0 +1,24 @@
+import { Type, type Static } from "typebox";
+export declare const utilsConfigSchema: Type.TObject<{
+    logging: Type.TObject<{
+        level: Type.TUnion<[Type.TLiteral<"debug">, Type.TLiteral<"info">, Type.TLiteral<"warn">, Type.TLiteral<"error">, Type.TLiteral<"silent">]>;
+        maxFiles: Type.TNumber;
+        maxBytes: Type.TNumber;
+    }>;
+    reminders: Type.TObject<{
+        debugShowAllInTui: Type.TBoolean;
+    }>;
+}>;
+export type UtilsConfig = Static<typeof utilsConfigSchema>;
+export declare const DEFAULT_UTILS_CONFIG: UtilsConfig;
+export declare const utilsConfig: import("./index.ts").DefinedConfig<Type.TObject<{
+    logging: Type.TObject<{
+        level: Type.TUnion<[Type.TLiteral<"debug">, Type.TLiteral<"info">, Type.TLiteral<"warn">, Type.TLiteral<"error">, Type.TLiteral<"silent">]>;
+        maxFiles: Type.TNumber;
+        maxBytes: Type.TNumber;
+    }>;
+    reminders: Type.TObject<{
+        debugShowAllInTui: Type.TBoolean;
+    }>;
+}>>;
+export declare function readUtilsConfigOrDefaults(mode?: "get" | "reload"): UtilsConfig;

package/dist/src/utils-config.js

@@ -0,0 +1,38 @@
+import { Type } from "typebox";
+import { defineConfig } from "./config/index.js";
+import { loggingConfigSchema } from "./logger/config.js";
+import { remindersConfigSchema } from "./reminders/config.js";
+export const utilsConfigSchema = Type.Object({
+    logging: loggingConfigSchema,
+    reminders: remindersConfigSchema,
+});
+export const DEFAULT_UTILS_CONFIG = {
+    logging: {
+        level: "info",
+        maxFiles: 3,
+        maxBytes: 1048576,
+    },
+    reminders: {
+        debugShowAllInTui: false,
+    },
+};
+export const utilsConfig = defineConfig({
+    name: "utils",
+    schema: utilsConfigSchema,
+});
+let warnedAboutInvalidConfig = false;
+export function readUtilsConfigOrDefaults(mode = "get") {
+    try {
+        return mode === "reload" ? utilsConfig.reload() : utilsConfig.get();
+    }
+    catch (error) {
+        if (!warnedAboutInvalidConfig) {
+            warnedAboutInvalidConfig = true;
+            console.warn("pi-extension-utils: invalid utils config; using defaults", error);
+        }
+        return cloneDefaultUtilsConfig();
+    }
+}
+function cloneDefaultUtilsConfig() {
+    return JSON.parse(JSON.stringify(DEFAULT_UTILS_CONFIG));
+}

package/dist/src/widgets/client.d.ts

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

package/dist/src/widgets/client.js

@@ -0,0 +1,130 @@
+import { basePayload, EVENTS, PROTOCOL_VERSION } from "./protocol.js";
+let nextLeaseId = 1;
+export function connectWidgetCoordinator(pi, opts) {
+    const { clientId } = opts;
+    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 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);
+                    }
+                },
+            };
+        },
+    };
+    return {
+        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,
+        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();
+        },
+    };
+}
+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/widgets/host.d.ts

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