TealState

class TealState {
  constructor(options: StateOptions);

  /** Evaluate a context mutation (add/update/remove) */
  evaluateMutation(mutation: ContextMutation, ctx: StateContext): Promise<MutationDecision>;

  /** Get current context size and budget */
  getContextBudget(agentId: string): Promise<ContextBudget>;

  /** Get provenance for a specific context entry */
  getProvenance(entryId: string): Promise<ProvenanceRecord>;

  /** Audit full context state */
  auditContext(agentId: string): Promise<ContextAudit>;
}

interface StateOptions {
  /** Enable context size governance */
  sizeGovernance: {
    enabled: boolean;
    /** Maximum context size in tokens */
    maxTokens: number;
    /** Warning threshold (percentage of max) */
    warningThreshold: number;  // e.g., 0.8 = warn at 80%
    /** Action when limit exceeded */
    onExceeded: 'deny' | 'truncate_oldest' | 'truncate_lowest_priority';
  };

  /** Enable provenance tracking */
  provenance: {
    enabled: boolean;
    /** Require source attribution for all entries */
    requireSource: boolean;
    /** Trust levels for different sources */
    trustLevels: Record<string, 'trusted' | 'verified' | 'unverified' | 'untrusted'>;
  };

  /** Context entry TTL */
  ttl?: {
    enabled: boolean;
    /** Default TTL for entries without explicit TTL */
    defaultTTL: string;  // '1h', '24h', etc.
    /** TTL by source type */
    bySource?: Record<string, string>;
  };

  /** Mutation governance */
  mutations?: {
    /** Require justification for context modifications */
    requireJustification: boolean;
    /** Maximum entries per agent */
    maxEntries: number;
    /** Allowed mutation types */
    allowedMutations: ('add' | 'update' | 'remove')[];
  };
}

import { TealState } from 'tealtiger/state';

const state = new TealState({
  sizeGovernance: {
    enabled: true,
    maxTokens: 8192,
    warningThreshold: 0.8,
    onExceeded: 'deny'
  },
  provenance: {
    enabled: true,
    requireSource: true,
    trustLevels: {
      'system': 'trusted',
      'user': 'verified',
      'tool_output': 'verified',
      'web_search': 'unverified',
      'agent_generated': 'unverified'
    }
  }
});

const decision = await state.evaluateMutation(
  {
    type: 'add',
    entry: {
      id: 'ctx-entry-001',
      content: 'Customer account balance: $4,521.00',
      source: 'tool_output',
      tool: 'account_lookup',
      tokens: 12,
      priority: 'high',
      ttl: '30m'
    }
  },
  {
    agentId: 'support-bot-001',
    correlation_id: 'req-001',
    currentContextTokens: 6000
  }
);

console.log(decision.allowed);        // true
console.log(decision.newContextSize); // 6012 tokens
console.log(decision.budgetRemaining); // 2180 tokens
console.log(decision.provenance);     // { source: 'tool_output', trust: 'verified' }

interface ContextMutation {
  /** Mutation type */
  type: 'add' | 'update' | 'remove';

  /** The context entry being mutated */
  entry: ContextEntry;

  /** Justification for the mutation (if required) */
  justification?: string;
}

interface ContextEntry {
  /** Unique entry identifier */
  id: string;

  /** Content of the entry */
  content: string;

  /** Source of this content */
  source: string;

  /** Tool that produced this content (if applicable) */
  tool?: string;

  /** Token count */
  tokens: number;

  /** Priority for eviction decisions */
  priority: 'critical' | 'high' | 'medium' | 'low';

  /** Time-to-live */
  ttl?: string;

  /** Custom metadata */
  metadata?: Record<string, unknown>;
}

interface MutationDecision {
  /** Whether the mutation is allowed */
  allowed: boolean;

  /** Reason for denial (if not allowed) */
  reason?: string;

  /** Reason codes */
  reason_codes: string[];

  /** New context size after mutation (if allowed) */
  newContextSize?: number;

  /** Remaining budget */
  budgetRemaining?: number;

  /** Provenance record created */
  provenance?: ProvenanceRecord;

  /** Warnings (e.g., approaching size limit) */
  warnings?: string[];
}

const state = new TealState({
  sizeGovernance: {
    enabled: true,
    maxTokens: 8192,
    warningThreshold: 0.8,
    onExceeded: 'truncate_lowest_priority'
  }
});

// When context is at 95% capacity and a new entry arrives:
const decision = await state.evaluateMutation(
  { type: 'add', entry: { content: '...', tokens: 500, priority: 'medium' } },
  { agentId: 'bot-001', currentContextTokens: 7800 }
);

// With 'truncate_lowest_priority':
// decision.allowed === true
// decision.evicted === ['ctx-entry-old-1', 'ctx-entry-old-2']  // Low-priority entries removed
// decision.newContextSize === 7200 (after eviction + addition)

interface ProvenanceRecord {
  /** Entry this provenance belongs to */
  entryId: string;

  /** Source of the content */
  source: string;

  /** Trust level assigned to this source */
  trustLevel: 'trusted' | 'verified' | 'unverified' | 'untrusted';

  /** When the entry was added */
  addedAt: string;

  /** Who/what added it */
  addedBy: string;

  /** Tool that produced it (if applicable) */
  tool?: string;

  /** Original request correlation ID */
  correlationId: string;

  /** Content hash for integrity verification */
  contentHash: string;

  /** TTL expiry time */
  expiresAt?: string;

  /** Modification history */
  modifications: ProvenanceModification[];
}

// Get provenance for a specific entry
const prov = await state.getProvenance('ctx-entry-001');
console.log(prov.source);      // 'tool_output'
console.log(prov.trustLevel);  // 'verified'
console.log(prov.addedAt);     // '2026-06-01T14:30:00Z'
console.log(prov.tool);        // 'account_lookup'

// Audit full context
const audit = await state.auditContext('support-bot-001');
console.log(audit.totalEntries);       // 42
console.log(audit.totalTokens);        // 6012
console.log(audit.byTrustLevel);       // { trusted: 5, verified: 30, unverified: 7 }
console.log(audit.expiringSoon);       // 3 entries expiring within 5 minutes
console.log(audit.untrustedEntries);   // Entries from untrusted sources

const budget = await state.getContextBudget('support-bot-001');

console.log(budget.maxTokens);        // 8192
console.log(budget.usedTokens);       // 6012
console.log(budget.remainingTokens);  // 2180
console.log(budget.utilizationPct);   // 73.4
console.log(budget.warning);          // false (below 80% threshold)
console.log(budget.entries);          // 42
console.log(budget.oldestEntry);      // '2026-06-01T14:00:00Z'
console.log(budget.newestEntry);      // '2026-06-01T14:45:00Z'

import { TealEngine, TealState } from 'tealtiger';

const engine = new TealEngine({
  policy: {
    state: {
      sizeGovernance: { enabled: true, maxTokens: 8192, onExceeded: 'deny' },
      provenance: { enabled: true, requireSource: true },
      ttl: { enabled: true, defaultTTL: '1h' }
    }
  },
  modules: [
    new TealState({
      sizeGovernance: { enabled: true, maxTokens: 8192, warningThreshold: 0.8, onExceeded: 'deny' },
      provenance: { enabled: true, requireSource: true, trustLevels: { system: 'trusted', user: 'verified' } }
    })
  ]
});