@xemahq/agent-session-runtime 0.1.1

package/src/lib/drift-detector.ts

@@ -0,0 +1,497 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Environment drift detector ──
+//
+// Diffs two `ResolvedEnvironment` snapshots and emits a structured
+// drift report. Used by agent-session resume to compare the
+// snapshot from the previous run against a freshly-resolved snapshot
+// at resume time — re-resolve is the source of truth, drift is what
+// surfaces to the operator.
+//
+// Drift kinds are a closed enum (`DriftKind`). Severity is `info |
+// warning` — purely advisory: NO drift blocks a resume. Resume always
+// proceeds with the freshly-resolved environment; the drift list is
+// surfaced to the operator (timeline entry + the `SessionResumed`
+// degradation toast) so they see what changed. `warning` flags the
+// changes worth a second look (a removed sub-agent/skill/credential, a
+// changed agent, a tightened permission); `info` is benign drift
+// (version bumps, additions, value tweaks).
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ToolSelectionEntry } from '@xemahq/kernel-contracts/mcp-tool';
+import type {
+  CompiledManifestCredential,
+  CompiledManifestSkillRef,
+  SubAgentBinding,
+} from '@xemahq/kernel-contracts/workflow';
+
+import type { ResolvedEnvironment } from './environment-resolver';
+
+export enum DriftKind {
+  AGENT_CHANGED = 'agent-changed',
+  ROLE_CHANGED = 'role-changed',
+  MANIFEST_VERSION_CHANGED = 'manifest-version-changed',
+  MODEL_CHANGED = 'model-changed',
+  SUBAGENT_ADDED = 'subagent-added',
+  SUBAGENT_REMOVED = 'subagent-removed',
+  SUBAGENT_MODEL_CHANGED = 'subagent-model-changed',
+  SKILL_ADDED = 'skill-added',
+  SKILL_REMOVED = 'skill-removed',
+  SKILL_VERSION_CHANGED = 'skill-version-changed',
+  TOOL_SELECTION_ADDED = 'tool-selection-added',
+  TOOL_SELECTION_REMOVED = 'tool-selection-removed',
+  CREDENTIAL_ADDED = 'credential-added',
+  CREDENTIAL_REMOVED = 'credential-removed',
+  CREDENTIAL_KIND_CHANGED = 'credential-kind-changed',
+  PERMISSION_TIGHTENED = 'permission-tightened',
+  PERMISSION_RELAXED = 'permission-relaxed',
+  PERSISTENCE_PATH_ADDED = 'persistence-path-added',
+  PERSISTENCE_PATH_REMOVED = 'persistence-path-removed',
+  OUTPUT_SURFACE_CHANGED = 'output-surface-changed',
+  ENV_VAR_ADDED = 'env-var-added',
+  ENV_VAR_REMOVED = 'env-var-removed',
+  ENV_VAR_VALUE_CHANGED = 'env-var-value-changed',
+  MOUNT_ADDED = 'mount-added',
+  MOUNT_REMOVED = 'mount-removed',
+  MOUNT_MODE_CHANGED = 'mount-mode-changed',
+}
+
+/**
+ * Advisory drift severity — `info` (benign) or `warning` (worth a look).
+ * There is deliberately no `critical`: resume is non-blocking by design
+ * (plan Epic D §D4), so severity only drives how the operator's drift
+ * toast renders, never whether the session resumes.
+ */
+export type DriftSeverity = 'info' | 'warning';
+
+export interface EnvironmentDrift {
+  readonly kind: DriftKind;
+  readonly severity: DriftSeverity;
+  readonly path: string;
+  readonly before?: unknown;
+  readonly after?: unknown;
+  readonly message: string;
+}
+
+/**
+ * Diff two `ResolvedEnvironment` snapshots. Returns a possibly-empty
+ * array of structured drifts. Order is stable (insertion order across
+ * the structured walk) so callers can render a deterministic timeline
+ * entry.
+ *
+ * Equal hashes short-circuit to `[]` — the hash covers every
+ * structured field, so two snapshots with the same hash are
+ * guaranteed to produce no drift.
+ */
+export function diffResolvedEnvironment(
+  prev: ResolvedEnvironment,
+  next: ResolvedEnvironment,
+): readonly EnvironmentDrift[] {
+  if (prev.hash === next.hash) {return [];}
+
+  const drifts: EnvironmentDrift[] = [];
+
+  diffAgent(prev, next, drifts);
+  diffSubAgents(prev.subAgents, next.subAgents, drifts);
+  diffSkills(prev.skills, next.skills, drifts);
+  diffToolSelection(prev.toolSelection, next.toolSelection, drifts);
+  diffCredentials(prev.credentials, next.credentials, drifts);
+  diffPermissions(prev, next, drifts);
+  diffPersistence(prev, next, drifts);
+  diffOutputSurface(prev, next, drifts);
+  diffEnv(prev, next, drifts);
+  diffMounts(prev, next, drifts);
+
+  return drifts;
+}
+
+function diffAgent(
+  prev: ResolvedEnvironment,
+  next: ResolvedEnvironment,
+  out: EnvironmentDrift[],
+): void {
+  if (prev.manifest.version !== next.manifest.version) {
+    out.push({
+      kind: DriftKind.MANIFEST_VERSION_CHANGED,
+      severity: 'info',
+      path: '$.manifest.version',
+      before: prev.manifest.version,
+      after: next.manifest.version,
+      message: `Manifest version moved ${prev.manifest.version} → ${next.manifest.version}.`,
+    });
+  }
+  if (prev.agent.slug !== next.agent.slug) {
+    out.push({
+      kind: DriftKind.AGENT_CHANGED,
+      severity: 'warning',
+      path: '$.agent.slug',
+      before: prev.agent.slug,
+      after: next.agent.slug,
+      message: `Primary agent slug changed ${prev.agent.slug} → ${next.agent.slug}; the session resumes with the new agent.`,
+    });
+  }
+  if (prev.agent.role !== next.agent.role) {
+    out.push({
+      kind: DriftKind.ROLE_CHANGED,
+      severity: 'info',
+      path: '$.agent.role',
+      before: prev.agent.role,
+      after: next.agent.role,
+      message: `Agent role changed ${prev.agent.role} → ${next.agent.role}; AGENTS.md will be re-rendered.`,
+    });
+  }
+  const prevModel = JSON.stringify(prev.agent.model ?? null);
+  const nextModel = JSON.stringify(next.agent.model ?? null);
+  if (prevModel !== nextModel) {
+    out.push({
+      kind: DriftKind.MODEL_CHANGED,
+      severity: 'info',
+      path: '$.agent.model',
+      before: prev.agent.model,
+      after: next.agent.model,
+      message: 'Primary agent default model changed.',
+    });
+  }
+}
+
+function diffSubAgents(
+  prev: readonly SubAgentBinding[],
+  next: readonly SubAgentBinding[],
+  out: EnvironmentDrift[],
+): void {
+  const prevBySlug = new Map(prev.map((s) => [s.slug, s]));
+  const nextBySlug = new Map(next.map((s) => [s.slug, s]));
+  for (const [slug, n] of nextBySlug) {
+    const p = prevBySlug.get(slug);
+    if (!p) {
+      out.push({
+        kind: DriftKind.SUBAGENT_ADDED,
+        severity: 'info',
+        path: `$.subAgents[${slug}]`,
+        after: n,
+        message: `Sub-agent '${slug}' added.`,
+      });
+      continue;
+    }
+    if (JSON.stringify(p.modelOverride ?? null) !== JSON.stringify(n.modelOverride ?? null)) {
+      out.push({
+        kind: DriftKind.SUBAGENT_MODEL_CHANGED,
+        severity: 'info',
+        path: `$.subAgents[${slug}].modelOverride`,
+        before: p.modelOverride,
+        after: n.modelOverride,
+        message: `Sub-agent '${slug}' model override changed.`,
+      });
+    }
+  }
+  for (const [slug, p] of prevBySlug) {
+    if (!nextBySlug.has(slug)) {
+      out.push({
+        kind: DriftKind.SUBAGENT_REMOVED,
+        severity: 'warning',
+        path: `$.subAgents[${slug}]`,
+        before: p,
+        message: `Sub-agent '${slug}' removed; existing delegations may fail until the session is restarted.`,
+      });
+    }
+  }
+}
+
+function diffSkills(
+  prev: readonly CompiledManifestSkillRef[],
+  next: readonly CompiledManifestSkillRef[],
+  out: EnvironmentDrift[],
+): void {
+  const prevBySlug = new Map(prev.map((s) => [s.slug, s]));
+  const nextBySlug = new Map(next.map((s) => [s.slug, s]));
+  for (const [slug, n] of nextBySlug) {
+    const p = prevBySlug.get(slug);
+    if (!p) {
+      out.push({
+        kind: DriftKind.SKILL_ADDED,
+        severity: 'info',
+        path: `$.skills[${slug}]`,
+        after: n,
+        message: `Skill '${slug}' added.`,
+      });
+      continue;
+    }
+    if (p.version !== n.version) {
+      out.push({
+        kind: DriftKind.SKILL_VERSION_CHANGED,
+        severity: 'info',
+        path: `$.skills[${slug}].version`,
+        before: p.version,
+        after: n.version,
+        message: `Skill '${slug}' version moved ${p.version ?? '*'} → ${n.version ?? '*'}.`,
+      });
+    }
+  }
+  for (const [slug, p] of prevBySlug) {
+    if (!nextBySlug.has(slug)) {
+      out.push({
+        kind: DriftKind.SKILL_REMOVED,
+        severity: 'warning',
+        path: `$.skills[${slug}]`,
+        before: p,
+        message: `Skill '${slug}' removed.`,
+      });
+    }
+  }
+}
+
+function toolSelectionKey(entry: ToolSelectionEntry): string {
+  return entry.kind === 'tool'
+    ? `tool:${entry.providerKind}:${entry.resourceId}:${entry.toolName}`
+    : `provider:${entry.providerKind}:${entry.resourceId}`;
+}
+
+function diffToolSelection(
+  prev: readonly ToolSelectionEntry[],
+  next: readonly ToolSelectionEntry[],
+  out: EnvironmentDrift[],
+): void {
+  const prevByKey = new Map(prev.map((e) => [toolSelectionKey(e), e]));
+  const nextByKey = new Map(next.map((e) => [toolSelectionKey(e), e]));
+  for (const [key, n] of nextByKey) {
+    if (!prevByKey.has(key)) {
+      out.push({
+        kind: DriftKind.TOOL_SELECTION_ADDED,
+        severity: 'info',
+        path: `$.toolSelection[${key}]`,
+        after: n,
+        message: `Tool selection entry '${key}' added.`,
+      });
+    }
+  }
+  for (const [key, p] of prevByKey) {
+    if (!nextByKey.has(key)) {
+      out.push({
+        kind: DriftKind.TOOL_SELECTION_REMOVED,
+        severity: 'warning',
+        path: `$.toolSelection[${key}]`,
+        before: p,
+        message: `Tool selection entry '${key}' removed.`,
+      });
+    }
+  }
+}
+
+function diffCredentials(
+  prev: readonly CompiledManifestCredential[],
+  next: readonly CompiledManifestCredential[],
+  out: EnvironmentDrift[],
+): void {
+  const prevByName = new Map(prev.map((c) => [c.name, c]));
+  const nextByName = new Map(next.map((c) => [c.name, c]));
+  for (const [name, n] of nextByName) {
+    const p = prevByName.get(name);
+    if (!p) {
+      out.push({
+        kind: DriftKind.CREDENTIAL_ADDED,
+        severity: 'info',
+        path: `$.credentials[${name}]`,
+        after: n,
+        message: `Credential '${name}' added.`,
+      });
+      continue;
+    }
+    if (p.kind !== n.kind) {
+      out.push({
+        kind: DriftKind.CREDENTIAL_KIND_CHANGED,
+        severity: 'warning',
+        path: `$.credentials[${name}].kind`,
+        before: p.kind,
+        after: n.kind,
+        message: `Credential '${name}' kind changed ${p.kind} → ${n.kind}; the resolver will re-route it on resume.`,
+      });
+    }
+  }
+  for (const [name, p] of prevByName) {
+    if (!nextByName.has(name)) {
+      out.push({
+        kind: DriftKind.CREDENTIAL_REMOVED,
+        // Resume is non-blocking even for a previously-required
+        // credential — the restore path degrades to a still-usable
+        // provider. `warning` simply flags it for the operator.
+        severity: 'warning',
+        path: `$.credentials[${name}]`,
+        before: p,
+        message: `Credential '${name}' removed${p.required ? ' (was required; the session resumes with the remaining credentials)' : ''}.`,
+      });
+    }
+  }
+}
+
+function diffPermissions(
+  prev: ResolvedEnvironment,
+  next: ResolvedEnvironment,
+  out: EnvironmentDrift[],
+): void {
+  const prevAllow = new Set(prev.permissions.tools.allow);
+  const nextAllow = new Set(next.permissions.tools.allow);
+  const prevDeny = new Set(prev.permissions.tools.deny);
+  const nextDeny = new Set(next.permissions.tools.deny);
+  // A tool is "tightened" if it was previously allowed and is now
+  // explicitly denied OR removed from the allow-list.
+  for (const tool of prevAllow) {
+    if (!nextAllow.has(tool) || nextDeny.has(tool)) {
+      out.push({
+        kind: DriftKind.PERMISSION_TIGHTENED,
+        severity: 'warning',
+        path: `$.permissions.tools.${tool}`,
+        before: 'allow',
+        after: nextDeny.has(tool) ? 'deny' : 'unset',
+        message: `Tool '${tool}' is no longer allowed.`,
+      });
+    }
+  }
+  for (const tool of nextAllow) {
+    if (!prevAllow.has(tool) || prevDeny.has(tool)) {
+      out.push({
+        kind: DriftKind.PERMISSION_RELAXED,
+        severity: 'info',
+        path: `$.permissions.tools.${tool}`,
+        before: prevDeny.has(tool) ? 'deny' : 'unset',
+        after: 'allow',
+        message: `Tool '${tool}' is now allowed.`,
+      });
+    }
+  }
+}
+
+function diffPersistence(
+  prev: ResolvedEnvironment,
+  next: ResolvedEnvironment,
+  out: EnvironmentDrift[],
+): void {
+  const prevPaths = new Set(prev.persistence.paths);
+  const nextPaths = new Set(next.persistence.paths);
+  for (const path of nextPaths) {
+    if (!prevPaths.has(path)) {
+      out.push({
+        kind: DriftKind.PERSISTENCE_PATH_ADDED,
+        severity: 'info',
+        path: `$.persistence.paths`,
+        after: path,
+        message: `Persistence path '${path}' added; future pauses will snapshot it.`,
+      });
+    }
+  }
+  for (const path of prevPaths) {
+    if (!nextPaths.has(path)) {
+      out.push({
+        kind: DriftKind.PERSISTENCE_PATH_REMOVED,
+        severity: 'info',
+        path: `$.persistence.paths`,
+        before: path,
+        message: `Persistence path '${path}' removed; future pauses will not snapshot it.`,
+      });
+    }
+  }
+}
+
+function diffOutputSurface(
+  prev: ResolvedEnvironment,
+  next: ResolvedEnvironment,
+  out: EnvironmentDrift[],
+): void {
+  if (
+    prev.outputSurface.kind !== next.outputSurface.kind ||
+    prev.outputSurface.port !== next.outputSurface.port ||
+    prev.outputSurface.healthPath !== next.outputSurface.healthPath ||
+    prev.outputSurface.mode !== next.outputSurface.mode
+  ) {
+    out.push({
+      kind: DriftKind.OUTPUT_SURFACE_CHANGED,
+      severity: 'info',
+      path: '$.outputSurface',
+      before: prev.outputSurface,
+      after: next.outputSurface,
+      message: 'Output surface configuration changed.',
+    });
+  }
+}
+
+function diffEnv(
+  prev: ResolvedEnvironment,
+  next: ResolvedEnvironment,
+  out: EnvironmentDrift[],
+): void {
+  const prevByName = new Map(prev.env.map((e) => [e.name, e.value]));
+  const nextByName = new Map(next.env.map((e) => [e.name, e.value]));
+  for (const [name, value] of nextByName) {
+    const prevValue = prevByName.get(name);
+    if (prevValue === undefined) {
+      out.push({
+        kind: DriftKind.ENV_VAR_ADDED,
+        severity: 'info',
+        path: `$.env[${name}]`,
+        after: value,
+        message: `Env var '${name}' added.`,
+      });
+    } else if (prevValue !== value) {
+      out.push({
+        kind: DriftKind.ENV_VAR_VALUE_CHANGED,
+        severity: 'info',
+        path: `$.env[${name}]`,
+        before: prevValue,
+        after: value,
+        message: `Env var '${name}' value changed.`,
+      });
+    }
+  }
+  for (const name of prevByName.keys()) {
+    if (!nextByName.has(name)) {
+      out.push({
+        kind: DriftKind.ENV_VAR_REMOVED,
+        severity: 'warning',
+        path: `$.env[${name}]`,
+        before: prevByName.get(name),
+        message: `Env var '${name}' removed.`,
+      });
+    }
+  }
+}
+
+function diffMounts(
+  prev: ResolvedEnvironment,
+  next: ResolvedEnvironment,
+  out: EnvironmentDrift[],
+): void {
+  const prevSlots = new Map(prev.mountPlan.entries.map((e) => [e.slot, e]));
+  const nextSlots = new Map(next.mountPlan.entries.map((e) => [e.slot, e]));
+  for (const [slot, entry] of nextSlots) {
+    const prevEntry = prevSlots.get(slot);
+    if (!prevEntry) {
+      out.push({
+        kind: DriftKind.MOUNT_ADDED,
+        severity: 'info',
+        path: `$.mounts[${slot}]`,
+        after: { mountKey: entry.mountKey },
+        message: `Mount slot '${slot}' added.`,
+      });
+      continue;
+    }
+    if (prevEntry.mode !== entry.mode) {
+      out.push({
+        kind: DriftKind.MOUNT_MODE_CHANGED,
+        severity: 'warning',
+        path: `$.mounts[${slot}].mode`,
+        before: prevEntry.mode,
+        after: entry.mode,
+        message: `Mount slot '${slot}' mode changed ${prevEntry.mode} → ${entry.mode}.`,
+      });
+    }
+  }
+  for (const slot of prevSlots.keys()) {
+    if (!nextSlots.has(slot)) {
+      out.push({
+        kind: DriftKind.MOUNT_REMOVED,
+        severity: 'warning',
+        path: `$.mounts[${slot}]`,
+        before: { slot },
+        message: `Mount slot '${slot}' removed.`,
+      });
+    }
+  }
+}