@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/adapters/openclaw.d.cts

@@ -0,0 +1,99 @@
+import { a as GuardVerdict, b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, G as GuardEvent, c as PlanProgress } from '../guard-contract-DqFcTScd.cjs';
+import { G as GovernanceBlockedError$1 } from '../shared-B8dvUUD8.cjs';
+
+/**
+ * NeuroVerse Adapter — OpenClaw
+ *
+ * Integrates NeuroVerse governance as an OpenClaw plugin.
+ * Provides pre-action and post-action governance hooks that
+ * evaluate agent actions against a world definition.
+ *
+ * Usage:
+ *   import { createNeuroVersePlugin } from 'neuroverse-governance/adapters/openclaw';
+ *
+ *   const plugin = await createNeuroVersePlugin('./world/');
+ *   agent.use(plugin);
+ */
+
+/** Generic agent action shape (OpenClaw-compatible). */
+interface AgentAction {
+    type: string;
+    tool?: string;
+    input?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/** Plugin hook result. */
+interface HookResult {
+    allowed: boolean;
+    verdict: GuardVerdict;
+    action: AgentAction;
+}
+interface NeuroVersePluginOptions {
+    /** Include full evaluation trace. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called for every evaluation. */
+    onEvaluate?: (result: HookResult) => void;
+    /** Custom action → GuardEvent mapping. */
+    mapAction?: (action: AgentAction, direction: 'input' | 'output') => GuardEvent;
+    /** Whether to evaluate output actions (post-action). Default: false. */
+    evaluateOutputs?: boolean;
+    /** Active plan overlay for task-scoped governance. */
+    plan?: PlanDefinition;
+    /** Called when plan progress changes. */
+    onPlanProgress?: (progress: PlanProgress) => void;
+    /** Called when all plan steps are completed. */
+    onPlanComplete?: () => void;
+}
+declare class GovernanceBlockedError extends GovernanceBlockedError$1 {
+    readonly action: AgentAction;
+    constructor(verdict: GuardVerdict, action: AgentAction);
+}
+/**
+ * NeuroVerse governance plugin for OpenClaw agents.
+ *
+ * Provides two hooks:
+ * - beforeAction: evaluates before the agent executes an action
+ * - afterAction: optionally evaluates outputs for post-action governance
+ */
+declare class NeuroVersePlugin {
+    readonly name = "neuroverse-governance";
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapAction;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: NeuroVersePluginOptions);
+    /**
+     * Evaluate an action before execution.
+     *
+     * @throws GovernanceBlockedError if BLOCKED
+     * @returns HookResult with verdict details
+     */
+    beforeAction(action: AgentAction): HookResult;
+    /**
+     * Evaluate an action's output (post-execution governance).
+     * Only runs if evaluateOutputs is enabled.
+     *
+     * @returns HookResult or null if output evaluation is disabled
+     */
+    afterAction(action: AgentAction, _output?: unknown): HookResult | null;
+    /**
+     * Get the plugin hooks object for agent.use().
+     */
+    hooks(): {
+        beforeAction: (action: AgentAction) => HookResult;
+        afterAction: (action: AgentAction, output?: unknown) => HookResult | null;
+    };
+}
+/**
+ * Create a NeuroVerse plugin from a world path.
+ */
+declare function createNeuroVersePlugin(worldPath: string, options?: NeuroVersePluginOptions): Promise<NeuroVersePlugin>;
+/**
+ * Create a NeuroVerse plugin from a pre-loaded world.
+ */
+declare function createNeuroVersePluginFromWorld(world: WorldDefinition, options?: NeuroVersePluginOptions): NeuroVersePlugin;
+
+export { type AgentAction, GovernanceBlockedError, type HookResult, NeuroVersePlugin, type NeuroVersePluginOptions, createNeuroVersePlugin, createNeuroVersePluginFromWorld };

package/dist/adapters/openclaw.d.ts

@@ -0,0 +1,99 @@
+import { a as GuardVerdict, b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, G as GuardEvent, c as PlanProgress } from '../guard-contract-DqFcTScd.js';
+import { G as GovernanceBlockedError$1 } from '../shared-Dr5Wiay8.js';
+
+/**
+ * NeuroVerse Adapter — OpenClaw
+ *
+ * Integrates NeuroVerse governance as an OpenClaw plugin.
+ * Provides pre-action and post-action governance hooks that
+ * evaluate agent actions against a world definition.
+ *
+ * Usage:
+ *   import { createNeuroVersePlugin } from 'neuroverse-governance/adapters/openclaw';
+ *
+ *   const plugin = await createNeuroVersePlugin('./world/');
+ *   agent.use(plugin);
+ */
+
+/** Generic agent action shape (OpenClaw-compatible). */
+interface AgentAction {
+    type: string;
+    tool?: string;
+    input?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/** Plugin hook result. */
+interface HookResult {
+    allowed: boolean;
+    verdict: GuardVerdict;
+    action: AgentAction;
+}
+interface NeuroVersePluginOptions {
+    /** Include full evaluation trace. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called for every evaluation. */
+    onEvaluate?: (result: HookResult) => void;
+    /** Custom action → GuardEvent mapping. */
+    mapAction?: (action: AgentAction, direction: 'input' | 'output') => GuardEvent;
+    /** Whether to evaluate output actions (post-action). Default: false. */
+    evaluateOutputs?: boolean;
+    /** Active plan overlay for task-scoped governance. */
+    plan?: PlanDefinition;
+    /** Called when plan progress changes. */
+    onPlanProgress?: (progress: PlanProgress) => void;
+    /** Called when all plan steps are completed. */
+    onPlanComplete?: () => void;
+}
+declare class GovernanceBlockedError extends GovernanceBlockedError$1 {
+    readonly action: AgentAction;
+    constructor(verdict: GuardVerdict, action: AgentAction);
+}
+/**
+ * NeuroVerse governance plugin for OpenClaw agents.
+ *
+ * Provides two hooks:
+ * - beforeAction: evaluates before the agent executes an action
+ * - afterAction: optionally evaluates outputs for post-action governance
+ */
+declare class NeuroVersePlugin {
+    readonly name = "neuroverse-governance";
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapAction;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: NeuroVersePluginOptions);
+    /**
+     * Evaluate an action before execution.
+     *
+     * @throws GovernanceBlockedError if BLOCKED
+     * @returns HookResult with verdict details
+     */
+    beforeAction(action: AgentAction): HookResult;
+    /**
+     * Evaluate an action's output (post-execution governance).
+     * Only runs if evaluateOutputs is enabled.
+     *
+     * @returns HookResult or null if output evaluation is disabled
+     */
+    afterAction(action: AgentAction, _output?: unknown): HookResult | null;
+    /**
+     * Get the plugin hooks object for agent.use().
+     */
+    hooks(): {
+        beforeAction: (action: AgentAction) => HookResult;
+        afterAction: (action: AgentAction, output?: unknown) => HookResult | null;
+    };
+}
+/**
+ * Create a NeuroVerse plugin from a world path.
+ */
+declare function createNeuroVersePlugin(worldPath: string, options?: NeuroVersePluginOptions): Promise<NeuroVersePlugin>;
+/**
+ * Create a NeuroVerse plugin from a pre-loaded world.
+ */
+declare function createNeuroVersePluginFromWorld(world: WorldDefinition, options?: NeuroVersePluginOptions): NeuroVersePlugin;
+
+export { type AgentAction, GovernanceBlockedError, type HookResult, NeuroVersePlugin, type NeuroVersePluginOptions, createNeuroVersePlugin, createNeuroVersePluginFromWorld };

package/dist/adapters/openclaw.js

@@ -0,0 +1,17 @@
+import {
+  GovernanceBlockedError,
+  NeuroVersePlugin,
+  createNeuroVersePlugin,
+  createNeuroVersePluginFromWorld
+} from "../chunk-BNKJPUPQ.js";
+import "../chunk-5U2MQO5P.js";
+import "../chunk-W7LLXRGY.js";
+import "../chunk-QLPTHTVB.js";
+import "../chunk-CTZHONLA.js";
+import "../chunk-QWGCMQQD.js";
+export {
+  GovernanceBlockedError,
+  NeuroVersePlugin,
+  createNeuroVersePlugin,
+  createNeuroVersePluginFromWorld
+};

package/dist/add-ROOZLU62.js

@@ -0,0 +1,314 @@
+import {
+  addGuard,
+  addInvariant,
+  addRule,
+  classifyIntent,
+  parseGuardDescription
+} from "./chunk-5TPFNWRU.js";
+import "./chunk-7P3S7MAY.js";
+import {
+  describeActiveWorld,
+  resolveWorldPath
+} from "./chunk-AKW5YVCE.js";
+import "./chunk-QWGCMQQD.js";
+
+// src/cli/add.ts
+function parseTriggerExpr(expr) {
+  const match = expr.match(/^(\S+)\s*(==|!=|>=|<=|>|<|in)\s*(.+?)(?:\s*\[(state|assumption)\])?\s*$/);
+  if (!match) {
+    throw new Error(`Invalid trigger expression: "${expr}". Expected: "field op value [state|assumption]"`);
+  }
+  const [, field, operator, rawValue, source] = match;
+  let value = rawValue.trim();
+  const num = Number(value);
+  if (!isNaN(num) && value !== "") value = num;
+  else if (value === "true") value = true;
+  else if (value === "false") value = false;
+  else if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    value = value.slice(1, -1);
+  }
+  return {
+    field,
+    operator,
+    value,
+    source: source ?? "state"
+  };
+}
+function parseEffectExpr(expr) {
+  const match = expr.match(/^(\S+)\s*(\*=|\+=|-=|=)\s*(.+)\s*$/);
+  if (!match) {
+    throw new Error(`Invalid effect expression: "${expr}". Expected: "target op value" (e.g., "viability *= 0.5")`);
+  }
+  const [, target, op, rawValue] = match;
+  const operationMap = {
+    "*=": "multiply",
+    "+=": "add",
+    "-=": "subtract",
+    "=": "set"
+  };
+  let value = rawValue.trim();
+  const num = Number(value);
+  if (!isNaN(num) && value !== "") value = num;
+  else if (value === "true") value = true;
+  else if (value === "false") value = false;
+  return {
+    target,
+    operation: operationMap[op],
+    value
+  };
+}
+function parseArgs(argv) {
+  const args = {
+    subcommand: "auto",
+    worldPath: "",
+    label: "",
+    json: false,
+    patterns: [],
+    appliesTo: [],
+    triggers: [],
+    effects: []
+  };
+  if (argv.length === 0) {
+    throw new Error('Usage: neuroverse add <guard|rule|invariant|"description"> --world <path>');
+  }
+  const first = argv[0];
+  if (first === "guard" || first === "rule" || first === "invariant") {
+    args.subcommand = first;
+    argv = argv.slice(1);
+  } else if (!first.startsWith("--")) {
+    args.subcommand = "auto";
+    args.rawText = first;
+    argv = argv.slice(1);
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--world":
+        args.worldPath = argv[++i];
+        break;
+      case "--label":
+        args.label = argv[++i];
+        break;
+      case "--id":
+        args.id = argv[++i];
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      case "--enforcement":
+        args.enforcement = argv[++i];
+        break;
+      case "--pattern":
+        args.patterns.push(argv[++i]);
+        break;
+      case "--category":
+        args.category = argv[++i];
+        break;
+      case "--applies-to":
+        args.appliesTo.push(argv[++i]);
+        break;
+      case "--severity":
+        args.severity = argv[++i];
+        break;
+      case "--trigger":
+        args.triggers.push(argv[++i]);
+        break;
+      case "--effect":
+        args.effects.push(argv[++i]);
+        break;
+      case "--description":
+        args.description = argv[++i];
+        break;
+      case "--help":
+      case "-h":
+        printUsage();
+        process.exit(0);
+        break;
+      default:
+        if (!arg.startsWith("--") && args.subcommand === "auto" && !args.rawText) {
+          args.rawText = arg;
+        }
+    }
+  }
+  return args;
+}
+function printUsage() {
+  process.stdout.write(`
+neuroverse add \u2014 Incremental governance authoring
+
+Usage:
+  neuroverse add "Block dairy orders" --world ./world/
+  neuroverse add guard --world ./world/ --label "Block dairy orders" --pattern "*dairy*"
+  neuroverse add rule --world ./world/ --label "Cost overrun" --severity degradation --trigger "cost > 100" --effect "viability *= 0.5"
+  neuroverse add invariant --world ./world/ --label "Budget must never exceed 1000"
+
+Auto mode:
+  Pass a quoted description as the first argument. The engine classifies it
+  as a guard, rule, or invariant based on the language used.
+
+  "Block ..."  / "Prevent ..."  / "Deny ..."     \u2192 guard
+  "If ... then ..."  / "When ... reduce ..."      \u2192 rule
+  "... must always ..."  / "... must never ..."   \u2192 invariant
+
+Flags:
+  --world <path>       World directory (required)
+  --id <id>            Explicit ID (auto-generated if omitted)
+  --json               Full JSON output
+
+Guard:
+  --enforcement <type>   block | pause | warn (default: block)
+  --pattern <glob>       Intent pattern (repeatable)
+  --category <cat>       structural | operational | advisory
+
+Rule:
+  --severity <level>     structural | degradation | advantage
+  --trigger <expr>       "field op value [state|assumption]" (repeatable)
+  --effect <expr>        "target op value" e.g. "viability *= 0.5" (repeatable)
+  --description <text>
+
+Invariant:
+  --enforcement <type>   structural | prompt (default: structural)
+`.trimStart());
+}
+async function main(argv = process.argv.slice(2)) {
+  try {
+    const args = parseArgs(argv);
+    const worldPath = resolveWorldPath(args.worldPath);
+    if (!worldPath) {
+      throw new Error(
+        "No world specified. Use --world <path>, set NEUROVERSE_WORLD, or run `neuroverse world use <name>`"
+      );
+    }
+    const worldInfo = describeActiveWorld(args.worldPath);
+    if (worldInfo) {
+      process.stderr.write(`Using world: ${worldInfo.name}
+`);
+    }
+    let result;
+    if (args.subcommand === "auto") {
+      const text = args.rawText ?? args.label;
+      if (!text) {
+        throw new Error('Provide a description: neuroverse add "Block dairy orders" --world ./world/');
+      }
+      const type = classifyIntent(text);
+      switch (type) {
+        case "guard": {
+          const input = parseGuardDescription(text);
+          if (args.id) input.id = args.id;
+          process.stderr.write(`Classified as: guard (${input.enforcement})
+`);
+          result = await addGuard(worldPath, input);
+          break;
+        }
+        case "invariant": {
+          process.stderr.write(`Classified as: invariant
+`);
+          result = await addInvariant(worldPath, {
+            label: text,
+            id: args.id
+          });
+          break;
+        }
+        case "rule":
+        case "ambiguous": {
+          if (type === "ambiguous") {
+            process.stderr.write(`Could not auto-classify. Defaulting to guard.
+`);
+            process.stderr.write(`Tip: use "neuroverse add guard|rule|invariant" for explicit control.
+`);
+          } else {
+            process.stderr.write(`Classified as: rule
+`);
+            process.stderr.write(`Note: auto-mode creates a minimal rule. Use explicit "neuroverse add rule" with --trigger and --effect for full control.
+`);
+          }
+          const input = parseGuardDescription(text);
+          if (args.id) input.id = args.id;
+          result = await addGuard(worldPath, input);
+          break;
+        }
+        default:
+          throw new Error(`Unexpected classification: ${type}`);
+      }
+    } else if (args.subcommand === "guard") {
+      const label = args.label;
+      if (!label) throw new Error("--label is required for guard");
+      const input = {
+        label,
+        enforcement: args.enforcement ?? "block",
+        intentPatterns: args.patterns.length > 0 ? args.patterns : [`*${label.toLowerCase().replace(/\s+/g, "*")}*`],
+        description: args.description,
+        category: args.category,
+        appliesTo: args.appliesTo.length > 0 ? args.appliesTo : void 0,
+        id: args.id
+      };
+      result = await addGuard(worldPath, input);
+    } else if (args.subcommand === "rule") {
+      const label = args.label;
+      if (!label) throw new Error("--label is required for rule");
+      if (args.triggers.length === 0) throw new Error("At least one --trigger is required for rule");
+      const input = {
+        label,
+        severity: args.severity ?? "degradation",
+        description: args.description,
+        triggers: args.triggers.map(parseTriggerExpr),
+        effects: args.effects.length > 0 ? args.effects.map(parseEffectExpr) : void 0,
+        id: args.id
+      };
+      result = await addRule(worldPath, input);
+    } else if (args.subcommand === "invariant") {
+      const label = args.label;
+      if (!label) throw new Error("--label is required for invariant");
+      result = await addInvariant(worldPath, {
+        label,
+        enforcement: args.enforcement ?? "structural",
+        id: args.id
+      });
+    } else {
+      throw new Error(`Unknown subcommand: ${args.subcommand}`);
+    }
+    if (args.json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      const icon = result.type === "guard" ? "GUARD" : result.type === "rule" ? "RULE" : "INVARIANT";
+      process.stdout.write(`
+[${icon}] Added: ${result.id}
+`);
+      process.stdout.write(`  File: ${result.file}
+`);
+      process.stdout.write(`  Valid: ${result.valid ? "yes" : "no"}
+`);
+      const errors = result.findings.filter((f) => f.severity === "error");
+      const warnings = result.findings.filter((f) => f.severity === "warning");
+      if (errors.length > 0) {
+        process.stdout.write(`  Errors: ${errors.length}
+`);
+        for (const e of errors.slice(0, 3)) {
+          process.stdout.write(`    - ${e.message}
+`);
+        }
+      }
+      if (warnings.length > 0) {
+        process.stdout.write(`  Warnings: ${warnings.length}
+`);
+        for (const w of warnings.slice(0, 3)) {
+          process.stdout.write(`    - ${w.message}
+`);
+        }
+      }
+      if (result.valid && errors.length === 0) {
+        process.stdout.write(`
+Ready. Guard will be enforced on next evaluation.
+`);
+      }
+    }
+    process.exit(result.valid ? 0 : 1);
+  } catch (e) {
+    process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}
+`);
+    process.exit(3);
+  }
+}
+export {
+  main
+};

package/dist/behavioral-MJO34S6Q.js

@@ -0,0 +1,118 @@
+import {
+  adaptationFromVerdict,
+  detectBehavioralPatterns,
+  generateAdaptationNarrative
+} from "./chunk-CNSO6XW5.js";
+import {
+  readAuditLog
+} from "./chunk-A7GKPPU7.js";
+import "./chunk-W7LLXRGY.js";
+import "./chunk-QLPTHTVB.js";
+import "./chunk-QWGCMQQD.js";
+
+// src/cli/behavioral.ts
+var USAGE = `
+neuroverse behavioral \u2014 Behavioral analysis from audit log
+
+Usage:
+  neuroverse behavioral [options]
+
+Options:
+  --log <path>   Path to audit log (default: .neuroverse/audit.ndjson)
+  --json         Raw JSON output
+
+Classifies agent adaptations, detects network-level patterns
+(coordinated silence, misinfo suppression, reward cascades),
+and generates a human-readable narrative.
+`.trim();
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") args.json = true;
+    else if (arg === "--help" || arg === "-h") args.help = true;
+    else if (arg === "--log" && argv[i + 1]) args.log = argv[++i];
+  }
+  return args;
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(USAGE + "\n");
+    process.exit(0);
+  }
+  const logPath = args.log ?? ".neuroverse/audit.ndjson";
+  const events = await readAuditLog(logPath);
+  if (events.length === 0) {
+    process.stderr.write(`No audit events found in ${logPath}
+`);
+    process.stderr.write("Run governance evaluations with audit logging enabled to generate events.\n");
+    process.exit(0);
+  }
+  const adaptations = events.map((event) => {
+    const agentId = event.actor ?? "unknown";
+    const intended = event.intent;
+    const executed = event.decision === "BLOCK" ? "idle" : intended;
+    const verdict = {
+      status: event.decision,
+      reason: event.reason,
+      ruleId: event.ruleId,
+      evidence: { worldId: event.worldId, worldName: event.worldName, worldVersion: event.worldVersion, evaluatedAt: Date.now(), invariantsSatisfied: 0, invariantsTotal: 0, guardsMatched: [], rulesMatched: [], enforcementLevel: "standard" }
+    };
+    return adaptationFromVerdict(agentId, intended, executed, verdict);
+  });
+  const uniqueAgents = new Set(adaptations.map((a) => a.agentId)).size;
+  const patterns = detectBehavioralPatterns(adaptations, uniqueAgents);
+  const narrative = generateAdaptationNarrative(patterns);
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ adaptations: adaptations.length, agents: uniqueAgents, patterns, narrative }, null, 2) + "\n");
+  } else {
+    process.stdout.write("\nBehavioral Analysis\n");
+    process.stdout.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n");
+    process.stdout.write(`  Events analyzed:  ${events.length}
+`);
+    process.stdout.write(`  Agents observed:  ${uniqueAgents}
+`);
+    process.stdout.write(`  Adaptations:      ${adaptations.length}
+`);
+    process.stdout.write(`  Patterns found:   ${patterns.length}
+
+`);
+    if (patterns.length > 0) {
+      process.stdout.write("Patterns Detected\n");
+      process.stdout.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+      for (const p of patterns) {
+        process.stdout.write(`  ${p.type} (${p.agentsAffected} agents)
+`);
+        process.stdout.write(`    ${p.description}
+
+`);
+      }
+    }
+    if (narrative) {
+      process.stdout.write("Narrative\n");
+      process.stdout.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+      process.stdout.write(`  ${narrative}
+
+`);
+    }
+    const shiftCounts = {};
+    for (const a of adaptations) {
+      const key = a.shiftType ?? `${a.intendedAction}\u2192${a.executedAction}`;
+      shiftCounts[key] = (shiftCounts[key] ?? 0) + 1;
+    }
+    const sortedShifts = Object.entries(shiftCounts).sort((a, b) => b[1] - a[1]);
+    if (sortedShifts.length > 0) {
+      process.stdout.write("Shift Breakdown\n");
+      process.stdout.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+      for (const [shift, count] of sortedShifts.slice(0, 10)) {
+        process.stdout.write(`  ${shift}: ${count}
+`);
+      }
+      process.stdout.write("\n");
+    }
+  }
+}
+export {
+  main
+};