@llblab/pi-telegram 0.52.2 → 0.53.0

package/lib/paths.ts

@@ -2,16 +2,20 @@
  * Telegram bridge path resolution for Pi-compatible runtimes
  * Zones: telemetry paths, filesystem, runtime identity
  * Owns agent-dir detection and extension-local path derivation
- *
- * This domain is path-only: it resolves directories and file paths from
- * environment and runtime identity. Its only filesystem read canonicalizes the
- * existing agent-dir prefix; it does not read config, manage state, or import
- * broader Telegram domains.
  */
+
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 
 export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
 
@@ -50,11 +54,22 @@ export function resolveAgentDir(
  * Reject aliases; never repair relative historical references or redirect storage.
  * Equality proves spelling only, not file identity, consumer closure or migration readiness.
  */
-export function requireTelegramStoragePathReference(path: string, expectedPath: string): string {
-  if (typeof path !== "string" || typeof expectedPath !== "string" ||
-      !isAbsolute(path) || resolve(path) !== path ||
-      !isAbsolute(expectedPath) || resolve(expectedPath) !== expectedPath || path !== expectedPath) {
-    throw new Error("Telegram storage reference does not match its approved absolute path.");
+export function requireTelegramStoragePathReference(
+  path: string,
+  expectedPath: string,
+): string {
+  if (
+    typeof path !== "string" ||
+    typeof expectedPath !== "string" ||
+    !isAbsolute(path) ||
+    resolve(path) !== path ||
+    !isAbsolute(expectedPath) ||
+    resolve(expectedPath) !== expectedPath ||
+    path !== expectedPath
+  ) {
+    throw new Error(
+      "Telegram storage reference does not match its approved absolute path.",
+    );
   }
   return path;
 }
@@ -67,17 +82,26 @@ export function resolveTelegramConfigPath(): string {
 /**
  * Resolve symlinks in the longest existing prefix of `path` and keep the missing suffix. Strict journal reads require
  * canonical anchors, so a symlinked agent directory (for example macOS `/var` → `/private/var`) must not leak in.
- * Relative input is returned unchanged so callers' exact-absolute-path guards still reject it. Windows keeps its
- * spelling: strict journal reads are POSIX-only there, and resolving a drive-less root would add a drive letter.
+ * Relative input is returned unchanged so callers' exact-absolute-path guards still reject it. On Windows only
+ * drive-letter and UNC paths resolve; resolving a drive-less root would add the current drive.
  */
 function canonicalizeExistingPrefix(path: string): string {
-  if (!isAbsolute(path) || process.platform === "win32") return path;
+  if (
+    !isAbsolute(path) ||
+    (process.platform === "win32" && !/^(?:[a-zA-Z]:[\\/]|\\\\)/u.test(path))
+  )
+    return path;
   const absolute = resolve(path);
   const missing: string[] = [];
   for (let current = absolute; ; current = dirname(current)) {
-    try { return join(realpathSync(current), ...missing.reverse()); }
-    catch (error) {
-      if ((error as { code?: unknown }).code !== "ENOENT" || dirname(current) === current) return absolute;
+    try {
+      return join(realpathSync(current), ...missing.reverse());
+    } catch (error) {
+      if (
+        (error as { code?: unknown }).code !== "ENOENT" ||
+        dirname(current) === current
+      )
+        return absolute;
       missing.push(basename(current));
     }
   }
@@ -89,12 +113,16 @@ export function resolveTelegramTempDir(agentDir = resolveAgentDir()): string {
 }
 
 /** Consolidated-root service artifacts (transaction guards, staging and IPC), never session custody. */
-export function resolveTelegramRuntimeDir(agentDir = resolveAgentDir()): string {
+export function resolveTelegramRuntimeDir(
+  agentDir = resolveAgentDir(),
+): string {
   return join(resolveTelegramTempDir(agentDir), "runtime");
 }
 
 /** Rotated shared runtime event segments, outside the persistent root-file census. */
-export function resolveTelegramRuntimeLogsDir(agentDir = resolveAgentDir()): string {
+export function resolveTelegramRuntimeLogsDir(
+  agentDir = resolveAgentDir(),
+): string {
   return join(resolveTelegramTempDir(agentDir), "logs");
 }
 
@@ -104,12 +132,16 @@ export function resolveTelegramStatePath(agentDir = resolveAgentDir()): string {
 }
 
 /** Flat attachment scratch directory (<agentDir>/tmp/pi-telegram/attachments). */
-export function resolveTelegramAttachmentsDir(agentDir = resolveAgentDir()): string {
+export function resolveTelegramAttachmentsDir(
+  agentDir = resolveAgentDir(),
+): string {
   return join(resolveTelegramTempDir(agentDir), "attachments");
 }
 
 /** Read-only pre-0.52.0 ownership file, consulted only to refuse a second poller beside a live older leader. */
-export function resolveLegacyTelegramOwnersPath(agentDir = resolveAgentDir()): string {
+export function resolveLegacyTelegramOwnersPath(
+  agentDir = resolveAgentDir(),
+): string {
   return join(agentDir, "tmp", "telegram", "owners.json");
 }
 
@@ -173,21 +205,38 @@ export function resolveTelegramServiceJournalStorage(
 ): { path: string; runtimeDir: string } {
   const profileHash = createHash("sha256").update(profileName).digest("hex");
   return {
-    path: join(resolveTelegramTempDir(agentDir), "journals", `${kind}.${profileHash}.json`),
+    path: join(
+      resolveTelegramTempDir(agentDir),
+      "journals",
+      `${kind}.${profileHash}.json`,
+    ),
     runtimeDir: resolveTelegramRuntimeDir(agentDir),
   };
 }
 
 /** Bind one non-session journal to its exact colocated-root service namespace, never a format fallback. */
-export function getTelegramJournalPublicationPaths(path: string, runtimeDir?: string): {
+export function getTelegramJournalPublicationPaths(
+  path: string,
+  runtimeDir?: string,
+): {
   transactionPath: string;
   temporaryBasePath: string;
 } {
-  if (runtimeDir === undefined) return { transactionPath: `${path}.transaction`, temporaryBasePath: path };
+  if (runtimeDir === undefined)
+    return { transactionPath: `${path}.transaction`, temporaryBasePath: path };
   requireTelegramStoragePathReference(path, resolve(path));
-  requireTelegramStoragePathReference(runtimeDir, join(dirname(dirname(path)), "runtime"));
-  if (basename(dirname(path)) !== "journals") throw new Error("Telegram service journal must use its journals namespace.");
-  return { transactionPath: join(runtimeDir, `${basename(path)}.transaction`), temporaryBasePath: join(runtimeDir, basename(path)) };
+  requireTelegramStoragePathReference(
+    runtimeDir,
+    join(dirname(dirname(path)), "runtime"),
+  );
+  if (basename(dirname(path)) !== "journals")
+    throw new Error(
+      "Telegram service journal must use its journals namespace.",
+    );
+  return {
+    transactionPath: join(runtimeDir, `${basename(path)}.transaction`),
+    temporaryBasePath: join(runtimeDir, basename(path)),
+  };
 }
 
 /** Durable inactive Thread cleanup work-set journal. */
@@ -195,7 +244,12 @@ export function resolveTelegramThreadCleanupWorkPath(
   agentDir = resolveAgentDir(),
   profileName?: string,
 ): string {
-  return resolveTelegramProfileTempFilePath("thread-cleanup", "json", agentDir, profileName);
+  return resolveTelegramProfileTempFilePath(
+    "thread-cleanup",
+    "json",
+    agentDir,
+    profileName,
+  );
 }
 
 /** Durable agent-authored channel post journal. */
@@ -203,7 +257,12 @@ export function resolveTelegramChannelPostJournalPath(
   agentDir = resolveAgentDir(),
   profileName?: string,
 ): string {
-  return resolveTelegramProfileTempFilePath("channel-posts", "json", agentDir, profileName);
+  return resolveTelegramProfileTempFilePath(
+    "channel-posts",
+    "json",
+    agentDir,
+    profileName,
+  );
 }
 
 /** Durable inbound update journal (<agentDir>/tmp/pi-telegram/inbox[.<profile>].json). */
@@ -248,7 +307,8 @@ export function resolveTelegramFollowerJournalPath(
 }
 
 const TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH = 200;
-const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/u;
+const WINDOWS_RESERVED_NAME =
+  /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/u;
 
 /**
  * Directory name for a session id. Lowercase letters, digits, `_`, `-` and inner `.` stay verbatim, so every real
@@ -256,22 +316,33 @@ const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/
  * filesystems never merge two sessions; a leading or trailing dot and Windows reserved names are encoded so the name
  * can never be `.`/`..`, hidden, or a device. The encoding is reversible; an empty or over-long result is refused.
  */
-export function encodeTelegramSessionDirectoryName(sessionId: string): string | undefined {
+export function encodeTelegramSessionDirectoryName(
+  sessionId: string,
+): string | undefined {
   if (typeof sessionId !== "string" || sessionId.length === 0) return undefined;
   const bytes = Buffer.from(sessionId, "utf8");
   if (bytes.toString("utf8") !== sessionId) return undefined;
   let name = "";
   bytes.forEach((byte, index) => {
     const char = String.fromCharCode(byte);
-    const safe = /[a-z0-9_-]/u.test(char) || (char === "." && index > 0 && index < bytes.length - 1);
-    name += safe ? char : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    const safe =
+      /[a-z0-9_-]/u.test(char) ||
+      (char === "." && index > 0 && index < bytes.length - 1);
+    name += safe
+      ? char
+      : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
   });
-  if (WINDOWS_RESERVED_NAME.test(name)) name = `%${name.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}${name.slice(1)}`;
-  return name.length <= TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH ? name : undefined;
+  if (WINDOWS_RESERVED_NAME.test(name))
+    name = `%${name.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}${name.slice(1)}`;
+  return name.length <= TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH
+    ? name
+    : undefined;
 }
 
 /** Inverse of `encodeTelegramSessionDirectoryName`; undefined unless the name is exactly canonical. */
-export function decodeTelegramSessionDirectoryName(name: string): string | undefined {
+export function decodeTelegramSessionDirectoryName(
+  name: string,
+): string | undefined {
   if (!/^[a-z0-9_.%A-F-]+$/u.test(name)) return undefined;
   const bytes: number[] = [];
   for (let index = 0; index < name.length; index++) {
@@ -283,25 +354,39 @@ export function decodeTelegramSessionDirectoryName(name: string): string | undef
     } else bytes.push(name.charCodeAt(index));
   }
   const decoded = Buffer.from(bytes).toString("utf8");
-  return encodeTelegramSessionDirectoryName(decoded) === name ? decoded : undefined;
+  return encodeTelegramSessionDirectoryName(decoded) === name
+    ? decoded
+    : undefined;
 }
 
 /** Root of every session folder (<agentDir>/tmp/pi-telegram/sessions). */
-export function resolveTelegramSessionsDir(agentDir = resolveAgentDir()): string {
+export function resolveTelegramSessionsDir(
+  agentDir = resolveAgentDir(),
+): string {
   return join(resolveTelegramTempDir(agentDir), "sessions");
 }
 
 /** One session's folder (<agentDir>/tmp/pi-telegram/sessions/<session id>). */
-export function resolveTelegramSessionDir(sessionId: string, agentDir = resolveAgentDir()): string {
+export function resolveTelegramSessionDir(
+  sessionId: string,
+  agentDir = resolveAgentDir(),
+): string {
   const name = encodeTelegramSessionDirectoryName(sessionId);
-  if (!name) throw new Error("Telegram session directory requires a usable session id.");
+  if (!name)
+    throw new Error("Telegram session directory requires a usable session id.");
   return join(resolveTelegramSessionsDir(agentDir), name);
 }
 
 /** Hash naming one recipient incarnation inside its session folder; unchanged from the former follower inbox. */
-export function getTelegramRecipientJournalHash(recipientBindingKey: string): string {
-  if (!recipientBindingKey) throw new Error("Telegram session journal binding key is required.");
-  return createHash("sha256").update(recipientBindingKey).digest("hex").slice(0, 16);
+export function getTelegramRecipientJournalHash(
+  recipientBindingKey: string,
+): string {
+  if (!recipientBindingKey)
+    throw new Error("Telegram session journal binding key is required.");
+  return createHash("sha256")
+    .update(recipientBindingKey)
+    .digest("hex")
+    .slice(0, 16);
 }
 
 /** Durable per-session journal (`sessions/<session id>/journal.<hash>[.<profile>].json`); the name never reveals a role. */
@@ -323,22 +408,36 @@ export function resolveTelegramSessionPollingJournalPath(
   agentDir = resolveAgentDir(),
   profileName?: string,
 ): string {
-  return join(resolveTelegramSessionDir(sessionId, agentDir), `inbox${getTelegramProfilePathSuffix(profileName)}.json`);
+  return join(
+    resolveTelegramSessionDir(sessionId, agentDir),
+    `inbox${getTelegramProfilePathSuffix(profileName)}.json`,
+  );
 }
 
 /** Accept only a canonical `sessions/<id>/inbox[.<profile>].json` beneath this agent's runtime. */
-export function isTelegramSessionPollingJournalPath(path: string, agentDir = resolveAgentDir()): boolean {
+export function isTelegramSessionPollingJournalPath(
+  path: string,
+  agentDir = resolveAgentDir(),
+): boolean {
   const parts = relative(resolveTelegramSessionsDir(agentDir), path).split(sep);
-  return isAbsolute(path) && parts.length === 2 && decodeTelegramSessionDirectoryName(parts[0]!) !== undefined &&
-    /^inbox(?:\.[a-zA-Z0-9._-]+)?\.json$/u.test(parts[1]!);
+  return (
+    isAbsolute(path) &&
+    parts.length === 2 &&
+    decodeTelegramSessionDirectoryName(parts[0]!) !== undefined &&
+    /^inbox(?:\.[a-zA-Z0-9._-]+)?\.json$/u.test(parts[1]!)
+  );
 }
 
 /** Runtime event log (<agentDir>/tmp/pi-telegram/logs.jsonl). */
-export function resolveTelegramRuntimeLogPath(agentDir = resolveAgentDir()): string {
+export function resolveTelegramRuntimeLogPath(
+  agentDir = resolveAgentDir(),
+): string {
   return resolveTelegramProfileTempFilePath("logs", "jsonl", agentDir);
 }
 
 /** Bounded previous shared log segment below `logs/`. */
-export function resolveTelegramPreviousSharedRuntimeLogPath(agentDir = resolveAgentDir()): string {
+export function resolveTelegramPreviousSharedRuntimeLogPath(
+  agentDir = resolveAgentDir(),
+): string {
   return join(resolveTelegramRuntimeLogsDir(agentDir), "logs._prev.jsonl");
 }

package/lib/pi.ts

@@ -93,6 +93,15 @@ function isPiRunMode(value: unknown): value is PiRunMode {
   );
 }
 
+/** Pi rejects a context captured before session replacement with a stale-context error; this is not a domain failure. */
+export function isPiStaleContextError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error.message.includes("stale after session") ||
+      error.message.includes("stale ctx"))
+  );
+}
+
 export function getExtensionContextMode(ctx: unknown): PiRunMode | undefined {
   const mode =
     typeof ctx === "object" && ctx !== null
@@ -184,10 +193,15 @@ type HostSettingsManager = {
 
 function readEnabledModels(value: unknown): string[] | undefined {
   if (value === undefined) return undefined;
-  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+  if (
+    Array.isArray(value) &&
+    value.every((entry) => typeof entry === "string")
+  ) {
     return [...value];
   }
-  throw new TypeError("Host settings enabledModels must be a string array or undefined.");
+  throw new TypeError(
+    "Host settings enabledModels must be a string array or undefined.",
+  );
 }
 
 export function normalizeSettingsManager(manager: unknown): PiSettingsManager {
@@ -198,18 +212,20 @@ export function normalizeSettingsManager(manager: unknown): PiSettingsManager {
   if (typeof host.flush !== "function") {
     throw new TypeError("Host settings manager must provide flush().");
   }
-  const read = typeof host.getEnabledModels === "function"
-    ? () => host.getEnabledModels!.call(host)
-    : typeof host.get === "function"
-      ? () => host.get!.call(host, "enabledModels")
-      : undefined;
-  const write = typeof host.setEnabledModels === "function"
-    ? (patterns: string[] | undefined) =>
-        host.setEnabledModels!.call(host, patterns)
-    : typeof host.set === "function"
+  const read =
+    typeof host.getEnabledModels === "function"
+      ? () => host.getEnabledModels!.call(host)
+      : typeof host.get === "function"
+        ? () => host.get!.call(host, "enabledModels")
+        : undefined;
+  const write =
+    typeof host.setEnabledModels === "function"
       ? (patterns: string[] | undefined) =>
-          host.set!.call(host, "enabledModels", patterns ?? [])
-      : undefined;
+          host.setEnabledModels!.call(host, patterns)
+      : typeof host.set === "function"
+        ? (patterns: string[] | undefined) =>
+            host.set!.call(host, "enabledModels", patterns ?? [])
+        : undefined;
   if (!read || !write) {
     throw new TypeError(
       "Host settings manager must provide enabled-model read and write capabilities.",
@@ -264,8 +280,12 @@ export function getExtensionContextCwd(ctx: ExtensionContext): string {
 }
 
 export function getExtensionContextSessionId(ctx: ExtensionContext): string;
-export function getExtensionContextSessionId(ctx: ExtensionContext | undefined): string | undefined;
-export function getExtensionContextSessionId(ctx: ExtensionContext | undefined): string | undefined {
+export function getExtensionContextSessionId(
+  ctx: ExtensionContext | undefined,
+): string | undefined;
+export function getExtensionContextSessionId(
+  ctx: ExtensionContext | undefined,
+): string | undefined {
   // Minimal hosts and stale contexts may omit a session manager; absence is not an invented ID.
   return ctx?.sessionManager?.getSessionId?.();
 }