nexus-agents 2.145.1 → 2.146.0

package/dist/chunk-RCQLUJY3.js

@@ -0,0 +1,208 @@
+import {
+  getTimeProvider
+} from "./chunk-Q4UU2W6L.js";
+
+// src/security/audit-trail.ts
+var MAX_EVENTS = 1e4;
+var MAX_STRIPPED_ELEMENTS_PER_EVENT = 20;
+var AuditTrail = class {
+  constructor(durableSink) {
+    this.durableSink = durableSink;
+  }
+  durableSink;
+  events = [];
+  nextId = 1;
+  /** Appends an event to the trail. Returns the assigned event ID. */
+  append(event) {
+    const id = `audit-${String(this.nextId++)}`;
+    const fullEvent = {
+      ...event,
+      id,
+      timestamp: getTimeProvider().nowIso()
+    };
+    this.events.push(fullEvent);
+    this.enforceLimit();
+    if (this.durableSink !== void 0) {
+      try {
+        this.durableSink(fullEvent);
+      } catch {
+      }
+    }
+    return id;
+  }
+  /** Queries events matching the given filter. */
+  query(filter = {}) {
+    let results = this.events;
+    if (filter.type !== void 0) {
+      results = results.filter((e) => e.type === filter.type);
+    }
+    if (filter.since !== void 0) {
+      results = filterSince(results, filter.since);
+    }
+    if (filter.until !== void 0) {
+      results = filterUntil(results, filter.until);
+    }
+    if (filter.trustTier !== void 0) {
+      results = filterByTrustTier(results, filter.trustTier);
+    }
+    if (filter.actionType !== void 0) {
+      results = filterByActionType(results, filter.actionType);
+    }
+    if (filter.actor !== void 0) {
+      results = filterByActor(results, filter.actor);
+    }
+    if (filter.violationRule !== void 0) {
+      results = filterByViolationRule(results, filter.violationRule);
+    }
+    const limit = filter.limit ?? results.length;
+    return results.slice(-limit);
+  }
+  /** Returns the total number of events. */
+  get size() {
+    return this.events.length;
+  }
+  /** Clears all events. */
+  clear() {
+    this.events = [];
+  }
+  /** Enforces MAX_EVENTS bound. */
+  enforceLimit() {
+    if (this.events.length > MAX_EVENTS) {
+      this.events = this.events.slice(-MAX_EVENTS);
+    }
+  }
+};
+function filterSince(events, since) {
+  const sinceTime = new Date(since).getTime();
+  return events.filter((e) => new Date(e.timestamp).getTime() >= sinceTime);
+}
+function filterUntil(events, until) {
+  const untilTime = new Date(until).getTime();
+  return events.filter((e) => new Date(e.timestamp).getTime() <= untilTime);
+}
+function filterByTrustTier(events, tier) {
+  return events.filter((e) => {
+    if (e.type === "trust_classification") return e.assignedTier === tier;
+    if (e.type === "policy_gate") return e.inputTrustTier === tier;
+    if (e.type === "reputation") return e.effectiveTier === tier;
+    return true;
+  });
+}
+function filterByActionType(events, actionType) {
+  return events.filter(
+    (e) => (e.type === "policy_gate" || e.type === "corroboration") && e.actionType === actionType
+  );
+}
+function filterByActor(events, actor) {
+  return events.filter(
+    (e) => (e.type === "trust_classification" || e.type === "reputation") && e.username === actor
+  );
+}
+function filterByViolationRule(events, rule) {
+  return events.filter((e) => e.type === "policy_gate" && e.violationRules.includes(rule));
+}
+function emitTrustEvent(trail, data) {
+  return trail.append({
+    type: "trust_classification",
+    component: "trust-classifier",
+    ...data
+  });
+}
+function emitPolicyEvent(trail, data) {
+  return trail.append({
+    type: "policy_gate",
+    component: "policy-gate",
+    ...data
+  });
+}
+function emitPipelinePolicyEvent(trail, data) {
+  return trail.append({
+    type: "policy_gate",
+    component: "pipeline-policy-evaluator",
+    ...data
+  });
+}
+function emitCorroborationEvent(trail, data) {
+  return trail.append({
+    type: "corroboration",
+    component: "corroboration-validator",
+    ...data
+  });
+}
+function emitReputationEvent(trail, data) {
+  return trail.append({
+    type: "reputation",
+    component: "reputation-model",
+    ...data
+  });
+}
+function emitSanitizationEvent(trail, data) {
+  return trail.append({
+    type: "sanitization",
+    component: "input-sanitizer",
+    ...data
+  });
+}
+function emitGraphExecutionEvent(trail, data) {
+  return trail.append({
+    type: "graph_execution",
+    component: "graph-executor",
+    ...data
+  });
+}
+function emitClawGuardViolation(trail, data) {
+  return trail.append({
+    type: "clawguard_violation",
+    component: "clawguard-audit",
+    ...data
+  });
+}
+function createGraphAuditBridge(trail) {
+  return (event) => {
+    const nodeId = typeof event["nodeId"] === "string" ? event["nodeId"] : void 0;
+    const stepNumber = typeof event["stepNumber"] === "number" ? event["stepNumber"] : 0;
+    emitGraphExecutionEvent(trail, {
+      graphEvent: event.type,
+      ...nodeId !== void 0 ? { nodeId } : {},
+      stepNumber,
+      detail: formatGraphEventDetail(event)
+    });
+  };
+}
+function formatGraphEventDetail(event) {
+  switch (event.type) {
+    case "node_started":
+      return `Node ${String(event["nodeId"])} starting`;
+    case "node_completed":
+      return `Node ${String(event["nodeId"])} completed in ${String(event["durationMs"])}ms`;
+    case "node_error":
+      return `Node ${String(event["nodeId"])} failed: ${String(event["error"])}`;
+    case "state_updated":
+      return `State updated: ${String(event["updatedKeys"])}`;
+    case "step_completed":
+      return `Step ${String(event["stepNumber"])}: ${String(event["nodesExecuted"])} nodes`;
+    case "execution_complete":
+      return `Complete: ${String(event["totalSteps"])} steps, ${String(event["durationMs"])}ms`;
+    default:
+      return event.type;
+  }
+}
+function createAuditTrail(durableSink) {
+  return new AuditTrail(durableSink);
+}
+
+export {
+  MAX_STRIPPED_ELEMENTS_PER_EVENT,
+  AuditTrail,
+  emitTrustEvent,
+  emitPolicyEvent,
+  emitPipelinePolicyEvent,
+  emitCorroborationEvent,
+  emitReputationEvent,
+  emitSanitizationEvent,
+  emitGraphExecutionEvent,
+  emitClawGuardViolation,
+  createGraphAuditBridge,
+  createAuditTrail
+};
+//# sourceMappingURL=chunk-RCQLUJY3.js.map

package/dist/chunk-RCQLUJY3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/security/audit-trail.ts"],"sourcesContent":["/**\n * nexus-agents/security - Audit Trail\n *\n * Machine-readable JSON audit events for security pipeline decisions.\n * Every trust classification, policy gate decision, corroboration check,\n * and reputation assessment is recorded as a structured event.\n *\n * Satisfies CLAUDE.md requirement: \"Every action on untrusted input must\n * log: trust tier, sources cited, policy gate decision, stripped content.\"\n *\n * @module security/audit-trail\n * (Source: Issue #832 — Security audit trail)\n */\n\nimport { getTimeProvider } from '../core/index.js';\nimport type { TrustTier } from './trust-types.js';\nimport type { AgentActionType } from './action-schema.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** Maximum stored events before oldest are evicted. */\nconst MAX_EVENTS = 10_000;\n\n/**\n * Discriminated union of audit event types.\n * Each event captures a single security pipeline decision.\n */\nexport type AuditEvent =\n  | TrustClassificationEvent\n  | PolicyGateEvent\n  | CorroborationEvent\n  | ReputationEvent\n  | SanitizationEvent\n  | GraphExecutionAuditEvent\n  | ClawGuardViolationEvent;\n\n/** Base fields shared by all audit events. */\ninterface AuditEventBase {\n  readonly id: string;\n  readonly timestamp: string;\n  readonly component: string;\n}\n\n/** Trust classification decision. */\nexport interface TrustClassificationEvent extends AuditEventBase {\n  readonly type: 'trust_classification';\n  readonly username: string;\n  readonly assignedTier: TrustTier;\n  readonly userRole: string;\n  readonly isAllowlisted: boolean;\n  readonly wasDowngraded: boolean;\n  readonly reason: string;\n}\n\n/** Policy gate evaluation result. */\nexport interface PolicyGateEvent extends AuditEventBase {\n  readonly type: 'policy_gate';\n  /**\n   * The agent action evaluated, for the security policy-gate path\n   * (security/policy-gate.ts). Optional because the PIPELINE policy path\n   * (pipeline/policy-evaluator.ts → #3710) records stage-boundary policy\n   * decisions that have no `AgentAction` — they carry {@link stageType} +\n   * {@link mode} + {@link ruleIds} instead. Security emitters always set it.\n   */\n  readonly actionType?: AgentActionType;\n  readonly allowed: boolean;\n  readonly requiresApproval: boolean;\n  readonly inputTrustTier: TrustTier;\n  readonly violationRules: readonly string[];\n  /**\n   * Pipeline-policy fields (#3710). Carried for the dev-pipeline\n   * consensus→execute seam so the DURABLE record can distinguish soak (`warn`)\n   * from enforce (`block`) and which rules/stage fired — without these the\n   * persisted event is useless to the tune/readiness loop. Absent for the\n   * security policy-gate path.\n   */\n  /** Enforcement mode the decision was made under: `warn` (soak) or `block` (enforce). */\n  readonly mode?: 'off' | 'warn' | 'block';\n  /** IDs of the policy rules that fired (mirrors `violationRules` for the pipeline path). */\n  readonly ruleIds?: readonly string[];\n  /** Type of the stage the gate guarded (e.g. `execute`). */\n  readonly stageType?: string;\n  /**\n   * #3727: discriminates a per-EVALUATION SUMMARY record (`'summary'` — emitted\n   * once per pipeline policy evaluation INCLUDING clean ones, the DENOMINATOR for\n   * the would-block rate) from a per-VIOLATION record (`'violation'` — the\n   * existing #3710 per-violation records). Absent for the security policy-gate\n   * path. Denominator = count(recordKind==='summary'); numerator = summaries with\n   * `violationCount > 0`. Scope the #3710 count-parity assertion to `'violation'`.\n   */\n  readonly recordKind?: 'summary' | 'violation';\n  /** #3727: number of violations in THIS evaluation (set on the summary record). */\n  readonly violationCount?: number;\n}\n\n/** Corroboration validation result. */\nexport interface CorroborationEvent extends AuditEventBase {\n  readonly type: 'corroboration';\n  readonly actionType: AgentActionType;\n  readonly satisfied: boolean;\n  readonly sourceCount: number;\n  readonly missingRequirements: readonly string[];\n}\n\n/** Reputation assessment result. */\nexport interface ReputationEvent extends AuditEventBase {\n  readonly type: 'reputation';\n  readonly username: string;\n  readonly reputationScore: number;\n  readonly isSuspicious: boolean;\n  readonly effectiveTier: TrustTier;\n  readonly signalCount: number;\n}\n\n/** Summary of a single element stripped during sanitization. */\nexport interface StrippedElementSummary {\n  /** Truncated tag text (≤30 chars + '...' from the sanitizer). */\n  readonly tag: string;\n  /** Reason the element was removed (e.g. 'Trail of Bits injection vector'). */\n  readonly reason: string;\n}\n\n/** Max stripped-element details retained per sanitization event. */\nexport const MAX_STRIPPED_ELEMENTS_PER_EVENT = 20;\n\n/** Input sanitization result. */\nexport interface SanitizationEvent extends AuditEventBase {\n  readonly type: 'sanitization';\n  readonly source: string;\n  readonly wasModified: boolean;\n  readonly strippedCount: number;\n  readonly injectionFlagCount: number;\n  /**\n   * Per-element tag/reason details, truncated to at most\n   * MAX_STRIPPED_ELEMENTS_PER_EVENT entries. Required by CLAUDE.md's\n   * Untrusted Input Policy: \"Log stripped elements for audit trail.\"\n   */\n  readonly strippedElements: readonly StrippedElementSummary[];\n}\n\n/**\n * ClawGuard AUDIT-mode violation (#4097). Records a tool call that VIOLATED the\n * derived access policy but was ALLOWED to proceed because the policy is in\n * `audit` mode (log-and-allow). Persisting these is what lets the audit→enforce\n * graduation loop size the real violation rate from durable telemetry rather\n * than ephemeral logs.\n */\nexport interface ClawGuardViolationEvent extends AuditEventBase {\n  readonly type: 'clawguard_violation';\n  /** The tool whose call violated the policy. */\n  readonly toolName: string;\n  /** Human-readable warning from the access decision (may be truncated). */\n  readonly warning: string;\n  /** Source of the derived policy (`llm` / `fallback-keyword` / `bypass`). */\n  readonly policySource: string;\n  /** Policy mode under which the violation was allowed (e.g. `audit`). */\n  readonly mode: string;\n  /** Request ID of the offending tool call, for correlation. */\n  readonly requestId: string;\n}\n\n/** Graph execution lifecycle event (Issue #839). */\nexport interface GraphExecutionAuditEvent extends AuditEventBase {\n  readonly type: 'graph_execution';\n  readonly graphEvent: string;\n  readonly nodeId?: string;\n  readonly stepNumber: number;\n  readonly detail: string;\n}\n\n/**\n * Query filter for retrieving audit events.\n *\n * The post-mortem dimensions (#3197) — `actionType`, `actor`, `violationRule`\n * — NARROW to events that actually carry the field (events lacking it are\n * excluded), unlike `trustTier`'s legacy keep-non-applicable behavior. Only\n * dimensions backed by a real event field are offered: `resource` and\n * `policyName` from the original ask were dropped because no AuditEvent\n * records them (a filter with no backing field would be dead config); the\n * policy-rule intent is served by `violationRule` (PolicyGateEvent's\n * `violationRules`).\n */\nexport interface AuditQuery {\n  readonly type?: AuditEvent['type'];\n  readonly since?: string;\n  readonly until?: string;\n  readonly trustTier?: TrustTier;\n  /** Match PolicyGate/Corroboration events by their `actionType`. */\n  readonly actionType?: AgentActionType;\n  /** Match Trust/Reputation events by `username` (the acting/assessed user). */\n  readonly actor?: string;\n  /** Match PolicyGate events whose `violationRules` include this rule name. */\n  readonly violationRule?: string;\n  readonly limit?: number;\n}\n\n// ============================================================================\n// AuditTrail\n// ============================================================================\n\n/**\n * Append-only audit trail for security pipeline decisions.\n * Events are bounded by MAX_EVENTS to prevent unbounded growth.\n */\n/**\n * Optional durable sink: receives every fully-formed event appended to the\n * trail, so security decisions can be mirrored to a persistent, hash-chained\n * store (see security/audit-bridge.ts). Default-off — when absent, the trail\n * behaves exactly as before (#3291).\n */\nexport type DurableAuditSink = (event: AuditEvent) => void;\n\nexport class AuditTrail {\n  private events: AuditEvent[] = [];\n  private nextId = 1;\n\n  constructor(private readonly durableSink?: DurableAuditSink) {}\n\n  /** Appends an event to the trail. Returns the assigned event ID. */\n  append(event: Omit<AuditEvent, 'id' | 'timestamp'>): string {\n    const id = `audit-${String(this.nextId++)}`;\n    const fullEvent = {\n      ...event,\n      id,\n      timestamp: getTimeProvider().nowIso(),\n    } as AuditEvent;\n\n    this.events.push(fullEvent);\n    this.enforceLimit();\n\n    // Mirror to the durable store when wired (#3291). Best-effort: a sink\n    // failure must never break the in-memory security pipeline.\n    if (this.durableSink !== undefined) {\n      try {\n        this.durableSink(fullEvent);\n      } catch {\n        // Sink implementations already swallow+log; this is belt-and-suspenders.\n      }\n    }\n\n    return id;\n  }\n\n  /** Queries events matching the given filter. */\n  query(filter: AuditQuery = {}): readonly AuditEvent[] {\n    let results = this.events as readonly AuditEvent[];\n\n    if (filter.type !== undefined) {\n      results = results.filter((e) => e.type === filter.type);\n    }\n\n    if (filter.since !== undefined) {\n      results = filterSince(results, filter.since);\n    }\n\n    if (filter.until !== undefined) {\n      results = filterUntil(results, filter.until);\n    }\n\n    if (filter.trustTier !== undefined) {\n      results = filterByTrustTier(results, filter.trustTier);\n    }\n\n    if (filter.actionType !== undefined) {\n      results = filterByActionType(results, filter.actionType);\n    }\n\n    if (filter.actor !== undefined) {\n      results = filterByActor(results, filter.actor);\n    }\n\n    if (filter.violationRule !== undefined) {\n      results = filterByViolationRule(results, filter.violationRule);\n    }\n\n    const limit = filter.limit ?? results.length;\n    return results.slice(-limit);\n  }\n\n  /** Returns the total number of events. */\n  get size(): number {\n    return this.events.length;\n  }\n\n  /** Clears all events. */\n  clear(): void {\n    this.events = [];\n  }\n\n  /** Enforces MAX_EVENTS bound. */\n  private enforceLimit(): void {\n    if (this.events.length > MAX_EVENTS) {\n      this.events = this.events.slice(-MAX_EVENTS);\n    }\n  }\n}\n\n// ============================================================================\n// Filter Helpers\n// ============================================================================\n\nfunction filterSince(events: readonly AuditEvent[], since: string): readonly AuditEvent[] {\n  const sinceTime = new Date(since).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() >= sinceTime);\n}\n\nfunction filterUntil(events: readonly AuditEvent[], until: string): readonly AuditEvent[] {\n  const untilTime = new Date(until).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() <= untilTime);\n}\n\nfunction filterByTrustTier(events: readonly AuditEvent[], tier: TrustTier): readonly AuditEvent[] {\n  return events.filter((e) => {\n    if (e.type === 'trust_classification') return e.assignedTier === tier;\n    if (e.type === 'policy_gate') return e.inputTrustTier === tier;\n    if (e.type === 'reputation') return e.effectiveTier === tier;\n    return true;\n  });\n}\n\n/**\n * Narrow to events carrying the given `actionType` (#3197). Only PolicyGate and\n * Corroboration events have one; all others are excluded.\n */\nfunction filterByActionType(\n  events: readonly AuditEvent[],\n  actionType: AgentActionType\n): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'policy_gate' || e.type === 'corroboration') && e.actionType === actionType\n  );\n}\n\n/**\n * Narrow to events for the given actor (#3197), matched on `username`. Only\n * Trust-classification and Reputation events carry a username; others are\n * excluded so an actor filter never returns unrelated rows.\n */\nfunction filterByActor(events: readonly AuditEvent[], actor: string): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'trust_classification' || e.type === 'reputation') && e.username === actor\n  );\n}\n\n/**\n * Narrow to PolicyGate events whose `violationRules` include the given rule\n * name (#3197) — the security post-mortem \"who tripped rule X\" query.\n */\nfunction filterByViolationRule(events: readonly AuditEvent[], rule: string): readonly AuditEvent[] {\n  return events.filter((e) => e.type === 'policy_gate' && e.violationRules.includes(rule));\n}\n\n// ============================================================================\n// Convenience Emitters\n// ============================================================================\n\n/**\n * Records a trust classification decision.\n */\nexport function emitTrustEvent(\n  trail: AuditTrail,\n  data: Omit<TrustClassificationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'trust_classification',\n    component: 'trust-classifier',\n    ...data,\n  });\n}\n\n/**\n * Records a policy gate evaluation.\n */\nexport function emitPolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'policy-gate',\n    ...data,\n  });\n}\n\n/**\n * Records a PIPELINE-policy gate decision (#3710) — the dev-pipeline\n * consensus→execute seam. Distinct from {@link emitPolicyEvent} (the security\n * policy-gate path with an `AgentAction`): this carries `mode`/`ruleIds`/\n * `stageType` so the durable record distinguishes soak(warn) from enforce(block)\n * and is usable by the tune/readiness loop. ONE append per call.\n */\nexport function emitPipelinePolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component' | 'actionType'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'pipeline-policy-evaluator',\n    ...data,\n  });\n}\n\n/** The pipeline-policy would-block rate over a window (#3727). */\nexport interface PolicyWouldBlockRate {\n  /** Total pipeline-policy evaluations (the denominator — summary records). */\n  readonly evaluations: number;\n  /** Evaluations that had ≥1 violation (what enforce mode WOULD block). */\n  readonly wouldBlock: number;\n  /** `wouldBlock / evaluations`; 0 when there are no evaluations. */\n  readonly rate: number;\n}\n\n/**\n * Compute the pipeline-policy would-block RATE from durable audit events (#3727)\n * — the read-side of the per-evaluation summary records, and the signal the\n * #3769-enforce soak-readiness gate needs. Denominator = per-evaluation SUMMARY\n * records (`recordKind === 'summary'`); numerator = summaries with\n * `violationCount > 0` (the would-block fraction, independent of warn/block mode).\n * Per-violation records (`recordKind === 'violation'`) are intentionally NOT\n * counted — counting them would double-count and break the denominator.\n */\nexport function computePolicyWouldBlockRate(events: readonly AuditEvent[]): PolicyWouldBlockRate {\n  let evaluations = 0;\n  let wouldBlock = 0;\n  for (const e of events) {\n    if (e.type !== 'policy_gate' || e.recordKind !== 'summary') continue;\n    evaluations += 1;\n    if ((e.violationCount ?? 0) > 0) wouldBlock += 1;\n  }\n  return { evaluations, wouldBlock, rate: evaluations > 0 ? wouldBlock / evaluations : 0 };\n}\n\n/**\n * Records a corroboration validation.\n */\nexport function emitCorroborationEvent(\n  trail: AuditTrail,\n  data: Omit<CorroborationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'corroboration',\n    component: 'corroboration-validator',\n    ...data,\n  });\n}\n\n/**\n * Records a reputation assessment.\n */\nexport function emitReputationEvent(\n  trail: AuditTrail,\n  data: Omit<ReputationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'reputation',\n    component: 'reputation-model',\n    ...data,\n  });\n}\n\n/**\n * Records an input sanitization result.\n */\nexport function emitSanitizationEvent(\n  trail: AuditTrail,\n  data: Omit<SanitizationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'sanitization',\n    component: 'input-sanitizer',\n    ...data,\n  });\n}\n\n/**\n * Records a graph execution lifecycle event.\n */\nexport function emitGraphExecutionEvent(\n  trail: AuditTrail,\n  data: Omit<GraphExecutionAuditEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'graph_execution',\n    component: 'graph-executor',\n    ...data,\n  });\n}\n\n/**\n * Records a ClawGuard AUDIT-mode violation (#4097) — a policy-violating tool\n * call that was log-and-allowed because the policy is in `audit` mode. ONE\n * append per call; mirrors to the durable sink when the trail is wired.\n */\nexport function emitClawGuardViolation(\n  trail: AuditTrail,\n  data: Omit<ClawGuardViolationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'clawguard_violation',\n    component: 'clawguard-audit',\n    ...data,\n  });\n}\n\n/**\n * Creates an onEvent callback that bridges graph events to the audit trail.\n * Pass the returned function as `onEvent` in GraphExecuteOptions.\n *\n * @example\n * const trail = createAuditTrail();\n * await executeGraph(graph, inputs, { onEvent: createGraphAuditBridge(trail) });\n */\nexport function createGraphAuditBridge(\n  trail: AuditTrail\n): (event: { readonly type: string; readonly [key: string]: unknown }) => void {\n  return (event) => {\n    const nodeId = typeof event['nodeId'] === 'string' ? event['nodeId'] : undefined;\n    const stepNumber = typeof event['stepNumber'] === 'number' ? event['stepNumber'] : 0;\n    emitGraphExecutionEvent(trail, {\n      graphEvent: event.type,\n      ...(nodeId !== undefined ? { nodeId } : {}),\n      stepNumber,\n      detail: formatGraphEventDetail(event),\n    });\n  };\n}\n\n/** Formats a brief detail string from a graph event. */\nfunction formatGraphEventDetail(event: {\n  readonly type: string;\n  readonly [key: string]: unknown;\n}): string {\n  switch (event.type) {\n    case 'node_started':\n      return `Node ${String(event['nodeId'])} starting`;\n    case 'node_completed':\n      return `Node ${String(event['nodeId'])} completed in ${String(event['durationMs'])}ms`;\n    case 'node_error':\n      return `Node ${String(event['nodeId'])} failed: ${String(event['error'])}`;\n    case 'state_updated':\n      return `State updated: ${String(event['updatedKeys'])}`;\n    case 'step_completed':\n      return `Step ${String(event['stepNumber'])}: ${String(event['nodesExecuted'])} nodes`;\n    case 'execution_complete':\n      return `Complete: ${String(event['totalSteps'])} steps, ${String(event['durationMs'])}ms`;\n    default:\n      return event.type;\n  }\n}\n\n/**\n * Creates a new AuditTrail instance. Pass a {@link DurableAuditSink} (e.g. from\n * `createDurableAuditSink(auditLogger)`) to mirror appended security decisions\n * to a durable, hash-chained store (#3291). Default: in-memory only.\n */\nexport function createAuditTrail(durableSink?: DurableAuditSink): AuditTrail {\n  return new AuditTrail(durableSink);\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-J2KMYVWA.js → chunk-RII4VXHO.js}

@@ -1,3 +1,6 @@
+import {
+  emitClawGuardViolation
+} from "./chunk-RCQLUJY3.js";
 import {
   CACHE_TIMEOUTS,
   MCP_TIMEOUTS,
@@ -1331,6 +1334,28 @@ function decideOnViolation(toolName, mode) {
 // src/security/access-constraint-deriver/mcp-guard.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
 var accessPolicyStorage = new AsyncLocalStorage2();
+var auditTrailStorage = new AsyncLocalStorage2();
+var MAX_WARNING_LEN = 500;
+function withAuditTrail(trail, fn) {
+  return auditTrailStorage.run(trail, fn);
+}
+function getActiveAuditTrail() {
+  return auditTrailStorage.getStore();
+}
+function recordAuditModeViolation(input) {
+  const trail = getActiveAuditTrail();
+  if (trail === void 0) return;
+  try {
+    emitClawGuardViolation(trail, {
+      toolName: input.toolName,
+      warning: input.warning.slice(0, MAX_WARNING_LEN),
+      policySource: input.policySource,
+      mode: input.mode,
+      requestId: input.requestId
+    });
+  } catch {
+  }
+}
 function withAccessPolicy(policy, fn) {
   return accessPolicyStorage.run(policy, fn);
 }
@@ -1372,6 +1397,13 @@ function createAccessPolicyChainMiddleware(toolName) {
         policySource: policy.source,
         requestId: ctx.requestContext.requestId
       });
+      recordAuditModeViolation({
+        toolName,
+        warning: decision.warning,
+        policySource: policy.source,
+        mode: policy.mode,
+        requestId: ctx.requestContext.requestId
+      });
       return next(args, ctx);
     }
     ctx.logger.info("access-policy: tool call denied", {
@@ -1968,6 +2000,7 @@ export {
   NOOP_NOTIFIER,
   abortSignalStorage,
   withProgressHeartbeat,
+  withAuditTrail,
   withAccessPolicy,
   getToolTimeout,
   wrapToolWithTimeout,
@@ -1990,4 +2023,4 @@ export {
   VOTING_THRESHOLDS,
   ConsensusMetricsSchema
 };
-//# sourceMappingURL=chunk-J2KMYVWA.js.map
+//# sourceMappingURL=chunk-RII4VXHO.js.map