deepline 0.2.73 → 0.3.0

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

@@ -99,12 +99,17 @@ import {
   TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
 } from '../../shared_libs/tool-execution-error.js';
 import { decodePlayRunPublicStatus } from '../../shared_libs/play-runtime/run-lifecycle-policy.js';
+import {
+  legacyRawFromToolResponseRawV2,
+  providerMetaFromToolResponseRawV2,
+  RAW_V2_TOOL_RESPONSE_CONTRACT,
+} from '../../shared_libs/play-runtime/tool-response-contract.js';
 
 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 V2_EXECUTE_RESPONSE_CONTRACT = 'v2-tool-response';
+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;
 const REGISTER_PLAY_ARTIFACTS_MAX_BATCH_COUNT = 3;
@@ -452,7 +457,8 @@ function resolveToolExecuteTimeoutMs(
 /**
  * Standard provider/tool execution envelope returned by low-level SDK calls.
  *
- * `toolResponse.raw` contains the provider result. `extractedValues` and
+ * `toolResponse.rawV2` contains the complete scrubbed provider response;
+ * `toolResponse.raw` is derived locally as the legacy provider-result projection. `extractedValues` and
  * `extractedLists` contain Deepline-normalized getters when the tool exposes
  * them. Billing fields are Deepline-facing and must not expose provider spend.
  */
@@ -462,7 +468,10 @@ export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
   meta?: Record<string, unknown>;
   toolResponse: {
     raw: TData;
+    rawV2?: unknown;
+    view?: 'data' | 'rawV2';
     meta?: TMeta;
+    responseMeta?: TMeta;
   };
   extractedLists?: Record<string, unknown>;
   extractedValues?: Record<string, unknown>;
@@ -1147,6 +1156,67 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
 
+/** Materialize raw-v2's rawV2-only wire response into the stable SDK result view. */
+function materializeToolExecutionResponse<
+  TData = unknown,
+  TMeta = Record<string, unknown>,
+>(response: ToolExecution<TData, TMeta>): ToolExecution<TData, TMeta> {
+  const toolResponse = response.toolResponse;
+  // An older V2 backend does not understand raw-v2 yet and therefore falls
+  // through to the historical `{ result: { data, meta? } }` response. New SDK
+  // clients must keep working during that server rollout window.
+  if (!toolResponse && isRecord(response.result)) {
+    const legacyResult = response.result;
+    if (Object.prototype.hasOwnProperty.call(legacyResult, 'data')) {
+      const legacyMeta = isRecord(legacyResult.meta)
+        ? (legacyResult.meta as TMeta)
+        : undefined;
+      return {
+        ...response,
+        toolResponse: {
+          raw: legacyResult.data as TData,
+          ...(legacyMeta ? { meta: legacyMeta } : {}),
+        },
+      };
+    }
+  }
+  if (
+    !toolResponse ||
+    Object.prototype.hasOwnProperty.call(toolResponse, 'raw')
+  ) {
+    return response;
+  }
+  const rawV2 = toolResponse.rawV2;
+  const view = toolResponse.view;
+  const providerMeta = providerMetaFromToolResponseRawV2(
+    rawV2,
+    view ?? 'rawV2',
+  ) as TMeta | undefined;
+  const responseMeta = isRecord(toolResponse.responseMeta)
+    ? (toolResponse.responseMeta as TMeta)
+    : undefined;
+  return {
+    ...response,
+    toolResponse: {
+      ...toolResponse,
+      raw: legacyRawFromToolResponseRawV2(
+        rawV2,
+        view ?? 'rawV2',
+        responseMeta as Record<string, unknown> | undefined,
+      ) as TData,
+      ...(toolResponse.meta || providerMeta || responseMeta
+        ? {
+            meta: {
+              ...(toolResponse.meta ?? {}),
+              ...(providerMeta ?? {}),
+              ...(responseMeta ?? {}),
+            } as TMeta,
+          }
+        : {}),
+    },
+  };
+}
+
 function isPrebuiltPlayDescription(
   play: Pick<PlayDescription, 'origin' | 'ownerType'>,
 ): boolean {
@@ -2019,7 +2089,7 @@ export class DeeplineClient {
     options?: ExecuteToolRawOptions,
   ): Promise<ToolExecution<TData, TMeta>> {
     const headers = {
-      [EXECUTE_RESPONSE_CONTRACT_HEADER]: V2_EXECUTE_RESPONSE_CONTRACT,
+      [EXECUTE_RESPONSE_CONTRACT_HEADER]: RAW_V2_EXECUTE_RESPONSE_CONTRACT,
       [TOOL_EXECUTION_ERROR_SCHEMA_HEADER]: String(
         TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
       ),
@@ -2028,7 +2098,7 @@ export class DeeplineClient {
         : {}),
       [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? 'raw',
     };
-    return this.http.post<ToolExecution<TData, TMeta>>(
+    const response = await this.http.post<ToolExecution<TData, TMeta>>(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       {
         payload: input,
@@ -2042,6 +2112,7 @@ export class DeeplineClient {
         toolId,
       },
     );
+    return materializeToolExecutionResponse(response);
   }
 
   /**

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

@@ -22,6 +22,10 @@ export type SdkCompatibilityResponse = {
   update_required: boolean;
   message: string;
   update_command: string;
+  update_summary?: {
+    version: string;
+    summary: string;
+  };
   command?: string | null;
   /**
    * Present only when the queried command postdates this CLI. Advisory: the

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

@@ -149,6 +149,7 @@ import type {
   PlayLooseObject,
   PlayReturnObject as PlayAuthoringReturnObject,
   PlaySecretAuth,
+  PlaySecretAuthInput,
   PlaySecretAwareRequestInit,
   PlaySecretHandle,
   PlaySqlQuery,
@@ -249,6 +250,7 @@ export type SqlListenerEvent<T extends object = Record<string, unknown>> =
 export type SqlQuery = PlaySqlQuery;
 export type SecretHandle = PlaySecretHandle;
 export type SecretAuth = PlaySecretAuth;
+export type SecretAuthInput = PlaySecretAuthInput;
 export type SecretAwareRequestInit = PlaySecretAwareRequestInit;
 export type LoosePlayObject = PlayLooseObject;
 
@@ -1469,6 +1471,8 @@ function toolExecutionEnvelopeToResult(
   },
 ): ToolExecuteResult {
   const raw = response.toolResponse?.raw ?? null;
+  const rawV2 = response.toolResponse?.rawV2;
+  const view = response.toolResponse?.view;
   const meta = response.toolResponse?.meta;
   const metadata = isRecord(response._metadata)
     ? response._metadata.tool
@@ -1485,6 +1489,11 @@ function toolExecutionEnvelopeToResult(
         data: raw,
         ...(isRecord(meta) ? { meta } : {}),
       },
+      response: {
+        ...(rawV2 !== undefined ? { rawV2 } : {}),
+        ...(view === 'data' || view === 'rawV2' ? { view } : {}),
+        ...(isRecord(meta) ? { meta } : {}),
+      },
       metadata: {
         toolId:
           typeof toolMetadata.toolId === 'string'

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

@@ -136,6 +136,12 @@ export type SdkRelease = {
    * publish time (auto-bump); edit by hand only for minor/major releases.
    */
   version: string;
+  /**
+   * One concise, agent-readable explanation shown while this release is an
+   * available update. Keep it actionable; the compatibility route includes it
+   * in its existing update message so older installed CLIs can print it too.
+   */
+  updateSummary?: string;
   /** Named compatibility policies. This is the only authored contract policy. */
   contracts: DeeplineContractPolicy;
   /** Public support policy reported by `/api/v2/sdk/compat`. */
@@ -183,7 +189,12 @@ export const SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: '0.2.73',
+  // 0.3.0 introduces raw-v2: complete scrubbed provider responses are
+  // available at toolResponse.rawV2 while toolResponse.raw and all declared
+  // getters keep their established compatibility behavior.
+  version: '0.3.0',
+  updateSummary:
+    'New raw-v2 tool responses preserve complete scrubbed provider envelopes at toolResponse.rawV2, including JSON:API included resources, links, cursors, and totals. Existing toolResponse.raw and declared getters keep working unchanged.',
   contracts: {
     api: {
       name: 'sdk-http-api',

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

@@ -212,12 +212,19 @@ export interface ToolDefinition {
         expression?: string;
         meaning?: string;
       };
+      canonicalToolResponse?: {
+        expression?: string;
+        meaning?: string;
+      };
       invalidGetterHint?: string;
     };
     toolExecutionResult?: {
       type?: 'ToolExecutionResult';
       toolResponse?: {
         raw?: string;
+        rawV2?: string;
+        view?: string;
+        responseMeta?: string;
         meta?: string;
       };
       meta?: string;

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

@@ -94,6 +94,14 @@ import {
   type RuntimeResourceGovernor,
 } from './resource-governor';
 import { CTX_FETCH_EGRESS_TOOL_ID } from './builtin-pacing';
+import {
+  legacyRawFromToolResponseRawV2,
+  normalizeToolResponseContract,
+  providerMetaFromToolResponseRawV2,
+  RAW_V2_TOOL_RESPONSE_CONTRACT,
+  type ToolResponseContract,
+  type ToolResponseView,
+} from './tool-response-contract';
 import { ProviderExhaustedError } from './run-failure';
 import {
   buildPlayContractCompatibility,
@@ -255,10 +263,12 @@ import {
   createBearerSecretAuth,
   createHeaderSecretAuth,
   createSecretHandle,
-  isSecretAuth,
+  isSecretAuthInput,
+  secretAuthEntries,
   secretAuthHeaderMarkers,
   valueContainsSecret,
   type SecretAuth,
+  type SecretAuthInput,
   type SecretAwareRequestInit,
   type SecretHandle,
 } from './secret-capability';
@@ -355,6 +365,8 @@ type InlineCompositionStore = {
   toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
   /** Immutable authoring semantics pinned by the child play artifact. */
   authoringContractEdition: PlayAuthoringContractEdition;
+  /** Immutable execute response contract pinned by the child artifact. */
+  toolResponseContract: ToolResponseContract;
 };
 const inlineCompositionContext =
   new AsyncLocalStorage<InlineCompositionStore>();
@@ -1114,6 +1126,8 @@ function isUnsafeOutboundUrlError(error: unknown): boolean {
 function publicToolResponseEnvelope(value: unknown): {
   status: string;
   raw: unknown;
+  rawV2?: unknown;
+  view?: ToolResponseView;
   meta?: Record<string, unknown>;
 } | null {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -1125,27 +1139,100 @@ function publicToolResponseEnvelope(value: unknown): {
   if (
     !toolResponse ||
     typeof toolResponse !== 'object' ||
-    Array.isArray(toolResponse) ||
-    !Object.prototype.hasOwnProperty.call(toolResponse, 'raw')
+    Array.isArray(toolResponse)
   ) {
     return null;
   }
   const response = toolResponse as Record<string, unknown>;
-  return {
-    status: record.status,
-    raw: response.raw,
-    ...(response.meta &&
+  const rawV2 = Object.prototype.hasOwnProperty.call(response, 'rawV2')
+    ? response.rawV2
+    : undefined;
+  const view =
+    response.view === 'data' || response.view === 'rawV2'
+      ? response.view
+      : undefined;
+  if (
+    !Object.prototype.hasOwnProperty.call(response, 'raw') &&
+    rawV2 === undefined
+  ) {
+    return null;
+  }
+  const providerMeta = providerMetaFromToolResponseRawV2(
+    rawV2,
+    view ?? 'rawV2',
+  );
+  const toolResponseMeta =
+    response.meta &&
     typeof response.meta === 'object' &&
     !Array.isArray(response.meta)
-      ? { meta: response.meta as Record<string, unknown> }
+      ? (response.meta as Record<string, unknown>)
+      : {};
+  const responseMeta =
+    response.responseMeta &&
+    typeof response.responseMeta === 'object' &&
+    !Array.isArray(response.responseMeta)
+      ? (response.responseMeta as Record<string, unknown>)
+      : {};
+  return {
+    status: record.status,
+    raw: Object.prototype.hasOwnProperty.call(response, 'raw')
+      ? response.raw
+      : legacyRawFromToolResponseRawV2(rawV2, view ?? 'rawV2', responseMeta),
+    ...(rawV2 !== undefined ? { rawV2 } : {}),
+    ...(view ? { view } : {}),
+    ...(Object.keys({ ...toolResponseMeta, ...providerMeta, ...responseMeta })
+      .length > 0
+      ? { meta: { ...toolResponseMeta, ...providerMeta, ...responseMeta } }
       : {}),
   };
 }
 
+/**
+ * A batched provider request returns one envelope for several logical source
+ * tool calls. Each source call persists only its own item-shaped canonical
+ * response: retaining the aggregate envelope would make its legacy `raw`
+ * projection change on receipt replay and duplicate every batch for every row.
+ */
+function publicToolResponseForBatchedItem(
+  execution: ParsedToolExecuteResponse,
+  result: unknown,
+  forceRawV2: boolean,
+): ParsedToolExecuteResponse['toolResponse'] | undefined {
+  const providerMeta = execution.toolResponse?.meta;
+  if (
+    !forceRawV2 &&
+    (!execution.toolResponse ||
+      !Object.prototype.hasOwnProperty.call(execution.toolResponse, 'rawV2'))
+  ) {
+    return undefined;
+  }
+  return {
+    rawV2: { data: result },
+    view: 'data',
+    ...(providerMeta ? { meta: providerMeta } : {}),
+  };
+}
+
+/**
+ * Batch splitters predate raw-v2 and receive the same legacy value they got
+ * from callToolAPI. Keep that input contract stable; raw-v2 is attached to the
+ * completed logical call separately by publicToolResponseForBatchedItem.
+ */
+function legacyResultForBatchSplitter(execution: ParsedToolExecuteResponse): unknown {
+  if (execution.toolResponse && 'raw' in execution.toolResponse) {
+    return execution.toolResponse.raw;
+  }
+  return execution.result != null &&
+    typeof execution.result === 'object' &&
+    !Array.isArray(execution.result) &&
+    'data' in execution.result
+    ? execution.result.data
+    : execution.result;
+}
+
 const EXECUTE_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 V2_EXECUTE_RESPONSE_CONTRACT = 'v2-tool-response';
 function recordOrNull(value: unknown): Record<string, unknown> | null {
   return value && typeof value === 'object' && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -2516,6 +2603,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     return TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
   }
 
+  private get currentToolResponseContract(): ToolResponseContract {
+    return normalizeToolResponseContract(
+      this.activeInlineComposition?.toolResponseContract ??
+        this.#options.toolResponseContract,
+    );
+  }
+
   private get currentAuthoringContractEdition(): PlayAuthoringContractEdition {
     return (
       this.activeInlineComposition?.authoringContractEdition ??
@@ -2676,7 +2770,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     }
   }
 
-  private async resolveSecretAuth(auth: SecretAuth | undefined) {
+  private async resolveSecretAuth(auth: SecretAuthInput | undefined) {
+    const headers: Record<string, string> = {};
+    for (const entry of secretAuthEntries(auth)) {
+      Object.assign(headers, await this.resolveSingleSecretAuth(entry));
+    }
+    return headers;
+  }
+
+  private async resolveSingleSecretAuth(auth: SecretAuth) {
     if (!auth) return {};
     let value: string | null = null;
     if (this.#options.resolveSecret) {
@@ -4965,6 +5067,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     result: unknown;
     metadata?: ToolResultMetadataInput | null;
     meta?: Record<string, unknown>;
+    toolResponse?: {
+      raw?: unknown;
+      rawV2?: unknown;
+      view?: 'data' | 'rawV2';
+      meta?: Record<string, unknown>;
+    };
     execution: ToolResultExecutionMetadata;
     requestInput?: Record<string, unknown>;
   }): Promise<ToolExecuteResult> {
@@ -4988,6 +5096,18 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ...(publicToolResult.meta ? { meta: publicToolResult.meta } : {}),
             }
           : input.result,
+        response: publicToolResult
+          ? {
+              ...(Object.prototype.hasOwnProperty.call(
+                publicToolResult,
+                'rawV2',
+              )
+                ? { rawV2: publicToolResult.rawV2 }
+                : {}),
+              ...(publicToolResult.view ? { view: publicToolResult.view } : {}),
+              ...(publicToolResult.meta ? { meta: publicToolResult.meta } : {}),
+            }
+          : input.toolResponse,
         metadata:
           input.metadata ??
           (await this.resolveToolResultMetadata(input.toolId)),
@@ -5126,6 +5246,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     metadata?: ToolResultMetadataInput | null,
     jobId?: string,
     meta?: Record<string, unknown>,
+    toolResponse?: ParsedToolExecuteResponse['toolResponse'],
   ): Promise<unknown> {
     const cacheKey = request.cacheKey;
     const receiptKey = request.receiptKey?.trim() || null;
@@ -5136,6 +5257,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       result,
       metadata,
       meta,
+      toolResponse,
       execution: toolExecutionMetadataForOutcome({
         kind: 'live',
         cacheKey,
@@ -5186,6 +5308,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       metadata?: ToolResultMetadataInput | null;
       jobId?: string;
       meta?: Record<string, unknown>;
+      toolResponse?: ParsedToolExecuteResponse['toolResponse'];
     }>,
   ): Promise<unknown[]> {
     const wrappedEntries = await Promise.all(
@@ -5198,6 +5321,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           result: entry.result,
           metadata: entry.metadata,
           meta: entry.meta,
+          toolResponse: entry.toolResponse,
           execution: toolExecutionMetadataForOutcome({
             kind: 'live',
             cacheKey: entry.request.cacheKey,
@@ -8931,6 +9055,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             status: execution.status,
             jobId: execution.jobId,
             result: execution.result,
+            toolResponse: execution.toolResponse,
             metadata: execution.metadata,
             meta: execution.meta,
             requestInput: input,
@@ -9328,6 +9453,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     );
     const childToolErrorSchemaVersion =
       childCompatibility.toolErrorSchemaVersion;
+    const childToolResponseContract = childCompatibility.toolResponseContract;
     const childExecutionDecision = resolveChildExecutionStrategy({
       pipeline: resolvedPlay.staticPipeline,
       timeoutMs: options?.timeoutMs,
@@ -9400,6 +9526,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             playName: resolvedName,
             staticPipeline: resolvedPlay.staticPipeline ?? null,
             toolErrorSchemaVersion: childToolErrorSchemaVersion,
+            toolResponseContract: childToolResponseContract,
             authoringContractEdition:
               childCompatibility.authoringContractEdition,
           },
@@ -9648,7 +9775,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         'ctx.fetch does not allow raw secret headers. Use ctx.secrets.bearer(...) or ctx.secrets.header(...).',
       );
     }
-    if (init.auth !== undefined && !isSecretAuth(init.auth)) {
+    if (init.auth !== undefined && !isSecretAuthInput(init.auth)) {
       throw new Error('ctx.fetch auth must come from ctx.secrets.');
     }
     // Secret handles are deliberately resolved at the last possible moment, so
@@ -10648,6 +10775,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     execution?.metadata ?? null,
                     execution?.jobId,
                     execution?.meta,
+                    execution?.toolResponse,
                   );
                   if (result != null) {
                     successfulLiveStepCallIds.add(owner.callId);
@@ -10974,7 +11102,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     });
                   let releaseToolSlot: () => void = () => undefined;
                   try {
-                    const value = await this.callToolAPI(
+                    const execution = await this.callToolExecutionAPI(
                       batch.batchOperation,
                       batch.batchPayload,
                       {
@@ -11033,7 +11161,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         },
                       },
                     );
-                    return { value, releaseToolSlot };
+                    return { execution, releaseToolSlot };
                   } catch (error) {
                     releaseToolSlot();
                     throw error;
@@ -11050,7 +11178,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     try {
                       const splitResults =
                         entry.result != null
-                          ? entry.request.splitResults(entry.result.value)
+                          ? entry.request.splitResults(
+                              legacyResultForBatchSplitter(
+                                entry.result.execution,
+                              ),
+                            )
                           : entry.request.memberRequests.map(() => null);
                       const resolvedResults =
                         await this.resolveToolCallBatchResults(
@@ -11059,6 +11191,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                             (request, index) => ({
                               request,
                               result: splitResults[index] ?? null,
+                              toolResponse:
+                                entry.result == null
+                                  ? undefined
+                                  : publicToolResponseForBatchedItem(
+                                      entry.result.execution,
+                                      splitResults[index] ?? null,
+                                      this.currentToolResponseContract ===
+                                        RAW_V2_TOOL_RESPONSE_CONTRACT,
+                                    ),
                             }),
                           ),
                         );
@@ -11095,6 +11236,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 metadata?: ToolResultMetadataInput | null;
                 jobId?: string;
                 meta?: Record<string, unknown>;
+                toolResponse?: ParsedToolExecuteResponse['toolResponse'];
                 resolve: (value: unknown) => void;
                 reject: (error: unknown) => void;
               }> = [];
@@ -11113,6 +11255,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         metadata: entry.metadata,
                         jobId: entry.jobId,
                         meta: entry.meta,
+                        toolResponse: entry.toolResponse,
                       })),
                     );
                   for (let index = 0; index < entries.length; index += 1) {
@@ -11145,6 +11288,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     metadata: execution.metadata ?? null,
                     jobId: execution.jobId,
                     meta: execution.meta,
+                    toolResponse: execution.toolResponse,
                     resolve,
                     reject,
                   });
@@ -11359,23 +11503,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     )(ctx, input);
   }
 
-  private async callToolAPI(
-    toolId: string,
-    input: Record<string, unknown>,
-    options?: ToolExecutionApiOptions,
-  ): Promise<unknown> {
-    const execution = await this.callToolExecutionAPI(toolId, input, options);
-    if (execution.toolResponse && 'raw' in execution.toolResponse) {
-      return execution.toolResponse.raw;
-    }
-    return execution.result != null &&
-      typeof execution.result === 'object' &&
-      !Array.isArray(execution.result) &&
-      'data' in execution.result
-      ? execution.result.data
-      : execution.result;
-  }
-
   private providerIdempotencyKeyForToolCall(input: {
     cacheKey: string;
     force?: boolean;
@@ -11863,7 +11990,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         'Content-Type': 'application/json',
                         Authorization: `Bearer ${this.#options.executorToken}`,
                         [EXECUTE_RESPONSE_CONTRACT_HEADER]:
-                          V2_EXECUTE_RESPONSE_CONTRACT,
+                          this.currentToolResponseContract,
                         [EXECUTE_RESPONSE_INTENT_HEADER]: 'dataset',
                         [EXECUTE_TOOL_METADATA_HEADER]: 'true',
                         [TOOL_EXECUTION_ERROR_SCHEMA_HEADER]: String(

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -51,6 +51,7 @@ import type {
   ToolExecutionFailureV1,
 } from '../tool-execution-error';
 import type { FixtureBehavior } from './fixture-behavior';
+import type { ToolResponseContract } from './tool-response-contract';
 
 export interface RowState {
   results: Map<string, unknown>;
@@ -572,6 +573,8 @@ export interface ContextOptions {
   authoringContractEdition?: PlayAuthoringContractEdition;
   /** Error shape pinned by the immutable play artifact; missing preserves legacy schema 0. */
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
+  /** Execute-result contract pinned by the immutable Play artifact. */
+  toolResponseContract?: ToolResponseContract;
   /** Short-lived HMAC-signed internal token for tool callbacks. Required for cloud execution. */
   executorToken?: string;
   baseUrl?: string;

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

@@ -15,6 +15,7 @@ import type { PlaySandboxRuntimeLimits } from './sandbox-runtime-limits';
 import type { PlayRunInputPayload } from './play-input';
 import type { PlayRunFailureDetails } from './run-failure';
 import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
+import type { ToolResponseContract } from './tool-response-contract';
 import type { FixtureBehavior } from './fixture-behavior';
 
 export type PlayRunnerRateStateBackendConfig =
@@ -138,6 +139,8 @@ export interface PlayRunnerContextConfig {
   maxConcurrentRows?: number | null;
   /** Immutable tool-error payload schema copied from the run contract. */
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
+  /** Immutable execute response contract copied from the Play artifact. */
+  toolResponseContract?: ToolResponseContract;
   orgId?: string;
   workflowId?: string;
   playId?: string;