deepline 0.3.409 → 0.3.411

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

@@ -76,6 +76,7 @@ export type SdkCompatibilitySkillsUpdate = {
 };
 
 const CHECK_TIMEOUT_MS = 2_000;
+const SDK_CLI_AUTO_UPDATE_CAPABILITY = 'safe-continuation-v1';
 /**
  * A cached clean policy younger than this is trusted outright: the command
  * runs without a live request. Policy floors move on a release cadence; the
@@ -132,12 +133,14 @@ function shouldSkipCompatibilityCheck(): boolean {
 
 export function sdkCompatibilityCachePath(
   baseUrl: string,
-  homeDir = homedir(),
+  homeDir = process.env.HOME?.trim() || homedir(),
 ): string {
   return join(sdkCliStateDirPath(baseUrl, homeDir), 'compat-cache.json');
 }
 
-function legacySdkCompatibilityCachePath(homeDir = homedir()): string {
+function legacySdkCompatibilityCachePath(
+  homeDir = process.env.HOME?.trim() || homedir(),
+): string {
   return join(homeDir, '.cache', 'deepline', 'sdk-compat-cache.json');
 }
 
@@ -229,6 +232,36 @@ function isSavedWithin(savedAt: unknown, windowMs: number, now: number) {
   return Number.isFinite(age) && age >= 0 && age <= windowMs;
 }
 
+const UPDATE_ADVISORY_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * True when the optional "update available" / "deprecated" notice is due for
+ * this host: at most once a day, so a loop of commands prints it once rather
+ * than once per iteration. A state directory that cannot be written repeats
+ * the notice instead of hiding it.
+ */
+export function claimUpdateAdvisory(
+  baseUrl: string,
+  now = Date.now(),
+): boolean {
+  const path = join(sdkCliStateDirPath(baseUrl), 'update-advisory.json');
+  try {
+    const { shownAt } = JSON.parse(readFileSync(path, 'utf8')) as {
+      shownAt?: unknown;
+    };
+    if (isSavedWithin(shownAt, UPDATE_ADVISORY_INTERVAL_MS, now)) return false;
+  } catch {
+    // No marker yet, or an unreadable one: the notice is due.
+  }
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ shownAt: now })}\n`);
+  } catch {
+    // Read-only state directory.
+  }
+  return true;
+}
+
 function readCachedCompatibility(
   baseUrl: string,
   command: string | null | undefined,
@@ -348,6 +381,8 @@ export async function checkSdkCompatibility(
     /** Optional read-only catalog result carried by the same live check. */
     catalog?: {
       toolId: string;
+      cliInvocationId?: string;
+      purpose?: 'execution_warnings';
       acceptMetadata: (metadata: unknown) => void;
     };
   } = {},
@@ -378,6 +413,9 @@ export async function checkSdkCompatibility(
     }
     if (options.catalog) {
       url.searchParams.set('catalog_tool_id', options.catalog.toolId);
+      if (options.catalog.purpose) {
+        url.searchParams.set('catalog_purpose', options.catalog.purpose);
+      }
     }
     const response = await fetch(url, {
       method: 'GET',
@@ -388,9 +426,13 @@ export async function checkSdkCompatibility(
         'X-Deepline-API-Major': String(SDK_API_MAJOR),
         'X-Deepline-API-Contract': SDK_API_CONTRACT,
         'X-Deepline-CLI-Update-Preferences': '1',
+        'X-Deepline-CLI-Auto-Update-Capability': SDK_CLI_AUTO_UPDATE_CAPABILITY,
         ...(options.catalog
           ? { Authorization: `Bearer ${resolveApiKeyForBaseUrl(baseUrl)}` }
           : {}),
+        ...(options.catalog?.cliInvocationId
+          ? { 'X-Deepline-CLI-Invocation-ID': options.catalog.cliInvocationId }
+          : {}),
       },
       signal: controller.signal,
     });
@@ -416,6 +458,7 @@ export async function checkSdkCompatibility(
       );
     }
     if (
+      data.ok &&
       options.catalog &&
       catalogMetadata &&
       typeof catalogMetadata === 'object' &&

package/dist/bundling-sources/sdk/src/db/query.ts

@@ -1,9 +1,6 @@
-import {
-  CustomerDbQueryOutcomeUnknownError,
-  DeeplineError,
-} from '../errors';
-import type { HttpClient } from '../http';
-import type { CustomerDbQueryResult } from '../types';
+import { CustomerDbQueryOutcomeUnknownError, DeeplineError } from '../errors';
+import type { HttpClient } from '../http.js';
+import type { CustomerDbQueryResult } from '../types.js';
 
 export type CustomerDbQueryOptions = {
   sql: string;
@@ -24,12 +21,13 @@ export type CustomerDbQueryPlan = {
     creditSpending: 'none';
     recovery: 'original_operation_key' | 'unkeyed_unknown_outcome';
   };
-  transport: { maxRetries: 0; urlFailover: 'disabled' };
+  transport: { maxRetries: number; urlFailover: 'disabled' | 'loopback_only' };
 };
 
 /** Validate and describe SQL execution without sending it. */
 export function planCustomerDbQuery(
   input: CustomerDbQueryOptions,
+  maxRetries = 3,
 ): CustomerDbQueryPlan {
   if (typeof input.sql !== 'string' || !input.sql.trim())
     throw new DeeplineError('sql must not be empty.', 400, 'INVALID_SQL');
@@ -87,8 +85,8 @@ export function planCustomerDbQuery(
           : 'original_operation_key',
     },
     transport: {
-      maxRetries: 0,
-      urlFailover: 'disabled',
+      maxRetries: operationKey === undefined ? 0 : maxRetries,
+      urlFailover: operationKey === undefined ? 'disabled' : 'loopback_only',
     },
   };
 }
@@ -96,8 +94,9 @@ export function planCustomerDbQuery(
 export async function queryCustomerDatabase(
   http: HttpClient,
   input: CustomerDbQueryOptions,
+  maxRetries: number,
 ): Promise<CustomerDbQueryResult> {
-  const plan = planCustomerDbQuery(input);
+  const plan = planCustomerDbQuery(input, maxRetries);
   let result: CustomerDbQueryResult;
   try {
     result = await http.post<CustomerDbQueryResult>(

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

@@ -54,6 +54,10 @@ import {
   WORKER_CALLBACK_URL_OVERRIDE_HEADER,
 } from '../../shared_libs/play-runtime/coordinator-headers.js';
 import { PLAY_RUNTIME_TEST_FAULT_HEADER } from '../../shared_libs/play-runtime/test-runtime-seams.js';
+import {
+  EXECUTE_RETRY_POLICY_HEADER,
+  parseExecuteRetryPolicy,
+} from '../../shared_libs/integration-contracts/execute-retry-contract.js';
 
 const MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
 const COWORK_NETWORK_HINT =
@@ -76,6 +80,10 @@ interface RequestOptions {
    * most mutating API calls must fail loudly after the first server response.
    */
   retryApiErrors?: boolean;
+  /** Only explicit server-authorized responses may retry; transport failures never retry. */
+  retryFromExecutePolicy?: boolean;
+  /** Retry budget enabled only by an explicit safe execute-policy response. */
+  executePolicyMaxRetries?: number;
   /** Per-request retry override. Use 0 for possibly delivered mutating calls. */
   maxRetries?: number;
   /** Disable localhost/127.0.0.1 failover for non-idempotent requests. */
@@ -101,10 +109,11 @@ interface RequestOptions {
 
 interface StreamOptions {
   method?: 'GET' | 'POST';
+  /** An unkeyed mutation must not try another URL after a lost response. */
+  exactUrlOnly?: boolean;
   body?: unknown;
   headers?: Record<string, string>;
   signal?: AbortSignal;
-  exactUrlOnly?: boolean;
 }
 
 type RequestAbortTaggedError = Error & {
@@ -314,29 +323,23 @@ export class HttpClient {
     if (agentSessionId) {
       headers['X-Deepline-Agent-Session-Id'] = agentSessionId;
     }
-    const playArtifactR2Prefix =
-      env.DEEPLINE_PLAY_ARTIFACT_R2_PREFIX;
+    const playArtifactR2Prefix = env.DEEPLINE_PLAY_ARTIFACT_R2_PREFIX;
     if (playArtifactR2Prefix) {
       headers['x-deepline-play-artifact-r2-prefix'] = playArtifactR2Prefix;
     }
-    const coordinatorUrl =
-      env.DEEPLINE_COORDINATOR_URL;
-    const coordinatorInternalToken =
-      env.DEEPLINE_INTERNAL_TOKEN;
-    const absurdReleaseOverride =
-      env.DEEPLINE_ABSURD_RELEASE;
+    const coordinatorUrl = env.DEEPLINE_COORDINATOR_URL;
+    const coordinatorInternalToken = env.DEEPLINE_INTERNAL_TOKEN;
+    const absurdReleaseOverride = env.DEEPLINE_ABSURD_RELEASE;
     const preferredReceiptGatewayMachineId =
       env.DEEPLINE_PREFERRED_RECEIPT_GATEWAY_MACHINE_ID;
     if (coordinatorUrl?.trim()) {
       headers[COORDINATOR_URL_OVERRIDE_HEADER] = coordinatorUrl.trim();
     }
-    const workerCallbackUrl =
-      env.DEEPLINE_WORKER_CALLBACK_URL;
+    const workerCallbackUrl = env.DEEPLINE_WORKER_CALLBACK_URL;
     if (workerCallbackUrl?.trim()) {
       headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
     }
-    const runtimeSchedulerSchema =
-      env.DEEPLINE_RUNTIME_SCHEDULER_SCHEMA;
+    const runtimeSchedulerSchema = env.DEEPLINE_RUNTIME_SCHEDULER_SCHEMA;
     if (runtimeSchedulerSchema?.trim()) {
       headers[RUNTIME_SCHEDULER_SCHEMA_OVERRIDE_HEADER] =
         runtimeSchedulerSchema.trim();
@@ -344,15 +347,13 @@ export class HttpClient {
     // Automated test harnesses (e.g. tests/gauntlet-e2e-tests) set DEEPLINE_SYNTHETIC_RUN
     // so their intentionally failing plays do not page the SDK CLI error
     // channel. Honored server-side only in non-prod (see plays/run route).
-    const syntheticRun =
-      env.DEEPLINE_SYNTHETIC_RUN;
+    const syntheticRun = env.DEEPLINE_SYNTHETIC_RUN;
     if (syntheticRun && syntheticRun.trim() && syntheticRun.trim() !== '0') {
       headers[SYNTHETIC_RUN_HEADER] = '1';
     }
     // Test-only runtime seam. The server validates both environment and value
     // before honoring this header.
-    const runtimeTestFault =
-      env.DEEPLINE_TEST_RUNTIME_FAULT;
+    const runtimeTestFault = env.DEEPLINE_TEST_RUNTIME_FAULT;
     if (runtimeTestFault?.trim()) {
       headers[PLAY_RUNTIME_TEST_FAULT_HEADER] = runtimeTestFault.trim();
     }
@@ -441,7 +442,7 @@ export class HttpClient {
     let retryAfterDelayMs: number | null = null;
     let totalRetryWaitMs = 0;
 
-    const maxRetries = options?.maxRetries ?? this.config.maxRetries;
+    let maxRetries = options?.maxRetries ?? this.config.maxRetries;
 
     requestAttempts: for (let attempt = 0; attempt <= maxRetries; attempt++) {
       if (options?.signal?.aborted) {
@@ -529,6 +530,18 @@ export class HttpClient {
             httpStatus: response.status,
             body: parsed,
           });
+          const responseRetryAllowed =
+            options?.retryFromExecutePolicy !== true ||
+            parseExecuteRetryPolicy(
+              response.headers.get(EXECUTE_RETRY_POLICY_HEADER),
+            ) === 'transient-http-safe';
+          if (
+            options?.retryFromExecutePolicy === true &&
+            responseRetryAllowed &&
+            options.executePolicyMaxRetries !== undefined
+          ) {
+            maxRetries = options.executePolicyMaxRetries;
+          }
 
           const structuredToolError =
             options?.toolId && !response.ok
@@ -553,7 +566,7 @@ export class HttpClient {
                       retryAfterMs:
                         failure.retryAfterMs ?? Math.max(0, retryAfter),
                     });
-              if (attempt < maxRetries) {
+              if (responseRetryAllowed && attempt < maxRetries) {
                 retryAfterDelayMs = retryAfter;
                 break;
               }
@@ -576,7 +589,7 @@ export class HttpClient {
             }
             const retryAfter = parseRetryAfter(response);
             lastError = new RateLimitError(retryAfter);
-            if (attempt < maxRetries) {
+            if (responseRetryAllowed && attempt < maxRetries) {
               retryAfterDelayMs = retryAfter;
               break;
             }
@@ -592,6 +605,7 @@ export class HttpClient {
           if (!response.ok) {
             const retryableApiError =
               options?.retryApiErrors === true &&
+              responseRetryAllowed &&
               isRetryableApiErrorResponse(response.status);
             // A 5xx that escaped a Worker can return Cloudflare's default HTML
             // error page. Never surface raw HTML to CLI users: replace the
@@ -693,6 +707,7 @@ export class HttpClient {
             timeoutMs,
             timedOut: requestTimedOut,
           });
+          if (options?.retryFromExecutePolicy) break requestAttempts;
         } finally {
           clearTimeout(timeoutId);
           options?.signal?.removeEventListener('abort', abortRequest);
@@ -918,7 +933,10 @@ export class HttpClient {
     options?: Pick<
       RequestOptions,
       | 'retryApiErrors'
+      | 'retryFromExecutePolicy'
+      | 'executePolicyMaxRetries'
       | 'timeout'
+      | 'signal'
       | 'maxRetries'
       | 'exactUrlOnly'
       | 'toolId'

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

@@ -78,10 +78,7 @@ export {
   MONITOR_JOB_RECONCILIATION_STATES,
   MONITOR_JOB_STATES,
 } from './client';
-export type {
-  CustomerDbQueryOptions,
-  CustomerDbQueryPlan,
-} from './db/query';
+export type { CustomerDbQueryOptions, CustomerDbQueryPlan } from './db/query';
 export { planCustomerDbQuery } from './db/query';
 export type { DeeplineToolCallOptions } from './play';
 export {
@@ -90,7 +87,7 @@ export {
 } from './plays/local-play-execution';
 export type { LocalPlayGraph } from './plays/local-play-execution';
 export type { PlayDescriptionOptions } from './plays/play-description';
-export { CtxFetchHttpError } from './play';
+export { CtxFetchHttpError, CtxFetchAmbiguousWriteError } from './play';
 export { RunObserveTransportUnavailableError } from './runs/observe-transport';
 export { RunEventQueryInputError } from '../../shared_libs/play-runtime/run-event-query';
 export type {
@@ -316,6 +313,8 @@ export type {
   DeeplineClientOptions,
   ResolvedConfig,
   ToolDefinition,
+  ToolCategorySummary,
+  ToolCategoryListing,
   ToolMetadata,
   ToolRequestCondition,
   ToolRequestWarningRule,

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

@@ -75,6 +75,7 @@
  * @module
  */
 import { DeeplineClient } from './client';
+import { createPlayClient, type PlayClientOperations } from './plays/client';
 import { DeeplineError } from './errors';
 import {
   attachToolResultListDataset,
@@ -83,7 +84,8 @@ import {
 } from '../../shared_libs/play-runtime/tool-result.js';
 export { readValue, readList } from '../../shared_libs/play-runtime/tool-result.js';
 import { createDeferredPlayDataset } from '../../shared_libs/plays/dataset.js';
-export { CtxFetchHttpError } from '../../shared_libs/plays/authoring-contract.js';
+export { CtxFetchHttpError } from '../../shared_libs/plays/fetch-http-error.js';
+export { CtxFetchAmbiguousWriteError } from '../../shared_libs/plays/ambiguous-write-error.js';
 import {
   QUERY_RESULT_DATASET_PAGE_SIZE,
   isCustomerDbDatasetTool,
@@ -955,7 +957,7 @@ class DeeplinePlayJobImpl<TOutput = unknown> implements PlayJob<TOutput> {
   readonly id: string;
 
   constructor(
-    private readonly client: DeeplineClient,
+    private readonly client: PlayClientOperations,
     runId: string,
   ) {
     this.id = runId;
@@ -1006,10 +1008,10 @@ class DeeplinePlayJobImpl<TOutput = unknown> implements PlayJob<TOutput> {
         if (status.package) {
           return status.package as TOutput;
         }
-        const payload = status.result as { output?: unknown } | undefined;
-        return ((payload && 'output' in payload
+        const payload = status.result;
+        return ((payload && typeof payload === 'object' && 'output' in payload
           ? payload.output
-          : status.result) ?? null) as TOutput;
+          : payload) ?? null) as TOutput;
       }
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
@@ -1028,7 +1030,7 @@ function createNamedPlayHandle<
   TInput = Record<string, unknown>,
   TOutput = unknown,
 >(
-  clientFactory: () => DeeplineClient,
+  clientFactory: () => PlayClientOperations,
   name: string,
 ): DeeplineNamedPlay<TInput, TOutput> {
   return {
@@ -1062,9 +1064,7 @@ function createNamedPlayHandle<
 }
 
 /**
- * High-level SDK context with tool shortcuts and play handles.
- *
- * Created by {@link Deepline.connect}. Wraps a {@link DeeplineClient} with a friendlier API for common operations.
+ * SDK context with tool shortcuts and play handles, created by {@link Deepline.connect}. Wraps a {@link DeeplineClient} for common operations.
  *
  * @example
  * ```typescript
@@ -1872,7 +1872,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
   });
 
   const handle = createNamedPlayHandle<TInput, TOutput>(
-    () => new DeeplineClient(),
+    () => createPlayClient(),
     name,
   );
   for (const key of [

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

@@ -1,11 +1,9 @@
-import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 import { realpath } from 'node:fs/promises';
 import {
   bundlePlayFile as bundlePlayFileCore,
-  PLAY_BUNDLE_CACHE_NAMESPACE,
   type BundlePlayFileOptions,
   type BundledPlayFileSuccess,
   type BundledPlayFileResult,
@@ -126,7 +124,10 @@ export function createSdkPlayBundlingAdapter(): PlayBundlingAdapter {
     nodeModulesDir: HAS_PACKAGED_BUNDLING_SOURCES
       ? resolve(SDK_PACKAGE_ROOT, 'node_modules')
       : resolve(PROJECT_ROOT, 'node_modules'),
-    cacheDir: join(tmpdir(), PLAY_BUNDLE_CACHE_NAMESPACE),
+    // Emit the current SDK/compiler implementation on every invocation. The
+    // customer graph hash does not include SDK/compiler source bytes, so reusing an
+    // artifact can silently retain an older compiler or SDK implementation.
+    cacheDir: null,
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
     sdkEntryFile: SDK_ENTRY_FILE,
@@ -156,6 +157,7 @@ export async function bundlePlayFile(
   const result = await bundlePlayFileCore(filePath, {
     target: options.target ?? defaultPlayBundleTarget(),
     exportName: options.exportName,
+    compatibility: options.compatibility,
     adapter: {
       ...createSdkPlayBundlingAdapter(),
       sourceIdentityRoot,

package/dist/bundling-sources/sdk/src/plays/check-local-play-graph.ts

@@ -0,0 +1,114 @@
+import type { BundledPlayFileSuccess } from '../../../shared_libs/plays/bundling/index.js';
+import type { DeeplineClient } from '../client.js';
+import { playAuthoringGraphPath } from './authoring-graph-path.js';
+
+type CheckRequest = Parameters<DeeplineClient['checkPlayArtifact']>[0];
+type CheckResult = Awaited<ReturnType<DeeplineClient['checkPlayArtifact']>>;
+type LocalPlayGraph = {
+  root: BundledPlayFileSuccess;
+  nodes: ReadonlyMap<string, BundledPlayFileSuccess>;
+};
+
+/** Source validation changes no customer resources and is safe to repeat. */
+export const LOCAL_PLAY_CHECK_EFFECTS = {
+  cloudMutations: [] as readonly string[],
+  localWrites: [] as readonly string[],
+  creditSpending: 'none',
+  recovery: 'repeat_validation',
+} as const;
+
+/** Check each future-authored composition under its own artifact and source policy. */
+export async function checkLocalPlayGraph(input: {
+  client: Pick<DeeplineClient, 'checkPlayArtifact'>;
+  graph: LocalPlayGraph;
+  rootPlayName: string;
+  exportName: string;
+  integrationMode?: CheckRequest['integrationMode'];
+  prepareArtifact?: (
+    artifact: BundledPlayFileSuccess['artifact'],
+  ) => BundledPlayFileSuccess['artifact'];
+}): Promise<{ result: CheckResult; failedChild?: BundledPlayFileSuccess }> {
+  const { client, graph } = input;
+  const nodesByPath = new Map(
+    [...graph.nodes.values()].map((node) => [node.filePath, node]),
+  );
+  const importedPlaysFor = (node: BundledPlayFileSuccess) => {
+    const imported = new Set<string>();
+    const collect = (parent: BundledPlayFileSuccess) => {
+      for (const dependency of parent.importedPlayDependencies) {
+        if (imported.has(dependency.filePath)) continue;
+        const child = nodesByPath.get(dependency.filePath);
+        if (!child)
+          throw new Error(
+            `Missing bundled Play dependency ${dependency.filePath}.`,
+          );
+        imported.add(dependency.filePath);
+        collect(child);
+      }
+    };
+    collect(node);
+    return [...imported].map((filePath) => {
+      const child = nodesByPath.get(filePath)!;
+      return {
+        playName: child.playName,
+        sourceCode: child.sourceCode,
+        sourcePath: playAuthoringGraphPath(node, child.filePath),
+      };
+    });
+  };
+  const checkNode = (node: BundledPlayFileSuccess) => {
+    const name =
+      node.playName ?? (node === graph.root ? input.rootPlayName : null);
+    if (!name)
+      throw new Error(`Bundled Play ${node.filePath} has no declared name.`);
+    const importedPlays = importedPlaysFor(node);
+    const exportName =
+      node === graph.root
+        ? input.exportName
+        : (node.artifact.exportName ?? 'default');
+    return client.checkPlayArtifact({
+      name,
+      sourceCode: node.sourceCode,
+      sourceFiles: node.sourceFiles,
+      description: node.playDescription ?? undefined,
+      artifact: input.prepareArtifact?.(node.artifact) ?? node.artifact,
+      ...(exportName === 'default' ? {} : { exportName }),
+      ...(importedPlays.length ? { importedPlays } : {}),
+      ...(input.integrationMode
+        ? { integrationMode: input.integrationMode }
+        : {}),
+    });
+  };
+  if (
+    [...graph.nodes.values()].some(
+      (node) =>
+        (node.artifact.compatibility.authoringContractEdition ?? 1) >= 10,
+    )
+  ) {
+    const checked = new Set<string>();
+    const checkChildren = async (
+      node: BundledPlayFileSuccess,
+    ): Promise<{
+      result: CheckResult;
+      failedChild: BundledPlayFileSuccess;
+    } | null> => {
+      if (checked.has(node.filePath)) return null;
+      checked.add(node.filePath);
+      for (const dependency of node.importedPlayDependencies) {
+        const child = nodesByPath.get(dependency.filePath);
+        if (!child)
+          throw new Error(
+            `Missing bundled Play dependency ${dependency.filePath}.`,
+          );
+        const failure = await checkChildren(child);
+        if (failure) return failure;
+      }
+      if (node === graph.root) return null;
+      const result = await checkNode(node);
+      return result.valid ? null : { result, failedChild: node };
+    };
+    const failure = await checkChildren(graph.root);
+    if (failure) return failure;
+  }
+  return { result: await checkNode(graph.root) };
+}