@mondaydotcomorg/z2h-shared-utils 0.3.2 → 0.3.4

package/dist/esm/observability/__tests__/tracker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tracker.test.d.ts.map

package/dist/esm/observability/__tests__/tracker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.test.d.ts","sourceRoot":"","sources":["../../../../src/observability/__tests__/tracker.test.ts"],"names":[],"mappings":""}

package/dist/esm/observability/events.d.ts

@@ -1,4 +1,4 @@
-/** BI events tracked via `trackEvent` in zth-backend-runner, grouped by emitter. */
+/** BI events tracked in zth-backend-runner, grouped by domain. */
 export declare const BackendRunnerEvents: {
     readonly invoke: {
         readonly succeeded: "z2h_backend_invoke_succeeded";
@@ -16,7 +16,7 @@ export declare const BackendRunnerEvents: {
         readonly connectDeclined: "z2h_integration_connect_declined";
     };
 };
-/** Metric names emitted by `bigbrain-zth` via `metric.increment`/`metric.distribution`, grouped by domain. */
+/** Metric names emitted by `bigbrain-zth`, grouped by domain. */
 export declare const Z2hServiceEvents: {
     readonly snowflake: {
         readonly queryDurationMs: "z2h_snowflake_query_duration_ms";
@@ -37,4 +37,14 @@ export declare const Z2hServiceEvents: {
         readonly captureFailed: "z2h_screenshot_capture_failed";
     };
 };
+/** Metric/event emitted by `bigbrain-zth-agent`. */
+export declare const Z2hAgentEvents: {
+    readonly subagents: {
+        readonly cliHelpUnavailable: "z2h.subagents.cli_help_unavailable";
+    };
+    readonly toolCall: {
+        readonly softFailureMetric: "z2h.agent_tool_call.soft_failure";
+        readonly biEvent: "z2h_agent_tool_call";
+    };
+};
 //# sourceMappingURL=events.d.ts.map

package/dist/esm/observability/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/observability/events.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;CAgBtB,CAAC;AAEX,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/observability/events.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;CAgBtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC"}

package/dist/esm/observability/events.mjs

@@ -1,4 +1,4 @@
-/** BI events tracked via `trackEvent` in zth-backend-runner, grouped by emitter. */
+/** BI events tracked in zth-backend-runner, grouped by domain. */
 const BackendRunnerEvents = {
     invoke: {
         succeeded: 'z2h_backend_invoke_succeeded',
@@ -16,7 +16,7 @@ const BackendRunnerEvents = {
         connectDeclined: 'z2h_integration_connect_declined',
     },
 };
-/** Metric names emitted by `bigbrain-zth` via `metric.increment`/`metric.distribution`, grouped by domain. */
+/** Metric names emitted by `bigbrain-zth`, grouped by domain. */
 const Z2hServiceEvents = {
     snowflake: {
         queryDurationMs: 'z2h_snowflake_query_duration_ms',
@@ -37,5 +37,15 @@ const Z2hServiceEvents = {
         captureFailed: 'z2h_screenshot_capture_failed',
     },
 };
+/** Metric/event emitted by `bigbrain-zth-agent`. */
+const Z2hAgentEvents = {
+    subagents: {
+        cliHelpUnavailable: 'z2h.subagents.cli_help_unavailable',
+    },
+    toolCall: {
+        softFailureMetric: 'z2h.agent_tool_call.soft_failure',
+        biEvent: 'z2h_agent_tool_call',
+    },
+};
 
-export { BackendRunnerEvents, Z2hServiceEvents };
+export { BackendRunnerEvents, Z2hAgentEvents, Z2hServiceEvents };

package/dist/esm/observability/index.d.ts

@@ -1,5 +1,5 @@
 export { trackEvent } from './tracker';
 export { createHttpTracker } from './httpTracker';
 export type { HttpTrackerDeps } from './httpTracker';
-export { BackendRunnerEvents, Z2hServiceEvents } from './events';
+export { BackendRunnerEvents, Z2hServiceEvents, Z2hAgentEvents } from './events';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/esm/observability/index.mjs

@@ -1,3 +1,3 @@
 export { trackEvent } from './tracker.mjs';
 export { createHttpTracker } from './httpTracker.mjs';
-export { BackendRunnerEvents, Z2hServiceEvents } from './events.mjs';
+export { BackendRunnerEvents, Z2hAgentEvents, Z2hServiceEvents } from './events.mjs';

package/dist/esm/observability/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../src/observability/tracker.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAU5F"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../src/observability/tracker.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAW5F"}

package/dist/esm/observability/tracker.mjs

@@ -13,13 +13,14 @@ function getUserContext() {
  * standalone processes (e.g. CLIs) that never bootstrap the Trident runtime.
  */
 function trackEvent(name, data, source) {
-    const sendBiEvent = Api.getPart('bigbrain')?.tracker?.sendBiEvent;
-    if (!sendBiEvent) {
+    const tracker = Api.getPart('bigbrain')?.tracker;
+    if (!tracker) {
         // eslint-disable-next-line no-console
         console.warn('[z2h-shared-utils] trackEvent: bigbrain API part unavailable, was Runtime.init() called? Dropping event.');
         return;
     }
-    sendBiEvent({ name, source, data: { ...getUserContext(), ...data } });
+    // Call through `tracker`, not a destructured reference — sendBiEvent relies on `this` internally.
+    tracker.sendBiEvent({ name, source, data: { ...getUserContext(), ...data } });
 }
 
 export { trackEvent };

package/dist/observability/__tests__/tracker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tracker.test.d.ts.map

package/dist/observability/__tests__/tracker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.test.d.ts","sourceRoot":"","sources":["../../../src/observability/__tests__/tracker.test.ts"],"names":[],"mappings":""}

package/dist/observability/events.d.ts

@@ -1,4 +1,4 @@
-/** BI events tracked via `trackEvent` in zth-backend-runner, grouped by emitter. */
+/** BI events tracked in zth-backend-runner, grouped by domain. */
 export declare const BackendRunnerEvents: {
     readonly invoke: {
         readonly succeeded: "z2h_backend_invoke_succeeded";
@@ -16,7 +16,7 @@ export declare const BackendRunnerEvents: {
         readonly connectDeclined: "z2h_integration_connect_declined";
     };
 };
-/** Metric names emitted by `bigbrain-zth` via `metric.increment`/`metric.distribution`, grouped by domain. */
+/** Metric names emitted by `bigbrain-zth`, grouped by domain. */
 export declare const Z2hServiceEvents: {
     readonly snowflake: {
         readonly queryDurationMs: "z2h_snowflake_query_duration_ms";
@@ -37,4 +37,14 @@ export declare const Z2hServiceEvents: {
         readonly captureFailed: "z2h_screenshot_capture_failed";
     };
 };
+/** Metric/event emitted by `bigbrain-zth-agent`. */
+export declare const Z2hAgentEvents: {
+    readonly subagents: {
+        readonly cliHelpUnavailable: "z2h.subagents.cli_help_unavailable";
+    };
+    readonly toolCall: {
+        readonly softFailureMetric: "z2h.agent_tool_call.soft_failure";
+        readonly biEvent: "z2h_agent_tool_call";
+    };
+};
 //# sourceMappingURL=events.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/observability/events.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;CAgBtB,CAAC;AAEX,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/observability/events.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;CAgBtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC"}

package/dist/observability/events.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-/** BI events tracked via `trackEvent` in zth-backend-runner, grouped by emitter. */
+/** BI events tracked in zth-backend-runner, grouped by domain. */
 const BackendRunnerEvents = {
     invoke: {
         succeeded: 'z2h_backend_invoke_succeeded',
@@ -18,7 +18,7 @@ const BackendRunnerEvents = {
         connectDeclined: 'z2h_integration_connect_declined',
     },
 };
-/** Metric names emitted by `bigbrain-zth` via `metric.increment`/`metric.distribution`, grouped by domain. */
+/** Metric names emitted by `bigbrain-zth`, grouped by domain. */
 const Z2hServiceEvents = {
     snowflake: {
         queryDurationMs: 'z2h_snowflake_query_duration_ms',
@@ -39,6 +39,17 @@ const Z2hServiceEvents = {
         captureFailed: 'z2h_screenshot_capture_failed',
     },
 };
+/** Metric/event emitted by `bigbrain-zth-agent`. */
+const Z2hAgentEvents = {
+    subagents: {
+        cliHelpUnavailable: 'z2h.subagents.cli_help_unavailable',
+    },
+    toolCall: {
+        softFailureMetric: 'z2h.agent_tool_call.soft_failure',
+        biEvent: 'z2h_agent_tool_call',
+    },
+};
 
 exports.BackendRunnerEvents = BackendRunnerEvents;
+exports.Z2hAgentEvents = Z2hAgentEvents;
 exports.Z2hServiceEvents = Z2hServiceEvents;

package/dist/observability/index.d.ts

@@ -1,5 +1,5 @@
 export { trackEvent } from './tracker';
 export { createHttpTracker } from './httpTracker';
 export type { HttpTrackerDeps } from './httpTracker';
-export { BackendRunnerEvents, Z2hServiceEvents } from './events';
+export { BackendRunnerEvents, Z2hServiceEvents, Z2hAgentEvents } from './events';
 //# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/observability/index.js

@@ -9,4 +9,5 @@ const observability_events = require('./events.js');
 exports.trackEvent = observability_tracker.trackEvent;
 exports.createHttpTracker = observability_httpTracker.createHttpTracker;
 exports.BackendRunnerEvents = observability_events.BackendRunnerEvents;
+exports.Z2hAgentEvents = observability_events.Z2hAgentEvents;
 exports.Z2hServiceEvents = observability_events.Z2hServiceEvents;

package/dist/observability/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/observability/tracker.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAU5F"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/observability/tracker.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAW5F"}

package/dist/observability/tracker.js

@@ -15,13 +15,14 @@ function getUserContext() {
  * standalone processes (e.g. CLIs) that never bootstrap the Trident runtime.
  */
 function trackEvent(name, data, source) {
-    const sendBiEvent = tridentBackendApi.Api.getPart('bigbrain')?.tracker?.sendBiEvent;
-    if (!sendBiEvent) {
+    const tracker = tridentBackendApi.Api.getPart('bigbrain')?.tracker;
+    if (!tracker) {
         // eslint-disable-next-line no-console
         console.warn('[z2h-shared-utils] trackEvent: bigbrain API part unavailable, was Runtime.init() called? Dropping event.');
         return;
     }
-    sendBiEvent({ name, source, data: { ...getUserContext(), ...data } });
+    // Call through `tracker`, not a destructured reference — sendBiEvent relies on `this` internally.
+    tracker.sendBiEvent({ name, source, data: { ...getUserContext(), ...data } });
 }
 
 exports.trackEvent = trackEvent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-shared-utils",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -29,6 +29,7 @@
     ]
   },
   "scripts": {
+    "test": "trident-library test",
     "build": "trident-library build",
     "watch": "trident-library build -w",
     "lint": "trident-library lint"
@@ -50,7 +51,8 @@
     "@mondaydotcomorg/trident-backend-api": "^0.24.3",
     "@mondaydotcomorg/trident-library": "^1.2.7",
     "@types/node": "^22.19.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
   },
   "engines": {
     "node": ">=24"

package/src/observability/__tests__/tracker.test.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { trackEvent } from '../tracker';
+
+const { getPartMock } = vi.hoisted(() => ({ getPartMock: vi.fn() }));
+vi.mock('@mondaydotcomorg/trident-backend-api', () => ({ Api: { getPart: getPartMock } }));
+
+/**
+ * Mirrors @mondaydotcomorg/bigbrain-tracker-node: sendBiEvent is a prototype method that
+ * delegates to this.sendBiEventAsync. A plain-object double would pass even when trackEvent
+ * detaches the method from its tracker, which is how that bug reached production —
+ * it only surfaces once Runtime.init() has supplied a real bigbrain part.
+ */
+class FakeTracker {
+  readonly sent: { name: string; source: string; data: Record<string, unknown> }[] = [];
+
+  async sendBiEventAsync(event: { name: string; source: string; data: Record<string, unknown> }): Promise<void> {
+    this.sent.push(event);
+  }
+
+  sendBiEvent(event: { name: string; source: string; data: Record<string, unknown> }): void {
+    void this.sendBiEventAsync(event);
+  }
+}
+
+function mockParts({ tracker, user }: { tracker?: FakeTracker; user?: { name: string } }) {
+  getPartMock.mockImplementation((part: string) => {
+    if (part === 'bigbrain') {
+      return tracker ? { tracker } : undefined;
+    }
+    if (part === 'context') {
+      return { execution: { get: () => (user ? { user } : undefined) } };
+    }
+    return undefined;
+  });
+}
+
+describe('trackEvent', () => {
+  beforeEach(() => {
+    getPartMock.mockReset();
+  });
+
+  it('sends the event through the tracker', () => {
+    const tracker = new FakeTracker();
+    mockParts({ tracker });
+
+    trackEvent('z2h_agent_tool_call', { tool_name: 'write_file' }, 'z2h-agent');
+
+    expect(tracker.sent).toEqual([
+      { name: 'z2h_agent_tool_call', source: 'z2h-agent', data: { tool_name: 'write_file' } },
+    ]);
+  });
+
+  it('attaches the current user to the event', () => {
+    const tracker = new FakeTracker();
+    mockParts({ tracker, user: { name: 'Arielle' } });
+
+    trackEvent('z2h_agent_tool_call', { tool_name: 'execute' }, 'z2h-agent');
+
+    expect(tracker.sent[0].data).toEqual({ user_name: 'Arielle', tool_name: 'execute' });
+  });
+
+  it('drops the event with a warning when the bigbrain part is unavailable', () => {
+    mockParts({});
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    expect(() => trackEvent('z2h_agent_tool_call', { tool_name: 'task' }, 'z2h-agent')).not.toThrow();
+
+    expect(warn).toHaveBeenCalledOnce();
+    warn.mockRestore();
+  });
+});

package/src/observability/events.ts

@@ -1,4 +1,4 @@
-/** BI events tracked via `trackEvent` in zth-backend-runner, grouped by emitter. */
+/** BI events tracked in zth-backend-runner, grouped by domain. */
 export const BackendRunnerEvents = {
   invoke: {
     succeeded: 'z2h_backend_invoke_succeeded',
@@ -17,7 +17,7 @@ export const BackendRunnerEvents = {
   },
 } as const;
 
-/** Metric names emitted by `bigbrain-zth` via `metric.increment`/`metric.distribution`, grouped by domain. */
+/** Metric names emitted by `bigbrain-zth`, grouped by domain. */
 export const Z2hServiceEvents = {
   snowflake: {
     queryDurationMs: 'z2h_snowflake_query_duration_ms',
@@ -38,3 +38,14 @@ export const Z2hServiceEvents = {
     captureFailed: 'z2h_screenshot_capture_failed',
   },
 } as const;
+
+/** Metric/event emitted by `bigbrain-zth-agent`. */
+export const Z2hAgentEvents = {
+  subagents: {
+    cliHelpUnavailable: 'z2h.subagents.cli_help_unavailable',
+  },
+  toolCall: {
+    softFailureMetric: 'z2h.agent_tool_call.soft_failure',
+    biEvent: 'z2h_agent_tool_call',
+  },
+} as const;

package/src/observability/index.ts

@@ -1,4 +1,4 @@
 export { trackEvent } from './tracker';
 export { createHttpTracker } from './httpTracker';
 export type { HttpTrackerDeps } from './httpTracker';
-export { BackendRunnerEvents, Z2hServiceEvents } from './events';
+export { BackendRunnerEvents, Z2hServiceEvents, Z2hAgentEvents } from './events';

package/src/observability/tracker.ts

@@ -15,13 +15,14 @@ function getUserContext(): { user_name?: string } {
  * standalone processes (e.g. CLIs) that never bootstrap the Trident runtime.
  */
 export function trackEvent(name: string, data: Record<string, unknown>, source: string): void {
-  const sendBiEvent = Api.getPart('bigbrain')?.tracker?.sendBiEvent;
-  if (!sendBiEvent) {
+  const tracker = Api.getPart('bigbrain')?.tracker;
+  if (!tracker) {
     // eslint-disable-next-line no-console
     console.warn(
       '[z2h-shared-utils] trackEvent: bigbrain API part unavailable, was Runtime.init() called? Dropping event.'
     );
     return;
   }
-  sendBiEvent({ name, source, data: { ...getUserContext(), ...data } });
+  // Call through `tracker`, not a destructured reference — sendBiEvent relies on `this` internally.
+  tracker.sendBiEvent({ name, source, data: { ...getUserContext(), ...data } });
 }