@gajae-code/coding-agent 0.6.4 → 0.7.0

package/src/notifications/rate-limit-pool.ts

@@ -0,0 +1,179 @@
+/**
+ * Host-wide shared Telegram rate-limit pool for the threaded session surface.
+ *
+ * Multiple GJC sessions on one host share a single bot token and paired chat.
+ * Telegram enforces per-bot/per-chat limits (~1 message/sec, bursts up to ~20),
+ * so the singleton notifications daemon owns ONE pool that all per-session
+ * threads draw from. The pool provides:
+ *
+ * - a token bucket (burst capacity + steady refill) modelling the chat limit;
+ * - priority lanes (`ask` > `finalized` > `live` > `idle`) so urgent frames
+ *   win scarce tokens;
+ * - per-session round-robin fairness within a lane so one session's live-edit
+ *   stream cannot starve other sessions;
+ * - coalescing of live edits that share a `coalesceKey` (the latest rendered
+ *   text replaces the queued one) so throttled edit storms collapse.
+ *
+ * The core is a pull-based scheduler with an injectable clock so fairness,
+ * starvation, and burst behaviour are deterministically unit-testable without
+ * real time or a live Bot API.
+ */
+
+/** Delivery lanes in descending priority. */
+export type RateLimitLane = "ask" | "finalized" | "live" | "idle";
+
+/** Lanes ordered from highest to lowest priority. */
+export const LANE_PRIORITY: readonly RateLimitLane[] = ["ask", "finalized", "live", "idle"];
+
+/** A unit of work competing for a send slot. */
+export interface RateLimitItem<T = unknown> {
+	/** Owning session id (used for per-session fairness). */
+	sessionId: string;
+	/** Priority lane. */
+	lane: RateLimitLane;
+	/**
+	 * Optional coalesce key. Submitting another item with the same
+	 * `(sessionId, lane, coalesceKey)` replaces the queued payload with the
+	 * newer one instead of enqueuing a duplicate (used for live edits).
+	 */
+	coalesceKey?: string;
+	/** Opaque payload the caller maps to an actual Telegram send. */
+	payload: T;
+}
+
+/** Options for {@link RateLimitPool}. */
+export interface RateLimitPoolOptions {
+	/** Burst capacity (max tokens). Default 20 (Telegram per-chat burst). */
+	capacity?: number;
+	/** Steady refill rate in tokens per second. Default 1 (~1 msg/sec/chat). */
+	refillPerSec?: number;
+	/** Injectable clock in ms. Default `Date.now`. */
+	now?: () => number;
+}
+
+interface QueuedItem<T> {
+	item: RateLimitItem<T>;
+	seq: number;
+}
+
+/**
+ * A deterministic, pull-based shared rate-limit scheduler.
+ *
+ * Callers {@link submit} work and periodically {@link drain} (e.g. on a timer
+ * or after each submit); `drain` returns the items granted a send slot, in the
+ * order they should be sent.
+ */
+export class RateLimitPool<T = unknown> {
+	private readonly capacity: number;
+	private readonly refillPerSec: number;
+	private readonly now: () => number;
+
+	/** Per-lane FIFO queues; each lane holds items across sessions. */
+	private readonly lanes = new Map<RateLimitLane, QueuedItem<T>[]>();
+	/** Rotating session cursor per lane for round-robin fairness. */
+	private readonly laneCursor = new Map<RateLimitLane, number>();
+
+	private tokens: number;
+	private lastRefill: number;
+	private seqCounter = 0;
+
+	constructor(options: RateLimitPoolOptions = {}) {
+		this.capacity = Math.max(1, options.capacity ?? 20);
+		this.refillPerSec = Math.max(0, options.refillPerSec ?? 1);
+		this.now = options.now ?? Date.now;
+		this.tokens = this.capacity;
+		this.lastRefill = this.now();
+		for (const lane of LANE_PRIORITY) this.lanes.set(lane, []);
+	}
+
+	/** Number of items currently queued across all lanes. */
+	get pending(): number {
+		let total = 0;
+		for (const queue of this.lanes.values()) total += queue.length;
+		return total;
+	}
+
+	/** Current available token count (after refill at `now`). */
+	availableTokens(nowMs: number = this.now()): number {
+		this.refill(nowMs);
+		return this.tokens;
+	}
+
+	/**
+	 * Submit an item. If it carries a `coalesceKey` matching a queued item in
+	 * the same `(sessionId, lane)`, the queued payload is replaced (latest
+	 * wins) and FIFO position is preserved; otherwise it is appended.
+	 */
+	submit(item: RateLimitItem<T>): void {
+		const queue = this.lanes.get(item.lane);
+		if (!queue) throw new Error(`unknown rate-limit lane: ${item.lane}`);
+		if (item.coalesceKey !== undefined) {
+			const existing = queue.find(
+				q => q.item.sessionId === item.sessionId && q.item.coalesceKey === item.coalesceKey,
+			);
+			if (existing) {
+				existing.item = item;
+				return;
+			}
+		}
+		queue.push({ item, seq: this.seqCounter++ });
+	}
+
+	/**
+	 * Grant as many queued items as tokens allow at `nowMs`. Items are selected
+	 * by lane priority, then round-robin across sessions within a lane (so no
+	 * single session monopolises a lane), consuming one token each.
+	 */
+	drain(nowMs: number = this.now()): RateLimitItem<T>[] {
+		this.refill(nowMs);
+		const granted: RateLimitItem<T>[] = [];
+		while (this.tokens >= 1) {
+			const next = this.takeNext();
+			if (!next) break;
+			this.tokens -= 1;
+			granted.push(next);
+		}
+		return granted;
+	}
+
+	private refill(nowMs: number): void {
+		if (nowMs <= this.lastRefill) return;
+		const elapsedSec = (nowMs - this.lastRefill) / 1000;
+		this.tokens = Math.min(this.capacity, this.tokens + elapsedSec * this.refillPerSec);
+		this.lastRefill = nowMs;
+	}
+
+	/** Pop the next item by lane priority + per-session round-robin fairness. */
+	private takeNext(): RateLimitItem<T> | undefined {
+		for (const lane of LANE_PRIORITY) {
+			const queue = this.lanes.get(lane)!;
+			if (queue.length === 0) continue;
+			const picked = this.pickFairIndex(lane, queue);
+			const [removed] = queue.splice(picked, 1);
+			return removed?.item;
+		}
+		return undefined;
+	}
+
+	/**
+	 * Choose the index to serve from a lane queue using round-robin over the
+	 * distinct session ids present, starting just after the last-served
+	 * session. Falls back to FIFO (index 0) when only one session is queued.
+	 */
+	private pickFairIndex(lane: RateLimitLane, queue: QueuedItem<T>[]): number {
+		const sessions: string[] = [];
+		for (const q of queue) if (!sessions.includes(q.item.sessionId)) sessions.push(q.item.sessionId);
+		if (sessions.length <= 1) return 0;
+		const cursor = this.laneCursor.get(lane) ?? 0;
+		// Choose the earliest-queued item whose session is the next in rotation.
+		for (let offset = 0; offset < sessions.length; offset++) {
+			const candidate = sessions[(cursor + offset) % sessions.length]!;
+			const idx = queue.findIndex(q => q.item.sessionId === candidate);
+			if (idx >= 0) {
+				this.laneCursor.set(lane, (cursor + offset + 1) % sessions.length);
+				return idx;
+			}
+		}
+		return 0;
+	}
+}

package/src/notifications/telegram-cli.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env bun
+/**
+ * Reference CLI for the notifications SDK Telegram client.
+ *
+ * Bridges a running GJC session's notification endpoint to a Telegram bot so you
+ * can answer asks / see idle pings from your phone — no RPC mode required. This
+ * is an EXAMPLE/template (the SDK contract is in `docs/notifications-sdk.md`);
+ * Discord/Slack clients are written the same way.
+ *
+ * Usage:
+ *   bun run packages/coding-agent/src/notifications/telegram-cli.ts \
+ *     --bot-token <token> [--chat-id <id>] [--endpoint-file <path> | --session-id <id>] [--repo <dir>]
+ *
+ * Env fallbacks: GJC_TG_BOT_TOKEN, GJC_TG_CHAT_ID.
+ * If --chat-id is omitted it is auto-resolved from getUpdates (message the bot once).
+ * If neither --endpoint-file nor --session-id is given, the newest endpoint file
+ * under <repo>/.gjc/state/notifications/ is used.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@gajae-code/utils";
+import { tokenFingerprint } from "./config";
+import { type DaemonState, daemonPaths, isFreshLiveOwner } from "./telegram-daemon";
+import { runTelegramReferenceClient } from "./telegram-reference";
+
+interface CliArgs {
+	botToken?: string;
+	chatId?: string;
+	endpointFile?: string;
+	sessionId?: string;
+	repo: string;
+	apiBase?: string;
+	force: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	const args: CliArgs = { repo: process.cwd(), force: false };
+	for (let i = 0; i < argv.length; i++) {
+		const next = () => argv[++i];
+		switch (argv[i]) {
+			case "--bot-token":
+				args.botToken = next();
+				break;
+			case "--chat-id":
+				args.chatId = next();
+				break;
+			case "--endpoint-file":
+				args.endpointFile = next();
+				break;
+			case "--session-id":
+				args.sessionId = next();
+				break;
+			case "--repo":
+				args.repo = next() ?? process.cwd();
+				break;
+			case "--api-base":
+				args.apiBase = next();
+				break;
+			case "--force":
+				args.force = true;
+				break;
+			case "-h":
+			case "--help":
+				printHelpAndExit();
+				break;
+			default:
+				break;
+		}
+	}
+	return args;
+}
+
+function printHelpAndExit(): never {
+	process.stdout.write(
+		[
+			"gjc notifications — Telegram reference client",
+			"",
+			"  --bot-token <token>     Telegram bot token (or env GJC_TG_BOT_TOKEN)",
+			"  --chat-id <id>          Target chat id (or env GJC_TG_CHAT_ID; auto-resolved if omitted)",
+			"  --endpoint-file <path>  Session endpoint discovery file",
+			"  --session-id <id>       Resolve <repo>/.gjc/state/notifications/<id>.json",
+			"  --repo <dir>            Repo root for endpoint discovery (default: cwd)",
+			"  --api-base <url>        Telegram API base (default: https://api.telegram.org)",
+			"  --force                 Bypass active daemon guard (debug only; may cause Telegram 409 conflicts)",
+			"",
+		].join("\n"),
+	);
+	process.exit(0);
+}
+
+/** Find the most recently modified endpoint discovery file under the repo. */
+function findLatestEndpoint(repo: string): string | undefined {
+	const dir = path.join(repo, ".gjc", "state", "notifications");
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
+	} catch {
+		return undefined;
+	}
+	let best: { file: string; mtime: number } | undefined;
+	for (const f of entries) {
+		const full = path.join(dir, f);
+		const mtime = fs.statSync(full).mtimeMs;
+		if (!best || mtime > best.mtime) best = { file: full, mtime };
+	}
+	return best?.file;
+}
+
+async function resolveChatId(botToken: string, apiBase: string): Promise<string> {
+	const api = `${apiBase}/bot${botToken}`;
+	for (let i = 0; i < 150; i++) {
+		const body = (await fetch(`${api}/getUpdates`)
+			.then(r => r.json())
+			.catch(() => ({}))) as {
+			result?: Array<Record<string, any>>;
+		};
+		for (const u of body.result ?? []) {
+			const id = u.message?.chat?.id ?? u.callback_query?.message?.chat?.id;
+			if (id !== undefined) return String(id);
+		}
+		if (i === 0) process.stderr.write("Waiting for a message to the bot to resolve the chat id...\n");
+		await new Promise(r => setTimeout(r, 2000));
+	}
+	throw new Error("could not resolve a chat id; send the bot a message first");
+}
+
+function pidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+function readDaemonState(): DaemonState | undefined {
+	try {
+		const raw = fs.readFileSync(daemonPaths(getAgentDir()).state, "utf8");
+		return JSON.parse(raw) as DaemonState;
+	} catch {
+		return undefined;
+	}
+}
+
+function activeDaemonOwnsToken(input: { botToken: string; chatId: string }): boolean {
+	const state = readDaemonState();
+	if (!state) return false;
+	return isFreshLiveOwner({
+		state,
+		now: Date.now(),
+		tokenFingerprint: tokenFingerprint(input.botToken),
+		chatId: input.chatId,
+		pidAlive,
+	});
+}
+
+async function main(): Promise<void> {
+	const args = parseArgs(process.argv.slice(2));
+	const apiBase = args.apiBase ?? "https://api.telegram.org";
+	const botToken = args.botToken ?? process.env.GJC_TG_BOT_TOKEN;
+	if (!botToken) {
+		process.stderr.write("error: --bot-token (or GJC_TG_BOT_TOKEN) is required\n");
+		process.exit(2);
+	}
+
+	const endpointFile =
+		args.endpointFile ??
+		(args.sessionId ? path.join(args.repo, ".gjc", "state", "notifications", `${args.sessionId}.json`) : undefined) ??
+		findLatestEndpoint(args.repo);
+	if (!endpointFile || !fs.existsSync(endpointFile)) {
+		process.stderr.write(
+			`error: no endpoint file found (looked under ${args.repo}/.gjc/state/notifications). Start a session with GJC_NOTIFICATIONS=1 first.\n`,
+		);
+		process.exit(2);
+	}
+
+	const chatId = args.chatId ?? process.env.GJC_TG_CHAT_ID ?? (await resolveChatId(botToken, apiBase));
+	if (!args.force && activeDaemonOwnsToken({ botToken, chatId })) {
+		process.stderr.write(
+			"an active gjc notifications daemon already owns this bot token; running a second poller will cause Telegram 409 conflicts. Re-run with --force to override.\n",
+		);
+		process.exit(1);
+	}
+	process.stderr.write(`notifications: bridging ${endpointFile} <-> Telegram chat ${chatId}\n`);
+	await runTelegramReferenceClient({ botToken, chatId, endpointFile, apiBase });
+}
+
+if (import.meta.main) {
+	main().catch(e => {
+		process.stderr.write(`fatal: ${String(e)}\n`);
+		process.exit(1);
+	});
+}

package/src/notifications/telegram-daemon-cli.ts

@@ -0,0 +1,74 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Settings } from "../config/settings";
+import { getNotificationConfig, isGloballyConfigured } from "./config";
+import { daemonPaths, TelegramNotificationDaemon } from "./telegram-daemon";
+import { clearTelegramControlRequest, readTelegramControlRequest } from "./telegram-daemon-control";
+
+export interface RunDaemonInternalDeps {
+	SettingsImpl?: Pick<typeof Settings, "init">;
+	DaemonImpl?: typeof TelegramNotificationDaemon;
+	processPid?: number;
+}
+
+function argValue(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name);
+	return i >= 0 ? argv[i + 1] : undefined;
+}
+
+export async function runDaemonSmoke(opts: { agentDir?: string } = {}): Promise<void> {
+	const agentDir = opts.agentDir ?? fs.mkdtempSync(path.join(process.cwd(), ".telegram-daemon-smoke-"));
+	const settings = Settings.isolated({});
+	const paths = daemonPaths(agentDir);
+	await fs.promises.mkdir(paths.dir, { recursive: true, mode: 0o700 });
+	const tempLock = `${paths.lock}.smoke.${process.pid}`;
+	const handle = await fs.promises.open(tempLock, "wx", 0o600);
+	await handle.close();
+	await fs.promises.unlink(tempLock);
+	void settings;
+}
+
+export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalDeps = {}): Promise<void> {
+	const smoke = argv.includes("--smoke");
+	const agentDir = argValue(argv, "--agent-dir");
+	if (smoke) return runDaemonSmoke({ agentDir });
+	const ownerId = argValue(argv, "--owner-id");
+	if (!ownerId) throw new Error("missing --owner-id");
+	const settings = await (deps.SettingsImpl ?? Settings).init(agentDir ? { agentDir } : {});
+	const cfg = getNotificationConfig(settings);
+	if (!isGloballyConfigured(cfg) || !cfg.botToken || !cfg.chatId) return;
+	const Daemon = deps.DaemonImpl ?? TelegramNotificationDaemon;
+	const daemon = new Daemon({
+		settings,
+		ownerId,
+		botToken: cfg.botToken,
+		chatId: cfg.chatId,
+		idleTimeoutMs: cfg.idleTimeoutMs,
+		pid: deps.processPid ?? process.pid,
+		control: {
+			shouldStop: async owner => {
+				const req = await readTelegramControlRequest(settings);
+				return Boolean(req && (!req.ownerId || req.ownerId === owner));
+			},
+			clear: async owner => {
+				const req = await readTelegramControlRequest(settings);
+				// Only clear a request that targets this daemon owner, so an exiting
+				// daemon never erases a newer request meant for a different owner.
+				if (req && (!req.ownerId || req.ownerId === owner)) {
+					await clearTelegramControlRequest(settings, req.requestId);
+				}
+			},
+		},
+	});
+	// Signals are a process concern: install them at the daemon-internal boundary,
+	// not inside the embeddable daemon class. SIGTERM is the reload wakeup path.
+	const onSignal = (): void => daemon.requestStop("signal");
+	process.once("SIGTERM", onSignal);
+	process.once("SIGINT", onSignal);
+	try {
+		await daemon.run();
+	} finally {
+		process.off("SIGTERM", onSignal);
+		process.off("SIGINT", onSignal);
+	}
+}