deepline 0.3.88 → 0.3.89

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

@@ -49,6 +49,12 @@ export const HOST_URL_ENV = 'DEEPLINE_HOST_URL';
 export const API_KEY_ENV = 'DEEPLINE_API_KEY';
 export const ACTIVE_ORG_ID_ENV = 'DEEPLINE_ACTIVE_ORG_ID';
 export const ACTIVE_ORG_NAME_ENV = 'DEEPLINE_ACTIVE_ORG_NAME';
+/**
+ * Comma-separated gated feature keys the server reported for the active
+ * workspace (`github-deploy`, …). Refreshed whenever credentials are saved;
+ * the CLI hides gated command groups whose key is absent.
+ */
+export const FEATURES_ENV = 'DEEPLINE_FEATURES';
 
 /** Production API base URL. */
 const PROD_URL = 'https://code.deepline.com';
@@ -83,8 +89,70 @@ const CLI_ENV_ALLOWED_KEYS = new Set([
   API_KEY_ENV,
   ACTIVE_ORG_ID_ENV,
   ACTIVE_ORG_NAME_ENV,
+  FEATURES_ENV,
 ]);
 
+/** Env line for a server-reported `features` list; absent input writes nothing. */
+export function featureEnvValues(data: {
+  features?: unknown;
+}): Record<string, string> {
+  if (!Array.isArray(data.features)) return {};
+  return {
+    [FEATURES_ENV]: data.features
+      .filter(
+        (key): key is string => typeof key === 'string' && key.trim() !== '',
+      )
+      .map((key) => key.trim())
+      .join(','),
+  };
+}
+
+/** The API key saved in the host's global credentials, or '' when none. */
+export function storedHostApiKey(baseUrl: string): string {
+  return loadCliEnv(normalizeBaseUrl(baseUrl) || baseUrl)[API_KEY_ENV] ?? '';
+}
+
+/** The raw features line saved with the host's global credentials, if any. */
+export function storedHostFeatures(baseUrl: string): string | undefined {
+  return loadCliEnv(normalizeBaseUrl(baseUrl) || baseUrl)[FEATURES_ENV];
+}
+
+/** Whether a stored features list names `feature`. */
+export function envHasFeature(env: EnvValues, feature: string): boolean {
+  return (env[FEATURES_ENV] ?? '')
+    .split(',')
+    .map((key) => key.trim())
+    .includes(feature);
+}
+
+/**
+ * Whether the active workspace was last seen with `feature` enabled. Reads
+ * the same credential sources, in the same order, as the API key: process
+ * env, the folder credentials pinned to the resolved host, then the host's
+ * global credentials. A host that cannot be resolved counts as no feature.
+ */
+export function cliFeatureEnabled(feature: string): boolean {
+  const processEnv = process.env as EnvValues;
+  if (envHasFeature(processEnv, feature)) return true;
+  // A process-env key wins for API calls, so only process-env features may
+  // describe it: a stored file's list belongs to a different credential.
+  if (processEnv[API_KEY_ENV]?.trim()) return false;
+  try {
+    const baseUrl = resolveBaseUrlOnly();
+    // The credential source that supplies the key also owns the features:
+    // a folder credential with no features line means "none", never "ask
+    // the global file", which may belong to a different workspace.
+    const projectEnv = loadProjectEnvCandidates().find(
+      ({ env }) =>
+        normalizeBaseUrl(env[HOST_URL_ENV] ?? '') === baseUrl &&
+        Boolean(env[API_KEY_ENV]),
+    );
+    return envHasFeature(projectEnv?.env ?? loadCliEnv(baseUrl), feature);
+  } catch {
+    return false;
+  }
+}
+
 export type CliCommandContext = {
   active_organization: {
     org_id: string;
@@ -402,6 +470,12 @@ function mergePersistedEnvValues(
   ) {
     delete merged[ACTIVE_ORG_ID_ENV];
     delete merged[ACTIVE_ORG_NAME_ENV];
+    delete merged[FEATURES_ENV];
+  }
+  // An explicit empty features list means "none": drop the stale line
+  // rather than keeping the previous workspace's features around.
+  if (values[FEATURES_ENV] === '') {
+    delete merged[FEATURES_ENV];
   }
   return merged;
 }
@@ -582,6 +656,9 @@ export function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig {
     baseUrl,
     timeout: options?.timeout ?? DEFAULT_TIMEOUT,
     maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
+    // Pass through untouched: the transport owns case-insensitive merging so
+    // there is exactly one place that decides which header wins.
+    ...(options?.headers ? { headers: { ...options.headers } } : {}),
   };
 }
 

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

@@ -104,6 +104,31 @@ function normalizeRequestAbortError(
   return normalized;
 }
 
+/**
+ * Merge caller-supplied headers over everything the transport already derived
+ * from the environment, so an explicitly passed header always wins.
+ *
+ * HTTP header names are case-insensitive, so an existing header is removed by
+ * case-insensitive match before the normalized lowercase name is set. Without
+ * that, `Authorization` and `authorization` would both survive into the record
+ * and `new Headers(record)` would concatenate the two values.
+ */
+function applyExplicitHeaders(
+  headers: Record<string, string>,
+  explicit: Record<string, string> | undefined,
+): Record<string, string> {
+  if (!explicit) return headers;
+  for (const [rawName, value] of Object.entries(explicit)) {
+    const name = rawName.trim().toLowerCase();
+    if (!name) continue;
+    for (const existing of Object.keys(headers)) {
+      if (existing.toLowerCase() === name) delete headers[existing];
+    }
+    headers[name] = value;
+  }
+  return headers;
+}
+
 function isAbortLikeError(error: Error): boolean {
   const name = error.name.toLowerCase();
   const message = error.message.toLowerCase();
@@ -114,6 +139,17 @@ function isAbortLikeError(error: Error): boolean {
   );
 }
 
+function withErrorCause<T extends Error>(error: T, cause: unknown): T {
+  if (cause !== null && cause !== undefined) {
+    Object.defineProperty(error, 'cause', {
+      value: cause,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return error;
+}
+
 function mapNetworkError(
   baseUrl: string,
   error: Error | null,
@@ -312,7 +348,11 @@ export class HttpClient {
       headers[COORDINATOR_INTERNAL_TOKEN_HEADER] =
         coordinatorInternalToken.trim();
     }
-    return headers;
+    // Explicit client-option headers (e.g. `deepline plays run --header`) are
+    // applied last so an operator can override an env-derived header without
+    // rewriting the environment. Authorization of these headers stays
+    // server-side.
+    return applyExplicitHeaders(headers, this.config.headers);
   }
 
   /**
@@ -540,37 +580,43 @@ export class HttpClient {
     );
     if (options?.toolId) {
       const code = mappedNetworkError.code;
-      throw new ToolExecutionError(
-        withCoworkNetworkHint(mappedNetworkError.message),
-        {
-          toolId: options.toolId,
-          provider: providerLabelFromToolId(options.toolId),
-          operation: options.toolId,
-          code,
-          origin: 'deepline',
-          category: 'network',
-          // A direct client timeout has ambiguous delivery. Fail closed unless
-          // the server returns the authoritative action delivery contract.
-          retryable: false,
-          statusCode: null,
-          requestId: null,
-          retryAfterMs: null,
-          networkKind:
-            code === 'NETWORK_TIMEOUT'
-              ? 'timeout'
-              : code === 'NETWORK_ABORTED'
-                ? 'unknown'
-                : 'unavailable',
-          networkScope: 'client_to_deepline',
-          details: mappedNetworkError.details,
-        },
+      throw withErrorCause(
+        new ToolExecutionError(
+          withCoworkNetworkHint(mappedNetworkError.message),
+          {
+            toolId: options.toolId,
+            provider: providerLabelFromToolId(options.toolId),
+            operation: options.toolId,
+            code,
+            origin: 'deepline',
+            category: 'network',
+            // A direct client timeout has ambiguous delivery. Fail closed unless
+            // the server returns the authoritative action delivery contract.
+            retryable: false,
+            statusCode: null,
+            requestId: null,
+            retryAfterMs: null,
+            networkKind:
+              code === 'NETWORK_TIMEOUT'
+                ? 'timeout'
+                : code === 'NETWORK_ABORTED'
+                  ? 'unknown'
+                  : 'unavailable',
+            networkScope: 'client_to_deepline',
+            details: mappedNetworkError.details,
+          },
+        ),
+        lastError,
       );
     }
-    throw new DeeplineError(
-      withCoworkNetworkHint(mappedNetworkError.message),
-      undefined,
-      mappedNetworkError.code,
-      mappedNetworkError.details,
+    throw withErrorCause(
+      new DeeplineError(
+        withCoworkNetworkHint(mappedNetworkError.message),
+        undefined,
+        mappedNetworkError.code,
+        mappedNetworkError.details,
+      ),
+      lastError,
     );
   }
 

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

@@ -94,6 +94,8 @@ export type {
   MonitorFleetWaitOptions,
   MonitorFleetResult,
   MonitorFleetsNamespace,
+  CreateNotificationGroupInput,
+  CreateNotificationGroupResult,
   IngestionStorageRepairResult,
   PlayStatus,
   PlaySheetRow,
@@ -270,6 +272,10 @@ export type {
   PlayDatasetInput,
   PlayCallExecution,
   PlayCallOptions,
+  PlayAsyncCallOptions,
+  AsyncPlayRunRef,
+  PlayRunId,
+  PlayReferenceLike,
   PlayFetchResponse,
   RuntimeStepOptions,
   FetchOptions,

package/dist/bundling-sources/sdk/src/monitor-fleet-contract.ts

@@ -1,7 +1,7 @@
 /**
  * The fleet member ceiling, mirrored — deliberately a literal.
  *
- * The canonical declaration is shared_libs/monitors/monitor-fleet-limits.ts,
+ * The canonical declaration is packages/monitors/monitor-fleet-limits.ts,
  * which the Convex commit mutation reads to size its transaction. This package
  * cannot import it: the workspace-architecture ratchet forbids NEW shared_libs
  * imports from packages absolutely (only relocations of pre-existing edges

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

@@ -113,6 +113,9 @@ import type { ToolExecution } from './client.js';
 import type {
   DurableCallStaleAfterSeconds,
   PlayAuthoringBindings,
+  AsyncPlayRunRef as PlayAuthoringAsyncPlayRunRef,
+  PlayAuthoringAsyncCallOptions,
+  PlayRunId as PlayAuthoringRunId,
   PlayAuthoringCallExecution,
   PlayAuthoringCallOptions,
   PlayAuthoringColumnResolver,
@@ -676,7 +679,18 @@ export type PrebuiltPlayRef = {
   readonly name: string;
 };
 
-export type PlayReferenceLike = PlayAuthoringReferenceLike;
+export type PlayReferenceLike<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+> = PlayAuthoringReferenceLike<TInput>;
+
+/** Branded durable identity returned by ctx.runPlayAsync. */
+export type PlayRunId = PlayAuthoringRunId;
+
+/** Serializable reference to an independently scheduled Play Run. */
+export type AsyncPlayRunRef = PlayAuthoringAsyncPlayRunRef;
+
+/** Author intent for an independently scheduled child Run. */
+export type PlayAsyncCallOptions = PlayAuthoringAsyncCallOptions;
 
 export type {
   PlayDataset,

package/dist/bundling-sources/sdk/src/plays/bundle-play-file.ts

@@ -40,7 +40,7 @@ export type {
 
 export { extractDefinedPlayName } from '../../../shared_libs/plays/bundling/index.js';
 
-const PLAY_BUNDLE_CACHE_VERSION = 35;
+const PLAY_BUNDLE_CACHE_VERSION = 37;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const SDK_PACKAGE_ROOT = resolve(MODULE_DIR, '..', '..');
 const SOURCE_REPO_ROOT = resolve(SDK_PACKAGE_ROOT, '..', '..');
@@ -84,7 +84,7 @@ let hasWarnedAboutNonDevelopmentBundling = false;
  * The SDK's job is to turn a local play file into a portable artifact using
  * only SDK/runtime sources. It must work for installed packages, source
  * checkouts, CI smoke jobs, and clean worktrees without app-generated files
- * such as `src/lib/generated/tool-typecheck-catalog.jsonl`.
+ * such as `packages/integrations/generated/tool-typecheck-catalog.jsonl`.
  *
  * Tool-aware validation belongs to the Deepline API after upload:
  * `compilePlayManifest` / server preflight runs the cloud typechecker inside

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.88',
+  version: '0.3.89',
   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

@@ -19,6 +19,19 @@ import type {
   PlayBootstrapStageKind,
   PlayBootstrapTemplate,
 } from '../../shared_libs/plays/bootstrap-routes';
+import type {
+  EffectiveProductNotificationConfiguration,
+  ProductNotificationConfigurationChange,
+  ProductNotificationDefaultPolicy,
+} from '../../shared_libs/product-notifications/configuration';
+import type { ProductNotificationTypeCatalogItem } from '../../shared_libs/product-notifications/catalog';
+
+export type {
+  EffectiveProductNotificationConfiguration,
+  ProductNotificationConfigurationChange,
+  ProductNotificationDefaultPolicy,
+  ProductNotificationTypeCatalogItem,
+};
 
 // ——————————————————————————————————————————————————————————
 // Config
@@ -56,6 +69,17 @@ export interface DeeplineClientOptions {
   timeout?: number;
   /** Maximum retry attempts for transient failures (network errors, 429s). Default: `3`. */
   maxRetries?: number;
+  /**
+   * Extra request headers attached to every request this client sends.
+   *
+   * They are merged *after* the headers the transport derives from the
+   * environment, so an explicit header replaces the env-derived one. Header
+   * names match case-insensitively and are normalized to lowercase.
+   *
+   * This is transport plumbing only: the server still authorizes every
+   * internal header it honors.
+   */
+  headers?: Record<string, string>;
 }
 
 /**
@@ -72,6 +96,12 @@ export interface ResolvedConfig {
   timeout: number;
   /** Max retry count for transient failures. */
   maxRetries: number;
+  /**
+   * Caller-supplied headers merged over the env-derived headers on every
+   * request. Absent unless the caller passed
+   * {@link DeeplineClientOptions.headers}.
+   */
+  headers?: Record<string, string>;
 }
 
 /** Column metadata returned by a customer data query. */
@@ -795,8 +825,9 @@ export interface PlayStatus {
   /**
    * Projected settled-charge billing for the run. Returned by `runs.get`.
    * `totalCredits`/`providerEvents` describe THIS run only; `rollup` (present
-   * with `--full`) carries the true subtree cost including ctx.runPlay children.
-   * Deepline credits only — provider spend is never exposed.
+   * with `--full`) carries the true subtree cost including independently
+   * executing ctx.runPlayAsync descendants. Deepline credits only — provider
+   * spend is never exposed.
    */
   billing?: RunBillingSummary;
   /**
@@ -808,14 +839,26 @@ export interface PlayStatus {
   billingChildCredits?: number;
   /** True when the child-run billing rollup could not be fully resolved. */
   billingRollupIncomplete?: boolean;
-  /** Durable summaries of ctx.runPlay children, returned by `runs.get --full`. */
+  /** Durable summaries of ctx.runPlayAsync children, returned by `runs.get --full`. */
   childRuns?: ChildRunSummary[];
+  /**
+   * Child Runs grouped by the authored ctx.runPlayAsync launch key. `complete`
+   * is false when the bounded response is a lower bound rather than the full
+   * direct-child set; use each opaque `runId` to retrieve a child Run.
+   */
+  childRunProjection?: AsyncChildRunProjection;
 }
 
-/** One ctx.runPlay child run exposed on the parent's `--full` payload. */
+/** One ctx.runPlayAsync child Run exposed on the parent's `--full` payload. */
 export interface ChildRunSummary {
   runId: string;
   playName?: string | null;
+  /** Authored ctx.runPlayAsync key; stable across row fanout. */
+  launchKey?: string | null;
+  /** Opaque durable identity for one authored invocation. */
+  invocationKey?: string | null;
+  /** Whether this child uses root-owned Deepline billing attribution. */
+  rootBillingOwned?: boolean;
   status: string;
   parentRunId?: string | null;
   rootRunId?: string | null;
@@ -824,6 +867,32 @@ export interface ChildRunSummary {
   finishedAt?: number | null;
 }
 
+export interface AsyncChildRunStatusCounts {
+  total: number;
+  queued: number;
+  active: number;
+  waiting: number;
+  succeeded: number;
+  failed: number;
+  cancelled: number;
+  unknown: number;
+}
+
+export interface AsyncChildRunLaunchProjection {
+  launchKey: string | null;
+  playName: string | null;
+  counts: AsyncChildRunStatusCounts;
+  children: ChildRunSummary[];
+}
+
+export interface AsyncChildRunProjection {
+  kind: 'async_child_runs';
+  returnedCount: number;
+  complete: boolean;
+  counts: AsyncChildRunStatusCounts;
+  launches: AsyncChildRunLaunchProjection[];
+}
+
 /**
  * Rolled-up billing for a run subtree, projected from settled Charge Lifecycle
  * facts. Deepline credits only — never provider spend.
@@ -1189,6 +1258,16 @@ export interface ProductNotification {
   lastErrorMessage?: string;
 }
 
+export interface ProductNotificationConfigurationResponse {
+  configuration: EffectiveProductNotificationConfiguration;
+  catalog: readonly ProductNotificationTypeCatalogItem[];
+  slackConnection: {
+    connected: boolean;
+    status: string;
+    connectionId?: string;
+  };
+}
+
 export interface PlayDescription {
   name: string;
   /** Stable registry key. Same value `plays list` reports for this play. */

package/dist/bundling-sources/shared_libs/integration-contracts/AGENTS.md

@@ -0,0 +1,9 @@
+# Integration Contracts
+
+This package is the only integration-owned boundary shared with public clients.
+
+- Put a value here only when both `packages/integrations` and a public client such as `packages/sdk` must interpret it identically.
+- Keep contracts pure and dependency-light. Do not import provider runtimes, generated catalogs, credentials, billing implementations, action schemas, or application code.
+- Provider implementations and server-only policy remain in `packages/integrations`.
+- The public SDK bundles this package; it must not acquire a runtime dependency on a private workspace package.
+- Prefer a server-driven protocol over adding provider-specific client knowledge when compatibility permits it.

package/dist/bundling-sources/shared_libs/integration-contracts/README.md

@@ -0,0 +1,3 @@
+# `@deepline/integration-contracts`
+
+Pure contracts that must be interpreted identically by integration runtimes and public clients. Server-only integration code belongs in `packages/integrations`; SDK-only behavior belongs in `packages/sdk`.

package/dist/bundling-sources/shared_libs/integration-contracts/index.ts

@@ -0,0 +1,2 @@
+export * from './bettercontact/execution-policy';
+export * from './theirstack/execution-policy';

package/dist/bundling-sources/shared_libs/monitors/analytics-install-guides.ts

@@ -0,0 +1,77 @@
+export type AnalyticsInstallGuide = {
+  id: 'html' | 'wordpress' | 'react' | 'nextjs' | 'gtm' | 'webflow' | 'shopify';
+  label: string;
+  steps: string[];
+};
+
+/** Kept as data so the UI, email preview, and regression test share one guide source. */
+export const ANALYTICS_INSTALL_GUIDES: readonly AnalyticsInstallGuide[] = [
+  {
+    id: 'html',
+    label: 'HTML',
+    steps: [
+      'Open the shared layout or template used by every page.',
+      'Paste the loader immediately before the closing </head> tag, publish, then validate below.',
+    ],
+  },
+  {
+    id: 'wordpress',
+    label: 'WordPress',
+    steps: [
+      'Install or open WPCode / Insert Headers and Footers.',
+      'Add the loader to the site-wide Header area, save it, clear any cache, then validate below.',
+    ],
+  },
+  {
+    id: 'react',
+    label: 'React',
+    steps: [
+      'Open the root HTML template (usually public/index.html).',
+      'Paste the loader in <head>, not inside a rendered component, deploy, then validate below.',
+    ],
+  },
+  {
+    id: 'nextjs',
+    label: 'Next.js',
+    steps: [
+      'Open app/layout.tsx (or pages/_document.tsx in the Pages Router).',
+      'Use the Next.js code below once in the document head, deploy, then validate below.',
+    ],
+  },
+  {
+    id: 'gtm',
+    label: 'Google Tag Manager',
+    steps: [
+      'Create a new Custom HTML tag and paste the loader.',
+      'Trigger it on All Pages, publish the container, then validate below.',
+    ],
+  },
+  {
+    id: 'webflow',
+    label: 'Webflow',
+    steps: [
+      'Open Project settings → Custom code.',
+      'Paste the loader in Head code, publish the site, then validate below.',
+    ],
+  },
+  {
+    id: 'shopify',
+    label: 'Shopify',
+    steps: [
+      'Open Online Store → Themes → Edit code → layout/theme.liquid.',
+      'Paste the loader immediately before </head>, save the theme, then validate below.',
+    ],
+  },
+];
+
+function scriptBody(loader: string) {
+  return loader.replace(/^<script>\s*/i, '').replace(/\s*<\/script>$/i, '');
+}
+
+export function analyticsGuideCode(
+  guide: AnalyticsInstallGuide,
+  loader: string,
+) {
+  if (guide.id !== 'nextjs') return loader;
+  return `import Script from 'next/script';\n\n<Script\n  id="deepline-analytics"\n  strategy="afterInteractive"\n  dangerouslySetInnerHTML={{ __html: ${JSON.stringify(scriptBody(loader))} }}\n/>`;
+}