@llblab/pi-kit 0.29.1 → 0.30.0

package/node_modules/@llblab/pi-telegram/dist/lib/lifecycle.d.ts

@@ -5,10 +5,9 @@
  * Transport authority, durable bindings, and queue custody remain with their owners.
  */
 import * as BusFollower from "./bus-follower.ts";
-import * as Queue from "./queue.ts";
 import type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AssistantMessageEvent, BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, InputEvent, MessageEndEvent, SessionBeforeCompactEvent, SessionCompactEvent, SessionCompactFailedEvent, SessionShutdownEvent, SessionStartEvent, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, UIPromptEndEvent, UIPromptStartEvent } from "./pi.ts";
-export declare function setResetTransportReplyDedup(fn: () => void): void;
-export declare function createAgentStartDedupHook(inner: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>, schedulePublication?: (task: () => Promise<void>) => void): (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>;
+import * as Queue from "./queue.ts";
+export declare function createAgentStartDedupHook(inner: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>, resetReplyDedup: () => void, schedulePublication?: (task: () => Promise<void>) => void): (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>;
 type TelegramBeforeAgentStartEvent = Omit<BeforeAgentStartEvent, "systemPrompt"> & {
     systemPrompt: string | string[];
 };
@@ -202,9 +201,6 @@ export interface TelegramMessageActivityTypingDeps<TContext> {
     recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
 }
 export declare function createTelegramMessageActivityTypingHooks<TContext extends ExtensionContext>(deps: TelegramMessageActivityTypingDeps<TContext>): Pick<TelegramLifecycleRegistrationDeps, "onMessageStart" | "onMessageUpdate">;
-export declare function createDedupAgentStartHook(dedup: {
-    reset(): void;
-}, inner: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>): (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>;
 export interface TelegramExtraLifecycleHooks {
     onSessionStart?: (event: SessionStartEvent, ctx: ExtensionContext) => Promise<void>;
     onSessionShutdown?: (event: SessionShutdownEvent, ctx: ExtensionContext) => Promise<void>;

package/node_modules/@llblab/pi-telegram/dist/lib/lifecycle.js

@@ -5,53 +5,58 @@
  * 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 { formatTelegramConnectionFailure } from "./status.js";
 import * as TextGroups from "./text-groups.js";
-let resetTransportReplyDedupFn;
-export function setResetTransportReplyDedup(fn) {
-    resetTransportReplyDedupFn = fn;
-}
-export function createAgentStartDedupHook(inner, schedulePublication) {
+export function createAgentStartDedupHook(inner, resetReplyDedup, schedulePublication) {
     return async (event, ctx) => {
-        const reset = resetTransportReplyDedupFn;
-        if (reset) {
-            // A new turn must not erase the anchor of a final still ahead in the FIFO.
-            if (schedulePublication)
-                schedulePublication(async () => { reset(); });
-            else
-                reset();
-        }
+        // 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] ??= {};
+    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() });
+            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 });
+            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);
+                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 (!(await deps.activateProfile(intent.profileName, isCurrent))) {
                         if (isCurrent())
                             ctx.ui.notify("Telegram profile unavailable. Run /telegram-setup.", "warning");
                         return;
@@ -65,11 +70,13 @@ export function createTelegramConnectionLifecycle(deps) {
                         deps.recordError(new Error(result.message ?? "Telegram resume connection failed."));
                         ctx.ui.notify(formatTelegramConnectionFailure(result.message), "warning");
                     }
-                })().catch((error) => {
+                })()
+                    .catch((error) => {
                     deps.recordError(error);
                     if (isCurrent())
                         ctx.ui.notify(formatTelegramConnectionFailure(error), "warning");
-                }).finally(() => deps.intent.finish(intent.id));
+                })
+                    .finally(() => deps.intent.finish(intent.id));
             };
         },
     };
@@ -97,23 +104,38 @@ export function createTelegramConnectionIntentRuntime(options = {}) {
             store.pending = undefined;
         },
         suspend(input) {
-            const intent = active ?? (input.connected
-                ? { id: randomUUID(), cwd: input.cwd, profileName: input.profileName }
-                : undefined);
+            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;
+            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 ||
+            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 };
+            active = {
+                id: randomUUID(),
+                cwd: handoff.cwd,
+                profileName: handoff.profileName,
+            };
             return { ...active };
         },
     };
@@ -258,10 +280,13 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             let preserveThread;
             if (event.reason === "quit") {
                 try {
-                    preserveThread = deps.services.prepareThreadPreservationOnQuit?.(isCurrent);
+                    preserveThread =
+                        deps.services.prepareThreadPreservationOnQuit?.(isCurrent);
                 }
                 catch (error) {
-                    deps.follower.recordRuntimeEvent("session", error, { phase: "preserve-thread-on-quit" });
+                    deps.follower.recordRuntimeEvent("session", error, {
+                        phase: "preserve-thread-on-quit",
+                    });
                 }
             }
             deps.services.guestPlaceholder?.stopAll();
@@ -280,7 +305,9 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
                 await preserveThread?.();
             }
             catch (error) {
-                deps.follower.recordRuntimeEvent("session", error, { phase: "preserve-thread-on-quit" });
+                deps.follower.recordRuntimeEvent("session", error, {
+                    phase: "preserve-thread-on-quit",
+                });
             }
         },
     };
@@ -316,6 +343,14 @@ export function createTelegramCompactionObserverRuntime(deps) {
         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);
     };
@@ -337,11 +372,7 @@ export function createTelegramCompactionObserverRuntime(deps) {
                 fallbackTimer = undefined;
                 if (deps.isContextActive && !deps.isContextActive(ctx))
                     return;
-                deps.setCompactionInProgress(false);
-                if (typingStartedByObserver)
-                    deps.stopTypingLoop?.();
-                typingStartedByObserver = false;
-                deps.updateStatus(ctx);
+                releaseCompactionPresence(ctx);
                 deps.recordRuntimeEvent?.("compact", new Error("Compaction observer timed out"));
                 // Observer expiry releases local presence, not Pi's eventual terminal result.
                 requestDispatch();
@@ -352,22 +383,14 @@ export function createTelegramCompactionObserverRuntime(deps) {
             if (deps.isContextActive && !deps.isContextActive(ctx))
                 return;
             clearFallbackTimer();
-            deps.setCompactionInProgress(false);
-            if (typingStartedByObserver)
-                deps.stopTypingLoop?.();
-            typingStartedByObserver = false;
-            deps.updateStatus(ctx);
+            releaseCompactionPresence(ctx);
             requestDispatch();
         },
         onSessionCompactFailed: (_event, ctx) => {
             if (deps.isContextActive && !deps.isContextActive(ctx))
                 return;
             clearFallbackTimer();
-            deps.setCompactionInProgress(false);
-            if (typingStartedByObserver)
-                deps.stopTypingLoop?.();
-            typingStartedByObserver = false;
-            deps.updateStatus(ctx);
+            releaseCompactionPresence(ctx);
             deps.onCompactionAbandoned?.();
             requestDispatch();
         },
@@ -402,12 +425,6 @@ export function createTelegramMessageActivityTypingHooks(deps) {
         onMessageUpdate: (event, ctx) => handleMessageActivity("update", event, ctx, deps.onMessageUpdate),
     };
 }
-export function createDedupAgentStartHook(dedup, inner) {
-    return async (event, ctx) => {
-        dedup.reset();
-        await inner(event, ctx);
-    };
-}
 export function appendTelegramLifecycleHooks(base, extra, isSessionActive) {
     return {
         onSessionStart: async (event, ctx) => {

package/node_modules/@llblab/pi-telegram/dist/lib/locks.d.ts

@@ -84,7 +84,7 @@ export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
     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>;
+    publishStateSectionIfOwned?: <T>(section: "workspace" | "runtime", mutate: TelegramRuntimeStateSectionReducer<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;
@@ -135,6 +135,31 @@ interface TelegramRenameRetryOptions {
     attempts?: number;
     retryDelayMs?: number;
 }
+export type TelegramPrivateFileFailure = "capacity" | "unsafe" | "changed";
+/** Typed private-file refusal; owners map the failure into their own error vocabulary. */
+export declare class TelegramPrivateFileError extends Error {
+    readonly failure: TelegramPrivateFileFailure;
+    constructor(failure: TelegramPrivateFileFailure, message: string);
+}
+/**
+ * Read flags for private runtime files. Where the platform offers them, no-follow and non-blocking opens refuse a
+ * swapped link or FIFO at open time. Windows has neither flag and no FIFOs in the file namespace; there the
+ * lstat-before/fstat-after identity binding every strict reader performs is the guard, so a link swapped in after
+ * inspection opens a different file and is refused as changed.
+ */
+export declare const TELEGRAM_STRICT_READ_FLAGS: number;
+/** POSIX owner and permission bits; Windows has no uid, so its ACL-protected agent directory carries privacy. */
+export declare function isTelegramOwnerPrivate(stat: {
+    uid: bigint;
+    mode: bigint;
+}): boolean;
+/**
+ * Read one owner-private, single-link, bounded regular file without following links. Absence returns undefined;
+ * an inode or metadata change between inspection and open refuses as `changed`.
+ */
+export declare function readTelegramPrivateFile(path: string, maxBytes: number): string | undefined;
+/** Atomically publish owner-private contents through a unique staging file; the rename consumes staging. */
+export declare function publishTelegramPrivateFile(path: string, temporaryBasePath: string, contents: string, label: string, onBoundary?: (boundary: "after-write-before-rename" | "after-rename") => void): void;
 /** Rename one Telegram runtime artifact with bounded Windows sharing retries. */
 export declare function renameTelegramPathWithRetry(sourcePath: string, destinationPath: string, options?: TelegramRenameRetryOptions): boolean;
 export interface TelegramFileTransactionOptions {
@@ -162,6 +187,8 @@ export declare function readTelegramRuntimeState(path: string): TelegramRuntimeS
  * 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;
+/** Pure section reducer: receives the stored section and its profile, returns the next section and result. */
+export type TelegramRuntimeStateSectionReducer<T> = (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>;
 export interface TelegramRuntimeStateMutation<T> {
     value: unknown;
     result: T;
@@ -183,10 +210,9 @@ export interface TelegramOwnedStatePublicationOptions extends TelegramRuntimeSta
  * 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 mutateTelegramRuntimeStateSection<T>(path: string, profile: string, section: TelegramRuntimeStateSection, mutate: TelegramRuntimeStateSectionReducer<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 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: {
@@ -215,6 +241,11 @@ type TelegramLockedPollingStartResult = {
 export interface TelegramLockedPollingRuntime<TContext extends TelegramLockContext> {
     start: (ctx: TContext, options?: TelegramLockedPollingStartOptions) => Promise<TelegramLockedPollingStartResult>;
     stop: () => Promise<string>;
+    /** Capture one disconnect attempt before cleanup awaits; a newer start revokes it. */
+    captureStop: () => {
+        isCurrent: () => boolean;
+        stop: () => Promise<string>;
+    };
     suspend: () => Promise<void>;
     isSuspended: () => boolean;
     /** Fence one owned polling generation; suspension, restart, conflict or lock loss revokes it. */