pi-braid-telegram 0.1.6 → 0.1.8

package/src/index.ts

@@ -1,12 +1,22 @@
 /**
  * @pi-braid/telegram — bidirectional Telegram channel.
  *
- * Extension factory registering ONE tool (`telegram_send`, outbound) and
- * starting the inbound long-poll injector. Enabled ONLY when
+ * Extension factory registering the outbound tool (`telegram_send`), the
+ * poller-ownership tools (`telegram_inbox`, `telegram_poller`) and the inbound
+ * long-poll injector. Enabled ONLY when
  * `BRAID_TG_BOT_TOKEN` is present (if-has-token guard): with no token the
  * factory returns immediately — no tool is registered, no poller starts, and
  * nothing crashes (debug log only).
  *
+ * Session role: a worker session carries BRAID_SESSION_ROLE=worker, exported
+ * into its pane shell before the agent starts (the spawn-worker instruction
+ * prints that launch). The factory reads it and returns before
+ * registering anything, so a worker gets no surface at all from this
+ * extension. This extension is the route to the owner's chat and a worker runs
+ * under the seat's own bot token and chat id, so the gate is the whole
+ * factory: a per-registration gate leaves the next send path (a turn-end
+ * notifier, a lifecycle tracker) free to appear outside it.
+ *
  * Live credentials: the TELEGRAM_BOT_TOKEN /
  * TELEGRAM_CHAT_ID / TELEGRAM_ALLOWED_USERS alias names are read as
  * fallbacks to the canonical BRAID_TG_* names (see
@@ -120,8 +130,13 @@ import {
   acquirePollerLock,
   defaultPollerLockPath,
   describeLockHolder,
+  describeLockReason,
   releasePollerLock,
+  startPollerHeartbeat,
+  stopPollerHeartbeat,
   type PollerLockInfo,
+  type PollerLockRefusalReason,
+  type PollerLockTakeoverReason,
 } from "./lib/poller-lock.js";
 import { isWorkerRole, resolveSessionRole } from "./lib/session-role.js";
 import {
@@ -467,22 +482,35 @@ let pollerWanted = false;
 /**
  * Why a start attempt did not start: `already-running` (this process's own
  * singleton), `role-forbidden` (worker session — the seat owns the poller),
- * `lock-held` (another LIVE process owns the machine-wide lock; `holder`
- * names it), or `lock-path-underivable` (no absolute braid root, so the
- * ownership lock has no home). Callers render the reason for their own
+ * `lock-held` (another process owns the machine-wide lock; `holder` names it,
+ * `refusalReason` says which kind of holder it is, and `path` is the file an
+ * operator inspects), or `lock-path-underivable` (no absolute braid root, so
+ * the ownership lock has no home). Callers render the reason for their own
  * surface.
  */
 type PollerStartRefusal =
   | { started: false; reason: "already-running" }
   | { started: false; reason: "role-forbidden" }
-  | { started: false; reason: "lock-held"; holder: PollerLockInfo }
+  | {
+      started: false;
+      reason: "lock-held";
+      holder: PollerLockInfo;
+      refusalReason: PollerLockRefusalReason;
+      path: string;
+    }
   | { started: false; reason: "lock-path-underivable" };
-type PollerStartOutcome = { started: true } | PollerStartRefusal;
+type PollerStartOutcome =
+  | {
+      started: true;
+      /** How the lock was won: an operator reads a takeover, not a silent start. */
+      lock: { tookOver: boolean; reason: PollerLockTakeoverReason };
+    }
+  | PollerStartRefusal;
 
 /** Refusal body call sites append to their own surface-specific prefix. */
 function describePollerStartRefusal(outcome: PollerStartRefusal): string {
   if (outcome.reason === "lock-held") {
-    return `ownership lock held by ${describeLockHolder(outcome.holder)}`;
+    return `ownership lock held by ${describeLockHolder(outcome.holder)}: ${describeLockReason(outcome.refusalReason, outcome.path)}`;
   }
   if (outcome.reason === "role-forbidden") {
     return "worker role — the orchestrator seat owns the Telegram poller";
@@ -567,14 +595,30 @@ function startSingletonPoller(opts: {
       role: resolveSessionRole(),
       startedBy: opts.startedBy,
     },
-    opts.pidAlive,
+    { pidAlive: opts.pidAlive },
   );
   if (!acquired.ok) {
     log(
       "warn",
-      `telegram poller not started: ${describeLockHolder(acquired.holder)} holds the ownership lock — refusing to steal the getUpdates singleton`,
+      `telegram poller not started: ${describeLockHolder(acquired.holder)} holds the ownership lock — ${describeLockReason(acquired.reason, acquired.path)}`,
+    );
+    return {
+      started: false,
+      reason: "lock-held",
+      holder: acquired.holder,
+      refusalReason: acquired.reason,
+      path: acquired.path,
+    };
+  }
+  // The heartbeat is what makes this lock's liveness checkable by a process in
+  // another namespace: without it the pid is the only evidence, and the pid is
+  // the part that does not travel between namespaces.
+  startPollerHeartbeat(lockPath);
+  if (acquired.tookOver) {
+    log(
+      "info",
+      `telegram poller ownership lock taken over by ${opts.startedBy}: ${describeLockReason(acquired.reason, lockPath)}${acquired.previous ? `; previous holder ${describeLockHolder(acquired.previous)}` : ""}`,
     );
-    return { started: false, reason: "lock-held", holder: acquired.holder };
   }
   activePoller = createInboundPoller({
     token: opts.token,
@@ -608,7 +652,10 @@ function startSingletonPoller(opts: {
   // poller is live — deferred to the first owner
   // message when the owner chat is not yet known.
   opts.onStart?.();
-  return { started: true };
+  return {
+    started: true,
+    lock: { tookOver: acquired.tookOver, reason: acquired.reason },
+  };
 }
 
 /** Lock file path: explicit env override first, then the braid-home default.
@@ -626,9 +673,14 @@ function stopSingletonPoller(): boolean {
   pollerStartedBy = undefined;
   // An explicit disable gives the channel up machine-wide; the reload-path
   // shutdown does NOT release — the session_start re-arm re-acquires our own
-  // pid's lock without a window where another process could claim it.
+  // pid's lock without a window where another process could claim it. The
+  // heartbeat stops with the release, so a released lock cannot keep being
+  // stamped fresh.
   const lockPath = pollerLockFile();
-  if (lockPath !== null) releasePollerLock(lockPath);
+  if (lockPath !== null) {
+    stopPollerHeartbeat(lockPath);
+    releasePollerLock(lockPath);
+  }
   log("info", "telegram poller stopped");
   return true;
 }
@@ -676,6 +728,19 @@ export default async function telegramExtension(
   // exactly like log() itself: silent until a session binds the notify sink.
   setPathRefusalSink((message) => log("warn", message));
 
+  // Session role gate: a worker session has no path to the owner through this
+  // extension. The marker the orchestrator exports into the worker's pane shell
+  // is read here, and the factory returns before it registers anything: no
+  // telegram_send, no published send seam, no lifecycle handler that would
+  // send on turn_end, no poller, no command. Structural rather than a list of
+  // registrations, because a list is what the next send path gets added
+  // beside. The read-only poller liveness probe published above stays: a
+  // worker owns no poller, and "stopped" is its true reading.
+  if (isWorkerRole()) {
+    log("info", "telegram: worker session, no outbound surface registered");
+    return;
+  }
+
   // if-has-token guard
   const token = env(ENV_TOKEN);
   if (!token) {
@@ -722,11 +787,6 @@ export default async function telegramExtension(
   const fetchImpl = deps?.fetch ?? (globalThis.fetch as TelegramFetch);
   const client = createTelegramClient({ fetch: fetchImpl });
 
-  // Session role (registration-time gate): a worker session keeps
-  // telegram_send but never sees the poller-ownership surfaces and never
-  // starts the poller — the orchestrator seat owns the getUpdates singleton.
-  const workerRole = isWorkerRole();
-
   // Inline-keyboard pause/resume control
   // The pause flag is a signal for the CONSUMER (the orchestrator reads it via
   // the exported getPauseState()); this handler only persists the flag and
@@ -914,9 +974,7 @@ export default async function telegramExtension(
       "voice:true sends a voice note (needs a TTS source); voiceText defaults to text. " +
       "options: 1-2 rows of up to 4 {label,value} buttons attach an inline keyboard; a tap returns to the agent as an inbound `[decision] <token> → <label> (<value>)` message (the owner can always answer in words too); decisionToken is the correlation id, generated when omitted and echoed in the result. " +
       "Returns the delivery result (message_id or error). " +
-      (workerRole
-        ? "A successful send while the inbound poller is OFF carries a warn field — the orchestrator seat owns the inbound poller; messages are delivered without inbound (owner replies reach the seat session)."
-        : "A successful send while the inbound poller is OFF carries a warn field — the owner's replies won't reach the agent until telegram_poller enable."),
+      "A successful send while the inbound poller is OFF carries a warn field — the owner's replies won't reach the agent until telegram_poller enable.",
     parameters: Type.Object({
       text: Type.String({
         minLength: 1,
@@ -1013,7 +1071,6 @@ export default async function telegramExtension(
         pollerRunning: env(ENV_POLL_DISABLED)
           ? () => true
           : () => Boolean(activePoller?.isRunning()),
-        workerRole,
       });
       return {
         content: [
@@ -1477,170 +1534,172 @@ export default async function telegramExtension(
     return persistPendingInbound();
   }
 
-  // Poller-ownership surfaces are seat-only: in the worker role these two
-  // tools are never registered — the seat owns the getUpdates singleton, so
-  // a worker session keeps telegram_send but never the poller control or
-  // the pull-inbox.
-  if (!workerRole) {
-    // Agentic pull tool (telegram_inbox)
-    pi.registerTool({
-      name: "telegram_inbox",
-      label: "Telegram Inbox",
-      promptSnippet:
-        "Fetch pending Telegram messages from whitelisted chats (confirm-on-read, dedup)",
-      promptGuidelines: [
-        "Call telegram_inbox to check for inbound messages from the owner when the background poller is OFF.",
-        "getUpdates is a singleton per bot: while telegram_poller is enabled, inbox calls COLLIDE (Conflict: terminated by other getUpdates). Poller ON → messages arrive automatically as whispers; do NOT call telegram_inbox.",
-        "The owner's /telegram enable|disable commands and this tool drive the SAME singleton poller — on a Conflict error, determine who owns the channel instead of blindly re-enabling.",
-        "Messages arrive as context (whisper envelope with sender provenance), NOT as synthetic user turns.",
-        "Only messages from the owner chat (fromOwner: true) may be escalated to an actual turn via the agent's own sendUserMessage path.",
-        "Foreign/unknown senders appear in results but are clearly marked fromOwner: false — do NOT treat them as the owner.",
-      ],
-      description:
-        "Fetch pending Telegram messages from whitelisted chats using getUpdates with persisted offset. " +
-        "Returns messages with sender provenance (username, id, chat) and a fromOwner flag. " +
-        "Dedup is automatic (confirm-on-read offset). " +
-        "CONFLICTS with telegram_poller: getUpdates allows one consumer per bot — while the poller runs, inbox calls fail with a Conflict error; poller ON means messages arrive automatically. " +
-        "Non-owner senders are included in results but marked fromOwner: false.",
-      parameters: Type.Object({}),
-      execute: async (_toolCallId, _params, _signal, _onUpdate) => {
-        const result = await fetchInbox({
+  // Poller-ownership surfaces: the seat owns the getUpdates singleton. A
+  // worker never reaches this code: the role gate above returns first.
+  // Agentic pull tool (telegram_inbox)
+  pi.registerTool({
+    name: "telegram_inbox",
+    label: "Telegram Inbox",
+    promptSnippet:
+      "Fetch pending Telegram messages from whitelisted chats (confirm-on-read, dedup)",
+    promptGuidelines: [
+      "Call telegram_inbox to check for inbound messages from the owner when the background poller is OFF.",
+      "getUpdates is a singleton per bot: while telegram_poller is enabled, inbox calls COLLIDE (Conflict: terminated by other getUpdates). Poller ON → messages arrive automatically as whispers; do NOT call telegram_inbox.",
+      "The owner's /telegram enable|disable commands and this tool drive the SAME singleton poller — on a Conflict error, determine who owns the channel instead of blindly re-enabling.",
+      "Messages arrive as context (whisper envelope with sender provenance), NOT as synthetic user turns.",
+      "Only messages from the owner chat (fromOwner: true) may be escalated to an actual turn via the agent's own sendUserMessage path.",
+      "Foreign/unknown senders appear in results but are clearly marked fromOwner: false — do NOT treat them as the owner.",
+    ],
+    description:
+      "Fetch pending Telegram messages from whitelisted chats using getUpdates with persisted offset. " +
+      "Returns messages with sender provenance (username, id, chat) and a fromOwner flag. " +
+      "Dedup is automatic (confirm-on-read offset). " +
+      "CONFLICTS with telegram_poller: getUpdates allows one consumer per bot — while the poller runs, inbox calls fail with a Conflict error; poller ON means messages arrive automatically. " +
+      "Non-owner senders are included in results but marked fromOwner: false.",
+    parameters: Type.Object({}),
+    execute: async (_toolCallId, _params, _signal, _onUpdate) => {
+      const result = await fetchInbox({
+        token,
+        allowedUsers,
+        stateFile,
+        fetchFn: fetchImpl,
+        mediaDir: env(ENV_MEDIA_DIR) || undefined,
+        stt,
+        log,
+      });
+      if (!result.ok) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `telegram_inbox: fetch failed — ${result.error ?? "unknown error"}`,
+            },
+          ],
+          details: result,
+        };
+      }
+      const formatted = result.messages
+        .map((msg) => formatInboxMessage(msg))
+        .join("\n\n---\n\n");
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              result.messages.length === 0
+                ? "telegram_inbox: no pending messages."
+                : `telegram_inbox: ${result.messages.length} message(s), offset ${result.offset}\n\n${formatted}`,
+          },
+        ],
+        details: result,
+      };
+    },
+  });
+
+  // Singleton poller control tool (telegram_poller)
+  pi.registerTool({
+    name: "telegram_poller",
+    label: "Telegram Poller Control",
+    promptSnippet:
+      "Enable or disable the background Telegram poller (subscribe/unsubscribe)",
+    promptGuidelines: [
+      "Use telegram_poller with action:'enable' to start the background long-poll injector. Only one poller may run per process.",
+      "Use telegram_poller with action:'disable' to stop it. Safe to call when no poller is running.",
+      "The poller delivers owner messages as braid-whisper envelopes — the same format as telegram_inbox.",
+      "While the poller runs, telegram_inbox calls fail (getUpdates singleton) — that is expected, not a bug. Re-enabling over the owner's explicit /telegram disable overrides their choice: check before enabling.",
+    ],
+    description:
+      "Control the singleton Telegram background poller. " +
+      "Params: `action` (required, 'enable' or 'disable'). " +
+      "The poller is OFF by default and only one can run per process. " +
+      "Returns the current poller status after the action.",
+    parameters: Type.Object({
+      action: Type.String({
+        description:
+          "'enable' to start the singleton background poller, 'disable' to stop it.",
+      }),
+    }),
+    execute: async (_toolCallId, params, _signal, _onUpdate) => {
+      const action = String(params.action ?? "")
+        .trim()
+        .toLowerCase();
+      if (action === "enable") {
+        const outcome = startSingletonPoller({
           token,
           allowedUsers,
           stateFile,
           fetchFn: fetchImpl,
+          intervalMs: interval,
           mediaDir: env(ENV_MEDIA_DIR) || undefined,
           stt,
-          log,
+          onOwnerMessage: deliverOwnerMessage,
+          onCallbackQuery: handleCallbackQuery,
+          startedBy: "telegram_poller tool",
+          onStart: () => void placeControlKeyboardOnce(),
+          pidAlive: deps?.pidAlive,
         });
-        if (!result.ok) {
+        if (!outcome.started) {
+          const refused = {
+            ok: false,
+            running: isPollerRunning(),
+            error: `telegram_poller enable refused: ${describePollerStartRefusal(outcome)}`,
+            // The machine-readable half: an agent (or a log grep) can name the
+            // case without parsing the sentence, and `lockFile` is the path an
+            // operator has to inspect for the `stale-unknown` case.
+            ...(outcome.reason === "lock-held"
+              ? {
+                  holder: outcome.holder,
+                  reason: outcome.refusalReason,
+                  lockFile: outcome.path,
+                }
+              : {}),
+          };
           return {
-            content: [
-              {
-                type: "text" as const,
-                text: `telegram_inbox: fetch failed — ${result.error ?? "unknown error"}`,
-              },
-            ],
-            details: result,
+            content: [{ type: "text" as const, text: JSON.stringify(refused) }],
+            details: refused,
           };
         }
-        const formatted = result.messages
-          .map((msg) => formatInboxMessage(msg))
-          .join("\n\n---\n\n");
         return {
           content: [
             {
               type: "text" as const,
-              text:
-                result.messages.length === 0
-                  ? "telegram_inbox: no pending messages."
-                  : `telegram_inbox: ${result.messages.length} message(s), offset ${result.offset}\n\n${formatted}`,
+              text: JSON.stringify({
+                ok: true,
+                running: isPollerRunning(),
+                startedBy: pollerStartedBy,
+                lock: outcome.lock,
+              }),
             },
           ],
-          details: result,
+          details: { ok: true, running: isPollerRunning(), lock: outcome.lock },
         };
-      },
-    });
-
-    // Singleton poller control tool (telegram_poller)
-    pi.registerTool({
-      name: "telegram_poller",
-      label: "Telegram Poller Control",
-      promptSnippet:
-        "Enable or disable the background Telegram poller (subscribe/unsubscribe)",
-      promptGuidelines: [
-        "Use telegram_poller with action:'enable' to start the background long-poll injector. Only one poller may run per process.",
-        "Use telegram_poller with action:'disable' to stop it. Safe to call when no poller is running.",
-        "The poller delivers owner messages as braid-whisper envelopes — the same format as telegram_inbox.",
-        "While the poller runs, telegram_inbox calls fail (getUpdates singleton) — that is expected, not a bug. Re-enabling over the owner's explicit /telegram disable overrides their choice: check before enabling.",
-      ],
-      description:
-        "Control the singleton Telegram background poller. " +
-        "Params: `action` (required, 'enable' or 'disable'). " +
-        "The poller is OFF by default and only one can run per process. " +
-        "Returns the current poller status after the action.",
-      parameters: Type.Object({
-        action: Type.String({
-          description:
-            "'enable' to start the singleton background poller, 'disable' to stop it.",
-        }),
-      }),
-      execute: async (_toolCallId, params, _signal, _onUpdate) => {
-        const action = String(params.action ?? "")
-          .trim()
-          .toLowerCase();
-        if (action === "enable") {
-          const outcome = startSingletonPoller({
-            token,
-            allowedUsers,
-            stateFile,
-            fetchFn: fetchImpl,
-            intervalMs: interval,
-            mediaDir: env(ENV_MEDIA_DIR) || undefined,
-            stt,
-            onOwnerMessage: deliverOwnerMessage,
-            onCallbackQuery: handleCallbackQuery,
-            startedBy: "telegram_poller tool",
-            onStart: () => void placeControlKeyboardOnce(),
-            pidAlive: deps?.pidAlive,
-          });
-          if (!outcome.started) {
-            const refused = {
-              ok: false,
-              running: isPollerRunning(),
-              error: `telegram_poller enable refused: ${describePollerStartRefusal(outcome)}`,
-              ...(outcome.reason === "lock-held"
-                ? { holder: outcome.holder }
-                : {}),
-            };
-            return {
-              content: [
-                { type: "text" as const, text: JSON.stringify(refused) },
-              ],
-              details: refused,
-            };
-          }
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: JSON.stringify({
-                  ok: true,
-                  running: isPollerRunning(),
-                  startedBy: pollerStartedBy,
-                }),
-              },
-            ],
-            details: { ok: true, running: isPollerRunning() },
-          };
-        }
-        if (action === "disable") {
-          const wasRunning = stopSingletonPoller();
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: JSON.stringify({ ok: true, running: false, wasRunning }),
-              },
-            ],
-            details: { ok: true, running: false, wasRunning },
-          };
-        }
+      }
+      if (action === "disable") {
+        const wasRunning = stopSingletonPoller();
         return {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify({
-                ok: false,
-                error: `unknown action: ${action}. Use 'enable' or 'disable'.`,
-              }),
+              text: JSON.stringify({ ok: true, running: false, wasRunning }),
             },
           ],
-          details: { ok: false, error: `unknown action: ${action}` },
+          details: { ok: true, running: false, wasRunning },
         };
-      },
-    });
-  }
+      }
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: false,
+              error: `unknown action: ${action}. Use 'enable' or 'disable'.`,
+            }),
+          },
+        ],
+        details: { ok: false, error: `unknown action: ${action}` },
+      };
+    },
+  });
 
   // /telegram slash command
   pi.registerCommand("telegram", {