@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/chunk-IS4WUH6Y.js

@@ -0,0 +1,363 @@
+import {
+  applyConsequence,
+  applyReward,
+  createAgentState,
+  tickAgentStates
+} from "./chunk-D2UCV5AK.js";
+import {
+  evaluateGuard
+} from "./chunk-W7LLXRGY.js";
+import {
+  advancePlan,
+  evaluatePlan,
+  getPlanProgress
+} from "./chunk-QLPTHTVB.js";
+import {
+  loadWorld
+} from "./chunk-CTZHONLA.js";
+
+// src/runtime/session.ts
+async function defaultToolExecutor(name, args) {
+  return `Tool "${name}" executed successfully with args: ${JSON.stringify(args)}`;
+}
+var SessionManager = class {
+  config;
+  state;
+  engineOptions;
+  executor;
+  constructor(config) {
+    this.config = config;
+    this.executor = config.toolExecutor ?? defaultToolExecutor;
+    this.engineOptions = {
+      trace: config.trace ?? false,
+      level: config.level,
+      plan: config.plan
+    };
+    this.state = {
+      active: false,
+      world: config.world,
+      plan: config.plan,
+      progress: config.plan ? getPlanProgress(config.plan) : void 0,
+      actionsEvaluated: 0,
+      actionsAllowed: 0,
+      actionsBlocked: 0,
+      actionsPaused: 0,
+      actionsModified: 0,
+      actionsPenalized: 0,
+      actionsRewarded: 0,
+      agentStates: /* @__PURE__ */ new Map()
+    };
+  }
+  /**
+   * Initialize the session — load world from disk if needed.
+   */
+  async start() {
+    if (this.config.worldPath && !this.config.world) {
+      this.state.world = await loadWorld(this.config.worldPath);
+    }
+    if (!this.state.world) {
+      throw new Error("No world provided. Use --world or pass a world definition.");
+    }
+    this.state.active = true;
+    return this.getState();
+  }
+  /**
+   * Evaluate a single event against governance.
+   * Returns the verdict without executing anything.
+   */
+  evaluate(event) {
+    this.engineOptions.plan = this.state.plan;
+    this.engineOptions.agentStates = this.state.agentStates;
+    const verdict = evaluateGuard(event, this.state.world, this.engineOptions);
+    this.state.actionsEvaluated++;
+    if (verdict.status === "ALLOW") this.state.actionsAllowed++;
+    if (verdict.status === "BLOCK") this.state.actionsBlocked++;
+    if (verdict.status === "PAUSE") this.state.actionsPaused++;
+    if (verdict.status === "MODIFY") this.state.actionsModified++;
+    if (verdict.status === "PENALIZE") this.state.actionsPenalized++;
+    if (verdict.status === "REWARD") this.state.actionsRewarded++;
+    if (event.roleId) {
+      let agentState = this.state.agentStates.get(event.roleId) ?? createAgentState(event.roleId);
+      if (verdict.status === "PENALIZE" && verdict.consequence) {
+        agentState = applyConsequence(agentState, verdict.consequence, verdict.ruleId ?? "unknown");
+      }
+      if (verdict.status === "REWARD" && verdict.reward) {
+        agentState = applyReward(agentState, verdict.reward, verdict.ruleId ?? "unknown");
+      }
+      this.state.agentStates.set(event.roleId, agentState);
+    }
+    this.config.onVerdict?.(verdict, event);
+    return verdict;
+  }
+  /**
+   * Advance all agent states by one round.
+   * Call this at the end of each simulation round to decrement cooldowns.
+   */
+  tickRound() {
+    this.state.agentStates = tickAgentStates(this.state.agentStates);
+  }
+  /**
+   * Get the behavior state for a specific agent.
+   */
+  getAgentState(agentId) {
+    return this.state.agentStates.get(agentId);
+  }
+  /**
+   * Evaluate and execute a tool call.
+   * Returns the execution result or block reason.
+   */
+  async executeToolCall(toolCall) {
+    let args;
+    try {
+      args = JSON.parse(toolCall.function.arguments);
+    } catch {
+      args = { raw: toolCall.function.arguments };
+    }
+    const event = {
+      intent: toolCall.function.name,
+      tool: toolCall.function.name,
+      args,
+      direction: "input"
+    };
+    const verdict = this.evaluate(event);
+    if (verdict.status === "BLOCK" || verdict.status === "PENALIZE") {
+      return { allowed: false, verdict };
+    }
+    if (verdict.status === "PAUSE") {
+      return { allowed: false, verdict };
+    }
+    const result = await this.executor(toolCall.function.name, args);
+    this.config.onToolResult?.(toolCall.function.name, result);
+    if (this.state.plan) {
+      const planVerdict = evaluatePlan(event, this.state.plan);
+      if (planVerdict.matchedStep) {
+        const advResult = advancePlan(this.state.plan, planVerdict.matchedStep);
+        if (advResult.success && advResult.plan) {
+          this.state.plan = advResult.plan;
+          this.engineOptions.plan = this.state.plan;
+        }
+        this.state.progress = getPlanProgress(this.state.plan);
+        this.config.onPlanProgress?.(this.state.progress);
+        if (this.state.progress.completed === this.state.progress.total) {
+          this.config.onPlanComplete?.();
+        }
+      }
+    }
+    return { allowed: true, verdict, result };
+  }
+  /**
+   * Process a model response — evaluate and execute all tool calls.
+   * Returns results for each tool call.
+   */
+  async processModelResponse(response, model) {
+    if (response.toolCalls.length === 0) {
+      return response;
+    }
+    for (const toolCall of response.toolCalls) {
+      const { allowed, verdict, result } = await this.executeToolCall(toolCall);
+      if (allowed && result) {
+        const nextResponse = await model.sendToolResult(toolCall.id, result);
+        if (nextResponse.toolCalls.length > 0) {
+          return this.processModelResponse(nextResponse, model);
+        }
+        return nextResponse;
+      } else {
+        const reason = verdict.reason ?? "Action blocked by governance.";
+        const nextResponse = await model.sendBlockedResult(toolCall.id, reason);
+        if (nextResponse.toolCalls.length > 0) {
+          return this.processModelResponse(nextResponse, model);
+        }
+        return nextResponse;
+      }
+    }
+    return response;
+  }
+  /** Get current session state. */
+  getState() {
+    return { ...this.state };
+  }
+  /** Stop the session. */
+  stop() {
+    this.state.active = false;
+    return this.getState();
+  }
+};
+async function runPipeMode(config) {
+  const session = new SessionManager(config);
+  await session.start();
+  const state = session.getState();
+  process.stderr.write(`[neuroverse] Pipe mode active
+`);
+  process.stderr.write(`[neuroverse] World: ${state.world.world.name}
+`);
+  if (state.plan) {
+    process.stderr.write(`[neuroverse] Plan: ${state.plan.plan_id} (${state.plan.objective})
+`);
+  }
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const event = JSON.parse(trimmed);
+          if (!event.intent) {
+            process.stderr.write(`[neuroverse] Warning: event missing "intent" field
+`);
+            continue;
+          }
+          const verdict = session.evaluate(event);
+          process.stdout.write(JSON.stringify(verdict) + "\n");
+        } catch (err) {
+          process.stderr.write(`[neuroverse] Error parsing line: ${err}
+`);
+        }
+      }
+    });
+    process.stdin.on("end", () => {
+      if (buffer.trim()) {
+        try {
+          const event = JSON.parse(buffer.trim());
+          if (event.intent) {
+            const verdict = session.evaluate(event);
+            process.stdout.write(JSON.stringify(verdict) + "\n");
+          }
+        } catch {
+        }
+      }
+      const finalState = session.stop();
+      process.stderr.write(
+        `[neuroverse] Session complete: ${finalState.actionsEvaluated} evaluated, ${finalState.actionsAllowed} allowed, ${finalState.actionsBlocked} blocked, ${finalState.actionsPaused} paused
+`
+      );
+      resolve();
+    });
+    process.stdin.on("error", reject);
+  });
+}
+async function runInteractiveMode(config, model) {
+  const session = new SessionManager(config);
+  await session.start();
+  const state = session.getState();
+  process.stdout.write("\n");
+  process.stdout.write(`  World: ${state.world.world.name}
+`);
+  if (state.plan) {
+    process.stdout.write(`  Plan: ${state.plan.plan_id}
+`);
+    process.stdout.write(`  Goal: ${state.plan.objective}
+`);
+    process.stdout.write(`  Steps: ${state.progress?.total ?? 0}
+`);
+  }
+  process.stdout.write(`  Type "exit" to end session.
+`);
+  process.stdout.write("\n");
+  const readline = await import("readline");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: "> "
+  });
+  const printProgress = () => {
+    const s = session.getState();
+    if (s.progress) {
+      process.stdout.write(
+        `  [plan: ${s.progress.completed}/${s.progress.total} (${s.progress.percentage}%)]
+`
+      );
+    }
+  };
+  rl.prompt();
+  rl.on("line", async (input) => {
+    const trimmed = input.trim();
+    if (!trimmed) {
+      rl.prompt();
+      return;
+    }
+    if (trimmed === "exit" || trimmed === "quit") {
+      const finalState = session.stop();
+      process.stdout.write("\n");
+      process.stdout.write(`  Session complete.
+`);
+      process.stdout.write(`  Actions: ${finalState.actionsEvaluated} evaluated`);
+      process.stdout.write(`, ${finalState.actionsAllowed} allowed`);
+      process.stdout.write(`, ${finalState.actionsBlocked} blocked
+`);
+      if (finalState.progress) {
+        process.stdout.write(
+          `  Plan: ${finalState.progress.completed}/${finalState.progress.total} steps completed
+`
+        );
+      }
+      process.stdout.write("\n");
+      rl.close();
+      return;
+    }
+    if (trimmed === "status") {
+      const s = session.getState();
+      process.stdout.write(`
+  World: ${s.world.world.name}
+`);
+      process.stdout.write(`  Actions: ${s.actionsEvaluated} evaluated
+`);
+      process.stdout.write(`  Allowed: ${s.actionsAllowed} | Blocked: ${s.actionsBlocked} | Modified: ${s.actionsModified} | Paused: ${s.actionsPaused}
+`);
+      process.stdout.write(`  Penalized: ${s.actionsPenalized} | Rewarded: ${s.actionsRewarded}
+`);
+      if (s.progress && s.plan) {
+        process.stdout.write(`  Plan: ${s.plan.plan_id} \u2014 ${s.progress.completed}/${s.progress.total} (${s.progress.percentage}%)
+`);
+        for (const step of s.plan.steps) {
+          const icon = step.status === "completed" ? "[x]" : "[ ]";
+          process.stdout.write(`    ${icon} ${step.label}
+`);
+        }
+      }
+      process.stdout.write("\n");
+      rl.prompt();
+      return;
+    }
+    try {
+      const response = await model.chat(trimmed);
+      if (response.toolCalls.length > 0) {
+        const finalResponse = await session.processModelResponse(response, model);
+        if (finalResponse.content) {
+          process.stdout.write(`
+${finalResponse.content}
+
+`);
+        }
+        printProgress();
+      } else if (response.content) {
+        process.stdout.write(`
+${response.content}
+
+`);
+      }
+    } catch (err) {
+      process.stderr.write(`
+  Error: ${err}
+
+`);
+    }
+    rl.prompt();
+  });
+  rl.on("close", () => {
+    session.stop();
+  });
+  return new Promise((resolve) => {
+    rl.on("close", resolve);
+  });
+}
+
+export {
+  SessionManager,
+  runPipeMode,
+  runInteractiveMode
+};

package/dist/chunk-MH7BT4VH.js

@@ -0,0 +1,15 @@
+// src/contracts/guard-contract.ts
+var GUARD_EXIT_CODES = {
+  ALLOW: 0,
+  BLOCK: 1,
+  PAUSE: 2,
+  ERROR: 3,
+  MODIFY: 4,
+  PENALIZE: 5,
+  REWARD: 6,
+  NEUTRAL: 7
+};
+
+export {
+  GUARD_EXIT_CODES
+};

package/dist/chunk-O5ABKEA7.js

@@ -0,0 +1,304 @@
+import {
+  GovernanceBlockedError,
+  buildEngineOptions,
+  extractScope,
+  trackPlanProgress
+} from "./chunk-5U2MQO5P.js";
+import {
+  evaluateGuard
+} from "./chunk-W7LLXRGY.js";
+import {
+  loadWorld
+} from "./chunk-CTZHONLA.js";
+
+// src/engine/tool-classifier.ts
+var TOOL_CATEGORY_MAP = {
+  // File operations
+  read_file: "file_read",
+  read: "file_read",
+  glob: "file_read",
+  grep: "file_read",
+  list_files: "file_read",
+  write_file: "file_write",
+  write: "file_write",
+  create_file: "file_write",
+  edit_file: "file_write",
+  edit: "file_write",
+  patch: "file_write",
+  delete_file: "file_delete",
+  remove_file: "file_delete",
+  // Shell
+  shell: "shell",
+  bash: "shell",
+  execute: "shell",
+  run_command: "shell",
+  terminal: "shell",
+  // Git
+  git: "git",
+  git_commit: "git",
+  git_push: "git",
+  git_checkout: "git",
+  // Network
+  http: "network",
+  fetch: "network",
+  curl: "network",
+  web_search: "network",
+  // Sub-agents
+  sub_agent: "sub_agent",
+  spawn_agent: "sub_agent",
+  delegate: "sub_agent",
+  // Context management
+  summarize: "context",
+  compress_context: "context"
+};
+function classifyTool(toolName) {
+  const normalized = toolName.toLowerCase().replace(/[-\s]/g, "_");
+  return TOOL_CATEGORY_MAP[normalized] ?? "unknown";
+}
+var DANGEROUS_SHELL_PATTERNS = [
+  { pattern: /rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+|.*-rf\s+|.*--force)/, label: "force-delete" },
+  { pattern: /rm\s+-[a-zA-Z]*r/, label: "recursive-delete" },
+  { pattern: />\s*\/dev\/sd/, label: "disk-overwrite" },
+  { pattern: /mkfs\./, label: "format-disk" },
+  { pattern: /dd\s+if=/, label: "disk-dump" },
+  { pattern: /chmod\s+(-R\s+)?777/, label: "world-writable" },
+  { pattern: /curl\s+.*\|\s*(bash|sh|zsh)/, label: "pipe-to-shell" },
+  { pattern: /wget\s+.*\|\s*(bash|sh|zsh)/, label: "pipe-to-shell" },
+  { pattern: /:(){ :\|:& };:/, label: "fork-bomb" },
+  { pattern: />\s*\/etc\//, label: "system-config-overwrite" },
+  { pattern: /shutdown|reboot|halt|poweroff/, label: "system-shutdown" },
+  { pattern: /kill\s+-9\s+1\b/, label: "kill-init" }
+];
+var DANGEROUS_GIT_PATTERNS = [
+  { pattern: /push\s+.*--force/, label: "force-push" },
+  { pattern: /push\s+.*-f\b/, label: "force-push" },
+  { pattern: /push\s+(origin\s+)?main\b/, label: "push-main" },
+  { pattern: /push\s+(origin\s+)?master\b/, label: "push-master" },
+  { pattern: /reset\s+--hard/, label: "hard-reset" },
+  { pattern: /clean\s+-fd/, label: "clean-force" },
+  { pattern: /branch\s+-D/, label: "force-delete-branch" }
+];
+function isDangerousCommand(command) {
+  const matched = DANGEROUS_SHELL_PATTERNS.filter((p) => p.pattern.test(command)).map((p) => p.label);
+  return { dangerous: matched.length > 0, labels: matched };
+}
+function isDangerousGitCommand(command) {
+  const matched = DANGEROUS_GIT_PATTERNS.filter((p) => p.pattern.test(command)).map((p) => p.label);
+  return { dangerous: matched.length > 0, labels: matched };
+}
+function assessRiskLevel(category) {
+  if (category === "file_read" || category === "context") return "low";
+  if (category === "file_write" || category === "sub_agent") return "medium";
+  if (category === "shell" || category === "file_delete" || category === "git" || category === "network") return "high";
+  return void 0;
+}
+function categoryToActionCategory(category) {
+  if (category === "file_read" || category === "context") return "read";
+  if (category === "file_write") return "write";
+  if (category === "file_delete") return "delete";
+  if (category === "shell") return "shell";
+  if (category === "network") return "network";
+  return "other";
+}
+
+// src/adapters/deep-agents.ts
+var GovernanceBlockedError2 = class extends GovernanceBlockedError {
+  toolCall;
+  category;
+  constructor(verdict, toolCall, category) {
+    super(verdict);
+    this.toolCall = toolCall;
+    this.category = category;
+  }
+};
+function defaultMapToolCall(toolCall) {
+  const category = classifyTool(toolCall.tool);
+  const args = toolCall.args;
+  const scope = extractScope(args);
+  let intent = toolCall.tool;
+  if (category === "shell" && typeof args.command === "string") {
+    intent = `shell: ${args.command}`;
+  } else if (category === "git" && typeof args.command === "string") {
+    intent = `git ${args.command}`;
+  } else if (category === "file_write" && scope) {
+    intent = `write ${scope}`;
+  } else if (category === "file_delete" && scope) {
+    intent = `delete ${scope}`;
+  }
+  const riskLevel = assessRiskLevel(category);
+  let irreversible = false;
+  if (category === "shell" && typeof args.command === "string") {
+    irreversible = DANGEROUS_SHELL_PATTERNS.some((p) => p.pattern.test(args.command));
+  } else if (category === "git" && typeof args.command === "string") {
+    irreversible = DANGEROUS_GIT_PATTERNS.some((p) => p.pattern.test(args.command));
+  } else if (category === "file_delete") {
+    irreversible = true;
+  }
+  return {
+    intent,
+    tool: toolCall.tool,
+    scope,
+    args,
+    direction: "input",
+    actionCategory: categoryToActionCategory(category),
+    riskLevel,
+    irreversible
+  };
+}
+var DeepAgentsGuard = class {
+  name = "neuroverse-deep-agents-guard";
+  world;
+  options;
+  engineOptions;
+  mapToolCall;
+  activePlan;
+  constructor(world, options = {}) {
+    this.world = world;
+    this.options = options;
+    this.activePlan = options.plan;
+    this.engineOptions = buildEngineOptions(options, this.activePlan);
+    this.mapToolCall = options.mapToolCall ?? defaultMapToolCall;
+  }
+  /**
+   * Evaluate a tool call against governance rules.
+   * Returns the result without side effects.
+   */
+  evaluate(toolCall) {
+    const event = this.mapToolCall(toolCall);
+    this.engineOptions.plan = this.activePlan;
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    const category = classifyTool(toolCall.tool);
+    const result = {
+      allowed: verdict.status === "ALLOW",
+      verdict,
+      toolCall,
+      category
+    };
+    this.options.onEvaluate?.(result);
+    if (verdict.status === "ALLOW" && this.activePlan) {
+      this.trackPlanProgressInternal(event);
+    }
+    return result;
+  }
+  /**
+   * Evaluate and enforce governance on a tool call.
+   *
+   * @throws GovernanceBlockedError if BLOCKED
+   * @throws GovernanceBlockedError if PAUSED and onPause returns false
+   * @returns DeepAgentsGuardResult on ALLOW
+   */
+  async enforce(toolCall) {
+    const result = this.evaluate(toolCall);
+    if (result.verdict.status === "BLOCK") {
+      this.options.onBlock?.(result);
+      throw new GovernanceBlockedError2(result.verdict, toolCall, result.category);
+    }
+    if (result.verdict.status === "PAUSE") {
+      const approved = await this.options.onPause?.(result);
+      if (!approved) {
+        throw new GovernanceBlockedError2(result.verdict, toolCall, result.category);
+      }
+    }
+    return result;
+  }
+  /**
+   * Evaluate and execute a tool call with governance enforcement.
+   *
+   * If ALLOW: runs the executor and returns its result.
+   * If BLOCK: returns a governance-blocked message.
+   * If PAUSE: calls onPause; blocks if not approved.
+   *
+   * @param toolCall - The Deep Agents tool call to evaluate
+   * @param executor - The actual tool execution function
+   * @returns The tool execution result or a blocked message
+   */
+  async execute(toolCall, executor) {
+    const guardResult = this.evaluate(toolCall);
+    if (guardResult.verdict.status === "BLOCK") {
+      this.options.onBlock?.(guardResult);
+      return {
+        blocked: true,
+        verdict: guardResult.verdict,
+        reason: guardResult.verdict.reason ?? "Action blocked by governance policy."
+      };
+    }
+    if (guardResult.verdict.status === "PAUSE") {
+      const approved = await this.options.onPause?.(guardResult);
+      if (!approved) {
+        return {
+          blocked: true,
+          verdict: guardResult.verdict,
+          reason: guardResult.verdict.reason ?? "Action requires approval."
+        };
+      }
+    }
+    const result = await executor(toolCall);
+    return { result, verdict: guardResult.verdict };
+  }
+  /**
+   * Returns a middleware function compatible with Deep Agents' tool pipeline.
+   *
+   * The middleware intercepts tool calls before execution:
+   *   agent.use(guard.middleware());
+   */
+  middleware() {
+    return async (toolCall, next) => {
+      await this.enforce(toolCall);
+      return next();
+    };
+  }
+  /**
+   * Returns a callback-handler-style object for LangChain integration.
+   * Compatible with Deep Agents' callback system.
+   */
+  callbacks() {
+    return {
+      handleToolStart: async (tool, input) => {
+        let parsedInput;
+        try {
+          parsedInput = typeof input === "string" ? JSON.parse(input) : input;
+        } catch {
+          parsedInput = { raw: input };
+        }
+        await this.enforce({ tool: tool.name, args: parsedInput });
+      }
+    };
+  }
+  /**
+   * Check if a shell command contains dangerous patterns.
+   * Useful for pre-screening before full governance evaluation.
+   */
+  static isDangerousCommand(command) {
+    return isDangerousCommand(command);
+  }
+  /**
+   * Check if a git command contains dangerous patterns.
+   */
+  static isDangerousGitCommand(command) {
+    return isDangerousGitCommand(command);
+  }
+  /**
+   * Classify a tool name into a category.
+   */
+  static classifyTool(toolName) {
+    return classifyTool(toolName);
+  }
+  // ─── Private ──────────────────────────────────────────────────────────────
+  trackPlanProgressInternal(event) {
+    trackPlanProgress(event, this, this.options);
+  }
+};
+async function createDeepAgentsGuard(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new DeepAgentsGuard(world, options);
+}
+function createDeepAgentsGuardFromWorld(world, options) {
+  return new DeepAgentsGuard(world, options);
+}
+
+export {
+  GovernanceBlockedError2 as GovernanceBlockedError,
+  DeepAgentsGuard,
+  createDeepAgentsGuard,
+  createDeepAgentsGuardFromWorld
+};