nebula-ai-plugin-system 0.1.0

package/src/code-execute.ts

@@ -0,0 +1,151 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { LocalBackend, type SandboxBackend, type ToolDef, redactEnv } from 'nebula-ai-core'
+import { z } from 'zod'
+import { type WorkingDirState, resolveCwd } from './cwd-state'
+
+/**
+ * `code.execute` runs a snippet in a subprocess. Wraps shell.run with an
+ * interpreter + temp-file pattern so the brain doesn't have to escape strings
+ * into a one-liner. Honours the same permission floor as shell.run via the
+ * pre_tool_call hook (the chat layer maps `code.execute` → `shell.run`-equivalent
+ * dangerous-pattern check).
+ */
+
+const ALLOWED_LANGUAGES = ['bash', 'python', 'node', 'bun', 'ts', 'js'] as const
+
+const ExecuteSchema = z.object({
+  language: z
+    .enum(ALLOWED_LANGUAGES)
+    .describe("Interpreter: 'bash', 'python', 'node', 'bun', 'ts', or 'js'."),
+  code: z.string().min(1).describe('Source code to execute.'),
+  stdin: z.string().optional().describe('Optional stdin content piped to the process.'),
+  timeout_ms: z
+    .number()
+    .int()
+    .positive()
+    .max(120_000)
+    .optional()
+    .describe('Kill the process after N ms. Default 30000.'),
+  cwd: z.string().optional().describe('Working directory. Default: workspace root.'),
+})
+
+interface CodeExecuteDeps {
+  /**
+   * Working directory. Pass a `WorkingDirState` to share with `shell.cd`
+   * (production); a plain string for a fixed cwd (tests).
+   */
+  cwd: string | WorkingDirState
+  /** Phase 9.5: sandbox backend wraps the spawn. LocalBackend = passthrough. Optional for back-compat. */
+  sandbox?: SandboxBackend
+}
+
+interface RunResult {
+  ok: boolean
+  data?: {
+    exit_code: number | null
+    stdout: string
+    stderr: string
+    timed_out: boolean
+  }
+  error?: string
+}
+
+export function makeCodeExecute(deps: CodeExecuteDeps): ToolDef<z.infer<typeof ExecuteSchema>> {
+  const sandbox = deps.sandbox ?? new LocalBackend()
+  const cwdState = resolveCwd(deps.cwd)
+  return {
+    name: 'code.execute',
+    description:
+      "Run a code snippet in bash/python/node/bun. Returns exit code, stdout, stderr. Honours the agent's permission/dangerous-pattern floor (shell.run-equivalent).",
+    searchHint: 'code execute python javascript bash run snippet',
+    schema: ExecuteSchema,
+    handler: async args => execute(args, cwdState.get(), sandbox),
+  }
+}
+
+async function execute(
+  args: z.infer<typeof ExecuteSchema>,
+  defaultCwd: string,
+  sandbox: SandboxBackend,
+): Promise<RunResult> {
+  const interp = pickInterpreter(args.language)
+  if (!interp) return { ok: false, error: `unsupported language: ${args.language}` }
+  const dir = await mkdtemp(join(tmpdir(), 'nebula-code-'))
+  const file = join(dir, `snippet.${interp.ext}`)
+  await writeFile(file, args.code, 'utf8')
+  const cwd = args.cwd && args.cwd.trim().length > 0 ? args.cwd : defaultCwd
+  const timeoutMs = args.timeout_ms ?? 30_000
+  const { env: redactedEnv } = redactEnv(process.env as Record<string, string>)
+  const wrapped = await sandbox.wrapSpawn({
+    command: interp.command,
+    args: [...interp.args, file],
+    options: { cwd, env: redactedEnv },
+  })
+  return await new Promise<RunResult>(resolve => {
+    const proc = spawn(wrapped.command, wrapped.args, wrapped.options)
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      try {
+        proc.kill('SIGKILL')
+      } catch {}
+    }, timeoutMs)
+    proc.stdout?.setEncoding('utf8')
+    proc.stderr?.setEncoding('utf8')
+    proc.stdout?.on('data', chunk => {
+      stdout += chunk as string
+      if (stdout.length > 50_000) stdout = stdout.slice(-50_000)
+    })
+    proc.stderr?.on('data', chunk => {
+      stderr += chunk as string
+      if (stderr.length > 50_000) stderr = stderr.slice(-50_000)
+    })
+    proc.on('error', err => {
+      clearTimeout(timer)
+      rm(dir, { recursive: true, force: true }).catch(() => {})
+      resolve({ ok: false, error: err.message })
+    })
+    proc.on('close', code => {
+      clearTimeout(timer)
+      rm(dir, { recursive: true, force: true }).catch(() => {})
+      resolve({
+        ok: !timedOut && (code ?? 0) === 0,
+        data: { exit_code: code, stdout, stderr, timed_out: timedOut },
+      })
+    })
+    if (args.stdin !== undefined) {
+      try {
+        proc.stdin?.write(args.stdin)
+        proc.stdin?.end()
+      } catch {}
+    } else {
+      proc.stdin?.end()
+    }
+  })
+}
+
+interface Interpreter {
+  command: string
+  args: string[]
+  ext: string
+}
+
+function pickInterpreter(lang: (typeof ALLOWED_LANGUAGES)[number]): Interpreter | null {
+  switch (lang) {
+    case 'bash':
+      return { command: 'bash', args: [], ext: 'sh' }
+    case 'python':
+      return { command: 'python3', args: [], ext: 'py' }
+    case 'node':
+    case 'js':
+      return { command: 'node', args: [], ext: 'js' }
+    case 'bun':
+    case 'ts':
+      return { command: 'bun', args: ['run'], ext: 'ts' }
+  }
+}

package/src/cwd-state.ts

@@ -0,0 +1,33 @@
+/**
+ * Mutable working-directory container shared across shell-class tools.
+ *
+ * shell.cd updates `current`; shell.run, code.execute, shell.process_start
+ * read `current` at handler invocation time. One instance per nebula session,
+ * created in the plugin's `register()` hook and threaded into every shell-class
+ * tool factory.
+ *
+ * Tests + legacy callers can pass a plain string to those factories; we
+ * normalize via `resolveCwd()` so the existing `cwd: '/tmp/foo'` shape keeps
+ * working but creates a tool-local container that won't share state with
+ * other tools — fine for unit tests, wrong for production where the chat
+ * layer must construct one shared `WorkingDirState`.
+ */
+export class WorkingDirState {
+  private current: string
+
+  constructor(initial: string) {
+    this.current = initial
+  }
+
+  get(): string {
+    return this.current
+  }
+
+  set(path: string): void {
+    this.current = path
+  }
+}
+
+export function resolveCwd(input: string | WorkingDirState): WorkingDirState {
+  return typeof input === 'string' ? new WorkingDirState(input) : input
+}

package/src/delegate.ts

@@ -0,0 +1,88 @@
+import {
+  type ClaudeAgent,
+  type DelegateBrainFactory,
+  type ToolDef,
+  coerceInt,
+} from 'nebula-ai-core'
+import { z } from 'zod'
+
+/**
+ * `delegate.task` spawns an isolated sub-brain with a constrained system
+ * prompt + tool subset. Used by the parent brain to off-load focused work
+ * (extraction, drafting, classification) without polluting its own context.
+ * Claude Code agents (~/.claude/plugins/cache/<m>/<p>/<v>/agents/<name>.md)
+ * are addressable via the `agent:` arg.
+ */
+
+interface DelegateDeps {
+  /** Builds a fresh brain instance. Chat.tsx supplies this with broker creds. */
+  makeBrain: DelegateBrainFactory
+  /** Claude Code agents available by short name. */
+  agents: ClaudeAgent[]
+}
+
+const DelegateSchema = z.object({
+  agent: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Name of a Claude Code agent (e.g. 'thymos', 'contract-explainer') OR omit and provide system_prompt directly.",
+    ),
+  system_prompt: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Custom system prompt for the sub-brain. Used when no agent is specified.'),
+  task: z.string().min(1).describe('The task description / user-message the sub-brain receives.'),
+  max_output_tokens: coerceInt
+    .refine(n => n > 0 && n <= 8_000, 'max_output_tokens must be 1..8000')
+    .optional(),
+})
+
+export function makeDelegateTask(deps: DelegateDeps): ToolDef<z.infer<typeof DelegateSchema>> {
+  return {
+    name: 'delegate.task',
+    description:
+      'Run a task on a sub-brain (same provider, isolated context). Useful for extraction, summarisation, classification. Pass `agent: <name>` for a Claude Code agent OR `system_prompt` for ad-hoc instructions. Returns content + token usage.',
+    searchHint: 'delegate task subagent isolated sub brain',
+    schema: DelegateSchema,
+    handler: async args => {
+      let systemPrompt: string
+      if (args.agent) {
+        const agent = deps.agents.find(a => a.name === args.agent || a.id === args.agent)
+        if (!agent) {
+          return { ok: false, error: `unknown agent: ${args.agent}` }
+        }
+        systemPrompt =
+          agent.body.trim().length > 0 ? agent.body : `You are ${agent.name}. ${agent.description}`
+      } else if (args.system_prompt) {
+        systemPrompt = args.system_prompt
+      } else {
+        return { ok: false, error: 'either agent or system_prompt is required' }
+      }
+      try {
+        const subBrain = await deps.makeBrain({ systemPrompt, tools: [] })
+        const turn = await subBrain.infer({
+          event: {
+            id: `delegate-${Date.now()}`,
+            source: 'stdin',
+            payload: { label: 'delegate', data: args.task },
+            ts: Date.now(),
+          },
+        })
+        return {
+          ok: true,
+          data: {
+            content: turn.content,
+            finishReason: turn.finishReason,
+            usage: turn.usage,
+            agent: args.agent ?? null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message }
+      }
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,160 @@
+/**
+ * nebula-ai-plugin-system: battery-included filesystem + shell + skills tools.
+ *
+ * Native plugin shape: exports a default `register(ctx)` consumed by nebula's
+ * loader. The ctx exposes `registerTool`, `registerListener`, `addHook`. Tools
+ * registered here ride through the same approval/permission floor as any other
+ * registered tool; chat.tsx hooks `pre_tool_call` to enforce.
+ */
+
+import { LocalBackend, type NativePlugin, type ToolDef } from 'nebula-ai-core'
+import {
+  findAgentBrowserOrNull,
+  makeBrowserBack,
+  makeBrowserClick,
+  makeBrowserConsole,
+  makeBrowserGetImages,
+  makeBrowserNavigate,
+  makeBrowserPress,
+  makeBrowserScroll,
+  makeBrowserSnapshot,
+  makeBrowserType,
+  makeBrowserVision,
+} from './browser'
+import { makeCodeExecute } from './code-execute'
+import { WorkingDirState } from './cwd-state'
+import { makeDelegateTask } from './delegate'
+import { makeFsPatch, makeFsRead, makeFsSearch, makeFsWrite } from './fs'
+import { makeSessionSearch } from './session-search'
+import { makeShellRun } from './shell'
+import { makeShellCd } from './shell-cd'
+import {
+  makeShellProcessKill,
+  makeShellProcessList,
+  makeShellProcessOutput,
+  makeShellProcessStart,
+} from './shell-process'
+import { makeSkillsList, makeSkillsView } from './skills'
+import { makeSkillsManage } from './skills-manage'
+import { makeClarify, makeTodo } from './todo'
+import { makeVisionAnalyze } from './vision'
+import { makeWebFetch } from './web-fetch'
+
+export {
+  makeFsRead,
+  makeFsWrite,
+  makeFsPatch,
+  makeFsSearch,
+  makeShellRun,
+  makeShellCd,
+  makeShellProcessStart,
+  makeShellProcessOutput,
+  makeShellProcessList,
+  makeShellProcessKill,
+  makeTodo,
+  makeClarify,
+  makeSkillsList,
+  makeSkillsView,
+  makeSkillsManage,
+  makeSessionSearch,
+  makeCodeExecute,
+  makeDelegateTask,
+  makeVisionAnalyze,
+  makeWebFetch,
+  makeBrowserNavigate,
+  makeBrowserSnapshot,
+  makeBrowserClick,
+  makeBrowserType,
+  makeBrowserScroll,
+  makeBrowserBack,
+  makeBrowserPress,
+  makeBrowserGetImages,
+  makeBrowserVision,
+  makeBrowserConsole,
+}
+export { WorkingDirState, resolveCwd } from './cwd-state'
+export { killAllProcesses } from './shell-process'
+export { isBrowserAvailable } from './browser'
+
+const plugin: NativePlugin = {
+  name: 'system',
+  register: ctx => {
+    const workspaceRoot = ctx.workspaceRoot ?? process.cwd()
+    // Phase 9.5: pull sandbox backend from context. If chat.tsx didn't supply
+    // one (legacy callers, tests), fall back to LocalBackend (passthrough)
+    // so existing behaviour is preserved exactly.
+    const sandbox = ctx.sandbox ?? new LocalBackend()
+    // Phase 9.6: ONE shared cwd state for shell.cd / shell.run / code.execute
+    // / shell.process_start. shell.cd mutates; the others read at handler
+    // invocation time. Tests that pass `cwd: '<path>'` get a private state
+    // automatically (resolveCwd promotes string → state per tool).
+    const cwdState = new WorkingDirState(workspaceRoot)
+    const fsDeps = { workspaceRoot, agentDir: ctx.agentDir }
+    const skillsDeps = {
+      importsClaudeCode: ctx.imports.claudeCode,
+      disabled: ctx.skillsDisabled.current,
+    }
+    const tools: ToolDef[] = [
+      makeFsRead(fsDeps) as ToolDef,
+      makeFsWrite(fsDeps) as ToolDef,
+      makeFsPatch(fsDeps) as ToolDef,
+      makeFsSearch(fsDeps) as ToolDef,
+      makeShellRun({ cwd: cwdState, sandbox }) as ToolDef,
+      makeShellCd({ cwd: cwdState, agentDir: ctx.agentDir }) as ToolDef,
+      makeWebFetch() as ToolDef,
+      makeTodo() as ToolDef,
+      makeClarify() as ToolDef,
+      makeSkillsList(skillsDeps) as ToolDef,
+      makeSkillsView(skillsDeps) as ToolDef,
+      makeSkillsManage({
+        importsClaudeCode: ctx.imports.claudeCode,
+        configPath: ctx.configPath,
+        disabledRef: ctx.skillsDisabled,
+      }) as ToolDef,
+      makeSessionSearch({ activityLogPath: ctx.activityLogPath }) as ToolDef,
+      makeCodeExecute({ cwd: cwdState, sandbox }) as ToolDef,
+      makeShellProcessStart({ cwd: cwdState, sandbox }) as ToolDef,
+      makeShellProcessOutput() as ToolDef,
+      makeShellProcessList() as ToolDef,
+      makeShellProcessKill() as ToolDef,
+      makeVisionAnalyze({
+        visionInfer: ctx.visionInfer ?? null,
+        agentDir: ctx.agentDir,
+      }) as ToolDef,
+    ]
+    // Skip browser.* registration when the agent-browser binary is absent
+    // (dev installs that skipped `bun install`). Pass workspaceRoot so the
+    // detector looks under the agent's actual checkout dir — enigma's
+    // harness daemon boots from $HOME, not the nebula workspace, so without
+    // the override `findAgentBrowser` misses the colocated node_modules
+    // and the brain falls back to web.fetch every time. Resolve the bin
+    // path ONCE here and pass it through `binPath` so per-call spawns
+    // don't re-search PATH (which would re-miss for the same reason).
+    const browserBin = findAgentBrowserOrNull(workspaceRoot)
+    if (browserBin) {
+      tools.push(
+        makeBrowserNavigate({ binPath: browserBin }) as ToolDef,
+        makeBrowserSnapshot({ binPath: browserBin }) as ToolDef,
+        makeBrowserClick({ binPath: browserBin }) as ToolDef,
+        makeBrowserType({ binPath: browserBin }) as ToolDef,
+        makeBrowserScroll({ binPath: browserBin }) as ToolDef,
+        makeBrowserBack({ binPath: browserBin }) as ToolDef,
+        makeBrowserPress({ binPath: browserBin }) as ToolDef,
+        makeBrowserGetImages({ binPath: browserBin }) as ToolDef,
+        makeBrowserConsole({ binPath: browserBin }) as ToolDef,
+        makeBrowserVision({ binPath: browserBin, visionInfer: ctx.visionInfer ?? null }) as ToolDef,
+      )
+    }
+    if (ctx.delegateFactory) {
+      tools.push(
+        makeDelegateTask({
+          makeBrain: ctx.delegateFactory,
+          agents: ctx.claudeAgents,
+        }) as ToolDef,
+      )
+    }
+    for (const t of tools) ctx.registerTool(t)
+  },
+}
+
+export default plugin

package/src/session-search.ts

@@ -0,0 +1,103 @@
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import readline from 'node:readline'
+import { type ToolDef, coerceBool } from 'nebula-ai-core'
+import { z } from 'zod'
+
+/**
+ * `session.search` scans the agent's activity-log JSONL (the same file the
+ * sync manager anchors to chain) for entries containing a substring match.
+ * The activity log captures every wake event, tool call, tool result, and
+ * brain response, so this is essentially "what did I do recently" search.
+ */
+
+interface SessionSearchDeps {
+  /** Path to the activity log JSONL. Falls back to a noop when missing. */
+  activityLogPath: string
+}
+
+const SearchSchema = z.object({
+  query: z
+    .string()
+    .min(1)
+    .describe(
+      "Plain substring to match against any JSON line. Default mode is SUBSTRING — do NOT escape regex metacharacters (e.g. for tool name 'shell.run' pass 'shell.run' as-is, NOT 'shell\\\\.run'). Set `regex: true` only when you genuinely need a pattern.",
+    ),
+  kind: z
+    .enum(['wake', 'tool-call', 'tool-result', 'brain-response', 'error', 'all'])
+    .optional()
+    .describe('Filter to a single activity kind. Default all.'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .max(200)
+    .optional()
+    .describe('Cap matches returned. Default 25.'),
+  regex: coerceBool
+    .optional()
+    .describe(
+      "Opt-in regex mode. Default false (substring). Only set true when the query uses regex constructs ('.+', '|', anchors); plain dotted tool names match fine in substring mode.",
+    ),
+})
+
+export function makeSessionSearch(deps: SessionSearchDeps): ToolDef<z.infer<typeof SearchSchema>> {
+  return {
+    name: 'session.search',
+    description:
+      "Search the agent's activity log for past wake events, tool calls/results, and brain responses. Useful for 'what did I do last hour?' or 'when did I call <tool>?'. Default is plain substring match — pass the tool name verbatim ('shell.run' not 'shell\\\\.run'). Returns timestamped JSON entries.",
+    searchHint: 'session search activity log history past',
+    schema: SearchSchema,
+    handler: async args => {
+      try {
+        await stat(deps.activityLogPath)
+      } catch {
+        return { ok: true, data: { matches: [], total: 0, note: 'activity log not yet created' } }
+      }
+      const limit = args.limit ?? 25
+      const matcher = compileMatcher(args.query, !!args.regex)
+      const matches: { ts: number; kind: string; line: string }[] = []
+      const stream = createReadStream(deps.activityLogPath, { encoding: 'utf8' })
+      const rl = readline.createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY })
+      let total = 0
+      try {
+        for await (const line of rl) {
+          if (!line.trim()) continue
+          let parsed: { ts?: number; kind?: string }
+          try {
+            parsed = JSON.parse(line) as { ts?: number; kind?: string }
+          } catch {
+            continue
+          }
+          if (args.kind && args.kind !== 'all' && parsed.kind !== args.kind) continue
+          if (!matcher(line)) continue
+          total++
+          if (matches.length < limit) {
+            matches.push({
+              ts: parsed.ts ?? 0,
+              kind: parsed.kind ?? 'unknown',
+              line: line.length > 4_000 ? `${line.slice(0, 4_000)}…` : line,
+            })
+          }
+        }
+      } finally {
+        rl.close()
+        stream.close()
+      }
+      return { ok: true, data: { matches, total } }
+    },
+  }
+}
+
+function compileMatcher(query: string, isRegex: boolean): (line: string) => boolean {
+  if (isRegex) {
+    try {
+      const re = new RegExp(query, 'i')
+      return line => re.test(line)
+    } catch {
+      // Bad regex falls back to substring match.
+    }
+  }
+  const lc = query.toLowerCase()
+  return line => line.toLowerCase().includes(lc)
+}

package/src/shell-cd.ts

@@ -0,0 +1,73 @@
+import { realpath, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { isAbsolute, resolve } from 'node:path'
+import { PathGuard, type ToolDef } from 'nebula-ai-core'
+import { z } from 'zod'
+import { type WorkingDirState, resolveCwd } from './cwd-state'
+
+interface ShellCdDeps {
+  /** Mutable cwd container shared with shell.run / code.execute / shell.process_start. */
+  cwd: string | WorkingDirState
+  /** PathGuard agentDir — refuses cd into the agent's own state tree. */
+  agentDir: string
+}
+
+const CdSchema = z.object({
+  path: z
+    .string()
+    .min(1)
+    .describe(
+      'Absolute path or path relative to the current cwd. Use ~ for home. The new cwd persists across subsequent shell.run / code.execute / shell.process_start calls within this session.',
+    ),
+})
+
+export function makeShellCd(deps: ShellCdDeps): ToolDef<z.infer<typeof CdSchema>> {
+  const cwdState = resolveCwd(deps.cwd)
+  const guard = new PathGuard({ agentDir: deps.agentDir })
+  return {
+    name: 'shell.cd',
+    description:
+      'Set the working directory for subsequent shell.run / code.execute / shell.process_start calls. Persists across calls in this session. Path is resolved against the current cwd; use absolute paths or ~ for clarity. Refuses to enter credential dirs (~/.ssh, ~/.aws, .config/gcloud) or the agent state tree.',
+    searchHint: 'shell cd chdir change directory cwd working',
+    schema: CdSchema,
+    handler: async args => {
+      const expanded = args.path.startsWith('~') ? args.path.replace('~', homedir()) : args.path
+      const abs = isAbsolute(expanded) ? expanded : resolve(cwdState.get(), expanded)
+      // Run the deny check FIRST — before any filesystem syscall — so a
+      // protected target denies cleanly even when the path doesn't exist on
+      // disk (e.g. CI runners without ~/.ssh would otherwise ENOENT before
+      // the deny rule fires). PathGuard now canonicalises via realpath
+      // internally and stores both raw + canonical denylist entries, so
+      // symlinked credential dirs are still caught.
+      const guardResult = guard.check(abs)
+      if (!guardResult.allowed) {
+        return { ok: false, error: guardResult.reason ?? 'path denied' }
+      }
+      // Canonicalise through realpath so the stored cwd matches what `pwd`
+      // would print inside subsequent shell.run calls (macOS resolves
+      // /var/folders → /private/var/folders, etc.).
+      let canonical: string
+      try {
+        canonical = await realpath(abs)
+      } catch (e) {
+        return { ok: false, error: `stat failed: ${(e as Error).message}` }
+      }
+      // Re-check after canonicalisation — covers the (rare) case where the
+      // raw form passes but the resolved target lands inside a denied tree.
+      const guardCanonical = guard.check(canonical)
+      if (!guardCanonical.allowed) {
+        return { ok: false, error: guardCanonical.reason ?? 'path denied' }
+      }
+      try {
+        const info = await stat(canonical)
+        if (!info.isDirectory()) {
+          return { ok: false, error: `not a directory: ${canonical}` }
+        }
+      } catch (e) {
+        return { ok: false, error: `stat failed: ${(e as Error).message}` }
+      }
+      cwdState.set(canonical)
+      return { ok: true, data: { cwd: canonical } }
+    },
+  }
+}