deepline 0.3.58 → 0.3.60

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

@@ -2057,6 +2057,9 @@ export class DeeplineClient {
       currentPublishedVersion:
         play.currentPublishedVersion ?? play.liveRevision?.version ?? null,
       latestRunId: play.latestRunId ?? detail.latestRuns[0]?.workflowId ?? null,
+      ...(play.triggerMetadata
+        ? { triggerMetadata: play.triggerMetadata }
+        : {}),
       ...(play.runtimeLimit ? { runtimeLimit: play.runtimeLimit } : {}),
       ...(play.activeScheduledPlays
         ? { activeScheduledPlays: play.activeScheduledPlays }

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

@@ -94,6 +94,27 @@ export type ProjectPinTarget =
       candidates: string[];
     };
 
+/**
+ * Where the CLI obtained the credentials for the current invocation.
+ *
+ * This is provenance only. SDK consumers may intentionally use host-level
+ * credentials, so CLI-only safety policy must be enforced by the CLI command
+ * dispatcher rather than by {@link resolveConfig}.
+ */
+export type CliAuthProvenance = {
+  scope: 'env' | 'folder' | 'global';
+  project:
+    | {
+        state: 'project';
+        dir: string;
+        pinPath: string;
+        source: 'marker' | 'cowork' | 'folder';
+      }
+    | { state: 'not_project' }
+    | { state: 'ambiguous_cowork_project'; candidates: string[] };
+  folderAuthPath: string | null;
+};
+
 /**
  * Convert a base URL to a filesystem-safe slug for per-host config storage.
  *
@@ -676,6 +697,75 @@ export function getActiveProjectAuthSource(
   return loadProjectEnvCandidates(startDir)[0] ?? null;
 }
 
+function findNearestProjectMarkerDir(startDir: string): string | null {
+  let current = resolve(startDir);
+  while (true) {
+    if (
+      COWORK_PROJECT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * Resolve credential provenance and whether the command is being run from a
+ * 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.
+ */
+export function resolveCliAuthProvenance(
+  config: Pick<ResolvedConfig, 'baseUrl' | 'apiKey'>,
+  startDir: string = process.cwd(),
+): CliAuthProvenance {
+  const envApiKey = process.env[API_KEY_ENV]?.trim();
+  const folderAuth = getResolvedProjectAuthSource(
+    config.baseUrl,
+    config.apiKey,
+    startDir,
+  );
+  const pinTarget = resolveProjectPinTarget(startDir);
+  const markerDir = findNearestProjectMarkerDir(startDir);
+  const project = !pinTarget.ok
+    ? {
+        state: 'ambiguous_cowork_project' as const,
+        candidates: pinTarget.candidates,
+      }
+    : folderAuth
+      ? {
+          state: 'project' as const,
+          dir: dirname(folderAuth.filePath),
+          pinPath: folderAuth.filePath,
+          source: 'folder' as const,
+        }
+      : pinTarget.source === 'cowork'
+        ? {
+            state: 'project' as const,
+            dir: pinTarget.dir,
+            pinPath: join(pinTarget.dir, PROJECT_DEEPLINE_ENV_FILE),
+            source: 'cowork' as const,
+          }
+        : markerDir
+          ? {
+              state: 'project' as const,
+              dir: markerDir,
+              pinPath: join(markerDir, PROJECT_DEEPLINE_ENV_FILE),
+              source: 'marker' as const,
+            }
+          : { state: 'not_project' as const };
+  return {
+    scope: envApiKey ? 'env' : folderAuth ? 'folder' : 'global',
+    project,
+    folderAuthPath: folderAuth?.filePath ?? null,
+  };
+}
+
 export {
   baseUrlSlug,
   loadCliEnv,

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

@@ -241,7 +241,8 @@ export type PlayFetchResponse = PlayAuthoringFetchResponse;
  *
  * @sdkReference runtime 030
  */
-export type PlayBindings = PlayAuthoringBindings;
+export type PlayBindings<TInput = Record<string, unknown>> =
+  PlayAuthoringBindings<TInput>;
 export type SqlListenerOperation = PlaySqlListenerOperation;
 export type SqlListenerFilterScalar = PlaySqlListenerFilterScalar;
 export type SqlListenerFilterOperator = PlaySqlListenerFilterOperator;
@@ -873,14 +874,28 @@ export type DefinedPlay<
   DeeplineNamedPlay<TInput, TOutput>
 >;
 
-type PlayMetadata = {
+type PlayHandlerInput<THandler> = THandler extends (
+  context: DeeplinePlayRuntimeContext,
+  input: infer TInput,
+) => Promise<PlayReturnObject>
+  ? TInput
+  : never;
+
+type PlayHandlerOutput<THandler> = THandler extends (
+  context: DeeplinePlayRuntimeContext,
+  input: unknown,
+) => Promise<infer TOutput extends PlayReturnObject>
+  ? TOutput
+  : never;
+
+type PlayMetadata<TInput = Record<string, unknown>> = {
   name: string;
   description?: string;
-  bindings?: PlayBindings;
+  bindings?: PlayBindings<TInput>;
   inputSchema?: Record<string, unknown>;
-  billing?: PlayBindings['billing'];
-  runtime?: PlayBindings['runtime'];
-  compatibility?: PlayBindings['compatibility'];
+  billing?: PlayBindings<TInput>['billing'];
+  runtime?: PlayBindings<TInput>['runtime'];
+  compatibility?: PlayBindings<TInput>['compatibility'];
 };
 
 const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
@@ -1608,6 +1623,18 @@ export function defineInput<TInput>(
 export function definePlay<TInput, TOutput extends PlayReturnObject>(
   config: DefinePlayConfig<TInput, TOutput>,
 ): DefinedPlay<TInput, TOutput>;
+/** @internal Contextually type unannotated monitor-event handlers as unknown. */
+export function definePlay<TOutput extends PlayReturnObject>(
+  name: string,
+  fn: (
+    context: DeeplinePlayRuntimeContext,
+    input: unknown,
+  ) => Promise<TOutput>,
+  bindings: PlayBindings<never> & {
+    readonly sqlListeners: readonly SqlListenerDeclaration[];
+  },
+): DefinedPlay<unknown, TOutput>;
+/* eslint-disable @typescript-eslint/no-explicit-any -- This constraint must infer a concrete contravariant handler input. */
 /**
  * Define a play with a name and function.
  *
@@ -1616,11 +1643,17 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
  * @param bindings - Play configuration, including runtime limits and triggers.
  * @returns Play handle.
  */
-export function definePlay<TInput, TOutput extends PlayReturnObject>(
+export function definePlay<
+  THandler extends (
+    context: DeeplinePlayRuntimeContext,
+    input: any,
+  ) => Promise<PlayReturnObject>,
+>(
   name: string,
-  fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>,
-  bindings?: PlayBindings,
-): DefinedPlay<TInput, TOutput>;
+  fn: THandler,
+  bindings?: PlayBindings<NoInfer<PlayHandlerInput<THandler>>>,
+): DefinedPlay<PlayHandlerInput<THandler>, PlayHandlerOutput<THandler>>;
+/* eslint-enable @typescript-eslint/no-explicit-any */
 /**
  * @sdkReference runtime 010
  */
@@ -1630,7 +1663,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
     ctx: DeeplinePlayRuntimeContext,
     input: TInput,
   ) => Promise<TOutput>,
-  maybeBindings?: PlayBindings,
+  maybeBindings?: PlayBindings<TInput>,
 ): DefinedPlay<TInput, TOutput> {
   const config =
     typeof nameOrConfig === 'string'
@@ -1690,7 +1723,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
     );
   }
 
-  const metadata: PlayMetadata = {
+  const metadata: PlayMetadata<TInput> = {
     name,
     ...(description ? { description } : {}),
     ...(bindings ? { bindings } : {}),

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.58',
+  version: '0.3.60',
   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

@@ -1089,6 +1089,20 @@ export interface PlayDefinitionDetail {
   liveRevision?: PlayRevisionSummary | null;
   /** `true` if the working revision differs from the live revision. */
   isDraftDirty?: boolean;
+  /** Live trigger state. This is operational state, not a source declaration. */
+  triggerStatus?: PlayTriggerStatus;
+  /**
+   * Additive scheduler metadata for human/UI rendering. Values are absent for
+   * plays with no cron binding and must never be inferred from source alone.
+   */
+  triggerMetadata?: {
+    cronSchedule?: string | null;
+    cronTimezone?: string | null;
+    nextScheduledAt?: number | null;
+    lastScheduledAt?: number | null;
+    blockedReason?: string | null;
+    [key: string]: unknown;
+  } | null;
   /** Effective sandbox limit from the live revision, or the working draft before first publish. */
   runtimeLimit?: PlayRuntimeLimit | null;
   /** Present for a Play with a cron trigger. Advisory only; publish remains authoritative. */
@@ -1125,11 +1139,14 @@ export interface PlayListItem {
   currentRevision?: PlayRevisionSummary | null;
   liveRevision?: PlayRevisionSummary | null;
   aliases?: string[];
-  triggerStatus?: {
-    cron: string | null;
-    webhook: string | null;
-    blockedReason: string | null;
-  };
+  triggerStatus?: PlayTriggerStatus;
+}
+
+/** Additive live trigger state shared by list, get, and describe. */
+export interface PlayTriggerStatus {
+  cron: string | null;
+  webhook: string | null;
+  blockedReason: string | null;
 }
 
 export interface ProductNotificationEventDefinition {
@@ -1202,11 +1219,9 @@ export interface PlayDescription {
    */
   liveVersion?: number | null;
   /** Whether this play's cron and webhook triggers are armed. */
-  triggerStatus?: {
-    cron: string | null;
-    webhook: string | null;
-    blockedReason: string | null;
-  };
+  triggerStatus?: PlayTriggerStatus;
+  /** Additive cron timing metadata for an operational description. */
+  triggerMetadata?: PlayDefinitionDetail['triggerMetadata'];
   isDraftDirty?: boolean;
   latestRunId?: string | null;
   /** Effective sandbox limit from the revision named runs use. */
@@ -1512,7 +1527,12 @@ export interface PlayCheckSqlListenerEventSummary {
 export interface PlayCheckTriggersSummary {
   sqlListeners?: PlayCheckSqlListenerTrigger[];
   sqlListenerEvent?: PlayCheckSqlListenerEventSummary;
-  cron?: { schedule: string; timezone?: string };
+  cron?: {
+    schedule: string;
+    timezone?: string;
+    /** Static input supplied to every run started by this cron binding. */
+    input?: Record<string, unknown>;
+  };
   webhook?: true;
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -30,6 +30,7 @@ import {
   compileRequestsWithStrategy,
   executeChunkedRequests,
 } from './batch-runtime';
+import type { CompiledRequestBatch } from './batch-runtime';
 import type { AnyBatchOperationStrategy } from './batching-types';
 import {
   PLAY_RUNTIME_WORK_RECEIPT_LEASE_TTL_MS,
@@ -112,6 +113,7 @@ import {
 import {
   isProviderUnavailable,
   serializeToolExecutionFailure,
+  ToolExecutionError,
   TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
   TOOL_EXECUTION_ERROR_SCHEMA_HEADER,
   type ToolExecutionErrorSchemaVersion,
@@ -169,10 +171,10 @@ import {
 import {
   buildDurableCtxCallCacheKey,
   buildDurableRunPlayInvocationScope,
-  buildDurableToolAggregateProviderIdempotencyKey,
   buildDurableToolAggregateReceiptKey,
   buildDurableToolCallAuthScopeDigest,
   buildDurableToolCallCacheKey,
+  buildDurableToolPayloadProviderIdempotencyKey,
   buildDurableToolProviderIdempotencyKey,
   buildDurableToolReceiptPrefix,
   resolveDurableCallCachePolicy,
@@ -2035,6 +2037,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   private readonly toolDispatchQueuedAtByLane = new Map<string, number>();
   private readonly toolDispatcherWakeWaiters = new Set<() => void>();
   private toolDispatcherFailure: unknown | null = null;
+  /**
+   * Deepline's own zero-credit denial is run-fatal. Keep it independently of
+   * customer control flow so a broad `try/catch` cannot turn it into a
+   * successful Play result. Provider account capacity remains a normal typed
+   * waterfall miss.
+   */
+  private deeplineInsufficientCreditsFailure: ToolExecutionError | null = null;
   private toolCallResolvers = new Map<
     string,
     { resolve: (value: unknown) => void; reject: (reason: unknown) => void }
@@ -2217,10 +2226,30 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 : {}),
             }
           : undefined,
-      ) as Promise<TOutput>;
+      ).catch((error: unknown) => {
+        this.recordDeeplineInsufficientCreditsFailure(error);
+        throw error;
+      }) as Promise<TOutput>;
     },
   };
 
+  private recordDeeplineInsufficientCreditsFailure(error: unknown): void {
+    if (
+      error instanceof ToolExecutionError &&
+      error.origin === 'deepline' &&
+      error.code === 'INSUFFICIENT_CREDITS'
+    ) {
+      this.deeplineInsufficientCreditsFailure ??= error;
+    }
+  }
+
+  /** Called by the runner after customer code returns, before a success settles. */
+  assertNoDeeplineInsufficientCreditsFailure(): void {
+    if (this.deeplineInsufficientCreditsFailure) {
+      throw this.deeplineInsufficientCreditsFailure;
+    }
+  }
+
   async tool<TOutput = unknown>(
     key: string,
     toolId: string,
@@ -11273,6 +11302,21 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       strategy,
       getPayload: (request: ToolCallRequest) => request.input,
     });
+    const compileOwnedPhysicalBatch = (
+      owned: ToolCallRequest[],
+    ): CompiledRequestBatch<ToolCallRequest> => {
+      const compiled = compileRequestsWithStrategy({
+        requests: owned,
+        strategy,
+        getPayload: (request: ToolCallRequest) => request.input,
+      });
+      if (compiled.length !== 1) {
+        throw new Error(
+          'Native batch owned members must compile into exactly one provider request.',
+        );
+      }
+      return compiled[0]!;
+    };
     const batchParallelismCeiling =
       this.governor.policy.pacing.workerToolBatchDefaultParallelism;
     const batchSize =
@@ -11282,6 +11326,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             batchParallelismCeiling,
           )
         : batchParallelismCeiling;
+    const batchProviderActionVersion =
+      (await this.#options.getToolActionCacheVersion?.(toolId))?.trim() ??
+      'unversioned';
     const successful: ToolCallRequest[] = [];
 
     const deliver = (request: ToolCallRequest, result: ToolExecuteResult) => {
@@ -11332,6 +11379,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           string,
           {
             members: ToolCallRequest[];
+            compiled: CompiledRequestBatch<ToolCallRequest>;
             providerOperationKey: string;
             receiptLeaseExpiresAt: string | null;
             timeoutMs: number | undefined;
@@ -11380,26 +11428,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         detail.members[0]?.executionAuthScopeDigest ?? null,
                       providerIdempotencyReceiptKey:
                         detail.providerOperationKey,
-                      providerIdempotencyKey:
-                        buildDurableToolAggregateProviderIdempotencyKey({
-                          aggregateReceiptKey: detail.providerOperationKey,
-                          receiptKeys: detail.members.map(
-                            (member) =>
-                              member.providerIdempotencyKeyBase ??
-                              member.receiptKey!,
-                          ),
-                          providerIdempotencyKeys: detail.members.map(
-                            (member) =>
-                              this.providerIdempotencyKeyForToolCall({
-                                cacheKey:
-                                  member.providerIdempotencyKeyBase ??
-                                  member.receiptKey!,
-                                force: member.force === true,
-                                leaseId: member.receiptLeaseId,
-                                logicalCallId: member.logicalCallId,
-                              }),
-                          ),
-                        }),
+                      providerIdempotencyKey: detail.providerOperationKey,
                       receiptLeaseExpiresAt: detail.receiptLeaseExpiresAt,
                       timeoutMs: detail.timeoutMs,
                     },
@@ -11477,10 +11506,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               (member) => batchRequestByCallId.get(member.memberId)!,
             );
             const receiptKeys = owned.map((request) => request.receiptKey!);
-            const providerReceiptKeys = owned.map(
-              (request) =>
-                request.providerIdempotencyKeyBase ?? request.receiptKey!,
-            );
             const aggregateReceiptKey = buildDurableToolAggregateReceiptKey({
               receiptKeys,
               prefix: 'batch',
@@ -11489,16 +11514,36 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 toolId: batch.batchOperation,
               }),
             });
-            const providerOperationKey = buildDurableToolAggregateReceiptKey({
-              receiptKeys: providerReceiptKeys,
-              prefix: 'batch',
-              aggregateReceiptPrefix: buildDurableToolReceiptPrefix({
+            const compiled = compileOwnedPhysicalBatch(owned);
+            if (compiled.batchOperation !== batch.batchOperation) {
+              throw new Error(
+                'Native batch owned members changed provider operation during compilation.',
+              );
+            }
+            const providerOperationKey =
+              buildDurableToolPayloadProviderIdempotencyKey({
                 orgId: this.#options.orgId,
                 toolId: batch.batchOperation,
-              }),
-            });
+                executionAuthScopeDigest:
+                  owned[0]?.executionAuthScopeDigest ?? null,
+                providerActionVersion: batchProviderActionVersion,
+                payload: compiled.batchPayload,
+                forceRefreshIdentities: owned
+                  .filter((request) => request.force === true)
+                  .map((request) =>
+                    this.providerIdempotencyKeyForToolCall({
+                      cacheKey:
+                        request.providerIdempotencyKeyBase ??
+                        request.receiptKey!,
+                      force: true,
+                      leaseId: request.receiptLeaseId,
+                      logicalCallId: request.logicalCallId,
+                    }),
+                  ),
+              });
             dispatchDetails.set(aggregateReceiptKey, {
               members: owned,
+              compiled,
               providerOperationKey,
               receiptLeaseExpiresAt: owned.reduce<string | null>(
                 (earliest, request) => {
@@ -11523,7 +11568,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             return {
               ...members[0]!.call,
               tool: { id: batch.batchOperation, providerActionVersion: '' },
-              payload: batch.batchPayload,
+              payload: compiled.batchPayload,
               compatibility: {
                 resultReceiptKey: aggregateReceiptKey,
                 providerOperationKey,
@@ -11531,7 +11576,40 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             };
           },
           splitResult: async ({ result: aggregate, members }) => {
-            const split = batch.splitResults(
+            const receiptKeys = members.map((member) => {
+              const request = batchRequestByCallId.get(member.memberId);
+              if (!request?.receiptKey) {
+                throw new Error(
+                  `Native batch Tool Call lost receipt for ${member.memberId}.`,
+                );
+              }
+              return request.receiptKey;
+            });
+            const aggregateReceiptKey = buildDurableToolAggregateReceiptKey({
+              receiptKeys,
+              prefix: 'batch',
+              aggregateReceiptPrefix: buildDurableToolReceiptPrefix({
+                orgId: this.#options.orgId,
+                toolId: batch.batchOperation,
+              }),
+            });
+            const detail = dispatchDetails.get(aggregateReceiptKey);
+            if (!detail) {
+              throw new Error(
+                'Native batch Tool Call lost its split compilation details.',
+              );
+            }
+            if (
+              detail.members.length !== members.length ||
+              !detail.members.every(
+                (request, index) => request.callId === members[index]?.memberId,
+              )
+            ) {
+              throw new Error(
+                'Native batch Tool Call split members changed in transit.',
+              );
+            }
+            const split = detail.compiled.splitResults(
               legacyResultForBatchSplitter(aggregate),
             );
             return await Promise.all(
@@ -12573,11 +12651,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   const receiptKeys = batch.memberRequests.map(
                     (request) => request.cacheKey,
                   );
-                  const providerIdempotencyReceiptKeys =
-                    batch.memberRequests.map(
-                      (request) =>
-                        request.providerIdempotencyKeyBase ?? request.cacheKey,
-                    );
                   const aggregateReceiptKey =
                     buildDurableToolAggregateReceiptKey({
                       receiptKeys,
@@ -12588,13 +12661,31 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       }),
                     });
                   const aggregateProviderIdempotencyReceiptKey =
-                    buildDurableToolAggregateReceiptKey({
-                      receiptKeys: providerIdempotencyReceiptKeys,
-                      prefix: 'batch',
-                      aggregateReceiptPrefix: buildDurableToolReceiptPrefix({
-                        orgId: this.#options.orgId,
-                        toolId: batch.batchOperation,
-                      }),
+                    buildDurableToolPayloadProviderIdempotencyKey({
+                      orgId: this.#options.orgId,
+                      toolId: batch.batchOperation,
+                      executionAuthScopeDigest:
+                        batch.memberRequests[0]?.executionAuthScopeDigest ??
+                        null,
+                      providerActionVersion:
+                        (
+                          await this.#options.getToolActionCacheVersion?.(
+                            batch.batchOperation,
+                          )
+                        )?.trim() ?? 'unversioned',
+                      payload: batch.batchPayload,
+                      forceRefreshIdentities: batch.memberRequests
+                        .filter((request) => request.force === true)
+                        .map((request) =>
+                          this.providerIdempotencyKeyForToolCall({
+                            cacheKey:
+                              request.providerIdempotencyKeyBase ??
+                              request.cacheKey,
+                            force: true,
+                            leaseId: request.receiptLeaseId,
+                            logicalCallId: request.logicalCallId,
+                          }),
+                        ),
                     });
                   let releaseToolSlot: () => void = () => undefined;
                   try {
@@ -12621,22 +12712,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           providerIdempotencyReceiptKey:
                             aggregateProviderIdempotencyReceiptKey,
                           providerIdempotencyKey:
-                            buildDurableToolAggregateProviderIdempotencyKey({
-                              aggregateReceiptKey:
-                                aggregateProviderIdempotencyReceiptKey,
-                              receiptKeys: providerIdempotencyReceiptKeys,
-                              providerIdempotencyKeys: batch.memberRequests.map(
-                                (request) =>
-                                  this.providerIdempotencyKeyForToolCall({
-                                    cacheKey:
-                                      request.providerIdempotencyKeyBase ??
-                                      request.cacheKey,
-                                    force: request.force === true,
-                                    leaseId: request.receiptLeaseId,
-                                    logicalCallId: request.logicalCallId,
-                                  }),
-                              ),
-                            }),
+                            aggregateProviderIdempotencyReceiptKey,
                           receiptLeaseExpiresAt: batch.memberRequests.reduce<
                             string | null
                           >((earliest, request) => {

package/dist/bundling-sources/shared_libs/play-runtime/durable-call-cache.ts

@@ -241,3 +241,42 @@ export function buildDurableToolAggregateProviderIdempotencyKey(input: {
     stableStringify({ receiptKeys, providerIdempotencyKeys }),
   )}`;
 }
+
+/**
+ * Provider-native batch caching is keyed by the exact compiled provider
+ * payload. Receipt identities coordinate ownership and terminal results; they
+ * cannot stand in for request identity because cache hits and foreign leases
+ * can remove members after the original batch was planned.
+ *
+ * An explicit force refresh is deliberately a separate namespace: it asks for
+ * a fresh provider operation even when the payload itself is unchanged.
+ */
+export function buildDurableToolPayloadProviderIdempotencyKey(input: {
+  orgId?: string | null;
+  toolId: string;
+  executionAuthScopeDigest?: string | null;
+  providerActionVersion?: string | null;
+  payload: Record<string, unknown>;
+  forceRefreshIdentities?: readonly string[];
+}): string {
+  const toolId = input.toolId.trim();
+  if (!toolId) {
+    throw new Error(
+      'Provider payload idempotency key needs a non-empty toolId.',
+    );
+  }
+  const forceRefreshIdentities = input.forceRefreshIdentities
+    ?.map((identity) => identity.trim())
+    .filter(Boolean);
+  return `${buildDurableToolReceiptPrefix({
+    orgId: input.orgId,
+    toolId,
+  })}payload-v1:${sha256Hex(
+    stableStringify({
+      executionAuthScopeDigest: input.executionAuthScopeDigest?.trim() || null,
+      providerActionVersion: input.providerActionVersion?.trim() || null,
+      payload: input.payload,
+      ...(forceRefreshIdentities?.length ? { forceRefreshIdentities } : {}),
+    }),
+  )}`;
+}