@neuroverseos/governance 0.3.1 → 0.3.4

package/dist/adapters/openai.d.cts

@@ -0,0 +1,99 @@
+import { a as GuardVerdict, G as GuardEvent, P as PlanDefinition, c as PlanProgress, b as GuardEngineOptions, W as WorldDefinition } from '../guard-contract-B7lplwm9.cjs';
+import { G as GovernanceBlockedError$1 } from '../shared-C_zpdvBm.cjs';
+
+/**
+ * NeuroVerse Adapter — OpenAI
+ *
+ * Wraps the governance engine as middleware for OpenAI function calling.
+ * Evaluates function/tool calls against a world definition before execution.
+ *
+ * Usage:
+ *   import { createGovernedToolExecutor } from 'neuroverse-governance/adapters/openai';
+ *
+ *   const executor = await createGovernedToolExecutor('./world/');
+ *
+ *   // In your tool execution loop:
+ *   for (const toolCall of message.tool_calls) {
+ *     const result = await executor.execute(toolCall, myToolRunner);
+ *   }
+ */
+
+/** Shape of an OpenAI tool call (from chat completions response). */
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** Result of a governed tool execution. */
+interface GovernedToolResult {
+    tool_call_id: string;
+    role: 'tool';
+    content: string;
+    /** The governance verdict for this tool call. */
+    _verdict: GuardVerdict;
+}
+interface GovernedExecutorOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called for every evaluation (logging hook). */
+    onEvaluate?: (verdict: GuardVerdict, event: GuardEvent) => void;
+    /** Custom mapping from function call to GuardEvent. */
+    mapFunctionCall?: (name: string, args: Record<string, unknown>) => GuardEvent;
+    /** Message returned to the model when a tool call is blocked. */
+    blockMessage?: (verdict: GuardVerdict) => string;
+    /** 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 toolCallId: string;
+    constructor(verdict: GuardVerdict, toolCallId: string);
+}
+/**
+ * Wraps tool execution with NeuroVerse governance.
+ * Evaluates each function call before allowing the tool runner to execute.
+ */
+declare class GovernedToolExecutor {
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapFn;
+    private blockMsg;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: GovernedExecutorOptions);
+    /**
+     * Evaluate a single tool call against governance rules.
+     * Returns the verdict without executing the tool.
+     */
+    evaluate(toolCall: OpenAIToolCall): GuardVerdict;
+    /**
+     * Execute a tool call with governance enforcement.
+     *
+     * If ALLOW: runs the tool and returns the result.
+     * If BLOCK: returns a blocked message (no execution).
+     * If PAUSE: throws — caller must handle approval flow.
+     *
+     * @param toolCall - The OpenAI tool call to evaluate
+     * @param runner - The actual tool execution function
+     * @returns A tool result message ready for the OpenAI API
+     */
+    execute(toolCall: OpenAIToolCall, runner: (name: string, args: Record<string, unknown>) => Promise<string>): Promise<GovernedToolResult>;
+}
+/**
+ * Create a governed tool executor from a world path.
+ */
+declare function createGovernedToolExecutor(worldPath: string, options?: GovernedExecutorOptions): Promise<GovernedToolExecutor>;
+/**
+ * Create a governed tool executor from a pre-loaded world.
+ */
+declare function createGovernedToolExecutorFromWorld(world: WorldDefinition, options?: GovernedExecutorOptions): GovernedToolExecutor;
+
+export { GovernanceBlockedError, type GovernedExecutorOptions, GovernedToolExecutor, type GovernedToolResult, type OpenAIToolCall, createGovernedToolExecutor, createGovernedToolExecutorFromWorld };

package/dist/adapters/openai.d.ts

@@ -0,0 +1,99 @@
+import { a as GuardVerdict, G as GuardEvent, P as PlanDefinition, c as PlanProgress, b as GuardEngineOptions, W as WorldDefinition } from '../guard-contract-B7lplwm9.js';
+import { G as GovernanceBlockedError$1 } from '../shared-Cf7yxx4-.js';
+
+/**
+ * NeuroVerse Adapter — OpenAI
+ *
+ * Wraps the governance engine as middleware for OpenAI function calling.
+ * Evaluates function/tool calls against a world definition before execution.
+ *
+ * Usage:
+ *   import { createGovernedToolExecutor } from 'neuroverse-governance/adapters/openai';
+ *
+ *   const executor = await createGovernedToolExecutor('./world/');
+ *
+ *   // In your tool execution loop:
+ *   for (const toolCall of message.tool_calls) {
+ *     const result = await executor.execute(toolCall, myToolRunner);
+ *   }
+ */
+
+/** Shape of an OpenAI tool call (from chat completions response). */
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** Result of a governed tool execution. */
+interface GovernedToolResult {
+    tool_call_id: string;
+    role: 'tool';
+    content: string;
+    /** The governance verdict for this tool call. */
+    _verdict: GuardVerdict;
+}
+interface GovernedExecutorOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called for every evaluation (logging hook). */
+    onEvaluate?: (verdict: GuardVerdict, event: GuardEvent) => void;
+    /** Custom mapping from function call to GuardEvent. */
+    mapFunctionCall?: (name: string, args: Record<string, unknown>) => GuardEvent;
+    /** Message returned to the model when a tool call is blocked. */
+    blockMessage?: (verdict: GuardVerdict) => string;
+    /** 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 toolCallId: string;
+    constructor(verdict: GuardVerdict, toolCallId: string);
+}
+/**
+ * Wraps tool execution with NeuroVerse governance.
+ * Evaluates each function call before allowing the tool runner to execute.
+ */
+declare class GovernedToolExecutor {
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapFn;
+    private blockMsg;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: GovernedExecutorOptions);
+    /**
+     * Evaluate a single tool call against governance rules.
+     * Returns the verdict without executing the tool.
+     */
+    evaluate(toolCall: OpenAIToolCall): GuardVerdict;
+    /**
+     * Execute a tool call with governance enforcement.
+     *
+     * If ALLOW: runs the tool and returns the result.
+     * If BLOCK: returns a blocked message (no execution).
+     * If PAUSE: throws — caller must handle approval flow.
+     *
+     * @param toolCall - The OpenAI tool call to evaluate
+     * @param runner - The actual tool execution function
+     * @returns A tool result message ready for the OpenAI API
+     */
+    execute(toolCall: OpenAIToolCall, runner: (name: string, args: Record<string, unknown>) => Promise<string>): Promise<GovernedToolResult>;
+}
+/**
+ * Create a governed tool executor from a world path.
+ */
+declare function createGovernedToolExecutor(worldPath: string, options?: GovernedExecutorOptions): Promise<GovernedToolExecutor>;
+/**
+ * Create a governed tool executor from a pre-loaded world.
+ */
+declare function createGovernedToolExecutorFromWorld(world: WorldDefinition, options?: GovernedExecutorOptions): GovernedToolExecutor;
+
+export { GovernanceBlockedError, type GovernedExecutorOptions, GovernedToolExecutor, type GovernedToolResult, type OpenAIToolCall, createGovernedToolExecutor, createGovernedToolExecutorFromWorld };

package/dist/adapters/openai.js

@@ -0,0 +1,17 @@
+import {
+  GovernanceBlockedError,
+  GovernedToolExecutor,
+  createGovernedToolExecutor,
+  createGovernedToolExecutorFromWorld
+} from "../chunk-4FLICVVA.js";
+import "../chunk-5U2MQO5P.js";
+import "../chunk-W7LLXRGY.js";
+import "../chunk-QLPTHTVB.js";
+import "../chunk-CTZHONLA.js";
+import "../chunk-QWGCMQQD.js";
+export {
+  GovernanceBlockedError,
+  GovernedToolExecutor,
+  createGovernedToolExecutor,
+  createGovernedToolExecutorFromWorld
+};