@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-telegram/lib/prompt-templates.ts

@@ -0,0 +1,158 @@
+/**
+ * Pi prompt-template bridge helpers
+ * Zones: pi agent prompts, telegram controls, filesystem
+ * Discovers Pi prompt-template slash commands and expands them before Telegram queue dispatch
+ */
+
+import { readFileSync } from "node:fs";
+import type { PiSlashCommandInfo } from "./pi.ts";
+
+export interface TelegramPromptTemplateCommand {
+  command: string;
+  description?: string;
+  path: string;
+}
+
+export type TelegramPromptTemplateReader = (path: string) => string;
+
+const TELEGRAM_BOT_COMMAND_NAME_PATTERN = /^[a-z0-9_]{1,32}$/;
+
+function stripPromptTemplateFrontmatter(content: string): string {
+  if (!content.startsWith("---")) return content;
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return content;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index]?.trim() === "---")
+      return lines.slice(index + 1).join("\n");
+  }
+  return content;
+}
+
+export function parsePromptTemplateArgs(argsString: string): string[] {
+  const args: string[] = [];
+  let current = "";
+  let quote: string | undefined;
+  for (const char of argsString) {
+    if (quote) {
+      if (char === quote) {
+        quote = undefined;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === " " || char === "\t") {
+      if (current) args.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) args.push(current);
+  return args;
+}
+
+export function substitutePromptTemplateArgs(
+  content: string,
+  args: readonly string[],
+): string {
+  let result = content.replace(/\$(\d+)/g, (_, num: string) => {
+    const index = Number.parseInt(num, 10) - 1;
+    return args[index] ?? "";
+  });
+  result = result.replace(
+    /\$\{@:(\d+)(?::(\d+))?\}/g,
+    (_, startValue: string, lengthValue: string | undefined) => {
+      const start = Math.max(Number.parseInt(startValue, 10) - 1, 0);
+      if (lengthValue) {
+        const length = Number.parseInt(lengthValue, 10);
+        return args.slice(start, start + length).join(" ");
+      }
+      return args.slice(start).join(" ");
+    },
+  );
+  const allArgs = args.join(" ");
+  return result.replace(/\$ARGUMENTS/g, allArgs).replace(/\$@/g, allArgs);
+}
+
+export function isTelegramPromptTemplateCommandName(name: string): boolean {
+  return TELEGRAM_BOT_COMMAND_NAME_PATTERN.test(name);
+}
+
+export function mapPiPromptTemplateNameToTelegramCommandName(
+  name: string,
+): string | undefined {
+  const command = name
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 32)
+    .replace(/_+$/g, "");
+  return isTelegramPromptTemplateCommandName(command) ? command : undefined;
+}
+
+export interface TelegramPromptTemplateCommandGetterDeps {
+  getCommands: () => readonly PiSlashCommandInfo[];
+  reservedCommandNames?: readonly string[];
+  getReservedCommandNames?: () => readonly string[];
+}
+
+export function getTelegramPromptTemplateCommands(
+  commands: readonly PiSlashCommandInfo[],
+  reservedNames: ReadonlySet<string> = new Set(),
+): TelegramPromptTemplateCommand[] {
+  const seen = new Set<string>();
+  const promptCommands: TelegramPromptTemplateCommand[] = [];
+  for (const command of commands) {
+    if (command.source !== "prompt") continue;
+    const telegramCommand = mapPiPromptTemplateNameToTelegramCommandName(
+      command.name,
+    );
+    if (!telegramCommand) continue;
+    if (reservedNames.has(telegramCommand)) continue;
+    if (seen.has(telegramCommand)) continue;
+    const sourcePath = command.sourceInfo?.path;
+    if (!sourcePath) continue;
+    seen.add(telegramCommand);
+    promptCommands.push({
+      command: telegramCommand,
+      description: command.description,
+      path: sourcePath,
+    });
+  }
+  return promptCommands.sort((a, b) => a.command.localeCompare(b.command));
+}
+
+export function createTelegramPromptTemplateCommandGetter(
+  deps: TelegramPromptTemplateCommandGetterDeps,
+): () => TelegramPromptTemplateCommand[] {
+  return () => {
+    return getTelegramPromptTemplateCommands(
+      deps.getCommands(),
+      new Set([
+        ...(deps.reservedCommandNames ?? []),
+        ...(deps.getReservedCommandNames?.() ?? []),
+      ]),
+    );
+  };
+}
+
+export function expandTelegramPromptTemplateCommand(
+  commandName: string,
+  args: string,
+  commands: readonly TelegramPromptTemplateCommand[],
+  readTemplate: TelegramPromptTemplateReader = (path) =>
+    readFileSync(path, "utf-8"),
+): string | undefined {
+  const command = commands.find(
+    (candidate) => candidate.command === commandName,
+  );
+  if (!command) return undefined;
+  const content = stripPromptTemplateFrontmatter(readTemplate(command.path));
+  return substitutePromptTemplateArgs(content, parsePromptTemplateArgs(args));
+}

package/node_modules/@llblab/pi-telegram/lib/prompts.ts

@@ -0,0 +1,218 @@
+/**
+ * Telegram prompt injection helpers
+ * Zones: pi agent prompts, telegram guidance
+ * Owns Telegram-specific system prompt suffixes injected into pi agent turns
+ */
+
+import type { BeforeAgentStartEvent } from "./pi.ts";
+import { TELEGRAM_PREFIX } from "./turns.ts";
+
+const LOCAL_SYSTEM_PROMPT_SUFFIX = `
+
+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: 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.";
+export const TELEGRAM_ATTACH_PROMPT_GUIDELINES = [
+  "When handling a [telegram] message and the user asked for a file or generated artifact, call telegram_attach with the local path instead of only mentioning the path in text.",
+  "When a local/TUI user explicitly asks to send a generated file to Telegram, telegram_attach can deliver it to the paired/default Telegram chat even without an active Telegram turn.",
+  "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
+] as const;
+export const TELEGRAM_MESSAGE_PROMPT_SNIPPET =
+  "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery outside the normal reply flow.";
+export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
+  "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
+  "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
+  "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
+  "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
+] as const;
+
+const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
+  "telegram_attach",
+  "telegram_bind",
+  "telegram_message",
+]);
+const TELEGRAM_MODEL_CONTEXT_MEMORY_KEY = Symbol.for(
+  "@llblab/pi-telegram:model-context-suspended-tools",
+);
+
+export interface TelegramModelContextAvailabilityMemory {
+  suspended: boolean;
+  toolNames: Set<string>;
+}
+
+function getTelegramModelContextAvailabilityMemory(): TelegramModelContextAvailabilityMemory {
+  const globals = globalThis as unknown as Record<symbol, unknown>;
+  const existing = globals[TELEGRAM_MODEL_CONTEXT_MEMORY_KEY];
+  if (
+    existing &&
+    typeof existing === "object" &&
+    "toolNames" in existing &&
+    (existing as { toolNames?: unknown }).toolNames instanceof Set
+  ) {
+    return existing as TelegramModelContextAvailabilityMemory;
+  }
+  const memory: TelegramModelContextAvailabilityMemory = {
+    suspended: false,
+    toolNames: new Set<string>(),
+  };
+  globals[TELEGRAM_MODEL_CONTEXT_MEMORY_KEY] = memory;
+  return memory;
+}
+
+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;
+  isAvailable: () => boolean;
+  canReconcile?: () => boolean;
+  memory?: TelegramModelContextAvailabilityMemory;
+}): TelegramModelContextAvailabilityRuntime {
+  const memory =
+    deps.memory ?? getTelegramModelContextAvailabilityMemory();
+  return {
+    reconcile() {
+      if (deps.canReconcile && !deps.canReconcile()) return;
+      const activeTools = deps.getActiveTools();
+      if (!deps.isAvailable()) {
+        if (!memory.suspended) {
+          memory.toolNames.clear();
+          for (const name of activeTools) {
+            if (TELEGRAM_MODEL_CONTEXT_TOOL_NAMES.has(name)) {
+              memory.toolNames.add(name);
+            }
+          }
+          memory.suspended = true;
+        }
+        const nextTools = activeTools.filter(
+          (name) => !TELEGRAM_MODEL_CONTEXT_TOOL_NAMES.has(name),
+        );
+        if (nextTools.length !== activeTools.length) {
+          deps.setActiveTools(nextTools);
+        }
+        return;
+      }
+      if (!memory.suspended) return;
+      const nextTools = [...activeTools];
+      for (const name of TELEGRAM_MODEL_CONTEXT_TOOL_NAMES) {
+        if (memory.toolNames.has(name) && !nextTools.includes(name)) {
+          nextTools.push(name);
+        }
+      }
+      memory.toolNames.clear();
+      memory.suspended = false;
+      if (nextTools.length !== activeTools.length) {
+        deps.setActiveTools(nextTools);
+      }
+    },
+  };
+}
+
+export function buildTelegramBridgeSystemPrompt(options: {
+  prompt: string;
+  systemPrompt: string;
+  telegramPrefix?: string;
+  localSystemPromptSuffix: string;
+  telegramTurnSystemPromptSuffix: string;
+}): { systemPrompt: string } {
+  const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
+  const telegramHead = telegramPrefix.endsWith("]")
+    ? telegramPrefix.slice(0, -1)
+    : telegramPrefix;
+  const trimmedPrompt = options.prompt.trimStart();
+  const telegramTurn =
+    trimmedPrompt.startsWith(`${telegramHead}]`) ||
+    trimmedPrompt.startsWith(`${telegramHead}|`);
+  const telegramSuffix = telegramTurn
+    ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
+    : "";
+  return {
+    systemPrompt:
+      options.systemPrompt + options.localSystemPromptSuffix + telegramSuffix,
+  };
+}
+
+export function createTelegramBeforeAgentStartHook(
+  options: {
+    telegramPrefix?: string;
+    localSystemPromptSuffix?: string;
+    telegramTurnSystemPromptSuffix?: string;
+  } = {},
+): (event: BeforeAgentStartEvent) => { systemPrompt: string } {
+  return (event) =>
+    buildTelegramBridgeSystemPrompt({
+      prompt: event.prompt,
+      systemPrompt: event.systemPrompt,
+      telegramPrefix: options.telegramPrefix,
+      localSystemPromptSuffix:
+        options.localSystemPromptSuffix ?? LOCAL_SYSTEM_PROMPT_SUFFIX,
+      telegramTurnSystemPromptSuffix:
+        options.telegramTurnSystemPromptSuffix ??
+        TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX,
+    });
+}
+
+function stripTelegramToolMetadataFromSystemPrompt(
+  systemPrompt: string,
+): string {
+  const telegramLines = new Set([
+    `- telegram_attach: ${TELEGRAM_ATTACH_PROMPT_SNIPPET}`,
+    `- telegram_message: ${TELEGRAM_MESSAGE_PROMPT_SNIPPET}`,
+    ...TELEGRAM_ATTACH_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+    ...TELEGRAM_MESSAGE_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+  ]);
+  return systemPrompt
+    .split("\n")
+    .filter((line) => !telegramLines.has(line))
+    .join("\n");
+}
+
+export interface TelegramProactivePromptHookDeps<TContext> {
+  baseHook?: (event: BeforeAgentStartEvent) => { systemPrompt: string };
+  reconcileAvailability?: () => void;
+  isAvailable: (ctx: TContext) => boolean;
+}
+
+export function createTelegramProactiveBeforeAgentStartHook<TContext>(
+  deps: TelegramProactivePromptHookDeps<TContext>,
+): (
+  event: BeforeAgentStartEvent,
+  ctx: TContext,
+) => Promise<{ systemPrompt: string }> {
+  const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
+  return async (event, ctx) => {
+    deps.reconcileAvailability?.();
+    if (!deps.isAvailable(ctx)) {
+      return {
+        systemPrompt: stripTelegramToolMetadataFromSystemPrompt(
+          event.systemPrompt,
+        ),
+      };
+    }
+    return baseHook(event);
+  };
+}