@mnemom/agent-alignment-protocol 0.1.0

package/dist/index.mjs

@@ -0,0 +1,576 @@
+// src/constants.ts
+var DEFAULT_SIMILARITY_THRESHOLD = 0.3;
+var DEFAULT_SUSTAINED_TURNS_THRESHOLD = 3;
+var NEAR_BOUNDARY_THRESHOLD = 0.35;
+var MIN_COHERENCE_FOR_PROCEED = 0.7;
+var CONFLICT_PENALTY_MULTIPLIER = 0.5;
+var MIN_WORD_LENGTH = 3;
+var MAX_TFIDF_FEATURES = 500;
+var ALGORITHM_VERSION = "1.0.0";
+
+// src/verification/features.ts
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "must",
+  "shall",
+  "can",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  "as",
+  "if",
+  "then",
+  "else"
+]);
+function tokenize(text) {
+  return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((word) => word.length >= MIN_WORD_LENGTH && !STOPWORDS.has(word));
+}
+function extractCardFeatures(card) {
+  const features = {};
+  for (const value of card.values.declared) {
+    features[`value:${value}`] = 1;
+  }
+  for (const conflict of card.values.conflicts_with ?? []) {
+    features[`conflict:${conflict}`] = 1;
+  }
+  for (const action of card.autonomy_envelope.bounded_actions) {
+    features[`action_name:${action}`] = 1;
+  }
+  for (const action of card.autonomy_envelope.forbidden_actions ?? []) {
+    features[`forbidden:${action}`] = 1;
+  }
+  for (const trigger of card.autonomy_envelope.escalation_triggers) {
+    features[`escalation:${trigger.action}`] = 1;
+    const conditionTokens = tokenize(trigger.condition);
+    for (const token of conditionTokens) {
+      features[`condition:${token}`] = (features[`condition:${token}`] ?? 0) + 0.5;
+    }
+  }
+  features[`category:${card.principal.type}`] = 1;
+  features[`category:${card.principal.relationship}`] = 1;
+  return features;
+}
+function extractTraceFeatures(trace) {
+  const features = {};
+  features[`action:${trace.action.type}`] = 1;
+  features[`category:${trace.action.category}`] = 1;
+  features[`action_name:${trace.action.name}`] = 1;
+  for (const value of trace.decision.values_applied) {
+    features[`value:${value}`] = 1;
+  }
+  if (trace.escalation) {
+    features[`escalation:${trace.escalation.required ? "required" : "not_required"}`] = 1;
+    if (trace.escalation.escalation_status) {
+      features[`escalation:${trace.escalation.escalation_status}`] = 1;
+    }
+  }
+  const reasoningTokens = tokenize(trace.decision.selection_reasoning);
+  for (const token of reasoningTokens) {
+    features[`content:${token}`] = (features[`content:${token}`] ?? 0) + 0.5;
+  }
+  for (const alt of trace.decision.alternatives_considered) {
+    const altTokens = tokenize(alt.description);
+    for (const token of altTokens) {
+      features[`content:${token}`] = (features[`content:${token}`] ?? 0) + 0.25;
+    }
+    if (alt.flags) {
+      for (const flag of alt.flags) {
+        features[`flag:${flag}`] = 1;
+      }
+    }
+  }
+  return features;
+}
+function cosineSimilarity(a, b) {
+  const keysA = Object.keys(a);
+  const keysB = new Set(Object.keys(b));
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+  for (const key of keysA) {
+    const valA = a[key];
+    normA += valA * valA;
+    if (keysB.has(key)) {
+      dotProduct += valA * b[key];
+    }
+  }
+  for (const key of keysB) {
+    const valB = b[key];
+    normB += valB * valB;
+  }
+  if (normA === 0 || normB === 0) {
+    return 0;
+  }
+  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+// src/verification/models.ts
+var VIOLATION_SEVERITY = {
+  unbounded_action: "high",
+  forbidden_action: "critical",
+  missed_escalation: "high",
+  undeclared_value: "medium",
+  card_expired: "high",
+  card_mismatch: "critical"
+};
+function createViolation(type, description, traceField) {
+  return {
+    type,
+    severity: VIOLATION_SEVERITY[type],
+    description,
+    trace_field: traceField
+  };
+}
+
+// src/verification/api.ts
+function verifyTrace(trace, card) {
+  const startTime = performance.now();
+  const violations = [];
+  const warnings = [];
+  const checksPerformed = [];
+  const traceId = trace.trace_id ?? "";
+  const cardId = card.card_id ?? "";
+  checksPerformed.push("card_reference");
+  if (trace.card_id !== cardId) {
+    violations.push(
+      createViolation(
+        "card_mismatch",
+        `Trace references card '${trace.card_id}' but verified against '${cardId}'`
+      )
+    );
+  }
+  checksPerformed.push("card_expiration");
+  if (card.expires_at) {
+    try {
+      const expiry = new Date(card.expires_at);
+      if (/* @__PURE__ */ new Date() > expiry) {
+        violations.push(
+          createViolation("card_expired", `Alignment Card expired at ${card.expires_at}`)
+        );
+      }
+    } catch {
+      warnings.push({
+        type: "invalid_expiry",
+        description: `Could not parse expires_at: ${card.expires_at}`,
+        trace_field: "card.expires_at"
+      });
+    }
+  }
+  const envelope = card.autonomy_envelope;
+  const action = trace.action;
+  checksPerformed.push("autonomy");
+  const actionCategory = action.category;
+  const actionName = action.name;
+  if (actionCategory === "bounded") {
+    const boundedActions = envelope.bounded_actions ?? [];
+    if (actionName && !boundedActions.includes(actionName)) {
+      violations.push(
+        createViolation(
+          "unbounded_action",
+          `Action '${actionName}' not in bounded_actions: ${JSON.stringify(boundedActions)}`,
+          "action.name"
+        )
+      );
+    }
+  }
+  checksPerformed.push("forbidden");
+  const forbiddenActions = envelope.forbidden_actions ?? [];
+  if (actionName && forbiddenActions.includes(actionName)) {
+    violations.push(
+      createViolation(
+        "forbidden_action",
+        `Action '${actionName}' is in forbidden_actions`,
+        "action.name"
+      )
+    );
+  }
+  checksPerformed.push("escalation");
+  const escalation = trace.escalation;
+  for (const trigger of envelope.escalation_triggers ?? []) {
+    const condition = trigger.condition ?? "";
+    if (evaluateCondition(condition, trace)) {
+      if (!escalation?.required) {
+        violations.push(
+          createViolation(
+            "missed_escalation",
+            `Trigger '${condition}' matched but escalation not required`,
+            "escalation.required"
+          )
+        );
+      } else if (escalation.escalation_status === "timeout") {
+        warnings.push({
+          type: "escalation_timeout",
+          description: `Escalation for trigger '${condition}' timed out`,
+          trace_field: "escalation.escalation_status"
+        });
+      }
+    }
+  }
+  checksPerformed.push("values");
+  const decision = trace.decision;
+  const declaredValues = card.values.declared ?? [];
+  const valuesApplied = decision.values_applied ?? [];
+  for (const value of valuesApplied) {
+    if (!declaredValues.includes(value)) {
+      violations.push(
+        createViolation(
+          "undeclared_value",
+          `Value '${value}' applied but not in declared values: ${JSON.stringify(declaredValues)}`,
+          "decision.values_applied"
+        )
+      );
+    }
+  }
+  const confidence = decision.confidence;
+  if (confidence != null && confidence < NEAR_BOUNDARY_THRESHOLD) {
+    warnings.push({
+      type: "near_boundary",
+      description: `Decision confidence ${confidence.toFixed(2)} below threshold ${NEAR_BOUNDARY_THRESHOLD}`,
+      trace_field: "decision.confidence"
+    });
+  }
+  for (let i = 0; i < decision.alternatives_considered.length; i++) {
+    const alt = decision.alternatives_considered[i];
+    const score = alt.score;
+    if (score != null && score < NEAR_BOUNDARY_THRESHOLD) {
+      warnings.push({
+        type: "near_boundary",
+        description: `Alternative '${alt.option_id}' score ${score.toFixed(2)} near boundary`,
+        trace_field: `decision.alternatives_considered[${i}].score`
+      });
+    }
+  }
+  const durationMs = performance.now() - startTime;
+  return {
+    verified: violations.length === 0,
+    trace_id: traceId,
+    card_id: cardId,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    violations,
+    warnings,
+    verification_metadata: {
+      algorithm_version: ALGORITHM_VERSION,
+      checks_performed: checksPerformed,
+      duration_ms: Math.round(durationMs * 100) / 100
+    }
+  };
+}
+function checkCoherence(myCard, theirCard, taskValues) {
+  const myValues = new Set(myCard.values.declared ?? []);
+  const theirValues = new Set(theirCard.values.declared ?? []);
+  const myConflicts = new Set(myCard.values.conflicts_with ?? []);
+  const theirConflicts = new Set(theirCard.values.conflicts_with ?? []);
+  const requiredValues = taskValues ? new Set(taskValues) : /* @__PURE__ */ new Set([...myValues, ...theirValues]);
+  const matched = [];
+  const unmatched = [];
+  for (const value of myValues) {
+    if (theirValues.has(value)) {
+      matched.push(value);
+    } else {
+      unmatched.push(value);
+    }
+  }
+  for (const value of theirValues) {
+    if (!myValues.has(value)) {
+      unmatched.push(value);
+    }
+  }
+  const conflicts = [];
+  for (const value of myValues) {
+    if (theirConflicts.has(value)) {
+      conflicts.push({
+        initiator_value: value,
+        responder_value: "(conflicts_with)",
+        conflict_type: "incompatible",
+        description: `Initiator's '${value}' is in responder's conflicts_with`
+      });
+    }
+  }
+  for (const value of theirValues) {
+    if (myConflicts.has(value)) {
+      conflicts.push({
+        initiator_value: "(conflicts_with)",
+        responder_value: value,
+        conflict_type: "incompatible",
+        description: `Responder's '${value}' is in initiator's conflicts_with`
+      });
+    }
+  }
+  const totalRequired = requiredValues.size || 1;
+  const matchedCount = taskValues ? matched.filter((v) => requiredValues.has(v)).length : matched.length;
+  const conflictPenalty = CONFLICT_PENALTY_MULTIPLIER * (conflicts.length / totalRequired);
+  let score = matchedCount / totalRequired * (1 - conflictPenalty);
+  score = Math.max(0, Math.min(1, score));
+  const compatible = conflicts.length === 0 && score >= MIN_COHERENCE_FOR_PROCEED;
+  const proceed = compatible;
+  let proposedResolution = null;
+  if (conflicts.length > 0 && !compatible) {
+    proposedResolution = {
+      type: "escalate_to_principals",
+      reason: "Value conflict requires human decision"
+    };
+  }
+  return {
+    compatible,
+    score: Math.round(score * 1e4) / 1e4,
+    value_alignment: {
+      matched,
+      unmatched,
+      conflicts
+    },
+    proceed,
+    conditions: [],
+    proposed_resolution: proposedResolution
+  };
+}
+function detectDrift(card, traces, similarityThreshold = DEFAULT_SIMILARITY_THRESHOLD, sustainedThreshold = DEFAULT_SUSTAINED_TURNS_THRESHOLD) {
+  if (traces.length < sustainedThreshold) {
+    return [];
+  }
+  const cardFeatures = extractCardFeatures(card);
+  const alerts = [];
+  let lowSimilarityStreak = [];
+  const escalationRates = [];
+  const valueUsage = {};
+  for (const trace of traces) {
+    const traceFeatures = extractTraceFeatures(trace);
+    const similarity = cosineSimilarity(traceFeatures, cardFeatures);
+    const escalation = trace.escalation;
+    escalationRates.push(escalation?.required ? 1 : 0);
+    for (const value of trace.decision.values_applied ?? []) {
+      valueUsage[value] = (valueUsage[value] ?? 0) + 1;
+    }
+    if (similarity < similarityThreshold) {
+      lowSimilarityStreak.push({ trace, similarity });
+    } else {
+      lowSimilarityStreak = [];
+    }
+    if (lowSimilarityStreak.length >= sustainedThreshold) {
+      const latest = lowSimilarityStreak[lowSimilarityStreak.length - 1];
+      const direction = inferDriftDirection(
+        lowSimilarityStreak,
+        card,
+        escalationRates,
+        valueUsage
+      );
+      const indicators = buildDriftIndicators(
+        lowSimilarityStreak,
+        escalationRates
+      );
+      const alert = {
+        alert_type: "drift_detected",
+        agent_id: latest.trace.agent_id ?? "",
+        card_id: card.card_id ?? "",
+        detection_timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        analysis: {
+          similarity_score: Math.round(latest.similarity * 1e4) / 1e4,
+          sustained_traces: lowSimilarityStreak.length,
+          threshold: similarityThreshold,
+          drift_direction: direction,
+          specific_indicators: indicators
+        },
+        recommendation: "Review recent decisions for alignment drift",
+        trace_ids: lowSimilarityStreak.map((s) => s.trace.trace_id ?? "")
+      };
+      alerts.push(alert);
+    }
+  }
+  return alerts;
+}
+function evaluateCondition(condition, trace) {
+  if (!condition) {
+    return false;
+  }
+  const actionTypeMatch = condition.match(/action_type\s*==\s*"([^"]+)"/);
+  if (actionTypeMatch) {
+    const expected = actionTypeMatch[1];
+    const actual = trace.action.type ?? "";
+    return actual === expected;
+  }
+  const numericMatch = condition.match(/(\w+)\s*([><=!]+)\s*(\d+(?:\.\d+)?)/);
+  if (numericMatch) {
+    const [, field, op, valueStr] = numericMatch;
+    const value = parseFloat(valueStr);
+    let actual = trace.context?.[field];
+    if (actual == null) {
+      actual = trace.context?.metadata?.[field];
+    }
+    if (actual == null) {
+      actual = trace.action.parameters?.[field];
+    }
+    if (actual == null) {
+      return false;
+    }
+    const actualNum = parseFloat(String(actual));
+    if (isNaN(actualNum)) {
+      return false;
+    }
+    switch (op) {
+      case ">":
+        return actualNum > value;
+      case "<":
+        return actualNum < value;
+      case ">=":
+        return actualNum >= value;
+      case "<=":
+        return actualNum <= value;
+      case "==":
+        return actualNum === value;
+      case "!=":
+        return actualNum !== value;
+      default:
+        return false;
+    }
+  }
+  if (/^\w+$/.test(condition)) {
+    const ctxValue = trace.context?.[condition];
+    return Boolean(ctxValue ?? trace.context?.metadata?.[condition]);
+  }
+  return false;
+}
+function inferDriftDirection(streak, card, escalationRates, valueUsage) {
+  const declaredValues = new Set(card.values.declared ?? []);
+  if (escalationRates.length >= 6) {
+    const earlyRate = escalationRates.slice(0, 3).reduce((a, b) => a + b, 0) / 3;
+    const lateRate = escalationRates.slice(-3).reduce((a, b) => a + b, 0) / 3;
+    if (earlyRate > 0.1 && lateRate < earlyRate * 0.5) {
+      return "autonomy_expansion";
+    }
+  }
+  let undeclaredUsage = 0;
+  let totalUsage = 0;
+  for (const [value, count] of Object.entries(valueUsage)) {
+    totalUsage += count;
+    if (!declaredValues.has(value)) {
+      undeclaredUsage += count;
+    }
+  }
+  if (totalUsage > 0 && undeclaredUsage / totalUsage > 0.3) {
+    return "value_drift";
+  }
+  if (declaredValues.has("principal_benefit")) {
+    const recentConfidences = streak.slice(-3).map(
+      (s) => s.trace.decision.confidence ?? 1
+    );
+    const avgConfidence = recentConfidences.reduce((a, b) => a + b, 0) / recentConfidences.length;
+    if (avgConfidence < 0.5) {
+      return "principal_misalignment";
+    }
+  }
+  return "unknown";
+}
+function buildDriftIndicators(streak, escalationRates) {
+  const indicators = [];
+  if (escalationRates.length >= 6) {
+    const baselineRate = escalationRates.slice(0, 3).reduce((a, b) => a + b, 0) / 3;
+    const currentRate = escalationRates.slice(-3).reduce((a, b) => a + b, 0) / 3;
+    if (Math.abs(baselineRate - currentRate) > 0.05) {
+      indicators.push({
+        indicator: "escalation_rate_change",
+        baseline: Math.round(baselineRate * 100) / 100,
+        current: Math.round(currentRate * 100) / 100,
+        description: `Escalation rate changed from ${(baselineRate * 100).toFixed(0)}% to ${(currentRate * 100).toFixed(0)}%`
+      });
+    }
+  }
+  const similarities = streak.map((s) => s.similarity);
+  if (similarities.length >= 3) {
+    const trend = similarities[similarities.length - 1] - similarities[0];
+    indicators.push({
+      indicator: "similarity_trend",
+      baseline: Math.round(similarities[0] * 1e4) / 1e4,
+      current: Math.round(similarities[similarities.length - 1] * 1e4) / 1e4,
+      description: `Similarity ${trend < 0 ? "decreasing" : "stable"} over ${streak.length} traces`
+    });
+  }
+  return indicators;
+}
+
+// src/schemas/alignment-card.ts
+function isCardExpired(card) {
+  if (!card.expires_at) return false;
+  return /* @__PURE__ */ new Date() > new Date(card.expires_at);
+}
+function hasValue(card, value) {
+  return card.values.declared.includes(value);
+}
+function isActionBounded(card, action) {
+  return card.autonomy_envelope.bounded_actions.includes(action);
+}
+function isActionForbidden(card, action) {
+  return (card.autonomy_envelope.forbidden_actions ?? []).includes(action);
+}
+
+// src/schemas/ap-trace.ts
+function getSelectedAlternative(trace) {
+  return trace.decision.alternatives_considered.find(
+    (alt) => alt.option_id === trace.decision.selected
+  );
+}
+function wasEscalated(trace) {
+  return trace.escalation != null && trace.escalation.required;
+}
+function hadViolations(trace) {
+  return trace.action.category === "forbidden";
+}
+export {
+  ALGORITHM_VERSION,
+  CONFLICT_PENALTY_MULTIPLIER,
+  DEFAULT_SIMILARITY_THRESHOLD,
+  DEFAULT_SUSTAINED_TURNS_THRESHOLD,
+  MAX_TFIDF_FEATURES,
+  MIN_COHERENCE_FOR_PROCEED,
+  MIN_WORD_LENGTH,
+  NEAR_BOUNDARY_THRESHOLD,
+  VIOLATION_SEVERITY,
+  checkCoherence,
+  cosineSimilarity,
+  createViolation,
+  detectDrift,
+  extractCardFeatures,
+  extractTraceFeatures,
+  getSelectedAlternative,
+  hadViolations,
+  hasValue,
+  isActionBounded,
+  isActionForbidden,
+  isCardExpired,
+  verifyTrace,
+  wasEscalated
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mnemom/agent-alignment-protocol",
+  "version": "0.1.0",
+  "description": "Agent Alignment Protocol (AAP) - Verification and drift detection for AI agents",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "alignment",
+    "verification",
+    "audit",
+    "a2a",
+    "mcp"
+  ],
+  "author": "AAP Contributors",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mnemom/aap"
+  },
+  "homepage": "https://mnemom.github.io/aap/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "eslint": "^8.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,44 @@
+/**
+ * Calibrated constants for AAP verification and drift detection.
+ *
+ * These thresholds were derived from empirical analysis of approximately 50
+ * multi-turn agent conversations. The underlying data is not published to
+ * protect deliberative privacy, but the methodology is documented in
+ * docs/CALIBRATION.md.
+ *
+ * Implementations MAY adjust thresholds based on their own calibration data,
+ * but SHOULD document the methodology used.
+ */
+
+// Drift Detection Thresholds
+// --------------------------
+/** Alert when behavioral similarity to declared alignment drops below this value. */
+export const DEFAULT_SIMILARITY_THRESHOLD = 0.3;
+
+/** Alert after this many consecutive traces show low similarity. */
+export const DEFAULT_SUSTAINED_TURNS_THRESHOLD = 3;
+
+// Verification Thresholds
+// -----------------------
+/** Score below which an action is flagged as "near boundary" warning */
+export const NEAR_BOUNDARY_THRESHOLD = 0.35;
+
+// Coherence Scoring
+// -----------------
+/** Minimum coherence score for automatic "proceed" recommendation */
+export const MIN_COHERENCE_FOR_PROCEED = 0.7;
+
+/** Penalty multiplier for value conflicts in coherence scoring */
+export const CONFLICT_PENALTY_MULTIPLIER = 0.5;
+
+// Feature Extraction
+// ------------------
+/** Minimum word length for content features (filters noise) */
+export const MIN_WORD_LENGTH = 3;
+
+/** Maximum features to extract from TF-IDF vectorization */
+export const MAX_TFIDF_FEATURES = 500;
+
+// Version
+// -------
+export const ALGORITHM_VERSION = "1.0.0";