@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/adapters/deep-agents.d.cts

@@ -0,0 +1,181 @@
+import { b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, a as GuardVerdict, G as GuardEvent, c as PlanProgress } from '../guard-contract-DqFcTScd.cjs';
+import { G as GovernanceBlockedError$1 } from '../shared-B8dvUUD8.cjs';
+
+/**
+ * Centralized Tool Classification & Risk Pattern Detection
+ *
+ * Extracted from deep-agents.ts where it was the only adapter
+ * with comprehensive tool classification and dangerous command
+ * detection. Now available to all adapters and the core engine.
+ */
+type ToolCategory = 'file_read' | 'file_write' | 'file_delete' | 'shell' | 'git' | 'network' | 'sub_agent' | 'context' | 'unknown';
+
+/**
+ * NeuroVerse Adapter — Deep Agents (LangChain)
+ *
+ * Intercepts tool execution in LangChain's Deep Agents framework
+ * and evaluates every action against a NeuroVerse world definition
+ * before allowing it to proceed.
+ *
+ * Deep Agents exposes a coding-agent loop with tools for file I/O,
+ * shell execution, sub-agent spawning, and context management.
+ * This adapter sits between the agent and those tools, enforcing
+ * governance rules deterministically.
+ *
+ * Usage:
+ *   import { createDeepAgentsGuard } from '@neuroverseos/governance/adapters/deep-agents';
+ *
+ *   const guard = await createDeepAgentsGuard('./world/');
+ *
+ *   // Wrap the agent's tool executor:
+ *   agent.use(guard.middleware());
+ *
+ *   // Or evaluate manually:
+ *   const verdict = guard.evaluate({ tool: 'shell', command: 'rm -rf /' });
+ */
+
+/** Shape of a Deep Agents tool invocation. */
+interface DeepAgentsToolCall {
+    /** Tool name: read_file, write_file, shell, edit_file, sub_agent, etc. */
+    tool: string;
+    /** Tool arguments as passed by the agent. */
+    args: Record<string, unknown>;
+    /** Optional run/session identifier. */
+    runId?: string;
+}
+/** Categorized tool types recognized by the adapter (re-exported from tool-classifier). */
+type DeepAgentsToolCategory = ToolCategory;
+/** Result of a governed evaluation. */
+interface DeepAgentsGuardResult {
+    allowed: boolean;
+    verdict: GuardVerdict;
+    toolCall: DeepAgentsToolCall;
+    category: DeepAgentsToolCategory;
+}
+interface DeepAgentsGuardOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called when an action is blocked. */
+    onBlock?: (result: DeepAgentsGuardResult) => void;
+    /** Called when an action requires approval. Return true to allow. */
+    onPause?: (result: DeepAgentsGuardResult) => Promise<boolean> | boolean;
+    /** Called for every evaluation (logging hook). */
+    onEvaluate?: (result: DeepAgentsGuardResult) => void;
+    /** Custom mapping from Deep Agents tool call to GuardEvent. */
+    mapToolCall?: (toolCall: DeepAgentsToolCall) => GuardEvent;
+    /** 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 toolCall: DeepAgentsToolCall;
+    readonly category: DeepAgentsToolCategory;
+    constructor(verdict: GuardVerdict, toolCall: DeepAgentsToolCall, category: DeepAgentsToolCategory);
+}
+/**
+ * NeuroVerse governance guard for LangChain Deep Agents.
+ *
+ * Evaluates every tool invocation against a world definition before
+ * allowing execution. Supports blocking, pausing (approval required),
+ * and plan-scoped governance.
+ */
+declare class DeepAgentsGuard {
+    readonly name = "neuroverse-deep-agents-guard";
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapToolCall;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: DeepAgentsGuardOptions);
+    /**
+     * Evaluate a tool call against governance rules.
+     * Returns the result without side effects.
+     */
+    evaluate(toolCall: DeepAgentsToolCall): DeepAgentsGuardResult;
+    /**
+     * Evaluate and enforce governance on a tool call.
+     *
+     * @throws GovernanceBlockedError if BLOCKED
+     * @throws GovernanceBlockedError if PAUSED and onPause returns false
+     * @returns DeepAgentsGuardResult on ALLOW
+     */
+    enforce(toolCall: DeepAgentsToolCall): Promise<DeepAgentsGuardResult>;
+    /**
+     * 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
+     */
+    execute<T>(toolCall: DeepAgentsToolCall, executor: (toolCall: DeepAgentsToolCall) => Promise<T>): Promise<{
+        result: T;
+        verdict: GuardVerdict;
+    } | {
+        blocked: true;
+        verdict: GuardVerdict;
+        reason: string;
+    }>;
+    /**
+     * Returns a middleware function compatible with Deep Agents' tool pipeline.
+     *
+     * The middleware intercepts tool calls before execution:
+     *   agent.use(guard.middleware());
+     */
+    middleware(): (toolCall: DeepAgentsToolCall, next: () => Promise<unknown>) => Promise<unknown>;
+    /**
+     * Returns a callback-handler-style object for LangChain integration.
+     * Compatible with Deep Agents' callback system.
+     */
+    callbacks(): {
+        handleToolStart: (tool: {
+            name: string;
+        }, input: string) => Promise<void>;
+    };
+    /**
+     * Check if a shell command contains dangerous patterns.
+     * Useful for pre-screening before full governance evaluation.
+     */
+    static isDangerousCommand(command: string): {
+        dangerous: boolean;
+        labels: string[];
+    };
+    /**
+     * Check if a git command contains dangerous patterns.
+     */
+    static isDangerousGitCommand(command: string): {
+        dangerous: boolean;
+        labels: string[];
+    };
+    /**
+     * Classify a tool name into a category.
+     */
+    static classifyTool(toolName: string): DeepAgentsToolCategory;
+    private trackPlanProgressInternal;
+}
+/**
+ * Create a Deep Agents guard from a world path.
+ *
+ * @param worldPath - Path to world directory, .nv-world.md, or .nv-world.zip
+ * @param options - Guard configuration
+ * @returns A guard ready to plug into Deep Agents
+ */
+declare function createDeepAgentsGuard(worldPath: string, options?: DeepAgentsGuardOptions): Promise<DeepAgentsGuard>;
+/**
+ * Create a Deep Agents guard from a pre-loaded world.
+ *
+ * @param world - A loaded WorldDefinition
+ * @param options - Guard configuration
+ * @returns A guard ready to plug into Deep Agents
+ */
+declare function createDeepAgentsGuardFromWorld(world: WorldDefinition, options?: DeepAgentsGuardOptions): DeepAgentsGuard;
+
+export { DeepAgentsGuard, type DeepAgentsGuardOptions, type DeepAgentsGuardResult, type DeepAgentsToolCall, type DeepAgentsToolCategory, GovernanceBlockedError, createDeepAgentsGuard, createDeepAgentsGuardFromWorld };

package/dist/adapters/deep-agents.d.ts

@@ -0,0 +1,181 @@
+import { b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, a as GuardVerdict, G as GuardEvent, c as PlanProgress } from '../guard-contract-DqFcTScd.js';
+import { G as GovernanceBlockedError$1 } from '../shared-Dr5Wiay8.js';
+
+/**
+ * Centralized Tool Classification & Risk Pattern Detection
+ *
+ * Extracted from deep-agents.ts where it was the only adapter
+ * with comprehensive tool classification and dangerous command
+ * detection. Now available to all adapters and the core engine.
+ */
+type ToolCategory = 'file_read' | 'file_write' | 'file_delete' | 'shell' | 'git' | 'network' | 'sub_agent' | 'context' | 'unknown';
+
+/**
+ * NeuroVerse Adapter — Deep Agents (LangChain)
+ *
+ * Intercepts tool execution in LangChain's Deep Agents framework
+ * and evaluates every action against a NeuroVerse world definition
+ * before allowing it to proceed.
+ *
+ * Deep Agents exposes a coding-agent loop with tools for file I/O,
+ * shell execution, sub-agent spawning, and context management.
+ * This adapter sits between the agent and those tools, enforcing
+ * governance rules deterministically.
+ *
+ * Usage:
+ *   import { createDeepAgentsGuard } from '@neuroverseos/governance/adapters/deep-agents';
+ *
+ *   const guard = await createDeepAgentsGuard('./world/');
+ *
+ *   // Wrap the agent's tool executor:
+ *   agent.use(guard.middleware());
+ *
+ *   // Or evaluate manually:
+ *   const verdict = guard.evaluate({ tool: 'shell', command: 'rm -rf /' });
+ */
+
+/** Shape of a Deep Agents tool invocation. */
+interface DeepAgentsToolCall {
+    /** Tool name: read_file, write_file, shell, edit_file, sub_agent, etc. */
+    tool: string;
+    /** Tool arguments as passed by the agent. */
+    args: Record<string, unknown>;
+    /** Optional run/session identifier. */
+    runId?: string;
+}
+/** Categorized tool types recognized by the adapter (re-exported from tool-classifier). */
+type DeepAgentsToolCategory = ToolCategory;
+/** Result of a governed evaluation. */
+interface DeepAgentsGuardResult {
+    allowed: boolean;
+    verdict: GuardVerdict;
+    toolCall: DeepAgentsToolCall;
+    category: DeepAgentsToolCategory;
+}
+interface DeepAgentsGuardOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called when an action is blocked. */
+    onBlock?: (result: DeepAgentsGuardResult) => void;
+    /** Called when an action requires approval. Return true to allow. */
+    onPause?: (result: DeepAgentsGuardResult) => Promise<boolean> | boolean;
+    /** Called for every evaluation (logging hook). */
+    onEvaluate?: (result: DeepAgentsGuardResult) => void;
+    /** Custom mapping from Deep Agents tool call to GuardEvent. */
+    mapToolCall?: (toolCall: DeepAgentsToolCall) => GuardEvent;
+    /** 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 toolCall: DeepAgentsToolCall;
+    readonly category: DeepAgentsToolCategory;
+    constructor(verdict: GuardVerdict, toolCall: DeepAgentsToolCall, category: DeepAgentsToolCategory);
+}
+/**
+ * NeuroVerse governance guard for LangChain Deep Agents.
+ *
+ * Evaluates every tool invocation against a world definition before
+ * allowing execution. Supports blocking, pausing (approval required),
+ * and plan-scoped governance.
+ */
+declare class DeepAgentsGuard {
+    readonly name = "neuroverse-deep-agents-guard";
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapToolCall;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: DeepAgentsGuardOptions);
+    /**
+     * Evaluate a tool call against governance rules.
+     * Returns the result without side effects.
+     */
+    evaluate(toolCall: DeepAgentsToolCall): DeepAgentsGuardResult;
+    /**
+     * Evaluate and enforce governance on a tool call.
+     *
+     * @throws GovernanceBlockedError if BLOCKED
+     * @throws GovernanceBlockedError if PAUSED and onPause returns false
+     * @returns DeepAgentsGuardResult on ALLOW
+     */
+    enforce(toolCall: DeepAgentsToolCall): Promise<DeepAgentsGuardResult>;
+    /**
+     * 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
+     */
+    execute<T>(toolCall: DeepAgentsToolCall, executor: (toolCall: DeepAgentsToolCall) => Promise<T>): Promise<{
+        result: T;
+        verdict: GuardVerdict;
+    } | {
+        blocked: true;
+        verdict: GuardVerdict;
+        reason: string;
+    }>;
+    /**
+     * Returns a middleware function compatible with Deep Agents' tool pipeline.
+     *
+     * The middleware intercepts tool calls before execution:
+     *   agent.use(guard.middleware());
+     */
+    middleware(): (toolCall: DeepAgentsToolCall, next: () => Promise<unknown>) => Promise<unknown>;
+    /**
+     * Returns a callback-handler-style object for LangChain integration.
+     * Compatible with Deep Agents' callback system.
+     */
+    callbacks(): {
+        handleToolStart: (tool: {
+            name: string;
+        }, input: string) => Promise<void>;
+    };
+    /**
+     * Check if a shell command contains dangerous patterns.
+     * Useful for pre-screening before full governance evaluation.
+     */
+    static isDangerousCommand(command: string): {
+        dangerous: boolean;
+        labels: string[];
+    };
+    /**
+     * Check if a git command contains dangerous patterns.
+     */
+    static isDangerousGitCommand(command: string): {
+        dangerous: boolean;
+        labels: string[];
+    };
+    /**
+     * Classify a tool name into a category.
+     */
+    static classifyTool(toolName: string): DeepAgentsToolCategory;
+    private trackPlanProgressInternal;
+}
+/**
+ * Create a Deep Agents guard from a world path.
+ *
+ * @param worldPath - Path to world directory, .nv-world.md, or .nv-world.zip
+ * @param options - Guard configuration
+ * @returns A guard ready to plug into Deep Agents
+ */
+declare function createDeepAgentsGuard(worldPath: string, options?: DeepAgentsGuardOptions): Promise<DeepAgentsGuard>;
+/**
+ * Create a Deep Agents guard from a pre-loaded world.
+ *
+ * @param world - A loaded WorldDefinition
+ * @param options - Guard configuration
+ * @returns A guard ready to plug into Deep Agents
+ */
+declare function createDeepAgentsGuardFromWorld(world: WorldDefinition, options?: DeepAgentsGuardOptions): DeepAgentsGuard;
+
+export { DeepAgentsGuard, type DeepAgentsGuardOptions, type DeepAgentsGuardResult, type DeepAgentsToolCall, type DeepAgentsToolCategory, GovernanceBlockedError, createDeepAgentsGuard, createDeepAgentsGuardFromWorld };

package/dist/adapters/deep-agents.js

@@ -0,0 +1,17 @@
+import {
+  DeepAgentsGuard,
+  GovernanceBlockedError,
+  createDeepAgentsGuard,
+  createDeepAgentsGuardFromWorld
+} from "../chunk-O5ABKEA7.js";
+import "../chunk-5U2MQO5P.js";
+import "../chunk-W7LLXRGY.js";
+import "../chunk-QLPTHTVB.js";
+import "../chunk-CTZHONLA.js";
+import "../chunk-QWGCMQQD.js";
+export {
+  DeepAgentsGuard,
+  GovernanceBlockedError,
+  createDeepAgentsGuard,
+  createDeepAgentsGuardFromWorld
+};