@gajae-code/coding-agent 0.12.11 → 0.12.13

package/src/sdk/bus/telegram-reference.ts

@@ -14,12 +14,15 @@
  * Dependency-free: uses global `fetch` and `WebSocket` (Bun/Node 22+).
  */
 
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import { logger } from "@gajae-code/utils";
 import {
 	bold,
 	buildCompactChoiceGrid,
 	escapeHtml,
 	numberedOptionList,
+	renumberableOptionText,
 	splitTelegramHtml,
 	TELEGRAM_PARSE_MODE,
 } from "./html-format";
@@ -33,6 +36,44 @@ const REFERENCE_CLIENT_HELLO = {
 	capabilities: ["ask_controls_v1"],
 } as const;
 
+const MAX_DIAGNOSTIC_CAPABILITIES = 4;
+const MAX_DIAGNOSTIC_CAPABILITY_CODE_POINTS = 64;
+const MAX_DIAGNOSTIC_ERROR_NAME_CODE_POINTS = 64;
+const MAX_DIAGNOSTIC_ERROR_MESSAGE_CODE_POINTS = 128;
+
+function boundedDiagnosticText(value: string, maxCodePoints: number): string {
+	let result = "";
+	let codePoints = 0;
+	for (const character of value) {
+		const codePoint = character.codePointAt(0)!;
+		if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) continue;
+		result += character;
+		codePoints++;
+		if (codePoints === maxCodePoints) break;
+	}
+	return result;
+}
+
+function boundedDiagnosticCallbackError(error: unknown): Readonly<{ errorName: string; errorMessage: string }> {
+	let errorName = "UnknownError";
+	let errorMessage = "Diagnostic callback threw";
+	try {
+		if (error instanceof Error) {
+			errorName = boundedDiagnosticText(error.name, MAX_DIAGNOSTIC_ERROR_NAME_CODE_POINTS) || "Error";
+			errorMessage =
+				boundedDiagnosticText(error.message, MAX_DIAGNOSTIC_ERROR_MESSAGE_CODE_POINTS) ||
+				"Diagnostic callback threw";
+		} else {
+			errorMessage =
+				boundedDiagnosticText(String(error), MAX_DIAGNOSTIC_ERROR_MESSAGE_CODE_POINTS) ||
+				"Diagnostic callback threw";
+		}
+	} catch {
+		// Hostile thrown values must not escape the diagnostic failure boundary.
+	}
+	return Object.freeze({ errorName, errorMessage });
+}
+
 /** One inline-keyboard button. */
 export interface InlineButton {
 	text: string;
@@ -85,18 +126,27 @@ export interface CallbackRoute {
 	sessionId: string;
 	actionId: string;
 	answer: TelegramCallbackAnswer;
+	/** Durable audit metadata only; never sufficient to route a callback after restart. */
+	chatId?: string;
+	messageId?: number;
+	ownerId?: string;
+	generation?: number;
 }
 
 export interface SerializedAliasTable {
-	version: 1;
+	version: 1 | 2;
 	next: number;
 	routes: Record<string, CallbackRoute>;
 }
 
 export interface AliasTable {
+	allocate(isReserved?: (alias: string) => boolean): string;
+	activate(alias: string, route: CallbackRoute): boolean;
 	put(route: CallbackRoute): string;
 	get(alias: string): CallbackRoute | undefined;
+	update(alias: string, patch: Partial<CallbackRoute>): boolean;
 	delete(alias: string): boolean;
+	clear(): void;
 	serialize(): SerializedAliasTable;
 	load(json: unknown): void;
 	entries(): Array<[string, CallbackRoute]>;
@@ -112,7 +162,11 @@ function isCallbackRoute(value: unknown): value is CallbackRoute {
 			typeof route.answer === "number" ||
 			(typeof route.answer === "object" &&
 				route.answer !== null &&
-				(route.answer as { controlId?: unknown }).controlId === "navigation_forward"))
+				(route.answer as { controlId?: unknown }).controlId === "navigation_forward")) &&
+		(route.chatId === undefined || typeof route.chatId === "string") &&
+		(route.messageId === undefined || (Number.isSafeInteger(route.messageId) && route.messageId > 0)) &&
+		(route.ownerId === undefined || typeof route.ownerId === "string") &&
+		(route.generation === undefined || (Number.isSafeInteger(route.generation) && route.generation >= 0))
 	);
 }
 
@@ -121,24 +175,46 @@ export function createAliasTable(): AliasTable {
 	let next = 1;
 	const routes = new Map<string, CallbackRoute>();
 	return {
-		put(route) {
+		allocate(isReserved) {
 			let alias: string;
 			do {
-				alias = `a${(next++).toString(36)}`;
-			} while (routes.has(alias));
+				// `b1_` is intentionally disjoint from every legacy sequential `aN`
+				// token, including accepted keyboards lost before their old daemon
+				// could persist them.
+				alias = `b1_${crypto.randomBytes(18).toString("base64url")}`;
+			} while (routes.has(alias) || isReserved?.(alias) === true);
+			next++;
 			if (Buffer.byteLength(alias, "utf8") > 64) throw new Error("callback alias exceeded Telegram limit");
+			return alias;
+		},
+		activate(alias, route) {
+			if (routes.has(alias) || Buffer.byteLength(alias, "utf8") > 64 || !isCallbackRoute(route)) return false;
 			routes.set(alias, { ...route });
+			return true;
+		},
+		put(route) {
+			const alias = this.allocate();
+			if (!this.activate(alias, route)) throw new Error("callback alias activation failed");
 			return alias;
 		},
 		get(alias) {
 			const route = routes.get(alias);
 			return route ? { ...route } : undefined;
 		},
+		update(alias, patch) {
+			const route = routes.get(alias);
+			if (!route) return false;
+			routes.set(alias, { ...route, ...patch });
+			return true;
+		},
 		delete(alias) {
 			return routes.delete(alias);
 		},
+		clear() {
+			routes.clear();
+		},
 		serialize() {
-			return { version: 1, next, routes: Object.fromEntries(routes.entries()) };
+			return { version: 2, next, routes: Object.fromEntries(routes.entries()) };
 		},
 		load(json) {
 			routes.clear();
@@ -218,7 +294,7 @@ export function buildActionMarkdown(action: {
 	const options = action.options ?? [];
 	const displayOptions = withRecommendedOptionLabel(options, action.recommendedIndex);
 	if (options.length === 0) return `${heading}\n\n(reply with text)`;
-	const list = displayOptions.map((label, i) => `${i + 1}. ${label.replace(/^\s*\d+[.)]\s+/, "")}`).join("\n");
+	const list = displayOptions.map((label, i) => `${i + 1}. ${renumberableOptionText(label)}`).join("\n");
 	return `${heading}\n\n${list}`;
 }
 
@@ -370,6 +446,12 @@ export function readEndpoint(path: string): { url: string; token: string; pid?:
 	};
 }
 
+/** A bounded, diagnostic-only notification mirrored to reference-client embedders. */
+export type TelegramReferenceDiagnostic = Readonly<{
+	code: "action_unavailable";
+	requiredCapabilities: readonly string[];
+}>;
+
 /** Options for {@link runTelegramReferenceClient}. */
 export interface TelegramReferenceOptions {
 	botToken: string;
@@ -378,6 +460,11 @@ export interface TelegramReferenceOptions {
 	apiBase?: string;
 	fetchImpl?: typeof fetch;
 	sound?: TelegramNotificationSound;
+	/**
+	 * Additive mirror of bounded logger diagnostics. It never receives tokens,
+	 * identifiers, raw frames, Telegram content, or WebSocket replies.
+	 */
+	onDiagnostic?: (diagnostic: TelegramReferenceDiagnostic) => void;
 }
 
 /**
@@ -434,15 +521,27 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 				msg.kind ?? "ask",
 			);
 		} else if (msg.type === "action_unavailable") {
-			const requiredCapabilities = Array.isArray(msg.requiredCapabilities)
-				? msg.requiredCapabilities
-						.filter((capability): capability is string => typeof capability === "string")
-						.slice(0, 4)
-						.map(capability => capability.slice(0, 64))
-				: [];
-			console.warn(
-				`Telegram reference client: server withheld a controlled ask because this client lacks requiredCapabilities=[${requiredCapabilities.join(", ") || "unspecified"}].`,
+			const requiredCapabilities = Object.freeze(
+				Array.isArray(msg.requiredCapabilities)
+					? msg.requiredCapabilities
+							.filter((capability): capability is string => typeof capability === "string")
+							.slice(0, MAX_DIAGNOSTIC_CAPABILITIES)
+							.map(capability => boundedDiagnosticText(capability, MAX_DIAGNOSTIC_CAPABILITY_CODE_POINTS))
+					: [],
 			);
+			const diagnostic: TelegramReferenceDiagnostic = Object.freeze({
+				code: "action_unavailable",
+				requiredCapabilities,
+			});
+			logger.warn("Telegram reference client action unavailable", diagnostic);
+			try {
+				opts.onDiagnostic?.(diagnostic);
+			} catch (error) {
+				logger.warn("Telegram reference client diagnostic callback failed", {
+					code: "diagnostic_callback_failed",
+					...boundedDiagnosticCallbackError(error),
+				});
+			}
 			// Diagnostic only: never turn it into a Telegram prompt or option buttons.
 			return;
 		} else if (msg.type === "action_resolved" && msg.id === latestPendingAskId) {