nebula-treasury 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# nebula-treasury
+
+The `nebula` CLI — a **Mantle-native, policy-aware AI treasury assistant**. Real
+on-chain work on Mantle (balances, transfers, swaps, wrap/unwrap, Aave lending,
+yield discovery, ERC-8004 identity) from your terminal, where every value-moving
+action is checked against a deterministic policy, dry-run simulated, and held for
+approval before broadcast. The model proposes; code disposes.
+
+## Install
+
+```bash
+bun add -g nebula-treasury
+nebula init     # bootstrap an agent (plain-EOA identity, local encrypted keystore)
+nebula          # chat with your agent
+```
+
+Requires [bun](https://bun.sh) — the CLI shebangs `bun`.
+
+## Commands
+
+```
+nebula init                bootstrap a new agent identity + local keystore
+nebula [--yolo]            interactive chat (default; --yolo skips approvals)
+nebula status              agent + wallet + config state
+nebula logs                tail the activity log
+nebula drain --to <addr>   sweep the agent EOA balance
+nebula model               re-pick the brain model
+nebula identity <sub>      ERC-8004 agent identity  (card | register | show)
+nebula telegram <sub>      phone-DM gateway         (setup | status | remove)
+nebula pairing <sub>       DM pairing approvals     (list | approve | revoke | clear-pending)
+nebula gateway <sub>       always-on daemon         (run | start | stop | restart | status | logs)
+```
+
+Configure the brain with `OPENAI_API_KEY` (or any OpenAI-compatible `NEBULA_LLM_*`),
+set `NEBULA_POLICY_*` fund-control limits, and fund the agent EOA with a little MNT
+for gas. Material-risk actions pause for your approval.
+
+See the [root README](https://github.com/rstfulzz/nebula#readme) for architecture
+and the full reference.

package/bin/nebula

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+// Register the @opentui/solid JSX transform plugin BEFORE any .tsx file
+// loads. bunfig.toml's `preload` only fires when bun discovers bunfig.toml
+// in the cwd lookup chain — running `nebula` from outside the repo (e.g.
+// `cd ~ && nebula`, or as an installed npm bin) skips it entirely, leaving
+// JSX compiled as React.createElement and the chat TUI rendering blank.
+// Importing the preload module here registers the plugin regardless of
+// cwd. The plugin is idempotent so this is a no-op if bunfig.toml ALSO
+// loaded it.
+import '@opentui/solid/preload'
+import '../src/index'

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "nebula-treasury",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "nebula CLI: a Mantle-native, policy-aware AI treasury assistant. Real on-chain work gated by policy, simulation, and approval",
+  "license": "MIT",
+  "homepage": "https://github.com/rstfulzz/nebula",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rstfulzz/nebula.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/rstfulzz/nebula/issues"
+  },
+  "keywords": [
+    "nebula",
+    "ai",
+    "agent",
+    "cli",
+    "tui",
+    "mantle",
+    "treasury",
+    "defi",
+    "erc-8004"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "bin",
+    "README.md"
+  ],
+  "bin": {
+    "nebula": "bin/nebula"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "@opentui/core": "^0.1.97",
+    "@opentui/solid": "^0.1.97",
+    "nebula-ai-core": "0.1.0",
+    "nebula-ai-gateway": "0.1.0",
+    "nebula-ai-plugin-onchain": "0.1.0",
+    "nebula-ai-plugin-system": "0.1.0",
+    "nebula-ai-plugin-telegram": "0.1.0",
+    "picocolors": "^1.1.1",
+    "qrcode-terminal": "^0.12.0",
+    "solid-js": "^1.9.12",
+    "viem": "^2.21.55"
+  },
+  "devDependencies": {
+    "@types/qrcode-terminal": "^0.12.2"
+  }
+}

package/src/commands/_agents.ts

@@ -0,0 +1,14 @@
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { agentPaths } from 'nebula-ai-core'
+
+export async function listAgentIds(): Promise<string[]> {
+  if (!existsSync(agentPaths.agentsDir)) return []
+  const entries = await readdir(agentPaths.agentsDir, { withFileTypes: true })
+  return entries.filter(e => e.isDirectory()).map(e => e.name)
+}
+
+export async function pickDefaultAgent(): Promise<string | null> {
+  const ids = await listAgentIds()
+  return ids[0] ?? null
+}

package/src/commands/_unlock.ts

@@ -0,0 +1,66 @@
+import { readFile } from 'node:fs/promises'
+import { spinner } from '@clack/prompts'
+import {
+  type NebulaConfig,
+  type NebulaNetwork,
+  agentPaths,
+  decodeKeystoreBytes,
+  decryptAgentKey,
+  placeholderAgentId,
+} from 'nebula-ai-core'
+import type { Address, Hex } from 'viem'
+import { withSilencedConsole } from '../util/silence-console'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+
+export interface UnlockedAgent {
+  agentPrivkey: Hex
+  agentAddress: Address
+  network: NebulaNetwork
+  close: () => Promise<void>
+}
+
+/**
+ * Shared operator-unlock dance for any command that needs the agent privkey:
+ *  1. pick the operator signer (keystore / WC / keychain) per config hint
+ *  2. read the local encrypted keystore cache
+ *  3. decrypt via operator signature
+ *
+ * Returns null if the operator picker is cancelled or the keystore can't be
+ * decrypted; caller should bail out early on null.
+ *
+ * Caller MUST call `close()` once done with the privkey, even on success, to
+ * release WC sessions / keystore tmpfiles.
+ */
+export async function unlockAgentSigner(
+  config: NebulaConfig,
+  spinnerLabel = 'Decrypting agent keystore via operator wallet',
+): Promise<UnlockedAgent | null> {
+  if (!config.identity.agent) return null
+  const network = config.network
+  const agentAddress = config.identity.agent as Address
+  const agentId = placeholderAgentId(agentAddress)
+  const paths = agentPaths.agent(agentId)
+
+  const operator = await loadOrPickOperatorSigner({ network, hint: config.operator })
+  if (!operator) return null
+
+  const close = async () => {
+    await operator.close?.()
+  }
+
+  const s = spinner()
+  s.start(spinnerLabel)
+  try {
+    const agentPrivkey = await withSilencedConsole(async (): Promise<Hex> => {
+      const raw = await readFile(paths.keystore, 'utf8')
+      const keystore = decodeKeystoreBytes(new TextEncoder().encode(raw))
+      return (await decryptAgentKey({ signer: operator, agentAddress, keystore })) as Hex
+    })
+    s.stop('unlocked (keystore source: local)')
+    return { agentPrivkey, agentAddress, network, close }
+  } catch (e) {
+    s.stop(`unlock failed: ${(e as Error).message.slice(0, 160)}`)
+    await close()
+    return null
+  }
+}

package/src/commands/chat-telegram.ts

@@ -0,0 +1,398 @@
+/**
+ * Local-mode telegram dispatch wiring for chat.tsx.
+ *
+ * Two pieces:
+ *
+ *  1. `buildTelegramRuntimeContext`: composes the side-band context the plugin
+ *     consumes via `(ctx as any).telegram`. The context's `dispatchUserMessage`
+ *     points at a *deferred* callback ref; chat.tsx populates the ref AFTER
+ *     brain init but BEFORE any inbound TG message can race.
+ *
+ *  2. `buildTelegramDispatch`: factory for the deferred callback itself.
+ *     Returns a handle with `{ dispatch, drainQueue, getQueueSize }`. chat.tsx
+ *     wires the dispatch into the slot AND subscribes to status idle so it
+ *     can call drainQueue to wake any messages that arrived during a stdin
+ *     turn (closes G4 starvation).
+ *
+ * Bypass commands (parseBypassCommand) skip the queue + busy gate. `/stop`
+ * aborts the active brain turn; `/status` reports thinking/idle; the rest
+ * are placeholders for future B5 inline-keyboard approvals.
+ */
+import type {
+  ActivityLog,
+  Brain,
+  FrozenPrefix,
+  PermissionDecision,
+  PermissionPrompter,
+  PermissionRequest,
+  PermissionService,
+} from 'nebula-ai-core'
+import { applyPerms, applyYolo, newEventId } from 'nebula-ai-core'
+import {
+  ActiveSessionTracker,
+  type ApprovalChoice,
+  type BypassCommand,
+  type TelegramApprovalBridge,
+  type TelegramDispatchInput,
+  type TelegramDispatchResult,
+  type TelegramRuntimeContext,
+  makeApprovalIdFactory,
+  parseBypassCommand,
+} from 'nebula-ai-plugin-telegram'
+import { summarizeApprovalSubject } from '../ui/approval-summary'
+
+export type DispatchUserMessage = (input: TelegramDispatchInput) => Promise<TelegramDispatchResult>
+
+/**
+ * Mutable callback ref. chat.tsx holds it across boot; we hand the ref into
+ * the plugin's runtime context via a closure that defers to the ref's current
+ * value at call-time.
+ */
+export interface TelegramDispatchSlot {
+  current: DispatchUserMessage | null
+}
+
+export interface RowSinkRef {
+  current: ((text: string) => void) | null
+}
+
+export function buildTelegramRuntimeContext(opts: {
+  botToken: string
+  allowedUserIds: number[]
+  agentName: string
+  slot: TelegramDispatchSlot
+  systemRowSink: RowSinkRef
+}): TelegramRuntimeContext {
+  return {
+    botToken: opts.botToken,
+    allowedUserIds: opts.allowedUserIds,
+    agentName: opts.agentName,
+    dispatchUserMessage: async input => {
+      const cb = opts.slot.current
+      if (!cb) {
+        return {
+          response: 'agent is still booting; try again in a moment.',
+        }
+      }
+      return cb(input)
+    },
+    onProcessingStart: async (chatId, _msgId) => {
+      opts.systemRowSink.current?.(`tg replying to chat ${chatId}`)
+    },
+    onProcessingEnd: async (chatId, _msgId, ok) => {
+      opts.systemRowSink.current?.(
+        ok ? `tg reply sent to chat ${chatId}` : `tg reply FAILED to chat ${chatId}`,
+      )
+    },
+  }
+}
+
+export interface BuildDispatchDeps {
+  activity: ActivityLog
+  /** Local-only memory persists via the memory.* tools; flushTurn is a no-op. */
+  sync: { flushTurn: () => Promise<{ txHash: string | null; changedSlots: string[] }> }
+  permission: PermissionService
+  pushAssistantRow: (text: string) => void
+  pushInboundRow: (preview: string) => void
+  /** Returns true if the brain is currently busy on another turn. */
+  isBusy: () => boolean
+  buildPrefix: () => Promise<FrozenPrefix>
+  brain: Brain & { refreshUserContext: (prefix: FrozenPrefix) => void }
+  /** Mark the brain as "thinking" / idle in the TUI state. */
+  setThinking: (on: boolean) => void
+  setActiveAbort: (ctrl: AbortController | null) => void
+  refreshBalances: () => void
+  formatInboundPreview: (input: TelegramDispatchInput) => string
+  /**
+   * Optional approval bridge from the listener. When present, dispatch swaps
+   * permission.setPrompter to a TG-aware prompter for the turn duration so
+   * the operator can approve tool calls from their phone via inline keyboard.
+   */
+  approvalBridge?: TelegramApprovalBridge
+}
+
+export interface TelegramDispatchHandle {
+  dispatch: DispatchUserMessage
+  /** Re-run the queue. Called by chat.tsx when stdin turn ends (closes G4). */
+  drainQueue: () => void
+  getQueueSize: () => number
+}
+
+/**
+ * Build the deferred dispatch callback. Caller assigns `handle.dispatch` into
+ * `slot.current` once brain.init resolves, and wires `handle.drainQueue` into
+ * a status-change effect.
+ */
+export function buildTelegramDispatch(deps: BuildDispatchDeps): TelegramDispatchHandle {
+  const queue: { input: TelegramDispatchInput; resolve: (r: TelegramDispatchResult) => void }[] = []
+  let draining = false
+  const tracker = new ActiveSessionTracker()
+  const pendingApprovals = new Map<string, (choice: ApprovalChoice) => void>()
+  const approvalIdFactory = makeApprovalIdFactory()
+  let callbackInstalled = false
+  const ensureCallbackInstalled = (): void => {
+    if (callbackInstalled) return
+    const install = deps.approvalBridge?.installCallbackHandler.current
+    if (!install) return
+    install((approvalId, choice, _fromUserId) => {
+      const r = pendingApprovals.get(approvalId)
+      if (r) {
+        pendingApprovals.delete(approvalId)
+        r(choice)
+      }
+    })
+    callbackInstalled = true
+  }
+
+  const drain = async (): Promise<void> => {
+    if (draining) return
+    draining = true
+    try {
+      while (queue.length > 0) {
+        if (deps.isBusy()) return
+        const item = queue.shift()!
+        ensureCallbackInstalled()
+        try {
+          const r = await runOne(item.input, deps, tracker, {
+            pendingApprovals,
+            approvalIdFactory,
+          })
+          item.resolve(r)
+        } catch (err) {
+          item.resolve({
+            response: `error processing your message: ${(err as Error).message.slice(0, 200)}`,
+          })
+        }
+      }
+    } finally {
+      draining = false
+    }
+  }
+
+  return {
+    dispatch: (input: TelegramDispatchInput) =>
+      new Promise<TelegramDispatchResult>(resolve => {
+        deps.pushInboundRow(deps.formatInboundPreview(input))
+
+        // Bypass commands skip the queue + busy gate entirely.
+        const bypass = parseBypassCommand(input.text)
+        if (bypass) {
+          void Promise.resolve(handleBypass(bypass, input, deps, tracker)).then(resolve)
+          return
+        }
+
+        queue.push({ input, resolve })
+        void drain()
+      }),
+    drainQueue: () => {
+      void drain()
+    },
+    getQueueSize: () => queue.length,
+  }
+}
+
+async function handleBypass(
+  bypass: { command: BypassCommand; args: string[] },
+  input: TelegramDispatchInput,
+  deps: BuildDispatchDeps,
+  tracker: ActiveSessionTracker,
+): Promise<TelegramDispatchResult> {
+  const { command: cmd, args } = bypass
+  switch (cmd) {
+    case '/stop': {
+      const aborted = tracker.abortActive(input.sessionKey)
+      if (!aborted && deps.isBusy()) {
+        return { response: 'no active turn to stop here, but the agent is busy on stdin.' }
+      }
+      return {
+        response: aborted ? 'stopped the current turn.' : 'no active turn to stop.',
+      }
+    }
+    case '/new':
+    case '/reset': {
+      // v0.20.0: real reset clears this channel's history. Falls back to a
+      // friendly note when the brain doesn't expose channel ops (StubBrain).
+      if (typeof deps.brain.clearChannel === 'function') {
+        await deps.brain.clearChannel(input.sessionKey)
+        return { response: "conversation reset (this chat's history cleared)." }
+      }
+      return { response: 'this brain does not support reset.' }
+    }
+    case '/status': {
+      const busy = deps.isBusy()
+      const qs = '' // queue size could be read via closure; keep terse here
+      return {
+        response: busy ? `currently thinking on another turn${qs}.` : `idle${qs}.`,
+      }
+    }
+    case '/approve':
+    case '/deny': {
+      return {
+        response: 'inline-keyboard approval is not yet wired in this build (B5 ships in v0.18.1).',
+      }
+    }
+    case '/yolo': {
+      const r = applyYolo(deps.permission)
+      return { response: r.message }
+    }
+    case '/perms': {
+      const r = applyPerms(deps.permission, args[0])
+      return { response: r.message }
+    }
+    case '/background':
+    case '/restart': {
+      return { response: `${cmd} is reserved for a future bundle.` }
+    }
+  }
+}
+
+interface RunOneOpts {
+  pendingApprovals: Map<string, (c: ApprovalChoice) => void>
+  approvalIdFactory: () => string
+}
+
+async function runOne(
+  input: TelegramDispatchInput,
+  deps: BuildDispatchDeps,
+  tracker: ActiveSessionTracker,
+  opts: RunOneOpts,
+): Promise<TelegramDispatchResult> {
+  // If the listener filled the approval bridge, swap the permission prompter
+  // to the TG-aware one for the turn duration. The brain will issue an
+  // inline-keyboard approval message; the operator clicks from their phone;
+  // the callback resolves the prompter's Promise. Permission resolves go
+  // through the normal PermissionService.resolve path: 'off' bypass, 'strict'
+  // deny, 'prompt' consults the prompter. We use 'prompt' for TG turns so
+  // the bridge is exercised; chat-telegram previously forced 'off' to bypass
+  // the TUI modal entirely.
+  const previousPrompter = (deps.permission as unknown as { prompter: PermissionPrompter }).prompter
+  const bridgeReady =
+    !!deps.approvalBridge?.sendApproval.current &&
+    !!deps.approvalBridge?.installCallbackHandler.current
+  const previousMode = deps.permission.getMode()
+  if (bridgeReady) {
+    const tgPrompter = buildTelegramPrompter({
+      chatId: input.chatId,
+      bridge: deps.approvalBridge!,
+      pendingApprovals: opts.pendingApprovals,
+      approvalIdFactory: opts.approvalIdFactory,
+    })
+    deps.permission.setPrompter(tgPrompter)
+    // Use 'prompt' so dangerous patterns + value-moving txs route through the
+    // TG prompter. Tools without prompts (e.g. fs.read) still pass.
+    deps.permission.setMode('prompt')
+  } else {
+    // No bridge: fall back to YOLO so brain doesn't deadlock on a TUI modal
+    // the phone-side operator can't reach.
+    deps.permission.setMode('off')
+  }
+  deps.setThinking(true)
+  const abortCtrl = new AbortController()
+  deps.setActiveAbort(abortCtrl)
+  // Synchronous mark-active BEFORE any await closes the race window per
+  // hermes base.py:1471. Two messages in the same tick now see the lock.
+  tracker.markActive(input.sessionKey, abortCtrl)
+  try {
+    const refreshed = await deps.buildPrefix()
+    deps.brain.refreshUserContext(refreshed)
+    await deps.activity.append({
+      ts: Date.now(),
+      kind: 'wake',
+      data: { source: 'telegram', chatId: input.chatId, userId: input.userId },
+    })
+    const turn = await deps.brain.infer({
+      event: {
+        id: newEventId(),
+        source: 'telegram',
+        payload: { label: 'telegram-message', data: input.text },
+        ts: Date.now(),
+      },
+      channelKey: input.sessionKey,
+      signal: abortCtrl.signal,
+      // Forward per-turn tool-call observer to the brain. The listener
+      // attaches a ProgressTracker on every dispatch; dropping it here
+      // would silently disable TG's live progress message.
+      onToolEvent: input.onToolEvent
+        ? ev => {
+            input.onToolEvent?.({
+              kind: ev.kind,
+              tool: ev.tool,
+              callId: ev.callId,
+              argsPreview: ev.argsPreview,
+              ok: ev.ok,
+            })
+          }
+        : undefined,
+    })
+    await deps.activity.append({
+      ts: Date.now(),
+      kind: 'brain-response',
+      data: {
+        content: turn.content,
+        toolCalls: turn.toolCalls.length,
+        finishReason: turn.finishReason,
+        usage: turn.usage,
+        source: 'telegram',
+      },
+    })
+    const response = (turn.content ?? '').trim()
+    if (response.length > 0) deps.pushAssistantRow(response)
+    deps.refreshBalances()
+    let syncTx: string | undefined
+    try {
+      const res = await deps.sync.flushTurn()
+      if (res.txHash) syncTx = res.txHash
+    } catch {
+      // sync errors stay in the activity log; not surfaced to TG.
+    }
+    return { response: response.length === 0 ? '(no reply)' : response, syncTx }
+  } finally {
+    deps.setThinking(false)
+    deps.setActiveAbort(null)
+    tracker.markIdle(input.sessionKey)
+    deps.permission.setMode(previousMode)
+    if (bridgeReady && previousPrompter) {
+      deps.permission.setPrompter(previousPrompter)
+    }
+  }
+}
+
+const APPROVAL_TIMEOUT_MS = 5 * 60_000
+
+function buildTelegramPrompter(opts: {
+  chatId: number
+  bridge: TelegramApprovalBridge
+  pendingApprovals: Map<string, (c: ApprovalChoice) => void>
+  approvalIdFactory: () => string
+}): PermissionPrompter {
+  return async (req: PermissionRequest) => {
+    const send = opts.bridge.sendApproval.current
+    if (!send) return 'deny'
+    const approvalId = opts.approvalIdFactory()
+    const body = formatApprovalBody(req)
+    return new Promise<PermissionDecision>(resolve => {
+      const timer = setTimeout(() => {
+        if (opts.pendingApprovals.delete(approvalId)) resolve('deny')
+      }, APPROVAL_TIMEOUT_MS)
+      opts.pendingApprovals.set(approvalId, choice => {
+        clearTimeout(timer)
+        resolve(mapChoiceToDecision(choice))
+      })
+      void send(opts.chatId, body, approvalId).catch(() => {
+        clearTimeout(timer)
+        if (opts.pendingApprovals.delete(approvalId)) resolve('deny')
+      })
+    })
+  }
+}
+
+function mapChoiceToDecision(choice: ApprovalChoice): PermissionDecision {
+  if (choice === 'once') return 'allow-once'
+  if (choice === 'session' || choice === 'always') return 'allow-session'
+  return 'deny'
+}
+
+function formatApprovalBody(req: PermissionRequest): string {
+  const subject = summarizeApprovalSubject(req)
+  return `🔐 Approval needed for ${req.kind}\n\n${subject}\n\nReason: ${req.reason}`
+}