nebula-ai-agent 0.3.1

package/src/commands/pairing-clear.ts

@@ -0,0 +1,39 @@
+import { confirm, isCancel } from '@clack/prompts'
+import { PairingStore, agentPaths, placeholderAgentId } from 'nebula-ai-core'
+import { findAndLoadConfig } from '../config/load'
+
+export interface RunPairingClearOpts {
+  platform?: string
+  yes?: boolean
+}
+
+export async function runPairingClear(opts: RunPairingClearOpts): Promise<void> {
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    console.error('No nebula.config.ts found. Run `nebula init` first.')
+    process.exit(1)
+  }
+  const { config } = loaded
+  if (!config.identity.agent) {
+    console.error('Config has no agent. Run `nebula init` first.')
+    process.exit(1)
+  }
+  const agentId = placeholderAgentId(config.identity.agent)
+  const dir = agentPaths.agent(agentId).pairingDir
+  const store = new PairingStore({ dir })
+
+  if (!opts.yes) {
+    const target = opts.platform ? `${opts.platform} pending` : 'ALL pending pairing codes'
+    const ok = await confirm({
+      message: `Clear ${target}?`,
+      initialValue: false,
+    })
+    if (isCancel(ok) || !ok) {
+      console.log('Aborted.')
+      return
+    }
+  }
+
+  const count = store.clearPending(opts.platform)
+  console.log(`✓ Cleared ${count} pending pairing code${count === 1 ? '' : 's'}`)
+}

package/src/commands/pairing-list.ts

@@ -0,0 +1,55 @@
+import { PairingStore, agentPaths, placeholderAgentId } from 'nebula-ai-core'
+import { findAndLoadConfig } from '../config/load'
+
+export interface RunPairingListOpts {
+  platform?: string
+}
+
+export async function runPairingList(opts: RunPairingListOpts): Promise<void> {
+  const store = await openPairingStore()
+  if (!store) return
+
+  const pending = store.listPending(opts.platform)
+  const approved = store.listApproved(opts.platform)
+
+  const pendingTitle = opts.platform ? `Pending (${opts.platform})` : 'Pending'
+  console.log(`\n${pendingTitle} (1h TTL):`)
+  if (pending.length === 0) {
+    console.log('  (none)')
+  } else {
+    for (const p of pending) {
+      const userLabel = p.userName ? `@${p.userName}` : '(unknown)'
+      const idLabel = `id=${p.userId}`
+      console.log(`  [${p.platform}] ${p.code}  ${userLabel} ${idLabel}  age=${p.ageMinutes}m`)
+    }
+  }
+
+  const approvedTitle = opts.platform ? `Approved (${opts.platform})` : 'Approved'
+  console.log(`\n${approvedTitle}:`)
+  if (approved.length === 0) {
+    console.log('  (none)')
+  } else {
+    for (const a of approved) {
+      const userLabel = a.userName ? `@${a.userName}` : '(unknown)'
+      const idLabel = `id=${a.userId}`
+      console.log(`  [${a.platform}] ${userLabel} ${idLabel}`)
+    }
+  }
+  console.log()
+}
+
+async function openPairingStore(): Promise<PairingStore | null> {
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    console.error('No nebula.config.ts found. Run `nebula init` first.')
+    return null
+  }
+  const { config } = loaded
+  if (!config.identity.agent) {
+    console.error('Config has no agent. Run `nebula init` first.')
+    return null
+  }
+  const agentId = placeholderAgentId(config.identity.agent)
+  const dir = agentPaths.agent(agentId).pairingDir
+  return new PairingStore({ dir })
+}

package/src/commands/pairing-revoke.ts

@@ -0,0 +1,49 @@
+import { confirm, isCancel } from '@clack/prompts'
+import { PairingStore, agentPaths, placeholderAgentId } from 'nebula-ai-core'
+import { findAndLoadConfig } from '../config/load'
+
+export interface RunPairingRevokeOpts {
+  platform: string
+  userId: string
+  yes?: boolean
+}
+
+export async function runPairingRevoke(opts: RunPairingRevokeOpts): Promise<void> {
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    console.error('No nebula.config.ts found. Run `nebula init` first.')
+    process.exit(1)
+  }
+  const { config } = loaded
+  if (!config.identity.agent) {
+    console.error('Config has no agent. Run `nebula init` first.')
+    process.exit(1)
+  }
+  const agentId = placeholderAgentId(config.identity.agent)
+  const dir = agentPaths.agent(agentId).pairingDir
+  const store = new PairingStore({ dir })
+
+  if (!store.isApproved(opts.platform, opts.userId)) {
+    console.error(`User ${opts.userId} is not on the ${opts.platform} approved list.`)
+    process.exit(1)
+  }
+
+  if (!opts.yes) {
+    const ok = await confirm({
+      message: `Revoke ${opts.platform} access for user id ${opts.userId}?`,
+      initialValue: false,
+    })
+    if (isCancel(ok) || !ok) {
+      console.log('Aborted.')
+      return
+    }
+  }
+
+  const removed = store.revoke(opts.platform, opts.userId)
+  if (removed) {
+    console.log(`✓ Revoked: ${opts.platform} id=${opts.userId}`)
+  } else {
+    console.error('Revoke failed (concurrent removal?)')
+    process.exit(1)
+  }
+}

package/src/commands/pairing.ts

@@ -0,0 +1,81 @@
+/**
+ * `nebula pairing <subcommand>` — argv dispatcher for the DM pairing flow.
+ *
+ * Subcommands:
+ *   list                          show pending codes + approved users
+ *   approve <platform> <code>     approve a pairing code (case-insensitive)
+ *   revoke <platform> <userId>    revoke an approved user
+ *   clear-pending [platform]      drop all pending codes
+ *
+ * Platform is `telegram` for Phase 12. Future platforms (discord, slack) will
+ * reuse the same command surface.
+ */
+
+export interface PairingArgs {
+  sub: 'list' | 'approve' | 'revoke' | 'clear-pending'
+  platform?: string
+  code?: string
+  userId?: string
+  yes?: boolean
+}
+
+const VALID_SUBS = ['list', 'approve', 'revoke', 'clear-pending'] as const
+
+export type PairingParseResult = PairingArgs | { error: string }
+
+export function parsePairingArgs(argv: string[]): PairingParseResult {
+  const sub = argv[0]
+  if (!sub) {
+    return {
+      error:
+        'usage: nebula pairing <list | approve <platform> <code> | revoke <platform> <userId> | clear-pending [platform]>',
+    }
+  }
+  if (!(VALID_SUBS as readonly string[]).includes(sub)) {
+    return { error: `unknown subcommand '${sub}' (expected: ${VALID_SUBS.join(' | ')})` }
+  }
+  const positional = argv.slice(1).filter(a => !a.startsWith('-'))
+  const yes = argv.includes('--yes') || argv.includes('-y')
+
+  if (sub === 'approve') {
+    if (positional.length < 2) {
+      return { error: 'usage: nebula pairing approve <platform> <code>' }
+    }
+    return { sub: 'approve', platform: positional[0], code: positional[1], yes }
+  }
+  if (sub === 'revoke') {
+    if (positional.length < 2) {
+      return { error: 'usage: nebula pairing revoke <platform> <userId>' }
+    }
+    return { sub: 'revoke', platform: positional[0], userId: positional[1], yes }
+  }
+  if (sub === 'clear-pending') {
+    return { sub: 'clear-pending', platform: positional[0], yes }
+  }
+  return { sub: 'list', platform: positional[0], yes }
+}
+
+export async function runPairing(args: PairingArgs): Promise<void> {
+  switch (args.sub) {
+    case 'list': {
+      const { runPairingList } = await import('./pairing-list')
+      await runPairingList({ platform: args.platform })
+      return
+    }
+    case 'approve': {
+      const { runPairingApprove } = await import('./pairing-approve')
+      await runPairingApprove({ platform: args.platform!, code: args.code! })
+      return
+    }
+    case 'revoke': {
+      const { runPairingRevoke } = await import('./pairing-revoke')
+      await runPairingRevoke({ platform: args.platform!, userId: args.userId!, yes: args.yes })
+      return
+    }
+    case 'clear-pending': {
+      const { runPairingClear } = await import('./pairing-clear')
+      await runPairingClear({ platform: args.platform, yes: args.yes })
+      return
+    }
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,44 @@
+import { existsSync, statSync } from 'node:fs'
+import { NETWORK_CHAIN_ID, NETWORK_RPC, agentPaths } from 'nebula-ai-core'
+import { http, createPublicClient } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import { listAgentIds } from './_agents'
+
+export async function runStatus(opts?: { cwd?: string }): Promise<void> {
+  const cwd = opts?.cwd ?? process.cwd()
+  const found = await findAndLoadConfig(cwd)
+  if (!found) {
+    console.log('No nebula.config.ts found. Run `nebula init` first.')
+    process.exit(1)
+  }
+  const { config, path } = found
+  console.log(`config    ${path}`)
+  console.log(`network   ${config.network} (chain ${NETWORK_CHAIN_ID[config.network]})`)
+  console.log(`rpc       ${NETWORK_RPC[config.network]}`)
+  console.log(`plugins   ${config.plugins.join(', ')}`)
+  if (config.identity.operator) console.log(`operator  ${config.identity.operator}`)
+  if (config.identity.agent) console.log(`agent EOA ${config.identity.agent}`)
+  console.log(`brain     ${config.brain.provider ?? '(not picked)'}`)
+
+  const ids = await listAgentIds()
+  if (ids.length === 0) {
+    console.log('\nNo agents found in ~/.nebula/agents. Re-run `nebula init`.')
+    return
+  }
+
+  const client = createPublicClient({
+    transport: http(NETWORK_RPC[config.network]),
+  })
+
+  for (const id of ids) {
+    console.log('')
+    console.log(`agent     ${id}`)
+    console.log(`dir       ${agentPaths.agent(id).dir}`)
+    const activityPath = agentPaths.agent(id).activityLog
+    if (existsSync(activityPath)) {
+      const sz = statSync(activityPath).size
+      console.log(`activity  ${sz} bytes`)
+    }
+    void client
+  }
+}

package/src/commands/telegram-remove.ts

@@ -0,0 +1,62 @@
+import { cancel, confirm, intro, isCancel, note, outro } from '@clack/prompts'
+import { placeholderAgentId } from 'nebula-ai-core'
+import { findAndLoadConfig } from '../config/load'
+import { writeConfigTs } from '../config/render'
+import {
+  removeTelegramSecrets,
+  telegramSecretsExist,
+  telegramSecretsPath,
+} from '../util/telegram-secrets'
+
+export interface TelegramRemoveOpts {
+  yes?: boolean
+}
+
+export async function runTelegramRemove(opts: TelegramRemoveOpts = {}): Promise<void> {
+  intro('nebula telegram remove')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No nebula.config.ts found. Run `nebula init` first.')
+    return
+  }
+  const { config, path: configPath } = loaded
+  if (!config.identity.agent) {
+    cancel('Config has no agent. Run `nebula init` first.')
+    return
+  }
+
+  const agentId = placeholderAgentId(config.identity.agent)
+
+  if (!telegramSecretsExist(agentId)) {
+    note('Nothing to remove.')
+    outro('not configured')
+    return
+  }
+
+  if (!opts.yes) {
+    const ok = (await confirm({
+      message: `Delete encrypted telegram-secrets for ${agentId}?`,
+      initialValue: false,
+    })) as boolean | symbol
+    if (isCancel(ok) || !ok) {
+      cancel('Aborted.')
+      return
+    }
+  }
+
+  await removeTelegramSecrets(agentId)
+
+  const plugins = (config.plugins ?? []).filter(p => p !== 'telegram')
+  if (plugins.length !== (config.plugins ?? []).length) {
+    const updated = { ...config, plugins }
+    await writeConfigTs(configPath, updated)
+  }
+
+  note(
+    `Local blob deleted: ${telegramSecretsPath(agentId)}\nThe bot token at @BotFather is STILL VALID. To fully revoke, run /token in\n@BotFather and pick "Revoke" for this bot.`,
+    'reminder',
+  )
+
+  outro('telegram removed')
+}

package/src/commands/telegram-setup.ts

@@ -0,0 +1,64 @@
+import { cancel, intro, note, outro } from '@clack/prompts'
+import { placeholderAgentId } from 'nebula-ai-core'
+import { type Address, getAddress } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+import { runTelegramStep } from './init/telegram-step'
+
+/**
+ * `nebula telegram setup` — standalone entry. Loads the operator wallet, then
+ * delegates to `runTelegramStep` (the same helper bundled into `nebula init`'s
+ * Phase E). Owns its own intro/outro framing.
+ */
+export async function runTelegramSetup(): Promise<void> {
+  intro('nebula telegram setup')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No nebula.config.ts found. Run `nebula init` first.')
+    return
+  }
+  const { config, path: configPath } = loaded
+  if (!config.identity.agent) {
+    cancel('Config has no agent. Run `nebula init` first.')
+    return
+  }
+
+  const agentAddress = getAddress(config.identity.agent) as Address
+  const agentId = placeholderAgentId(agentAddress)
+
+  const operator = await loadOrPickOperatorSigner({
+    network: config.network,
+    hint: config.operator,
+  })
+  if (!operator) {
+    cancel('No operator wallet available; cannot encrypt secrets.')
+    return
+  }
+
+  let result: Awaited<ReturnType<typeof runTelegramStep>>
+  try {
+    result = await runTelegramStep({
+      signer: operator,
+      agentId,
+      agentAddress,
+      configPath,
+      config,
+      network: config.network,
+    })
+  } finally {
+    await operator.close?.()
+  }
+
+  if (!result.configured) {
+    cancel(result.cancelled ? 'Aborted.' : 'Setup failed.')
+    return
+  }
+
+  note(
+    `Open https://t.me/${result.botUsername} in Telegram and send any message.\nThen run \`nebula\` (or \`nebula gateway start\`) to bring the agent online.`,
+    'next step',
+  )
+
+  outro(`telegram setup complete (@${result.botUsername}, mode: ${result.modeUsed})`)
+}

package/src/commands/telegram-status.ts

@@ -0,0 +1,87 @@
+import { cancel, intro, log, outro, spinner } from '@clack/prompts'
+import { placeholderAgentId } from 'nebula-ai-core'
+import { type Address, getAddress } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import {
+  fetchBotInfo,
+  loadTelegramSecrets,
+  telegramSecretsExist,
+  telegramSecretsPath,
+} from '../util/telegram-secrets'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+
+export async function runTelegramStatus(): Promise<void> {
+  intro('nebula telegram status')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No nebula.config.ts found. Run `nebula init` first.')
+    return
+  }
+  const { config } = loaded
+  if (!config.identity.agent) {
+    cancel('Config has no agent. Run `nebula init` first.')
+    return
+  }
+
+  const agentAddress = getAddress(config.identity.agent) as Address
+  const agentId = placeholderAgentId(agentAddress)
+  const path = telegramSecretsPath(agentId)
+
+  if (!telegramSecretsExist(agentId)) {
+    log.warn(`No telegram secrets stored for ${agentId}.`)
+    log.info(`Expected at: ${path}\nRun \`nebula telegram setup\` to configure.`)
+    outro('not configured')
+    return
+  }
+
+  const operator = await loadOrPickOperatorSigner({
+    network: config.network,
+    hint: config.operator,
+  })
+  if (!operator) {
+    cancel('No operator wallet available; cannot decrypt secrets.')
+    return
+  }
+
+  const sLoad = spinner()
+  sLoad.start('Decrypting telegram secrets via operator wallet')
+  let secrets: Awaited<ReturnType<typeof loadTelegramSecrets>>
+  try {
+    secrets = await loadTelegramSecrets({ signer: operator, agentAddress, agentId })
+    sLoad.stop('decrypted')
+  } catch (e) {
+    sLoad.stop(`decrypt failed: ${(e as Error).message.slice(0, 200)}`)
+    await operator.close?.()
+    return
+  } finally {
+    await operator.close?.()
+  }
+  if (!secrets) {
+    cancel('Empty telegram-secrets blob.')
+    return
+  }
+
+  const sPing = spinner()
+  sPing.start('Pinging Telegram getMe')
+  try {
+    const info = await fetchBotInfo(secrets.botToken)
+    sPing.stop(`bot ok: @${info.username} (id ${info.id})`)
+  } catch (e) {
+    sPing.stop(`getMe failed: ${(e as Error).message.slice(0, 200)}`)
+    log.warn('Token may have been revoked at @BotFather. Re-run `nebula telegram setup`.')
+    return
+  }
+
+  log.info(
+    [
+      `path             ${path}`,
+      `bot username     @${secrets.botUsername ?? '(unknown)'}`,
+      `bot id           ${secrets.botId ?? '(unknown)'}`,
+      `allowed user ids ${secrets.allowedUserIds.length === 0 ? '(open access)' : secrets.allowedUserIds.join(', ')}`,
+      `plugin enabled   ${(config.plugins ?? []).includes('telegram') ? 'yes' : 'no — add `telegram` to plugins'}`,
+    ].join('\n'),
+  )
+
+  outro(`telegram configured for ${agentId}`)
+}

package/src/commands/telegram.ts

@@ -0,0 +1,44 @@
+/**
+ * `nebula telegram <subcommand>` — argv dispatcher.
+ *
+ * Subcommands:
+ *   setup    interactive wizard: validate token, encrypt + persist locally
+ *   status   confirm token still valid + show stored config
+ *   remove   delete the encrypted local blob (does NOT revoke at @BotFather)
+ */
+
+export interface TelegramArgs {
+  sub: 'setup' | 'status' | 'remove'
+  yes?: boolean
+}
+
+const VALID_SUBS = ['setup', 'status', 'remove'] as const
+
+export function parseTelegramArgs(argv: string[]): TelegramArgs | { error: string } {
+  const sub = argv[0]
+  if (!sub) return { error: 'usage: nebula telegram <setup | status | remove>' }
+  const valid = (VALID_SUBS as readonly string[]).includes(sub)
+  if (!valid) return { error: `unknown subcommand '${sub}' (expected: ${VALID_SUBS.join(' | ')})` }
+  const yes = argv.includes('--yes') || argv.includes('-y')
+  return { sub: sub as TelegramArgs['sub'], yes }
+}
+
+export async function runTelegram(args: TelegramArgs): Promise<void> {
+  switch (args.sub) {
+    case 'setup': {
+      const { runTelegramSetup } = await import('./telegram-setup')
+      await runTelegramSetup()
+      return
+    }
+    case 'status': {
+      const { runTelegramStatus } = await import('./telegram-status')
+      await runTelegramStatus()
+      return
+    }
+    case 'remove': {
+      const { runTelegramRemove } = await import('./telegram-remove')
+      await runTelegramRemove({ yes: args.yes })
+      return
+    }
+  }
+}