jeopi-cli 16.5.5 → 16.6.1

package/src/messenger/telegram.ts

@@ -0,0 +1,244 @@
+import { logger } from "jeopi-utils";
+import { MessengerHttpError, messengerFetchJson, splitMessengerText, waitForMessengerRetry } from "./http";
+import type { MessengerAdapter, MessengerMessage, MessengerPlatformConfig, MessengerTransportDeps } from "./types";
+
+interface TelegramIdentity {
+	id: number;
+	username: string;
+}
+
+class TelegramApiError extends Error {
+	constructor(
+		readonly status: number,
+		readonly retryAfterMs = 0,
+	) {
+		super("Telegram API request failed");
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value);
+}
+
+function isPositiveId(value: unknown): value is number {
+	return isInteger(value) && value > 0;
+}
+
+function parseIdentity(value: unknown): TelegramIdentity {
+	if (
+		!isRecord(value) ||
+		!isPositiveId(value.id) ||
+		value.is_bot !== true ||
+		typeof value.username !== "string" ||
+		!/^[a-zA-Z0-9_]{1,32}$/.test(value.username)
+	) {
+		throw new TelegramApiError(400);
+	}
+	return { id: value.id, username: value.username };
+}
+
+function stripMention(
+	text: string,
+	entities: unknown,
+	identity: TelegramIdentity,
+): { text: string; mentioned: boolean } {
+	const mention = `@${identity.username.toLowerCase()}`;
+	const ranges: { start: number; end: number }[] = [];
+	if (Array.isArray(entities)) {
+		for (const entity of entities) {
+			if (
+				!isRecord(entity) ||
+				!isInteger(entity.offset) ||
+				!isPositiveId(entity.length) ||
+				entity.offset < 0 ||
+				entity.offset + entity.length > text.length
+			) {
+				continue;
+			}
+			const start = entity.offset;
+			const end = start + entity.length;
+			const value = text.slice(start, end).toLowerCase();
+			if (
+				(entity.type === "mention" && value === mention) ||
+				(entity.type === "text_mention" && isRecord(entity.user) && entity.user.id === identity.id)
+			) {
+				ranges.push({ start, end });
+			} else if (
+				entity.type === "bot_command" &&
+				/^\/[a-z0-9_]+@[a-z0-9_]+$/.test(value) &&
+				value.endsWith(mention)
+			) {
+				ranges.push({ start: end - mention.length, end });
+			}
+		}
+	} else if (entities === undefined) {
+		// Username is validated before interpolation; reject email/name substrings.
+		const pattern = new RegExp(`(^|[^\\p{L}\\p{N}_@])@${identity.username}(?![\\p{L}\\p{N}_])`, "giu");
+		for (const match of text.matchAll(pattern)) {
+			const start = match.index + match[1].length;
+			ranges.push({ start, end: start + mention.length });
+		}
+	}
+	if (ranges.length === 0) return { text, mentioned: false };
+	ranges.sort((left, right) => left.start - right.start);
+	let cursor = 0;
+	let stripped = "";
+	for (const range of ranges) {
+		if (range.start < cursor) continue;
+		stripped += text.slice(cursor, range.start);
+		cursor = range.end;
+	}
+	return { text: (stripped + text.slice(cursor)).trim(), mentioned: true };
+}
+
+function parseMessage(value: unknown, identity: TelegramIdentity): MessengerMessage | undefined {
+	if (
+		!isRecord(value) ||
+		!isPositiveId(value.message_id) ||
+		typeof value.text !== "string" ||
+		!isRecord(value.from) ||
+		!isPositiveId(value.from.id) ||
+		value.from.is_bot !== false ||
+		!isRecord(value.chat) ||
+		!isInteger(value.chat.id) ||
+		value.chat.id === 0 ||
+		(value.chat.type !== "private" && value.chat.type !== "group" && value.chat.type !== "supergroup") ||
+		(value.message_thread_id !== undefined && !isPositiveId(value.message_thread_id)) ||
+		value.edit_date !== undefined ||
+		value.sender_chat !== undefined
+	) {
+		return undefined;
+	}
+	const content = stripMention(value.text, value.entities, identity);
+	const direct = value.chat.type === "private";
+	if (!content.text.trim()) return undefined;
+	return {
+		platform: "telegram",
+		accountId: String(identity.id),
+		channelId: String(value.chat.id),
+		senderId: String(value.from.id),
+		messageId: String(value.message_id),
+		text: content.text,
+		...(value.message_thread_id === undefined ? {} : { threadId: String(value.message_thread_id) }),
+		direct,
+		mentioned: content.mentioned,
+	};
+}
+
+function isPermanent(error: unknown): boolean {
+	if (!(error instanceof TelegramApiError || error instanceof MessengerHttpError)) return false;
+	return error.status >= 400 && error.status < 500 && error.status !== 408 && error.status !== 429;
+}
+
+export function createTelegramAdapter(
+	config: MessengerPlatformConfig,
+	env: Record<string, string | undefined> = process.env,
+	deps: MessengerTransportDeps = {},
+): MessengerAdapter {
+	const token = env[config.tokenEnv];
+	if (!token?.trim()) throw new Error("Telegram bot token is missing");
+	const baseUrl = `https://api.telegram.org/bot${encodeURIComponent(token).replaceAll("%3A", ":")}/`;
+	let running = false;
+	let offset = 0;
+
+	async function request(method: string, parameters: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+		const response = await messengerFetchJson(
+			`${baseUrl}${method}`,
+			{ method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(parameters) },
+			signal,
+			deps.fetch,
+		);
+		if (!isRecord(response) || typeof response.ok !== "boolean") throw new TelegramApiError(400);
+		if (!response.ok) {
+			const status = isInteger(response.error_code) ? response.error_code : 400;
+			const retryAfter = isRecord(response.parameters) ? response.parameters.retry_after : undefined;
+			throw new TelegramApiError(status, isPositiveId(retryAfter) ? Math.min(retryAfter, 300) * 1_000 : 0);
+		}
+		if (!("result" in response)) throw new TelegramApiError(400);
+		return response.result;
+	}
+
+	return {
+		platform: "telegram",
+		async start(onMessage, signal) {
+			if (signal.aborted) return;
+			if (running) throw new Error("Telegram adapter is already running");
+			running = true;
+			const stopped = Promise.withResolvers<void>();
+			const onAbort = () => stopped.resolve();
+			signal.addEventListener("abort", onAbort, { once: true });
+			let identity: TelegramIdentity | undefined;
+			let retryMs = 1_000;
+			try {
+				while (!signal.aborted) {
+					try {
+						identity ??= parseIdentity(await request("getMe", {}, signal));
+						if (signal.aborted) break;
+						const updates = await request(
+							"getUpdates",
+							{ offset, timeout: 25, allowed_updates: ["message"] },
+							signal,
+						);
+						if (!Array.isArray(updates)) throw new TelegramApiError(400);
+						retryMs = 1_000;
+						for (const update of updates) {
+							if (signal.aborted) break;
+							if (
+								!isRecord(update) ||
+								!isInteger(update.update_id) ||
+								update.update_id < 0 ||
+								update.update_id === Number.MAX_SAFE_INTEGER
+							) {
+								throw new TelegramApiError(400);
+							}
+							if (update.update_id < offset) continue;
+							// Acknowledge even ignored/failed callbacks: replaying can duplicate replies.
+							offset = update.update_id + 1;
+							const message = parseMessage(update.message, identity);
+							if (!message) continue;
+							const processing = Promise.resolve()
+								.then(() => onMessage(message))
+								.catch(() => {
+									logger.warn("Telegram message handler failed");
+								});
+							await Promise.race([processing, stopped.promise]);
+						}
+					} catch (error) {
+						if (signal.aborted) break;
+						if (isPermanent(error)) throw new Error("Telegram authentication or polling configuration failed");
+						const delay =
+							error instanceof TelegramApiError || error instanceof MessengerHttpError
+								? Math.max(retryMs, error.retryAfterMs ?? 0)
+								: retryMs;
+						await waitForMessengerRetry(delay, signal);
+						retryMs = Math.min(retryMs * 2, 30_000);
+					}
+				}
+			} finally {
+				signal.removeEventListener("abort", onAbort);
+				running = false;
+			}
+		},
+		async send(message, text, signal) {
+			const threadId = message.threadId === undefined ? undefined : Number(message.threadId);
+			if (threadId !== undefined && !isPositiveId(threadId)) throw new Error("Telegram topic identifier is invalid");
+			for (const chunk of splitMessengerText(text, 4_096)) {
+				// Never retry an ambiguous send failure: Telegram may already have delivered it.
+				const result = await request(
+					"sendMessage",
+					{
+						chat_id: message.channelId,
+						text: chunk,
+						...(threadId === undefined ? {} : { message_thread_id: threadId }),
+					},
+					signal,
+				);
+				if (!isRecord(result) || !isPositiveId(result.message_id)) throw new TelegramApiError(400);
+			}
+		},
+	};
+}

package/src/messenger/types.ts

@@ -0,0 +1,47 @@
+export type MessengerPlatform = "discord" | "telegram" | "slack";
+
+export interface MessengerMessage {
+	platform: MessengerPlatform;
+	accountId: string;
+	channelId: string;
+	senderId: string;
+	messageId: string;
+	text: string;
+	threadId?: string;
+	direct: boolean;
+	mentioned: boolean;
+}
+
+export interface MessengerAdapter {
+	platform: MessengerPlatform;
+	start(onMessage: (message: MessengerMessage) => Promise<void>, signal: AbortSignal): Promise<void>;
+	send(message: MessengerMessage, text: string, signal?: AbortSignal): Promise<void>;
+}
+
+export interface MessengerPlatformConfig {
+	tokenEnv: string;
+	appTokenEnv?: string;
+	allowedUserIds: string[];
+	allowedChannelIds?: string[];
+}
+
+export interface MessengerConfig {
+	cwd: string;
+	sessionDir: string;
+	toolNames: string[];
+	platforms: Partial<Record<MessengerPlatform, MessengerPlatformConfig>>;
+}
+
+export interface MessengerTransportDeps {
+	fetch?: typeof fetch;
+	WebSocket?: typeof WebSocket;
+}
+
+export type MessengerReply = (message: MessengerMessage, signal: AbortSignal) => Promise<string>;
+/** A partially initialized SDK must not be retried inside a live gateway. */
+export class MessengerFatalError extends Error {
+	constructor() {
+		super("Messenger session initialization failed; restart required");
+		this.name = "MessengerFatalError";
+	}
+}

package/src/modes/components/assistant-message.ts

@@ -726,7 +726,7 @@ export class AssistantMessageComponent extends Container {
 		);
 
 		// Fast path: reuse Markdown children when shape is stable during streaming
-		if (this.#tryFastPathUpdate(message)) return;
+		if (this.#tryFastPathUpdate(message, opts)) return;
 
 		// Clear content container
 		this.#contentContainer.clear();

package/src/modes/controllers/streaming-reveal.ts

@@ -215,6 +215,7 @@ export class StreamingRevealController {
 	#component: StreamingRevealComponent | undefined;
 	#timer: NodeJS.Timeout | undefined;
 	#revealed = 0;
+	#targetDirty = false;
 	#hideThinkingBlock = false;
 	#proseOnlyThinking = true;
 	#smoothStreaming = true;
@@ -275,6 +276,9 @@ export class StreamingRevealController {
 		if (!this.#component) return;
 		if (!this.#smoothStreaming) {
 			const total = this.#visibleUnits(message);
+			this.#revealed = total;
+			this.#targetDirty = false;
+			this.#stopTimer();
 			this.#component.updateContent(this.#build(message, total), { transient: true });
 			return;
 		}
@@ -283,6 +287,7 @@ export class StreamingRevealController {
 			// A tool call is a transcript-order boundary: finish any leading
 			// assistant text before EventController renders the separate tool card.
 			this.#revealed = total;
+			this.#targetDirty = false;
 			this.#stopTimer();
 			this.#component.updateContent(this.#build(message, this.#revealed), {
 				transient: true,
@@ -292,8 +297,15 @@ export class StreamingRevealController {
 		if (this.#revealed > total) {
 			this.#revealed = total;
 		}
-		this.#renderCurrent();
-		this.#syncTimer(total);
+		if (this.#revealed < total) {
+			// ponytail: reuse the reveal timer; only add another scheduler if streaming needs a separate cadence.
+			this.#targetDirty = false;
+			this.#syncTimer(total);
+			return;
+		}
+		// Caught-up rewrites still need one render of the newest target at the next tick.
+		this.#startTimer();
+		this.#targetDirty = true;
 	}
 
 	stop(): void {
@@ -301,6 +313,7 @@ export class StreamingRevealController {
 		this.#target = undefined;
 		this.#component = undefined;
 		this.#revealed = 0;
+		this.#targetDirty = false;
 		this.#unitCounter.reset();
 	}
 
@@ -377,6 +390,12 @@ export class StreamingRevealController {
 		}
 		const total = this.#visibleUnits(target);
 		if (this.#revealed >= total) {
+			if (this.#targetDirty) {
+				this.#targetDirty = false;
+				this.#revealed = total;
+				this.#renderCurrent();
+				this.#requestRender();
+			}
 			this.#stopTimer();
 			return;
 		}

package/src/session/session-persistence.ts

@@ -59,9 +59,14 @@ function shouldExternalizeImagePayload(
 	return (key === TEXT_CONTENT_KEY && isImageBlock(value)) || key === "images";
 }
 
+/** Signature and encrypted fields bind their carrier to its exact bytes. */
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
 /**
  * Recursively truncate large strings in an object for session persistence.
- * - Truncates any oversized string fields (key-agnostic)
+ * - Truncates oversized strings except signed/encrypted blocks and signature keys
  * - Externalizes oversized image payloads to blob refs
  * - Updates lineCount when content is truncated
  * - Returns original object if no changes needed (structural sharing)
@@ -76,16 +81,29 @@ function truncateForPersistence(obj: unknown, blobStore: BlobStore, key?: string
 	if (shouldExternalizeImagePayload(obj, key)) {
 		return { ...obj, data: externalizeImageDataSync(blobStore, obj.data, obj.mimeType) };
 	}
+	// Signed content and encrypted reasoning must replay byte-for-byte. Keep the
+	// whole carrier, including paired text and tool arguments; unsigned content
+	// still follows the normal size and transient-field sanitization rules.
+	if (typeof obj === "object" && "type" in obj) {
+		const signed =
+			(obj.type === "thinking" && "thinkingSignature" in obj && isNonEmptyString(obj.thinkingSignature)) ||
+			(obj.type === "text" && "textSignature" in obj && isNonEmptyString(obj.textSignature)) ||
+			(obj.type === "toolCall" && "thoughtSignature" in obj && isNonEmptyString(obj.thoughtSignature));
+		const redacted = obj.type === "redactedThinking" && "data" in obj && isNonEmptyString(obj.data);
+		const encryptedReasoning =
+			obj.type === "reasoning" && "encrypted_content" in obj && isNonEmptyString(obj.encrypted_content);
+		if (signed || redacted || encryptedReasoning) return obj;
+	}
 
 	if (typeof obj === "string") {
 		if (key === "image_url" && isImageDataUrl(obj)) {
 			return externalizeImageDataUrlSync(blobStore, obj);
 		}
 		if (obj.length > MAX_PERSIST_CHARS) {
-			// Cryptographic signatures must be preserved exactly or cleared entirely — never truncated.
-			// Truncation would produce an invalid signature that the API rejects.
+			// Unknown carrier shapes must retain opaque signatures too: clearing or
+			// truncating one loses provider context or makes replay invalid.
 			if (key === "thinkingSignature" || key === "thoughtSignature" || key === "textSignature") {
-				return "";
+				return obj;
 			}
 			const limit = Math.max(0, MAX_PERSIST_CHARS - TRUNCATION_NOTICE.length);
 			return `${truncateString(obj, limit)}${TRUNCATION_NOTICE}`;

package/src/tools/builtin-names.ts

@@ -35,15 +35,24 @@ export const BUILTIN_TOOL_NAMES = [
 
 export type BuiltinToolName = (typeof BUILTIN_TOOL_NAMES)[number];
 
+export const HIDDEN_TOOL_NAMES = ["yield", "report_finding", "report_tool_issue", "resolve", "goal"] as const;
+
 const LEGACY_BUILTIN_TOOL_NAME_ALIASES: ReadonlyMap<string, BuiltinToolName> = new Map([
 	["search", "grep"],
 	["find", "glob"],
 ]);
 
-/** Return the canonical tool name for current and legacy built-in tool IDs. */
+const CANONICAL_TOOL_NAMES: Record<string, true> = Object.fromEntries(
+	[...BUILTIN_TOOL_NAMES, ...HIDDEN_TOOL_NAMES].map(name => [name, true]),
+);
+
+/** Canonicalize built-in IDs and legacy aliases. Leave plugin names unchanged. */
 export function normalizeToolName(name: string): string {
 	const normalized = name.toLowerCase();
-	return LEGACY_BUILTIN_TOOL_NAME_ALIASES.get(normalized) ?? normalized;
+	return (
+		LEGACY_BUILTIN_TOOL_NAME_ALIASES.get(normalized) ??
+		(Object.hasOwn(CANONICAL_TOOL_NAMES, normalized) ? normalized : name)
+	);
 }
 
 /** Normalize and deduplicate tool names while preserving first-seen order. */

package/src/tools/index.ts

@@ -40,7 +40,7 @@ import { AstEditTool } from "./ast-edit";
 import { AstGrepTool } from "./ast-grep";
 import { BashTool } from "./bash";
 import { BrowserTool } from "./browser";
-import { type BuiltinToolName, normalizeToolNames } from "./builtin-names";
+import { type BuiltinToolName, type HIDDEN_TOOL_NAMES, normalizeToolNames } from "./builtin-names";
 import { type CheckpointState, CheckpointTool, type CompletedRewindState, RewindTool } from "./checkpoint";
 import { DebugTool } from "./debug";
 import { EvalTool } from "./eval";
@@ -494,7 +494,7 @@ export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
 	report_tool_issue: s => createReportToolIssueTool(s),
 	resolve: s => new ResolveTool(s),
 	goal: s => new GoalTool(s),
-};
+} satisfies Record<(typeof HIDDEN_TOOL_NAMES)[number], ToolFactory>;
 
 export type ToolName = BuiltinToolName;