deepline 0.3.88 → 0.3.89

package/dist/bundling-sources/shared_libs/monitors/tracking-provider-guidance.ts

@@ -0,0 +1,73 @@
+import type { ProviderMonitorPostDeployGuidance } from '@deepline/monitors/provider-monitor-capability';
+
+// Client-safe provider setup metadata. Provider monitor definitions reference
+// these exact objects, while the integrations dialog reads them directly.
+export const VECTOR_POST_DEPLOY_GUIDANCE = {
+  title: 'Connect Vector to this monitor',
+  steps: [
+    'In Vector, open the segment named in this monitor setup.',
+    'Add a webhook endpoint using {{callback_url}}, then select contact.visited.',
+    'Enable the webhook action on the segment and send a Vector test event.',
+  ],
+  event_type: 'contact.visited',
+  documentation: [
+    {
+      label: 'Vector SiteID action integration guide',
+      url: 'https://learn.vector.co/articles/2260541690-building-an-action-integration-for-siteid',
+    },
+  ],
+  payload_example: {
+    type: 'contact.visited',
+    externalId: 'contact_123',
+    companyDomain: 'example.com',
+  },
+} as const satisfies ProviderMonitorPostDeployGuidance;
+
+export const RB2B_POST_DEPLOY_GUIDANCE = {
+  title: 'Connect RB2B to this monitor',
+  steps: [
+    'In RB2B, open Integrations and choose Webhook.',
+    'Paste {{callback_url}} as the single webhook URL and save.',
+    "Use RB2B's Send a Test Event action to verify the connection.",
+  ],
+  documentation: [
+    {
+      label: 'RB2B webhook setup guide',
+      url: 'https://support.rb2b.com/en/articles/8976614-setup-guide-webhook',
+    },
+  ],
+  payload_example: {
+    'LinkedIn URL': 'https://www.linkedin.com/in/example',
+    Website: 'https://example.com',
+  },
+} as const satisfies ProviderMonitorPostDeployGuidance;
+
+export const SNITCHER_POST_DEPLOY_GUIDANCE = {
+  title: 'Install Deepline Analytics',
+  steps: [
+    'Create the tracker code in Deepline, then paste it in your site’s document head.',
+    'Confirm cookie consent before persistent tracking when your privacy policy requires it.',
+  ],
+  documentation: [
+    {
+      label: 'Deepline Analytics setup guide',
+      url: 'https://docs.snitcher.com/powered-by-snitcher/radar/installation',
+    },
+  ],
+  payload_example: {
+    session_uuid: '00000000-0000-4000-8000-000000000001',
+    start_time: '2026-01-01T00:00:00.000Z',
+    last_activity: '2026-01-01T00:01:00.000Z',
+    engagement_time: 60,
+    user_properties: { $uuid: 'deepline-test-visitor' },
+    events: [
+      { event_name: '$pageview', created_at: '2026-01-01T00:00:00.000Z' },
+    ],
+  },
+} as const satisfies ProviderMonitorPostDeployGuidance;
+
+export const TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE = {
+  vector: VECTOR_POST_DEPLOY_GUIDANCE,
+  rb2b: RB2B_POST_DEPLOY_GUIDANCE,
+  snitcher: SNITCHER_POST_DEPLOY_GUIDANCE,
+} as const;

package/dist/bundling-sources/shared_libs/monitors/tracking-provider-integrations.ts

@@ -0,0 +1,81 @@
+import { TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE } from '@deepline/monitors/tracking-provider-guidance';
+import {
+  ANALYTICS_INTEGRATION_SLUG,
+  ANALYTICS_PUBLIC_TOOL,
+} from '@/lib/analytics/public';
+
+export const TRACKING_PROVIDER_INTEGRATIONS = {
+  vector: {
+    provider: 'vector',
+    displayName: 'Vector',
+    tool: 'vector.visitor_events',
+    monitorKey: 'vector-high-intent-visitors',
+  },
+  rb2b: {
+    provider: 'rb2b',
+    displayName: 'RB2B',
+    tool: 'rb2b.visitor_events',
+    monitorKey: 'rb2b-website-visitors',
+  },
+  [ANALYTICS_INTEGRATION_SLUG]: {
+    provider: 'snitcher',
+    displayName: 'Deepline Analytics',
+    // Used only by the server-side monitor adapter to resolve upstream wiring.
+    tool: 'snitcher.website_sessions',
+    publicTool: ANALYTICS_PUBLIC_TOOL,
+    monitorKey: 'snitcher-website-sessions',
+  },
+} as const;
+
+export type TrackingProviderIntegration =
+  (typeof TRACKING_PROVIDER_INTEGRATIONS)[keyof typeof TRACKING_PROVIDER_INTEGRATIONS] & {
+    docsUrl: string;
+    docsLabel: string;
+  };
+
+export function getTrackingProviderIntegration(
+  provider: string,
+): TrackingProviderIntegration | null {
+  const integration =
+    TRACKING_PROVIDER_INTEGRATIONS[
+      provider as keyof typeof TRACKING_PROVIDER_INTEGRATIONS
+    ];
+  if (!integration) return null;
+  const docs =
+    TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE[
+      integration.provider as keyof typeof TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE
+    ]?.documentation[0];
+  if (!docs) return null;
+  return { ...integration, docsUrl: docs.url, docsLabel: docs.label };
+}
+
+export function trackingProviderWebhookSetup(
+  provider: string,
+  webhookEndpoint: string,
+): {
+  webhook_endpoint: string;
+  event_type?: 'contact.visited';
+  instructions: string[];
+} | null {
+  const integration = getTrackingProviderIntegration(
+    provider === 'snitcher' ? ANALYTICS_INTEGRATION_SLUG : provider,
+  );
+  const guidance = integration
+    ? TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE[
+        integration.provider as keyof typeof TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE
+      ]
+    : null;
+  if (!guidance) return null;
+  return {
+    webhook_endpoint: webhookEndpoint,
+    ...('event_type' in guidance && guidance.event_type === 'contact.visited'
+      ? { event_type: guidance.event_type }
+      : {}),
+    // The dialog shows the URL in a dedicated copy target, so retain its
+    // compact `webhook_endpoint` wording while deriving every step from the
+    // same metadata used by CLI/API guidance.
+    instructions: guidance.steps.map((step) =>
+      step.replaceAll('{{callback_url}}', 'webhook_endpoint'),
+    ),
+  };
+}

package/dist/bundling-sources/shared_libs/monitors/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "incremental": false,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/dist/bundling-sources/shared_libs/play-runtime/activity-observation.ts

@@ -101,7 +101,11 @@ export type PlayActivityState =
     };
 
 export type PlayActivityObservation = {
-  schemaVersion: 1;
+  /**
+   * Retired marker. Producers stopped writing it; envelopes still in flight
+   * from an older producer carry `1`, so readers tolerate both shapes.
+   */
+  schemaVersion?: 1;
   /** Stable within one run, for example `tool:discover_ctos` or `dataset:leads`. */
   activityId: string;
   /** Optional owning play step. */
@@ -126,7 +130,7 @@ export function isPlayActivityObservation(
 ): value is PlayActivityObservation {
   if (
     !isRecord(value) ||
-    value.schemaVersion !== 1 ||
+    (value.schemaVersion !== undefined && value.schemaVersion !== 1) ||
     typeof value.activityId !== 'string' ||
     !value.activityId.trim() ||
     typeof value.observedAt !== 'number' ||
@@ -316,7 +320,6 @@ export function createPlayActivityReporter(input: {
         type: 'activity.observed',
         observation: {
           ...observation,
-          schemaVersion: 1,
           observedAt: observation.observedAt ?? input.now?.() ?? Date.now(),
         },
       });
@@ -402,7 +405,6 @@ export function projectPlayRunActivity(input: {
   if (input.waitKind === 'detached_runner') {
     return projection(
       {
-        schemaVersion: 1,
         activityId: 'runner:managed',
         target: {
           kind: 'runner',
@@ -418,7 +420,6 @@ export function projectPlayRunActivity(input: {
   if (input.waitKind === 'sleep') {
     return projection(
       {
-        schemaVersion: 1,
         activityId: 'run:sleep',
         target: {
           kind: 'step',
@@ -441,7 +442,6 @@ export function projectPlayRunActivity(input: {
   ) {
     return projection(
       {
-        schemaVersion: 1,
         activityId: `event:${input.activeNodeId ?? 'run'}`,
         stepId: input.activeNodeId ?? undefined,
         target: {
@@ -468,7 +468,6 @@ export function projectPlayRunActivity(input: {
   if (normalizedStatus === 'waiting') {
     return projection(
       {
-        schemaVersion: 1,
         activityId: 'run:legacy-wait',
         target: {
           kind: 'step',
@@ -506,7 +505,6 @@ export function projectPlayRunActivity(input: {
     const datasetProgress = datasetStep?.progress ?? null;
     return projection(
       {
-        schemaVersion: 1,
         activityId: `dataset:${pendingDataset.datasetId ?? pendingDataset.tableNamespace}`,
         target: {
           kind: 'dataset',
@@ -548,7 +546,6 @@ export function projectPlayRunActivity(input: {
     const provider = toolId?.split(/[._]/)[0]?.trim() || null;
     return projection(
       {
-        schemaVersion: 1,
         activityId: `step:${activeStep.nodeId}`,
         stepId: activeStep.nodeId,
         target:
@@ -577,7 +574,6 @@ export function projectPlayRunActivity(input: {
   if (normalizedStatus === 'queued') {
     return projection(
       {
-        schemaVersion: 1,
         activityId: 'capacity:worker',
         target: { kind: 'capacity', pool: 'worker' },
         state: { kind: 'queued', reason: 'capacity' },
@@ -588,7 +584,6 @@ export function projectPlayRunActivity(input: {
   }
 
   const fallback: PlayActivityObservation = {
-    schemaVersion: 1,
     activityId: 'run:legacy',
     target: {
       kind: 'step',

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -4,6 +4,7 @@ import { stat } from 'node:fs/promises';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import type { PlaySheetContract } from '../plays/static-pipeline';
+import type { AsyncPlayRunRef } from '../plays/authoring-contract';
 import type { PlayRowUpdate } from './/ctx-types';
 import type { PlayRunTimelineEntry } from './/live-events';
 import type { PlayDatasetBornFrom } from './/cell-provenance';
@@ -179,6 +180,51 @@ type RuntimeApiRequest =
       runId: string;
       firstClaimLatencyMs: number;
     }
+  | {
+      action: 'launch_play_async';
+      key: string;
+      invocationKey: string;
+      playRef: string;
+      input: Record<string, unknown>;
+      description: string;
+      schedulerSchema?: string | null;
+      ancestryPlayIds: string[];
+    }
+  | {
+      action: 'project_run_created';
+      idempotencyKey: string;
+      playName: string;
+      playReference?: string | null;
+      workflowId: string;
+      runId: string;
+      workflowFamilyKey: string;
+      definitionScope?: 'org' | 'system';
+      revisionId?: string | null;
+      artifactStorageKey?: string | null;
+      artifactHash?: string | null;
+      graphHash?: string | null;
+      runtimeBackend?: string | null;
+      schedulerBackend?: string | null;
+      schedulerSchema?: string | null;
+      executionProfile?: string | null;
+      runtimeReleaseId?: string | null;
+      runtimeDeployVersion?: string | null;
+      runtimeCallbackBaseUrl?: string | null;
+      coordinatorUrl?: string | null;
+      coordinatorWorkerName?: string | null;
+      runtimeWorkflowName?: string | null;
+      runtimeHarnessWorkerName?: string | null;
+      maxCreditsPerRun?: number | null;
+      staticPipeline?: unknown;
+      source?: 'published' | 'ad_hoc' | 'draft';
+      triggerSource?: 'webhook' | 'cron' | 'sql_listener' | 'api';
+      inputFileId?: string;
+      inputBytes?: number;
+      inputSha256?: string;
+      replayedFromRunId?: string | null;
+      secretRefs?: unknown[];
+      inputSummary?: Record<string, unknown>;
+    }
   | ({
       action: 'save_results';
     } & RuntimeSaveResults)
@@ -719,7 +765,8 @@ function isRetryableAppRuntimeAction(
     action === 'release_runtime_step_receipt' ||
     action === 'save_results' ||
     action === 'skip_runtime_step_receipt' ||
-    action === 'start_run'
+    action === 'start_run' ||
+    action === 'launch_play_async'
   );
 }
 
@@ -1073,7 +1120,8 @@ export class AppRuntimeApiResponseError extends Error {
     this.requestId = input.requestId?.trim() || null;
     this.retryable = input.retryable;
     this.retryAfterMs =
-      typeof input.retryAfterMs === 'number' && Number.isFinite(input.retryAfterMs)
+      typeof input.retryAfterMs === 'number' &&
+      Number.isFinite(input.retryAfterMs)
         ? Math.max(0, Math.floor(input.retryAfterMs))
         : null;
     this.detail = input.detail;
@@ -1963,16 +2011,14 @@ export async function appendRunEventsViaAppRuntime(
   let terminalBatchIndex = -1;
   for (let index = batches.length - 1; index >= 0; index -= 1) {
     if (
-      batches[index]!.some(
-        (event) => {
-          const key = event.key ?? event.type;
-          return (
-            key === 'run.completed' ||
-            key === 'run.failed' ||
-            key === 'run.cancelled'
-          );
-        },
-      )
+      batches[index]!.some((event) => {
+        const key = event.key ?? event.type;
+        return (
+          key === 'run.completed' ||
+          key === 'run.failed' ||
+          key === 'run.cancelled'
+        );
+      })
     ) {
       terminalBatchIndex = index;
       break;
@@ -2021,6 +2067,19 @@ export async function startRunViaAppRuntime(
   });
 }
 
+export async function projectRunCreatedViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: Omit<
+    Extract<RuntimeApiRequest, { action: 'project_run_created' }>,
+    'action'
+  >,
+): Promise<void> {
+  await postAppRuntimeApi<{ ok: true; status: 'queued' }>(context, {
+    action: 'project_run_created',
+    ...input,
+  });
+}
+
 export async function recordFirstClaimLatencyViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: { runId: string; firstClaimLatencyMs: number },
@@ -2031,6 +2090,25 @@ export async function recordFirstClaimLatencyViaAppRuntime(
   });
 }
 
+export async function launchPlayAsyncViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: {
+    key: string;
+    invocationKey: string;
+    playRef: string;
+    input: Record<string, unknown>;
+    description: string;
+    schedulerSchema?: string | null;
+    ancestryPlayIds: readonly string[];
+  },
+): Promise<AsyncPlayRunRef> {
+  return await postAppRuntimeApi<AsyncPlayRunRef>(context, {
+    action: 'launch_play_async',
+    ...input,
+    ancestryPlayIds: [...input.ancestryPlayIds],
+  });
+}
+
 export async function saveResultsViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: RuntimeSaveResults,

package/dist/bundling-sources/shared_libs/play-runtime/async-play-invocation.ts

@@ -0,0 +1,78 @@
+import {
+  flattenStaticPipeline,
+  type PlayStaticPipeline,
+} from '../plays/static-pipeline';
+import { SHARED_EXECUTION_POLICY } from './governor/policy';
+
+export const CTX_RUN_PLAY_ASYNC_TARGET_UNRESOLVED =
+  'CTX_RUN_PLAY_ASYNC_TARGET_UNRESOLVED';
+export const CTX_RUN_PLAY_ASYNC_DATASET_UNSUPPORTED =
+  'CTX_RUN_PLAY_ASYNC_DATASET_UNSUPPORTED';
+export const CTX_RUN_PLAY_ASYNC_RECURSIVE = 'CTX_RUN_PLAY_ASYNC_RECURSIVE';
+export const CTX_RUN_PLAY_ASYNC_DEPTH_EXCEEDED =
+  'CTX_RUN_PLAY_ASYNC_DEPTH_EXCEEDED';
+export const MAX_ASYNC_PLAY_CALL_DEPTH =
+  SHARED_EXECUTION_POLICY.budgets.maxPlayCallDepth;
+
+/**
+ * Assert that one independently scheduled Play closure may be admitted.
+ *
+ * Async children may suspend for sleep/HITL, but never own a Dataset, CSV, or
+ * Runtime Sheet. The checker and runtime both call this function so the same
+ * authored target cannot pass publish and fail differently at execution.
+ */
+export function assertAsyncPlayInvocation(input: {
+  pipeline: PlayStaticPipeline | null | undefined;
+  childPlayName?: string | null;
+}): void {
+  const childPlayName = input.childPlayName?.trim() || 'child';
+  if (!input.pipeline) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_TARGET_UNRESOLVED}: ctx.runPlayAsync("${childPlayName}") requires a statically resolved published Play contract. Publish the target with the current Deepline CLI before launching it.`,
+    );
+  }
+
+  const steps = flattenStaticPipeline(input.pipeline);
+  if (
+    input.pipeline.tableNamespace ||
+    input.pipeline.sheetContract ||
+    steps.some((step) => step.type === 'dataset' || step.type === 'csv')
+  ) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_DATASET_UNSUPPORTED}: ctx.runPlayAsync("${childPlayName}") launches one independent scalar or HITL Play Run, but the target owns ctx.dataset(), ctx.csv(), or a Runtime Sheet. Keep batch work in its top-level Play or extract a scalar per-record child.`,
+    );
+  }
+
+}
+
+/** Admit a child against the persisted root-to-parent Play lineage. */
+export function admitAsyncPlayLineage(input: {
+  ancestryPlayIds: readonly string[];
+  childPlayName: string;
+}): Readonly<{ ancestryPlayIds: readonly string[]; callDepth: number }> {
+  const childPlayName = input.childPlayName.trim();
+  const ancestryPlayIds = input.ancestryPlayIds
+    .map((playId) => playId.trim())
+    .filter(Boolean);
+  if (ancestryPlayIds.includes(childPlayName)) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_RECURSIVE}: Recursive play graph detected: ${[
+        ...ancestryPlayIds,
+        childPlayName,
+      ].join(' -> ')}`,
+    );
+  }
+  // The lineage includes the root Play, while call depth counts child edges.
+  // Appending this child therefore makes its depth equal to the current
+  // lineage length: [root] -> child is depth 1, not depth 2.
+  const callDepth = ancestryPlayIds.length;
+  if (callDepth > MAX_ASYNC_PLAY_CALL_DEPTH) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_DEPTH_EXCEEDED}: Play-call depth exceeded (${callDepth}/${MAX_ASYNC_PLAY_CALL_DEPTH}).`,
+    );
+  }
+  return {
+    ancestryPlayIds: [...ancestryPlayIds, childPlayName],
+    callDepth,
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/checkpoint-boundaries.ts

@@ -0,0 +1,70 @@
+/**
+ * Durable checkpoint boundary kinds — the one list every checkpoint reader
+ * narrows against.
+ *
+ * Compatibility contract (`docs/runtime-compatibility-contract.md`): a parked
+ * run's checkpoint is written by one build and read by a newer-or-same build.
+ * Adding a boundary KIND is therefore not an additive change: a build that does
+ * not know the kind falls through every `existing?.kind === '...'` narrow and
+ * silently re-arms the wait or re-executes the side effect the boundary already
+ * resolved. That is a duplicate durable wait or a duplicate external effect,
+ * with no trace of what happened.
+ *
+ * So an unknown kind FAILS LOUD here instead. Recovery is roll-forward: deploy a
+ * build that understands the kind, and the parked run resumes.
+ */
+import type { PlayCheckpoint } from './ctx-types';
+
+/** One entry of `PlayCheckpoint.resolvedBoundaries`. */
+export type PlayResolvedBoundary = NonNullable<
+  PlayCheckpoint['resolvedBoundaries']
+>[string];
+
+/** Every boundary kind this build can replay. */
+export const PLAY_RESOLVED_BOUNDARY_KINDS = [
+  'sleep',
+  'integration_event',
+  'fetch',
+  'step',
+] as const satisfies readonly PlayResolvedBoundary['kind'][];
+
+/**
+ * Compile fence in the other direction: adding a kind to `PlayCheckpoint`
+ * without listing it above resolves to `never` and fails the build, rather than
+ * shipping a kind that every reader would then reject at runtime.
+ */
+type UnlistedBoundaryKind = Exclude<
+  PlayResolvedBoundary['kind'],
+  (typeof PLAY_RESOLVED_BOUNDARY_KINDS)[number]
+>;
+const ALL_BOUNDARY_KINDS_LISTED: UnlistedBoundaryKind extends never
+  ? true
+  : never = true;
+void ALL_BOUNDARY_KINDS_LISTED;
+
+/**
+ * Return the checkpoint entry for `boundaryId`, or throw when it carries a kind
+ * this build cannot replay. Absent (`undefined`/`null`) stays absent — an
+ * unresolved boundary is normal and simply re-arms.
+ */
+export function assertKnownResolvedBoundary(
+  boundaryId: string,
+  entry: PlayResolvedBoundary | null | undefined,
+): PlayResolvedBoundary | undefined {
+  if (entry === null || entry === undefined) return undefined;
+  const kind = (entry as { kind?: unknown }).kind;
+  if (
+    typeof kind !== 'string' ||
+    !(PLAY_RESOLVED_BOUNDARY_KINDS as readonly string[]).includes(kind)
+  ) {
+    throw new Error(
+      `Play checkpoint boundary "${boundaryId}" is resolved with unknown kind ` +
+        `"${String(kind)}". This build only replays ` +
+        `${PLAY_RESOLVED_BOUNDARY_KINDS.join(', ')}. The checkpoint was written ` +
+        `by a newer runtime build; continuing would re-arm the wait or re-run ` +
+        `the effect this boundary already resolved. Roll forward to a build ` +
+        `that understands "${String(kind)}".`,
+    );
+  }
+  return entry;
+}