@gajae-code/coding-agent 0.6.5 → 0.7.1

package/dist/types/setup/credential-auto-import.d.ts

@@ -0,0 +1,63 @@
+import type { AuthCredentialIfAbsentReason, AuthCredentialIfAbsentSnapshotResult, AuthStorage } from "@gajae-code/ai";
+import type { ModelRegistry } from "../config/model-registry";
+import { type CredentialDiscoveryResult, type CredentialOrigin, type DiscoveryOptions, type ImportableCredential } from "./credential-import";
+export declare const CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING = "Refreshing in gjc may log out the Claude/Codex CLI because OAuth refresh tokens can rotate.";
+export type CredentialAutoImportSourceLabel = "claude-code-file" | "claude-code-keychain" | "codex-file";
+export type CredentialAutoImportTrigger = "startup" | "bare-login" | "setup-cli";
+export declare function getCredentialAutoImportStatePath(agentDir?: string): string;
+export declare function readCredentialImportMarker(agentDir?: string): Promise<string | undefined>;
+export declare function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean>;
+export declare enum CredentialAutoImportFailureClass {
+    DiscoveryUnavailable = "discovery-unavailable",
+    SourceUnreadable = "source-unreadable",
+    SourceMalformed = "source-malformed",
+    KeychainDenied = "keychain-denied",
+    WriteInvalid = "write-invalid",
+    WriteConflict = "write-conflict",
+    BrokerUnavailable = "broker-unavailable",
+    BrokerUnsupported = "broker-unsupported",
+    Unknown = "unknown"
+}
+export interface CredentialAutoImportSkipped {
+    credential: ImportableCredential;
+    reason: AuthCredentialIfAbsentReason;
+    entries: AuthCredentialIfAbsentSnapshotResult["entries"];
+}
+export interface CredentialAutoImportFailure {
+    credential?: ImportableCredential;
+    origin?: CredentialOrigin;
+    source?: string;
+    failureClass: CredentialAutoImportFailureClass;
+}
+export interface CredentialAutoImportResult {
+    imported: ImportableCredential[];
+    skipped: CredentialAutoImportSkipped[];
+    failures: CredentialAutoImportFailure[];
+    discovered: boolean;
+    discovery?: CredentialDiscoveryResult;
+    globalDiscoveryFailure?: CredentialAutoImportFailure;
+}
+export type CredentialAutoImportAuthStorage = Pick<AuthStorage, "importCredentialIfAbsent">;
+export interface CredentialAutoImportOptions {
+    authStorage: CredentialAutoImportAuthStorage;
+    discover?: (options?: DiscoveryOptions) => Promise<CredentialDiscoveryResult>;
+    discoveryOptions?: DiscoveryOptions;
+    trigger: CredentialAutoImportTrigger;
+    sourceLabel?: CredentialAutoImportSourceLabel;
+}
+export declare function runExternalCredentialAutoImport({ authStorage, discover, discoveryOptions }: CredentialAutoImportOptions): Promise<CredentialAutoImportResult>;
+export declare function buildCredentialAutoImportNotice(result: Pick<CredentialAutoImportResult, "imported">): string | undefined;
+export declare function formatCredentialAutoImportResult(result: CredentialAutoImportResult): string[];
+export interface CredentialImportMarkerStore {
+    read: () => Promise<string | undefined> | string | undefined;
+    write: (version: string) => Promise<boolean> | boolean;
+}
+export interface StartupCredentialAutoImportOptions {
+    authStorage: CredentialAutoImportOptions["authStorage"];
+    modelRegistry: Pick<ModelRegistry, "refresh">;
+    discover?: CredentialAutoImportOptions["discover"];
+    version?: string;
+    agentDir?: string;
+    markerStore?: CredentialImportMarkerStore;
+}
+export declare function runStartupCredentialAutoImportIfNeeded({ authStorage: activeAuthStorage, modelRegistry: activeModelRegistry, discover, version, agentDir, markerStore }: StartupCredentialAutoImportOptions): Promise<string | undefined>;

package/dist/types/setup/credential-import.d.ts

@@ -3,6 +3,7 @@ import type { AuthCredential } from "@gajae-code/ai";
 export type ExternalProvider = "anthropic" | "openai-codex";
 /** Where a discovered credential came from. */
 export type CredentialOrigin = "claude-code-file" | "claude-code-keychain" | "codex-file";
+export declare const AUTO_IMPORT_OAUTH_PROVIDER_ORIGINS: Record<ExternalProvider, ReadonlySet<CredentialOrigin>>;
 /** Human labels for providers, used in redacted summaries. */
 export declare const EXTERNAL_PROVIDER_LABELS: Record<ExternalProvider, string>;
 /** A credential that can be safely imported into gjc's store. */
@@ -72,6 +73,8 @@ export declare function discoverExternalCredentials(options?: DiscoveryOptions):
 export declare function formatCredentialSummary(credential: ImportableCredential): string;
 /** Redacted summary lines for an entire discovery result. Never includes secrets. */
 export declare function formatDiscoverySummary(result: CredentialDiscoveryResult): string[];
+export declare function isAutoImportOAuthCredential(credential: ImportableCredential): boolean;
+export declare function filterAutoImportOAuthCredentials(credentials: readonly ImportableCredential[]): ImportableCredential[];
 /**
  * Persist discovered credentials via `upsert`. Each credential is imported
  * independently; a failure on one is recorded without aborting the rest.

package/dist/types/setup/host-plugin-setup.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Host plugin setup for `gjc setup claude` and `gjc setup codex`.
+ *
+ * Renders install guidance and a fail-closed coordinator MCP config preview for
+ * the canonical generated plugin bundle under `plugins/`. This is intentionally
+ * render-only and fail-closed: the workdir allowlist is scoped to the project
+ * root and no mutation class is enabled until the user opts in.
+ */
+export type HostPluginKind = "claude" | "codex";
+export interface HostPluginSetupFlags {
+    json?: boolean;
+    check?: boolean;
+    root?: string[];
+    repo?: string;
+}
+export interface HostPluginSetupResult {
+    ok: true;
+    host: HostPluginKind;
+    mode: "render";
+    gated: boolean;
+    pluginPath: string;
+    manifestPath: string;
+    marketplacePath: string;
+    installGuidance: string[];
+    coordinatorConfigPreview: {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+    mutationPolicy: string;
+    notes: string[];
+    check?: {
+        ok: boolean;
+        checked: string[];
+        missing: string[];
+    };
+}
+export declare function buildHostPluginSetup(host: HostPluginKind, flags?: HostPluginSetupFlags): HostPluginSetupResult;
+export declare function formatHostPluginSetup(result: HostPluginSetupResult): string;

package/dist/types/tools/ask-answer-registry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Process-wide registry mapping a session id to its active {@link AskAnswerSource}.
+ *
+ * Decouples the `ask` tool (which reads the source via `AgentSession`) from the
+ * notifications extension (which registers one), without threading a new method
+ * through the extension/runner/controller wiring. A session has at most one
+ * source; registering returns a disposer.
+ */
+import type { AskAnswerSource } from "./index";
+/** Register `source` for `sessionId`. Returns a disposer that clears it. */
+export declare function registerAskAnswerSource(sessionId: string, source: AskAnswerSource): () => void;
+/** The answer source for `sessionId`, if one is registered. */
+export declare function getAskAnswerSource(sessionId: string): AskAnswerSource | undefined;

package/dist/types/tools/index.d.ts

@@ -68,6 +68,17 @@ export type ContextFileEntry = {
 };
 export type { DiscoverableMCPTool } from "../runtime-mcp/discoverable-tool-metadata";
 export type { DiscoverableTool, DiscoverableToolSearchIndex, DiscoverableToolSearchResult, DiscoverableToolSource, } from "../tool-discovery/tool-index";
+/**
+ * Source of remote answers for interactive asks (e.g. a Telegram reply routed
+ * through the notifications SDK). Lets a pending ask resolve without RPC mode.
+ */
+export interface AskAnswerSource {
+    /**
+     * Race a remote answer against the local UI for one question. Resolves with the
+     * chosen option label or free-text answer, or `undefined` to defer to local UI.
+     */
+    awaitAnswer(question: string, options: string[], signal?: AbortSignal): Promise<string | undefined>;
+}
 /** Session context for tool factories */
 export interface ToolSession {
     /** Current working directory */
@@ -167,6 +178,13 @@ export interface ToolSession {
     getGoalModeState?: () => GoalModeState | undefined;
     /** Unattended workflow-gate emitter (present only when unattended mode is negotiated). */
     getWorkflowGateEmitter?: () => WorkflowGateEmitter | undefined;
+    /**
+     * Optional remote answer source for interactive asks. When present, the ask
+     * tool races the local UI selection against a remote answer (e.g. a Telegram
+     * reply via the notifications SDK) so asks can be answered without RPC mode.
+     * No-op when undefined: the ask path behaves exactly as before.
+     */
+    getAskAnswerSource?: () => AskAnswerSource | undefined;
     /** Optional per-session restriction for goal tool operations. */
     goalToolAllowedOps?: readonly ("create" | "get" | "complete" | "resume" | "drop" | "pause")[];
     /** Goal runtime for the active agent session. */

package/dist/types/tools/subagent.d.ts

@@ -42,6 +42,9 @@ export interface SubagentSnapshot {
     outputRef?: string;
     truncated?: boolean;
     guidance?: string;
+    steerMessage?: string;
+    steerState?: "queued" | "resume_queued" | "resume_started";
+    steerPauseRequested?: boolean;
     /** Live streaming progress for the awaited subagent (await panel only; UI detail). */
     progress?: AgentProgress;
     /** True when a live in-session progress producer exists for this subagent. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.6.5",
+	"version": "0.7.1",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -51,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.6.5",
-		"@gajae-code/agent-core": "0.6.5",
-		"@gajae-code/ai": "0.6.5",
-		"@gajae-code/natives": "0.6.5",
-		"@gajae-code/tui": "0.6.5",
-		"@gajae-code/utils": "0.6.5",
+		"@gajae-code/stats": "0.7.1",
+		"@gajae-code/agent-core": "0.7.1",
+		"@gajae-code/ai": "0.7.1",
+		"@gajae-code/natives": "0.7.1",
+		"@gajae-code/tui": "0.7.1",
+		"@gajae-code/utils": "0.7.1",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/build-binary.ts

@@ -66,6 +66,9 @@ async function main(): Promise<void> {
 					"../stats/src/sync-worker.ts",
 					"./src/tools/browser/tab-worker-entry.ts",
 					"./src/eval/js/worker-entry.ts",
+					// Hidden notify daemon CLI (loaded via dynamic import from notify-cli); list it
+					// explicitly so Bun standalone keeps `gjc notify daemon-internal` usable.
+					"./src/notifications/telegram-daemon-cli.ts",
 					"--outfile",
 					"dist/gjc",
 				],

package/src/async/job-manager.ts

@@ -84,7 +84,11 @@ export interface SubagentLiveHandle {
 	/** Request a cooperative safe-boundary pause (never aborts the in-flight tool). */
 	requestPause(): void;
 	/** Inject a steering message into the live session. */
-	injectMessage(content: string, deliverAs: "steer" | "followUp" | "nextTurn"): Promise<void>;
+	injectMessage(
+		content: string,
+		deliverAs: "steer" | "followUp" | "nextTurn",
+		opts?: { fromAgentId?: string },
+	): Promise<void>;
 }
 
 /**

package/src/cli/daemon-cli.ts

@@ -0,0 +1,122 @@
+/**
+ * `gjc daemon` command handler.
+ *
+ * Generic over the static built-in daemon controller map: lists/inspects
+ * daemons and drives cooperative stop/reload. Telegram is the only kind today.
+ */
+
+import { Settings } from "../config/settings";
+import { selectDaemonControllers } from "../daemon/builtin";
+import type {
+	BuiltInDaemonController,
+	DaemonKind,
+	DaemonOperationOptions,
+	DaemonOperationResult,
+	DaemonStatus,
+} from "../daemon/control-types";
+
+export type DaemonCliAction = "list" | "status" | "stop" | "reload";
+
+export interface DaemonCommandArgs {
+	action: DaemonCliAction;
+	kinds: DaemonKind[];
+	all: boolean;
+	json: boolean;
+	force: boolean;
+	gracefulTimeoutMs?: number;
+	killTimeoutMs?: number;
+	spawnIfStopped?: boolean;
+}
+
+export interface DaemonCommandDeps {
+	settings?: Settings;
+	controllers?: BuiltInDaemonController[];
+}
+
+const KNOWN_ACTIONS: DaemonCliAction[] = ["list", "status", "stop", "reload"];
+const KNOWN_KINDS: DaemonKind[] = ["telegram"];
+
+export function parseDaemonArgs(argv: string[]): DaemonCommandArgs | undefined {
+	if (argv.length === 0 || argv[0] !== "daemon") return undefined;
+	const rest = argv.slice(1);
+	const action = (KNOWN_ACTIONS as string[]).includes(rest[0] ?? "") ? (rest[0] as DaemonCliAction) : "status";
+	const positional = (KNOWN_ACTIONS as string[]).includes(rest[0] ?? "") ? rest.slice(1) : rest;
+	const kinds: DaemonKind[] = [];
+	let all = false;
+	let json = false;
+	let force = false;
+	let gracefulTimeoutMs: number | undefined;
+	let killTimeoutMs: number | undefined;
+	let spawnIfStopped: boolean | undefined;
+	for (let i = 0; i < positional.length; i++) {
+		const arg = positional[i];
+		if (arg === "--all") all = true;
+		else if (arg === "--json") json = true;
+		else if (arg === "--force") force = true;
+		else if (arg === "--spawn-if-stopped") spawnIfStopped = true;
+		else if (arg === "--graceful-timeout-ms") gracefulTimeoutMs = Number.parseInt(positional[++i], 10);
+		else if (arg === "--kill-timeout-ms") killTimeoutMs = Number.parseInt(positional[++i], 10);
+		else if (!arg.startsWith("--") && (KNOWN_KINDS as string[]).includes(arg)) kinds.push(arg as DaemonKind);
+	}
+	return { action, kinds, all, json, force, gracefulTimeoutMs, killTimeoutMs, spawnIfStopped };
+}
+
+function formatStatus(status: DaemonStatus): string {
+	const parts = [
+		`${status.kind}: ${status.health}`,
+		status.configured ? undefined : "(not configured)",
+		status.pid !== undefined ? `pid=${status.pid}` : undefined,
+		status.ownerId ? `owner=${status.ownerId}` : undefined,
+		status.rootCount !== undefined ? `roots=${status.rootCount}` : undefined,
+		`mode=${status.runtime.mode}`,
+	].filter(Boolean);
+	let line = parts.join(" ");
+	if (status.runtime.warning) line += `\n  warning: ${status.runtime.warning}`;
+	return line;
+}
+
+function formatResult(result: DaemonOperationResult): string {
+	const head = `${result.kind} ${result.action}: ${result.ok ? "ok" : "failed"} — ${result.message}`;
+	const warnings = result.warnings.map(w => `\n  warning: ${w}`).join("");
+	return head + warnings;
+}
+
+export async function runDaemonCommand(cmd: DaemonCommandArgs, deps: DaemonCommandDeps = {}): Promise<void> {
+	const unknownKinds = cmd.kinds.filter(kind => !(KNOWN_KINDS as string[]).includes(kind));
+	if (unknownKinds.length > 0) {
+		process.stderr.write(
+			`Unknown daemon kind(s): ${unknownKinds.join(", ")}. Known kinds: ${KNOWN_KINDS.join(", ")}.\n`,
+		);
+		process.exitCode = 1;
+		return;
+	}
+	const settings = deps.settings ?? (await Settings.init());
+	const controllers = deps.controllers ?? selectDaemonControllers(settings, cmd.kinds, cmd.all);
+
+	if (cmd.action === "list" || cmd.action === "status") {
+		const statuses = await Promise.all(controllers.map(c => c.status()));
+		if (cmd.json) {
+			process.stdout.write(`${JSON.stringify(statuses, null, 2)}\n`);
+		} else {
+			process.stdout.write(`${statuses.map(formatStatus).join("\n")}\n`);
+		}
+		return;
+	}
+
+	const opts: DaemonOperationOptions = {
+		gracefulTimeoutMs: cmd.gracefulTimeoutMs,
+		killTimeoutMs: cmd.killTimeoutMs,
+		force: cmd.force,
+		spawnIfStopped: cmd.spawnIfStopped,
+	};
+	const results: DaemonOperationResult[] = [];
+	for (const controller of controllers) {
+		results.push(cmd.action === "reload" ? await controller.reload(opts) : await controller.stop(opts));
+	}
+	if (cmd.json) {
+		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+	} else {
+		process.stdout.write(`${results.map(formatResult).join("\n")}\n`);
+	}
+	if (results.some(r => !r.ok)) process.exitCode = 1;
+}

package/src/cli/notify-cli.ts

@@ -0,0 +1,274 @@
+/**
+ * Notify CLI command handlers.
+ *
+ * Handles `gjc notify` setup/status and the hidden daemon entrypoint.
+ */
+import { createInterface } from "node:readline/promises";
+import { APP_NAME } from "@gajae-code/utils";
+import chalk from "chalk";
+import { Settings } from "../config/settings";
+import { getNotificationConfig, maskToken } from "../notifications/config";
+
+export type NotifyAction = "setup" | "status" | "daemon-internal";
+
+export interface NotifyCommandArgs {
+	action: NotifyAction;
+	smoke?: boolean;
+	rawArgs: string[];
+	token?: string;
+	chatId?: string;
+	redact?: boolean;
+}
+
+export interface NotifyCommandDeps {
+	fetchImpl?: typeof fetch;
+	apiBase?: string;
+	settings?: Settings;
+	setupToken?: string;
+	pollTimeoutMs?: number;
+	pollIntervalMs?: number;
+	setupChatId?: string;
+	setupRedact?: boolean;
+}
+
+interface TelegramApiResponse<T> {
+	ok: boolean;
+	result?: T;
+	description?: string;
+}
+
+interface TelegramUpdate {
+	update_id: number;
+	message?: {
+		chat?: {
+			id?: number | string;
+			type?: string;
+		};
+	};
+}
+
+const DEFAULT_API_BASE = "https://api.telegram.org";
+const DEFAULT_POLL_TIMEOUT_MS = 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+
+export function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "notify") {
+		return undefined;
+	}
+
+	const action = args[1];
+	if (action === "setup" || action === "status") {
+		const rest = args.slice(2);
+		const flag = (name: string): string | undefined => {
+			const i = rest.indexOf(name);
+			return i >= 0 ? rest[i + 1] : undefined;
+		};
+		return {
+			action,
+			rawArgs: rest,
+			token: flag("--token"),
+			chatId: flag("--chat-id"),
+			redact: rest.includes("--redact"),
+		};
+	}
+	if (action === "daemon-internal") {
+		return {
+			action,
+			smoke: args.slice(2).includes("--smoke"),
+			rawArgs: args.slice(2),
+		};
+	}
+
+	return { action: "status", rawArgs: args.slice(1) };
+}
+
+export async function runNotifyCommand(cmd: NotifyCommandArgs, deps: NotifyCommandDeps = {}): Promise<void> {
+	switch (cmd.action) {
+		case "setup":
+			await runSetup({
+				...deps,
+				setupToken: deps.setupToken ?? cmd.token,
+				setupChatId: deps.setupChatId ?? cmd.chatId,
+				setupRedact: deps.setupRedact ?? cmd.redact,
+			});
+			return;
+		case "status":
+			await runStatus(deps);
+			return;
+		case "daemon-internal": {
+			const m = await import("../notifications/telegram-daemon-cli");
+			if (cmd.smoke) {
+				await m.runDaemonSmoke();
+			} else {
+				await m.runDaemonInternal(cmd.rawArgs);
+			}
+			return;
+		}
+	}
+}
+
+async function getSettings(deps: NotifyCommandDeps): Promise<Settings> {
+	return deps.settings ?? (await Settings.init());
+}
+
+async function runSetup(deps: NotifyCommandDeps): Promise<void> {
+	const settings = await getSettings(deps);
+	const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+	const apiBase = deps.apiBase ?? DEFAULT_API_BASE;
+	const token = deps.setupToken ?? (await promptForToken());
+	if (!token.trim()) {
+		throw new Error("Telegram bot token is required.");
+	}
+
+	await callTelegram(fetchImpl, apiBase, token, "getMe", {});
+	process.stdout.write(
+		"Token validated. Message your bot now from the private Telegram chat to pair notifications.\n",
+	);
+
+	let chatId: string;
+	if (deps.setupChatId?.trim()) {
+		chatId = deps.setupChatId.trim();
+		process.stdout.write(`Using provided chat id ${chatId} (non-interactive).\n`);
+	} else {
+		const stale = await getUpdates(fetchImpl, apiBase, token, { timeout: 0, allowed_updates: ["message"] });
+		const offset = nextOffset(stale);
+		chatId = await waitForPrivateChat(fetchImpl, apiBase, token, {
+			offset,
+			pollTimeoutMs: deps.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS,
+			pollIntervalMs: deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+		});
+	}
+
+	settings.set("notifications.telegram.botToken", token);
+	settings.set("notifications.telegram.chatId", chatId);
+	settings.set("notifications.enabled", true);
+	if (deps.setupRedact) settings.set("notifications.redact", true);
+	await settings.flush();
+
+	process.stdout.write(`Notifications enabled. botToken=${maskToken(token)} chatId=${chatId}\n`);
+}
+
+async function promptForToken(): Promise<string> {
+	if (!process.stdin.isTTY) {
+		throw new Error("notify setup requires an interactive TTY unless setupToken is injected.");
+	}
+	const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+	try {
+		return (await rl.question("Telegram BotFather token: ")).trim();
+	} finally {
+		rl.close();
+	}
+}
+
+async function runStatus(deps: NotifyCommandDeps): Promise<void> {
+	const settings = await getSettings(deps);
+	const cfg = getNotificationConfig(settings);
+	process.stdout.write(
+		`${chalk.bold("Notifications")}\n` +
+			`  enabled: ${cfg.enabled}\n` +
+			`  botToken: ${maskToken(cfg.botToken)}\n` +
+			`  chatId: ${cfg.chatId ?? "(unset)"}\n` +
+			`  redact: ${cfg.redact}\n`,
+	);
+}
+
+async function waitForPrivateChat(
+	fetchImpl: typeof fetch,
+	apiBase: string,
+	token: string,
+	opts: { offset: number | undefined; pollTimeoutMs: number; pollIntervalMs: number },
+): Promise<string> {
+	const deadline = Date.now() + opts.pollTimeoutMs;
+	let offset = opts.offset;
+	let sawRejectedChatType: string | undefined;
+
+	while (Date.now() <= deadline) {
+		const updates = await getUpdates(fetchImpl, apiBase, token, { offset, timeout: 0, allowed_updates: ["message"] });
+		offset = nextOffset(updates, offset);
+		for (const update of updates) {
+			const chat = update.message?.chat;
+			if (!chat) continue;
+			if (chat.type === "private" && chat.id !== undefined) {
+				return String(chat.id);
+			}
+			if (chat.type === "group" || chat.type === "supergroup" || chat.type === "channel") {
+				sawRejectedChatType = chat.type;
+				process.stderr.write(
+					`Rejected ${chat.type} chat. Pairing requires a private Telegram chat with the bot.\n`,
+				);
+			}
+		}
+		if (opts.pollIntervalMs > 0) {
+			await new Promise(resolve =>
+				setTimeout(resolve, Math.min(opts.pollIntervalMs, Math.max(0, deadline - Date.now()))),
+			);
+		}
+	}
+
+	if (sawRejectedChatType) {
+		throw new Error(`Pairing rejected ${sawRejectedChatType} chat; message the bot from a private chat.`);
+	}
+	throw new Error("Timed out waiting for a private Telegram message to pair notifications.");
+}
+
+function nextOffset(updates: TelegramUpdate[], fallback?: number): number | undefined {
+	let max = fallback === undefined ? undefined : fallback - 1;
+	for (const update of updates) {
+		if (typeof update.update_id === "number" && (max === undefined || update.update_id > max)) {
+			max = update.update_id;
+		}
+	}
+	return max === undefined ? fallback : max + 1;
+}
+
+async function getUpdates(
+	fetchImpl: typeof fetch,
+	apiBase: string,
+	token: string,
+	params: Record<string, unknown>,
+): Promise<TelegramUpdate[]> {
+	return await callTelegram<TelegramUpdate[]>(fetchImpl, apiBase, token, "getUpdates", params);
+}
+
+async function callTelegram<T>(
+	fetchImpl: typeof fetch,
+	apiBase: string,
+	token: string,
+	method: string,
+	body: Record<string, unknown>,
+): Promise<T> {
+	const response = await fetchImpl(`${apiBase.replace(/\/$/, "")}/bot${token}/${method}`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body),
+	});
+	let payload: TelegramApiResponse<T>;
+	try {
+		payload = (await response.json()) as TelegramApiResponse<T>;
+	} catch {
+		throw new Error(`Telegram ${method} returned invalid JSON.`);
+	}
+	if (!response.ok || !payload.ok) {
+		throw new Error(`Telegram ${method} failed: ${payload.description ?? response.statusText}`);
+	}
+	return payload.result as T;
+}
+
+export function printNotifyHelp(): void {
+	process.stdout.write(`${chalk.bold(`${APP_NAME} notify`)} - Configure Telegram notifications
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} notify setup
+  ${APP_NAME} notify setup --token <botToken> --chat-id <chatId> [--redact]
+  ${APP_NAME} notify status
+
+${chalk.bold("Subcommands:")}
+  setup     Pair a Telegram bot token with a private chat
+  status    Show notification configuration without secrets
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} notify setup
+  ${APP_NAME} notify setup --token <botToken> --chat-id <chatId> [--redact]
+  ${APP_NAME} notify status
+`);
+}