@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/config/settings-schema.ts

@@ -36,7 +36,8 @@ export type SettingTab =
 	| "editing"
 	| "tools"
 	| "tasks"
-	| "providers";
+	| "providers"
+	| "integrations";
 
 /** Tab display metadata - icon is resolved via theme.symbol() */
 export type TabMetadata = { label: string; icon: `tab.${string}` };
@@ -52,6 +53,7 @@ export const SETTING_TABS: SettingTab[] = [
 	"tools",
 	"tasks",
 	"providers",
+	"integrations",
 ];
 
 /** Tab display metadata - icon is a symbol key from theme.ts (tab.*) */
@@ -65,6 +67,7 @@ export const TAB_METADATA: Record<SettingTab, { label: string; icon: `tab.${stri
 	tools: { label: "Tools", icon: "tab.tools" },
 	tasks: { label: "Tasks", icon: "tab.tasks" },
 	providers: { label: "Providers", icon: "tab.providers" },
+	integrations: { label: "Integrations", icon: "tab.integrations" },
 };
 
 /** Status line segment identifiers */
@@ -281,7 +284,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "interaction",
 			label: "Terminal Bell",
-			description: "Emit a BEL character for local terminal notifications",
+			description:
+				"Emit a BEL character for local terminal notifications. Windows Terminal may keep BEL silent depending on profile/system sound settings; use completion.notifyCommand for a PowerShell Console.Beep workaround.",
 		},
 	},
 	"notifications.bellOnComplete": {
@@ -476,7 +480,7 @@ export const SETTINGS_SCHEMA = {
 	// Status line
 	"statusLine.preset": {
 		type: "enum",
-		values: ["default", "minimal", "compact", "full", "nerd", "ascii", "custom"] as const,
+		values: ["default", "default-usage", "minimal", "compact", "full", "nerd", "ascii", "custom"] as const,
 		default: "default",
 		ui: {
 			tab: "appearance",
@@ -484,6 +488,11 @@ export const SETTINGS_SCHEMA = {
 			description: "Pre-built status line configurations",
 			options: [
 				{ value: "default", label: "Default", description: "Model, path, git, context, tokens, cost" },
+				{
+					value: "default-usage",
+					label: "Default + Usage",
+					description: "Default layout with provider usage quota",
+				},
 				{ value: "minimal", label: "Minimal", description: "Path and git only" },
 				{ value: "compact", label: "Compact", description: "Model, git, cost, context" },
 				{ value: "full", label: "Full", description: "All segments including time" },
@@ -523,6 +532,21 @@ export const SETTINGS_SCHEMA = {
 			description: "Use the session name color for the editor border and status line gap",
 		},
 	},
+	"statusLine.maxRows": {
+		type: "number",
+		default: 1,
+		ui: {
+			tab: "appearance",
+			label: "Status Line Rows",
+			description:
+				"Maximum rows for the status line. When greater than 1, overflowing segments wrap onto additional rows instead of being dropped.",
+			options: [
+				{ value: "1", label: "1 row", description: "Single line; overflow is truncated (default)" },
+				{ value: "2", label: "2 rows", description: "Wrap overflow onto a second row" },
+				{ value: "3", label: "3 rows", description: "Wrap overflow across up to three rows" },
+			],
+		},
+	},
 	"tools.artifactSpillThreshold": {
 		type: "number",
 		default: 50,
@@ -546,6 +570,42 @@ export const SETTINGS_SCHEMA = {
 			],
 		},
 	},
+
+	"tools.readArtifactSpillThreshold": {
+		type: "number",
+		default: 0,
+		ui: {
+			tab: "tools",
+			label: "Experimental read-tool artifact spill threshold (KB)",
+			description:
+				"Advanced opt-in only: combined-size cap for `read` output across all requested ranges. Above this the full output is saved as an artifact and a bounded head+tail snippet is kept inline. Live layofflabs/gpt-5.5 medium evidence on 2026-07-07 found no token savings and a lower cache-hit rate at 50 KB, so normal coding sessions should leave this Off unless intentionally measuring large-read behavior.",
+			options: [
+				{ value: "0", label: "Off", description: "Default; no read-specific spill (backstop only)" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens" },
+				{ value: "100", label: "100 KB", description: "~25K tokens" },
+				{ value: "256", label: "256 KB", description: "~64K tokens" },
+				{ value: "512", label: "512 KB", description: "~128K tokens" },
+				{ value: "1000", label: "1 MB", description: "~250K tokens" },
+			],
+		},
+	},
+
+	"tools.fileMentionInlineBytes": {
+		type: "number",
+		default: 20,
+		ui: {
+			tab: "tools",
+			label: "File-mention inline cap (KB)",
+			description:
+				"Inline byte cap for auto-read `@path` file mentions, deliberately below the read-tool cap so an incidental mention injects a smaller snippet than an explicit read. The full file is still available via the read tool.",
+			options: [
+				{ value: "5", label: "5 KB", description: "~1.25K tokens" },
+				{ value: "10", label: "10 KB", description: "~2.5K tokens" },
+				{ value: "20", label: "20 KB", description: "Default; ~5K tokens" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens (matches read cap)" },
+			],
+		},
+	},
 	"tools.artifactTailBytes": {
 		type: "number",
 		default: 20,
@@ -624,6 +684,25 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"tools.maxInlineResultBytes": {
+		type: "number",
+		default: 0,
+		ui: {
+			tab: "tools",
+			label: "Max inline tool-result size (KB)",
+			description:
+				"Absolute backstop cap on inline tool-result text, enforced after artifact spill for every tool (including read and tools that set their own partial artifact meta). Output above this size is force-saved as an artifact and truncated to head+tail. 0 disables (default; opt-in pending measurement).",
+			options: [
+				{ value: "0", label: "Off", description: "Disabled; no absolute inline cap" },
+				{ value: "20", label: "20 KB", description: "~5K tokens" },
+				{ value: "30", label: "30 KB", description: "~7.5K tokens" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens" },
+				{ value: "75", label: "75 KB", description: "~19K tokens" },
+				{ value: "100", label: "100 KB", description: "~25K tokens" },
+			],
+		},
+	},
+
 	"statusLine.showHookStatus": {
 		type: "boolean",
 		default: false,
@@ -1201,7 +1280,7 @@ export const SETTINGS_SCHEMA = {
 			tab: "interaction",
 			label: "Completion Notification Command",
 			description:
-				"Optional user-level shell command to run when an agent turn completes; receives SKC_NOTIFICATION_* environment variables.",
+				"Optional user-level shell command to run when an agent turn completes; receives SKC_NOTIFICATION_* environment variables. On Windows, this can call PowerShell [Console]::Beep when terminal BEL is silent.",
 		},
 	},
 
@@ -1386,6 +1465,15 @@ export const SETTINGS_SCHEMA = {
 
 	"compaction.remoteEndpoint": { type: "string", default: undefined },
 
+	// Below-threshold maintenance pruning (Finding 13). Internal/measurement-only:
+	// keep the runtime setting for targeted experiments, but do not expose it in
+	// settings UI. Live layofflabs/gpt-5.5 medium evidence on 2026-07-07 showed no
+	// savings and a cache-hit regression; pruning rewrites already-sent history and
+	// can force a provider cache-epoch reset.
+	"compaction.maintenancePruningEnabled": { type: "boolean", default: false },
+
+	"compaction.maintenancePruningMinSavingsTokens": { type: "number", default: 8000 },
+
 	// Idle compaction
 	"compaction.idleEnabled": {
 		type: "boolean",
@@ -1659,7 +1747,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "context",
 			label: "TTSR Context Mode",
-			description: "What to do with partial output when TTSR triggers",
+			description:
+				"What to do with partial output when TTSR triggers. 'discard' (recommended) drops the aborted partial turn so it never accumulates in context. 'keep' retains every aborted partial turn, which grows the token footprint each time a rule fires — prefer 'discard' unless you specifically need the partial output.",
 		},
 	},
 
@@ -2226,6 +2315,11 @@ export const SETTINGS_SCHEMA = {
 		ui: { tab: "tools", label: "Web Search", description: "Enable the web_search tool for web searching" },
 	},
 
+	"web_search.provider": {
+		type: "enum",
+		values: ["auto", ...CONFIGURABLE_SEARCH_PROVIDER_IDS] as const,
+		default: "auto",
+	},
 	"web_search.fallback": {
 		type: "array",
 		default: EMPTY_STRING_ARRAY,
@@ -2489,7 +2583,7 @@ export const SETTINGS_SCHEMA = {
 	"tools.discoveryMode": {
 		type: "enum",
 		values: ["off", "all"] as const,
-		default: "off",
+		default: "all",
 		ui: {
 			tab: "tools",
 			label: "Tool Discovery",
@@ -2504,7 +2598,7 @@ export const SETTINGS_SCHEMA = {
 			tab: "tools",
 			label: "Essential Tools Override",
 			description:
-				"Override the always-loaded built-in tools (default: read, bash, edit). Leave empty to use defaults.",
+				"Override the always-loaded built-in tools (default: read, bash, edit, write, search, find). Leave empty to use defaults.",
 		},
 	},
 
@@ -3156,6 +3250,151 @@ export const SETTINGS_SCHEMA = {
 			description: "Score threshold (0–100) above which block mode denies install. Default 60.",
 		},
 	},
+
+	// Telegram Remote — two-way messaging integration.
+	// Maps to SKC_TELEGRAM_REMOTE_* env vars consumed by the
+	// @sayknow-cli/telegram-remote gateway (packages/telegram-remote).
+	// The settings bridge converts these into env before spawning the gateway.
+	"telegram.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "integrations",
+			label: "Telegram Remote",
+			description: "Enable two-way Telegram bot control of skc sessions",
+		},
+	},
+
+	"telegram.botToken": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Bot Token",
+			description: "Telegram bot token from @BotFather (required when enabled)",
+		},
+	},
+
+	"telegram.allowedUserIds": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Allowed User IDs",
+			description: "Comma-separated Telegram user IDs permitted to send commands",
+		},
+	},
+
+	"telegram.allowedChatIds": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Allowed Chat IDs",
+			description: "Comma-separated Telegram chat IDs permitted to send commands",
+		},
+	},
+
+	"telegram.backend": {
+		type: "enum",
+		values: ["coordinator", "rpc"] as const,
+		default: "coordinator",
+		ui: {
+			tab: "integrations",
+			label: "Backend",
+			description: "Coordinator (multi-session lifecycle) or RPC (single persistent session)",
+			options: [
+				{ value: "coordinator", label: "Coordinator", description: "Multi-session lifecycle + observation" },
+				{ value: "rpc", label: "RPC", description: "Attach/detach to one persistent session socket" },
+			],
+		},
+	},
+
+	"telegram.enableStop": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "integrations",
+			label: "Enable /stop",
+			description: "Allow graceful stop requests (adds the reports mutation class)",
+		},
+	},
+
+	"telegram.enableRich": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "integrations",
+			label: "Rich Messages",
+			description: "HTML formatting + inline keyboards",
+		},
+	},
+
+	"telegram.enablePush": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "integrations",
+			label: "Push Notifications",
+			description: "Follow/Mute subscriptions via coordinator event watch",
+		},
+	},
+
+	"telegram.registerCommands": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "integrations",
+			label: "Register Bot Menu",
+			description: "Register the Bot command menu at startup",
+		},
+	},
+
+	"telegram.presets": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Session Presets",
+			description: "JSON array of {id, workdir, sessionCommand, taskTemplate?, taskMaxLen?}",
+		},
+	},
+
+	"telegram.rpcSocket": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "RPC Socket",
+			description: "Path to the skc launch --output rpc UNIX socket (RPC backend only)",
+		},
+	},
+
+	"telegram.stateDir": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "State Directory",
+			description: "Gateway state dir for reconnect/resync (required for RPC backend)",
+		},
+	},
+
+	// Telegram advanced — hidden from UI, editable via config.yml
+	"telegram.pollTimeoutSec": { type: "number", default: 30 },
+	"telegram.apiBase": { type: "string", default: undefined },
+	"telegram.coordinatorCommand": { type: "string", default: "skc" },
+	"telegram.coordinatorArgs": { type: "string", default: "mcp-serve,coordinator" },
+	"telegram.enableEditMessageText": { type: "boolean", default: false },
+	"telegram.richCallbackTtlMs": { type: "number", default: 600000 },
+	"telegram.richCallbackMaxTokens": { type: "number", default: 500 },
+	"telegram.defaultTaskMaxLen": { type: "number", default: 2000 },
+	"telegram.livenessMs": { type: "number", default: 60000 },
+	"telegram.followTtlMs": { type: "number", default: 86400000 },
+	"telegram.subscriptionsMax": { type: "number", default: 1000 },
+	"telegram.longPollMs": { type: "number", default: 25000 },
+	"telegram.digestThreshold": { type: "number", default: 5 },
+	"telegram.allowAttachSocketArg": { type: "boolean", default: false },
 } as const;
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -3247,6 +3486,8 @@ export interface CompactionSettings {
 	autoContinue: boolean;
 	remoteEnabled: boolean;
 	remoteEndpoint: string | undefined;
+	maintenancePruningEnabled: boolean;
+	maintenancePruningMinSavingsTokens: number;
 	idleEnabled: boolean;
 	idleThresholdTokens: number;
 	idleTimeoutSeconds: number;
@@ -3323,6 +3564,7 @@ export interface ExaSettings {
 export interface StatusLineSettings {
 	preset: StatusLinePreset;
 	separator: StatusLineSeparatorStyle;
+	maxRows: number;
 	showHookStatus: boolean;
 	showSkillHud: boolean;
 	leftSegments: StatusLineSegmentId[];
@@ -3383,6 +3625,35 @@ export interface NotificationsSettings {
 	};
 }
 
+export interface TelegramSettings {
+	enabled: boolean;
+	botToken: string | undefined;
+	allowedUserIds: string | undefined;
+	allowedChatIds: string | undefined;
+	backend: "coordinator" | "rpc";
+	enableStop: boolean;
+	enableRich: boolean;
+	enablePush: boolean;
+	registerCommands: boolean;
+	presets: string | undefined;
+	rpcSocket: string | undefined;
+	stateDir: string | undefined;
+	pollTimeoutSec: number;
+	apiBase: string | undefined;
+	coordinatorCommand: string;
+	coordinatorArgs: string;
+	enableEditMessageText: boolean;
+	richCallbackTtlMs: number;
+	richCallbackMaxTokens: number;
+	defaultTaskMaxLen: number;
+	livenessMs: number;
+	followTtlMs: number;
+	subscriptionsMax: number;
+	longPollMs: number;
+	digestThreshold: number;
+	allowAttachSocketArg: boolean;
+}
+
 /** Map group prefix -> typed settings interface */
 export interface GroupTypeMap {
 	compaction: CompactionSettings;
@@ -3401,6 +3672,7 @@ export interface GroupTypeMap {
 	modelTags: ModelTagsSettings;
 	cycleOrder: string[];
 	shellMinimizer: ShellMinimizerSettings;
+	telegram: TelegramSettings;
 	notifications: NotificationsSettings;
 }
 

package/src/config/settings.ts

@@ -476,6 +476,28 @@ export class Settings {
 			this.override("modelRoles", { ...shallowStringRecord(runtimeOverrides), [role]: modelId });
 		}
 	}
+	/**
+	 * Set an agent model override while keeping any live runtime override aligned.
+	 *
+	 * Runtime model profiles override `task.agentModelOverrides` for the current
+	 * session. A user-selected role assignment must win immediately in that same
+	 * session, but only the explicit agent change should be persisted.
+	 */
+	setAgentModelOverride(agentName: string, modelId: string): void {
+		const current = shallowStringRecord(getByPath(this.#global, ["task", "agentModelOverrides"]));
+		const runtimeOverrides = getByPath(this.#overrides, ["task", "agentModelOverrides"]);
+		const updateRuntimeOverride =
+			!!runtimeOverrides && typeof runtimeOverrides === "object" && !Array.isArray(runtimeOverrides);
+
+		this.set("task.agentModelOverrides", { ...current, [agentName]: modelId });
+
+		if (updateRuntimeOverride) {
+			this.override("task.agentModelOverrides", {
+				...shallowStringRecord(runtimeOverrides),
+				[agentName]: modelId,
+			});
+		}
+	}
 
 	/**
 	 * Get a model role (helper for modelRoles record).

package/src/config/telegram-autostart.ts

@@ -0,0 +1,107 @@
+/**
+ * Auto-start the Telegram Remote gateway when `telegram.enabled` is on.
+ *
+ * Called once during skc startup (interactive / persistent modes only — not
+ * `-p` print or auto-print). Spawns the gateway as a detached background
+ * process, tracks its PID so repeated skc invocations don't double-spawn,
+ * and redirects output to a log file under the config root.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getConfigRootDir, isCompiledBinary, logger } from "@sayknow-cli/utils";
+import { settings } from "./settings";
+import type { TelegramSettings } from "./settings-schema";
+import { telegramSettingsToEnv, validateTelegramSettings } from "./telegram-env-bridge";
+
+function readTelegramSettings(): TelegramSettings {
+	return {
+		enabled: settings.get("telegram.enabled"),
+		botToken: settings.get("telegram.botToken"),
+		allowedUserIds: settings.get("telegram.allowedUserIds"),
+		allowedChatIds: settings.get("telegram.allowedChatIds"),
+		backend: settings.get("telegram.backend"),
+		enableStop: settings.get("telegram.enableStop"),
+		enableRich: settings.get("telegram.enableRich"),
+		enablePush: settings.get("telegram.enablePush"),
+		registerCommands: settings.get("telegram.registerCommands"),
+		presets: settings.get("telegram.presets"),
+		rpcSocket: settings.get("telegram.rpcSocket"),
+		stateDir: settings.get("telegram.stateDir"),
+		pollTimeoutSec: settings.get("telegram.pollTimeoutSec"),
+		apiBase: settings.get("telegram.apiBase"),
+		coordinatorCommand: settings.get("telegram.coordinatorCommand") ?? "skc",
+		coordinatorArgs: settings.get("telegram.coordinatorArgs") ?? "mcp-serve,coordinator",
+		enableEditMessageText: settings.get("telegram.enableEditMessageText"),
+		richCallbackTtlMs: settings.get("telegram.richCallbackTtlMs"),
+		richCallbackMaxTokens: settings.get("telegram.richCallbackMaxTokens"),
+		defaultTaskMaxLen: settings.get("telegram.defaultTaskMaxLen"),
+		livenessMs: settings.get("telegram.livenessMs"),
+		followTtlMs: settings.get("telegram.followTtlMs"),
+		subscriptionsMax: settings.get("telegram.subscriptionsMax"),
+		longPollMs: settings.get("telegram.longPollMs"),
+		digestThreshold: settings.get("telegram.digestThreshold"),
+		allowAttachSocketArg: settings.get("telegram.allowAttachSocketArg"),
+	};
+}
+
+function resolveGatewayCommand(): { cmd: string; args: string[] } {
+	if (isCompiledBinary()) {
+		return { cmd: "skc-telegram-remote", args: [] };
+	}
+	const cliPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../telegram-remote/src/cli.ts");
+	return { cmd: process.execPath, args: ["run", cliPath] };
+}
+
+function isAlreadyRunning(pidFile: string): boolean {
+	try {
+		const pid = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+		if (!Number.isInteger(pid)) return false;
+		process.kill(pid, 0); // signal 0 — throws if the process is gone
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * If `telegram.enabled` is true and the gateway is not already running, spawn
+ * it in the background. Never throws — failures are logged as warnings so the
+ * main skc session is unaffected.
+ */
+export async function maybeAutostartTelegramRemote(): Promise<void> {
+	if (!settings.get("telegram.enabled")) return;
+
+	const config = readTelegramSettings();
+	const errors = validateTelegramSettings(config);
+	if (errors.length > 0) {
+		logger.warn("Telegram Remote enabled but misconfigured, skipping autostart", { errors });
+		return;
+	}
+
+	const configRoot = getConfigRootDir();
+	const pidFile = path.join(configRoot, "telegram-remote.pid");
+	if (isAlreadyRunning(pidFile)) {
+		logger.info("Telegram Remote already running, skipping autostart");
+		return;
+	}
+
+	const env = telegramSettingsToEnv(config);
+	const { cmd, args } = resolveGatewayCommand();
+	const logDir = path.join(configRoot, "logs");
+	fs.mkdirSync(logDir, { recursive: true });
+	const logFd = fs.openSync(path.join(logDir, "telegram-remote.log"), "a");
+
+	try {
+		const proc = Bun.spawn([cmd, ...args], {
+			env: { ...process.env, ...env },
+			stdio: ["ignore", logFd, logFd],
+			detached: true,
+		});
+		proc.unref();
+		fs.writeFileSync(pidFile, String(proc.pid));
+		logger.info("Telegram Remote gateway auto-started", { pid: proc.pid });
+	} catch (err) {
+		logger.warn("Failed to auto-start Telegram Remote gateway", { error: String(err) });
+	}
+}

package/src/config/telegram-env-bridge.ts

@@ -0,0 +1,92 @@
+/**
+ * Bridge between skc settings (`telegram.*`) and the
+ * `@sayknow-cli/telegram-remote` gateway's environment-driven config
+ * (`loadConfigFromEnv` in packages/telegram-remote/src/config.ts).
+ *
+ * The gateway is a standalone process (`skc-telegram-remote`) that reads all
+ * configuration from `SKC_TELEGRAM_REMOTE_*` env vars. This module converts the
+ * typed settings group into those env vars so skc can spawn the gateway with a
+ * consistent, settings-page-driven configuration.
+ */
+import type { TelegramSettings } from "./settings-schema";
+
+/** Convert telegram settings into the env-var map the gateway expects. */
+export function telegramSettingsToEnv(s: TelegramSettings): Record<string, string> {
+	const env: Record<string, string> = {};
+
+	const str = (v: string | undefined, key: string): void => {
+		if (v !== undefined && v !== "") env[key] = v;
+	};
+	const num = (v: number, key: string): void => {
+		env[key] = String(v);
+	};
+	const bool = (v: boolean, key: string): void => {
+		env[key] = v ? "true" : "false";
+	};
+
+	// Required
+	str(s.botToken, "SKC_TELEGRAM_REMOTE_BOT_TOKEN");
+
+	// Allowlists
+	str(s.allowedUserIds, "SKC_TELEGRAM_REMOTE_ALLOWED_USER_IDS");
+	str(s.allowedChatIds, "SKC_TELEGRAM_REMOTE_ALLOWED_CHAT_IDS");
+
+	// Presets
+	str(s.presets, "SKC_TELEGRAM_REMOTE_PRESETS");
+
+	// Toggles
+	bool(s.enableStop, "SKC_TELEGRAM_REMOTE_ENABLE_STOP");
+	bool(s.enableRich, "SKC_TELEGRAM_REMOTE_ENABLE_RICH");
+	bool(s.enablePush, "SKC_TELEGRAM_REMOTE_ENABLE_PUSH");
+	bool(s.registerCommands, "SKC_TELEGRAM_REMOTE_REGISTER_COMMANDS");
+	bool(s.enableEditMessageText, "SKC_TELEGRAM_REMOTE_ENABLE_EDIT_MESSAGE_TEXT");
+	bool(s.allowAttachSocketArg, "SKC_TELEGRAM_REMOTE_ALLOW_ATTACH_SOCKET_ARG");
+
+	// Backend + RPC
+	str(s.backend, "SKC_TELEGRAM_REMOTE_BACKEND");
+	str(s.rpcSocket, "SKC_TELEGRAM_REMOTE_RPC_SOCKET");
+	str(s.stateDir, "SKC_TELEGRAM_REMOTE_STATE_DIR");
+	num(s.livenessMs, "SKC_TELEGRAM_REMOTE_LIVENESS_MS");
+
+	// Transport
+	str(s.apiBase, "SKC_TELEGRAM_REMOTE_API_BASE");
+	num(s.pollTimeoutSec, "SKC_TELEGRAM_REMOTE_POLL_TIMEOUT_SEC");
+	num(s.longPollMs, "SKC_TELEGRAM_REMOTE_WATCH_TIMEOUT_MS");
+
+	// Rich callback tuning
+	num(s.richCallbackTtlMs, "SKC_TELEGRAM_REMOTE_RICH_CALLBACK_TTL_MS");
+	num(s.richCallbackMaxTokens, "SKC_TELEGRAM_REMOTE_RICH_CALLBACK_MAX_TOKENS");
+
+	// Push / subscriptions
+	num(s.followTtlMs, "SKC_TELEGRAM_REMOTE_FOLLOW_TTL_MS");
+	num(s.subscriptionsMax, "SKC_TELEGRAM_REMOTE_SUBSCRIPTIONS_MAX");
+	num(s.digestThreshold, "SKC_TELEGRAM_REMOTE_DIGEST_THRESHOLD");
+
+	// Coordinator subprocess
+	str(s.coordinatorCommand, "SKC_TELEGRAM_REMOTE_COORDINATOR_COMMAND");
+	str(s.coordinatorArgs, "SKC_TELEGRAM_REMOTE_COORDINATOR_ARGS");
+
+	// Preset task cap
+	num(s.defaultTaskMaxLen, "SKC_TELEGRAM_REMOTE_DEFAULT_TASK_MAX_LEN");
+
+	return env;
+}
+
+/**
+ * Validate telegram settings before spawning the gateway.
+ * Returns a list of human-readable error strings (empty when valid).
+ */
+export function validateTelegramSettings(s: TelegramSettings): string[] {
+	const errors: string[] = [];
+
+	if (!s.botToken) errors.push("Bot Token is required");
+	if (!s.allowedUserIds && !s.allowedChatIds) {
+		errors.push("At least one of Allowed User IDs or Allowed Chat IDs is required");
+	}
+	if (s.backend === "rpc") {
+		if (!s.rpcSocket) errors.push("RPC Socket is required for the RPC backend");
+		if (!s.stateDir) errors.push("State Directory is required for the RPC backend");
+	}
+
+	return errors;
+}