@gajae-code/coding-agent 0.7.0 → 0.7.2

package/src/notifications/telegram-daemon.ts

@@ -1,5 +1,7 @@
 import { spawn as childProcessSpawn } from "node:child_process";
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { logger } from "@gajae-code/utils";
 import { withFileLock } from "../config/file-lock";
@@ -19,7 +21,7 @@ import {
 	readEndpoint,
 	routeInboundUpdate,
 } from "./telegram-reference";
-import { decideThreadedInbound } from "./threaded-inbound";
+import { decideThreadedInbound, type InboundAttachment } from "./threaded-inbound";
 import { renderThreadedFrame, type ThreadedSend } from "./threaded-render";
 import { TopicRegistry, type TopicRegistryState } from "./topic-registry";
 
@@ -582,8 +584,14 @@ export class TelegramNotificationDaemon {
 	private readonly fsImpl: TelegramDaemonFs;
 	private readonly botApi: BotApi;
 	private readonly topics = new TopicRegistry();
-	private readonly pool: RateLimitPool<{ send: ThreadedSend; topicId: string }>;
+	private readonly pool: RateLimitPool<{ send: ThreadedSend; topicId?: string }>;
 	private readonly seenUpdateIds = new Set<number>();
+	/** True once the daemon has nudged the user to enable Threaded Mode. */
+	private threadedFallbackNoticeSent = false;
+	/** Sessions whose identity header was already sent flat (Threaded Mode off). */
+	private readonly flatIdentitySent = new Set<string>();
+	/** Cached result of whether the paired chat is a private chat (flat-fallback gate). */
+	private pairedChatPrivate: boolean | undefined;
 	private flushTimer: ReturnType<typeof setInterval> | undefined;
 	private scanTimer: ReturnType<typeof setInterval> | undefined;
 	private scanning = false;
@@ -646,6 +654,35 @@ export class TelegramNotificationDaemon {
 					);
 					return res.json();
 				}
+				const docBody = body as { document?: unknown } | null;
+				if (method === "sendDocument" && docBody && typeof docBody.document === "string") {
+					const b = body as {
+						chat_id: unknown;
+						message_thread_id?: unknown;
+						document: string;
+						mime?: string;
+						fileName?: string;
+						caption?: string;
+						parse_mode?: string;
+					};
+					const form = new FormData();
+					form.set("chat_id", String(b.chat_id));
+					if (b.message_thread_id !== undefined) form.set("message_thread_id", String(b.message_thread_id));
+					if (b.caption) form.set("caption", b.caption);
+					if (b.parse_mode) form.set("parse_mode", String(b.parse_mode));
+					form.set(
+						"document",
+						new Blob([Buffer.from(b.document, "base64")], { type: b.mime ?? "application/octet-stream" }),
+						b.fileName ?? "file",
+					);
+					const res = await fetchWithRetry(
+						fetchImpl,
+						url,
+						{ method: "POST", body: form, signal: callOpts?.signal },
+						sleep,
+					);
+					return res.json();
+				}
 				const res = await fetchWithRetry(
 					fetchImpl,
 					url,
@@ -660,7 +697,7 @@ export class TelegramNotificationDaemon {
 				return res.json();
 			},
 		};
-		this.pool = new RateLimitPool<{ send: ThreadedSend; topicId: string }>({ now: opts.now });
+		this.pool = new RateLimitPool<{ send: ThreadedSend; topicId?: string }>({ now: opts.now });
 	}
 
 	async loadAliases(): Promise<void> {
@@ -797,6 +834,7 @@ export class TelegramNotificationDaemon {
 		"context_update",
 		"turn_stream",
 		"image_attachment",
+		"file_attachment",
 		"config_update",
 	]);
 
@@ -815,8 +853,9 @@ export class TelegramNotificationDaemon {
 
 	/**
 	 * Resolve (creating once via `createForumTopic`) the forum topic for a
-	 * session. Threaded mode is required: on capability failure this returns
-	 * `undefined` and the caller drops the send (no flat fallback).
+	 * session. On capability failure (e.g. Threaded Mode off) this returns
+	 * `undefined`; callers then flat-deliver to a private paired chat (with a
+	 * one-time nudge) or drop fail-closed for a non-private chat.
 	 */
 	private async ensureTopic(sessionId: string, name: string): Promise<string | undefined> {
 		const existing = this.topics.get(sessionId);
@@ -857,26 +896,140 @@ export class TelegramNotificationDaemon {
 		if (raw && typeof raw === "object") this.topics.load(raw);
 	}
 
+	/** Download a Telegram file by its file_path (from getFile) into memory. */
+	private async downloadTelegramFile(filePath: string): Promise<Buffer | undefined> {
+		const apiBase = this.opts.apiBase ?? "https://api.telegram.org";
+		const fetchImpl = this.opts.fetchImpl ?? fetch;
+		// `filePath` is remote metadata from getFile; reject suspicious segments
+		// (traversal/absolute/backslash) and percent-encode each component before
+		// composing the download URL.
+		if (filePath.includes("..") || filePath.startsWith("/") || filePath.includes("\\")) {
+			logger.warn("notifications: rejecting suspicious Telegram file_path");
+			return undefined;
+		}
+		const encodedPath = filePath.split("/").map(encodeURIComponent).join("/");
+		const url = `${apiBase}/file/bot${this.opts.botToken}/${encodedPath}`;
+		try {
+			const res = await fetchImpl(url);
+			if (!res.ok) return undefined;
+			return Buffer.from(await res.arrayBuffer());
+		} catch (e) {
+			logger.warn(`notifications: file download failed: ${String(e)}`);
+			return undefined;
+		}
+	}
+
+	/**
+	 * Per-session private temp directories (mode 0700) holding inbound non-image
+	 * attachments. Keyed by session id and reused across transient reconnects;
+	 * removed when the daemon stops (see {@link cleanupAllAttachmentDirs}).
+	 */
+	private readonly attachmentDirs = new Map<string, string>();
+
+	/** Lazily create a private, unguessable 0700 temp dir for `sessionId`. */
+	private async ensureAttachmentDir(sessionId: string): Promise<string> {
+		const existing = this.attachmentDirs.get(sessionId);
+		if (existing) return existing;
+		// mkdtemp creates a directory with an unguessable suffix and 0700 perms;
+		// chmod defensively in case of an unusual platform/umask.
+		const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "gjc-telegram-"));
+		await fs.promises.chmod(dir, 0o700).catch(() => undefined);
+		this.attachmentDirs.set(sessionId, dir);
+		return dir;
+	}
+
+	/** Remove all per-session attachment directories. Called on daemon shutdown. */
+	private async cleanupAllAttachmentDirs(): Promise<void> {
+		const dirs = [...this.attachmentDirs.values()];
+		this.attachmentDirs.clear();
+		await Promise.all(dirs.map(dir => fs.promises.rm(dir, { recursive: true, force: true }).catch(() => undefined)));
+	}
+
+	/**
+	 * Resolve an inbound attachment to inline image bytes (forwarded as images) or
+	 * a securely-saved file path note (non-images). Non-image bytes are written
+	 * into a private per-session temp dir (0700) under an unguessable name via an
+	 * exclusive 0600 create (`wx`), so the files are not world-readable and the
+	 * write never follows a pre-existing symlink. The directory is removed when the
+	 * daemon stops. Returns base64 images to inline plus human-readable file notes
+	 * to append to the injected text.
+	 */
+	private async resolveInboundAttachment(
+		att: InboundAttachment,
+		sessionId: string,
+	): Promise<{ images: { data: string; mime?: string }[]; fileNotes: string[] }> {
+		const images: { data: string; mime?: string }[] = [];
+		const fileNotes: string[] = [];
+		const label = att.fileName ?? att.kind;
+		try {
+			const got = (await this.botApi.call("getFile", { file_id: att.fileId })) as {
+				result?: { file_path?: unknown };
+			};
+			const filePath = typeof got?.result?.file_path === "string" ? got.result.file_path : undefined;
+			if (!filePath) {
+				fileNotes.push(`[attachment unavailable: ${label}]`);
+				return { images, fileNotes };
+			}
+			const bytes = await this.downloadTelegramFile(filePath);
+			if (!bytes) {
+				fileNotes.push(`[attachment download failed: ${label}]`);
+				return { images, fileNotes };
+			}
+			const isImage = att.kind === "photo" || (typeof att.mime === "string" && att.mime.startsWith("image/"));
+			if (isImage) {
+				images.push({ data: bytes.toString("base64"), mime: att.mime ?? "image/jpeg" });
+			} else {
+				const safeBase =
+					(att.fileName?.trim() || path.basename(filePath) || `${att.kind}-${att.fileId}`)
+						.replace(/[^\w.-]+/g, "_") // drop path separators and unusual chars
+						.replace(/\.\.+/g, "_") // neutralize any ".." traversal-looking runs
+						.replace(/^[.-]+/, "_") // no leading dot/hyphen
+						.slice(-128) || "file";
+				const dir = await this.ensureAttachmentDir(sessionId);
+				// Unguessable, non-colliding name inside the private 0700 dir; the
+				// exclusive 0600 create (`wx`) refuses to follow a pre-existing file/symlink.
+				const dest = path.join(dir, `${crypto.randomBytes(8).toString("hex")}-${safeBase}`);
+				await fs.promises.writeFile(dest, bytes, { flag: "wx", mode: 0o600 });
+				fileNotes.push(`[user attached a file, saved to ${dest}${att.mime ? ` (${att.mime})` : ""}]`);
+			}
+		} catch (e) {
+			logger.warn(`notifications: inbound attachment failed: ${String(e)}`);
+			fileNotes.push(`[attachment error: ${label}]`);
+		}
+		return { images, fileNotes };
+	}
+
 	/** Drain the shared rate-limit pool and deliver each granted send to its topic. */
 	private async flushPool(): Promise<void> {
 		for (const item of this.pool.drain()) {
 			const { send, topicId } = item.payload;
-			const thread = Number(topicId);
+			// Threaded topic when available; otherwise deliver flat to the paired chat.
+			const threadField = topicId ? { message_thread_id: Number(topicId) } : {};
 			try {
 				if (send.method === "sendPhoto" && send.photoBase64) {
 					// Real photo upload (the default botApi multiparts base64 -> file).
 					await this.botApi.call("sendPhoto", {
 						chat_id: this.opts.chatId,
-						message_thread_id: thread,
+						...threadField,
 						photo: send.photoBase64,
 						mime: send.mime,
 						caption: send.text,
 						parse_mode: TELEGRAM_PARSE_MODE,
 					});
+				} else if (send.method === "sendDocument" && send.documentBase64) {
+					await this.botApi.call("sendDocument", {
+						chat_id: this.opts.chatId,
+						...threadField,
+						document: send.documentBase64,
+						mime: send.mime,
+						fileName: send.fileName,
+						caption: send.text,
+						parse_mode: TELEGRAM_PARSE_MODE,
+					});
 				} else if (send.text) {
 					await this.botApi.call("sendMessage", {
 						chat_id: this.opts.chatId,
-						message_thread_id: thread,
+						...threadField,
 						text: send.text,
 						parse_mode: TELEGRAM_PARSE_MODE,
 					});
@@ -887,6 +1040,57 @@ export class TelegramNotificationDaemon {
 		}
 	}
 
+	/**
+	 * Threaded Mode is unavailable (the bot owner has not enabled forum topics in
+	 * @BotFather, so `createForumTopic` fails). Deliver the rendered frame flat to
+	 * the paired chat instead of dropping it, and nudge the user once. Flat delivery
+	 * is gated on the paired chat being a private chat: for a group/supergroup/channel
+	 * (e.g. a legacy or hand-edited `chatId`) we keep dropping fail-closed so session
+	 * content never lands in a shared chat. Identity headers are sent at most once per
+	 * session in flat mode.
+	 */
+	private async deliverFlatFallback(sessionId: string, send: ThreadedSend): Promise<void> {
+		if (!(await this.pairedChatIsPrivate())) return;
+		await this.notifyThreadedFallback();
+		if (send.identity && this.flatIdentitySent.has(sessionId)) return;
+		this.pool.submit({ sessionId, lane: send.lane, coalesceKey: send.coalesceKey, payload: { send } });
+		await this.flushPool();
+		if (send.identity) this.flatIdentitySent.add(sessionId);
+	}
+
+	/**
+	 * Resolve once (cached) whether the paired `chatId` is a private chat. Flat
+	 * fallback is only safe in a private DM; any non-private chat or an unresolvable
+	 * `getChat` is treated as not-private so delivery fails closed.
+	 */
+	private async pairedChatIsPrivate(): Promise<boolean> {
+		if (this.pairedChatPrivate !== undefined) return this.pairedChatPrivate;
+		try {
+			const res = (await this.botApi.call("getChat", { chat_id: this.opts.chatId })) as {
+				result?: { type?: string };
+			};
+			this.pairedChatPrivate = res.result?.type === "private";
+		} catch {
+			this.pairedChatPrivate = false;
+		}
+		return this.pairedChatPrivate;
+	}
+
+	/** Tell the user once (per daemon run) how to enable Threaded Mode. */
+	private async notifyThreadedFallback(): Promise<void> {
+		if (this.threadedFallbackNoticeSent) return;
+		this.threadedFallbackNoticeSent = true;
+		try {
+			await this.botApi.call("sendMessage", {
+				chat_id: this.opts.chatId,
+				text: "turn on threaded mode from botfather miniapp to receive gjc notification!",
+				parse_mode: TELEGRAM_PARSE_MODE,
+			});
+		} catch {
+			// Best-effort nudge; never block delivery.
+		}
+	}
+
 	private startFlushTimer(): void {
 		if (this.flushTimer) return;
 		const setIntervalImpl = this.opts.setIntervalImpl ?? setInterval;
@@ -1015,7 +1219,10 @@ export class TelegramNotificationDaemon {
 			const send = renderThreadedFrame(msg);
 			if (!send) return;
 			const topicId = await this.ensureTopic(session.sessionId, this.topicNameFor(session.sessionId, msg));
-			if (!topicId) return;
+			if (!topicId) {
+				await this.deliverFlatFallback(session.sessionId, send);
+				return;
+			}
 			if (send.identity) {
 				// Rename the topic if the title changed (e.g. the session title was
 				// auto-generated after the topic was first created). This runs on
@@ -1058,7 +1265,12 @@ export class TelegramNotificationDaemon {
 		if (msg.type === "action_needed" && msg.id) {
 			if (msg.kind === "ask") session.pending.set(msg.id, { sessionId: session.sessionId, actionId: msg.id });
 			const topicId = await this.ensureTopic(session.sessionId, this.topicNameFor(session.sessionId, msg));
-			if (!topicId) return;
+			if (!topicId) {
+				// Fail closed for non-private chats; only nudge + flat-deliver in a private DM.
+				if (!(await this.pairedChatIsPrivate())) return;
+				await this.notifyThreadedFallback();
+			}
+			const threadField = topicId ? { message_thread_id: Number(topicId) } : {};
 			const rendered = buildActionMessage({
 				kind: msg.kind ?? "ask",
 				id: msg.id,
@@ -1074,7 +1286,7 @@ export class TelegramNotificationDaemon {
 			);
 			const result = (await this.botApi.call("sendMessage", {
 				chat_id: this.opts.chatId,
-				message_thread_id: Number(topicId),
+				...threadField,
 				text: rendered.text,
 				parse_mode: TELEGRAM_PARSE_MODE,
 				...(inline_keyboard.length ? { reply_markup: { inline_keyboard } } : {}),
@@ -1138,12 +1350,19 @@ export class TelegramNotificationDaemon {
 				this.seenUpdateIds.add(inbound.updateId);
 				const session = this.sessions.get(inbound.sessionId);
 				if (session?.ws.readyState === WebSocket.OPEN) {
-					const cfg = parseInThreadConfigCommand(inbound.text);
+					const attachmentResult = inbound.attachment
+						? await this.resolveInboundAttachment(inbound.attachment, inbound.sessionId)
+						: undefined;
+					const images = attachmentResult?.images ?? [];
+					const fileNotes = attachmentResult?.fileNotes ?? [];
+					const hasMedia = images.length > 0 || fileNotes.length > 0;
+					const injectedText = [inbound.text, ...fileNotes].filter(Boolean).join("\n");
+					const cfg = hasMedia ? undefined : parseInThreadConfigCommand(inbound.text);
 					// A plain (non-config) message while an ask is pending for this session
 					// answers that ask as free-input — instead of starting a new user turn.
 					// Telegram asks always accept custom text (the SDK maps a string answer
 					// to the ask's custom-input slot), so route the latest pending ask here.
-					const pendingAsk = cfg ? undefined : [...session.pending.values()].at(-1);
+					const pendingAsk = cfg || hasMedia ? undefined : [...session.pending.values()].at(-1);
 					if (pendingAsk) {
 						session.ws.send(
 							JSON.stringify({
@@ -1163,10 +1382,11 @@ export class TelegramNotificationDaemon {
 								: {
 										type: "user_message",
 										sessionId: inbound.sessionId,
-										text: inbound.text,
+										text: injectedText,
 										token: session.token,
 										updateId: inbound.updateId,
 										threadId: inbound.threadId,
+										images,
 									},
 						),
 					);
@@ -1343,6 +1563,7 @@ export class TelegramNotificationDaemon {
 			this.stopFlushTimer();
 			this.stopScanTimer();
 			this.stopTypingTimer();
+			await this.cleanupAllAttachmentDirs();
 			// Persist durable state before releasing ownership so a fresh daemon
 			// (e.g. after reload) reloads aliases/topics seamlessly.
 			await this.persistAliases().catch(() => undefined);

package/src/notifications/threaded-inbound.ts

@@ -21,11 +21,30 @@ export interface InboundUpdate {
 	message?: {
 		message_id?: unknown;
 		text?: unknown;
+		caption?: unknown;
+		photo?: unknown;
+		document?: unknown;
+		video?: unknown;
+		audio?: unknown;
+		voice?: unknown;
+		animation?: unknown;
 		chat?: { id?: unknown };
 		message_thread_id?: unknown;
 	};
 }
 
+/** A downloadable media attachment referenced by an inbound message. */
+export interface InboundAttachment {
+	/** Telegram file_id to resolve via getFile. */
+	fileId: string;
+	/** Source media kind; "photo" is always an image. */
+	kind: "photo" | "document" | "video" | "audio" | "voice" | "animation";
+	/** MIME type when Telegram provides one. */
+	mime?: string;
+	/** Original file name when provided. */
+	fileName?: string;
+}
+
 /** Context for {@link decideThreadedInbound}. All lookups are injected. */
 export interface ThreadedInboundCtx {
 	/** The single paired chat id (string-compared). */
@@ -38,7 +57,15 @@ export interface ThreadedInboundCtx {
 
 /** Outcome of routing an inbound update. */
 export type ThreadedInboundDecision =
-	| { kind: "inject"; sessionId: string; text: string; updateId: number; threadId: string; messageId?: number }
+	| {
+			kind: "inject";
+			sessionId: string;
+			text: string;
+			updateId: number;
+			threadId: string;
+			messageId?: number;
+			attachment?: InboundAttachment;
+	  }
 	| { kind: "duplicate"; updateId: number }
 	| { kind: "ignore"; reason: string };
 
@@ -48,6 +75,29 @@ function asString(value: unknown): string | undefined {
 	return undefined;
 }
 
+function extractAttachment(message: NonNullable<InboundUpdate["message"]>): InboundAttachment | undefined {
+	if (Array.isArray(message.photo) && message.photo.length > 0) {
+		const photo = message.photo[message.photo.length - 1];
+		if (photo && typeof photo === "object" && "file_id" in photo && typeof photo.file_id === "string") {
+			return { fileId: photo.file_id, kind: "photo", mime: "image/jpeg" };
+		}
+	}
+
+	for (const kind of ["document", "video", "audio", "voice", "animation"] as const) {
+		const file = message[kind];
+		if (file && typeof file === "object" && "file_id" in file && typeof file.file_id === "string") {
+			return {
+				fileId: file.file_id,
+				kind,
+				mime: "mime_type" in file && typeof file.mime_type === "string" ? file.mime_type : undefined,
+				fileName: "file_name" in file && typeof file.file_name === "string" ? file.file_name : undefined,
+			};
+		}
+	}
+
+	return undefined;
+}
+
 /**
  * Decide whether an inbound update should inject a user turn. Fail-closed:
  * returns `ignore` (with a reason) or `duplicate` for anything that is not an
@@ -72,9 +122,15 @@ export function decideThreadedInbound(update: InboundUpdate, ctx: ThreadedInboun
 	const updateId = update.update_id;
 	if (ctx.isDuplicate(updateId)) return { kind: "duplicate", updateId };
 
-	const text = typeof message.text === "string" ? message.text.trim() : "";
-	if (!text) return { kind: "ignore", reason: "empty_text" };
+	const text =
+		typeof message.text === "string"
+			? message.text.trim()
+			: typeof message.caption === "string"
+				? message.caption.trim()
+				: "";
+	const attachment = extractAttachment(message);
+	if (!text && attachment === undefined) return { kind: "ignore", reason: "empty_text" };
 
 	const messageId = typeof message.message_id === "number" ? message.message_id : undefined;
-	return { kind: "inject", sessionId, text, updateId, threadId, messageId };
+	return { kind: "inject", sessionId, text, updateId, threadId, messageId, attachment };
 }

package/src/notifications/threaded-render.ts

@@ -15,15 +15,19 @@ import type { RateLimitLane } from "./rate-limit-pool";
 
 /** A Telegram send derived from a threaded frame (topic id is applied by the daemon). */
 export interface ThreadedSend {
-	method: "sendMessage" | "sendPhoto";
+	method: "sendMessage" | "sendPhoto" | "sendDocument";
 	/** Rate-limit lane for prioritisation/fairness. */
 	lane: RateLimitLane;
 	/** Message text (sendMessage) or photo caption (sendPhoto). */
 	text?: string;
 	/** Base64 image bytes for sendPhoto. */
 	photoBase64?: string;
+	/** Base64 file bytes for sendDocument. */
+	documentBase64?: string;
 	/** Image MIME type for sendPhoto. */
 	mime?: string;
+	/** Suggested document filename. */
+	fileName?: string;
 	/** Coalesce key for live edits (same key collapses to the latest). */
 	coalesceKey?: string;
 	/** True for the one-time identity header (the daemon pins it once). */
@@ -49,11 +53,12 @@ interface ThreadedFrame {
 	phase?: unknown;
 	text?: unknown;
 	messageRef?: unknown;
-	// image_attachment
+	// image_attachment / file_attachment
 	source?: unknown;
 	data?: unknown;
 	mime?: unknown;
 	caption?: unknown;
+	name?: unknown;
 	// config_update
 	verbosity?: unknown;
 	redact?: unknown;
@@ -141,6 +146,19 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 				text: finalizeTelegramHtml(caption === undefined ? undefined : escapeHtml(caption)),
 			};
 		}
+		case "file_attachment": {
+			const data = str(frame.data);
+			if (!data) return undefined;
+			const caption = str(frame.caption);
+			return {
+				method: "sendDocument",
+				lane: "finalized",
+				documentBase64: data,
+				mime: str(frame.mime),
+				fileName: str(frame.name),
+				text: finalizeTelegramHtml(caption === undefined ? undefined : escapeHtml(caption)),
+			};
+		}
 		case "config_update": {
 			const verbosity = str(frame.verbosity);
 			const redact = typeof frame.redact === "boolean" ? `redact ${frame.redact ? "on" : "off"}` : undefined;