pi-harness-runtime 1.1.398 → 1.1.402

package/packages/telegram/src/inbound.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Telegram inbound handler pipeline
+ * Zones: telegram inbound, command templates, prompt preparation
+ * Owns MIME/type matching, command-template execution, fallback handling, and prompt injection before prompt enqueueing
+ */
+import { type CommandTemplateConfig, type CommandTemplateObjectConfig } from "./command-templates.ts";
+type TelegramInboundCommandTemplateConfig = string | CommandTemplateObjectConfig;
+export interface TelegramInboundHandlerConfig {
+    match?: string | string[];
+    mime?: string | string[];
+    type?: string | string[];
+    template?: string | TelegramInboundCommandTemplateConfig[];
+    /** Falsy skips this handler so selection continues with the next match. */
+    when?: CommandTemplateObjectConfig["when"];
+    args?: string[];
+    defaults?: Record<string, unknown>;
+    timeout?: number | string;
+    retry?: CommandTemplateObjectConfig["retry"];
+    recover?: CommandTemplateObjectConfig["recover"];
+}
+export interface TelegramInboundHandlerFile {
+    path: string;
+    fileName?: string;
+    mimeType?: string;
+    kind?: string;
+    isImage?: boolean;
+}
+export interface TelegramInboundHandlerOutput {
+    file: TelegramInboundHandlerFile;
+    output: string;
+    handler: TelegramInboundHandlerConfig;
+}
+export interface TelegramInboundHandlerProcessResult<TFile extends TelegramInboundHandlerFile = TelegramInboundHandlerFile> {
+    rawText: string;
+    promptFiles: TFile[];
+    handlerOutputs: string[];
+    handledFiles: TelegramInboundHandlerOutput[];
+}
+export interface TelegramInboundHandlerExecOptions {
+    cwd?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+    stdin?: string;
+    retry?: number;
+    recover?: () => Promise<void>;
+}
+export interface TelegramInboundHandlerExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+}
+export interface TelegramInboundHandlerRuntimeDeps<TContext> {
+    getHandlers: () => TelegramInboundHandlerConfig[] | undefined;
+    execCommand: (command: string, args: string[], options?: TelegramInboundHandlerExecOptions) => Promise<TelegramInboundHandlerExecResult>;
+    getCwd: (ctx: TContext) => string;
+    recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
+}
+export interface TelegramInboundHandlerRuntime<TContext> {
+    process: <TFile extends TelegramInboundHandlerFile>(files: TFile[], rawText: string, ctx: TContext) => Promise<TelegramInboundHandlerProcessResult<TFile>>;
+}
+export type TelegramInboundProgrammaticHandlerResult = string | {
+    text: string;
+} | undefined;
+export interface TelegramInboundProgrammaticHandlerInput {
+    kind: string;
+    text?: string;
+    file?: TelegramInboundHandlerFile;
+    mimeType?: string;
+}
+export type TelegramInboundProgrammaticHandler = (input: TelegramInboundProgrammaticHandlerInput, options?: {
+    cwd?: string;
+}) => Promise<TelegramInboundProgrammaticHandlerResult>;
+export interface TelegramInboundHandlerRegistry {
+    handlers: Map<string, TelegramInboundProgrammaticHandler[]>;
+}
+interface InboundHandlerInvocation {
+    command: string;
+    args: string[];
+}
+export declare function registerTelegramInboundHandler(kind: string, handler: TelegramInboundProgrammaticHandler): () => void;
+export declare function clearTelegramInboundHandlers(): void;
+export declare function telegramInboundHandlerMatchesFile(handler: TelegramInboundHandlerConfig, file: TelegramInboundHandlerFile): boolean;
+export declare function buildTelegramInboundHandlerInvocation(handler: CommandTemplateConfig, file: TelegramInboundHandlerFile, cwd: string, appendFileIfMissing?: boolean): InboundHandlerInvocation;
+export declare function processTelegramInboundHandlers<TFile extends TelegramInboundHandlerFile>(options: {
+    files: TFile[];
+    rawText: string;
+    handlers?: TelegramInboundHandlerConfig[];
+    cwd: string;
+    execCommand: TelegramInboundHandlerRuntimeDeps<unknown>["execCommand"];
+    recordRuntimeEvent?: TelegramInboundHandlerRuntimeDeps<unknown>["recordRuntimeEvent"];
+}): Promise<TelegramInboundHandlerProcessResult<TFile>>;
+export declare function createTelegramInboundHandlerRuntime<TContext>(deps: TelegramInboundHandlerRuntimeDeps<TContext>): TelegramInboundHandlerRuntime<TContext>;
+export {};

package/packages/telegram/src/inbound.js

@@ -0,0 +1,478 @@
+/**
+ * Telegram inbound handler pipeline
+ * Zones: telegram inbound, command templates, prompt preparation
+ * Owns MIME/type matching, command-template execution, fallback handling, and prompt injection before prompt enqueueing
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { buildCommandTemplateInvocation, createCommandTemplateRecovery, getCommandTemplateCompositionSteps, getCommandTemplateConfiguredTimeout, getCommandTemplateStepTimeout, normalizeCommandTemplateConfig, resolveCommandTemplateNumericField, shouldRunCommandTemplateConfig, } from "./command-templates.js";
+import { getTelegramVoiceTranscriptionProviders } from "./voice.js";
+const DEFAULT_INBOUND_HANDLER_TIMEOUT_MS = 120_000;
+const INBOUND_HANDLER_REGISTRY_KEY = "__piTelegramInboundHandlers__";
+const MAX_INBOUND_HANDLER_OUTPUT_LENGTH = 24_000;
+const MAX_INBOUND_HANDLER_FAILURE_STREAM_LENGTH = 4_000;
+const BUILT_IN_TEXT_ATTACHMENT_MAX_BYTES = 1_000_000;
+function getOrCreateInboundHandlerRegistry() {
+    const existing = globalThis[INBOUND_HANDLER_REGISTRY_KEY];
+    if (existing &&
+        typeof existing === "object" &&
+        existing !== null &&
+        "handlers" in existing &&
+        existing.handlers instanceof Map) {
+        return existing;
+    }
+    const registry = {
+        handlers: new Map(),
+    };
+    globalThis[INBOUND_HANDLER_REGISTRY_KEY] =
+        registry;
+    return registry;
+}
+export function registerTelegramInboundHandler(kind, handler) {
+    const normalizedKind = kind.trim() || "*";
+    const registry = getOrCreateInboundHandlerRegistry();
+    const list = registry.handlers.get(normalizedKind) ?? [];
+    list.push(handler);
+    registry.handlers.set(normalizedKind, list);
+    return () => {
+        const updated = registry.handlers.get(normalizedKind) ?? [];
+        const index = updated.indexOf(handler);
+        if (index !== -1) {
+            updated.splice(index, 1);
+            registry.handlers.set(normalizedKind, updated);
+        }
+    };
+}
+function getTelegramInboundProgrammaticHandlers(kind) {
+    const registry = getOrCreateInboundHandlerRegistry();
+    return [
+        ...(registry.handlers.get(kind) ?? []),
+        ...(kind === "*" ? [] : (registry.handlers.get("*") ?? [])),
+    ];
+}
+export function clearTelegramInboundHandlers() {
+    getOrCreateInboundHandlerRegistry().handlers.clear();
+}
+function truncateTelegramInboundText(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength).trimEnd()}… [truncated ${text.length - maxLength} chars]`;
+}
+function truncateTelegramInboundOutput(text) {
+    return truncateTelegramInboundText(text, MAX_INBOUND_HANDLER_OUTPUT_LENGTH);
+}
+function truncateTelegramInboundFailureStream(text) {
+    return truncateTelegramInboundText(text.trimEnd(), MAX_INBOUND_HANDLER_FAILURE_STREAM_LENGTH);
+}
+function normalizeInboundProgrammaticHandlerText(result) {
+    const text = typeof result === "string" ? result : result?.text;
+    const normalized = text?.trim();
+    return normalized ? truncateTelegramInboundOutput(normalized) : undefined;
+}
+function normalizeStringList(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map(String)
+            .map((item) => item.trim())
+            .filter(Boolean);
+    }
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    return [];
+}
+function matchesWildcard(pattern, value) {
+    if (!value)
+        return false;
+    const normalizedPattern = pattern.toLowerCase();
+    const normalizedValue = value.toLowerCase();
+    if (normalizedPattern === "*")
+        return true;
+    const escaped = normalizedPattern
+        .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+        .replace(/\\\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(normalizedValue);
+}
+function handlerHasSelectors(handler) {
+    return (normalizeStringList(handler.match).length > 0 ||
+        normalizeStringList(handler.mime).length > 0 ||
+        normalizeStringList(handler.type).length > 0);
+}
+function matchesAnyPattern(patterns, value) {
+    return patterns.some((pattern) => matchesWildcard(pattern, value));
+}
+function isTelegramTextMimeType(mimeType) {
+    return matchesWildcard("text/*", mimeType);
+}
+export function telegramInboundHandlerMatchesFile(handler, file) {
+    if (!handlerHasSelectors(handler))
+        return true;
+    const matchPatterns = normalizeStringList(handler.match);
+    const mimePatterns = normalizeStringList(handler.mime);
+    const typePatterns = normalizeStringList(handler.type);
+    if (matchesAnyPattern(mimePatterns, file.mimeType))
+        return true;
+    if (matchesAnyPattern(typePatterns, file.kind))
+        return true;
+    if (matchesAnyPattern(matchPatterns, file.mimeType))
+        return true;
+    return matchesAnyPattern(matchPatterns, file.kind);
+}
+function findTelegramInboundHandlers(handlers, file) {
+    if (!Array.isArray(handlers))
+        return [];
+    return handlers.filter((handler) => !!handler &&
+        typeof handler === "object" &&
+        telegramInboundHandlerMatchesFile(handler, file));
+}
+function hasInboundFilePlaceholder(value) {
+    return /\{file\}/.test(value);
+}
+function getTelegramInboundHandlerTemplateValues(file, text = "") {
+    return {
+        file: file.path,
+        mime: file.mimeType ?? "",
+        text,
+        type: file.kind ?? "",
+    };
+}
+function buildTelegramInboundTemplateInvocation(handler, file, cwd, appendFileIfMissing = true) {
+    const values = getTelegramInboundHandlerTemplateValues(file);
+    const templateConfig = normalizeCommandTemplateConfig(handler);
+    const hadFilePlaceholder = typeof templateConfig.template === "string"
+        ? hasInboundFilePlaceholder(templateConfig.template)
+        : false;
+    const invocation = buildCommandTemplateInvocation(handler, values, cwd, {
+        emptyMessage: "Inbound handler template is empty",
+        missingLabel: "inbound handler template",
+    });
+    if (appendFileIfMissing && !hadFilePlaceholder)
+        invocation.args.push(file.path);
+    return invocation;
+}
+export function buildTelegramInboundHandlerInvocation(handler, file, cwd, appendFileIfMissing = true) {
+    const { template } = normalizeCommandTemplateConfig(handler);
+    if (!template)
+        throw new Error("Inbound handler template is required");
+    return buildTelegramInboundTemplateInvocation(handler, file, cwd, appendFileIfMissing);
+}
+function getTelegramInboundHandlerTimeout(handler) {
+    return (getCommandTemplateConfiguredTimeout(handler) ??
+        DEFAULT_INBOUND_HANDLER_TIMEOUT_MS);
+}
+function getTelegramInboundHandlerKind(handler) {
+    if (Array.isArray(handler.template))
+        return "composition";
+    if (handler.template)
+        return "template";
+    return "unknown";
+}
+function formatTelegramInboundHandlerFailure(result) {
+    const parts = [
+        `Inbound handler exited with code ${result.code}${result.killed ? " (killed)" : ""}`,
+    ];
+    if (result.stderr.trim())
+        parts.push(`stderr:\n${truncateTelegramInboundFailureStream(result.stderr)}`);
+    if (result.stdout.trim())
+        parts.push(`stdout:\n${truncateTelegramInboundFailureStream(result.stdout)}`);
+    return parts.join("\n\n");
+}
+function getTelegramInboundHandlerRetryOptions(handler, values, cwd, timeout, deps) {
+    if (typeof handler !== "object" || handler.retry === undefined)
+        return {};
+    const recover = createCommandTemplateRecovery(handler, values, {
+        cwd,
+        timeout,
+        execCommand: deps.execCommand,
+    });
+    return {
+        retry: resolveCommandTemplateNumericField(handler.retry, {}, "retry"),
+        ...(recover ? { recover } : {}),
+    };
+}
+async function executeTelegramInboundHandlerInvocation(handler, file, cwd, deps, appendFileIfMissing = true, timeout = getTelegramInboundHandlerTimeout(handler), stdin) {
+    const invocation = buildTelegramInboundHandlerInvocation(handler, file, cwd, appendFileIfMissing);
+    const result = await deps.execCommand(invocation.command, invocation.args, {
+        cwd,
+        timeout,
+        ...getTelegramInboundHandlerRetryOptions(handler, getTelegramInboundHandlerTemplateValues(file), cwd, timeout, deps),
+        ...(stdin !== undefined ? { stdin } : {}),
+    });
+    if (result.code !== 0)
+        throw new Error(formatTelegramInboundHandlerFailure(result));
+    return truncateTelegramInboundOutput(result.stdout);
+}
+function getTelegramTextHandlerFile() {
+    return {
+        path: "",
+        fileName: "message.txt",
+        mimeType: "text/plain",
+        kind: "text",
+        isImage: false,
+    };
+}
+function findTelegramTextHandlers(handlers) {
+    if (!Array.isArray(handlers))
+        return [];
+    const textFile = getTelegramTextHandlerFile();
+    return handlers.filter((handler) => !!handler &&
+        typeof handler === "object" &&
+        handlerHasSelectors(handler) &&
+        telegramInboundHandlerMatchesFile(handler, textFile));
+}
+function buildTelegramTextHandlerInvocation(handler, text, cwd) {
+    const values = getTelegramInboundHandlerTemplateValues(getTelegramTextHandlerFile(), text);
+    const { template } = normalizeCommandTemplateConfig(handler);
+    if (!template)
+        throw new Error("Text handler template is required");
+    return buildCommandTemplateInvocation(handler, values, cwd, {
+        emptyMessage: "Text handler template is empty",
+        missingLabel: "text handler template",
+    });
+}
+async function executeTelegramTextHandlerInvocation(handler, text, cwd, deps, timeout = getTelegramInboundHandlerTimeout(handler)) {
+    const invocation = buildTelegramTextHandlerInvocation(handler, text, cwd);
+    const result = await deps.execCommand(invocation.command, invocation.args, {
+        cwd,
+        timeout,
+        stdin: text,
+        ...getTelegramInboundHandlerRetryOptions(handler, getTelegramInboundHandlerTemplateValues(getTelegramTextHandlerFile(), text), cwd, timeout, deps),
+    });
+    if (result.code !== 0)
+        throw new Error(formatTelegramInboundHandlerFailure(result));
+    return truncateTelegramInboundOutput(result.stdout);
+}
+async function executeTelegramTextHandler(handler, text, cwd, deps) {
+    const steps = getCommandTemplateCompositionSteps(handler);
+    if (steps.length === 0) {
+        return (await executeTelegramTextHandlerInvocation(handler, text, cwd, deps)).trim();
+    }
+    const startedAt = Date.now();
+    let output = text;
+    for (const [index, step] of steps.entries()) {
+        if (!shouldRunCommandTemplateConfig(step, getTelegramInboundHandlerTemplateValues(getTelegramTextHandlerFile(), output)))
+            continue;
+        try {
+            output = await executeTelegramTextHandlerInvocation(step, output, cwd, deps, getCommandTemplateStepTimeout(getTelegramInboundHandlerTimeout(handler), step, index === 0 ? undefined : Date.now() - startedAt));
+        }
+        catch (error) {
+            if (typeof step === "object" && step.failure === "root")
+                throw error;
+            output = "";
+        }
+        if (index > 0 && !output)
+            output = text;
+    }
+    return output.trim();
+}
+async function processTelegramTextHandlers(options) {
+    if (!options.rawText)
+        return options.rawText;
+    let text = options.rawText;
+    for (const handler of findTelegramTextHandlers(options.handlers)) {
+        try {
+            // An unresolvable guard fails only this handler, like its command would.
+            if (!shouldRunCommandTemplateConfig(handler, getTelegramInboundHandlerTemplateValues(getTelegramTextHandlerFile(), text)))
+                continue;
+            const output = await executeTelegramTextHandler(handler, text, options.cwd, options);
+            if (output)
+                text = output;
+        }
+        catch (error) {
+            options.recordRuntimeEvent?.("inbound-text-handler", error, {
+                handler: getTelegramInboundHandlerKind(handler),
+            });
+        }
+    }
+    for (const handler of getTelegramInboundProgrammaticHandlers("text")) {
+        try {
+            const output = normalizeInboundProgrammaticHandlerText(await handler({ kind: "text", text, mimeType: "text/plain" }, { cwd: options.cwd }));
+            if (output)
+                text = output;
+        }
+        catch (error) {
+            options.recordRuntimeEvent?.("inbound-programmatic-handler", error, {
+                kind: "text",
+            });
+        }
+    }
+    return text;
+}
+function isTelegramVoiceLikeFile(file) {
+    return (file.kind === "voice" ||
+        file.kind === "audio" ||
+        matchesWildcard("audio/*", file.mimeType));
+}
+async function processTelegramFileWithProgrammaticHandlers(file, options) {
+    const kind = file.kind || "*";
+    for (const handler of getTelegramInboundProgrammaticHandlers(kind)) {
+        try {
+            const output = normalizeInboundProgrammaticHandlerText(await handler({
+                kind,
+                file,
+                mimeType: file.mimeType,
+            }, { cwd: options.cwd }));
+            if (output)
+                return output;
+        }
+        catch (error) {
+            options.recordRuntimeEvent?.("inbound-programmatic-handler", error, {
+                fileName: file.fileName || basename(file.path),
+                kind,
+            });
+        }
+    }
+    return undefined;
+}
+async function transcribeTelegramVoiceFileWithProviders(file, options) {
+    if (!isTelegramVoiceLikeFile(file))
+        return undefined;
+    for (const provider of getTelegramVoiceTranscriptionProviders()) {
+        try {
+            const result = await provider(file, {});
+            const text = typeof result === "string" ? result : result?.text;
+            if (text?.trim())
+                return truncateTelegramInboundOutput(text.trim());
+        }
+        catch (error) {
+            options.recordRuntimeEvent?.("voice-transcription-provider", error, {
+                fileName: file.fileName || basename(file.path),
+            });
+        }
+    }
+    return undefined;
+}
+async function readBuiltInTelegramTextAttachment(file) {
+    if (!isTelegramTextMimeType(file.mimeType))
+        return undefined;
+    const content = await readFile(file.path, "utf8");
+    const normalized = content.trim();
+    if (!normalized ||
+        Buffer.byteLength(normalized, "utf8") > BUILT_IN_TEXT_ATTACHMENT_MAX_BYTES) {
+        return undefined;
+    }
+    const name = file.fileName || basename(file.path);
+    return truncateTelegramInboundOutput(`[${name}]\n${normalized}`);
+}
+async function executeTelegramInboundHandler(handler, file, cwd, deps) {
+    const steps = getCommandTemplateCompositionSteps(handler);
+    if (steps.length === 0) {
+        const output = await executeTelegramInboundHandlerInvocation(handler, file, cwd, deps);
+        return output.trim();
+    }
+    const startedAt = Date.now();
+    const values = getTelegramInboundHandlerTemplateValues(file);
+    let output = "";
+    let started = false;
+    for (const step of steps) {
+        if (!shouldRunCommandTemplateConfig(step, values))
+            continue;
+        const first = !started;
+        started = true;
+        try {
+            output = await executeTelegramInboundHandlerInvocation(step, file, cwd, deps, false, getCommandTemplateStepTimeout(getTelegramInboundHandlerTimeout(handler), step, first ? undefined : Date.now() - startedAt), first ? undefined : output);
+        }
+        catch (error) {
+            if (typeof step === "object" && step.failure === "root")
+                throw error;
+            output = "";
+        }
+    }
+    return output.trim();
+}
+export async function processTelegramInboundHandlers(options) {
+    const rawText = await processTelegramTextHandlers({
+        rawText: options.rawText,
+        handlers: options.handlers,
+        cwd: options.cwd,
+        execCommand: options.execCommand,
+        recordRuntimeEvent: options.recordRuntimeEvent,
+    });
+    const promptFiles = [...options.files];
+    const outputs = [];
+    for (const file of options.files) {
+        let hasOutput = false;
+        const handlers = findTelegramInboundHandlers(options.handlers, file);
+        for (const handler of handlers) {
+            try {
+                if (!shouldRunCommandTemplateConfig(handler, getTelegramInboundHandlerTemplateValues(file)))
+                    continue;
+                const output = await executeTelegramInboundHandler(handler, file, options.cwd, options);
+                if (output) {
+                    outputs.push({ file, output, handler });
+                    hasOutput = true;
+                }
+                break;
+            }
+            catch (error) {
+                options.recordRuntimeEvent?.("inbound-handler", error, {
+                    fileName: file.fileName || basename(file.path),
+                    handler: getTelegramInboundHandlerKind(handler),
+                });
+            }
+        }
+        if (!hasOutput) {
+            try {
+                const output = await processTelegramFileWithProgrammaticHandlers(file, {
+                    cwd: options.cwd,
+                    recordRuntimeEvent: options.recordRuntimeEvent,
+                });
+                if (output) {
+                    outputs.push({ file, output, handler: { type: "programmatic" } });
+                    hasOutput = true;
+                }
+            }
+            catch (error) {
+                options.recordRuntimeEvent?.("inbound-programmatic-handler", error, {
+                    fileName: file.fileName || basename(file.path),
+                });
+            }
+        }
+        if (!hasOutput) {
+            try {
+                const output = await transcribeTelegramVoiceFileWithProviders(file, {
+                    recordRuntimeEvent: options.recordRuntimeEvent,
+                });
+                if (output) {
+                    outputs.push({ file, output, handler: { type: "voice-provider" } });
+                    hasOutput = true;
+                }
+            }
+            catch (error) {
+                options.recordRuntimeEvent?.("voice-transcription-provider", error, {
+                    fileName: file.fileName || basename(file.path),
+                });
+            }
+        }
+        if (!hasOutput) {
+            try {
+                const output = await readBuiltInTelegramTextAttachment(file);
+                if (output)
+                    outputs.push({ file, output, handler: { type: "text" } });
+            }
+            catch (error) {
+                options.recordRuntimeEvent?.("inbound-handler", error, {
+                    fileName: file.fileName || basename(file.path),
+                    handler: "built-in-text",
+                });
+            }
+        }
+    }
+    return {
+        rawText,
+        promptFiles,
+        handlerOutputs: outputs.map((output) => output.output),
+        handledFiles: outputs,
+    };
+}
+export function createTelegramInboundHandlerRuntime(deps) {
+    return {
+        process: (files, rawText, ctx) => processTelegramInboundHandlers({
+            files,
+            rawText,
+            handlers: deps.getHandlers(),
+            cwd: deps.getCwd(ctx),
+            execCommand: deps.execCommand,
+            recordRuntimeEvent: deps.recordRuntimeEvent,
+        }),
+    };
+}

package/packages/telegram/src/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Telegram package entrypoint
+ * Zones: telegram, pi agent, public API
+ * Re-exports the extension composition root without owning runtime wiring.
+ */
+export { default } from "./lib/extension.ts";

package/packages/telegram/src/index.js

@@ -0,0 +1,6 @@
+/**
+ * Telegram package entrypoint
+ * Zones: telegram, pi agent, public API
+ * Re-exports the extension composition root without owning runtime wiring.
+ */
+export { default } from "./extension.js";

package/packages/telegram/src/keyboard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Telegram inline-keyboard structural contracts
+ * Zones: telegram ui, shared structure
+ * Owns the shared Bot API reply-markup shape while feature domains own their button semantics
+ */
+export type TelegramInlineKeyboardButtonStyle = "danger" | "success" | "primary";
+export type TelegramInlineKeyboardButton = {
+    text: string;
+    style?: TelegramInlineKeyboardButtonStyle;
+} & ({
+    callback_data: string;
+    disabled?: never;
+} | {
+    disabled: Record<string, never>;
+    callback_data?: never;
+});
+export interface TelegramInlineKeyboardMarkup {
+    inline_keyboard: TelegramInlineKeyboardButton[][];
+}
+export declare function assertTelegramCallbackData(callbackData: string, context?: string): string;
+export declare function assertTelegramInlineKeyboardCallbackData(replyMarkup: unknown, context?: string): void;

package/packages/telegram/src/keyboard.js

@@ -0,0 +1,37 @@
+/**
+ * Telegram inline-keyboard structural contracts
+ * Zones: telegram ui, shared structure
+ * Owns the shared Bot API reply-markup shape while feature domains own their button semantics
+ */
+const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
+function getTelegramCallbackDataByteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+export function assertTelegramCallbackData(callbackData, context = "Telegram callback_data") {
+    const byteLength = getTelegramCallbackDataByteLength(callbackData);
+    if (byteLength > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
+        throw new Error(`${context} exceeds ${TELEGRAM_CALLBACK_DATA_MAX_BYTES} bytes (${byteLength}). Use a shorter action/payload or store state behind a compact key.`);
+    }
+    return callbackData;
+}
+export function assertTelegramInlineKeyboardCallbackData(replyMarkup, context = "Telegram inline keyboard callback_data") {
+    if (!replyMarkup || typeof replyMarkup !== "object")
+        return;
+    const keyboard = replyMarkup
+        .inline_keyboard;
+    if (!Array.isArray(keyboard))
+        return;
+    for (const row of keyboard) {
+        if (!Array.isArray(row))
+            continue;
+        for (const button of row) {
+            if (!button || typeof button !== "object")
+                continue;
+            const callbackData = button
+                .callback_data;
+            if (typeof callbackData !== "string")
+                continue;
+            assertTelegramCallbackData(callbackData, context);
+        }
+    }
+}