@neuroverseos/governance 0.2.2 → 0.3.0

package/.well-known/ai-plugin.json

@@ -0,0 +1,26 @@
+{
+  "schema_version": "v1",
+  "name": "neuroverse-governance",
+  "description": "Enforce governance rules on AI agent actions. Turn plans into enforceable constraints. Deterministic evaluation — no LLM in the loop.",
+  "capabilities": {
+    "plan_enforcement": {
+      "description": "Compile a plan into enforceable rules. Block actions outside the plan. Track progress.",
+      "input": "Plan markdown or JSON",
+      "output": "ON_PLAN / OFF_PLAN / CONSTRAINT_VIOLATED / PLAN_COMPLETE verdict with evidence"
+    },
+    "world_governance": {
+      "description": "Full governance engine with invariants, guards, roles, kernel rules, and audit trails.",
+      "input": "GuardEvent JSON",
+      "output": "ALLOW / BLOCK / PAUSE verdict with trace"
+    },
+    "plan_derive": {
+      "description": "Generate a full governance world from a plan markdown file.",
+      "input": "Plan markdown",
+      "output": "World definition files (world.json, invariants.json, guards.json)"
+    }
+  },
+  "install": "npm install @neuroverseos/governance",
+  "adapters": ["openclaw", "langchain", "openai", "express"],
+  "cli": "neuroverse",
+  "repository": "https://github.com/NeuroverseOS/Neuroverseos-governance"
+}

package/.well-known/mcp.json

@@ -0,0 +1,68 @@
+{
+  "schema_version": "1.0",
+  "server": {
+    "name": "neuroverse-governance",
+    "version": "0.2.2",
+    "description": "Deterministic governance engine for AI agents. Evaluates actions against world rules and plan constraints. Returns ALLOW, BLOCK, or PAUSE verdicts.",
+    "vendor": "NeuroverseOS",
+    "homepage": "https://neuroverseos.com",
+    "repository": "https://github.com/NeuroverseOS/Neuroverseos-governance"
+  },
+  "install": {
+    "npm": "@neuroverseos/governance",
+    "command": "npx @neuroverseos/governance mcp --world ./world"
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": false,
+    "prompts": false
+  },
+  "tools": [
+    {
+      "name": "neuroverse_guard",
+      "description": "Evaluate whether an agent action is allowed by governance rules. Returns ALLOW, BLOCK, or PAUSE.",
+      "inputSchema": {
+        "type": "object",
+        "required": ["intent"],
+        "properties": {
+          "intent": { "type": "string", "description": "What the agent wants to do" },
+          "tool": { "type": "string", "description": "Tool being invoked" },
+          "scope": { "type": "string", "description": "Resource being accessed" }
+        }
+      }
+    },
+    {
+      "name": "neuroverse_plan_check",
+      "description": "Check whether an action matches a step in the active plan. Returns ON_PLAN, OFF_PLAN, CONSTRAINT_VIOLATED, or PLAN_COMPLETE.",
+      "inputSchema": {
+        "type": "object",
+        "required": ["intent"],
+        "properties": {
+          "intent": { "type": "string", "description": "What the agent wants to do" }
+        }
+      }
+    },
+    {
+      "name": "neuroverse_plan_advance",
+      "description": "Mark a plan step as completed. In verified mode, requires evidence for steps with a verify field.",
+      "inputSchema": {
+        "type": "object",
+        "required": ["stepId"],
+        "properties": {
+          "stepId": { "type": "string", "description": "Step ID to advance" },
+          "evidenceType": { "type": "string", "description": "Evidence type (must match step verify field)" },
+          "evidenceProof": { "type": "string", "description": "Proof payload (URL, hash, etc.)" }
+        }
+      }
+    },
+    {
+      "name": "neuroverse_plan_status",
+      "description": "Get current plan progress — completed steps, total steps, percentage.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    }
+  ],
+  "tags": ["governance", "ai-safety", "agent-guardrails", "deterministic", "plan-enforcement"]
+}

package/AGENTS.md

@@ -0,0 +1,219 @@
+# NeuroVerse Governance — Agent Integration Guide
+
+## What This Package Does
+
+Runtime containment for AI agents. Define what an agent can and cannot do, then enforce it at every action. Deterministic — same event + same rules = same verdict. No LLM in the evaluation loop.
+
+## Quick Start for Agents
+
+### Install
+
+```bash
+npm install @neuroverseos/governance
+```
+
+### Enforce a world (permanent rules)
+
+```javascript
+const { evaluateGuard, loadWorld } = require('@neuroverseos/governance');
+
+const world = await loadWorld('./world/');
+const verdict = evaluateGuard({ intent: 'delete user', tool: 'db' }, world);
+// → { status: 'BLOCK', reason: 'destructive database operation' }
+```
+
+### Enforce a plan (temporary task scope)
+
+```javascript
+const { evaluatePlan, parsePlanMarkdown } = require('@neuroverseos/governance');
+
+const plan = parsePlanMarkdown(planMarkdownString);
+const verdict = evaluatePlan({ intent: 'send email', tool: 'smtp' }, plan.plan);
+// → { allowed: false, status: 'OFF_PLAN', reason: 'Action does not match any plan step.' }
+```
+
+### Enforce both (plan on top of world)
+
+```javascript
+const verdict = evaluateGuard(event, world, { plan });
+// Plan rules AND world rules both apply
+// Plan can only restrict, never expand
+```
+
+### Guard with trace (see what fired)
+
+```javascript
+const verdict = evaluateGuard(event, world, { trace: true, level: 'strict' });
+// verdict.trace contains:
+//   safetyChecks, guardChecks, kernelRuleChecks, levelChecks, invariantChecks
+```
+
+## Available Commands
+
+```
+neuroverse init                         Scaffold a .nv-world.md template
+neuroverse bootstrap --input <.md> --output <dir>  Compile to world JSON
+neuroverse build <input.md>             Derive + compile in one step
+neuroverse validate --world <dir>       9 static analysis checks
+neuroverse guard --world <dir>          Evaluate action (stdin → verdict)
+neuroverse test --world <dir>           14 standard + fuzz guard tests
+neuroverse redteam --world <dir>        28 adversarial attacks, containment score
+neuroverse doctor                       Environment sanity check
+neuroverse playground --world <dir>     Interactive web demo at localhost:4242
+neuroverse explain <world>              Human-readable world summary
+neuroverse simulate <world>             State evolution simulation
+neuroverse improve <world>              Actionable improvement suggestions
+neuroverse plan compile <plan.md>       Parse plan markdown into plan.json
+neuroverse plan check --plan plan.json  Check action against plan (stdin)
+neuroverse plan status --plan plan.json Show plan progress
+neuroverse plan advance <step_id>       Mark a step as completed
+neuroverse plan derive <plan.md>        Generate a full world from a plan
+neuroverse run --world <dir>            Governed runtime (pipe or interactive)
+neuroverse mcp --world <dir>            MCP governance server
+neuroverse trace --log <path>           Action audit log
+neuroverse impact --log <path>          Counterfactual impact report
+neuroverse world status|diff|snapshot|rollback  World management
+neuroverse worlds                       List available worlds
+neuroverse derive --input <path>        AI-assisted world synthesis
+neuroverse configure-ai                 Configure AI provider credentials
+```
+
+## Plan Markdown Format
+
+Plans are written in simple markdown that any LLM can produce:
+
+```markdown
+---
+plan_id: product_launch
+objective: Launch the NeuroVerse governance plugin
+sequential: false
+completion: verified
+---
+
+# Steps
+- Write announcement blog post [tag: content, marketing]
+- Publish GitHub release [tag: deploy] [verify: github_release_created]
+- Post on Product Hunt (after: publish_github_release) [tag: marketing]
+
+# Constraints
+- No spending above $500
+- All external posts require human review [type: approval]
+```
+
+### Completion modes
+
+- `completion: trust` (default) — caller says "done", step advances
+- `completion: verified` — steps with `[verify: ...]` require evidence to advance
+
+```javascript
+// Trust mode — just advance
+const result = advancePlan(plan, 'write_announcement_blog_post');
+// → { success: true, plan: <updated> }
+
+// Verified mode — evidence required for steps with verify
+const result = advancePlan(plan, 'publish_github_release', {
+  type: 'github_release_created',
+  proof: 'https://github.com/org/repo/releases/v1.0',
+});
+// → { success: true, plan: <updated>, evidence: { ... } }
+
+// Verified mode — missing evidence
+const result = advancePlan(plan, 'publish_github_release');
+// → { success: false, reason: 'Step requires evidence (verify: github_release_created)' }
+```
+
+## Governance Model
+
+```
+Safety checks  →  Plan enforcement  →  Role rules  →  Guards  →  Kernel
+(country laws)    (mom's trip rules)   (driving laws)  (domain)   (boundaries)
+```
+
+Plans are temporary guard overlays. They define task scope.
+Worlds are permanent governance. They define domain rules.
+Both layers must pass for an action to be allowed.
+
+## Evaluation Pipeline
+
+Every action passes through 6 phases:
+
+1. **Safety** — prompt injection, scope escape, data exfil detection (always on)
+2. **Plan** — is the action within the current mission scope?
+3. **Roles** — does the actor have permission?
+4. **Guards** — do domain-specific rules allow it?
+5. **Kernel** — does it violate LLM boundary rules?
+6. **Level** — does enforcement strictness allow it?
+
+First BLOCK wins. If nothing blocks, ALLOW.
+
+## Adapters
+
+### OpenAI
+
+```javascript
+import { createGovernedToolExecutor } from '@neuroverseos/governance/adapters/openai';
+
+const executor = await createGovernedToolExecutor('./world/', { trace: true, plan });
+const result = await executor.execute(toolCall, myToolRunner);
+// ALLOW → runs tool  |  BLOCK → returns blocked  |  PAUSE → throws
+```
+
+### LangChain
+
+```javascript
+import { createNeuroVerseCallbackHandler } from '@neuroverseos/governance/adapters/langchain';
+
+const handler = await createNeuroVerseCallbackHandler('./world/', {
+  plan,
+  onBlock: (verdict) => console.log('Blocked:', verdict.reason),
+});
+const agent = new AgentExecutor({ ..., callbacks: [handler] });
+```
+
+### OpenClaw
+
+```javascript
+import { createNeuroVersePlugin } from '@neuroverseos/governance/adapters/openclaw';
+
+const plugin = await createNeuroVersePlugin('./world/', { plan });
+agent.use(plugin.hooks());
+```
+
+### Express / Fastify
+
+```javascript
+import { createGovernanceMiddleware } from '@neuroverseos/governance/adapters/express';
+
+const middleware = await createGovernanceMiddleware('./world/', { level: 'strict' });
+app.use('/api', middleware);
+// Returns 403 on BLOCK
+```
+
+### MCP Server
+
+```bash
+neuroverse mcp --world ./world --plan plan.json
+```
+
+Exposes governed tools over Model Context Protocol. Works with Claude, Cursor, and any MCP client.
+
+## Exit Codes
+
+- 0 = ALLOW / ON_PLAN / SUCCESS
+- 1 = BLOCK / OFF_PLAN / FAIL
+- 2 = PAUSE / CONSTRAINT_VIOLATED
+- 3 = ERROR
+- 4 = PLAN_COMPLETE
+
+## Containment Testing
+
+```bash
+# Standard guard test suite (14 tests + optional fuzz)
+neuroverse test --world ./world --fuzz --count 50
+
+# Adversarial red team (28 attacks, 6 categories)
+neuroverse redteam --world ./world --level strict
+# → Containment score: 91%
+```
+
+Red team categories: prompt injection (8), tool escalation (4), scope escape (5), data exfiltration (3), identity manipulation (3), constraint bypass (3).

package/README.md

@@ -15,6 +15,14 @@ Deterministic. No LLM in the evaluation loop. Same event + same rules = same ver
 npm install @neuroverseos/governance
 ```
 
+### Quick test (no install required)
+
+```bash
+npx @neuroverseos/governance init
+npx @neuroverseos/governance build
+npx @neuroverseos/governance guard
+```
+
 ---
 
 ## The 5-Minute Demo
@@ -109,7 +117,7 @@ Returns ALLOW, BLOCK, or PAUSE. No network calls. No async. Pure function.
 
 ---
 
-## The "Oh Shit" Moment
+## The Moment Governance Matters
 
 Your AI agent decides to clean up the production database:
 
@@ -259,6 +267,47 @@ import { parsePlanMarkdown, evaluatePlan, advancePlan } from '@neuroverseos/gove
 const { plan } = parsePlanMarkdown(markdown);
 const verdict = evaluatePlan({ intent: 'write blog post' }, plan);
 // → { status: 'ON_PLAN', matchedStep: 'write_announcement_blog_post' }
+
+const result = advancePlan(plan, 'write_announcement_blog_post');
+// → { success: true, plan: <updated plan> }
+```
+
+### Completion modes
+
+Plans support two completion modes, set in frontmatter:
+
+**Trust** (default) — caller asserts "done", step advances:
+
+```markdown
+---
+plan_id: product_launch
+completion: trust
+---
+```
+
+**Verified** — steps with `[verify: ...]` require evidence to advance:
+
+```markdown
+---
+plan_id: product_launch
+completion: verified
+---
+
+# Steps
+- Write blog post [tag: content]
+- Publish GitHub release [verify: github_release_created]
+```
+
+Steps without `verify` still advance on trust, even in verified mode.
+
+```bash
+# Trust mode — just advance:
+neuroverse plan advance write_blog_post --plan plan.json
+
+# Verified mode — evidence required for steps with verify:
+neuroverse plan advance publish_github_release --plan plan.json \
+  --evidence github_release_created \
+  --proof "https://github.com/org/repo/releases/v1.0"
 ```
 
 ---
@@ -413,7 +462,7 @@ src/
   loader/
     world-loader.ts         # Load WorldDefinition from disk
 
-test/                       # 293 tests
+test/                       # 303 tests
 ```
 
 Zero runtime dependencies. Pure TypeScript. Node.js 18+.
@@ -432,8 +481,19 @@ Zero runtime dependencies. Pure TypeScript. Node.js 18+.
 
 This package includes machine-readable manifests for agent ecosystems:
 
-- **`AGENTS.md`** — Agent-discoverable integration guide
-- **`.well-known/ai-plugin.json`** — Standard capability manifest
+| File | Purpose | Who reads it |
+|------|---------|-------------|
+| **`AGENTS.md`** | Integration guide for coding agents | Claude Code, Cursor, Windsurf |
+| **`llms.txt`** | Package description for any LLM | Any LLM browsing the web or repo |
+| **`.well-known/ai-plugin.json`** | Capability manifest | ChatGPT plugins, OpenAI ecosystem |
+| **`.well-known/mcp.json`** | MCP server registry manifest | MCP clients, tool registries |
+| **`openapi.yaml`** | OpenAPI 3.1 spec for the HTTP API | AutoGPT, CrewAI, API-aware agents |
+
+### GitHub Topics
+
+Add these topics to the GitHub repo for search discovery:
+
+`ai-governance` `ai-safety` `mcp-server` `agent-guardrails` `deterministic` `plan-enforcement` `model-context-protocol` `ai-agents`
 
 ## License
 

package/dist/adapters/autoresearch.cjs

@@ -0,0 +1,196 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/autoresearch.ts
+var autoresearch_exports = {};
+__export(autoresearch_exports, {
+  AutoresearchGovernor: () => AutoresearchGovernor
+});
+module.exports = __toCommonJS(autoresearch_exports);
+var AutoresearchGovernor = class {
+  config;
+  state;
+  constructor(config) {
+    this.config = config;
+    this.state = {
+      experiments_run: 0,
+      best_result: null,
+      architectures_tested: [],
+      experiment_log: [],
+      total_compute_minutes: 0,
+      keep_count: 0
+    };
+  }
+  /**
+   * Convert an experiment proposal into a GuardEvent for governance evaluation.
+   */
+  proposalToGuardEvent(proposal) {
+    return {
+      intent: `run experiment: ${proposal.description}`,
+      tool: "experiment_runner",
+      scope: "experiment",
+      roleId: "experiment_runner",
+      direction: "output",
+      actionCategory: "shell",
+      args: {
+        experiment_id: String(proposal.experiment_id),
+        architecture: proposal.architecture,
+        estimated_minutes: String(proposal.estimated_minutes || 5)
+      }
+    };
+  }
+  /**
+   * Evaluate an experiment proposal against governance rules.
+   * Returns a simplified verdict without requiring the full guard engine.
+   */
+  evaluateProposal(proposal) {
+    const warnings = [];
+    const estimatedMinutes = proposal.estimated_minutes || 5;
+    if (this.state.total_compute_minutes + estimatedMinutes > this.config.computeBudgetMinutes) {
+      return {
+        allowed: false,
+        reason: `Compute budget exhausted: ${this.state.total_compute_minutes}/${this.config.computeBudgetMinutes} minutes used`,
+        warnings
+      };
+    }
+    if (this.config.constraints) {
+      for (const constraint of this.config.constraints) {
+        const lower = constraint.toLowerCase();
+        const archLower = proposal.architecture.toLowerCase();
+        const descLower = proposal.description.toLowerCase();
+        if (lower.startsWith("no ")) {
+          const forbidden = lower.slice(3).trim();
+          if (archLower.includes(forbidden) || descLower.includes(forbidden)) {
+            return {
+              allowed: false,
+              reason: `Architecture constraint violated: ${constraint}`,
+              warnings
+            };
+          }
+        }
+      }
+    }
+    const failureCount = this.state.experiment_log.filter((e) => !e.success).length;
+    if (failureCount > 5) {
+      warnings.push(`High failure rate: ${failureCount} failed experiments. Consider investigating root cause.`);
+    }
+    const recentArchitectures = this.state.experiment_log.slice(-5).map((e) => e.architecture);
+    const uniqueRecent = new Set(recentArchitectures).size;
+    if (recentArchitectures.length >= 5 && uniqueRecent === 1) {
+      warnings.push("Research may be stuck: last 5 experiments used the same architecture.");
+    }
+    return { allowed: true, reason: "Experiment approved", warnings };
+  }
+  /**
+   * Record an experiment result and update research state.
+   */
+  recordResult(result) {
+    this.state.experiments_run++;
+    this.state.total_compute_minutes += result.wall_clock_minutes;
+    this.state.experiment_log.push(result);
+    if (!this.state.architectures_tested.includes(result.architecture)) {
+      this.state.architectures_tested.push(result.architecture);
+    }
+    if (!result.success) {
+      return { kept: false, improvement: null, state: { ...this.state } };
+    }
+    let kept = false;
+    let improvement = null;
+    if (this.state.best_result === null) {
+      kept = true;
+      this.state.best_result = result;
+      this.state.keep_count++;
+    } else {
+      const prev = this.state.best_result.metric_value;
+      const curr = result.metric_value;
+      if (this.config.optimize === "minimize") {
+        kept = curr < prev;
+        improvement = kept ? prev - curr : null;
+      } else {
+        kept = curr > prev;
+        improvement = kept ? curr - prev : null;
+      }
+      if (kept) {
+        this.state.best_result = result;
+        this.state.keep_count++;
+      }
+    }
+    return { kept, improvement, state: { ...this.state } };
+  }
+  /**
+   * Export current state as a state snapshot compatible with the world file.
+   */
+  toWorldState() {
+    const successfulExperiments = this.state.experiment_log.filter((e) => e.success);
+    const failedCount = this.state.experiment_log.filter((e) => !e.success).length;
+    const keepRate = this.state.experiments_run > 0 ? Math.round(this.state.keep_count / this.state.experiments_run * 100) : 0;
+    let improvementRate = 0;
+    if (successfulExperiments.length >= 2) {
+      const recent = successfulExperiments.slice(-10);
+      let improvements = 0;
+      for (let i = 1; i < recent.length; i++) {
+        const prev = recent[i - 1].metric_value;
+        const curr = recent[i].metric_value;
+        if (this.config.optimize === "minimize" ? curr < prev : curr > prev) {
+          improvements++;
+        }
+      }
+      improvementRate = Math.round(improvements / (recent.length - 1) * 100);
+    }
+    return {
+      experiments_run: this.state.experiments_run,
+      best_metric_value: this.state.best_result?.metric_value ?? (this.config.optimize === "minimize" ? 100 : -1e3),
+      keep_rate: keepRate,
+      compute_used_minutes: Math.round(this.state.total_compute_minutes),
+      compute_budget_minutes: this.config.computeBudgetMinutes,
+      failed_experiments: failedCount,
+      metric_improvement_rate: improvementRate,
+      research_context_drift: 0
+      // would need NLP to compute properly
+    };
+  }
+  /**
+   * Get a summary of the current research state.
+   */
+  getSummary() {
+    return {
+      experiments_run: this.state.experiments_run,
+      best_result: this.state.best_result,
+      keep_rate: this.state.experiments_run > 0 ? Math.round(this.state.keep_count / this.state.experiments_run * 100) : 0,
+      compute_remaining_minutes: this.config.computeBudgetMinutes - this.state.total_compute_minutes,
+      architectures_tested: [...this.state.architectures_tested]
+    };
+  }
+  /**
+   * Load state from a persisted research context file.
+   */
+  loadState(state) {
+    this.state = { ...state };
+  }
+  /**
+   * Export state for persistence.
+   */
+  exportState() {
+    return { ...this.state };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AutoresearchGovernor
+});