nebula-ai-core 0.1.0

package/src/identity/erc8004.ts

@@ -0,0 +1,161 @@
+/**
+ * ERC-8004 ("Trustless Agents") Identity Registry client.
+ *
+ * Thin viem wrapper over the on-chain `NebulaIdentityRegistry` (see
+ * contracts/src/NebulaIdentityRegistry.sol). Each agent owns a transferable
+ * ERC-721 identity whose tokenURI is the agent card. Register, resolve, and
+ * reverse-resolve (agent EOA → id).
+ *
+ * The registry address is supplied per call (the CLI/tools read it from
+ * `NEBULA_IDENTITY_REGISTRY` or config). No canonical Mantle deployment is
+ * baked in yet — run `contracts/script/DeployIdentityRegistry.s.sol` and set
+ * the env var.
+ */
+import type { Address, Hex, PublicClient, WalletClient } from 'viem'
+import type { NebulaNetwork } from '../config'
+
+export const IDENTITY_REGISTRY_ABI = [
+  {
+    type: 'function',
+    name: 'register',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'cardURI', type: 'string' },
+      { name: 'agentAddress', type: 'address' },
+    ],
+    outputs: [{ name: 'agentId', type: 'uint256' }],
+  },
+  {
+    type: 'function',
+    name: 'setAgentCard',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'agentId', type: 'uint256' },
+      { name: 'cardURI', type: 'string' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'resolve',
+    stateMutability: 'view',
+    inputs: [{ name: 'agentId', type: 'uint256' }],
+    outputs: [
+      { name: 'owner', type: 'address' },
+      { name: 'agentAddress', type: 'address' },
+      { name: 'cardURI', type: 'string' },
+    ],
+  },
+  {
+    type: 'function',
+    name: 'agentIdByAddress',
+    stateMutability: 'view',
+    inputs: [{ name: '', type: 'address' }],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+  {
+    type: 'function',
+    name: 'ownerOf',
+    stateMutability: 'view',
+    inputs: [{ name: 'tokenId', type: 'uint256' }],
+    outputs: [{ name: 'owner', type: 'address' }],
+  },
+  {
+    type: 'function',
+    name: 'tokenURI',
+    stateMutability: 'view',
+    inputs: [{ name: 'agentId', type: 'uint256' }],
+    outputs: [{ name: '', type: 'string' }],
+  },
+  {
+    type: 'function',
+    name: 'totalAgents',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+  {
+    type: 'event',
+    name: 'AgentRegistered',
+    inputs: [
+      { name: 'agentId', type: 'uint256', indexed: true },
+      { name: 'owner', type: 'address', indexed: true },
+      { name: 'agentAddress', type: 'address', indexed: true },
+      { name: 'cardURI', type: 'string', indexed: false },
+    ],
+  },
+] as const
+
+/**
+ * Deployed registry addresses per network. Override at runtime with
+ * NEBULA_IDENTITY_REGISTRY. Mainnet pending a funded deploy.
+ */
+export const NEBULA_IDENTITY_REGISTRY: Partial<Record<NebulaNetwork, Address>> = {
+  'mantle-testnet': '0x529ae7B0e8A8191c0307b918AA62f1Fc6557a621',
+}
+
+/** Resolve the registry address: explicit override → env → baked-in. null if unset. */
+export function resolveRegistryAddress(network: NebulaNetwork, override?: string): Address | null {
+  const candidate =
+    override || process.env.NEBULA_IDENTITY_REGISTRY || NEBULA_IDENTITY_REGISTRY[network]
+  if (!candidate) return null
+  return candidate as Address
+}
+
+export interface ResolvedAgent {
+  agentId: bigint
+  owner: Address
+  agentAddress: Address
+  cardURI: string
+}
+
+/** Register a new agent identity. Returns the minted agentId + tx hash. */
+export async function registerAgent(opts: {
+  walletClient: WalletClient
+  publicClient: PublicClient
+  registry: Address
+  cardURI: string
+  agentAddress: Address
+}): Promise<{ agentId: bigint; txHash: Hex }> {
+  const account = opts.walletClient.account
+  if (!account) throw new Error('walletClient has no account')
+  const { request, result } = await opts.publicClient.simulateContract({
+    address: opts.registry,
+    abi: IDENTITY_REGISTRY_ABI,
+    functionName: 'register',
+    args: [opts.cardURI, opts.agentAddress],
+    account,
+  })
+  const txHash = await opts.walletClient.writeContract(request)
+  await opts.publicClient.waitForTransactionReceipt({ hash: txHash })
+  return { agentId: result as bigint, txHash }
+}
+
+/** Resolve an agent id → owner, operational address, card URI. */
+export async function resolveAgentById(opts: {
+  publicClient: PublicClient
+  registry: Address
+  agentId: bigint
+}): Promise<ResolvedAgent> {
+  const [owner, agentAddress, cardURI] = (await opts.publicClient.readContract({
+    address: opts.registry,
+    abi: IDENTITY_REGISTRY_ABI,
+    functionName: 'resolve',
+    args: [opts.agentId],
+  })) as [Address, Address, string]
+  return { agentId: opts.agentId, owner, agentAddress, cardURI }
+}
+
+/** Reverse-resolve: agent operational EOA → agentId (0n if not registered). */
+export async function agentIdByAddress(opts: {
+  publicClient: PublicClient
+  registry: Address
+  agentAddress: Address
+}): Promise<bigint> {
+  return (await opts.publicClient.readContract({
+    address: opts.registry,
+    abi: IDENTITY_REGISTRY_ABI,
+    functionName: 'agentIdByAddress',
+    args: [opts.agentAddress],
+  })) as bigint
+}

package/src/identity/index.ts

@@ -0,0 +1,29 @@
+export type { AgentIdentity, IdentityProvider } from './types'
+export { StubIdentity } from './stub'
+
+export {
+  EXPLORER_BASE,
+  type NetworkName,
+  explorerTxUrl,
+  explorerTokenUrl,
+} from './deployments'
+export { saveKeystoreLocally } from './keystore-blob'
+
+// ERC-8004 (Trustless Agents) identity
+export {
+  IDENTITY_REGISTRY_ABI,
+  NEBULA_IDENTITY_REGISTRY,
+  resolveRegistryAddress,
+  registerAgent,
+  resolveAgentById,
+  agentIdByAddress,
+  type ResolvedAgent,
+} from './erc8004'
+export {
+  type AgentCard,
+  type AgentCardSkill,
+  type AgentCardRegistration,
+  DEFAULT_AGENT_SKILLS,
+  buildAgentCard,
+  cardToDataUri,
+} from './agent-card'

package/src/identity/keystore-blob.ts

@@ -0,0 +1,60 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { Address, Hex } from 'viem'
+import type { OperatorSigner } from '../operator/signer'
+import {
+  type OperatorEncryptedKeystore,
+  encodeKeystoreBytes,
+  encryptAgentKey,
+} from '../wallet/operator-keystore-crypto'
+
+/**
+ * Local encrypted-keystore lifecycle.
+ *
+ * The agent's private key is encrypted to the operator wallet and stored as a
+ * local file at `~/.nebula/agents/<id>/keystore.json`. The ciphertext is
+ * decryptable only by the operator's wallet signature (sign-derived key, see
+ * operator-keystore-crypto.ts). Keys never leave RAM in plaintext.
+ */
+
+/** Write an encrypted keystore JSON to `cachePath`, mkdir-p'ing the parent. */
+async function writeKeystoreCache(
+  cachePath: string,
+  keystore: OperatorEncryptedKeystore,
+): Promise<void> {
+  await mkdir(dirname(cachePath), { recursive: true })
+  await writeFile(cachePath, JSON.stringify(keystore, null, 2), 'utf8')
+}
+
+/**
+ * Encrypt the agent privkey to the operator wallet and save the ciphertext
+ * to a local file. Performs ZERO chain or storage operations.
+ *
+ * **Call this BEFORE funding the agent EOA.** The encrypted keystore on disk
+ * is the durable insurance against any subsequent failure: once it exists,
+ * the operator wallet can always decrypt + recover the agent privkey, even
+ * if any later step blows up.
+ */
+export async function saveKeystoreLocally(opts: {
+  signer?: OperatorSigner
+  agentAddress: Address
+  agentPrivkey: Hex
+  cachePath: string
+  /**
+   * Optional pre-derived AES key (32 bytes). When provided, the caller has
+   * already derived the keystore-scope key via `precomputeAllScopes` and wants
+   * to avoid a second `signTypedData` call. Used by `nebula init` so the
+   * operator-session cache and the encrypted keystore share the same derive.
+   */
+  precomputedKey?: Buffer
+}): Promise<{ keystore: OperatorEncryptedKeystore; bytes: Uint8Array }> {
+  const keystore = await encryptAgentKey({
+    signer: opts.signer,
+    agentAddress: opts.agentAddress,
+    agentPrivkey: opts.agentPrivkey,
+    precomputedKey: opts.precomputedKey,
+  })
+  await writeKeystoreCache(opts.cachePath, keystore)
+  const bytes = encodeKeystoreBytes(keystore)
+  return { keystore, bytes }
+}

package/src/identity/receipt.ts

@@ -0,0 +1,27 @@
+import type { Hex, PublicClient, TransactionReceipt } from 'viem'
+
+/**
+ * viem's `waitForTransactionReceipt` throws `TransactionReceiptNotFoundError`
+ * from inside its block-watcher when the RPC returns null for a tx that's
+ * still propagating. On Mantle's eventually-consistent testnet that's common.
+ * Wrap with a tolerant poll loop so hackathon-path UX doesn't bail.
+ */
+export async function waitForReceiptResilient(
+  client: PublicClient,
+  hash: Hex,
+  opts?: { tries?: number; delayMs?: number },
+): Promise<TransactionReceipt> {
+  const tries = opts?.tries ?? 30
+  const delayMs = opts?.delayMs ?? 2000
+  let lastErr: unknown
+  for (let i = 0; i < tries; i++) {
+    try {
+      const receipt = await client.getTransactionReceipt({ hash })
+      return receipt
+    } catch (e) {
+      lastErr = e
+      await new Promise(r => setTimeout(r, delayMs))
+    }
+  }
+  throw lastErr ?? new Error(`receipt never arrived for ${hash}`)
+}

package/src/identity/stub.ts

@@ -0,0 +1,29 @@
+import { placeholderAgentId } from '../paths'
+import type { AgentIdentity, IdentityProvider } from './types'
+
+/**
+ * Local stub identity provider. Fabricates an agent id from the wallet
+ * address so runtime + memory have something stable to key on before the
+ * iNFT is minted (phase 4).
+ */
+export class StubIdentity implements IdentityProvider {
+  constructor(
+    private readonly ownerAddress: string,
+    private readonly agentEoa: string,
+    private readonly subname?: string,
+  ) {}
+
+  async current(): Promise<AgentIdentity> {
+    return {
+      agentId: placeholderAgentId(this.agentEoa),
+      iNFT: {
+        contract: null,
+        tokenId: null,
+        ownerAddress: this.ownerAddress,
+        network: 'local-stub',
+      },
+      agentEoa: this.agentEoa,
+      subname: this.subname,
+    }
+  }
+}

package/src/identity/types.ts

@@ -0,0 +1,20 @@
+/**
+ * iNFT state as seen by the runtime. Phase 4 wires this to the real
+ * ERC-7857 contract. Phase 1 provides a stub that fabricates an id from
+ * the wallet address so the rest of the runtime can reference identity.
+ */
+export interface AgentIdentity {
+  agentId: string
+  iNFT: {
+    contract: string | null
+    tokenId: string | null
+    ownerAddress: string
+    network: 'mantle-mainnet' | 'mantle-testnet' | 'local-stub'
+  }
+  agentEoa: string
+  subname?: string
+}
+
+export interface IdentityProvider {
+  current(): Promise<AgentIdentity>
+}

package/src/index.ts

@@ -0,0 +1,372 @@
+// nebula-ai-core: always-on infrastructure for the nebula harness.
+export const VERSION = '0.0.0'
+
+export * from './config'
+export { formatMnt } from './format'
+export { agentPaths, placeholderAgentId } from './paths'
+
+export type {
+  NebulaEvent,
+  EventPayload,
+  EventSource,
+  Listener,
+  RouterDeps,
+} from './events'
+export { EventQueue, newEventId, listeners, routeLoop } from './events'
+
+export type {
+  ToolCall,
+  ToolDef,
+  ToolResult,
+  ToolSchema,
+  JSONSchema,
+  FetchEscalation,
+  EscalationDeps,
+} from './tools'
+export {
+  ToolRegistry,
+  zodToJsonSchema,
+  coerceBool,
+  coerceInt,
+  detectFetchEscalation,
+  mergeEscalationResult,
+  runEscalation,
+} from './tools'
+
+export type {
+  ApplyResult,
+  CommandScope,
+  CommandSurface,
+  ParsedSlash,
+  PermissionApi,
+  PermissionToggleMode,
+  SlashCommand,
+} from './commands'
+export {
+  COMMAND_REGISTRY,
+  applyPerms,
+  applyYolo,
+  commandsForSurface,
+  findCommand,
+  parseSlash,
+  suggestForPrefix,
+} from './commands'
+
+export type {
+  Brain,
+  BrainCompactionEvent,
+  BrainInferInput,
+  BrainTurn,
+  BrainMessage,
+  BrainProvider,
+  BrainProviderOpts,
+  CompactionOpts,
+  FrozenPrefix,
+  HistoryPersist,
+  FsHistoryPersistOpts,
+  OpenAIBrainOpts,
+  SummarizeFn,
+} from './brain'
+export {
+  StubBrain,
+  OpenAIBrain,
+  DEFAULT_BASE_URL,
+  DEFAULT_MODEL,
+  DEFAULT_CHANNEL_KEY,
+  DEFAULT_MAX_OUTPUT_TOKENS,
+  previewToolArgs,
+  inferToolOk,
+  buildFrozenPrefix,
+  renderFrozenPrefix,
+  DEFAULT_SYSTEM_PROMPT,
+  DEFAULT_COMPACTION_OPTS,
+  SUMMARY_SYSTEM_PROMPT,
+  estimateTokens,
+  shouldCompact,
+  compactHistory,
+  createFsHistoryPersist,
+  sanitizeChannelKey,
+} from './brain'
+
+export type {
+  MemoryType,
+  MemoryPartition,
+  MemoryFrontmatter,
+  MemoryTopic,
+  MemoryIndexEntry,
+  MemoryIndex,
+  EditOp,
+  EditAction,
+  ThreatScanResult,
+} from './memory'
+export {
+  parseTopic,
+  stringifyTopic,
+  scanForThreats,
+  applyEdit,
+  EditError,
+  parseIndex,
+  stringifyIndex,
+  readIndexFile,
+  writeIndexFile,
+  addEntryLine,
+  removeEntryLine,
+  readTopic,
+  writeTopic,
+  topicPath,
+  makeMemorySaveTool,
+  type MemorySaveArgs,
+  makeMemoryReadTool,
+  type MemoryReadArgs,
+  makeMemoryListTool,
+  type MemoryListArgs,
+  type MemoryListAgentFile,
+  ensureSyntheticIndexEntries,
+  STANDARD_SYNTHETIC_INDEX_FILES,
+  type SyntheticIndexFile,
+  type SyntheticIndexResult,
+  INDEX_LINE_LIMIT,
+  INDEX_BYTE_LIMIT,
+  MEMORY_BLOB_VERSION,
+  deriveMemoryKey,
+  encryptMemoryBytes,
+  decryptMemoryBytes,
+  PACK_BLOB_VERSION,
+  encodePackBlob,
+  decodePackBlob,
+  isV2Envelope,
+  type PackBlob,
+  type EncodePackOpts,
+  gatherAgentPack,
+  gatherUserPack,
+  writeAgentPack,
+  writeUserPack,
+  type GatherResult,
+} from './memory'
+
+export type { Storage } from './storage'
+export {
+  LocalStubStorage,
+  SqliteStorage,
+  getStorage,
+  downloadBlobByRoot,
+  encrypt as encryptBytes,
+  decrypt as decryptBytes,
+  packEnvelope,
+  unpackEnvelope,
+  type EncryptedEnvelope,
+} from './storage'
+
+export {
+  encryptKey,
+  decryptKey,
+  generateAgentWallet,
+  saveKeystore,
+  loadKeystore,
+  type EncryptedKeystore,
+  type AgentWalletMaterial,
+  OPERATOR_KEYSTORE_VERSION,
+  OPERATOR_BLOB_SCOPES,
+  type OperatorBlobScope,
+  encryptAgentKey,
+  decryptAgentKey,
+  encryptOperatorBlob,
+  decryptOperatorBlob,
+  encodeKeystoreBytes,
+  decodeKeystoreBytes,
+  encodeOperatorBlobBytes,
+  decodeOperatorBlobBytes,
+  sniffKeystoreVersion,
+  deriveKeystoreKey,
+  deriveBlobKey,
+  deriveLegacyEmptyDomainKey,
+  tryDecryptKeystoreWithKey,
+  tryDecryptOperatorBlobWithKey,
+  type OperatorEncryptedKeystore,
+  type OperatorEncryptedBlob,
+  OPERATOR_SESSION_VERSION,
+  DEFAULT_OPERATOR_SESSION_TTL_MS,
+  type OperatorSession,
+  type OperatorSessionKeys,
+  type PrecomputeAllScopesOpts,
+  type PrecomputeVerifyKey,
+  operatorSessionPath,
+  writeOperatorSession,
+  readOperatorSession,
+  clearOperatorSession,
+  isOperatorSessionFresh,
+  isOperatorSessionComplete,
+  requiredScopesForAgent,
+  getSessionKey,
+  precomputeAllScopes,
+  buildOperatorSession,
+  drainAgentEOA,
+  type DrainAgentResult,
+} from './wallet'
+
+export type { AgentIdentity, IdentityProvider } from './identity'
+export {
+  StubIdentity,
+  EXPLORER_BASE,
+  type NetworkName,
+  explorerTxUrl,
+  explorerTokenUrl,
+  saveKeystoreLocally,
+  IDENTITY_REGISTRY_ABI,
+  NEBULA_IDENTITY_REGISTRY,
+  resolveRegistryAddress,
+  registerAgent,
+  resolveAgentById,
+  agentIdByAddress,
+  type ResolvedAgent,
+  type AgentCard,
+  type AgentCardSkill,
+  type AgentCardRegistration,
+  DEFAULT_AGENT_SKILLS,
+  buildAgentCard,
+  cardToDataUri,
+} from './identity'
+
+export {
+  type OperatorSigner,
+  KeychainOperatorSigner,
+  KeystoreFileOperatorSigner,
+  RawPrivkeyOperatorSigner,
+  WalletConnectOperatorSigner,
+  NEBULA_WC_PROJECT_ID,
+  type WalletConnectOperatorSignerOptions,
+} from './operator'
+export { waitForReceiptResilient } from './identity/receipt'
+export {
+  MIN_GAS_PRICE,
+  STORAGE_SUBMIT_GAS,
+  getGasPriceWithFloor,
+  makeViemClients,
+  mantleChain,
+  type ViemClients,
+} from './chain'
+
+export { Runtime, type RuntimeDeps, ActivityLog, type ActivityEntry } from './runtime'
+
+export {
+  acquireScopedLock,
+  clearStaleScopedLock,
+  DEFAULT_LOCK_TTL_SECONDS,
+  type AcquireScopedLockOpts,
+  type AcquireScopedLockResult,
+  type ClearStaleScopedLockReason,
+  type ClearStaleScopedLockResult,
+  type ScopedLockHandle,
+} from './locks'
+
+export {
+  PairingStore,
+  PAIRING_ALPHABET,
+  PAIRING_CODE_LENGTH,
+  PAIRING_CODE_TTL_SECONDS,
+  PAIRING_RATE_LIMIT_SECONDS,
+  PAIRING_LOCKOUT_SECONDS,
+  PAIRING_MAX_PENDING_PER_PLATFORM,
+  PAIRING_MAX_FAILED_ATTEMPTS,
+  type PairingStoreOpts,
+  type PendingEntry,
+  type ApprovedEntry,
+  type PendingListing,
+  type ApprovedListing,
+  type ApproveResult,
+} from './pairing'
+
+export {
+  encryptToPubkey,
+  decryptWithPrivkey,
+  generateBootstrapKeypair,
+  type Option3Envelope,
+} from './migration'
+
+export {
+  HookBus,
+  type HookName,
+  type HookHandler,
+  type PreToolCallContext,
+  type PreToolCallResult,
+  type PostToolCallContext,
+  loadPlugins,
+  type PluginContext,
+  type NativePlugin,
+  type PluginLoadResult,
+  type PluginLoaderDeps,
+  type DelegateBrainFactory,
+  type DelegateBrainFactoryOpts,
+  type DelegateBrainHandle,
+  type DelegateBrainTurn,
+  type VisionInferFn,
+  type VisionInferInput,
+  type VisionInferImage,
+  type VisionInferResult,
+  makeToolSearchTool,
+  type ToolSearchArgs,
+} from './plugins'
+
+export {
+  detectDangerousCommand,
+  DANGEROUS_PATTERNS,
+  PathGuard,
+  type PathGuardOpts,
+  type PathGuardResult,
+  redactEnv,
+  type EnvRedactResult,
+  PermissionService,
+  type PermissionMode,
+  type PermissionDecision,
+  type PermissionRequest,
+  type PermissionPrompter,
+  type PermissionServiceOpts,
+  type DangerousMatch,
+} from './permission'
+
+export type { SkillFrontmatter, SkillRef, SkillSource } from './skills'
+export {
+  scanSkills,
+  parseFrontmatter as parseSkillFrontmatter,
+  matchTriggers as matchSkillTriggers,
+  matchFilePattern,
+  matchBashPattern,
+  type SkillScannerOptions,
+  type SkillTriggerMatch,
+} from './skills'
+
+export {
+  discoverMcpServers,
+  McpManager,
+  McpStdioClient,
+  type McpDiscoveryOptions,
+  type McpServerConfig,
+  type McpServerStdio,
+  type McpServerHttp,
+  type McpToolMeta,
+  type McpDiscoveryResult,
+} from './mcp'
+
+export {
+  discoverClaudeExtras,
+  type ClaudeExtrasOptions,
+  type ClaudeCommand,
+  type ClaudeAgent,
+  type ClaudeExtrasDiscoveryResult,
+} from './claude-plugins'
+
+export {
+  LocalBackend,
+  MacOSSandboxExecBackend,
+  DockerBackend,
+  makeSandboxBackend,
+  buildSeatbeltProfile,
+  type SandboxBackend,
+  type SandboxBackendOpts,
+  type SandboxMode,
+  type SandboxSpawnRequest,
+  type WrappedSpawn,
+  type SeatbeltProfileOpts,
+  type MakeSandboxOpts,
+  type DockerBackendOpts,
+} from './sandbox'