@mondaydotcomorg/z2h-shared-utils 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -0,0 +1,468 @@
+# CHANGELOG
+
+## `0.7.3` (October 5, 2026, 13:41)
+
+### Improvements
+
+- [#509](https://github.com/DaPulse/bigbrain-z2h/pull/509) refactor(z2h): move bucket and app-name constants to z2h-shared-utils (@eitan-ts)
+- Added: New `constants.ts` module exporting S3 bucket, manifest, skills, and app-name configuration constants that were previously only available from `@mondaydotcomorg/z2h-cli`. These constants are now part of the public API of this package.
+  *Usage:*
+  ```ts
+  import { BUCKET_WRITE_NAME, REGION, MANIFEST_KEY } from '@mondaydotcomorg/z2h-shared-utils';
+  ```
+- Added: `BUCKET_WRITE_NAME` constant (`'prod-use1-bigbrain-zth-mf-assets'`) for the S3 bucket used for writing Z2H microfrontend assets.
+- Added: `REGION` constant (`'us-east-1'`) for the AWS region of the Z2H asset bucket.
+- Added: `BUCKET_WRITE_URL` constant computed as `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazonaws.com` for direct S3 uploads.
+- Added: `BUCKET_READ_DNS_NAME` constant (`'bigbrain-zth-mf-assets'`) for the CloudFront/DNS-fronted bucket name.
+- Added: `BUCKET_READ_DNS_URL` constant (`https://${BUCKET_READ_DNS_NAME}.bigbrain.me`) for reading deployed assets via CDN.
+- Added: `S3_PREVIEWS_FOLDER` constant (`'previews'`) defining the root prefix for ephemeral preview uploads.
+- Added: `MANIFEST_KEY` constant (`'mf-assets'`) for the S3 key where the manifest JSON lives (without `.json` extension, as TridentSkeleton appends `/mf-assets` to the bucket base).
+- Added: `MANIFEST_READ_URL` constant computed as `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}` for fetching the production manifest.
+- Added: `S3_SKILLS_BUCKET_NAME` constant (`'prod-use1-bigbrain-zth-skills'`) for the read-only skills bucket used by the broker and agent.
+- Added: `DATAVIZ_SKILLS_PREFIX` constant (`'dataviz/'`) for the S3 prefix where data-cookbook publishes design-system skills.
+- Added: `APP_NAME_PATTERN` regular expression (`/^[a-z][a-z0-9-]{1,49}$/`) for validating Z2H app names (lowercase kebab-case, starts with a letter, 2-50 characters). The backend broker rejects names that don't match this pattern with HTTP 400.
+  *Usage:*
+  ```ts
+  import { APP_NAME_PATTERN } from '@mondaydotcomorg/z2h-shared-utils';
+  if (!APP_NAME_PATTERN.test(appName)) {
+    throw new Error('Invalid app name format');
+  }
+  ```
+- Added: `PREVIEW_APP_NAME_PREFIX` constant (`'zth-preview-'`) for the naming convention of preview deployments.
+- Changed: Package now exports all constants from the new `constants.ts` module via the main `index.ts` entry point.
+
+## `0.7.2` (October 1, 2026, 13:00)
+
+### Bug Fixes
+
+- [#494](https://github.com/DaPulse/bigbrain-z2h/pull/494) fix(z2h-cli): track only opted-in commands under enum event names (@arielmonday)
+- Added 8 new CLI event name constants to the `Z2hCliEvents` object: `deploySuccess` (`'z2h_app_deploy_success'`), `previewSuccess` (`'z2h_app_preview_success'`), `createSuccess` (`'z2h_app_created'`), `templatesSuccess` (`'z2h_cli_templates_success'`), `generateAppTemplateSuccess` (`'z2h_cli_generate_app_template_success'`), `editSuccess` (`'z2h_app_edit_pulled'`), `buildSuccess` (`'z2h_app_build_success'`), and `deleteSuccess` (`'z2h_app_delete_success'`).
+- Exported a new type `Z2hCliEventName` from `observability/events.ts` and `observability/index.ts`, defined as `(typeof Z2hCliEvents)[keyof typeof Z2hCliEvents]`. This type represents all valid CLI event names and is used in `z2h-cli` to enforce that the `event` field in `CommandSpec` only accepts known event names.
+  *Usage:*
+  ```ts
+  import { Z2hCliEvents, type Z2hCliEventName } from '@mondaydotcomorg/z2h-shared-utils/observability';
+  
+  function trackCommand(event: Z2hCliEventName) {
+    // event is constrained to Z2hCliEvents values
+  }
+  trackCommand(Z2hCliEvents.deploySuccess); // ✓
+  trackCommand('z2h_cli_unknown'); // ✗ Type error
+  ```
+
+## `0.7.1` (September 30, 2026, 09:49)
+
+### Improvements
+
+- [#488](https://github.com/DaPulse/bigbrain-z2h/pull/488) feat(z2h): sandbox run — backend invoke runs the local handler before deploy (@EranZidkiya)
+- Added: New `sandbox` entry in the `BackendRunnerEvents` object for observability of sandbox runs, including four new metric/event names: `successMetric: 'z2h.backend_sandbox.success'`, `failureMetric: 'z2h.backend_sandbox.error'`, `biEvent: 'z2h_backend_sandbox_run'`, and `channelCallMetric: 'z2h.backend_sandbox.channel_call'`.
+  *Usage:*
+  ```typescript
+  import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils';
+  // Access sandbox metrics:
+  const successMetric = BackendRunnerEvents.sandbox.successMetric; // 'z2h.backend_sandbox.success'
+  const channelMetric = BackendRunnerEvents.sandbox.channelCallMetric; // 'z2h.backend_sandbox.channel_call'
+  ```
+
+## `0.7.0` (September 30, 2026, 03:58)
+
+### New Features
+
+- [#478](https://github.com/DaPulse/bigbrain-z2h/pull/478) Feat/yarin/custom pat channel zth-runner channel integration (@yarinmonday)
+
+## `0.6.2` (September 17, 2026, 10:56)
+
+### Bug Fixes
+
+- [#445](https://github.com/DaPulse/bigbrain-z2h/pull/445) fix(bigbrain-zth-agent): add run-limit guards to stop stuck subagent loops before recursion crash (@arielmonday)
+- Added: New event constants in `Z2hAgentEvents` for tracking agent run limit hits. The `subagents.runLimitHit` event (`'z2h.subagents.run_limit_hit'`) fires when a subagent (cli-runner or general-purpose) reaches its configured call limit before hitting LangGraph's hard recursion limit. The `mainAgent.runLimitHit` event (`'z2h.main_agent.run_limit_hit'`) fires when the main agent hits LangGraph's hard recursion limit. These events enable Datadog metric emission for monitoring stuck loops that would otherwise cause crashes.
+  *Usage:*
+  ```ts
+  import { Z2hAgentEvents } from '@mondaydotcomorg/z2h-shared-utils';
+  
+  // Emit when subagent hits run limit
+  metrics.increment(Z2hAgentEvents.subagents.runLimitHit, { thread_id: threadId });
+  
+  // Emit when main agent hits hard limit
+  metrics.increment(Z2hAgentEvents.mainAgent.runLimitHit, { thread_id: threadId });
+  ```
+
+## `0.6.1` (September 16, 2026, 12:43)
+
+### Bug Fixes
+
+- [#447](https://github.com/DaPulse/bigbrain-z2h/pull/447) fix(z2h-shared-utils): stop eagerly loading trident-backend-api from root barrel (@eitan-ts)
+- **Breaking**: Removed `secrets/` module from the root barrel export (`src/index.ts`). The `secrets/` module statically imports `@mondaydotcomorg/trident-backend-api`, which is declared as an optional peer dependency. This eager re-export caused `MODULE_NOT_FOUND` errors in downstream packages like `z2h-cli` that import unrelated constants from the root barrel but do not have `trident-backend-api` installed. To access secrets functionality, consumers must now use the subpath export `@mondaydotcomorg/z2h-shared-utils/secrets` instead of importing from the package root.
+  *Before:*
+  ```ts
+  import { encryptSecret, decryptSecret } from '@mondaydotcomorg/z2h-shared-utils';
+  ```
+  *After:*
+  ```ts
+  import { encryptSecret, decryptSecret } from '@mondaydotcomorg/z2h-shared-utils/secrets';
+  ```
+- Fixed: Fresh global installations of `@mondaydotcomorg/z2h-cli` (versions ≥0.28.0) no longer crash with `MODULE_NOT_FOUND: Cannot find module '@mondaydotcomorg/trident-backend-api'` when running any CLI command. The CLI imports `ALWAYS_ON_CHANNELS` and `DECLARED_INTEGRATIONS` from `z2h-shared-utils` but never uses `trident-backend-api`, so the removed re-export eliminates the transitive static import that caused the crash.
+
+## `0.6.0` (September 16, 2026, 09:13)
+
+### New Features
+
+- [#426](https://github.com/DaPulse/bigbrain-z2h/pull/426) feat(z2h-cli): validate backend handlers with acorn AST (@eitan-ts)
+- Added: Backend channel constants and types exported from package root. `ALWAYS_ON_CHANNELS` is a readonly array `['db', 'llm', 'snowflake']` representing channels that need no OAuth and are never declared. `DECLARED_INTEGRATIONS` is a readonly array `['monday']` representing OAuth-gated integrations that must be declared.
+  *Usage:*
+  ```ts
+  import { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS, type AlwaysOnChannel, type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
+  ```
+- Added: `AlwaysOnChannel` type, a union of always-on channel names: `'db' | 'llm' | 'snowflake'`.
+- Added: `DeclaredIntegration` type, a union of declared integration names: `'monday'`.
+- Added: `handlerParseError` event constant (`'z2h_cli_handler_parse_error'`) to `Z2hCliEvents` object in `@mondaydotcomorg/z2h-shared-utils/observability/events`. This event is emitted by the CLI when a backend handler fails to parse.
+
+## `0.5.0` (September 15, 2026, 10:53)
+
+### New Features
+
+- [#435](https://github.com/DaPulse/bigbrain-z2h/pull/435) feat(z2h-shared-utils): add secret-cipher — AES-256-GCM encryption for PATs at rest (@yarinmonday)
+- Added: New `encryptSecret` function for encrypting plaintext secrets using AES-256-GCM encryption. The function returns a versioned encrypted blob string with embedded salt, IV, and authentication tag. The encryption key is derived via scrypt from a passphrase stored in the `z2h_secrets_key` configuration variable.
+  ```ts
+  import { encryptSecret } from '@mondaydotcomorg/z2h-shared-utils';
+  
+  const encrypted = encryptSecret('my-secret-token');
+  // Returns: 'v1:<iv>:<salt>:<tag>:<encrypted-data>' (all base64-encoded)
+  ```
+- Added: New `decryptSecret` function for decrypting encrypted secret blobs produced by `encryptSecret`. The function validates the blob format, version, and authentication tag before decrypting.
+  ```ts
+  import { decryptSecret } from '@mondaydotcomorg/z2h-shared-utils';
+  
+  const plaintext = decryptSecret(encryptedBlob);
+  // Returns: 'my-secret-token'
+  ```
+- Added: Internal key derivation caching mechanism that caches up to 256 derived keys by (passphrase-hash, salt) pairs to optimize repeated encryption/decryption operations without re-running scrypt.
+- Changed: Package now exports public API from `src/secrets/secret-cipher.ts` via the main entry point. Previously the package exported an empty object.
+  *Before:*
+  ```ts
+  // src/index.ts
+  export {};
+  ```
+  *After:*
+  ```ts
+  // src/index.ts
+  export * from './secrets';
+  ```
+- Added: Encryption scheme uses a versioned format (`v1:` prefix) to support future key rotation or algorithm changes without breaking existing encrypted blobs.
+- Added: The implementation enforces a full-length GCM authentication tag (16 bytes) to maintain 2^128 forgery resistance and prevent truncation attacks.
+- Added: Each encrypted blob includes a unique random 16-byte salt, ensuring that encrypting the same plaintext multiple times produces different ciphertext outputs.
+- Added: The passphrase source function reads from `Api.getPart('configurationVariables')?.get('z2h_secrets_key')` expecting a `{ key: string }` object structure. The `encryptSecret` and `decryptSecret` functions will throw an error if this configuration variable is not set.
+
+## `0.4.3` (September 9, 2026, 10:21)
+
+### Improvements
+
+- [#419](https://github.com/DaPulse/bigbrain-z2h/pull/419) feat(zth-backend-runner): emit a Datadog metric for the snowflake channel cache (@eitan-ts)
+- Added: New `cacheMetric` event constant (`'z2h.channel.snowflake.cache'`) to `BackendRunnerEvents.snowflake` for tracking Snowflake query cache hits and misses in Datadog. This metric is incremented by the snowflake channel with `appName` and `result` tags (`hit` or `miss`) to provide visibility into cache effectiveness.
+  *Usage:*
+  ```ts
+  import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils';
+  
+  // The new metric is available at:
+  BackendRunnerEvents.snowflake.cacheMetric // 'z2h.channel.snowflake.cache'
+  ```
+
+## Unreleased
+
+### Improvements
+
+- Added `BackendRunnerEvents.snowflake.cacheMetric` (`'z2h.channel.snowflake.cache'`) — a Datadog counter for the snowflake channel's Redis-backed query cache, tagged by `appName` and `result` (`hit`/`miss`), so cache effectiveness is visible in Datadog rather than only in the BI event.
+
+## `0.4.2` (September 8, 2026, 11:37)
+
+### Improvements
+
+- [#414](https://github.com/DaPulse/bigbrain-z2h/pull/414) feat(zth-backend-runner): emit per-channel success and failure telemetry (@eitan-ts)
+- Changed: Renamed `BackendRunnerEvents.invoke.succeeded` to `BackendRunnerEvents.invoke.successMetric` to clarify it emits a Datadog metric rather than a BI event.
+  *Before:*
+  ```ts
+  BackendRunnerEvents.invoke.succeeded // 'z2h.backend_invoke.success'
+  ```
+  *After:*
+  ```ts
+  BackendRunnerEvents.invoke.successMetric // 'z2h.backend_invoke.success'
+  ```
+
+- Changed: Renamed `BackendRunnerEvents.invoke.failed` to `BackendRunnerEvents.invoke.failureMetric` to clarify it emits a Datadog metric rather than a BI event.
+  *Before:*
+  ```ts
+  BackendRunnerEvents.invoke.failed // 'z2h.backend_invoke.error'
+  ```
+  *After:*
+  ```ts
+  BackendRunnerEvents.invoke.failureMetric // 'z2h.backend_invoke.error'
+  ```
+
+- Added: New `BackendRunnerEvents.invoke.biEvent` constant with value `'z2h_backend_invoke'` for tracking invoke outcomes via BI events.
+  *Usage:*
+  ```ts
+  BackendRunnerEvents.invoke.biEvent // 'z2h_backend_invoke'
+  ```
+
+- Added: New `BackendRunnerEvents.channel` section containing three telemetry constants for unified channel call tracking:
+  - `callMetric`: `'z2h.channel.call'` (Datadog metric for success/failure by app, channel, method)
+  - `durationMetric`: `'z2h.channel.duration_ms'` (Datadog metric for latency by app, channel, method)
+  - `biEvent`: `'z2h_channel_call'` (BI event with outcome field)
+  *Usage:*
+  ```ts
+  BackendRunnerEvents.channel.callMetric // 'z2h.channel.call'
+  BackendRunnerEvents.channel.durationMetric // 'z2h.channel.duration_ms'
+  BackendRunnerEvents.channel.biEvent // 'z2h_channel_call'
+  ```
+
+- Changed: Updated top-level JSDoc comment to clarify that `*Metric`-suffixed properties emit Datadog metrics via `metric.*` with bounded tags, while other properties are BI events sent via `trackEvent`. This distinguishes between the two telemetry destinations and their constraints.
+
+## Unreleased
+
+### Improvements
+
+- **Breaking**: Split `BackendRunnerEvents.invoke` into separate Datadog-metric and BI-event names, matching the `*Metric` / `biEvent` convention already used by `Z2hAgentEvents.toolCall`. `succeeded` is now `successMetric` and `failed` is now `failureMetric` (both keep their existing name strings), and the new `biEvent` (`'z2h_backend_invoke'`) replaces them as the BI event name. Success and failure are now distinguished by an `outcome` field on the event rather than by two separate event names, so analytics querying `z2h.backend_invoke.success` / `z2h.backend_invoke.error` as BI events must move to `z2h_backend_invoke` and filter on `outcome`.
+  *Before:*
+  ```ts
+  BackendRunnerEvents.invoke.succeeded; // 'z2h.backend_invoke.success'
+  BackendRunnerEvents.invoke.failed; // 'z2h.backend_invoke.error'
+  ```
+  *After:*
+  ```ts
+  BackendRunnerEvents.invoke.successMetric; // 'z2h.backend_invoke.success'  (Datadog)
+  BackendRunnerEvents.invoke.failureMetric; // 'z2h.backend_invoke.error'    (Datadog)
+  BackendRunnerEvents.invoke.biEvent; // 'z2h_backend_invoke'          (BI, has `outcome`)
+  ```
+- Added `BackendRunnerEvents.channel` constants for the unified per-channel call counter, duration distribution, and BI event. These names support success and failure rates grouped by app, channel, and method.
+
+## `0.4.1` (September 6, 2026, 09:22)
+
+### Improvements
+
+- [#372](https://github.com/DaPulse/bigbrain-z2h/pull/372) refactor(z2h-cli): single command wrapper for telemetry + bounded failure reasons (@eitan-ts)
+- **Breaking**: Changed `BackendRunnerEvents.invoke.succeeded` event name from `'z2h_backend_invoke_succeeded'` to `'z2h.backend_invoke.success'`. Update any code that references this event name constant or queries the old event name in analytics.
+  *Before:*
+  ```ts
+  BackendRunnerEvents.invoke.succeeded; // 'z2h_backend_invoke_succeeded'
+  ```
+  *After:*
+  ```ts
+  BackendRunnerEvents.invoke.succeeded; // 'z2h.backend_invoke.success'
+  ```
+- **Breaking**: Changed `BackendRunnerEvents.invoke.failed` event name from `'z2h_backend_invoke_failed'` to `'z2h.backend_invoke.error'`. Update any code that references this event name constant or queries the old event name in analytics.
+  *Before:*
+  ```ts
+  BackendRunnerEvents.invoke.failed; // 'z2h_backend_invoke_failed'
+  ```
+  *After:*
+  ```ts
+  BackendRunnerEvents.invoke.failed; // 'z2h.backend_invoke.error'
+  ```
+- Added: New `BackendRunnerEvents.integrationOAuth` object with three metric name constants: `revokeMetric` (`'z2h.integration_oauth.revoke'`), `revokeFailedMetric` (`'z2h.integration_oauth.revoke.error'`), and `tokenRequestMetric` (`'z2h.integration_oauth.token_request'`).
+- Added: New `BackendRunnerEvents.integrationToken` object with three metric name constants: `decryptFailedMetric` (`'z2h.integration_token.decrypt_failed'`), `unexpectedShapeMetric` (`'z2h.integration_token.unexpected_shape'`), and `refreshMetric` (`'z2h.integration_token.refresh'`).
+- Added: New `Z2hCliEvents` object exported from `@mondaydotcomorg/z2h-shared-utils/observability`, containing `error: 'z2h_cli_error'` for CLI error telemetry.
+- **Breaking**: `trackEvent` is no longer exported from the root `@mondaydotcomorg/z2h-shared-utils/observability` entry. It now requires the Trident runtime and is only available via the new `/observability/trident` subpath export.
+  *Before:*
+  ```ts
+  import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability';
+  ```
+  *After:*
+  ```ts
+  import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trident';
+  ```
+- Added: New `/observability/trident` subpath export for Trident-runtime-specific helpers. This subpath exports `trackEvent`, which depends on `@mondaydotcomorg/trident-backend-api`. Use the root `/observability` export for standalone processes (e.g., CLIs) that don't have the Trident runtime.
+- Changed: `createHttpTracker` now returns an object with two methods: `trackEvent` and `trackDuration`. Previously it returned only the `trackEvent` function.
+  *Before:*
+  ```ts
+  const trackEvent = createHttpTracker(deps);
+  await trackEvent('event_name', { data });
+  ```
+  *After:*
+  ```ts
+  const { trackEvent, trackDuration } = createHttpTracker(deps);
+  await trackEvent('event_name', { data });
+  await trackDuration('event_name', async () => { /* work */ }, { data });
+  ```
+- Added: New `HttpTracker` interface exported from `@mondaydotcomorg/z2h-shared-utils/observability`, defining the shape returned by `createHttpTracker`.
+  ```ts
+  interface HttpTracker {
+    trackEvent(name: string, data: Record<string, unknown>): Promise<void>;
+    trackDuration<T>(name: string, fn: () => Promise<T>, data?: Record<string, unknown>): Promise<T>;
+  }
+  ```
+- Changed: `trackDuration` method now included in the `HttpTracker` return value. It times the provided function and automatically sends a `duration_ms` dimension with the event. If the function throws, the event is not sent and the error propagates.
+- Changed: `trackEvent` in the Trident-runtime tracker (from `/observability/trident`) now returns `Promise<void>` instead of `void`, making it consistent with the HTTP tracker.
+- Changed: Trident-runtime tracker warning message simplified from "bigbrain API part unavailable, was Runtime.init() called? Dropping event." to "bigbrain API part unavailable. Dropping event."
+- Added: TypeScript `typesVersions` mapping for the new `/observability/trident` subpath export to support `moduleResolution: 'node'` (node10 resolution).
+
+## `0.4.0` (September 6, 2026, 07:21)
+
+### New Features
+
+- [#378](https://github.com/DaPulse/bigbrain-z2h/pull/378) feat(dashboard-templates): release the z2h-dashboard-templates package (@EranZidkiya)
+- Added: `dashboardTemplateHooks.ts` module defining TypeScript interfaces for dashboard template lifecycle hooks. These types enable templates to define custom transformation and setup logic that executes during dashboard generation.
+
+- Added: `DashboardTemplateSetupAPI` interface exposing a `createBackend(handlerName: string, content: string): void` method. This API is passed to setup hooks, allowing them to programmatically create backend handler files during generation.
+  *Usage example:*
+  ```ts
+  function setupBackend(config, setupAPI: DashboardTemplateSetupAPI) {
+    setupAPI.createBackend('widget_query_0', 'export default async function handler() { ... }');
+  }
+  ```
+
+- Added: `ToFrontendConfigHook<TConfig>` type alias for config transformation hooks. Functions of this type receive the raw config object and return a potentially modified config that will be embedded in the frontend bundle.
+  *Signature:*
+  ```ts
+  type ToFrontendConfigHook<TConfig = Record<string, unknown>> = (rawConfig: TConfig) => TConfig;
+  ```
+  *Usage example:*
+  ```ts
+  const toFrontendConfig: ToFrontendConfigHook<MyConfig> = (rawConfig) => {
+    // Strip server-only fields like SQL queries before bundling
+    return { ...rawConfig, widgets: rawConfig.widgets.map(w => omit(w, 'sql')) };
+  };
+  ```
+
+- Added: `SetupBackendHook<TConfig>` type alias for backend setup hooks. Functions of this type receive the raw config and the `DashboardTemplateSetupAPI`, enabling them to create backend handlers based on config data.
+  *Signature:*
+  ```ts
+  type SetupBackendHook<TConfig = Record<string, unknown>> = (
+    rawConfig: TConfig,
+    setupAPI: DashboardTemplateSetupAPI
+  ) => void;
+  ```
+  *Usage example:*
+  ```ts
+  const setupBackend: SetupBackendHook<DashboardConfig> = (config, setupAPI) => {
+    config.widgets.forEach((widget, i) => {
+      setupAPI.createBackend(`widget_query_${i}`, generateHandlerCode(widget.sql));
+    });
+  };
+  ```
+
+## `0.3.4` (September 3, 2026, 06:26)
+
+### Bug Fixes
+
+- [#403](https://github.com/DaPulse/bigbrain-z2h/pull/403) fix(z2h-shared-utils): preserve tracker this binding in trackEvent (@eitan-ts)
+- Fixed: `trackEvent` function now correctly preserves the `this` binding when calling `tracker.sendBiEvent`. Previously, the function destructured `sendBiEvent` off the tracker instance, which caused the method to lose its `this` context. Since `sendBiEvent` internally calls `this.sendBiEventAsync`, this resulted in crashes with "Cannot read properties of undefined (reading 'sendBiEventAsync')" on every invocation. The fix ensures `sendBiEvent` is called through the tracker instance instead of as a detached reference. This bug affected any Studio agent reply that invoked a tool (write, deploy, `ls`, etc.), as `toolTelemetryMiddleware` calls `trackEvent` on every tool call.
+  *Before (broken):*
+  ```ts
+  const sendBiEvent = Api.getPart('bigbrain')?.tracker?.sendBiEvent;
+  if (!sendBiEvent) { return; }
+  sendBiEvent({ name, source, data });
+  ```
+  *After (fixed):*
+  ```ts
+  const tracker = Api.getPart('bigbrain')?.tracker;
+  if (!tracker) { return; }
+  tracker.sendBiEvent({ name, source, data });
+  ```
+
+## `0.3.3` (September 2, 2026, 15:08)
+
+### Improvements
+
+- [#396](https://github.com/DaPulse/bigbrain-z2h/pull/396) feat(bigbrain-zth-agent): tool-call latency metric, cli-help gap counter, shared tracker (@eitan-ts)
+- Added: New `Z2hAgentEvents` constant exported from `observability` module, providing standardized event and metric names for the z2h agent. This constant includes `subagents.cliHelpUnavailable` for tracking CLI help availability issues, and `toolCall.softFailureMetric` and `toolCall.biEvent` for tool call telemetry.
+  *Usage:*
+  ```ts
+  import { Z2hAgentEvents } from '@mondaydotcomorg/z2h-shared-utils';
+  
+  // Track CLI help unavailability
+  metric.increment(Z2hAgentEvents.subagents.cliHelpUnavailable);
+  
+  // Track tool call soft failures
+  metric.increment(Z2hAgentEvents.toolCall.softFailureMetric);
+  
+  // Track tool call BI event
+  trackEvent(Z2hAgentEvents.toolCall.biEvent, eventData);
+  ```
+- Changed: Documentation comments for `BackendRunnerEvents` and `Z2hServiceEvents` constants have been simplified. `BackendRunnerEvents` comment changed from "BI events tracked via `trackEvent` in zth-backend-runner, grouped by emitter" to "BI events tracked in zth-backend-runner, grouped by domain". `Z2hServiceEvents` comment changed from "Metric names emitted by `bigbrain-zth` via `metric.increment`/`metric.distribution`, grouped by domain" to "Metric names emitted by `bigbrain-zth`, grouped by domain". These changes clarify the grouping approach and remove implementation details from the documentation.
+- Changed: The public API surface of the observability module now exports `Z2hAgentEvents` alongside the existing `BackendRunnerEvents` and `Z2hServiceEvents` exports.
+  *Before:*
+  ```ts
+  export { BackendRunnerEvents, Z2hServiceEvents } from './events';
+  ```
+  *After:*
+  ```ts
+  export { BackendRunnerEvents, Z2hServiceEvents, Z2hAgentEvents } from './events';
+  ```
+
+## `0.3.2` (September 2, 2026, 14:48)
+
+### Improvements
+
+- [#385](https://github.com/DaPulse/bigbrain-z2h/pull/385) feat(z2h-obs): app load-failure origin split + Snowflake telemetry alignment (@eitan-ts)
+
+## `0.3.1` (September 2, 2026, 14:20)
+
+### Improvements
+
+- [#393](https://github.com/DaPulse/bigbrain-z2h/pull/393) obs: emit BI events for backend-runner invoke/Snowflake, move shared to z2h-shared-utils (@eitan-ts)
+- **Breaking**: The main package entry point (`index.ts`) no longer re-exports observability utilities. Imports must now use the specific `/observability` subpath.
+  *Before:*
+  ```ts
+  import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils';
+  ```
+  *After:*
+  ```ts
+  import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability';
+  ```
+- **Added**: New `BackendRunnerEvents` constant that provides a centralized registry of BI event names tracked by the backend runner. This prevents string literal duplication and serves as a single source of truth for tracked events.
+  *Usage:*
+  ```ts
+  import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
+  trackEvent(BackendRunnerEvents.invoke.succeeded, { /* ... */ });
+  ```
+- **Added**: Event definitions for backend invoke lifecycle (`z2h_backend_invoke_succeeded`, `z2h_backend_invoke_failed`) to track handler execution outcomes in the BI pipeline.
+- **Added**: Event definition for Snowflake query execution (`z2h_snowflake_query_executed`) to track database query activity.
+- **Added**: Event definitions for LLM calls (`z2h_llm_call`) and integration flows (`z2h_integration_connect_started`, `z2h_integration_connected`, `z2h_integration_connect_declined`) to support future observability requirements across backend runner channels.
+
+## `0.3.0` (September 2, 2026, 11:05)
+
+### New Features
+
+- [#399](https://github.com/DaPulse/bigbrain-z2h/pull/399) refactor(z2h-cli): extract MF scaffold templates into z2h-shared-utils (@EranZidkiya)
+- Added: New `mfScaffold.ts` module exposing microfrontend scaffold templates via the `./mf-scaffold` subpath export. This module provides reusable template strings and functions for generating Trident MF wrapper code, configuration files, and TypeScript declarations.
+  *Usage:*
+  ```ts
+  import {
+    WRAPPER_TEMPLATE,
+    tridentrcTemplate,
+    dtsFileTemplate,
+    TSCONFIG_TEMPLATE,
+  } from '@mondaydotcomorg/z2h-shared-utils/mf-scaffold';
+  ```
+- Added: `WRAPPER_TEMPLATE` export — a complete React microfrontend wrapper template string with typed root management (`Map<HTMLElement, ReactDOM.Root>`), error boundary, and lifecycle methods (`init`, `render(element: HTMLElement)`, `unmount`).
+- Added: `tridentrcTemplate(appName: string, port: number): string` export — generates `.tridentrc.js` configuration content for a given app name and port.
+- Added: `dtsFileTemplate(): string` export — generates TypeScript declaration file content for common asset module types (CSS/SCSS modules, images, WASM, HTML, Rive files).
+- Added: `TSCONFIG_TEMPLATE` export — a complete TypeScript configuration object for microfrontend projects with `moduleResolution: "bundler"`, React JSX transform, and appropriate compiler options for Trident MF builds.
+
+## `0.2.0` (August 31, 2026, 08:25)
+
+### New Features
+
+- [#386](https://github.com/DaPulse/bigbrain-z2h/pull/386) feat(z2h-shared-utils): add shared utils package (observability/createTracker) (@eitan-ts)
+- Added: New package `@mondaydotcomorg/z2h-shared-utils` providing shared backend-microservice utilities, initially focused on observability/tracking capabilities.
+- Added: `trackEvent(name, data, source)` function for components running inside the Trident backend runtime (after `Runtime.init()`). Reads the live execution context via `Api.getPart('context')` from `@mondaydotcomorg/trident-backend-api` and automatically attaches the current user's name to all events. No-ops with a console warning if the bigbrain API part is unavailable, rather than throwing an error.
+  ```ts
+  import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils';
+  
+  trackEvent('feature_used', { feature: 'export' }, 'my-service');
+  // Automatically includes { user_name: '...' } from execution context
+  ```
+- Added: `createHttpTracker({ url, source, getContext })` factory function for standalone processes that never bootstrap the Trident runtime (e.g., CLI tools). Returns an async tracker function that posts events directly over HTTP instead of using the bigbrain API. Network errors and timeouts (5s) are silently swallowed to ensure tracking failures never interrupt the caller.
+  ```ts
+  import { createHttpTracker } from '@mondaydotcomorg/z2h-shared-utils';
+  
+  const trackEvent = createHttpTracker({
+    url: 'https://tracking.example.com/events',
+    source: 'z2h-cli',
+    getContext: () => ({ cli_version: '1.0.0' })
+  });
+  
+  await trackEvent('command_run', { command: 'deploy' });
+  // Posts: { name: 'command_run', source: 'z2h-cli', data: { cli_version: '1.0.0', command: 'deploy' } }
+  ```
+- Added: `HttpTrackerDeps` TypeScript interface defining the shape of dependencies for `createHttpTracker`: `url` (string), `source` (string), and `getContext` (function returning a record of context data).
+- Changed: Package structure uses `src/observability/` as a scoped directory to allow future unrelated shared utilities to coexist without organizational churn.

package/dist/constants.d.ts

@@ -10,4 +10,7 @@ export declare const S3_SKILLS_BUCKET_NAME = "prod-use1-bigbrain-zth-skills";
 export declare const DATAVIZ_SKILLS_PREFIX = "dataviz/";
 export declare const APP_NAME_PATTERN: RegExp;
 export declare const PREVIEW_APP_NAME_PREFIX = "zth-preview-";
+export declare const APP_USAGE_BUCKET_NAME = "de-integration-bigbrain";
+export declare const APP_USAGE_PREFIX = "prod/studio/entity=app_usage";
+export declare const appUsageFolder: (appName: string, appId: number) => string;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAGjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAI7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAG1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAGrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAGhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAGjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAI7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAG1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAGrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAGhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAGtD,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAC/D,eAAO,MAAM,gBAAgB,iCAAiC,CAAC;AAC/D,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,WAA8C,CAAC"}

package/dist/constants.js

@@ -18,8 +18,14 @@ const DATAVIZ_SKILLS_PREFIX = 'dataviz/';
 // Lowercase kebab-case, starts with a letter, 2-50 chars. Broker rejects anything else with 400.
 const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
+// Every object dropped under this prefix becomes one appended row in BIGBRAIN.L0.STUDIO_APP_USAGE.
+const APP_USAGE_BUCKET_NAME = 'de-integration-bigbrain';
+const APP_USAGE_PREFIX = 'prod/studio/entity=app_usage';
+const appUsageFolder = (appName, appId) => `${APP_USAGE_PREFIX}/${appName}_${appId}`;
 
 exports.APP_NAME_PATTERN = APP_NAME_PATTERN;
+exports.APP_USAGE_BUCKET_NAME = APP_USAGE_BUCKET_NAME;
+exports.APP_USAGE_PREFIX = APP_USAGE_PREFIX;
 exports.BUCKET_READ_DNS_NAME = BUCKET_READ_DNS_NAME;
 exports.BUCKET_READ_DNS_URL = BUCKET_READ_DNS_URL;
 exports.BUCKET_WRITE_NAME = BUCKET_WRITE_NAME;
@@ -31,3 +37,4 @@ exports.PREVIEW_APP_NAME_PREFIX = PREVIEW_APP_NAME_PREFIX;
 exports.REGION = REGION;
 exports.S3_PREVIEWS_FOLDER = S3_PREVIEWS_FOLDER;
 exports.S3_SKILLS_BUCKET_NAME = S3_SKILLS_BUCKET_NAME;
+exports.appUsageFolder = appUsageFolder;

package/dist/esm/constants.d.ts

@@ -10,4 +10,7 @@ export declare const S3_SKILLS_BUCKET_NAME = "prod-use1-bigbrain-zth-skills";
 export declare const DATAVIZ_SKILLS_PREFIX = "dataviz/";
 export declare const APP_NAME_PATTERN: RegExp;
 export declare const PREVIEW_APP_NAME_PREFIX = "zth-preview-";
+export declare const APP_USAGE_BUCKET_NAME = "de-integration-bigbrain";
+export declare const APP_USAGE_PREFIX = "prod/studio/entity=app_usage";
+export declare const appUsageFolder: (appName: string, appId: number) => string;
 //# sourceMappingURL=constants.d.ts.map

package/dist/esm/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAGjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAI7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAG1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAGrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAGhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAGjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAI7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAG1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAGrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAGhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAGtD,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAC/D,eAAO,MAAM,gBAAgB,iCAAiC,CAAC;AAC/D,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,WAA8C,CAAC"}

package/dist/esm/constants.mjs

@@ -16,5 +16,9 @@ const DATAVIZ_SKILLS_PREFIX = 'dataviz/';
 // Lowercase kebab-case, starts with a letter, 2-50 chars. Broker rejects anything else with 400.
 const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
+// Every object dropped under this prefix becomes one appended row in BIGBRAIN.L0.STUDIO_APP_USAGE.
+const APP_USAGE_BUCKET_NAME = 'de-integration-bigbrain';
+const APP_USAGE_PREFIX = 'prod/studio/entity=app_usage';
+const appUsageFolder = (appName, appId) => `${APP_USAGE_PREFIX}/${appName}_${appId}`;
 
-export { APP_NAME_PATTERN, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, MANIFEST_KEY, MANIFEST_READ_URL, PREVIEW_APP_NAME_PREFIX, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME };
+export { APP_NAME_PATTERN, APP_USAGE_BUCKET_NAME, APP_USAGE_PREFIX, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, MANIFEST_KEY, MANIFEST_READ_URL, PREVIEW_APP_NAME_PREFIX, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, appUsageFolder };

package/dist/esm/index.mjs

@@ -1,2 +1,2 @@
-export { APP_NAME_PATTERN, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, MANIFEST_KEY, MANIFEST_READ_URL, PREVIEW_APP_NAME_PREFIX, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME } from './constants.mjs';
+export { APP_NAME_PATTERN, APP_USAGE_BUCKET_NAME, APP_USAGE_PREFIX, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, MANIFEST_KEY, MANIFEST_READ_URL, PREVIEW_APP_NAME_PREFIX, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, appUsageFolder } from './constants.mjs';
 export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS } from './integrations.mjs';

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

@@ -78,6 +78,16 @@ export declare const Z2hAgentEvents: {
         readonly softFailureMetric: "z2h.agent_tool_call.soft_failure";
         readonly biEvent: "z2h_agent_tool_call";
     };
+    readonly asyncRun: {
+        readonly started: "z2h.agent_run.started";
+        readonly finished: "z2h.agent_run.finished";
+        readonly durationMs: "z2h.agent_run.duration_ms";
+        readonly sendMessageResponse: "z2h.send_message.response";
+        readonly busyRejected: "z2h.agent_run.busy_rejected";
+        readonly leaseHeartbeatFailed: "z2h.agent_run.lease_heartbeat_failed";
+        readonly redisUnavailable: "z2h.agent_run.redis_unavailable";
+        readonly statusPoll: "z2h.agent_status.poll";
+    };
 };
 /**
  * BI events tracked in `z2h-cli`. Every event the CLI sends is named here.

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;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;;;;;CAYjB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;CAWf,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;CAuBjB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;CAWf,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC"}

package/dist/esm/observability/events.mjs

@@ -78,6 +78,17 @@ const Z2hAgentEvents = {
         softFailureMetric: 'z2h.agent_tool_call.soft_failure',
         biEvent: 'z2h_agent_tool_call',
     },
+    // send_message / get_message_status wait-or-jobId flow (active-run lease in Redis).
+    asyncRun: {
+        started: 'z2h.agent_run.started',
+        finished: 'z2h.agent_run.finished',
+        durationMs: 'z2h.agent_run.duration_ms',
+        sendMessageResponse: 'z2h.send_message.response',
+        busyRejected: 'z2h.agent_run.busy_rejected',
+        leaseHeartbeatFailed: 'z2h.agent_run.lease_heartbeat_failed',
+        redisUnavailable: 'z2h.agent_run.redis_unavailable',
+        statusPoll: 'z2h.agent_status.poll',
+    },
 };
 /**
  * BI events tracked in `z2h-cli`. Every event the CLI sends is named here.

package/dist/index.js

@@ -6,6 +6,8 @@ const integrations = require('./integrations.js');
 
 
 exports.APP_NAME_PATTERN = constants.APP_NAME_PATTERN;
+exports.APP_USAGE_BUCKET_NAME = constants.APP_USAGE_BUCKET_NAME;
+exports.APP_USAGE_PREFIX = constants.APP_USAGE_PREFIX;
 exports.BUCKET_READ_DNS_NAME = constants.BUCKET_READ_DNS_NAME;
 exports.BUCKET_READ_DNS_URL = constants.BUCKET_READ_DNS_URL;
 exports.BUCKET_WRITE_NAME = constants.BUCKET_WRITE_NAME;
@@ -17,5 +19,6 @@ exports.PREVIEW_APP_NAME_PREFIX = constants.PREVIEW_APP_NAME_PREFIX;
 exports.REGION = constants.REGION;
 exports.S3_PREVIEWS_FOLDER = constants.S3_PREVIEWS_FOLDER;
 exports.S3_SKILLS_BUCKET_NAME = constants.S3_SKILLS_BUCKET_NAME;
+exports.appUsageFolder = constants.appUsageFolder;
 exports.ALWAYS_ON_CHANNELS = integrations.ALWAYS_ON_CHANNELS;
 exports.DECLARED_INTEGRATIONS = integrations.DECLARED_INTEGRATIONS;

package/dist/observability/events.d.ts

@@ -78,6 +78,16 @@ export declare const Z2hAgentEvents: {
         readonly softFailureMetric: "z2h.agent_tool_call.soft_failure";
         readonly biEvent: "z2h_agent_tool_call";
     };
+    readonly asyncRun: {
+        readonly started: "z2h.agent_run.started";
+        readonly finished: "z2h.agent_run.finished";
+        readonly durationMs: "z2h.agent_run.duration_ms";
+        readonly sendMessageResponse: "z2h.send_message.response";
+        readonly busyRejected: "z2h.agent_run.busy_rejected";
+        readonly leaseHeartbeatFailed: "z2h.agent_run.lease_heartbeat_failed";
+        readonly redisUnavailable: "z2h.agent_run.redis_unavailable";
+        readonly statusPoll: "z2h.agent_status.poll";
+    };
 };
 /**
  * BI events tracked in `z2h-cli`. Every event the CLI sends is named here.

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;;;;;CAYjB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;CAWf,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;CAuBjB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;CAWf,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC"}

package/dist/observability/events.js

@@ -80,6 +80,17 @@ const Z2hAgentEvents = {
         softFailureMetric: 'z2h.agent_tool_call.soft_failure',
         biEvent: 'z2h_agent_tool_call',
     },
+    // send_message / get_message_status wait-or-jobId flow (active-run lease in Redis).
+    asyncRun: {
+        started: 'z2h.agent_run.started',
+        finished: 'z2h.agent_run.finished',
+        durationMs: 'z2h.agent_run.duration_ms',
+        sendMessageResponse: 'z2h.send_message.response',
+        busyRejected: 'z2h.agent_run.busy_rejected',
+        leaseHeartbeatFailed: 'z2h.agent_run.lease_heartbeat_failed',
+        redisUnavailable: 'z2h.agent_run.redis_unavailable',
+        statusPoll: 'z2h.agent_status.poll',
+    },
 };
 /**
  * BI events tracked in `z2h-cli`. Every event the CLI sends is named here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-shared-utils",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -77,4 +77,4 @@
     "url": "https://github.com/DaPulse/bigbrain-z2h.git",
     "directory": "packages/z2h-shared-utils"
   }
-}
+}

package/src/constants.ts

@@ -23,3 +23,8 @@ export const DATAVIZ_SKILLS_PREFIX = 'dataviz/';
 export const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 
 export const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
+
+// Every object dropped under this prefix becomes one appended row in BIGBRAIN.L0.STUDIO_APP_USAGE.
+export const APP_USAGE_BUCKET_NAME = 'de-integration-bigbrain';
+export const APP_USAGE_PREFIX = 'prod/studio/entity=app_usage';
+export const appUsageFolder = (appName: string, appId: number) => `${APP_USAGE_PREFIX}/${appName}_${appId}`;

package/src/observability/events.ts

@@ -80,6 +80,17 @@ export const Z2hAgentEvents = {
     softFailureMetric: 'z2h.agent_tool_call.soft_failure',
     biEvent: 'z2h_agent_tool_call',
   },
+  // send_message / get_message_status wait-or-jobId flow (active-run lease in Redis).
+  asyncRun: {
+    started: 'z2h.agent_run.started',
+    finished: 'z2h.agent_run.finished',
+    durationMs: 'z2h.agent_run.duration_ms',
+    sendMessageResponse: 'z2h.send_message.response',
+    busyRejected: 'z2h.agent_run.busy_rejected',
+    leaseHeartbeatFailed: 'z2h.agent_run.lease_heartbeat_failed',
+    redisUnavailable: 'z2h.agent_run.redis_unavailable',
+    statusPoll: 'z2h.agent_status.poll',
+  },
 } as const;
 
 /**