nebula-treasury 0.1.0

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
+    }
+  }
+}

package/src/config/load.ts

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { type NebulaConfig, agentPaths } from 'nebula-ai-core'
+
+/**
+ * Load the user's `nebula.config.ts`.
+ *
+ * Phase 6.6: canonical location is `~/.nebula/config.ts` (returned by
+ * `agentPaths.config`). If that file exists, it wins. Otherwise, fall back
+ * to walking upward from cwd looking for `nebula.config.ts` (legacy v0.5.0
+ * pattern, kept so existing dev setups still work without a migration step).
+ */
+export async function findAndLoadConfig(
+  startDir: string = process.cwd(),
+): Promise<{ config: NebulaConfig; path: string } | null> {
+  const canonical = agentPaths.config
+  if (existsSync(canonical)) {
+    const mod = (await import(canonical)) as { default: NebulaConfig }
+    if (!mod.default) throw new Error(`nebula config at ${canonical} has no default export`)
+    return { config: mod.default, path: canonical }
+  }
+
+  let dir = resolve(startDir)
+  while (true) {
+    const candidate = resolve(dir, 'nebula.config.ts')
+    if (existsSync(candidate)) {
+      const mod = (await import(candidate)) as { default: NebulaConfig }
+      if (!mod.default) throw new Error(`nebula.config.ts at ${candidate} has no default export`)
+      return { config: mod.default, path: candidate }
+    }
+    const parent = resolve(dir, '..')
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/config/render.ts

@@ -0,0 +1,99 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { NebulaConfig } from 'nebula-ai-core'
+
+export interface RenderConfigOpts {
+  header?: string
+}
+
+/**
+ * Serialize an NebulaConfig into a `~/.nebula/config.ts` file body.
+ *
+ * Phase 6.6: the config lives at `~/.nebula/config.ts` which is outside any
+ * workspace, so it MUST NOT import `nebula-ai-core` (the import won't
+ * resolve from `~/.nebula/`). We emit a plain `export default { ... }` object;
+ * the runtime loader treats it as `NebulaConfig` directly.
+ */
+export function renderConfigTs(cfg: NebulaConfig, opts: RenderConfigOpts = {}): string {
+  const header = opts.header ?? ''
+  const operatorLine = cfg.operator ? `  operator: ${JSON.stringify(cfg.operator)},\n` : ''
+  // Emit either the operator's chosen sandbox config OR an annotated
+  // "OPTION 1/2/3" block so the operator can opt in by uncommenting. Default
+  // mode stays `none` (passthrough); documentation IS the UX.
+  const sandboxBlock = renderSandboxBlock(cfg.sandbox)
+  return `${header ? `${header}\n\n` : ''}export default {
+  identity: ${JSON.stringify(cfg.identity)},
+  network: ${JSON.stringify(cfg.network)},
+  storage: { network: ${JSON.stringify(cfg.storage.network)} },
+  brain: {
+    provider: ${JSON.stringify(cfg.brain.provider)},
+    model: ${JSON.stringify(cfg.brain.model)},
+  },
+  plugins: ${JSON.stringify(cfg.plugins)},
+  tools: ${JSON.stringify(cfg.tools)},
+  imports: { claudeCode: ${cfg.imports.claudeCode} },
+${operatorLine}${sandboxBlock}}
+`
+}
+
+function renderSandboxBlock(sandbox: NebulaConfig['sandbox']): string {
+  // Phase 11: deploy-target sandbox metadata (id/providerAddress/endpoint/
+  // snapshotName) OR Phase 9.5 limb-sandbox mode = anything non-default → emit
+  // verbatim. Only surface the doc-comment template when the operator has
+  // touched neither.
+  const hasNonDefaultLimbMode = sandbox?.mode && sandbox.mode !== 'none'
+  if (hasNonDefaultLimbMode) {
+    return `  sandbox: ${JSON.stringify(sandbox, null, 2).replace(/\n/g, '\n  ')},\n`
+  }
+  // Fresh install: write the active default + commented examples for the
+  // other tiers. Operator can opt in by uncommenting and editing.
+  return `  sandbox: { mode: 'none' },
+  // ---------------------------------------------------------------------------
+  //  Limb sandbox (Phase 9.5). Defense-in-depth beneath the permission floor:
+  //  even when the modal grants 'allow session' or YOLO disables prompts,
+  //  the sandbox profile/container blocks writes outside an allowlist.
+  //  All shell.run / code.execute / shell.process_start spawns route through
+  //  the chosen backend. fs.* and browser.* still run on the host (PathGuard
+  //  applies). Override at runtime via NEBULA_SANDBOX_MODE=os|docker|none.
+  //
+  //  OPTION 1: none (default): passthrough, fastest, permission floor only.
+  //
+  //  OPTION 2: os (macOS sandbox-exec / seatbelt). Allows writes to agentDir +
+  //    cwd + /tmp/nebula-* + /var/folders. Denies reads of ~/.ssh, ~/.aws,
+  //    ~/Library/Keychains, ~/.config/gcloud. Linux bubblewrap pending.
+  //  sandbox: { mode: 'os' },
+  //
+  //  OPTION 3: docker (long-lived container per session), every shell-class
+  //    spawn through 'docker exec'. Auto-detects Docker Desktop or Podman.
+  //    Default image 'nikolaik/python-nodejs:python3.11-nodejs20' (matches
+  //    hermes; ~700 MB; bash + python3 + node + npm + git on standard PATH).
+  //    Override with 'oven/bun:1' (~250 MB) if you only need bun/ts.
+  //    'dockerMountWorkspace: true' bind-mounts your launch cwd into
+  //    /workspace (off by default for max isolation). 'dockerRuntimePath'
+  //    forces a specific runtime binary. Resource caps are unset by default
+  //    (container competes fairly with host work). Set them to mirror hermes'
+  //    production hardening: dockerCpu=1, dockerMemoryMb=5120, dockerDiskMb=
+  //    51200 (Linux+overlay2 only). dockerNoNetwork=true blocks all internet
+  //    access from the container (max paranoia for code.execute).
+  //  sandbox: {
+  //    mode: 'docker',
+  //    dockerImage: 'nikolaik/python-nodejs:python3.11-nodejs20',
+  //    dockerMountWorkspace: false,
+  //    // dockerRuntimePath: '/opt/homebrew/bin/podman',
+  //    // dockerCpu: 1,           // CPU cores cap
+  //    // dockerMemoryMb: 5120,   // 5 GB memory cap
+  //    // dockerDiskMb: 51200,    // 50 GB disk cap (Linux + overlay2 only)
+  //    // dockerNoNetwork: true,  // block all network from inside container
+  //  },
+  // ---------------------------------------------------------------------------
+`
+}
+
+export async function writeConfigTs(
+  path: string,
+  cfg: NebulaConfig,
+  opts: RenderConfigOpts = {},
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, renderConfigTs(cfg, opts), 'utf8')
+}