pi-harness-runtime 1.1.398 → 1.1.403

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

@@ -0,0 +1,159 @@
+/**
+ * Telegram bridge runtime-state helpers
+ * Zones: pi agent runtime state, telegram session, shared coordination
+ * Owns small session-local runtime primitives that are shared by orchestration but are not specific to queueing, rendering, polling, or Telegram transport
+ */
+export interface TelegramRuntimeQueueCounters {
+    nextQueuedTelegramItemOrder: number;
+    nextQueuedTelegramControlOrder: number;
+}
+export interface TelegramRuntimeLifecycleFlags {
+    activeTelegramToolExecutions: number;
+    telegramTurnDispatchPending: boolean;
+    compactionInProgress: boolean;
+    foldQueuedPromptsIntoHistory: boolean;
+    setupInProgress: boolean;
+}
+export interface TelegramBridgeRuntimeState extends TelegramRuntimeQueueCounters, TelegramRuntimeLifecycleFlags {
+    abortHandler?: () => void;
+    typingInterval?: ReturnType<typeof setInterval>;
+    typingInFlight?: Promise<void>;
+    typingLoopDeps?: TelegramTypingLoopDeps;
+    typingLoopKey?: string;
+}
+export interface TelegramRuntimeQueuePort {
+    syncCounters: (counters: Partial<TelegramRuntimeQueueCounters>) => void;
+    allocateItemOrder: () => number;
+    allocateControlOrder: () => number;
+}
+export interface TelegramRuntimeLifecyclePort {
+    syncFlags: (flags: Partial<TelegramRuntimeLifecycleFlags>) => void;
+    getActiveToolExecutions: () => number;
+    setActiveToolExecutions: (count: number) => void;
+    resetActiveToolExecutions: () => void;
+    hasDispatchPending: () => boolean;
+    setDispatchPending: (pending: boolean) => void;
+    clearDispatchPending: () => void;
+    isCompactionInProgress: () => boolean;
+    setCompactionInProgress: (inProgress: boolean) => void;
+    shouldFoldQueuedPromptsIntoHistory: () => boolean;
+    setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
+}
+export interface TelegramRuntimeSetupPort {
+    isInProgress: () => boolean;
+    start: () => boolean;
+    finish: () => void;
+}
+export interface TelegramRuntimeAbortPort {
+    hasHandler: () => boolean;
+    setHandler: (abortHandler: () => void) => void;
+    clearHandler: () => void;
+    getHandler: () => (() => void) | undefined;
+    abortTurn: () => boolean;
+}
+export interface TelegramRuntimeTypingPort {
+    start: (deps: TelegramTypingLoopDeps) => boolean;
+    stop: () => boolean;
+    waitForIdle: () => Promise<void>;
+}
+export interface TelegramBridgeRuntime {
+    state: TelegramBridgeRuntimeState;
+    queue: TelegramRuntimeQueuePort;
+    lifecycle: TelegramRuntimeLifecyclePort;
+    setup: TelegramRuntimeSetupPort;
+    abort: TelegramRuntimeAbortPort;
+    typing: TelegramRuntimeTypingPort;
+}
+export declare function createTelegramBridgeRuntimeState(): TelegramBridgeRuntimeState;
+export declare function createTelegramBridgeRuntime(state?: TelegramBridgeRuntimeState): TelegramBridgeRuntime;
+export declare function syncTelegramQueueRuntimeCounters(state: TelegramBridgeRuntimeState, counters: Partial<TelegramRuntimeQueueCounters>): void;
+export declare function allocateTelegramQueueItemOrder(state: TelegramBridgeRuntimeState): number;
+export declare function allocateTelegramQueueControlOrder(state: TelegramBridgeRuntimeState): number;
+export declare function syncTelegramLifecycleRuntimeFlags(state: TelegramBridgeRuntimeState, flags: Partial<TelegramRuntimeLifecycleFlags>): void;
+export declare function getActiveTelegramToolExecutions(state: TelegramBridgeRuntimeState): number;
+export declare function setActiveTelegramToolExecutions(state: TelegramBridgeRuntimeState, count: number): void;
+export declare function resetActiveTelegramToolExecutions(state: TelegramBridgeRuntimeState): void;
+export declare function hasTelegramDispatchPending(state: TelegramBridgeRuntimeState): boolean;
+export declare function clearTelegramDispatchPending(state: TelegramBridgeRuntimeState): void;
+export declare function isTelegramCompactionInProgress(state: TelegramBridgeRuntimeState): boolean;
+export declare function setTelegramCompactionInProgress(state: TelegramBridgeRuntimeState, inProgress: boolean): void;
+export declare function shouldFoldQueuedPromptsIntoHistory(state: TelegramBridgeRuntimeState): boolean;
+export declare function setFoldQueuedPromptsIntoHistory(state: TelegramBridgeRuntimeState, fold: boolean): void;
+export declare function isTelegramSetupInProgress(state: TelegramBridgeRuntimeState): boolean;
+export declare function startTelegramSetup(state: TelegramBridgeRuntimeState): boolean;
+export declare function finishTelegramSetup(state: TelegramBridgeRuntimeState): void;
+export declare function hasTelegramAbortHandler(state: TelegramBridgeRuntimeState): boolean;
+export declare function setTelegramAbortHandler(state: TelegramBridgeRuntimeState, abortHandler: () => void): void;
+export declare function clearTelegramAbortHandler(state: TelegramBridgeRuntimeState): void;
+export declare function getTelegramAbortHandler(state: TelegramBridgeRuntimeState): (() => void) | undefined;
+export declare function abortTelegramTurn(state: TelegramBridgeRuntimeState): boolean;
+export interface TelegramTypingLoopTarget {
+    chatId: number;
+    threadId?: number;
+}
+export interface TelegramTypingLoopDeps {
+    chatId: number | undefined;
+    target?: TelegramTypingLoopTarget;
+    intervalMs: number;
+    sendTypingAction: (chatId: number, options?: {
+        message_thread_id?: number;
+    }) => Promise<unknown>;
+    shouldContinue?: () => boolean;
+    onStopped?: () => void;
+}
+export interface TelegramRuntimeEventRecorderPort {
+    recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
+}
+export interface TelegramTypingLoopStarterDeps<TContext> extends TelegramRuntimeEventRecorderPort {
+    typing: TelegramRuntimeTypingPort;
+    getDefaultChatId: () => number | undefined;
+    sendTypingAction: (chatId: number, options?: {
+        message_thread_id?: number;
+    }) => Promise<unknown>;
+    updateStatus: (ctx: TContext, error?: string) => void;
+    isContextActive?: (ctx: TContext) => boolean;
+    isTransportAvailable?: () => boolean;
+    getTransportAuthority?: () => string | number | undefined;
+    intervalMs?: number;
+}
+export declare function createTelegramTypingLoopStarter<TContext>(deps: TelegramTypingLoopStarterDeps<TContext>): (ctx: TContext, chatId?: number, options?: {
+    target?: TelegramTypingLoopTarget;
+}) => boolean;
+export declare function startTelegramTypingLoop(state: TelegramBridgeRuntimeState, deps: TelegramTypingLoopDeps): boolean;
+export declare function stopTelegramTypingLoop(state: TelegramBridgeRuntimeState): boolean;
+export declare function waitForTelegramTypingLoopIdle(state: TelegramBridgeRuntimeState, timeoutMs?: number): Promise<void>;
+export declare function createTelegramContextAbortHandlerSetter<TContext extends {
+    abort: () => void;
+}>(abort: Pick<TelegramRuntimeAbortPort, "setHandler">): (ctx: TContext) => void;
+export interface TelegramAgentEndResetDeps {
+    abort: Pick<TelegramRuntimeAbortPort, "clearHandler">;
+    typing: Pick<TelegramRuntimeTypingPort, "stop">;
+    clearActiveTurn: () => void;
+    resetToolExecutions: () => void;
+    clearPendingModelSwitch: () => void;
+    clearDispatchPending: () => void;
+}
+export declare function createTelegramAgentEndResetter(deps: TelegramAgentEndResetDeps): () => void;
+export interface TelegramPromptDispatchLifecycleDeps<TContext> extends TelegramRuntimeEventRecorderPort {
+    lifecycle: Pick<TelegramRuntimeLifecyclePort, "setDispatchPending" | "clearDispatchPending">;
+    typing: Pick<TelegramRuntimeTypingPort, "stop">;
+    startTypingLoop: (ctx: TContext, chatId?: number, options?: {
+        target?: TelegramTypingLoopTarget;
+    }) => boolean | void;
+    updateStatus: (ctx: TContext, error?: string) => void;
+}
+export interface TelegramPromptDispatchRuntimeDeps<TContext> extends TelegramTypingLoopStarterDeps<TContext> {
+    lifecycle: TelegramPromptDispatchLifecycleDeps<TContext>["lifecycle"];
+}
+export interface TelegramPromptDispatchRuntime<TContext> {
+    startTypingLoop: (ctx: TContext, chatId?: number, options?: {
+        target?: TelegramTypingLoopTarget;
+    }) => boolean | void;
+    onPromptDispatchStart: (ctx: TContext, chatId?: number) => void;
+    onPromptDispatchFailure: (ctx: TContext, message: string) => void;
+}
+export declare function createTelegramPromptDispatchRuntime<TContext>(deps: TelegramPromptDispatchRuntimeDeps<TContext>): TelegramPromptDispatchRuntime<TContext>;
+export declare function createTelegramPromptDispatchLifecycle<TContext>(deps: TelegramPromptDispatchLifecycleDeps<TContext>): {
+    onPromptDispatchStart: (ctx: TContext, chatId?: number) => void;
+    onPromptDispatchFailure: (ctx: TContext, message: string) => void;
+};

package/packages/telegram/src/runtime.js

@@ -0,0 +1,351 @@
+/**
+ * Telegram bridge runtime-state helpers
+ * Zones: pi agent runtime state, telegram session, shared coordination
+ * Owns small session-local runtime primitives that are shared by orchestration but are not specific to queueing, rendering, polling, or Telegram transport
+ */
+const TELEGRAM_TYPING_ACTION_INTERVAL_MS = 3_000;
+const TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS = 250;
+export function createTelegramBridgeRuntimeState() {
+    return {
+        nextQueuedTelegramItemOrder: 0,
+        nextQueuedTelegramControlOrder: 0,
+        activeTelegramToolExecutions: 0,
+        telegramTurnDispatchPending: false,
+        compactionInProgress: false,
+        foldQueuedPromptsIntoHistory: false,
+        setupInProgress: false,
+    };
+}
+export function createTelegramBridgeRuntime(state = createTelegramBridgeRuntimeState()) {
+    return {
+        state,
+        queue: {
+            syncCounters: (counters) => syncTelegramQueueRuntimeCounters(state, counters),
+            allocateItemOrder: () => allocateTelegramQueueItemOrder(state),
+            allocateControlOrder: () => allocateTelegramQueueControlOrder(state),
+        },
+        lifecycle: {
+            syncFlags: (flags) => syncTelegramLifecycleRuntimeFlags(state, flags),
+            getActiveToolExecutions: () => getActiveTelegramToolExecutions(state),
+            setActiveToolExecutions: (count) => setActiveTelegramToolExecutions(state, count),
+            resetActiveToolExecutions: () => resetActiveTelegramToolExecutions(state),
+            hasDispatchPending: () => hasTelegramDispatchPending(state),
+            setDispatchPending: (pending) => setTelegramDispatchPending(state, pending),
+            clearDispatchPending: () => clearTelegramDispatchPending(state),
+            isCompactionInProgress: () => isTelegramCompactionInProgress(state),
+            setCompactionInProgress: (inProgress) => setTelegramCompactionInProgress(state, inProgress),
+            shouldFoldQueuedPromptsIntoHistory: () => shouldFoldQueuedPromptsIntoHistory(state),
+            setFoldQueuedPromptsIntoHistory: (fold) => setFoldQueuedPromptsIntoHistory(state, fold),
+        },
+        setup: {
+            isInProgress: () => isTelegramSetupInProgress(state),
+            start: () => startTelegramSetup(state),
+            finish: () => finishTelegramSetup(state),
+        },
+        abort: {
+            hasHandler: () => hasTelegramAbortHandler(state),
+            setHandler: (abortHandler) => setTelegramAbortHandler(state, abortHandler),
+            clearHandler: () => clearTelegramAbortHandler(state),
+            getHandler: () => getTelegramAbortHandler(state),
+            abortTurn: () => abortTelegramTurn(state),
+        },
+        typing: {
+            start: (deps) => startTelegramTypingLoop(state, deps),
+            stop: () => stopTelegramTypingLoop(state),
+            waitForIdle: () => waitForTelegramTypingLoopIdle(state),
+        },
+    };
+}
+export function syncTelegramQueueRuntimeCounters(state, counters) {
+    if (counters.nextQueuedTelegramItemOrder !== undefined) {
+        state.nextQueuedTelegramItemOrder = counters.nextQueuedTelegramItemOrder;
+    }
+    if (counters.nextQueuedTelegramControlOrder !== undefined) {
+        state.nextQueuedTelegramControlOrder =
+            counters.nextQueuedTelegramControlOrder;
+    }
+}
+export function allocateTelegramQueueItemOrder(state) {
+    return state.nextQueuedTelegramItemOrder++;
+}
+export function allocateTelegramQueueControlOrder(state) {
+    return state.nextQueuedTelegramControlOrder++;
+}
+export function syncTelegramLifecycleRuntimeFlags(state, flags) {
+    if (flags.activeTelegramToolExecutions !== undefined) {
+        state.activeTelegramToolExecutions = flags.activeTelegramToolExecutions;
+    }
+    if (flags.telegramTurnDispatchPending !== undefined) {
+        state.telegramTurnDispatchPending = flags.telegramTurnDispatchPending;
+    }
+    if (flags.compactionInProgress !== undefined) {
+        state.compactionInProgress = flags.compactionInProgress;
+    }
+    if (flags.foldQueuedPromptsIntoHistory !== undefined) {
+        state.foldQueuedPromptsIntoHistory = flags.foldQueuedPromptsIntoHistory;
+    }
+    if (flags.setupInProgress !== undefined) {
+        state.setupInProgress = flags.setupInProgress;
+    }
+}
+export function getActiveTelegramToolExecutions(state) {
+    return state.activeTelegramToolExecutions;
+}
+export function setActiveTelegramToolExecutions(state, count) {
+    state.activeTelegramToolExecutions = count;
+}
+export function resetActiveTelegramToolExecutions(state) {
+    state.activeTelegramToolExecutions = 0;
+}
+export function hasTelegramDispatchPending(state) {
+    return state.telegramTurnDispatchPending;
+}
+function setTelegramDispatchPending(state, pending) {
+    state.telegramTurnDispatchPending = pending;
+}
+export function clearTelegramDispatchPending(state) {
+    state.telegramTurnDispatchPending = false;
+}
+export function isTelegramCompactionInProgress(state) {
+    return state.compactionInProgress;
+}
+export function setTelegramCompactionInProgress(state, inProgress) {
+    state.compactionInProgress = inProgress;
+}
+export function shouldFoldQueuedPromptsIntoHistory(state) {
+    return state.foldQueuedPromptsIntoHistory;
+}
+export function setFoldQueuedPromptsIntoHistory(state, fold) {
+    state.foldQueuedPromptsIntoHistory = fold;
+}
+export function isTelegramSetupInProgress(state) {
+    return state.setupInProgress;
+}
+export function startTelegramSetup(state) {
+    if (state.setupInProgress)
+        return false;
+    state.setupInProgress = true;
+    return true;
+}
+export function finishTelegramSetup(state) {
+    state.setupInProgress = false;
+}
+export function hasTelegramAbortHandler(state) {
+    return !!state.abortHandler;
+}
+export function setTelegramAbortHandler(state, abortHandler) {
+    state.abortHandler = abortHandler;
+}
+export function clearTelegramAbortHandler(state) {
+    state.abortHandler = undefined;
+}
+export function getTelegramAbortHandler(state) {
+    return state.abortHandler;
+}
+export function abortTelegramTurn(state) {
+    if (!state.abortHandler)
+        return false;
+    state.abortHandler();
+    return true;
+}
+function getTelegramTypingLoopThreadParams(target) {
+    const threadId = target?.threadId;
+    return Number.isInteger(threadId)
+        ? { message_thread_id: threadId }
+        : undefined;
+}
+function updateTelegramRuntimeStatusSafely(updateStatus, ctx, options) {
+    try {
+        updateStatus(ctx, options.error);
+    }
+    catch (statusError) {
+        try {
+            options.recordRuntimeEvent?.(options.category, statusError, {
+                phase: options.phase,
+            });
+        }
+        catch {
+            // Status diagnostics cannot escape an asynchronous runtime owner.
+        }
+    }
+}
+export function createTelegramTypingLoopStarter(deps) {
+    return (ctx, chatId, options) => {
+        const transportAuthority = deps.getTransportAuthority?.();
+        const hasTransport = () => deps.getTransportAuthority
+            ? transportAuthority !== undefined &&
+                Object.is(deps.getTransportAuthority(), transportAuthority)
+            : deps.isTransportAvailable?.() !== false;
+        if (!hasTransport())
+            return false;
+        let active = true;
+        return deps.typing.start({
+            chatId: chatId ?? deps.getDefaultChatId(),
+            target: options?.target,
+            intervalMs: deps.intervalMs ?? TELEGRAM_TYPING_ACTION_INTERVAL_MS,
+            sendTypingAction: async (targetChatId, actionOptions) => {
+                if (!active)
+                    return;
+                if (!hasTransport()) {
+                    deps.typing.stop();
+                    return;
+                }
+                try {
+                    await deps.sendTypingAction(targetChatId, actionOptions);
+                }
+                catch (error) {
+                    if (deps.isContextActive?.(ctx) === false)
+                        return;
+                    if (!active)
+                        return;
+                    if (!hasTransport()) {
+                        deps.typing.stop();
+                        return;
+                    }
+                    try {
+                        deps.recordRuntimeEvent?.("typing", error, {
+                            chatId: targetChatId,
+                        });
+                    }
+                    catch {
+                        // Typing diagnostics cannot escape the in-flight action owner.
+                    }
+                }
+            },
+            shouldContinue: hasTransport,
+            onStopped: () => {
+                active = false;
+            },
+        });
+    };
+}
+function getTelegramTypingLoopKey(deps) {
+    const threadId = deps.target?.threadId;
+    return `${deps.chatId ?? 0}:${Number.isInteger(threadId) ? threadId : "all"}`;
+}
+export function startTelegramTypingLoop(state, deps) {
+    if (deps.chatId === undefined || deps.chatId === 0)
+        return false;
+    const previousKey = state.typingLoopKey;
+    const previousDeps = state.typingLoopDeps;
+    const nextKey = getTelegramTypingLoopKey(deps);
+    if (previousDeps && previousDeps !== deps) {
+        previousDeps.onStopped?.();
+        state.typingInFlight = undefined;
+    }
+    state.typingLoopDeps = deps;
+    state.typingLoopKey = nextKey;
+    const sendTyping = () => {
+        const activeDeps = state.typingLoopDeps;
+        if (!activeDeps ||
+            activeDeps.chatId === undefined ||
+            activeDeps.chatId === 0)
+            return;
+        if (activeDeps.shouldContinue?.() === false) {
+            stopTelegramTypingLoop(state);
+            return;
+        }
+        if (state.typingInFlight)
+            return;
+        const targetChatId = activeDeps.chatId;
+        const threadParams = getTelegramTypingLoopThreadParams(activeDeps.target);
+        const typing = Promise.resolve()
+            .then(() => activeDeps.sendTypingAction(targetChatId, threadParams))
+            .then(() => undefined)
+            .catch(() => undefined);
+        state.typingInFlight = typing;
+        void typing.finally(() => {
+            if (state.typingInFlight === typing)
+                state.typingInFlight = undefined;
+        });
+    };
+    if (state.typingInterval) {
+        if (previousKey === nextKey)
+            return false;
+        sendTyping();
+        return true;
+    }
+    sendTyping();
+    state.typingInterval = setInterval(sendTyping, deps.intervalMs);
+    state.typingInterval.unref?.();
+    return true;
+}
+export function stopTelegramTypingLoop(state) {
+    if (!state.typingInterval)
+        return false;
+    clearInterval(state.typingInterval);
+    const activeDeps = state.typingLoopDeps;
+    state.typingInterval = undefined;
+    state.typingLoopDeps = undefined;
+    state.typingLoopKey = undefined;
+    state.typingInFlight = undefined;
+    activeDeps?.onStopped?.();
+    return true;
+}
+export async function waitForTelegramTypingLoopIdle(state, timeoutMs = TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS) {
+    const inFlight = state.typingInFlight;
+    if (!inFlight)
+        return;
+    if (timeoutMs <= 0) {
+        await Promise.race([inFlight, Promise.resolve()]);
+        return;
+    }
+    await Promise.race([
+        inFlight,
+        new Promise((resolve) => {
+            setTimeout(resolve, timeoutMs);
+        }),
+    ]);
+}
+export function createTelegramContextAbortHandlerSetter(abort) {
+    return (ctx) => {
+        abort.setHandler(() => ctx.abort());
+    };
+}
+export function createTelegramAgentEndResetter(deps) {
+    return () => {
+        deps.abort.clearHandler();
+        deps.typing.stop();
+        deps.clearActiveTurn();
+        deps.resetToolExecutions();
+        deps.clearPendingModelSwitch();
+        deps.clearDispatchPending();
+    };
+}
+export function createTelegramPromptDispatchRuntime(deps) {
+    const startTypingLoop = createTelegramTypingLoopStarter(deps);
+    return {
+        startTypingLoop,
+        ...createTelegramPromptDispatchLifecycle({
+            lifecycle: deps.lifecycle,
+            typing: deps.typing,
+            startTypingLoop,
+            updateStatus: deps.updateStatus,
+            recordRuntimeEvent: deps.recordRuntimeEvent,
+        }),
+    };
+}
+export function createTelegramPromptDispatchLifecycle(deps) {
+    return {
+        onPromptDispatchStart: (ctx, chatId) => {
+            deps.lifecycle.setDispatchPending(true);
+            deps.startTypingLoop(ctx, chatId);
+            updateTelegramRuntimeStatusSafely(deps.updateStatus, ctx, {
+                category: "dispatch",
+                phase: "status-update",
+                recordRuntimeEvent: deps.recordRuntimeEvent,
+            });
+        },
+        onPromptDispatchFailure: (ctx, message) => {
+            deps.lifecycle.clearDispatchPending();
+            deps.typing.stop();
+            deps.recordRuntimeEvent?.("dispatch", new Error(message));
+            updateTelegramRuntimeStatusSafely(deps.updateStatus, ctx, {
+                error: `dispatch failed: ${message}`,
+                category: "dispatch",
+                phase: "status-update",
+                recordRuntimeEvent: deps.recordRuntimeEvent,
+            });
+        },
+    };
+}