deepline 0.3.88 → 0.3.90

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

@@ -1,3 +1,4 @@
+import { iterateCursorPages } from './pagination.js';
 /**
  * The main API client for interacting with the Deepline platform.
  *
@@ -37,6 +38,16 @@ import { resolveConfig } from './config.js';
 import { DeeplineError } from './errors.js';
 import { HttpClient } from './http.js';
 import { PRODUCT_NOTIFICATION_SLACK_OAUTH_SCOPES } from '../../shared_libs/product-notifications/contract.js';
+import {
+  DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
+  normalizeProductNotificationEmail,
+} from '../../shared_libs/product-notifications/configuration.js';
+import {
+  type ProductNotificationConfigurationChange,
+  type EffectiveProductNotificationDestination,
+  type EffectiveProductNotificationGroup,
+  type ProductNotificationGroupDraft,
+} from '../../shared_libs/product-notifications/configuration.js';
 import {
   STREAM_HEALTHY_CONNECTION_MS,
   isTransientPlayStreamError,
@@ -60,6 +71,7 @@ import type {
   PlayLiveEvent,
   PlayListItem,
   ProductNotificationSettings,
+  ProductNotificationConfigurationResponse,
   PlayDescription,
   StopPlayRunResult,
   StopAllPlayRunsResult,
@@ -88,11 +100,11 @@ import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
 import { RUNTIME_ENVIRONMENT_TOKEN_HEADER } from '../../shared_libs/play-runtime/coordinator-headers.js';
-import { resolveTheirstackClientTimeoutMs } from '../../shared_libs/integrations/theirstack-execution-policy.js';
+import { resolveTheirstackClientTimeoutMs } from '../../shared_libs/integration-contracts/theirstack/execution-policy.js';
 import {
   BETTERCONTACT_LAUNCHER_CLIENT_TIMEOUT_MS,
   usesExtendedBetterContactLauncherBudget,
-} from '../../shared_libs/integrations/bettercontact-execution-policy.js';
+} from '../../shared_libs/integration-contracts/bettercontact/execution-policy.js';
 import {
   normalizePlayRuntimeEnvironment,
   normalizePlayRuntimeNamespace,
@@ -124,6 +136,76 @@ export type UpdateNotificationInput =
   | { enabled: boolean }
   | ({ name: string; eventTypes: string[] } & SlackNotificationTarget);
 
+export type CreateNotificationGroupInput = {
+  name: string;
+  targets: string[];
+  legacyEvents?: string[];
+  dryRun?: boolean;
+};
+
+export type CreateNotificationGroupResult =
+  | {
+      mode: 'dry_run';
+      compatibilityMode: boolean;
+      name: string;
+      targets: string[];
+      legacyEvents: string[];
+    }
+  | { mode: 'legacy'; notification: unknown }
+  | {
+      mode: 'native';
+      groupKey: string;
+      targets: string[];
+      group: EffectiveProductNotificationGroup;
+      destinations: EffectiveProductNotificationDestination[];
+    };
+
+type ParsedNotificationGroupTarget =
+  | { kind: 'email'; email: string }
+  | { kind: 'slack'; channel: string }
+  | { kind: 'slack'; memberId: string };
+
+const MAX_NOTIFICATION_GROUP_CREATE_TARGETS = 50;
+
+function parseNotificationGroupTarget(
+  value: string,
+): ParsedNotificationGroupTarget {
+  const normalized = value.trim();
+  if (normalized.toLowerCase().startsWith('email:')) {
+    const email = normalizeProductNotificationEmail(normalized.slice(6));
+    if (!email) {
+      throw new Error(
+        `Invalid email notification target "${value}". Use --to email:name@example.com.`,
+      );
+    }
+    return { kind: 'email', email };
+  }
+  const slack = /^slack:(.+)$/i.exec(normalized)?.[1]?.trim();
+  if (!slack) {
+    const provider = normalized.split(':', 1)[0] || normalized;
+    throw new Error(
+      `Unsupported notification destination "${provider}". Use email: or slack:.`,
+    );
+  }
+  const member = /^member:([UW][A-Z0-9]{8,})$/i.exec(slack);
+  if (member?.[1]) {
+    return { kind: 'slack', memberId: member[1].toUpperCase() };
+  }
+  if (slack.toLowerCase().startsWith('member:')) {
+    throw new Error(
+      'Slack member IDs must look like slack:member:U0123456789.',
+    );
+  }
+  if (!slack.replace(/^#/, '').trim()) {
+    throw new Error('Use --to slack:#channel.');
+  }
+  return { kind: 'slack', channel: slack };
+}
+
+function notificationObjectKey(kind: 'group' | 'destination') {
+  return `${kind}.${globalThis.crypto.randomUUID()}`;
+}
+
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
 const EXECUTE_RESPONSE_CONTRACT_HEADER = 'x-deepline-execute-response-contract';
@@ -514,6 +596,35 @@ export type RunsListOptions = {
   offset?: number;
 };
 
+/** One server page; legacy runs.list continues to return an array. */
+export type RunsListPage = {
+  runs: PlayRunListItem[];
+  total?: number;
+  offset?: number;
+  limit?: number;
+  hasMore?: boolean;
+};
+
+export type PlaysListOptions = {
+  origin?: 'prebuilt' | 'owned';
+  grep?: string;
+  /**
+   * @deprecated Grep is always evaluated by the Convex full-text index.
+   * This retained option is ignored for source compatibility.
+   */
+  grepMode?: 'all' | 'any' | 'phrase';
+  categories?: string | string[];
+  includeToolCategories?: boolean;
+  includeArchived?: boolean;
+  includeCostEstimates?: boolean;
+};
+
+export type PlaysListPage = {
+  plays: PlayListItem[];
+  cursor: string | null;
+  hasMore: boolean;
+};
+
 /** Options for `client.runs.get(...)`. */
 export type RunsGetOptions = {
   /** Return the raw status payload instead of the compact package. */
@@ -645,12 +756,17 @@ export type PlaySecretMetadata = {
   lastUsedAt?: number;
 };
 
+export type PlaySecretCheck = {
+  ok: boolean;
+  name: string;
+  playName: string | null;
+  reason: 'active' | 'missing' | 'disabled' | 'empty' | 'invalid_version';
+  secret: PlaySecretMetadata | null;
+};
+
 /**
- * Public runs namespace exposed as `client.runs`.
- *
- * This namespace mirrors the canonical `/api/v2/runs` resource family and is
- * the preferred low-level surface for polling, streaming, stopping, reading
- * logs, and exporting durable dataset rows.
+ * `client.runs` mirrors `/api/v2/runs`: the preferred low-level surface for
+ * polling, streaming, stopping, reading logs, and exporting durable dataset rows.
  *
  * @sdkReference client 020 client.runs
  */
@@ -675,6 +791,8 @@ export type RunsNamespace = {
   }>;
   /** List runs for one play, optionally filtered by status. */
   list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
+  /** Read one run page with total, offset, limit and completeness metadata. */
+  listPage: (options: RunsListOptions) => Promise<RunsListPage>;
   /** Stream run events and return the latest/terminal run status. */
   tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
   /** Fetch persisted log lines for a run. */
@@ -930,6 +1048,62 @@ export type MonitorFleetWaitOptions = {
   until?: 'converged' | 'deactivated';
 };
 
+/** A durable monitor batch can name a small key set, a query target, or one Fleet. */
+export type MonitorBatchScope =
+  | { kind: 'keys'; monitorKeys: string[] }
+  | {
+      kind: 'target';
+      target: 'all' | 'all-active' | 'billing-suspended' | 'needs-repair';
+    }
+  | { kind: 'fleet'; fleetId: string };
+
+export type MonitorBatchExistingSubmitOptions = {
+  kind: 'audit' | 'deactivate' | 'reactivate' | 'repair';
+  scope: MonitorBatchScope;
+  dryRun?: boolean;
+  /** Required for deactivate; it is the declared reason shown by health/UI. */
+  deactivationReason?: string;
+  /** Stable retry key. Reusing it joins the original durable operation. */
+  idempotencyKey: string;
+};
+
+/** Complete definitions, one JSON object per line; uploaded as bounded shards. */
+export type MonitorBatchDeploySubmitOptions = {
+  kind: 'deploy';
+  manifestNdjson: string;
+  dryRun?: boolean;
+  /** Stable retry key. Reusing it joins the same content-addressed manifest. */
+  idempotencyKey: string;
+};
+
+export type MonitorBatchSubmitOptions =
+  | MonitorBatchExistingSubmitOptions
+  | MonitorBatchDeploySubmitOptions;
+
+export type MonitorBatchOperationResult = {
+  ok?: boolean;
+  rejoined?: boolean;
+  operation: {
+    runId: string;
+    kind: 'audit' | 'deactivate' | 'reactivate' | 'deploy' | 'repair';
+    state: 'running' | 'retry_scheduled' | 'completed' | 'failed';
+    dryRun: boolean;
+    scope: unknown;
+    submittedAt: number;
+    updatedAt: number;
+    deactivationReason?: string;
+    nextAttemptAt?: number;
+    completedAt?: number;
+    summary?: Record<string, unknown>;
+    lastError?: string;
+  };
+  results?: {
+    page: Array<Record<string, unknown>>;
+    isDone: boolean;
+    continueCursor: string;
+  };
+};
+
 export type MonitorFleetsNamespace = {
   /**
    * Create, update, or re-plan a fleet. Pass a definition to admit new source
@@ -963,6 +1137,16 @@ export type MonitorFleetsNamespace = {
   ) => Promise<MonitorFleetResult>;
 };
 
+export type MonitorBatchNamespace = {
+  submit: (
+    options: MonitorBatchSubmitOptions,
+  ) => Promise<MonitorBatchOperationResult>;
+  get: (
+    operationId: string,
+    options?: { cursor?: string | null },
+  ) => Promise<MonitorBatchOperationResult>;
+};
+
 /**
  * Delivery and convergence health for a scope, from
  * `GET /api/v2/monitors/health`.
@@ -977,6 +1161,16 @@ export type MonitorsHealth = {
   scanned: number;
   /** True when the scope was larger than one bounded read; counts are partial. */
   truncated: boolean;
+  /**
+   * A durable whole-scope snapshot is rebuilding. Counts remain intentionally
+   * partial until it completes; older servers omit this additive field.
+   */
+  refresh?: {
+    state: 'running' | 'completed';
+    started_at: number;
+    updated_at: number;
+    completed_at: number | null;
+  };
   desired: { active: number; inactive: number; unset: number };
   observed: {
     active: number;
@@ -987,6 +1181,11 @@ export type MonitorsHealth = {
   };
   converged: number;
   needs_repair: number;
+  /**
+   * Unknown records without an upstream resource id. Use the exact inventory
+   * reconciler to align them; ordinary repair never guesses an identity.
+   */
+  alignment_required: number;
   /** Observed active, but nothing delivered inside `silent_window_days`. */
   silent: number;
   silent_window_days: number;
@@ -1003,6 +1202,27 @@ export type MonitorsHealth = {
     observed_at: number | null;
     provider_resource_id: string | null;
   }>;
+  /** Bounded current durable monitor work, if the server supports it. */
+  batch_operations?: Array<{
+    run_id: string;
+    kind: 'audit' | 'deactivate' | 'reactivate' | 'repair' | 'deploy';
+    state: 'running' | 'retry_scheduled';
+    updated_at: number;
+    next_attempt_at?: number;
+    summary?: Record<string, unknown>;
+  }>;
+  /** Bounded sample explaining why normal audit did not settle the row. */
+  unaudited_monitors: Array<{
+    monitor_key: string;
+    tool: string;
+    observed: 'unknown' | null;
+    observed_at: number | null;
+    provider_resource_id: string | null;
+    reason:
+      | 'not_yet_audited'
+      | 'missing_provider_resource_id'
+      | 'provider_observation_unknown';
+  }>;
 };
 
 /** One bounded audit pass, from `POST /api/v2/monitors/audit`. */
@@ -1137,12 +1357,16 @@ export type MonitorsNamespace = {
   }) => Promise<MonitorsRepairResult>;
   /** Delivery and convergence health for the workspace or one fleet. */
   health: (options?: { fleetId?: string }) => Promise<MonitorsHealth>;
+  /** Durable bulk audit/deactivation/reactivation/repair with retained progress. */
+  batch: MonitorBatchNamespace;
   /** Define, reconcile, and control table-backed monitor fleets. */
   fleets: MonitorFleetsNamespace;
 };
 
 /** One credit grant pool reported by the billing subscription status endpoint. */
 export type BillingCreditPool = {
+  /** Stable grant identity; optional when talking to an older server. */
+  grant_id?: string;
   pool: string;
   credits_remaining: number;
   credits_granted: number;
@@ -1227,10 +1451,10 @@ export type TargetBillingOperation = {
 };
 
 export type TargetBillingPlan = {
-  sku: 'payg-v1' | 'builder-v1' | 'team-v1';
+  sku: 'payg-v1' | 'builder-v1' | 'growth-v1' | 'growth-canary-v1' | 'team-v1';
   name: string;
   recurring_price_usd: number;
-  interval: 'month';
+  interval: 'month' | 'year';
   included_credits: number;
   purchased_credit_price_usd: number;
 };
@@ -1293,7 +1517,12 @@ export type TargetBillingMutationResult = {
 export type TargetBillingPlanTransitionOptions =
   | {
       action: 'start_or_change';
-      targetPlanSku: 'payg-v1' | 'builder-v1' | 'team-v1';
+      targetPlanSku:
+        | 'payg-v1'
+        | 'builder-v1'
+        | 'growth-v1'
+        | 'growth-canary-v1'
+        | 'team-v1';
       idempotencyKey: string;
     }
   | {
@@ -1379,7 +1608,12 @@ export type WorkspaceCreateResult = {
   org_name: string;
   org_slug: string;
   plan_sku: 'payg-v1';
-  rate_policy_ref: 'payg-rates-v2';
+  /**
+   * The PAYG rate policy the workspace was provisioned onto, taken from the
+   * catalog revision its operation pinned: v4 bound payg-rates-v2, v5 binds
+   * the flat payg-rates-v3.
+   */
+  rate_policy_ref: 'payg-rates-v2' | 'payg-rates-v3';
   operation: {
     id: string;
     state: 'completed';
@@ -2007,6 +2241,7 @@ export class DeeplineClient {
     this.runs = {
       get: (runId, options) => this.getRunStatus(runId, options),
       list: (options) => this.listRuns(options),
+      listPage: (options) => this.listRunsPage(options),
       tail: (runId, options) => this.tailRun(runId, options),
       logs: (runId, options) => this.getRunLogs(runId, options),
       input: (runId) => this.getRunInput(runId),
@@ -2059,6 +2294,11 @@ export class DeeplineClient {
       audit: (options) => this.auditMonitors(options),
       repair: (options) => this.repairMonitors(options),
       health: (options) => this.readMonitorsHealth(options),
+      batch: {
+        submit: (options) => this.submitMonitorBatch(options),
+        get: (operationId, options) =>
+          this.getMonitorBatch(operationId, options),
+      },
       fleets: {
         sync: (definitionOrId, options) =>
           this.syncMonitorFleet(definitionOrId, options),
@@ -2271,6 +2511,20 @@ export class DeeplineClient {
     );
   }
 
+  /** Check effective scope and active-version health without reading the value.
+   * Without playName, checks the organization-scoped secret only. With a Play
+   * name, an active Play secret takes precedence; a deleted/disabled Play
+   * secret falls back to the organization-scoped secret.
+   */
+  async inspectSecret(
+    name: string,
+    options: { playName?: string } = {},
+  ): Promise<PlaySecretCheck> {
+    const params = new URLSearchParams({ name: name.trim().toUpperCase() });
+    if (options.playName !== undefined) params.set('play', options.playName);
+    return this.http.get(`/api/v2/secrets?${params.toString()}`);
+  }
+
   // ——————————————————————————————————————————————————————————
   // Tools
   // ——————————————————————————————————————————————————————————
@@ -2376,6 +2630,10 @@ export class DeeplineClient {
       `/api/v2/integrations/${encodeURIComponent(toolId)}/get`,
       {
         method: 'GET',
+        // Tool metadata is a read-only catalog lookup. Keep the metadata
+        // header while opting into the same transient edge-response retries as
+        // other GET catalog methods such as searchTools().
+        retryApiErrors: true,
         headers: {
           'x-deepline-tool-meta-only': '1',
         },
@@ -3664,6 +3922,11 @@ export class DeeplineClient {
    * ```
    */
   async listRuns(options: RunsListOptions): Promise<PlayRunListItem[]> {
+    return (await this.listRunsPage(options)).runs;
+  }
+
+  /** Read one run page without discarding server pagination metadata. */
+  async listRunsPage(options: RunsListOptions): Promise<RunsListPage> {
     const playName = options.play?.trim();
     const params = new URLSearchParams();
     if (playName) {
@@ -3695,10 +3958,10 @@ export class DeeplineClient {
       throw new Error('runs.list requires options.play or options.status.');
     }
     params.set('compact', 'true');
-    const response = await this.http.get<{ runs: PlayRunListItem[] }>(
+    const response = await this.http.get<RunsListPage>(
       `/api/v2/runs?${params.toString()}`,
     );
-    return response.runs ?? [];
+    return { ...response, runs: response.runs ?? [] };
   }
 
   /**
@@ -4189,20 +4452,46 @@ export class DeeplineClient {
   }
 
   /**
-   * List callable plays visible to the workspace.
+   * List one page of callable plays; grep retains exhaustive matching results.
+   * Use listPlaysPage to retain pagination metadata.
    *
    * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
    * `origin: "owned"` for org-owned plays.
    */
-  async listPlays(options?: {
-    origin?: 'prebuilt' | 'owned';
-    grep?: string;
-    grepMode?: 'all' | 'any' | 'phrase';
-    categories?: string | string[];
-    includeToolCategories?: boolean;
-    includeArchived?: boolean;
-  }): Promise<PlayListItem[]> {
+  async listPlays(options?: PlaysListOptions): Promise<PlayListItem[]> {
+    if (!options?.grep?.trim()) {
+      return (await this.requestPlaysPage(options, false)).plays;
+    }
+    const plays: PlayListItem[] = [];
+    for await (const items of iterateCursorPages(async (cursor) => {
+      const page = await this.listPlaysPage({ ...options, cursor });
+      return { items: page.plays, cursor: page.cursor, hasMore: page.hasMore };
+    })) {
+      plays.push(...items);
+    }
+    return plays;
+  }
+
+  /** Read one bounded inventory page; cursor continues the same filters. */
+  async listPlaysPage(
+    options?: PlaysListOptions & {
+      limit?: number;
+      cursor?: string | null;
+    },
+  ): Promise<PlaysListPage> {
+    return this.requestPlaysPage(options);
+  }
+
+  private async requestPlaysPage(
+    options?: PlaysListOptions & {
+      limit?: number;
+      cursor?: string | null;
+    },
+    paginateInventory = true,
+  ): Promise<PlaysListPage> {
     const params = new URLSearchParams();
+    if (paginateInventory && !options?.grep?.trim())
+      params.set('inventory_paginated', '1');
     if (options?.origin) params.set('origin', options.origin);
     if (options?.categories) {
       params.set(
@@ -4216,32 +4505,32 @@ export class DeeplineClient {
       params.set('include_tool_categories', '1');
     }
     if (options?.includeArchived) params.set('include_archived', '1');
+    if (options?.includeCostEstimates) {
+      params.set('include_cost_estimates', '1');
+    }
     if (options?.grep?.trim()) {
       params.set('grep', options.grep.trim());
-      params.set('grep_mode', options.grepMode ?? 'all');
-      params.set('grep_paginated', '1');
       params.set('limit', '60');
     }
-    type PlayListResponse = {
+    if (options?.limit !== undefined) {
+      if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+        throw new Error('Play page limit must be a positive integer');
+      }
+      params.set('limit', String(options.limit));
+    }
+    if (options?.cursor) params.set('cursor', options.cursor);
+    const suffix = params.size ? `?${params.toString()}` : '';
+    const response = await this.http.get<{
       plays?: PlayListItem[];
       cursor?: string | null;
       hasMore?: boolean;
       pagination?: { cursor?: string | null; hasMore?: boolean };
+    }>(`/api/v2/plays${suffix}`);
+    return {
+      plays: response.plays ?? [],
+      cursor: response.pagination?.cursor ?? response.cursor ?? null,
+      hasMore: Boolean(response.pagination?.hasMore ?? response.hasMore),
     };
-    const plays: PlayListItem[] = [];
-    let cursor: string | null = null;
-    let hasMore = true;
-    do {
-      if (cursor) params.set('cursor', cursor);
-      const suffix = params.toString() ? `?${params.toString()}` : '';
-      const response = await this.http.get<PlayListResponse>(
-        `/api/v2/plays${suffix}`,
-      );
-      plays.push(...(response.plays ?? []));
-      cursor = response.pagination?.cursor ?? response.cursor ?? null;
-      hasMore = Boolean(response.pagination?.hasMore ?? response.hasMore);
-    } while (Boolean(options?.grep?.trim()) && hasMore && cursor);
-    return plays;
   }
 
   /** Set whether an org-owned Play sorts before unpinned Plays. */
@@ -4342,6 +4631,244 @@ export class DeeplineClient {
     return this.http.get('/api/v2/notifications');
   }
 
+  /** Read the group-based product-notification configuration and rule catalog. */
+  async getNotificationConfiguration(): Promise<ProductNotificationConfigurationResponse> {
+    return this.http.get('/api/v2/notifications/configuration');
+  }
+
+  /** Atomically apply one retry-safe desired configuration change. */
+  async changeNotificationConfiguration(
+    expectedWorkspaceVersion: number,
+    change: ProductNotificationConfigurationChange,
+  ): Promise<Pick<ProductNotificationConfigurationResponse, 'configuration'>> {
+    return this.http.put('/api/v2/notifications/configuration', {
+      expectedWorkspaceVersion,
+      change,
+    });
+  }
+
+  /** Create one notification group and its destinations as a retry-safe unit. */
+  async createNotificationGroup(
+    input: CreateNotificationGroupInput,
+  ): Promise<CreateNotificationGroupResult> {
+    const name = input.name.trim().replace(/\s+/g, ' ');
+    if (!name) throw new Error('Notification group name is required.');
+    if (
+      input.targets.length < 1 ||
+      input.targets.length > MAX_NOTIFICATION_GROUP_CREATE_TARGETS
+    ) {
+      throw new Error(
+        `Choose between 1 and ${MAX_NOTIFICATION_GROUP_CREATE_TARGETS} notification targets.`,
+      );
+    }
+
+    const targets = input.targets.map(parseNotificationGroupTarget);
+    const legacyEvents = input.legacyEvents ?? [];
+    const legacyTarget =
+      targets.length === 1 &&
+      targets[0]?.kind === 'slack' &&
+      legacyEvents.length > 0
+        ? targets[0]
+        : null;
+    if (legacyEvents.length > 0 && !legacyTarget) {
+      throw new Error(
+        '--for is supported only by the legacy one-Slack-target form. Create the group first, then add rules in notification configuration.',
+      );
+    }
+
+    if (!legacyTarget && name.toLowerCase() === 'default') {
+      throw new Error(
+        'Default is reserved for the workspace default notification group.',
+      );
+    }
+
+    const normalizedTargets = targets.map((target) =>
+      target.kind === 'email'
+        ? `email:${target.email}`
+        : 'memberId' in target
+          ? `slack:member:${target.memberId}`
+          : `slack:${target.channel}`,
+    );
+    if (input.dryRun) {
+      return {
+        mode: 'dry_run' as const,
+        compatibilityMode: legacyTarget !== null,
+        name: legacyTarget ? input.name : name,
+        targets: normalizedTargets,
+        legacyEvents,
+      };
+    }
+
+    if (legacyTarget) {
+      const notification = await this.createNotification({
+        name: input.name,
+        provider: 'slack',
+        ...('channel' in legacyTarget
+          ? { channel: legacyTarget.channel }
+          : { memberId: legacyTarget.memberId }),
+        eventTypes: legacyEvents,
+      });
+      return { mode: 'legacy' as const, notification };
+    }
+
+    const current = await this.getNotificationConfiguration();
+    const existingGroup = current.configuration.groups.find(
+      (candidate) => candidate.name.toLowerCase() === name.toLowerCase(),
+    );
+    const groupKey = existingGroup?.groupKey ?? notificationObjectKey('group');
+    const group: EffectiveProductNotificationGroup = existingGroup ?? {
+      groupKey,
+      name,
+      enabled: true,
+      deliveryTiming: DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
+      source: 'workspace',
+      configMode: 'custom',
+      version: 0,
+    };
+    const destinations = current.configuration.destinations.filter(
+      (destination) => destination.groupKey === groupKey,
+    );
+
+    const emails = [
+      ...new Set(
+        targets.flatMap((target) =>
+          target.kind === 'email' ? [target.email] : [],
+        ),
+      ),
+    ].sort();
+    const existingEmails = new Set(
+      destinations.flatMap((destination) =>
+        destination.settings.kind === 'email_addresses'
+          ? destination.settings.to
+          : [],
+      ),
+    );
+    const newEmails = emails.filter((email) => !existingEmails.has(email));
+    if (newEmails.length > 0) {
+      destinations.push({
+        destinationKey: notificationObjectKey('destination'),
+        groupKey,
+        name: 'Email recipients',
+        enabled: true,
+        source: 'workspace',
+        configMode: 'custom',
+        version: 0,
+        status: 'active',
+        settings: { kind: 'email_addresses', to: newEmails },
+      });
+    }
+
+    const slackTargets = new Map<
+      string,
+      Extract<ParsedNotificationGroupTarget, { kind: 'slack' }>
+    >();
+    for (const target of targets) {
+      if (target.kind !== 'slack') continue;
+      const targetKey =
+        'memberId' in target
+          ? `member:${target.memberId}`
+          : `channel:${target.channel.replace(/^#/, '').toLowerCase()}`;
+      slackTargets.set(targetKey, target);
+    }
+    const connectionId = current.slackConnection.connectionId;
+    if (slackTargets.size > 0 && !connectionId) {
+      throw new Error(
+        'Slack is not connected to this workspace. Connect it in Dashboard → Integrations, then retry.',
+      );
+    }
+    const resolvedSlackTargets = await Promise.all(
+      [...slackTargets.values()].map(async (target) => {
+        if ('memberId' in target) {
+          return {
+            targetKind: 'member' as const,
+            targetId: target.memberId,
+            targetName: target.memberId,
+          };
+        }
+        const channel = target.channel;
+        const requested = channel.replace(/^#/, '');
+        const response = await this.listNotificationChannels(channel);
+        const matches = response.channels.filter(
+          (candidate) =>
+            candidate.id === requested ||
+            candidate.name.toLowerCase() === requested.toLowerCase(),
+        );
+        if (matches.length !== 1) {
+          throw new Error(
+            matches.length === 0
+              ? `Slack channel ${channel} was not found or is not visible to the Deepline app.`
+              : `Slack channel ${channel} is ambiguous. Use its channel ID.`,
+          );
+        }
+        return {
+          targetKind: 'channel' as const,
+          targetId: matches[0]!.id,
+          targetName: matches[0]!.name,
+        };
+      }),
+    );
+    const uniqueSlackTargets = new Map(
+      resolvedSlackTargets.map((target) => [
+        `${target.targetKind}:${target.targetId}`,
+        target,
+      ]),
+    );
+    for (const target of uniqueSlackTargets.values()) {
+      if (
+        destinations.some(
+          (destination) =>
+            destination.settings.kind === 'slack' &&
+            destination.settings.targetKind === target.targetKind &&
+            destination.settings.targetId === target.targetId,
+        )
+      ) {
+        continue;
+      }
+      destinations.push({
+        destinationKey: notificationObjectKey('destination'),
+        groupKey,
+        name: `${target.targetKind === 'channel' ? '#' : '@'}${target.targetName}`,
+        enabled: true,
+        source: 'workspace',
+        configMode: 'custom',
+        version: 0,
+        status: 'pending_verification',
+        settings: {
+          kind: 'slack',
+          ...target,
+          oauthConnectionId: connectionId!,
+        },
+      });
+    }
+
+    const draft: ProductNotificationGroupDraft = {
+      group,
+      destinations,
+      rules: current.configuration.rules.filter(
+        (rule) => rule.groupKey === groupKey,
+      ),
+    };
+    const result = await this.changeNotificationConfiguration(
+      current.configuration.workspaceVersion,
+      { kind: 'save_group', draft },
+    );
+    const storedGroup = result.configuration.groups.find(
+      (candidate) => candidate.groupKey === groupKey,
+    );
+    if (!storedGroup) {
+      throw new Error('Notification group creation returned no saved group.');
+    }
+    return {
+      mode: 'native' as const,
+      groupKey,
+      targets: normalizedTargets,
+      group: storedGroup,
+      destinations: result.configuration.destinations.filter(
+        (destination) => destination.groupKey === groupKey,
+      ),
+    };
+  }
+
   /** List Slack channels available to an already-connected Slack integration. */
   async listNotificationChannels(query?: string): Promise<{
     identity: { teamId: string; teamName?: string };
@@ -5049,6 +5576,92 @@ export class DeeplineClient {
     );
   }
 
+  /** Submit durable monitor work; transport retries use the same idempotency key. */
+  async submitMonitorBatch(
+    options: MonitorBatchSubmitOptions,
+  ): Promise<MonitorBatchOperationResult> {
+    const idempotencyKey = options.idempotencyKey.trim();
+    if (!idempotencyKey) {
+      throw new DeeplineError(
+        'Monitor batch idempotencyKey is required.',
+        undefined,
+        'INVALID_MONITOR_BATCH_IDEMPOTENCY_KEY',
+      );
+    }
+    if (options.kind === 'deploy') {
+      if (!options.manifestNdjson.trim()) {
+        throw new DeeplineError(
+          'Monitor batch deploy requires a non-empty NDJSON manifest.',
+          undefined,
+          'INVALID_MONITOR_BATCH_MANIFEST',
+        );
+      }
+      return this.http.request<MonitorBatchOperationResult>(
+        '/api/v2/monitors/batch',
+        {
+          method: 'POST',
+          body: {
+            kind: 'deploy',
+            manifest_ndjson: options.manifestNdjson,
+            dry_run: options.dryRun === true,
+            idempotency_key: idempotencyKey,
+          },
+          headers: { 'Idempotency-Key': idempotencyKey },
+          maxRetries: 0,
+          exactUrlOnly: true,
+        },
+      );
+    }
+    const scope =
+      options.scope.kind === 'keys'
+        ? { kind: 'keys', monitor_keys: options.scope.monitorKeys }
+        : options.scope.kind === 'fleet'
+          ? { kind: 'fleet', fleet_id: options.scope.fleetId }
+          : { kind: 'target', target: options.scope.target };
+    return this.http.request<MonitorBatchOperationResult>(
+      '/api/v2/monitors/batch',
+      {
+        method: 'POST',
+        body: {
+          kind: options.kind,
+          scope,
+          dry_run: options.dryRun === true,
+          idempotency_key: idempotencyKey,
+          ...(options.deactivationReason === undefined
+            ? {}
+            : { deactivation_reason: options.deactivationReason }),
+        },
+        headers: { 'Idempotency-Key': idempotencyKey },
+        // Durable submission is itself idempotent, but an ambiguous local retry
+        // must retain the exact key and never turn a CLI attempt into two runs.
+        maxRetries: 0,
+        exactUrlOnly: true,
+      },
+    );
+  }
+
+  /** Get durable batch progress and a bounded retained evidence page. */
+  async getMonitorBatch(
+    operationId: string,
+    options?: { cursor?: string | null },
+  ): Promise<MonitorBatchOperationResult> {
+    const runId = operationId.trim();
+    if (!runId) {
+      throw new DeeplineError(
+        'Monitor batch operation id is required.',
+        undefined,
+        'INVALID_MONITOR_BATCH_OPERATION_ID',
+      );
+    }
+    const params = new URLSearchParams();
+    if (options?.cursor) params.set('cursor', options.cursor);
+    const suffix = params.size > 0 ? `?${params}` : '';
+    return this.http.request<MonitorBatchOperationResult>(
+      `/api/v2/monitors/batch/${encodeURIComponent(runId)}${suffix}`,
+      { method: 'GET' },
+    );
+  }
+
   /**
    * The deployable monitor tools catalog. Pass a tool id (positional or
    * `{ tool }`) to describe one tool's full payload/stream contract, or no tool