@kairos-sdk/core 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -46,8 +46,15 @@ __export(index_exports, {
   ProviderError: () => ProviderError,
   ResponseParseError: () => ResponseParseError,
   TelemetryCollector: () => TelemetryCollector,
+  TelemetryReader: () => TelemetryReader,
+  TemplateSyncer: () => TemplateSyncer,
   ValidationError: () => ValidationError,
-  nullLogger: () => nullLogger
+  buildSearchCorpus: () => buildSearchCorpus,
+  clusterWorkflows: () => clusterWorkflows,
+  hybridScore: () => hybridScore,
+  nullLogger: () => nullLogger,
+  rerank: () => rerank,
+  tokenize: () => tokenize
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -71,6 +78,8 @@ var NullLibrary = class {
   }
   async recordDeployment(_id) {
   }
+  async recordOutcome(_id, _outcome) {
+  }
   async get(_id) {
     return null;
   }
@@ -85,6 +94,9 @@ var KairosError = class extends Error {
     super(message);
     this.cause = cause;
     this.name = "KairosError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
   }
   cause;
 };
@@ -107,8 +119,34 @@ var ProviderError = class extends KairosError {
   }
 };
 
+// src/utils/retry.ts
+async function withRetry(fn, maxAttempts, delayMs, shouldRetry) {
+  let lastError;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (attempt > 0) {
+      const jitter = Math.random() * delayMs * 0.5;
+      await new Promise((resolve) => setTimeout(resolve, delayMs * 2 ** (attempt - 1) + jitter));
+    }
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (shouldRetry && !shouldRetry(err)) throw err;
+    }
+  }
+  throw lastError;
+}
+function fetchWithTimeout(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  return fetch(url, { ...init, signal: controller.signal }).finally(() => clearTimeout(timer));
+}
+
 // src/providers/n8n/api-client.ts
 var EXECUTION_LIMIT_CAP = 100;
+var REQUEST_TIMEOUT_MS = 3e4;
+var RETRY_ATTEMPTS = 3;
+var RETRY_DELAY_MS = 1e3;
 var N8nApiClient = class {
   constructor(baseUrl, apiKey, logger) {
     this.baseUrl = baseUrl;
@@ -121,9 +159,21 @@ var N8nApiClient = class {
   async request(method, path, body) {
     const url = `${this.baseUrl.replace(/\/$/, "")}/api/v1${path}`;
     this.logger.debug(`n8n ${method} ${path}`);
+    const isSafe = method === "GET";
+    if (!isSafe) {
+      return this.singleRequest(url, method, path, body);
+    }
+    return withRetry(
+      () => this.singleRequest(url, method, path, body),
+      RETRY_ATTEMPTS,
+      RETRY_DELAY_MS,
+      (err) => err instanceof ProviderError || err instanceof ApiError && err.statusCode === 429
+    );
+  }
+  async singleRequest(url, method, path, body) {
     let response;
     try {
-      response = await fetch(url, {
+      response = await fetchWithTimeout(url, {
         method,
         headers: {
           "X-N8N-API-KEY": this.apiKey,
@@ -131,7 +181,7 @@ var N8nApiClient = class {
           Accept: "application/json"
         },
         ...body !== void 0 ? { body: JSON.stringify(body) } : {}
-      });
+      }, REQUEST_TIMEOUT_MS);
     } catch (err) {
       throw new ProviderError(`Network error calling n8n API: ${path}`, err);
     }
@@ -165,15 +215,24 @@ var N8nApiClient = class {
     return this.request("GET", `/workflows/${id}`);
   }
   async listWorkflows() {
-    const response = await this.request("GET", "/workflows?limit=250");
-    return response.data.map((w) => ({
-      id: w.id,
-      name: w.name,
-      active: w.active,
-      createdAt: w.createdAt,
-      updatedAt: w.updatedAt,
-      ...w.tags !== void 0 ? { tags: w.tags } : {}
-    }));
+    const all = [];
+    let path = "/workflows?limit=250";
+    for (; ; ) {
+      const response = await this.request("GET", path);
+      for (const w of response.data) {
+        all.push({
+          id: w.id,
+          name: w.name,
+          active: w.active,
+          createdAt: w.createdAt,
+          updatedAt: w.updatedAt,
+          ...w.tags !== void 0 ? { tags: w.tags } : {}
+        });
+      }
+      if (!response.nextCursor) break;
+      path = `/workflows?limit=250&cursor=${response.nextCursor}`;
+    }
+    return all;
   }
   async deleteWorkflow(id) {
     await this.request("DELETE", `/workflows/${id}`);
@@ -200,8 +259,17 @@ var N8nApiClient = class {
     return { ...this.mapExecution(response), data: response.data, workflowData: response.workflowData };
   }
   async listTags() {
-    const response = await this.request("GET", "/tags");
-    return response.data.map((t) => ({ id: t.id, name: t.name }));
+    const all = [];
+    let path = "/tags?limit=250";
+    for (; ; ) {
+      const response = await this.request("GET", path);
+      for (const t of response.data) {
+        all.push({ id: t.id, name: t.name });
+      }
+      if (!response.nextCursor) break;
+      path = `/tags?limit=250&cursor=${response.nextCursor}`;
+    }
+    return all;
   }
   async createTag(name) {
     const response = await this.request("POST", "/tags", { name });
@@ -240,7 +308,8 @@ var FORBIDDEN_ON_CREATE = [
   "active",
   "pinData",
   "triggerCount",
-  "shared"
+  "shared",
+  "staticData"
 ];
 var FORBIDDEN_ON_UPDATE = FORBIDDEN_ON_CREATE.filter((f) => f !== "id");
 
@@ -399,6 +468,8 @@ var DEFAULT_REGISTRY = [
   { type: "@n8n/n8n-nodes-langchain.agent", safeTypeVersions: [1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9], requiredParams: [] },
   { type: "@n8n/n8n-nodes-langchain.chainLlm", safeTypeVersions: [1, 1.1, 1.2, 1.3, 1.4, 1.5], requiredParams: [] },
   { type: "@n8n/n8n-nodes-langchain.chainRetrievalQa", safeTypeVersions: [1, 1.1, 1.2, 1.3, 1.4], requiredParams: [] },
+  { type: "@n8n/n8n-nodes-langchain.openAi", safeTypeVersions: [1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8], requiredParams: [], credentialType: "openAiApi" },
+  { type: "@n8n/n8n-nodes-langchain.anthropic", safeTypeVersions: [1], requiredParams: [], credentialType: "anthropicApi" },
   { type: "@n8n/n8n-nodes-langchain.informationExtractor", safeTypeVersions: [1], requiredParams: [] },
   { type: "@n8n/n8n-nodes-langchain.textClassifier", safeTypeVersions: [1], requiredParams: [] },
   // AI / LangChain sub-nodes (models)
@@ -409,7 +480,8 @@ var DEFAULT_REGISTRY = [
   { type: "@n8n/n8n-nodes-langchain.memoryBufferWindow", safeTypeVersions: [1, 1.1, 1.2, 1.3], requiredParams: [] },
   { type: "@n8n/n8n-nodes-langchain.toolWorkflow", safeTypeVersions: [1, 1.1, 1.2, 1.3], requiredParams: [] },
   { type: "@n8n/n8n-nodes-langchain.toolCode", safeTypeVersions: [1, 1.1], requiredParams: [] },
-  { type: "@n8n/n8n-nodes-langchain.toolHttpRequest", safeTypeVersions: [1, 1.1], requiredParams: [] }
+  { type: "@n8n/n8n-nodes-langchain.toolHttpRequest", safeTypeVersions: [1, 1.1], requiredParams: [] },
+  { type: "@n8n/n8n-nodes-langchain.toolCalculator", safeTypeVersions: [1], requiredParams: [] }
 ];
 var NodeRegistry = class {
   byType;
@@ -422,11 +494,17 @@ var NodeRegistry = class {
   isTrigger(type) {
     return this.byType.get(type)?.isTrigger === true;
   }
+  isKnown(type) {
+    return this.byType.has(type);
+  }
   isVersionSafe(type, version) {
     const def = this.byType.get(type);
     if (!def) return true;
     return def.safeTypeVersions.includes(version);
   }
+  getRequiredParams(type) {
+    return this.byType.get(type)?.requiredParams ?? [];
+  }
 };
 
 // src/validation/validator.ts
@@ -442,7 +520,7 @@ var AI_CONNECTION_TYPES = [
   "ai_vectorStore"
 ];
 var TRIGGER_TYPE_PATTERNS = [/trigger/i, /Trigger$/];
-var NODE_TYPE_PATTERN = /^(@[a-z0-9-]+\/[a-z0-9-]+\.|n8n-nodes-[a-z0-9-]+\.)[a-zA-Z][a-zA-Z0-9]+$/;
+var NODE_TYPE_PATTERN = /^(@[a-z0-9-]+\/[a-z0-9-]+\.|n8n-nodes-[a-z0-9-]+\.)[a-zA-Z][a-zA-Z0-9-]+$/;
 var N8nValidator = class {
   registry;
   constructor(registry = new NodeRegistry(DEFAULT_REGISTRY)) {
@@ -469,6 +547,10 @@ var N8nValidator = class {
     this.checkRule17(workflow, issues);
     this.checkRule18(workflow, issues);
     this.checkRule19(workflow, issues);
+    this.checkRule20(workflow, issues);
+    this.checkRule21(workflow, issues);
+    this.checkRule22(workflow, issues);
+    this.checkRule23(workflow, issues);
     const errors = issues.filter((i) => i.severity === "error");
     return { valid: errors.length === 0, issues };
   }
@@ -604,6 +686,7 @@ var N8nValidator = class {
       }
     }
     for (const node of w.nodes) {
+      if (node.type.includes("stickyNote")) continue;
       if (!this.isTriggerNode(node) && !reachable.has(node.name)) {
         this.warn(issues, 11, `Node "${node.name}" has no incoming connections and may never execute`, node.id);
       }
@@ -673,7 +756,7 @@ var N8nValidator = class {
       }
     }
   }
-  // Rule 18 (WARN): AI connections originate from sub-nodes, not the agent/chain root
+  // Rule 18 (ERROR): AI connections must originate from sub-nodes, not the agent/chain root
   checkRule18(w, issues) {
     if (typeof w.connections !== "object" || w.connections === null) return;
     const agentTypes = /* @__PURE__ */ new Set([
@@ -691,7 +774,7 @@ var N8nValidator = class {
       if (typeof outputs !== "object" || outputs === null) continue;
       for (const connType of AI_CONNECTION_TYPES) {
         if (connType in outputs) {
-          this.warn(
+          this.err(
             issues,
             18,
             `Node "${sourceName}" uses AI connection type "${connType}" as a SOURCE \u2014 AI sub-nodes should be the source, not the agent/chain root`,
@@ -716,6 +799,111 @@ var N8nValidator = class {
       }
     }
   }
+  // Rule 20 (WARN): cycle detection — no node should be reachable from itself
+  // Exempts splitInBatches loops which are an intentional n8n pattern
+  checkRule20(w, issues) {
+    if (!Array.isArray(w.nodes) || typeof w.connections !== "object" || w.connections === null) return;
+    const splitBatchNodes = new Set(
+      w.nodes.filter((n) => n.type.includes("splitInBatches")).map((n) => n.name)
+    );
+    const adj = /* @__PURE__ */ new Map();
+    for (const [sourceName, outputs] of Object.entries(w.connections)) {
+      if (typeof outputs !== "object" || outputs === null) continue;
+      const targets = [];
+      for (const portGroup of Object.values(outputs)) {
+        if (!Array.isArray(portGroup)) continue;
+        for (const conns of portGroup) {
+          if (!Array.isArray(conns)) continue;
+          for (const conn of conns) {
+            const t = conn;
+            if (typeof t?.node === "string") {
+              if (splitBatchNodes.has(t.node)) continue;
+              targets.push(t.node);
+            }
+          }
+        }
+      }
+      adj.set(sourceName, targets);
+    }
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = /* @__PURE__ */ new Map();
+    for (const node of w.nodes) color.set(node.name, WHITE);
+    const dfs = (name) => {
+      color.set(name, GRAY);
+      for (const neighbor of adj.get(name) ?? []) {
+        const c = color.get(neighbor);
+        if (c === GRAY) return true;
+        if (c === WHITE && dfs(neighbor)) return true;
+      }
+      color.set(name, BLACK);
+      return false;
+    };
+    for (const node of w.nodes) {
+      if (color.get(node.name) === WHITE && dfs(node.name)) {
+        this.warn(issues, 20, "Workflow contains a connection cycle \u2014 this may cause infinite loops");
+        return;
+      }
+    }
+  }
+  // Rule 22 (WARN): check requiredParams from registry
+  checkRule22(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (typeof node.type !== "string") continue;
+      const required = this.registry.getRequiredParams(node.type);
+      if (required.length === 0) continue;
+      const params = node.parameters ?? {};
+      for (const param of required) {
+        const value = params[param];
+        if (value === void 0 || value === null || value === "") {
+          this.warn(
+            issues,
+            22,
+            `Node "${node.name}" (${node.type}) is missing required parameter "${param}"`,
+            node.id
+          );
+        }
+      }
+    }
+  }
+  // Rule 23 (WARN): unknown node types not in registry
+  checkRule23(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (typeof node.type !== "string") continue;
+      if (node.type.includes("stickyNote")) continue;
+      if (!NODE_TYPE_PATTERN.test(node.type)) continue;
+      if (!this.registry.isKnown(node.type)) {
+        this.warn(
+          issues,
+          23,
+          `Node "${node.name}" uses unknown type "${node.type}" \u2014 it may not exist in n8n`,
+          node.id
+        );
+      }
+    }
+  }
+  // Rule 21 (WARN): webhook with responseMode="responseNode" must have respondToWebhook node
+  checkRule21(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const webhooksNeedingResponse = w.nodes.filter((n) => {
+      if (!n.type.includes("webhook")) return false;
+      const params = n.parameters;
+      return params?.responseMode === "responseNode";
+    });
+    if (webhooksNeedingResponse.length === 0) return;
+    const hasRespondNode = w.nodes.some((n) => n.type.includes("respondToWebhook"));
+    if (!hasRespondNode) {
+      for (const wh of webhooksNeedingResponse) {
+        this.warn(
+          issues,
+          21,
+          `Webhook "${wh.name}" uses responseMode "responseNode" but no respondToWebhook node exists in the workflow`,
+          wh.id
+        );
+      }
+    }
+  }
 };
 
 // src/errors/generation-error.ts
@@ -763,7 +951,7 @@ id, active, createdAt, updatedAt, versionId, meta, isArchived, activeVersionId,
     "saveDataErrorExecution": "all",
     "saveDataSuccessExecution": "all",
     "executionTimeout": 3600,
-    "timezone": "America/New_York",
+    "timezone": "UTC",
     "executionOrder": "v1"
   }
 }
@@ -805,9 +993,21 @@ Every AI Agent must have at least one ai_languageModel sub-node connected.
 ### IF node \u2014 two output ports (0 = true, 1 = false):
 "IF Check": { "main": [ [{ "node": "True Path", "type": "main", "index": 0 }], [{ "node": "False Path", "type": "main", "index": 0 }] ] }
 
+### SplitInBatches \u2014 two output ports (0 = done/finished, 1 = loop body per batch):
+Connect output 0 to the node that runs AFTER all batches complete.
+Connect output 1 to the processing chain for each batch. The last node in the chain loops back to SplitInBatches via main input.
+
+### Webhook + RespondToWebhook pattern:
+When webhook responseMode is "responseNode", you MUST include a respondToWebhook node in the flow.
+"Webhook": { "main": [[{ "node": "Process Data", "type": "main", "index": 0 }]] }
+"Process Data": { "main": [[{ "node": "Respond to Webhook", "type": "main", "index": 0 }]] }
+
 ### Triggers have no incoming connections.
 ### Connection keys are NODE NAMES, never node IDs.
 
+### Nested parameters:
+Node parameters like conditions, assignments, and rule intervals MUST include all required nested fields. Do not leave nested objects empty or partially filled.
+
 ---
 
 ## NODE CATALOG \u2014 exact type strings and safe typeVersions
@@ -871,16 +1071,16 @@ n8n-nodes-base.redis                  typeVersion: 1       \u2014 cred: redis
 n8n-nodes-base.supabase               typeVersion: 1       \u2014 cred: supabaseApi
 n8n-nodes-base.awsS3                  typeVersion: 2       \u2014 cred: aws
 
-### AI \u2014 Root nodes (sit on main data flow):
+### AI \u2014 Root nodes (sit on main data flow, receive ai_* connections as TARGETS):
 @n8n/n8n-nodes-langchain.agent        typeVersion: 1.9     \u2014 params: promptType, text (if define), options.systemMessage
 @n8n/n8n-nodes-langchain.chainLlm     typeVersion: 1.5
 @n8n/n8n-nodes-langchain.chainRetrievalQa typeVersion: 1.4
-@n8n/n8n-nodes-langchain.openAi       typeVersion: 1.8     \u2014 cred: openAiApi
-@n8n/n8n-nodes-langchain.anthropic    typeVersion: 1       \u2014 cred: anthropicApi
+@n8n/n8n-nodes-langchain.openAi       typeVersion: 1.8     \u2014 cred: openAiApi \u2014 standalone node, calls OpenAI directly without sub-nodes
+@n8n/n8n-nodes-langchain.anthropic    typeVersion: 1       \u2014 cred: anthropicApi \u2014 standalone node, calls Anthropic directly without sub-nodes
 
-### AI \u2014 Sub-nodes (sources of ai_* connections):
-@n8n/n8n-nodes-langchain.lmChatOpenAi      typeVersion: 1.7  \u2014 cred: openAiApi       \u2014 ai_languageModel
-@n8n/n8n-nodes-langchain.lmChatAnthropic   typeVersion: 1.3  \u2014 cred: anthropicApi    \u2014 ai_languageModel
+### AI \u2014 Sub-nodes (sources of ai_* connections, wire INTO root nodes above):
+@n8n/n8n-nodes-langchain.lmChatOpenAi      typeVersion: 1.7  \u2014 cred: openAiApi       \u2014 ai_languageModel \u2014 use with agent/chain, NOT standalone
+@n8n/n8n-nodes-langchain.lmChatAnthropic   typeVersion: 1.3  \u2014 cred: anthropicApi    \u2014 ai_languageModel \u2014 use with agent/chain, NOT standalone
 @n8n/n8n-nodes-langchain.lmChatGoogleGemini typeVersion: 1   \u2014 cred: googlePalmApi   \u2014 ai_languageModel
 @n8n/n8n-nodes-langchain.memoryBufferWindow typeVersion: 1.3  \u2014                       \u2014 ai_memory
 @n8n/n8n-nodes-langchain.toolWorkflow      typeVersion: 2     \u2014                       \u2014 ai_tool
@@ -915,11 +1115,42 @@ Cron: { "rule": { "interval": [{ "field": "cronExpression", "expression": "0 9 *
 Respond ONLY with a generate_workflow tool call. No prose. No markdown outside the tool call.
 If the request is impossible or unclear, set the error field instead of generating a workflow.`;
 
+// src/utils/thresholds.ts
+var DIRECT_THRESHOLD = 0.92;
+var REFERENCE_THRESHOLD = 0.72;
+function scoreToMode(score) {
+  if (score >= DIRECT_THRESHOLD) return "direct";
+  if (score >= REFERENCE_THRESHOLD) return "reference";
+  return "scratch";
+}
+
 // src/generation/prompt-builder.ts
+var RULE_REMEDIES = {
+  1: "Provide a non-empty workflow name string",
+  2: "Include at least one node in the nodes array",
+  3: "Every node must have a unique UUID v4 string as its id field",
+  4: "Ensure all node ids are unique \u2014 no two nodes can share the same id",
+  5: "Every node must have a non-empty type string",
+  6: "Every node must have a positive integer typeVersion",
+  7: "Every node must have a position array of exactly [x, y] numbers",
+  8: "Every node must have a non-empty name string",
+  9: "connections must be a plain object (use {} if no connections)",
+  10: "Every node name in connections (source and target) must exactly match a name in the nodes array",
+  12: "Remove forbidden fields: id, active, createdAt, updatedAt, versionId, meta, tags \u2014 these are server-assigned",
+  14: "Include at least one trigger node (e.g. webhook, scheduleTrigger, manualTrigger)",
+  15: 'Node type strings must be fully qualified: "n8n-nodes-base.httpRequest" not just "httpRequest"',
+  16: "All node names must be unique within the workflow",
+  17: 'Credentials must be an object with non-empty string id and name fields: { id: "placeholder-id", name: "My Credential" }',
+  18: "AI sub-nodes (languageModel, memory, tool) must be the CONNECTION SOURCE pointing TO the agent \u2014 not the reverse",
+  19: "Use known safe typeVersion values for each node type",
+  20: "Remove connection cycles \u2014 ensure no node can reach itself through the connection graph",
+  21: 'When using webhook with responseMode "responseNode", include a respondToWebhook node in the flow',
+  22: "Ensure all required parameters are set for each node type (e.g. webhook needs httpMethod and path)"
+};
 var PromptBuilder = class {
-  build(request, matches) {
+  build(request, matches, globalFailureRates = []) {
     const mode = this.resolveMode(matches);
-    const system = this.buildSystem(matches, mode);
+    const system = this.buildSystem(matches, mode, globalFailureRates);
     const userMessage = this.buildUserMessage(request, matches, mode);
     return { system, userMessage, mode, matches };
   }
@@ -936,11 +1167,9 @@ Fix ALL of the above issues in your new response. Do not repeat any of these mis
     if (matches.length === 0) return "scratch";
     const top = matches[0];
     if (!top) return "scratch";
-    if (top.score >= 0.92) return "direct";
-    if (top.score >= 0.72) return "reference";
-    return "scratch";
+    return scoreToMode(top.score);
   }
-  buildSystem(matches, mode) {
+  buildSystem(matches, mode, globalFailureRates = []) {
     const blocks = [
       {
         type: "text",
@@ -964,15 +1193,63 @@ ${refText}`
     }
     if (mode === "direct" && matches[0]) {
       const match = matches[0];
+      const json = JSON.stringify(match.workflow.workflow, null, 2);
+      if (json.length > 3e4) {
+        const nodes = match.workflow.workflow.nodes.map((n) => `  - ${n.name} (${n.type} v${n.typeVersion})`).join("\n");
+        blocks.push({
+          type: "text",
+          text: `## Closely Matched Workflow (score: ${match.score.toFixed(2)}) \u2014 too large for full JSON, using reference:
+Nodes:
+${nodes}`
+        });
+      } else {
+        blocks.push({
+          type: "text",
+          text: `## Closely Matched Workflow (score: ${match.score.toFixed(2)}) \u2014 adapt this structure:
+
+${json}`
+        });
+      }
+    }
+    if (mode === "scratch" && matches.length > 0 && matches[0].score >= 0.4) {
+      const hint = matches[0];
+      const nodeTypes = hint.workflow.workflow.nodes.map((n) => n.type.split(".").pop()).join(", ");
       blocks.push({
         type: "text",
-        text: `## Closely Matched Workflow (score: ${match.score.toFixed(2)}) \u2014 adapt this structure:
-
-${JSON.stringify(match.workflow.workflow, null, 2)}`
+        text: `## Weak Structural Hint
+A loosely similar workflow (score: ${hint.score.toFixed(2)}) used these node types: ${nodeTypes}`
       });
     }
+    const warnings = this.buildFailureWarnings(matches, globalFailureRates);
+    if (warnings) {
+      blocks.push({ type: "text", text: warnings });
+    }
     return blocks;
   }
+  buildFailureWarnings(matches, globalFailureRates) {
+    const lines = [];
+    for (const match of matches) {
+      const patterns = match.workflow.failurePatterns;
+      if (!patterns?.length) continue;
+      for (const fp of patterns) {
+        const remedy = RULE_REMEDIES[fp.rule];
+        const remedyStr = remedy ? ` \u2014 Fix: ${remedy}` : "";
+        lines.push(`- Rule ${fp.rule}: "${fp.message}"${remedyStr} (seen ${fp.occurrences}x in similar workflows)`);
+      }
+    }
+    const highFreqRules = globalFailureRates.filter((r) => r.rate >= 0.15);
+    for (const rule of highFreqRules) {
+      const remedy = RULE_REMEDIES[rule.rule];
+      const remedyStr = remedy ? ` \u2014 Fix: ${remedy}` : "";
+      lines.push(`- Rule ${rule.rule}: "${rule.commonMessage}"${remedyStr} (fails in ${Math.round(rule.rate * 100)}% of all builds)`);
+    }
+    if (lines.length === 0) return null;
+    const unique = [...new Set(lines)];
+    return `## Known Failure Patterns \u2014 AVOID THESE
+
+Previous builds frequently failed the following validation rules. Ensure your output does NOT repeat these mistakes:
+${unique.join("\n")}`;
+  }
   buildUserMessage(request, _matches, _mode) {
     const namePart = request.name ? `
 Workflow name: "${request.name}"` : "";
@@ -1019,7 +1296,7 @@ var GENERATE_WORKFLOW_TOOL = {
         description: "Set this if the request cannot be fulfilled \u2014 explain why"
       }
     },
-    required: ["workflow"]
+    required: []
   }
 };
 var WorkflowDesigner = class {
@@ -1035,24 +1312,24 @@ var WorkflowDesigner = class {
   logger;
   validator;
   promptBuilder;
-  async design(request, matches) {
-    const allIssues = [];
+  async design(request, matches, globalFailureRates = []) {
     const attemptMetadata = [];
+    let lastErrors = [];
     let attempts = 0;
+    const built = this.promptBuilder.build(request, matches, globalFailureRates);
     for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
       attempts = attempt;
       const temperature = attempt === MAX_ATTEMPTS ? FINAL_TEMPERATURE : BASE_TEMPERATURE;
-      const built = this.promptBuilder.build(request, matches);
       let userMessage;
       if (attempt === 1) {
         userMessage = built.userMessage;
         this.logger.debug("WorkflowDesigner: attempt 1", { description: request.description });
       } else {
-        const issueLines = allIssues.map(
+        const issueLines = lastErrors.map(
           (i) => `- [Rule ${i.rule}] ${i.message}${i.nodeId ? ` (node: ${i.nodeId})` : ""}`
         );
         userMessage = this.promptBuilder.buildCorrectionMessage(request, matches, issueLines, attempt - 1);
-        this.logger.debug(`WorkflowDesigner: correction attempt ${attempt}`, { issueCount: allIssues.length });
+        this.logger.debug(`WorkflowDesigner: correction attempt ${attempt}`, { issueCount: lastErrors.length });
       }
       const start = Date.now();
       const message = await this.callClaude(built.system, userMessage, temperature);
@@ -1070,35 +1347,43 @@ var WorkflowDesigner = class {
         tokensInput: message.usage.input_tokens,
         tokensOutput: message.usage.output_tokens,
         validationPassed: validation.valid,
-        issues: errors
+        issues: validation.issues
       });
       if (validation.valid) {
         return { workflow: parsed.workflow, credentialsNeeded: parsed.credentialsNeeded, attempts, attemptMetadata };
       }
-      allIssues.push(...errors);
+      lastErrors = errors;
       this.logger.warn(`WorkflowDesigner: validation failed on attempt ${attempt}`, {
-        newErrors: errors.length,
-        totalErrors: allIssues.length
+        errorCount: errors.length
       });
     }
+    const finalIssues = attemptMetadata.at(-1)?.issues ?? lastErrors;
     throw new ValidationError(
-      `Workflow failed validation after ${MAX_ATTEMPTS} attempts (${allIssues.length} total errors)`,
-      allIssues
+      `Workflow failed validation after ${MAX_ATTEMPTS} attempts`,
+      finalIssues
     );
   }
   async callClaude(system, userMessage, temperature) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 12e4);
     try {
-      return await this.anthropic.messages.create({
-        model: this.model,
-        max_tokens: 8192,
-        temperature,
-        system,
-        messages: [{ role: "user", content: userMessage }],
-        tools: [GENERATE_WORKFLOW_TOOL],
-        tool_choice: { type: "tool", name: "generate_workflow" }
-      });
+      return await this.anthropic.messages.create(
+        {
+          model: this.model,
+          max_tokens: 8192,
+          temperature,
+          system: system.map((b) => ({ type: b.type, text: b.text, ...b.cache_control ? { cache_control: b.cache_control } : {} })),
+          messages: [{ role: "user", content: userMessage }],
+          tools: [GENERATE_WORKFLOW_TOOL],
+          tool_choice: { type: "tool", name: "generate_workflow" }
+        },
+        { signal: controller.signal }
+      );
     } catch (err) {
-      throw new GenerationError("Anthropic API call failed", err);
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new GenerationError(`Anthropic API call failed: ${detail}`, err);
+    } finally {
+      clearTimeout(timer);
     }
   }
   extractToolUse(message) {
@@ -1131,27 +1416,125 @@ var WorkflowDesigner = class {
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
 var import_node_os = require("os");
+
+// src/telemetry/types.ts
+var TELEMETRY_SCHEMA_VERSION = 2;
+
+// src/telemetry/collector.ts
 var TelemetryCollector = class {
   dir;
   sessionId;
+  dirReady = null;
   constructor(dir) {
     this.dir = dir ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".kairos", "telemetry");
     this.sessionId = generateUUID();
   }
   async emit(eventType, data) {
     const event = {
+      schemaVersion: TELEMETRY_SCHEMA_VERSION,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       sessionId: this.sessionId,
       eventType,
       data
     };
-    await (0, import_promises.mkdir)(this.dir, { recursive: true });
+    if (!this.dirReady) {
+      this.dirReady = (0, import_promises.mkdir)(this.dir, { recursive: true }).then(() => {
+      });
+    }
+    await this.dirReady;
     const filename = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10) + ".jsonl";
     const filepath = (0, import_node_path.join)(this.dir, filename);
     await (0, import_promises.appendFile)(filepath, JSON.stringify(event) + "\n", "utf-8");
   }
 };
 
+// src/telemetry/reader.ts
+var import_promises2 = require("fs/promises");
+var import_node_path2 = require("path");
+var import_node_os2 = require("os");
+var TelemetryReader = class {
+  dir;
+  cache = null;
+  cacheTime = 0;
+  constructor(dir) {
+    this.dir = dir ?? (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".kairos", "telemetry");
+  }
+  async getFailureRates(days = 30) {
+    const now = Date.now();
+    if (this.cache && now - this.cacheTime < 5 * 60 * 1e3) {
+      return this.cache;
+    }
+    const events = await this.readRecentEvents(days);
+    const buildSessions = new Set(
+      events.filter((e) => e.eventType === "build_complete" && !e.data.dryRun).map((e) => e.sessionId)
+    );
+    if (buildSessions.size === 0) return [];
+    const ruleSessions = /* @__PURE__ */ new Map();
+    for (const event of events) {
+      if (event.eventType !== "generation_attempt") continue;
+      if (!buildSessions.has(event.sessionId)) continue;
+      const data = event.data;
+      if (data.validationPassed || !data.issues) continue;
+      for (const issue of data.issues) {
+        const entry = ruleSessions.get(issue.rule) ?? { sessions: /* @__PURE__ */ new Set(), messages: /* @__PURE__ */ new Map() };
+        entry.sessions.add(event.sessionId);
+        entry.messages.set(issue.message, (entry.messages.get(issue.message) ?? 0) + 1);
+        ruleSessions.set(issue.rule, entry);
+      }
+    }
+    const rates = [];
+    for (const [rule, entry] of ruleSessions) {
+      let topMessage = "";
+      let topCount = 0;
+      for (const [msg, count] of entry.messages) {
+        if (count > topCount) {
+          topMessage = msg;
+          topCount = count;
+        }
+      }
+      rates.push({
+        rule,
+        failureCount: entry.sessions.size,
+        totalBuilds: buildSessions.size,
+        rate: entry.sessions.size / buildSessions.size,
+        commonMessage: topMessage
+      });
+    }
+    rates.sort((a, b) => b.rate - a.rate);
+    this.cache = rates;
+    this.cacheTime = now;
+    return rates;
+  }
+  async readRecentEvents(days) {
+    let files;
+    try {
+      files = await (0, import_promises2.readdir)(this.dir);
+    } catch {
+      return [];
+    }
+    const cutoff = /* @__PURE__ */ new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+    const cutoffStr = cutoff.toISOString().slice(0, 10);
+    const datePattern = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+    const recentFiles = files.filter((f) => datePattern.test(f) && f >= cutoffStr).sort();
+    const events = [];
+    for (const file of recentFiles) {
+      try {
+        const content = await (0, import_promises2.readFile)((0, import_node_path2.join)(this.dir, file), "utf-8");
+        for (const line of content.split("\n")) {
+          if (!line.trim()) continue;
+          try {
+            events.push(JSON.parse(line));
+          } catch {
+          }
+        }
+      } catch {
+      }
+    }
+    return events;
+  }
+};
+
 // src/utils/logger.ts
 var nullLogger = {
   debug() {
@@ -1173,27 +1556,53 @@ var Kairos = class {
   library;
   logger;
   telemetry;
+  telemetryReader;
   model;
+  saveQueue = Promise.resolve(null);
   constructor(options) {
     const logger = options.logger ?? nullLogger;
     this.model = options.model ?? DEFAULT_MODEL;
+    if (options.n8nBaseUrl && options.n8nApiKey) {
+      try {
+        new URL(options.n8nBaseUrl);
+      } catch {
+        throw new GuardError(`Invalid n8nBaseUrl: "${options.n8nBaseUrl}" \u2014 must be a valid URL`);
+      }
+      const apiClient = new N8nApiClient(options.n8nBaseUrl, options.n8nApiKey, logger);
+      const stripper = new N8nFieldStripper();
+      this.provider = new N8nProvider(apiClient, stripper);
+    } else {
+      this.provider = null;
+    }
     const anthropic = new import_sdk.default({ apiKey: options.anthropicApiKey });
-    const apiClient = new N8nApiClient(options.n8nBaseUrl, options.n8nApiKey, logger);
-    const stripper = new N8nFieldStripper();
-    this.provider = new N8nProvider(apiClient, stripper);
     this.designer = new WorkflowDesigner(anthropic, this.model, logger);
     this.validator = new N8nValidator();
     this.library = options.library ?? new NullLibrary();
     this.logger = logger;
     if (options.telemetry === true) {
       this.telemetry = new TelemetryCollector();
+      this.telemetryReader = new TelemetryReader();
     } else if (typeof options.telemetry === "string") {
       this.telemetry = new TelemetryCollector(options.telemetry);
+      this.telemetryReader = new TelemetryReader(options.telemetry);
     } else {
       this.telemetry = null;
+      this.telemetryReader = null;
+    }
+  }
+  requireProvider() {
+    if (!this.provider) {
+      throw new GuardError("n8nBaseUrl and n8nApiKey are required for this operation \u2014 set them in the Kairos constructor, or use { dryRun: true } for generation-only mode");
+    }
+    return this.provider;
+  }
+  validateDescription(description) {
+    if (!description || description.trim().length === 0) {
+      throw new GuardError("Description is required and must be non-empty");
     }
   }
   async build(description, options) {
+    this.validateDescription(description);
     this.logger.info("Kairos.build", { description, dryRun: options?.dryRun });
     const buildStart = Date.now();
     await this.telemetry?.emit("build_start", {
@@ -1203,33 +1612,28 @@ var Kairos = class {
     });
     await this.library.initialize();
     const matches = await this.library.search(description);
+    if (matches.length > 0) {
+      const top = matches[0];
+      this.logger.info(`Library: ${matches.length} match(es), top="${top.workflow.description.slice(0, 50)}" score=${top.score.toFixed(2)} mode=${top.mode}`);
+    } else {
+      this.logger.info("Library: no matches (scratch mode)");
+    }
+    const globalFailureRates = await this.telemetryReader?.getFailureRates() ?? [];
+    if (globalFailureRates.length > 0) {
+      const highFreq = globalFailureRates.filter((r) => r.rate >= 0.15);
+      if (highFreq.length > 0) {
+        this.logger.info(`Telemetry: ${highFreq.length} high-frequency failure rule(s) will be warned about`);
+      }
+    }
     const designResult = await this.designer.design(
       { description, ...options?.name ? { name: options.name } : {} },
-      matches
+      matches,
+      globalFailureRates
     );
-    for (const meta of designResult.attemptMetadata) {
-      await this.telemetry?.emit("generation_attempt", {
-        description,
-        attempt: meta.attempt,
-        temperature: meta.temperature,
-        durationMs: meta.durationMs,
-        tokensInput: meta.tokensInput,
-        tokensOutput: meta.tokensOutput,
-        validationPassed: meta.validationPassed,
-        issueCount: meta.issues.length,
-        issues: meta.issues.map((i) => ({ rule: i.rule, message: i.message }))
-      });
-    }
+    await this.emitAttemptTelemetry(description, designResult);
     const workflow = options?.name ? { ...designResult.workflow, name: options.name } : designResult.workflow;
+    this.saveToLibrary(workflow, description, designResult, matches);
     if (options?.dryRun) {
-      const result2 = {
-        workflowId: null,
-        name: workflow.name,
-        credentialsNeeded: designResult.credentialsNeeded,
-        activationRequired: true,
-        generationAttempts: designResult.attempts,
-        dryRun: true
-      };
       const totalTokensInput2 = designResult.attemptMetadata.reduce((s, m) => s + m.tokensInput, 0);
       const totalTokensOutput2 = designResult.attemptMetadata.reduce((s, m) => s + m.tokensOutput, 0);
       await this.telemetry?.emit("build_complete", {
@@ -1244,23 +1648,64 @@ var Kairos = class {
         dryRun: true,
         credentialsNeeded: designResult.credentialsNeeded.length
       });
-      return result2;
+      return {
+        workflowId: null,
+        name: workflow.name,
+        workflow,
+        credentialsNeeded: designResult.credentialsNeeded,
+        activationRequired: true,
+        generationAttempts: designResult.attempts,
+        dryRun: true
+      };
     }
-    const deployed = await this.provider.deploy(workflow);
-    this.library.save(workflow, { description }).catch((err) => {
-      this.logger.warn("Failed to save workflow to library (non-fatal)", { err: String(err) });
-    });
+    const provider = this.requireProvider();
+    const deployed = await provider.deploy(workflow);
+    this.recordDeploy();
     if (options?.activate) {
-      await this.provider.activate(deployed.workflowId);
+      await provider.activate(deployed.workflowId);
     }
-    const result = {
+    const totalTokensInput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensInput, 0);
+    const totalTokensOutput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensOutput, 0);
+    await this.telemetry?.emit("build_complete", {
+      description,
+      success: true,
+      totalAttempts: designResult.attempts,
+      totalDurationMs: Date.now() - buildStart,
+      totalTokensInput,
+      totalTokensOutput,
+      workflowName: deployed.name,
+      workflowId: deployed.workflowId,
+      dryRun: false,
+      credentialsNeeded: designResult.credentialsNeeded.length
+    });
+    return {
       workflowId: deployed.workflowId,
       name: deployed.name,
+      workflow,
       credentialsNeeded: designResult.credentialsNeeded,
       activationRequired: !options?.activate,
       generationAttempts: designResult.attempts,
       dryRun: false
     };
+  }
+  async replace(id, description) {
+    this.validateDescription(description);
+    this.logger.info("Kairos.update", { id, description });
+    const buildStart = Date.now();
+    await this.telemetry?.emit("build_start", {
+      description,
+      model: this.model,
+      dryRun: false
+    });
+    await this.library.initialize();
+    const matches = await this.library.search(description);
+    const globalFailureRates = await this.telemetryReader?.getFailureRates() ?? [];
+    const designResult = await this.designer.design({ description }, matches, globalFailureRates);
+    await this.emitAttemptTelemetry(description, designResult);
+    const provider = this.requireProvider();
+    const deployed = await provider.update(id, designResult.workflow);
+    this.saveToLibrary(designResult.workflow, description, designResult, matches);
+    this.recordDeploy();
     const totalTokensInput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensInput, 0);
     const totalTokensOutput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensOutput, 0);
     await this.telemetry?.emit("build_complete", {
@@ -1275,134 +1720,449 @@ var Kairos = class {
       dryRun: false,
       credentialsNeeded: designResult.credentialsNeeded.length
     });
-    return result;
-  }
-  async update(id, description) {
-    this.logger.info("Kairos.update", { id, description });
-    const matches = await this.library.search(description);
-    const designResult = await this.designer.design({ description }, matches);
-    const deployed = await this.provider.update(id, designResult.workflow);
     return {
       workflowId: deployed.workflowId,
       name: deployed.name,
+      workflow: designResult.workflow,
       credentialsNeeded: designResult.credentialsNeeded,
       activationRequired: true,
       generationAttempts: designResult.attempts,
       dryRun: false
     };
   }
+  async drain() {
+    await this.saveQueue.catch(() => {
+    });
+  }
+  async emitAttemptTelemetry(description, designResult) {
+    for (const meta of designResult.attemptMetadata) {
+      await this.telemetry?.emit("generation_attempt", {
+        description,
+        attempt: meta.attempt,
+        temperature: meta.temperature,
+        durationMs: meta.durationMs,
+        tokensInput: meta.tokensInput,
+        tokensOutput: meta.tokensOutput,
+        validationPassed: meta.validationPassed,
+        issueCount: meta.issues.length,
+        issues: meta.issues.map((i) => ({ rule: i.rule, message: i.message }))
+      });
+    }
+  }
+  recordDeploy() {
+    this.saveQueue = this.saveQueue.then(async (savedId) => {
+      if (savedId) {
+        await this.library.recordDeployment(savedId);
+      }
+      return savedId;
+    }).catch((err) => {
+      this.logger.warn("Failed to record deployment (non-fatal)", { err: String(err) });
+      return null;
+    });
+  }
+  saveToLibrary(workflow, description, designResult, matches) {
+    const failedAttempts = designResult.attemptMetadata.filter((m) => !m.validationPassed);
+    const failurePatterns = failedAttempts.flatMap(
+      (m) => m.issues.map((i) => ({ rule: i.rule, message: i.message }))
+    );
+    const topMatch = matches[0];
+    const generationMode = topMatch ? scoreToMode(topMatch.score) : "scratch";
+    const autoTags = Array.from(new Set(
+      workflow.nodes.flatMap((n) => {
+        const bare = n.type.split(".").pop() ?? "";
+        const tags = [bare];
+        if (n.type.includes("Trigger") || n.type.includes("trigger")) tags.push(`trigger:${bare}`);
+        if (n.type.includes("langchain")) tags.push("ai");
+        return tags;
+      })
+    ));
+    const metadata = {
+      description,
+      generationMode,
+      generationAttempts: designResult.attempts
+    };
+    if (autoTags.length > 0) metadata.tags = autoTags;
+    if (failurePatterns.length > 0) metadata.failurePatterns = failurePatterns;
+    if (matches.length > 0) metadata.sourceWorkflowIds = matches.map((m) => m.workflow.id);
+    if (topMatch) metadata.topMatchScore = topMatch.score;
+    if (designResult.credentialsNeeded.length > 0) metadata.credentialsNeeded = designResult.credentialsNeeded;
+    const firstTryPass = designResult.attemptMetadata.length > 0 && designResult.attemptMetadata[0].validationPassed;
+    const failedRules = Array.from(new Set(
+      designResult.attemptMetadata.filter((m) => !m.validationPassed).flatMap((m) => m.issues.map((i) => i.rule))
+    ));
+    this.saveQueue = this.saveQueue.then(async () => {
+      const savedId = await this.library.save(workflow, metadata);
+      for (const match of matches) {
+        if (match.mode === "direct" || match.mode === "reference") {
+          await this.library.recordOutcome(match.workflow.id, {
+            attempts: designResult.attempts,
+            firstTryPass,
+            failedRules,
+            mode: match.mode
+          });
+        }
+      }
+      return savedId;
+    }).catch((err) => {
+      this.logger.warn("Failed to save workflow to library (non-fatal)", { err: String(err) });
+      return null;
+    });
+  }
   async get(id) {
-    return this.provider.get(id);
+    return this.requireProvider().get(id);
   }
   async list() {
-    return this.provider.list();
+    return this.requireProvider().list();
   }
   async activate(id) {
-    await this.provider.activate(id);
+    await this.requireProvider().activate(id);
   }
   async deactivate(id) {
-    await this.provider.deactivate(id);
+    await this.requireProvider().deactivate(id);
   }
   async delete(id, options) {
-    await this.provider.delete(id, options);
+    await this.requireProvider().delete(id, options);
   }
   async executions(workflowId, filter) {
-    return this.provider.executions(workflowId, filter);
+    return this.requireProvider().executions(workflowId, filter);
   }
   async execution(id) {
-    return this.provider.execution(id);
+    return this.requireProvider().execution(id);
   }
   async listTags() {
-    return this.provider.listTags();
+    return this.requireProvider().listTags();
   }
   async createTag(name) {
-    return this.provider.createTag(name);
+    return this.requireProvider().createTag(name);
   }
   async tag(workflowId, tagIds) {
-    await this.provider.tag(workflowId, tagIds);
+    await this.requireProvider().tag(workflowId, tagIds);
   }
   async untag(workflowId, tagIds) {
-    await this.provider.untag(workflowId, tagIds);
+    await this.requireProvider().untag(workflowId, tagIds);
   }
 };
 
 // src/library/file-library.ts
-var import_promises2 = require("fs/promises");
-var import_node_path2 = require("path");
-var import_node_os2 = require("os");
+var import_promises3 = require("fs/promises");
+var import_node_path3 = require("path");
+var import_node_os3 = require("os");
+
+// src/library/scorer.ts
+var WEIGHTS = {
+  tfidf: 0.35,
+  nodeFingerprint: 0.3,
+  outcome: 0.2,
+  deploy: 0.15
+};
+var NODE_KEYWORDS = {
+  slack: ["slack", "slackApi"],
+  email: ["gmail", "sendEmail", "emailSend", "emailReadImap"],
+  webhook: ["webhook", "webhookTrigger"],
+  schedule: ["scheduleTrigger", "cron"],
+  http: ["httpRequest"],
+  sheets: ["googleSheets"],
+  github: ["github", "githubTrigger"],
+  telegram: ["telegram", "telegramTrigger"],
+  ai: ["agent", "openAi", "lmChatOpenAi", "lmChatAnthropic", "chainLlm", "chainSummarization"],
+  memory: ["memoryBufferWindow", "memoryXata", "memoryPostgres"],
+  vector: ["vectorStoreInMemory", "vectorStorePinecone", "vectorStoreQdrant"],
+  database: ["postgres", "mySql", "redis", "mongoDb"],
+  airtable: ["airtable"],
+  notion: ["notion"],
+  s3: ["awsS3"],
+  code: ["code"],
+  merge: ["merge"],
+  switch: ["switch"],
+  if: ["if"],
+  wait: ["wait"],
+  rss: ["rssFeedRead", "rssFeedReadTrigger"],
+  form: ["formTrigger"],
+  set: ["set"],
+  split: ["splitInBatches"],
+  filter: ["filter"],
+  telegram_trigger: ["telegramTrigger"],
+  stripe: ["stripe"]
+};
+function extractQueryFingerprint(description) {
+  const lower = description.toLowerCase();
+  const matches = /* @__PURE__ */ new Set();
+  for (const [keyword, nodeTypes] of Object.entries(NODE_KEYWORDS)) {
+    if (lower.includes(keyword)) {
+      for (const nt of nodeTypes) matches.add(nt);
+    }
+  }
+  if (/\bevery\b|\bdaily\b|\bhourly\b|\bweekly\b|\bmonthly\b|\bcron\b|\bschedule\b|\bat \d/.test(lower)) {
+    matches.add("scheduleTrigger");
+  }
+  if (/\bwebhook\b|\breceive\b.*\bpost\b|\bpost\b.*\brequest\b/.test(lower)) {
+    matches.add("webhook");
+  }
+  if (/\bchat\b|\bchatbot\b|\bconversation\b/.test(lower)) {
+    matches.add("chatTrigger");
+  }
+  if (/\bai\b|\bllm\b|\bgpt\b|\bclaude\b|\bagent\b|\bsummariz/.test(lower)) {
+    matches.add("agent");
+  }
+  return matches;
+}
+function extractWorkflowFingerprint(w) {
+  const fp = /* @__PURE__ */ new Set();
+  for (const node of w.workflow.nodes) {
+    const bare = node.type.split(".").pop() ?? "";
+    fp.add(bare);
+  }
+  return fp;
+}
+function jaccardSimilarity(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersection = 0;
+  for (const item of a) {
+    if (b.has(item)) intersection++;
+  }
+  const union = a.size + b.size - intersection;
+  return union > 0 ? intersection / union : 0;
+}
+function outcomeScore(w) {
+  const stats = w.outcomeStats;
+  if (!stats || stats.totalUses === 0) return 0.5;
+  const passRate = stats.firstTryPasses / stats.totalUses;
+  const avgAttempts = stats.totalAttempts / stats.totalUses;
+  const attemptPenalty = Math.max(0, 1 - (avgAttempts - 1) * 0.3);
+  return passRate * 0.6 + attemptPenalty * 0.4;
+}
+function deployScore(w) {
+  return 1 + Math.log(w.deployCount + 1) * 0.1;
+}
+function hybridScore(queryTokens, queryDescription, workflows, docTokenArrays, idf) {
+  const queryFp = extractQueryFingerprint(queryDescription);
+  const ceiling = queryTokens.reduce((sum, qt) => sum + (idf.get(qt) ?? 0), 0) || 1;
+  return workflows.map((w, i) => {
+    const docTokens = docTokenArrays[i];
+    let tfidfRaw = 0;
+    const docFreq = /* @__PURE__ */ new Map();
+    for (const t of docTokens) {
+      docFreq.set(t, (docFreq.get(t) ?? 0) + 1);
+    }
+    for (const qt of queryTokens) {
+      const tf = docTokens.length > 0 ? (docFreq.get(qt) ?? 0) / docTokens.length : 0;
+      const idfVal = idf.get(qt) ?? 0;
+      tfidfRaw += tf * idfVal;
+    }
+    const tfidf = Math.min(tfidfRaw / ceiling, 1);
+    const workflowFp = extractWorkflowFingerprint(w);
+    const nodeFingerprint = queryFp.size > 0 ? jaccardSimilarity(queryFp, workflowFp) : 0;
+    const outcome = outcomeScore(w);
+    const deploy = Math.min(deployScore(w), 1.5) / 1.5;
+    const score = Math.min(
+      WEIGHTS.tfidf * tfidf + WEIGHTS.nodeFingerprint * nodeFingerprint + WEIGHTS.outcome * outcome + WEIGHTS.deploy * deploy,
+      1
+    );
+    return {
+      workflow: w,
+      score,
+      signals: { tfidf, nodeFingerprint, outcome, deploy }
+    };
+  });
+}
+
+// src/library/cluster.ts
+function getFingerprint(w) {
+  return w.workflow.nodes.map((n) => n.type.split(".").pop() ?? "").sort();
+}
+function fingerprintKey(fp) {
+  return fp.join("|");
+}
+function describePattern(fp) {
+  const triggers = fp.filter((n) => /trigger/i.test(n));
+  const outputs = fp.filter((n) => /slack|gmail|email|telegram|sheets|airtable|notion/i.test(n));
+  const ai = fp.filter((n) => /agent|openai|anthropic|chain|memory/i.test(n));
+  const core = fp.filter((n) => /httpRequest|code|merge|switch|if|set|filter/i.test(n));
+  const parts = [];
+  if (triggers.length > 0) parts.push(triggers[0]);
+  if (ai.length > 0) parts.push("AI");
+  if (core.length > 0) parts.push(core.slice(0, 2).join("+"));
+  if (outputs.length > 0) parts.push(outputs[0]);
+  return parts.length > 0 ? parts.join(" \u2192 ") : fp.slice(0, 3).join(" \u2192 ");
+}
+function clusterWorkflows(workflows) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const w of workflows) {
+    const fp = getFingerprint(w);
+    const key = fingerprintKey(fp);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(w);
+    } else {
+      groups.set(key, [w]);
+    }
+  }
+  const clusters = [];
+  for (const [, members] of groups) {
+    if (members.length === 0) continue;
+    const fp = getFingerprint(members[0]);
+    const withStats = members.filter((m) => m.outcomeStats && m.outcomeStats.totalUses > 0);
+    let avgFirstTryPassRate = 0;
+    let avgAttempts = 0;
+    if (withStats.length > 0) {
+      avgFirstTryPassRate = withStats.reduce((sum, m) => {
+        const s = m.outcomeStats;
+        return sum + s.firstTryPasses / s.totalUses;
+      }, 0) / withStats.length;
+      avgAttempts = withStats.reduce((sum, m) => {
+        const s = m.outcomeStats;
+        return sum + s.totalAttempts / s.totalUses;
+      }, 0) / withStats.length;
+    }
+    const ruleCounts = /* @__PURE__ */ new Map();
+    let totalFailureInstances = 0;
+    for (const m of withStats) {
+      const rules = m.outcomeStats.failedRules;
+      for (const [rule, count] of Object.entries(rules)) {
+        const r = parseInt(rule, 10);
+        ruleCounts.set(r, (ruleCounts.get(r) ?? 0) + count);
+        totalFailureInstances += count;
+      }
+    }
+    const commonFailedRules = [...ruleCounts.entries()].map(([rule, count]) => ({
+      rule,
+      frequency: totalFailureInstances > 0 ? count / totalFailureInstances : 0
+    })).filter((r) => r.frequency >= 0.1).sort((a, b) => b.frequency - a.frequency);
+    clusters.push({
+      pattern: describePattern(fp),
+      fingerprint: fp,
+      members,
+      avgFirstTryPassRate,
+      avgAttempts,
+      commonFailedRules
+    });
+  }
+  return clusters.sort((a, b) => b.members.length - a.members.length);
+}
+function rerank(candidates, clusters) {
+  const clusterMap = /* @__PURE__ */ new Map();
+  for (const cluster of clusters) {
+    for (const member of cluster.members) {
+      clusterMap.set(member.id, cluster);
+    }
+  }
+  return candidates.map((c) => {
+    const cluster = clusterMap.get(c.workflow.id);
+    let boost = 0;
+    if (cluster && cluster.avgFirstTryPassRate > 0) {
+      boost = (cluster.avgFirstTryPassRate - 0.5) * 0.1;
+    }
+    if (cluster && cluster.commonFailedRules.length > 0) {
+      boost -= cluster.commonFailedRules.length * 0.02;
+    }
+    return {
+      workflow: c.workflow,
+      score: Math.max(0, Math.min(1, c.score + boost)),
+      ...cluster ? { clusterPattern: cluster.pattern } : {}
+    };
+  }).sort((a, b) => b.score - a.score);
+}
+
+// src/library/file-library.ts
 function tokenize(text) {
   return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((t) => t.length > 2);
 }
-function computeTfIdf(queryTokens, docTokens, idf) {
-  if (docTokens.length === 0) return 0;
-  let score = 0;
-  const docFreq = /* @__PURE__ */ new Map();
-  for (const t of docTokens) {
-    docFreq.set(t, (docFreq.get(t) ?? 0) + 1);
-  }
-  for (const qt of queryTokens) {
-    const tf = (docFreq.get(qt) ?? 0) / docTokens.length;
-    const idfVal = idf.get(qt) ?? 0;
-    score += tf * idfVal;
-  }
-  return score;
+function buildSearchCorpus(w) {
+  const nodeTokens = w.workflow.nodes.map((n) => {
+    const bare = n.type.split(".").pop() ?? "";
+    const spaced = bare.replace(/([A-Z])/g, " $1").trim().toLowerCase();
+    return `${bare} ${spaced}`;
+  });
+  return `${w.description} ${w.workflow.name} ${w.tags.join(" ")} ${nodeTokens.join(" ")}`;
 }
+var MAX_LIBRARY_SIZE = 500;
 var FileLibrary = class {
   dir;
   workflows = [];
-  initialized = false;
+  initPromise = null;
+  writeQueue = Promise.resolve();
   constructor(dir) {
-    this.dir = dir ?? (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".kairos", "library");
+    this.dir = dir ?? (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".kairos", "library");
   }
   async initialize() {
-    if (this.initialized) return;
-    await (0, import_promises2.mkdir)(this.dir, { recursive: true });
-    const indexPath = (0, import_node_path2.join)(this.dir, "index.json");
+    if (!this.initPromise) {
+      this.initPromise = this.doInitialize();
+    }
+    return this.initPromise;
+  }
+  async doInitialize() {
+    await (0, import_promises3.mkdir)(this.dir, { recursive: true });
+    const indexPath = (0, import_node_path3.join)(this.dir, "index.json");
     try {
-      const raw = await (0, import_promises2.readFile)(indexPath, "utf-8");
-      this.workflows = JSON.parse(raw);
+      const raw = await (0, import_promises3.readFile)(indexPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) {
+        this.workflows = [];
+      } else {
+        this.workflows = parsed.filter(
+          (item) => typeof item === "object" && item !== null && typeof item.id === "string" && typeof item.description === "string" && typeof item.workflow === "object" && item.workflow !== null && Array.isArray(item.workflow.nodes)
+        );
+      }
     } catch {
       this.workflows = [];
     }
-    this.initialized = true;
   }
   async search(description, options) {
-    if (this.workflows.length === 0) return [];
+    const searchable = this.workflows.filter((w) => w.trustLevel !== "blocked");
+    if (searchable.length === 0) return [];
     const limit = options?.limit ?? 3;
     const queryTokens = tokenize(description);
     if (queryTokens.length === 0) return [];
-    const docTokenSets = this.workflows.map(
-      (w) => tokenize(`${w.description} ${w.workflow.name} ${w.tags.join(" ")}`)
-    );
-    const docCount = this.workflows.length;
+    const docTokenArrays = searchable.map((w) => tokenize(buildSearchCorpus(w)));
+    const docTokenSets = docTokenArrays.map((tokens) => new Set(tokens));
+    const docCount = searchable.length;
     const idf = /* @__PURE__ */ new Map();
     const allTokens = new Set(queryTokens);
     for (const token of allTokens) {
-      const docsWithToken = docTokenSets.filter((d) => d.includes(token)).length;
+      const docsWithToken = docTokenSets.filter((d) => d.has(token)).length;
       idf.set(token, Math.log((docCount + 1) / (docsWithToken + 1)) + 1);
     }
-    const scored = this.workflows.map((w, i) => ({
-      workflow: w,
-      score: computeTfIdf(queryTokens, docTokenSets[i], idf)
-    })).filter((m) => m.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
-    return scored.map((m) => ({
-      workflow: m.workflow,
-      score: m.score,
-      mode: m.score > 0.5 ? "direct" : "reference"
-    }));
+    const scored = hybridScore(queryTokens, description, searchable, docTokenArrays, idf).filter((m) => m.score > 0).sort((a, b) => b.score - a.score);
+    const clusters = clusterWorkflows(searchable);
+    const reranked = rerank(scored, clusters).slice(0, limit);
+    const results = reranked.map((m) => {
+      return { workflow: m.workflow, score: m.score, mode: scoreToMode(m.score) };
+    });
+    if (results.length > 0) {
+      for (const r of results) {
+        r.workflow.timesRetrieved = (r.workflow.timesRetrieved ?? 0) + 1;
+      }
+      this.persist();
+    }
+    return results;
   }
   async save(workflow, metadata) {
     const id = generateUUID();
+    const failurePatterns = this.deduplicateFailurePatterns(metadata.failurePatterns);
     const stored = {
       id,
       workflow,
       description: metadata.description,
       tags: metadata.tags ?? [],
       platform: metadata.platform ?? "n8n",
-      deployCount: 1,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      deployCount: 0,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...failurePatterns?.length ? { failurePatterns } : {},
+      ...metadata.sourceWorkflowIds?.length ? { sourceWorkflowIds: metadata.sourceWorkflowIds } : {},
+      ...metadata.generationMode ? { generationMode: metadata.generationMode } : {},
+      ...metadata.topMatchScore != null ? { topMatchScore: metadata.topMatchScore } : {},
+      ...metadata.generationAttempts != null ? { generationAttempts: metadata.generationAttempts } : {},
+      ...metadata.credentialsNeeded?.length ? { credentialsNeeded: metadata.credentialsNeeded } : {},
+      ...metadata.sourceKind ? { sourceKind: metadata.sourceKind } : {},
+      ...metadata.sourceId ? { sourceId: metadata.sourceId } : {},
+      ...metadata.sourceUrl ? { sourceUrl: metadata.sourceUrl } : {},
+      ...metadata.trustLevel ? { trustLevel: metadata.trustLevel } : {}
     };
     this.workflows.push(stored);
+    if (this.workflows.length > MAX_LIBRARY_SIZE) {
+      this.workflows.sort((a, b) => (b.deployCount ?? 1) - (a.deployCount ?? 1));
+      this.workflows = this.workflows.slice(0, MAX_LIBRARY_SIZE);
+    }
     await this.persist();
     return id;
   }
@@ -1414,6 +2174,28 @@ var FileLibrary = class {
       await this.persist();
     }
   }
+  async recordOutcome(id, outcome) {
+    const w = this.workflows.find((w2) => w2.id === id);
+    if (!w) return;
+    if (outcome.mode === "direct") {
+      w.timesUsedAsDirect = (w.timesUsedAsDirect ?? 0) + 1;
+    } else {
+      w.timesUsedAsReference = (w.timesUsedAsReference ?? 0) + 1;
+    }
+    const stats = w.outcomeStats ?? { totalUses: 0, totalAttempts: 0, firstTryPasses: 0, failedRules: {} };
+    stats.totalUses++;
+    stats.totalAttempts += outcome.attempts;
+    if (outcome.firstTryPass) stats.firstTryPasses++;
+    for (const rule of outcome.failedRules) {
+      const key = String(rule);
+      stats.failedRules[key] = (stats.failedRules[key] ?? 0) + 1;
+    }
+    w.outcomeStats = stats;
+    await this.persist();
+  }
+  async drain() {
+    await this.writeQueue;
+  }
   async get(id) {
     return this.workflows.find((w) => w.id === id) ?? null;
   }
@@ -1427,9 +2209,202 @@ var FileLibrary = class {
     }
     return result;
   }
-  async persist() {
-    const indexPath = (0, import_node_path2.join)(this.dir, "index.json");
-    await (0, import_promises2.writeFile)(indexPath, JSON.stringify(this.workflows, null, 2), "utf-8");
+  deduplicateFailurePatterns(patterns) {
+    if (!patterns?.length) return void 0;
+    const map = /* @__PURE__ */ new Map();
+    for (const fp of patterns) {
+      const existing = map.get(fp.rule);
+      if (existing) {
+        existing.occurrences++;
+      } else {
+        map.set(fp.rule, { rule: fp.rule, message: fp.message, occurrences: 1 });
+      }
+    }
+    return [...map.values()];
+  }
+  persist() {
+    this.writeQueue = this.writeQueue.then(async () => {
+      const indexPath = (0, import_node_path3.join)(this.dir, "index.json");
+      const tmpPath = `${indexPath}.tmp`;
+      await (0, import_promises3.writeFile)(tmpPath, JSON.stringify(this.workflows, null, 2), "utf-8");
+      await (0, import_promises3.rename)(tmpPath, indexPath);
+    });
+    return this.writeQueue;
+  }
+};
+
+// src/templates/safety.ts
+var BLOCKED_NODE_TYPES = /* @__PURE__ */ new Set([
+  "n8n-nodes-base.code",
+  "n8n-nodes-base.executeCommand",
+  "n8n-nodes-base.ssh"
+]);
+var REVIEW_NODE_TYPES = /* @__PURE__ */ new Set([
+  "n8n-nodes-base.httpRequest"
+]);
+var SECRET_PATTERNS = [
+  /sk-[a-zA-Z0-9]{20,}/,
+  /ghp_[a-zA-Z0-9]{36}/,
+  /xoxb-[0-9]+-[0-9]+-[a-zA-Z0-9]+/,
+  /AIza[a-zA-Z0-9_-]{35}/,
+  /AKIA[A-Z0-9]{16}/
+];
+function assessTemplateSafety(workflow) {
+  const reasons = [];
+  let worst = "safe";
+  const escalate = (level, reason) => {
+    reasons.push(reason);
+    if (level === "blocked") worst = "blocked";
+    else if (level === "review" && worst === "safe") worst = "review";
+  };
+  for (const node of workflow.nodes) {
+    if (BLOCKED_NODE_TYPES.has(node.type)) {
+      escalate("blocked", `Contains ${node.type} node "${node.name}"`);
+    }
+    if (REVIEW_NODE_TYPES.has(node.type)) {
+      escalate("review", `Contains ${node.type} node "${node.name}"`);
+    }
+    const paramStr = JSON.stringify(node.parameters);
+    for (const pattern of SECRET_PATTERNS) {
+      if (pattern.test(paramStr)) {
+        escalate("blocked", `Node "${node.name}" parameters contain a hardcoded secret`);
+        break;
+      }
+    }
+  }
+  return { trustLevel: worst, reasons };
+}
+
+// src/templates/syncer.ts
+var N8N_TEMPLATE_API = "https://api.n8n.io/api/templates";
+var PAGE_SIZE = 50;
+var DELAY_BETWEEN_FETCHES_MS = 200;
+var DEFAULT_SETTINGS = {
+  executionOrder: "v1",
+  saveManualExecutions: true,
+  timezone: "UTC"
+};
+var TemplateSyncer = class {
+  constructor(library, logger) {
+    this.library = library;
+    this.validator = new N8nValidator();
+    this.logger = logger;
+  }
+  library;
+  validator;
+  logger;
+  async sync(options) {
+    const maxTemplates = options?.maxTemplates ?? 500;
+    await this.library.initialize();
+    const existing = await this.library.list();
+    const existingSourceIds = new Set(
+      existing.filter((w) => w.sourceKind === "n8n-template" && w.sourceId).map((w) => w.sourceId)
+    );
+    const progress = {
+      total: 0,
+      processed: 0,
+      saved: 0,
+      skippedPaid: 0,
+      skippedDuplicate: 0,
+      blocked: 0,
+      reviewed: 0
+    };
+    const templateIds = await this.fetchTemplateIds(maxTemplates, progress);
+    for (const id of templateIds) {
+      if (existingSourceIds.has(String(id))) {
+        progress.skippedDuplicate++;
+        progress.processed++;
+        options?.onProgress?.(progress);
+        continue;
+      }
+      try {
+        await this.processTemplate(id, progress);
+      } catch (err) {
+        this.logger.warn(`Failed to process template ${id}`, { err: String(err) });
+      }
+      progress.processed++;
+      options?.onProgress?.(progress);
+      await new Promise((resolve) => setTimeout(resolve, DELAY_BETWEEN_FETCHES_MS));
+    }
+    return progress;
+  }
+  async fetchTemplateIds(max, progress) {
+    const ids = [];
+    let page = 1;
+    while (ids.length < max) {
+      const url = `${N8N_TEMPLATE_API}/search?page=${page}&rows=${PAGE_SIZE}`;
+      const response = await fetch(url);
+      if (!response.ok) break;
+      const data = await response.json();
+      progress.total = Math.min(data.totalWorkflows, max);
+      for (const template of data.workflows) {
+        if (ids.length >= max) break;
+        if (template.price && template.price > 0) {
+          progress.skippedPaid++;
+          continue;
+        }
+        ids.push(template.id);
+      }
+      if (data.workflows.length < PAGE_SIZE) break;
+      page++;
+      await new Promise((resolve) => setTimeout(resolve, DELAY_BETWEEN_FETCHES_MS));
+    }
+    return ids;
+  }
+  async processTemplate(id, progress) {
+    const url = `${N8N_TEMPLATE_API}/workflows/${id}`;
+    const response = await fetch(url);
+    if (!response.ok) return;
+    const data = await response.json();
+    const templateMeta = data.workflow;
+    const rawWorkflow = templateMeta.workflow;
+    if (!rawWorkflow?.nodes?.length) return;
+    const workflow = {
+      name: templateMeta.name,
+      nodes: rawWorkflow.nodes.filter((n) => n.type && n.name),
+      connections: rawWorkflow.connections,
+      settings: rawWorkflow.settings ? { executionOrder: "v1", ...rawWorkflow.settings } : { ...DEFAULT_SETTINGS }
+    };
+    const validation = this.validator.validate(workflow);
+    const validationErrors = validation.issues.filter((i) => i.severity === "error");
+    if (validationErrors.length > 0) {
+      progress.blocked++;
+      this.logger.debug(`Template ${id} blocked: ${validationErrors.length} validation errors`);
+      return;
+    }
+    const safety = assessTemplateSafety(workflow);
+    if (safety.trustLevel === "blocked") {
+      progress.blocked++;
+      this.logger.debug(`Template ${id} blocked: ${safety.reasons.join(", ")}`);
+      return;
+    }
+    if (safety.trustLevel === "review") {
+      progress.reviewed++;
+    }
+    const description = this.cleanDescription(templateMeta.description);
+    const autoTags = Array.from(new Set(
+      workflow.nodes.flatMap((n) => {
+        const bare = n.type.split(".").pop() ?? "";
+        const tags = [bare];
+        if (n.type.includes("Trigger") || n.type.includes("trigger")) tags.push(`trigger:${bare}`);
+        if (n.type.includes("langchain")) tags.push("ai");
+        return tags;
+      })
+    ));
+    const metadata = {
+      description,
+      tags: autoTags,
+      sourceKind: "n8n-template",
+      sourceId: String(id),
+      sourceUrl: `https://n8n.io/workflows/${id}`,
+      trustLevel: safety.trustLevel
+    };
+    await this.library.save(workflow, metadata);
+    progress.saved++;
+    this.logger.debug(`Template ${id} saved: "${templateMeta.name}" (${safety.trustLevel})`);
+  }
+  cleanDescription(raw) {
+    return raw.replace(/#{1,6}\s*/g, "").replace(/\*{1,2}([^*]+)\*{1,2}/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\n{3,}/g, "\n\n").trim().slice(0, 500);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1450,7 +2425,14 @@ var FileLibrary = class {
   ProviderError,
   ResponseParseError,
   TelemetryCollector,
+  TelemetryReader,
+  TemplateSyncer,
   ValidationError,
-  nullLogger
+  buildSearchCorpus,
+  clusterWorkflows,
+  hybridScore,
+  nullLogger,
+  rerank,
+  tokenize
 });
 //# sourceMappingURL=index.cjs.map