deepline 0.3.325 → 0.3.326

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

@@ -51,6 +51,12 @@ import { playInputExampleArgs } from './plays/input-example.js';
  */
 import { resolveConfig } from './config.js';
 import { DeeplineError } from './errors.js';
+import {
+  planCustomerDbQuery,
+  queryCustomerDatabase,
+  type CustomerDbQueryOptions,
+  type CustomerDbQueryPlan,
+} from './db/query.js';
 import {
   ToolCalls,
   type ExecuteToolRawOptions,
@@ -1256,11 +1262,10 @@ export type StopAllRunsOptions = {
 
 /** Current mutable customer database namespace exposed as `client.db`. */
 export type DbNamespace = {
-  /** Run a bounded SQL query against the current customer data plane. */
-  query: (input: {
-    sql: string;
-    maxRows?: number;
-  }) => Promise<CustomerDbQueryResult>;
+  /** Run a bounded SQL query; every request is attempted once. */
+  query: (input: CustomerDbQueryOptions) => Promise<CustomerDbQueryResult>;
+  /** Describe the request, effects and recovery policy without executing SQL. */
+  planQuery: (input: CustomerDbQueryOptions) => CustomerDbQueryPlan;
 };
 
 /**
@@ -2921,6 +2926,7 @@ export class DeeplineClient {
     };
     this.db = {
       query: (input) => this.queryDb(input),
+      planQuery: (input) => planCustomerDbQuery(input),
     };
     this.billing = {
       topUp: (options) => this.topUpBillingBalance(options),
@@ -3485,21 +3491,10 @@ export class DeeplineClient {
     return this.executeTool<TData, TMeta>(toolId, input, options);
   }
 
-  private async queryDb(input: {
-    sql: string;
-    maxRows?: number;
-  }): Promise<CustomerDbQueryResult> {
-    const result = await this.http.post<CustomerDbQueryResult>(
-      '/api/v2/db/query',
-      {
-        sql: input.sql,
-        ...(input.maxRows ? { max_rows: input.maxRows } : {}),
-      },
-    );
-    return {
-      ...result,
-      scope: { kind: 'database', mutability: 'current' },
-    };
+  private async queryDb(
+    input: CustomerDbQueryOptions,
+  ): Promise<CustomerDbQueryResult> {
+    return queryCustomerDatabase(this.http, input);
   }
 
   /**
@@ -3510,10 +3505,9 @@ export class DeeplineClient {
    *
    * @deprecated Use {@link DeeplineClient.db} `.query(...)`.
    */
-  async queryCustomerDb(input: {
-    sql: string;
-    maxRows?: number;
-  }): Promise<CustomerDbQueryResult> {
+  async queryCustomerDb(
+    input: CustomerDbQueryOptions,
+  ): Promise<CustomerDbQueryResult> {
     return this.db.query(input);
   }
 
@@ -3627,6 +3621,8 @@ export class DeeplineClient {
     artifact: Record<string, unknown>;
     compilerManifest?: PlayCompilerManifest;
     publish?: boolean;
+    /** Store execution content without changing a draft or live revision. */
+    artifactOnly?: boolean;
     ownerType?: 'org' | 'deepline';
     scope?: 'org' | 'system';
     userId?: string;
@@ -3652,7 +3648,9 @@ export class DeeplineClient {
         artifact: input.artifact,
       }));
     return this.http.post(
-      '/api/v2/plays/artifacts',
+      input.artifactOnly === true
+        ? '/api/v2/plays/artifacts/immutable'
+        : '/api/v2/plays/artifacts',
       {
         ...input,
         compilerManifest,

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

@@ -338,6 +338,8 @@ export async function checkSdkCompatibility(
     skillsVersion?: string | null;
     /** Blocking budget for the live request; defaults to the full timeout. */
     timeoutMs?: number;
+    /** Disable cache writes and invalidation for commands that permit no local maintenance. */
+    persistCache?: boolean;
     /** Optional read-only catalog result carried by the same live check. */
     catalog?: {
       toolId: string;
@@ -396,12 +398,14 @@ export async function checkSdkCompatibility(
     }
     // Catalog results belong to this command only, never the policy cache.
     const { catalog_metadata: catalogMetadata, ...data } = raw;
-    writeCachedCompatibility(
-      baseUrl,
-      options.command,
-      options.skillsVersion,
-      data,
-    );
+    if (options.persistCache !== false) {
+      writeCachedCompatibility(
+        baseUrl,
+        options.command,
+        options.skillsVersion,
+        data,
+      );
+    }
     if (
       options.catalog &&
       catalogMetadata &&
@@ -423,6 +427,7 @@ export async function checkSdkCompatibility(
     );
     if (cached) {
       if (
+        options.persistCache !== false &&
         options.timeoutMs !== undefined &&
         options.timeoutMs < CHECK_TIMEOUT_MS
       ) {

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

@@ -0,0 +1,172 @@
+import {
+  CustomerDbQueryOutcomeUnknownError,
+  DeeplineError,
+} from '../errors.js';
+import type { HttpClient } from '../http.js';
+import type { CustomerDbQueryResult } from '../types.js';
+
+export type CustomerDbQueryOptions = {
+  sql: string;
+  maxRows?: number;
+  /** Reuse only to recover the original statement and options. */
+  operationKey?: string;
+};
+
+export type CustomerDbQueryPlan = {
+  request: {
+    method: 'POST';
+    path: '/api/v2/db/query';
+    body: { sql: string; max_rows?: number; operation_key?: string };
+  };
+  effects: {
+    cloudMutations: 'statement_dependent';
+    localWrites: 'none';
+    creditSpending: 'none';
+    recovery: 'original_operation_key' | 'unkeyed_unknown_outcome';
+  };
+  transport: { maxRetries: 0; urlFailover: 'disabled' };
+};
+
+/** Validate and describe SQL execution without sending it. */
+export function planCustomerDbQuery(
+  input: CustomerDbQueryOptions,
+): CustomerDbQueryPlan {
+  if (typeof input.sql !== 'string' || !input.sql.trim())
+    throw new DeeplineError('sql must not be empty.', 400, 'INVALID_SQL');
+  if (
+    input.operationKey !== undefined &&
+    typeof input.operationKey !== 'string'
+  )
+    throw new DeeplineError(
+      'operationKey must be a string containing 1–512 characters.',
+      400,
+      'INVALID_OPERATION_KEY',
+    );
+  // An operation key is an opaque identity shared with REST and tool callers.
+  // Trim only to reject blank input; changing a valid key creates new intent.
+  const operationKey = input.operationKey;
+  if (
+    operationKey !== undefined &&
+    (!operationKey.trim() || operationKey.length > 512)
+  ) {
+    throw new DeeplineError(
+      'operationKey must contain 1–512 characters.',
+      400,
+      'INVALID_OPERATION_KEY',
+    );
+  }
+  if (
+    input.maxRows !== undefined &&
+    (!Number.isSafeInteger(input.maxRows) ||
+      input.maxRows < 1 ||
+      input.maxRows > 1000)
+  ) {
+    throw new DeeplineError(
+      'maxRows must be a whole number from 1 to 1000.',
+      400,
+      'INVALID_MAX_ROWS',
+    );
+  }
+  return {
+    request: {
+      method: 'POST',
+      path: '/api/v2/db/query',
+      body: {
+        sql: input.sql,
+        ...(input.maxRows !== undefined ? { max_rows: input.maxRows } : {}),
+        ...(operationKey !== undefined ? { operation_key: operationKey } : {}),
+      },
+    },
+    effects: {
+      cloudMutations: 'statement_dependent',
+      localWrites: 'none',
+      creditSpending: 'none',
+      recovery:
+        operationKey === undefined
+          ? 'unkeyed_unknown_outcome'
+          : 'original_operation_key',
+    },
+    transport: {
+      maxRetries: 0,
+      urlFailover: 'disabled',
+    },
+  };
+}
+
+export async function queryCustomerDatabase(
+  http: HttpClient,
+  input: CustomerDbQueryOptions,
+): Promise<CustomerDbQueryResult> {
+  const plan = planCustomerDbQuery(input);
+  let result: CustomerDbQueryResult;
+  try {
+    result = await http.post<CustomerDbQueryResult>(
+      plan.request.path,
+      plan.request.body,
+      undefined,
+      {
+        maxRetries: plan.transport.maxRetries,
+        exactUrlOnly: plan.transport.urlFailover === 'disabled',
+      },
+    );
+  } catch (error) {
+    if (
+      error instanceof DeeplineError &&
+      (error.code?.startsWith('NETWORK_') ||
+        // Older API readers return PostgreSQL errors as HTTP 400, including
+        // lost connections and explicitly unknown transaction resolution.
+        /^08[A-Z0-9]{3}$/.test(error.code ?? '') ||
+        ['57P01', '57P02', '57P03'].includes(error.code ?? '') ||
+        error.statusCode === 408 ||
+        (error.statusCode ?? 0) >= 500)
+    ) {
+      throw new CustomerDbQueryOutcomeUnknownError(
+        error,
+        plan.request.body.operation_key,
+      );
+    }
+    throw error;
+  }
+  if (
+    !result ||
+    typeof result !== 'object' ||
+    Array.isArray(result) ||
+    typeof result.command !== 'string' ||
+    !Array.isArray(result.columns) ||
+    !Array.isArray(result.rows) ||
+    typeof result.truncated !== 'boolean' ||
+    (result.row_count !== null &&
+      (!Number.isSafeInteger(result.row_count) || result.row_count < 0)) ||
+    !Number.isSafeInteger(result.row_count_returned) ||
+    result.row_count_returned < 0
+  ) {
+    throw new CustomerDbQueryOutcomeUnknownError(
+      new DeeplineError(
+        'The SQL response did not contain a valid result.',
+        200,
+        'CUSTOMER_DB_QUERY_RESPONSE_INVALID',
+      ),
+      plan.request.body.operation_key,
+    );
+  }
+  const operation = result.operation;
+  if (
+    input.operationKey !== undefined &&
+    (!operation ||
+      operation.operation_key !== input.operationKey ||
+      !Number.isSafeInteger(operation.completed_at_ms) ||
+      operation.completed_at_ms < 0 ||
+      !['executed', 'operation_recovery'].includes(operation.source))
+  ) {
+    throw new CustomerDbQueryOutcomeUnknownError(
+      new DeeplineError(
+        'The server did not confirm the original atomic SQL operation.',
+        200,
+        'CUSTOMER_DB_OPERATION_ACK_INVALID',
+      ),
+      input.operationKey,
+      { recoveryAvailable: false },
+    );
+  }
+  return { ...result, scope: { kind: 'database', mutability: 'current' } };
+}

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

@@ -18,6 +18,41 @@ import {
   type ToolExecutionPublicDetails,
 } from '../../shared_libs/plays/tool-execution-error';
 
+/** SQL may have committed, but its response was not confirmed. */
+export class CustomerDbQueryOutcomeUnknownError extends DeeplineError {
+  declare readonly cause: DeeplineError;
+  readonly outcome = 'unknown' as const;
+  readonly operationKey?: string;
+  readonly retryable: boolean;
+
+  constructor(
+    cause: DeeplineError,
+    operationKey?: string,
+    options: { recoveryAvailable?: boolean } = {},
+  ) {
+    const recoveryAvailable =
+      operationKey !== undefined && options.recoveryAvailable !== false;
+    super(
+      operationKey === undefined
+        ? 'SQL outcome is unknown. The unkeyed request was attempted once; inspect the database before issuing another write. An operation key added afterwards cannot recover this request.'
+        : recoveryAvailable
+          ? 'SQL outcome is unknown. Recover by submitting the same SQL and options with the original operation key; do not use a new key.'
+          : 'SQL outcome is unknown. The server did not confirm atomic recovery support. Do not resubmit this write; inspect the database and confirm reader support before recovering with the original operation key.',
+      cause.statusCode,
+      'CUSTOMER_DB_QUERY_OUTCOME_UNKNOWN',
+      {
+        outcome: 'unknown',
+        recovery: recoveryAvailable ? 'original_operation_key' : 'unavailable',
+        causeCode: cause.code,
+      },
+    );
+    this.name = 'CustomerDbQueryOutcomeUnknownError';
+    this.operationKey = operationKey;
+    this.retryable = recoveryAvailable;
+    Object.defineProperty(this, 'cause', { value: cause, configurable: true });
+  }
+}
+
 export {
   DeeplineError,
   ProviderTransientError,

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

@@ -41,6 +41,7 @@ export type {
  * export default definePlay('my-play', async (ctx, input: { domain: string }) => {
  *   ctx.log(`Looking up ${input.domain}`);
  *   const company = await ctx.tools.execute({
+ *     staleAfterSeconds: 0,
  *     id: 'company_search',
  *     tool: 'test_company_search',
  *     input: { domain: input.domain },
@@ -76,6 +77,17 @@ export {
   MONITOR_JOB_RECONCILIATION_STATES,
   MONITOR_JOB_STATES,
 } from './client.js';
+export type {
+  CustomerDbQueryOptions,
+  CustomerDbQueryPlan,
+} from './db/query.js';
+export { planCustomerDbQuery } from './db/query.js';
+export type { DeeplineToolCallOptions } from './play.js';
+export {
+  planLocalPlayExecution,
+  pinLocalPlayImports,
+} from './plays/local-play-execution.js';
+export type { LocalPlayGraph } from './plays/local-play-execution.js';
 export { CtxFetchHttpError } from './play.js';
 export { RunObserveTransportUnavailableError } from './runs/observe-transport.js';
 export { RunEventQueryInputError } from '../../shared_libs/play-runtime/run-event-query';
@@ -258,6 +270,7 @@ export {
 // ——— Errors ———
 export {
   DeeplineError,
+  CustomerDbQueryOutcomeUnknownError,
   ProviderTransientError,
   ToolExecutionError,
   getProviderUnavailableReason,

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

@@ -29,6 +29,7 @@
  * export default definePlay('my-play', async (ctx, input: { domain: string }) => {
  *   ctx.log(`Looking up ${input.domain}`);
  *   const company = await ctx.tools.execute({
+ *     staleAfterSeconds: 0,
  *     id: 'company_search',
  *     tool: 'test_company_search',
  *     input: { domain: input.domain },
@@ -59,6 +60,7 @@
  *
  * export default definePlay('daily-sync', async (ctx) => {
  *   const data = await ctx.tools.execute({
+ *     staleAfterSeconds: 0,
  *     id: 'crm_export',
  *     tool: 'crm_export',
  *     input: {},
@@ -115,6 +117,7 @@ import type {
   ExecutionRecovery,
   ToolExecution,
 } from './client.js';
+import type { ExecuteToolRawOptions } from './tool-calls.js';
 import type {
   DurableCallStaleAfterSeconds,
   PlayAuthoringBindings,
@@ -638,6 +641,12 @@ export interface DeeplineNamedPlay<
   ): Promise<TOutput>;
 }
 
+/** Per-call HTTP deadline and recovery identity for a direct tool operation. */
+export type DeeplineToolCallOptions = Pick<
+  ExecuteToolRawOptions,
+  'timeout' | 'idempotencyKey' | 'recover' | 'onExecution' | 'recoveryTimeoutMs'
+>;
+
 /**
  * Tool/provider operations available from a connected {@link DeeplineContext}.
  *
@@ -652,6 +661,12 @@ export type DeeplineToolsNamespace = {
   list(): Promise<ToolDefinition[]>;
   /** Get detailed metadata for one provider-backed tool. */
   get(toolId: string): Promise<ToolMetadata>;
+  /** Call one tool. A key or recover enables same-execution recovery after a lost response. */
+  call(
+    toolId: string,
+    input: Record<string, unknown>,
+    options?: DeeplineToolCallOptions,
+  ): Promise<DeeplineToolExecuteResult>;
   /**
    * Execute a provider-backed tool from a regular SDK process.
    *
@@ -661,14 +676,7 @@ export type DeeplineToolsNamespace = {
   execute(
     toolId: string,
     input: Record<string, unknown>,
-    options?: {
-      idempotencyKey?: string;
-      recover?: boolean;
-      onExecution?: (execution: {
-        idempotencyKey: string;
-      }) => void | Promise<void>;
-      recoveryTimeoutMs?: number;
-    },
+    options?: DeeplineToolCallOptions,
   ): Promise<DeeplineToolExecuteResult>;
 };
 
@@ -1100,35 +1108,30 @@ export class DeeplineContext {
    * ```
    */
   get tools(): DeeplineToolsNamespace {
+    const call: DeeplineToolsNamespace['call'] = async (
+      toolId,
+      input,
+      options,
+    ) => {
+      const response = await this.client.executeTool(toolId, input, {
+        includeToolMetadata: true,
+        responseIntent: 'dataset',
+        ...options,
+      });
+      return toolExecutionEnvelopeToResult(toolId, response, {
+        client: this.client,
+        input,
+      });
+    };
     return {
       /** List all available tools. */
       list: (): Promise<ToolDefinition[]> => this.client.listTools(),
       /** Get detailed metadata for a tool. */
       get: (toolId: string): Promise<ToolMetadata> =>
         this.client.getTool(toolId),
-      /** Execute a tool and return the standard execution envelope. */
-      execute: async (
-        toolId: string,
-        input: Record<string, unknown>,
-        options?: {
-          idempotencyKey?: string;
-          recover?: boolean;
-          onExecution?: (execution: {
-            idempotencyKey: string;
-          }) => void | Promise<void>;
-          recoveryTimeoutMs?: number;
-        },
-      ): Promise<DeeplineToolExecuteResult> => {
-        const response = await this.client.executeTool(toolId, input, {
-          includeToolMetadata: true,
-          responseIntent: 'dataset',
-          ...options,
-        });
-        return toolExecutionEnvelopeToResult(toolId, response, {
-          client: this.client,
-          input,
-        });
-      },
+      call,
+      /** Compatibility spelling for the same tool operation. */
+      execute: call,
     };
   }
 

package/dist/bundling-sources/sdk/src/plays/authoring-graph-path.ts

@@ -0,0 +1,13 @@
+import { dirname, isAbsolute, join, relative } from 'node:path';
+
+/** Transport a child path in its importing artifact's source identity frame. */
+export function playAuthoringGraphPath(
+  parent: { filePath: string; artifact: { entryFile: string } },
+  filePath: string,
+): string {
+  if (isAbsolute(parent.artifact.entryFile)) return filePath;
+  return join(
+    dirname(parent.artifact.entryFile),
+    relative(dirname(parent.filePath), filePath),
+  ).replaceAll('\\', '/');
+}

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

@@ -141,7 +141,7 @@ export function createSdkPlayBundlingAdapter(): PlayBundlingAdapter {
 
 export async function bundlePlayFile(
   filePath: string,
-  options: BundlePlayFileOptions = {},
+  options: BundlePlayFileOptions & { cache?: boolean } = {},
 ): Promise<BundledPlayFileResult> {
   // The SDK sends this graph to a remote checker/runtime. Its file identities
   // therefore must describe the authoring workspace, rather than the local
@@ -159,6 +159,7 @@ export async function bundlePlayFile(
     adapter: {
       ...createSdkPlayBundlingAdapter(),
       sourceIdentityRoot,
+      ...(options.cache === false ? { cacheDir: null } : {}),
     },
   });
   if (result.success)