skyloom 1.5.3 → 1.7.0

package/src/core/filter.ts

@@ -0,0 +1,103 @@
+/**
+ * 输出过滤模块 — sensitive information sanitization.
+ *
+ * Before agent responses reach the user (or are persisted),
+ * scan for and redact sensitive patterns like API keys,
+ * tokens, passwords, PII, and internal paths.
+ */
+
+/* ═══════════════════════════════════════
+   Detection patterns — compiled once at module load
+   ═══════════════════════════════════════ */
+const SENSITIVE_PATTERNS: Array<[RegExp, string]> = [
+  // API keys & tokens
+  [/sk-[a-zA-Z0-9]{32,}/g, "[REDACTED:API_KEY]"],
+  [/(?:api_key|apikey|secret_key|access_token|auth_token)\s*[:=]\s*["']?[^\s"']{8,}["']?/gi, "$1: [REDACTED]"],
+  [/ghp_[a-zA-Z0-9]{36}/g, "[REDACTED:GITHUB_TOKEN]"],
+  [/gho_[a-zA-Z0-9]{36}/g, "[REDACTED:GITHUB_TOKEN]"],
+
+  // AWS credentials
+  [/AKIA[0-9A-Z]{16}/g, "[REDACTED:AWS_KEY]"],
+  [/(?:aws_access_key_id|aws_secret_access_key)\s*[:=]\s*["']?[^\s"']+/gi, "$1: [REDACTED]"],
+
+  // Passwords
+  [/(?:password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, "$1: [REDACTED]"],
+  [/(?:密码|口令)\s*[:=]\s*["']?[^\s"']{2,}["']?/g, "$1: [已脱敏]"],
+
+  // Connection strings
+  [/(?:mongodb|postgres|mysql|redis):\/\/[^\s]+/g, "[REDACTED:DB_URI]"],
+  [/(?:jdbc|odbc):[^\s]+/g, "[REDACTED:DB_URI]"],
+
+  // Private keys
+  [/-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END .*?PRIVATE KEY-----/g, "[REDACTED:PRIVATE_KEY]"],
+
+  // IP addresses (local only)
+  [/192\.168\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
+  [/10\.\d{1,3}\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
+  [/172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
+
+  // File paths
+  [/(?:\/etc\/(?:passwd|shadow|hosts|sudoers))/g, "[REDACTED:SYSTEM_PATH]"],
+];
+
+/* Email masking (function-based, handled separately) */
+const EMAIL_RE = /([a-zA-Z0-9._%+-]{3,})@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/g;
+
+
+/* ═══════════════════════════════════════
+   Filter function
+   ═══════════════════════════════════════ */
+export interface FilterResult {
+  clean: string;
+  redacted: boolean;
+  count: number;
+  details: string[];
+}
+
+export function filterOutput(text: string): FilterResult {
+  if (!text) return { clean: "", redacted: false, count: 0, details: [] };
+
+  let clean = text;
+  let count = 0;
+  const details: string[] = [];
+
+  // Email masking (function-based replacement)
+  let emailCount = 0;
+  clean = clean.replace(EMAIL_RE, (full, user, domain) => {
+    emailCount++;
+    return (user as string).slice(0, 2) + "***@" + (domain as string);
+  });
+  if (emailCount > 0) {
+    count += emailCount;
+    details.push(`Masked ${emailCount}x email addresses`);
+  }
+
+  for (const [pattern, replacement] of SENSITIVE_PATTERNS) {
+    const matches = clean.match(pattern);
+    if (matches) {
+      count += matches.length;
+      if (typeof replacement === "string") {
+        details.push(`Redacted ${matches.length}x ${pattern.source.slice(0, 30)}`);
+      } else {
+        details.push(`Masked ${matches.length}x email addresses`);
+      }
+      clean = clean.replace(pattern, replacement as string);
+    }
+  }
+
+  return { clean, redacted: count > 0, count, details };
+}
+
+/* ═══════════════════════════════════════
+   Quick check — is filtering needed?
+   ═══════════════════════════════════════ */
+export function needsFiltering(text: string): boolean {
+  if (!text) return false;
+  // Quick scan with the most common patterns
+  if (/sk-[a-zA-Z0-9]{32,}/.test(text)) return true;
+  if (/api_key.*[:=]/.test(text)) return true;
+  if (/password.*[:=]/.test(text)) return true;
+  if (/-----BEGIN.*PRIVATE KEY-----/.test(text)) return true;
+  if (EMAIL_RE.test(text)) return true;
+  return false;
+}

package/src/core/index.ts

@@ -26,6 +26,12 @@ export * from './skill';
 export * from './router';
 export * from './agent';
 export * from './factory';
+export * from './security';
+export * from './learn';
+export * from './longdoc';
+export * from './filter';
+export * from './estimate';
+export * from './arbitrate';
 
-// Version
-export const VERSION = '1.4.0';
+// Version — read from package.json
+export const VERSION = (() => { try { return require('../../package.json').version; } catch { return '1.6.0'; } })();

package/src/core/learn.ts

@@ -0,0 +1,146 @@
+/**
+ * 持续学习模块 — post-task review + experience recording.
+ *
+ * After each task, the agent writes a structured review.
+ * Failed attempts are indexed for similarity search to avoid repetition.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { USER_CONFIG_DIR } from "./config";
+import { getLogger } from "./logger";
+
+const log = getLogger("learn");
+
+/* ── Data types ── */
+export interface TaskReview {
+  ts: string;
+  agent: string;
+  goal: string;
+  success: boolean;
+  durationMs: number;
+  toolCalls: string[];
+  errorMsg?: string;
+  rootCause?: string;
+  improvement?: string;
+}
+
+export interface ExperienceEntry {
+  id: string;
+  pattern: string;       // What went wrong (key for similarity search)
+  solution: string;      // What fixed it
+  frequency: number;     // How often this pattern repeats
+  lastSeen: string;
+}
+
+/* ── Persistence ── */
+const reviewDir = path.join(USER_CONFIG_DIR, "reviews");
+const expFile = path.join(USER_CONFIG_DIR, "experiences.json");
+const reviewDir_ = reviewDir; // for closure
+
+function ensureDir() { if (!fs.existsSync(reviewDir_)) fs.mkdirSync(reviewDir_, { recursive: true }); }
+
+/* ═══════════════════════════════════════
+   Task Review Recording
+   ═══════════════════════════════════════ */
+export function recordReview(review: TaskReview): void {
+  ensureDir();
+  const file = path.join(reviewDir_, `${review.ts.slice(0, 10)}_${review.agent}.jsonl`);
+  const line = JSON.stringify(review);
+  fs.appendFileSync(file, line + "\n");
+  log.debug("review_recorded", { agent: review.agent, success: review.success });
+
+  // If failed, also record as experience
+  if (!review.success && review.errorMsg) {
+    recordExperience(review.errorMsg, review.rootCause || "unknown", review.improvement || "no improvement noted");
+  }
+}
+
+/* ═══════════════════════════════════════
+   Experience Recording (for failure patterns)
+   ═══════════════════════════════════════ */
+function loadExperiences(): ExperienceEntry[] {
+  try {
+    if (fs.existsSync(expFile)) return JSON.parse(fs.readFileSync(expFile, "utf-8"));
+  } catch { /* ignore */ }
+  return [];
+}
+
+function saveExperiences(entries: ExperienceEntry[]): void {
+  ensureDir();
+  fs.writeFileSync(expFile, JSON.stringify(entries, null, 2), "utf-8");
+}
+
+export function recordExperience(errorPattern: string, rootCause: string, solution: string): void {
+  const entries = loadExperiences();
+  const normalized = errorPattern.toLowerCase().slice(0, 200);
+
+  // Check for existing similar pattern (simple substring match)
+  const existing = entries.find(e => e.pattern.toLowerCase().includes(normalized.slice(0, 50)) || normalized.includes(e.pattern.toLowerCase().slice(0, 50)));
+  if (existing) {
+    existing.frequency++;
+    existing.lastSeen = new Date().toISOString();
+    if (solution && solution !== "no improvement noted") existing.solution = solution;
+  } else {
+    entries.push({
+      id: Math.random().toString(36).slice(2, 10),
+      pattern: errorPattern.slice(0, 200),
+      solution,
+      frequency: 1,
+      lastSeen: new Date().toISOString(),
+    });
+  }
+
+  // Keep top 100 experiences, sorted by frequency
+  entries.sort((a, b) => b.frequency - a.frequency);
+  if (entries.length > 100) entries.splice(100);
+  saveExperiences(entries);
+}
+
+/* ═══════════════════════════════════════
+   Query experiences
+   ═══════════════════════════════════════ */
+export function queryExperiences(problem: string, limit: number = 3): ExperienceEntry[] {
+  const entries = loadExperiences();
+  const lower = problem.toLowerCase();
+  return entries
+    .filter(e => {
+      const plow = e.pattern.toLowerCase();
+      // Simple token overlap scoring
+      const tokens = lower.split(/\s+/).filter(t => t.length > 2);
+      const matches = tokens.filter(t => plow.includes(t));
+      return matches.length >= 2;
+    })
+    .sort((a, b) => b.frequency - a.frequency)
+    .slice(0, limit);
+}
+
+/* ═══════════════════════════════════════
+   Format experiences for system prompt injection
+   ═══════════════════════════════════════ */
+export function formatExperiencesForPrompt(problem: string): string {
+  const exps = queryExperiences(problem);
+  if (!exps.length) return "";
+  const lines = ["## 历史教训（从经验库检索）", "以下是与当前任务相关的过往失败案例，请避免重复："];
+  for (const e of exps) {
+    lines.push(`- **模式**: ${e.pattern.slice(0, 120)}`);
+    lines.push(`  **解决**: ${e.solution.slice(0, 200)} (出现 ${e.frequency} 次)`);
+  }
+  return lines.join("\n");
+}
+
+/* ═══════════════════════════════════════
+   Generate a structured review after task completion
+   ═══════════════════════════════════════ */
+export function generateReview(
+  agent: string, goal: string, success: boolean, durationMs: number,
+  toolCalls: string[], errorMsg?: string
+): TaskReview {
+  return {
+    ts: new Date().toISOString(),
+    agent, goal, success, durationMs, toolCalls,
+    errorMsg,
+    rootCause: errorMsg ? "auto-detected failure" : undefined,
+    improvement: errorMsg ? "review error and adjust approach" : undefined,
+  };
+}

package/src/core/longdoc.ts

@@ -0,0 +1,155 @@
+/**
+ * 长文档处理策略 — sliding window + summary chain.
+ *
+ * When an input exceeds the agent's effective context window,
+ * split into overlapping chunks, summarize each, then chain
+ * summaries into a final digest.
+ *
+ * Architecture:
+ *   Input → Chunk(sliding window) → Per-chunk Summary → Chain → Final Digest
+ *
+ * All summaries are generated by the calling agent's LLM, so quality
+ * depends on the model in use. The chunker is pure text processing
+ * and works without any LLM call.
+ */
+
+import type { BaseAgent } from "./agent";
+
+/* ═══════════════════════════════════════
+   Chunker — split text into overlapping windows
+   ═══════════════════════════════════════ */
+export interface ChunkOptions {
+  /** Target chunk size in characters (default 6000) */
+  chunkSize?: number;
+  /** Overlap between consecutive chunks in characters (default 800) */
+  overlap?: number;
+  /** Minimum chunk size before we stop splitting (default 500) */
+  minChunk?: number;
+}
+
+export function chunkText(text: string, opts?: ChunkOptions): string[] {
+  const cs = opts?.chunkSize ?? 6000;
+  const ol = opts?.overlap ?? 800;
+  const min = opts?.minChunk ?? 500;
+  const chunks: string[] = [];
+
+  if (text.length <= cs + min) { chunks.push(text); return chunks; }
+
+  let start = 0;
+  while (start < text.length) {
+    let end = start + cs;
+    if (end >= text.length) { end = text.length; }
+    else {
+      // Try to break at paragraph boundary
+      const searchEnd = Math.min(end + 400, text.length);
+      const paraBreak = text.lastIndexOf("\n\n", searchEnd);
+      if (paraBreak > start + min) end = paraBreak;
+      else {
+        const lineBreak = text.lastIndexOf("\n", searchEnd);
+        if (lineBreak > start + min) end = lineBreak;
+        else {
+          const space = text.lastIndexOf(" ", searchEnd);
+          if (space > start + min) end = space;
+        }
+      }
+    }
+
+    chunks.push(text.slice(start, end).trim());
+    if (end >= text.length) break;
+    start = end - ol;
+    if (start < 0) start = 0;
+  }
+
+  return chunks;
+}
+
+/* ═══════════════════════════════════════
+   Summary chain — ask agent to summarize chunks then chain
+   ═══════════════════════════════════════ */
+export interface SummaryOptions {
+  /** Max total chars for the final digest (default 3000) */
+  maxDigestChars?: number;
+  /** Custom summarization prompt for each chunk */
+  chunkPrompt?: string;
+  /** Custom chain prompt for combining summaries */
+  chainPrompt?: string;
+}
+
+const DEFAULT_CHUNK_PROMPT = `Summarize the following text concisely. Keep all key facts, names, numbers, and code snippets. Output the summary directly without preamble. Limit to 300 words.
+
+Text:
+{text}`;
+
+const DEFAULT_CHAIN_PROMPT = `Combine the following section summaries into a single coherent digest. Preserve all key facts, remove redundancy. Output directly without preamble.
+
+{summaries}`;
+
+export async function summarizeLongDoc(
+  agent: BaseAgent,
+  text: string,
+  opts?: SummaryOptions
+): Promise<string> {
+  const maxDigest = opts?.maxDigestChars ?? 3000;
+  const chunks = chunkText(text);
+
+  // Single chunk — no summarization needed
+  if (chunks.length <= 1) {
+    if (text.length <= maxDigest) return text;
+    const prompt = (opts?.chunkPrompt || DEFAULT_CHUNK_PROMPT).replace("{text}", text);
+    return agent.chatOneshot(prompt, { maxTokens: maxDigest });
+  }
+
+  // Multi-chunk: summarize each, then chain
+  const summaries: string[] = [];
+  for (let i = 0; i < chunks.length; i++) {
+    const prompt = (opts?.chunkPrompt || DEFAULT_CHUNK_PROMPT).replace("{text}", chunks[i]);
+    try {
+      const s = await agent.chatOneshot(prompt, { maxTokens: 600 });
+      summaries.push(s);
+    } catch {
+      summaries.push(chunks[i].slice(0, 400) + "...");
+    }
+  }
+
+  // Chain summaries
+  if (summaries.length === 1) return summaries[0].slice(0, maxDigest);
+
+  const joined = summaries.map((s, i) => `## Section ${i + 1}\n${s}`).join("\n\n");
+  if (joined.length <= maxDigest) return joined;
+
+  const chainPrompt = (opts?.chainPrompt || DEFAULT_CHAIN_PROMPT).replace("{summaries}", joined);
+  const final = await agent.chatOneshot(chainPrompt, { maxTokens: maxDigest });
+  return final.slice(0, maxDigest);
+}
+
+/* ═══════════════════════════════════════
+   Structured data parsing helpers
+   ═══════════════════════════════════════ */
+export function parseStructuredInput(input: string): {
+  hasTable: boolean; hasJSON: boolean; hasCSV: boolean;
+  extractedJSON: string | null; extractedTable: string[][] | null;
+} {
+  const result = { hasTable: false, hasJSON: false, hasCSV: false, extractedJSON: null as string | null, extractedTable: null as string[][] | null };
+
+  // Detect JSON
+  const jsonMatch = input.match(/\{[\s\S]*\}|\[[\s\S]*\]/);
+  if (jsonMatch) {
+    try { JSON.parse(jsonMatch[0]); result.hasJSON = true; result.extractedJSON = jsonMatch[0]; }
+    catch { /* not valid JSON */ }
+  }
+
+  // Detect markdown table
+  const tableMatch = input.match(/\|[\s\S]*?\|/);
+  if (tableMatch) {
+    result.hasTable = true;
+    const lines = input.split("\n").filter(l => l.includes("|") && !l.startsWith("|---") && !l.startsWith("| --"));
+    result.extractedTable = lines.map(l => l.split("|").filter(c => c.trim()).map(c => c.trim()));
+  }
+
+  // Detect CSV
+  if (input.includes(",") && input.split("\n").filter(l => l.includes(",")).length >= 2) {
+    result.hasCSV = true;
+  }
+
+  return result;
+}

package/src/core/security.ts

@@ -0,0 +1,243 @@
+/**
+ * 安全与对齐模块 — Security & Alignment
+ *
+ * Danger level grading, red-line enforcement, audit trail, human-in-the-loop.
+ * All security decisions flow through this module before tool execution.
+ */
+
+import { getLogger } from "./logger";
+
+const log = getLogger("security");
+
+/* ── Danger levels ── */
+export enum DangerLevel {
+  /** Read-only, no side effects — auto-approved */
+  SAFE = 0,
+  /** Minor side effects (write single file, git status) — logged */
+  LOW = 1,
+  /** Significant side effects (overwrite, delete, git push) — notify */
+  MEDIUM = 2,
+  /** Dangerous (sudo, remote deploy, mass delete) — confirm */
+  HIGH = 3,
+  /** Red-line — NEVER execute without human-in-the-loop */
+  CRITICAL = 4,
+}
+
+/* ═══════════════════════════════════════
+   Red-line list: operations that are NEVER auto-approved
+   ═══════════════════════════════════════ */
+const REDLINE_PATTERNS = [
+  /rm\s+-rf/,           /format\s+\w:/,         /dd\s+if=/,
+  />\s*\/dev\/sd/,      /mkfs\./,               /:(){ :\|:& };:/,
+  /sudo\s+rm/,          /chmod\s+777\s+\//,     /wget.*\|.*sh/,
+  /curl.*\|.*bash/,     /eval\s+\$/,            /exec\s+\$/,
+  /subprocess\.call.*rm/, /os\.system.*rm/,
+];
+
+const REDLINE_COMMANDS = [
+  "shutdown", "reboot", "init 0", "init 6",
+  "del /f /s /q C:\\*", "rd /s /q C:\\",
+];
+
+/* ═══════════════════════════════════════
+   Per-tool danger level mapping
+   ═══════════════════════════════════════ */
+const TOOL_DANGER_MAP: Record<string, DangerLevel> = {
+  read_file: DangerLevel.SAFE,
+  list_directory: DangerLevel.SAFE,
+  tree: DangerLevel.SAFE,
+  file_search: DangerLevel.SAFE,
+  code_search: DangerLevel.SAFE,
+  grep: DangerLevel.SAFE,
+  git_status: DangerLevel.SAFE,
+  git_diff: DangerLevel.SAFE,
+  git_log: DangerLevel.SAFE,
+  system_info: DangerLevel.SAFE,
+  system_diagnose: DangerLevel.SAFE,
+  list_processes: DangerLevel.SAFE,
+  list_installed_apps: DangerLevel.SAFE,
+  list_skills: DangerLevel.SAFE,
+  recall_facts: DangerLevel.SAFE,
+  mcp_list_servers: DangerLevel.SAFE,
+
+  write_file: DangerLevel.LOW,
+  edit_file: DangerLevel.LOW,
+  copy_file: DangerLevel.LOW,
+  move_file: DangerLevel.LOW,
+  http_get: DangerLevel.LOW,
+  fetch_page: DangerLevel.LOW,
+  web_search: DangerLevel.LOW,
+  remember_fact: DangerLevel.LOW,
+  use_skill: DangerLevel.LOW,
+  task_done: DangerLevel.LOW,
+
+  delete_file: DangerLevel.MEDIUM,
+  git_add: DangerLevel.MEDIUM,
+  git_commit: DangerLevel.MEDIUM,
+  git_checkout: DangerLevel.MEDIUM,
+  http_post: DangerLevel.MEDIUM,
+  mcp_add_server: DangerLevel.MEDIUM,
+  mcp_remove_server: DangerLevel.MEDIUM,
+  launch_app: DangerLevel.MEDIUM,
+  open_path: DangerLevel.MEDIUM,
+  browser_open: DangerLevel.MEDIUM,
+
+  run_bash: DangerLevel.HIGH,
+  shell_exec: DangerLevel.HIGH,
+  kill_process: DangerLevel.HIGH,
+  package_manager: DangerLevel.HIGH,
+  service_control: DangerLevel.HIGH,
+  delegate_to: DangerLevel.HIGH,
+  mcp_scaffold_server: DangerLevel.HIGH,
+};
+
+/* ═══════════════════════════════════════
+   Audit trail entry
+   ═══════════════════════════════════════ */
+export interface AuditEntry {
+  ts: string;
+  agent: string;
+  tool: string;
+  args: Record<string, any>;
+  dangerLevel: DangerLevel;
+  approved: boolean;
+  result: string;
+  durationMs: number;
+  traceId: string;
+}
+
+/* ═══════════════════════════════════════
+   Security context — per-session security state
+   ═══════════════════════════════════════ */
+export class SecurityContext {
+  public auditLog: AuditEntry[] = [];
+  public deniedCount = 0;
+  public autoApprovedCount = 0;
+  public manualApprovedCount = 0;
+  public approvalMode: "auto" | "interactive" | "strict" = "auto";
+
+  private approvalCallback: ((tool: string, args: Record<string, any>, level: DangerLevel) => Promise<boolean>) | null = null;
+
+  constructor(opts?: { mode?: "auto" | "interactive" | "strict"; onApprove?: (tool: string, args: Record<string, any>, level: DangerLevel) => Promise<boolean> }) {
+    if (opts?.mode) this.approvalMode = opts.mode;
+    if (opts?.onApprove) this.approvalCallback = opts.onApprove;
+  }
+
+  /** Get the danger level for a tool. Defaults to SAFE for unknown tools. */
+  getDangerLevel(toolName: string): DangerLevel {
+    return TOOL_DANGER_MAP[toolName] ?? DangerLevel.SAFE;
+  }
+
+  /** Check if arguments contain red-line patterns (critical danger). */
+  checkRedline(toolName: string, args: Record<string, any>): string | null {
+    if (toolName !== "run_bash" && toolName !== "shell_exec") return null;
+    const cmd = String(args.command || args.cmd || "").toLowerCase();
+    for (const pattern of REDLINE_PATTERNS) {
+      if (pattern.test(cmd)) return `Red-line pattern detected: ${pattern.source.slice(0, 40)}`;
+    }
+    for (const forbidden of REDLINE_COMMANDS) {
+      if (cmd.includes(forbidden)) return `Red-line command: ${forbidden}`;
+    }
+    return null;
+  }
+
+  /** Determine whether a tool call is permitted. Returns [approved, reason]. */
+  async checkApproval(toolName: string, args: Record<string, any>, agentName: string): Promise<[boolean, string]> {
+    const level = this.getDangerLevel(toolName);
+
+    // Red-line check
+    const redline = this.checkRedline(toolName, args);
+    if (redline) {
+      log.warn("redline_blocked", { agent: agentName, tool: toolName, reason: redline });
+      return [false, redline];
+    }
+
+    // Safe — always allow
+    if (level === DangerLevel.SAFE) return [true, "safe"];
+
+    // Strict mode — deny all non-safe
+    if (this.approvalMode === "strict") {
+      return [false, `Strict mode: tool '${toolName}' (level ${level}) requires manual approval`];
+    }
+
+    // Auto mode — allow LOW, prompt for MEDIUM+, deny CRITICAL
+    if (this.approvalMode === "auto") {
+      if (level <= DangerLevel.LOW) return [true, "auto-low"];
+      if (level === DangerLevel.CRITICAL) return [false, `CRITICAL tool '${toolName}' requires explicit human approval`];
+      // MEDIUM/HIGH with auto mode => need callback
+      if (this.approvalCallback) {
+        const approved = await this.approvalCallback(toolName, args, level);
+        return [approved, approved ? "user-approved" : "user-denied"];
+      }
+      return [true, "auto-med"]; // no callback → auto-allow but log
+    }
+
+    // Interactive mode — prompt for LOW+
+    if (this.approvalCallback) {
+      const approved = await this.approvalCallback(toolName, args, level);
+      return [approved, approved ? "user-approved" : "user-denied"];
+    }
+    return [true, "no-callback"];
+  }
+
+  /** Record an audit entry. */
+  recordAudit(tool: string, agent: string, args: Record<string, any>, dangerLevel: DangerLevel, approved: boolean, resultPreview: string, durationMs: number, traceId: string): void {
+    const entry: AuditEntry = {
+      ts: new Date().toISOString(),
+      agent, tool, args, dangerLevel, approved,
+      result: resultPreview.slice(0, 500),
+      durationMs, traceId,
+    };
+    this.auditLog.push(entry);
+    if (this.auditLog.length > 5000) this.auditLog.shift();
+
+    if (approved) {
+      if (dangerLevel >= DangerLevel.HIGH) this.manualApprovedCount++;
+      else this.autoApprovedCount++;
+    } else {
+      this.deniedCount++;
+    }
+
+    log.info(dangerLevel >= DangerLevel.HIGH ? "dangerous_tool_executed" : "tool_executed", {
+      tool, agent, level: dangerLevel, approved,
+    });
+  }
+
+  /** Get summary statistics. */
+  getStats() {
+    return {
+      total: this.auditLog.length,
+      denied: this.deniedCount,
+      autoApproved: this.autoApprovedCount,
+      manualApproved: this.manualApprovedCount,
+      byLevel: {
+        safe: this.auditLog.filter(e => e.dangerLevel === DangerLevel.SAFE).length,
+        low: this.auditLog.filter(e => e.dangerLevel === DangerLevel.LOW).length,
+        medium: this.auditLog.filter(e => e.dangerLevel === DangerLevel.MEDIUM).length,
+        high: this.auditLog.filter(e => e.dangerLevel === DangerLevel.HIGH).length,
+        critical: this.auditLog.filter(e => e.dangerLevel === DangerLevel.CRITICAL).length,
+      },
+      lastDenied: this.auditLog.filter(e => !e.approved).slice(-5).map(e => `${e.tool}: ${e.result}`),
+    };
+  }
+
+  /** Install approval callback for interactive mode. */
+  setApprovalCallback(fn: (tool: string, args: Record<string, any>, level: DangerLevel) => Promise<boolean>) {
+    this.approvalCallback = fn;
+  }
+}
+
+/* ── Global security context ── */
+let globalSecurity: SecurityContext | null = null;
+
+export function getSecurity(): SecurityContext {
+  if (!globalSecurity) globalSecurity = new SecurityContext();
+  return globalSecurity;
+}
+
+export function resetSecurity(): void {
+  globalSecurity = null;
+}
+
+/** Red-line patterns for reference (used by tools to self-check). */
+export { REDLINE_PATTERNS, REDLINE_COMMANDS };