skyloom 1.12.0 → 1.13.0

package/src/core/filter.ts

@@ -1,103 +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;
-}
+/**
+ * 输出过滤模块 — 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/graph.ts

@@ -1,156 +1,156 @@
-/**
- * 简易知识图谱 — entity-relation storage in SQLite.
- *
- * Lightweight triple store: (subject, predicate, object) with metadata.
- * Used for: project info, tool preferences, dependency relationships.
- *
- * Schema:
- *   CREATE TABLE triples (subj, pred, obj, agent, ts, meta)
- *
- * Queries:
- *   - Find all relations for an entity
- *   - Find all entities matching a predicate
- *   - Transitive closure (2-hop max for performance)
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import { USER_CONFIG_DIR } from "./config";
-import { getLogger } from "./logger";
-
-const log = getLogger("graph");
-
-/* ═══════════════════════════════════════
-   Triple store — in-memory + optional persistence
-   ═══════════════════════════════════════ */
-interface Triple {
-  subj: string;
-  pred: string;
-  obj: string;
-  agent: string;
-  ts: string;
-  meta?: Record<string, string>;
-}
-
-export class KnowledgeGraph {
-  private triples: Triple[] = [];
-  private indexPath: string;
-
-  constructor(name: string = "default") {
-    this.indexPath = path.join(USER_CONFIG_DIR, `kg_${name}.json`);
-    this.load();
-  }
-
-  /** Add a fact: (subject, predicate, object). */
-  add(subj: string, pred: string, obj: string, agent: string = "system", meta?: Record<string, string>): void {
-    // Deduplicate
-    const exists = this.triples.find(t => t.subj === subj && t.pred === pred && t.obj === obj);
-    if (exists) { exists.ts = new Date().toISOString(); if (meta) exists.meta = { ...exists.meta, ...meta }; return; }
-
-    this.triples.push({ subj, pred, obj, agent, ts: new Date().toISOString(), meta });
-    if (this.triples.length > 5000) this.triples.splice(0, this.triples.length - 5000);
-    this.save();
-  }
-
-  /** Find all facts about an entity. */
-  about(entity: string, limit: number = 20): Triple[] {
-    return this.triples.filter(t => t.subj === entity || t.obj === entity).slice(-limit);
-  }
-
-  /** Find all subjects matching a predicate. */
-  byPredicate(pred: string): Triple[] {
-    return this.triples.filter(t => t.pred === pred);
-  }
-
-  /** Find all objects for a subject-predicate pair. */
-  find(subj: string, pred: string): Triple[] {
-    return this.triples.filter(t => t.subj === subj && t.pred === pred);
-  }
-
-  /** Transitive expansion: 2-hop from a starting entity. */
-  expand(entity: string, maxDepth: number = 2): Triple[] {
-    const seen = new Set<Triple>();
-    const queue = [entity];
-    for (let depth = 0; depth < maxDepth && queue.length > 0; depth++) {
-      const current = queue.shift()!;
-      const facts = this.about(current, 10);
-      for (const f of facts) {
-        if (seen.has(f)) continue;
-        seen.add(f);
-        if (f.subj === current && !queue.includes(f.obj)) queue.push(f.obj);
-        if (f.obj === current && !queue.includes(f.subj)) queue.push(f.subj);
-      }
-    }
-    return Array.from(seen);
-  }
-
-  /** Remove a fact. */
-  remove(subj: string, pred: string, obj: string): void {
-    this.triples = this.triples.filter(t => !(t.subj === subj && t.pred === pred && t.obj === obj));
-    this.save();
-  }
-
-  /** Search for entities or predicates containing a keyword. */
-  search(keyword: string, limit: number = 15): Triple[] {
-    const k = keyword.toLowerCase();
-    return this.triples.filter(t => t.subj.toLowerCase().includes(k) || t.pred.toLowerCase().includes(k) || t.obj.toLowerCase().includes(k)).slice(-limit);
-  }
-
-  /** Format facts as readable text. */
-  format(entity?: string): string {
-    const facts = entity ? this.about(entity) : this.triples.slice(-30);
-    if (facts.length === 0) return "(no facts)";
-    const bySubj = new Map<string, string[]>();
-    for (const f of facts) {
-      if (!bySubj.has(f.subj)) bySubj.set(f.subj, []);
-      bySubj.get(f.subj)!.push(`${f.pred} → ${f.obj}`);
-    }
-    const lines: string[] = [];
-    for (const [subj, preds] of bySubj) {
-      lines.push(`**${subj}**: ${preds.join(", ")}`);
-    }
-    return lines.join("\n");
-  }
-
-  get size(): number { return this.triples.length; }
-
-  private save(): void {
-    try {
-      const dir = path.dirname(this.indexPath);
-      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(this.indexPath, JSON.stringify(this.triples.slice(-2000)), "utf-8");
-    } catch (e) { log.warn("kg_save_failed", { error: String(e) }); }
-  }
-
-  private load(): void {
-    try {
-      if (fs.existsSync(this.indexPath)) {
-        this.triples = JSON.parse(fs.readFileSync(this.indexPath, "utf-8"));
-      }
-    } catch { this.triples = []; }
-  }
-}
-
-/* ── Auto-extract facts from conversation ── */
-const RELATION_PATTERNS: Array<[RegExp, string]> = [
-  [/(\w+) (?:是|为|属于|使用|用|用到了|采用) (.+?)(?:[。，,.\n]|$)/g, "is"],
-  [/(\w+) (?:版本|version|v) (?:是|为)? ?(\d[\d.]*)/gi, "version"],
-  [/(\w+) (?:depends|依赖|需要|requires) (\w+)/gi, "depends_on"],
-  [/(\w+) (?:config|配置) (?:为|是)? (.+?)(?:[。，,.\n]|$)/gi, "config"],
-  [/(\w+) (?:file|path|文件|路径) (?:在|为|at) (.+?)(?:[。，,.\n]|$)/gi, "located_at"],
-];
-
-export function extractFacts(text: string, agent: string): Array<[string, string, string]> {
-  const facts: Array<[string, string, string]> = [];
-  for (const [pattern, pred] of RELATION_PATTERNS) {
-    let match;
-    while ((match = pattern.exec(text)) !== null) {
-      const subj = match[1].trim().toLowerCase();
-      const obj = match[2].trim();
-      if (subj.length >= 2 && obj.length >= 2 && subj !== obj) {
-        facts.push([subj, pred, obj]);
-      }
-    }
-  }
-  return facts;
-}
+/**
+ * 简易知识图谱 — entity-relation storage in SQLite.
+ *
+ * Lightweight triple store: (subject, predicate, object) with metadata.
+ * Used for: project info, tool preferences, dependency relationships.
+ *
+ * Schema:
+ *   CREATE TABLE triples (subj, pred, obj, agent, ts, meta)
+ *
+ * Queries:
+ *   - Find all relations for an entity
+ *   - Find all entities matching a predicate
+ *   - Transitive closure (2-hop max for performance)
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { USER_CONFIG_DIR } from "./config";
+import { getLogger } from "./logger";
+
+const log = getLogger("graph");
+
+/* ═══════════════════════════════════════
+   Triple store — in-memory + optional persistence
+   ═══════════════════════════════════════ */
+interface Triple {
+  subj: string;
+  pred: string;
+  obj: string;
+  agent: string;
+  ts: string;
+  meta?: Record<string, string>;
+}
+
+export class KnowledgeGraph {
+  private triples: Triple[] = [];
+  private indexPath: string;
+
+  constructor(name: string = "default") {
+    this.indexPath = path.join(USER_CONFIG_DIR, `kg_${name}.json`);
+    this.load();
+  }
+
+  /** Add a fact: (subject, predicate, object). */
+  add(subj: string, pred: string, obj: string, agent: string = "system", meta?: Record<string, string>): void {
+    // Deduplicate
+    const exists = this.triples.find(t => t.subj === subj && t.pred === pred && t.obj === obj);
+    if (exists) { exists.ts = new Date().toISOString(); if (meta) exists.meta = { ...exists.meta, ...meta }; return; }
+
+    this.triples.push({ subj, pred, obj, agent, ts: new Date().toISOString(), meta });
+    if (this.triples.length > 5000) this.triples.splice(0, this.triples.length - 5000);
+    this.save();
+  }
+
+  /** Find all facts about an entity. */
+  about(entity: string, limit: number = 20): Triple[] {
+    return this.triples.filter(t => t.subj === entity || t.obj === entity).slice(-limit);
+  }
+
+  /** Find all subjects matching a predicate. */
+  byPredicate(pred: string): Triple[] {
+    return this.triples.filter(t => t.pred === pred);
+  }
+
+  /** Find all objects for a subject-predicate pair. */
+  find(subj: string, pred: string): Triple[] {
+    return this.triples.filter(t => t.subj === subj && t.pred === pred);
+  }
+
+  /** Transitive expansion: 2-hop from a starting entity. */
+  expand(entity: string, maxDepth: number = 2): Triple[] {
+    const seen = new Set<Triple>();
+    const queue = [entity];
+    for (let depth = 0; depth < maxDepth && queue.length > 0; depth++) {
+      const current = queue.shift()!;
+      const facts = this.about(current, 10);
+      for (const f of facts) {
+        if (seen.has(f)) continue;
+        seen.add(f);
+        if (f.subj === current && !queue.includes(f.obj)) queue.push(f.obj);
+        if (f.obj === current && !queue.includes(f.subj)) queue.push(f.subj);
+      }
+    }
+    return Array.from(seen);
+  }
+
+  /** Remove a fact. */
+  remove(subj: string, pred: string, obj: string): void {
+    this.triples = this.triples.filter(t => !(t.subj === subj && t.pred === pred && t.obj === obj));
+    this.save();
+  }
+
+  /** Search for entities or predicates containing a keyword. */
+  search(keyword: string, limit: number = 15): Triple[] {
+    const k = keyword.toLowerCase();
+    return this.triples.filter(t => t.subj.toLowerCase().includes(k) || t.pred.toLowerCase().includes(k) || t.obj.toLowerCase().includes(k)).slice(-limit);
+  }
+
+  /** Format facts as readable text. */
+  format(entity?: string): string {
+    const facts = entity ? this.about(entity) : this.triples.slice(-30);
+    if (facts.length === 0) return "(no facts)";
+    const bySubj = new Map<string, string[]>();
+    for (const f of facts) {
+      if (!bySubj.has(f.subj)) bySubj.set(f.subj, []);
+      bySubj.get(f.subj)!.push(`${f.pred} → ${f.obj}`);
+    }
+    const lines: string[] = [];
+    for (const [subj, preds] of bySubj) {
+      lines.push(`**${subj}**: ${preds.join(", ")}`);
+    }
+    return lines.join("\n");
+  }
+
+  get size(): number { return this.triples.length; }
+
+  private save(): void {
+    try {
+      const dir = path.dirname(this.indexPath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(this.indexPath, JSON.stringify(this.triples.slice(-2000)), "utf-8");
+    } catch (e) { log.warn("kg_save_failed", { error: String(e) }); }
+  }
+
+  private load(): void {
+    try {
+      if (fs.existsSync(this.indexPath)) {
+        this.triples = JSON.parse(fs.readFileSync(this.indexPath, "utf-8"));
+      }
+    } catch { this.triples = []; }
+  }
+}
+
+/* ── Auto-extract facts from conversation ── */
+const RELATION_PATTERNS: Array<[RegExp, string]> = [
+  [/(\w+) (?:是|为|属于|使用|用|用到了|采用) (.+?)(?:[。，,.\n]|$)/g, "is"],
+  [/(\w+) (?:版本|version|v) (?:是|为)? ?(\d[\d.]*)/gi, "version"],
+  [/(\w+) (?:depends|依赖|需要|requires) (\w+)/gi, "depends_on"],
+  [/(\w+) (?:config|配置) (?:为|是)? (.+?)(?:[。，,.\n]|$)/gi, "config"],
+  [/(\w+) (?:file|path|文件|路径) (?:在|为|at) (.+?)(?:[。，,.\n]|$)/gi, "located_at"],
+];
+
+export function extractFacts(text: string, agent: string): Array<[string, string, string]> {
+  const facts: Array<[string, string, string]> = [];
+  for (const [pattern, pred] of RELATION_PATTERNS) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const subj = match[1].trim().toLowerCase();
+      const obj = match[2].trim();
+      if (subj.length >= 2 && obj.length >= 2 && subj !== obj) {
+        facts.push([subj, pred, obj]);
+      }
+    }
+  }
+  return facts;
+}

package/src/core/icons.ts

@@ -1,53 +1,53 @@
-/**
- * Agent icon system — dynamic status indicators.
- *
- * Each agent is identified by its display name with color styling.
- * During processing, agent spinners provide dynamic status.
- */
-
-import * as path from 'path';
-
-const ICONS_DIR = path.resolve(__dirname, '..', 'assets', 'icons');
-
-export const AGENT_COLORS: Record<string, string> = {
-  fog: 'bright_white',
-  rain: 'blue',
-  frost: 'cyan',
-  snow: 'bright_white',
-  dew: 'green',
-  fair: '#FFD700',
-};
-
-export const AGENT_EMOJI: Record<string, string> = {
-  fog: '≋',
-  rain: '⸽',
-  frost: '✱',
-  snow: '❉',
-  dew: '∘',
-  fair: '☼',
-};
-
-/**
- * Return the filesystem path to an agent's SVG icon file.
- */
-export function svgPath(name: string): string {
-  return path.join(ICONS_DIR, `${name}.svg`);
-}
-
-/**
- * Return the plain-text icon for an agent.
- *
- * Used in dashboards, prompts, logs, and any UI where SVG can't render.
- * The glyphs are deliberately chosen from Unicode blocks that render
- * as monochrome text on virtually every terminal.
- *
- *   fog  ≋  three wavy lines — drifting mist
- *   rain ⸽  six vertical dots — falling rain streaks
- *   frost ✱  pointed asterisk — frost crystal
- *   snow ❉  balloon-spoked star — snowflake
- *   dew  ∘  ring — dewdrop
- *   fair ☼  sun with rays — clear sky
- */
-export function iconText(name: string): string {
-  return AGENT_EMOJI[name] ?? name;
-}
+/**
+ * Agent icon system — dynamic status indicators.
+ *
+ * Each agent is identified by its display name with color styling.
+ * During processing, agent spinners provide dynamic status.
+ */
+
+import * as path from 'path';
+
+const ICONS_DIR = path.resolve(__dirname, '..', 'assets', 'icons');
+
+export const AGENT_COLORS: Record<string, string> = {
+  fog: 'bright_white',
+  rain: 'blue',
+  frost: 'cyan',
+  snow: 'bright_white',
+  dew: 'green',
+  fair: '#FFD700',
+};
+
+export const AGENT_EMOJI: Record<string, string> = {
+  fog: '≋',
+  rain: '⸽',
+  frost: '✱',
+  snow: '❉',
+  dew: '∘',
+  fair: '☼',
+};
+
+/**
+ * Return the filesystem path to an agent's SVG icon file.
+ */
+export function svgPath(name: string): string {
+  return path.join(ICONS_DIR, `${name}.svg`);
+}
+
+/**
+ * Return the plain-text icon for an agent.
+ *
+ * Used in dashboards, prompts, logs, and any UI where SVG can't render.
+ * The glyphs are deliberately chosen from Unicode blocks that render
+ * as monochrome text on virtually every terminal.
+ *
+ *   fog  ≋  three wavy lines — drifting mist
+ *   rain ⸽  six vertical dots — falling rain streaks
+ *   frost ✱  pointed asterisk — frost crystal
+ *   snow ❉  balloon-spoked star — snowflake
+ *   dew  ∘  ring — dewdrop
+ *   fair ☼  sun with rays — clear sky
+ */
+export function iconText(name: string): string {
+  return AGENT_EMOJI[name] ?? name;
+}