@llblab/pi-telegram 0.51.5 → 0.52.0

package/dist/lib/keyboard.d.ts

@@ -17,7 +17,5 @@ export type TelegramInlineKeyboardButton = {
 export interface TelegramInlineKeyboardMarkup {
     inline_keyboard: TelegramInlineKeyboardButton[][];
 }
-export declare const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
-export declare function getTelegramCallbackDataByteLength(value: string): number;
 export declare function assertTelegramCallbackData(callbackData: string, context?: string): string;
 export declare function assertTelegramInlineKeyboardCallbackData(replyMarkup: unknown, context?: string): void;

package/dist/lib/keyboard.js

@@ -3,8 +3,8 @@
  * Zones: telegram ui, shared structure
  * Owns the shared Bot API reply-markup shape while feature domains own their button semantics
  */
-export const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
-export function getTelegramCallbackDataByteLength(value) {
+const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
+function getTelegramCallbackDataByteLength(value) {
     return new TextEncoder().encode(value).byteLength;
 }
 export function assertTelegramCallbackData(callbackData, context = "Telegram callback_data") {

package/dist/lib/lifecycle.d.ts

@@ -1,7 +1,8 @@
 /**
- * Telegram lifecycle hook registration helpers
+ * Telegram session lifecycle coordination and hook registration
  * Zones: pi agent lifecycle, telegram session
- * Binds prepared Telegram lifecycle runtimes to pi extension lifecycle events
+ * Owns context generations, bounded connect intent across resume, and session sequencing.
+ * Transport authority, durable bindings, and queue custody remain with their owners.
  */
 import * as BusFollower from "./bus-follower.ts";
 import * as Queue from "./queue.ts";
@@ -50,6 +51,58 @@ export interface TelegramSessionLifecycleHooks {
     onSessionStart: (event: SessionStartEvent, ctx: ExtensionContext) => Promise<void>;
     onSessionShutdown: (event: SessionShutdownEvent, ctx: ExtensionContext) => Promise<void>;
 }
+export interface TelegramConnectionIntent {
+    id: string;
+    cwd: string;
+    profileName?: string;
+}
+interface TelegramConnectionHandoff extends TelegramConnectionIntent {
+    pid: number;
+    targetSessionFile: string;
+    expiresAtMs: number;
+}
+export interface TelegramConnectionHandoffStore {
+    pending?: TelegramConnectionHandoff;
+}
+export interface TelegramConnectionLifecycle {
+    prepare(event: SessionStartEvent, ctx: ExtensionContext): (() => void) | undefined;
+    onSessionShutdown(event: SessionShutdownEvent, ctx: ExtensionContext): void;
+}
+export declare function createTelegramConnectionLifecycle(deps: {
+    intent: ReturnType<typeof createTelegramConnectionIntentRuntime>;
+    getGeneration(): number;
+    isCurrent(ctx: ExtensionContext): boolean;
+    getProfileName(): string | undefined;
+    isConnected(): boolean;
+    activateProfile(profileName: string | undefined, isCurrent: () => boolean): Promise<boolean>;
+    start(ctx: ExtensionContext): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    recordError(error: unknown): void;
+}): TelegramConnectionLifecycle;
+export declare function createTelegramConnectionIntentRuntime(options?: {
+    store?: TelegramConnectionHandoffStore;
+    now?: () => number;
+    pid?: number;
+}): {
+    begin(cwd: string, profileName?: string): string;
+    isActive(id: string): boolean;
+    finish(id: string): void;
+    cancel(): void;
+    suspend(input: {
+        reason: string;
+        cwd: string;
+        targetSessionFile?: string;
+        connected: boolean;
+        profileName?: string;
+    }): void;
+    resume(input: {
+        reason: string;
+        cwd: string;
+        sessionFile?: string;
+    }): TelegramConnectionIntent | undefined;
+};
 export interface TelegramSessionContextStore<TContext> {
     get: () => TContext | undefined;
     getGeneration: () => number;
@@ -62,6 +115,7 @@ export declare function createTelegramSessionContextStore<TContext>(options?: {
 }): TelegramSessionContextStore<TContext>;
 export declare function createTelegramSessionGenerationFence(store: TelegramSessionContextStore<ExtensionContext>, hooks: TelegramSessionLifecycleHooks): TelegramSessionLifecycleHooks;
 export interface TelegramBridgeSessionServiceRuntime {
+    connection?: TelegramConnectionLifecycle;
     resumeGroupedInput(ctx: ExtensionContext): void;
     suspendGroupedInput(): void;
     delivery: {
@@ -108,6 +162,7 @@ export interface TelegramBridgeSessionLifecyclePorts<TQueueItem, TModel = unknow
         };
         delivery: TelegramBridgeSessionServiceRuntime["delivery"];
         polling: TelegramBridgeSessionServiceRuntime["polling"];
+        connection?: TelegramBridgeSessionServiceRuntime["connection"];
         inboundWorker: TelegramBridgeSessionServiceRuntime["inboundWorker"];
         capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
         queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];

package/dist/lib/lifecycle.js

@@ -1,8 +1,11 @@
 /**
- * Telegram lifecycle hook registration helpers
+ * Telegram session lifecycle coordination and hook registration
  * Zones: pi agent lifecycle, telegram session
- * Binds prepared Telegram lifecycle runtimes to pi extension lifecycle events
+ * 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 { formatTelegramConnectionFailure } from "./status.js";
 import * as BusFollower from "./bus-follower.js";
 import * as Queue from "./queue.js";
 import * as TextGroups from "./text-groups.js";
@@ -23,6 +26,98 @@ export function createAgentStartDedupHook(inner, schedulePublication) {
         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;
@@ -112,6 +207,7 @@ export function createTelegramBridgeSessionLifecycleDeps(ports) {
             }),
             delivery: ports.services.delivery,
             polling: ports.services.polling,
+            connection: ports.services.connection,
             inboundWorker: ports.services.inboundWorker,
             capabilityMonitor: ports.services.capabilityMonitor,
             queueWatchdog: ports.services.queueWatchdog,
@@ -128,20 +224,27 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
         suspendPolling: deps.follower.suspendPolling,
         recordRuntimeEvent: deps.follower.recordRuntimeEvent,
     });
+    let preserveTarget = true;
     const queueLifecycle = Queue.createTelegramSessionLifecycleRuntime({
         ...deps.queue,
         isSessionActive,
-        stopPolling: suspendForReplacement,
+        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();
-            await deps.services.polling.onSessionStart(event, ctx);
+            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);
         },
@@ -150,6 +253,8 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             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 {
@@ -238,7 +343,7 @@ export function createTelegramCompactionObserverRuntime(deps) {
                 typingStartedByObserver = false;
                 deps.updateStatus(ctx);
                 deps.recordRuntimeEvent?.("compact", new Error("Compaction observer timed out"));
-                deps.onCompactionAbandoned?.();
+                // Observer expiry releases local presence, not Pi's eventual terminal result.
                 requestDispatch();
             }, timeoutMs);
             unrefTelegramLifecycleTimer(fallbackTimer);

package/dist/lib/locks.d.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram singleton lock helpers
  * Zones: telegram ownership, filesystem, transport authority
- * Owns extension-local owners.json access and Telegram bridge ownership semantics
+ * Owns filesystem authority, atomic runtime-section publication and Telegram bridge ownership semantics
  */
 import { renameSync } from "node:fs";
 export declare const TELEGRAM_LOCK_KEY = "default";
@@ -14,10 +14,21 @@ export declare const TELEGRAM_OWNERSHIP_REFRESH_MS = 2000;
  * Named profile → the validated profile name
  */
 export declare function resolveTelegramLockKey(activeProfile?: string): string;
-export interface TelegramActiveProfileGetter {
+interface TelegramActiveProfileGetter {
     getActiveProfileName: () => string | undefined;
 }
 export declare function createTelegramLockKeyResolver(activeProfile: TelegramActiveProfileGetter): () => string;
+/** Structural session view; Locks never imports the lifecycle owner. */
+interface TelegramOwnedStateSessionPort<TContext extends TelegramLockContext> {
+    get: () => TContext | undefined;
+    getGeneration: () => number;
+    isCurrent: (ctx: TContext, generation?: number) => boolean;
+}
+/**
+ * Captures exact context, session generation and owned leader epoch before awaits.
+ * Session replacement, release or re-election revokes the grant; a successor never renews it.
+ */
+export declare function createTelegramOwnedStateAuthorityCapture<TContext extends TelegramLockContext>(lock: Pick<TelegramLockRuntime<TContext>, "owns" | "getOwnedLeaderEpoch">, session: TelegramOwnedStateSessionPort<TContext>): () => (() => boolean) | undefined;
 export interface TelegramLockEntry {
     pid: number;
     cwd?: string;
@@ -27,6 +38,8 @@ export interface TelegramLockEntry {
     runtimeGeneration?: number;
     busSocketPath?: string;
     busSecret?: string;
+    /** Polling journal custody; inherited by every successor and kept after release. */
+    journalPath?: string;
 }
 export interface TelegramLockContext {
     cwd: string;
@@ -43,12 +56,12 @@ export type TelegramLockState = {
     kind: "stale";
     lock: TelegramLockEntry;
 };
-export interface TelegramLockAcquireOptions {
+interface TelegramLockAcquireOptions {
     force?: boolean;
     expectedOwner?: TelegramLockEntry;
     election?: boolean;
 }
-export type TelegramLockAcquireResult = {
+type TelegramLockAcquireResult = {
     ok: true;
     lock: TelegramLockEntry;
     replacedStale: boolean;
@@ -56,6 +69,12 @@ export type TelegramLockAcquireResult = {
     ok: false;
     lock: TelegramLockEntry;
 };
+export type TelegramOwnedStatePublicationResult<T> = {
+    committed: false;
+} | {
+    committed: true;
+    result: T;
+};
 export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
     acquire: (ctx: TContext, options?: TelegramLockAcquireOptions) => TelegramLockAcquireResult;
     release: () => TelegramLockState;
@@ -64,17 +83,26 @@ export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
     getOwnedLeaderEpoch: () => number | string | undefined;
     owns: (ctx?: TelegramLockContext) => boolean;
     commitIfOwned: (commit: () => void) => boolean;
+    /** Consolidated-store publication; domain reducers retain their own exact payload/CAS rules. */
+    publishStateSectionIfOwned?: <T>(section: "workspace" | "runtime", mutate: (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>, options: TelegramOwnedStatePublicationOptions) => TelegramOwnedStatePublicationResult<T>;
     refresh: (ctx?: TelegramLockContext) => boolean;
+    /** The polling journal named by owners.json for this key, owned or not. */
+    getJournalPath: () => string | undefined;
 }
-export interface TelegramLockOwnershipGuard<TContext extends TelegramLockContext> {
+interface TelegramLockOwnershipGuard<TContext extends TelegramLockContext> {
     ownsContext: (ctx: TContext) => boolean;
 }
-export interface TelegramLockContextStore<TContext extends TelegramLockContext> {
+interface TelegramLockContextStore<TContext extends TelegramLockContext> {
     get: () => TContext | undefined;
 }
-export interface TelegramLockRuntimeOptions {
+interface TelegramLockRuntimeOptions {
     key?: string | (() => string | undefined);
     locksPath?: string;
+    /** Consolidated version-2 state envelope; exclusive with `locksPath`. */
+    statePath?: string;
+    statePublication?: Pick<TelegramRuntimeStatePublicationOptions, "onPublicationBoundary" | "publishRename">;
+    /** Read-only ownership file of releases that used another directory; a live fresh owner there blocks acquisition. */
+    legacyLocksPath?: string;
     pid?: number;
     isProcessAlive?: (pid: number) => boolean;
     instanceId?: string;
@@ -84,9 +112,25 @@ export interface TelegramLockRuntimeOptions {
     mintLeaderEpoch?: () => number | string;
     runtimeGeneration?: number;
     staleHeartbeatMs?: number;
+    /** First leader without an inherited pointer names the polling journal it creates. */
+    createJournalPath?: (ctx: TelegramLockContext) => string | undefined;
 }
+/**
+ * Leader polling journal: the path owners.json names, else the session that would host it on acquisition.
+ * Without a session identity, the flat root `inbox` remains the compatibility fallback.
+ */
+export declare function createTelegramLeaderJournalPathResolver(deps: {
+    getNamedJournalPath: () => string | undefined;
+    getSessionId: () => string | undefined;
+    getProfileName: () => string | undefined;
+}): {
+    createJournalPath: () => string | undefined;
+    resolve(profileName?: string): string;
+};
+/** A released key keeps only `{ journalPath }`: no owner, but the successor's polling custody. */
+export declare function readTelegramLockJournalPath(value: unknown): string | undefined;
 export declare function readLocks(path?: string): Record<string, unknown>;
-export interface TelegramRenameRetryOptions {
+interface TelegramRenameRetryOptions {
     rename?: typeof renameSync;
     attempts?: number;
     retryDelayMs?: number;
@@ -100,17 +144,56 @@ export interface TelegramFileTransactionOptions {
     retryDelayMs?: number;
 }
 export declare function withTelegramFileTransaction<T>(transactionPath: string, operation: () => T, options?: TelegramFileTransactionOptions): T;
+export type TelegramRuntimeStateSection = "transport" | "workspace" | "admission" | "runtime";
+type TelegramRuntimeStateProfile = Partial<Record<TelegramRuntimeStateSection, unknown>>;
+interface TelegramRuntimeStateFile {
+    version: 2;
+    profiles: Record<string, TelegramRuntimeStateProfile>;
+}
+export declare class TelegramRuntimeStateError extends Error {
+    readonly code: "invalid" | "authority-changed" | "publication-unknown";
+    constructor(code: TelegramRuntimeStateError["code"], message: string, options?: ErrorOptions);
+}
+/** Strict, observational envelope read; section owners validate their own payloads. Legacy state is never adopted here. */
+export declare function readTelegramRuntimeState(path: string): TelegramRuntimeStateFile;
+/**
+ * Operator-approved optimistic recovery before leader acquisition: when the shared envelope, any transport section or a
+ * caller-validated section is damaged, publish a fresh empty envelope instead of refusing. All profiles lose runtime
+ * continuity. Filesystem access errors are not damage and still throw. Returns whether a reset was published.
+ */
+export declare function resetDamagedTelegramRuntimeState(path: string, validateProfile?: (profile: string, sections: Readonly<TelegramRuntimeStateProfile>) => void): boolean;
+export interface TelegramRuntimeStateMutation<T> {
+    value: unknown;
+    result: T;
+}
+interface TelegramRuntimeStatePublicationOptions {
+    /** Exact domain authority, recaptured by the caller before invoking this synchronous transaction. */
+    isCurrent: () => boolean;
+    onPublicationBoundary?: (boundary: "before-write" | "after-write-before-rename" | "after-rename") => void;
+    publishRename?: typeof renameSync;
+}
+export interface TelegramOwnedStatePublicationOptions extends TelegramRuntimeStatePublicationOptions {
+    /** Optional caller-bound physical/logical identity; a mismatch cannot redirect an owner grant. */
+    expectedScope?: {
+        path: string;
+        profile: string;
+    };
+}
+/**
+ * One physical read/check/write transaction for one named section. The caller supplies domain policy; copies expose
+ * current sibling facts without granting writes to them. No await, nested transaction, repair or legacy import.
+ */
+export declare function mutateTelegramRuntimeStateSection<T>(path: string, profile: string, section: TelegramRuntimeStateSection, mutate: (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>, options: TelegramRuntimeStatePublicationOptions): T;
 export declare function writeLocks(path: string, locks: Record<string, unknown>): void;
 export declare function parseTelegramLockEntry(value: unknown): TelegramLockEntry | undefined;
 export declare function isProcessAlive(pid: number): boolean;
-export declare function formatTelegramLockEntry(lock: TelegramLockEntry): string;
 export declare function createTelegramLockRuntime<TContext extends TelegramLockContext>(options?: TelegramLockRuntimeOptions): TelegramLockRuntime<TContext>;
 export declare function createTelegramLockOwnershipGuard<TContext extends TelegramLockContext>(lock: TelegramLockRuntime<TContext>): TelegramLockOwnershipGuard<TContext>;
 export declare function createTelegramDirectDeliveryOwnershipChecker<TContext extends TelegramLockContext>(deps: {
     lock: TelegramLockRuntime<TContext>;
     contextStore: TelegramLockContextStore<TContext>;
 }): () => boolean;
-export interface TelegramLockedPollingStartOptions {
+interface TelegramLockedPollingStartOptions {
     force?: boolean;
     forceFreshLeaderThread?: boolean;
     requestedThreadName?: string;
@@ -119,7 +202,7 @@ export interface TelegramLockedPollingStartOptions {
     };
     onAcquired?: () => Promise<void> | void;
 }
-export type TelegramLockedPollingStartResult = {
+type TelegramLockedPollingStartResult = {
     ok: true;
     message?: string;
     canTakeover?: false;
@@ -134,14 +217,18 @@ export interface TelegramLockedPollingRuntime<TContext extends TelegramLockConte
     stop: () => Promise<string>;
     suspend: () => Promise<void>;
     isSuspended: () => boolean;
+    /** Fence one owned polling generation; suspension, restart, conflict or lock loss revokes it. */
+    captureTransportAuthority: (ctx: TContext) => (() => boolean) | undefined;
     onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
     onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
     registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     restoreFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     stopFollowerRegistration?: () => void;
 }
-export interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext> {
+interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext> {
     lock: TelegramLockRuntime<TContext>;
+    /** Optimistically replaces a damaged shared runtime state before a non-election acquisition. */
+    resetDamagedState?: () => boolean;
     hasBotToken: () => boolean;
     getBotTokenDiagnostic?: () => string | undefined;
     canStartPolling?: (ctx: TContext) => boolean;
@@ -163,3 +250,4 @@ export interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockC
     ownershipRefreshMs?: number;
 }
 export declare function createTelegramLockedPollingRuntime<TContext extends TelegramLockContext>(deps: TelegramLockedPollingRuntimeDeps<TContext>): TelegramLockedPollingRuntime<TContext>;
+export {};