Skip to main content

​
TealEngine

TealEngine is the core policy evaluation engine that provides mode-based enforcement with the deterministic Decision contract.

​
Overview

TealEngine evaluates requests against configured policies and returns Decision objects with:
  • Mode-specific behavior (ENFORCE, MONITOR, REPORT_ONLY)
  • Risk scoring for security analysis
  • Reason codes for explainability
  • Correlation IDs for traceability

​
Class

class TealEngine {
  constructor(config: TealEngineConfig);
  
  evaluate(
    request: RequestContext,
    context?: ExecutionContext
  ): Promise<Decision>;
  
  getModeConfig(): ModeConfig;
}

​
Configuration

interface TealEngineConfig {
  policies: PolicyConfig;
  mode?: ModeConfig;
  cache?: {
    enabled?: boolean;
    ttl?: number;
    maxSize?: number;
  };
}

interface ModeConfig {
  default: PolicyMode;
  environment?: Record<string, PolicyMode>;
  policy?: Record<string, PolicyMode>;
}

​
Creating an Engine

​
Basic Configuration

import { TealEngine, PolicyMode } from '@tealtiger/sdk';

const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: { allowed: false },
      database_query: { allowed: true }
    }
  },
  mode: {
    default: PolicyMode.ENFORCE
  }
});

​
Environment-Specific Modes

const engine = new TealEngine({
  policies: myPolicies,
  mode: {
    default: PolicyMode.ENFORCE,
    environment: {
      'development': PolicyMode.REPORT_ONLY,
      'staging': PolicyMode.MONITOR,
      'production': PolicyMode.ENFORCE
    }
  }
});

​
Policy-Specific Modes

const engine = new TealEngine({
  policies: myPolicies,
  mode: {
    default: PolicyMode.ENFORCE,
    policy: {
      'tools.file_delete': PolicyMode.MONITOR,
      'cost-limit': PolicyMode.REPORT_ONLY
    }
  }
});

​
Evaluating Requests

​
Basic Evaluation

import { ExecutionContext } from '@tealtiger/sdk';

const context = ExecutionContext.create({
  actor: { id: 'user-123', type: 'user' }
});

const decision = await engine.evaluate({
  agentId: 'agent-001',
  action: 'tool.execute',
  tool: 'file_delete'
}, context);

console.log(decision.action); // DENY or ALLOW
console.log(decision.risk_score); // 0-100
console.log(decision.reason_codes); // [ReasonCode.TOOL_NOT_ALLOWED]

​
With Metadata

const decision = await engine.evaluate({
  agentId: 'agent-001',
  action: 'llm.call',
  model: 'gpt-4',
  metadata: {
    provider: 'openai',
    estimated_cost: 0.05
  }
}, context);

​
Policy Modes

​
ENFORCE Mode

// Blocks violations, allows compliant requests
const engine = new TealEngine({
  policies: myPolicies,
  mode: { default: PolicyMode.ENFORCE }
});

const decision = await engine.evaluate(request, context);

if (decision.action === DecisionAction.DENY) {
  throw new Error(`Request denied: ${decision.reason}`);
}

​
MONITOR Mode

// Always allows but logs violations
const engine = new TealEngine({
  policies: myPolicies,
  mode: { default: PolicyMode.MONITOR }
});

const decision = await engine.evaluate(request, context);

// Always ALLOW, but check for violations
if (decision.reason_codes.includes(ReasonCode.MONITOR_MODE_VIOLATION)) {
  console.warn(`Policy violation detected: ${decision.reason}`);
}

​
REPORT_ONLY Mode

// Skips evaluation, always allows
const engine = new TealEngine({
  policies: myPolicies,
  mode: { default: PolicyMode.REPORT_ONLY }
});

const decision = await engine.evaluate(request, context);

// Always ALLOW, no evaluation performed
console.log(decision.metadata.evaluation_performed); // false

​
Mode Resolution

Mode resolution follows this priority:
  1. Policy-specific override (highest priority)
  2. Environment-specific override
  3. Global default (lowest priority)
const engine = new TealEngine({
  policies: myPolicies,
  mode: {
    default: PolicyMode.ENFORCE,
    environment: {
      'staging': PolicyMode.MONITOR
    },
    policy: {
      'tools.file_delete': PolicyMode.ENFORCE
    }
  }
});

// In staging environment:
// - tools.file_delete → ENFORCE (policy-specific wins)
// - other policies → MONITOR (environment-specific)

​
Caching

const engine = new TealEngine({
  policies: myPolicies,
  cache: {
    enabled: true,
    ttl: 60000, // 60 seconds
    maxSize: 1000
  }
});

const decision = await engine.evaluate(request, context);

console.log(decision.metadata.cache_hit); // true or false

​
Integration with TealAudit

import { TealEngine, TealAudit } from '@tealtiger/sdk';

const engine = new TealEngine(config);
const audit = new TealAudit({ outputs: [new ConsoleOutput()] });

const decision = await engine.evaluate(request, context);

// Log decision to audit
await audit.log('policy_evaluation', {
  decision,
  context
});

​
Error Handling

try {
  const decision = await engine.evaluate(request, context);
  
  if (decision.action === DecisionAction.DENY) {
    // Handle denial
    console.error(`Request denied: ${decision.reason}`);
    console.error(`Risk score: ${decision.risk_score}`);
    console.error(`Reason codes: ${decision.reason_codes.join(', ')}`);
  }
} catch (error) {
  console.error('Policy evaluation failed:', error);
}

​
Performance

TealEngine targets:
  • < 10ms per evaluation (p99, without external calls)
  • < 50ms with caching (p99, cache hit)
  • Deterministic results (same inputs → same outputs)

​
Best Practices

​
Always Provide Context

// ❌ Bad: No context
const decision = await engine.evaluate(request);

// ✅ Good: Always provide context
const context = ExecutionContext.create({ actor });
const decision = await engine.evaluate(request, context);

​
Use Appropriate Modes

// ✅ Good: Gradual rollout
const engine = new TealEngine({
  policies: newPolicies,
  mode: {
    default: PolicyMode.MONITOR, // Start with monitoring
    environment: {
      'production': PolicyMode.ENFORCE // Enforce in prod after testing
    }
  }
});

​
Handle Denials Gracefully

const decision = await engine.evaluate(request, context);

if (decision.action === DecisionAction.DENY) {
  // Log for investigation
  logger.warn('Request denied', {
    correlation_id: decision.correlation_id,
    reason: decision.reason,
    risk_score: decision.risk_score
  });
  
  // Return user-friendly error
  throw new PolicyViolationError(
    'This action is not allowed by policy'
  );
}