@datasynx/agentic-ai-cartography 0.9.2 → 1.1.0

package/dist/index.js

@@ -2,6 +2,203 @@
 import Database from "better-sqlite3";
 import { mkdirSync } from "fs";
 import { dirname } from "path";
+import { z as z2 } from "zod";
+
+// src/types.ts
+import { z } from "zod";
+var NODE_TYPES = [
+  "host",
+  "database_server",
+  "database",
+  "table",
+  "web_service",
+  "api_endpoint",
+  "cache_server",
+  "message_broker",
+  "queue",
+  "topic",
+  "container",
+  "pod",
+  "k8s_cluster",
+  "config_file",
+  "saas_tool",
+  "unknown"
+];
+var EDGE_RELATIONSHIPS = [
+  "connects_to",
+  "reads_from",
+  "writes_to",
+  "calls",
+  "contains",
+  "depends_on"
+];
+var NodeSchema = z.object({
+  id: z.string().describe('Format: "{type}:{host}:{port}" oder "{type}:{name}"'),
+  type: z.enum(NODE_TYPES),
+  name: z.string(),
+  discoveredVia: z.string(),
+  confidence: z.number().min(0).max(1).default(0.5),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  tags: z.array(z.string()).default([]),
+  domain: z.string().optional().describe('Business domain, e.g. "Marketing", "Finance"'),
+  subDomain: z.string().optional().describe('Sub-domain, e.g. "Forecast client orders"'),
+  qualityScore: z.number().min(0).max(100).optional().describe("Data quality score 0\u2013100")
+});
+var EdgeSchema = z.object({
+  sourceId: z.string(),
+  targetId: z.string(),
+  relationship: z.enum(EDGE_RELATIONSHIPS),
+  evidence: z.string(),
+  confidence: z.number().min(0).max(1).default(0.5)
+});
+var DataAssetSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  domain: z.string(),
+  subDomain: z.string().optional(),
+  qualityScore: z.number().min(0).max(100).optional(),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  position: z.object({ q: z.number(), r: z.number() })
+});
+var ClusterSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  domain: z.string(),
+  color: z.string(),
+  assetIds: z.array(z.string()),
+  centroid: z.object({ x: z.number(), y: z.number() })
+});
+var ConnectionSchema = z.object({
+  id: z.string(),
+  sourceAssetId: z.string(),
+  targetAssetId: z.string(),
+  type: z.string().optional()
+});
+var DOMAIN_COLORS = {
+  "Quality Control": "#1a2744",
+  "Supply Chain": "#1e3a6e",
+  "Marketing": "#6a7fb5",
+  "Finance": "#3a8a8a",
+  "HR": "#2a5a9a",
+  "Logistics": "#0e7490",
+  "Sales": "#1d4ed8",
+  "Engineering": "#4338ca",
+  "Operations": "#0891b2",
+  "Data Layer": "#1e3352",
+  "Web / API": "#1a3a1a",
+  "Messaging": "#2a1a3a",
+  "Infrastructure": "#0f2a40",
+  "Other": "#374151"
+};
+var DOMAIN_PALETTE = [
+  "#1a2e5a",
+  "#1e3a8a",
+  "#1d4ed8",
+  "#2563eb",
+  "#3b82f6",
+  "#6366f1",
+  "#818cf8",
+  "#7c9fc3",
+  "#0e7490",
+  "#0891b2",
+  "#06b6d4",
+  "#22d3ee",
+  "#0d9488",
+  "#14b8a6",
+  "#2dd4bf",
+  "#5eead4"
+];
+function defaultConfig(overrides = {}) {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  return {
+    maxDepth: 8,
+    maxTurns: 50,
+    entryPoints: ["localhost"],
+    agentModel: "claude-sonnet-4-5-20250929",
+    outputDir: "./cartography-output",
+    dbPath: `${home}/.cartography/cartography.db`,
+    verbose: false,
+    ...overrides
+  };
+}
+
+// src/db.ts
+var SessionRowSchema = z2.object({
+  id: z2.string(),
+  mode: z2.literal("discover"),
+  started_at: z2.string(),
+  completed_at: z2.string().nullable().optional(),
+  config: z2.string()
+});
+var NodeRowSchema = z2.object({
+  id: z2.string(),
+  session_id: z2.string(),
+  type: z2.enum(NODE_TYPES),
+  name: z2.string(),
+  discovered_via: z2.string().nullable().optional(),
+  discovered_at: z2.string(),
+  path_id: z2.string().nullable().optional(),
+  depth: z2.number().default(0),
+  confidence: z2.number().default(0.5),
+  metadata: z2.string().default("{}"),
+  tags: z2.string().default("[]"),
+  domain: z2.string().nullable().optional(),
+  sub_domain: z2.string().nullable().optional(),
+  quality_score: z2.number().nullable().optional()
+});
+var EdgeRowSchema = z2.object({
+  id: z2.string(),
+  session_id: z2.string(),
+  source_id: z2.string(),
+  target_id: z2.string(),
+  relationship: z2.enum(EDGE_RELATIONSHIPS),
+  evidence: z2.string().nullable().optional(),
+  confidence: z2.number().default(0.5),
+  discovered_at: z2.string()
+});
+var EventRowSchema = z2.object({
+  id: z2.string(),
+  session_id: z2.string(),
+  task_id: z2.string().nullable().optional(),
+  timestamp: z2.string(),
+  event_type: z2.string(),
+  process: z2.string(),
+  pid: z2.number(),
+  target: z2.string().nullable().optional(),
+  target_type: z2.string().nullable().optional(),
+  port: z2.number().nullable().optional(),
+  duration_ms: z2.number().nullable().optional()
+});
+var TaskRowSchema = z2.object({
+  id: z2.string(),
+  session_id: z2.string(),
+  description: z2.string().nullable().optional(),
+  started_at: z2.string(),
+  completed_at: z2.string().nullable().optional(),
+  steps: z2.string().default("[]"),
+  involved_services: z2.string().default("[]"),
+  status: z2.enum(["active", "completed", "cancelled"])
+});
+var WorkflowRowSchema = z2.object({
+  id: z2.string(),
+  session_id: z2.string(),
+  name: z2.string().nullable().optional(),
+  pattern: z2.string(),
+  task_ids: z2.string().default("[]"),
+  occurrences: z2.number().default(1),
+  first_seen: z2.string(),
+  last_seen: z2.string(),
+  avg_duration_ms: z2.number().nullable().optional(),
+  involved_services: z2.string().default("[]")
+});
+var ConnectionRowSchema = z2.object({
+  id: z2.string(),
+  session_id: z2.string(),
+  source_asset_id: z2.string(),
+  target_asset_id: z2.string(),
+  type: z2.string().nullable().optional(),
+  created_at: z2.string()
+});
 var SCHEMA = `
 PRAGMA journal_mode = WAL;
 PRAGMA foreign_keys = ON;
@@ -166,12 +363,13 @@ var CartographyDB = class {
     return rows.map((r) => this.mapSession(r));
   }
   mapSession(r) {
+    const v = SessionRowSchema.parse(r);
     return {
-      id: r["id"],
-      mode: r["mode"],
-      startedAt: r["started_at"],
-      completedAt: r["completed_at"] ?? void 0,
-      config: r["config"]
+      id: v.id,
+      mode: v.mode,
+      startedAt: v.started_at,
+      completedAt: v.completed_at ?? void 0,
+      config: v.config
     };
   }
   // ── Nodes ───────────────────────────────
@@ -202,21 +400,22 @@ var CartographyDB = class {
     return rows.map((r) => this.mapNode(r));
   }
   mapNode(r) {
+    const v = NodeRowSchema.parse(r);
     return {
-      id: r["id"],
-      sessionId: r["session_id"],
-      type: r["type"],
-      name: r["name"],
-      discoveredVia: r["discovered_via"],
-      discoveredAt: r["discovered_at"],
-      depth: r["depth"],
-      confidence: r["confidence"],
-      metadata: JSON.parse(r["metadata"]),
-      tags: JSON.parse(r["tags"]),
-      pathId: r["path_id"],
-      domain: r["domain"] ?? void 0,
-      subDomain: r["sub_domain"] ?? void 0,
-      qualityScore: r["quality_score"] ?? void 0
+      id: v.id,
+      sessionId: v.session_id,
+      type: v.type,
+      name: v.name,
+      discoveredVia: v.discovered_via ?? "",
+      discoveredAt: v.discovered_at,
+      depth: v.depth,
+      confidence: v.confidence,
+      metadata: JSON.parse(v.metadata),
+      tags: JSON.parse(v.tags),
+      pathId: v.path_id ?? void 0,
+      domain: v.domain ?? void 0,
+      subDomain: v.sub_domain ?? void 0,
+      qualityScore: v.quality_score ?? void 0
     };
   }
   deleteNode(sessionId, nodeId) {
@@ -245,16 +444,19 @@ var CartographyDB = class {
   }
   getEdges(sessionId) {
     const rows = this.db.prepare("SELECT * FROM edges WHERE session_id = ?").all(sessionId);
-    return rows.map((r) => ({
-      id: r["id"],
-      sessionId: r["session_id"],
-      sourceId: r["source_id"],
-      targetId: r["target_id"],
-      relationship: r["relationship"],
-      evidence: r["evidence"],
-      confidence: r["confidence"],
-      discoveredAt: r["discovered_at"]
-    }));
+    return rows.map((r) => {
+      const v = EdgeRowSchema.parse(r);
+      return {
+        id: v.id,
+        sessionId: v.session_id,
+        sourceId: v.source_id,
+        targetId: v.target_id,
+        relationship: v.relationship,
+        evidence: v.evidence ?? "",
+        confidence: v.confidence,
+        discoveredAt: v.discovered_at
+      };
+    });
   }
   // ── Events ──────────────────────────────
   insertEvent(sessionId, event, taskId) {
@@ -278,19 +480,22 @@ var CartographyDB = class {
   }
   getEvents(sessionId, since) {
     const rows = since ? this.db.prepare("SELECT * FROM activity_events WHERE session_id = ? AND timestamp > ? ORDER BY timestamp").all(sessionId, since) : this.db.prepare("SELECT * FROM activity_events WHERE session_id = ? ORDER BY timestamp").all(sessionId);
-    return rows.map((r) => ({
-      id: r["id"],
-      sessionId: r["session_id"],
-      taskId: r["task_id"],
-      timestamp: r["timestamp"],
-      eventType: r["event_type"],
-      process: r["process"],
-      pid: r["pid"],
-      target: r["target"],
-      targetType: r["target_type"],
-      port: r["port"],
-      durationMs: r["duration_ms"]
-    }));
+    return rows.map((r) => {
+      const v = EventRowSchema.parse(r);
+      return {
+        id: v.id,
+        sessionId: v.session_id,
+        taskId: v.task_id ?? void 0,
+        timestamp: v.timestamp,
+        eventType: v.event_type,
+        process: v.process,
+        pid: v.pid,
+        target: v.target ?? void 0,
+        targetType: v.target_type ?? void 0,
+        port: v.port ?? void 0,
+        durationMs: v.duration_ms ?? void 0
+      };
+    });
   }
   // ── Tasks ───────────────────────────────
   startTask(sessionId, description) {
@@ -324,15 +529,16 @@ var CartographyDB = class {
     return rows.map((r) => this.mapTask(r));
   }
   mapTask(r) {
+    const v = TaskRowSchema.parse(r);
     return {
-      id: r["id"],
-      sessionId: r["session_id"],
-      description: r["description"],
-      startedAt: r["started_at"],
-      completedAt: r["completed_at"],
-      steps: r["steps"],
-      involvedServices: r["involved_services"],
-      status: r["status"]
+      id: v.id,
+      sessionId: v.session_id,
+      description: v.description ?? void 0,
+      startedAt: v.started_at,
+      completedAt: v.completed_at ?? void 0,
+      steps: v.steps,
+      involvedServices: v.involved_services,
+      status: v.status
     };
   }
   // ── Workflows ───────────────────────────
@@ -358,18 +564,21 @@ var CartographyDB = class {
   }
   getWorkflows(sessionId) {
     const rows = this.db.prepare("SELECT * FROM workflows WHERE session_id = ?").all(sessionId);
-    return rows.map((r) => ({
-      id: r["id"],
-      sessionId: r["session_id"],
-      name: r["name"],
-      pattern: r["pattern"],
-      taskIds: r["task_ids"],
-      occurrences: r["occurrences"],
-      firstSeen: r["first_seen"],
-      lastSeen: r["last_seen"],
-      avgDurationMs: r["avg_duration_ms"],
-      involvedServices: r["involved_services"]
-    }));
+    return rows.map((r) => {
+      const v = WorkflowRowSchema.parse(r);
+      return {
+        id: v.id,
+        sessionId: v.session_id,
+        name: v.name ?? void 0,
+        pattern: v.pattern,
+        taskIds: v.task_ids,
+        occurrences: v.occurrences,
+        firstSeen: v.first_seen,
+        lastSeen: v.last_seen,
+        avgDurationMs: v.avg_duration_ms ?? 0,
+        involvedServices: v.involved_services
+      };
+    });
   }
   // ── Connections (user-created hex map links) ─────────────────────────────
   upsertConnection(sessionId, conn) {
@@ -386,14 +595,17 @@ var CartographyDB = class {
   }
   getConnections(sessionId) {
     const rows = this.db.prepare("SELECT * FROM connections WHERE session_id = ?").all(sessionId);
-    return rows.map((r) => ({
-      id: r["id"],
-      sessionId: r["session_id"],
-      sourceAssetId: r["source_asset_id"],
-      targetAssetId: r["target_asset_id"],
-      type: r["type"] ?? void 0,
-      createdAt: r["created_at"]
-    }));
+    return rows.map((r) => {
+      const v = ConnectionRowSchema.parse(r);
+      return {
+        id: v.id,
+        sessionId: v.session_id,
+        sourceAssetId: v.source_asset_id,
+        targetAssetId: v.target_asset_id,
+        type: v.type ?? void 0,
+        createdAt: v.created_at
+      };
+    });
   }
   deleteConnection(sessionId, connectionId) {
     this.db.prepare("DELETE FROM connections WHERE session_id = ? AND id = ?").run(sessionId, connectionId);
@@ -408,6 +620,31 @@ var CartographyDB = class {
     const row = this.db.prepare("SELECT action FROM node_approvals WHERE pattern = ?").get(pattern);
     return row?.action;
   }
+  // ── Pruning ──────────────────────────────
+  /**
+   * Delete a session and all its associated data (nodes, edges, events, tasks, workflows, connections).
+   */
+  deleteSession(sessionId) {
+    this.db.prepare("DELETE FROM connections WHERE session_id = ?").run(sessionId);
+    this.db.prepare("DELETE FROM workflows WHERE session_id = ?").run(sessionId);
+    this.db.prepare("DELETE FROM activity_events WHERE session_id = ?").run(sessionId);
+    this.db.prepare("DELETE FROM tasks WHERE session_id = ?").run(sessionId);
+    this.db.prepare("DELETE FROM edges WHERE session_id = ?").run(sessionId);
+    this.db.prepare("DELETE FROM nodes WHERE session_id = ?").run(sessionId);
+    this.db.prepare("DELETE FROM sessions WHERE id = ?").run(sessionId);
+  }
+  /**
+   * Prune sessions older than the given ISO date string. Returns count of deleted sessions.
+   */
+  pruneSessions(olderThan) {
+    const rows = this.db.prepare(
+      "SELECT id FROM sessions WHERE started_at < ?"
+    ).all(olderThan);
+    for (const row of rows) {
+      this.deleteSession(row.id);
+    }
+    return rows.length;
+  }
   // ── Stats ───────────────────────────────
   getStats(sessionId) {
     const nodes = this.db.prepare("SELECT COUNT(*) as c FROM nodes WHERE session_id = ?").get(sessionId).c;
@@ -419,129 +656,11 @@ var CartographyDB = class {
 };
 
 // src/tools.ts
-import { z as z2 } from "zod";
-
-// src/types.ts
-import { z } from "zod";
-var NODE_TYPES = [
-  "host",
-  "database_server",
-  "database",
-  "table",
-  "web_service",
-  "api_endpoint",
-  "cache_server",
-  "message_broker",
-  "queue",
-  "topic",
-  "container",
-  "pod",
-  "k8s_cluster",
-  "config_file",
-  "saas_tool",
-  "unknown"
-];
-var EDGE_RELATIONSHIPS = [
-  "connects_to",
-  "reads_from",
-  "writes_to",
-  "calls",
-  "contains",
-  "depends_on"
-];
-var NodeSchema = z.object({
-  id: z.string().describe('Format: "{type}:{host}:{port}" oder "{type}:{name}"'),
-  type: z.enum(NODE_TYPES),
-  name: z.string(),
-  discoveredVia: z.string(),
-  confidence: z.number().min(0).max(1).default(0.5),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  tags: z.array(z.string()).default([]),
-  domain: z.string().optional().describe('Business domain, e.g. "Marketing", "Finance"'),
-  subDomain: z.string().optional().describe('Sub-domain, e.g. "Forecast client orders"'),
-  qualityScore: z.number().min(0).max(100).optional().describe("Data quality score 0\u2013100")
-});
-var EdgeSchema = z.object({
-  sourceId: z.string(),
-  targetId: z.string(),
-  relationship: z.enum(EDGE_RELATIONSHIPS),
-  evidence: z.string(),
-  confidence: z.number().min(0).max(1).default(0.5)
-});
-var DataAssetSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  domain: z.string(),
-  subDomain: z.string().optional(),
-  qualityScore: z.number().min(0).max(100).optional(),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  position: z.object({ q: z.number(), r: z.number() })
-});
-var ClusterSchema = z.object({
-  id: z.string(),
-  label: z.string(),
-  domain: z.string(),
-  color: z.string(),
-  assetIds: z.array(z.string()),
-  centroid: z.object({ x: z.number(), y: z.number() })
-});
-var ConnectionSchema = z.object({
-  id: z.string(),
-  sourceAssetId: z.string(),
-  targetAssetId: z.string(),
-  type: z.string().optional()
-});
-var DOMAIN_COLORS = {
-  "Quality Control": "#1a2744",
-  "Supply Chain": "#1e3a6e",
-  "Marketing": "#6a7fb5",
-  "Finance": "#3a8a8a",
-  "HR": "#2a5a9a",
-  "Logistics": "#0e7490",
-  "Sales": "#1d4ed8",
-  "Engineering": "#4338ca",
-  "Operations": "#0891b2",
-  "Data Layer": "#1e3352",
-  "Web / API": "#1a3a1a",
-  "Messaging": "#2a1a3a",
-  "Infrastructure": "#0f2a40",
-  "Other": "#374151"
-};
-var DOMAIN_PALETTE = [
-  "#1a2e5a",
-  "#1e3a8a",
-  "#1d4ed8",
-  "#2563eb",
-  "#3b82f6",
-  "#6366f1",
-  "#818cf8",
-  "#7c9fc3",
-  "#0e7490",
-  "#0891b2",
-  "#06b6d4",
-  "#22d3ee",
-  "#0d9488",
-  "#14b8a6",
-  "#2dd4bf",
-  "#5eead4"
-];
-function defaultConfig(overrides = {}) {
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
-  return {
-    maxDepth: 8,
-    maxTurns: 50,
-    entryPoints: ["localhost"],
-    agentModel: "claude-sonnet-4-5-20250929",
-    outputDir: "./cartography-output",
-    dbPath: `${home}/.cartography/cartography.db`,
-    verbose: false,
-    ...overrides
-  };
-}
+import { z as z3 } from "zod";
 
 // src/bookmarks.ts
 import { tmpdir } from "os";
-import { existsSync as existsSync2, readFileSync, readdirSync, copyFileSync, statSync } from "fs";
+import { existsSync as existsSync2, readFileSync, readdirSync, copyFileSync, statSync, unlinkSync } from "fs";
 import { join as join2 } from "path";
 
 // src/platform.ts
@@ -568,13 +687,42 @@ function getShell() {
   if (!_shell) _shell = platformShell();
   return _shell;
 }
+var SAFE_ENV_KEYS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LANG",
+  "LC_ALL",
+  "TERM",
+  "SHELL",
+  "USERPROFILE",
+  "LOCALAPPDATA",
+  "APPDATA",
+  "PROGRAMFILES",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_RUNTIME_DIR",
+  "AWS_DEFAULT_REGION",
+  "AWS_PROFILE",
+  "AWS_CONFIG_FILE",
+  "KUBECONFIG",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  "AZURE_CONFIG_DIR"
+];
+function safeEnv() {
+  const env = {};
+  for (const key of SAFE_ENV_KEYS) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
 function run(cmd, opts = {}) {
   try {
     return execSync(cmd, {
       stdio: "pipe",
       timeout: opts.timeout ?? 1e4,
       shell: getShell(),
-      env: opts.env
+      env: opts.env ?? safeEnv()
     }).toString().trim();
   } catch {
     return "";
@@ -688,6 +836,23 @@ function scanWindowsDbServices() {
 }
 
 // src/bookmarks.ts
+function cleanupTempFiles() {
+  let cleaned = 0;
+  const tmp = tmpdir();
+  try {
+    for (const f of readdirSync(tmp)) {
+      if (f.startsWith("cartograph_") && f.endsWith(".sqlite")) {
+        try {
+          unlinkSync(join2(tmp, f));
+          cleaned++;
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  return cleaned;
+}
 function extractHost(rawUrl, source) {
   try {
     const u = new URL(rawUrl);
@@ -933,6 +1098,22 @@ async function scanAllHistory() {
 }
 
 // src/tools.ts
+function createScanRunner(runFn, opts = {}) {
+  const threshold = opts.threshold ?? 3;
+  let consecutiveFailures = 0;
+  let tripped = false;
+  return (cmd) => {
+    if (tripped) return "(skipped \u2014 circuit breaker: too many consecutive failures)";
+    const result = runFn(cmd, { timeout: opts.timeout ?? 2e4, env: opts.env });
+    if (!result) {
+      consecutiveFailures++;
+      if (consecutiveFailures >= threshold) tripped = true;
+      return "(error or not available)";
+    }
+    consecutiveFailures = 0;
+    return result;
+  };
+}
 function stripSensitive(target) {
   try {
     const url = new URL(target.startsWith("http") ? target : `tcp://${target}`);
@@ -945,16 +1126,16 @@ async function createCartographyTools(db, sessionId, opts = {}) {
   const { tool, createSdkMcpServer } = await import("@anthropic-ai/claude-agent-sdk");
   const tools = [
     tool("save_node", "Save an infrastructure node to the catalog", {
-      id: z2.string(),
-      type: z2.enum(NODE_TYPES),
-      name: z2.string(),
-      discoveredVia: z2.string(),
-      confidence: z2.number().min(0).max(1),
-      metadata: z2.record(z2.string(), z2.unknown()).optional(),
-      tags: z2.array(z2.string()).optional(),
-      domain: z2.string().optional().describe('Business domain, e.g. "Marketing", "Finance"'),
-      subDomain: z2.string().optional().describe('Sub-domain, e.g. "Forecast client orders"'),
-      qualityScore: z2.number().min(0).max(100).optional().describe("Data quality score 0\u2013100")
+      id: z3.string(),
+      type: z3.enum(NODE_TYPES),
+      name: z3.string(),
+      discoveredVia: z3.string(),
+      confidence: z3.number().min(0).max(1),
+      metadata: z3.record(z3.string(), z3.unknown()).optional(),
+      tags: z3.array(z3.string()).optional(),
+      domain: z3.string().optional().describe('Business domain, e.g. "Marketing", "Finance"'),
+      subDomain: z3.string().optional().describe('Sub-domain, e.g. "Forecast client orders"'),
+      qualityScore: z3.number().min(0).max(100).optional().describe("Data quality score 0\u2013100")
     }, async (args) => {
       const node = {
         id: stripSensitive(args["id"]),
@@ -972,11 +1153,11 @@ async function createCartographyTools(db, sessionId, opts = {}) {
       return { content: [{ type: "text", text: `\u2713 Node: ${node.id}` }] };
     }),
     tool("save_edge", "Save a relationship (edge) between two nodes \u2014 ALWAYS save edges when connections are clear", {
-      sourceId: z2.string(),
-      targetId: z2.string(),
-      relationship: z2.enum(EDGE_RELATIONSHIPS),
-      evidence: z2.string(),
-      confidence: z2.number().min(0).max(1)
+      sourceId: z3.string(),
+      targetId: z3.string(),
+      relationship: z3.enum(EDGE_RELATIONSHIPS),
+      evidence: z3.string(),
+      confidence: z3.number().min(0).max(1)
     }, async (args) => {
       db.insertEdge(sessionId, {
         sourceId: args["sourceId"],
@@ -988,7 +1169,7 @@ async function createCartographyTools(db, sessionId, opts = {}) {
       return { content: [{ type: "text", text: `\u2713 ${args["sourceId"]}\u2192${args["targetId"]}` }] };
     }),
     tool("get_catalog", "Get the current catalog \u2014 use before save_node to avoid duplicates", {
-      includeEdges: z2.boolean().default(true)
+      includeEdges: z3.boolean().default(true)
     }, async (args) => {
       const nodes = db.getNodes(sessionId);
       const edges = args["includeEdges"] ? db.getEdges(sessionId) : [];
@@ -1003,8 +1184,8 @@ async function createCartographyTools(db, sessionId, opts = {}) {
       };
     }),
     tool("ask_user", "Ask the user a question \u2014 for clarifications, missing context, or consent (e.g. before scanning browser history)", {
-      question: z2.string().describe("The question for the user (clear and specific)"),
-      context: z2.string().optional().describe("Optional context explaining why this is relevant")
+      question: z3.string().describe("The question for the user (clear and specific)"),
+      context: z3.string().optional().describe("Optional context explaining why this is relevant")
     }, async (args) => {
       const question = args["question"];
       const context = args["context"];
@@ -1017,7 +1198,7 @@ async function createCartographyTools(db, sessionId, opts = {}) {
       };
     }),
     tool("scan_bookmarks", "Scan all browser bookmarks \u2014 hostnames only, no personal data (Chrome, Chromium, Edge, Brave, Vivaldi, Opera, Firefox)", {
-      minConfidence: z2.number().min(0).max(1).default(0.5).optional()
+      minConfidence: z3.number().min(0).max(1).default(0.5).optional()
     }, async () => {
       const hosts = await scanAllBookmarks();
       return {
@@ -1037,7 +1218,7 @@ async function createCartographyTools(db, sessionId, opts = {}) {
       };
     }),
     tool("scan_browser_history", "Scan browser history \u2014 anonymized hostnames + visit frequency. ALWAYS call ask_user for consent before using this tool.", {
-      minVisits: z2.number().min(1).default(3).optional().describe("Minimum visit count to include a host (filters rarely-visited sites)")
+      minVisits: z3.number().min(1).default(3).optional().describe("Minimum visit count to include a host (filters rarely-visited sites)")
     }, async (args) => {
       const minVisits = args["minVisits"] ?? 3;
       const hosts = await scanAllHistory();
@@ -1059,7 +1240,7 @@ async function createCartographyTools(db, sessionId, opts = {}) {
       };
     }),
     tool("scan_local_databases", "Scan for local database files and running DB servers \u2014 PostgreSQL databases, MySQL, SQLite files from installed apps", {
-      deep: z2.boolean().default(false).optional().describe("Also search home directory recursively for SQLite/DB files (slower)")
+      deep: z3.boolean().default(false).optional().describe("Also search home directory recursively for SQLite/DB files (slower)")
     }, async (args) => {
       const deep = args["deep"] ?? false;
       const results = {};
@@ -1131,14 +1312,11 @@ ${v}`).join("\n\n");
       return { content: [{ type: "text", text: out }] };
     }),
     tool("scan_k8s_resources", "Scan Kubernetes cluster via kubectl \u2014 100% readonly (get, describe)", {
-      namespace: z2.string().optional().describe("Filter by namespace \u2014 empty = all namespaces")
+      namespace: z3.string().optional().describe("Filter by namespace \u2014 empty = all namespaces")
     }, async (args) => {
       const ns = args["namespace"];
       const nsFlag = ns ? `-n ${ns}` : "--all-namespaces";
-      const runK = (cmd) => {
-        const r = run(cmd, { timeout: 15e3 });
-        return r || `(error or not available)`;
-      };
+      const runK = createScanRunner(run, { timeout: 15e3, threshold: 3 });
       const sections = IS_WIN ? [
         ["CONTEXT", "kubectl config current-context"],
         ["NODES", "kubectl get nodes -o wide"],
@@ -1165,15 +1343,15 @@ ${runK(c)}`).join("\n\n");
       return { content: [{ type: "text", text: out }] };
     }),
     tool("scan_aws_resources", "Scan AWS infrastructure via AWS CLI \u2014 100% readonly (describe, list)", {
-      region: z2.string().optional().describe("AWS Region \u2014 default: AWS_DEFAULT_REGION or profile"),
-      profile: z2.string().optional().describe("AWS CLI profile")
+      region: z3.string().optional().describe("AWS Region \u2014 default: AWS_DEFAULT_REGION or profile"),
+      profile: z3.string().optional().describe("AWS CLI profile")
     }, async (args) => {
       const region = args["region"];
       const profile = args["profile"];
       const env = { ...process.env };
       if (region) env["AWS_DEFAULT_REGION"] = region;
       const pf = profile ? `--profile ${profile}` : "";
-      const runAws = (cmd) => run(cmd, { timeout: 2e4, env }) || "(error or not available)";
+      const runAws = createScanRunner(run, { timeout: 2e4, env, threshold: 3 });
       const sections = [
         ["IDENTITY", `aws sts get-caller-identity ${pf} --output json`],
         ["EC2", `aws ec2 describe-instances ${pf} --query "Reservations[*].Instances[*].[InstanceId,InstanceType,State.Name,PublicIpAddress,PrivateIpAddress]" --output table`],
@@ -1189,11 +1367,11 @@ ${runAws(c)}`).join("\n\n");
       return { content: [{ type: "text", text: out }] };
     }),
     tool("scan_gcp_resources", "Scan Google Cloud Platform via gcloud CLI \u2014 100% readonly (list, describe)", {
-      project: z2.string().optional().describe("GCP Project ID \u2014 default: current gcloud project")
+      project: z3.string().optional().describe("GCP Project ID \u2014 default: current gcloud project")
     }, async (args) => {
       const project = args["project"];
       const pf = project ? `--project ${project}` : "";
-      const runGcp = (cmd) => run(cmd, { timeout: 2e4 }) || "(error or not available)";
+      const runGcp = createScanRunner(run, { timeout: 2e4, threshold: 3 });
       const sections = [
         ["IDENTITY", `gcloud config list account --format="value(core.account)"`],
         ["COMPUTE_INSTANCES", `gcloud compute instances list ${pf}`],
@@ -1210,14 +1388,14 @@ ${runGcp(c)}`).join("\n\n");
       return { content: [{ type: "text", text: out }] };
     }),
     tool("scan_azure_resources", "Scan Azure infrastructure via az CLI \u2014 100% readonly (list, show)", {
-      subscription: z2.string().optional().describe("Azure Subscription ID"),
-      resourceGroup: z2.string().optional().describe("Filter by resource group")
+      subscription: z3.string().optional().describe("Azure Subscription ID"),
+      resourceGroup: z3.string().optional().describe("Filter by resource group")
     }, async (args) => {
       const sub = args["subscription"];
       const rg = args["resourceGroup"];
       const sf = sub ? `--subscription ${sub}` : "";
       const rf = rg ? `--resource-group ${rg}` : "";
-      const runAz = (cmd) => run(cmd, { timeout: 2e4 }) || "(error or not available)";
+      const runAz = createScanRunner(run, { timeout: 2e4, threshold: 3 });
       const sections = [
         ["IDENTITY", `az account show --output json ${sf}`],
         ["VMS", `az vm list ${sf} ${rf} --output table`],
@@ -1234,7 +1412,7 @@ ${runAz(c)}`).join("\n\n");
       return { content: [{ type: "text", text: out }] };
     }),
     tool("scan_installed_apps", "Scan all installed apps and tools \u2014 IDEs, office, dev tools, business apps, databases", {
-      searchHint: z2.string().optional().describe('Optional search term to find specific tools (e.g. "hubspot windsurf cursor")')
+      searchHint: z3.string().optional().describe('Optional search term to find specific tools (e.g. "hubspot windsurf cursor")')
     }, async (args) => {
       const hint = args["searchHint"];
       const results = {};
@@ -1558,68 +1736,81 @@ Then scan_local_databases() for database servers and SQLite files.
 Then systematically scan local services, then config files.
 Finally, map all edges (Step 8 \u2014 critical!) before finishing.
 Use ask_user when you need context from the user.`;
+  const MAX_DISCOVERY_MS = 30 * 60 * 1e3;
   let turnCount = 0;
-  for await (const msg of query({
-    prompt: initialPrompt,
-    options: {
-      model: config.agentModel,
-      maxTurns: config.maxTurns,
-      systemPrompt,
-      mcpServers: { cartography: tools },
-      allowedTools: [
-        "Bash",
-        "mcp__cartograph__save_node",
-        "mcp__cartograph__save_edge",
-        "mcp__cartograph__get_catalog",
-        "mcp__cartograph__scan_bookmarks",
-        "mcp__cartograph__scan_browser_history",
-        "mcp__cartograph__scan_installed_apps",
-        "mcp__cartograph__scan_local_databases",
-        "mcp__cartograph__scan_k8s_resources",
-        "mcp__cartograph__scan_aws_resources",
-        "mcp__cartograph__scan_gcp_resources",
-        "mcp__cartograph__scan_azure_resources",
-        "mcp__cartograph__ask_user"
-      ],
-      hooks: {
-        PreToolUse: [{ matcher: "Bash", hooks: [safetyHook] }]
-      },
-      permissionMode: "bypassPermissions"
-    }
-  })) {
-    if (!onEvent) continue;
-    if (msg.type === "assistant") {
-      turnCount++;
-      onEvent({ kind: "turn", turn: turnCount });
-      for (const block of msg.message.content) {
-        if (block.type === "text") {
-          onEvent({ kind: "thinking", text: block.text });
-        }
-        if (block.type === "tool_use") {
-          onEvent({
-            kind: "tool_call",
-            tool: block.name,
-            input: block.input
-          });
+  try {
+    const startTime = Date.now();
+    for await (const msg of query({
+      prompt: initialPrompt,
+      options: {
+        model: config.agentModel,
+        maxTurns: config.maxTurns,
+        systemPrompt,
+        mcpServers: { cartography: tools },
+        allowedTools: [
+          "Bash",
+          "mcp__cartograph__save_node",
+          "mcp__cartograph__save_edge",
+          "mcp__cartograph__get_catalog",
+          "mcp__cartograph__scan_bookmarks",
+          "mcp__cartograph__scan_browser_history",
+          "mcp__cartograph__scan_installed_apps",
+          "mcp__cartograph__scan_local_databases",
+          "mcp__cartograph__scan_k8s_resources",
+          "mcp__cartograph__scan_aws_resources",
+          "mcp__cartograph__scan_gcp_resources",
+          "mcp__cartograph__scan_azure_resources",
+          "mcp__cartograph__ask_user"
+        ],
+        hooks: {
+          PreToolUse: [{ matcher: "Bash", hooks: [safetyHook] }]
+        },
+        permissionMode: "bypassPermissions"
+      }
+    })) {
+      if (Date.now() - startTime > MAX_DISCOVERY_MS) {
+        onEvent?.({ kind: "error", text: `Discovery timeout after ${MAX_DISCOVERY_MS / 6e4} minutes` });
+        onEvent?.({ kind: "done" });
+        return;
+      }
+      if (!onEvent) continue;
+      if (msg.type === "assistant") {
+        turnCount++;
+        onEvent({ kind: "turn", turn: turnCount });
+        for (const block of msg.message.content) {
+          if (block.type === "text") {
+            onEvent({ kind: "thinking", text: block.text });
+          }
+          if (block.type === "tool_use") {
+            onEvent({
+              kind: "tool_call",
+              tool: block.name,
+              input: block.input
+            });
+          }
         }
       }
-    }
-    if (msg.type === "user") {
-      const content = msg.message?.content;
-      if (Array.isArray(content)) {
-        for (const block of content) {
-          if (typeof block === "object" && block !== null && "type" in block && block.type === "tool_result") {
-            const tb = block;
-            const text = typeof tb.content === "string" ? tb.content : "";
-            onEvent({ kind: "tool_result", tool: tb.tool_use_id ?? "", output: text });
+      if (msg.type === "user") {
+        const content = msg.message?.content;
+        if (Array.isArray(content)) {
+          for (const block of content) {
+            if (typeof block === "object" && block !== null && "type" in block && block.type === "tool_result") {
+              const tb = block;
+              const text = typeof tb.content === "string" ? tb.content : "";
+              onEvent({ kind: "tool_result", tool: tb.tool_use_id ?? "", output: text });
+            }
           }
         }
       }
+      if (msg.type === "result") {
+        onEvent({ kind: "done" });
+        return;
+      }
     }
-    if (msg.type === "result") {
-      onEvent({ kind: "done" });
-      return;
-    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    onEvent?.({ kind: "error", text: `Discovery error: ${message}` });
+    throw err;
   }
 }
 
@@ -3238,11 +3429,40 @@ function checkPrerequisites() {
     process.stderr.write("\u2713 Eingeloggt via claude login (Subscription)\n");
   }
 }
+
+// src/logger.ts
+var verboseMode = false;
+function setVerbose(v) {
+  verboseMode = v;
+}
+function log(level, message, context) {
+  if (level === "DEBUG" && !verboseMode) return;
+  const entry = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message,
+    ...context && Object.keys(context).length > 0 ? { context } : {}
+  };
+  process.stderr.write(JSON.stringify(entry) + "\n");
+}
+function logDebug(message, context) {
+  log("DEBUG", message, context);
+}
+function logInfo(message, context) {
+  log("INFO", message, context);
+}
+function logWarn(message, context) {
+  log("WARN", message, context);
+}
+function logError(message, context) {
+  log("ERROR", message, context);
+}
 export {
   CartographyDB,
   assignColors,
   buildMapData,
   checkPrerequisites,
+  cleanupTempFiles,
   computeCentroid,
   computeClusterBounds,
   createCartographyTools,
@@ -3264,10 +3484,16 @@ export {
   hexSpiral,
   hexToPixel,
   layoutClusters,
+  log,
+  logDebug,
+  logError,
+  logInfo,
+  logWarn,
   nodesToAssets,
   pixelToHex,
   runDiscovery,
   safetyHook,
+  setVerbose,
   shadeVariant,
   stripSensitive
 };