@mandatedev/agent 0.1.0

package/src/hooks/langchain.ts

@@ -0,0 +1,141 @@
+// ============================================================
+// MANDATE — LangChain / LangGraph Hook
+// Uses before_tool_call callback for full semantic enforcement.
+// Compatible with LangChain.js and LangGraph.
+// ============================================================
+
+import type {
+    AgentIntent,
+    MandateConfig,
+    EvaluationResult,
+  } from '../types';
+  import type { JSPolicyEvaluator } from '../evaluator/js-evaluator';
+  import type { AuditBuffer } from '../buffer';
+  import type { DegradationManager } from '../degradation';
+  
+  interface LangChainToolCall {
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+  }
+  
+  export class MandateLangChainHook {
+    private evaluator: JSPolicyEvaluator;
+    private buffer: AuditBuffer;
+    private degradation: DegradationManager;
+    private config: MandateConfig;
+    private sessionId: string;
+    private stepCounter: number = 0;
+  
+    constructor(
+      config: MandateConfig,
+      evaluator: JSPolicyEvaluator,
+      buffer: AuditBuffer,
+      degradation: DegradationManager
+    ) {
+      this.config = config;
+      this.evaluator = evaluator;
+      this.buffer = buffer;
+      this.degradation = degradation;
+      this.sessionId = `sess_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    }
+  
+    // Returns a before_tool_call callback for LangChain
+    // Usage: agent.beforeToolCall = mandateHook.getBeforeToolCallHook()
+    getBeforeToolCallHook(): (
+      toolCall: LangChainToolCall
+    ) => Promise<LangChainToolCall | null> {
+      return async (
+        toolCall: LangChainToolCall
+      ): Promise<LangChainToolCall | null> => {
+        const step = this.stepCounter++;
+        const intent = this.buildIntent(toolCall, step);
+        const result = this.evaluator.evaluate(intent);
+  
+        this.logToBuffer(intent, result);
+  
+        if (result.decision === 'ALLOW') {
+          return toolCall;
+        }
+  
+        if (result.decision === 'THROTTLE') {
+          await this.delay(2000);
+          this.config.onAlert?.(intent, result.anomalyScore ?? 0);
+          return toolCall;
+        }
+  
+        // DENY or ESCALATE — block the tool call
+        this.config.onViolation?.(intent, result);
+        return null;
+      };
+    }
+  
+    // Direct interception for manual use
+    async interceptToolCall(
+      toolCall: LangChainToolCall
+    ): Promise<{ allowed: boolean; result: EvaluationResult }> {
+      const step = this.stepCounter++;
+      const intent = this.buildIntent(toolCall, step);
+      const result = this.evaluator.evaluate(intent);
+  
+      this.logToBuffer(intent, result);
+  
+      if (result.decision === 'DENY' || result.decision === 'ESCALATE') {
+        this.config.onViolation?.(intent, result);
+        return { allowed: false, result };
+      }
+  
+      if (result.decision === 'THROTTLE') {
+        await this.delay(2000);
+        this.config.onAlert?.(intent, result.anomalyScore ?? 0);
+      }
+  
+      return { allowed: true, result };
+    }
+  
+    // ============================================================
+    // PRIVATE
+    // ============================================================
+  
+    private buildIntent(
+      toolCall: LangChainToolCall,
+      step: number
+    ): AgentIntent {
+      return {
+        toolName: toolCall.name,
+        args: toolCall.args,
+        context: {
+          agentId: this.config.agentId,
+          sessionId: this.sessionId,
+          environment: this.config.environment,
+          stepInChain: step,
+          framework: 'langchain',
+          timestamp: Date.now(),
+        },
+      };
+    }
+  
+    private logToBuffer(intent: AgentIntent, result: EvaluationResult): void {
+      if (this.config.auditLevel === 'off') return;
+  
+      this.buffer.append({
+        timestamp: Date.now(),
+        source: 'REALTIME',
+        agentId: this.config.agentId,
+        orgId: this.config.orgId,
+        policyHash: this.config.policy.policyHash,
+        degradationTier: this.degradation.getCurrentTier(),
+        toolName: intent.toolName,
+        toolArgs: this.config.auditLevel === 'full' ? intent.args : {},
+        intentContext: intent.context,
+        anomalyScore: result.anomalyScore ?? 0,
+        policyDecision: result.decision,
+        responseLevel: 1,
+        evalLatencyMs: result.latencyMs,
+      });
+    }
+  
+    private delay(ms: number): Promise<void> {
+      return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+  }

package/src/hooks/openai.ts

@@ -0,0 +1,142 @@
+// ============================================================
+// MANDATE — OpenAI Assistants API + Function Calling Hook
+// Intercepts function_call declarations before execution.
+// Full semantic enforcement on structured tool-call intent.
+// ============================================================
+
+import type {
+    AgentIntent,
+    MandateConfig,
+    EvaluationResult,
+  } from '../types';
+  import type { JSPolicyEvaluator } from '../evaluator/js-evaluator';
+  import type { AuditBuffer } from '../buffer';
+  import type { DegradationManager } from '../degradation';
+  
+  interface OpenAIFunctionCall {
+    name: string;
+    arguments: string;
+  }
+  
+  interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: OpenAIFunctionCall;
+  }
+  
+  interface InterceptResult {
+    allowed: OpenAIToolCall[];
+    blocked: Array<{ toolCall: OpenAIToolCall; result: EvaluationResult }>;
+  }
+  
+  export class MandateOpenAIHook {
+    private evaluator: JSPolicyEvaluator;
+    private buffer: AuditBuffer;
+    private degradation: DegradationManager;
+    private config: MandateConfig;
+    private sessionId: string;
+  
+    constructor(
+      config: MandateConfig,
+      evaluator: JSPolicyEvaluator,
+      buffer: AuditBuffer,
+      degradation: DegradationManager
+    ) {
+      this.config = config;
+      this.evaluator = evaluator;
+      this.buffer = buffer;
+      this.degradation = degradation;
+      this.sessionId = this.generateSessionId();
+    }
+  
+    // Intercept OpenAI tool calls before execution
+    async interceptToolCalls(
+      toolCalls: OpenAIToolCall[],
+      stepInChain: number = 0
+    ): Promise<InterceptResult> {
+      const allowed: OpenAIToolCall[] = [];
+      const blocked: Array<{
+        toolCall: OpenAIToolCall;
+        result: EvaluationResult;
+      }> = [];
+  
+      for (const toolCall of toolCalls) {
+        const intent = this.buildIntent(toolCall, stepInChain);
+        const result = this.evaluator.evaluate(intent);
+  
+        this.logToBuffer(intent, result);
+  
+        if (result.decision === 'ALLOW') {
+          allowed.push(toolCall);
+        } else if (result.decision === 'THROTTLE') {
+          await this.delay(2000);
+          this.config.onAlert?.(intent, result.anomalyScore ?? 0);
+          allowed.push(toolCall);
+        } else {
+          blocked.push({ toolCall, result });
+          this.config.onViolation?.(intent, result);
+        }
+      }
+  
+      return { allowed, blocked };
+    }
+  
+    // ============================================================
+    // PRIVATE
+    // ============================================================
+  
+    private buildIntent(
+      toolCall: OpenAIToolCall,
+      stepInChain: number
+    ): AgentIntent {
+      let args: Record<string, unknown> = {};
+      try {
+        const parsed: unknown = JSON.parse(toolCall.function.arguments);
+        if (typeof parsed === 'object' && parsed !== null) {
+          args = parsed as Record<string, unknown>;
+        }
+      } catch {
+        args = { raw: toolCall.function.arguments };
+      }
+      return {
+        toolName: toolCall.function.name,
+        args,
+        context: {
+          agentId: this.config.agentId,
+          sessionId: this.sessionId,
+          environment: this.config.environment,
+          stepInChain,
+          framework: 'openai-assistants',
+          timestamp: Date.now(),
+        },
+      };
+    }
+  
+    private logToBuffer(intent: AgentIntent, result: EvaluationResult): void {
+      if (this.config.auditLevel === 'off') return;
+  
+      this.buffer.append({
+        timestamp: Date.now(),
+        source: 'REALTIME',
+        agentId: this.config.agentId,
+        orgId: this.config.orgId,
+        policyHash: this.config.policy.policyHash,
+        degradationTier: this.degradation.getCurrentTier(),
+        toolName: intent.toolName,
+        toolArgs: this.config.auditLevel === 'full' ? intent.args : {},
+        intentContext: intent.context,
+        anomalyScore: result.anomalyScore ?? 0,
+        policyDecision: result.decision,
+        responseLevel: 1,
+        evalLatencyMs: result.latencyMs,
+      });
+    }
+  
+    private generateSessionId(): string {
+      return `sess_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    }
+  
+    private delay(ms: number): Promise<void> {
+      return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+  }

package/src/index.ts

@@ -0,0 +1,175 @@
+// ============================================================
+// @mandate/agent — Trust Engine for the Agent Economy
+// The Mandate Agent SDK main entry point
+// Every developer imports from here
+// ============================================================
+
+import { JSPolicyEvaluator } from './evaluator/js-evaluator';
+import { AuditBuffer } from './buffer';
+import { DegradationManager } from './degradation';
+import { MandateOpenAIHook } from './hooks/openai';
+import { MandateLangChainHook } from './hooks/langchain';
+import { MandateAnthropicHook } from './hooks/anthropic';
+
+import type {
+  MandateConfig,
+  AgentIntent,
+  EvaluationResult,
+  AuditEvent,
+  DegradationTier,
+  MandatePolicy,
+} from './types';
+
+// Re-export all types for developer use
+export type {
+  MandateConfig,
+  MandatePolicy,
+  AgentIntent,
+  EvaluationResult,
+  AuditEvent,
+  DegradationTier,
+  AgentFramework,
+  AgentEnvironment,
+  AgentRiskTier,
+  PolicyDecision,
+  PolicyRule,
+  PolicyCondition,
+  ResponseLevel,
+} from './types';
+
+// ============================================================
+// MANDATE AGENT — main class
+// ============================================================
+
+export class MandateAgent {
+  private config: MandateConfig;
+  private evaluator: JSPolicyEvaluator;
+  private buffer: AuditBuffer;
+  private degradation: DegradationManager;
+
+  // Framework hooks — use the one matching your agent framework
+  public readonly openai: MandateOpenAIHook;
+  public readonly langchain: MandateLangChainHook;
+  public readonly anthropic: MandateAnthropicHook;
+
+  constructor(config: MandateConfig) {
+    this.config = config;
+
+    // Initialize core components
+    this.evaluator = new JSPolicyEvaluator(config.policy);
+
+    this.buffer = new AuditBuffer({
+      maxSize: 10000,
+      flushCallback: async (events) => {
+        await this.sendToControlPlane(events);
+      },
+    });
+
+    this.degradation = new DegradationManager({
+      gracePeriodMs: config.policy.localAutonomy.gracePeriodMs,
+      riskTier: config.riskTier ?? 'STANDARD',
+      onTierChange: (from, to) => {
+        config.onDegradation?.(from, to);
+        console.warn(`[Mandate] Degradation: ${from} → ${to}`);
+      },
+    });
+
+    // Initialize framework-specific hooks
+    this.openai = new MandateOpenAIHook(
+      config,
+      this.evaluator,
+      this.buffer,
+      this.degradation
+    );
+
+    this.langchain = new MandateLangChainHook(
+      config,
+      this.evaluator,
+      this.buffer,
+      this.degradation
+    );
+
+    this.anthropic = new MandateAnthropicHook(
+      config,
+      this.evaluator,
+      this.buffer,
+      this.degradation
+    );
+
+    console.log(
+      `[Mandate] Agent "${config.agentId}" initialized | ` +
+      `env: ${config.environment} | ` +
+      `framework: ${config.framework} | ` +
+      `policy: ${config.policy.policyHash}`
+    );
+  }
+
+  // Direct evaluation for custom frameworks
+  evaluate(intent: AgentIntent): EvaluationResult {
+    return this.evaluator.evaluate(intent);
+  }
+
+  // Flush the audit buffer manually
+  async flushAuditBuffer(): Promise<AuditEvent[]> {
+    return this.buffer.flush();
+  }
+
+  // Verify the cryptographic integrity of the audit chain
+  verifyAuditChain(): { valid: boolean; corruptedAt?: number } {
+    return this.buffer.verify();
+  }
+
+  // Get current degradation tier
+  getDegradationTier(): DegradationTier {
+    return this.degradation.getCurrentTier();
+  }
+
+  // Get current audit buffer size
+  getBufferSize(): number {
+    return this.buffer.size();
+  }
+
+  // Update policy — hot reload, no restart required
+  updatePolicy(policy: MandatePolicy): void {
+    this.evaluator.updatePolicy(policy);
+    console.log(`[Mandate] Policy updated: ${policy.policyHash}`);
+  }
+
+  // ============================================================
+  // PRIVATE
+  // ============================================================
+
+  private async sendToControlPlane(events: AuditEvent[]): Promise<void> {
+    if (!this.config.controlPlaneUrl || !this.config.apiKey) return;
+
+    try {
+      const response = await fetch(
+        `${this.config.controlPlaneUrl}/v1/events`,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.config.apiKey}`,
+          },
+          body: JSON.stringify({ events }),
+        }
+      );
+
+      if (!response.ok) {
+        throw new Error(`Control plane responded with ${response.status}`);
+      }
+
+      this.degradation.onControlPlaneReconnected();
+    } catch {
+      this.degradation.onControlPlaneUnreachable();
+    }
+  }
+}
+
+// ============================================================
+// CONVENIENCE FACTORY — three lines of code to wrap any agent
+// ============================================================
+
+export function createMandateAgent(config: MandateConfig): MandateAgent {
+  return new MandateAgent(config);
+}

package/src/types.ts

@@ -0,0 +1,162 @@
+// ============================================================
+// MANDATE CORE TYPES
+// Every component in the SDK depends on these definitions
+// ============================================================
+
+// The framework the agent is built on
+export type AgentFramework =
+  | 'openai-assistants'
+  | 'langchain'
+  | 'autogen'
+  | 'crewai'
+  | 'anthropic'
+  | 'custom';
+
+// Environment the agent runs in
+export type AgentEnvironment = 'production' | 'staging' | 'development';
+
+// Risk level assigned to this agent
+export type AgentRiskTier = 'LOW' | 'STANDARD' | 'HIGH' | 'CRITICAL';
+
+// Degradation tiers — V3 five-tier state machine
+export type DegradationTier =
+  | 'NOMINAL'     // Full real-time enforcement, live audit streaming
+  | 'DEGRADED'    // Local cache active, audit buffered, agent at full capacity
+  | 'ISOLATED'    // Control plane unreachable, local enforcement only
+  | 'GRACE_STD'   // 30min grace elapsed, standard risk agent continues
+  | 'GRACE_HIGH'; // 30min grace elapsed, high risk agent → PAUSE
+
+// Policy decision returned by the evaluator
+export type PolicyDecision = 'ALLOW' | 'DENY' | 'ESCALATE' | 'THROTTLE';
+
+// Kill switch response levels
+export type ResponseLevel = 1 | 2 | 3 | 4 | 5;
+// 1=ALERT 2=THROTTLE 3=PAUSE 4=SCOPED_KILL 5=FULL_KILL
+
+// ============================================================
+// INTENT — what Mandate intercepts from agent frameworks
+// ============================================================
+
+export interface IntentContext {
+  agentId: string;
+  sessionId: string;
+  environment: AgentEnvironment;
+  stepInChain: number;
+  framework: AgentFramework;
+  timestamp: number;
+}
+
+export interface AgentIntent {
+  toolName: string;
+  args: Record<string, unknown>;
+  context: IntentContext;
+}
+
+// ============================================================
+// EVALUATION RESULT
+// ============================================================
+
+export interface EvaluationResult {
+  decision: PolicyDecision;
+  reason: string;
+  latencyMs: number;
+  ruleMatched?: string;
+  anomalyScore?: number;
+  responseLevel?: ResponseLevel;
+}
+
+// ============================================================
+// POLICY — JSON representation (MPL compiles to this format)
+// ============================================================
+
+export type ConditionOperator =
+  | 'eq' | 'neq'
+  | 'lt' | 'lte'
+  | 'gt' | 'gte'
+  | 'in' | 'nin'
+  | 'startsWith'
+  | 'endsWith'
+  | 'contains';
+
+export interface PolicyCondition {
+  field: string;       // dot-notation: "intent.args.amount"
+  operator: ConditionOperator;
+  value: unknown;
+}
+
+export interface PolicyRule {
+  tool: string;        // supports wildcards: "read_*", "*", "process_payment"
+  conditions?: PolicyCondition[];
+}
+
+export interface PolicyIdentity {
+  org: string;
+  env: AgentEnvironment;
+  framework?: string;
+}
+
+export interface AnomalyThresholds {
+  alert: number;       // default 0.60 — fires ALERT
+  throttle: number;    // default 0.80 — fires THROTTLE
+}
+
+export interface LocalAutonomyConfig {
+  gracePeriodMs: number;       // default 1800000 (30 minutes)
+  postGrace: 'PAUSE' | 'STOP';
+}
+
+export interface MandatePolicy {
+  agentId: string;
+  version: string;
+  policyHash: string;
+  identity: PolicyIdentity;
+  allow: PolicyRule[];
+  deny: PolicyRule[];
+  anomalyThresholds: AnomalyThresholds;
+  localAutonomy: LocalAutonomyConfig;
+}
+
+// ============================================================
+// AUDIT EVENT — written to the hash-chain buffer
+// ============================================================
+
+export interface AuditEvent {
+  eventId: string;
+  prevHash: string;
+  eventHash: string;
+  timestamp: number;
+  source: 'REALTIME' | 'BUFFER_SYNC';
+  agentId: string;
+  orgId: string;
+  policyHash: string;
+  degradationTier: DegradationTier;
+  toolName: string;
+  toolArgs: Record<string, unknown>;
+  intentContext: IntentContext;
+  anomalyScore: number;
+  blastRadiusEst?: string;
+  policyDecision: PolicyDecision;
+  responseLevel: ResponseLevel;
+  evalLatencyMs: number;
+  tokensUsed?: number;
+  costUsd?: number;
+}
+
+// ============================================================
+// MANDATE CONFIGURATION
+// ============================================================
+
+export interface MandateConfig {
+  agentId: string;
+  orgId: string;
+  apiKey?: string;
+  controlPlaneUrl?: string;
+  policy: MandatePolicy;
+  framework: AgentFramework;
+  environment: AgentEnvironment;
+  auditLevel: 'full' | 'minimal' | 'off';
+  riskTier?: AgentRiskTier;
+  onViolation?: (intent: AgentIntent, result: EvaluationResult) => void;
+  onAlert?: (intent: AgentIntent, score: number) => void;
+  onDegradation?: (from: DegradationTier, to: DegradationTier) => void;
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+    "compilerOptions": {
+      "target": "ES2020",
+      "module": "ESNext",
+      "moduleResolution": "bundler",
+      "lib": ["ES2020", "DOM"],
+      "strict": true,
+      "exactOptionalPropertyTypes": true,
+      "noUncheckedIndexedAccess": true,
+      "noImplicitReturns": true,
+      "noFallthroughCasesInSwitch": true,
+      "declaration": true,
+      "declarationMap": true,
+      "sourceMap": true,
+      "outDir": "./dist",
+      "rootDir": "./src",
+      "skipLibCheck": true
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+  }