nebula-ai-core 0.1.0

package/src/sandbox/linux.ts

@@ -0,0 +1,141 @@
+/**
+ * Linux bubblewrap (`bwrap`) backend. Mirrors the macOS sandbox-exec backend
+ * for Linux operators. Wraps every tool spawn in:
+ *
+ *   bwrap <profile-args...> <orig-command> <orig-args...>
+ *
+ * `bwrap` is unprivileged user-namespace sandboxing — the same primitive
+ * Flatpak / Bubblewrap / chromium use. No setuid required (kernel must have
+ * unprivileged user namespaces enabled, which is the default on every modern
+ * distro: Ubuntu 22+, Fedora, Arch, Debian 11+).
+ *
+ * Profile policy mirrors macOS seatbelt:
+ *   - read-only bind of / (so commands like `cat`, `ls`, `find` work)
+ *   - writable bind of agentDir + workspaceRoot
+ *   - writable bind of /tmp (nebula-* dirs land there)
+ *   - tmpfs overlay of credential dirs (~/.ssh, ~/.aws, ~/Library/Keychains
+ *     [doesn't exist on Linux but cheap to include for portability],
+ *     ~/.config/gcloud) — reads return empty
+ *   - --unshare-all --share-net keeps network reachable so nebula can still
+ *     hit Mantle RPC, the indexer, etc.
+ *   - --die-with-parent kills the child if nebula crashes, no zombies
+ *   - --new-session puts the child in its own session (Ctrl-C from nebula
+ *     doesn't propagate to the inner command)
+ */
+
+import { existsSync } from 'node:fs'
+import { credentialDirs } from './credentials'
+import type {
+  SandboxBackend,
+  SandboxBackendOpts,
+  SandboxEnvHint,
+  SandboxSpawnRequest,
+  WrappedSpawn,
+} from './types'
+
+/**
+ * Probe order for bwrap binary. Most distros put it at /usr/bin/bwrap; some
+ * via pkg-managed systems at /usr/local/bin. First existing path wins.
+ */
+const BWRAP_CANDIDATES: ReadonlyArray<string> = ['/usr/bin/bwrap', '/usr/local/bin/bwrap']
+
+function findBwrap(): string | null {
+  for (const path of BWRAP_CANDIDATES) {
+    if (existsSync(path)) return path
+  }
+  return null
+}
+
+/**
+ * Build the bwrap argv prefix that wraps the user command. Returns a flat
+ * argv array; the actual command + args are appended after.
+ */
+export function buildBwrapArgs(opts: SandboxBackendOpts): string[] {
+  const args: string[] = []
+
+  // Base filesystem: read-only bind of /. The container can read system tools
+  // (cat, ls, etc.) but cannot modify them. Override specific subdirs below.
+  args.push('--ro-bind', '/', '/')
+
+  // Writable subdirs: agentDir + workspaceRoot + /tmp (for nebula-* test dirs)
+  args.push('--bind', opts.agentDir, opts.agentDir)
+  args.push('--bind', opts.workspaceRoot, opts.workspaceRoot)
+  args.push('--bind', '/tmp', '/tmp')
+
+  // Optional extra-writable subpaths (test sandbox dirs, custom workspaces).
+  if (opts.extraWriteAllow) {
+    for (const path of opts.extraWriteAllow) {
+      args.push('--bind', path, path)
+    }
+  }
+
+  // Credential blackouts: empty tmpfs overlays so reads return ENOENT-equivalent.
+  // Shared list with seatbelt-profile.ts to prevent platform drift.
+  for (const dir of credentialDirs(opts.homedir)) {
+    args.push('--tmpfs', dir)
+  }
+
+  // Optional extra denies via tmpfs.
+  if (opts.extraWriteDeny) {
+    for (const path of opts.extraWriteDeny) {
+      args.push('--tmpfs', path)
+    }
+  }
+
+  // System pseudo-filesystems.
+  args.push('--proc', '/proc')
+  args.push('--dev', '/dev')
+
+  // Namespace isolation: unshare everything except network (nebula needs network
+  // for Mantle RPC, indexer, brain inference). PID namespace isolates process tree
+  // from host. UTS namespace gives the sandbox its own hostname.
+  args.push('--unshare-all', '--share-net')
+
+  // Lifetime + signal handling.
+  args.push('--die-with-parent') // child dies if nebula dies
+  args.push('--new-session') // Ctrl-C from nebula doesn't kill the child directly
+
+  return args
+}
+
+export class LinuxBubblewrapBackend implements SandboxBackend {
+  readonly mode = 'os' as const
+  readonly label = 'os:linux'
+  private readonly bwrapPath: string
+  private readonly bwrapArgs: string[]
+
+  constructor(opts: SandboxBackendOpts) {
+    const path = findBwrap()
+    if (!path) {
+      throw new Error(
+        `bwrap not found in ${BWRAP_CANDIDATES.join(', ')}. Linux sandbox backend requires bubblewrap (apt install bubblewrap / dnf install bubblewrap).`,
+      )
+    }
+    this.bwrapPath = path
+    this.bwrapArgs = buildBwrapArgs(opts)
+  }
+
+  /** Test-only accessor for the bwrap argv prefix. */
+  getBwrapArgs(): readonly string[] {
+    return this.bwrapArgs
+  }
+
+  envHint(): SandboxEnvHint {
+    return {
+      mode: 'os',
+      label: this.label,
+      innerOs: 'linux',
+      workspaceMount: null,
+      scope:
+        'shell.run, code.execute, shell.process_start are wrapped in a bubblewrap profile; writes outside agentDir + cwd + /tmp/nebula-* are denied',
+    }
+  }
+
+  async wrapSpawn(req: SandboxSpawnRequest): Promise<WrappedSpawn> {
+    return {
+      command: this.bwrapPath,
+      args: [...this.bwrapArgs, '--', req.command, ...req.args],
+      options: req.options,
+    }
+  }
+}

package/src/sandbox/local.ts

@@ -0,0 +1,19 @@
+/**
+ * Passthrough backend. Used when `sandbox.mode = 'none'` (today's default for
+ * back-compat) or when the platform doesn't support `os` mode.
+ */
+
+import type { SandboxBackend, SandboxSpawnRequest, WrappedSpawn } from './types'
+
+export class LocalBackend implements SandboxBackend {
+  readonly mode = 'none' as const
+  readonly label = 'none'
+
+  async wrapSpawn(req: SandboxSpawnRequest): Promise<WrappedSpawn> {
+    return {
+      command: req.command,
+      args: req.args,
+      options: req.options,
+    }
+  }
+}

package/src/sandbox/macos.ts

@@ -0,0 +1,71 @@
+/**
+ * macOS sandbox-exec backend. Wraps every tool spawn in:
+ *
+ *   sandbox-exec -p '<seatbelt-profile>' <orig-command> <orig-args...>
+ *
+ * `sandbox-exec` is at /usr/bin/sandbox-exec on every macOS install. The
+ * `man` page calls it "deprecated" in favour of the modern App Sandbox API,
+ * but it's still ships and is used by Apple internally; verified working on
+ * macOS 25.4.0. The deprecation is a recommendation that new GUI apps adopt
+ * App Sandbox, not a removal.
+ *
+ * The profile is built once at backend-init and reused for every spawn. The
+ * profile is passed inline via `-p` (no temp file management needed).
+ */
+
+import { existsSync } from 'node:fs'
+import { buildSeatbeltProfile } from './seatbelt-profile'
+import type {
+  SandboxBackend,
+  SandboxBackendOpts,
+  SandboxEnvHint,
+  SandboxSpawnRequest,
+  WrappedSpawn,
+} from './types'
+
+const SANDBOX_EXEC_PATH = '/usr/bin/sandbox-exec'
+
+export class MacOSSandboxExecBackend implements SandboxBackend {
+  readonly mode = 'os' as const
+  readonly label = 'os:darwin'
+  private readonly profile: string
+
+  constructor(opts: SandboxBackendOpts) {
+    if (!existsSync(SANDBOX_EXEC_PATH)) {
+      throw new Error(
+        `sandbox-exec not found at ${SANDBOX_EXEC_PATH}. macOS sandbox backend requires the system tool.`,
+      )
+    }
+    this.profile = buildSeatbeltProfile({
+      agentDir: opts.agentDir,
+      workspaceRoot: opts.workspaceRoot,
+      homedir: opts.homedir,
+      extraWriteAllow: opts.extraWriteAllow,
+      extraWriteDeny: opts.extraWriteDeny,
+    })
+  }
+
+  /** Test-only accessor for the rendered profile. */
+  getProfile(): string {
+    return this.profile
+  }
+
+  envHint(): SandboxEnvHint {
+    return {
+      mode: 'os',
+      label: this.label,
+      innerOs: 'darwin',
+      workspaceMount: null,
+      scope:
+        'shell.run, code.execute, shell.process_start are wrapped in sandbox-exec; writes outside agentDir + cwd + /tmp/nebula-* are denied',
+    }
+  }
+
+  async wrapSpawn(req: SandboxSpawnRequest): Promise<WrappedSpawn> {
+    return {
+      command: SANDBOX_EXEC_PATH,
+      args: ['-p', this.profile, req.command, ...req.args],
+      options: req.options,
+    }
+  }
+}

package/src/sandbox/seatbelt-profile.ts

@@ -0,0 +1,139 @@
+/**
+ * macOS seatbelt (SBPL) profile generator. Used by MacOSSandboxExecBackend to
+ * build the `-p` argument for `sandbox-exec`.
+ *
+ * Profile policy (deny-default + targeted allows):
+ *
+ *   READS: broad (allow file-read*). Reading is fine; it's writes + network
+ *   exfil + process-fork-into-system that need gating. The brain's job is to
+ *   help with files; we don't want it crippled on read.
+ *
+ *   WRITES: deny default, allow ONLY:
+ *     - agentDir (nebula state)
+ *     - workspaceRoot (the cwd nebula was launched from; fs.write authorized
+ *       through the modal lands here)
+ *     - /tmp/nebula-* (nebula's own temp scratch — code.execute snippets, etc.)
+ *     - /private/tmp/nebula-* (macOS canonical /tmp)
+ *     - /var/folders (macOS user temp dir, where mkdtemp() defaults land)
+ *     - any extra subpaths in `extraWriteAllow`
+ *
+ *   EXPLICIT WRITE DENY (overrides allows on overlap):
+ *     - $HOME/.ssh
+ *     - $HOME/.aws
+ *     - $HOME/Library/Keychains
+ *     - $HOME/.config/gcloud
+ *     - $HOME/.nebula (the broader nebula state tree — only the agent's own
+ *       agentDir is allowed; brain shouldn't rewrite ~/.nebula/config.ts)
+ *
+ *   NETWORK: allow* (nebula legitimately needs Mantle RPC, indexer, compute,
+ *   WC relay, plus user-asked-for HTTP). Future hardening: allowlist by host.
+ *
+ *   PROCESS: allow process-fork + process-exec (tools spawn child binaries).
+ *   IPC: allow mach-lookup, ipc-posix-shm, signal — needed by most CLI
+ *   tooling, otherwise the simplest commands fail.
+ *
+ * The seatbelt syntax is Apple's internal SBPL (Scheme-like). It's
+ * undocumented officially but stable across macOS versions; deprecated in
+ * `man sandbox-exec` but still functional and used by Apple itself for many
+ * system services.
+ *
+ * NOTE on order: in seatbelt SBPL, deny rules placed AFTER allows take
+ * precedence on overlap. So we put the denylist after the allowlist for
+ * credentials.
+ */
+
+import { credentialDirs } from './credentials'
+
+export interface SeatbeltProfileOpts {
+  agentDir: string
+  workspaceRoot: string
+  homedir: string
+  extraWriteAllow?: string[]
+  extraWriteDeny?: string[]
+}
+
+/**
+ * Escape a path for safe inclusion in an SBPL string literal. Seatbelt strings
+ * are double-quoted; embedded backslashes and double quotes need escaping.
+ * Newlines also break the parser. Nebula paths come from process.cwd() and
+ * homedir() so they're well-formed Unix paths in practice, but we escape
+ * defensively.
+ */
+function sbplEscape(p: string): string {
+  return p.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ')
+}
+
+export function buildSeatbeltProfile(opts: SeatbeltProfileOpts): string {
+  const home = sbplEscape(opts.homedir)
+  const agent = sbplEscape(opts.agentDir)
+  const workspace = sbplEscape(opts.workspaceRoot)
+
+  const allowSubpaths = [
+    `(allow file-write* (subpath "${agent}"))`,
+    `(allow file-write* (subpath "${workspace}"))`,
+    `(allow file-write* (regex #"^/tmp/nebula-"))`,
+    `(allow file-write* (regex #"^/private/tmp/nebula-"))`,
+    `(allow file-write* (subpath "/var/folders"))`,
+    `(allow file-write* (subpath "/private/var/folders"))`,
+    ...(opts.extraWriteAllow ?? []).map(p => `(allow file-write* (subpath "${sbplEscape(p)}"))`),
+  ].join('\n  ')
+
+  const credDirs = credentialDirs(opts.homedir).map(sbplEscape)
+  const denySubpaths = [
+    ...credDirs.map(p => `(deny file-write* (subpath "${p}"))`),
+    `(deny file-write* (subpath "${home}/.nebula"))`,
+    ...(opts.extraWriteDeny ?? []).map(p => `(deny file-write* (subpath "${sbplEscape(p)}"))`),
+  ].join('\n  ')
+
+  // Read-side: allow broadly (the agent legitimately needs to read system
+  // binaries, libraries, project files, etc.) but EXPLICITLY deny credential
+  // dirs. This blocks `cat ~/.ssh/id_rsa` -- shell.run that bypasses
+  // PathGuard's tool-level checks. Network is broad; if exfil is a concern
+  // (read public file + POST somewhere), use Docker mode.
+  const denyReadSubpaths = credDirs.map(p => `(deny file-read* (subpath "${p}"))`).join('\n  ')
+
+  // The agentDir is under ~/.nebula/agents/<id>/, and we deny ~/.nebula broadly,
+  // so we MUST re-allow agentDir AFTER the deny to keep nebula's own state
+  // writable. SBPL is order-sensitive: later rules win on overlap.
+  return `(version 1)
+(deny default)
+
+;; Process management — tools spawn binaries.
+(allow process-fork)
+(allow process-exec)
+
+;; IPC + system bookkeeping that any non-trivial CLI needs.
+(allow mach-lookup)
+(allow mach-priv-host-port)
+(allow mach-task-name)
+(allow ipc-posix-shm)
+(allow signal)
+(allow sysctl-read)
+(allow sysctl-write)
+(allow system-fsctl)
+(allow system-info)
+(allow system-socket)
+(allow iokit-open)
+
+;; Network — broad. Nebula needs Mantle RPC, indexer, compute, WC relay, plus
+;; arbitrary HTTP for browse + brain-driven fetches. Tighten via allowlist
+;; when we have explicit host policy.
+(allow network*)
+
+;; Reads — broad by default so binaries/libraries/project files work.
+(allow file-read*)
+
+;; Explicit credential read denies (override allow file-read*).
+  ${denyReadSubpaths}
+
+;; Writes — deny default, allowlist:
+  ${allowSubpaths}
+
+;; Explicit credential + state-tree denies (override allowlist on overlap).
+  ${denySubpaths}
+
+;; Re-allow agentDir AFTER the ~/.nebula broad deny so nebula's own state is
+;; writable. SBPL applies later rules first, so this comes last.
+  (allow file-write* (subpath "${agent}"))
+`
+}

package/src/sandbox/types.ts

@@ -0,0 +1,129 @@
+/**
+ * Sandbox abstraction for limb execution.
+ *
+ * Phase 9.5 (Apr 28 2026 incident response). Nebula's limbs run on the operator's
+ * host. Permission floors (PathGuard + dangerous-pattern modal + strict/prompt/yolo)
+ * caught the rm correctly during the v0.9.3 benchmark, but once the modal granted
+ * `s` (allow session), the command ran on the real host with full FS access. The
+ * cascade (tmux socket → daemon detach → orphan name-slot blocking) was severe.
+ *
+ * This module adds a structural layer BENEATH the permission floor: every
+ * spawn() call from a tool is routed through a `SandboxBackend` which can wrap
+ * the command in an OS sandbox before execution. Even if the permission floor
+ * is bypassed (yolo, allow-session, allow-once), the sandbox profile prevents
+ * writes outside an allowlist.
+ *
+ * Mirrors hermes-agent's TERMINAL_ENV pattern (local | docker | modal | daytona |
+ * singularity | ssh) but starts smaller: `none` (passthrough) and `os` (macOS
+ * sandbox-exec / future Linux bubblewrap). Docker mode is a separate followup
+ * bundle.
+ */
+
+import type { SpawnOptions } from 'node:child_process'
+
+/**
+ * Mode selector. Lives under `sandbox.mode` in `~/.nebula/config.ts`.
+ *
+ *  - `none`: passthrough (today's behaviour). No sandboxing applied. Default
+ *    for backward compatibility while Tier 2 stabilizes.
+ *  - `os`: native OS sandbox. macOS uses sandbox-exec with a deny-default
+ *    seatbelt profile. Linux uses bubblewrap (post-MVP). On unsupported
+ *    platforms falls back to `none` with a startup warning.
+ *  - `docker`: long-lived container per session, every spawn goes through
+ *    `docker exec`. Future bundle.
+ */
+export type SandboxMode = 'none' | 'os' | 'docker'
+
+/**
+ * Inputs the factory needs to construct a backend.
+ *  - `agentDir`: write-allowed (nebula writes activity log, mcp debug, etc.).
+ *  - `workspaceRoot`: write-allowed (where the operator launched nebula from;
+ *    fs.write/fs.patch authorized through the modal land here).
+ *  - `homedir`: used by the seatbelt profile to deny secret-bearing subdirs
+ *    (`~/.ssh`, `~/.aws`, `~/Library/Keychains`, `~/.config/gcloud`).
+ *  - `extraWriteAllow`: optional extra subpaths to allow writes under (test
+ *    sandbox dirs, custom workspaces).
+ *  - `extraWriteDeny`: optional extra subpaths to explicitly block writes.
+ */
+export interface SandboxBackendOpts {
+  agentDir: string
+  workspaceRoot: string
+  homedir: string
+  extraWriteAllow?: string[]
+  extraWriteDeny?: string[]
+}
+
+/**
+ * One spawn request, fully described before the backend wraps it. We pass
+ * `argv` rather than the legacy `(command, options)` form because backends
+ * that prepend `sandbox-exec -p ...` need to construct an explicit argv;
+ * mixing `shell: true` with a wrapper produces confused quoting.
+ */
+export interface WrappedSpawn {
+  /** The binary that should actually be exec'd. May be the original, may be a wrapper. */
+  command: string
+  /** Args to pass. Wrapper backends prepend their own. */
+  args: string[]
+  /** SpawnOptions to pass through. `shell` is intentionally omitted because the wrapper builds the explicit argv. */
+  options: SpawnOptions
+}
+
+/**
+ * Inputs the tool layer hands the backend per spawn. The backend wraps the
+ * argv (e.g. prepend `sandbox-exec -p <profile>` or rewrite as `docker exec
+ * <containerId> ...`). For shell.run-style tools, the caller MUST pass an
+ * explicit argv (`command='/bin/sh', args=['-c', userCommand]`) — the backend
+ * cannot use `shell: true` because the wrapper builds the argv itself.
+ */
+export interface SandboxSpawnRequest {
+  command: string
+  args: string[]
+  options: SpawnOptions
+}
+
+/**
+ * Environment hint surfaced to the brain via the frozen prefix's # Environment
+ * block. Lets the brain skip the "run pwd + ls / + uname to figure out where
+ * I am" empirical-discovery dance — saves wasted tool calls when the brain
+ * defaults to host-style commands inside a Linux container (BSD sed, fs.read
+ * /workspace ENOENT, etc.).
+ *
+ * Each non-passthrough backend implements `envHint()` to surface its specific
+ * shape. `LocalBackend` returns null (no sandbox, no hint).
+ */
+export interface SandboxEnvHint {
+  mode: SandboxMode
+  label: string
+  innerOs?: 'linux' | 'darwin' | null
+  workspaceMount?: string | null
+  scope?: string | null
+}
+
+/**
+ * The backend interface. Implementations: LocalBackend (passthrough),
+ * MacOSSandboxExecBackend (sandbox-exec wrapper), LinuxBubblewrapBackend
+ * (bwrap wrapper), DockerBackend (per-session container).
+ *
+ * `wrapSpawn` is async to allow lifecycle work (e.g. DockerBackend lazy-starts
+ * the container on first call). Sync backends just `return Promise.resolve(...)`.
+ * Optional `dispose` lets backends clean up (DockerBackend kills its container).
+ * Optional `envHint` returns a brain-facing description of the sandbox shape.
+ */
+export interface SandboxBackend {
+  /** Backend identifier surfaced in logs / debug output. */
+  readonly mode: SandboxMode
+  /** Backend label including platform detail (e.g. 'os:darwin', 'docker:oven/bun:1'). */
+  readonly label: string
+  /**
+   * Wrap a spawn request. Returns (a Promise of) the argv that should be
+   * passed to `spawn(command, args, options)`. For `none`, returns the request
+   * unchanged. For `os`, returns a sandbox-exec wrapper. For `docker`, returns
+   * `docker exec <containerId> <orig-command>`, awaiting container start on
+   * the first call.
+   */
+  wrapSpawn(req: SandboxSpawnRequest): Promise<WrappedSpawn>
+  /** Optional cleanup (kill long-lived containers, remove temp files). Called on nebula exit. */
+  dispose?(): Promise<void>
+  /** Optional brain-facing description of the sandbox shape. Null for passthrough. */
+  envHint?(): SandboxEnvHint | null
+}

package/src/skills/index.ts

@@ -0,0 +1,8 @@
+export type { SkillFrontmatter, SkillRef, SkillSource } from './types'
+export { scanSkills, parseFrontmatter, type SkillScannerOptions } from './scanner'
+export {
+  matchTriggers,
+  matchFilePattern,
+  matchBashPattern,
+  type SkillTriggerMatch,
+} from './triggers'