@llblab/pi-telegram 0.27.12 → 0.29.0

package/lib/prompts.ts

@@ -4,19 +4,16 @@
  * Owns Telegram-specific system prompt suffixes injected into pi agent turns
  */
 
-import { Type } from "@sinclair/typebox";
-
-import { getTelegramDiagnosticsDisplayPaths } from "./paths.ts";
-import type { BeforeAgentStartEvent, ExtensionAPI } from "./pi.ts";
+import type { BeforeAgentStartEvent } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram bridge available. Do not use it from local/TUI prompts unless explicitly asked.`;
+Telegram bridge available. Load the \`telegram-bridge\` Skill for Telegram delivery, actions, Threaded Mode, or diagnosis. Do not use Telegram from local/TUI prompts unless explicitly asked.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram turn note: Call \`telegram_help\` if you need the pi-telegram bridge action contract.`;
+Telegram turn note: Load and follow the \`telegram-bridge\` Skill.`;
 
 export const TELEGRAM_ATTACH_PROMPT_SNIPPET =
   "Queue files for the active Telegram reply; outside Telegram turns, send files directly to Telegram.";
@@ -37,7 +34,6 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
   "telegram_attach",
   "telegram_message",
-  "telegram_help",
 ]);
 const TELEGRAM_MODEL_CONTEXT_MEMORY_KEY = Symbol.for(
   "@llblab/pi-telegram:model-context-suspended-tools",
@@ -71,6 +67,23 @@ export interface TelegramModelContextAvailabilityRuntime {
   reconcile: () => void;
 }
 
+export interface TelegramModelContextAvailabilityBinding
+  extends TelegramModelContextAvailabilityRuntime {
+  bind: (runtime: TelegramModelContextAvailabilityRuntime) => void;
+}
+
+export function createTelegramModelContextAvailabilityBinding(): TelegramModelContextAvailabilityBinding {
+  let runtime: TelegramModelContextAvailabilityRuntime | undefined;
+  return {
+    bind(next) {
+      runtime = next;
+    },
+    reconcile() {
+      runtime?.reconcile();
+    },
+  };
+}
+
 export function createTelegramModelContextAvailabilityRuntime(deps: {
   getActiveTools: () => string[];
   setActiveTools: (names: string[]) => void;
@@ -118,88 +131,6 @@ export function createTelegramModelContextAvailabilityRuntime(deps: {
   };
 }
 
-function buildTelegramHelpText(profileName?: string): string {
-  const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
-  return `--- TELEGRAM BRIDGE HELP ---
-
-How to understand Telegram turns:
-- \`[telegram|thread:name|from:user|guest:group]\` marks Telegram origin and attributes.
-- \`thread\` is the visible Thread identity in Threaded Mode; it is not a bus role.
-- \`[reply]\` is quoted context only; act on the user's current instruction.
-- \`[attachments]\` are local files; \`[outputs]\` are handler results/transcripts; \`[time]\` is wall-clock context.
-- \`[voice] delivery: automatic voice\` means pi-telegram will synthesize ordinary assistant text for this turn; no \`[voice]\` line means no automatic voice policy.
-
-How to answer Telegram turns:
-- Reply in concise, scannable mobile Telegram Rich Markdown.
-- Use \`$...$\` for inline math and \`$$...$$\` for block math.
-- Real code blocks must stay literal.
-- For generated/requested files, call \`telegram_attach(local_path)\`; do not only mention the path.
-
-Assistant-authored Telegram actions:
-- \`telegram_voice\` and \`telegram_button\` are hidden top-level HTML comments, not Pi tools.
-- Put action comments at column zero, outside code, quotes, lists, and indented examples.
-- Action payloads use either JSON or double-quoted attributes; the colon after the action name is optional and does not affect parsing. Voice accepts equivalent \`text\` or \`value\`: \`<!-- telegram_voice: {"value":"Short summary","lang":"en"} -->\` or \`<!-- telegram_voice text="Short summary" lang="en" -->\`.
-- Keep the complete action in one top-level comment and include non-empty \`text\` or \`value\`; encode line breaks inside JSON strings as \`\\n\`.
-- Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
-- Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
-- Voice reply modes are compact: \`hidden\` emits no automatic context, \`mirror\` emits it for voice/audio input, and \`always\` emits it for every Telegram turn. Explicit \`telegram_voice\` remains available for an intentionally distinct spoken payload.
-- Button payloads use \`label\` plus \`prompt\`, or compact \`value\` when both are identical: \`<!-- telegram_button: {"label":"Continue","prompt":"Continue with the current plan."} -->\` or \`<!-- telegram_button value="Continue" -->\`.
-- Optional \`selected_style\` in either payload form controls the button after queue admission: \`primary\` (default, blue), \`success\` (green), or \`danger\` (red). It never suppresses the prompt.
-- If hidden button comments form the whole reply, the bridge supplies the standard \`☑️ **Choose an option:**\` heading automatically.
-
-Local/TUI direct delivery:
-- Do not send Telegram actions from local/TUI prompts unless explicitly asked.
-- Use \`telegram_attach\` for files and \`telegram_message\` for direct Markdown text.
-- Direct delivery requires this Pi instance to own \`/telegram-connect\` or be registered with the Threaded Mode bus.
-- For explicit targets, pass \`chat_id\` plus optional \`thread_id\`; registered followers default to their assigned Thread target.
-- Do not use \`telegram_message\` for ordinary Telegram-originated replies; answer normally and let the bridge deliver the active turn reply.
-
-Threaded Mode:
-- pi-telegram supports private-chat Threaded Mode when Telegram exposes thread support for the bot.
-- Product/user language is Thread; Bot API primitive names may still say topic.
-- Threaded Mode has one leader transport and visible follower Pi processes joined manually through \`/telegram-connect\`.
-- Thread names are bridge-assigned or preserved identities; do not invent rename prompts or use a rename tool.
-- The \`All\` surface is for routing/control, not hidden Pi process creation.
-
-Configurable handlers:
-- \`telegram.json\` can add no-code \`inboundHandlers\`/\`outboundHandlers\` using command templates before writing an extension.
-- For speech-to-text, configure an \`inboundHandlers\` entry matching \`type: "voice"\` or \`mime: "audio/*"\`; stdout becomes \`[outputs]\` prompt context.
-- If command-template config is not enough, build a companion extension through the public pi-telegram APIs; do not import package-private \`lib/*\` paths.
-
-Debugging pi-telegram:
-- Inspect \`${diagnosticsPaths.state}\` for runtime state, roster, bindings, slots, reservations, and diagnostics.
-- Inspect \`${diagnosticsPaths.logs}\` for redacted runtime event evidence.
-- Use terminal \`telegram-status\` for compact human health; use \`telegram-status --debug\` for the full human-readable diagnostic dump.`;
-}
-
-export function getTelegramHelpText(profileName?: string): string {
-  return buildTelegramHelpText(profileName);
-}
-
-export function registerTelegramHelpTool(
-  pi: ExtensionAPI,
-  options: { getActiveProfileName?: () => string | undefined } = {},
-): void {
-  pi.registerTool({
-    name: "telegram_help",
-    label: "Telegram Help",
-    description:
-      "Read pi-telegram usage guidance for delivery actions, Threaded Mode, handlers, formatting, and debugging.",
-    parameters: Type.Object({}),
-    async execute() {
-      return {
-        content: [
-          {
-            type: "text",
-            text: getTelegramHelpText(options.getActiveProfileName?.()),
-          },
-        ],
-        details: {},
-      };
-    },
-  });
-}
-
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;
   systemPrompt: string;