deepline 0.3.74 → 0.3.76

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

@@ -128,6 +128,10 @@ 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';
 const EXECUTE_RESPONSE_INTENT_HEADER = 'x-deepline-execute-response-intent';
+const MONITOR_NON_RETRYABLE_MUTATION_OPTIONS = {
+  maxRetries: 0,
+  exactUrlOnly: true,
+};
 const RAW_V2_EXECUTE_RESPONSE_CONTRACT = RAW_V2_TOOL_RESPONSE_CONTRACT;
 const COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1_000];
 const REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY = 3;
@@ -771,6 +775,8 @@ export type MonitorsListResult = {
   monitors?: MonitorListEntry[];
   total?: number;
   returned?: number;
+  has_more?: boolean;
+  /** @deprecated Use has_more. */
   is_truncated?: boolean;
   next_cursor?: string | null;
   status_filter_applied?: string;
@@ -786,6 +792,7 @@ export type MonitorsListOptions = {
   limit?: number | string;
   /** Page past a truncated result using a prior response's `next_cursor`. */
   cursor?: string;
+  /** @deprecated Accepted as a no-op for compatibility. */
   compact?: boolean;
   /** Include bounded current SQL-listener delivery/run health (requires limit <= 20). */
   includeConsumers?: boolean;
@@ -849,6 +856,15 @@ export type MonitorUpdateResult = {
 export type MonitorDeleteResult = Record<string, unknown>;
 export type MonitorReactivateResult = Record<string, unknown>;
 export type MonitorTestResult = Record<string, unknown>;
+
+/**
+ * @deprecated Monitor tests are always validation-only. `dispatch` and
+ * `validationOnly: false` are rejected before a request is made.
+ */
+export type MonitorTestOptions = {
+  validationOnly?: boolean;
+  dispatch?: boolean;
+};
 export type MonitorValidateResult = Record<string, unknown>;
 
 /**
@@ -867,7 +883,10 @@ export type MonitorFleetStatus =
   | 'converged'
   | 'degraded'
   | 'deactivating'
-  | 'deactivated';
+  | 'deactivated'
+  | 'billing_suspending'
+  | 'billing_suspended'
+  | 'billing_reactivating';
 
 export type MonitorFleetSyncOptions = {
   /** Return the plan without changing fleet state (`dry_run: true`). */
@@ -891,6 +910,10 @@ export type MonitorFleetDeactivateOptions = {
   idempotencyKey?: string;
 };
 
+export type MonitorFleetReactivateOptions = {
+  idempotencyKey?: string;
+};
+
 export type MonitorFleetWaitOptions = {
   /** Give up after this long. Default 10 minutes. */
   timeoutMs?: number;
@@ -928,6 +951,11 @@ export type MonitorFleetsNamespace = {
     fleetId: string,
     options?: MonitorFleetDeactivateOptions,
   ) => Promise<MonitorFleetResult>;
+  /** Explicitly recreate a fleet after a credit-triggered suspension. */
+  reactivate: (
+    fleetId: string,
+    options?: MonitorFleetReactivateOptions,
+  ) => Promise<MonitorFleetResult>;
   /** Poll the fleet until the server reports a terminal status (or the timeout elapses). */
   waitForConvergence: (
     fleetId: string,
@@ -935,6 +963,104 @@ export type MonitorFleetsNamespace = {
   ) => Promise<MonitorFleetResult>;
 };
 
+/**
+ * Delivery and convergence health for a scope, from
+ * `GET /api/v2/monitors/health`.
+ *
+ * Counts and bounded samples on purpose. It is also what `--watch` polls, so
+ * its shape is fixed independently of the transport: phase 2b publishes the
+ * same object over a reactive subscription without changing this contract.
+ */
+export type MonitorsHealth = {
+  ok?: boolean;
+  scope: { org_id: string; fleet_id?: string };
+  scanned: number;
+  /** True when the scope was larger than one bounded read; counts are partial. */
+  truncated: boolean;
+  desired: { active: number; inactive: number; unset: number };
+  observed: {
+    active: number;
+    inactive: number;
+    missing: number;
+    unknown: number;
+    unset: number;
+  };
+  converged: number;
+  needs_repair: number;
+  /** Observed active, but nothing delivered inside `silent_window_days`. */
+  silent: number;
+  silent_window_days: number;
+  deactivation_reasons: Array<{
+    reason: string;
+    count: number;
+    summary: string | null;
+    resolution: string | null;
+  }>;
+  worst_offenders: Array<{
+    monitor_key: string;
+    tool: string;
+    last_event_at: number | null;
+    observed_at: number | null;
+    provider_resource_id: string | null;
+  }>;
+};
+
+/** One bounded audit pass, from `POST /api/v2/monitors/audit`. */
+export type MonitorsAuditResult = {
+  ok?: boolean;
+  scope: { org_id: string; fleet_id?: string };
+  audit: {
+    scanned: number;
+    asked: number;
+    observed: {
+      active: number;
+      inactive: number;
+      missing: number;
+      unknown: number;
+    };
+    /** Observations a concurrent settle overtook. Not an error. */
+    stale: number;
+    absent: number;
+    /** Capabilities that declare no batch read, so nothing could be asked. */
+    unauditable_capabilities: string[];
+    complete: boolean;
+    /** Non-null when the scope was larger than one pass. Pass it back. */
+    cursor: string | null;
+  };
+  health: MonitorsHealth;
+};
+
+/** One repair pass or plan, from `POST /api/v2/monitors/repair`. */
+export type MonitorsRepairResult = {
+  ok?: boolean;
+  dry_run: boolean;
+  scope: { org_id: string; fleet_id?: string };
+  repair: {
+    scanned: number;
+    queued: number;
+    plan: Array<{
+      monitor_key: string;
+      action: 'create' | 'remove';
+      desired: 'active' | 'inactive';
+      observed: 'active' | 'inactive' | 'missing';
+      deactivation_reason?: string;
+    }>;
+    /** Disagreeing monitors no fleet owns; the convergence driver cannot move them. */
+    unowned: string[];
+    /** Monitors nobody has observed. Run audit first. */
+    unaudited: string[];
+    /**
+     * Monitors with a provider operation still in flight. Deepline's own
+     * convergence loop owns these; repair leaves them alone rather than risk
+     * asking the provider to do the same work twice.
+     */
+    fenced: string[];
+    refused: string[];
+    complete: boolean;
+  };
+  health: MonitorsHealth;
+};
+
 /**
  * Public monitors namespace exposed as `client.monitors`.
  *
@@ -969,14 +1095,11 @@ export type MonitorsNamespace = {
   list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
   /** Fetch one deployed monitor by public key with bounded current listener health. */
   get: (key: string) => Promise<MonitorDetail>;
-  /**
-   * Test a deployed monitor. `validationOnly` safely verifies the callback
-   * envelope; omitted options preserve the historic full-ingestion behavior.
-   */
+  /** Test a deployed monitor's callback envelope without side effects. */
   test: (
     key: string,
     payload: Record<string, unknown>,
-    options?: { validationOnly?: boolean; dispatch?: boolean },
+    options?: MonitorTestOptions,
   ) => Promise<MonitorTestResult>;
   validate: (key: string) => Promise<MonitorValidateResult>;
   /** List the published plays depending on one monitor's output streams. */
@@ -996,6 +1119,24 @@ export type MonitorsNamespace = {
     key: string,
     options?: { dryRun?: boolean },
   ) => Promise<MonitorReactivateResult>;
+  /**
+   * Re-read what the provider holds onto the monitors that claim it. Bounded
+   * and idempotent: pass `cursor` back while `audit.cursor` is non-null.
+   */
+  audit: (options?: {
+    fleetId?: string;
+    cursor?: string | null;
+  }) => Promise<MonitorsAuditResult>;
+  /**
+   * Converge the monitors whose desired and observed states disagree.
+   * `dryRun` returns the same plan without queueing anything.
+   */
+  repair: (options?: {
+    fleetId?: string;
+    dryRun?: boolean;
+  }) => Promise<MonitorsRepairResult>;
+  /** Delivery and convergence health for the workspace or one fleet. */
+  health: (options?: { fleetId?: string }) => Promise<MonitorsHealth>;
   /** Define, reconcile, and control table-backed monitor fleets. */
   fleets: MonitorFleetsNamespace;
 };
@@ -1915,6 +2056,9 @@ export class DeeplineClient {
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options) => this.deleteMonitor(key, options),
       reactivate: (key, options) => this.reactivateMonitor(key, options),
+      audit: (options) => this.auditMonitors(options),
+      repair: (options) => this.repairMonitors(options),
+      health: (options) => this.readMonitorsHealth(options),
       fleets: {
         sync: (definitionOrId, options) =>
           this.syncMonitorFleet(definitionOrId, options),
@@ -1925,6 +2069,8 @@ export class DeeplineClient {
         list: () => this.listMonitorFleets(),
         deactivate: (fleetId, options) =>
           this.deactivateMonitorFleet(fleetId, options),
+        reactivate: (fleetId, options) =>
+          this.reactivateMonitorFleet(fleetId, options),
         waitForConvergence: (fleetId, options) =>
           this.waitForMonitorFleetConvergence(fleetId, options),
       },
@@ -4073,13 +4219,29 @@ export class DeeplineClient {
     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');
     }
-    const suffix = params.toString() ? `?${params.toString()}` : '';
-    const response = await this.http.get<{ plays: PlayListItem[] }>(
-      `/api/v2/plays${suffix}`,
-    );
-    return response.plays ?? [];
+    type PlayListResponse = {
+      plays?: PlayListItem[];
+      cursor?: string | null;
+      hasMore?: boolean;
+      pagination?: { cursor?: string | null; hasMore?: boolean };
+    };
+    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. */
@@ -4838,6 +5000,55 @@ export class DeeplineClient {
     };
   }
 
+  /**
+   * One bounded audit pass. Prefer `client.monitors.audit(...)`.
+   *
+   * Never auto-retried: it is idempotent, but a retry that races the caller's
+   * own next pass would spend a provider slot to learn nothing new.
+   */
+  async auditMonitors(options?: {
+    fleetId?: string;
+    cursor?: string | null;
+  }): Promise<MonitorsAuditResult> {
+    return this.http.request<MonitorsAuditResult>('/api/v2/monitors/audit', {
+      method: 'POST',
+      body: {
+        ...(options?.fleetId ? { fleet_id: options.fleetId } : {}),
+        ...(options?.cursor ? { cursor: options.cursor } : {}),
+      },
+      maxRetries: 0,
+    });
+  }
+
+  /** One repair pass or plan. Prefer `client.monitors.repair(...)`. */
+  async repairMonitors(options?: {
+    fleetId?: string;
+    dryRun?: boolean;
+  }): Promise<MonitorsRepairResult> {
+    return this.http.request<MonitorsRepairResult>('/api/v2/monitors/repair', {
+      method: 'POST',
+      body: {
+        ...(options?.fleetId ? { fleet_id: options.fleetId } : {}),
+        ...(options?.dryRun === undefined ? {} : { dry_run: options.dryRun }),
+      },
+      maxRetries: 0,
+    });
+  }
+
+  /** Delivery and convergence health. Prefer `client.monitors.health(...)`. */
+  async readMonitorsHealth(options?: {
+    fleetId?: string;
+  }): Promise<MonitorsHealth> {
+    const params = new URLSearchParams();
+    if (options?.fleetId) params.set('fleet_id', options.fleetId);
+    const query = params.toString();
+    const suffix = query ? `?${query}` : '';
+    return this.http.request<MonitorsHealth>(
+      `/api/v2/monitors/health${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
@@ -4953,7 +5164,8 @@ export class DeeplineClient {
     if (options?.limit !== undefined)
       params.set('limit', String(options.limit));
     if (options?.cursor) params.set('cursor', options.cursor);
-    if (options?.compact) params.set('compact', 'true');
+    // `compact` used to promise a semantic projection. It is deliberately a
+    // no-op now: audit fields must never disappear from a list response.
     if (options?.includeConsumers) params.set('include_consumers', 'true');
     const query = params.toString();
     // Single interpolation only — see availableMonitors: a nested template in
@@ -4976,19 +5188,24 @@ export class DeeplineClient {
   async testMonitorWebhook(
     key: string,
     payload: Record<string, unknown>,
-    options?: { validationOnly?: boolean; dispatch?: boolean },
+    options?: MonitorTestOptions,
   ): Promise<MonitorTestResult> {
+    if (options?.dispatch === true || options?.validationOnly === false) {
+      throw new DeeplineError(
+        'Monitor tests are validation-only and cannot dispatch events.',
+        undefined,
+        'MONITOR_TEST_DISPATCH_NOT_SUPPORTED',
+      );
+    }
     return this.http.request<MonitorTestResult>(
       `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
       {
         method: 'POST',
         body: {
           payload,
-          ...(options?.validationOnly
-            ? { mode: 'validation_only' }
-            : options?.dispatch
-              ? { mode: 'dispatch' }
-              : {}),
+          // Send the legacy safe mode as well as accepting it server-side: an
+          // upgraded SDK must be safe when it reaches a still-running server.
+          mode: 'validation_only',
         },
       },
     );
@@ -5026,7 +5243,14 @@ export class DeeplineClient {
   ): Promise<MonitorUpdateResult> {
     return this.http.request<MonitorUpdateResult>(
       `/api/v2/monitors/deployed/${encodeURIComponent(key)}`,
-      { method: 'PATCH', body: patch },
+      {
+        method: 'PATCH',
+        body: patch,
+        // A monitor write may have reached the control plane before a network
+        // failure reaches the caller. Do not turn that unknown outcome into a
+        // second mutation with a fresh snapshot.
+        ...MONITOR_NON_RETRYABLE_MUTATION_OPTIONS,
+      },
     );
   }
 
@@ -5051,7 +5275,14 @@ export class DeeplineClient {
     const query = params.toString();
     return this.http.request<MonitorDeleteResult>(
       `/api/v2/monitors/deployed/${encodeURIComponent(key)}${query ? `?${query}` : ''}`,
-      { method: 'DELETE' },
+      options?.dryRun
+        ? { method: 'DELETE' }
+        : {
+            method: 'DELETE',
+            // Deletion is a provider lifecycle operation. A timeout is an
+            // unknown outcome, not authority to begin another delete attempt.
+            ...MONITOR_NON_RETRYABLE_MUTATION_OPTIONS,
+          },
     );
   }
 
@@ -5066,7 +5297,15 @@ export class DeeplineClient {
     const query = options?.dryRun ? '?dry_run=true' : '';
     return this.http.request<MonitorReactivateResult>(
       `/api/v2/monitors/deployed/${encodeURIComponent(key)}/reactivate${query}`,
-      { method: 'POST', body: {} },
+      options?.dryRun
+        ? { method: 'POST', body: {} }
+        : {
+            method: 'POST',
+            body: {},
+            // Reactivation can create an upstream resource, so it must not use
+            // the generic transport's automatic replay policy.
+            ...MONITOR_NON_RETRYABLE_MUTATION_OPTIONS,
+          },
     );
   }
 
@@ -5170,6 +5409,25 @@ export class DeeplineClient {
     );
   }
 
+  async reactivateMonitorFleet(
+    fleetId: string,
+    options?: MonitorFleetReactivateOptions,
+  ): Promise<MonitorFleetResult> {
+    return this.http.request<MonitorFleetResult>(
+      `${this.monitorFleetPath(fleetId)}/reactivate`,
+      {
+        method: 'POST',
+        body: {},
+        headers: this.monitorFleetHeaders(
+          'reactivate',
+          options?.idempotencyKey,
+        ),
+        maxRetries: 0,
+        exactUrlOnly: true,
+      },
+    );
+  }
+
   /**
    * Poll one fleet until the server reports a terminal status.
    *

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

@@ -541,6 +541,24 @@ function getResolvedProjectAuthSource(
 /**
  * Resolve SDK configuration from the public SDK CLI env contract.
  */
+/**
+ * Base URL only, with no API key requirement. The GitHub connect flow is the
+ * chicken-and-egg case: it is the FIRST command a workspace runs, it only
+ * opens a browser URL, and the browser session — not an API key — carries the
+ * authorization. Requiring a key here would make the entry point unreachable.
+ */
+export function resolveBaseUrlOnly(options?: DeeplineClientOptions): string {
+  const baseUrl = normalizeBaseUrl(
+    options?.baseUrl?.trim() || autoDetectBaseUrl(),
+  );
+  if (!baseUrl) {
+    throw new ConfigError(
+      `Invalid ${HOST_URL_ENV}. Expected an http(s) URL such as https://code.deepline.com.`,
+    );
+  }
+  return baseUrl;
+}
+
 export function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig {
   const baseUrl = normalizeBaseUrl(
     options?.baseUrl?.trim() || autoDetectBaseUrl(),
@@ -762,9 +780,9 @@ function findNearestProjectMarkerDir(startDir: string): string | null {
  * project. A project is a marked checkout, a Cowork-mounted project, or a
  * folder that already carries Deepline project auth.
  *
- * The result intentionally does not expose an API key. It lets the CLI reject
- * cloud mutations which would otherwise inherit a different project's shared
- * host-level organization selection.
+ * The result intentionally does not expose an API key. CLI diagnostics use it
+ * to show whether a project-specific pin is available while preserving
+ * compatibility with valid global credentials.
  */
 export function resolveCliAuthProvenance(
   config: Pick<ResolvedConfig, 'baseUrl' | 'apiKey'>,

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

@@ -87,6 +87,7 @@ export type {
   MonitorDeleteResult,
   MonitorReactivateResult,
   MonitorFleetDeactivateOptions,
+  MonitorFleetReactivateOptions,
   MonitorFleetGetOptions,
   MonitorFleetSyncOptions,
   MonitorFleetStatus,

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

@@ -290,8 +290,8 @@ export type { PreviousCell } from '../../shared_libs/plays/cell-staleness.js';
  * Keyword-style request object for `ctx.tools.execute(...)`.
  *
  * The `tool` value comes from live tool discovery. The `id` is the stable
- * logical call name used for logs, metadata, and receipt attachment. Provider
- * call reuse is keyed by play, tool, semantic input, auth scope, provider action
+ * logical call name used for logs, metadata, and result-cache identity. Provider
+ * result reuse is keyed by play, tool, semantic input, auth scope, provider action
  * version, and cache policy.
  *
  * @sdkReference runtime 160
@@ -1626,10 +1626,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
 /** @internal Contextually type unannotated monitor-event handlers as unknown. */
 export function definePlay<TOutput extends PlayReturnObject>(
   name: string,
-  fn: (
-    context: DeeplinePlayRuntimeContext,
-    input: unknown,
-  ) => Promise<TOutput>,
+  fn: (context: DeeplinePlayRuntimeContext, input: unknown) => Promise<TOutput>,
   bindings: PlayBindings<never> & {
     readonly sqlListeners: readonly SqlListenerDeclaration[];
   },

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

@@ -199,7 +199,7 @@ export const SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: '0.3.74',
+  version: '0.3.76',
   updateSummary:
     'Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.',
   packageCapabilities: {

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

@@ -282,8 +282,9 @@ export interface ToolDefinition {
     term?: string;
   }>;
   /**
-   * Whether this tool is callable in the current workspace. `false` for a
-   * bring-your-own-credential provider that has not been connected.
+   * Whether this tool is callable in the current workspace. `false` when a
+   * required customer credential is missing or a managed provider is
+   * temporarily unavailable.
    */
   connected?: boolean;
   /** Whether the tool can be executed. Exact lookup may return non-callable deprecated aliases. */