switchroom 0.5.0

package/telegram-plugin/foreman/setup-flow.ts

@@ -0,0 +1,345 @@
+/**
+ * Pure /setup wizard state machine.
+ *
+ * Walks the user through creating a new agent entirely from Telegram:
+ *   asked-slug       → ask for the agent slug (e.g. "gymbro")
+ *   asked-persona    → ask for the persona display name (e.g. "Gym Bro")
+ *   asked-model      → ask which Claude model to use (or skip for default)
+ *   asked-emoji      → ask for a topic emoji (or skip)
+ *   asked-bot-token  → user creates a bot via BotFather and pastes the token
+ *   confirming-allowlist → confirm the calling user_id is the allowed user
+ *   reconciling      → foreman provisions + starts the agent (orchestrator step)
+ *   done
+ *
+ * This module is pure: no grammY, no SQLite, no network calls.
+ * foreman.ts interprets the returned actions and executes side-effects.
+ *
+ * Deferral notes in foreman.ts:
+ *   // TODO(#<issue>): BotFather auto-flow — currently user creates bot manually
+ *   // TODO(#<issue>): OAuth code paste step — currently manual terminal instruction
+ *   // TODO(#<issue>): Skills selector — currently shows placeholder message
+ */
+
+import type { SetupFlowState, SetupFlowStep } from './setup-state.js'
+
+// ─── Action types ────────────────────────────────────────────────────────
+
+export type SetupFlowAction =
+  | { kind: 'ask-slug' }
+  | { kind: 'ask-persona'; slug: string }
+  | { kind: 'ask-model'; slug: string; persona: string }
+  | { kind: 'ask-emoji'; slug: string; persona: string; model: string | null }
+  | { kind: 'ask-profile'; slug: string; persona: string; model: string | null; emoji: string | null; profiles: string[] }
+  | { kind: 'ask-bot-token'; slug: string; persona: string; model: string | null; emoji: string | null; profile: string }
+  | { kind: 'confirm-allowlist'; slug: string; callerId: string }
+  // Pre-fix this was call-reconcile (single-step that did createAgent inline +
+  // told the user to run `switchroom auth code` from a terminal). Split per
+  // #189/#190 into call-create-agent (returns loginUrl) → asked-oauth-code
+  // (collects the code via Telegram) → call-complete-creation (runs the
+  // submit + starts the agent).
+  | { kind: 'call-create-agent'; slug: string; persona: string; model: string | null; emoji: string | null; profile: string; botToken: string; allowedUserId: string }
+  | { kind: 'ask-oauth-code'; slug: string; loginUrl: string | null }
+  | { kind: 'call-complete-creation'; slug: string; persona: string; code: string }
+  | { kind: 'done'; slug: string; botUsername: string | null }
+  | { kind: 'error'; message: string; stayInStep: boolean }
+  | { kind: 'cancel'; reason: string }
+
+// ─── Validation helpers ───────────────────────────────────────────────────
+
+/** Agent slug: same rules as assertSafeAgentName */
+export function isValidSlug(slug: string): boolean {
+  return /^[a-z0-9][a-z0-9_-]{0,50}$/.test(slug)
+}
+
+/** Persona name: 1-80 printable chars, no control characters */
+export function isValidPersonaName(name: string): boolean {
+  return name.length >= 1 && name.length <= 80 && !/[\x00-\x1f\x7f]/.test(name)
+}
+
+/** Known short model aliases and full IDs we accept */
+const KNOWN_MODEL_ALIASES = new Set(['sonnet', 'opus', 'haiku', 'inherit'])
+
+/** Model: alphanumeric with . _ - / [ ] : only, or short alias */
+export function isValidModel(model: string): boolean {
+  return KNOWN_MODEL_ALIASES.has(model.toLowerCase()) ||
+    /^[a-zA-Z0-9][a-zA-Z0-9._\-/[\]:]*$/.test(model)
+}
+
+/** Emoji: one or two Unicode grapheme clusters (rough check) */
+export function isValidEmoji(emoji: string): boolean {
+  const trimmed = emoji.trim()
+  return trimmed.length >= 1 && trimmed.length <= 16
+}
+
+/** Skip keywords */
+export function isSkip(text: string): boolean {
+  const t = text.trim().toLowerCase()
+  return t === 'skip' || t === 's' || t === '-'
+}
+
+/** Cancel keywords */
+export function isCancel(text: string): boolean {
+  const t = text.trim().toLowerCase()
+  return t === '/cancel' || t === 'cancel' || t === 'abort'
+}
+
+// ─── Flow entry point ────────────────────────────────────────────────────
+
+/**
+ * Start a new /setup wizard. Optionally pre-fills slug from inline arg.
+ */
+export function startSetupFlow(
+  inlineSlug: string | null,
+): SetupFlowAction {
+  if (!inlineSlug) {
+    return { kind: 'ask-slug' }
+  }
+
+  if (!isValidSlug(inlineSlug)) {
+    return {
+      kind: 'error',
+      message: `"${inlineSlug}" is not a valid agent slug. Use lowercase letters, numbers, hyphens or underscores (max 51 chars).`,
+      stayInStep: false,
+    }
+  }
+
+  return { kind: 'ask-persona', slug: inlineSlug }
+}
+
+// ─── Step transition ──────────────────────────────────────────────────────
+
+export interface SetupStepInput {
+  state: SetupFlowState | null
+  text: string
+  /** The Telegram user_id of the foreman caller (used for allowlist confirmation). */
+  callerId: string
+  /** Available profile names — passed through to the asked-profile step.
+   *  Foreman calls listAvailableProfiles() and forwards the list. */
+  profiles: string[]
+}
+
+/**
+ * Given the current state and user text, compute the next action.
+ * Returns 'cancel' with reason='user-cancelled' when the user types /cancel.
+ */
+export function handleSetupText(input: SetupStepInput): SetupFlowAction {
+  const { state, text, callerId, profiles } = input
+  const trimmed = text.trim()
+
+  if (!state) {
+    return { kind: 'cancel', reason: 'no-active-flow' }
+  }
+
+  // Global cancel at any step
+  if (isCancel(trimmed)) {
+    return { kind: 'cancel', reason: 'user-cancelled' }
+  }
+
+  switch (state.step) {
+    case 'asked-slug': {
+      if (!isValidSlug(trimmed)) {
+        return {
+          kind: 'error',
+          message: `"${trimmed}" is not a valid agent slug. Use lowercase letters, numbers, hyphens or underscores (max 51 chars). Try again:`,
+          stayInStep: true,
+        }
+      }
+      return { kind: 'ask-persona', slug: trimmed }
+    }
+
+    case 'asked-persona': {
+      const slug = state.slug ?? trimmed
+      if (!isValidPersonaName(trimmed)) {
+        return {
+          kind: 'error',
+          message: 'Persona name must be 1-80 printable characters. Try again:',
+          stayInStep: true,
+        }
+      }
+      return { kind: 'ask-model', slug, persona: trimmed }
+    }
+
+    case 'asked-model': {
+      const slug = state.slug ?? ''
+      const persona = state.persona ?? ''
+      if (isSkip(trimmed)) {
+        // Use default model
+        return { kind: 'ask-emoji', slug, persona, model: null }
+      }
+      if (!isValidModel(trimmed)) {
+        return {
+          kind: 'error',
+          message: `Unknown model "${trimmed}". Use <code>sonnet</code>, <code>opus</code>, <code>haiku</code>, a full model ID, or <code>skip</code> for the default:`,
+          stayInStep: true,
+        }
+      }
+      return { kind: 'ask-emoji', slug, persona, model: trimmed }
+    }
+
+    case 'asked-emoji': {
+      const slug = state.slug ?? ''
+      const persona = state.persona ?? ''
+      const model = state.model ?? null
+      const emoji = isSkip(trimmed) ? null : trimmed
+      if (!isSkip(trimmed) && !isValidEmoji(trimmed)) {
+        return {
+          kind: 'error',
+          message: 'Emoji must be 1-16 characters. Try again, or type <code>skip</code>:',
+          stayInStep: true,
+        }
+      }
+      // #190: gate on the profile selector before bot-token. The previous
+      // wizard skipped straight to bot-token and hard-coded profile='default'.
+      return { kind: 'ask-profile', slug, persona, model, emoji, profiles }
+    }
+
+    case 'asked-profile': {
+      // #190: validate against the live list passed in by the foreman.
+      if (!profiles.includes(trimmed)) {
+        return {
+          kind: 'error',
+          message: `Unknown profile "${escapeForMessage(trimmed)}". Choose one of: ${profiles.join(', ')}`,
+          stayInStep: true,
+        }
+      }
+      const slug = state.slug ?? ''
+      const persona = state.persona ?? ''
+      const model = state.model ?? null
+      const emoji = state.emoji ?? null
+      if (!slug || !persona) {
+        return { kind: 'cancel', reason: 'missing-slug-or-persona' }
+      }
+      return { kind: 'ask-bot-token', slug, persona, model, emoji, profile: trimmed }
+    }
+
+    case 'asked-bot-token': {
+      const slug = state.slug ?? ''
+      const persona = state.persona ?? ''
+      // Basic bot token shape check
+      if (!trimmed.includes(':') || trimmed.length < 20) {
+        return {
+          kind: 'error',
+          message: "That doesn't look like a BotFather token (expected <code>1234567890:AAH...</code>). Try again:",
+          stayInStep: true,
+        }
+      }
+      if (!slug || !persona) {
+        return { kind: 'cancel', reason: 'missing-slug-or-persona' }
+      }
+      return { kind: 'confirm-allowlist', slug, callerId }
+    }
+
+    case 'confirming-allowlist': {
+      const slug = state.slug ?? ''
+      const persona = state.persona ?? ''
+      const model = state.model ?? null
+      const emoji = state.emoji ?? null
+      // #190: profile is captured in asked-profile. Default to 'default' for
+      // legacy in-flight flows that started before the selector was added —
+      // they pre-date the schema migration and have profile=null.
+      const profile = state.profile ?? 'default'
+      const botToken = state.botToken ?? ''
+      const allowedUserId = trimmed.toLowerCase() === 'yes' || trimmed.toLowerCase() === 'y'
+        ? callerId
+        : trimmed // let the user override with a different user_id
+
+      if (!allowedUserId) {
+        return {
+          kind: 'error',
+          message: 'Please reply <b>yes</b> to use your own user_id, or paste a different user_id:',
+          stayInStep: true,
+        }
+      }
+      // #189: was 'call-reconcile' (createAgent + send-to-terminal); now
+      // 'call-create-agent' which returns loginUrl so we can ask for the
+      // OAuth code in-wizard. completeCreation runs in the next state.
+      return { kind: 'call-create-agent', slug, persona, model, emoji, profile, botToken, allowedUserId }
+    }
+
+    case 'asked-oauth-code': {
+      // #189: collect the OAuth code pasted by the user and pass it to
+      // call-complete-creation. Same shape as the create-flow's equivalent.
+      const slug = state.slug ?? ''
+      const persona = state.persona ?? ''
+      if (!slug) return { kind: 'cancel', reason: 'missing-slug' }
+      if (trimmed.length < 4) {
+        return {
+          kind: 'error',
+          message: 'That code looks too short. Paste the full code from the browser:',
+          stayInStep: true,
+        }
+      }
+      return { kind: 'call-complete-creation', slug, persona, code: trimmed }
+    }
+
+    case 'reconciling':
+      // Should not receive text during reconciliation — foreman handles this step programmatically
+      return { kind: 'cancel', reason: 'unexpected-text-in-reconciling' }
+
+    case 'done':
+      return { kind: 'cancel', reason: 'flow-already-done' }
+
+    default: {
+      const _exhaustive: never = state.step
+      return { kind: 'cancel', reason: `unknown-step:${String(_exhaustive)}` }
+    }
+  }
+}
+
+/** Tiny HTML-escape for inline error messages. The foreman renders these
+ *  via switchroomReply with html: true, so user-supplied text needs the
+ *  same escape pass the rest of the wizard does. */
+function escapeForMessage(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+// ─── State factory helpers ────────────────────────────────────────────────
+
+export function makeSetupInitialState(
+  chatId: string,
+  slug: string | null,
+): SetupFlowState {
+  const now = Date.now()
+  return {
+    chatId,
+    step: slug ? 'asked-persona' : 'asked-slug',
+    slug,
+    persona: null,
+    model: null,
+    emoji: null,
+    profile: null,
+    botToken: null,
+    allowedUserId: null,
+    authSessionName: null,
+    loginUrl: null,
+    startedAt: now,
+    updatedAt: now,
+  }
+}
+
+export function advanceSetupState(
+  state: SetupFlowState,
+  updates: Partial<Omit<SetupFlowState, 'chatId' | 'startedAt'>>,
+): SetupFlowState {
+  return {
+    ...state,
+    ...updates,
+    updatedAt: Date.now(),
+  }
+}
+
+/** Human-readable step label for resume messages. */
+export function setupStepLabel(step: SetupFlowStep): string {
+  switch (step) {
+    case 'asked-slug': return 'waiting for agent slug'
+    case 'asked-persona': return 'waiting for persona name'
+    case 'asked-model': return 'waiting for model choice'
+    case 'asked-emoji': return 'waiting for emoji'
+    case 'asked-profile': return 'waiting for profile selection'
+    case 'asked-bot-token': return 'waiting for BotFather token'
+    case 'confirming-allowlist': return 'waiting for allowlist confirmation'
+    case 'reconciling': return 'provisioning agent'
+    case 'asked-oauth-code': return 'waiting for OAuth code'
+    case 'done': return 'done'
+  }
+}

package/telegram-plugin/foreman/setup-state.ts

@@ -0,0 +1,239 @@
+/**
+ * /setup wizard conversation state — SQLite-backed per-chat state.
+ *
+ * Survives foreman restarts so a wizard started before a restart can resume.
+ *
+ * Location: ~/.switchroom/foreman/state.sqlite (same DB as create_flow)
+ * Override via SWITCHROOM_FOREMAN_DIR env var.
+ *
+ * Schema:
+ *   CREATE TABLE IF NOT EXISTS setup_flow (
+ *     chat_id         TEXT PRIMARY KEY,
+ *     step            TEXT NOT NULL,
+ *     slug            TEXT,
+ *     persona         TEXT,
+ *     model           TEXT,
+ *     emoji           TEXT,
+ *     bot_token       TEXT,
+ *     allowed_user_id TEXT,
+ *     started_at      INTEGER NOT NULL,
+ *     updated_at      INTEGER NOT NULL
+ *   );
+ */
+
+import { Database } from 'bun:sqlite'
+import { chmodSync, mkdirSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export type SetupFlowStep =
+  | 'asked-slug'
+  | 'asked-persona'
+  | 'asked-model'
+  | 'asked-emoji'
+  | 'asked-profile'        // #190: skills/profile selector before bot-token
+  | 'asked-bot-token'
+  | 'confirming-allowlist'
+  | 'reconciling'
+  | 'asked-oauth-code'     // #189: in-wizard OAuth code paste (replaces "go to terminal")
+  | 'done'
+
+export interface SetupFlowState {
+  chatId: string
+  step: SetupFlowStep
+  slug: string | null
+  persona: string | null
+  model: string | null
+  emoji: string | null
+  /** #190: which profile to use when scaffolding. Defaults to 'default'
+   *  for flows that started before the profile-selector step landed. */
+  profile: string | null
+  botToken: string | null
+  allowedUserId: string | null
+  /** #189: foreman captures these from createAgent's return value so the
+   *  asked-oauth-code step can render the URL and the call-complete-creation
+   *  action can find the right session. Null until call-create-agent runs. */
+  authSessionName: string | null
+  loginUrl: string | null
+  startedAt: number
+  updatedAt: number
+}
+
+// ─── DB singleton ─────────────────────────────────────────────────────────
+
+let _setupDb: Database | null = null
+
+function getSetupDb(): Database {
+  if (_setupDb) return _setupDb
+
+  const foremanDir =
+    process.env.SWITCHROOM_FOREMAN_DIR ?? join(homedir(), '.switchroom', 'foreman')
+
+  mkdirSync(foremanDir, { recursive: true, mode: 0o700 })
+
+  const dbPath = join(foremanDir, 'state.sqlite')
+  _setupDb = new Database(dbPath)
+  try {
+    chmodSync(dbPath, 0o600)
+  } catch {
+    // best-effort
+  }
+
+  _setupDb.exec(`
+    CREATE TABLE IF NOT EXISTS setup_flow (
+      chat_id         TEXT PRIMARY KEY,
+      step            TEXT NOT NULL,
+      slug            TEXT,
+      persona         TEXT,
+      model           TEXT,
+      emoji           TEXT,
+      bot_token       TEXT,
+      allowed_user_id TEXT,
+      started_at      INTEGER NOT NULL,
+      updated_at      INTEGER NOT NULL
+    );
+  `)
+
+  // #189/#190: idempotent column additions for installs that pre-date the
+  // profile + OAuth-code steps. ALTER TABLE ADD COLUMN is a no-op when the
+  // column already exists in SQLite ≥ 3.35; older versions throw — wrap in
+  // try/catch so the migration is forward-compatible.
+  for (const migration of [
+    `ALTER TABLE setup_flow ADD COLUMN profile TEXT`,
+    `ALTER TABLE setup_flow ADD COLUMN auth_session_name TEXT`,
+    `ALTER TABLE setup_flow ADD COLUMN login_url TEXT`,
+  ]) {
+    try {
+      _setupDb.exec(migration)
+    } catch {
+      // Column already exists. Ignore.
+    }
+  }
+
+  return _setupDb
+}
+
+// ─── Row type ─────────────────────────────────────────────────────────────
+
+interface SetupFlowRow {
+  chat_id: string
+  step: string
+  slug: string | null
+  persona: string | null
+  model: string | null
+  emoji: string | null
+  bot_token: string | null
+  allowed_user_id: string | null
+  started_at: number
+  updated_at: number
+  // #189/#190: nullable in legacy rows that pre-date the migration.
+  profile: string | null
+  auth_session_name: string | null
+  login_url: string | null
+}
+
+function rowToState(row: SetupFlowRow): SetupFlowState {
+  return {
+    chatId: row.chat_id,
+    step: row.step as SetupFlowStep,
+    slug: row.slug,
+    persona: row.persona,
+    model: row.model,
+    emoji: row.emoji,
+    profile: row.profile,
+    botToken: row.bot_token,
+    allowedUserId: row.allowed_user_id,
+    authSessionName: row.auth_session_name,
+    loginUrl: row.login_url,
+    startedAt: row.started_at,
+    updatedAt: row.updated_at,
+  }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/** Upsert the setup wizard state for a given chat. */
+export function setSetupState(state: SetupFlowState): void {
+  const db = getSetupDb()
+  db.prepare(`
+    INSERT INTO setup_flow
+      (chat_id, step, slug, persona, model, emoji, profile, bot_token,
+       allowed_user_id, auth_session_name, login_url, started_at, updated_at)
+    VALUES
+      ($chatId, $step, $slug, $persona, $model, $emoji, $profile, $botToken,
+       $allowedUserId, $authSessionName, $loginUrl, $startedAt, $updatedAt)
+    ON CONFLICT(chat_id) DO UPDATE SET
+      step              = excluded.step,
+      slug              = excluded.slug,
+      persona           = excluded.persona,
+      model             = excluded.model,
+      emoji             = excluded.emoji,
+      profile           = excluded.profile,
+      bot_token         = excluded.bot_token,
+      allowed_user_id   = excluded.allowed_user_id,
+      auth_session_name = excluded.auth_session_name,
+      login_url         = excluded.login_url,
+      updated_at        = excluded.updated_at
+  `).run({
+    $chatId: state.chatId,
+    $step: state.step,
+    $slug: state.slug,
+    $persona: state.persona,
+    $model: state.model,
+    $emoji: state.emoji,
+    $profile: state.profile,
+    $botToken: state.botToken,
+    $allowedUserId: state.allowedUserId,
+    $authSessionName: state.authSessionName,
+    $loginUrl: state.loginUrl,
+    $startedAt: state.startedAt,
+    $updatedAt: state.updatedAt,
+  })
+}
+
+/** Retrieve the setup wizard state for a given chat, or null if none. */
+export function getSetupState(chatId: string): SetupFlowState | null {
+  const db = getSetupDb()
+  const row = db.prepare<SetupFlowRow, [string]>(`
+    SELECT chat_id, step, slug, persona, model, emoji, profile, bot_token,
+           allowed_user_id, auth_session_name, login_url, started_at, updated_at
+    FROM setup_flow
+    WHERE chat_id = ?
+  `).get(chatId)
+
+  return row ? rowToState(row) : null
+}
+
+/** Remove the setup wizard state for a given chat. */
+export function clearSetupState(chatId: string): void {
+  const db = getSetupDb()
+  db.prepare('DELETE FROM setup_flow WHERE chat_id = ?').run(chatId)
+}
+
+/**
+ * List all in-progress setup flows updated within the last `maxAgeMs` ms.
+ * Used at foreman startup to resume flows that survived a restart.
+ */
+export function listActiveSetupFlows(maxAgeMs = 60 * 60 * 1000): SetupFlowState[] {
+  const db = getSetupDb()
+  const cutoff = Date.now() - maxAgeMs
+  const rows = db.prepare<SetupFlowRow, [number]>(`
+    SELECT chat_id, step, slug, persona, model, emoji, profile, bot_token,
+           allowed_user_id, auth_session_name, login_url, started_at, updated_at
+    FROM setup_flow
+    WHERE step != 'done' AND updated_at > ?
+    ORDER BY updated_at DESC
+  `).all(cutoff)
+
+  return rows.map(rowToState)
+}
+
+/** Reset the DB singleton (useful in tests to avoid sharing state). */
+export function _resetSetupDbForTest(): void {
+  if (_setupDb) {
+    _setupDb.close()
+    _setupDb = null
+  }
+}