@sayknow-cli/coding-agent 0.3.16 → 0.4.0

package/src/sdk/bus/threaded-inbound.ts

@@ -0,0 +1,141 @@
+/**
+ * Fail-closed routing for inbound Telegram updates in threaded session mode.
+ *
+ * In the threaded surface, a free-text reply inside a session's forum topic
+ * injects a new user turn into that session (steering it at any time). That is
+ * remote control of the agent, so every inbound path must fail closed:
+ *
+ * - the update must come from the single paired chat id;
+ * - it must carry a `message_thread_id` (topic) that maps to a KNOWN session;
+ * - its `update_id` must not have been seen before (idempotency / replay guard);
+ * - the text must be non-empty.
+ *
+ * Anything ambiguous or unmapped is ignored with a reason rather than guessed.
+ * This module is pure (the dedupe set and topic map are injected) so the
+ * security rules are exhaustively unit-testable without a live Bot API.
+ */
+
+/** Minimal shape of the inbound Telegram message we route on. */
+export interface InboundUpdate {
+	update_id?: unknown;
+	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). */
+	pairedChatId: string;
+	/** Resolve a topic/thread id to its owning session id, or undefined. */
+	topicToSession: (threadId: string) => string | undefined;
+	/** Whether this `update_id` has already been processed. */
+	isDuplicate: (updateId: number) => boolean;
+}
+
+/** Outcome of routing an inbound update. */
+export type ThreadedInboundDecision =
+	| {
+			kind: "inject";
+			sessionId: string;
+			text: string;
+			updateId: number;
+			threadId: string;
+			messageId: number;
+			attachment?: InboundAttachment;
+	  }
+	| { kind: "duplicate"; updateId: number }
+	| { kind: "ignore"; reason: string };
+
+function asString(value: unknown): string | undefined {
+	if (typeof value === "string") return value;
+	if (typeof value === "number") return String(value);
+	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
+ * unambiguous, first-seen, paired-chat, known-topic text message.
+ */
+export function decideThreadedInbound(update: InboundUpdate, ctx: ThreadedInboundCtx): ThreadedInboundDecision {
+	const message = update.message;
+	if (!message) return { kind: "ignore", reason: "no_message" };
+
+	const chatId = asString(message.chat?.id);
+	if (chatId === undefined || chatId !== String(ctx.pairedChatId)) {
+		return { kind: "ignore", reason: "wrong_chat" };
+	}
+
+	const threadId = asString(message.message_thread_id);
+	if (threadId === undefined) return { kind: "ignore", reason: "no_topic" };
+
+	const sessionId = ctx.topicToSession(threadId);
+	if (sessionId === undefined) return { kind: "ignore", reason: "unknown_topic" };
+
+	if (typeof update.update_id !== "number" || !Number.isSafeInteger(update.update_id) || update.update_id < 0) {
+		return { kind: "ignore", reason: "missing_update_id" };
+	}
+	const updateId = update.update_id;
+	if (ctx.isDuplicate(updateId)) return { kind: "duplicate", updateId };
+
+	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" };
+
+	if (typeof message.message_id !== "number" || !Number.isSafeInteger(message.message_id) || message.message_id <= 0) {
+		return { kind: "ignore", reason: "missing_message_id" };
+	}
+	const messageId = message.message_id;
+	return { kind: "inject", sessionId, text, updateId, threadId, messageId, attachment };
+}

package/src/sdk/bus/threaded-render.ts

@@ -0,0 +1,294 @@
+/**
+ * Pure rendering of threaded-session frames into Telegram send specs.
+ *
+ * The daemon receives the additive `ServerMessage` frames (identity_header,
+ * context_update, turn_stream, image_attachment, config_update) over the session
+ * WS and must turn each into a Bot API call scoped to the session's forum topic
+ * (`message_thread_id`), throttled through the shared rate-limit pool. This
+ * module is the pure frame→send mapping (including the priority lane and live-
+ * edit coalesce key), so rendering is unit-testable without a live Bot API.
+ */
+
+import { truncate } from "./helpers";
+import { bold, code, escapeHtml, finalizeTelegramHtml, italic, markdownToTelegramHtml, pre } from "./html-format";
+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" | "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). */
+	identity?: boolean;
+	/**
+	 * When true the daemon may deliver this as an in-place edit of the message
+	 * previously sent under the same `(sessionId, coalesceKey)` instead of a new
+	 * message. Set for streamed turn frames so live + finalized share one message.
+	 */
+	editable?: boolean;
+	/** Rich message class metadata. Only finalized final-answer sends are ever
+	 * rich-promoted; the daemon gate (`shouldPromoteRich`) requires exactly this. */
+	richClass?: "final";
+	/** Rich final-answer markdown (raw). Delivery marker derived ONLY from a frame's `finalAnswer` bit; never inferred from `phase`. */
+	richMarkdown?: string;
+	/** Live-turn raw markdown for opt-in draft streaming (set ONLY on non-finalized turn frames; never triggers rich-final promotion, which requires `lane === "finalized"`). */
+	richDraftMarkdown?: string;
+	/**
+	 * True for a terminal tool_activity frame (phase completed/failed/cancelled/
+	 * unknown). The daemon evicts the tool's `tool:<toolCallId>` live-message entry
+	 * after delivering it, so completed tools do not accumulate unbounded across a
+	 * long session (concurrent in-flight `started` entries are retained).
+	 */
+	terminal?: boolean;
+}
+
+interface ThreadedFrame {
+	type?: unknown;
+	sessionId?: unknown;
+	// identity_header
+	repo?: unknown;
+	branch?: unknown;
+	machine?: unknown;
+	title?: unknown;
+	// context_update
+	lastMessage?: unknown;
+	task?: unknown;
+	goal?: unknown;
+	tokenUsage?: unknown;
+	model?: unknown;
+	diff?: unknown;
+	cwd?: unknown;
+	// turn_stream / reasoning_summary
+	phase?: unknown;
+	finalAnswer?: boolean;
+	text?: unknown;
+	messageRef?: unknown;
+	turnRef?: unknown;
+	// tool_activity
+	toolCallId?: unknown;
+	toolName?: unknown;
+	argsSummary?: unknown;
+	resultSummary?: unknown;
+	isError?: unknown;
+	// image_attachment / file_attachment
+	source?: unknown;
+	data?: unknown;
+	mime?: unknown;
+	caption?: unknown;
+	name?: unknown;
+	// config_update
+	verbosity?: unknown;
+	redact?: unknown;
+	// control_command_result
+	status?: unknown;
+	message?: unknown;
+}
+
+function str(v: unknown): string | undefined {
+	return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function isDotOnlyText(value: string): boolean {
+	return /^[.\s]+$/.test(value);
+}
+
+/** Format the one-time identity header as pinned bullets. */
+export function formatIdentityHeader(frame: {
+	repo?: unknown;
+	branch?: unknown;
+	machine?: unknown;
+	sessionId?: unknown;
+	title?: unknown;
+}): string {
+	const title = str(frame.title) ?? "SKC session";
+	const bullets = [
+		`• repo: ${code(str(frame.repo) ?? "?")}`,
+		`• branch: ${code(str(frame.branch) ?? "?")}`,
+		`• machine: ${code(str(frame.machine) ?? "?")}`,
+		`• session: ${code(str(frame.sessionId) ?? "?")}`,
+	];
+	return `${bold(title)}\n${bullets.join("\n")}`;
+}
+
+/** Format a streamed context update into a compact block (omitting empty fields). */
+export function formatContextUpdate(frame: ThreadedFrame): string | undefined {
+	const lines: string[] = [];
+	const session = str(frame.sessionId);
+	const cwd = str(frame.cwd);
+	const last = str(frame.lastMessage);
+	const task = str(frame.task);
+	const goal = str(frame.goal);
+	const usage = str(frame.tokenUsage);
+	const model = str(frame.model);
+	const diff = str(frame.diff);
+	if (!cwd && !last && !task && !goal && !usage && !model && !diff) return undefined;
+	const meta = [session ? `session: ${code(session)}` : undefined, cwd ? `cwd: ${code(cwd)}` : undefined].filter(
+		Boolean,
+	);
+	if (meta.length > 0) lines.push(meta.join(" · "));
+	if (last) lines.push(escapeHtml(truncate(last, 600)));
+	if (task) lines.push(`${italic("task:")} ${escapeHtml(task)}`);
+	if (goal) lines.push(`${italic("goal:")} ${escapeHtml(goal)}`);
+	if (usage || model) lines.push(`ctx: ${code([usage, model].filter(Boolean).join(" · "))}`);
+	if (diff) lines.push(`diff:\n${pre(truncate(diff, 1200))}`);
+	return lines.join("\n");
+}
+
+/**
+ * Map a threaded frame to a Telegram send spec, or `undefined` when there is
+ * nothing to send (e.g. an empty context update or an unknown frame type).
+ */
+export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefined {
+	switch (frame.type) {
+		case "identity_header":
+			return {
+				method: "sendMessage",
+				lane: "finalized",
+				text: finalizeTelegramHtml(formatIdentityHeader(frame)),
+				identity: true,
+			};
+		case "context_update": {
+			const text = finalizeTelegramHtml(formatContextUpdate(frame));
+			return text
+				? { method: "sendMessage", lane: "live", text, coalesceKey: `ctx:${str(frame.sessionId) ?? ""}` }
+				: undefined;
+		}
+		case "turn_stream": {
+			const raw = str(frame.text);
+			if (!raw) return undefined;
+			if (frame.phase === "finalized" && isDotOnlyText(raw)) return undefined;
+			const text = markdownToTelegramHtml(raw);
+			const finalized = frame.phase === "finalized";
+			// A per-turn ref ties the streamed live edits and the finalized text to
+			// ONE message. Without a ref (streaming off), finalized keeps its legacy
+			// keyless behaviour: a fresh message per turn.
+			const ref = str(frame.messageRef);
+			const coalesceKey = finalized
+				? ref
+					? `turn:${ref}`
+					: undefined
+				: `turn:${ref ?? str(frame.sessionId) ?? ""}`;
+			return {
+				method: "sendMessage",
+				lane: finalized ? "finalized" : "live",
+				text,
+				coalesceKey,
+				editable: coalesceKey !== undefined,
+				// Rich-final markers are set ONLY on a non-editable finalized final
+				// (no messageRef / coalesceKey). A streamed (editable) final owns a live
+				// message edited in place, so it is never rich-promoted and carries no
+				// rich marker to leak into split continuations.
+				richClass: frame.finalAnswer === true && coalesceKey === undefined ? "final" : undefined,
+				richMarkdown: frame.finalAnswer === true && coalesceKey === undefined ? raw : undefined,
+				// Live-only draft marker: carries the RAW markdown on non-finalized turn
+				// frames so the opt-in draft gate has the source. It never arms rich-final
+				// promotion (shouldPromoteRich requires lane === "finalized").
+				richDraftMarkdown: finalized ? undefined : raw,
+			};
+		}
+		case "tool_activity": {
+			const toolCallId = str(frame.toolCallId);
+			if (!toolCallId) return undefined;
+			const phase = str(frame.phase);
+			const status =
+				phase === "started"
+					? "started"
+					: phase === "completed" && frame.isError !== true
+						? "ok"
+						: phase === "completed" || phase === "failed"
+							? "error"
+							: phase === "cancelled"
+								? "cancelled"
+								: "unknown";
+			const argsSummary = str(frame.argsSummary);
+			const resultSummary = str(frame.resultSummary);
+			const lines = [`⚙ ${escapeHtml(truncate(str(frame.toolName) ?? "tool", 300))} — ${status}`];
+			if (argsSummary) lines.push(`args:\n${pre(truncate(argsSummary, 1200))}`);
+			if (resultSummary) lines.push(`result:\n${pre(truncate(resultSummary, 1200))}`);
+			return {
+				method: "sendMessage",
+				lane: phase === "started" ? "live" : "finalized",
+				text: finalizeTelegramHtml(lines.join("\n")),
+				coalesceKey: `tool:${toolCallId}`,
+				editable: true,
+				terminal: phase !== "started",
+			};
+		}
+		case "reasoning_summary": {
+			const text = str(frame.text);
+			if (!text) return undefined;
+			const turnRef = str(frame.turnRef);
+			return {
+				method: "sendMessage",
+				lane: "finalized",
+				// markdownToTelegramHtml escapes raw markdown itself; pre-escaping here
+				// would turn entities such as < into visible &amp;lt; text.
+				text: finalizeTelegramHtml(markdownToTelegramHtml(text)),
+				coalesceKey: turnRef ? `reason:${turnRef}` : undefined,
+				editable: turnRef !== undefined,
+			};
+		}
+		case "image_attachment": {
+			const data = str(frame.data);
+			if (!data) return undefined;
+			const caption = str(frame.caption);
+			return {
+				method: "sendPhoto",
+				lane: "finalized",
+				photoBase64: data,
+				mime: str(frame.mime),
+				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;
+			const parts = [verbosity ? `verbosity ${verbosity}` : undefined, redact].filter(Boolean);
+			return parts.length
+				? {
+						method: "sendMessage",
+						lane: "idle",
+						text: finalizeTelegramHtml(`⚙ ${escapeHtml(parts.join(", "))}`),
+					}
+				: undefined;
+		}
+		case "control_command_result": {
+			const message = str(frame.message);
+			if (!message) return undefined;
+			const status = str(frame.status);
+			const prefix = status === "ok" ? "✅" : status === "unavailable" ? "⚠️" : "❌";
+			return {
+				method: "sendMessage",
+				lane: "idle",
+				text: finalizeTelegramHtml(`${prefix} ${escapeHtml(truncate(message, 1200))}`),
+			};
+		}
+		default:
+			return undefined;
+	}
+}