@edictum/core 0.1.0

package/dist/chunk-X5E2YY35.mjs

@@ -0,0 +1,1299 @@
+import {
+  EdictumConfigError,
+  EdictumDenied,
+  EdictumToolError,
+  SideEffect,
+  createEnvelope
+} from "./chunk-CRPQFRYJ.mjs";
+
+// src/approval.ts
+import { randomUUID } from "crypto";
+import * as readline from "readline";
+
+// src/redaction.ts
+var RedactionPolicy = class _RedactionPolicy {
+  static DEFAULT_SENSITIVE_KEYS = /* @__PURE__ */ new Set([
+    "password",
+    "secret",
+    "token",
+    "api_key",
+    "apikey",
+    "api-key",
+    "authorization",
+    "auth",
+    "credentials",
+    "private_key",
+    "privatekey",
+    "access_token",
+    "refresh_token",
+    "client_secret",
+    "connection_string",
+    "database_url",
+    "db_password",
+    "ssh_key",
+    "passphrase"
+  ]);
+  static BASH_REDACTION_PATTERNS = [
+    [
+      String.raw`(export\s+\w*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)\w*=)\S+`,
+      "$1[REDACTED]"
+    ],
+    [String.raw`(-p\s*|--password[= ])\S+`, "$1[REDACTED]"],
+    [String.raw`(://\w+:)\S+(@)`, "$1[REDACTED]$2"]
+  ];
+  static SECRET_VALUE_PATTERNS = [
+    String.raw`^(sk-[a-zA-Z0-9]{20,})`,
+    String.raw`^(AKIA[A-Z0-9]{16})`,
+    String.raw`^(eyJ[a-zA-Z0-9_-]{20,}\.)`,
+    String.raw`^(ghp_[a-zA-Z0-9]{36})`,
+    String.raw`^(xox[bpas]-[a-zA-Z0-9-]{10,})`
+  ];
+  static MAX_PAYLOAD_SIZE = 32768;
+  static MAX_REGEX_INPUT = 1e4;
+  static MAX_PATTERN_LENGTH = 1e4;
+  _keys;
+  _patterns;
+  _compiledPatterns;
+  _compiledSecretPatterns;
+  _detectValues;
+  constructor(sensitiveKeys, customPatterns, detectSecretValues = true) {
+    const baseKeys = sensitiveKeys ? /* @__PURE__ */ new Set([..._RedactionPolicy.DEFAULT_SENSITIVE_KEYS, ...sensitiveKeys]) : new Set(_RedactionPolicy.DEFAULT_SENSITIVE_KEYS);
+    this._keys = new Set([...baseKeys].map((k) => k.toLowerCase()));
+    if (customPatterns) {
+      for (const [pattern] of customPatterns) {
+        if (pattern.length > _RedactionPolicy.MAX_PATTERN_LENGTH) {
+          throw new EdictumConfigError(
+            `Custom redaction pattern exceeds ${_RedactionPolicy.MAX_PATTERN_LENGTH} characters`
+          );
+        }
+      }
+    }
+    this._patterns = [
+      ...customPatterns ?? [],
+      ..._RedactionPolicy.BASH_REDACTION_PATTERNS
+    ];
+    this._compiledPatterns = this._patterns.map(
+      ([pattern, replacement]) => [new RegExp(pattern, "g"), replacement]
+    );
+    this._compiledSecretPatterns = _RedactionPolicy.SECRET_VALUE_PATTERNS.map(
+      (p) => new RegExp(p)
+    );
+    this._detectValues = detectSecretValues;
+  }
+  /** Recursively redact sensitive data from tool arguments. */
+  redactArgs(args) {
+    if (args !== null && typeof args === "object" && !Array.isArray(args)) {
+      const result = {};
+      for (const [key, value] of Object.entries(
+        args
+      )) {
+        result[key] = this._isSensitiveKey(key) ? "[REDACTED]" : this.redactArgs(value);
+      }
+      return result;
+    }
+    if (Array.isArray(args)) {
+      return args.map((item) => this.redactArgs(item));
+    }
+    if (typeof args === "string") {
+      if (this._detectValues && this._looksLikeSecret(args)) {
+        return "[REDACTED]";
+      }
+      if (args.length > 1e3) {
+        return args.slice(0, 997) + "...";
+      }
+      return args;
+    }
+    return args;
+  }
+  /** Check if a key name indicates sensitive data. */
+  _isSensitiveKey(key) {
+    const k = key.toLowerCase();
+    if (this._keys.has(k)) return true;
+    const normalized = key.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+    if (normalized !== k && this._keys.has(normalized)) return true;
+    const parts = normalized.split(/[_\-]/);
+    return parts.some(
+      (part) => part === "token" || part === "key" || part === "secret" || part === "password" || part === "credential"
+    );
+  }
+  /** Check if a string value looks like a known secret format. */
+  _looksLikeSecret(value) {
+    const capped = value.length > _RedactionPolicy.MAX_REGEX_INPUT ? value.slice(0, _RedactionPolicy.MAX_REGEX_INPUT) : value;
+    for (const regex of this._compiledSecretPatterns) {
+      if (regex.test(capped)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /** Apply redaction patterns to a bash command string. */
+  redactBashCommand(command) {
+    const capped = command.length > _RedactionPolicy.MAX_REGEX_INPUT ? command.slice(0, _RedactionPolicy.MAX_REGEX_INPUT) : command;
+    let result = capped;
+    for (const [regex, replacement] of this._compiledPatterns) {
+      regex.lastIndex = 0;
+      result = result.replace(regex, replacement);
+    }
+    return result;
+  }
+  /** Apply redaction patterns and truncate a result string. */
+  redactResult(result, maxLength = 500) {
+    const capped = result.length > _RedactionPolicy.MAX_REGEX_INPUT ? result.slice(0, _RedactionPolicy.MAX_REGEX_INPUT) : result;
+    let redacted = capped;
+    for (const [regex, replacement] of this._compiledPatterns) {
+      regex.lastIndex = 0;
+      redacted = redacted.replace(regex, replacement);
+    }
+    if (redacted.length > maxLength) {
+      redacted = redacted.slice(0, maxLength - 3) + "...";
+    }
+    return redacted;
+  }
+  /** Cap total serialized size of audit payload. Returns a new object if truncated. */
+  capPayload(data) {
+    const serialized = JSON.stringify(data);
+    if (serialized.length > _RedactionPolicy.MAX_PAYLOAD_SIZE) {
+      const { resultSummary: _rs, toolArgs: _ta, ...rest } = data;
+      void _rs;
+      void _ta;
+      return {
+        ...rest,
+        _truncated: true,
+        toolArgs: { _redacted: "payload exceeded 32KB" }
+      };
+    }
+    return data;
+  }
+};
+
+// src/approval.ts
+function sanitizeForTerminal(s) {
+  return s.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/[\x00-\x1f\x7f]/g, "");
+}
+var ApprovalStatus = {
+  PENDING: "pending",
+  APPROVED: "approved",
+  DENIED: "denied",
+  TIMEOUT: "timeout"
+};
+function createApprovalRequest(fields) {
+  const request = {
+    approvalId: fields.approvalId,
+    toolName: fields.toolName,
+    toolArgs: Object.freeze({ ...fields.toolArgs }),
+    message: fields.message,
+    timeout: fields.timeout,
+    timeoutEffect: fields.timeoutEffect,
+    principal: fields.principal !== null ? Object.freeze({ ...fields.principal }) : null,
+    metadata: Object.freeze({ ...fields.metadata }),
+    createdAt: fields.createdAt ?? /* @__PURE__ */ new Date()
+  };
+  return Object.freeze(request);
+}
+function createApprovalDecision(fields) {
+  const decision = {
+    approved: fields.approved,
+    approver: fields.approver ?? null,
+    reason: fields.reason ?? null,
+    status: fields.status ?? ApprovalStatus.PENDING,
+    timestamp: fields.timestamp ?? /* @__PURE__ */ new Date()
+  };
+  return Object.freeze(decision);
+}
+var LocalApprovalBackend = class {
+  _pending = /* @__PURE__ */ new Map();
+  async requestApproval(toolName, toolArgs, message, options) {
+    const approvalId = randomUUID();
+    const request = createApprovalRequest({
+      approvalId,
+      toolName,
+      toolArgs,
+      message,
+      timeout: options?.timeout ?? 300,
+      timeoutEffect: options?.timeoutEffect ?? "deny",
+      principal: options?.principal ?? null,
+      metadata: options?.metadata ?? {}
+    });
+    this._pending.set(approvalId, request);
+    const redaction = new RedactionPolicy();
+    const safeArgs = redaction.redactArgs(toolArgs);
+    process.stdout.write(`[APPROVAL REQUIRED] ${sanitizeForTerminal(message)}
+`);
+    process.stdout.write(`  Tool: ${sanitizeForTerminal(toolName)}
+`);
+    process.stdout.write(`  Args: ${sanitizeForTerminal(JSON.stringify(safeArgs))}
+`);
+    process.stdout.write(`  ID:   ${approvalId}
+`);
+    return request;
+  }
+  async waitForDecision(approvalId, timeout) {
+    const request = this._pending.get(approvalId);
+    const effectiveTimeout = timeout ?? (request ? request.timeout : 300);
+    try {
+      const response = await this._readStdin(approvalId, effectiveTimeout);
+      const approved = ["y", "yes", "approve"].includes(
+        response.trim().toLowerCase()
+      );
+      const status = approved ? ApprovalStatus.APPROVED : ApprovalStatus.DENIED;
+      return createApprovalDecision({
+        approved,
+        approver: "local",
+        status
+      });
+    } catch {
+      const timeoutEffect = request ? request.timeoutEffect : "deny";
+      const approved = timeoutEffect === "allow";
+      return createApprovalDecision({
+        approved,
+        status: ApprovalStatus.TIMEOUT
+      });
+    }
+  }
+  /** Read a single line from stdin with a timeout. */
+  _readStdin(approvalId, timeoutSeconds) {
+    return new Promise((resolve, reject) => {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      const timer = setTimeout(() => {
+        rl.close();
+        reject(new Error("Approval timed out"));
+      }, timeoutSeconds * 1e3);
+      rl.question(`Approve? [y/N] (id: ${approvalId}): `, (answer) => {
+        clearTimeout(timer);
+        rl.close();
+        resolve(answer);
+      });
+    });
+  }
+};
+
+// src/audit.ts
+import { appendFile } from "fs/promises";
+var AuditAction = {
+  CALL_DENIED: "call_denied",
+  CALL_WOULD_DENY: "call_would_deny",
+  CALL_ALLOWED: "call_allowed",
+  CALL_EXECUTED: "call_executed",
+  CALL_FAILED: "call_failed",
+  POSTCONDITION_WARNING: "postcondition_warning",
+  CALL_APPROVAL_REQUESTED: "call_approval_requested",
+  CALL_APPROVAL_GRANTED: "call_approval_granted",
+  CALL_APPROVAL_DENIED: "call_approval_denied",
+  CALL_APPROVAL_TIMEOUT: "call_approval_timeout"
+};
+function createAuditEvent(f = {}) {
+  return {
+    schemaVersion: f.schemaVersion ?? "0.3.0",
+    timestamp: f.timestamp ?? /* @__PURE__ */ new Date(),
+    runId: f.runId ?? "",
+    callId: f.callId ?? "",
+    callIndex: f.callIndex ?? 0,
+    parentCallId: f.parentCallId ?? null,
+    toolName: f.toolName ?? "",
+    toolArgs: f.toolArgs ?? {},
+    sideEffect: f.sideEffect ?? "",
+    environment: f.environment ?? "",
+    principal: f.principal ?? null,
+    action: f.action ?? AuditAction.CALL_DENIED,
+    decisionSource: f.decisionSource ?? null,
+    decisionName: f.decisionName ?? null,
+    reason: f.reason ?? null,
+    hooksEvaluated: f.hooksEvaluated ?? [],
+    contractsEvaluated: f.contractsEvaluated ?? [],
+    toolSuccess: f.toolSuccess ?? null,
+    postconditionsPassed: f.postconditionsPassed ?? null,
+    durationMs: f.durationMs ?? 0,
+    error: f.error ?? null,
+    resultSummary: f.resultSummary ?? null,
+    sessionAttemptCount: f.sessionAttemptCount ?? 0,
+    sessionExecutionCount: f.sessionExecutionCount ?? 0,
+    mode: f.mode ?? "enforce",
+    policyVersion: f.policyVersion ?? null,
+    policyError: f.policyError ?? false
+  };
+}
+var MarkEvictedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MarkEvictedError";
+  }
+};
+var CompositeSink = class {
+  _sinks;
+  constructor(sinks) {
+    if (sinks.length === 0) throw new Error("CompositeSink requires at least one sink");
+    this._sinks = [...sinks];
+  }
+  get sinks() {
+    return [...this._sinks];
+  }
+  async emit(event) {
+    const errors = [];
+    for (const sink of this._sinks) {
+      try {
+        await sink.emit(event);
+      } catch (err) {
+        errors.push(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+    if (errors.length > 0) {
+      throw new AggregateError(errors, "CompositeSink: one or more sinks failed");
+    }
+  }
+};
+function _toPlain(event) {
+  const { timestamp, ...rest } = event;
+  return { ...rest, timestamp: timestamp.toISOString() };
+}
+var StdoutAuditSink = class {
+  _redaction;
+  constructor(redaction) {
+    this._redaction = redaction ?? new RedactionPolicy();
+  }
+  async emit(event) {
+    process.stdout.write(JSON.stringify(this._redaction.capPayload(_toPlain(event))) + "\n");
+  }
+};
+var FileAuditSink = class {
+  _path;
+  _redaction;
+  constructor(path, redaction) {
+    this._path = path;
+    this._redaction = redaction ?? new RedactionPolicy();
+  }
+  async emit(event) {
+    const data = this._redaction.capPayload(_toPlain(event));
+    await appendFile(this._path, JSON.stringify(data) + "\n", "utf-8");
+  }
+};
+var CollectingAuditSink = class {
+  _events = [];
+  _maxEvents;
+  _totalEmitted = 0;
+  constructor(maxEvents = 5e4) {
+    if (maxEvents < 1) throw new Error(`max_events must be >= 1, got ${maxEvents}`);
+    this._maxEvents = maxEvents;
+  }
+  async emit(event) {
+    this._events.push(event);
+    this._totalEmitted += 1;
+    if (this._events.length > this._maxEvents) this._events = this._events.slice(-this._maxEvents);
+  }
+  get events() {
+    return [...this._events];
+  }
+  mark() {
+    return this._totalEmitted;
+  }
+  sinceMark(m) {
+    if (m > this._totalEmitted) {
+      throw new Error(`Mark ${m} is ahead of total emitted (${this._totalEmitted})`);
+    }
+    const evictedCount = this._totalEmitted - this._events.length;
+    if (m < evictedCount) {
+      throw new MarkEvictedError(
+        `Mark ${m} references evicted events (buffer starts at ${evictedCount}, max_events=${this._maxEvents})`
+      );
+    }
+    return [...this._events.slice(m - evictedCount)];
+  }
+  last() {
+    if (this._events.length === 0) throw new Error("No events collected");
+    const last = this._events[this._events.length - 1];
+    if (!last) throw new Error("No events collected");
+    return last;
+  }
+  filter(action) {
+    return this._events.filter((e) => e.action === action);
+  }
+  clear() {
+    this._events = [];
+  }
+};
+
+// src/contracts.ts
+var Verdict = {
+  /**
+   * Contract passed — tool call is acceptable.
+   */
+  pass_() {
+    return Object.freeze({ passed: true, message: null, metadata: Object.freeze({}) });
+  },
+  /**
+   * Contract failed with an actionable message (truncated to 500 chars).
+   *
+   * Make it SPECIFIC and INSTRUCTIVE — the agent uses it to self-correct.
+   */
+  fail(message, metadata = {}) {
+    const truncated = message.length > 500 ? message.slice(0, 497) + "..." : message;
+    return Object.freeze({
+      passed: false,
+      message: truncated,
+      metadata: Object.freeze({ ...metadata })
+    });
+  }
+};
+
+// src/hooks.ts
+var HookResult = {
+  ALLOW: "allow",
+  DENY: "deny"
+};
+var HookDecision = {
+  allow() {
+    return Object.freeze({ result: HookResult.ALLOW, reason: null });
+  },
+  deny(reason) {
+    const truncated = reason.length > 500 ? reason.slice(0, 497) + "..." : reason;
+    return Object.freeze({ result: HookResult.DENY, reason: truncated });
+  }
+};
+
+// src/pipeline.ts
+function createPreDecision(partial) {
+  return {
+    action: partial.action,
+    reason: partial.reason ?? null,
+    decisionSource: partial.decisionSource ?? null,
+    decisionName: partial.decisionName ?? null,
+    hooksEvaluated: partial.hooksEvaluated ?? [],
+    contractsEvaluated: partial.contractsEvaluated ?? [],
+    observed: partial.observed ?? false,
+    policyError: partial.policyError ?? false,
+    observeResults: partial.observeResults ?? [],
+    approvalTimeout: partial.approvalTimeout ?? 300,
+    approvalTimeoutEffect: partial.approvalTimeoutEffect ?? "deny",
+    approvalMessage: partial.approvalMessage ?? null
+  };
+}
+function createPostDecision(partial) {
+  return {
+    toolSuccess: partial.toolSuccess,
+    postconditionsPassed: partial.postconditionsPassed ?? true,
+    warnings: partial.warnings ?? [],
+    contractsEvaluated: partial.contractsEvaluated ?? [],
+    policyError: partial.policyError ?? false,
+    redactedResponse: partial.redactedResponse ?? null,
+    outputSuppressed: partial.outputSuppressed ?? false
+  };
+}
+function hasPolicyError(contractsEvaluated) {
+  return contractsEvaluated.some((c) => {
+    const meta = c["metadata"];
+    return meta?.["policy_error"] === true;
+  });
+}
+var GovernancePipeline = class {
+  _guard;
+  constructor(guard) {
+    this._guard = guard;
+  }
+  async preExecute(envelope, session) {
+    const hooksEvaluated = [];
+    const contractsEvaluated = [];
+    let hasObservedDeny = false;
+    let toolNameForBatch;
+    if (envelope.toolName in this._guard.limits.maxCallsPerTool) {
+      toolNameForBatch = envelope.toolName;
+    }
+    const counters = await session.batchGetCounters({
+      includeTool: toolNameForBatch
+    });
+    const attemptCount = counters["attempts"] ?? 0;
+    if (attemptCount >= this._guard.limits.maxAttempts) {
+      return createPreDecision({
+        action: "deny",
+        reason: `Attempt limit reached (${this._guard.limits.maxAttempts}). Agent may be stuck in a retry loop. Stop and reassess.`,
+        decisionSource: "attempt_limit",
+        decisionName: "max_attempts",
+        hooksEvaluated,
+        contractsEvaluated
+      });
+    }
+    for (const hookReg of this._guard.getHooks("before", envelope)) {
+      if (hookReg.when && !hookReg.when(envelope)) {
+        continue;
+      }
+      let decision;
+      try {
+        decision = await hookReg.callback(envelope);
+      } catch (exc) {
+        decision = HookDecision.deny(`Hook error: ${exc}`);
+      }
+      const hookRecord = {
+        name: hookReg.callback.name || "anonymous",
+        result: decision.result,
+        reason: decision.reason
+      };
+      hooksEvaluated.push(hookRecord);
+      if (decision.result === HookResult.DENY) {
+        return createPreDecision({
+          action: "deny",
+          reason: decision.reason,
+          decisionSource: "hook",
+          decisionName: hookRecord["name"],
+          hooksEvaluated,
+          contractsEvaluated,
+          policyError: (decision.reason ?? "").includes("Hook error:")
+        });
+      }
+    }
+    for (const contract of this._guard.getPreconditions(envelope)) {
+      let verdict;
+      try {
+        verdict = await contract.check(envelope);
+      } catch (exc) {
+        verdict = Verdict.fail(`Precondition error: ${exc}`, {
+          policy_error: true
+        });
+      }
+      const contractRecord = {
+        name: contract.name,
+        type: "precondition",
+        passed: verdict.passed,
+        message: verdict.message
+      };
+      if (verdict.metadata && Object.keys(verdict.metadata).length > 0) {
+        contractRecord["metadata"] = verdict.metadata;
+      }
+      contractsEvaluated.push(contractRecord);
+      if (!verdict.passed) {
+        if (contract.mode === "observe") {
+          contractRecord["observed"] = true;
+          hasObservedDeny = true;
+          continue;
+        }
+        const source = contract.source ?? "precondition";
+        const pe2 = hasPolicyError(contractsEvaluated);
+        const effect = contract.effect ?? "deny";
+        if (effect === "approve") {
+          return createPreDecision({
+            action: "pending_approval",
+            reason: verdict.message,
+            decisionSource: source,
+            decisionName: contract.name,
+            hooksEvaluated,
+            contractsEvaluated,
+            policyError: pe2,
+            approvalTimeout: contract.timeout ?? 300,
+            approvalTimeoutEffect: contract.timeoutEffect ?? "deny",
+            approvalMessage: verdict.message
+          });
+        }
+        return createPreDecision({
+          action: "deny",
+          reason: verdict.message,
+          decisionSource: source,
+          decisionName: contract.name,
+          hooksEvaluated,
+          contractsEvaluated,
+          policyError: pe2
+        });
+      }
+    }
+    for (const contract of this._guard.getSandboxContracts(envelope)) {
+      let verdict;
+      try {
+        verdict = await contract.check(envelope);
+      } catch (exc) {
+        verdict = Verdict.fail(`Sandbox contract error: ${exc}`, {
+          policy_error: true
+        });
+      }
+      const contractRecord = {
+        name: contract.name,
+        type: "sandbox",
+        passed: verdict.passed,
+        message: verdict.message
+      };
+      if (verdict.metadata && Object.keys(verdict.metadata).length > 0) {
+        contractRecord["metadata"] = verdict.metadata;
+      }
+      contractsEvaluated.push(contractRecord);
+      if (!verdict.passed) {
+        if (contract.mode === "observe") {
+          contractRecord["observed"] = true;
+          hasObservedDeny = true;
+          continue;
+        }
+        const source = contract.source ?? "yaml_sandbox";
+        const pe2 = hasPolicyError(contractsEvaluated);
+        const effect = contract.effect ?? "deny";
+        if (effect === "approve") {
+          return createPreDecision({
+            action: "pending_approval",
+            reason: verdict.message,
+            decisionSource: source,
+            decisionName: contract.name,
+            hooksEvaluated,
+            contractsEvaluated,
+            policyError: pe2,
+            approvalTimeout: contract.timeout ?? 300,
+            approvalTimeoutEffect: contract.timeoutEffect ?? "deny",
+            approvalMessage: verdict.message
+          });
+        }
+        return createPreDecision({
+          action: "deny",
+          reason: verdict.message,
+          decisionSource: source,
+          decisionName: contract.name,
+          hooksEvaluated,
+          contractsEvaluated,
+          policyError: pe2
+        });
+      }
+    }
+    for (const contract of this._guard.getSessionContracts()) {
+      let verdict;
+      try {
+        verdict = await contract.check(session);
+      } catch (exc) {
+        verdict = Verdict.fail(`Session contract error: ${exc}`, {
+          policy_error: true
+        });
+      }
+      const contractRecord = {
+        name: contract.name,
+        type: "session_contract",
+        passed: verdict.passed,
+        message: verdict.message
+      };
+      if (verdict.metadata && Object.keys(verdict.metadata).length > 0) {
+        contractRecord["metadata"] = verdict.metadata;
+      }
+      contractsEvaluated.push(contractRecord);
+      if (!verdict.passed) {
+        const source = contract.source ?? "session_contract";
+        const pe2 = hasPolicyError(contractsEvaluated);
+        return createPreDecision({
+          action: "deny",
+          reason: verdict.message,
+          decisionSource: source,
+          decisionName: contract.name,
+          hooksEvaluated,
+          contractsEvaluated,
+          policyError: pe2
+        });
+      }
+    }
+    const execCount = counters["execs"] ?? 0;
+    if (execCount >= this._guard.limits.maxToolCalls) {
+      return createPreDecision({
+        action: "deny",
+        reason: `Execution limit reached (${this._guard.limits.maxToolCalls} calls). Summarize progress and stop.`,
+        decisionSource: "operation_limit",
+        decisionName: "max_tool_calls",
+        hooksEvaluated,
+        contractsEvaluated
+      });
+    }
+    if (envelope.toolName in this._guard.limits.maxCallsPerTool) {
+      const toolKey = `tool:${envelope.toolName}`;
+      const toolCount = counters[toolKey] ?? 0;
+      const toolLimit = this._guard.limits.maxCallsPerTool[envelope.toolName] ?? 0;
+      if (toolCount >= toolLimit) {
+        return createPreDecision({
+          action: "deny",
+          reason: `Per-tool limit: ${envelope.toolName} called ${toolCount} times (limit: ${toolLimit}).`,
+          decisionSource: "operation_limit",
+          decisionName: `max_calls_per_tool:${envelope.toolName}`,
+          hooksEvaluated,
+          contractsEvaluated
+        });
+      }
+    }
+    const pe = hasPolicyError(contractsEvaluated);
+    const observeResults = await this._evaluateObserveContracts(
+      envelope,
+      session
+    );
+    return createPreDecision({
+      action: "allow",
+      hooksEvaluated,
+      contractsEvaluated,
+      observed: hasObservedDeny,
+      policyError: pe,
+      observeResults
+    });
+  }
+  async postExecute(envelope, toolResponse, toolSuccess) {
+    const warnings = [];
+    const contractsEvaluated = [];
+    let redactedResponse = null;
+    let outputSuppressed = false;
+    for (const contract of this._guard.getPostconditions(envelope)) {
+      let verdict;
+      try {
+        verdict = await contract.check(envelope, toolResponse);
+      } catch (exc) {
+        verdict = Verdict.fail(`Postcondition error: ${exc}`, {
+          policy_error: true
+        });
+      }
+      const contractRecord = {
+        name: contract.name,
+        type: "postcondition",
+        passed: verdict.passed,
+        message: verdict.message
+      };
+      if (verdict.metadata && Object.keys(verdict.metadata).length > 0) {
+        contractRecord["metadata"] = verdict.metadata;
+      }
+      contractsEvaluated.push(contractRecord);
+      if (!verdict.passed) {
+        const effect = contract.effect ?? "warn";
+        const contractMode = contract.mode;
+        const isSafe = envelope.sideEffect === SideEffect.PURE || envelope.sideEffect === SideEffect.READ;
+        if (contractMode === "observe") {
+          contractRecord["observed"] = true;
+          warnings.push(`\u26A0\uFE0F [observe] ${verdict.message}`);
+        } else if (effect === "redact" && isSafe) {
+          const patterns = contract.redactPatterns ?? [];
+          const source = redactedResponse !== null ? redactedResponse : toolResponse;
+          let text = source != null ? String(source) : "";
+          if (patterns.length > 0) {
+            for (const pat of patterns) {
+              const globalPat = pat.global ? pat : new RegExp(pat.source, pat.flags + "g");
+              text = text.replace(globalPat, "[REDACTED]");
+            }
+          } else {
+            const policy = new RedactionPolicy();
+            text = policy.redactResult(text, text.length + 100);
+          }
+          redactedResponse = text;
+          warnings.push(
+            `\u26A0\uFE0F Content redacted by ${contract.name}.`
+          );
+        } else if (effect === "deny" && isSafe) {
+          redactedResponse = `[OUTPUT SUPPRESSED] ${verdict.message}`;
+          outputSuppressed = true;
+          warnings.push(
+            `\u26A0\uFE0F Output suppressed by ${contract.name}.`
+          );
+        } else if ((effect === "redact" || effect === "deny") && !isSafe) {
+          warnings.push(
+            `\u26A0\uFE0F ${verdict.message} Tool already executed \u2014 assess before proceeding.`
+          );
+        } else if (isSafe) {
+          warnings.push(
+            `\u26A0\uFE0F ${verdict.message} Consider retrying.`
+          );
+        } else {
+          warnings.push(
+            `\u26A0\uFE0F ${verdict.message} Tool already executed \u2014 assess before proceeding.`
+          );
+        }
+      }
+    }
+    for (const hookReg of this._guard.getHooks("after", envelope)) {
+      if (hookReg.when && !hookReg.when(envelope)) {
+        continue;
+      }
+      try {
+        await hookReg.callback(envelope, toolResponse);
+      } catch {
+      }
+    }
+    for (const contract of this._guard.getObservePostconditions(envelope)) {
+      let verdict;
+      try {
+        verdict = await contract.check(envelope, toolResponse);
+      } catch (exc) {
+        verdict = Verdict.fail(
+          `Observe-mode postcondition error: ${exc}`,
+          { policy_error: true }
+        );
+      }
+      const record = {
+        name: contract.name,
+        type: "postcondition",
+        passed: verdict.passed,
+        message: verdict.message,
+        observed: true,
+        source: contract.source ?? "yaml_postcondition"
+      };
+      if (verdict.metadata && Object.keys(verdict.metadata).length > 0) {
+        record["metadata"] = verdict.metadata;
+      }
+      contractsEvaluated.push(record);
+      if (!verdict.passed) {
+        warnings.push(`\u26A0\uFE0F [observe] ${verdict.message}`);
+      }
+    }
+    const postconditionsPassed = contractsEvaluated.length > 0 ? contractsEvaluated.every(
+      (c) => c["passed"] === true || c["observed"] === true
+    ) : true;
+    const pe = hasPolicyError(contractsEvaluated);
+    return createPostDecision({
+      toolSuccess,
+      postconditionsPassed,
+      warnings,
+      contractsEvaluated,
+      policyError: pe,
+      redactedResponse,
+      outputSuppressed
+    });
+  }
+  /**
+   * Evaluate observe-mode contracts without affecting the real decision.
+   *
+   * Observe-mode contracts are identified by mode === "observe" on the
+   * internal contract. Results are returned as dicts for audit emission
+   * but never block calls.
+   */
+  async _evaluateObserveContracts(envelope, session) {
+    const results = [];
+    for (const contract of this._guard.getObservePreconditions(
+      envelope
+    )) {
+      let verdict;
+      try {
+        verdict = await contract.check(envelope);
+      } catch (exc) {
+        verdict = Verdict.fail(
+          `Observe-mode precondition error: ${exc}`,
+          { policy_error: true }
+        );
+      }
+      results.push({
+        name: contract.name,
+        type: "precondition",
+        passed: verdict.passed,
+        message: verdict.message,
+        source: contract.source ?? "yaml_precondition"
+      });
+    }
+    for (const contract of this._guard.getObserveSandboxContracts(
+      envelope
+    )) {
+      let verdict;
+      try {
+        verdict = await contract.check(envelope);
+      } catch (exc) {
+        verdict = Verdict.fail(
+          `Observe-mode sandbox error: ${exc}`,
+          { policy_error: true }
+        );
+      }
+      results.push({
+        name: contract.name,
+        type: "sandbox",
+        passed: verdict.passed,
+        message: verdict.message,
+        source: contract.source ?? "yaml_sandbox"
+      });
+    }
+    for (const contract of this._guard.getObserveSessionContracts()) {
+      let verdict;
+      try {
+        verdict = await contract.check(session);
+      } catch (exc) {
+        verdict = Verdict.fail(
+          `Observe-mode session contract error: ${exc}`,
+          { policy_error: true }
+        );
+      }
+      results.push({
+        name: contract.name,
+        type: "session_contract",
+        passed: verdict.passed,
+        message: verdict.message,
+        source: contract.source ?? "yaml_session"
+      });
+    }
+    return results;
+  }
+};
+
+// src/session.ts
+function hasBatchGet(backend) {
+  return "batchGet" in backend;
+}
+var MAX_ID_LENGTH = 1e4;
+function _validateStorageKeyComponent(value, label) {
+  if (!value) {
+    throw new EdictumConfigError(`Invalid ${label}: ${JSON.stringify(value)}`);
+  }
+  if (value.length > MAX_ID_LENGTH) {
+    throw new EdictumConfigError(`Invalid ${label}: exceeds ${MAX_ID_LENGTH} characters`);
+  }
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 32 || code === 127) {
+      throw new EdictumConfigError(`Invalid ${label}: ${JSON.stringify(value)}`);
+    }
+  }
+}
+var Session = class {
+  _sid;
+  _backend;
+  constructor(sessionId, backend) {
+    _validateStorageKeyComponent(sessionId, "session_id");
+    this._sid = sessionId;
+    this._backend = backend;
+  }
+  get sessionId() {
+    return this._sid;
+  }
+  /** Increment attempt counter. Called in PreToolUse (before governance). */
+  async incrementAttempts() {
+    return await this._backend.increment(`s:${this._sid}:attempts`);
+  }
+  async attemptCount() {
+    return Number(await this._backend.get(`s:${this._sid}:attempts`) ?? 0);
+  }
+  /** Record a tool execution. Called in PostToolUse. */
+  async recordExecution(toolName, success) {
+    _validateStorageKeyComponent(toolName, "tool_name");
+    await this._backend.increment(`s:${this._sid}:execs`);
+    await this._backend.increment(`s:${this._sid}:tool:${toolName}`);
+    if (success) {
+      await this._backend.delete(`s:${this._sid}:consec_fail`);
+    } else {
+      await this._backend.increment(`s:${this._sid}:consec_fail`);
+    }
+  }
+  async executionCount() {
+    return Number(await this._backend.get(`s:${this._sid}:execs`) ?? 0);
+  }
+  async toolExecutionCount(tool) {
+    _validateStorageKeyComponent(tool, "tool_name");
+    return Number(
+      await this._backend.get(`s:${this._sid}:tool:${tool}`) ?? 0
+    );
+  }
+  async consecutiveFailures() {
+    return Number(
+      await this._backend.get(`s:${this._sid}:consec_fail`) ?? 0
+    );
+  }
+  /**
+   * Pre-fetch multiple session counters in a single backend call.
+   *
+   * Returns a record with keys: "attempts", "execs", and optionally
+   * "tool:{name}" if includeTool is provided.
+   *
+   * Uses batchGet() on the backend when available (single HTTP round
+   * trip for ServerBackend). Falls back to individual get() calls for
+   * backends without batchGet support.
+   */
+  async batchGetCounters(options) {
+    const keys = [
+      `s:${this._sid}:attempts`,
+      `s:${this._sid}:execs`
+    ];
+    const keyLabels = ["attempts", "execs"];
+    if (options?.includeTool != null) {
+      _validateStorageKeyComponent(options.includeTool, "tool_name");
+      keys.push(`s:${this._sid}:tool:${options.includeTool}`);
+      keyLabels.push(`tool:${options.includeTool}`);
+    }
+    let raw;
+    if (hasBatchGet(this._backend)) {
+      raw = await this._backend.batchGet(keys);
+    } else {
+      raw = {};
+      for (const key of keys) {
+        raw[key] = await this._backend.get(key);
+      }
+    }
+    const result = {};
+    for (let i = 0; i < keys.length; i++) {
+      const label = keyLabels[i] ?? "";
+      const key = keys[i] ?? "";
+      result[label] = Number(raw[key] ?? 0);
+    }
+    return result;
+  }
+};
+
+// src/runner.ts
+function defaultSuccessCheck(_toolName, result) {
+  if (result == null) {
+    return true;
+  }
+  if (typeof result === "object" && !Array.isArray(result)) {
+    const dict = result;
+    if (dict["is_error"]) {
+      return false;
+    }
+  }
+  if (typeof result === "string") {
+    const lower = result.slice(0, 7).toLowerCase();
+    if (lower.startsWith("error:") || lower.startsWith("fatal:")) {
+      return false;
+    }
+  }
+  return true;
+}
+async function _emitRunPreAudit(guard, envelope, session, action, pre) {
+  const event = createAuditEvent({
+    action,
+    runId: envelope.runId,
+    callId: envelope.callId,
+    toolName: envelope.toolName,
+    toolArgs: guard.redaction.redactArgs(envelope.args),
+    sideEffect: envelope.sideEffect,
+    environment: envelope.environment,
+    principal: envelope.principal ? { ...envelope.principal } : null,
+    decisionSource: pre.decisionSource,
+    decisionName: pre.decisionName,
+    reason: pre.reason,
+    hooksEvaluated: pre.hooksEvaluated,
+    contractsEvaluated: pre.contractsEvaluated,
+    sessionAttemptCount: await session.attemptCount(),
+    sessionExecutionCount: await session.executionCount(),
+    mode: guard.mode,
+    policyVersion: guard.policyVersion,
+    policyError: pre.policyError
+  });
+  await guard.auditSink.emit(event);
+}
+async function run(guard, toolName, args, toolCallable, options) {
+  const sessionId = options?.sessionId ?? guard.sessionId;
+  const session = new Session(sessionId, guard.backend);
+  const pipeline = new GovernancePipeline(guard);
+  const env = options?.environment ?? guard.environment;
+  let principal = options?.principal ?? void 0;
+  if (principal === void 0) {
+    const resolved = guard._resolvePrincipal(toolName, args);
+    if (resolved != null) {
+      principal = resolved;
+    }
+  }
+  const envelope = createEnvelope(toolName, args, {
+    runId: sessionId,
+    environment: env,
+    registry: guard.toolRegistry,
+    principal: principal ?? null
+  });
+  await session.incrementAttempts();
+  try {
+    const pre = await pipeline.preExecute(envelope, session);
+    if (pre.action === "pending_approval") {
+      if (guard._approvalBackend == null) {
+        throw new EdictumDenied(
+          `Approval required but no approval backend configured: ${pre.reason}`,
+          pre.decisionSource,
+          pre.decisionName
+        );
+      }
+      const principalDict = envelope.principal ? { ...envelope.principal } : null;
+      const approvalRequest = await guard._approvalBackend.requestApproval(
+        envelope.toolName,
+        envelope.args,
+        pre.approvalMessage ?? pre.reason ?? "",
+        {
+          timeout: pre.approvalTimeout,
+          timeoutEffect: pre.approvalTimeoutEffect,
+          principal: principalDict
+        }
+      );
+      await _emitRunPreAudit(
+        guard,
+        envelope,
+        session,
+        AuditAction.CALL_APPROVAL_REQUESTED,
+        pre
+      );
+      const decision = await guard._approvalBackend.waitForDecision(
+        approvalRequest.approvalId,
+        pre.approvalTimeout
+      );
+      let approved = false;
+      if (decision.status === ApprovalStatus.TIMEOUT) {
+        await _emitRunPreAudit(
+          guard,
+          envelope,
+          session,
+          AuditAction.CALL_APPROVAL_TIMEOUT,
+          pre
+        );
+        if (pre.approvalTimeoutEffect === "allow") {
+          approved = true;
+        }
+      } else if (!decision.approved) {
+        await _emitRunPreAudit(
+          guard,
+          envelope,
+          session,
+          AuditAction.CALL_APPROVAL_DENIED,
+          pre
+        );
+      } else {
+        approved = true;
+        await _emitRunPreAudit(
+          guard,
+          envelope,
+          session,
+          AuditAction.CALL_APPROVAL_GRANTED,
+          pre
+        );
+      }
+      if (approved) {
+        if (guard._onAllow) {
+          try {
+            guard._onAllow(envelope);
+          } catch {
+          }
+        }
+      } else {
+        const denyReason = decision.reason ?? pre.reason ?? "";
+        if (guard._onDeny) {
+          try {
+            guard._onDeny(envelope, denyReason, pre.decisionName);
+          } catch {
+          }
+        }
+        throw new EdictumDenied(
+          decision.reason ?? pre.reason ?? "denied",
+          pre.decisionSource,
+          pre.decisionName
+        );
+      }
+    }
+    const realDeny = pre.action === "deny" && !pre.observed;
+    if (pre.action === "pending_approval") {
+    } else if (realDeny) {
+      const auditAction = guard.mode === "observe" ? AuditAction.CALL_WOULD_DENY : AuditAction.CALL_DENIED;
+      await _emitRunPreAudit(guard, envelope, session, auditAction, pre);
+      if (guard.mode === "enforce") {
+        if (guard._onDeny) {
+          try {
+            guard._onDeny(envelope, pre.reason ?? "", pre.decisionName);
+          } catch {
+          }
+        }
+        throw new EdictumDenied(
+          pre.reason ?? "denied",
+          pre.decisionSource,
+          pre.decisionName
+        );
+      }
+    } else {
+      for (const cr of pre.contractsEvaluated) {
+        if (cr["observed"] && !cr["passed"]) {
+          const observedEvent = createAuditEvent({
+            action: AuditAction.CALL_WOULD_DENY,
+            runId: envelope.runId,
+            callId: envelope.callId,
+            toolName: envelope.toolName,
+            toolArgs: guard.redaction.redactArgs(envelope.args),
+            sideEffect: envelope.sideEffect,
+            environment: envelope.environment,
+            principal: envelope.principal ? { ...envelope.principal } : null,
+            decisionSource: "precondition",
+            decisionName: cr["name"],
+            reason: cr["message"],
+            mode: "observe",
+            policyVersion: guard.policyVersion,
+            policyError: pre.policyError
+          });
+          await guard.auditSink.emit(observedEvent);
+        }
+      }
+      await _emitRunPreAudit(
+        guard,
+        envelope,
+        session,
+        AuditAction.CALL_ALLOWED,
+        pre
+      );
+      if (guard._onAllow) {
+        try {
+          guard._onAllow(envelope);
+        } catch {
+        }
+      }
+    }
+    for (const sr of pre.observeResults) {
+      const observeAction = sr["passed"] ? AuditAction.CALL_ALLOWED : AuditAction.CALL_WOULD_DENY;
+      const observeEvent = createAuditEvent({
+        action: observeAction,
+        runId: envelope.runId,
+        callId: envelope.callId,
+        toolName: envelope.toolName,
+        toolArgs: guard.redaction.redactArgs(envelope.args),
+        sideEffect: envelope.sideEffect,
+        environment: envelope.environment,
+        principal: envelope.principal ? { ...envelope.principal } : null,
+        decisionSource: sr["source"],
+        decisionName: sr["name"],
+        reason: sr["message"],
+        mode: "observe",
+        policyVersion: guard.policyVersion
+      });
+      await guard.auditSink.emit(observeEvent);
+    }
+    let result;
+    let toolSuccess;
+    try {
+      result = toolCallable(envelope.args);
+      if (result != null && typeof result === "object" && typeof result.then === "function") {
+        result = await result;
+      }
+      if (guard._successCheck) {
+        toolSuccess = guard._successCheck(toolName, result);
+      } else {
+        toolSuccess = defaultSuccessCheck(toolName, result);
+      }
+    } catch (e) {
+      result = String(e);
+      toolSuccess = false;
+    }
+    const post = await pipeline.postExecute(envelope, result, toolSuccess);
+    await session.recordExecution(toolName, toolSuccess);
+    const postAction = toolSuccess ? AuditAction.CALL_EXECUTED : AuditAction.CALL_FAILED;
+    const postEvent = createAuditEvent({
+      action: postAction,
+      runId: envelope.runId,
+      callId: envelope.callId,
+      toolName: envelope.toolName,
+      toolArgs: guard.redaction.redactArgs(envelope.args),
+      sideEffect: envelope.sideEffect,
+      environment: envelope.environment,
+      principal: envelope.principal ? { ...envelope.principal } : null,
+      toolSuccess,
+      postconditionsPassed: post.postconditionsPassed,
+      contractsEvaluated: post.contractsEvaluated,
+      sessionAttemptCount: await session.attemptCount(),
+      sessionExecutionCount: await session.executionCount(),
+      mode: guard.mode,
+      policyVersion: guard.policyVersion,
+      policyError: post.policyError
+    });
+    await guard.auditSink.emit(postEvent);
+    if (!toolSuccess) {
+      throw new EdictumToolError(String(result));
+    }
+    return post.redactedResponse != null ? post.redactedResponse : result;
+  } finally {
+  }
+}
+
+export {
+  Verdict,
+  HookResult,
+  HookDecision,
+  Session,
+  RedactionPolicy,
+  ApprovalStatus,
+  LocalApprovalBackend,
+  AuditAction,
+  createAuditEvent,
+  MarkEvictedError,
+  CompositeSink,
+  StdoutAuditSink,
+  FileAuditSink,
+  CollectingAuditSink,
+  createPreDecision,
+  createPostDecision,
+  GovernancePipeline,
+  defaultSuccessCheck,
+  run
+};
+//# sourceMappingURL=chunk-X5E2YY35.mjs.map