pi-extension-utils 0.1.0 → 0.2.1

package/README.md

@@ -22,8 +22,23 @@ const client = connect(pi, { ctx, clientId: "my-extension" });
 client.widgets.set("belowEditor", "status", (tui, theme) => component, { order: 10 });
 client.widgets.remove("belowEditor", "status");
 
+// Run a custom fullscreen UI: widgets are blanked before mount and
+// restored afterwards, even if the component throws.
+const result = await client.ui.fullscreen<string | null>(
+  (tui, theme, keybindings, done) => new MyOverlayComponent(tui, theme, done),
+);
+
+// Lower-level lease, for manual control over the blank/restore window.
 const lease = client.fullscreen.acquire();
 lease.release();
+
+// Reminders (host absorbed from pi-reminders): fire-and-forget emits;
+// list() resolves { reminders: [], count: 0 } when no host is present.
+client.reminders.upsert({ id: "my-reminder", text: "...", source: "my-extension" });
+client.reminders.remove("my-reminder");
+client.reminders.clearSource("my-extension");
+const { reminders } = await client.reminders.list();
+
 client.dispose();
 
 const log = createLogger("my-extension");

package/dist/index.js

@@ -1,8 +1,10 @@
+import { registerReminderHost } from "./src/reminders/index.js";
 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) {
+    registerReminderHost(pi);
     const widgets = new Map();
     const fullscreenStack = [];
     let seq = 0;

package/dist/src/client.d.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { WidgetFactory, WidgetPlacement } from "./protocol.ts";
+import { type ReminderAnnounceNowRequest, type ReminderIntent, type ReminderSnapshot } from "./reminders/types.ts";
 export interface UtilsClientOptions {
     ctx: ExtensionContext;
     clientId?: string;
@@ -10,6 +11,18 @@ export interface WidgetSetOptions {
 export interface FullscreenLease {
     release(): void;
 }
+/**
+ * Factory signature accepted by `ctx.ui.custom`. Typed structurally so the
+ * client 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 RemindersClient {
+    upsert(intent: ReminderIntent): void;
+    remove(source: string, key: string): void;
+    clearSource(source: string): void;
+    announceNow(payload?: ReminderAnnounceNowRequest): void;
+    list(source?: string): Promise<ReminderSnapshot>;
+}
 export interface UtilsClient {
     readonly clientId: string;
     readonly mode: "fallback" | "coordinated";
@@ -20,6 +33,15 @@ export interface UtilsClient {
     fullscreen: {
         acquire(): FullscreenLease;
     };
+    ui: {
+        /**
+         * 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>;
+    };
+    reminders: RemindersClient;
     dispose(): void;
 }
 export declare function connect(pi: ExtensionAPI, opts: UtilsClientOptions): UtilsClient;

package/dist/src/client.js

@@ -1,3 +1,4 @@
+import { REMINDER_ANNOUNCE_NOW_EVENT, REMINDER_CLEAR_SOURCE_EVENT, REMINDER_LIST_EVENT, REMINDER_REMOVE_EVENT, REMINDER_UPSERT_EVENT, } from "./reminders/types.js";
 import { basePayload, EVENTS, PROTOCOL_VERSION, } from "./protocol.js";
 let nextClientId = 1;
 let nextLeaseId = 1;
@@ -103,6 +104,64 @@ export function connect(pi, opts) {
                 };
             },
         },
+        ui: {
+            async fullscreen(factory) {
+                const ui = opts.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 = client.fullscreen.acquire();
+                try {
+                    return await ui.custom(factory);
+                }
+                finally {
+                    lease.release();
+                }
+            },
+        },
+        reminders: {
+            upsert(intent) {
+                if (disposed)
+                    return;
+                pi.events.emit(REMINDER_UPSERT_EVENT, intent);
+            },
+            remove(source, key) {
+                if (disposed)
+                    return;
+                pi.events.emit(REMINDER_REMOVE_EVENT, { source, id: key });
+            },
+            clearSource(source) {
+                if (disposed)
+                    return;
+                pi.events.emit(REMINDER_CLEAR_SOURCE_EVENT, { source });
+            },
+            announceNow(payload = {}) {
+                if (disposed)
+                    return;
+                pi.events.emit(REMINDER_ANNOUNCE_NOW_EVENT, payload);
+            },
+            list(source) {
+                if (disposed)
+                    return Promise.resolve(emptyReminderSnapshot());
+                let settled = false;
+                let resolveSnapshot;
+                let rejectSnapshot;
+                const promise = new Promise((resolve, reject) => {
+                    resolveSnapshot = (snapshot) => {
+                        settled = true;
+                        resolve(snapshot);
+                    };
+                    rejectSnapshot = (error) => {
+                        settled = true;
+                        reject(error);
+                    };
+                });
+                pi.events.emit(REMINDER_LIST_EVENT, { source, resolve: resolveSnapshot, reject: rejectSnapshot });
+                if (!settled)
+                    resolveSnapshot(emptyReminderSnapshot());
+                return promise;
+            },
+        },
         dispose() {
             if (disposed)
                 return;
@@ -130,3 +189,6 @@ function isReadyPayload(data) {
     const payload = data;
     return typeof payload.protocolVersion === "number" && payload.protocolVersion <= PROTOCOL_VERSION && typeof payload.clientId === "string";
 }
+function emptyReminderSnapshot() {
+    return { reminders: [], count: 0 };
+}

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

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

@@ -0,0 +1,6 @@
+export interface RemindersConfig {
+    debugShowAllInTui?: boolean;
+}
+export declare function configPath(cwd: string): string;
+export declare function loadConfig(cwd: string): RemindersConfig;
+export declare function saveConfig(config: RemindersConfig, cwd: string): void;

package/dist/src/reminders/config.js

@@ -0,0 +1,23 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function configPath(cwd) {
+    return join(cwd, ".pi", "reminders", "reminders-config.json");
+}
+export function loadConfig(cwd) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath(cwd), "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return {};
+        return {
+            debugShowAllInTui: typeof parsed.debugShowAllInTui === "boolean" ? parsed.debugShowAllInTui : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(config, cwd) {
+    const filePath = configPath(cwd);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(config, null, 2));
+}

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

@@ -0,0 +1,37 @@
+import type { ReminderSnapshot } from "./types.ts";
+export interface ReminderCacheDiagnosticsInput {
+    payload?: unknown;
+    resultPayload?: unknown;
+    snapshot: ReminderSnapshot;
+    trailer: string | null;
+    inserted: boolean;
+    skippedReason?: string;
+    providerApi?: string;
+    strategy?: string;
+    adapterName?: string;
+}
+export interface ReminderCacheDiagnostics {
+    event: "reminder_cache_diagnostics";
+    timestamp: string;
+    inserted: boolean;
+    skippedReason?: string;
+    providerApi?: string;
+    strategy?: string;
+    adapterName?: string;
+    payloadShape: "messages" | "input" | "unsupported";
+    messagesBefore: number | null;
+    messagesAfter: number | null;
+    activeReminderCount: number;
+    activeReminderSources: string[];
+    activeReminderLabels: string[];
+    trailerChars: number;
+    trailerHash: string | null;
+    stablePrefixHash: string | null;
+    cacheControlBeforeCount: number;
+    cacheControlBeforePaths: string[];
+    cacheControlInOrAfterTrailerCount: number;
+    cacheControlInOrAfterTrailerPaths: string[];
+}
+export declare function buildReminderCacheDiagnostics(input: ReminderCacheDiagnosticsInput): ReminderCacheDiagnostics;
+export declare function writeReminderCacheDiagnostics(diagnostics: ReminderCacheDiagnostics): void;
+export declare function writeReminderDiagnostic(record: Record<string, unknown>): void;

package/dist/src/reminders/debug.js

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { deriveLabel } from "./renderer.js";
+const DEBUG_LOG_PATH = join(homedir(), ".pi", "log", "reminders.jsonl");
+export function buildReminderCacheDiagnostics(input) {
+    const before = getProviderMessages(input.payload);
+    const after = getProviderMessages(input.resultPayload);
+    const messagesBefore = before.messages;
+    const messagesAfter = after.messages;
+    const trailerMessage = input.inserted && messagesAfter ? messagesAfter[messagesAfter.length - 1] : undefined;
+    const trailerPath = after.shape === "input" ? "input[-1]" : "messages[-1]";
+    const cacheControlBeforePaths = findCacheControlPaths(messagesBefore ?? input.payload, before.path);
+    const cacheControlInOrAfterTrailerPaths = trailerMessage ? findCacheControlPaths(trailerMessage, trailerPath) : [];
+    const sources = uniqueSorted(input.snapshot.reminders.map((reminder) => reminder.source));
+    const labels = uniqueSorted(input.snapshot.reminders.map((reminder) => deriveLabel(reminder.source, reminder.label)));
+    return {
+        event: "reminder_cache_diagnostics",
+        timestamp: new Date().toISOString(),
+        inserted: input.inserted,
+        skippedReason: input.skippedReason,
+        providerApi: input.providerApi,
+        strategy: input.strategy,
+        adapterName: input.adapterName,
+        payloadShape: before.shape,
+        messagesBefore: messagesBefore?.length ?? null,
+        messagesAfter: messagesAfter?.length ?? null,
+        activeReminderCount: input.snapshot.count,
+        activeReminderSources: sources,
+        activeReminderLabels: labels,
+        trailerChars: input.trailer?.length ?? 0,
+        trailerHash: input.trailer ? hashString(input.trailer) : null,
+        stablePrefixHash: messagesBefore ? hashJson(messagesBefore) : null,
+        cacheControlBeforeCount: cacheControlBeforePaths.length,
+        cacheControlBeforePaths,
+        cacheControlInOrAfterTrailerCount: cacheControlInOrAfterTrailerPaths.length,
+        cacheControlInOrAfterTrailerPaths,
+    };
+}
+export function writeReminderCacheDiagnostics(diagnostics) {
+    writeReminderDiagnostic({ ...diagnostics });
+}
+export function writeReminderDiagnostic(record) {
+    try {
+        const path = process.env.PI_REMINDERS_DEBUG_LOG || DEBUG_LOG_PATH;
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify({ timestamp: new Date().toISOString(), ...record })}\n`, "utf8");
+    }
+    catch {
+        // Debug logging is best-effort and must not affect provider requests.
+    }
+}
+function getProviderMessages(payload) {
+    if (!isRecord(payload))
+        return { shape: "unsupported", path: "messages", messages: null };
+    if (Array.isArray(payload.messages))
+        return { shape: "messages", path: "messages", messages: payload.messages };
+    if (Array.isArray(payload.input))
+        return { shape: "input", path: "input", messages: payload.input };
+    return { shape: "unsupported", path: "messages", messages: null };
+}
+function findCacheControlPaths(value, prefix = "messages") {
+    const paths = [];
+    visit(value, prefix, paths);
+    return paths;
+}
+function visit(value, path, paths) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => visit(item, `${path}[${index}]`, paths));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        const childPath = `${path}.${key}`;
+        if (key === "cache_control")
+            paths.push(childPath);
+        visit(child, childPath, paths);
+    }
+}
+function hashJson(value) {
+    return hashString(stableStringify(value));
+}
+function hashString(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (isRecord(value)) {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

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

@@ -0,0 +1,5 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ReminderManager } from "./manager.ts";
+/** Register the pi-reminders extension hooks and event listeners. */
+export declare function registerReminderHost(pi: ExtensionAPI, manager?: ReminderManager): ReminderManager;
+export default function reminderHost(pi: ExtensionAPI): void;

package/dist/src/reminders/index.js

@@ -0,0 +1,308 @@
+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;
+}

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

@@ -0,0 +1,32 @@
+import type { ReminderAnnounceNowRequest, ReminderClearSourceRequest, ReminderIntent, ReminderRecord, ReminderRemoveRequest, ReminderSnapshot } from "./types.ts";
+export interface ReminderAnnouncement {
+    text: string;
+    displayText: string | null;
+    reminders: ReminderRecord[];
+    displayReminders: ReminderRecord[];
+}
+/** In-memory store for system reminder intents and announcement state. */
+export declare class ReminderManager {
+    private readonly reminders;
+    private clock;
+    private turnIndex;
+    constructor(options?: {
+        clock?: () => number;
+    });
+    upsert(intent: ReminderIntent): boolean;
+    remove(request: ReminderRemoveRequest): boolean;
+    clearSource(request: ReminderClearSourceRequest): number;
+    clearSession(): void;
+    advanceTurn(): void;
+    forceAnnounce(request?: ReminderAnnounceNowRequest): number;
+    snapshot(source?: string): ReminderSnapshot;
+    render(): string | null;
+    collectDueAnnouncement(options?: {
+        showHiddenInDisplay?: boolean;
+    }): ReminderAnnouncement | null;
+    get size(): number;
+    private isDue;
+    private markAnnounced;
+    private sortedRecords;
+    private sortedStoredRecords;
+}

package/dist/src/reminders/manager.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { renderReminderBody, renderReminderTrailer } from "./renderer.js";
+const DEFAULT_TTL = "once";
+/** In-memory store for system reminder intents and announcement state. */
+export class ReminderManager {
+    reminders = new Map();
+    clock;
+    turnIndex = 0;
+    constructor(options = {}) {
+        this.clock = options.clock ?? Date.now;
+    }
+    upsert(intent) {
+        const normalized = normalizeIntent(intent);
+        if (!normalized)
+            return false;
+        if (normalized.text.trim().length === 0) {
+            return this.remove({ source: normalized.source, id: normalized.id });
+        }
+        const now = this.clock();
+        const key = reminderKey(normalized.source, normalized.id);
+        const existing = this.reminders.get(key);
+        const textHash = hashReminderText(normalized);
+        this.reminders.set(key, {
+            ...normalized,
+            priority: normalized.priority ?? 0,
+            display: normalized.display ?? true,
+            ttl: normalized.ttl ?? DEFAULT_TTL,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            lastAnnouncedTextHash: existing?.lastAnnouncedTextHash,
+            lastAnnouncedTurn: existing?.lastAnnouncedTurn,
+            forceAnnounce: existing?.forceAnnounce || existing?.lastAnnouncedTextHash !== textHash,
+        });
+        return true;
+    }
+    remove(request) {
+        const source = request.source.trim();
+        const id = request.id.trim();
+        if (!source || !id)
+            return false;
+        return this.reminders.delete(reminderKey(source, id));
+    }
+    clearSource(request) {
+        const source = request.source.trim();
+        if (!source)
+            return 0;
+        let removed = 0;
+        for (const [key, reminder] of this.reminders) {
+            if (reminder.source === source) {
+                this.reminders.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    clearSession() {
+        this.reminders.clear();
+        this.turnIndex = 0;
+    }
+    advanceTurn() {
+        this.turnIndex++;
+    }
+    forceAnnounce(request = {}) {
+        const source = request.source?.trim();
+        const id = request.id?.trim();
+        let count = 0;
+        for (const reminder of this.reminders.values()) {
+            if (source && reminder.source !== source)
+                continue;
+            if (id && reminder.id !== id)
+                continue;
+            reminder.forceAnnounce = true;
+            count++;
+        }
+        return count;
+    }
+    snapshot(source) {
+        const filtered = this.sortedRecords().filter((reminder) => source === undefined || reminder.source === source);
+        return {
+            reminders: filtered.map(cloneRecord),
+            count: filtered.length,
+        };
+    }
+    render() {
+        return renderReminderTrailer(this.sortedRecords());
+    }
+    collectDueAnnouncement(options = {}) {
+        const due = this.sortedStoredRecords().filter((reminder) => this.isDue(reminder));
+        const text = renderReminderTrailer(due);
+        if (!text)
+            return null;
+        const displayReminders = options.showHiddenInDisplay ? due : due.filter((reminder) => reminder.display);
+        const displayText = renderReminderBody(displayReminders);
+        const announced = due.map(cloneRecord);
+        const displayed = displayReminders.map(cloneRecord);
+        this.markAnnounced(due);
+        return { text, displayText, reminders: announced, displayReminders: displayed };
+    }
+    get size() {
+        return this.reminders.size;
+    }
+    isDue(reminder) {
+        if (reminder.forceAnnounce)
+            return true;
+        const textHash = hashReminderText(reminder);
+        if (reminder.lastAnnouncedTextHash !== textHash)
+            return true;
+        if (reminder.ttl !== "persistent")
+            return false;
+        if (!reminder.repeatEveryTurns || reminder.repeatEveryTurns <= 0)
+            return false;
+        if (reminder.lastAnnouncedTurn === undefined)
+            return true;
+        return this.turnIndex - reminder.lastAnnouncedTurn >= reminder.repeatEveryTurns;
+    }
+    markAnnounced(reminders) {
+        for (const reminder of reminders) {
+            const key = reminderKey(reminder.source, reminder.id);
+            const stored = this.reminders.get(key);
+            if (!stored)
+                continue;
+            if (stored.ttl === "once") {
+                this.reminders.delete(key);
+                continue;
+            }
+            stored.lastAnnouncedTextHash = hashReminderText(stored);
+            stored.lastAnnouncedTurn = this.turnIndex;
+            stored.forceAnnounce = false;
+        }
+    }
+    sortedRecords() {
+        return this.sortedStoredRecords().map(cloneRecord);
+    }
+    sortedStoredRecords() {
+        return [...this.reminders.values()].sort(compareRecords);
+    }
+}
+function normalizeIntent(intent) {
+    const source = intent.source?.trim();
+    const id = intent.id?.trim();
+    if (!source || !id)
+        return null;
+    const priority = intent.priority;
+    const repeatEveryTurns = intent.repeatEveryTurns;
+    return {
+        ...intent,
+        source,
+        id,
+        text: String(intent.text ?? ""),
+        label: intent.label?.trim(),
+        priority: Number.isFinite(priority) ? Math.trunc(priority) : undefined,
+        display: intent.display !== false,
+        ttl: normalizeTtl(intent.ttl),
+        repeatEveryTurns: Number.isFinite(repeatEveryTurns) && repeatEveryTurns > 0
+            ? Math.trunc(repeatEveryTurns)
+            : undefined,
+        metadata: cloneMetadata(intent.metadata),
+    };
+}
+function normalizeTtl(ttl) {
+    if (ttl === undefined)
+        return undefined;
+    return ttl === "once" || ttl === "persistent" || ttl === "session" ? ttl : undefined;
+}
+function reminderKey(source, id) {
+    return `${source}\u0000${id}`;
+}
+function compareRecords(a, b) {
+    return b.priority - a.priority || a.source.localeCompare(b.source) || a.id.localeCompare(b.id);
+}
+function cloneRecord(record) {
+    return {
+        id: record.id,
+        source: record.source,
+        text: record.text,
+        label: record.label,
+        priority: record.priority,
+        display: record.display,
+        ttl: record.ttl,
+        repeatEveryTurns: record.repeatEveryTurns,
+        metadata: cloneMetadata(record.metadata),
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    };
+}
+function cloneMetadata(metadata) {
+    return metadata === undefined ? undefined : { ...metadata };
+}
+function hashReminderText(reminder) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        id: reminder.id,
+        label: reminder.label,
+        priority: reminder.priority,
+        display: reminder.display,
+        source: reminder.source,
+        text: reminder.text,
+    }))
+        .digest("hex");
+}

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

@@ -0,0 +1,7 @@
+import type { RenderReminderInput } from "./types.ts";
+/** Render reminders into one compact model-visible trailer. */
+export declare function renderReminderTrailer(reminders: readonly RenderReminderInput[]): string | null;
+/** Render reminders without wrapper tags for custom chat display. */
+export declare function renderReminderBody(reminders: readonly RenderReminderInput[]): string | null;
+export declare function sanitizeText(text: string): string;
+export declare function deriveLabel(source: string, label?: string): string;

package/dist/src/reminders/renderer.js

@@ -0,0 +1,96 @@
+const SOURCE_LABELS = {
+    "pi-dag-tasks": "Tasks",
+    tasks: "Tasks",
+    dcp: "DCP",
+    "pi-dynamic-context-pruning": "DCP",
+    "pi-subagents": "Subagents",
+    subagents: "Subagents",
+};
+/** Render reminders into one compact model-visible trailer. */
+export function renderReminderTrailer(reminders) {
+    const body = renderReminderBody(reminders);
+    return body ? `<system-reminder>\n${body}\n</system-reminder>` : null;
+}
+/** Render reminders without wrapper tags for custom chat display. */
+export function renderReminderBody(reminders) {
+    const normalized = reminders
+        .map((reminder) => ({
+        ...reminder,
+        text: sanitizeText(reminder.text),
+        label: deriveLabel(reminder.source, reminder.label),
+    }))
+        .filter((reminder) => reminder.text.length > 0);
+    if (normalized.length === 0)
+        return null;
+    const groups = buildGroups(normalized);
+    return groups.map((group) => renderGroup(group)).join("\n");
+}
+export function sanitizeText(text) {
+    return escapeWrapperText(text.trim().replace(/\s+/g, " "));
+}
+export function deriveLabel(source, label) {
+    const explicit = sanitizeLabel(label ?? "");
+    if (explicit.length > 0)
+        return explicit;
+    const mapped = SOURCE_LABELS[source.trim().toLowerCase()];
+    if (mapped)
+        return mapped;
+    const fallback = source
+        .trim()
+        .replace(/^pi[-_]/i, "")
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join("");
+    return sanitizeLabel(fallback || "Reminder");
+}
+function buildGroups(reminders) {
+    const byLabel = new Map();
+    for (const reminder of reminders) {
+        const label = deriveLabel(reminder.source, reminder.label);
+        const key = label.toLowerCase();
+        const existing = byLabel.get(key);
+        if (existing) {
+            existing.maxPriority = Math.max(existing.maxPriority, reminder.priority);
+            existing.reminders.push(reminder);
+            if (reminder.source < existing.source)
+                existing.source = reminder.source;
+        }
+        else {
+            byLabel.set(key, {
+                label,
+                source: reminder.source,
+                maxPriority: reminder.priority,
+                reminders: [reminder],
+            });
+        }
+    }
+    return [...byLabel.values()]
+        .map((group) => ({
+        ...group,
+        reminders: [...group.reminders].sort(compareReminders),
+    }))
+        .sort(compareGroups);
+}
+function renderGroup(group) {
+    const text = group.reminders.map((reminder) => reminder.text).join("; ");
+    return `${group.label}: ${text}`;
+}
+function compareGroups(a, b) {
+    return b.maxPriority - a.maxPriority || a.label.localeCompare(b.label) || a.source.localeCompare(b.source);
+}
+function compareReminders(a, b) {
+    return b.priority - a.priority || a.id.localeCompare(b.id);
+}
+function sanitizeLabel(label) {
+    return label
+        .trim()
+        .replace(/[^A-Za-z0-9_-]+/g, "")
+        .slice(0, 24);
+}
+function escapeWrapperText(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}

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

@@ -0,0 +1,61 @@
+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";
+export declare const REMINDER_LIST_EVENT = "reminder:list";
+export declare const REMINDER_ANNOUNCE_NOW_EVENT = "reminder:announce-now";
+export type ReminderTtl = "once" | "session" | "persistent";
+export interface ReminderIntent {
+    /** Stable unique ID within the producer source. */
+    id: string;
+    /** Producer namespace, e.g. "pi-dag-tasks", "dcp", "pi-subagents". */
+    source: string;
+    /** Compact model-facing reminder text. Source/id are not rendered by default. */
+    text: string;
+    /** Optional compact display label, e.g. "Tasks", "DCP", "Subagents". */
+    label?: string;
+    /** Higher values render earlier. Default: 0. */
+    priority?: number;
+    /** Whether this reminder should be shown in chat. Default: true. */
+    display?: boolean;
+    /** Lifecycle policy. Default: "once". */
+    ttl?: ReminderTtl;
+    /** Optional turn interval for repeating persistent reminders. */
+    repeatEveryTurns?: number;
+    /** Optional structured metadata for debugging; never rendered in the normal reminder. */
+    metadata?: Record<string, unknown>;
+}
+export interface ReminderRemoveRequest {
+    source: string;
+    id: string;
+}
+export interface ReminderClearSourceRequest {
+    source: string;
+}
+export interface ReminderAnnounceNowRequest {
+    source?: string;
+    id?: string;
+}
+export interface ReminderListRequest {
+    source?: string;
+    resolve: (snapshot: ReminderSnapshot) => void;
+    reject?: (error: unknown) => void;
+}
+export interface ReminderRecord extends ReminderIntent {
+    priority: number;
+    display: boolean;
+    ttl: ReminderTtl;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ReminderSnapshot {
+    reminders: ReminderRecord[];
+    count: number;
+}
+export interface RenderReminderInput {
+    id: string;
+    source: string;
+    text: string;
+    label?: string;
+    priority: number;
+    display?: boolean;
+}

package/dist/src/reminders/types.js

@@ -0,0 +1,5 @@
+export const REMINDER_UPSERT_EVENT = "reminder:upsert";
+export const REMINDER_REMOVE_EVENT = "reminder:remove";
+export const REMINDER_CLEAR_SOURCE_EVENT = "reminder:clear-source";
+export const REMINDER_LIST_EVENT = "reminder:list";
+export const REMINDER_ANNOUNCE_NOW_EVENT = "reminder:announce-now";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-extension-utils",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "Shared Pi extension utilities for coordinated widgets, fullscreen leases, and logging.",
 	"type": "module",
 	"main": "./dist/src/index.js",
@@ -11,9 +11,15 @@
 			"default": "./dist/src/index.js"
 		}
 	},
-	"files": ["dist", "README.md", "LICENSE"],
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
 	"pi": {
-		"extensions": ["./dist/index.js"]
+		"extensions": [
+			"./dist/index.js"
+		]
 	},
 	"scripts": {
 		"build": "rm -rf dist && tsc -p tsconfig.build.json",