@automagik/omni 2.260906.3 → 2.260906.4

package/db/drizzle/0058_omni_events_causation_id.sql

@@ -0,0 +1,24 @@
+-- causationId in the persisted event journal (#957, RFC #925 G3 feature half).
+--
+-- `metadata->correlationId` groups a flow (the bag of events); `causation_id`
+-- gives the tree — the id of the IMMEDIATE parent event whose consumption
+-- caused this one to be published. NULL for root events (external ingress
+-- mints a fresh correlation, no parent) and for every pre-existing row
+-- (forward-only: the ~349k historical journal events have no derivable
+-- parent, no backfill). Not an FK — the parent may never have been persisted
+-- or may have been pruned.
+--
+-- The index serves the `omni events trace` descendants walk
+-- (children = rows WHERE causation_id = :id).
+--
+-- Hand-written following the 0055_asc_flow_handoff_mode precedent (additive,
+-- idempotent — the snapshot chain stops at 0026 so drizzle-kit generate is
+-- not usable here). No explicit BEGIN/COMMIT — the boot migrator executes
+-- this file on a pooled postgres-js connection, which rejects raw transaction
+-- control. ADD COLUMN with no default does not rewrite the table.
+
+ALTER TABLE "omni_events"
+  ADD COLUMN IF NOT EXISTS "causation_id" uuid;
+
+CREATE INDEX IF NOT EXISTS "omni_events_causation_idx"
+  ON "omni_events" ("causation_id");

package/db/drizzle/meta/_journal.json

@@ -407,6 +407,13 @@
       "when": 1785700000000,
       "tag": "0057_connector_lifecycle_contract",
       "breakpoints": true
+    },
+    {
+      "idx": 58,
+      "version": "7",
+      "when": 1785800000000,
+      "tag": "0058_omni_events_causation_id",
+      "breakpoints": true
     }
   ]
 }

package/dist/commands/events.d.ts

@@ -3,11 +3,25 @@
  *
  * omni events list --instance <id>
  * omni events stream [flags]
+ * omni events trace <id>
  * omni events search <query>
  * omni events timeline <person-id>
  */
 import type { Event } from '@omni/sdk';
 import { Command } from 'commander';
+/** One journal row as returned inside a trace response. */
+interface TraceEvent {
+    id: string;
+    eventType: string;
+    receivedAt: string;
+    causationId: string | null;
+    metadata?: {
+        correlationId?: string;
+    } | null;
+    textContent?: string | null;
+}
+/** One human-readable trace line: type, short id, time, correlation. */
+export declare function formatTraceLine(event: TraceEvent, marker: string): string;
 /** A registered event schema as returned by the API. */
 interface EventSchemaData {
     id: string;

package/dist/commands/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/commands/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsMpC,wDAAwD;AACxD,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,iBAAe,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAe1G;AAED,kFAAkF;AAClF,iBAAS,kBAAkB,CAAC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUhG;AAED,iBAAS,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzE;AAyED,eAAO,MAAM,WAAW;;;;CAA+D,CAAC;AAoBxF,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAQvF;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAOpD;AA6HD,wBAAgB,mBAAmB,IAAI,OAAO,CAqP7C"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/commands/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsMpC,2DAA2D;AAC3D,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AA+BD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzE;AAyCD,wDAAwD;AACxD,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,iBAAe,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAe1G;AAED,kFAAkF;AAClF,iBAAS,kBAAkB,CAAC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUhG;AAED,iBAAS,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzE;AAyED,eAAO,MAAM,WAAW;;;;CAA+D,CAAC;AAoBxF,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAQvF;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAOpD;AA6HD,wBAAgB,mBAAmB,IAAI,OAAO,CAmQ7C"}

package/dist/index.js

@@ -12345,6 +12345,19 @@ var init_types3 = __esm(() => {
     "flow.data_exchange"
   ];
 });
+// ../core/src/events/causality.ts
+import { AsyncLocalStorage } from "async_hooks";
+function runWithEventCausality(context, fn) {
+  return storage.run(context, fn);
+}
+function currentEventCausality() {
+  return storage.getStore();
+}
+var storage;
+var init_causality = __esm(() => {
+  storage = new AsyncLocalStorage;
+});
+
 // ../core/src/events/envelope.ts
 function classifyEnvelope(metadata) {
   if (metadata === null || metadata === undefined)
@@ -30370,6 +30383,38 @@ var init_logger = __esm(() => {
   rootLogger = createLogger("system");
 });
 
+// ../core/src/events/factory.ts
+function createOmniEvent(type, payload, metadata, serviceName) {
+  const eventId = crypto.randomUUID();
+  const timestamp = Date.now();
+  const tenantId = resolvePublishTenantId(metadata?.tenantId, metadata?.instanceId);
+  const ambient = currentEventCausality();
+  const causationId = metadata?.causationId ?? ambient?.causationId;
+  return {
+    id: eventId,
+    type,
+    payload,
+    timestamp,
+    metadata: {
+      correlationId: metadata?.correlationId ?? ambient?.correlationId ?? eventId,
+      ...causationId ? { causationId } : {},
+      instanceId: metadata?.instanceId,
+      channelType: metadata?.channelType,
+      personId: metadata?.personId,
+      platformIdentityId: metadata?.platformIdentityId,
+      traceId: metadata?.traceId ?? eventId,
+      source: metadata?.source ?? serviceName,
+      ingestMode: metadata?.ingestMode,
+      timings: metadata?.timings,
+      ...tenantId ? { envelopeVersion: CURRENT_ENVELOPE_VERSION, tenantId } : {}
+    }
+  };
+}
+var init_factory = __esm(() => {
+  init_causality();
+  init_envelope();
+});
+
 // ../core/src/events/nats/streams.ts
 function getStreamForEventType(eventType) {
   const prefix = eventType.split(".")[0] ?? "";
@@ -31176,27 +31221,8 @@ class NatsEventBus {
   }
   async publishInternal(type, payload, metadata) {
     await this.ensureConnected();
-    const eventId = crypto.randomUUID();
-    const timestamp = Date.now();
-    const tenantId = resolvePublishTenantId(metadata?.tenantId, metadata?.instanceId);
-    const event = {
-      id: eventId,
-      type,
-      payload,
-      timestamp,
-      metadata: {
-        correlationId: metadata?.correlationId ?? eventId,
-        instanceId: metadata?.instanceId,
-        channelType: metadata?.channelType,
-        personId: metadata?.personId,
-        platformIdentityId: metadata?.platformIdentityId,
-        traceId: metadata?.traceId ?? eventId,
-        source: metadata?.source ?? this.config.serviceName,
-        ingestMode: metadata?.ingestMode,
-        timings: metadata?.timings,
-        ...tenantId ? { envelopeVersion: CURRENT_ENVELOPE_VERSION, tenantId } : {}
-      }
-    };
+    const event = createOmniEvent(type, payload, metadata, this.config.serviceName);
+    const eventId = event.id;
     let subject;
     if (metadata?.channelType && metadata?.instanceId) {
       subject = buildSubject(type, metadata.channelType, metadata.instanceId);
@@ -31472,7 +31498,7 @@ async function connectEventBus(config2) {
 var import_api2, import_nats, log4, DEFAULTS, ENSURE_CONNECTED_WAIT_MS = 5000;
 var init_client = __esm(() => {
   init_logger();
-  init_envelope();
+  init_factory();
   init_consumer();
   init_registry();
   init_streams();
@@ -39465,6 +39491,7 @@ function estimateCompletion(progress) {
 // ../core/src/events/index.ts
 var init_events = __esm(() => {
   init_types3();
+  init_causality();
   init_envelope();
   init_nats();
   init_dead_letter();
@@ -45144,13 +45171,7 @@ function resolveFollowUpValue(trimmed, followUp) {
       return;
   }
 }
-function resolveTemplatePath(path, context) {
-  const trimmed = path.trim();
-  if (!trimmed)
-    return;
-  const parts = trimmed.split(".");
-  const root = parts[0] ?? "";
-  const rest = parts.slice(1).join(".");
+function resolveSpecialValue(trimmed, root, rest, context) {
   if (context.debounce) {
     const debounceValue = resolveDebounceValue(trimmed, rest, context.debounce);
     if (debounceValue !== undefined)
@@ -45161,6 +45182,21 @@ function resolveTemplatePath(path, context) {
     if (followUpValue !== undefined)
       return followUpValue;
   }
+  if (root === "event" && context.event) {
+    return rest ? getNestedValue(context.event, rest) : context.event;
+  }
+  return;
+}
+function resolveTemplatePath(path, context) {
+  const trimmed = path.trim();
+  if (!trimmed)
+    return;
+  const parts = trimmed.split(".");
+  const root = parts[0] ?? "";
+  const rest = parts.slice(1).join(".");
+  const specialValue = resolveSpecialValue(trimmed, root, rest, context);
+  if (specialValue !== undefined)
+    return specialValue;
   if (root === "payload")
     return rest ? getNestedValue(context.payload, rest) : context.payload;
   if (root === "env")
@@ -45242,7 +45278,9 @@ function createTemplateContext(payload, options = {}) {
     variables: options.variables ?? {},
     env: process.env,
     debounce: options.debounce,
-    followUp
+    followUp,
+    event: options.event,
+    automation: options.automation
   };
 }
 var TEMPLATE_REGEX;
@@ -45814,8 +45852,12 @@ var init_egress = __esm(() => {
 });
 
 // ../core/src/automations/actions.ts
-function buildWebhookHeaders(config2, context) {
+function buildWebhookHeaders(config2, context, actionIndex) {
   const headers = { "Content-Type": "application/json" };
+  if (context.event) {
+    headers["X-Omni-Event-Id"] = context.event.id;
+    headers["X-Omni-Delivery-Id"] = `${context.event.id}:${context.automation?.id ?? "manual"}:${actionIndex}`;
+  }
   if (config2.headers) {
     for (const [key, value] of Object.entries(config2.headers)) {
       headers[key] = substituteTemplate(value, context);
@@ -45823,16 +45865,28 @@ function buildWebhookHeaders(config2, context) {
   }
   return headers;
 }
+function buildDefaultWebhookBody(config2, context) {
+  if (context.event && config2.includeEnvelope !== false) {
+    return JSON.stringify({
+      id: context.event.id,
+      type: context.event.type,
+      payload: context.payload,
+      metadata: context.event.metadata,
+      timestamp: context.event.timestamp
+    });
+  }
+  return JSON.stringify(context.payload);
+}
 async function parseWebhookResponse(response) {
   const contentType = response.headers.get("content-type") ?? "";
   return contentType.includes("application/json") ? response.json() : response.text();
 }
-async function executeWebhookAction(config2, context, _deps, trustedTenantId) {
+async function executeWebhookAction(config2, context, _deps, trustedTenantId, actionIndex = 0) {
   try {
     const url = substituteTemplate(config2.url, context);
     const method = config2.method ?? "POST";
-    const headers = buildWebhookHeaders(config2, context);
-    const body = config2.bodyTemplate ? substituteTemplate(config2.bodyTemplate, context) : JSON.stringify(context.payload);
+    const headers = buildWebhookHeaders(config2, context, actionIndex);
+    const body = config2.bodyTemplate ? substituteTemplate(config2.bodyTemplate, context) : buildDefaultWebhookBody(config2, context);
     logger2.debug(`Webhook ${method} ${url}`, { method, url, waitForResponse: config2.waitForResponse });
     const response = await brokeredFetch(url, {
       method,
@@ -45922,8 +45976,10 @@ async function executeEmitEventAction(config2, context, deps, trustedTenantId) {
       }
     }
     logger2.debug("Emitting event", { eventType });
+    const correlationId = context.event?.metadata.correlationId ?? context.payload.correlationId ?? undefined;
     const result = await deps.eventBus.publishGeneric(eventType, payload, {
-      correlationId: context.payload.correlationId ?? undefined,
+      correlationId,
+      causationId: context.event?.id,
       source: "automation",
       ...trustedTenantId ? { tenantId: trustedTenantId } : {}
     });
@@ -46016,7 +46072,12 @@ function extractAgentCallContext(config2, context) {
       threadId,
       senderId,
       senderName,
-      messages: messagesResult
+      messages: messagesResult,
+      event: context.event ? {
+        id: context.event.id,
+        type: context.event.type,
+        correlationId: context.event.metadata.correlationId
+      } : undefined
     }
   };
 }
@@ -46057,12 +46118,12 @@ async function executeCallAgentAction(config2, context, deps, trustedTenantId) {
     return { success: false, error: errorMessage };
   }
 }
-async function executeAction(action, context, deps, trustedTenantId) {
+async function executeAction(action, context, deps, trustedTenantId, actionIndex = 0) {
   const start = Date.now();
   let result;
   switch (action.type) {
     case "webhook":
-      result = await executeWebhookAction(action.config, context, deps, trustedTenantId);
+      result = await executeWebhookAction(action.config, context, deps, trustedTenantId, actionIndex);
       break;
     case "send_message":
       result = await executeSendMessageAction(action.config, context, deps, trustedTenantId);
@@ -46091,12 +46152,12 @@ async function executeAction(action, context, deps, trustedTenantId) {
 async function executeActions(actions, context, deps, trustedTenantId) {
   const results = [];
   const variables = { ...context.variables };
-  for (const action of actions) {
+  for (const [actionIndex, action] of actions.entries()) {
     const actionContext = {
       ...context,
       variables
     };
-    const result = await executeAction(action, actionContext, deps, trustedTenantId);
+    const result = await executeAction(action, actionContext, deps, trustedTenantId, actionIndex);
     results.push(result);
     if (action.type === "webhook" && action.config.responseAs && result.status === "success" && result.result) {
       variables[action.config.responseAs] = result.result;
@@ -46526,13 +46587,18 @@ class AutomationEngine {
       type: content?.type ?? "unknown",
       text: content?.text,
       timestamp: event.timestamp,
-      payload
+      payload,
+      eventId: event.id,
+      correlationId: event.metadata.correlationId
     };
     manager.addMessage(key, message2, from, instanceId, stamp);
   }
   async handleImmediate(automation, event) {
     const instanceId = event.metadata.instanceId ?? "global";
-    const context = createTemplateContext(event.payload);
+    const context = createTemplateContext(event.payload, {
+      event: { id: event.id, type: event.type, timestamp: event.timestamp, metadata: event.metadata },
+      automation: { id: automation.id }
+    });
     await this.queueExecution(automation, event, context, instanceId);
   }
   setupDebounceManager(automation) {
@@ -46542,28 +46608,35 @@ class AutomationEngine {
         logger4.warn("Debounce callback fired with empty messages array", { key });
         return;
       }
-      const context = createTemplateContext(lastMessage.payload, {
-        debounce: {
-          messages: messages2.map((m2) => ({
-            type: m2.type,
-            text: m2.text,
-            timestamp: m2.timestamp
-          })),
-          from,
-          instanceId
-        }
-      });
       const syntheticEvent = {
         id: generateId(),
         type: automation.triggerEventType,
         payload: lastMessage.payload,
         metadata: {
-          correlationId: generateId(),
+          correlationId: lastMessage.correlationId ?? generateId(),
           instanceId,
           ...stamp ? { envelopeVersion: stamp.envelopeVersion, tenantId: stamp.tenantId } : {}
         },
         timestamp: Date.now()
       };
+      const context = createTemplateContext(lastMessage.payload, {
+        debounce: {
+          messages: messages2.map((m2) => ({
+            type: m2.type,
+            text: m2.text,
+            timestamp: m2.timestamp
+          })),
+          from,
+          instanceId
+        },
+        event: {
+          id: lastMessage.eventId ?? syntheticEvent.id,
+          type: syntheticEvent.type,
+          timestamp: syntheticEvent.timestamp,
+          metadata: syntheticEvent.metadata
+        },
+        automation: { id: automation.id }
+      });
       await this.queueExecution(automation, syntheticEvent, context, instanceId);
     };
     const manager = new DebounceManager(automation.debounce, callback);
@@ -46651,7 +46724,10 @@ class AutomationEngine {
         await this.logExecution(result2, trustedTenantId);
         return result2;
       }
-      const actionsExecuted = await executeActions(automation.actions, context, this.deps, trustedTenantId);
+      const actionsExecuted = await runWithEventCausality({
+        correlationId: context.event?.metadata.correlationId ?? event.metadata.correlationId,
+        causationId: context.event?.id ?? event.id
+      }, () => executeActions(automation.actions, context, this.deps, trustedTenantId));
       const allSucceeded = actionsExecuted.every((a) => a.status === "success");
       const status = allSucceeded ? "success" : "failed";
       const result = {
@@ -46747,6 +46823,7 @@ function createAutomationEngine(config2) {
 }
 var logger4, QueueFullError;
 var init_engine = __esm(() => {
+  init_causality();
   init_envelope();
   init_ids();
   init_logger();
@@ -74655,7 +74732,7 @@ function isProviderSchemaSupported(schema) {
 function getSupportedProviderSchemas() {
   return ["agno", "webhook", "openclaw", "claude-code", "ag-ui", "a2a", "nats-genie"];
 }
-var init_factory = __esm(() => {
+var init_factory2 = __esm(() => {
   init_a2a_client();
   init_ag_ui_client();
   init_agno_client();
@@ -74675,7 +74752,7 @@ var init_providers = __esm(() => {
   init_ag_ui_provider();
   init_a2a_provider();
   init_nats_genie_provider();
-  init_factory();
+  init_factory2();
 });
 
 // ../core/src/cache/types.ts
@@ -75359,6 +75436,7 @@ __export(exports_src, {
   scheduledJobRuns: () => scheduledJobRuns,
   scheduledJobNextRun: () => scheduledJobNextRun,
   scheduledJobDuration: () => scheduledJobDuration,
+  runWithEventCausality: () => runWithEventCausality,
   rootLogger: () => rootLogger,
   resolveResetConfig: () => resolveResetConfig,
   resolvePublishTenantId: () => resolvePublishTenantId,
@@ -75471,6 +75549,7 @@ __export(exports_src, {
   dbQueries: () => dbQueries,
   dbPoolSize: () => dbPoolSize,
   dbErrors: () => dbErrors,
+  currentEventCausality: () => currentEventCausality,
   createValidatedSubscription: () => createValidatedSubscription,
   createTemplateContext: () => createTemplateContext,
   createSubscription: () => createSubscription,
@@ -81878,9 +81957,11 @@ var init_schema2 = __esm(() => {
     agentRequest: jsonb("agent_request").$type(),
     agentResponse: jsonb("agent_response").$type(),
     metadata: jsonb("metadata").$type(),
+    causationId: uuid("causation_id"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     tenantId: uuid("tenant_id").references(() => tenants.id, { onDelete: "restrict" })
   }, (table3) => ({
+    causationIdx: index("omni_events_causation_idx").on(table3.causationId),
     tenantIdx: index("omni_events_tenant_idx").on(table3.tenantId),
     tenantIdUq: uniqueIndex("omni_events_tenant_id_uq").on(table3.tenantId, table3.id),
     externalIdIdx: index("omni_events_external_id_idx").on(table3.externalId),
@@ -136258,7 +136339,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "@automagik/omni",
-  version: "2.260906.3",
+  version: "2.260906.4",
   repository: {
     type: "git",
     url: "git+https://github.com/automagik-dev/omni.git",
@@ -142883,6 +142964,46 @@ ${title}:`);
   const items = Object.entries(record).sort(([, a], [, b2]) => b2 - a).map(([key, count]) => ({ [keyName]: key, count }));
   list(items);
 }
+async function fetchTrace(id) {
+  const config = loadConfig();
+  const baseUrl = config.apiUrl ?? "http://localhost:8882";
+  const resp = await fetch(`${baseUrl}/api/v2/events/${encodeURIComponent(id)}/trace`, {
+    headers: { "x-api-key": config.apiKey ?? "" }
+  });
+  if (!resp.ok) {
+    throw new Error(`API returned ${resp.status}: ${await resp.text()}`);
+  }
+  return (await resp.json()).data;
+}
+function formatTraceLine(event, marker) {
+  const time = new Date(event.receivedAt).toISOString().replace("T", " ").slice(0, 19);
+  const corr = event.metadata?.correlationId?.slice(0, 8) ?? "--------";
+  const text = event.textContent ? `  "${event.textContent.slice(0, 40)}"` : "";
+  return `${marker}${event.eventType}  ${event.id.slice(0, 8)}  ${time}  corr=${corr}${text}`;
+}
+function displayTrace(data2) {
+  if (getOutputFormat() === "json") {
+    data(data2);
+    return;
+  }
+  let indent = 0;
+  for (const ancestor of data2.ancestors) {
+    const label = indent === 0 && !ancestor.causationId ? " (root)" : "";
+    raw(`${"  ".repeat(indent)}${formatTraceLine(ancestor, indent === 0 ? "\u25CF " : "\u2514\u2500 ")}${label}`);
+    indent++;
+  }
+  const focusIsRoot = data2.ancestors.length === 0 && !data2.event.causationId;
+  raw(`${"  ".repeat(indent)}${formatTraceLine(data2.event, indent === 0 ? "\u25CF " : "\u2514\u2500 ")}${focusIsRoot ? " (root)" : ""}  \u2190 trace target`);
+  for (const { event, depth } of data2.descendants) {
+    raw(`${"  ".repeat(indent + depth)}${formatTraceLine(event, "\u2514\u2500 ")}`);
+  }
+  if (data2.descendants.length === 0) {
+    dim("(no descendants \u2014 nothing was caused by this event)");
+  }
+  if (data2.truncated) {
+    warn("Trace truncated (depth/node cap reached)");
+  }
+}
 async function schemaApiRequest(path, init = {}) {
   const config = loadConfig();
   const baseUrl = config.apiUrl ?? "http://localhost:8882";
@@ -143129,6 +143250,15 @@ function createEventsCommand() {
       error(`Failed to get event: ${message}`);
     }
   });
+  events.command("trace <id>").description("Walk the causality chain around an event: root \u2192 parents \u2192 this event \u2192 everything it caused").action(async (id) => {
+    try {
+      const data2 = await fetchTrace(id);
+      displayTrace(data2);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      error(`Failed to trace event: ${message}`);
+    }
+  });
   events.command("search <query>").description("Search events by content").option("--since <time>", "Events since (e.g., 24h, 7d)").option("--limit <n>", "Limit results", (v) => Number.parseInt(v, 10), 50).action(async (query, options) => {
     const client = getClient();
     try {