diff --git a/AGENT_INTEGRATION.md b/AGENT_INTEGRATION.md index 83a24f29..b06ddfcf 100644 --- a/AGENT_INTEGRATION.md +++ b/AGENT_INTEGRATION.md @@ -1,18 +1,23 @@ # Agent Integration Guide -Rune works with all major AI agents via native MCP (Model Context Protocol) support. +Rune works with all major AI agents via native MCP (Model Context Protocol) +support. In v0.4 the MCP server is a single Go binary +(`bin/rune-mcp`) that the host CLI auto-spawns over stdio — no Python +runtime, no `pip install`, no manual `mcp add` for the supported CLIs. ## Integration Principles ### Cross-agent common (single source of truth) - -- Runtime prep (venv/deps/self-healing) must go through `scripts/bootstrap-mcp.sh`. -- Do not duplicate Python setup logic per agent. +- The Go binary at `cmd/rune-mcp/` is the only MCP server entry point. + Plugin / extension manifests point each CLI at the same binary. +- Runtime preparation happens at install time (the binary is already + built and shipped with the plugin tarball — see Task #30 for the + release pipeline). Nothing needs to be (re)bootstrapped at session + start. ### Agent-specific adapters (thin layer only) - - Codex-only tasks: `codex mcp add/remove/list` registration flows -- Claude/Gemini/OpenAI tasks: each client's native MCP registration flow +- Claude / Gemini / OpenAI: each client's native MCP registration flow Keep these layers separate to avoid cross-agent drift. @@ -20,66 +25,77 @@ Keep these layers separate to avoid cross-agent drift. | Agent | Integration | Setup | |-------|-------------|-------| -| **Claude Code** | MCP Native (stdio) | ⭐ Easy | -| **Codex CLI** | MCP Native (stdio) | ⭐ One Command | -| **Gemini CLI** | MCP Native (stdio) | ⭐ One Command | -| **OpenAI GPT** | MCP Native (stdio) | ⭐ Easy | +| **Claude Code** | MCP Native (stdio) | ⭐ Plugin install | +| **Codex CLI** | MCP Native (stdio) | ⭐ Skill install | +| **Gemini CLI** | MCP Native (stdio) | ⭐ Extension install | +| **OpenAI GPT** | MCP Native (stdio) | ⭐ Programmatic | -> **Note**: The MCP server uses **stdio transport only**. HTTP/SSE mode is not supported. - ---- +> The MCP server uses **stdio transport only**. HTTP/SSE mode is not supported. --- ## Claude Code -### Automatic Setup (Recommended) +### Plugin install (recommended) ```bash -cd rune -./scripts/install.sh +# From terminal (local clone) +$ claude plugin marketplace add ./ +$ claude plugin install rune + +# From inside a Claude Code session (remote) +> /plugin marketplace add https://github.com/CryptoLabInc/rune +> /plugin install rune ``` -This prepares runtime using the shared bootstrap flow for Claude usage. +The plugin manifest (`.claude-plugin/plugin.json`) declares the binary +path; Claude Code spawns `${CLAUDE_PLUGIN_ROOT}/bin/rune-mcp` via stdio +on session start. enVector Cloud credentials are delivered automatically +via the Vault bundle — you never set `ENVECTOR_*` env vars directly. -### Manual Setup +### Configure credentials -```bash -claude mcp add --scope user --transport stdio \ - -e RUNE_CONFIG="$HOME/.rune/config.json" \ - -e PYTHONPATH="/path/to/rune/mcp" \ - rune -- \ - /path/to/rune/.venv/bin/python3 \ - /path/to/rune/mcp/server/server.py --mode stdio +``` +> /rune:configure ``` -> enVector Cloud credentials are delivered automatically via the Vault bundle at session start. +Walks you through Vault endpoint + token + TLS choice, writes +`~/.rune/config.json`, and triggers the boot loop. -Restart Claude Code → MCP tools auto-load. +### Verify ---- +``` +> /rune:status +``` -## Codex CLI +Renders per-subsystem health (Vault / EncKey / AgentDEK / Embedder / +enVector) via the `diagnostics` MCP tool. -### One-Command Installation +### Dev mode (running from a local clone) ```bash -cd rune -./scripts/install-codex.sh +$ claude --plugin-dir /path/to/rune ``` -This automatically: -1. Creates `.venv` and installs Python dependencies -2. Registers Rune MCP server as `rune` in Codex +Loads the plugin from the working tree instead of the installed cache. +Useful for iterating on `commands/claude/*.md` or the Go binary without +re-installing the plugin. -### Codex-only Runtime Ensure +--- -```bash -cd rune -./scripts/ensure-codex-ready.sh --register +## Codex CLI + +### Skill install + +``` +> $skill-installer install https://github.com/CryptoLabInc/rune.git ``` -This is a Codex-only adapter that reuses `bootstrap-mcp.sh` and then ensures Codex MCP registration. +### Configure + +``` +> $rune configure +``` ### Verify @@ -88,204 +104,129 @@ codex mcp list # Should show rune ``` -### Configuration - -After installation, configure credentials: +If `rune` is not listed after install, re-register manually: ```bash -cp config/config.template.json ~/.rune/config.json -# Edit with your Vault endpoint and token -# enVector credentials are delivered automatically via the Vault bundle +codex mcp add rune --command /path/to/bin/rune-mcp --transport stdio ``` - --- ## Gemini CLI -### Option 1: Gemini SDK +### Extension install ```bash -pip install google-generativeai mcp +$ gemini extensions install https://github.com/CryptoLabInc/rune.git ``` -```python -import google.generativeai as genai -from mcp import ClientSession, StdioServerParameters -from mcp.client.stdio import stdio_client +### Configure -genai.configure(api_key="your-api-key") - -async def main(): - server_params = StdioServerParameters( - command="/path/to/rune/.venv/bin/python3", - args=["/path/to/rune/mcp/server/server.py"], - env={"PYTHONPATH": "/path/to/rune/mcp"} - ) - - async with stdio_client(server_params) as (read, write): - async with ClientSession(read, write) as session: - model = genai.GenerativeModel( - model_name='gemini-2.0-flash-exp', - tools=[session] # MCP session - ) - - chat = model.start_chat() - response = await chat.send_message_async( - "Create an index called team-decisions" - ) - print(response.text) - -import asyncio -asyncio.run(main()) ``` - -### Option 2: Gemini CLI MCP Config - -```bash -npm install -g @google/generative-ai-cli +> /rune:configure ``` -Edit `~/.gemini/mcp_config.json`: +### Manual `mcp_config.json` (advanced) + ```json { "mcpServers": { "rune": { - "command": "/path/to/rune/.venv/bin/python3", - "args": ["/path/to/rune/mcp/server/server.py"], - "env": { - "PYTHONPATH": "/path/to/rune/mcp" - } + "command": "/path/to/bin/rune-mcp", + "transport": "stdio" } } } ``` -```bash -gemini chat -> Create an index called team-decisions -# MCP tools auto-called -``` +> The legacy `gemini-extension.json` still references +> `scripts/bootstrap-mcp.sh`; rewriting it for the Go binary is tracked +> as a follow-up under the Gemini track. --- ## OpenAI GPT -**Update 2025**: OpenAI has [native MCP support](https://venturebeat.com/programming-development/openai-updates-its-new-responses-api-rapidly-with-mcp-support-gpt-4o-native-image-gen-and-more-enterprise-features) via Responses API. - -### Option 1: OpenAI Agents SDK (Recommended) - -```bash -pip install openai-agents -``` - -```python -from openai_agents import Agent -from openai_agents.mcp import MCPServerStdio - -mcp_server = MCPServerStdio( - command="/path/to/rune/.venv/bin/python3", - args=["/path/to/rune/mcp/server/server.py"], - env={"PYTHONPATH": "/path/to/rune/mcp"} -) - -agent = Agent( - model="gpt-4o", - mcp_servers=[mcp_server] -) - -response = agent.run("Create an index called team-decisions") -print(response.final_output) -``` - -### Option 2: Responses API (stdio via MCP SDK) - -```bash -pip install openai mcp -``` +OpenAI's Responses API has [native MCP support](https://venturebeat.com/programming-development/openai-updates-its-new-responses-api-rapidly-with-mcp-support-gpt-4o-native-image-gen-and-more-enterprise-features), +so you point it at the same Go binary via stdio: ```python from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client -# Connect to Rune MCP server via stdio server_params = StdioServerParameters( - command="/path/to/rune/.venv/bin/python3", - args=["/path/to/rune/mcp/server/server.py"], - env={"PYTHONPATH": "/path/to/rune/mcp"} + command="/path/to/bin/rune-mcp", + args=[], # binary takes no args; reads ~/.rune/config.json ) -# Use with OpenAI function calling by listing MCP tools async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: tools = await session.list_tools() - # Convert MCP tools to OpenAI function format and call as needed + # forward tools to OpenAI function calling ``` +The OpenAI Agents SDK pattern is identical — pass the same `command` +into `MCPServerStdio`. + --- ## Multi-Agent Collaboration -Multiple agents can share the same Rune infrastructure via stdio: - -``` -# Each agent launches its own MCP server process (stdio) -# All connect to the same enVector Cloud index + Rune-Vault -``` +Each agent spawns its own MCP server process; shared state is +maintained via enVector Cloud (encrypted vectors) and Rune-Vault +(decryption keys). -**Architecture**: ``` -Claude ──→ MCP Server (stdio) ──┐ - ├──→ enVector Cloud (encrypted) -Gemini ──→ MCP Server (stdio) ──┤ └──→ Rune-Vault (secret key) - │ -GPT ─────→ MCP Server (stdio) ──┘ +Claude ──→ rune-mcp (stdio) ──┐ + ├──→ enVector Cloud (encrypted) +Gemini ──→ rune-mcp (stdio) ──┤ └──→ Rune-Vault (secret key) + │ +GPT ──→ rune-mcp (stdio) ──┘ ``` -Each agent spawns its own MCP server process. Shared state is maintained via enVector Cloud (encrypted vectors) and Rune-Vault (decryption keys). +All three connect to the same team index + Vault, so a capture from +one agent is recallable by another. --- ## Troubleshooting -### Re-run shared bootstrap (all agents) -```bash -cd rune -SETUP_ONLY=1 ./scripts/bootstrap-mcp.sh -``` - ### MCP server won't start + ```bash -cd rune -source .venv/bin/activate -python mcp/server/server.py --help +# Run the binary directly to see startup errors +/path/to/bin/rune-mcp +# (it will block on stdin — Ctrl-D to exit; you're looking for slog +# error output before the block) ``` -### Codex-only registration repair +If you set `RUNE_MCP_LOG_FILE=` in the spawning shell, the server tees +its slog to `~/.rune/logs/rune-mcp.log` so you can `tail -f` while the +host CLI runs it. + +### Codex registration repair + ```bash -cd rune -./scripts/ensure-codex-ready.sh --register codex mcp list +codex mcp add rune --command /path/to/bin/rune-mcp --transport stdio ``` -### Missing environment variables +### Missing or wrong credentials + ```bash cat ~/.rune/config.json - -# Or set environment variables directly: -export RUNEVAULT_ENDPOINT="vault-yourteam.oci.envector.io:50051" -export RUNEVAULT_TOKEN="your-token" -# Optional: explicit gRPC target override (auto-derived from RUNEVAULT_ENDPOINT if omitted) -# export RUNEVAULT_GRPC_TARGET="vault-host:50051" - -# enVector credentials are delivered automatically via the Vault bundle. -# You do NOT need to set ENVECTOR_ENDPOINT or ENVECTOR_API_KEY. +# vault.endpoint, vault.token, ca_cert, tls_disable, state ``` +enVector credentials are delivered automatically via the Vault bundle +at boot — they live in memory only and are not stored locally. You do +NOT need to set `ENVECTOR_ENDPOINT` or `ENVECTOR_API_KEY`. + ### Verify MCP tools are available -In Claude Code, after plugin installation: +In Claude Code after plugin install: ``` -/rune:status +/plugin # confirm 'rune' loaded, Errors 0 +/rune:status # confirm Active + diagnostics snapshot ``` --- @@ -296,4 +237,3 @@ In Claude Code, after plugin installation: - [Google Cloud MCP Announcement](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) - [OpenAI Responses API MCP](https://venturebeat.com/programming-development/openai-updates-its-new-responses-api-rapidly-with-mcp-support-gpt-4o-native-image-gen-and-more-enterprise-features) - [Gemini CLI MCP Docs](https://geminicli.com/docs/tools/mcp-server/) -- [FastMCP](https://github.com/jlowin/fastmcp) diff --git a/CLAUDE.md b/CLAUDE.md index ba24c4c3..84ddf38f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -53,7 +53,7 @@ When Rune state is `"active"`, **proactively spawn a background `rune:scribe` su | Need | Use | NOT | |------|-----|-----| | Search organizational memory | `rune:retriever` / `recall` MCP tool | Explore agent (no MCP access) | -| Capture decisions | `rune:scribe` / `capture` MCP tool (agent-delegated: pass `extracted` JSON) | Writing Python scripts to `/tmp` | +| Capture decisions | `rune:scribe` / `capture` MCP tool (agent-delegated: pass `extracted` JSON) | Writing scripts to `/tmp` | | Search this codebase | Explore agent / Glob / Grep | `recall` (that's for decisions, not code) | | Brainstorm from scratch | `superpowers:brainstorming` | `recall` (nothing to recall yet) | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 243632e7..906f8a61 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,13 +42,11 @@ Feature requests should include: ``` 3. **Make your changes** - - Follow existing code style + - Follow existing code style (`gofmt -w` + `go vet ./...` should be clean) - Update documentation - - Test your changes - - Files must live under a `tests/` subdirectory and be named `test_*.py` - - Test classes must start with `Test` - - Test functions/methods must start with `test_` - + - Test your changes: + - Tests live alongside the package they cover, named `*_test.go` + - Run with `go test ./...` (use `-race` before submitting) - Pass cross-agent invariant checks (see checklist below) 4. **Commit your changes** @@ -74,7 +72,7 @@ Feature requests should include: ### Prerequisites - Git -- Python 3.12 +- Go 1.26.2+ (the toolchain pin is in `go.mod`) - Text editor (VS Code recommended) - An MCP-compatible agent for testing (Claude Code, Codex CLI, etc.) @@ -112,8 +110,9 @@ Feature requests should include: 4. **Run tests** ```bash - source .venv/bin/activate - python -m pytest agents/tests/ -v + go build ./... + go vet ./... + go test -race ./... ``` 5. **Test changes in an agent** @@ -139,13 +138,12 @@ Feature requests should include: Use this checklist for any integration/setup/runtime change: -- [ ] `scripts/bootstrap-mcp.sh` remains the single source of truth for runtime prep (venv/deps/self-heal) -- [ ] No agent-specific script duplicates bootstrap/setup logic +- [ ] The Go binary at `cmd/rune-mcp/` remains the single MCP server entry point — no per-agent server process - [ ] Agent-specific scripts stay thin adapters (registration/wiring only) - [ ] Codex-only commands (`codex mcp ...`) are clearly separated from cross-agent/common instructions - [ ] Claude/Gemini/OpenAI instructions do not include Codex-only commands -- [ ] Non-server callers of `bootstrap-mcp.sh` use `SETUP_ONLY=1` to avoid exec-ing the MCP server process - [ ] `SKILL.md`, `commands/rune/*.toml`, and `AGENT_INTEGRATION.md` remain consistent on common vs agent-specific boundaries +- [ ] Plugin manifests (`.claude-plugin/plugin.json`, `gemini-extension.json`) point at the same Go binary command path ### Manual Testing Checklist @@ -266,35 +264,41 @@ rune/ ├── GEMINI.md # Gemini CLI context file ├── CONTRIBUTING.md # This file ├── LICENSE # Apache License 2.0 -├── requirements.txt # Python dependencies +├── go.mod / go.sum # Go module pin (toolchain + deps) ├── package.json # Package metadata (version source) ├── .claude-plugin/ -│ ├── plugin.json # Claude Code plugin manifest +│ ├── plugin.json # Claude Code plugin manifest (points at bin/rune-mcp) │ └── marketplace.json # Marketplace listing ├── gemini-extension.json # Gemini CLI extension manifest ├── hooks/ │ └── hooks.json # Gemini lifecycle hooks -├── mcp/ -│ ├── server/ -│ │ └── server.py # MCP server (stdio transport) -│ └── adapter/ # enVector SDK + Vault adapters +├── cmd/ +│ └── rune-mcp/ # MCP server entry point (Go, stdio transport) +├── internal/ +│ ├── mcp/ # tool registration + handler dispatch +│ ├── service/ # CaptureService / RecallService / LifecycleService +│ ├── lifecycle/ # boot loop + state machine +│ ├── adapters/ # vault / envector / embedder / config / logio gRPC clients +│ ├── domain/ # schemas + typed errors (Python parity) +│ ├── policy/ # pure helpers (novelty, rerank, query parse) +│ └── obs/ # slog handler with sensitive-data redaction ├── agents/ -│ ├── claude/ # Claude agent specs (.md) +│ ├── claude/ # Claude agent specs (.md, referenced by plugin.json) │ │ ├── scribe.md │ │ └── retriever.md │ ├── gemini/ # Gemini agent specs (.md) │ │ ├── scribe.md │ │ └── retriever.md -│ ├── common/ # Shared Python modules -│ ├── scribe/ # Scribe pipeline code -│ ├── retriever/ # Retriever pipeline code -│ └── tests/ # Agent tests (pytest) +│ └── codex/ # Codex agent spec +│ └── scribe.md ├── commands/ │ ├── claude/ # Claude commands (.md format) │ └── rune/ # Gemini commands (.toml format) ├── patterns/ # Capture trigger patterns (en/ko/ja) -├── scripts/ # Install, configure, bootstrap scripts -├── config/ # Configuration templates +├── scripts/ +│ ├── dev/v04/ # dev-only helpers (preflight, etc.) +│ └── ... # legacy install scripts (Gemini path — under review) +├── docs/ # architecture / migration / spec └── examples/ # Usage examples ``` @@ -302,11 +306,11 @@ rune/ - **CLAUDE.md**: Claude Code project guidelines - **GEMINI.md**: Gemini CLI context file -- **.claude-plugin/plugin.json**: Claude Code plugin manifest +- **.claude-plugin/plugin.json**: Claude Code plugin manifest (points at `${CLAUDE_PLUGIN_ROOT}/bin/rune-mcp`) - **gemini-extension.json**: Gemini CLI extension manifest -- **mcp/server/server.py**: The MCP server (stdio transport) -- **agents/common/config.py**: `LLMConfig` dataclass and config schema -- **agents/common/llm_client.py**: Multi-provider LLM abstraction +- **cmd/rune-mcp/main.go**: MCP server entry point — wires services + boot loop + slog +- **internal/lifecycle/boot.go**: Boot loop (Vault dial → EncKey → embedder → envector → Active) +- **internal/service/{capture,recall,lifecycle}.go**: 8 MCP tool handlers ## Release Process @@ -314,10 +318,10 @@ Maintainers only: 1. Update version in `package.json`, `.claude-plugin/plugin.json`, and `gemini-extension.json` 2. Update CHANGELOG.md -3. Run tests: `python -m pytest agents/tests/ -v` -4. Create git tag: `git tag v0.2.0` -5. Push tag: `git push origin v0.2.0` -6. Create GitHub release with notes +3. Run tests: `go test -race ./...` +4. Create git tag: `git tag v0.4.0` +5. Push tag: `git push origin v0.4.0` +6. Create GitHub release with notes (attach platform binaries — see Task #30 for the release pipeline plan) ## Questions? diff --git a/GEMINI.md b/GEMINI.md index 27bac71c..a36e77ba 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -82,19 +82,29 @@ When both apply, **call Rune first** to surface prior context, then reason with ## Configuration & Runtime Operations -To ensure consistent behavior across different environments, follow these rules for configuration and initialization: - -### Plugin Root Detection (STRICT) -When executing setup or maintenance tasks, you MUST detect the Rune plugin root using this **STRICT** priority order. **DO NOT use `find` or slow recursive searches.** Immediately check these paths in order: -1. **Direct Path (Primary)**: `~/.gemini/extensions/rune/` (If `/scripts/bootstrap-mcp.sh` exists here, STOP searching and use this). -2. **Environment Variable**: `$RUNE_PLUGIN_ROOT` (if set). -3. **Local Workspace**: Current working directory. - -**Mandate**: Use the first valid path found. DO NOT explore the filesystem beyond these direct checks. - -### Runtime Preparation & Isolation (STRICT) -Before performing any operation that requires the Rune runtime: -- Always run `SETUP_ONLY=1 /scripts/bootstrap-mcp.sh` to ensure dependencies and environment are ready. -- **Environment Isolation**: In "no sandbox" mode, you MUST prevent workspace environment bleed. For ALL Python-related commands, you MUST prepend the command with environment sanitization: - `env -u VIRTUAL_ENV -u PYTHONPATH /.venv/bin/python3 ...` -- Use `/scripts/bootstrap-mcp.sh` as the single source of truth for runtime setup. Do not attempt to manually install dependencies. +In v0.4 Rune ships as a single Go binary (`bin/rune-mcp`) declared by the +plugin / extension manifest. The host CLI (Gemini / Claude / Codex) auto- +spawns it on session start over stdio — there is no venv, no install +script, no manual `pip` step. Runtime preparation happens at install time; +nothing needs to be (re)bootstrapped at session start. + +### Plugin Root Detection +You only need the plugin root for diagnostics or to inspect +`~/.gemini/extensions/rune/` artifacts. The MCP server itself is started +by the CLI; you never invoke it manually. + +If you do need the path (e.g. to read extension files): +1. **Default install location**: `~/.gemini/extensions/rune/` +2. **Environment variable**: `$RUNE_PLUGIN_ROOT` (if set) +3. **Local workspace**: current working directory (dev mode) + +Use the first valid path found. Do NOT shell out to `find` or recurse +through the filesystem. + +### Runtime Health +The MCP server's health is observable via the `diagnostics` and +`vault_status` tools — call those instead of probing the binary directly. +There is no Python environment, no venv, no `bootstrap-mcp.sh` to source. +If the boot loop hasn't reached Active, `/rune:status` surfaces the exact +sub-system that's failing (Vault / Embedder / enVector / etc.) and the +recovery action. diff --git a/README.md b/README.md index 3a3d0863..29772c0a 100644 --- a/README.md +++ b/README.md @@ -289,22 +289,18 @@ Then reinstall from the [Install](#install) section above. ## Troubleshooting ``` -/rune:status # or: $rune status +/rune:status # or: $rune status — full health snapshot via diagnostics MCP tool +/rune:reset # or: $rune reset — clear config and return to dormant +/rune:configure # or: $rune configure — re-enter Vault credentials ``` -```bash -# Check infrastructure -cd rune && ./scripts/check-infrastructure.sh - -# Reset and reconfigure -/rune:reset # or: $rune reset -/rune:configure # or: $rune configure -``` +`/rune:status` reports per-subsystem state (vault / encryption key / embedder / +enVector reachability). Failures surface a recovery action on the same line. ## Related Projects - [Rune-Admin](https://github.com/CryptoLabInc/rune-admin) — Infrastructure deployment and admin tools -- [pyenvector](https://socket.dev/pypi/package/pyenvector) — FHE encryption SDK +- [envector-go-sdk](https://github.com/CryptoLabInc/envector-go-sdk) — FHE encryption SDK (Go) - [enVector Cloud](https://envector.io) — Encrypted vector database ## Support diff --git a/SKILL.md b/SKILL.md index 8a7890b1..f34ac9ae 100644 --- a/SKILL.md +++ b/SKILL.md @@ -7,19 +7,19 @@ description: Encrypted organizational memory workflow for Rune with activation c **Context**: This skill provides encrypted organizational memory capabilities using Fully Homomorphic Encryption (FHE). It allows teams to capture, store, and retrieve institutional knowledge while maintaining zero-knowledge privacy. Works with Claude Code, Codex CLI, Gemini CLI, and any MCP-compatible agent. -## Execution Model (Single Source of Truth) +## Execution Model -**Cross-agent invariant**: -- `scripts/bootstrap-mcp.sh` is the **single source of truth** for local runtime preparation (venv, deps, self-healing). -- All agent integrations must reuse this bootstrap flow. Do not duplicate dependency/setup logic in agent-specific scripts. +In v0.4 the MCP server is a single Go binary (`${CLAUDE_PLUGIN_ROOT}/bin/rune-mcp`) +auto-spawned by the host CLI from the plugin manifest. There is no venv, no +install script, and no `bootstrap-mcp.sh` to source. The runtime is the +binary the CLI already launched. -**Agent-specific boundary**: -- **Common (all agents)**: plugin root detection, runtime bootstrap, local MCP server readiness checks. -- **Agent-specific (thin adapter only)**: - - Codex: `codex mcp add/remove/list` registration actions - - Claude/Gemini/others: their native MCP registration mechanism +**Agent-specific surface** stays thin: +- Codex: `codex mcp add/remove/list` registration actions +- Claude / Gemini / others: each CLI's native plugin / extension flow -Keep agent-specific instructions clearly labeled and never mix Codex-only commands into cross-agent/common instructions. +Keep agent-specific instructions clearly labeled and never mix Codex-only +commands into cross-agent/common instructions. ## Activation State @@ -29,23 +29,12 @@ Keep agent-specific instructions clearly labeled and never mix Codex-only comman **BEFORE doing anything, run this check:** -0. **Local Runtime Check (No Vault network calls)**: - - Detect plugin root by locating `scripts/bootstrap-mcp.sh`. Search in order: - 1. `$RUNE_PLUGIN_ROOT` environment variable (if set) - 2. `~/.claude/plugins/cache/*/rune/*/scripts/bootstrap-mcp.sh` - 3. `~/.codex/skills/rune/scripts/bootstrap-mcp.sh` - 4. Current working directory and its parent directories - - Ensure runtime via: - - `SETUP_ONLY=1 scripts/bootstrap-mcp.sh` - - If the runtime/bootstrap step fails, treat as **Dormant State** and show setup guidance. - 1. **Config File Check**: Does `~/.rune/config.json` exist? - NO → **Go to Dormant State** - YES → Continue to step 2 2. **Config Validation**: Does config contain all required fields? - `vault.endpoint` and `vault.token` - - `envector.endpoint` and `envector.api_key` - `state` is set to `"active"` - NO → **Go to Dormant State** - YES → Continue to step 3 @@ -54,7 +43,12 @@ Keep agent-specific instructions clearly labeled and never mix Codex-only comman - `state` is `"active"` → **Go to Active State** - Otherwise → **Go to Dormant State** -**IMPORTANT**: Do NOT attempt to ping Vault or make network requests during activation check. This wastes tokens. Only local runtime/config checks are allowed. +**Note**: enVector credentials are NOT in `~/.rune/config.json`. They are +delivered via the Vault bundle at runtime when the boot loop dials Vault. + +**IMPORTANT**: Do NOT attempt to ping Vault or make network requests during +activation check. This wastes tokens. The MCP server runs its own boot +loop; the activation check is purely a local config inspection. ### If Active ✅ - All functionality enabled @@ -69,9 +63,10 @@ Keep agent-specific instructions clearly labeled and never mix Codex-only comman - **Do NOT waste tokens on failed operations** - Show setup instructions when `/rune` commands (or `$rune` for Codex CLI) are used - Prompt user to: - 1. Check infrastructure: `scripts/check-infrastructure.sh` - 2. Configure: `/rune:configure` (or `$rune configure` for Codex CLI) - 3. Start MCP servers: `scripts/start-mcp-servers.sh` + 1. Configure: `/rune:configure` (or `$rune configure` for Codex CLI) — + this writes `~/.rune/config.json` and triggers the boot loop. + 2. Verify health: `/rune:status` (or `$rune status` for Codex CLI) — + surfaces per-subsystem state via the `diagnostics` MCP tool. ### Fail-Safe Behavior If in Active state but operations fail: @@ -113,14 +108,16 @@ If in Active state but operations fail: Note: enVector credentials are delivered automatically via the Vault bundle — no user input needed. -4. **Validate infrastructure** (run `scripts/check-infrastructure.sh`) - - If validation fails: Create config with `state: "dormant"`, warn user - - If validation passes: Continue to step 5 -5. Create `~/.rune/config.json` with proper structure -6. Set state based on validation: - - Infrastructure ready: `state: "active"` - - Infrastructure not ready: `state: "dormant"` -7. Confirm configuration and show next steps if dormant +4. Create `~/.rune/config.json` with `state: "active"` and the values + above (`mkdir -p ~/.rune && chmod 700 ~/.rune`, then `chmod 600` the + file). +5. Call the `reload_pipelines` MCP tool. The MCP server's boot loop + dials Vault, fetches the agent manifest (EncKey + envector + creds), connects to enVector, and transitions to Active. +6. Confirm health by calling `diagnostics` and showing the per- + subsystem snapshot. If the boot loop landed in Dormant, surface + the `dormant_reason` (e.g. `vault_unreachable`, + `vault_token_invalid`) with the recovery action. ### `/rune:status` (or `$rune status` for Codex CLI) @@ -128,33 +125,30 @@ If in Active state but operations fail: **Purpose**: Check plugin activation status and infrastructure health **Steps**: -1. Check if config exists -2. Show current state (Active/Dormant) -3. Run infrastructure checks: - - Config file: ✓/✗ - - Vault Endpoint configured: ✓/✗ - - enVector endpoint configured: ✓/✗ - - MCP server logs recent: ✓/✗ - - Virtual environment: ✓/✗ +1. Read `~/.rune/config.json` +2. Call the `diagnostics` MCP tool (read-only; safe before Active) +3. Render the per-subsystem snapshot **Response Format**: ``` Rune Plugin Status ================== -State: Active ✅ (or Dormant ⏸️) +State: Active ✅ (or Dormant ⏸️ — reason) Configuration: ✓ Config file: ~/.rune/config.json ✓ Vault Endpoint: configured - ✓ enVector: configured -Infrastructure: - ✓ Python venv: /path/to/.venv - ✗ MCP servers: Not running (last log: 2 days ago) +System Health (from diagnostics): + ✓ Vault : reachable + ✓ Encryption Key : loaded (key_id: ) + ✓ Agent DEK : loaded + ✓ Embedder : (, dim=) + ✓ enVector Cloud : reachable (ms) Recommendations: - - Start MCP servers: scripts/start-mcp-servers.sh - - Check full status: scripts/check-infrastructure.sh + - If Dormant: /rune:configure to (re)trigger the boot loop + - If a subsystem failed: surface the recovery action on its row ``` ### `/rune:capture ` @@ -210,19 +204,16 @@ Recommendations: 1. Check if config exists - NO → Redirect to `/rune:configure` (or `$rune configure` for Codex CLI) - YES → Continue -2. Run full infrastructure validation: - - Check Vault connectivity (curl vault-url/health) - - Check MCP server processes - - Check Python environment -3. If all checks pass: - - Update config.json `state` to `"active"` - - Notify: "Plugin activated ✅" -4. If checks fail: - - Keep state as `"dormant"` - - Show detailed error report - - Suggest: `/rune:status` (or `$rune status` for Codex CLI) for more info - -**Important**: This is the ONLY command that makes network requests to validate infrastructure. +2. If `state` is already `"active"`, skip to step 4 (just verify health). +3. If `state` is `"dormant"`, set it to `"active"` and clear any + `dormant_reason` / `dormant_since` fields. +4. Call the `reload_pipelines` MCP tool. From a terminal Dormant the + boot loop is re-spawned; from Active it is a no-op. +5. Call `diagnostics` and render the per-subsystem snapshot. +6. If any subsystem failed: keep state as `"active"` (the boot loop + will retry transient failures), surface the dormant_reason if the + loop fell back to Dormant, and suggest `/rune:status` for the full + snapshot. ### `/rune:reset` (or `$rune reset` for Codex CLI) @@ -231,10 +222,9 @@ Recommendations: **Steps**: 1. Confirm with user -2. Stop MCP servers if running -3. Delete `~/.rune/config.json` -4. Set state to dormant -5. Show reconfiguration instructions +2. Delete `~/.rune/config.json` (the MCP server stays alive; it transitions + to Dormant on the next reload because no config means no Vault dial) +3. Show reconfiguration instructions ## Automatic Behavior (When Active)