nexus-agents 2.95.0 → 2.97.0

package/dist/chunk-5LGAPYX7.js

@@ -0,0 +1,2133 @@
+import {
+  CACHE_TIMEOUTS,
+  MCP_TIMEOUTS,
+  SecurityError,
+  TIMEOUT_GUARD,
+  ValidationError,
+  createLogger,
+  createMetricsMiddleware,
+  err,
+  formatZodError,
+  getErrorMessage,
+  getTimeProvider,
+  ok
+} from "./chunk-JTQLV374.js";
+import {
+  getNexusDataDir
+} from "./chunk-CH7QIDHQ.js";
+
+// src/mcp/middleware/validation.ts
+function validateToolInput(schema, args) {
+  const parsed = schema.safeParse(args);
+  if (parsed.success) {
+    return ok(parsed.data);
+  }
+  const message = formatZodError(parsed.error);
+  const validationError = new ValidationError(`Invalid tool input: ${message}`, {
+    context: {
+      issues: parsed.error.issues,
+      receivedType: typeof args
+    }
+  });
+  return err(validationError);
+}
+function createValidator(schema) {
+  return (args) => validateToolInput(schema, args);
+}
+
+// src/mcp/middleware/rate-limiter.ts
+var DEFAULT_REFILL_INTERVAL_MS = CACHE_TIMEOUTS.rateLimitRefillMs;
+var RateLimiter = class {
+  tokens;
+  capacity;
+  refillRate;
+  refillIntervalMs;
+  lastRefillTime;
+  logger;
+  name;
+  constructor(config) {
+    this.capacity = config.capacity;
+    this.refillRate = config.refillRate;
+    this.refillIntervalMs = config.refillIntervalMs ?? DEFAULT_REFILL_INTERVAL_MS;
+    this.tokens = this.capacity;
+    this.lastRefillTime = getTimeProvider().now();
+    this.name = config.name ?? "rate-limiter";
+    this.logger = config.logger ?? createLogger({ component: this.name });
+    this.logger.debug("Rate limiter initialized", {
+      capacity: this.capacity,
+      refillRate: this.refillRate,
+      refillIntervalMs: this.refillIntervalMs
+    });
+  }
+  /**
+   * Refills tokens based on elapsed time.
+   * Called automatically before each acquire attempt.
+   */
+  refill() {
+    const now = getTimeProvider().now();
+    const elapsed = now - this.lastRefillTime;
+    const intervals = Math.floor(elapsed / this.refillIntervalMs);
+    if (intervals > 0) {
+      const tokensToAdd = intervals * this.refillRate;
+      this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
+      this.lastRefillTime = now - elapsed % this.refillIntervalMs;
+      if (tokensToAdd > 0) {
+        this.logger.debug("Tokens refilled", {
+          added: tokensToAdd,
+          current: this.tokens
+        });
+      }
+    }
+  }
+  /**
+   * Attempts to acquire a token.
+   *
+   * @param count - Number of tokens to acquire (default: 1)
+   * @returns True if tokens were acquired, false if rate limited
+   */
+  tryAcquire(count = 1) {
+    this.refill();
+    if (this.tokens >= count) {
+      this.tokens -= count;
+      this.logger.debug("Token acquired", {
+        requested: count,
+        remaining: this.tokens
+      });
+      return true;
+    }
+    this.logger.warn("Rate limit exceeded", {
+      requested: count,
+      available: this.tokens
+    });
+    return false;
+  }
+  /**
+   * Gets the current state of the rate limiter.
+   *
+   * @returns The current rate limiter state
+   */
+  getState() {
+    this.refill();
+    const nextTokenMs = this.tokens > 0 ? 0 : this.refillIntervalMs - (getTimeProvider().now() - this.lastRefillTime);
+    return {
+      tokens: this.tokens,
+      capacity: this.capacity,
+      nextTokenMs: Math.max(0, nextTokenMs)
+    };
+  }
+  /**
+   * Resets the rate limiter to full capacity.
+   * Useful for testing or after configuration changes.
+   */
+  reset() {
+    this.tokens = this.capacity;
+    this.lastRefillTime = getTimeProvider().now();
+    this.logger.debug("Rate limiter reset", { tokens: this.tokens });
+  }
+};
+function createDefaultRateLimiter(name, logger) {
+  const config = {
+    capacity: 100,
+    refillRate: 10,
+    refillIntervalMs: 1e3
+  };
+  if (name !== void 0) {
+    config.name = name;
+  }
+  if (logger !== void 0) {
+    config.logger = logger;
+  }
+  return new RateLimiter(config);
+}
+
+// src/mcp/middleware/policy-types.ts
+import { z } from "zod";
+var PolicyError = class extends SecurityError {
+  decision;
+  constructor(message, decision) {
+    super(message, {
+      context: {
+        allowed: decision.allowed,
+        reason: decision.reason,
+        ruleName: decision.ruleName,
+        requiredArtifact: decision.requiredArtifact
+      }
+    });
+    this.name = "PolicyError";
+    this.decision = decision;
+  }
+};
+var PolicyConfigSchema = z.object({
+  defaultMode: z.enum(["read-only", "read-write"]).default("read-only"),
+  policyMode: z.enum(["enforce", "warn"]).default("enforce"),
+  allowedPaths: z.array(z.string()).default(["./"])
+});
+
+// src/mcp/middleware/policy-helpers.ts
+function isPathSafe(targetPath, allowedPaths) {
+  const normalizedTarget = normalizePath(targetPath);
+  for (const allowed of allowedPaths) {
+    const normalizedAllowed = normalizePath(allowed);
+    if (normalizedTarget.startsWith(normalizedAllowed)) {
+      return true;
+    }
+  }
+  return false;
+}
+function normalizePath(p) {
+  let normalized = p.replace(/\/{1,100}$/, "");
+  if (normalized === ".") {
+    normalized = "";
+  } else if (normalized.startsWith("./")) {
+    normalized = normalized.slice(2);
+  }
+  if (!normalized.startsWith("/")) {
+    normalized = "/" + normalized;
+  }
+  return normalized;
+}
+function extractPathFromArgs(args) {
+  if (args === null || typeof args !== "object") {
+    return void 0;
+  }
+  const argsObj = args;
+  const pathFields = ["path", "filePath", "file_path", "directory", "dir", "target"];
+  for (const field of pathFields) {
+    const value = argsObj[field];
+    if (typeof value === "string") {
+      return value;
+    }
+  }
+  return void 0;
+}
+
+// src/mcp/middleware/policy-rules.ts
+var MUTATION_TOOLS = /* @__PURE__ */ new Set([
+  "write_file",
+  "edit_file",
+  "delete_file",
+  "create_directory",
+  "remove_directory",
+  "execute_command",
+  "run_shell",
+  "bash",
+  "create_expert",
+  "run_workflow"
+]);
+var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
+  "read_file",
+  "list_directory",
+  "search_files",
+  "get_status",
+  "orchestrate",
+  "delegate_to_model"
+]);
+function isMutationTool(toolName) {
+  if (MUTATION_TOOLS.has(toolName)) {
+    return true;
+  }
+  if (READ_ONLY_TOOLS.has(toolName)) {
+    return false;
+  }
+  return true;
+}
+var denyMutationsWithoutModeRule = {
+  name: "deny-mutations-without-mode",
+  description: "Blocks write operations unless mode is read-write",
+  check(ctx) {
+    if (ctx.mode === "read-write") {
+      return { allowed: true, reason: "Read-write mode enabled" };
+    }
+    if (isMutationTool(ctx.toolName)) {
+      return {
+        allowed: false,
+        reason: `Tool '${ctx.toolName}' is a mutation operation but mode is '${ctx.mode}'. Set mode to 'read-write' to enable.`
+      };
+    }
+    return { allowed: true, reason: "Read-only operation allowed" };
+  }
+};
+var safePathsRule = {
+  name: "safe-paths",
+  description: "Validates paths against allowed root directories",
+  check(ctx) {
+    const targetPath = extractPathFromArgs(ctx.args);
+    if (targetPath === void 0) {
+      return { allowed: true, reason: "No path argument found" };
+    }
+    if (targetPath.includes("..")) {
+      return {
+        allowed: false,
+        reason: `Path contains '..' which may indicate path traversal: ${targetPath}`
+      };
+    }
+    const allowedPaths = ctx.allowedPaths ?? ["./"];
+    if (!isPathSafe(targetPath, allowedPaths)) {
+      return {
+        allowed: false,
+        reason: `Path '${targetPath}' is outside allowed directories: ${allowedPaths.join(", ")}`
+      };
+    }
+    return { allowed: true, reason: "Path is within allowed directories" };
+  }
+};
+
+// src/mcp/middleware/policy.ts
+var PolicyFirewall = class {
+  rules = [];
+  mode;
+  logger;
+  constructor(config) {
+    this.mode = config?.mode ?? "enforce";
+    this.logger = config?.logger ?? createLogger({ component: "policy-firewall" });
+    if (config?.rules) {
+      for (const rule of config.rules) {
+        this.rules.push(rule);
+      }
+    }
+    this.logger.debug("Policy firewall initialized", {
+      mode: this.mode,
+      ruleCount: this.rules.length
+    });
+  }
+  /**
+   * Evaluates all policy rules against the given context.
+   *
+   * Rules are evaluated in order. The first rule that denies stops
+   * evaluation and returns the denial decision.
+   *
+   * @param ctx - The policy context to evaluate
+   * @returns The policy decision
+   */
+  evaluate(ctx) {
+    this.logger.debug("Evaluating policy", {
+      toolName: ctx.toolName,
+      mode: ctx.mode,
+      ruleCount: this.rules.length
+    });
+    if (this.rules.length === 0) {
+      return this.allowWithReason(ctx, "No policy rules configured");
+    }
+    for (const rule of this.rules) {
+      const decision = rule.check(ctx);
+      if (!decision.allowed) {
+        return this.handleDenial(ctx, rule, decision);
+      }
+    }
+    return this.allowWithReason(ctx, "All policy rules passed");
+  }
+  /**
+   * Creates an allow decision with the given reason and logs it.
+   */
+  allowWithReason(ctx, reason) {
+    const decision = { allowed: true, reason };
+    this.logDecision(ctx, decision);
+    return decision;
+  }
+  /**
+   * Handles a rule denial, respecting warn mode if configured.
+   */
+  handleDenial(ctx, rule, decision) {
+    const denialDecision = {
+      ...decision,
+      ruleName: rule.name
+    };
+    this.logDecision(ctx, denialDecision);
+    if (this.mode === "warn") {
+      this.logger.warn("Policy denial overridden by warn mode", {
+        toolName: ctx.toolName,
+        ruleName: rule.name,
+        reason: decision.reason
+      });
+      return {
+        allowed: true,
+        reason: `[WARN MODE] Would be denied: ${decision.reason}`,
+        ruleName: rule.name
+      };
+    }
+    return denialDecision;
+  }
+  /**
+   * Adds a policy rule to the firewall.
+   *
+   * @param rule - The rule to add
+   */
+  addRule(rule) {
+    const existingIndex = this.rules.findIndex((r) => r.name === rule.name);
+    if (existingIndex >= 0) {
+      this.logger.warn("Replacing existing policy rule", { ruleName: rule.name });
+      this.rules[existingIndex] = rule;
+    } else {
+      this.rules.push(rule);
+      this.logger.debug("Policy rule added", { ruleName: rule.name });
+    }
+  }
+  /**
+   * Removes a policy rule by name.
+   *
+   * @param name - The name of the rule to remove
+   * @returns True if the rule was found and removed
+   */
+  removeRule(name) {
+    const index = this.rules.findIndex((r) => r.name === name);
+    if (index >= 0) {
+      this.rules.splice(index, 1);
+      this.logger.debug("Policy rule removed", { ruleName: name });
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Gets all registered policy rules.
+   *
+   * @returns A readonly array of policy rules
+   */
+  getRules() {
+    return [...this.rules];
+  }
+  /**
+   * Sets the policy enforcement mode.
+   *
+   * @param mode - The new enforcement mode
+   */
+  setMode(mode) {
+    const previousMode = this.mode;
+    this.mode = mode;
+    this.logger.info("Policy mode changed", { from: previousMode, to: mode });
+  }
+  /**
+   * Gets the current policy enforcement mode.
+   *
+   * @returns The current mode
+   */
+  getMode() {
+    return this.mode;
+  }
+  /**
+   * Logs a policy decision for audit purposes.
+   */
+  logDecision(ctx, decision) {
+    const logData = {
+      toolName: ctx.toolName,
+      mode: ctx.mode,
+      workflowId: ctx.workflowId,
+      allowed: decision.allowed,
+      reason: decision.reason,
+      ruleName: decision.ruleName
+    };
+    if (decision.allowed) {
+      this.logger.debug("Policy decision: ALLOWED", logData);
+    } else {
+      this.logger.warn("Policy decision: DENIED", logData);
+    }
+  }
+};
+function createDefaultPolicyFirewall(config) {
+  const firewall = new PolicyFirewall(config);
+  firewall.addRule(denyMutationsWithoutModeRule);
+  firewall.addRule(safePathsRule);
+  return firewall;
+}
+function evaluatePolicy(firewall, ctx) {
+  const decision = firewall.evaluate(ctx);
+  if (decision.allowed) {
+    return ok(void 0);
+  }
+  return err(new PolicyError(`Policy denied: ${decision.reason}`, decision));
+}
+function createPolicyContext(toolName, args, options) {
+  const base = {
+    toolName,
+    args,
+    mode: options?.mode ?? "read-only"
+  };
+  const result = { ...base };
+  if (options?.artifacts !== void 0) {
+    result["artifacts"] = options.artifacts;
+  }
+  if (options?.workflowId !== void 0) {
+    result["workflowId"] = options.workflowId;
+  }
+  if (options?.allowedPaths !== void 0) {
+    result["allowedPaths"] = options.allowedPaths;
+  }
+  return result;
+}
+
+// src/audit/secure-handler-audit.ts
+function actorFromContext(ctx, fallback) {
+  const caller = ctx.caller;
+  const clientId = caller.clientId;
+  if (clientId !== void 0 && clientId.length > 0) {
+    return {
+      type: clientId.includes("api") ? "external" : clientId.includes("cli") ? "agent" : "user",
+      id: clientId,
+      name: caller.userAgent
+    };
+  }
+  return fallback ?? { type: "system", id: "unknown", name: "Unknown Caller" };
+}
+function resultToOutcome(isError, isPolicyDenied) {
+  if (isPolicyDenied) return "denied";
+  if (isError === true) return "failure";
+  return "success";
+}
+function logToolInvocationAudit(opts) {
+  opts.auditLogger.logToolInvocation({
+    toolName: opts.toolName,
+    outcome: opts.outcome,
+    actor: opts.actor,
+    requestId: opts.requestId,
+    durationMs: opts.durationMs,
+    errorMessage: opts.errorMessage
+  });
+}
+function logPolicyAudit(opts) {
+  opts.auditLogger.logPolicyDecision({
+    policyName: opts.policyName,
+    decision: opts.decision,
+    reason: opts.reason,
+    toolName: opts.toolName,
+    actor: opts.actor,
+    requestId: opts.requestId
+  });
+}
+function logRateLimitAudit(opts) {
+  opts.auditLogger.logRateLimitViolation({
+    toolName: opts.toolName,
+    actor: opts.actor,
+    currentRate: opts.currentRate,
+    limitRate: opts.limitRate,
+    requestId: opts.requestId
+  });
+}
+
+// src/mcp/error-envelope.ts
+import { z as z2 } from "zod";
+var ErrorCategorySchema = z2.enum([
+  "transient",
+  "validation",
+  "permission",
+  "business",
+  "internal"
+]);
+var ToolErrorEnvelopeSchema = z2.object({
+  errorCategory: ErrorCategorySchema,
+  /** Whether retrying the same call could succeed without caller changes. */
+  isRetryable: z2.boolean(),
+  /** Human-readable summary. Bounded to keep stack traces out of results. */
+  message: z2.string().min(1).max(2e3),
+  /**
+   * Optional structured context. MUST NOT carry secrets, credentials,
+   * absolute filesystem paths, or raw Error/response objects — those are
+   * an information-disclosure risk (this field is not output-sanitized).
+   */
+  detail: z2.record(z2.string(), z2.unknown()).optional()
+});
+var ERROR_ENVELOPE_META_KEY = "nexus-agents/error";
+function defaultRetryable(category) {
+  return category === "transient";
+}
+
+// src/mcp/tools/tool-result.ts
+function toolSuccess(text) {
+  return {
+    content: [{ type: "text", text }]
+  };
+}
+function toolSuccessStructured(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    structuredContent: data
+  };
+}
+function toolStructuredError(input) {
+  const envelope = {
+    errorCategory: input.errorCategory,
+    isRetryable: input.isRetryable ?? defaultRetryable(input.errorCategory),
+    message: input.message,
+    ...input.detail !== void 0 ? { detail: input.detail } : {}
+  };
+  return {
+    isError: true,
+    content: [{ type: "text", text: envelope.message }],
+    _meta: { [ERROR_ENVELOPE_META_KEY]: envelope }
+  };
+}
+function toolError(message) {
+  return toolStructuredError({ errorCategory: "internal", message });
+}
+
+// src/mcp/middleware/request-context.ts
+import { randomBytes } from "crypto";
+function generateRequestId() {
+  const bytes = randomBytes(8);
+  return `req_${bytes.toString("hex")}`;
+}
+function formatTimestamp() {
+  const now = new Date(getTimeProvider().now());
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: "America/New_York",
+    timeZoneName: "shortOffset"
+  });
+  const parts = formatter.formatToParts(now);
+  const offset = parts.find((p) => p.type === "timeZoneName")?.value ?? "-05:00";
+  const base = now.toLocaleString("sv-SE", {
+    timeZone: "America/New_York",
+    hour12: false
+  });
+  return base.replace(" ", "T") + offset.replace("GMT", "");
+}
+function deriveTrustTier(caller) {
+  const knownClients = ["claude-cli", "gemini-cli", "codex-cli"];
+  if (caller.transport === "stdio") return "1";
+  if (caller.authenticated === true) {
+    if (caller.clientId !== void 0 && knownClients.includes(caller.clientId)) {
+      return "1";
+    }
+    return "2";
+  }
+  return "3";
+}
+function createRequestContext(options) {
+  const caller = options.caller ?? {};
+  const context = {
+    requestId: generateRequestId(),
+    timestamp: formatTimestamp(),
+    toolName: options.toolName,
+    caller,
+    trustTier: options.trustTier ?? deriveTrustTier(caller),
+    ...options.traceId !== void 0 && { traceId: options.traceId },
+    ...options.parentSpanId !== void 0 && { parentSpanId: options.parentSpanId }
+  };
+  return Object.freeze(context);
+}
+function contextForLogging(ctx) {
+  return {
+    requestId: ctx.requestId,
+    toolName: ctx.toolName,
+    trustTier: ctx.trustTier,
+    ...ctx.caller.clientId !== void 0 && { clientId: ctx.caller.clientId },
+    ...ctx.traceId !== void 0 && { traceId: ctx.traceId }
+  };
+}
+
+// src/mcp/middleware/tool-input-sanitizer.ts
+var XML_INJECTION_PATTERN = /<\/?(system|human|assistant|instructions|user|prompt|context|tool_use|tool_result)\b[^>]*>/gi;
+var INJECTION_DETECTORS = [
+  { name: "system_prompt_override", pattern: /ignore (?:all )?previous (?:instructions|rules)/i },
+  { name: "role_impersonation", pattern: /i(?:'m| am) the (?:repo |project )?(?:owner|admin)/i },
+  { name: "hidden_instruction", pattern: /<!--[\s\S]*?(?:execute|delete|merge|apply)[\s\S]*?-->/i }
+];
+function sanitizeString(value) {
+  XML_INJECTION_PATTERN.lastIndex = 0;
+  const cleaned = value.replace(XML_INJECTION_PATTERN, "");
+  return { cleaned, modified: cleaned !== value };
+}
+function detectPatterns(value) {
+  const detected = [];
+  for (const { name, pattern } of INJECTION_DETECTORS) {
+    pattern.lastIndex = 0;
+    if (pattern.test(value)) {
+      detected.push(name);
+    }
+  }
+  return detected;
+}
+function sanitizeValue(value, stats) {
+  if (typeof value === "string") {
+    const patterns = detectPatterns(value);
+    if (patterns.length > 0) {
+      stats.patterns.push(...patterns);
+    }
+    const { cleaned, modified } = sanitizeString(value);
+    if (modified) stats.count++;
+    return cleaned;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeValue(item, stats));
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = sanitizeValue(val, stats);
+    }
+    return result;
+  }
+  return value;
+}
+function sanitizeToolInput(args) {
+  if (args === void 0 || args === null) {
+    return { sanitized: args, wasModified: false, modifiedCount: 0, detectedPatterns: [] };
+  }
+  const stats = { count: 0, patterns: [] };
+  const sanitized = sanitizeValue(args, stats);
+  const uniquePatterns = [...new Set(stats.patterns)];
+  return {
+    sanitized,
+    wasModified: stats.count > 0,
+    modifiedCount: stats.count,
+    detectedPatterns: uniquePatterns
+  };
+}
+function logSanitizationResult(result, logger, toolName) {
+  if (result.wasModified) {
+    logger.warn("Tool input sanitized \u2014 XML injection tags stripped", {
+      tool: toolName,
+      modifiedFields: result.modifiedCount
+    });
+  }
+  if (result.detectedPatterns.length > 0) {
+    logger.warn("Injection patterns detected in tool input", {
+      tool: toolName,
+      patterns: result.detectedPatterns
+    });
+  }
+}
+
+// src/mcp/middleware/secure-handler.ts
+function rateLimitError(nextTokenMs) {
+  return toolStructuredError({
+    errorCategory: "transient",
+    message: `Rate limit exceeded. Try again in ${String(nextTokenMs)}ms.`
+  });
+}
+function policyDeniedError(reason, requestId) {
+  return toolStructuredError({
+    errorCategory: "permission",
+    message: `Policy denied: ${reason} (request: ${requestId})`
+  });
+}
+function internalError(message, requestId) {
+  return toolStructuredError({
+    errorCategory: "internal",
+    message: `Internal error: ${message} (request: ${requestId})`
+  });
+}
+var MAX_INPUT_SIZE_BYTES = 10 * 1024 * 1024;
+var SECRET_PATTERNS = [
+  // API keys with common prefixes
+  /\b(sk-[a-zA-Z0-9]{20,})\b/g,
+  /\b(pk-[a-zA-Z0-9]{20,})\b/g,
+  // AWS-style keys
+  /\b(AKIA[A-Z0-9]{16})\b/g,
+  // Bearer tokens in output
+  /Bearer\s+[a-zA-Z0-9_\-.~+/]+=*/g,
+  // Generic long hex secrets (40+ chars)
+  /\b[0-9a-f]{40,}\b/gi,
+  // password= or token= in output
+  /(?:password|token|secret|apikey|api_key)\s*[=:]\s*\S{8,}/gi
+];
+function sanitizeOutput(text, logger) {
+  let sanitized = text;
+  for (const pattern of SECRET_PATTERNS) {
+    const before = sanitized;
+    sanitized = sanitized.replace(pattern, "[REDACTED]");
+    if (sanitized !== before) {
+      logger.warn("Potential secret detected in tool output, redacting", {
+        pattern: pattern.source.slice(0, 30)
+      });
+    }
+  }
+  return sanitized;
+}
+function sanitizeToolResult(result, logger) {
+  for (const item of result.content) {
+    item.text = sanitizeOutput(item.text, logger);
+  }
+}
+function checkInputSize(args, logger, requestId) {
+  if (args === void 0) return null;
+  const inputSize = JSON.stringify(args).length;
+  if (inputSize > MAX_INPUT_SIZE_BYTES) {
+    logger.warn("Input size exceeds limit", { inputSize, limit: MAX_INPUT_SIZE_BYTES });
+    return internalError("Input too large", requestId);
+  }
+  return null;
+}
+function checkRateLimit(rateLimiter, logger) {
+  const acquired = rateLimiter.tryAcquire();
+  if (!acquired) {
+    const state = rateLimiter.getState();
+    logger.warn("Rate limit exceeded");
+    return rateLimitError(state.nextTokenMs);
+  }
+  return null;
+}
+function checkPolicy(opts) {
+  const ctxOpts = {
+    mode: opts.mode,
+    ...opts.allowedPaths && { allowedPaths: opts.allowedPaths }
+  };
+  const decision = opts.firewall.evaluate(createPolicyContext(opts.toolName, opts.args, ctxOpts));
+  if (!decision.allowed) {
+    opts.logger.warn("Policy denied tool execution", {
+      reason: decision.reason,
+      ruleName: decision.ruleName
+    });
+    return policyDeniedError(decision.reason, opts.requestId);
+  }
+  opts.logger.debug("Policy check passed", { reason: decision.reason });
+  return null;
+}
+async function executeHandler(handler, args, ctx, logger) {
+  const startTime = getTimeProvider().now();
+  const result = handler.length >= 2 ? await handler(args, ctx) : await handler(args);
+  const durationMs = getTimeProvider().now() - startTime;
+  if (result.isError === true) {
+    logger.warn("Tool execution completed with error", { durationMs });
+  } else {
+    logger.info("Tool execution completed", { durationMs });
+  }
+  return result;
+}
+function emitToolAudit(auditLogger, toolName, ctx, result, durationMs) {
+  const actor = actorFromContext(ctx);
+  const outcome = resultToOutcome(result.isError, false);
+  auditLogger.logToolInvocation({
+    toolName,
+    outcome,
+    actor,
+    requestId: ctx.requestId,
+    durationMs
+  });
+}
+function emitToolAuditException(auditLogger, toolName, ctx, durationMs) {
+  const actor = actorFromContext(ctx);
+  auditLogger.logToolInvocation({
+    toolName,
+    outcome: "error",
+    actor,
+    requestId: ctx.requestId,
+    durationMs
+  });
+}
+function emitPolicyAudit(auditLogger, toolName, ctx, reason) {
+  const actor = actorFromContext(ctx);
+  auditLogger.logPolicyDecision({
+    policyName: "default",
+    decision: "deny",
+    reason,
+    toolName,
+    actor,
+    requestId: ctx.requestId
+  });
+}
+function emitRateLimitAudit(auditLogger, toolName, ctx) {
+  const actor = actorFromContext(ctx);
+  auditLogger.logRateLimitViolation({
+    toolName,
+    actor,
+    currentRate: 0,
+    limitRate: 0,
+    requestId: ctx.requestId
+  });
+}
+function checkSecurityTier(config, sanitizeResult, logger) {
+  const tier = config.securityTier ?? "standard";
+  if (tier === "standard" || sanitizeResult.detectedPatterns.length === 0) {
+    return null;
+  }
+  logger.warn("Input rejected by security tier validation", {
+    tier,
+    patterns: sanitizeResult.detectedPatterns
+  });
+  return toolStructuredError({
+    errorCategory: "permission",
+    message: `Input validation failed: detected patterns [${sanitizeResult.detectedPatterns.join(", ")}]. Remove prompt injection patterns and retry.`
+  });
+}
+function runPreChecks(config, args, mode, requestContext, logger) {
+  const sizeResult = checkInputSize(args, logger, requestContext.requestId);
+  if (sizeResult) return { error: sizeResult, sanitizedArgs: args };
+  const sanitizeResult = sanitizeToolInput(args);
+  logSanitizationResult(sanitizeResult, logger, config.toolName);
+  const sanitizedArgs = sanitizeResult.wasModified ? sanitizeResult.sanitized : args;
+  const tierError = checkSecurityTier(config, sanitizeResult, logger);
+  if (tierError !== null) return { error: tierError, sanitizedArgs };
+  if (config.rateLimiter) {
+    const rlResult = checkRateLimit(config.rateLimiter, logger);
+    if (rlResult) {
+      if (config.auditLogger)
+        emitRateLimitAudit(config.auditLogger, config.toolName, requestContext);
+      return { error: rlResult, sanitizedArgs };
+    }
+  }
+  if (config.policyFirewall) {
+    const pResult = checkPolicy({
+      firewall: config.policyFirewall,
+      toolName: config.toolName,
+      args: sanitizedArgs,
+      mode,
+      allowedPaths: config.allowedPaths,
+      logger,
+      requestId: requestContext.requestId
+    });
+    if (pResult) {
+      if (config.auditLogger)
+        emitPolicyAudit(config.auditLogger, config.toolName, requestContext, "policy denied");
+      return { error: pResult, sanitizedArgs };
+    }
+  }
+  return { error: null, sanitizedArgs };
+}
+function createSecureHandler(handler, config) {
+  const logger = config.logger ?? createLogger({ tool: config.toolName });
+  const mode = config.executionMode ?? "read-only";
+  return async (args) => {
+    const ctxOpts = {
+      toolName: config.toolName,
+      ...config.callerInfo && { caller: config.callerInfo }
+    };
+    const requestContext = createRequestContext(ctxOpts);
+    const requestLogger = logger.child(contextForLogging(requestContext));
+    requestLogger.info("Tool invocation started");
+    const { error: preCheckError, sanitizedArgs } = runPreChecks(
+      config,
+      args,
+      mode,
+      requestContext,
+      requestLogger
+    );
+    if (preCheckError) return preCheckError;
+    return executeAndAudit(handler, sanitizedArgs, requestContext, requestLogger, config);
+  };
+}
+async function executeAndAudit(handler, sanitizedArgs, requestContext, requestLogger, config) {
+  const execStartTime = getTimeProvider().now();
+  try {
+    const result = await executeHandler(
+      handler,
+      sanitizedArgs,
+      { requestContext, logger: requestLogger },
+      requestLogger
+    );
+    sanitizeToolResult(result, requestLogger);
+    if (config.auditLogger) {
+      emitToolAudit(
+        config.auditLogger,
+        config.toolName,
+        requestContext,
+        result,
+        getTimeProvider().now() - execStartTime
+      );
+    }
+    return result;
+  } catch (error) {
+    const rawMessage = error instanceof Error ? error.message : "Unknown error";
+    requestLogger.error("Tool execution failed", error instanceof Error ? error : void 0);
+    if (config.auditLogger) {
+      emitToolAuditException(
+        config.auditLogger,
+        config.toolName,
+        requestContext,
+        getTimeProvider().now() - execStartTime
+      );
+    }
+    const sanitized = sanitizeOutput(rawMessage, requestLogger);
+    return internalError(sanitized, requestContext.requestId);
+  }
+}
+
+// src/mcp/mcp-notifier.ts
+import { AsyncLocalStorage } from "async_hooks";
+var internalLogger = createLogger({ component: "mcp-notifier" });
+function createMcpNotifier(server) {
+  function send(level, logger, data) {
+    try {
+      server.sendLoggingMessage({ level, logger, data }).catch((error) => {
+        internalLogger.debug("Failed to send MCP notification", {
+          level,
+          logger,
+          error: getErrorMessage(error)
+        });
+      });
+    } catch (error) {
+      internalLogger.debug("Failed to send MCP notification", {
+        level,
+        logger,
+        error: getErrorMessage(error)
+      });
+    }
+  }
+  return {
+    info: (logger, data) => {
+      send("info", logger, data);
+    },
+    debug: (logger, data) => {
+      send("debug", logger, data);
+    },
+    warn: (logger, data) => {
+      send("warning", logger, data);
+    }
+  };
+}
+var NOOP_NOTIFIER = {
+  info: () => void 0,
+  debug: () => void 0,
+  warn: () => void 0
+};
+var progressContextStorage = new AsyncLocalStorage();
+var abortSignalStorage = new AsyncLocalStorage();
+async function withProgressHeartbeat(toolName, notifier, operation, intervalMs = 15e3) {
+  const startTime = Date.now();
+  let beatCount = 0;
+  const progressCtx = progressContextStorage.getStore();
+  const timer = setInterval(() => {
+    beatCount++;
+    const elapsed = Math.round((Date.now() - startTime) / 1e3);
+    if (progressCtx !== void 0) {
+      progressCtx.sendNotification(beatCount);
+    }
+    notifier.debug(toolName, {
+      event: "heartbeat",
+      elapsedSeconds: elapsed,
+      beatCount,
+      hasProgressToken: progressCtx !== void 0
+    });
+  }, intervalMs);
+  try {
+    return await operation();
+  } finally {
+    clearInterval(timer);
+  }
+}
+
+// src/mcp/middleware/tool-wrapper.ts
+import { randomUUID } from "crypto";
+import { appendFileSync, existsSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+
+// src/mcp/middleware/timeout-guard.ts
+var DEFAULT_TIMEOUT_MS = TIMEOUT_GUARD.defaultMs;
+var MAX_TIMEOUT_MS = TIMEOUT_GUARD.maxMs;
+var NEAR_TIMEOUT_THRESHOLD = TIMEOUT_GUARD.nearTimeoutThreshold;
+function createTimeoutError(operationName, timeoutMs) {
+  return {
+    code: "OPERATION_TIMEOUT",
+    message: `Operation '${operationName}' timed out after ${String(timeoutMs)}ms`,
+    operation: operationName,
+    timeoutMs
+  };
+}
+function createGuardError(error, operationName) {
+  const guardError = {
+    code: "GUARD_ERROR",
+    message: getErrorMessage(error),
+    operation: operationName
+  };
+  if (error instanceof Error) {
+    return { ...guardError, cause: error };
+  }
+  return guardError;
+}
+var TimeoutGuard = class {
+  defaultTimeoutMs;
+  maxTimeoutMs;
+  enableLogging;
+  logger;
+  constructor(config) {
+    this.defaultTimeoutMs = config?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxTimeoutMs = config?.maxTimeoutMs ?? MAX_TIMEOUT_MS;
+    this.enableLogging = config?.enableLogging ?? true;
+    this.logger = config?.logger ?? createLogger({ component: "timeout-guard" });
+  }
+  /** Resolves effective timeout and operation name from options. */
+  resolveOptions(options) {
+    return {
+      timeoutMs: Math.min(options?.timeoutMs ?? this.defaultTimeoutMs, this.maxTimeoutMs),
+      operationName: options?.operationName ?? "unknown"
+    };
+  }
+  /**
+   * Executes an async operation with timeout protection.
+   */
+  async execute(operation, options) {
+    const { timeoutMs, operationName } = this.resolveOptions(options);
+    const validationError = this.validateTimeout(timeoutMs, operationName);
+    if (validationError !== null) {
+      return err(validationError);
+    }
+    return this.runGuarded(operation, timeoutMs, operationName, options);
+  }
+  /** Runs the operation with timeout and optional abort signal. */
+  async runGuarded(operation, timeoutMs, operationName, options) {
+    this.logStart(operationName, timeoutMs);
+    const startTime = getTimeProvider().now();
+    const state = { timeoutId: void 0, timedOut: false };
+    try {
+      const result = await this.runWithTimeout(
+        operation,
+        timeoutMs,
+        state,
+        options?.onTimeout,
+        options?.signal
+      );
+      return this.handleSuccess(result, startTime, timeoutMs, operationName);
+    } catch {
+      const cancelled = options?.signal?.aborted === true && !state.timedOut;
+      return err(
+        this.handleFailure(state.timedOut, operationName, timeoutMs, startTime, cancelled)
+      );
+    } finally {
+      if (state.timeoutId !== void 0) {
+        clearTimeout(state.timeoutId);
+      }
+    }
+  }
+  validateTimeout(timeoutMs, operationName) {
+    if (timeoutMs <= 0) {
+      return {
+        code: "INVALID_TIMEOUT",
+        message: `Invalid timeout: ${String(timeoutMs)}ms`,
+        operation: operationName
+      };
+    }
+    return null;
+  }
+  logStart(operationName, timeoutMs) {
+    if (this.enableLogging) {
+      this.logger.debug("Starting guarded operation", { operation: operationName, timeoutMs });
+    }
+  }
+  async runWithTimeout(operation, timeoutMs, state, onTimeout, signal) {
+    const timeoutPromise = new Promise((_resolve, reject) => {
+      state.timeoutId = setTimeout(() => {
+        state.timedOut = true;
+        onTimeout?.();
+        reject(new Error(`Operation timed out after ${String(timeoutMs)}ms`));
+      }, timeoutMs);
+    });
+    const promises = [operation(), timeoutPromise];
+    if (signal !== void 0 && !signal.aborted) {
+      const abortPromise = new Promise((_resolve, reject) => {
+        signal.addEventListener(
+          "abort",
+          () => {
+            reject(new Error("Operation cancelled by client"));
+          },
+          { once: true }
+        );
+      });
+      promises.push(abortPromise);
+    }
+    return Promise.race(promises);
+  }
+  handleSuccess(result, startTime, timeoutMs, operationName) {
+    const durationMs = getTimeProvider().now() - startTime;
+    const nearTimeout = durationMs > timeoutMs * NEAR_TIMEOUT_THRESHOLD;
+    if (nearTimeout && this.enableLogging) {
+      this.logger.warn("Operation completed near timeout threshold", {
+        operation: operationName,
+        durationMs,
+        timeoutMs,
+        thresholdPercent: Math.round(durationMs / timeoutMs * 100)
+      });
+    }
+    if (this.enableLogging) {
+      this.logger.debug("Guarded operation completed", { operation: operationName, durationMs });
+    }
+    return ok({ value: result, durationMs, nearTimeout });
+  }
+  handleFailure(timedOut, operationName, timeoutMs, startTime, cancelled = false) {
+    const durationMs = getTimeProvider().now() - startTime;
+    if (cancelled) {
+      this.logger.info("Operation cancelled by client", {
+        operation: operationName,
+        durationMs
+      });
+      return {
+        code: "OPERATION_CANCELLED",
+        message: `Operation '${operationName}' cancelled by client`,
+        operation: operationName
+      };
+    }
+    if (timedOut) {
+      this.logger.error("Operation timed out", void 0, {
+        operation: operationName,
+        timeoutMs,
+        durationMs
+      });
+      return createTimeoutError(operationName, timeoutMs);
+    }
+    return createGuardError(new Error("Unknown error"), operationName);
+  }
+  /**
+   * Creates a guarded version of an async function.
+   */
+  guard(fn, options) {
+    return async (...args) => {
+      return this.execute(() => fn(...args), options);
+    };
+  }
+};
+
+// src/security/access-constraint-deriver/denylist.ts
+var UNBYPASSABLE_PATH_PATTERNS = [
+  // Environment files
+  ".env",
+  ".env.*",
+  "**/.env",
+  "**/.env.*",
+  // SSH credentials
+  "~/.ssh/**",
+  "**/ssh/id_*",
+  "**/*_rsa",
+  "**/*_ed25519",
+  "**/*.pem",
+  // Cloud credentials
+  "~/.aws/**",
+  "~/.azure/**",
+  "~/.gcp/**",
+  "~/.config/gcloud/**",
+  "~/.kube/config",
+  // Unix secret files
+  "/etc/shadow",
+  "/etc/sudoers",
+  "/etc/sudoers.d/**",
+  // Common secret file patterns
+  "**/secrets.*",
+  "**/credentials.*",
+  "**/private_key.*",
+  "**/id_rsa*"
+];
+var UNBYPASSABLE_TOOL_NAMES = [
+  // Destructive git operations
+  "git_push_force",
+  "git_reset_hard",
+  "git_branch_delete_force",
+  "git_clean_force",
+  // Destructive filesystem
+  "rm_recursive_force",
+  "chmod_recursive",
+  // Identity / auth mutations
+  "ssh_add_key",
+  "gpg_add_key",
+  "npm_publish_force",
+  // Remote destruction
+  "github_repo_delete",
+  "github_org_transfer",
+  "aws_account_close"
+];
+function compileGlobToRegex(pattern) {
+  const pat = pattern.toLowerCase();
+  const escaped = pat.replace(/[\\.+^$()|[\]{}]/g, "\\$&").replace(/\*\*/g, "__DOUBLESTAR__").replace(/\*/g, "[^/]*").replace(/__DOUBLESTAR__/g, ".*");
+  const anchored = escaped.startsWith("~/") ? `(^|/)${escaped.slice(2)}$` : escaped.startsWith("/") ? `^${escaped}$` : `(^|/)${escaped}$`;
+  return new RegExp(anchored);
+}
+var COMPILED_PATH_PATTERNS = UNBYPASSABLE_PATH_PATTERNS.map((pattern) => ({
+  pattern,
+  regex: compileGlobToRegex(pattern)
+}));
+function isPathDenied(path) {
+  const normalized = path.toLowerCase();
+  return COMPILED_PATH_PATTERNS.some((c) => c.regex.test(normalized));
+}
+function isToolDenied(toolName) {
+  return UNBYPASSABLE_TOOL_NAMES.includes(toolName);
+}
+
+// src/security/access-constraint-deriver/tool-risk.ts
+var READ_ONLY_TOOLS2 = /* @__PURE__ */ new Set([
+  // Discovery / listing
+  "list_experts",
+  "list_workflows",
+  // Research reads
+  "research_query",
+  "research_analyze",
+  "research_catalog_review",
+  "research_synthesize",
+  // Memory reads
+  "memory_query",
+  "memory_stats",
+  // Observability
+  "weather_report",
+  "query_trace",
+  "query_task_state",
+  // Async-mode result polling (#3042 / epic #2631)
+  "get_job_result",
+  // Async-mode job discovery (#3046 / epic #2631 Stage 5)
+  "list_jobs",
+  // Codebase intelligence (read-only over local files)
+  "search_codebase",
+  "extract_symbols",
+  // Repo analysis (read-only)
+  "repo_analyze",
+  "repo_security_plan",
+  // Routing recommendation (no side effects — returns recommendation)
+  "delegate_to_model",
+  // Registry import (returns a draft template — does not write)
+  "registry_import"
+]);
+function isRiskyTool(toolName) {
+  return !READ_ONLY_TOOLS2.has(toolName);
+}
+
+// src/security/access-constraint-deriver/enforcer.ts
+function checkAccess(toolName, policy, args) {
+  if (isToolDenied(toolName)) {
+    return {
+      decision: "deny",
+      reason: `tool "${toolName}" is on the unbypassable deny-tool list`,
+      matchedRule: "unbypassable:tool"
+    };
+  }
+  if (typeof args?.path === "string" && args.path.length > 0 && isPathDenied(args.path)) {
+    return {
+      decision: "deny",
+      reason: `path "${args.path}" is on the unbypassable deny-path list`,
+      matchedRule: "unbypassable:path"
+    };
+  }
+  if (policy.allowedTools === "*") return { decision: "allow" };
+  if (policy.allowedTools.includes(toolName)) return { decision: "allow" };
+  return decideOnViolation(toolName, policy.mode);
+}
+function decideOnViolation(toolName, mode) {
+  if (mode === "audit") {
+    return {
+      decision: "log-and-allow",
+      warning: `tool "${toolName}" not in derived policy (audit mode)`
+    };
+  }
+  if (mode === "confirm_risky") {
+    if (!isRiskyTool(toolName)) {
+      return {
+        decision: "log-and-allow",
+        warning: `tool "${toolName}" not in derived policy (confirm_risky mode, read-only \u2014 would have required human approval, allowed because read-only)`
+      };
+    }
+    return {
+      decision: "deny",
+      reason: `tool "${toolName}" not in derived policy (confirm_risky mode, risky \u2014 would have required human approval; denied for now, add to allowedTools or run in audit mode to allow)`,
+      matchedRule: "allowedTools:confirm_risky"
+    };
+  }
+  return {
+    decision: "deny",
+    reason: `tool "${toolName}" not in derived policy`,
+    matchedRule: "allowedTools"
+  };
+}
+
+// src/security/access-constraint-deriver/mcp-guard.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+var accessPolicyStorage = new AsyncLocalStorage2();
+function withAccessPolicy(policy, fn) {
+  return accessPolicyStorage.run(policy, fn);
+}
+function getActivePolicy() {
+  return accessPolicyStorage.getStore();
+}
+function denyToToolResult(decision, requestId) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `access denied: ${decision.reason} (rule: ${decision.matchedRule}, request: ${requestId})`
+      }
+    ]
+  };
+}
+
+// src/security/access-constraint-deriver/chain-adapter.ts
+function toGuardArgs(args) {
+  if (typeof args !== "object" || args === null) return void 0;
+  const path = args["path"];
+  return typeof path === "string" && path.length > 0 ? { path } : void 0;
+}
+function createAccessPolicyChainMiddleware(toolName) {
+  return async (args, ctx, next) => {
+    const policy = getActivePolicy();
+    if (policy === void 0 || policy.mode === "off") {
+      return next(args, ctx);
+    }
+    const decision = checkAccess(toolName, policy, toGuardArgs(args));
+    if (decision.decision === "allow") {
+      return next(args, ctx);
+    }
+    if (decision.decision === "log-and-allow") {
+      ctx.logger.warn("access-policy: audit violation", {
+        tool: toolName,
+        warning: decision.warning,
+        policySource: policy.source,
+        requestId: ctx.requestContext.requestId
+      });
+      return next(args, ctx);
+    }
+    ctx.logger.info("access-policy: tool call denied", {
+      tool: toolName,
+      reason: decision.reason,
+      matchedRule: decision.matchedRule,
+      policySource: policy.source,
+      mode: policy.mode,
+      requestId: ctx.requestContext.requestId
+    });
+    return denyToToolResult(decision, ctx.requestContext.requestId);
+  };
+}
+
+// src/mcp/middleware/middleware-chain.ts
+function errorResult(category, message, requestId) {
+  return toolStructuredError({
+    errorCategory: category,
+    message: `${message} (request: ${requestId})`
+  });
+}
+function createValidationMiddleware(schema) {
+  return async (args, ctx, next) => {
+    const result = validateToolInput(schema, args);
+    if (!result.ok) {
+      ctx.logger.warn("Validation failed", {
+        error: result.error.message
+      });
+      return errorResult(
+        "validation",
+        `Validation error: ${result.error.message}`,
+        ctx.requestContext.requestId
+      );
+    }
+    ctx.validatedArgs = result.value;
+    return next(result.value, ctx);
+  };
+}
+function createPolicyMiddleware(firewall, toolName, mode, allowedPaths) {
+  return async (args, ctx, next) => {
+    const policyCtx = createPolicyContext(toolName, args, {
+      mode,
+      ...allowedPaths !== void 0 && { allowedPaths }
+    });
+    const decision = firewall.evaluate(policyCtx);
+    if (!decision.allowed) {
+      ctx.logger.warn("Policy denied", {
+        reason: decision.reason,
+        ruleName: decision.ruleName
+      });
+      return errorResult(
+        "permission",
+        `Policy denied: ${decision.reason}`,
+        ctx.requestContext.requestId
+      );
+    }
+    ctx.logger.debug("Policy check passed", { reason: decision.reason });
+    return next(args, ctx);
+  };
+}
+function createRateLimitMiddleware(limiter) {
+  return async (args, ctx, next) => {
+    const acquired = limiter.tryAcquire();
+    if (!acquired) {
+      const state = limiter.getState();
+      ctx.logger.warn("Rate limit exceeded", {
+        nextTokenMs: state.nextTokenMs
+      });
+      return errorResult(
+        "transient",
+        `Rate limit exceeded. Try again in ${String(state.nextTokenMs)}ms`,
+        ctx.requestContext.requestId
+      );
+    }
+    return next(args, ctx);
+  };
+}
+function createTimeoutMiddleware(guard, toolName) {
+  return async (args, ctx, next) => {
+    const signal = abortSignalStorage.getStore();
+    const result = await guard.execute(() => next(args, ctx), {
+      operationName: toolName,
+      ...signal !== void 0 ? { signal } : {}
+    });
+    if (!result.ok) {
+      ctx.logger.error("Operation timed out", void 0, {
+        code: result.error.code,
+        timeoutMs: result.error.timeoutMs
+      });
+      return errorResult("transient", result.error.message, ctx.requestContext.requestId);
+    }
+    if (result.value.nearTimeout) {
+      ctx.logger.warn("Operation completed near timeout threshold", {
+        durationMs: result.value.durationMs
+      });
+    }
+    return result.value.value;
+  };
+}
+function createAuditMiddleware() {
+  return async (args, ctx, next) => {
+    const startTime = getTimeProvider().now();
+    ctx.logger.info("Tool invocation started");
+    try {
+      const result = await next(args, ctx);
+      const durationMs = getTimeProvider().now() - startTime;
+      if (result.isError === true) {
+        ctx.logger.warn("Tool execution completed with error", { durationMs });
+      } else {
+        ctx.logger.info("Tool execution completed", { durationMs });
+      }
+      return result;
+    } catch (error) {
+      const durationMs = getTimeProvider().now() - startTime;
+      const message = error instanceof Error ? error.message : "Unknown error";
+      ctx.logger.error("Tool execution failed", error instanceof Error ? error : void 0, {
+        durationMs
+      });
+      return errorResult("internal", `Internal error: ${message}`, ctx.requestContext.requestId);
+    }
+  };
+}
+function composeMiddleware(middlewares) {
+  return (args, ctx, finalHandler) => {
+    const dispatch = (index, currentArgs) => {
+      if (index >= middlewares.length) {
+        return finalHandler(currentArgs, ctx);
+      }
+      const middleware = middlewares[index];
+      if (middleware === void 0) {
+        return finalHandler(currentArgs, ctx);
+      }
+      return middleware(currentArgs, ctx, (nextArgs) => dispatch(index + 1, nextArgs));
+    };
+    return dispatch(0, args);
+  };
+}
+function addAuditMiddleware(middlewares, skip) {
+  if (skip.audit !== true) {
+    middlewares.push(createAuditMiddleware());
+  }
+}
+function addRateLimitMiddleware(middlewares, config, skip) {
+  if (skip.rateLimit !== true && config.rateLimiter !== void 0) {
+    const limiter = config.rateLimiter instanceof RateLimiter ? config.rateLimiter : new RateLimiter(config.rateLimiter);
+    middlewares.push(createRateLimitMiddleware(limiter));
+  }
+}
+function addValidationMiddleware(middlewares, config, skip) {
+  if (skip.validation !== true && config.schema !== void 0) {
+    middlewares.push(createValidationMiddleware(config.schema));
+  }
+}
+function addPolicyMiddleware(middlewares, config, skip) {
+  if (skip.policy !== true && config.policyFirewall !== void 0) {
+    const mode = config.executionMode ?? "read-only";
+    middlewares.push(
+      createPolicyMiddleware(config.policyFirewall, config.toolName, mode, config.allowedPaths)
+    );
+  }
+}
+function addTimeoutMiddleware(middlewares, config, skip) {
+  if (skip.timeout !== true && config.timeout !== void 0) {
+    const guard = new TimeoutGuard(config.timeout);
+    middlewares.push(createTimeoutMiddleware(guard, config.toolName));
+  }
+}
+function addAccessPolicyMiddleware(middlewares, config, skip) {
+  if (skip.accessPolicy !== true) {
+    middlewares.push(createAccessPolicyChainMiddleware(config.toolName));
+  }
+}
+function buildMiddlewareStack(config) {
+  const skip = config.skip ?? {};
+  const middlewares = [];
+  middlewares.push(createMetricsMiddleware());
+  addAuditMiddleware(middlewares, skip);
+  addRateLimitMiddleware(middlewares, config, skip);
+  addValidationMiddleware(middlewares, config, skip);
+  addPolicyMiddleware(middlewares, config, skip);
+  addAccessPolicyMiddleware(middlewares, config, skip);
+  addTimeoutMiddleware(middlewares, config, skip);
+  return middlewares;
+}
+function createMiddlewareChain(config) {
+  const logger = config.logger ?? createLogger({ tool: config.toolName });
+  const middlewares = buildMiddlewareStack(config);
+  const composed = composeMiddleware(middlewares);
+  return (handler) => {
+    return async (args) => {
+      const requestContext = createRequestContext({ toolName: config.toolName });
+      const requestLogger = logger.child(contextForLogging(requestContext));
+      const ctx = { requestContext, logger: requestLogger };
+      return composed(args, ctx, (finalArgs, finalCtx) => handler(finalArgs, finalCtx));
+    };
+  };
+}
+function withMiddleware(toolName, handler, options) {
+  const config = {
+    toolName,
+    ...options
+  };
+  const chain = createMiddlewareChain(config);
+  const wrappedHandler = (args, ctx) => {
+    if (handler.length >= 2) {
+      return handler(args, ctx);
+    }
+    return handler(args);
+  };
+  return chain(wrappedHandler);
+}
+
+// src/mcp/middleware/tool-wrapper.ts
+var DEFAULT_TIMEOUT_CONFIG = {
+  defaultTimeoutMs: MCP_TIMEOUTS.defaultMs,
+  maxTimeoutMs: MCP_TIMEOUTS.maxMs,
+  enableLogging: true,
+  uriValidation: true
+};
+var DEFAULT_TOOL_TIMEOUTS = {
+  ...MCP_TIMEOUTS.perTool
+};
+function getToolTimeout(toolName, security, explicitMs) {
+  if (explicitMs !== void 0) {
+    return explicitMs;
+  }
+  const perToolConfig = security?.timeout?.perToolTimeout;
+  const perToolMs = perToolConfig?.[toolName];
+  if (perToolMs !== void 0) {
+    return perToolMs;
+  }
+  const builtInDefault = DEFAULT_TOOL_TIMEOUTS[toolName];
+  if (builtInDefault !== void 0) {
+    return builtInDefault;
+  }
+  return security?.timeout?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_CONFIG.defaultTimeoutMs;
+}
+function getTimeoutConfig(security, overrideMs) {
+  const timeoutConfig = security?.timeout ?? DEFAULT_TIMEOUT_CONFIG;
+  return {
+    defaultTimeoutMs: overrideMs ?? timeoutConfig.defaultTimeoutMs,
+    maxTimeoutMs: timeoutConfig.maxTimeoutMs,
+    enableLogging: timeoutConfig.enableLogging
+  };
+}
+function wrapToolWithTimeout(toolName, handler, options) {
+  return withMiddleware(toolName, handler, {
+    timeout: getTimeoutConfig(void 0, options?.timeoutMs),
+    logger: options?.logger
+  });
+}
+var wrapperLogger = createLogger({ component: "tool-wrapper" });
+function extractProgressContext(extra) {
+  const sdk = extra;
+  const token = sdk?._meta?.progressToken;
+  const sendFn = sdk?.sendNotification;
+  if (token === void 0 || sendFn === void 0) return void 0;
+  return {
+    progressToken: token,
+    sendNotification: (progress, total) => {
+      const params = {
+        progressToken: token,
+        progress
+      };
+      if (total !== void 0) params["total"] = total;
+      sendFn({ method: "notifications/progress", params }).catch((err2) => {
+        wrapperLogger.debug("Failed to send progress notification", {
+          error: getErrorMessage(err2)
+        });
+      });
+    }
+  };
+}
+function runWithContexts(handler, args, progressCtx, signal) {
+  const run = () => handler(args);
+  if (signal !== void 0 && progressCtx !== void 0) {
+    return abortSignalStorage.run(signal, () => progressContextStorage.run(progressCtx, run));
+  }
+  if (signal !== void 0) {
+    return abortSignalStorage.run(signal, run);
+  }
+  if (progressCtx !== void 0) {
+    return progressContextStorage.run(progressCtx, run);
+  }
+  return run();
+}
+function toSdkCallback(handler) {
+  return (args, extra) => {
+    const progressCtx = extractProgressContext(extra);
+    const signal = extra?.signal;
+    return runWithContexts(handler, args, progressCtx, signal);
+  };
+}
+var MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+var TIMEOUT_MISMATCH_TELEMETRY_REL_PATH = "mcp-telemetry/timeout-mismatch-events.jsonl";
+var ensuredDirs = /* @__PURE__ */ new Set();
+function appendTimeoutMismatchEvent(event) {
+  try {
+    const path = join(getNexusDataDir(), TIMEOUT_MISMATCH_TELEMETRY_REL_PATH);
+    const dir = dirname(path);
+    if (!ensuredDirs.has(dir)) {
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      ensuredDirs.add(dir);
+    }
+    appendFileSync(path, JSON.stringify(event) + "\n", "utf-8");
+  } catch (err2) {
+    wrapperLogger.debug("Best-effort timeout-mismatch event recording failed", {
+      error: getErrorMessage(err2)
+    });
+  }
+}
+function extractErrorCategoryFromResult(result) {
+  const envelope = result._meta?.["nexus-agents/error"];
+  if (envelope !== null && typeof envelope === "object" && "errorCategory" in envelope) {
+    const cat = envelope.errorCategory;
+    if (typeof cat === "string") return cat;
+  }
+  return void 0;
+}
+function extractErrorMessageFromResult(result) {
+  const first = result.content[0];
+  if (first?.type === "text" && typeof first.text === "string") {
+    return first.text.slice(0, 500);
+  }
+  return void 0;
+}
+function buildMismatchEvent(ctx, eventId, t0, outcome) {
+  const t1 = Date.now();
+  return {
+    eventId,
+    toolName: ctx.toolName,
+    configuredTimeoutMs: ctx.configuredTimeoutMs,
+    mcpSdkDefaultMs: MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS,
+    startedAt: new Date(t0).toISOString(),
+    endedAt: new Date(t1).toISOString(),
+    durationMs: t1 - t0,
+    outcome: outcome.outcome,
+    ...outcome.errorCategory !== void 0 ? { errorCategory: outcome.errorCategory } : {},
+    ...outcome.errorMessage !== void 0 ? { errorMessage: outcome.errorMessage } : {}
+  };
+}
+function classifyResult(result) {
+  if (result.isError !== true) return { outcome: "success" };
+  const errorCategory = extractErrorCategoryFromResult(result);
+  const errorMessage = extractErrorMessageFromResult(result);
+  return {
+    outcome: "error",
+    ...errorCategory !== void 0 ? { errorCategory } : {},
+    ...errorMessage !== void 0 ? { errorMessage } : {}
+  };
+}
+async function runMismatchedCall(ctx) {
+  const eventId = randomUUID();
+  const t0 = Date.now();
+  ctx.log.warn(
+    "MCP tool budget exceeds client default and no progressToken received \u2014 request likely to be killed by client before server-side deadline",
+    {
+      tool: ctx.toolName,
+      eventId,
+      configuredTimeoutMs: ctx.configuredTimeoutMs,
+      mcpSdkDefaultMs: MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS,
+      remediation: "Client should pass `onprogress` and `resetTimeoutOnProgress: true` when calling, or extend `options.timeout`. See docs/architecture/MCP_PROTOCOL.md."
+    }
+  );
+  try {
+    const result = await runWithContexts(ctx.handler, ctx.args, ctx.progressCtx, ctx.signal);
+    appendTimeoutMismatchEvent(buildMismatchEvent(ctx, eventId, t0, classifyResult(result)));
+    return result;
+  } catch (err2) {
+    appendTimeoutMismatchEvent(
+      buildMismatchEvent(ctx, eventId, t0, {
+        outcome: "error",
+        errorMessage: getErrorMessage(err2).slice(0, 500)
+      })
+    );
+    throw err2;
+  }
+}
+function toSdkCallbackWithBudgetCheck(handler, toolName, configuredTimeoutMs, logger) {
+  const log = logger ?? wrapperLogger;
+  return (args, extra) => {
+    const progressCtx = extractProgressContext(extra);
+    const signal = extra?.signal;
+    const isMismatch = configuredTimeoutMs > MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS && progressCtx === void 0;
+    if (!isMismatch) return runWithContexts(handler, args, progressCtx, signal);
+    return runMismatchedCall({
+      log,
+      handler,
+      args,
+      progressCtx,
+      signal,
+      toolName,
+      configuredTimeoutMs
+    });
+  };
+}
+
+// src/mcp/tool-annotations.ts
+var TOOL_ANNOTATIONS = {
+  // ============================================================================
+  // Orchestration & expert lifecycle
+  // ============================================================================
+  /** Orchestrator coordinates expert agents; spawns workers that may mutate state. */
+  orchestrate: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Creates an expert and adds it to the in-memory expert registry. */
+  create_expert: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  /** Executes a previously created expert; invokes external CLIs. */
+  execute_expert: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  // ============================================================================
+  // Workflow / pipeline execution
+  // ============================================================================
+  /** Runs a workflow template; steps may write to the registry or filesystem. */
+  run_workflow: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Runs a graph-based workflow with checkpointing. */
+  run_graph_workflow: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Runs a pipeline plugin by name. */
+  run_pipeline: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Full dev pipeline: research → plan → vote → implement → QA. */
+  run_dev_pipeline: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Executes an AI-software-factory spec pipeline. */
+  execute_spec: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  // ============================================================================
+  // Voting / decision
+  // ============================================================================
+  /** Records vote outcomes to the audit log; doesn't write to repo state. */
+  consensus_vote: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Per-axis tradeoff vote; records outcome to the store. */
+  supply_chain_tradeoff_panel: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Multi-voter PR review; may write review comments. */
+  pr_review: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  // ============================================================================
+  // Routing & introspection (read-only)
+  // ============================================================================
+  /** Returns a routing recommendation; doesn't execute. */
+  delegate_to_model: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Lists registered expert types. */
+  list_experts: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Lists registered workflow templates. */
+  list_workflows: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  // ============================================================================
+  // Research registry — reads
+  // ============================================================================
+  /** Queries the research registry. */
+  research_query: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Analyzes registry for gaps, trends, coverage. */
+  research_analyze: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Synthesizes registry into topic clusters. */
+  research_synthesize: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Discovers research items via external APIs; doesn't mutate registry. */
+  research_discover: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  // ============================================================================
+  // Research registry — mutations
+  // ============================================================================
+  /** Adds an arXiv paper to the registry. Dedup-checked but first call has effects. */
+  research_add: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Adds a non-paper source to the registry. */
+  research_add_source: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Reviews auto-cataloged research references; may approve/dismiss. */
+  research_catalog_review: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  // ============================================================================
+  // Transient lookups (no registry persistence)
+  // ============================================================================
+  /** Transient OSS search via GitHub API; no persistence. */
+  survey_oss_landscape: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  /** Static lookup against curated vendor seed data. */
+  vendor_publishing_audit: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Diffs two YAML/JSON files; local-only. */
+  compare_data_feeds: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  // ============================================================================
+  // Memory
+  // ============================================================================
+  /** Reads from memory backends. */
+  memory_query: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Returns memory statistics. */
+  memory_stats: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Writes to a memory backend. */
+  memory_write: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  // ============================================================================
+  // Observability
+  // ============================================================================
+  /** Multi-CLI performance weather report; reads outcome store. */
+  weather_report: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Queries execution traces from disk. */
+  query_trace: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Queries structured task-state log. */
+  query_task_state: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Reads job-result sidecar file for an async-mode dispatch (#3042 / #2631). */
+  get_job_result: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Lists async-mode job summaries from the sidecar dir (#3046 / #2631 Stage 5). */
+  list_jobs: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Cancels an in-flight async-mode job (#3042 Stage 1b / #2631). */
+  cancel_job: {
+    // Mutates the sidecar record — NOT read-only.
+    readOnlyHint: false,
+    // Reversibility: cancel writes a new state, but doesn't delete data —
+    // not destructive in the OWASP sense (no irreversible data loss).
+    destructiveHint: false,
+    // Idempotent: repeat cancels are no-ops with explicit outcome envelope.
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Verifies hash chain of audit log files. */
+  verify_audit_chain: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** CI infrastructure health check — composes status-page + recent-runs signals (#3076). */
+  ci_health_check: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    // Hits external services (githubstatus.com + GitHub API) — `openWorldHint`.
+    openWorldHint: true
+  },
+  /** Threshold-gated observability loop; may file GitHub issues when fileIssues=true. */
+  improvement_review: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  // ============================================================================
+  // Repository analysis
+  // ============================================================================
+  /** Analyzes a GitHub repository structure; doesn't write. */
+  repo_analyze: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  /** Generates a security-scanning pipeline plan; returns plan, doesn't write it. */
+  repo_security_plan: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  /** Extracts code symbols from source files. */
+  extract_symbols: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  /** Searches codebase for patterns or symbols. */
+  search_codebase: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  // ============================================================================
+  // Issue triage & registry imports
+  // ============================================================================
+  /** Triages a GitHub issue; may write labels/comments when authorized. */
+  issue_triage: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  /** Generates a draft model-registry entry; doesn't write. */
+  registry_import: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+function getToolAnnotations(name) {
+  const a = TOOL_ANNOTATIONS[name];
+  if (a === void 0) {
+    throw new Error(
+      `getToolAnnotations: no entry for tool "${name}". Add it to TOOL_ANNOTATIONS in src/mcp/tool-annotations.ts (#2648).`
+    );
+  }
+  return a;
+}
+
+export {
+  validateToolInput,
+  createValidator,
+  RateLimiter,
+  createDefaultRateLimiter,
+  PolicyError,
+  PolicyConfigSchema,
+  denyMutationsWithoutModeRule,
+  safePathsRule,
+  PolicyFirewall,
+  createDefaultPolicyFirewall,
+  evaluatePolicy,
+  createPolicyContext,
+  actorFromContext,
+  resultToOutcome,
+  logToolInvocationAudit,
+  logPolicyAudit,
+  logRateLimitAudit,
+  toolSuccess,
+  toolSuccessStructured,
+  toolStructuredError,
+  toolError,
+  createSecureHandler,
+  createMcpNotifier,
+  NOOP_NOTIFIER,
+  abortSignalStorage,
+  withProgressHeartbeat,
+  withAccessPolicy,
+  getToolTimeout,
+  wrapToolWithTimeout,
+  toSdkCallback,
+  toSdkCallbackWithBudgetCheck,
+  getToolAnnotations
+};
+//# sourceMappingURL=chunk-5LGAPYX7.js.map