deepline 0.2.1 → 0.2.3

package/dist/bundling-sources/sdk/src/client.ts

@@ -686,6 +686,13 @@ export type MonitorListEntry = {
   status?: string;
   tool?: string;
   name?: string;
+  configured?: boolean;
+  active?: boolean;
+  provider?: string;
+  output_table?: string | null;
+  webhook_state?: string;
+  last_received_event?: string | null;
+  bound_plays?: Array<Record<string, unknown>>;
   [key: string]: unknown;
 };
 
@@ -744,7 +751,10 @@ export type MonitorUpdateChangeSummary = {
   };
   upstream: {
     resource_replaced: boolean;
-    strategy: 'unchanged' | 'create_then_delete_previous';
+    strategy:
+      | 'unchanged'
+      | 'create_then_delete_previous'
+      | 'deferred_until_reactivation';
   };
 };
 export type MonitorUpdateResult = {
@@ -753,6 +763,8 @@ export type MonitorUpdateResult = {
 };
 export type MonitorDeleteResult = Record<string, unknown>;
 export type MonitorReactivateResult = Record<string, unknown>;
+export type MonitorTestResult = Record<string, unknown>;
+export type MonitorValidateResult = Record<string, unknown>;
 
 /**
  * Public monitors namespace exposed as `client.monitors`.
@@ -788,6 +800,12 @@ export type MonitorsNamespace = {
   list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
   /** Fetch one deployed monitor by public key (without dependents). */
   get: (key: string) => Promise<MonitorDetail>;
+  /** Send an explicit payload through the deployed monitor's normal webhook path. */
+  test: (
+    key: string,
+    payload: Record<string, unknown>,
+  ) => Promise<MonitorTestResult>;
+  validate: (key: string) => Promise<MonitorValidateResult>;
   /** List the published plays depending on one monitor's output streams. */
   dependents: (key: string) => Promise<MonitorDependents>;
   /** Update a deployed monitor by public key. */
@@ -1486,6 +1504,8 @@ export class DeeplineClient {
       deploy: (definition, options) => this.deployMonitor(definition, options),
       list: (options) => this.listMonitors(options),
       get: (key) => this.getMonitor(key),
+      test: (key, payload) => this.testMonitorWebhook(key, payload),
+      validate: (key) => this.validateMonitor(key),
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options) => this.deleteMonitor(key, options),
@@ -4082,10 +4102,33 @@ export class DeeplineClient {
         body: definition,
       });
     }
-    return this.http.request<MonitorDeployResult>('/api/v2/monitors/deploy', {
+    const deployed = await this.http.request<MonitorDeployResult>(
+      '/api/v2/monitors/deploy',
+      {
       method: 'POST',
       body: definition,
-    });
+      },
+    );
+    if (definition.tool !== 'deepline.deanonymizer') return deployed;
+
+    // Deanonymizer remains an ordinary monitor deploy. Its provider-specific
+    // post-deploy work creates/reuses the tracker and returns the artifact a
+    // caller needs to install it; there is intentionally no separate setup
+    // command in the public monitor lifecycle.
+    const setup = await this.setupMonitor(
+      definition.tool,
+      definition.payload ?? {},
+    );
+    return {
+      ...deployed,
+      monitor: {
+        ...(deployed.monitor && typeof deployed.monitor === 'object'
+          ? deployed.monitor
+          : {}),
+        tracking: setup.tracking ?? null,
+        ip2company: setup.ip2company ?? null,
+      },
+    };
   }
 
   /** List deployed monitors. Prefer `client.monitors.list(...)`. */
@@ -4116,6 +4159,33 @@ export class DeeplineClient {
     );
   }
 
+  async testMonitorWebhook(
+    key: string,
+    payload: Record<string, unknown>,
+  ): Promise<MonitorTestResult> {
+    return this.http.request<MonitorTestResult>(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
+      { method: 'POST', body: { payload } },
+    );
+  }
+
+  async setupMonitor(
+    tool: string,
+    payload: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    return this.http.request<Record<string, unknown>>(
+      `/api/v2/monitors/setup/${encodeURIComponent(tool)}`,
+      { method: 'POST', body: payload },
+    );
+  }
+
+  async validateMonitor(key: string): Promise<MonitorValidateResult> {
+    return this.http.request<MonitorValidateResult>(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/validate`,
+      { method: 'POST', body: {} },
+    );
+  }
+
   /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
   async getMonitorDependents(key: string): Promise<MonitorDependents> {
     return this.http.request<MonitorDependents>(

package/dist/bundling-sources/sdk/src/release.ts

@@ -160,7 +160,7 @@ export const SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: '0.2.1',
+  version: '0.2.3',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/bundling-sources/shared_libs/observability/scheduled-job-errors.ts

@@ -0,0 +1,95 @@
+import { redactTelemetryText } from './redaction';
+
+const MAX_ERROR_SUMMARY_LENGTH = 900;
+
+const SECRET_ASSIGNMENT =
+  /\b((?:[A-Za-z][A-Za-z0-9_-]*[_-])?(?:token|secret|password|api[_ -]?key|access[_ -]?key))\b(\s*[:=]\s*)([^\s,;]+)/gi;
+const AUTHORIZATION_VALUE =
+  /\bauthorization\b(\s*[:=]\s*)(?:Bearer\s+)?[^\s,;|]+/gi;
+const BEARER_TOKEN = /\bBearer\s+[A-Za-z0-9._~+/=-]+/gi;
+const SLACK_WEBHOOK =
+  /https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9/_-]+/gi;
+const URL_SECRET = /([?&](?:token|secret|key|signature|sig|code)=)[^&\s]+/gi;
+const BARE_CREDENTIAL_PATTERNS = [
+  /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/gi,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/gi,
+  /\b(?:xaat|xain)-[A-Za-z0-9_-]{16,}\b/gi,
+  /\bsk-ant-(?:api|oat)[A-Za-z0-9_-]{8,}\b/gi,
+  /\bxox(?:a|b|p|r|s)-[A-Za-z0-9-]{10,}\b/gi,
+] as const;
+
+export type ScheduledJobFailure = {
+  jobId: string;
+  jobName: string;
+  scheduler: string;
+  error: unknown;
+  runUrl?: string | null;
+  stage?: string | null;
+  attempt?: number | null;
+  occurredAt?: string;
+  test?: boolean;
+};
+
+export function sanitizeScheduledJobError(
+  error: unknown,
+  maxLength = MAX_ERROR_SUMMARY_LENGTH,
+): string {
+  const raw =
+    error instanceof Error
+      ? `${error.name}: ${error.message}`
+      : typeof error === 'string'
+        ? error
+        : safeJson(error);
+  let compact = redactTelemetryText(raw)
+    .replace(/\u001b\[[0-9;]*m/g, '')
+    .replace(/\r/g, '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(' | ')
+    .replace(
+      AUTHORIZATION_VALUE,
+      (_match, separator) => `Authorization${separator}[REDACTED]`,
+    )
+    .replace(BEARER_TOKEN, 'Bearer [REDACTED]')
+    .replace(SLACK_WEBHOOK, '[REDACTED_SLACK_WEBHOOK]')
+    .replace(SECRET_ASSIGNMENT, (_match, label, separator) => {
+      return `${label}${separator}[REDACTED]`;
+    })
+    .replace(URL_SECRET, '$1[REDACTED]')
+    .replace(/\s+/g, ' ')
+    .trim();
+  for (const pattern of BARE_CREDENTIAL_PATTERNS) {
+    compact = compact.replace(pattern, '[REDACTED_CREDENTIAL]');
+  }
+  if (!compact) return 'No error detail was captured.';
+  return compact.length <= maxLength
+    ? compact
+    : `${compact.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+
+export function formatScheduledJobFailure(input: ScheduledJobFailure): string {
+  const title = input.test
+    ? '[TEST] Scheduled job failure alert'
+    : 'Scheduled job failed';
+  return [
+    title,
+    `Job: ${input.jobName} (${input.jobId})`,
+    `Scheduler: ${input.scheduler}`,
+    input.stage ? `Stage: ${input.stage}` : null,
+    input.attempt ? `Attempt: ${input.attempt}` : null,
+    `Error: ${sanitizeScheduledJobError(input.error)}`,
+    `Occurred: ${input.occurredAt ?? new Date().toISOString()}`,
+    input.runUrl ? `Diagnostics: ${input.runUrl}` : null,
+  ]
+    .filter((line): line is string => Boolean(line))
+    .join('\n');
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-lifecycle.ts

@@ -9,6 +9,7 @@ import {
   STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
   validatePlaySandboxRuntimeLimits,
 } from '@shared_libs/play-runtime/sandbox-runtime-limits';
+import type { PlayRunnerRuntimeLifecycleEvent } from '../types';
 
 const DAYTONA_CREATE_TIMEOUT_SECONDS = 10;
 const DAYTONA_CREATE_RETRY_DELAYS_MS = [0, 500, 1_500] as const;
@@ -41,6 +42,10 @@ export type DaytonaStageEmitter = (
   extra?: Record<string, unknown>,
 ) => void;
 
+type DaytonaCreateCallObserver = (
+  event: PlayRunnerRuntimeLifecycleEvent,
+) => Promise<void>;
+
 export type AcquiredDaytonaSandbox = {
   sandbox: DaytonaSandbox;
   daytonaOrganizationId: string;
@@ -104,6 +109,16 @@ type DaytonaCreateResult = {
   attemptElapsedMs: number;
 };
 
+function daytonaCreateErrorClass(
+  error: unknown,
+): 'timeout' | 'capacity' | 'rate_limit' | 'other' {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/timed out|timeout/i.test(message)) return 'timeout';
+  if (/total cpu limit|capacity/i.test(message)) return 'capacity';
+  if (/too many requests|rate limit|429/i.test(message)) return 'rate_limit';
+  return 'other';
+}
+
 async function rejectAcquiredSandbox(
   sandbox: DaytonaSandbox,
   reason: string,
@@ -307,11 +322,13 @@ async function createRetriedOneShotDaytonaSandbox(input: {
   orgId: string;
   context: DaytonaExecutionContext;
   emitStage: DaytonaStageEmitter;
+  observeCreateCall?: DaytonaCreateCallObserver;
+  nextProviderAttempt: () => number;
   startedAt: number;
 }): Promise<DaytonaCreateResult> {
   const errors: string[] = [];
   for (const [index, delayMs] of DAYTONA_CREATE_RETRY_DELAYS_MS.entries()) {
-    const attempt = index + 1;
+    const attempt = input.nextProviderAttempt();
     const sandboxName = `dl-${crypto.randomUUID()}`;
     if (delayMs > 0) {
       input.emitStage('create:retry', {
@@ -323,19 +340,26 @@ async function createRetriedOneShotDaytonaSandbox(input: {
       await new Promise((resolve) => setTimeout(resolve, delayMs));
     }
     const attemptStartedAt = Date.now();
+    await input.observeCreateCall?.({
+      type: 'daytona_create_call_started',
+      occurredAtMs: attemptStartedAt,
+      providerAttempt: attempt,
+    });
+    let sandbox: DaytonaSandbox;
     try {
-      const sandbox = await createOneShotDaytonaSandbox({
+      sandbox = await createOneShotDaytonaSandbox({
         daytona: input.daytona,
         orgId: input.orgId,
         context: input.context,
         sandboxName,
       });
-      return {
-        sandbox,
-        attempt,
-        attemptElapsedMs: Date.now() - attemptStartedAt,
-      };
     } catch (error) {
+      await input.observeCreateCall?.({
+        type: 'daytona_create_call_failed',
+        occurredAtMs: Date.now(),
+        providerAttempt: attempt,
+        errorClass: daytonaCreateErrorClass(error),
+      });
       const message = error instanceof Error ? error.message : String(error);
       errors.push(message);
       input.emitStage('create:attempt_failed', {
@@ -366,7 +390,38 @@ async function createRetriedOneShotDaytonaSandbox(input: {
           { cause: error },
         );
       }
+      continue;
     }
+    // The outcome must be attributed immediately after Daytona acknowledges
+    // creation, before resource-policy validation can reject it. Otherwise a
+    // created-but-rejected sandbox is indistinguishable from an unknown
+    // create result. Do not turn a failed *post-create* journal write into a
+    // new provider create: the sandbox is already real. The missing durable
+    // outcome is deliberately loud in worker logs and makes the capture gate
+    // fail as incomplete telemetry, while the normal resource ledger still
+    // records the known sandbox for cleanup below.
+    const acquiredAt = Date.now();
+    try {
+      await input.observeCreateCall?.({
+        type: 'daytona_create_call_succeeded',
+        occurredAtMs: acquiredAt,
+        providerAttempt: attempt,
+        sandboxId: sandbox.id,
+      });
+    } catch {
+      console.error('[play-runner.daytona.create_lifecycle_event_unrecorded]', {
+        workflowId: input.context.workflowId ?? null,
+        runId: input.context.runId ?? null,
+        attempt,
+        sandboxId: sandbox.id,
+        eventType: 'daytona_create_call_succeeded',
+      });
+    }
+    return {
+      sandbox,
+      attempt,
+      attemptElapsedMs: acquiredAt - attemptStartedAt,
+    };
   }
   const message = `Daytona sandbox create failed across ${errors.length} bounded attempts: ${errors.join('; ')}`;
   const fallbackReason =
@@ -385,6 +440,8 @@ async function acquireOneShotDaytonaSandbox(input: {
   orgId: string;
   context: DaytonaExecutionContext;
   emitStage: DaytonaStageEmitter;
+  observeCreateCall?: DaytonaCreateCallObserver;
+  nextProviderAttempt: () => number;
   startedAt: number;
 }): Promise<AcquiredDaytonaSandbox> {
   const limits = validatePlaySandboxRuntimeLimits(
@@ -464,11 +521,13 @@ export function createOneShotDaytonaSandboxLifecycle(input: {
   daytona: DaytonaClient;
   context: DaytonaExecutionContext;
   emitStage: DaytonaStageEmitter;
+  observeCreateCall?: DaytonaCreateCallObserver;
   startedAt?: number;
 }): OneShotDaytonaSandboxLifecycle {
   const orgId = validateDaytonaExecutionContext(input.context);
   const startedAt = input.startedAt ?? Date.now();
   let disposed = false;
+  let providerAttempt = 0;
   const acquiredSandboxes = new Map<string, AcquiredDaytonaSandbox>();
   let latestAcquiredSandboxPromise: Promise<AcquiredDaytonaSandbox>;
   const createFreshSandbox = () => {
@@ -477,6 +536,11 @@ export function createOneShotDaytonaSandboxLifecycle(input: {
       orgId,
       context: input.context,
       emitStage: input.emitStage,
+      observeCreateCall: input.observeCreateCall,
+      nextProviderAttempt: () => {
+        providerAttempt += 1;
+        return providerAttempt;
+      },
       startedAt,
     }).then((acquired) => {
       acquiredSandboxes.set(acquired.sandbox.id, acquired);

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona.ts

@@ -670,6 +670,7 @@ function prepareDaytonaExecution(
     context: input.context,
     emitStage: (stage, extra) =>
       emitDaytonaStage(callbacks, input.context, stage, extra),
+    observeCreateCall: callbacks?.onRuntimeLifecycleEvent,
   });
   return {
     kind: 'daytona',

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/types.ts

@@ -40,6 +40,22 @@ export type RuntimeResourceTerminalReason =
   | 'cancelled'
   | 'lease_expired';
 
+/**
+ * Safe, provider-edge lifecycle evidence. The scheduler records these before
+ * relying on a non-idempotent provider outcome; raw provider responses,
+ * commands, inputs, and credentials are intentionally not part of the type.
+ */
+export type PlayRunnerRuntimeLifecycleEvent = {
+  type:
+    | 'daytona_create_call_started'
+    | 'daytona_create_call_succeeded'
+    | 'daytona_create_call_failed';
+  occurredAtMs: number;
+  providerAttempt: number;
+  sandboxId?: string;
+  errorClass?: 'timeout' | 'capacity' | 'rate_limit' | 'other';
+};
+
 export class RuntimeResourceFenceLostError extends Error {
   constructor(message: string) {
     super(message);
@@ -55,6 +71,13 @@ export interface PlayRunnerCallbacks {
   onRuntimeResourceAcquired?: (
     resource: PlayRunnerRuntimeResource,
   ) => void | Promise<void>;
+  /**
+   * Durable scheduler-owned evidence for a provider create call. Backends
+   * await this callback at the create boundary; it is not best-effort logging.
+   */
+  onRuntimeLifecycleEvent?: (
+    event: PlayRunnerRuntimeLifecycleEvent,
+  ) => Promise<void>;
   /**
    * Scheduler-owned readiness read for a detached runner attempt. Daytona uses
    * this direct control-plane port before parking; it is never serialized into

package/dist/cli/index.js

@@ -1040,7 +1040,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.1",
+  version: "0.2.3",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3778,6 +3778,8 @@ var DeeplineClient = class {
       deploy: (definition, options2) => this.deployMonitor(definition, options2),
       list: (options2) => this.listMonitors(options2),
       get: (key) => this.getMonitor(key),
+      test: (key, payload) => this.testMonitorWebhook(key, payload),
+      validate: (key) => this.validateMonitor(key),
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options2) => this.deleteMonitor(key, options2),
@@ -5739,10 +5741,26 @@ var DeeplineClient = class {
         body: definition
       });
     }
-    return this.http.request("/api/v2/monitors/deploy", {
-      method: "POST",
-      body: definition
-    });
+    const deployed = await this.http.request(
+      "/api/v2/monitors/deploy",
+      {
+        method: "POST",
+        body: definition
+      }
+    );
+    if (definition.tool !== "deepline.deanonymizer") return deployed;
+    const setup = await this.setupMonitor(
+      definition.tool,
+      definition.payload ?? {}
+    );
+    return {
+      ...deployed,
+      monitor: {
+        ...deployed.monitor && typeof deployed.monitor === "object" ? deployed.monitor : {},
+        tracking: setup.tracking ?? null,
+        ip2company: setup.ip2company ?? null
+      }
+    };
   }
   /** List deployed monitors. Prefer `client.monitors.list(...)`. */
   async listMonitors(options) {
@@ -5766,6 +5784,24 @@ var DeeplineClient = class {
       { method: "GET" }
     );
   }
+  async testMonitorWebhook(key, payload) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
+      { method: "POST", body: { payload } }
+    );
+  }
+  async setupMonitor(tool, payload) {
+    return this.http.request(
+      `/api/v2/monitors/setup/${encodeURIComponent(tool)}`,
+      { method: "POST", body: payload }
+    );
+  }
+  async validateMonitor(key) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/validate`,
+      { method: "POST", body: {} }
+    );
+  }
   /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
   async getMonitorDependents(key) {
     return this.http.request(
@@ -25753,6 +25789,26 @@ function renderMonitorDeployCompletion(payload) {
   if (pricingLine) {
     lines.push("", `Pricing: ${pricingLine}`);
   }
+  const guidance = asRecord2(payload.setup_guidance);
+  if (guidance) {
+    const callbackUrl = asString(guidance.callback_url);
+    const steps = Array.isArray(guidance.steps) ? guidance.steps : [];
+    const docs = Array.isArray(guidance.documentation) ? guidance.documentation : [];
+    lines.push("", asString(guidance.title) ?? "Provider setup:");
+    if (callbackUrl) lines.push(`  Callback URL: ${callbackUrl}`);
+    for (const step of steps)
+      if (asString(step)) lines.push(`  \u2022 ${asString(step)}`);
+    for (const raw of docs) {
+      const doc = asRecord2(raw);
+      const label = asString(doc?.label);
+      const url = asString(doc?.url);
+      if (label && url) lines.push(`  Docs: ${label} \u2014 ${url}`);
+    }
+    const payloadExample = asRecord2(guidance.payload_example);
+    if (payloadExample) {
+      lines.push(`  Payload example: ${JSON.stringify(payloadExample)}`);
+    }
+  }
   lines.push(
     "",
     "This monitor streams new rows into your Customer DB \u2014 there is no manual run.",
@@ -25970,9 +26026,21 @@ function renderDeployedListText(payload, requestedStatus) {
     const status = asString(entry.status);
     const tool = asString(entry.tool);
     const name = asString(entry.name);
+    const outputTable = asString(entry.output_table);
+    const webhookState = asString(entry.webhook_state);
+    const boundPlays = Array.isArray(entry.bound_plays) ? entry.bound_plays.length : void 0;
     lines.push(
       `  ${key}${status ? `  ${status}` : ""}${tool ? `  ${tool}` : ""}${name ? `  (${name})` : ""}`
     );
+    if (outputTable || webhookState || boundPlays !== void 0) {
+      lines.push(
+        `    ${[
+          outputTable ? `table: ${outputTable}` : null,
+          webhookState ? `webhook: ${webhookState}` : null,
+          boundPlays !== void 0 ? `bound Plays: ${boundPlays}` : null
+        ].filter(Boolean).join("  ")}`
+      );
+    }
   }
   const applied = asString(payload.status_filter_applied) ?? requestedStatus ?? "active";
   lines.push(
@@ -26054,6 +26122,8 @@ function renderMonitorGet(payload) {
   const billing = asRecord2(payload.billing);
   const nextRenewalAt = billing ? asString(billing.next_renewal_at) : void 0;
   const dependents = asRecord2(payload.dependents);
+  const webhook = asRecord2(payload.webhook);
+  const guidance = asRecord2(payload.setup_guidance);
   const plays = dependents && Array.isArray(dependents.plays) ? dependents.plays : [];
   const lines = [
     `Monitor: ${key}`,
@@ -26065,6 +26135,36 @@ function renderMonitorGet(payload) {
   if (definition) {
     lines.push("", "Current definition:", `  ${JSON.stringify(definition)}`);
   }
+  if (webhook) {
+    lines.push("", `Webhook: ${asString(webhook.state) ?? "unknown"}`);
+    const callbackUrl = asString(webhook.callback_url);
+    if (callbackUrl) lines.push(`  Callback URL (sensitive): ${callbackUrl}`);
+  }
+  if (guidance) {
+    lines.push("", asString(guidance.title) ?? "Provider setup:");
+    for (const step of Array.isArray(guidance.steps) ? guidance.steps : []) {
+      const text = asString(step);
+      if (text) lines.push(`  \u2022 ${text}`);
+    }
+    for (const raw of Array.isArray(guidance.documentation) ? guidance.documentation : []) {
+      const doc = asRecord2(raw);
+      const label = asString(doc?.label);
+      const url = asString(doc?.url);
+      if (label && url) lines.push(`  Docs: ${label} \u2014 ${url}`);
+    }
+    const payloadExample = asRecord2(guidance.payload_example);
+    if (payloadExample) {
+      lines.push(`  Payload example: ${JSON.stringify(payloadExample)}`);
+    }
+  }
+  const samplePayload2 = asRecord2(payload.sample_payload);
+  if (samplePayload2) {
+    lines.push(
+      "",
+      `Sample test payload: ${JSON.stringify(samplePayload2)}`,
+      `  deepline monitors test ${key} '${JSON.stringify(samplePayload2)}' --json`
+    );
+  }
   lines.push("", `Dependent published plays (${plays.length}):`);
   if (plays.length === 0) {
     lines.push("  none");
@@ -26096,6 +26196,20 @@ async function handleMonitorsGet(key, options) {
     text: renderMonitorGet(detail)
   });
 }
+async function handleMonitorsTest(key, payload, options) {
+  const explicitPayload = parseJsonObjectArg(payload, "<payload>");
+  const result = await new DeeplineClient().monitors.test(key, explicitPayload);
+  const text = `Webhook test for ${key}: ${result.accepted === true ? "accepted" : "rejected"}
+  persisted rows: ${asFiniteNumber(result.persisted_rows) ?? 0}
+  bound Plays dispatched: ${asFiniteNumber(result.dispatched_bound_plays) ?? 0}
+`;
+  printCommandEnvelope(result, { json: options.json, text });
+}
+async function handleMonitorsValidate(key, options) {
+  const result = await new DeeplineClient().monitors.validate(key);
+  printCommandEnvelope(result, { json: options.json });
+  if (result.valid === false) process.exitCode = 7;
+}
 async function confirmMonitorDelete(key, options) {
   const rl = (0, import_promises4.createInterface)({
     input: process.stdin,
@@ -26185,8 +26299,8 @@ Notes:
   Deepline monitors are Deepline-native signal feeds: a monitor writes events
   into a Customer DB table; a play reacts to each new row via a
   sqlListeners trigger \u2014 see \`deepline plays bootstrap monitor-triggered\`.
-  The customer launch currently includes Company Radar and Contact Radar; use
-  \`deepline monitors available\` for the exact live tool ids.
+  The Monitors rollout controls access to the live provider catalog; use
+  \`deepline tools list --categories monitors\` for the exact tool ids available to you.
   Access is granted by a Deepline admin via Admin -> Rollouts; until then these
   commands return a clear monitor_access_required error.
 
@@ -26296,6 +26410,25 @@ Examples:
 `
     )
   ).action(monitorsAction(handleMonitorsGet));
+  withJsonOption(
+    monitors.command("test <key> <payload>").description(
+      "Send an explicit payload through a monitor\u2019s webhook ingestion path."
+    ).addHelpText(
+      "after",
+      `
+Notes:
+  <payload> must be an explicit JSON object. The command uses the deployed
+  monitor\u2019s real validation, persistence, and inline Play dispatch path; it does
+  not synthesize a provider event or accept an omitted payload.
+
+Examples:
+  deepline monitors test rb2b-website-visitors '{"LinkedIn URL":"https://www.linkedin.com/in/example","Website":"https://example.com"}' --json
+`
+    )
+  ).action(monitorsAction(handleMonitorsTest));
+  withJsonOption(
+    monitors.command("validate <key>").description("Validate a deployed monitor\u2019s provider configuration.")
+  ).action(monitorsAction(handleMonitorsValidate));
   withJsonOption(
     monitors.command("check [definition]").description("Validate a monitor definition without deploying it.").addHelpText(
       "after",

package/dist/cli/index.mjs

@@ -1025,7 +1025,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.1",
+  version: "0.2.3",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3763,6 +3763,8 @@ var DeeplineClient = class {
       deploy: (definition, options2) => this.deployMonitor(definition, options2),
       list: (options2) => this.listMonitors(options2),
       get: (key) => this.getMonitor(key),
+      test: (key, payload) => this.testMonitorWebhook(key, payload),
+      validate: (key) => this.validateMonitor(key),
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options2) => this.deleteMonitor(key, options2),
@@ -5724,10 +5726,26 @@ var DeeplineClient = class {
         body: definition
       });
     }
-    return this.http.request("/api/v2/monitors/deploy", {
-      method: "POST",
-      body: definition
-    });
+    const deployed = await this.http.request(
+      "/api/v2/monitors/deploy",
+      {
+        method: "POST",
+        body: definition
+      }
+    );
+    if (definition.tool !== "deepline.deanonymizer") return deployed;
+    const setup = await this.setupMonitor(
+      definition.tool,
+      definition.payload ?? {}
+    );
+    return {
+      ...deployed,
+      monitor: {
+        ...deployed.monitor && typeof deployed.monitor === "object" ? deployed.monitor : {},
+        tracking: setup.tracking ?? null,
+        ip2company: setup.ip2company ?? null
+      }
+    };
   }
   /** List deployed monitors. Prefer `client.monitors.list(...)`. */
   async listMonitors(options) {
@@ -5751,6 +5769,24 @@ var DeeplineClient = class {
       { method: "GET" }
     );
   }
+  async testMonitorWebhook(key, payload) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
+      { method: "POST", body: { payload } }
+    );
+  }
+  async setupMonitor(tool, payload) {
+    return this.http.request(
+      `/api/v2/monitors/setup/${encodeURIComponent(tool)}`,
+      { method: "POST", body: payload }
+    );
+  }
+  async validateMonitor(key) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/validate`,
+      { method: "POST", body: {} }
+    );
+  }
   /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
   async getMonitorDependents(key) {
     return this.http.request(
@@ -25789,6 +25825,26 @@ function renderMonitorDeployCompletion(payload) {
   if (pricingLine) {
     lines.push("", `Pricing: ${pricingLine}`);
   }
+  const guidance = asRecord2(payload.setup_guidance);
+  if (guidance) {
+    const callbackUrl = asString(guidance.callback_url);
+    const steps = Array.isArray(guidance.steps) ? guidance.steps : [];
+    const docs = Array.isArray(guidance.documentation) ? guidance.documentation : [];
+    lines.push("", asString(guidance.title) ?? "Provider setup:");
+    if (callbackUrl) lines.push(`  Callback URL: ${callbackUrl}`);
+    for (const step of steps)
+      if (asString(step)) lines.push(`  \u2022 ${asString(step)}`);
+    for (const raw of docs) {
+      const doc = asRecord2(raw);
+      const label = asString(doc?.label);
+      const url = asString(doc?.url);
+      if (label && url) lines.push(`  Docs: ${label} \u2014 ${url}`);
+    }
+    const payloadExample = asRecord2(guidance.payload_example);
+    if (payloadExample) {
+      lines.push(`  Payload example: ${JSON.stringify(payloadExample)}`);
+    }
+  }
   lines.push(
     "",
     "This monitor streams new rows into your Customer DB \u2014 there is no manual run.",
@@ -26006,9 +26062,21 @@ function renderDeployedListText(payload, requestedStatus) {
     const status = asString(entry.status);
     const tool = asString(entry.tool);
     const name = asString(entry.name);
+    const outputTable = asString(entry.output_table);
+    const webhookState = asString(entry.webhook_state);
+    const boundPlays = Array.isArray(entry.bound_plays) ? entry.bound_plays.length : void 0;
     lines.push(
       `  ${key}${status ? `  ${status}` : ""}${tool ? `  ${tool}` : ""}${name ? `  (${name})` : ""}`
     );
+    if (outputTable || webhookState || boundPlays !== void 0) {
+      lines.push(
+        `    ${[
+          outputTable ? `table: ${outputTable}` : null,
+          webhookState ? `webhook: ${webhookState}` : null,
+          boundPlays !== void 0 ? `bound Plays: ${boundPlays}` : null
+        ].filter(Boolean).join("  ")}`
+      );
+    }
   }
   const applied = asString(payload.status_filter_applied) ?? requestedStatus ?? "active";
   lines.push(
@@ -26090,6 +26158,8 @@ function renderMonitorGet(payload) {
   const billing = asRecord2(payload.billing);
   const nextRenewalAt = billing ? asString(billing.next_renewal_at) : void 0;
   const dependents = asRecord2(payload.dependents);
+  const webhook = asRecord2(payload.webhook);
+  const guidance = asRecord2(payload.setup_guidance);
   const plays = dependents && Array.isArray(dependents.plays) ? dependents.plays : [];
   const lines = [
     `Monitor: ${key}`,
@@ -26101,6 +26171,36 @@ function renderMonitorGet(payload) {
   if (definition) {
     lines.push("", "Current definition:", `  ${JSON.stringify(definition)}`);
   }
+  if (webhook) {
+    lines.push("", `Webhook: ${asString(webhook.state) ?? "unknown"}`);
+    const callbackUrl = asString(webhook.callback_url);
+    if (callbackUrl) lines.push(`  Callback URL (sensitive): ${callbackUrl}`);
+  }
+  if (guidance) {
+    lines.push("", asString(guidance.title) ?? "Provider setup:");
+    for (const step of Array.isArray(guidance.steps) ? guidance.steps : []) {
+      const text = asString(step);
+      if (text) lines.push(`  \u2022 ${text}`);
+    }
+    for (const raw of Array.isArray(guidance.documentation) ? guidance.documentation : []) {
+      const doc = asRecord2(raw);
+      const label = asString(doc?.label);
+      const url = asString(doc?.url);
+      if (label && url) lines.push(`  Docs: ${label} \u2014 ${url}`);
+    }
+    const payloadExample = asRecord2(guidance.payload_example);
+    if (payloadExample) {
+      lines.push(`  Payload example: ${JSON.stringify(payloadExample)}`);
+    }
+  }
+  const samplePayload2 = asRecord2(payload.sample_payload);
+  if (samplePayload2) {
+    lines.push(
+      "",
+      `Sample test payload: ${JSON.stringify(samplePayload2)}`,
+      `  deepline monitors test ${key} '${JSON.stringify(samplePayload2)}' --json`
+    );
+  }
   lines.push("", `Dependent published plays (${plays.length}):`);
   if (plays.length === 0) {
     lines.push("  none");
@@ -26132,6 +26232,20 @@ async function handleMonitorsGet(key, options) {
     text: renderMonitorGet(detail)
   });
 }
+async function handleMonitorsTest(key, payload, options) {
+  const explicitPayload = parseJsonObjectArg(payload, "<payload>");
+  const result = await new DeeplineClient().monitors.test(key, explicitPayload);
+  const text = `Webhook test for ${key}: ${result.accepted === true ? "accepted" : "rejected"}
+  persisted rows: ${asFiniteNumber(result.persisted_rows) ?? 0}
+  bound Plays dispatched: ${asFiniteNumber(result.dispatched_bound_plays) ?? 0}
+`;
+  printCommandEnvelope(result, { json: options.json, text });
+}
+async function handleMonitorsValidate(key, options) {
+  const result = await new DeeplineClient().monitors.validate(key);
+  printCommandEnvelope(result, { json: options.json });
+  if (result.valid === false) process.exitCode = 7;
+}
 async function confirmMonitorDelete(key, options) {
   const rl = createInterface({
     input: process.stdin,
@@ -26221,8 +26335,8 @@ Notes:
   Deepline monitors are Deepline-native signal feeds: a monitor writes events
   into a Customer DB table; a play reacts to each new row via a
   sqlListeners trigger \u2014 see \`deepline plays bootstrap monitor-triggered\`.
-  The customer launch currently includes Company Radar and Contact Radar; use
-  \`deepline monitors available\` for the exact live tool ids.
+  The Monitors rollout controls access to the live provider catalog; use
+  \`deepline tools list --categories monitors\` for the exact tool ids available to you.
   Access is granted by a Deepline admin via Admin -> Rollouts; until then these
   commands return a clear monitor_access_required error.
 
@@ -26332,6 +26446,25 @@ Examples:
 `
     )
   ).action(monitorsAction(handleMonitorsGet));
+  withJsonOption(
+    monitors.command("test <key> <payload>").description(
+      "Send an explicit payload through a monitor\u2019s webhook ingestion path."
+    ).addHelpText(
+      "after",
+      `
+Notes:
+  <payload> must be an explicit JSON object. The command uses the deployed
+  monitor\u2019s real validation, persistence, and inline Play dispatch path; it does
+  not synthesize a provider event or accept an omitted payload.
+
+Examples:
+  deepline monitors test rb2b-website-visitors '{"LinkedIn URL":"https://www.linkedin.com/in/example","Website":"https://example.com"}' --json
+`
+    )
+  ).action(monitorsAction(handleMonitorsTest));
+  withJsonOption(
+    monitors.command("validate <key>").description("Validate a deployed monitor\u2019s provider configuration.")
+  ).action(monitorsAction(handleMonitorsValidate));
   withJsonOption(
     monitors.command("check [definition]").description("Validate a monitor definition without deploying it.").addHelpText(
       "after",

package/dist/index.d.mts

@@ -1930,6 +1930,13 @@ type MonitorListEntry = {
     status?: string;
     tool?: string;
     name?: string;
+    configured?: boolean;
+    active?: boolean;
+    provider?: string;
+    output_table?: string | null;
+    webhook_state?: string;
+    last_received_event?: string | null;
+    bound_plays?: Array<Record<string, unknown>>;
     [key: string]: unknown;
 };
 /**
@@ -1992,7 +1999,7 @@ type MonitorUpdateChangeSummary = {
     };
     upstream: {
         resource_replaced: boolean;
-        strategy: 'unchanged' | 'create_then_delete_previous';
+        strategy: 'unchanged' | 'create_then_delete_previous' | 'deferred_until_reactivation';
     };
 };
 type MonitorUpdateResult = {
@@ -2001,6 +2008,8 @@ type MonitorUpdateResult = {
 };
 type MonitorDeleteResult = Record<string, unknown>;
 type MonitorReactivateResult = Record<string, unknown>;
+type MonitorTestResult = Record<string, unknown>;
+type MonitorValidateResult = Record<string, unknown>;
 /**
  * Public monitors namespace exposed as `client.monitors`.
  *
@@ -2033,6 +2042,9 @@ type MonitorsNamespace = {
     list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
     /** Fetch one deployed monitor by public key (without dependents). */
     get: (key: string) => Promise<MonitorDetail>;
+    /** Send an explicit payload through the deployed monitor's normal webhook path. */
+    test: (key: string, payload: Record<string, unknown>) => Promise<MonitorTestResult>;
+    validate: (key: string) => Promise<MonitorValidateResult>;
     /** List the published plays depending on one monitor's output streams. */
     dependents: (key: string) => Promise<MonitorDependents>;
     /** Update a deployed monitor by public key. */
@@ -3162,6 +3174,9 @@ declare class DeeplineClient {
     listMonitors(options?: MonitorsListOptions): Promise<MonitorsListResult>;
     /** Fetch one deployed monitor by public key. Prefer `client.monitors.get(...)`. */
     getMonitor(key: string): Promise<MonitorDetail>;
+    testMonitorWebhook(key: string, payload: Record<string, unknown>): Promise<MonitorTestResult>;
+    setupMonitor(tool: string, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
+    validateMonitor(key: string): Promise<MonitorValidateResult>;
     /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
     getMonitorDependents(key: string): Promise<MonitorDependents>;
     /** Update a deployed monitor by public key. Prefer `client.monitors.update(...)`. */

package/dist/index.d.ts

@@ -1930,6 +1930,13 @@ type MonitorListEntry = {
     status?: string;
     tool?: string;
     name?: string;
+    configured?: boolean;
+    active?: boolean;
+    provider?: string;
+    output_table?: string | null;
+    webhook_state?: string;
+    last_received_event?: string | null;
+    bound_plays?: Array<Record<string, unknown>>;
     [key: string]: unknown;
 };
 /**
@@ -1992,7 +1999,7 @@ type MonitorUpdateChangeSummary = {
     };
     upstream: {
         resource_replaced: boolean;
-        strategy: 'unchanged' | 'create_then_delete_previous';
+        strategy: 'unchanged' | 'create_then_delete_previous' | 'deferred_until_reactivation';
     };
 };
 type MonitorUpdateResult = {
@@ -2001,6 +2008,8 @@ type MonitorUpdateResult = {
 };
 type MonitorDeleteResult = Record<string, unknown>;
 type MonitorReactivateResult = Record<string, unknown>;
+type MonitorTestResult = Record<string, unknown>;
+type MonitorValidateResult = Record<string, unknown>;
 /**
  * Public monitors namespace exposed as `client.monitors`.
  *
@@ -2033,6 +2042,9 @@ type MonitorsNamespace = {
     list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
     /** Fetch one deployed monitor by public key (without dependents). */
     get: (key: string) => Promise<MonitorDetail>;
+    /** Send an explicit payload through the deployed monitor's normal webhook path. */
+    test: (key: string, payload: Record<string, unknown>) => Promise<MonitorTestResult>;
+    validate: (key: string) => Promise<MonitorValidateResult>;
     /** List the published plays depending on one monitor's output streams. */
     dependents: (key: string) => Promise<MonitorDependents>;
     /** Update a deployed monitor by public key. */
@@ -3162,6 +3174,9 @@ declare class DeeplineClient {
     listMonitors(options?: MonitorsListOptions): Promise<MonitorsListResult>;
     /** Fetch one deployed monitor by public key. Prefer `client.monitors.get(...)`. */
     getMonitor(key: string): Promise<MonitorDetail>;
+    testMonitorWebhook(key: string, payload: Record<string, unknown>): Promise<MonitorTestResult>;
+    setupMonitor(tool: string, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
+    validateMonitor(key: string): Promise<MonitorValidateResult>;
     /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
     getMonitorDependents(key: string): Promise<MonitorDependents>;
     /** Update a deployed monitor by public key. Prefer `client.monitors.update(...)`. */

package/dist/index.js

@@ -763,7 +763,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.1",
+  version: "0.2.3",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3501,6 +3501,8 @@ var DeeplineClient = class {
       deploy: (definition, options2) => this.deployMonitor(definition, options2),
       list: (options2) => this.listMonitors(options2),
       get: (key) => this.getMonitor(key),
+      test: (key, payload) => this.testMonitorWebhook(key, payload),
+      validate: (key) => this.validateMonitor(key),
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options2) => this.deleteMonitor(key, options2),
@@ -5462,10 +5464,26 @@ var DeeplineClient = class {
         body: definition
       });
     }
-    return this.http.request("/api/v2/monitors/deploy", {
-      method: "POST",
-      body: definition
-    });
+    const deployed = await this.http.request(
+      "/api/v2/monitors/deploy",
+      {
+        method: "POST",
+        body: definition
+      }
+    );
+    if (definition.tool !== "deepline.deanonymizer") return deployed;
+    const setup = await this.setupMonitor(
+      definition.tool,
+      definition.payload ?? {}
+    );
+    return {
+      ...deployed,
+      monitor: {
+        ...deployed.monitor && typeof deployed.monitor === "object" ? deployed.monitor : {},
+        tracking: setup.tracking ?? null,
+        ip2company: setup.ip2company ?? null
+      }
+    };
   }
   /** List deployed monitors. Prefer `client.monitors.list(...)`. */
   async listMonitors(options) {
@@ -5489,6 +5507,24 @@ var DeeplineClient = class {
       { method: "GET" }
     );
   }
+  async testMonitorWebhook(key, payload) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
+      { method: "POST", body: { payload } }
+    );
+  }
+  async setupMonitor(tool, payload) {
+    return this.http.request(
+      `/api/v2/monitors/setup/${encodeURIComponent(tool)}`,
+      { method: "POST", body: payload }
+    );
+  }
+  async validateMonitor(key) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/validate`,
+      { method: "POST", body: {} }
+    );
+  }
   /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
   async getMonitorDependents(key) {
     return this.http.request(

package/dist/index.mjs

@@ -689,7 +689,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.1",
+  version: "0.2.3",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3427,6 +3427,8 @@ var DeeplineClient = class {
       deploy: (definition, options2) => this.deployMonitor(definition, options2),
       list: (options2) => this.listMonitors(options2),
       get: (key) => this.getMonitor(key),
+      test: (key, payload) => this.testMonitorWebhook(key, payload),
+      validate: (key) => this.validateMonitor(key),
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options2) => this.deleteMonitor(key, options2),
@@ -5388,10 +5390,26 @@ var DeeplineClient = class {
         body: definition
       });
     }
-    return this.http.request("/api/v2/monitors/deploy", {
-      method: "POST",
-      body: definition
-    });
+    const deployed = await this.http.request(
+      "/api/v2/monitors/deploy",
+      {
+        method: "POST",
+        body: definition
+      }
+    );
+    if (definition.tool !== "deepline.deanonymizer") return deployed;
+    const setup = await this.setupMonitor(
+      definition.tool,
+      definition.payload ?? {}
+    );
+    return {
+      ...deployed,
+      monitor: {
+        ...deployed.monitor && typeof deployed.monitor === "object" ? deployed.monitor : {},
+        tracking: setup.tracking ?? null,
+        ip2company: setup.ip2company ?? null
+      }
+    };
   }
   /** List deployed monitors. Prefer `client.monitors.list(...)`. */
   async listMonitors(options) {
@@ -5415,6 +5433,24 @@ var DeeplineClient = class {
       { method: "GET" }
     );
   }
+  async testMonitorWebhook(key, payload) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
+      { method: "POST", body: { payload } }
+    );
+  }
+  async setupMonitor(tool, payload) {
+    return this.http.request(
+      `/api/v2/monitors/setup/${encodeURIComponent(tool)}`,
+      { method: "POST", body: payload }
+    );
+  }
+  async validateMonitor(key) {
+    return this.http.request(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/validate`,
+      { method: "POST", body: {} }
+    );
+  }
   /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
   async getMonitorDependents(key) {
     return this.http.request(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {