@llblab/pi-telegram 0.16.3 → 0.16.4

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.16.4: Follow-Up And Runtime Mode Hotfix
+
+- `[Runtime]` Feature-detect Pi `ctx.mode` and keep `print`/`json` runs passive by blocking polling start/resume in those modes. Impact: CLI/headless sessions can finish local work without inheriting Telegram polling, while `tui`/`rpc` and older Pi runtimes keep existing behavior.
+- `[Queue]` Forward queued Telegram prompts and unknown callback fallbacks to Pi with explicit `followUp` delivery semantics. Impact: Telegram input keeps the existing non-steering queue contract even when Pi's native streaming-message API requires an explicit busy-run policy.
+
 ## 0.16.3: Ownership And Shutdown Hotfix
 
 - `[Ownership]` Lock-gated proactive local/headless final-result push so only the current `/telegram-connect` owner can send non-Telegram agent-end replies to the paired chat, while accepted Telegram turns and queued work still finalize session-locally after polling ownership moves away. Impact: child/headless/non-owner instances no longer leak unrelated local results into Telegram.

package/docs/architecture.md

@@ -88,6 +88,7 @@ Telegram configuration lives in `~/.pi/agent/telegram.json`. Polling ownership l
 - `/telegram-connect` acquires or moves singleton polling ownership before polling starts.
 - `/telegram-disconnect` stops polling and releases ownership.
 - Session start resumes polling only when the existing lock already points at the current `pid`/`cwd`, or when a stale same-`cwd` lock can be safely replaced after process restart.
+- Pi `print`/`json` run modes stay passive: they do not start or resume Telegram polling even if a lock is present. Older Pi runtimes without `ctx.mode` keep the previous compatibility behavior.
 - Inherited child sessions that see the same `telegram.json` but do not own the `pid`/`cwd` lock must not auto-start polling or call `getUpdates` unless the operator force-takes ownership.
 - Session replacement suspends polling/watchers without releasing ownership so the next session-start hook in the same process can resume.
 - Live polling owners require explicit takeover confirmation.
@@ -140,7 +141,7 @@ Dispatch requires:
 
 A dispatched prompt remains queued until `agent_start` consumes it. This keeps the active Telegram turn bound for previews, attachments, aborts, and final replies.
 
-Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere.
+Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere. When a queued Telegram prompt is forwarded into Pi, it uses Pi's explicit `followUp` delivery option so Telegram input preserves the existing non-steering queue contract even if Pi is still settling active work.
 
 ### Controls And Menus
 

package/index.ts

@@ -386,6 +386,8 @@ export default function (pi: Pi.ExtensionAPI) {
   const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
     lock: lockRuntime,
     hasBotToken: configStore.hasBotToken,
+    canStartPolling: Pi.canStartPollingInExtensionContext,
+    formatStartBlockedMessage: Pi.formatPollingStartBlockedByRunMode,
     startPolling: pollingRuntime.start,
     stopPolling: pollingRuntime.stop,
     updateStatus,

package/lib/locks.ts

@@ -101,6 +101,8 @@ export interface TelegramLockedPollingRuntimeDeps<
 > {
   lock: TelegramLockRuntime<TContext>;
   hasBotToken: () => boolean;
+  canStartPolling?: (ctx: TContext) => boolean;
+  formatStartBlockedMessage?: (ctx: TContext) => string;
   startPolling: (ctx: TContext) => void | Promise<void>;
   stopPolling: () => Promise<void>;
   updateStatus: (ctx: TContext) => void;
@@ -309,10 +311,18 @@ export function createTelegramLockedPollingRuntime<
     }, ownershipCheckMs);
     ownershipInterval.unref?.();
   };
+  const canStartPolling = (ctx: TContext): boolean =>
+    deps.canStartPolling?.(ctx) ?? true;
+  const formatStartBlockedMessage = (ctx: TContext): string =>
+    deps.formatStartBlockedMessage?.(ctx) ??
+    "Telegram polling is unavailable in this π run mode.";
   return {
     start: async (ctx, options = {}) => {
       if (!deps.hasBotToken())
         return { ok: false, message: "Telegram bot is not configured." };
+      if (!canStartPolling(ctx)) {
+        return { ok: false, message: formatStartBlockedMessage(ctx) };
+      }
       const acquired = deps.lock.acquire(ctx, options);
       if (!acquired.ok) {
         return {
@@ -341,6 +351,7 @@ export function createTelegramLockedPollingRuntime<
     suspend: suspendPolling,
     onSessionStart: async (_event, ctx) => {
       if (!deps.hasBotToken()) return;
+      if (!canStartPolling(ctx)) return;
       const ownsCurrentLock = deps.lock.owns(ctx);
       const state = ownsCurrentLock ? undefined : deps.lock.getState();
       const canResumeStaleSameCwd =

package/lib/pi.ts

@@ -41,6 +41,44 @@ export interface PiSettingsManager {
 }
 
 export type PiSlashCommandInfo = SlashCommandInfo;
+export type PiRunMode = "tui" | "rpc" | "json" | "print";
+
+function isPiRunMode(value: unknown): value is PiRunMode {
+  return (
+    value === "tui" ||
+    value === "rpc" ||
+    value === "json" ||
+    value === "print"
+  );
+}
+
+export function getExtensionContextMode(ctx: unknown): PiRunMode | undefined {
+  const mode =
+    typeof ctx === "object" && ctx !== null
+      ? (ctx as { mode?: unknown }).mode
+      : undefined;
+  return isPiRunMode(mode) ? mode : undefined;
+}
+
+export function isExtensionContextPassiveRunMode(ctx: unknown): boolean {
+  const mode = getExtensionContextMode(ctx);
+  return mode === "print" || mode === "json";
+}
+
+export function canStartPollingInExtensionContext(ctx: unknown): boolean {
+  return !isExtensionContextPassiveRunMode(ctx);
+}
+
+export function formatPollingStartBlockedByRunMode(ctx: unknown): string {
+  const mode = getExtensionContextMode(ctx);
+  return mode
+    ? `Telegram polling is unavailable in π ${mode} mode. Use /telegram-connect from a long-lived π session.`
+    : "Telegram polling is unavailable in this π run mode.";
+}
+
+export type PiSendUserMessageOptions = NonNullable<
+  Parameters<ExtensionAPI["sendUserMessage"]>[1]
+>;
 
 export interface PiExtensionApiRuntimePorts {
   sendUserMessage: ExtensionAPI["sendUserMessage"];
@@ -63,7 +101,7 @@ export function createExtensionApiRuntimePorts(
   >,
 ): PiExtensionApiRuntimePorts {
   return {
-    sendUserMessage: (content) => api.sendUserMessage(content),
+    sendUserMessage: (content, options) => api.sendUserMessage(content, options),
     exec: (command, args, options) => api.exec(command, args, options),
     getCommands: () => api.getCommands(),
     getThinkingLevel: () => api.getThinkingLevel(),

package/lib/queue.ts

@@ -1820,6 +1820,14 @@ export function createTelegramDeferredQueueDispatchRuntime<TContext = unknown>(
 
 // --- Dispatch Runtime ---
 
+export interface TelegramPromptDeliveryOptions {
+  deliverAs: "followUp";
+}
+
+export const TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY = {
+  deliverAs: "followUp",
+} as const satisfies TelegramPromptDeliveryOptions;
+
 export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
   executeControlItem: (
     item: Extract<
@@ -1833,6 +1841,7 @@ export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
       TelegramQueueDispatchAction,
       { kind: "prompt" }
     >["item"]["content"],
+    options?: TelegramPromptDeliveryOptions,
   ) => void;
   onPromptDispatchFailure: (message: string) => void;
   onIdle: () => void;
@@ -1870,7 +1879,7 @@ export function executeTelegramQueueDispatchPlan<TContext = unknown>(
   }
   deps.onPromptDispatchStart(plan.item.chatId);
   try {
-    deps.sendUserMessage(plan.item.content);
+    deps.sendUserMessage(plan.item.content, TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY);
   } catch (error) {
     const message = getTelegramQueueErrorMessage(error);
     deps.onPromptDispatchFailure(message);

package/lib/routing.ts

@@ -122,7 +122,10 @@ export interface TelegramInboundRouteRuntimeDeps<
     ctx: TContext,
   ) => Promise<void>;
   setModel: (model: TModel) => Promise<boolean>;
-  sendUserMessage?: (message: string) => void;
+  sendUserMessage?: (
+    message: string,
+    options?: Queue.TelegramPromptDeliveryOptions,
+  ) => void;
   isIdle: (ctx: TContext) => boolean;
   hasPendingMessages: (ctx: TContext) => boolean;
   compact: (
@@ -315,7 +318,10 @@ export function createTelegramInboundRouteRuntime<
       callbackData &&
       !isTelegramOwnedCallbackData(callbackData)
     ) {
-      deps.sendUserMessage(`[callback] ${callbackData}`);
+      deps.sendUserMessage(
+        `[callback] ${callbackData}`,
+        Queue.TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY,
+      );
       await deps.answerCallbackQuery(query.id);
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "private": false,
   "publishConfig": {
     "access": "public"