nebula-ai-core 0.1.0

package/src/config.ts

@@ -0,0 +1,213 @@
+/**
+ * User-facing configuration shape for `nebula.config.ts`.
+ *
+ * Example:
+ *
+ *   import { defineConfig } from 'nebula-ai-core'
+ *
+ *   export default defineConfig({
+ *     network: 'mantle-mainnet',              // or 'mantle-testnet'
+ *     storage: { network: 'mantle-mainnet' },
+ *     brain: { model: 'gpt-4o-mini' },        // chosen at `nebula init`
+ *     plugins: ['onchain', 'system'],
+ *     tools: { 'defi.*': false, 'shell.run': false },
+ *     imports: { claudeCode: true },
+ *   })
+ */
+
+export type NebulaNetwork = 'mantle-mainnet' | 'mantle-testnet'
+
+export type NebulaPlugin = 'onchain' | 'comms' | 'system' | 'telegram'
+
+export type OperatorSourceKind = 'walletconnect' | 'keychain' | 'keystore-file' | 'raw-privkey'
+
+/**
+ * Persisted hint about which operator source to use when commands like
+ * `nebula` (chat) and `nebula drain` need to talk to the operator wallet
+ * again. Stores enough metadata to reconstruct the signer without re-prompting
+ * the user from scratch (passphrases / QR scans still happen per-session).
+ */
+export interface OperatorSourceHint {
+  source: OperatorSourceKind
+  /** Only for `keychain`: the macOS Keychain service name to read. */
+  keychainService?: string
+  /** Only for `keystore-file`: absolute or `~`-prefixed path to the JSON keystore. */
+  keystorePath?: string
+}
+
+export interface NebulaConfig {
+  identity: {
+    /** Operator wallet address that encrypts (and can recover) the agent keystore. */
+    operator: string | null
+    /** Agent EOA address (separate key, signs + pays gas). */
+    agent: string | null
+  }
+  network: NebulaNetwork
+  storage: {
+    network: NebulaNetwork
+  }
+  brain: {
+    provider: string | null
+    model: string | null
+    /** Max assistant output tokens per turn. Default 4096. */
+    maxOutputTokens?: number
+    /**
+     * Model context window. Used for auto-compaction trigger. Default
+     * 1_000_000. Override for smaller models.
+     */
+    contextWindow?: number
+    /**
+     * Pre-flight summarize-fold of older history when the running estimate
+     * breaches `threshold * contextWindow`. Set to `null` to disable.
+     * Default: { threshold: 0.5, keepRecent: 8 }.
+     */
+    compaction?: {
+      threshold?: number
+      keepRecent?: number
+    } | null
+    /**
+     * Persist channel histories to JSONL under
+     * `~/.nebula/agents/<id>/conversations/`. Loaded on boot, appended per
+     * turn, atomically rewritten on compaction. Default true.
+     */
+    persistConversations?: boolean
+  }
+  plugins: NebulaPlugin[]
+  /** Glob-level tool allow/deny. Right-most match wins. */
+  tools: Record<string, boolean>
+  imports: {
+    claudeCode: boolean
+  }
+  /**
+   * Which operator source to use when reconnecting. Optional so legacy configs
+   * still parse; commands fall back to the interactive picker when missing.
+   */
+  operator?: OperatorSourceHint | null
+  /**
+   * Permission system. `prompt` (default) prompts on dangerous commands;
+   * `strict` always denies them; `off` is YOLO (no prompts). The `--yolo` CLI
+   * flag and `/yolo` TUI slash both flip the active service to 'off' for the
+   * current session without rewriting the file.
+   */
+  approvals?: {
+    mode: 'strict' | 'prompt' | 'off'
+    /** Always-approved patterns (regex against `kind|command|path` signature). */
+    allowlist?: string[]
+  }
+  /**
+   * Skills system. `disabled` is the persistent list of skill ids that should
+   * never auto-load or appear in the index.
+   */
+  skills?: {
+    disabled?: string[]
+  }
+  /**
+   * Operator-supplied additions to the system prompt. `append` is concatenated
+   * under a `# Operator instructions` header AFTER nebula's built-in safety +
+   * tool-use scaffolding. Can NOT replace the base prompt; use it for personal
+   * rules ("always reply in Indonesian", "prefer Bun over npm").
+   */
+  prompt?: {
+    append?: string | null
+  }
+  /**
+   * Multimodal vision routing. Vision limbs (vision.analyze, browser.vision)
+   * call this OpenAI-compatible provider; the brain stays on `brain.provider`.
+   * Set `null` to disable; tools then return a clear "not configured" error.
+   */
+  vision?: {
+    provider?: string | null
+  }
+  /**
+   * Structural sandbox for limb spawns. Defense-in-depth BENEATH the permission
+   * floor — even when `s` (allow session) or yolo grants a destructive command,
+   * the sandbox profile prevents writes outside an allowlist (agentDir +
+   * workspaceRoot + /tmp/nebula-* + /var/folders).
+   *
+   *  - `none` (default): passthrough. Permission floor only.
+   *  - `os`: native OS sandbox. macOS = sandbox-exec wrapper. Linux = bubblewrap.
+   *  - `docker`: long-lived container per session, every spawn through `docker exec`.
+   */
+  sandbox?: {
+    mode?: 'none' | 'os' | 'docker'
+    /**
+     * docker mode only: container image. Default `oven/bun:1`. Compatible with
+     * Docker Desktop AND Podman. Override for custom tooling.
+     */
+    dockerImage?: string
+    /**
+     * docker mode only: bind-mount the host's workspaceRoot into the container
+     * at /workspace. Default `false` for max isolation.
+     */
+    dockerMountWorkspace?: boolean
+    /**
+     * docker mode only: force a specific container runtime binary. Auto-detect
+     * by default (tries docker, then podman).
+     */
+    dockerRuntimePath?: string
+    /** docker mode only: CPU cores cap (`--cpus`). Default unlimited. */
+    dockerCpu?: number
+    /** docker mode only: memory cap in MB (`--memory <N>m`). Default unlimited. */
+    dockerMemoryMb?: number
+    /**
+     * docker mode only: per-container writable-layer disk cap in MB. Linux +
+     * overlay2 with pquota only — silently dropped on macOS / podman.
+     */
+    dockerDiskMb?: number
+    /**
+     * docker mode only: block all network access from inside the container
+     * (`--network=none`). Default false.
+     */
+    dockerNoNetwork?: boolean
+  }
+}
+
+export type NebulaConfigInput = Partial<NebulaConfig> & Pick<NebulaConfig, 'network'>
+
+const DEFAULT_CONFIG: Omit<NebulaConfig, 'network' | 'storage'> = {
+  identity: { operator: null, agent: null },
+  brain: { provider: null, model: null },
+  plugins: ['onchain', 'system'],
+  tools: {},
+  imports: { claudeCode: true },
+  operator: null,
+  approvals: { mode: 'prompt', allowlist: [] },
+  skills: { disabled: [] },
+  prompt: { append: null },
+  vision: { provider: undefined },
+  sandbox: { mode: 'none' },
+}
+
+export function defineConfig(input: NebulaConfigInput): NebulaConfig {
+  return {
+    ...DEFAULT_CONFIG,
+    identity: input.identity ?? DEFAULT_CONFIG.identity,
+    network: input.network,
+    storage: input.storage ?? { network: input.network },
+    brain: input.brain ?? DEFAULT_CONFIG.brain,
+    plugins: input.plugins ?? DEFAULT_CONFIG.plugins,
+    tools: input.tools ?? DEFAULT_CONFIG.tools,
+    imports: input.imports ?? DEFAULT_CONFIG.imports,
+    operator: input.operator ?? DEFAULT_CONFIG.operator,
+    approvals: input.approvals ?? DEFAULT_CONFIG.approvals,
+    skills: input.skills ?? DEFAULT_CONFIG.skills,
+    prompt: input.prompt ?? DEFAULT_CONFIG.prompt,
+    vision: input.vision ?? DEFAULT_CONFIG.vision,
+    sandbox: input.sandbox ?? DEFAULT_CONFIG.sandbox,
+  }
+}
+
+export const NETWORK_RPC: Record<NebulaNetwork, string> = {
+  'mantle-mainnet': 'https://rpc.mantle.xyz',
+  'mantle-testnet': 'https://rpc.sepolia.mantle.xyz',
+}
+
+export const NETWORK_CHAIN_ID: Record<NebulaNetwork, number> = {
+  'mantle-mainnet': 5000,
+  'mantle-testnet': 5003,
+}
+
+export function networkFromChainId(id: number): NebulaNetwork | null {
+  return (Object.entries(NETWORK_CHAIN_ID).find(([, cid]) => cid === id)?.[0] ??
+    null) as NebulaNetwork | null
+}

package/src/economy/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Economy module. The legacy decentralized-compute self-funding manager was
+ * removed with the 0G compute backend (Nebula uses an API-key LLM). Reserved
+ * for Mantle-native economy primitives (treasury limits, spend caps, etc.).
+ */
+export {}

package/src/events/index.ts

@@ -0,0 +1,4 @@
+export type { NebulaEvent, EventPayload, EventSource } from './types'
+export { EventQueue, newEventId } from './queue'
+export { type Listener, listeners } from './listeners'
+export { routeLoop, type RouterDeps } from './router'

package/src/events/listeners.ts

@@ -0,0 +1,37 @@
+import type { EventQueue } from './queue'
+
+/**
+ * A Listener watches some source (stdin, chain, a2a, ...) and pushes events
+ * onto the queue. Plugins contribute listeners via `registerListener()`.
+ */
+export interface Listener {
+  name: string
+  source: string
+  start(queue: EventQueue): Promise<void>
+  stop(): Promise<void>
+}
+
+class ListenerRegistry {
+  private registered: Listener[] = []
+
+  register(l: Listener): void {
+    if (this.registered.some(x => x.name === l.name)) {
+      throw new Error(`Listener already registered: ${l.name}`)
+    }
+    this.registered.push(l)
+  }
+
+  list(): readonly Listener[] {
+    return this.registered
+  }
+
+  async startAll(queue: EventQueue): Promise<void> {
+    await Promise.all(this.registered.map(l => l.start(queue)))
+  }
+
+  async stopAll(): Promise<void> {
+    await Promise.all(this.registered.map(l => l.stop()))
+  }
+}
+
+export const listeners = new ListenerRegistry()

package/src/events/queue.ts

@@ -0,0 +1,63 @@
+import type { NebulaEvent } from './types'
+
+/**
+ * Minimal in-memory FIFO queue. Async-iterable so consumers `for await` over
+ * incoming events. Enqueue resolves immediately; dequeue awaits the next event.
+ */
+export class EventQueue {
+  private buffer: NebulaEvent[] = []
+  private waiters: Array<(ev: NebulaEvent) => void> = []
+  private closed = false
+
+  enqueue(ev: NebulaEvent): void {
+    if (this.closed) throw new Error('EventQueue closed')
+    const w = this.waiters.shift()
+    if (w) {
+      w(ev)
+      return
+    }
+    this.buffer.push(ev)
+  }
+
+  async dequeue(): Promise<NebulaEvent> {
+    const head = this.buffer.shift()
+    if (head) return head
+    if (this.closed) throw new Error('EventQueue closed')
+    return new Promise<NebulaEvent>(resolve => {
+      this.waiters.push(resolve)
+    })
+  }
+
+  /** Close and wake all waiters with error. */
+  close(): void {
+    this.closed = true
+    for (const w of this.waiters) {
+      Promise.resolve().then(() => w({} as NebulaEvent))
+    }
+    this.waiters = []
+  }
+
+  get length(): number {
+    return this.buffer.length
+  }
+
+  get isClosed(): boolean {
+    return this.closed
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<NebulaEvent> {
+    while (!this.closed) {
+      try {
+        yield await this.dequeue()
+      } catch {
+        return
+      }
+    }
+  }
+}
+
+let counter = 0
+export function newEventId(): string {
+  counter += 1
+  return `${Date.now().toString(36)}-${counter.toString(36)}`
+}

package/src/events/router.ts

@@ -0,0 +1,42 @@
+import type { Brain, BrainTurn } from '../brain/types'
+import type { ToolRegistry } from '../tools/registry'
+import type { EventQueue } from './queue'
+import type { NebulaEvent } from './types'
+
+export interface RouterDeps {
+  brain: Brain
+  tools: ToolRegistry
+  onTurn?: (ev: NebulaEvent, turn: BrainTurn) => void | Promise<void>
+}
+
+/**
+ * Pulls events from the queue, assembles a prompt via the brain, executes any
+ * returned tool_calls until the brain produces a final message, and yields
+ * the turn back via `onTurn`.
+ */
+export async function routeLoop(queue: EventQueue, deps: RouterDeps): Promise<void> {
+  for await (const ev of queue) {
+    if (!ev.source) continue // closed sentinel
+    await handleOne(ev, deps)
+  }
+}
+
+async function handleOne(ev: NebulaEvent, deps: RouterDeps): Promise<void> {
+  // Seed conversation with the triggering event (stub does echo; real brain
+  // in phase 3 will load memory, assemble frozen prefix, etc.)
+  const turn = await deps.brain.infer({ event: ev })
+
+  // Resolve any tool calls in a single iteration for MVP — phase 3 extends
+  // this to a proper multi-turn loop.
+  for (const call of turn.toolCalls ?? []) {
+    const tool = deps.tools.find(call.name)
+    if (!tool) continue
+    try {
+      await tool.handler(call.args)
+    } catch {
+      // Tool errors are surfaced in activity log by the runtime, not here.
+    }
+  }
+
+  await deps.onTurn?.(ev, turn)
+}

package/src/events/types.ts

@@ -0,0 +1,28 @@
+/** Sources that can enqueue events into the runtime. */
+export type EventSource =
+  | 'stdin'
+  | 'cron'
+  | 'webhook'
+  | 'a2a'
+  | 'marketplace'
+  | 'chain'
+  | 'internal'
+  | 'telegram'
+
+export interface EventPayload {
+  /** Short human-readable label for logs/status. */
+  label: string
+  /** Arbitrary structured data. Listener-specific shape. */
+  data: unknown
+  /** Any peer address (ECIES pubkey or .0g name) that originated this event. */
+  peer?: string
+  /** Per-listener hint about which memory topics are relevant for this event. */
+  memoryHint?: string[]
+}
+
+export interface NebulaEvent {
+  id: string
+  source: EventSource
+  payload: EventPayload
+  ts: number
+}

package/src/format.ts

@@ -0,0 +1,12 @@
+import { formatEther } from 'viem'
+
+/**
+ * Render a wei bigint as a 6-decimal Mantle string. Matches the statusline,
+ * `nebula ledger balance`, and `nebula balance` output styles. Always emits
+ * exactly 6 decimal places (zero-padded) so columns align.
+ */
+export function formatMnt(wei: bigint): string {
+  const raw = formatEther(wei)
+  const [whole, frac = ''] = raw.split('.')
+  return `${whole}.${frac.padEnd(6, '0').slice(0, 6)}`
+}

package/src/identity/agent-card.ts

@@ -0,0 +1,110 @@
+/**
+ * ERC-8004 / A2A "agent card" — the JSON identity document an agent publishes
+ * so other agents and systems can discover what it is, where to reach it, and
+ * which on-chain identity backs it. Referenced by the Identity Registry's
+ * tokenURI (see erc8004.ts).
+ */
+import type { Address } from 'viem'
+import type { NebulaNetwork } from '../config'
+import { NETWORK_CHAIN_ID } from '../config'
+
+export interface AgentCardSkill {
+  id: string
+  name: string
+  description: string
+}
+
+export interface AgentCardRegistration {
+  agentId: string
+  registry: Address
+  chainId: number
+}
+
+export interface AgentCard {
+  /** A2A protocol version this card conforms to. */
+  protocolVersion: string
+  name: string
+  description: string
+  /** Service endpoint (optional; e.g. a gateway URL). */
+  url?: string
+  version: string
+  /** The agent's operational EOA — signs + pays gas. */
+  agentAddress: Address
+  network: NebulaNetwork
+  chainId: number
+  /** What this agent is built to do well. */
+  capabilities: {
+    policyAware: boolean
+    simulation: boolean
+    approvals: boolean
+    auditable: boolean
+  }
+  skills: AgentCardSkill[]
+  /** ERC-8004 on-chain identity registrations backing this card. */
+  registrations: AgentCardRegistration[]
+}
+
+/** Nebula's default skill set — the defensible treasury-operator surface. */
+export const DEFAULT_AGENT_SKILLS: AgentCardSkill[] = [
+  {
+    id: 'treasury-ops',
+    name: 'Policy-aware treasury operations',
+    description:
+      'Transfers, swaps (Agni + Merchant Moe best-execution), wrap/unwrap, and Aave V3 lending on Mantle — every write policy-checked, simulated, and approval-gated.',
+  },
+  {
+    id: 'risk-analysis',
+    name: 'Pre-trade risk + counterparty intel',
+    description:
+      'Token risk vetting (exit/liquidity/restricted-RWA) and Nansen counterparty labels before any value-moving action.',
+  },
+  {
+    id: 'yield-discovery',
+    name: 'Yield discovery',
+    description:
+      'DeFiLlama analytics: Mantle pools ranked by APY/TVL with risk + RWA flags (read-only).',
+  },
+]
+
+export function buildAgentCard(opts: {
+  name: string
+  agentAddress: Address
+  network: NebulaNetwork
+  description?: string
+  url?: string
+  version?: string
+  skills?: AgentCardSkill[]
+  registration?: { agentId: bigint; registry: Address }
+}): AgentCard {
+  const chainId = NETWORK_CHAIN_ID[opts.network]
+  return {
+    protocolVersion: '0.3.0',
+    name: opts.name,
+    description:
+      opts.description ??
+      'A Mantle-native, policy-aware AI treasury assistant. The AI advises; deterministic code enforces the fund controls.',
+    url: opts.url,
+    version: opts.version ?? '0.1.0',
+    agentAddress: opts.agentAddress,
+    network: opts.network,
+    chainId,
+    capabilities: { policyAware: true, simulation: true, approvals: true, auditable: true },
+    skills: opts.skills ?? DEFAULT_AGENT_SKILLS,
+    registrations: opts.registration
+      ? [
+          {
+            agentId: opts.registration.agentId.toString(),
+            registry: opts.registration.registry,
+            chainId,
+          },
+        ]
+      : [],
+  }
+}
+
+/** Encode a card as an on-chain `data:` URI so it can be the tokenURI without external hosting. */
+export function cardToDataUri(card: AgentCard): string {
+  const json = JSON.stringify(card)
+  const b64 = Buffer.from(json, 'utf8').toString('base64')
+  return `data:application/json;base64,${b64}`
+}

package/src/identity/deployments.ts

@@ -0,0 +1,20 @@
+import type { NebulaNetwork } from '../config'
+
+export const EXPLORER_BASE: Record<NebulaNetwork, string> = {
+  'mantle-mainnet': 'https://mantlescan.xyz',
+  'mantle-testnet': 'https://sepolia.mantlescan.xyz',
+}
+
+export type NetworkName = NebulaNetwork
+
+export function explorerTxUrl(network: NebulaNetwork, txHash: string): string {
+  return `${EXPLORER_BASE[network]}/tx/${txHash}`
+}
+
+export function explorerTokenUrl(
+  network: NebulaNetwork,
+  contract: string,
+  tokenId: bigint,
+): string {
+  return `${EXPLORER_BASE[network]}/token/${contract}/${tokenId}`
+}