nemoris 0.1.0 → 0.1.2

package/src/onboarding/phases/telegram.js

@@ -1,377 +1,377 @@
-/**
- * Telegram onboarding sub-phase — optional, runs inside Build (Phase 3).
- *
- * Steps: token validation → chat_id discovery (daemon-aware) → mode selection
- *        → config write → smoke test with failure handling.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { getMe, whoami } from "../../runtime/telegram-inbound.js";
-import { writeEnvFile } from "../auth/api-key.js";
-import { isDaemonRunning, setDaemonEnv } from "../platform.js";
-import { writeTomlSection } from "../toml-writer.js";
-import {
-  confirm, prompt, promptSecret, select, waitForEnter,
-  bold, green, red, yellow, dim, cyan, progressLine,
-} from "../tui.js";
-
-export const TELEGRAM_START_INSTRUCTION =
-  "Before continuing, open Telegram, search for your new bot, and send it /start — otherwise it won't be able to receive messages.";
-
-// ── Helpers ──────────────────────────────────────────────────────
-
-export function stripAnsi(str) {
-  // eslint-disable-next-line no-control-regex
-  return str.replace(/\x1b\[[0-9;]*m/g, "");
-}
-
-export function buildTelegramToml({ botTokenEnv, pollingMode, webhookUrl, operatorChatId, authorizedChatIds, defaultAgent }) {
-  const authIds = (authorizedChatIds || []).map((id) => `"${id}"`).join(", ");
-  return [
-    "",
-    "[telegram]",
-    `bot_token_env = "${botTokenEnv}"`,
-    `polling_mode = ${pollingMode}`,
-    `webhook_url = "${webhookUrl || ""}"`,
-    `operator_chat_id = "${operatorChatId || ""}"`,
-    `authorized_chat_ids = [${authIds}]`,
-    `default_agent = "${defaultAgent}"`,
-    "",
-  ].join("\n");
-}
-
-export function patchRuntimeToml(installDir, telegramToml) {
-  const runtimePath = path.join(installDir, "config", "runtime.toml");
-  writeTomlSection(runtimePath, "telegram", telegramToml);
-}
-
-async function sendTestMessage(token, chatId, text, { fetchImpl = globalThis.fetch } = {}) {
-  try {
-    const url = `https://api.telegram.org/bot${token}/sendMessage`;
-    const res = await fetchImpl(url, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ chat_id: chatId, text }),
-    });
-    const body = await res.json();
-    if (!body.ok) return { ok: false, error: `${res.status}: ${body.description || "unknown error"}` };
-    return { ok: true };
-  } catch (error) {
-    return { ok: false, error: error.message };
-  }
-}
-
-/**
- * Discover chat_id when the daemon is running — polls active.db for a
- * telegram interactive job created after `since` (ISO string).
- */
-function discoverChatIdFromStore(installDir, since, { timeoutMs = 120_000, intervalMs = 2000 } = {}) {
-  const dbPath = path.join(installDir, "state", "active.db");
-  return new Promise((resolve) => {
-    const deadline = Date.now() + timeoutMs;
-
-    const tick = () => {
-      try {
-        // Lazy-require to avoid hard dep on better-sqlite3 at module level
-        const require = createRequire(import.meta.url);
-        const Database = require("better-sqlite3");
-        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
-        const row = db.prepare(
-          "SELECT chat_id FROM interactive_jobs WHERE source = 'telegram' AND created_at > ? ORDER BY created_at DESC LIMIT 1"
-        ).get(since);
-        db.close();
-        if (row?.chat_id) return resolve(row.chat_id);
-      } catch {
-        // DB may not exist yet or table missing — keep polling
-      }
-
-      if (Date.now() >= deadline) return resolve(null);
-      setTimeout(tick, intervalMs);
-    };
-    tick();
-  });
-}
-
-// ── Main Phase ───────────────────────────────────────────────────
-
-/**
- * Run the Telegram onboarding sub-phase (interactive).
- *
- * @param {{ installDir: string, agentId: string, nonInteractive?: boolean, skipGate?: boolean }} options
- * @returns {Promise<{ configured: boolean, verified: boolean, botUsername?: string }>}
- */
-export async function runTelegramPhase({ installDir, agentId, nonInteractive = false, skipGate = false, tui = {} }) {
-  const botTokenEnv = "NEMORIS_TELEGRAM_BOT_TOKEN";
-  const confirmImpl = tui.confirm || confirm;
-  const promptImpl = tui.prompt || prompt;
-  const promptSecretImpl = tui.promptSecret || promptSecret;
-  const selectImpl = tui.select || select;
-  const waitForEnterImpl = tui.waitForEnter || waitForEnter;
-  const redImpl = tui.red || red;
-  const yellowImpl = tui.yellow || yellow;
-  const dimImpl = tui.dim || dim;
-  const cyanImpl = tui.cyan || cyan;
-  const progressLineImpl = tui.progressLine || progressLine;
-
-  // ── Non-interactive mode ───────────────────────────────────────
-  if (nonInteractive) {
-    const token = process.env[botTokenEnv];
-    if (!token || process.env.NEMORIS_SKIP_TELEGRAM === "true") {
-      return { configured: false, verified: false };
-    }
-
-    const me = await getMe(token);
-    if (!me.ok) return { configured: false, verified: false };
-
-    const chatId = process.env.NEMORIS_TELEGRAM_CHAT_ID || "";
-    const mode = process.env.NEMORIS_TELEGRAM_MODE || "polling";
-    const webhookUrl = process.env.NEMORIS_TELEGRAM_WEBHOOK_URL || "";
-
-    // Security: empty authorized_chat_ids with no chat_id means any sender is accepted.
-    // Require NEMORIS_ALLOW_ANY_CHAT=true to opt in to this open configuration.
-    if (!chatId && process.env.NEMORIS_ALLOW_ANY_CHAT !== "true") {
-      console.error("NEMORIS_TELEGRAM_CHAT_ID not set. Set it, or set NEMORIS_ALLOW_ANY_CHAT=true to allow any sender.");
-      return { configured: false, verified: false };
-    }
-
-    const authorizedChatIds = chatId ? [chatId] : [];
-
-    writeEnvFile(installDir, { [botTokenEnv]: token });
-    patchRuntimeToml(installDir, buildTelegramToml({
-      botTokenEnv, pollingMode: mode === "polling", webhookUrl,
-      operatorChatId: chatId, authorizedChatIds, defaultAgent: agentId,
-    }));
-
-    return { configured: true, verified: false, botUsername: me.username, botToken: token, operatorChatId: chatId };
-  }
-
-  // ── Interactive mode ───────────────────────────────────────────
-
-  // Gate
-  if (!skipGate) {
-    const gate = await confirmImpl(`Connect via ${cyanImpl("Telegram")}? This lets you message your agent from your phone.`, true);
-    if (!gate) {
-      return { configured: false, verified: false };
-    }
-  }
-
-  // Step 1: Bot token
-  let token = null;
-  let botUsername = null;
-
-  console.log(`\n  ${dimImpl("Need a bot token? Open Telegram → search @BotFather → send /newbot → follow the steps.")}`);
-  console.log(`  ${dimImpl("After creating your bot, open it in Telegram and tap Start before coming back here.")}`);
-  console.log(`  ${dimImpl("Your input will be hidden as you type — just paste and press Enter.")}\n`);
-
-  while (!token) {
-    const raw = await promptSecretImpl(`Your bot token`);
-    if (!raw) {
-      console.log(`  ${dimImpl("Skipping Telegram — you can add it later with `nemoris setup telegram`.")}`);
-      return { configured: false, verified: false };
-    }
-
-    const me = await getMe(raw);
-    if (me.ok) {
-      token = raw;
-      botUsername = me.username;
-      console.log(progressLineImpl("Token validated", `@${me.username}`));
-      console.log(`  ${dimImpl(TELEGRAM_START_INSTRUCTION)}`);
-    } else {
-      console.log(`  ${redImpl("✗")} That token didn't work — double-check it in BotFather and try again.`);
-      console.log(`  ${dimImpl("Try again or press Enter to skip.")}`);
-    }
-  }
-
-  // Write token to .env + daemon env
-  writeEnvFile(installDir, { [botTokenEnv]: token });
-  await setDaemonEnv(botTokenEnv, token);
-
-  // Step 2: Chat ID discovery
-  let chatId = null;
-  const daemonRunning = isDaemonRunning();
-
-  if (daemonRunning) {
-    // Path A: daemon is running — read from state store
-    console.log(`\n  Open Telegram, find ${cyanImpl(`@${botUsername}`)}, send it any message — then press Enter.`);
-    const since = new Date().toISOString();
-    chatId = await discoverChatIdFromStore(installDir, since);
-
-    if (chatId) {
-      console.log(progressLineImpl("Found you", `chat_id: ${chatId}`));
-    } else {
-      console.log(`  ${yellowImpl("!")} Timed out waiting for a message. Try opening Telegram and sending a message to @${botUsername} first.`);
-      const manual = await promptImpl("Enter chat_id manually (or press Enter to skip)", "");
-      chatId = manual || null;
-    }
-  } else {
-    // Path B: daemon not running — use whoami probe
-    await waitForEnterImpl(`Open Telegram, find ${cyanImpl(`@${botUsername}`)}, send it a message — anything works. Then come back and press Enter.`);
-    const result = await whoami(token);
-    if (result) {
-      chatId = String(result.chatId);
-      const label = result.username ? `chat_id: ${chatId}, @${result.username}` : `chat_id: ${chatId}`;
-      console.log(progressLineImpl("Found you", label));
-    } else {
-      console.log(`  ${yellowImpl("!")} No messages found.`);
-      console.log(`  ${dimImpl("The bot may not have received your message yet.")}`);
-      const manual = await promptImpl("Enter chat_id manually (or press Enter to skip)", "");
-      chatId = manual || null;
-    }
-  }
-
-  const authorizedChatIds = chatId ? [chatId] : [];
-
-  // Step 3: Delivery mode
-  const mode = await selectImpl("Delivery mode:", [
-    { label: `Long polling ${dimImpl("(recommended — no tunnel needed)")}`, value: "polling" },
-    { label: `Webhook — for servers with a public address (advanced)`, value: "webhook" },
-  ]);
-
-  let webhookUrl = "";
-  if (mode === "webhook") {
-    webhookUrl = await promptImpl("Public webhook URL", "");
-    if (webhookUrl) {
-      const { registerWebhook } = await import("../../runtime/telegram-inbound.js");
-      const reg = await registerWebhook(token, webhookUrl);
-      if (reg.ok) {
-        console.log(progressLineImpl("Webhook registered", `${webhookUrl}/telegram/webhook`));
-      } else {
-        console.log(`  ${redImpl("✗")} Webhook registration failed — make sure the URL is publicly reachable.`);
-        console.log(`  ${dimImpl("Falling back to polling mode.")}`);
-        webhookUrl = "";
-      }
-    }
-  }
-
-  const pollingMode = !webhookUrl;
-
-  // Step 4: Write config
-  patchRuntimeToml(installDir, buildTelegramToml({
-    botTokenEnv, pollingMode, webhookUrl,
-    operatorChatId: chatId || "", authorizedChatIds, defaultAgent: agentId,
-  }));
-
-  // Store chat_id in state for later phases (e.g. hatch)
-  const result = { configured: true, verified: false, botUsername, botToken: token, operatorChatId: chatId || "" };
-
-  console.log(progressLineImpl("Telegram configured", webhookUrl ? "webhook" : "long-poll"));
-
-  // Step 5: Smoke test (with failure handling)
-  if (!chatId) {
-    console.log(`  ${yellowImpl("!")} No chat ID — skipping test message.`);
-    return result;
-  }
-
-  let verified = false;
-  let smokeAttempt = true;
-
-  while (smokeAttempt) {
-    console.log(progressLineImpl("Sending test message", chatId));
-    const smokeResult = await sendTestMessage(token, chatId, "Nemoris is running. Send me a message and I'll get to work.");
-
-    if (smokeResult.ok) {
-      console.log(progressLineImpl("Telegram connected", `message delivered to ${chatId}`));
-      verified = true;
-      smokeAttempt = false;
-    } else {
-      console.log(`  ${redImpl("✗")} Delivery failed: ${smokeResult.error}\n`);
-      const choice = await selectImpl("What next?", [
-        { label: "Retry", value: "retry" },
-        { label: `Skip — finish setup without verification`, value: "skip" },
-        { label: "Re-enter bot token", value: "retoken" },
-      ]);
-
-      if (choice === "retry") continue;
-      if (choice === "skip") {
-        smokeAttempt = false;
-      }
-      if (choice === "retoken") {
-        // Recursive — restart from Step 1
-        return runTelegramPhase({ installDir, agentId, nonInteractive, skipGate: true });
-      }
-    }
-  }
-
-  return { ...result, verified };
-}
-
-/**
- * Send the agent's "hatch" moment message to Telegram.
- *
- * When providerConfig and identity content are supplied, generates a
- * personalised AI greeting via the provider stack. Falls back to the
- * static greeting on provider failure or when no config is available.
- *
- * @param {{ token: string, chatId: string, agentName?: string, userName?: string, installDir?: string, agentId?: string, userGoal?: string, soulContent?: string, purposeContent?: string, providerConfig?: object, fetchImpl?: Function }} opts
- * @returns {Promise<boolean>}
- */
-export async function sendHatchMessage({
-  token,
-  chatId,
-  agentName,
-  userName,
-  installDir = null,
-  agentId = null,
-  userGoal = "",
-  soulContent = "",
-  purposeContent = "",
-  providerConfig = null,
-  migrated = false,
-  fetchImpl = globalThis.fetch,
-}) {
-  const name = stripAnsi(userName || "there");
-  const agent = stripAnsi(agentName || "your agent");
-
-  // Attempt provider-generated greeting
-  let text = null;
-  if (providerConfig) {
-    try {
-      const { generateGreeting } = await import("./hatch.js");
-      const result = await generateGreeting({
-        agentName: agent,
-        userName: name,
-        userGoal,
-        soulContent,
-        purposeContent,
-        providerConfig,
-        migrated,
-      });
-      if (result.fromProvider) {
-        text = result.greeting;
-      }
-    } catch {
-      // Fall through to static greeting
-    }
-  }
-
-  // Static fallback — tone matches migrated vs fresh
-  if (!text) {
-    const { staticGreeting } = await import("./hatch.js");
-    text = staticGreeting(agent, name, migrated);
-  }
-
-  // Write birth fact to memory (best-effort, non-blocking)
-  if (installDir && agentId) {
-    try {
-      const { writeBirthFact } = await import("./hatch.js");
-      await writeBirthFact({ installDir, agentId, agentName: agent, userName: name, migrated });
-    } catch {
-      // Non-fatal — don't fail the Telegram send
-    }
-  }
-
-  // Send to Telegram
-  const url = `https://api.telegram.org/bot${token}/sendMessage`;
-  try {
-    const res = await fetchImpl(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ chat_id: chatId, text }),
-    });
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
+/**
+ * Telegram onboarding sub-phase — optional, runs inside Build (Phase 3).
+ *
+ * Steps: token validation → chat_id discovery (daemon-aware) → mode selection
+ *        → config write → smoke test with failure handling.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { getMe, whoami } from "../../runtime/telegram-inbound.js";
+import { writeEnvFile } from "../auth/api-key.js";
+import { isDaemonRunning, setDaemonEnv } from "../platform.js";
+import { writeTomlSection } from "../toml-writer.js";
+import {
+  confirm, prompt, promptSecret, select, waitForEnter,
+  bold, green, red, yellow, dim, cyan, progressLine,
+} from "../tui.js";
+
+export const TELEGRAM_START_INSTRUCTION =
+  "Before continuing, open Telegram, search for your new bot, and send it /start — otherwise it won't be able to receive messages.";
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+export function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export function buildTelegramToml({ botTokenEnv, pollingMode, webhookUrl, operatorChatId, authorizedChatIds, defaultAgent }) {
+  const authIds = (authorizedChatIds || []).map((id) => `"${id}"`).join(", ");
+  return [
+    "",
+    "[telegram]",
+    `bot_token_env = "${botTokenEnv}"`,
+    `polling_mode = ${pollingMode}`,
+    `webhook_url = "${webhookUrl || ""}"`,
+    `operator_chat_id = "${operatorChatId || ""}"`,
+    `authorized_chat_ids = [${authIds}]`,
+    `default_agent = "${defaultAgent}"`,
+    "",
+  ].join("\n");
+}
+
+export function patchRuntimeToml(installDir, telegramToml) {
+  const runtimePath = path.join(installDir, "config", "runtime.toml");
+  writeTomlSection(runtimePath, "telegram", telegramToml);
+}
+
+async function sendTestMessage(token, chatId, text, { fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const url = `https://api.telegram.org/bot${token}/sendMessage`;
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ chat_id: chatId, text }),
+    });
+    const body = await res.json();
+    if (!body.ok) return { ok: false, error: `${res.status}: ${body.description || "unknown error"}` };
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * Discover chat_id when the daemon is running — polls active.db for a
+ * telegram interactive job created after `since` (ISO string).
+ */
+function discoverChatIdFromStore(installDir, since, { timeoutMs = 120_000, intervalMs = 2000 } = {}) {
+  const dbPath = path.join(installDir, "state", "active.db");
+  return new Promise((resolve) => {
+    const deadline = Date.now() + timeoutMs;
+
+    const tick = () => {
+      try {
+        // Lazy-require to avoid hard dep on better-sqlite3 at module level
+        const require = createRequire(import.meta.url);
+        const Database = require("better-sqlite3");
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        const row = db.prepare(
+          "SELECT chat_id FROM interactive_jobs WHERE source = 'telegram' AND created_at > ? ORDER BY created_at DESC LIMIT 1"
+        ).get(since);
+        db.close();
+        if (row?.chat_id) return resolve(row.chat_id);
+      } catch {
+        // DB may not exist yet or table missing — keep polling
+      }
+
+      if (Date.now() >= deadline) return resolve(null);
+      setTimeout(tick, intervalMs);
+    };
+    tick();
+  });
+}
+
+// ── Main Phase ───────────────────────────────────────────────────
+
+/**
+ * Run the Telegram onboarding sub-phase (interactive).
+ *
+ * @param {{ installDir: string, agentId: string, nonInteractive?: boolean, skipGate?: boolean }} options
+ * @returns {Promise<{ configured: boolean, verified: boolean, botUsername?: string }>}
+ */
+export async function runTelegramPhase({ installDir, agentId, nonInteractive = false, skipGate = false, tui = {} }) {
+  const botTokenEnv = "NEMORIS_TELEGRAM_BOT_TOKEN";
+  const confirmImpl = tui.confirm || confirm;
+  const promptImpl = tui.prompt || prompt;
+  const promptSecretImpl = tui.promptSecret || promptSecret;
+  const selectImpl = tui.select || select;
+  const waitForEnterImpl = tui.waitForEnter || waitForEnter;
+  const redImpl = tui.red || red;
+  const yellowImpl = tui.yellow || yellow;
+  const dimImpl = tui.dim || dim;
+  const cyanImpl = tui.cyan || cyan;
+  const progressLineImpl = tui.progressLine || progressLine;
+
+  // ── Non-interactive mode ───────────────────────────────────────
+  if (nonInteractive) {
+    const token = process.env[botTokenEnv];
+    if (!token || process.env.NEMORIS_SKIP_TELEGRAM === "true") {
+      return { configured: false, verified: false };
+    }
+
+    const me = await getMe(token);
+    if (!me.ok) return { configured: false, verified: false };
+
+    const chatId = process.env.NEMORIS_TELEGRAM_CHAT_ID || "";
+    const mode = process.env.NEMORIS_TELEGRAM_MODE || "polling";
+    const webhookUrl = process.env.NEMORIS_TELEGRAM_WEBHOOK_URL || "";
+
+    // Security: empty authorized_chat_ids with no chat_id means any sender is accepted.
+    // Require NEMORIS_ALLOW_ANY_CHAT=true to opt in to this open configuration.
+    if (!chatId && process.env.NEMORIS_ALLOW_ANY_CHAT !== "true") {
+      console.error("NEMORIS_TELEGRAM_CHAT_ID not set. Set it, or set NEMORIS_ALLOW_ANY_CHAT=true to allow any sender.");
+      return { configured: false, verified: false };
+    }
+
+    const authorizedChatIds = chatId ? [chatId] : [];
+
+    writeEnvFile(installDir, { [botTokenEnv]: token });
+    patchRuntimeToml(installDir, buildTelegramToml({
+      botTokenEnv, pollingMode: mode === "polling", webhookUrl,
+      operatorChatId: chatId, authorizedChatIds, defaultAgent: agentId,
+    }));
+
+    return { configured: true, verified: false, botUsername: me.username, botToken: token, operatorChatId: chatId };
+  }
+
+  // ── Interactive mode ───────────────────────────────────────────
+
+  // Gate
+  if (!skipGate) {
+    const gate = await confirmImpl(`Connect via ${cyanImpl("Telegram")}? This lets you message your agent from your phone.`, true);
+    if (!gate) {
+      return { configured: false, verified: false };
+    }
+  }
+
+  // Step 1: Bot token
+  let token = null;
+  let botUsername = null;
+
+  console.log(`\n  ${dimImpl("Need a bot token? Open Telegram → search @BotFather → send /newbot → follow the steps.")}`);
+  console.log(`  ${dimImpl("After creating your bot, open it in Telegram and tap Start before coming back here.")}`);
+  console.log(`  ${dimImpl("Your input will be hidden as you type — just paste and press Enter.")}\n`);
+
+  while (!token) {
+    const raw = await promptSecretImpl(`Your bot token`);
+    if (!raw) {
+      console.log(`  ${dimImpl("Skipping Telegram — you can add it later with `nemoris setup telegram`.")}`);
+      return { configured: false, verified: false };
+    }
+
+    const me = await getMe(raw);
+    if (me.ok) {
+      token = raw;
+      botUsername = me.username;
+      console.log(progressLineImpl("Token validated", `@${me.username}`));
+      console.log(`  ${dimImpl(TELEGRAM_START_INSTRUCTION)}`);
+    } else {
+      console.log(`  ${redImpl("✗")} That token didn't work — double-check it in BotFather and try again.`);
+      console.log(`  ${dimImpl("Try again or press Enter to skip.")}`);
+    }
+  }
+
+  // Write token to .env + daemon env
+  writeEnvFile(installDir, { [botTokenEnv]: token });
+  await setDaemonEnv(botTokenEnv, token);
+
+  // Step 2: Chat ID discovery
+  let chatId = null;
+  const daemonRunning = isDaemonRunning();
+
+  if (daemonRunning) {
+    // Path A: daemon is running — read from state store
+    console.log(`\n  Open Telegram, find ${cyanImpl(`@${botUsername}`)}, send it any message — then press Enter.`);
+    const since = new Date().toISOString();
+    chatId = await discoverChatIdFromStore(installDir, since);
+
+    if (chatId) {
+      console.log(progressLineImpl("Found you", `chat_id: ${chatId}`));
+    } else {
+      console.log(`  ${yellowImpl("!")} Timed out waiting for a message. Try opening Telegram and sending a message to @${botUsername} first.`);
+      const manual = await promptImpl("Enter chat_id manually (or press Enter to skip)", "");
+      chatId = manual || null;
+    }
+  } else {
+    // Path B: daemon not running — use whoami probe
+    await waitForEnterImpl(`Open Telegram, find ${cyanImpl(`@${botUsername}`)}, send it a message — anything works. Then come back and press Enter.`);
+    const result = await whoami(token);
+    if (result) {
+      chatId = String(result.chatId);
+      const label = result.username ? `chat_id: ${chatId}, @${result.username}` : `chat_id: ${chatId}`;
+      console.log(progressLineImpl("Found you", label));
+    } else {
+      console.log(`  ${yellowImpl("!")} No messages found.`);
+      console.log(`  ${dimImpl("The bot may not have received your message yet.")}`);
+      const manual = await promptImpl("Enter chat_id manually (or press Enter to skip)", "");
+      chatId = manual || null;
+    }
+  }
+
+  const authorizedChatIds = chatId ? [chatId] : [];
+
+  // Step 3: Delivery mode
+  const mode = await selectImpl("Delivery mode:", [
+    { label: `Long polling ${dimImpl("(recommended — no tunnel needed)")}`, value: "polling" },
+    { label: `Webhook — for servers with a public address (advanced)`, value: "webhook" },
+  ]);
+
+  let webhookUrl = "";
+  if (mode === "webhook") {
+    webhookUrl = await promptImpl("Public webhook URL", "");
+    if (webhookUrl) {
+      const { registerWebhook } = await import("../../runtime/telegram-inbound.js");
+      const reg = await registerWebhook(token, webhookUrl);
+      if (reg.ok) {
+        console.log(progressLineImpl("Webhook registered", `${webhookUrl}/telegram/webhook`));
+      } else {
+        console.log(`  ${redImpl("✗")} Webhook registration failed — make sure the URL is publicly reachable.`);
+        console.log(`  ${dimImpl("Falling back to polling mode.")}`);
+        webhookUrl = "";
+      }
+    }
+  }
+
+  const pollingMode = !webhookUrl;
+
+  // Step 4: Write config
+  patchRuntimeToml(installDir, buildTelegramToml({
+    botTokenEnv, pollingMode, webhookUrl,
+    operatorChatId: chatId || "", authorizedChatIds, defaultAgent: agentId,
+  }));
+
+  // Store chat_id in state for later phases (e.g. hatch)
+  const result = { configured: true, verified: false, botUsername, botToken: token, operatorChatId: chatId || "" };
+
+  console.log(progressLineImpl("Telegram configured", webhookUrl ? "webhook" : "long-poll"));
+
+  // Step 5: Smoke test (with failure handling)
+  if (!chatId) {
+    console.log(`  ${yellowImpl("!")} No chat ID — skipping test message.`);
+    return result;
+  }
+
+  let verified = false;
+  let smokeAttempt = true;
+
+  while (smokeAttempt) {
+    console.log(progressLineImpl("Sending test message", chatId));
+    const smokeResult = await sendTestMessage(token, chatId, "Nemoris is running. Send me a message and I'll get to work.");
+
+    if (smokeResult.ok) {
+      console.log(progressLineImpl("Telegram connected", `message delivered to ${chatId}`));
+      verified = true;
+      smokeAttempt = false;
+    } else {
+      console.log(`  ${redImpl("✗")} Delivery failed: ${smokeResult.error}\n`);
+      const choice = await selectImpl("What next?", [
+        { label: "Retry", value: "retry" },
+        { label: `Skip — finish setup without verification`, value: "skip" },
+        { label: "Re-enter bot token", value: "retoken" },
+      ]);
+
+      if (choice === "retry") continue;
+      if (choice === "skip") {
+        smokeAttempt = false;
+      }
+      if (choice === "retoken") {
+        // Recursive — restart from Step 1
+        return runTelegramPhase({ installDir, agentId, nonInteractive, skipGate: true });
+      }
+    }
+  }
+
+  return { ...result, verified };
+}
+
+/**
+ * Send the agent's "hatch" moment message to Telegram.
+ *
+ * When providerConfig and identity content are supplied, generates a
+ * personalised AI greeting via the provider stack. Falls back to the
+ * static greeting on provider failure or when no config is available.
+ *
+ * @param {{ token: string, chatId: string, agentName?: string, userName?: string, installDir?: string, agentId?: string, userGoal?: string, soulContent?: string, purposeContent?: string, providerConfig?: object, fetchImpl?: Function }} opts
+ * @returns {Promise<boolean>}
+ */
+export async function sendHatchMessage({
+  token,
+  chatId,
+  agentName,
+  userName,
+  installDir = null,
+  agentId = null,
+  userGoal = "",
+  soulContent = "",
+  purposeContent = "",
+  providerConfig = null,
+  migrated = false,
+  fetchImpl = globalThis.fetch,
+}) {
+  const name = stripAnsi(userName || "there");
+  const agent = stripAnsi(agentName || "your agent");
+
+  // Attempt provider-generated greeting
+  let text = null;
+  if (providerConfig) {
+    try {
+      const { generateGreeting } = await import("./hatch.js");
+      const result = await generateGreeting({
+        agentName: agent,
+        userName: name,
+        userGoal,
+        soulContent,
+        purposeContent,
+        providerConfig,
+        migrated,
+      });
+      if (result.fromProvider) {
+        text = result.greeting;
+      }
+    } catch {
+      // Fall through to static greeting
+    }
+  }
+
+  // Static fallback — tone matches migrated vs fresh
+  if (!text) {
+    const { staticGreeting } = await import("./hatch.js");
+    text = staticGreeting(agent, name, migrated);
+  }
+
+  // Write birth fact to memory (best-effort, non-blocking)
+  if (installDir && agentId) {
+    try {
+      const { writeBirthFact } = await import("./hatch.js");
+      await writeBirthFact({ installDir, agentId, agentName: agent, userName: name, migrated });
+    } catch {
+      // Non-fatal — don't fail the Telegram send
+    }
+  }
+
+  // Send to Telegram
+  const url = `https://api.telegram.org/bot${token}/sendMessage`;
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ chat_id: chatId, text }),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}