TealTemporal

class TealTemporal {
  constructor(options: TemporalOptions);

  /** Evaluate temporal constraints for a request */
  evaluate(request: TemporalRequest, ctx: TemporalContext): Promise<TemporalDecision>;

  /** Check if an agent's session is still valid */
  checkSession(agentId: string, sessionId: string): Promise<SessionStatus>;

  /** Record an action for cooldown tracking */
  recordAction(agentId: string, action: string): Promise<void>;

  /** Get remaining cooldown for an action */
  getCooldown(agentId: string, action: string): Promise<CooldownStatus>;
}

interface TemporalOptions {
  /** Session TTL configuration */
  session: {
    enabled: boolean;
    /** Default session duration */
    defaultTTL: string;  // '8h', '30m', '24h'
    /** Maximum session duration (hard cap) */
    maxTTL: string;
    /** Action on session expiry */
    onExpiry: 'deny' | 'require_reauth' | 'warn';
    /** Grace period after expiry for in-flight requests */
    gracePeriod?: string;
  };

  /** Cooldown configuration */
  cooldown: {
    enabled: boolean;
    /** Per-action cooldown rules */
    rules: CooldownRule[];
    /** Action on cooldown violation */
    onViolation: 'deny' | 'queue' | 'warn';
  };

  /** Time-of-day restrictions */
  timeRestrictions: {
    enabled: boolean;
    /** Timezone for evaluating restrictions */
    timezone: string;
    /** Restriction rules */
    rules: TimeRestrictionRule[];
    /** Action outside allowed windows */
    onViolation: 'deny' | 'queue_until_window' | 'approval_required';
  };
}

import { TealTemporal } from 'tealtiger/temporal';

const temporal = new TealTemporal({
  session: {
    enabled: true,
    defaultTTL: '8h',
    maxTTL: '24h',
    onExpiry: 'deny',
    gracePeriod: '30s'
  }
});

// Check session validity
const status = await temporal.checkSession('agent-001', 'sess-abc');
console.log(status.valid);          // true
console.log(status.remainingTTL);   // '2h 15m'
console.log(status.startedAt);      // '2026-06-01T08:00:00Z'
console.log(status.expiresAt);      // '2026-06-01T16:00:00Z'

// After session expires:
const expired = await temporal.checkSession('agent-001', 'sess-abc');
console.log(expired.valid);         // false
console.log(expired.reason);        // 'SESSION_TTL_EXPIRED'
console.log(expired.expiredAt);     // '2026-06-01T16:00:00Z'

interface SessionStatus {
  /** Whether the session is still valid */
  valid: boolean;

  /** Remaining TTL (if valid) */
  remainingTTL?: string;

  /** When the session started */
  startedAt: string;

  /** When the session expires */
  expiresAt: string;

  /** Reason for invalidity (if not valid) */
  reason?: 'SESSION_TTL_EXPIRED' | 'SESSION_REVOKED' | 'SESSION_NOT_FOUND';

  /** Whether in grace period */
  inGracePeriod?: boolean;
}

const temporal = new TealTemporal({
  cooldown: {
    enabled: true,
    rules: [
      {
        action: 'payment.refund',
        cooldown: '5m',
        scope: 'per_agent'  // Each agent has independent cooldown
      },
      {
        action: 'database.write',
        cooldown: '10s',
        scope: 'per_session'
      },
      {
        action: 'file.delete',
        cooldown: '30s',
        scope: 'per_agent',
        maxPerWindow: { count: 5, window: '1h' }  // Max 5 deletes per hour
      }
    ],
    onViolation: 'deny'
  }
});

// First refund — allowed
await temporal.recordAction('agent-001', 'payment.refund');

// Immediate retry — denied (cooldown active)
const cooldown = await temporal.getCooldown('agent-001', 'payment.refund');
console.log(cooldown.active);        // true
console.log(cooldown.remainingTime); // '4m 58s'
console.log(cooldown.nextAllowed);   // '2026-06-01T14:35:00Z'

interface CooldownRule {
  /** Action pattern (supports wildcards) */
  action: string;

  /** Minimum time between actions */
  cooldown: string;

  /** Cooldown scope */
  scope: 'per_agent' | 'per_session' | 'global';

  /** Maximum actions per time window (rate limiting) */
  maxPerWindow?: {
    count: number;
    window: string;
  };

  /** Exempt agents (e.g., admin bots) */
  exempt?: string[];
}

interface CooldownStatus {
  /** Whether cooldown is currently active */
  active: boolean;

  /** Remaining cooldown time */
  remainingTime?: string;

  /** When the next action is allowed */
  nextAllowed?: string;

  /** Actions performed in current window */
  actionsInWindow?: number;

  /** Maximum actions allowed in window */
  maxInWindow?: number;
}

const temporal = new TealTemporal({
  timeRestrictions: {
    enabled: true,
    timezone: 'America/New_York',
    rules: [
      {
        name: 'business-hours-only',
        actions: ['payment.*', 'database.migrate', 'deployment.*'],
        allowedWindows: [
          { days: ['mon', 'tue', 'wed', 'thu', 'fri'], start: '09:00', end: '17:00' }
        ]
      },
      {
        name: 'no-deployments-friday-afternoon',
        actions: ['deployment.*'],
        deniedWindows: [
          { days: ['fri'], start: '14:00', end: '23:59' }
        ]
      },
      {
        name: 'maintenance-window',
        actions: ['database.migrate', 'system.update'],
        allowedWindows: [
          { days: ['sat'], start: '02:00', end: '06:00' }
        ]
      }
    ],
    onViolation: 'deny'
  }
});

// At 3 PM on Friday:
const decision = await temporal.evaluate(
  { action: 'deployment.production' },
  { agentId: 'deploy-bot', correlation_id: 'req-001' }
);

// decision.allowed === false
// decision.reason === 'TIME_RESTRICTION_VIOLATED'
// decision.restriction === 'no-deployments-friday-afternoon'
// decision.nextAllowedWindow === 'Mon 09:00 ET'

interface TimeRestrictionRule {
  /** Rule name */
  name: string;

  /** Actions this rule applies to (supports wildcards) */
  actions: string[];

  /** Time windows when actions ARE allowed */
  allowedWindows?: TimeWindow[];

  /** Time windows when actions are NOT allowed (takes precedence) */
  deniedWindows?: TimeWindow[];
}

interface TimeWindow {
  /** Days of the week */
  days: ('mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun')[];

  /** Start time (HH:MM, 24-hour) */
  start: string;

  /** End time (HH:MM, 24-hour) */
  end: string;
}

const decision = await temporal.evaluate(
  {
    action: 'payment.refund',
    sessionId: 'sess-abc',
    metadata: { amount: 250 }
  },
  {
    agentId: 'support-bot-001',
    correlation_id: 'req-001',
    timestamp: Date.now()
  }
);

console.log(decision.allowed);           // false
console.log(decision.violations);        // ['COOLDOWN_ACTIVE']
console.log(decision.sessionValid);      // true
console.log(decision.cooldownActive);    // true
console.log(decision.timeWindowValid);   // true
console.log(decision.details.cooldown.remainingTime); // '3m 22s'

interface TemporalDecision {
  /** Whether all temporal constraints pass */
  allowed: boolean;

  /** Which constraints were violated */
  violations: string[];

  /** Session validity check result */
  sessionValid: boolean;

  /** Whether a cooldown is blocking */
  cooldownActive: boolean;

  /** Whether current time is within allowed window */
  timeWindowValid: boolean;

  /** Detailed results per constraint type */
  details: {
    session?: SessionStatus;
    cooldown?: CooldownStatus;
    timeWindow?: { rule: string; nextAllowed: string };
  };
}

import { TealEngine, TealTemporal } from 'tealtiger';

const engine = new TealEngine({
  policy: {
    temporal: {
      session: { defaultTTL: '8h', maxTTL: '24h', onExpiry: 'deny' },
      cooldown: {
        rules: [
          { action: 'payment.*', cooldown: '5m', scope: 'per_agent' }
        ]
      },
      timeRestrictions: {
        timezone: 'UTC',
        rules: [
          { name: 'business-hours', actions: ['payment.*'], allowedWindows: [{ days: ['mon','tue','wed','thu','fri'], start: '08:00', end: '18:00' }] }
        ]
      }
    }
  },
  modules: [new TealTemporal({ /* ... */ })]
});