pi-harness-runtime 1.1.397 → 1.1.402

package/packages/telegram/src/lifecycle.js

@@ -0,0 +1,538 @@
+/**
+ * Telegram session lifecycle coordination and hook registration
+ * Zones: pi agent lifecycle, telegram session
+ * Owns context generations, bounded connect intent across resume, and session sequencing.
+ * Transport authority, durable bindings, and queue custody remain with their owners.
+ */
+import { randomUUID } from "node:crypto";
+import * as BusFollower from "./bus-follower.js";
+import * as Queue from "./queue.js";
+import { formatTelegramConnectionFailure } from "./status.js";
+import * as TextGroups from "./text-groups.js";
+export function createAgentStartDedupHook(inner, resetReplyDedup, schedulePublication) {
+    return async (event, ctx) => {
+        // A new turn must not erase the anchor of a final still ahead in the FIFO.
+        if (schedulePublication)
+            schedulePublication(async () => {
+                resetReplyDedup();
+            });
+        else
+            resetReplyDedup();
+        return inner(event, ctx);
+    };
+}
+const HANDOFF_KEY = Symbol.for("pi-telegram.connection-resume.v1");
+function processHandoffStore() {
+    const globals = globalThis;
+    return (globals[HANDOFF_KEY] ??= {});
+}
+export function createTelegramConnectionLifecycle(deps) {
+    return {
+        onSessionShutdown(event, ctx) {
+            deps.intent.suspend({
+                reason: event.reason,
+                cwd: ctx.cwd,
+                targetSessionFile: event.targetSessionFile,
+                connected: deps.isConnected(),
+                profileName: deps.getProfileName(),
+            });
+        },
+        prepare(event, ctx) {
+            const intent = deps.intent.resume({
+                reason: event.reason,
+                cwd: ctx.cwd,
+                sessionFile: event.reason === "resume"
+                    ? ctx.sessionManager.getSessionFile()
+                    : undefined,
+            });
+            if (!intent)
+                return undefined;
+            const generation = deps.getGeneration();
+            const isCurrent = () => deps.intent.isActive(intent.id) &&
+                generation === deps.getGeneration() &&
+                deps.isCurrent(ctx);
+            return () => {
+                // Startup remains extension-owned background work; no captured command ctx crosses resume.
+                void (async () => {
+                    if (!isCurrent())
+                        return;
+                    if (!(await deps.activateProfile(intent.profileName, isCurrent))) {
+                        if (isCurrent())
+                            ctx.ui.notify("Telegram profile unavailable. Run /telegram-setup.", "warning");
+                        return;
+                    }
+                    if (!isCurrent())
+                        return;
+                    const result = await deps.start(ctx);
+                    if (!isCurrent())
+                        return;
+                    if (!result.ok) {
+                        deps.recordError(new Error(result.message ?? "Telegram resume connection failed."));
+                        ctx.ui.notify(formatTelegramConnectionFailure(result.message), "warning");
+                    }
+                })()
+                    .catch((error) => {
+                    deps.recordError(error);
+                    if (isCurrent())
+                        ctx.ui.notify(formatTelegramConnectionFailure(error), "warning");
+                })
+                    .finally(() => deps.intent.finish(intent.id));
+            };
+        },
+    };
+}
+export function createTelegramConnectionIntentRuntime(options = {}) {
+    const store = options.store ?? processHandoffStore();
+    const now = options.now ?? Date.now;
+    const pid = options.pid ?? process.pid;
+    let active;
+    return {
+        begin(cwd, profileName) {
+            store.pending = undefined;
+            active = { id: randomUUID(), cwd, profileName };
+            return active.id;
+        },
+        isActive(id) {
+            return active?.id === id;
+        },
+        finish(id) {
+            if (active?.id === id)
+                active = undefined;
+        },
+        cancel() {
+            active = undefined;
+            store.pending = undefined;
+        },
+        suspend(input) {
+            const intent = active ??
+                (input.connected
+                    ? { id: randomUUID(), cwd: input.cwd, profileName: input.profileName }
+                    : undefined);
+            active = undefined;
+            store.pending =
+                input.reason === "resume" &&
+                    input.targetSessionFile &&
+                    intent?.cwd === input.cwd
+                    ? {
+                        ...intent,
+                        pid,
+                        targetSessionFile: input.targetSessionFile,
+                        expiresAtMs: now() + 30_000,
+                    }
+                    : undefined;
+        },
+        resume(input) {
+            const handoff = store.pending;
+            store.pending = undefined;
+            if (!handoff ||
+                handoff.pid !== pid ||
+                now() >= handoff.expiresAtMs ||
+                input.reason !== "resume" ||
+                input.cwd !== handoff.cwd ||
+                input.sessionFile !== handoff.targetSessionFile)
+                return undefined;
+            active = {
+                id: randomUUID(),
+                cwd: handoff.cwd,
+                profileName: handoff.profileName,
+            };
+            return { ...active };
+        },
+    };
+}
+export function createTelegramSessionContextStore(options = {}) {
+    let currentContext;
+    let currentIdentity;
+    let generation = 0;
+    const objectIdentityGenerations = new WeakMap();
+    const primitiveIdentityGenerations = new Map();
+    const resolveIdentity = (ctx) => options.getIdentity?.(ctx) ?? ctx;
+    const getIdentityGeneration = (identity) => (typeof identity === "object" && identity !== null) ||
+        typeof identity === "function"
+        ? objectIdentityGenerations.get(identity)
+        : primitiveIdentityGenerations.get(identity);
+    const setIdentityGeneration = (identity, value) => {
+        if ((typeof identity === "object" && identity !== null) ||
+            typeof identity === "function") {
+            objectIdentityGenerations.set(identity, value);
+        }
+        else {
+            primitiveIdentityGenerations.set(identity, value);
+        }
+    };
+    return {
+        get: () => currentContext,
+        getGeneration: () => generation,
+        isCurrent: (ctx, expectedGeneration) => {
+            if (currentContext === undefined)
+                return false;
+            const identity = resolveIdentity(ctx);
+            return (identity === currentIdentity &&
+                getIdentityGeneration(identity) === generation &&
+                (expectedGeneration === undefined || generation === expectedGeneration));
+        },
+        set: (ctx) => {
+            currentContext = ctx;
+            currentIdentity = resolveIdentity(ctx);
+            generation += 1;
+            setIdentityGeneration(currentIdentity, generation);
+            return generation;
+        },
+        clear: (ctx) => {
+            if (ctx !== undefined) {
+                const identity = resolveIdentity(ctx);
+                if (identity !== currentIdentity ||
+                    getIdentityGeneration(identity) !== generation) {
+                    return false;
+                }
+            }
+            if (currentContext === undefined)
+                return false;
+            currentContext = undefined;
+            currentIdentity = undefined;
+            generation += 1;
+            return true;
+        },
+    };
+}
+export function createTelegramSessionGenerationFence(store, hooks) {
+    return {
+        async onSessionStart(event, ctx) {
+            const generation = store.set(ctx);
+            await hooks.onSessionStart(event, ctx);
+            if (!store.isCurrent(ctx, generation))
+                return;
+        },
+        async onSessionShutdown(event, ctx) {
+            const generation = store.getGeneration();
+            if (!store.isCurrent(ctx, generation))
+                return;
+            await hooks.onSessionShutdown(event, ctx);
+            if (store.isCurrent(ctx, generation))
+                store.clear(ctx);
+        },
+    };
+}
+export function createTelegramBridgeSessionLifecycleDeps(ports) {
+    return {
+        contextStore: ports.contextStore,
+        queue: ports.queue,
+        follower: ports.follower,
+        services: {
+            resumeGroupedInput(ctx) {
+                ports.services.mediaGroup.resume(ctx);
+                ports.services.textGroup.resume(ctx);
+            },
+            suspendGroupedInput: TextGroups.createTelegramGroupedInputClearer({
+                clearMediaGroups: ports.services.mediaGroup.suspend,
+                clearTextGroups: ports.services.textGroup.suspend,
+            }),
+            delivery: ports.services.delivery,
+            polling: ports.services.polling,
+            connection: ports.services.connection,
+            inboundWorker: ports.services.inboundWorker,
+            capabilityMonitor: ports.services.capabilityMonitor,
+            queueWatchdog: ports.services.queueWatchdog,
+            guestPlaceholder: ports.services.guestPlaceholder,
+            prepareThreadPreservationOnQuit: ports.services.prepareThreadPreservationOnQuit,
+        },
+    };
+}
+export function createTelegramBridgeSessionLifecycleAssembly(deps) {
+    const isSessionActive = deps.contextStore.isCurrent;
+    const suspendForReplacement = BusFollower.createTelegramBusFollowerSessionReplacementSuspender({
+        registrationState: deps.follower.registrationState,
+        instanceId: deps.follower.instanceId,
+        suspendPolling: deps.follower.suspendPolling,
+        recordRuntimeEvent: deps.follower.recordRuntimeEvent,
+    });
+    let preserveTarget = true;
+    const queueLifecycle = Queue.createTelegramSessionLifecycleRuntime({
+        ...deps.queue,
+        isSessionActive,
+        stopPolling: () => suspendForReplacement(preserveTarget),
+        clearPendingMediaGroups: deps.services.suspendGroupedInput,
+    });
+    const servicesLifecycle = {
+        async onSessionStart(event, ctx) {
+            const resumeConnection = deps.services.connection?.prepare(event, ctx);
+            await queueLifecycle.onSessionStart(event, ctx);
+            if (!isSessionActive(ctx))
+                return;
+            deps.services.resumeGroupedInput(ctx);
+            await deps.services.delivery.onSessionStart();
+            if (!isSessionActive(ctx))
+                return;
+            if (resumeConnection)
+                resumeConnection();
+            else
+                await deps.services.polling.onSessionStart(event, ctx);
+            deps.services.capabilityMonitor.start(ctx);
+            deps.services.queueWatchdog.start(ctx);
+        },
+        async onSessionShutdown(event, ctx) {
+            const generation = deps.contextStore.getGeneration();
+            const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
+            if (!isCurrent())
+                return;
+            deps.services.connection?.onSessionShutdown(event, ctx);
+            preserveTarget = event.reason !== "resume";
+            let preserveThread;
+            if (event.reason === "quit") {
+                try {
+                    preserveThread =
+                        deps.services.prepareThreadPreservationOnQuit?.(isCurrent);
+                }
+                catch (error) {
+                    deps.follower.recordRuntimeEvent("session", error, {
+                        phase: "preserve-thread-on-quit",
+                    });
+                }
+            }
+            deps.services.guestPlaceholder?.stopAll();
+            await deps.services.delivery.onSessionShutdown();
+            if (!isCurrent())
+                return;
+            deps.services.queueWatchdog.stop();
+            deps.services.capabilityMonitor.stop();
+            await queueLifecycle.onSessionShutdown(event, ctx);
+            if (!isCurrent())
+                return;
+            await deps.services.inboundWorker.onSessionShutdown();
+            if (!isCurrent())
+                return;
+            try {
+                await preserveThread?.();
+            }
+            catch (error) {
+                deps.follower.recordRuntimeEvent("session", error, {
+                    phase: "preserve-thread-on-quit",
+                });
+            }
+        },
+    };
+    const followerLifecycle = appendTelegramLifecycleHooks(servicesLifecycle, {
+        onSessionStart: BusFollower.createTelegramBusFollowerSessionRefreshHook({
+            registrationState: deps.follower.registrationState,
+            registrationRuntime: deps.follower.registrationRuntime,
+            getLeaderState: deps.follower.getLeaderState,
+            isSessionActive,
+            updateStatus: deps.follower.updateStatus,
+            recordRuntimeEvent: deps.follower.recordRuntimeEvent,
+        }),
+    }, isSessionActive);
+    return createTelegramSessionGenerationFence(deps.contextStore, followerLifecycle);
+}
+function unrefTelegramLifecycleTimer(timer) {
+    if (!timer || typeof timer !== "object")
+        return;
+    if (typeof timer.unref === "function")
+        timer.unref();
+}
+export function createTelegramCompactionObserverRuntime(deps) {
+    const timeoutMs = deps.timeoutMs ?? 300_000;
+    const setTimer = deps.setTimer ?? setTimeout;
+    const clearTimer = deps.clearTimer ?? clearTimeout;
+    let fallbackTimer;
+    let observationGeneration = 0;
+    let typingStartedByObserver = false;
+    const clearFallbackTimer = () => {
+        observationGeneration += 1;
+        if (!fallbackTimer)
+            return;
+        clearTimer(fallbackTimer);
+        fallbackTimer = undefined;
+    };
+    // Stop only a typing loop this observer started; a pre-existing agent-owned loop is preserved.
+    const releaseCompactionPresence = (ctx) => {
+        deps.setCompactionInProgress(false);
+        if (typingStartedByObserver)
+            deps.stopTypingLoop?.();
+        typingStartedByObserver = false;
+        deps.updateStatus(ctx);
+    };
+    const requestDispatch = () => {
+        deps.requestDeferredDispatchNextQueuedTelegramTurn(deps.dispatchNextQueuedTelegramTurn);
+    };
+    return {
+        onSessionBeforeCompact: (_event, ctx) => {
+            if (deps.isContextActive && !deps.isContextActive(ctx))
+                return;
+            deps.setCompactionInProgress(true);
+            const typingStartResult = deps.startTypingLoop?.(ctx);
+            typingStartedByObserver =
+                !!deps.startTypingLoop && typingStartResult !== false;
+            deps.updateStatus(ctx);
+            clearFallbackTimer();
+            const admittedGeneration = observationGeneration;
+            fallbackTimer = setTimer(() => {
+                if (observationGeneration !== admittedGeneration)
+                    return;
+                observationGeneration += 1;
+                fallbackTimer = undefined;
+                if (deps.isContextActive && !deps.isContextActive(ctx))
+                    return;
+                releaseCompactionPresence(ctx);
+                deps.recordRuntimeEvent?.("compact", new Error("Compaction observer timed out"));
+                // Observer expiry releases local presence, not Pi's eventual terminal result.
+                requestDispatch();
+            }, timeoutMs);
+            unrefTelegramLifecycleTimer(fallbackTimer);
+        },
+        onSessionCompact: (_event, ctx) => {
+            if (deps.isContextActive && !deps.isContextActive(ctx))
+                return;
+            clearFallbackTimer();
+            releaseCompactionPresence(ctx);
+            requestDispatch();
+        },
+        onSessionCompactFailed: (_event, ctx) => {
+            if (deps.isContextActive && !deps.isContextActive(ctx))
+                return;
+            clearFallbackTimer();
+            releaseCompactionPresence(ctx);
+            deps.onCompactionAbandoned?.();
+            requestDispatch();
+        },
+        onSessionShutdown: () => {
+            clearFallbackTimer();
+            if (typingStartedByObserver)
+                deps.stopTypingLoop?.();
+            typingStartedByObserver = false;
+        },
+    };
+}
+export function createTelegramMessageActivityTypingHooks(deps) {
+    const ensureTyping = (ctx) => {
+        if (deps.hasActiveTurn())
+            deps.startTypingLoop(ctx);
+    };
+    const handleMessageActivity = async (phase, event, ctx, inner) => {
+        const typedCtx = ctx;
+        ensureTyping(typedCtx);
+        try {
+            await inner(event, ctx);
+        }
+        catch (error) {
+            deps.recordRuntimeEvent?.("message-activity", error, { phase });
+        }
+        finally {
+            ensureTyping(typedCtx);
+        }
+    };
+    return {
+        onMessageStart: (event, ctx) => handleMessageActivity("start", event, ctx, deps.onMessageStart),
+        onMessageUpdate: (event, ctx) => handleMessageActivity("update", event, ctx, deps.onMessageUpdate),
+    };
+}
+export function appendTelegramLifecycleHooks(base, extra, isSessionActive) {
+    return {
+        onSessionStart: async (event, ctx) => {
+            await base.onSessionStart(event, ctx);
+            if (isSessionActive?.(ctx) === false)
+                return;
+            await extra.onSessionStart?.(event, ctx);
+        },
+        onSessionShutdown: async (event, ctx) => {
+            await base.onSessionShutdown(event, ctx);
+            if (isSessionActive?.(ctx) === false)
+                return;
+            await extra.onSessionShutdown?.(event, ctx);
+        },
+    };
+}
+export function registerTelegramLifecycleHooks(pi, deps) {
+    const isActive = (ctx) => deps.isSessionActive?.(ctx) !== false;
+    pi.on("input", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onInput?.(event, ctx);
+    });
+    pi.on("session_start", async (event, ctx) => {
+        await deps.onSessionStart(event, ctx);
+    });
+    pi.on("session_shutdown", async (event, ctx) => {
+        await deps.onSessionShutdown(event, ctx);
+    });
+    pi.on("session_before_compact", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onSessionBeforeCompact?.(event, ctx);
+    });
+    pi.on("session_compact", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onSessionCompact?.(event, ctx);
+    });
+    pi.on("session_compact_failed", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onSessionCompactFailed?.(event, ctx);
+    });
+    // The Pi SDK still types this result as a string; compatible runtimes may
+    // preserve ordered system prompt blocks through the same public hook.
+    const registerBeforeAgentStart = pi.on.bind(pi);
+    registerBeforeAgentStart("before_agent_start", async (event, ctx) => {
+        return deps.onBeforeAgentStart(event, ctx);
+    });
+    pi.on("model_select", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onModelSelect(event, ctx);
+    });
+    pi.on("agent_start", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onAgentStart(event, ctx);
+    });
+    pi.on("tool_execution_start", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onToolExecutionStart(event, ctx);
+    });
+    pi.on("tool_execution_update", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onToolExecutionUpdate?.(event, ctx);
+    });
+    pi.on("tool_execution_end", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onToolExecutionEnd(event, ctx);
+    });
+    pi.on("message_start", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onMessageStart(event, ctx);
+    });
+    pi.on("message_update", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onMessageUpdate(event, ctx);
+    });
+    pi.on("message_end", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onMessageEnd?.(event, ctx);
+    });
+    pi.on("ui_prompt_start", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onUiPromptStart?.(event, ctx);
+    });
+    pi.on("ui_prompt_end", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onUiPromptEnd?.(event, ctx);
+    });
+    pi.on("agent_end", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onAgentEnd(event, ctx);
+    });
+    pi.on("agent_settled", async (event, ctx) => {
+        if (!isActive(ctx))
+            return;
+        await deps.onAgentSettled?.(event, ctx);
+    });
+}

package/packages/telegram/src/pi.d.ts

@@ -0,0 +1,76 @@
+/**
+ * pi SDK adapter boundary
+ * Zones: pi agent sdk boundary, shared adapters
+ * Owns direct pi SDK imports and exposes narrow bridge-facing helpers/types for the extension composition layer
+ */
+import type { AssistantMessageEvent } from "@earendil-works/pi-ai";
+import { type AgentEndEvent, type AgentSettledEvent, type AgentStartEvent, type BeforeAgentStartEvent, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, type InputEvent, type MessageEndEvent, type SessionBeforeCompactEvent, type SessionCompactEvent, type SessionShutdownEvent, type SessionStartEvent, type SlashCommandInfo, type UIPromptEndEvent, type UIPromptStartEvent } from "@earendil-works/pi-coding-agent";
+export type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AssistantMessageEvent, BeforeAgentStartEvent, ExtensionAPI, ExtensionCommandContext, ExtensionContext, InputEvent, MessageEndEvent, SessionBeforeCompactEvent, SessionCompactEvent, SessionShutdownEvent, SessionStartEvent, SlashCommandInfo, UIPromptEndEvent, UIPromptStartEvent, };
+export interface SessionCompactFailedEvent {
+    type: "session_compact_failed";
+    reason: "manual" | "threshold" | "overflow";
+    errorMessage?: string;
+    aborted: boolean;
+    willRetry: boolean;
+    fromExtension: boolean;
+}
+export interface ToolExecutionStartEvent {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+export interface ToolExecutionUpdateEvent {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    partialResult: unknown;
+}
+export interface ToolExecutionEndEvent {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    isError: boolean;
+}
+export interface PiSettingsManager {
+    reload: () => Promise<void>;
+    flush: () => Promise<void>;
+    getEnabledModels: () => string[] | undefined;
+    setEnabledModels: (patterns: string[] | undefined) => void;
+}
+export type PiSlashCommandInfo = SlashCommandInfo;
+export type PiRunMode = "tui" | "rpc" | "json" | "print";
+/** Pi rejects a context captured before session replacement with a stale-context error; this is not a domain failure. */
+export declare function isPiStaleContextError(error: unknown): boolean;
+export declare function getExtensionContextMode(ctx: unknown): PiRunMode | undefined;
+export declare function isExtensionContextPassiveRunMode(ctx: unknown): boolean;
+export declare function canStartPollingInExtensionContext(ctx: unknown): boolean;
+export declare function formatPollingStartBlockedByRunMode(ctx: unknown): string;
+export declare function getSessionCompactionReason(event: unknown): "manual" | "threshold" | "overflow" | "unknown";
+export interface PiExtensionApiRuntimePorts {
+    sendUserMessage: ExtensionAPI["sendUserMessage"];
+    exec: ExtensionAPI["exec"];
+    getCommands: ExtensionAPI["getCommands"];
+    getThinkingLevel: ExtensionAPI["getThinkingLevel"];
+    setThinkingLevel: ExtensionAPI["setThinkingLevel"];
+    getActiveTools: ExtensionAPI["getActiveTools"];
+    setActiveTools: ExtensionAPI["setActiveTools"];
+    setModel: ExtensionAPI["setModel"];
+    registerCommand: ExtensionAPI["registerCommand"];
+}
+export declare function createExtensionApiRuntimePorts(api: Pick<ExtensionAPI, "sendUserMessage" | "exec" | "getCommands" | "getThinkingLevel" | "setThinkingLevel" | "getActiveTools" | "setActiveTools" | "setModel" | "registerCommand">): PiExtensionApiRuntimePorts;
+export declare function normalizeSettingsManager(manager: unknown): PiSettingsManager;
+export declare function createSettingsManager(cwd: string): Promise<PiSettingsManager>;
+export declare function createScopedModelPatternPersister(deps: {
+    createSettingsManager: (cwd: string) => PiSettingsManager | PromiseLike<PiSettingsManager>;
+    clearCachedModelMenuInputs: () => void;
+}): (patterns: string[], ctx: ExtensionContext) => Promise<void>;
+export declare function getExtensionContextModel(ctx: ExtensionContext): ExtensionContext["model"];
+export declare function getExtensionContextCwd(ctx: ExtensionContext): string;
+export declare function getExtensionContextSessionId(ctx: ExtensionContext): string;
+export declare function getExtensionContextSessionId(ctx: ExtensionContext | undefined): string | undefined;
+export declare function isExtensionContextIdle(ctx: ExtensionContext): boolean;
+export declare function hasExtensionContextPendingMessages(ctx: ExtensionContext): boolean;
+export declare function compactExtensionContext(ctx: ExtensionContext, callbacks: Parameters<ExtensionContext["compact"]>[0]): ReturnType<ExtensionContext["compact"]>;