Skip to content

orchestration.md

Latest commit

 

History

History
158 lines (111 loc) · 3.08 KB

orchestration.md

File metadata and controls

158 lines (111 loc) · 3.08 KB
Raw

Orchestration

Nerva is designed as an agent runtime, not only a prompt wrapper.

The orchestration surface is intentionally visible so a project can change how the agent plans, gathers evidence, uses tools, recalls memory, compacts context, delegates to subagents, and reacts to runtime events.

Runtime Layers

High-level flow:

  1. CLI parses args and interactive controls.
  2. Bootstrap assembles settings, provider registry, tools, skills, extensions, MCP runtime, session state, and theme.
  3. Agent builds outbound context from system fragments, session transcript, memory recall, attached files, and prompt input.
  4. Provider adapter streams or returns model output.
  5. Tool, skill, MCP, and subagent calls are routed through the runtime.
  6. Turn trace records what happened.
  7. Context and memory systems decide what should survive.

Relevant source areas:

src/bootstrap/
src/agent/
src/app/
src/control/
src/events/
src/extensions/
src/subagents/

Built-In Prompt Stack

Built-in prompt fragments live in:

src/bootstrap/builtin/prompts/

They define the default posture for:

  • orchestration
  • workflow and verification
  • tool and skill discipline
  • code structure
  • context and memory
  • browser workflows

Project and user prompt fragments can be added under:

./.nerva/prompts/
~/.nerva/prompts/

Role Tools

Nerva exposes role tools that make workflow state visible:

  • plan
  • develop
  • review
  • finish

The intent is to keep the model honest about what phase it is in and what proof is still missing.

Subagents

Subagents let Nerva split work into child activity streams while preserving a parent session.

Useful controls:

/subagents
/subagent <id>
/subagent back
/subagent close <id>

The model-visible subagent tool is registered by default.

Extension Hooks

Extensions can observe or intercept runtime events.

Hook modes:

  • observe
  • intercept

Intercept hooks can return actions:

  • call_tool
  • call_skill
  • call_mcp
  • prompt_as_user

This makes extensions a practical orchestration layer without requiring an in-process plugin ABI.

See Extension SDK for the full hook contract.

MCP

MCP servers extend the tool surface through stdio servers.

Project config:

./.nerva/mcp.json

Controls:

/mcp servers
/mcp capabilities
/mcp init
/mcp reload

Context and Memory

Nerva keeps context and memory separate:

  • context is active working state for the next request
  • memory is durable workspace knowledge that should survive turns

Context controls:

/context
/context full
/context diff
/compact

Memory tools:

  • memory_add
  • memory_search
  • memory_delete

Practical Customization Path

For a project-specific agent setup:

  1. Add ./.nerva/settings.json.
  2. Add ./.nerva/prompts/ for project rules.
  3. Add ./.nerva/skills/ for repeatable reasoning workflows.
  4. Add ./.nerva/extensions/ for commands, tools, and hooks.
  5. Add ./.nerva/mcp.json for external tool ecosystems.
  6. Use /context full and /tools to verify what the model can actually see.