@goodandready/dsh-approval-gate 0.1.17 → 0.1.19

package/lib/latency.js

@@ -0,0 +1,137 @@
+// lib/latency.js
+// Classifier latency tracking and SLA-based fallback on deterministic rules (#57).
+
+export const DEFAULT_CLASSIFIER_SLA_MS = 2000;
+export const DEFAULT_LATENCY_WINDOW_SIZE = 50;
+export const DEFAULT_DEGRADE_THRESHOLD_COUNT = 3;
+export const DEFAULT_RECOVERY_THRESHOLD_COUNT = 2;
+
+/**
+ * Tracks external semantic classifier latency with sliding window statistics and SLA health (#57).
+ */
+export class ClassifierLatencyTracker {
+  /**
+   * @param {{
+   *   slaMs?: number,
+   *   windowSize?: number,
+   *   degradeThresholdCount?: number,
+   *   recoveryThresholdCount?: number
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.slaMs = typeof options.slaMs === "number" && options.slaMs > 0
+      ? options.slaMs
+      : DEFAULT_CLASSIFIER_SLA_MS;
+    this.windowSize = typeof options.windowSize === "number" && options.windowSize > 0
+      ? options.windowSize
+      : DEFAULT_LATENCY_WINDOW_SIZE;
+    this.degradeThresholdCount = typeof options.degradeThresholdCount === "number" && options.degradeThresholdCount > 0
+      ? options.degradeThresholdCount
+      : DEFAULT_DEGRADE_THRESHOLD_COUNT;
+    this.recoveryThresholdCount = typeof options.recoveryThresholdCount === "number" && options.recoveryThresholdCount > 0
+      ? options.recoveryThresholdCount
+      : DEFAULT_RECOVERY_THRESHOLD_COUNT;
+
+    this._samples = [];
+    this._consecutiveSlow = 0;
+    this._consecutiveFast = 0;
+    this._degraded = false;
+  }
+
+  /**
+   * Records a latency observation in milliseconds.
+   *
+   * @param {number} durationMs
+   * @returns {{ degraded: boolean, p95Ms: number, avgMs: number }}
+   */
+  recordSample(durationMs) {
+    const val = Math.max(0, Number(durationMs) || 0);
+    this._samples.push(val);
+    if (this._samples.length > this.windowSize) {
+      this._samples.shift();
+    }
+
+    if (val > this.slaMs) {
+      this._consecutiveSlow += 1;
+      this._consecutiveFast = 0;
+      if (this._consecutiveSlow >= this.degradeThresholdCount) {
+        this._degraded = true;
+      }
+    } else {
+      this._consecutiveFast += 1;
+      this._consecutiveSlow = 0;
+      if (this._consecutiveFast >= this.recoveryThresholdCount) {
+        this._degraded = false;
+      }
+    }
+
+    if (!this._degraded && this._samples.length >= 5 && this.getP95() > this.slaMs && this._consecutiveSlow > 0) {
+      this._degraded = true;
+    }
+
+    return {
+      degraded: this.isDegraded(),
+      p95Ms: this.getP95(),
+      avgMs: this.getAvg(),
+    };
+  }
+
+  /**
+   * Calculates 95th percentile latency from the current sliding window.
+   * @returns {number}
+   */
+  getP95() {
+    if (this._samples.length === 0) return 0;
+    const sorted = this._samples.slice().sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * 0.95) - 1));
+    return Math.round(sorted[idx] * 10) / 10;
+  }
+
+  /**
+   * Calculates mean latency from current window.
+   * @returns {number}
+   */
+  getAvg() {
+    if (this._samples.length === 0) return 0;
+    const sum = this._samples.reduce((acc, v) => acc + v, 0);
+    return Math.round((sum / this._samples.length) * 10) / 10;
+  }
+
+  /**
+   * Checks whether the classifier is currently marked degraded due to SLA violations.
+   * @returns {boolean}
+   */
+  isDegraded() {
+    return this._degraded;
+  }
+
+  /**
+   * Resets all tracked samples and returns to healthy state.
+   */
+  reset() {
+    this._samples = [];
+    this._consecutiveSlow = 0;
+    this._consecutiveFast = 0;
+    this._degraded = false;
+  }
+
+  /**
+   * Returns a snapshot of current latency metrics.
+   * @returns {{ count: number, avgMs: number, p95Ms: number, minMs: number, maxMs: number, degraded: boolean, slaMs: number, consecutiveSlow: number }}
+   */
+  getMetrics() {
+    const count = this._samples.length;
+    const minMs = count > 0 ? Math.min(...this._samples) : 0;
+    const maxMs = count > 0 ? Math.max(...this._samples) : 0;
+    return {
+      count,
+      avgMs: this.getAvg(),
+      p95Ms: this.getP95(),
+      minMs,
+      maxMs,
+      degraded: this.isDegraded(),
+      slaMs: this.slaMs,
+      consecutiveSlow: this._consecutiveSlow,
+    };
+  }
+}

package/lib/messages.js

@@ -67,6 +67,16 @@ export const MESSAGES = Object.freeze({
     ruleClassifierTimeoutPermissive: "Semantic classifier timed out; allowed by low-risk fallback policy",
     askClassifierTimeout: "Semantic classifier request timed out; human confirmation required",
     askClassifierError: "Semantic classifier error; human confirmation required",
+    askClassifierSlaFallback: "Semantic classifier exceeded SLA latency threshold; manual review required",
+    askMalformedClassifierResponse: "Semantic classifier returned malformed or unverified decision; manual review required",
+    askPayloadTooLarge: "Command arguments exceed maximum payload size limit; review before allowing",
+    ruleReviewerInjectionAttempt: "Prompt instruction injection detected in tool arguments",
+    askContractViolation: "Operation falls outside task contract boundaries; review before allowing",
+    ruleContractViolation: "Execution violated task contract boundaries",
+    askUnisolatedTempPath: "Target path uses global /tmp instead of isolated project temp directory; review before allowing",
+    ruleUnisolatedTempPath: "Target path uses unisolated global temp directory",
+    askOverengineeringLimit: "Session file creation limit exceeded; potential overengineering requires review before allowing",
+    ruleOverengineeringLimit: "Session exceeded maximum allowed created files limit",
     hintRecursiveRm: "Specify exact target files instead of recursive deletion",
     hintPathTraversal: "Keep operations strictly within the project directory",
     hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
@@ -83,6 +93,13 @@ export const MESSAGES = Object.freeze({
     hintFailClosedAudit: "Ensure the audit log directory is writable and disk space is available",
     hintLockedAskUnattended: "Switch to an interactive session or request explicit human confirmation",
     hintClassifierTimeout: "Check external LLM connectivity or review timeout policy settings",
+    hintClassifierSlaFallback: "Check external LLM classifier load or increase classifierSlaMs",
+    hintMalformedClassifierResponse: "Verify model JSON output format or check response schema compatibility",
+    hintPayloadTooLarge: "Reduce input payload size or chunk data into smaller batches",
+    hintReviewerInjectionAttempt: "Remove adversarial prompt override directives from input",
+    hintContractViolation: "Confine operations to permitted task tools and project scope",
+    hintUnisolatedTempPath: "Use workspace-isolated temporary directory (<workspace>/.dsh/tmp)",
+    hintOverengineeringLimit: "Reuse existing files and avoid creating redundant abstractions or boilerplate",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -149,6 +166,16 @@ export const MESSAGES = Object.freeze({
     ruleClassifierTimeoutPermissive: "语义分类器超时；根据低风险容错策略放行",
     askClassifierTimeout: "语义分类器请求超时；需要人工审查",
     askClassifierError: "语义分类器发生异常；需要人工审查",
+    askClassifierSlaFallback: "语义分类器延迟超出 SLA 阈值；需要人工审查",
+    askMalformedClassifierResponse: "语义分类器返回非预期或未通过校验的判定；需要人工审查",
+    askPayloadTooLarge: "命令参数超过最大负载大小限制；请在允许前进行审查",
+    ruleReviewerInjectionAttempt: "在工具参数中检测到提示词指令注入尝试",
+    askContractViolation: "操作超出任务契约范围；请在允许前进行审查",
+    ruleContractViolation: "执行违反了任务契约边界",
+    askUnisolatedTempPath: "目标路径使用全局 /tmp 而非隔离的项目临时目录；请在允许前进行审查",
+    ruleUnisolatedTempPath: "目标路径使用未隔离的全局临时目录",
+    askOverengineeringLimit: "会话创建文件数超过限制；潜在的过度工程需要人工审查",
+    ruleOverengineeringLimit: "会话超出最大允许创建文件数限制",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -165,6 +192,13 @@ export const MESSAGES = Object.freeze({
     hintFailClosedAudit: "请确保审计日志目录可写且磁盘空间充足",
     hintLockedAskUnattended: "请切换到交互式会话或请求人工显式确认",
     hintClassifierTimeout: "请检查外部 LLM 服务连通性或调整分类器超时容错策略",
+    hintClassifierSlaFallback: "请检查外部 LLM 分类器负载或调高 classifierSlaMs 阈值",
+    hintMalformedClassifierResponse: "请检查模型 JSON 输出格式或验证返回模式兼容性",
+    hintPayloadTooLarge: "减小输入参数大小或分批传输数据",
+    hintReviewerInjectionAttempt: "从输入中移除对抗性指令覆盖指令",
+    hintContractViolation: "将操作限制在允许的任务工具和项目范围内",
+    hintUnisolatedTempPath: "使用工作区隔离的临时目录 (<workspace>/.dsh/tmp)",
+    hintOverengineeringLimit: "复用现有文件，避免创建多余的抽象或样板代码",
   },
 });
 
@@ -230,6 +264,12 @@ const RULE_KEYS = Object.freeze({
   "classifier-timeout-strict": "ruleClassifierTimeoutStrict",
   "classifier-timeout-fallback-strict": "ruleClassifierTimeoutStrict",
   "classifier-timeout-fallback-permissive": "ruleClassifierTimeoutPermissive",
+  "classifier-sla-fallback": "askClassifierSlaFallback",
+  "malformed-classifier-response": "askMalformedClassifierResponse",
+  "reviewer-injection-attempt": "ruleReviewerInjectionAttempt",
+  "contract-violation": "ruleContractViolation",
+  "unisolated-temp-path": "ruleUnisolatedTempPath",
+  "overengineering-file-limit": "ruleOverengineeringLimit",
 });
 
 const HINT_KEYS = Object.freeze({
@@ -250,6 +290,13 @@ const HINT_KEYS = Object.freeze({
   "locked-ask-unattended-denied": "hintLockedAskUnattended",
   "classifier-timeout-strict": "hintClassifierTimeout",
   "classifier-timeout-fallback-strict": "hintClassifierTimeout",
+  "classifier-sla-fallback": "hintClassifierSlaFallback",
+  "malformed-classifier-response": "hintMalformedClassifierResponse",
+  "payload-too-large": "hintPayloadTooLarge",
+  "reviewer-injection-attempt": "hintReviewerInjectionAttempt",
+  "contract-violation": "hintContractViolation",
+  "unisolated-temp-path": "hintUnisolatedTempPath",
+  "overengineering-file-limit": "hintOverengineeringLimit",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -268,6 +315,12 @@ const ASK_KEYS = Object.freeze({
   "classifier-timeout-strict": "askClassifierTimeout",
   "classifier-timeout-fallback-strict": "askClassifierTimeout",
   "classifier-error": "askClassifierError",
+  "classifier-sla-fallback": "askClassifierSlaFallback",
+  "malformed-classifier-response": "askMalformedClassifierResponse",
+  "payload-too-large": "askPayloadTooLarge",
+  "contract-violation": "askContractViolation",
+  "unisolated-temp-path": "askUnisolatedTempPath",
+  "overengineering-file-limit": "askOverengineeringLimit",
 });
 
 const DETAIL_KEYS = Object.freeze({

package/lib/overengineering.js

@@ -0,0 +1,97 @@
+// lib/overengineering.js
+// Overengineering guard limiting excessive file creation per session (#89).
+
+export const DEFAULT_MAX_FILES_PER_SESSION = 10;
+
+/**
+ * Tracks and limits file creation within agent sessions to prevent codebase bloat and overengineering (#89).
+ */
+export class OverengineeringGuard {
+  /**
+   * @param {{ maxFilesPerSession?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxFilesPerSession =
+      typeof options.maxFilesPerSession === "number" && options.maxFilesPerSession > 0
+        ? options.maxFilesPerSession
+        : (typeof options.maxCreatedFilesPerSession === "number" && options.maxCreatedFilesPerSession > 0
+            ? options.maxCreatedFilesPerSession
+            : DEFAULT_MAX_FILES_PER_SESSION);
+    this.maxCreatedFilesPerSession = this.maxFilesPerSession;
+    this._sessionFiles = new Map();
+  }
+
+  /**
+   * Gets or initializes the Set of files created in this session.
+   * @private
+   */
+  _getSessionSet(sessionId) {
+    const key = sessionId || "default";
+    if (!this._sessionFiles.has(key)) {
+      this._sessionFiles.set(key, new Set());
+    }
+    return this._sessionFiles.get(key);
+  }
+
+  /**
+   * Checks file creation against threshold and records new files.
+   *
+   * @param {string} sessionId
+   * @param {string} filePath
+   * @returns {{ allowed: boolean, reason?: string, count: number, limit: number, detail?: string }}
+   */
+  checkAndRecord(sessionId, filePath) {
+    if (!filePath || typeof filePath !== "string") {
+      return { allowed: true, count: this.getCount(sessionId), limit: this.maxFilesPerSession };
+    }
+
+    const cleanPath = filePath.trim().replace(/\\/g, "/");
+    const set = this._getSessionSet(sessionId);
+
+    // If file was already created/tracked in this session, modifying it is permitted
+    if (set.has(cleanPath)) {
+      return { allowed: true, count: set.size, limit: this.maxFilesPerSession };
+    }
+
+    // Check if adding this file exceeds limit
+    if (set.size >= this.maxCreatedFilesPerSession) {
+      return {
+        allowed: false,
+        reason: "overengineering-file-limit",
+        count: set.size + 1,
+        limit: this.maxCreatedFilesPerSession,
+        detail: `Created ${set.size + 1} files in session, exceeding limit of ${this.maxCreatedFilesPerSession} files (#89)`,
+      };
+    }
+
+    set.add(cleanPath);
+    return { allowed: true, count: set.size, limit: this.maxFilesPerSession };
+  }
+
+  /**
+   * Returns current count of created files in session.
+   * @param {string} sessionId
+   * @returns {number}
+   */
+  getCount(sessionId) {
+    const key = sessionId || "default";
+    const set = this._sessionFiles.get(key);
+    return set ? set.size : 0;
+  }
+
+  /**
+   * Clears session tracked files.
+   * @param {string} sessionId
+   */
+  reset(sessionId) {
+    const key = sessionId || "default";
+    this._sessionFiles.delete(key);
+  }
+
+  /**
+   * Clears all session tracking.
+   */
+  clear() {
+    this._sessionFiles.clear();
+  }
+}