nebula-ai-plugin-system 0.1.0

package/src/shell-process.ts

@@ -0,0 +1,255 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+import {
+  LocalBackend,
+  type SandboxBackend,
+  type ToolDef,
+  coerceBool,
+  redactEnv,
+} from 'nebula-ai-core'
+import { z } from 'zod'
+import { type WorkingDirState, resolveCwd } from './cwd-state'
+
+/**
+ * v0.9.3 split: long-running subprocess management is FOUR flat tools, not
+ * a discriminated union. qwen3.6-plus narrates results when faced with
+ * `action: 'start'|'output'|'list'|'kill'` schemas (regression #1). Flat
+ * z.object schemas remove that footgun.
+ *
+ * - `shell.process_start`  — spawn a backgrounded command, returns id
+ * - `shell.process_output` — read stdout/stderr by id
+ * - `shell.process_list`   — list active + recently-exited entries
+ * - `shell.process_kill`   — terminate by id (SIGTERM / SIGKILL / SIGINT)
+ *
+ * State lives in module-level memory shared across the four tools; the
+ * process tree is killed when nebula exits via killAllProcesses().
+ *
+ * Distinct from `shell.run` which waits for completion (one-shot
+ * commands). shell.process_start backgrounds it (dev servers, watchers).
+ */
+
+interface BackgroundProcess {
+  id: string
+  command: string
+  cwd: string
+  proc: ChildProcess
+  stdout: string
+  stderr: string
+  startedAt: number
+  exitCode: number | null
+  exitedAt: number | null
+}
+
+const processes = new Map<string, BackgroundProcess>()
+
+interface ShellProcessDeps {
+  /**
+   * 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 wraps the long-running spawn. LocalBackend = passthrough. Optional for back-compat. */
+  sandbox?: SandboxBackend
+}
+
+const StartSchema = z.object({
+  command: z.string().min(1).describe('Command to run via /bin/sh -c, in the background.'),
+  cwd: z.string().optional().describe('Working directory override. Defaults to nebula cwd.'),
+})
+
+const OutputSchema = z.object({
+  id: z.string().min(1).describe('Process id from a prior shell.process_start.'),
+  clear: coerceBool.optional().describe('Clear captured output after returning. Default false.'),
+})
+
+const ListSchema = z.object({})
+
+const KillSchema = z.object({
+  id: z.string().min(1).describe('Process id from a prior shell.process_start.'),
+  signal: z
+    .enum(['SIGTERM', 'SIGKILL', 'SIGINT'])
+    .optional()
+    .describe('Signal to send. Default SIGTERM.'),
+})
+
+export function makeShellProcessStart(
+  deps: ShellProcessDeps,
+): ToolDef<z.infer<typeof StartSchema>> {
+  const sandbox = deps.sandbox ?? new LocalBackend()
+  const cwdState = resolveCwd(deps.cwd)
+  return {
+    name: 'shell.process_start',
+    description:
+      'Spawn a backgrounded shell command and return its id. Use for dev servers, watchers, REPLs, anything you need to keep running while you do other things. For one-shot commands, use shell.run instead.',
+    searchHint: 'shell process spawn background daemon long running start',
+    schema: StartSchema,
+    handler: async args => startProcess(args.command, args.cwd ?? cwdState.get(), sandbox),
+  }
+}
+
+export function makeShellProcessOutput(): ToolDef<z.infer<typeof OutputSchema>> {
+  return {
+    name: 'shell.process_output',
+    description:
+      'Read accumulated stdout + stderr of a backgrounded process by id. Returns running flag and exit_code (null while running). Set clear=true to drain the buffer after reading.',
+    searchHint: 'shell process output stdout stderr capture read',
+    schema: OutputSchema,
+    handler: async args => captureOutput(args.id, args.clear ?? false),
+  }
+}
+
+export function makeShellProcessList(): ToolDef<z.infer<typeof ListSchema>> {
+  return {
+    name: 'shell.process_list',
+    description:
+      'List all backgrounded processes (active and recently-exited) with their commands, cwd, and status.',
+    searchHint: 'shell process list active running daemons subprocesses',
+    schema: ListSchema,
+    handler: async () => listProcesses(),
+  }
+}
+
+export function makeShellProcessKill(): ToolDef<z.infer<typeof KillSchema>> {
+  return {
+    name: 'shell.process_kill',
+    description:
+      'Terminate a backgrounded process by id. Default signal is SIGTERM. Returns killed=true if a live process was signalled, killed=false if it had already exited.',
+    searchHint: 'shell process kill terminate sigterm sigkill stop',
+    schema: KillSchema,
+    handler: async args => killProcess(args.id, args.signal ?? 'SIGTERM'),
+  }
+}
+
+async function startProcess(
+  command: string,
+  cwd: string,
+  sandbox: SandboxBackend,
+): Promise<{ ok: boolean; data?: { id: string }; error?: string }> {
+  const id = `proc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  const { env } = redactEnv(process.env as Record<string, string>)
+  const wrapped = await sandbox.wrapSpawn({
+    command: '/bin/sh',
+    args: ['-c', command],
+    options: { cwd, env },
+  })
+  const proc = spawn(wrapped.command, wrapped.args, wrapped.options)
+  const entry: BackgroundProcess = {
+    id,
+    command,
+    cwd,
+    proc,
+    stdout: '',
+    stderr: '',
+    startedAt: Date.now(),
+    exitCode: null,
+    exitedAt: null,
+  }
+  processes.set(id, entry)
+  proc.stdout?.setEncoding('utf8')
+  proc.stderr?.setEncoding('utf8')
+  proc.stdout?.on('data', chunk => {
+    entry.stdout += chunk as string
+    if (entry.stdout.length > 200_000) entry.stdout = entry.stdout.slice(-200_000)
+  })
+  proc.stderr?.on('data', chunk => {
+    entry.stderr += chunk as string
+    if (entry.stderr.length > 100_000) entry.stderr = entry.stderr.slice(-100_000)
+  })
+  proc.on('exit', code => {
+    entry.exitCode = code
+    entry.exitedAt = Date.now()
+  })
+  return { ok: true, data: { id } }
+}
+
+function captureOutput(
+  id: string,
+  clear: boolean,
+): {
+  ok: boolean
+  data?: {
+    id: string
+    stdout: string
+    stderr: string
+    exit_code: number | null
+    running: boolean
+    started_at: number
+    exited_at: number | null
+  }
+  error?: string
+} {
+  const entry = processes.get(id)
+  if (!entry) return { ok: false, error: `unknown process: ${id}` }
+  const out = {
+    id,
+    stdout: entry.stdout,
+    stderr: entry.stderr,
+    exit_code: entry.exitCode,
+    running: entry.exitCode === null,
+    started_at: entry.startedAt,
+    exited_at: entry.exitedAt,
+  }
+  if (clear) {
+    entry.stdout = ''
+    entry.stderr = ''
+  }
+  if (entry.exitCode !== null && clear) {
+    processes.delete(id)
+  }
+  return { ok: true, data: out }
+}
+
+function listProcesses(): {
+  ok: boolean
+  data: {
+    processes: Array<{
+      id: string
+      command: string
+      cwd: string
+      running: boolean
+      exit_code: number | null
+      started_at: number
+    }>
+  }
+} {
+  return {
+    ok: true,
+    data: {
+      processes: [...processes.values()].map(p => ({
+        id: p.id,
+        command: p.command,
+        cwd: p.cwd,
+        running: p.exitCode === null,
+        exit_code: p.exitCode,
+        started_at: p.startedAt,
+      })),
+    },
+  }
+}
+
+function killProcess(
+  id: string,
+  signal: 'SIGTERM' | 'SIGKILL' | 'SIGINT',
+): { ok: boolean; data?: { id: string; killed: boolean }; error?: string } {
+  const entry = processes.get(id)
+  if (!entry) return { ok: false, error: `unknown process: ${id}` }
+  if (entry.exitCode !== null) {
+    processes.delete(id)
+    return { ok: true, data: { id, killed: false } }
+  }
+  try {
+    entry.proc.kill(signal)
+    return { ok: true, data: { id, killed: true } }
+  } catch (e) {
+    return { ok: false, error: (e as Error).message }
+  }
+}
+
+/** Kill all tracked processes. Called by chat.tsx on session exit. */
+export function killAllProcesses(): void {
+  for (const entry of processes.values()) {
+    if (entry.exitCode !== null) continue
+    try {
+      entry.proc.kill('SIGTERM')
+    } catch {}
+  }
+}

package/src/shell.ts

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process'
+import { LocalBackend, type SandboxBackend, type ToolDef, redactEnv } from 'nebula-ai-core'
+import { z } from 'zod'
+import { type WorkingDirState, resolveCwd } from './cwd-state'
+
+interface ShellToolDeps {
+  /**
+   * Working directory for spawned commands. Pass a `WorkingDirState` to share
+   * the cwd with `shell.cd` and other shell-class tools (production path), or
+   * a plain string for a fixed cwd (legacy + tests).
+   */
+  cwd: string | WorkingDirState
+  /** Default timeout in ms. */
+  defaultTimeoutMs?: number
+  /**
+   * Phase 9.5: sandbox backend wraps the spawn before exec. Default
+   * `LocalBackend` is a passthrough (today's behaviour). When sandbox.mode='os'
+   * on darwin, this becomes a sandbox-exec wrapper that denies writes outside
+   * agentDir + workspaceRoot + /tmp/nebula-* + /var/folders. Optional for
+   * back-compat: tests + legacy callers that don't supply it get LocalBackend.
+   */
+  sandbox?: SandboxBackend
+}
+
+const ShellSchema = z.object({
+  command: z
+    .string()
+    .min(1)
+    .describe('Shell command to run. Quoted, fully formed (e.g., `ls -la`).'),
+  timeout_ms: z
+    .number()
+    .int()
+    .positive()
+    .max(300_000)
+    .optional()
+    .describe('Override default 60s timeout.'),
+})
+
+export function makeShellRun(deps: ShellToolDeps): ToolDef<z.infer<typeof ShellSchema>> {
+  const sandbox = deps.sandbox ?? new LocalBackend()
+  const cwdState = resolveCwd(deps.cwd)
+  return {
+    name: 'shell.run',
+    description:
+      'Run a shell command in the agent workspace. Subject to permission approval (mode `prompt` or `strict`). Wallet/API-key environment variables are redacted before launch. Captures stdout/stderr; killed on timeout.',
+    searchHint: 'shell run bash command execute subprocess',
+    schema: ShellSchema,
+    handler: async args => {
+      const cwd = cwdState.get()
+      const timeout = args.timeout_ms ?? deps.defaultTimeoutMs ?? 60_000
+      const { env: redactedEnv, removed } = redactEnv(process.env)
+      // Build an explicit /bin/sh -c <cmd> argv so the sandbox backend can
+      // wrap it without colliding with shell:true semantics. The wrapper may
+      // prepend e.g. sandbox-exec -p <profile>; spawn must see a real argv.
+      const wrapped = await sandbox.wrapSpawn({
+        command: '/bin/sh',
+        args: ['-c', args.command],
+        options: { cwd, env: redactedEnv },
+      })
+      return new Promise(resolve => {
+        const child = spawn(wrapped.command, wrapped.args, wrapped.options)
+        let stdout = ''
+        let stderr = ''
+        let timedOut = false
+        const timer = setTimeout(() => {
+          timedOut = true
+          child.kill('SIGKILL')
+        }, timeout)
+        child.stdout?.on('data', chunk => {
+          stdout += String(chunk)
+          if (stdout.length > 200_000) stdout = stdout.slice(-200_000)
+        })
+        child.stderr?.on('data', chunk => {
+          stderr += String(chunk)
+          if (stderr.length > 200_000) stderr = stderr.slice(-200_000)
+        })
+        child.on('close', code => {
+          clearTimeout(timer)
+          resolve({
+            ok: !timedOut && code === 0,
+            data: {
+              command: args.command,
+              code,
+              timedOut,
+              stdout: stdout.slice(-32_000),
+              stderr: stderr.slice(-32_000),
+              cwd,
+              redactedEnvVars: removed,
+            },
+            ...(timedOut
+              ? { error: `command timed out after ${timeout}ms` }
+              : code !== 0
+                ? { error: `exit code ${code}` }
+                : {}),
+          })
+        })
+        child.on('error', e => {
+          clearTimeout(timer)
+          resolve({ ok: false, error: e.message })
+        })
+      })
+    },
+  }
+}

package/src/skills-manage.ts

@@ -0,0 +1,126 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { type ToolDef, scanSkills } from 'nebula-ai-core'
+import { z } from 'zod'
+
+/**
+ * Phase 9.1 skills.manage. Persists per-skill on/off state into the user's
+ * nebula config (under `skills.disabled[]`). Re-scans the disk on every call so
+ * the user can install a new skill in another shell and the agent picks it up
+ * without restart.
+ */
+
+interface SkillsManageDeps {
+  importsClaudeCode: boolean
+  /** Path to ~/.nebula/config.ts. Used to read+rewrite the disabled list. */
+  configPath: string
+  /** When set, the manage tool reports this list as the active disabled set. */
+  disabledRef?: { current: string[] }
+  nebulaSkillsRoot?: string
+  claudeSkillsRoot?: string
+  claudePluginsCacheRoot?: string
+  nebulaPluginsRoot?: string
+}
+
+const DISABLED_BLOCK_RE = /skills:\s*\{[^}]*disabled:\s*\[([\s\S]*?)\][^}]*\}/
+
+const ManageSchema = z.object({
+  action: z
+    .enum(['list', 'enable', 'disable', 'refresh'])
+    .describe(
+      "'list' shows enabled+disabled skills; 'enable' / 'disable' flip a specific skill id; 'refresh' re-scans the disk.",
+    ),
+  id: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Skill id to enable/disable. Required for enable/disable actions.'),
+})
+
+export function makeSkillsManage(deps: SkillsManageDeps): ToolDef<z.infer<typeof ManageSchema>> {
+  return {
+    name: 'skills.manage',
+    description:
+      "Enable/disable specific skills, or list all skills with their on/off state. Disabled skills are persisted in ~/.nebula/config.ts so the next session honors the choice. Use 'refresh' to re-scan the disk after installing a new skill.",
+    searchHint: 'skills manage enable disable toggle',
+    schema: ManageSchema,
+    handler: async args => {
+      const all = await scanSkills({
+        importsClaudeCode: deps.importsClaudeCode,
+        nebulaSkillsRoot: deps.nebulaSkillsRoot,
+        nebulaPluginsRoot: deps.nebulaPluginsRoot,
+        claudeSkillsRoot: deps.claudeSkillsRoot,
+        claudePluginsCacheRoot: deps.claudePluginsCacheRoot,
+      })
+      const disabled = new Set(deps.disabledRef?.current ?? [])
+      if (args.action === 'list' || args.action === 'refresh') {
+        return {
+          ok: true,
+          data: {
+            total: all.length,
+            disabled: [...disabled].sort(),
+            skills: all
+              .map(s => ({
+                id: s.id,
+                source: s.source,
+                enabled: !disabled.has(s.id),
+                description: s.description,
+              }))
+              .sort((a, b) => a.id.localeCompare(b.id)),
+          },
+        }
+      }
+      if (!args.id) {
+        return { ok: false, error: 'id is required for enable/disable' }
+      }
+      const known = all.find(s => s.id === args.id)
+      if (!known) return { ok: false, error: `unknown skill: ${args.id}` }
+      if (args.action === 'enable') disabled.delete(args.id)
+      else disabled.add(args.id)
+      const next = [...disabled].sort()
+      try {
+        await persistDisabled(deps.configPath, next)
+      } catch (e) {
+        return { ok: false, error: `failed to update config: ${(e as Error).message}` }
+      }
+      if (deps.disabledRef) deps.disabledRef.current = next
+      return {
+        ok: true,
+        data: { id: args.id, action: args.action, disabled: next },
+      }
+    },
+  }
+}
+
+async function persistDisabled(configPath: string, disabled: readonly string[]): Promise<void> {
+  let raw: string
+  try {
+    raw = await readFile(configPath, 'utf8')
+  } catch {
+    raw = ''
+  }
+  const block = `skills: { disabled: [${disabled.map(s => `'${s.replace(/'/g, "\\'")}'`).join(', ')}] }`
+  if (raw.includes('skills:')) {
+    const next = raw.replace(DISABLED_BLOCK_RE, block)
+    await writeFile(configPath, next, 'utf8')
+    return
+  }
+  // Insert just before the closing `}` of the top-level config object. Works
+  // for both `defineConfig({...})` and `export default {...}` shapes.
+  const inserted = injectKey(raw, block)
+  if (inserted) {
+    await writeFile(configPath, inserted, 'utf8')
+    return
+  }
+  await writeFile(configPath, `${raw}\n// nebula added: ${block}\n`, 'utf8')
+}
+
+function injectKey(raw: string, block: string): string | null {
+  // Find the last `}` that closes the config object (handles both
+  // `}\n` and `})\n` endings; strips trailing whitespace).
+  const closer = raw.match(/\n}\)?\s*$/)
+  if (!closer) return null
+  const before = raw.slice(0, closer.index)
+  const after = raw.slice(closer.index!)
+  const sep = before.trimEnd().endsWith(',') ? '\n' : ',\n'
+  return `${before.trimEnd()}${sep}  ${block}${after}`
+}

package/src/skills.ts

@@ -0,0 +1,107 @@
+import { readFile } from 'node:fs/promises'
+import { type SkillRef, type ToolDef, coerceInt, scanSkills } from 'nebula-ai-core'
+import { z } from 'zod'
+
+/**
+ * Phase 9.1 skills surface. The scanner now lives in core (it's also used by
+ * the frozen-prefix builder + auto-trigger hook); these two tools are the
+ * brain-callable views.
+ */
+
+interface SkillsToolDeps {
+  importsClaudeCode: boolean
+  /** Override the nebula skills root. Defaults to agentPaths.skills. */
+  nebulaSkillsRoot?: string
+  /** Override the Claude Code skills root. Default: $HOME/.claude/skills. */
+  claudeSkillsRoot?: string
+  /** Override the Claude Code plugins cache root. Default: $HOME/.claude/plugins/cache. */
+  claudePluginsCacheRoot?: string
+  /** Override the nebula plugins root. Defaults to agentPaths.plugins. */
+  nebulaPluginsRoot?: string
+  /** Disabled skill ids (skills.manage persists this set into config). */
+  disabled?: readonly string[]
+}
+
+async function discover(deps: SkillsToolDeps): Promise<SkillRef[]> {
+  const found = await scanSkills({
+    importsClaudeCode: deps.importsClaudeCode,
+    nebulaSkillsRoot: deps.nebulaSkillsRoot,
+    nebulaPluginsRoot: deps.nebulaPluginsRoot,
+    claudeSkillsRoot: deps.claudeSkillsRoot,
+    claudePluginsCacheRoot: deps.claudePluginsCacheRoot,
+  })
+  if (!deps.disabled || deps.disabled.length === 0) return found
+  const disabled = new Set(deps.disabled)
+  return found.filter(s => !disabled.has(s.id))
+}
+
+const ListSchema = z.object({
+  source: z.enum(['nebula', 'nebula-plugin', 'claude-code', 'claude-plugin', 'all']).optional(),
+})
+
+export function makeSkillsList(deps: SkillsToolDeps): ToolDef<z.infer<typeof ListSchema>> {
+  return {
+    name: 'skills.list',
+    description:
+      'List skills from ~/.nebula/skills, ~/.nebula/plugins/<n>/skills, ~/.claude/skills, and ~/.claude/plugins/cache/<m>/<p>/<v>/skills (when imports.claudeCode). Returns id, name, description, source, path.',
+    searchHint: 'skills list catalog discover available',
+    schema: ListSchema,
+    handler: async args => {
+      const all = await discover(deps)
+      const filter = args.source ?? 'all'
+      const filtered = filter === 'all' ? all : all.filter(s => s.source === filter)
+      return {
+        ok: true,
+        data: {
+          skills: filtered.map(s => ({
+            id: s.id,
+            name: s.frontmatter.name ?? s.name,
+            description: s.description,
+            path: s.path,
+            source: s.source,
+            filePattern: s.frontmatter.filePattern ?? null,
+            bashPattern: s.frontmatter.bashPattern ?? null,
+          })),
+        },
+      }
+    },
+  }
+}
+
+const ViewSchema = z.object({
+  id: z.string().min(1).describe('Skill id from skills.list (e.g., "nebula:dogfood").'),
+  max_bytes: coerceInt.refine(n => n > 0 && n <= 200_000, 'max_bytes must be 1..200000').optional(),
+})
+
+export function makeSkillsView(deps: SkillsToolDeps): ToolDef<z.infer<typeof ViewSchema>> {
+  return {
+    name: 'skills.view',
+    description:
+      'Read the full SKILL.md body for a skill identified by `skills.list`. Use to inline a skill before applying it.',
+    searchHint: 'skills view read body content',
+    schema: ViewSchema,
+    handler: async args => {
+      const all = await discover(deps)
+      const skill = all.find(s => s.id === args.id)
+      if (!skill) return { ok: false, error: `unknown skill: ${args.id}` }
+      try {
+        const buf = await readFile(skill.path)
+        const cap = args.max_bytes ?? 100_000
+        const truncated = buf.byteLength > cap
+        const text = buf.subarray(0, Math.min(buf.byteLength, cap)).toString('utf8')
+        return {
+          ok: true,
+          data: {
+            id: skill.id,
+            path: skill.path,
+            text,
+            bytes: buf.byteLength,
+            truncated,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message }
+      }
+    },
+  }
+}

package/src/todo.ts

@@ -0,0 +1,91 @@
+import type { ToolDef } from 'nebula-ai-core'
+import { z } from 'zod'
+
+/**
+ * In-session task list. Brain uses this to plan multi-step work, similar to
+ * Claude Code's TodoWrite. State lives in-memory per session; when the
+ * process exits, the list is gone (this is intentional; persistent task
+ * state belongs in `memory.save` with `project` type).
+ */
+
+interface TodoItem {
+  id: string
+  text: string
+  status: 'pending' | 'in_progress' | 'completed'
+}
+
+const TodoSchema = z.object({
+  action: z
+    .enum(['add', 'update', 'list', 'clear'])
+    .describe('add a task, update its status, list current tasks, or clear all.'),
+  id: z.string().optional().describe('Required for update; the task id returned from add.'),
+  text: z.string().optional().describe('Task description. Required for add.'),
+  status: z
+    .enum(['pending', 'in_progress', 'completed'])
+    .optional()
+    .describe('Required for update.'),
+})
+
+export function makeTodo(): ToolDef<z.infer<typeof TodoSchema>> {
+  const tasks: TodoItem[] = []
+  let next = 1
+  return {
+    name: 'todo',
+    description:
+      'Manage an in-session task list. Use to plan multi-step work; the list is shown to the user via post-tool-call rendering. Tasks reset when chat exits.',
+    searchHint: 'todo task plan steps tracker',
+    schema: TodoSchema,
+    handler: args => {
+      if (args.action === 'add') {
+        if (!args.text) return { ok: false, error: 'text is required for add' }
+        const id = String(next++)
+        tasks.push({ id, text: args.text, status: 'pending' })
+        return { ok: true, data: { id, tasks } }
+      }
+      if (args.action === 'update') {
+        if (!args.id || !args.status) {
+          return { ok: false, error: 'id + status required for update' }
+        }
+        const idx = tasks.findIndex(t => t.id === args.id)
+        if (idx === -1) return { ok: false, error: `unknown task: ${args.id}` }
+        tasks[idx] = { ...tasks[idx]!, status: args.status }
+        return { ok: true, data: { tasks } }
+      }
+      if (args.action === 'clear') {
+        tasks.length = 0
+        return { ok: true, data: { tasks } }
+      }
+      return { ok: true, data: { tasks } }
+    },
+  }
+}
+
+const ClarifySchema = z.object({
+  question: z.string().min(3).describe('Question to ask the operator.'),
+  options: z
+    .array(z.string())
+    .optional()
+    .describe('Optional multiple-choice options for the operator.'),
+})
+
+/**
+ * `clarify` is the brain's escape hatch when it doesn't have enough info to
+ * proceed. Phase 9.0 implementation surfaces the question via the tool result
+ * (chat.tsx renders it as a system row); the operator can answer in their next
+ * message. A future phase will add a structured pause.
+ */
+export function makeClarify(): ToolDef<z.infer<typeof ClarifySchema>> {
+  return {
+    name: 'clarify',
+    description:
+      'Ask the operator a question and surface it inline. Use when the next step requires information the brain does not have. The result echoes the question back for display; the operator answers in their next message.',
+    searchHint: 'clarify ask question prompt operator',
+    schema: ClarifySchema,
+    handler: args => {
+      return {
+        ok: true,
+        data: { question: args.question, options: args.options ?? null },
+      }
+    },
+  }
+}