agentgate-runtime-control 2.13.8

package/src/observability.js

@@ -0,0 +1,395 @@
+/**
+ * AgentGate Observability + Cost Control + Security-Aware Analytics.
+ * Deterministic analytics over runtime runs; no LLM is used for scoring or authorization.
+ */
+
+import { analyzeBehavior } from './behavior.js';
+
+export const COST_DECISIONS = Object.freeze({ ALLOW: 'ALLOW', ASK: 'ASK', BLOCK: 'BLOCK' });
+
+const DEFAULT_PRICING = Object.freeze({});
+
+export class PricingRegistry {
+  constructor(pricing = {}) { this.pricing = { ...DEFAULT_PRICING, ...normalizePricingMap(pricing) }; }
+  set(model, price = {}) {
+    const name = String(model || '').trim();
+    if (!name) throw new TypeError('Model name is required');
+    this.pricing[name] = normalizePrice(price);
+    return this.pricing[name];
+  }
+  get(model) { return this.pricing[String(model || '')] || null; }
+  list() { return structuredCloneSafe(this.pricing); }
+}
+
+export function calculateCost(input = {}, pricing = {}) {
+  const usage = normalizeUsage(input.usage || input);
+  const model = input.model || input.usage?.model || null;
+  const price = input.price || pricing[model] || null;
+  if (!price) return { currency: 'USD', total: 0, known: false, model, usage };
+  const inputRate = Number(price.inputPer1M ?? price.input ?? 0);
+  const outputRate = Number(price.outputPer1M ?? price.output ?? 0);
+  const cachedRate = Number(price.cachedInputPer1M ?? price.cachedInput ?? 0);
+  const inputTokens = Math.max(0, usage.inputTokens - usage.cachedInputTokens);
+  const cachedTokens = Math.max(0, usage.cachedInputTokens);
+  const outputTokens = Math.max(0, usage.outputTokens);
+  const total = (inputTokens / 1_000_000) * inputRate +
+    (cachedTokens / 1_000_000) * cachedRate +
+    (outputTokens / 1_000_000) * outputRate;
+  return {
+    currency: price.currency || 'USD',
+    total: roundMoney(total),
+    known: true,
+    model,
+    usage,
+    rates: { inputPer1M: inputRate, outputPer1M: outputRate, cachedInputPer1M: cachedRate }
+  };
+}
+
+export class CostController {
+  constructor(options = {}) {
+    this.budgets = normalizeBudgets(options.budgets || {});
+    this.events = [];
+    this.maxEvents = options.maxEvents || 5000;
+  }
+  configure(budgets = {}) { this.budgets = normalizeBudgets(budgets); return this.budgets; }
+  record(run, cost = {}) {
+    const amount = Number(cost.total || 0);
+    const event = {
+      runId: run.id,
+      tenantId: run.tenantId || null,
+      agent: run.request?.agent || 'unknown',
+      cost: amount,
+      currency: cost.currency || 'USD',
+      at: run.createdAt || new Date().toISOString()
+    };
+    this.events.unshift(event);
+    if (this.events.length > this.maxEvents) this.events.pop();
+    return event;
+  }
+  evaluate({ tenantId = null, agent = null, estimatedCost = 0, now = new Date(), history = null } = {}) {
+    const amount = Math.max(0, Number(estimatedCost) || 0);
+    const daily = this.spent({ tenantId, agent, period: 'daily', now, history }) + amount;
+    const monthly = this.spent({ tenantId, agent, period: 'monthly', now, history }) + amount;
+    const d = this.budgets.daily;
+    const m = this.budgets.monthly;
+    if ((d.hard > 0 && daily > d.hard) || (m.hard > 0 && monthly > m.hard)) {
+      return { decision: COST_DECISIONS.BLOCK, reason: 'Cost budget would be exceeded', daily, monthly };
+    }
+    if ((d.ask > 0 && daily > d.ask) || (m.ask > 0 && monthly > m.ask)) {
+      return { decision: COST_DECISIONS.ASK, reason: 'Cost approval threshold reached', daily, monthly };
+    }
+    return { decision: COST_DECISIONS.ALLOW, reason: 'Cost budget within configured thresholds', daily, monthly };
+  }
+  spent({ tenantId = null, agent = null, period = 'daily', now = new Date(), history = null } = {}) {
+    const date = now instanceof Date ? now : new Date(now);
+    const start = period === 'monthly'
+      ? new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1))
+      : new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+    if (Array.isArray(history)) {
+      return history.filter(r => new Date(r.createdAt) >= start && (!tenantId || r.tenantId === tenantId) && (!agent || (r.request?.agent || 'unknown') === agent))
+        .reduce((sum, r) => sum + Number(r.cost?.total || 0), 0);
+    }
+    return this.events.filter(e => new Date(e.at) >= start && (!tenantId || e.tenantId === tenantId) && (!agent || e.agent === agent))
+      .reduce((sum, e) => sum + Number(e.cost || 0), 0);
+  }
+  snapshot({ tenantId = null, agent = null, now = new Date(), history = null } = {}) {
+    const daily = this.spent({ tenantId, agent, period: 'daily', now, history });
+    const monthly = this.spent({ tenantId, agent, period: 'monthly', now, history });
+    return {
+      currency: 'USD',
+      daily: roundMoney(daily),
+      monthly: roundMoney(monthly),
+      budgets: structuredCloneSafe(this.budgets),
+      remaining: {
+        daily: remaining(this.budgets.daily.hard, daily),
+        monthly: remaining(this.budgets.monthly.hard, monthly)
+      }
+    };
+  }
+}
+
+/**
+ * Full deterministic observability report. The report intentionally joins
+ * runtime, cost, security and behavior data instead of treating traces as logs.
+ */
+export function analyzeObservability(runs = [], options = {}) {
+  const list = Array.isArray(runs) ? runs : [];
+  const latencies = list.map(r => Number(r.durationMs)).filter(Number.isFinite).sort((a, b) => a - b);
+  const decisions = countBy(list, r => r.decision || 'UNKNOWN');
+  const tools = groupStats(list, r => r.request?.tool || r.request?.action || 'unknown');
+  const agents = groupStats(list, r => r.request?.agent || 'unknown');
+  const models = groupStats(list, r => r.request?.model || r.cost?.model || 'unknown');
+  const security = {
+    blocked: decisions.BLOCK || 0,
+    approvalRequired: decisions.ASK || 0,
+    egressBlocked: list.filter(r => r.egressBlocked).length,
+    egressRedacted: list.filter(r => r.egress?.action === 'REDACT').length,
+    highRisk: list.filter(r => Number(r.risk) >= 70).length,
+    criticalRisk: list.filter(r => Number(r.risk) >= 90).length
+  };
+  const costs = list.map(r => Number(r.cost?.total || 0)).filter(Number.isFinite);
+  const knownCosts = list.filter(r => r.cost?.known);
+  const behavior = analyzeBehavior(list, options.behavior || {});
+  const costAnalytics = analyzeCostAnalytics(list, options);
+  const efficiency = analyzeAgentEfficiency(list, options);
+  const forecast = forecastCost(list, options);
+  const correlation = correlateBehaviorCostSecurity(list, behavior);
+  const traces = list.map(buildUnifiedTrace);
+
+  return {
+    runs: list.length,
+    decisions,
+    successRate: list.length ? round((list.filter(r => r.executed && !r.error && !r.egressBlocked).length / list.length) * 100, 2) : 0,
+    errorRate: list.length ? round((list.filter(r => r.error).length / list.length) * 100, 2) : 0,
+    latency: percentileSummary(latencies),
+    security,
+    cost: {
+      total: roundMoney(costs.reduce((a, b) => a + b, 0)),
+      average: costs.length ? roundMoney(costs.reduce((a, b) => a + b, 0) / costs.length) : 0,
+      knownRuns: knownCosts.length,
+      unknownRuns: list.length - knownCosts.length,
+      currency: options.currency || 'USD'
+    },
+    tools,
+    agents,
+    models,
+    efficiency,
+    forecast,
+    behavior,
+    correlation,
+    costAnalytics,
+    traces,
+    generatedAt: new Date().toISOString()
+  };
+}
+
+/** Build the security-aware trace shown by AgentGate instead of a generic log trace. */
+export function buildUnifiedTrace(run = {}) {
+  const request = run.request || {};
+  const events = [];
+  const at = run.createdAt || new Date().toISOString();
+  const add = (stage, detail, status = 'INFO') => events.push({ stage, status, detail });
+
+  add('LLM', { agent: request.agent || 'unknown', model: request.model || run.cost?.model || 'unknown', usage: run.cost?.usage || request.usage || null });
+  add('TOOL', { tool: request.tool || request.action || 'unknown', action: request.action || request.tool || 'unknown', amount: request.amount ?? null });
+  add('POLICY', { decision: run.decision || 'UNKNOWN', risk: Number(run.risk || 0), reason: run.reason || null });
+
+  if (run.approvalId || run.approval || run.status === 'pending_approval' || run.decision === 'ASK') {
+    const approvalStatus = run.approval?.status || (run.status === 'pending_approval' ? 'PENDING' : 'REQUIRED');
+    add('HUMAN_APPROVAL', { approvalId: run.approvalId || null, status: approvalStatus }, approvalStatus === 'APPROVED' ? 'PASS' : 'CONTROL');
+  }
+
+  if (run.executed) add('TOOL_EXECUTION', { status: run.error ? 'ERROR' : 'EXECUTED', latencyMs: run.durationMs ?? null });
+  if (run.egress) add('RESPONSE_EGRESS', { action: run.egress.action, findings: run.egress.findings || [], risk: run.egress.risk || 0 }, run.egress.action === 'BLOCK' ? 'BLOCK' : run.egress.action === 'REDACT' ? 'CONTROL' : 'PASS');
+  if (run.error) add('ERROR', { message: run.error }, 'ERROR');
+
+  const behaviorStatus = Number(run.behaviorRisk || run.risk || 0) >= 70 ? 'HIGH_RISK' : 'NORMAL';
+  add('BEHAVIOR', { status: behaviorStatus, risk: Number(run.behaviorRisk || 0) || null });
+  add('COST', { amount: Number(run.cost?.total || 0), currency: run.cost?.currency || 'USD', known: Boolean(run.cost?.known), budget: run.cost?.budget || null });
+
+  return {
+    runId: run.id || null,
+    agent: request.agent || 'unknown',
+    model: request.model || run.cost?.model || null,
+    tenantId: run.tenantId || null,
+    decision: run.decision || 'UNKNOWN',
+    risk: Number(run.risk || 0),
+    status: run.status || (run.executed ? 'executed' : 'decided'),
+    latencyMs: Number.isFinite(Number(run.durationMs)) ? Number(run.durationMs) : null,
+    cost: run.cost || { total: 0, known: false },
+    security: {
+      policyDecision: run.decision || 'UNKNOWN',
+      egress: run.egress || null,
+      egressBlocked: Boolean(run.egressBlocked),
+      approvalId: run.approvalId || null,
+      risk: Number(run.risk || 0)
+    },
+    events,
+    createdAt: at
+  };
+}
+
+/**
+ * Deterministic Agent Efficiency score. Formula is deliberately transparent:
+ * success 30%, error-free reliability 20%, tool economy 15%, latency 15%,
+ * control friction 10%, cost efficiency 10%. No model/LLM judgment is used.
+ */
+export function calculateAgentEfficiency(runs = [], agent = null, options = {}) {
+  const scoped = (runs || []).filter(r => !agent || (r.request?.agent || 'unknown') === agent);
+  if (!scoped.length) return { agent: agent || 'unknown', score: 0, status: 'NO_DATA', breakdown: {}, metrics: {} };
+  const success = ratio(scoped, r => r.executed && !r.error && !r.egressBlocked) * 100;
+  const reliability = (1 - ratio(scoped, r => Boolean(r.error))) * 100;
+  const taskCalls = averageToolCallsPerTask(scoped);
+  const toolEconomy = scoreLowerIsBetter(taskCalls, Number(options.idealToolCalls || 4), Number(options.maxToolCalls || 12));
+  const latencies = scoped.map(r => Number(r.durationMs)).filter(Number.isFinite).sort((a,b)=>a-b);
+  const latencyP50 = percentileSummary(latencies).p50;
+  const latencyScore = scoreLowerIsBetter(latencyP50, Number(options.idealLatencyMs || 1000), Number(options.maxLatencyMs || 10000));
+  const approvalRate = ratio(scoped, r => r.decision === 'ASK') * 100;
+  const blockedRate = ratio(scoped, r => r.decision === 'BLOCK') * 100;
+  const controlFriction = clamp(100 - (approvalRate * 0.5) - (blockedRate * 2), 0, 100);
+  const successful = scoped.filter(r => r.executed && !r.error && !r.egressBlocked);
+  const successfulTaskIds = new Set(successful.map(r => taskIdOf(r)));
+  const taskCost = new Map();
+  for (const r of successful) taskCost.set(taskIdOf(r), (taskCost.get(taskIdOf(r)) || 0) + Number(r.cost?.total || 0));
+  const totalCost = [...taskCost.values()].reduce((s,r)=>s+r,0);
+  const costPerSuccess = successfulTaskIds.size ? totalCost / successfulTaskIds.size : 0;
+  const peerCosts = (runs || []).filter(r => r.executed && !r.error && !r.egressBlocked).map(r => Number(r.cost?.total||0)).filter(Number.isFinite).sort((a,b)=>a-b);
+  const peerMedian = peerCosts.length ? percentile(peerCosts, .5) : costPerSuccess;
+  const costEfficiency = peerMedian > 0 ? clamp(100 * (peerMedian / Math.max(costPerSuccess, 0.000001)), 0, 100) : (costPerSuccess === 0 ? 100 : 50);
+  const score = round(success*0.30 + reliability*0.20 + toolEconomy*0.15 + latencyScore*0.15 + controlFriction*0.10 + costEfficiency*0.10, 1);
+  return {
+    agent: agent || scoped[0]?.request?.agent || 'unknown',
+    score,
+    status: score >= 80 ? 'HEALTHY' : score >= 60 ? 'ATTENTION' : 'DEGRADED',
+    breakdown: { success: round(success), reliability: round(reliability), toolEconomy: round(toolEconomy), latency: round(latencyScore), controlFriction: round(controlFriction), costEfficiency: round(costEfficiency) },
+    metrics: { runs: scoped.length, successRate: round(success), successfulTasks: successfulTaskIds.size, avgToolCalls: round(taskCalls,2), p50LatencyMs: latencyP50, approvalRate: round(approvalRate), blockedRate: round(blockedRate), retryRate: round(ratio(scoped, r => Number(r.request?.retryCount || 0) > 0)*100), costPerSuccessfulTask: roundMoney(costPerSuccess) }
+  };
+}
+
+export function analyzeAgentEfficiency(runs = [], options = {}) {
+  const agents = [...new Set(runs.map(r => r.request?.agent || 'unknown'))];
+  const byAgent = Object.fromEntries(agents.map(agent => [agent, calculateAgentEfficiency(runs, agent, options)]));
+  return { byAgent, overall: calculateAgentEfficiency(runs, null, options) };
+}
+
+/** Forecast uses deterministic month-to-date daily run-rate; no probabilistic model. */
+export function forecastCost(runs = [], options = {}) {
+  const now = options.now ? new Date(options.now) : new Date();
+  const monthStart = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+  const nextMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth()+1, 1));
+  const daysInMonth = Math.round((nextMonth - monthStart) / 86400000);
+  const elapsedDays = Math.max(1, Math.min(daysInMonth, Math.floor((now - monthStart) / 86400000) + 1));
+  const monthly = runs.filter(r => new Date(r.createdAt || 0) >= monthStart).reduce((s,r)=>s+Number(r.cost?.total||0),0);
+  const dailyRate = monthly / elapsedDays;
+  const forecast = dailyRate * daysInMonth;
+  const budget = Number(options.monthlyBudget || 0);
+  return { currency: options.currency || 'USD', monthToDate: roundMoney(monthly), elapsedDays, daysInMonth, dailyRunRate: roundMoney(dailyRate), forecast: roundMoney(forecast), budget: budget > 0 ? budget : null, varianceVsBudget: budget > 0 ? roundMoney(forecast - budget) : null, method: 'month-to-date daily run-rate' };
+}
+
+/** Correlates behavior findings with cost, tool volume and security outcomes. */
+export function correlateBehaviorCostSecurity(runs = [], behavior = null) {
+  const report = behavior || analyzeBehavior(runs);
+  const anomalyIds = new Set((report.findings || []).map(f => f.runId).filter(Boolean));
+  const anomalous = runs.filter(r => anomalyIds.has(r.id));
+  const normal = runs.filter(r => !anomalyIds.has(r.id));
+  const cost = xs => xs.reduce((s,r)=>s+Number(r.cost?.total||0),0);
+  const avg = (xs, fn) => xs.length ? fn(xs)/xs.length : 0;
+  const toolRate = xs => xs.length;
+  const blocked = anomalous.filter(r => r.decision === 'BLOCK').length;
+  const asked = anomalous.filter(r => r.decision === 'ASK').length;
+  const anomalyCost = cost(anomalous);
+  const normalCost = cost(normal);
+  return {
+    anomalyRuns: anomalous.length,
+    normalRuns: normal.length,
+    anomalyCost: roundMoney(anomalyCost),
+    normalCost: roundMoney(normalCost),
+    avgAnomalyCost: roundMoney(avg(anomalous, cost)),
+    avgNormalCost: roundMoney(avg(normal, cost)),
+    costDeltaPercent: normalCost > 0 && anomalous.length ? round(((anomalyCost / anomalous.length) / Math.max(normalCost / Math.max(normal.length,1),0.000001) - 1) * 100) : null,
+    blockedAnomalyRuns: blocked,
+    approvalAnomalyRuns: asked,
+    toolCallDelta: anomalous.length && normal.length ? round((toolRate(anomalous) / anomalous.length - toolRate(normal) / normal.length), 2) : null,
+    securityCorrelation: {
+      status: blocked > 0 || asked > 0 ? 'CONTROLLED_ANOMALY' : anomalous.length ? 'BEHAVIOR_ANOMALY' : 'NORMAL',
+      findings: (report.findings || []).slice(0, 20).map(f => ({ id:f.id, title:f.title, risk:f.risk, runId:f.runId, agent:f.agent }))
+    }
+  };
+}
+
+export function analyzeCostAnalytics(runs = [], options = {}) {
+  const group = (keyFn) => {
+    const map = new Map();
+    for (const r of runs) {
+      const key = keyFn(r) || 'unknown';
+      const x = map.get(key) || { runs:0, cost:0, blocked:0, approvals:0, errors:0, tokens:0 };
+      x.runs++;
+      x.cost += Number(r.cost?.total||0);
+      x.blocked += r.decision === 'BLOCK' ? 1 : 0;
+      x.approvals += r.decision === 'ASK' ? 1 : 0;
+      x.errors += r.error ? 1 : 0;
+      x.tokens += Number(r.cost?.usage?.totalTokens || 0);
+      map.set(key,x);
+    }
+    return Object.fromEntries([...map].map(([k,v])=>[k,{...v,cost:roundMoney(v.cost),avgCost:roundMoney(v.cost/v.runs)}]));
+  };
+  const successful = runs.filter(r=>r.executed&&!r.error&&!r.egressBlocked);
+  const securityCost = {
+    blockedCalls: roundMoney(runs.filter(r=>r.decision==='BLOCK').reduce((s,r)=>s+Number(r.cost?.total||0),0)),
+    approvalCalls: roundMoney(runs.filter(r=>r.decision==='ASK').reduce((s,r)=>s+Number(r.cost?.total||0),0)),
+    attackTests: roundMoney(runs.filter(r=>r.request?.attackTest===true || r.attackTest===true).reduce((s,r)=>s+Number(r.cost?.total||0),0)),
+    egressBlocks: roundMoney(runs.filter(r=>r.egressBlocked).reduce((s,r)=>s+Number(r.cost?.total||0),0))
+  };
+  return {
+    byAgent: group(r=>r.request?.agent),
+    byModel: group(r=>r.request?.model || r.cost?.model),
+    byTool: group(r=>r.request?.tool || r.request?.action),
+    byTenant: group(r=>r.tenantId),
+    byCustomer: group(r=>r.request?.customerId || r.request?.userId || r.request?.identity?.userId),
+    byAction: group(r=>r.request?.action || r.request?.tool),
+    securityCost,
+    successfulTaskCost: successful.length ? roundMoney(successful.reduce((s,r)=>s+Number(r.cost?.total||0),0)/successful.length) : 0,
+    totalTokens: runs.reduce((s,r)=>s+Number(r.cost?.usage?.totalTokens||0),0),
+    currency: options.currency || 'USD'
+  };
+}
+
+export function createObservability(options = {}) {
+  const pricing = new PricingRegistry(options.pricing || {});
+  const costControl = options.costControl || new CostController({ budgets: options.budgets, maxEvents: options.maxCostEvents });
+  const recordedRuns = new Set();
+  function enrichRun(run = {}) {
+    const usage = run.usage || run.request?.usage || null;
+    const model = run.model || run.request?.model || usage?.model || null;
+    const cost = calculateCost({ model, usage, price: run.price }, pricing.list());
+    run.cost = { ...run.cost, ...cost };
+    if (cost.known && run.id && !recordedRuns.has(run.id)) { costControl.record(run, cost); recordedRuns.add(run.id); }
+    return run;
+  }
+  return {
+    pricing,
+    costControl,
+    enrichRun,
+    analyze: runs => analyzeObservability(runs, options),
+    trace: run => buildUnifiedTrace(run),
+    efficiency: (runs, opts) => analyzeAgentEfficiency(runs, opts || options.efficiency),
+    forecast: (runs, opts) => forecastCost(runs, opts || options.forecast),
+    correlation: runs => correlateBehaviorCostSecurity(runs),
+    costAnalytics: (runs, opts) => analyzeCostAnalytics(runs, opts || {})
+  };
+}
+
+function normalizePricingMap(input) { return Object.fromEntries(Object.entries(input || {}).map(([k,v]) => [k, normalizePrice(v)])); }
+function normalizePrice(price = {}) { return { currency: price.currency || 'USD', inputPer1M: Number(price.inputPer1M ?? price.input ?? 0), outputPer1M: Number(price.outputPer1M ?? price.output ?? 0), cachedInputPer1M: Number(price.cachedInputPer1M ?? price.cachedInput ?? 0) }; }
+function normalizeUsage(usage = {}) {
+  const inputTokens = Number(usage.inputTokens ?? usage.promptTokens ?? usage.input_tokens ?? 0) || 0;
+  const outputTokens = Number(usage.outputTokens ?? usage.completionTokens ?? usage.output_tokens ?? 0) || 0;
+  const cachedInputTokens = Number(usage.cachedInputTokens ?? usage.cacheReadTokens ?? usage.cached_input_tokens ?? 0) || 0;
+  return { inputTokens, outputTokens, cachedInputTokens, totalTokens: Number(usage.totalTokens ?? usage.total_tokens ?? inputTokens + outputTokens) || 0 };
+}
+function normalizeBudgets(input = {}) { const normalize = x => ({ ask: Math.max(0, Number(x?.ask ?? 0) || 0), hard: Math.max(0, Number(x?.hard ?? x?.block ?? 0) || 0) }); return { daily: normalize(input.daily), monthly: normalize(input.monthly) }; }
+function remaining(limit, spent) { return limit > 0 ? roundMoney(Math.max(0, limit - spent)) : null; }
+function countBy(items, fn) { return items.reduce((m, x) => { const k = fn(x); m[k] = (m[k] || 0) + 1; return m; }, {}); }
+function groupStats(items, keyFn) {
+  const map = new Map();
+  for (const r of items) {
+    const key = keyFn(r); const x = map.get(key) || { runs:0, blocked:0, asked:0, errors:0, cost:0, latency:[] };
+    x.runs++; if (r.decision === 'BLOCK') x.blocked++; if (r.decision === 'ASK') x.asked++; if (r.error) x.errors++;
+    x.cost += Number(r.cost?.total || 0); if (Number.isFinite(Number(r.durationMs))) x.latency.push(Number(r.durationMs)); map.set(key,x);
+  }
+  return Object.fromEntries([...map].map(([k,v])=>[k,{runs:v.runs,blocked:v.blocked,asked:v.asked,errors:v.errors,cost:roundMoney(v.cost),latency:percentileSummary(v.latency.sort((a,b)=>a-b))}]));
+}
+function percentileSummary(values) { if (!values.length) return {count:0,avgMs:0,p50:0,p95:0,p99:0,maxMs:0}; const sum=values.reduce((a,b)=>a+b,0); return {count:values.length,avgMs:round(sum/values.length,3),p50:percentile(values,.5),p95:percentile(values,.95),p99:percentile(values,.99),maxMs:values[values.length-1]}; }
+function percentile(values,p) { const i=(values.length-1)*p,lo=Math.floor(i),hi=Math.ceil(i); return lo===hi?values[lo]:round(values[lo]+(values[hi]-values[lo])*(i-lo),3); }
+function ratio(items,predicate){ return items.length ? items.filter(predicate).length/items.length : 0; }
+function clamp(n,min,max){return Math.max(min,Math.min(max,n));}
+function scoreLowerIsBetter(value,ideal,max){ if(!Number.isFinite(value)||value<=ideal)return 100; if(value>=max)return 0; return 100*(1-(value-ideal)/(max-ideal)); }
+function taskIdOf(r){ return r.request?.context?.taskId || r.request?.taskId || r.request?.sessionId || r.id; }
+function averageToolCallsPerTask(runs){
+  const tasks=new Map();
+  for(const r of runs){const id=taskIdOf(r); tasks.set(id,(tasks.get(id)||0)+1);}
+  return tasks.size ? [...tasks.values()].reduce((a,b)=>a+b,0)/tasks.size : 0;
+}
+function round(n,d=2){const p=10**d;return Math.round((Number(n)||0)*p)/p;}
+function roundMoney(n){return round(n,6);}
+function structuredCloneSafe(v){try{return structuredClone(v);}catch{return JSON.parse(JSON.stringify(v));}}

package/src/oidc.js

@@ -0,0 +1,38 @@
+import crypto from 'node:crypto';
+
+export function mapOIDCClaims(claims={}, options={}) {
+  const rolesClaim=options.rolesClaim||'roles'; const tenantClaim=options.tenantClaim||'tenant_id'; const subjectClaim=options.subjectClaim||'sub';
+  return { userId:claims[subjectClaim]||null, tenantId:claims[tenantClaim]||null, roles:Array.isArray(claims[rolesClaim])?claims[rolesClaim]:[], attributes:{issuer:claims.iss||null,email:claims.email||null}, claims };
+}
+export function validateOIDCIdentity(identity, tenantId){ return Boolean(identity?.userId&&identity?.tenantId&&identity.tenantId===tenantId); }
+
+export function decodeJWT(token) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3) throw new Error('Invalid JWT format');
+  const decode = value => JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+  return { header: decode(parts[0]), payload: decode(parts[1]), signingInput: `${parts[0]}.${parts[1]}`, signature: Buffer.from(parts[2], 'base64url') };
+}
+
+export function verifyOIDCJWT(token, options = {}) {
+  const { header, payload, signingInput, signature } = decodeJWT(token);
+  const algorithms = options.algorithms || ['RS256', 'ES256', 'HS256'];
+  if (!algorithms.includes(header.alg)) throw new Error('JWT algorithm is not allowed');
+  if (options.issuer && payload.iss !== options.issuer) throw new Error('JWT issuer mismatch');
+  if (options.audience) {
+    const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    if (!audiences.includes(options.audience)) throw new Error('JWT audience mismatch');
+  }
+  const now = Math.floor(Date.now() / 1000);
+  const tolerance = Math.max(0, Number(options.clockTolerance || 0));
+  if (payload.exp != null && now >= Number(payload.exp) + tolerance) throw new Error('JWT expired');
+  if (payload.nbf != null && now < Number(payload.nbf) - tolerance) throw new Error('JWT not active');
+  if (options.maxTokenAge != null && payload.iat != null && now - Number(payload.iat) > Number(options.maxTokenAge) + tolerance) throw new Error('JWT too old');
+  const key = options.publicKey || options.secret;
+  if (!key) throw new Error('JWT verification key is required');
+  let valid = false;
+  if (header.alg === 'HS256') { const expected = crypto.createHmac('sha256', key).update(signingInput).digest(); valid = signature.length === expected.length && crypto.timingSafeEqual(signature, expected); }
+  else if (header.alg === 'RS256') valid = crypto.verify('RSA-SHA256', Buffer.from(signingInput), key, signature);
+  else if (header.alg === 'ES256') { if (signature.length !== 64) throw new Error('Invalid ES256 signature'); const r = signature.subarray(0, 32); const sPart = signature.subarray(32); const int = b => { let x = Buffer.from(b); while (x.length > 1 && x[0] === 0) x = x.subarray(1); if (x[0] & 0x80) x = Buffer.concat([Buffer.from([0]), x]); return Buffer.concat([Buffer.from([0x02, x.length]), x]); }; const body = Buffer.concat([int(r), int(sPart)]); const der = Buffer.concat([Buffer.from([0x30, body.length]), body]); valid = crypto.verify('sha256', Buffer.from(signingInput), { key, dsaEncoding: 'der' }, der); }
+  if (!valid) throw new Error('JWT signature verification failed');
+  return payload;
+}

package/src/persistent-store.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class PersistentCollectionStore {
+  constructor(filePath, { key = 'id', limit = 25000, seed = [] } = {}) {
+    this.filePath = path.resolve(filePath);
+    this.key = key;
+    this.limit = limit;
+    this.items = this.#load(seed);
+  }
+
+  add(item) {
+    this.items.unshift(item);
+    this.#trim();
+    this.save();
+    return item;
+  }
+  get(id) { return this.items.find(item => item?.[this.key] === id) || null; }
+  list(filter) {
+    const values = [...this.items];
+    if (typeof filter === 'function') return values.filter(filter);
+    return values;
+  }
+  update(id, patch) {
+    const item = this.get(id);
+    if (!item) return null;
+    Object.assign(item, patch);
+    this.save();
+    return item;
+  }
+  replace(items) { this.items = Array.isArray(items) ? items.slice(0, this.limit) : []; this.save(); return this.list(); }
+  save() {
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    const temp = `${this.filePath}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(this.items, null, 2), 'utf8');
+    fs.renameSync(temp, this.filePath);
+  }
+  #load(seed) {
+    try {
+      if (!fs.existsSync(this.filePath)) return Array.isArray(seed) ? seed.slice(0, this.limit) : [];
+      const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf8'));
+      return Array.isArray(parsed) ? parsed.slice(0, this.limit) : [];
+    } catch { return Array.isArray(seed) ? seed.slice(0, this.limit) : []; }
+  }
+  #trim() { if (this.items.length > this.limit) this.items.splice(this.limit); }
+}
+
+export function createPersistentRunStore(options = {}) {
+  return new PersistentCollectionStore(options.filePath || '.agentgate/runs.json', { limit: options.limit || 25000 });
+}
+export function createPersistentApprovalStore(options = {}) {
+  return new PersistentCollectionStore(options.filePath || '.agentgate/approvals.json', { limit: options.limit || 25000 });
+}
+export function createPersistentAgentStore(options = {}) {
+  return new PersistentCollectionStore(options.filePath || '.agentgate/agents.json', { limit: options.limit || 1000 });
+}

package/src/policy-builder.js

@@ -0,0 +1,74 @@
+import { DECISIONS } from './policy-engine.js';
+
+/**
+ * Convert attack results into deterministic, reviewable policy suggestions.
+ * Suggestions are data only; AgentGate never auto-authorizes from them.
+ */
+export function generatePolicySuggestions(results = []) {
+  const suggestions = [];
+  const blocked = new Set();
+  const approval = new Set();
+
+  for (const result of results) {
+    const action = String(result.action || '').toLowerCase();
+    if (!action) continue;
+
+    if (result.decision === DECISIONS.BLOCK) {
+      blocked.add(action);
+      suggestions.push({
+        id: `block-${action}`,
+        type: 'block_action',
+        action,
+        reason: result.reason || 'Attack was blocked by AgentGate',
+        confidence: 0.98
+      });
+    } else if (result.decision === DECISIONS.ASK) {
+      approval.add(action);
+      suggestions.push({
+        id: `approval-${action}`,
+        type: 'require_approval',
+        action,
+        reason: result.reason || 'Attack requires human approval',
+        confidence: 0.92
+      });
+    } else if (result.risk >= 70) {
+      approval.add(action);
+      suggestions.push({
+        id: `review-${action}`,
+        type: 'require_approval',
+        action,
+        reason: 'High-risk action should require review',
+        confidence: 0.85
+      });
+    }
+  }
+
+  const policy = {};
+  if (blocked.size) policy.blockActions = [...blocked].sort();
+  if (approval.size) policy.approvalActions = [...approval].filter(a => !blocked.has(a)).sort();
+
+  return { policy, suggestions: dedupe(suggestions) };
+}
+
+export function mergePolicies(base = {}, generated = {}) {
+  return {
+    ...base,
+    ...generated,
+    blockActions: unique([...(base.blockActions || []), ...(generated.blockActions || [])]),
+    approvalActions: unique([...(base.approvalActions || []), ...(generated.approvalActions || [])])
+      .filter(action => !(generated.blockActions || []).includes(action) && !(base.blockActions || []).includes(action))
+  };
+}
+
+function unique(values) {
+  return [...new Set(values.map(value => String(value).toLowerCase()))];
+}
+
+function dedupe(items) {
+  const seen = new Set();
+  return items.filter(item => {
+    if (seen.has(item.id)) return false;
+    seen.add(item.id);
+    return true;
+  });
+}

package/src/policy-bundles.js

@@ -0,0 +1,17 @@
+import crypto from 'node:crypto';
+import { PersistentCollectionStore } from './persistent-store.js';
+import { evaluate } from './policy-engine.js';
+export const BUNDLE_STATES=Object.freeze({DRAFT:'draft',TESTED:'tested',ACTIVE:'active',ARCHIVED:'archived'});
+export class PolicyBundleRegistry {
+  constructor(options={}){ this.store=options.store||new PersistentCollectionStore(options.filePath||'.agentgate/policy-bundles.json',{limit:options.limit||2000}); }
+  create(name,policies={},metadata={},tenantId=null){ const versions=this.store.list(x=>x.name===name && (tenantId==null ? !x.tenantId : x.tenantId===tenantId)); const version=(Math.max(0,...versions.map(x=>x.version||0))+1); const item={id:`bundle_${crypto.randomBytes(8).toString('hex')}`,name,version,state:BUNDLE_STATES.DRAFT,tenantId:tenantId||null,policies:{...policies},metadata,hash:hash(policies),createdAt:new Date().toISOString()}; return this.store.add(item); }
+  list(name,tenantId=null){ return this.store.list(x=>(!name||x.name===name) && (tenantId==null ? !x.tenantId : x.tenantId===tenantId)); }
+  get(name,version,tenantId=null){ return this.store.list(x=>x.name===name&&x.version===Number(version) && (tenantId==null ? !x.tenantId : x.tenantId===tenantId))[0]||null; }
+  test(name,version,cases=[],tenantId=null){ const b=this.get(name,version,tenantId); if(!b) throw new Error('Policy bundle not found'); const results=cases.map(c=>{const r=evaluate(c.input||{},b.policies); return {...c,actual:r.decision,passed:r.decision===c.expected};}); const passed=results.every(x=>x.passed); if(passed){b.state=BUNDLE_STATES.TESTED;b.testedAt=new Date().toISOString();b.testResults=results;this.store.save();} return {passed,results}; }
+  activate(name,version,tenantId=null){ const b=this.get(name,version,tenantId); if(!b) throw new Error('Policy bundle not found'); if(b.state!==BUNDLE_STATES.TESTED&&b.state!==BUNDLE_STATES.ACTIVE) throw new Error('Bundle must pass tests before activation'); for(const x of this.store.list(i=>i.name===name&&i.state===BUNDLE_STATES.ACTIVE && (tenantId==null ? !i.tenantId : i.tenantId===tenantId))){x.state=BUNDLE_STATES.ARCHIVED;} b.state=BUNDLE_STATES.ACTIVE;b.activatedAt=new Date().toISOString();this.store.save();return b; }
+  active(name,tenantId=null){ return this.store.list(x=>x.name===name&&x.state===BUNDLE_STATES.ACTIVE && (tenantId==null ? !x.tenantId : x.tenantId===tenantId))[0]||null; }
+  activeAll(tenantId=null){ return this.store.list(x=>x.state===BUNDLE_STATES.ACTIVE && (tenantId==null ? !x.tenantId : x.tenantId===tenantId)); }
+  diff(name,a,b,tenantId=null){const x=this.get(name,a,tenantId),y=this.get(name,b,tenantId);if(!x||!y)throw new Error('Policy bundle version not found');const keys=new Set([...Object.keys(x.policies),...Object.keys(y.policies)]);return [...keys].filter(k=>JSON.stringify(x.policies[k])!==JSON.stringify(y.policies[k])).map(k=>({key:k,from:x.policies[k],to:y.policies[k]}));}
+}
+function hash(v){return crypto.createHash('sha256').update(JSON.stringify(v,Object.keys(v).sort())).digest('hex');}
+export const createPolicyBundleRegistry=o=>new PolicyBundleRegistry(o);

package/src/policy-engine.js

@@ -0,0 +1,67 @@
+import { authorize } from './identity.js';
+
+export const DECISIONS = Object.freeze({ ALLOW: 'ALLOW', ASK: 'ASK', BLOCK: 'BLOCK' });
+
+const destructive = new Set(['delete','refund','publish','deploy','export_all','update_production']);
+const readOnly = new Set(['read','search','list','get','fetch']);
+
+export function evaluate(input = {}, policies = {}) {
+  const auth = authorize(input, policies.authorization);
+  const trace = [{ id: 'authorization', matched: auth.decision === 'BLOCK', decision: auth.decision, reason: auth.reason, matchedRule: auth.matchedRule || null }];
+  if (auth.decision === 'BLOCK') return decision('BLOCK', auth.reason, 96, { authorization: auth, ruleTrace: trace, winningRule: auth.matchedRule || 'authorization' });
+  const action = String(input.action || '').toLowerCase();
+  const hasAmount = Object.prototype.hasOwnProperty.call(input, 'amount') && input.amount !== undefined && input.amount !== null;
+  if (hasAmount && (typeof input.amount !== 'number' || !Number.isFinite(input.amount) || input.amount < 0)) {
+    return decision('BLOCK', 'Amount must be a finite non-negative number', 98, { ruleTrace: [...trace, { id: 'invalid-amount', matched: true, decision: 'BLOCK', reason: 'Amount must be a finite non-negative number' }], winningRule: 'invalid-amount' });
+  }
+  const amount = hasAmount ? input.amount : 0;
+  const env = input.environment || 'production';
+
+  if (policies.blockActions?.includes(action) || action === 'export_all') {
+    return decision('BLOCK', 'Action explicitly blocked by policy', 95, { ruleTrace: [...trace, { id: 'explicit-block', matched: true, decision: 'BLOCK', reason: 'Action explicitly blocked by policy' }], winningRule: 'explicit-block' });
+  }
+  if (policies.productionBlock && env === 'production' && destructive.has(action)) {
+    return decision('BLOCK', 'Destructive production action is blocked', 90, { ruleTrace: [...trace, { id: 'production-block', matched: true, decision: 'BLOCK', reason: 'Destructive production action is blocked' }], winningRule: 'production-block' });
+  }
+  if (amount > 0 && amount > (policies.approvalAmount ?? 5000)) {
+    return decision('BLOCK', 'Amount exceeds the maximum permitted threshold', 92, { ruleTrace: [...trace, { id: 'approval-amount-hard', matched: true, decision: 'BLOCK', reason: 'Amount exceeds the maximum permitted threshold' }], winningRule: 'approval-amount-hard' });
+  }
+  if (policies.approvalActions?.includes(action)) {
+    return decision('ASK', 'Approval required for sensitive action', 70, { ruleTrace: [...trace, { id: 'approval-action', matched: true, decision: 'ASK', reason: 'Approval required for sensitive action' }], winningRule: 'approval-action' });
+  }
+  if (amount > 0 && amount > (policies.autoApproveAmount ?? 500)) {
+    return decision('ASK', 'Amount exceeds the automatic approval threshold', 65, { ruleTrace: [...trace, { id: 'auto-approval-threshold', matched: true, decision: 'ASK', reason: 'Amount exceeds the automatic approval threshold' }], winningRule: 'auto-approval-threshold' });
+  }
+  if (readOnly.has(action)) return decision('ALLOW', 'Read-only action allowed', 5, { ruleTrace: [...trace, { id: 'readonly-allow', matched: true, decision: 'ALLOW', reason: 'Read-only action allowed' }], winningRule: 'readonly-allow' });
+  if (destructive.has(action) && policies.requireApprovalForDestructive !== false) {
+    return decision('ASK', 'Destructive action requires approval', 75, { ruleTrace: [...trace, { id: 'destructive-approval', matched: true, decision: 'ASK', reason: 'Destructive action requires approval' }], winningRule: 'destructive-approval' });
+  }
+  return decision('ALLOW', 'No blocking policy matched', 10, { ruleTrace: [...trace, { id: 'default-allow', matched: true, decision: 'ALLOW', reason: 'No blocking policy matched' }], winningRule: 'default-allow' });
+}
+
+function decision(decision, reason, risk, extra = {}) {
+  return { decision, reason, risk, timestamp: new Date().toISOString(), ...extra };
+}
+
+export function protect(tool, options = {}) {
+  if (typeof tool !== 'function') throw new TypeError('protect() expects a function');
+  const policies = {
+    autoApproveAmount: 500,
+    approvalAmount: 5000,
+    ...options
+  };
+  return async function protectedTool(input = {}, context = {}) {
+    const result = evaluate({ ...input, ...context }, policies);
+    if (result.decision === 'BLOCK') {
+      const error = new Error(`AgentGate blocked action: ${result.reason}`);
+      error.code = 'AGENTGATE_BLOCKED';
+      error.agentgate = result;
+      throw error;
+    }
+    if (result.decision === 'ASK') {
+      return { status: 'approval_required', agentgate: result };
+    }
+    const value = await tool(input);
+    return { status: 'executed', value, agentgate: result };
+  };
+}