@2en/clawly-plugins 1.26.0-beta.0 → 1.26.0

package/gateway/cron-telemetry.test.ts

@@ -0,0 +1,407 @@
+import {afterEach, beforeEach, describe, expect, mock, test} from 'bun:test'
+import type {PluginApi} from '../types'
+import {
+  markCronDelivered,
+  markCronDeliverySkipped,
+  markCronPushSent,
+  markCronPushSkipped,
+  registerCronTelemetry,
+} from './cron-telemetry'
+
+// ── Mock OTel logger ─────────────────────────────────────────────
+
+type LogRecord = {
+  severityNumber: number
+  severityText: string
+  body: string
+  attributes: Record<string, unknown>
+}
+
+let otelRecords: LogRecord[] = []
+
+let posthogEvents: {event: string; properties?: Record<string, unknown>}[] = []
+
+mock.module('@opentelemetry/api-logs', () => ({
+  SeverityNumber: {INFO: 9},
+}))
+
+mock.module('./posthog', () => ({
+  captureEvent: (event: string, properties?: Record<string, unknown>) =>
+    posthogEvents.push({event, properties}),
+}))
+
+mock.module('./otel', () => ({
+  getOtelLogger: () => ({
+    emit: (record: LogRecord) => otelRecords.push(record),
+  }),
+}))
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+type AfterToolCallHandler = (event: Record<string, unknown>) => void
+type AgentEndHandler = (event: Record<string, unknown>, ctx?: Record<string, unknown>) => void
+
+let afterToolCallHandler: AfterToolCallHandler
+let agentEndHandler: AgentEndHandler
+let logs: string[]
+
+function createMockApi(pluginConfig?: Record<string, unknown>): PluginApi {
+  logs = []
+  otelRecords = []
+  posthogEvents = []
+  return {
+    id: 'test',
+    name: 'Test',
+    pluginConfig,
+    runtime: {},
+    logger: {
+      info: (msg: string) => logs.push(msg),
+      warn: (msg: string) => logs.push(`WARN: ${msg}`),
+      error: (msg: string) => logs.push(`ERROR: ${msg}`),
+    },
+    registerGatewayMethod: () => {},
+    registerTool: () => {},
+    registerCommand: () => {},
+    registerChannel: () => {},
+    registerHttpRoute: () => {},
+    on: (hookName: string, handler: (...args: any[]) => any, _opts?: {priority?: number}) => {
+      if (hookName === 'after_tool_call') afterToolCallHandler = handler as AfterToolCallHandler
+      if (hookName === 'agent_end') agentEndHandler = handler as AgentEndHandler
+    },
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────
+
+describe('cron-telemetry', () => {
+  beforeEach(() => {
+    registerCronTelemetry(createMockApi({instanceId: 'inst-001'}))
+  })
+
+  describe('after_tool_call — cron add', () => {
+    test('captures job creation with id, name, and schedule', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {
+          action: 'add',
+          job: {name: 'daily-check', schedule: '0 9 * * *'},
+        },
+        result: {id: 'job-123'},
+      })
+
+      expect(logs.some((l) => l.includes('job created') && l.includes('job-123'))).toBe(true)
+      expect(logs.some((l) => l.includes('daily-check'))).toBe(true)
+      expect(logs.some((l) => l.includes('0 9 * * *'))).toBe(true)
+    })
+
+    test('emits OTel LogRecord with structured attributes', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {
+          action: 'add',
+          job: {name: 'daily-check', schedule: '0 9 * * *'},
+        },
+        result: {id: 'job-123'},
+      })
+
+      expect(otelRecords).toHaveLength(1)
+      const r = otelRecords[0]
+      expect(r.body).toBe('cron.lifecycle.created')
+      expect(r.attributes['cron.lifecycle']).toBe('created')
+      expect(r.attributes['cron.job.id']).toBe('job-123')
+      expect(r.attributes['cron.job.name']).toBe('daily-check')
+      expect(r.attributes['cron.job.schedule']).toBe('0 9 * * *')
+    })
+
+    test('handles missing job name and schedule', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {action: 'add', job: {}},
+        result: {id: 'job-456'},
+      })
+
+      expect(otelRecords).toHaveLength(1)
+      expect(otelRecords[0].attributes['cron.job.id']).toBe('job-456')
+      expect(otelRecords[0].attributes['cron.job.name']).toBeUndefined()
+      expect(otelRecords[0].attributes['cron.job.schedule']).toBeUndefined()
+    })
+
+    test('ignores non-cron tools', () => {
+      afterToolCallHandler({
+        toolName: 'other-tool',
+        params: {action: 'add'},
+        result: {id: 'x'},
+      })
+
+      expect(otelRecords).toHaveLength(0)
+    })
+
+    test('ignores cron tool with non-add action', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {action: 'list'},
+        result: {},
+      })
+
+      expect(otelRecords).toHaveLength(0)
+    })
+  })
+
+  describe('after_tool_call — cron remove', () => {
+    test('captures job deletion with structured attributes', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {action: 'remove', id: 'job-789'},
+      })
+
+      expect(logs.some((l) => l.includes('job deleted') && l.includes('job-789'))).toBe(true)
+      expect(otelRecords).toHaveLength(1)
+      expect(otelRecords[0].attributes['cron.lifecycle']).toBe('deleted')
+      expect(otelRecords[0].attributes['cron.job.id']).toBe('job-789')
+    })
+
+    test('handles jobId param variant', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {action: 'remove', jobId: 'job-abc'},
+      })
+
+      expect(otelRecords[0].attributes['cron.job.id']).toBe('job-abc')
+    })
+  })
+
+  describe('agent_end — cron execution', () => {
+    test('captures successful cron execution with structured attributes', () => {
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: 'agent:clawly:cron:job-123'})
+
+      expect(
+        logs.some(
+          (l) => l.includes('job executed') && l.includes('job-123') && l.includes('success=true'),
+        ),
+      ).toBe(true)
+      expect(otelRecords).toHaveLength(1)
+      const a = otelRecords[0].attributes
+      expect(a['cron.lifecycle']).toBe('executed')
+      expect(a['cron.job.id']).toBe('job-123')
+      expect(a['cron.execution.success']).toBe(true)
+      expect(a['cron.delivery.app_message_sent']).toBe(false)
+      expect(a['cron.delivery.push_notification_sent']).toBe(false)
+      expect(a['instance.id']).toBe('inst-001')
+    })
+
+    test('captures failed cron execution', () => {
+      agentEndHandler(
+        {messages: [], error: 'timeout'},
+        {trigger: 'cron', sessionKey: 'agent:clawly:cron:job-456'},
+      )
+
+      expect(otelRecords[0].attributes['cron.execution.success']).toBe(false)
+      expect(otelRecords[0].attributes['cron.execution.error']).toBe('timeout')
+    })
+
+    test('ignores non-cron sessions', () => {
+      agentEndHandler({messages: []}, {trigger: 'user', sessionKey: 'agent:clawly:main'})
+
+      expect(otelRecords).toHaveLength(0)
+    })
+
+    test('ignores missing sessionKey', () => {
+      agentEndHandler({messages: []}, {trigger: 'cron'})
+
+      expect(otelRecords).toHaveLength(0)
+    })
+
+    test('detects cron session by sessionKey prefix even without trigger field', () => {
+      agentEndHandler({messages: []}, {sessionKey: 'agent:clawly:cron:job-notrigger'})
+
+      expect(otelRecords).toHaveLength(1)
+      expect(otelRecords[0].attributes['cron.lifecycle']).toBe('executed')
+      expect(otelRecords[0].attributes['cron.job.id']).toBe('job-notrigger')
+    })
+
+    test('reports durationMs when present', () => {
+      agentEndHandler(
+        {messages: [], durationMs: 1500},
+        {trigger: 'cron', sessionKey: 'agent:clawly:cron:job-x'},
+      )
+
+      expect(otelRecords[0].attributes['cron.execution.duration_ms']).toBe(1500)
+      expect(logs.some((l) => l.includes('duration=1500ms'))).toBe(true)
+    })
+  })
+
+  describe('cross-hook coordination flags', () => {
+    test('markCronDelivered sets appMessage flag', () => {
+      const sk = 'agent:clawly:cron:job-d1'
+      markCronDelivered(sk)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      expect(otelRecords[0].attributes['cron.delivery.app_message_sent']).toBe(true)
+      expect(otelRecords[0].attributes['cron.delivery.push_notification_sent']).toBe(false)
+    })
+
+    test('markCronPushSent sets push flag', () => {
+      const sk = 'agent:clawly:cron:job-p1'
+      markCronPushSent(sk)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      expect(otelRecords[0].attributes['cron.delivery.push_notification_sent']).toBe(true)
+      expect(otelRecords[0].attributes['cron.delivery.app_message_sent']).toBe(false)
+    })
+
+    test('both flags set when both hooks fire', () => {
+      const sk = 'agent:clawly:cron:job-both'
+      markCronDelivered(sk)
+      markCronPushSent(sk)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      const a = otelRecords[0].attributes
+      expect(a['cron.delivery.app_message_sent']).toBe(true)
+      expect(a['cron.delivery.push_notification_sent']).toBe(true)
+    })
+
+    test('flags are cleaned up after consumption', () => {
+      const sk = 'agent:clawly:cron:job-cleanup'
+      markCronDelivered(sk)
+
+      // First call consumes
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      // Second call should have default flags
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+      expect(otelRecords[1].attributes['cron.delivery.app_message_sent']).toBe(false)
+    })
+  })
+
+  describe('agent.id attribute', () => {
+    test('includes agent.id from ctx on executed events', () => {
+      agentEndHandler(
+        {messages: []},
+        {trigger: 'cron', sessionKey: 'agent:clawly:cron:job-aid', agentId: 'agent-42'},
+      )
+
+      expect(otelRecords[0].attributes['agent.id']).toBe('agent-42')
+    })
+
+    test('omits agent.id when ctx has no agentId', () => {
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: 'agent:clawly:cron:job-noid'})
+
+      expect(otelRecords[0].attributes['agent.id']).toBeUndefined()
+    })
+  })
+
+  describe('client.online attribute', () => {
+    test('includes client.online when push is skipped with clientOnline', () => {
+      const sk = 'agent:clawly:cron:job-online'
+      markCronPushSkipped(sk, 'client online', true)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      expect(otelRecords[0].attributes['client.online']).toBe(true)
+    })
+
+    test('includes client.online=false when push is skipped offline', () => {
+      const sk = 'agent:clawly:cron:job-offline'
+      markCronPushSkipped(sk, 'filtered: empty assistant', false)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      expect(otelRecords[0].attributes['client.online']).toBe(false)
+    })
+
+    test('omits client.online when not set', () => {
+      agentEndHandler(
+        {messages: []},
+        {trigger: 'cron', sessionKey: 'agent:clawly:cron:job-noonline'},
+      )
+
+      expect(otelRecords[0].attributes['client.online']).toBeUndefined()
+    })
+  })
+
+  describe('skip reason attributes', () => {
+    test('delivery skip reason is present when delivery is skipped', () => {
+      const sk = 'agent:clawly:cron:job-dskip'
+      markCronDeliverySkipped(sk, 'no assistant message')
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      const a = otelRecords[0].attributes
+      expect(a['cron.delivery.app_message_sent']).toBe(false)
+      expect(a['cron.delivery.app_message_skip_reason']).toBe('no assistant message')
+    })
+
+    test('push skip reason is present when push is skipped', () => {
+      const sk = 'agent:clawly:cron:job-pskip'
+      markCronPushSkipped(sk, 'send failed', false)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      const a = otelRecords[0].attributes
+      expect(a['cron.delivery.push_notification_sent']).toBe(false)
+      expect(a['cron.delivery.push_skip_reason']).toBe('send failed')
+    })
+
+    test('no skip reasons when delivery and push succeed', () => {
+      const sk = 'agent:clawly:cron:job-success'
+      markCronDelivered(sk)
+      markCronPushSent(sk)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      const a = otelRecords[0].attributes
+      expect(a['cron.delivery.app_message_sent']).toBe(true)
+      expect(a['cron.delivery.app_message_skip_reason']).toBeUndefined()
+      expect(a['cron.delivery.push_notification_sent']).toBe(true)
+      expect(a['cron.delivery.push_skip_reason']).toBeUndefined()
+    })
+
+    test('delivery skipped + push sent is consistent', () => {
+      const sk = 'agent:clawly:cron:job-mixed'
+      markCronDeliverySkipped(sk, 'no agentId')
+      markCronPushSent(sk)
+
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: sk})
+
+      const a = otelRecords[0].attributes
+      expect(a['cron.delivery.app_message_sent']).toBe(false)
+      expect(a['cron.delivery.app_message_skip_reason']).toBe('no agentId')
+      expect(a['cron.delivery.push_notification_sent']).toBe(true)
+      expect(a['cron.delivery.push_skip_reason']).toBeUndefined()
+    })
+  })
+
+  describe('PostHog events', () => {
+    test('emits posthog event for cron created', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {action: 'add', job: {name: 'test'}},
+        result: {id: 'job-ph1'},
+      })
+
+      expect(posthogEvents).toHaveLength(1)
+      expect(posthogEvents[0].event).toBe('cron.created')
+      expect(posthogEvents[0].properties?.['cron.job.id']).toBe('job-ph1')
+    })
+
+    test('emits posthog event for cron executed', () => {
+      agentEndHandler({messages: []}, {trigger: 'cron', sessionKey: 'agent:clawly:cron:job-ph2'})
+
+      expect(posthogEvents).toHaveLength(1)
+      expect(posthogEvents[0].event).toBe('cron.executed')
+    })
+
+    test('emits posthog event for cron deleted', () => {
+      afterToolCallHandler({
+        toolName: 'cron',
+        params: {action: 'remove', id: 'job-ph3'},
+      })
+
+      expect(posthogEvents).toHaveLength(1)
+      expect(posthogEvents[0].event).toBe('cron.deleted')
+    })
+  })
+})

package/gateway/cron-telemetry.ts

@@ -0,0 +1,253 @@
+/**
+ * Cron lifecycle telemetry — captures creation, execution, and deletion
+ * events for cron jobs via the plugin hook system.
+ *
+ * Events are emitted as OTel LogRecords via @opentelemetry/sdk-logs when
+ * plugin telemetry config contains Axiom credentials.
+ * Human-readable logs are always emitted via api.logger regardless.
+ *
+ * Hooks:
+ * - after_tool_call — captures cron add/remove tool results
+ * - agent_end (priority 100) — captures cron execution outcomes
+ *   Runs after cron-delivery and offline-push so delivery/push flags are set.
+ *
+ * Cross-hook coordination:
+ * - markCronDelivered(sessionKey) — called by cron-delivery on successful inject
+ * - markCronDeliverySkipped(sessionKey, reason) — called by cron-delivery on skip
+ * - markCronPushSent(sessionKey) — called by offline-push on successful push
+ * - markCronPushSkipped(sessionKey, reason, clientOnline) — called by offline-push on skip
+ */
+
+import {SeverityNumber} from '@opentelemetry/api-logs'
+import type {PluginApi} from '../types'
+import {getOtelLogger} from './otel'
+import {captureEvent} from './posthog'
+import {readTelemetryPluginConfig} from './telemetry-config'
+
+// ── Structured telemetry attributes (OTel LogRecord) ────────────
+
+export type CronTelemetryAttributes = {
+  'cron.lifecycle': 'created' | 'executed' | 'deleted'
+  'cron.job.id': string
+  'cron.job.name'?: string
+  'cron.job.schedule'?: string
+  'cron.execution.success'?: boolean
+  'cron.execution.error'?: string
+  'cron.execution.duration_ms'?: number
+  'cron.delivery.app_message_sent'?: boolean
+  'cron.delivery.app_message_skip_reason'?: string
+  'cron.delivery.push_notification_sent'?: boolean
+  'cron.delivery.push_skip_reason'?: string
+  'instance.id'?: string
+  'agent.id'?: string
+  'client.online'?: boolean
+}
+
+// ── Cross-hook coordination flags ───────────────────────────────
+
+type CronRunFlags = {
+  delivered: boolean
+  deliverySkipReason?: string
+  pushSent: boolean
+  pushSkipReason?: string
+  clientOnline?: boolean
+  createdAt: number
+}
+
+const cronRunFlags = new Map<string, CronRunFlags>()
+
+/** Max age for flag entries (10 minutes). Safety net against leaks. */
+const FLAG_TTL_MS = 10 * 60 * 1000
+
+function getOrCreate(sessionKey: string): CronRunFlags {
+  let flags = cronRunFlags.get(sessionKey)
+  if (!flags) {
+    // Evict stale entries on insertion to bound map size
+    if (cronRunFlags.size >= 50) {
+      const now = Date.now()
+      for (const [key, val] of cronRunFlags) {
+        if (now - val.createdAt > FLAG_TTL_MS) cronRunFlags.delete(key)
+      }
+    }
+    flags = {delivered: false, pushSent: false, createdAt: Date.now()}
+    cronRunFlags.set(sessionKey, flags)
+  }
+  return flags
+}
+
+export function markCronDelivered(sessionKey: string) {
+  getOrCreate(sessionKey).delivered = true
+}
+
+export function markCronDeliverySkipped(sessionKey: string, reason: string) {
+  const flags = getOrCreate(sessionKey)
+  flags.delivered = false
+  flags.deliverySkipReason = reason
+}
+
+export function markCronPushSent(sessionKey: string) {
+  getOrCreate(sessionKey).pushSent = true
+}
+
+export function markCronPushSkipped(sessionKey: string, reason: string, clientOnline?: boolean) {
+  const flags = getOrCreate(sessionKey)
+  flags.pushSent = false
+  flags.pushSkipReason = reason
+  if (clientOnline != null) flags.clientOnline = clientOnline
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function extractJobId(sessionKey: string): string | null {
+  const prefix = 'agent:clawly:cron:'
+  if (!sessionKey.startsWith(prefix)) return null
+  return sessionKey.slice(prefix.length) || null
+}
+
+function emit(attributes: CronTelemetryAttributes, api: PluginApi) {
+  // Emit structured OTel LogRecord (if provider is initialized)
+  const otelLogger = getOtelLogger()
+  if (otelLogger) {
+    otelLogger.emit({
+      severityNumber: SeverityNumber.INFO,
+      severityText: 'INFO',
+      body: `cron.lifecycle.${attributes['cron.lifecycle']}`,
+      attributes: attributes as Record<string, unknown>,
+    })
+  }
+
+  // Emit PostHog event
+  captureEvent(`cron.${attributes['cron.lifecycle']}`, attributes as Record<string, unknown>)
+
+  // Always log human-readable summary
+  const a = attributes
+  switch (a['cron.lifecycle']) {
+    case 'created':
+      api.logger.info(
+        `cron-telemetry: job created jobId=${a['cron.job.id']}${a['cron.job.name'] ? ` name="${a['cron.job.name']}"` : ''}${a['cron.job.schedule'] ? ` schedule="${a['cron.job.schedule']}"` : ''}`,
+      )
+      break
+    case 'deleted':
+      api.logger.info(`cron-telemetry: job deleted jobId=${a['cron.job.id']}`)
+      break
+    case 'executed':
+      api.logger.info(
+        `cron-telemetry: job executed jobId=${a['cron.job.id']} success=${a['cron.execution.success']} appMessage=${a['cron.delivery.app_message_sent']} push=${a['cron.delivery.push_notification_sent']}${a['cron.execution.duration_ms'] != null ? ` duration=${a['cron.execution.duration_ms']}ms` : ''}`,
+      )
+      break
+  }
+}
+
+// ── Registration ─────────────────────────────────────────────────
+
+export function registerCronTelemetry(api: PluginApi) {
+  // 1. after_tool_call: capture cron add/remove
+  api.on('after_tool_call', (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    api.logger.info(
+      `cron-telemetry[debug]: after_tool_call fired toolName=${String(event.toolName)} params.action=${String((event.params as any)?.action)} ctx=${JSON.stringify(ctx ?? {})}`,
+    )
+    if (event.toolName !== 'cron') return
+
+    const params = (event.params ?? {}) as Record<string, unknown>
+    const result = event.result as Record<string, unknown> | undefined
+    api.logger.info(
+      `cron-telemetry[debug]: cron tool detected action=${String(params.action)} result=${JSON.stringify(result ?? null)} error=${String(event.error ?? 'none')}`,
+    )
+
+    if (params.action === 'add' && result) {
+      const job = (params.job ?? params) as Record<string, unknown>
+      const jobId =
+        typeof result.id === 'string'
+          ? result.id
+          : typeof result.jobId === 'string'
+            ? result.jobId
+            : 'unknown'
+      const jobName = typeof job.name === 'string' ? job.name : undefined
+      const schedule = typeof job.schedule === 'string' ? job.schedule : undefined
+
+      emit(
+        {
+          'cron.lifecycle': 'created',
+          'cron.job.id': jobId,
+          ...(jobName ? {'cron.job.name': jobName} : {}),
+          ...(schedule ? {'cron.job.schedule': schedule} : {}),
+        },
+        api,
+      )
+    }
+
+    if (params.action === 'remove') {
+      const jobId =
+        typeof params.id === 'string'
+          ? params.id
+          : typeof params.jobId === 'string'
+            ? params.jobId
+            : 'unknown'
+
+      emit({'cron.lifecycle': 'deleted', 'cron.job.id': jobId}, api)
+    }
+  })
+
+  // Read instance.id once at registration time
+  const instanceId =
+    readTelemetryPluginConfig(api.pluginConfig).instanceId ?? process.env.INSTANCE_ID
+
+  // 2. agent_end: capture cron execution (priority 100 = runs after delivery/push hooks)
+  api.on(
+    'agent_end',
+    (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+      const sessionKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey : undefined
+      api.logger.info(
+        `cron-telemetry[debug]: agent_end fired trigger=${String(ctx?.trigger ?? 'undefined')} sessionKey=${sessionKey ?? 'undefined'} agentId=${String(ctx?.agentId ?? 'undefined')} eventKeys=${Object.keys(event).join(',')}`,
+      )
+
+      // Detect cron sessions by sessionKey prefix (consistent with cron-delivery)
+      // instead of ctx.trigger which may not be set by all OpenClaw versions.
+      if (!sessionKey?.startsWith('agent:clawly:cron:')) return
+
+      const jobId = extractJobId(sessionKey)
+      if (!jobId) {
+        api.logger.info(
+          `cron-telemetry[debug]: agent_end skipped — extractJobId returned null for sessionKey=${sessionKey}`,
+        )
+        return
+      }
+
+      const agentId = typeof ctx.agentId === 'string' ? ctx.agentId : undefined
+      const flags: CronRunFlags = cronRunFlags.get(sessionKey) ?? {
+        delivered: false,
+        pushSent: false,
+      }
+      cronRunFlags.delete(sessionKey)
+
+      const success = event.error == null
+      const error = typeof event.error === 'string' ? event.error : undefined
+      const durationMs = typeof event.durationMs === 'number' ? event.durationMs : undefined
+
+      emit(
+        {
+          'cron.lifecycle': 'executed',
+          'cron.job.id': jobId,
+          'cron.execution.success': success,
+          ...(error ? {'cron.execution.error': error} : {}),
+          ...(durationMs != null ? {'cron.execution.duration_ms': durationMs} : {}),
+          'cron.delivery.app_message_sent': flags.delivered,
+          ...(flags.deliverySkipReason
+            ? {'cron.delivery.app_message_skip_reason': flags.deliverySkipReason}
+            : {}),
+          'cron.delivery.push_notification_sent': flags.pushSent,
+          ...(flags.pushSkipReason ? {'cron.delivery.push_skip_reason': flags.pushSkipReason} : {}),
+          ...(instanceId ? {'instance.id': instanceId} : {}),
+          ...(agentId ? {'agent.id': agentId} : {}),
+          ...(flags.clientOnline != null ? {'client.online': flags.clientOnline} : {}),
+        },
+        api,
+      )
+    },
+    {priority: 100},
+  )
+
+  api.logger.info(
+    'cron-telemetry: registered after_tool_call + agent_end hooks (debug-instrumented)',
+  )
+}