tide-commander 1.32.2 → 1.35.0

package/dist/src/packages/server/routes/workflow-routes.js

@@ -5,6 +5,7 @@
  */
 import { Router } from 'express';
 import * as workflowService from '../services/workflow-service.js';
+import * as workflowExecutor from '../services/workflow-executor.js';
 import * as workflowChatService from '../services/workflow-chat-service.js';
 const router = Router();
 // ─── Query Helpers (same pattern as event-routes.ts) ───
@@ -125,7 +126,33 @@ router.patch('/instances/:id/cancel', (req, res) => {
     }
     res.json(instance);
 });
-// ─── Manual Transition ───
+// ─── Explicit Transition (agent-driven) ───
+router.put('/instances/:id/transition', async (req, res) => {
+    try {
+        const { targetStateId, reason } = req.body;
+        if (!targetStateId) {
+            res.status(400).json({ error: 'targetStateId is required' });
+            return;
+        }
+        const instance = await workflowService.transitionTo(req.params.id, targetStateId, reason);
+        res.json(instance);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Transition failed';
+        res.status(400).json({ error: msg });
+    }
+});
+router.get('/instances/:id/available-transitions', (req, res) => {
+    try {
+        const transitions = workflowService.getAvailableTransitions(req.params.id);
+        res.json({ transitions });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Failed to get transitions';
+        res.status(400).json({ error: msg });
+    }
+});
+// ─── Legacy Manual Transition (event-based) ───
 router.post('/instances/:id/transition', async (req, res) => {
     try {
         await workflowService.notifyEvent({
@@ -172,6 +199,63 @@ router.post('/instances/:id/event', async (req, res) => {
         res.status(400).json({ error: msg });
     }
 });
+// ─── Trigger Routing (workflow-executor) ───
+router.post('/trigger', async (req, res) => {
+    try {
+        const { triggerId, triggerData, agentId } = req.body;
+        if (!triggerId) {
+            res.status(400).json({ error: 'triggerId is required' });
+            return;
+        }
+        await workflowExecutor.handleTrigger({
+            triggerId,
+            triggerData: triggerData ?? {},
+            agentId,
+        });
+        res.json({ routed: true, triggerId });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Trigger routing failed';
+        res.status(500).json({ error: msg });
+    }
+});
+// ─── Agent Complete with Reasoning (workflow-executor) ───
+router.post('/instances/:id/agent-complete', async (req, res) => {
+    try {
+        const { agentResponse, agentReasoning, agentSummary, variables, triggerId, transitionId } = req.body;
+        const instance = await workflowExecutor.transitionInstance(req.params.id, 'agent_complete', { agentResponse, agentReasoning, agentSummary, variables }, { triggerId, transitionId });
+        if (!instance) {
+            res.status(404).json({ error: 'Instance not found' });
+            return;
+        }
+        res.json(instance);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Agent complete failed';
+        res.status(400).json({ error: msg });
+    }
+});
+// ─── Bind Agent to Instance (workflow-executor) ───
+router.post('/instances/:id/bind-agent', (req, res) => {
+    try {
+        const { agentId, stateId } = req.body;
+        if (!agentId) {
+            res.status(400).json({ error: 'agentId is required' });
+            return;
+        }
+        const result = workflowExecutor.executeInstanceState(req.params.id, stateId || workflowService.getInstance(req.params.id)?.currentStateId || '', agentId);
+        res.json({
+            instanceId: result.instance.id,
+            stateId: result.state.id,
+            stateName: result.state.name,
+            currentStepId: result.currentStep?.id,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Bind agent failed';
+        res.status(400).json({ error: msg });
+    }
+});
 // ============================================================================
 // History & Audit (reads from SQLite)
 // ============================================================================
@@ -193,7 +277,7 @@ router.get('/instances/:id/variables', (req, res) => {
     res.json({ changes });
 });
 router.get('/instances/:id/reasoning', (req, res) => {
-    const steps = workflowService.getInstanceReasoning(req.params.id);
+    const steps = workflowExecutor.getReasoningChain(req.params.id);
     res.json({ steps });
 });
 // ============================================================================

package/dist/src/packages/server/services/boss-message-service.js

@@ -12,7 +12,7 @@ import { buildBossContext } from './subordinate-context-service.js';
 export function buildBossSystemPrompt(bossName, bossId) {
     const agent = agentService.getAgent(bossId);
     const customInstructions = agent?.customInstructions;
-    let prompt = `You are "${bossName}", a Boss Agent manager with ID \`${bossId}\`. You have access to all tools, but prefer delegating coding tasks to your subordinates when available. Use tools yourself only for quick lookups, exploration, or when you have no subordinates.
+    let prompt = `You are "${bossName}", a Boss Agent manager with ID \`${bossId}\`. Your default is to delegate tasks to your subordinates. Do small tasks yourself only when you already have the context to finish quickly (1-2 tool calls). For anything requiring exploration or substantial work, delegate to your team.
 
 Your agent ID for notifications: ${bossId}`;
     // Append agent-specific custom instructions

package/dist/src/packages/server/services/llm-matcher-service.js

@@ -3,39 +3,57 @@
  * Evaluates whether events match triggers using LLM-powered semantic matching,
  * and extracts structured variables from unstructured event content.
  *
- * Uses Anthropic's API with Haiku by default (fast, cheap classification).
- * Temperature 0 for deterministic results.
- * 5-second timeout — match treated as false on timeout (fail-safe).
+ * Uses the Anthropic SDK to call Claude (requires TC_ANTHROPIC_API_KEY environment variable).
+ * Haiku by default (fast, cheap classification).
+ * 15-second timeout — match treated as false on timeout (fail-safe).
  */
 import Anthropic from '@anthropic-ai/sdk';
 import { createLogger } from '../utils/logger.js';
 const log = createLogger('LLMMatcher');
-// Model mapping: short names to full model IDs
+const TIMEOUT_MS = 15_000;
+// Model mapping — use latest available model IDs
 const MODEL_MAP = {
     haiku: 'claude-haiku-4-5-20251001',
-    sonnet: 'claude-sonnet-4-6',
-    opus: 'claude-opus-4-6',
+    sonnet: 'claude-sonnet-4-6-20250514',
+    opus: 'claude-opus-4-6-20250514',
 };
 function resolveModel(model) {
     if (!model)
         return MODEL_MAP.haiku;
     return MODEL_MAP[model] || model;
 }
-// Lazy-initialized client
-let client = null;
-function getClient() {
-    if (!client) {
-        client = new Anthropic();
+/**
+ * Execute a prompt via the Anthropic SDK.
+ * Returns the raw text response.
+ */
+async function callAnthropicAPI(prompt, model) {
+    const startTime = Date.now();
+    const client = new Anthropic({
+        apiKey: process.env.TC_ANTHROPIC_API_KEY,
+        timeout: TIMEOUT_MS,
+    });
+    try {
+        const message = await client.messages.create({
+            model,
+            max_tokens: 1024,
+            messages: [{ role: 'user', content: prompt }],
+        });
+        const durationMs = Date.now() - startTime;
+        const text = message.content
+            .filter(block => block.type === 'text')
+            .map(block => block.text)
+            .join('\n');
+        return { text, durationMs };
+    }
+    catch (err) {
+        throw err;
     }
-    return client;
 }
 // ─── LLM Match ───
 export async function llmMatch(formattedEvent, config) {
     const startTime = Date.now();
     const model = resolveModel(config.model);
-    const temperature = config.temperature ?? 0;
-    const maxTokens = config.maxTokens ?? 150;
-    const systemPrompt = `You are an event classifier. Your job is to decide whether an incoming event matches a given condition.
+    const prompt = `You are an event classifier. Your job is to decide whether an incoming event matches a given condition.
 
 EVENT:
 ---
@@ -55,18 +73,7 @@ Respond ONLY with valid JSON (no markdown, no explanation outside JSON):
   "confidence": 0.0 to 1.0
 }`;
     try {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5000);
-        const response = await getClient().messages.create({
-            model,
-            max_tokens: maxTokens,
-            temperature,
-            messages: [{ role: 'user', content: systemPrompt }],
-        }, { signal: controller.signal });
-        clearTimeout(timeout);
-        const durationMs = Date.now() - startTime;
-        const text = response.content[0]?.type === 'text' ? response.content[0].text : '';
-        const tokensUsed = (response.usage?.input_tokens || 0) + (response.usage?.output_tokens || 0);
+        const { text, durationMs } = await callAnthropicAPI(prompt, model);
         try {
             // Extract JSON from response (handle potential markdown wrapping)
             const jsonMatch = text.match(/\{[\s\S]*\}/);
@@ -79,7 +86,7 @@ Respond ONLY with valid JSON (no markdown, no explanation outside JSON):
                 confidence: typeof parsed.confidence === 'number' ? parsed.confidence : (parsed.match ? 1.0 : 0.0),
                 durationMs,
                 model,
-                tokensUsed,
+                tokensUsed: 0,
             };
         }
         catch (parseErr) {
@@ -90,32 +97,19 @@ Respond ONLY with valid JSON (no markdown, no explanation outside JSON):
                 confidence: 0,
                 durationMs,
                 model,
-                tokensUsed,
+                tokensUsed: 0,
             };
         }
     }
     catch (err) {
         const durationMs = Date.now() - startTime;
-        if (err instanceof Error && err.name === 'AbortError') {
-            log.warn('LLM match timed out after 5s');
-            return {
-                match: false,
-                reason: 'LLM call timed out (5s)',
-                confidence: 0,
-                durationMs,
-                model,
-                tokensUsed: 0,
-            };
+        const reason = err instanceof Error ? err.message : 'unknown';
+        if (reason.includes('timed out') || reason.includes('timeout')) {
+            log.warn(`LLM match timed out after ${TIMEOUT_MS}ms`);
+            return { match: false, reason: `LLM call timed out (${TIMEOUT_MS}ms)`, confidence: 0, durationMs, model, tokensUsed: 0 };
         }
         log.error('LLM match error:', err);
-        return {
-            match: false,
-            reason: `LLM error: ${err instanceof Error ? err.message : 'unknown'}`,
-            confidence: 0,
-            durationMs,
-            model,
-            tokensUsed: 0,
-        };
+        return { match: false, reason: `LLM error: ${reason}`, confidence: 0, durationMs, model, tokensUsed: 0 };
     }
 }
 // ─── LLM Variable Extraction ───
@@ -123,7 +117,7 @@ export async function llmExtractVariables(formattedEvent, config) {
     const startTime = Date.now();
     const model = resolveModel(config.model);
     const variableList = config.variables.map(v => `- ${v}`).join('\n');
-    const systemPrompt = `You are a data extractor. Extract specific variables from the event below.
+    const prompt = `You are a data extractor. Extract specific variables from the event below.
 
 EVENT:
 ---
@@ -147,18 +141,7 @@ Respond ONLY with valid JSON (no markdown, no explanation outside JSON):
   "reason": "Brief explanation of how you extracted each value"
 }`;
     try {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5000);
-        const response = await getClient().messages.create({
-            model,
-            max_tokens: 300,
-            temperature: 0,
-            messages: [{ role: 'user', content: systemPrompt }],
-        }, { signal: controller.signal });
-        clearTimeout(timeout);
-        const durationMs = Date.now() - startTime;
-        const text = response.content[0]?.type === 'text' ? response.content[0].text : '';
-        const tokensUsed = (response.usage?.input_tokens || 0) + (response.usage?.output_tokens || 0);
+        const { text, durationMs } = await callAnthropicAPI(prompt, model);
         try {
             const jsonMatch = text.match(/\{[\s\S]*\}/);
             if (!jsonMatch)
@@ -169,17 +152,10 @@ Respond ONLY with valid JSON (no markdown, no explanation outside JSON):
             for (const v of config.variables) {
                 variables[v] = parsed.variables?.[v] ?? '';
             }
-            return {
-                variables,
-                reason: parsed.reason || '',
-                durationMs,
-                model,
-                tokensUsed,
-            };
+            return { variables, reason: parsed.reason || '', durationMs, model, tokensUsed: 0 };
         }
         catch (parseErr) {
             log.error('Failed to parse LLM extract response:', text);
-            // Return empty variables on parse failure
             const variables = {};
             for (const v of config.variables) {
                 variables[v] = '';
@@ -187,9 +163,7 @@ Respond ONLY with valid JSON (no markdown, no explanation outside JSON):
             return {
                 variables,
                 reason: `Parse error: ${parseErr instanceof Error ? parseErr.message : 'unknown'}`,
-                durationMs,
-                model,
-                tokensUsed,
+                durationMs, model, tokensUsed: 0,
             };
         }
     }
@@ -199,17 +173,12 @@ Respond ONLY with valid JSON (no markdown, no explanation outside JSON):
         for (const v of config.variables) {
             variables[v] = '';
         }
-        if (err instanceof Error && err.name === 'AbortError') {
-            log.warn('LLM extract timed out after 5s');
-            return { variables, reason: 'LLM call timed out (5s)', durationMs, model, tokensUsed: 0 };
+        const reason = err instanceof Error ? err.message : 'unknown';
+        if (reason.includes('timed out') || reason.includes('timeout')) {
+            log.warn(`LLM extract timed out after ${TIMEOUT_MS}ms`);
+            return { variables, reason: `LLM call timed out (${TIMEOUT_MS}ms)`, durationMs, model, tokensUsed: 0 };
         }
         log.error('LLM extract error:', err);
-        return {
-            variables,
-            reason: `LLM error: ${err instanceof Error ? err.message : 'unknown'}`,
-            durationMs,
-            model,
-            tokensUsed: 0,
-        };
+        return { variables, reason: `LLM error: ${reason}`, durationMs, model, tokensUsed: 0 };
     }
 }

package/dist/src/packages/server/services/trigger-service.js

@@ -160,27 +160,54 @@ export function deleteTrigger(id) {
 // ─── Event Evaluation ───
 async function evaluateEvent(handler, event) {
     const triggersOfType = Array.from(triggers.values()).filter(t => t.type === handler.triggerType && t.enabled);
+    // Extract source info from the event for per-message debugging
+    const sourceType = event.source;
+    const sourceId = extractSourceId(event);
+    const sourceTimestamp = event.timestamp;
     for (const trigger of triggersOfType) {
         try {
             let matched = false;
+            let structuralPassed = true;
             let llmResult;
             let llmExtractResult;
+            const matcherExecutions = [];
+            const sourceInfo = { sourceType, sourceId, sourceTimestamp };
             // Step 1: Structural matching
             if (trigger.matchMode === 'structural' || trigger.matchMode === 'hybrid') {
                 const structuralResult = handler.structuralMatch(trigger, event);
+                matcherExecutions.push({
+                    matcherType: 'structural',
+                    matcherName: `${trigger.type}_structural`,
+                    executedAt: Date.now(),
+                    matched: structuralResult,
+                    reason: structuralResult ? 'Structural match passed' : 'Structural match failed',
+                    resultJson: { triggerType: trigger.type, matchMode: trigger.matchMode },
+                    ...sourceInfo,
+                });
                 if (trigger.matchMode === 'structural') {
                     matched = structuralResult;
                 }
                 else {
                     // hybrid: structural must pass before LLM is called
+                    structuralPassed = structuralResult;
                     if (!structuralResult)
-                        continue;
+                        matched = false;
                 }
             }
-            // Step 2: LLM matching
-            if (trigger.matchMode === 'llm' || trigger.matchMode === 'hybrid') {
+            // Step 2: LLM matching (skip if hybrid structural failed)
+            if (structuralPassed && (trigger.matchMode === 'llm' || trigger.matchMode === 'hybrid')) {
                 if (!trigger.llmMatch) {
                     log.warn(`Trigger ${trigger.name} has matchMode=${trigger.matchMode} but no llmMatch config`);
+                    matcherExecutions.push({
+                        matcherType: 'llm',
+                        matcherName: 'llm_match',
+                        executedAt: Date.now(),
+                        matched: false,
+                        reason: 'No llmMatch config defined',
+                        ...sourceInfo,
+                    });
+                    // Log non-match executions and skip to next trigger
+                    logMatcherExecutions(null, trigger.id, matcherExecutions);
                     continue;
                 }
                 const formatted = handler.formatEventForLLM(event);
@@ -188,10 +215,28 @@ async function evaluateEvent(handler, event) {
                 // Check confidence threshold
                 const minConfidence = trigger.llmMatch.minConfidence ?? 0.0;
                 matched = llmResult.match && llmResult.confidence >= minConfidence;
+                matcherExecutions.push({
+                    matcherType: 'llm',
+                    matcherName: 'llm_match',
+                    executedAt: Date.now(),
+                    matched,
+                    confidence: llmResult.confidence,
+                    reason: llmResult.reason,
+                    resultJson: {
+                        model: llmResult.model,
+                        tokensUsed: llmResult.tokensUsed,
+                        durationMs: llmResult.durationMs,
+                        minConfidence,
+                    },
+                    ...sourceInfo,
+                });
             }
-            if (!matched)
+            // Log non-match executions directly (they won't go through fireTrigger)
+            if (!matched) {
+                logMatcherExecutions(null, trigger.id, matcherExecutions);
                 continue;
-            // Step 3: Variable extraction
+            }
+            // Step 3: Variable extraction (only on match)
             let variables;
             if (trigger.extractionMode === 'llm' && trigger.llmExtract) {
                 const formatted = handler.formatEventForLLM(event);
@@ -199,15 +244,39 @@ async function evaluateEvent(handler, event) {
                 // Merge with structural variables as fallback
                 const structuralVars = handler.extractVariables(trigger, event);
                 variables = { ...structuralVars, ...llmExtractResult.variables };
+                matcherExecutions.push({
+                    matcherType: 'extraction',
+                    matcherName: 'llm_extract',
+                    executedAt: Date.now(),
+                    matched: Object.keys(llmExtractResult.variables).length > 0,
+                    reason: llmExtractResult.reason,
+                    resultJson: {
+                        extractedVariables: llmExtractResult.variables,
+                        model: llmExtractResult.model,
+                        tokensUsed: llmExtractResult.tokensUsed,
+                        durationMs: llmExtractResult.durationMs,
+                    },
+                    ...sourceInfo,
+                });
             }
             else {
                 variables = handler.extractVariables(trigger, event);
+                matcherExecutions.push({
+                    matcherType: 'extraction',
+                    matcherName: 'structural_extract',
+                    executedAt: Date.now(),
+                    matched: Object.keys(variables).length > 0,
+                    reason: `Extracted ${Object.keys(variables).length} variables`,
+                    resultJson: { extractedVariables: variables },
+                    ...sourceInfo,
+                });
             }
-            // Step 4: Fire the trigger
+            // Step 4: Fire the trigger (matcher executions linked after trigger_event created)
             await fireTrigger(trigger.id, variables, {
                 rawPayload: event.data,
                 llmMatchResult: llmResult,
                 llmExtractResult: llmExtractResult,
+                matcherExecutions,
             });
         }
         catch (err) {
@@ -218,6 +287,33 @@ async function evaluateEvent(handler, event) {
         }
     }
 }
+/**
+ * Extract a stable identifier from an external event's data.
+ * Each integration stores its message ID in a different field.
+ */
+function extractSourceId(event) {
+    if (!event.data || typeof event.data !== 'object')
+        return undefined;
+    const data = event.data;
+    // Slack: ts or thread_ts
+    if (data.ts)
+        return String(data.ts);
+    if (data.event_ts)
+        return String(data.event_ts);
+    // Email: messageId or id
+    if (data.messageId)
+        return String(data.messageId);
+    // Jira: issue key or id
+    if (data.issue && typeof data.issue === 'object') {
+        const issue = data.issue;
+        if (issue.key)
+            return String(issue.key);
+    }
+    // Webhook: try id field
+    if (data.id)
+        return String(data.id);
+    return undefined;
+}
 // ─── Test Match (dry run — no fire, no SQLite log) ───
 export async function testMatch(triggerId, event) {
     const trigger = triggers.get(triggerId);
@@ -229,9 +325,18 @@ export async function testMatch(triggerId, event) {
     let structuralResult;
     let llmResult;
     let wouldFire = false;
+    const matcherExecutions = [];
     // Structural matching
     if (trigger.matchMode === 'structural' || trigger.matchMode === 'hybrid') {
         structuralResult = effectiveHandler.structuralMatch(trigger, event);
+        matcherExecutions.push({
+            matcherType: 'structural',
+            matcherName: `${trigger.type}_structural`,
+            executedAt: Date.now(),
+            matched: structuralResult,
+            reason: structuralResult ? 'Structural match passed' : 'Structural match failed',
+            resultJson: { triggerType: trigger.type, matchMode: trigger.matchMode },
+        });
         if (trigger.matchMode === 'structural') {
             wouldFire = structuralResult;
         }
@@ -241,6 +346,7 @@ export async function testMatch(triggerId, event) {
                 structuralMatch: structuralResult,
                 extractedVariables: {},
                 wouldFire: false,
+                matcherExecutions,
             };
         }
     }
@@ -251,6 +357,20 @@ export async function testMatch(triggerId, event) {
             llmResult = await llmMatch(formatted, trigger.llmMatch);
             const minConfidence = trigger.llmMatch.minConfidence ?? 0.0;
             wouldFire = llmResult.match && llmResult.confidence >= minConfidence;
+            matcherExecutions.push({
+                matcherType: 'llm',
+                matcherName: 'llm_match',
+                executedAt: Date.now(),
+                matched: wouldFire,
+                confidence: llmResult.confidence,
+                reason: llmResult.reason,
+                resultJson: {
+                    model: llmResult.model,
+                    tokensUsed: llmResult.tokensUsed,
+                    durationMs: llmResult.durationMs,
+                    minConfidence,
+                },
+            });
         }
     }
     // Variable extraction (always run for test)
@@ -260,15 +380,37 @@ export async function testMatch(triggerId, event) {
         const extractResult = await llmExtractVariables(formatted, trigger.llmExtract);
         const structuralVars = effectiveHandler.extractVariables(trigger, event);
         extractedVariables = { ...structuralVars, ...extractResult.variables };
+        matcherExecutions.push({
+            matcherType: 'extraction',
+            matcherName: 'llm_extract',
+            executedAt: Date.now(),
+            matched: Object.keys(extractResult.variables).length > 0,
+            reason: extractResult.reason,
+            resultJson: {
+                extractedVariables: extractResult.variables,
+                model: extractResult.model,
+                tokensUsed: extractResult.tokensUsed,
+                durationMs: extractResult.durationMs,
+            },
+        });
     }
     else {
         extractedVariables = effectiveHandler.extractVariables(trigger, event);
+        matcherExecutions.push({
+            matcherType: 'extraction',
+            matcherName: 'structural_extract',
+            executedAt: Date.now(),
+            matched: Object.keys(extractedVariables).length > 0,
+            reason: `Extracted ${Object.keys(extractedVariables).length} variables`,
+            resultJson: { extractedVariables },
+        });
     }
     return {
         structuralMatch: structuralResult,
         llmMatch: llmResult,
         extractedVariables,
         wouldFire,
+        matcherExecutions,
     };
 }
 // ─── Fire Trigger ───
@@ -305,6 +447,10 @@ export async function fireTrigger(id, variables, opts) {
             error: null,
             duration_ms: null,
         });
+        // Log matcher executions linked to this trigger event
+        if (opts?.matcherExecutions && eventId > 0) {
+            logMatcherExecutions(eventId, trigger.id, opts.matcherExecutions);
+        }
     }
     catch (err) {
         log.error('Failed to log trigger fire to SQLite:', err);
@@ -332,6 +478,16 @@ export async function fireTrigger(id, variables, opts) {
         }
         emit('trigger_fired', { triggerId: id, agentId: trigger.agentId, timestamp: startTime });
         log.log(`Fired trigger ${trigger.name} -> agent ${trigger.agentId}`);
+        // Route to workflow instances that are waiting for this trigger
+        try {
+            const { handleTrigger } = await import('./workflow-executor.js');
+            await handleTrigger({
+                triggerId: id,
+                triggerData: variables,
+                agentId: trigger.agentId,
+            });
+        }
+        catch { /* workflow routing is best-effort */ }
     }
     catch (err) {
         const errorMsg = err instanceof Error ? err.message : 'Unknown error';
@@ -434,6 +590,39 @@ export function getTriggerEvents(triggerId, limit = 50) {
 export function getAllTriggerEvents(limit = 100) {
     return queryMany('SELECT * FROM trigger_events ORDER BY fired_at DESC LIMIT ?', [limit]);
 }
+// ─── Matcher Execution Logging (debugging) ───
+function logMatcherExecutions(triggerEventId, triggerId, executions) {
+    for (const exec of executions) {
+        try {
+            insertOne('matcher_executions', {
+                trigger_event_id: triggerEventId,
+                trigger_id: triggerId,
+                matcher_type: exec.matcherType,
+                matcher_name: exec.matcherName,
+                executed_at: exec.executedAt,
+                matched: exec.matched ? 1 : 0,
+                confidence: exec.confidence ?? null,
+                reason: exec.reason ?? null,
+                result_json: exec.resultJson ? JSON.stringify(exec.resultJson) : null,
+                source_type: exec.sourceType ?? null,
+                source_id: exec.sourceId ?? null,
+                source_timestamp: exec.sourceTimestamp ?? null,
+            });
+        }
+        catch (err) {
+            log.error(`Failed to log matcher execution: ${err}`);
+        }
+    }
+}
+export function getMatchersByEvent(triggerEventId) {
+    return queryMany('SELECT * FROM matcher_executions WHERE trigger_event_id = ? ORDER BY executed_at ASC', [triggerEventId]);
+}
+export function getMatcherHistoryByTrigger(triggerId, limit = 100) {
+    return queryMany('SELECT * FROM matcher_executions WHERE trigger_id = ? ORDER BY executed_at DESC LIMIT ?', [triggerId, limit]);
+}
+export function getMatchersBySource(sourceType, sourceId) {
+    return queryMany('SELECT * FROM matcher_executions WHERE source_type = ? AND source_id = ? ORDER BY executed_at ASC', [sourceType, sourceId]);
+}
 // ─── Webhook Handler (basic built-in handler for webhook triggers) ───
 function createWebhookHandler() {
     return {