nebula-ai-core 0.1.0

package/src/chain.ts

@@ -0,0 +1,75 @@
+import {
+  http,
+  type Chain,
+  type Hex,
+  type PublicClient,
+  type WalletClient,
+  createPublicClient,
+  createWalletClient,
+  defineChain,
+} from 'viem'
+import { type PrivateKeyAccount, privateKeyToAccount } from 'viem/accounts'
+import { NETWORK_CHAIN_ID, NETWORK_RPC, type NebulaNetwork } from './config'
+
+/**
+ * Static fallback floor when `eth_gasPrice` is unreachable. 4 gwei matches the
+ * current Mantle mainnet floor (verified Apr 27 2026). Real callers should prefer
+ * `getGasPriceWithFloor` so the value tracks network conditions; this constant
+ * is the safety net.
+ *
+ * History: was 2.5 gwei; bumped to 4 gwei when txs began rejecting with
+ * "gas required exceeds allowance" (Geth's misleading wording for min-fee
+ * rejection, not OOG).
+ */
+export const MIN_GAS_PRICE = 4_000_000_000n
+
+/**
+ * Read the network's current `eth_gasPrice` and return `max(networkPrice, MIN_GAS_PRICE)`.
+ * Falls back to MIN_GAS_PRICE on RPC failure. Always returns a value safe to
+ * pass as `maxFeePerGas` / `maxPriorityFeePerGas` for an EIP-1559 tx; the
+ * floor protects against a momentarily-low quote, and using the live value
+ * means we don't underpay when the network's floor moves up.
+ */
+export async function getGasPriceWithFloor(client: PublicClient): Promise<bigint> {
+  try {
+    const price = await client.getGasPrice()
+    return price > MIN_GAS_PRICE ? price : MIN_GAS_PRICE
+  } catch {
+    return MIN_GAS_PRICE
+  }
+}
+
+/** Empirical gas budget for `Mantle Storage Flow.submit()`. Used by preflight balance checks. */
+export const STORAGE_SUBMIT_GAS = 250_000n
+
+export function mantleChain(network: NebulaNetwork): Chain {
+  const isMainnet = network === 'mantle-mainnet'
+  return defineChain({
+    id: NETWORK_CHAIN_ID[network],
+    name: isMainnet ? 'Mantle' : 'Mantle Sepolia Testnet',
+    nativeCurrency: { name: 'Mantle', symbol: 'MNT', decimals: 18 },
+    rpcUrls: { default: { http: [NETWORK_RPC[network]] } },
+    blockExplorers: {
+      default: {
+        name: isMainnet ? 'MantleScan' : 'Mantle Sepolia Explorer',
+        url: isMainnet ? 'https://mantlescan.xyz' : 'https://sepolia.mantlescan.xyz',
+      },
+    },
+  })
+}
+
+export interface ViemClients {
+  chain: Chain
+  account: PrivateKeyAccount
+  publicClient: PublicClient
+  walletClient: WalletClient
+}
+
+export function makeViemClients(opts: { network: NebulaNetwork; privkeyHex: Hex }): ViemClients {
+  const chain = mantleChain(opts.network)
+  const account = privateKeyToAccount(opts.privkeyHex)
+  const transport = http(NETWORK_RPC[opts.network])
+  const publicClient = createPublicClient({ transport, chain })
+  const walletClient = createWalletClient({ transport, account, chain })
+  return { chain, account, publicClient, walletClient }
+}

package/src/claude-plugins/discovery.ts

@@ -0,0 +1,152 @@
+import type { Dirent } from 'node:fs'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { ClaudeAgent, ClaudeCommand, ClaudeExtrasDiscoveryResult } from './types'
+
+export interface ClaudeExtrasOptions {
+  importsClaudeCode?: boolean
+  /** Override for ~/.claude/plugins/cache/. */
+  claudePluginsCacheRoot?: string
+}
+
+export async function discoverClaudeExtras(
+  opts: ClaudeExtrasOptions = {},
+): Promise<ClaudeExtrasDiscoveryResult> {
+  const importsClaudeCode = opts.importsClaudeCode ?? true
+  if (!importsClaudeCode) return { commands: [], agents: [] }
+  const cacheRoot = opts.claudePluginsCacheRoot ?? join(homedir(), '.claude', 'plugins', 'cache')
+  const commands: ClaudeCommand[] = []
+  const agents: ClaudeAgent[] = []
+
+  let marketplaces: Dirent[]
+  try {
+    const s = await stat(cacheRoot)
+    if (!s.isDirectory()) return { commands, agents }
+    marketplaces = (await readdir(cacheRoot, { withFileTypes: true })) as Dirent[]
+  } catch {
+    return { commands, agents }
+  }
+
+  for (const market of marketplaces) {
+    if (!market.isDirectory()) continue
+    const marketDir = join(cacheRoot, market.name)
+    let plugins: Dirent[]
+    try {
+      plugins = (await readdir(marketDir, { withFileTypes: true })) as Dirent[]
+    } catch {
+      continue
+    }
+    for (const plugin of plugins) {
+      if (!plugin.isDirectory()) continue
+      const pluginDir = join(marketDir, plugin.name)
+      let versions: Dirent[]
+      try {
+        versions = (await readdir(pluginDir, { withFileTypes: true })) as Dirent[]
+      } catch {
+        continue
+      }
+      const versionDirs = versions
+        .filter(v => v.isDirectory())
+        .map(v => v.name)
+        .sort()
+      const latest = versionDirs[versionDirs.length - 1]
+      if (!latest) continue
+      const versionDir = join(pluginDir, latest)
+      const source = { marketplace: market.name, plugin: plugin.name, version: latest }
+      await collectFromDir(join(versionDir, 'commands'), source, 'command', commands, agents)
+      await collectFromDir(join(versionDir, 'agents'), source, 'agent', commands, agents)
+    }
+  }
+  return { commands, agents }
+}
+
+async function collectFromDir(
+  dir: string,
+  source: { marketplace: string; plugin: string; version: string },
+  kind: 'command' | 'agent',
+  commands: ClaudeCommand[],
+  agents: ClaudeAgent[],
+): Promise<void> {
+  let entries: Dirent[]
+  try {
+    const s = await stat(dir)
+    if (!s.isDirectory()) return
+    entries = (await readdir(dir, { withFileTypes: true })) as Dirent[]
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+    const filePath = join(dir, entry.name)
+    let raw: string
+    try {
+      raw = await readFile(filePath, 'utf8')
+    } catch {
+      continue
+    }
+    const parsed = parseFile(raw)
+    if (!parsed) continue
+    const id = `${source.plugin}:${parsed.name ?? entry.name.replace(/\.md$/, '')}`
+    const name = parsed.name ?? entry.name.replace(/\.md$/, '')
+    if (kind === 'command') {
+      commands.push({
+        id,
+        name,
+        description: parsed.description ?? '',
+        argumentHint: parsed.argumentHint,
+        path: filePath,
+        body: parsed.body,
+        source,
+      })
+    } else {
+      agents.push({
+        id,
+        name,
+        description: parsed.description ?? '',
+        model: parsed.model,
+        path: filePath,
+        body: parsed.body,
+        source,
+      })
+    }
+  }
+}
+
+interface ParsedFile {
+  name?: string
+  description?: string
+  argumentHint?: string
+  model?: string
+  body: string
+}
+
+function parseFile(raw: string): ParsedFile | null {
+  if (!raw.startsWith('---')) {
+    return { body: raw }
+  }
+  const end = raw.indexOf('\n---', 4)
+  if (end === -1) return { body: raw }
+  const block = raw.slice(4, end)
+  const body = raw.slice(end + 4).replace(/^\n/, '')
+  const out: ParsedFile = { body }
+  for (const line of block.split('\n')) {
+    const m = line.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/)
+    if (!m?.[1]) continue
+    const key = m[1]
+    const value = unquote(m[2] ?? '')
+    if (key === 'name') out.name = value
+    else if (key === 'description') out.description = value
+    else if (key === 'argument-hint' || key === 'argumentHint') out.argumentHint = value
+    else if (key === 'model') out.model = value
+  }
+  return out
+}
+
+function unquote(s: string): string {
+  const t = s.trim()
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1)
+  }
+  return t
+}

package/src/claude-plugins/index.ts

@@ -0,0 +1,6 @@
+export { discoverClaudeExtras, type ClaudeExtrasOptions } from './discovery'
+export type {
+  ClaudeCommand,
+  ClaudeAgent,
+  ClaudeExtrasDiscoveryResult,
+} from './types'

package/src/claude-plugins/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Phase 9.2 Bundle 8 surfaces: Claude Code commands + agents discovered from
+ * the local plugin cache. Both are markdown files with YAML frontmatter; the
+ * body is the prompt that nebula inlines when the command/agent fires.
+ */
+
+export interface ClaudeCommand {
+  /** `<plugin>:<name>` (nebula drops the marketplace prefix; the cmd surface is flat). */
+  id: string
+  /** Bare command name (e.g. `setup`, `mode`, `commit`). */
+  name: string
+  description: string
+  /** Optional argument-hint shown after the slash command in help. */
+  argumentHint?: string
+  /** Absolute path to the markdown file. */
+  path: string
+  /** Body without frontmatter; this is the prompt template nebula inlines. */
+  body: string
+  /** Source plugin coordinates (marketplace, plugin, version). */
+  source: { marketplace: string; plugin: string; version: string }
+}
+
+export interface ClaudeAgent {
+  /** `<plugin>:<name>` */
+  id: string
+  name: string
+  description: string
+  /** Optional model hint from frontmatter (e.g. `sonnet`). nebula ignores it (uses configured brain). */
+  model?: string
+  path: string
+  body: string
+  source: { marketplace: string; plugin: string; version: string }
+}
+
+export interface ClaudeExtrasDiscoveryResult {
+  commands: ClaudeCommand[]
+  agents: ClaudeAgent[]
+}

package/src/commands/index.ts

@@ -0,0 +1,16 @@
+export {
+  COMMAND_REGISTRY,
+  applyPerms,
+  applyYolo,
+  commandsForSurface,
+  findCommand,
+  parseSlash,
+  suggestForPrefix,
+  type ApplyResult,
+  type CommandScope,
+  type CommandSurface,
+  type ParsedSlash,
+  type PermissionApi,
+  type PermissionToggleMode,
+  type SlashCommand,
+} from './registry'

package/src/commands/registry.ts

@@ -0,0 +1,255 @@
+/**
+ * Shared slash-command registry. The TUI autocomplete popup, TG
+ * `setMyCommands` registration, and the various bypass dispatchers all read
+ * from this single source so command lists never drift between surfaces.
+ */
+
+export type CommandSurface = 'tui' | 'tg'
+
+/**
+ * - `local`  : runs in the CLI process (TUI handler, local TG via chat-telegram)
+ * - `gateway`: runs in the gateway process (sandbox harness or local-mode gateway daemon)
+ * - `both`   : valid in either surface; routing decided by where the command arrives
+ */
+export type CommandScope = 'local' | 'gateway' | 'both'
+
+export interface SlashCommand {
+  /** Command name without leading slash, e.g. "yolo". Lowercased. */
+  name: string
+  /** One-line human description used in TUI menu + TG client menu. */
+  description: string
+  /** Surfaces the command should appear in for discovery. */
+  surfaces: CommandSurface[]
+  /** Where the command actually executes. */
+  scope: CommandScope
+  /** True when the command short-circuits before brain.infer (control commands). */
+  bypassesBrain: boolean
+  /** Optional argument hint shown next to the name in menus, e.g. "off|prompt|strict". */
+  argHint?: string
+}
+
+export const COMMAND_REGISTRY: SlashCommand[] = [
+  {
+    name: 'yolo',
+    description: 'Toggle approval prompts on/off',
+    surfaces: ['tui', 'tg'],
+    scope: 'both',
+    bypassesBrain: true,
+  },
+  {
+    name: 'perms',
+    description: 'Set permission mode',
+    surfaces: ['tui', 'tg'],
+    scope: 'both',
+    bypassesBrain: true,
+    argHint: 'off|prompt|strict',
+  },
+  {
+    name: 'reset',
+    description: 'Clear conversation history for this channel',
+    surfaces: ['tui', 'tg'],
+    scope: 'both',
+    bypassesBrain: true,
+  },
+  {
+    name: 'sync',
+    description: 'Force memory sync to Mantle Storage',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'model',
+    description: 'Show brain model switch hint',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'jobs',
+    description: 'List active marketplace jobs',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'help',
+    description: 'Show all commands',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'exit',
+    description: 'Quit nebula',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'quit',
+    description: 'Quit nebula',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'stop',
+    description: 'Cancel current turn',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'new',
+    description: 'Start a fresh session',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'status',
+    description: 'Show agent status',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'approve',
+    description: 'Approve the pending request',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'deny',
+    description: 'Deny the pending request',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'background',
+    description: 'Move the current turn to background',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'restart',
+    description: 'Restart the active session',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+]
+
+export function commandsForSurface(surface: CommandSurface): SlashCommand[] {
+  return COMMAND_REGISTRY.filter(c => c.surfaces.includes(surface))
+}
+
+export function findCommand(name: string): SlashCommand | undefined {
+  const needle = name.replace(/^\/+/, '').toLowerCase()
+  return COMMAND_REGISTRY.find(c => c.name === needle)
+}
+
+export interface ParsedSlash {
+  /** Raw command name lowercased, no leading slash. */
+  name: string
+  /** Whitespace-split argv after the command. */
+  args: string[]
+  /** Resolved registry entry when name matches a known command, otherwise undefined. */
+  command?: SlashCommand
+}
+
+/**
+ * Parse a leading-slash message into name + args. Returns null when the input
+ * doesn't start with a slash. Unknown command names still return a parsed
+ * shape (with `command` undefined) so callers can distinguish "not a slash"
+ * from "slash but unknown".
+ */
+export function parseSlash(text: string): ParsedSlash | null {
+  const trimmed = text.trimStart()
+  if (!trimmed.startsWith('/')) return null
+  const stripped = trimmed.slice(1).trimEnd()
+  if (stripped.length === 0) return null
+  const parts = stripped.split(/\s+/)
+  const name = (parts[0] ?? '').toLowerCase()
+  if (name.length === 0) return null
+  const args = parts.slice(1)
+  return { name, args, command: findCommand(name) }
+}
+
+/**
+ * Filter commands by surface and prefix for autocomplete suggestions.
+ * Empty or single-`/` query returns all commands for the surface.
+ */
+export function suggestForPrefix(surface: CommandSurface, query: string): SlashCommand[] {
+  const stripped = query.replace(/^\/+/, '').toLowerCase()
+  const all = commandsForSurface(surface)
+  if (stripped.length === 0) return all
+  return all.filter(c => c.name.startsWith(stripped))
+}
+
+/**
+ * Permission modes operators can flip via /yolo and /perms. Matches
+ * `PermissionMode` from `../permission` but redeclared here to avoid the
+ * commands module taking a transitive dependency on the permission service.
+ */
+export type PermissionToggleMode = 'off' | 'prompt' | 'strict'
+
+export interface PermissionApi {
+  getMode(): PermissionToggleMode
+  setMode(mode: PermissionToggleMode): void
+}
+
+export interface ApplyResult {
+  /** Operator-facing message describing the new state. */
+  message: string
+  /** Mode after the operation, for callers that mirror UI state. */
+  mode: PermissionToggleMode
+}
+
+/**
+ * Toggle approval prompts between `off` (YOLO) and `prompt` (re-enable).
+ * `strict` flips to `prompt` on toggle to give an off-ramp from lockdown.
+ * Single source of truth; consumed by TUI `/yolo`, TG-local `/yolo`, and
+ * gateway TG `/yolo` so wording stays in lockstep.
+ */
+export function applyYolo(permission: PermissionApi): ApplyResult {
+  const cur = permission.getMode()
+  const next: PermissionToggleMode = cur === 'off' ? 'prompt' : 'off'
+  permission.setMode(next)
+  return {
+    mode: next,
+    message:
+      next === 'off'
+        ? 'YOLO ON. Approval prompts disabled for this session.'
+        : 'YOLO OFF. Approvals back on.',
+  }
+}
+
+/**
+ * Set the permission mode explicitly. `arg === undefined` returns the current
+ * mode without mutation. Returns the same `{ message, mode }` shape so callers
+ * have one branch instead of two for "show vs set".
+ */
+export function applyPerms(
+  permission: PermissionApi,
+  arg: string | undefined,
+): ApplyResult | { message: string; mode: PermissionToggleMode; error: true } {
+  if (!arg) {
+    const mode = permission.getMode()
+    return { mode, message: `perms: ${mode}` }
+  }
+  const lower = arg.toLowerCase()
+  if (lower !== 'off' && lower !== 'prompt' && lower !== 'strict') {
+    return {
+      mode: permission.getMode(),
+      message: `unknown perms mode '${arg}'. try: off | prompt | strict`,
+      error: true,
+    }
+  }
+  permission.setMode(lower as PermissionToggleMode)
+  return { mode: lower as PermissionToggleMode, message: `perms set to ${lower}` }
+}