deepline 0.2.73 → 0.3.0

package/dist/bundling-sources/shared_libs/play-runtime/secret-capability.ts

@@ -30,8 +30,10 @@ export type SecretAuth = PlaySecretAuth &
       }
   );
 
+export type SecretAuthInput = SecretAuth | readonly SecretAuth[];
+
 export type SecretAwareRequestInit = PlaySecretAwareRequestInit & {
-  auth?: SecretAuth;
+  auth?: SecretAuthInput;
 };
 
 function isRecord(value: unknown): value is Record<string | symbol, unknown> {
@@ -46,6 +48,22 @@ export function isSecretAuth(value: unknown): value is SecretAuth {
   return isRecord(value) && value[SECRET_AUTH_BRAND] === true;
 }
 
+export function isSecretAuthInput(value: unknown): value is SecretAuthInput {
+  return (
+    isSecretAuth(value) ||
+    (Array.isArray(value) &&
+      value.length > 0 &&
+      value.every((entry) => isSecretAuth(entry)))
+  );
+}
+
+export function secretAuthEntries(
+  auth: SecretAuthInput | undefined,
+): readonly SecretAuth[] {
+  if (!auth) return [];
+  return isSecretAuth(auth) ? [auth] : auth;
+}
+
 export function valueContainsSecret(value: unknown): boolean {
   const pending: unknown[] = [value];
   const seen = new WeakSet<object>();
@@ -107,17 +125,24 @@ export function createHeaderSecretAuth(
 }
 
 export function secretAuthHeaderMarkers(
-  auth: SecretAuth | undefined,
+  auth: SecretAuthInput | undefined,
 ): Record<string, string> {
-  if (!auth) return {};
-  if (auth.kind === 'bearer') {
-    return { authorization: `[secret:${auth.secret.name}]` };
+  const markers: Record<string, string> = {};
+  for (const entry of secretAuthEntries(auth)) {
+    const header =
+      entry.kind === 'bearer' ? 'authorization' : entry.header.toLowerCase();
+    if (markers[header] !== undefined) {
+      throw new Error(
+        `ctx.fetch cannot attach more than one secret to the ${header} header.`,
+      );
+    }
+    markers[header] = `[secret:${entry.secret.name}]`;
   }
-  return { [auth.header.toLowerCase()]: `[secret:${auth.secret.name}]` };
+  return markers;
 }
 
 export function assertSecretAuthUsesTls(
-  auth: SecretAuth | undefined,
+  auth: SecretAuthInput | undefined,
   input: string | URL,
   sink: string,
 ): void {

package/dist/bundling-sources/shared_libs/play-runtime/tool-response-contract.ts

@@ -0,0 +1,89 @@
+/**
+ * Public tool-response contracts shared by the API, SDK, Play bundler, and
+ * runtime. A response contract is transport behavior, never Play authoring.
+ */
+export const V2_TOOL_RESPONSE_CONTRACT = 'v2-tool-response' as const;
+export const RAW_V2_TOOL_RESPONSE_CONTRACT = 'raw-v2' as const;
+
+export type ToolResponseContract =
+  | typeof V2_TOOL_RESPONSE_CONTRACT
+  | typeof RAW_V2_TOOL_RESPONSE_CONTRACT;
+
+export type ToolResponseView = 'data' | 'rawV2';
+
+export function isToolResponseContract(
+  value: unknown,
+): value is ToolResponseContract {
+  return (
+    value === V2_TOOL_RESPONSE_CONTRACT ||
+    value === RAW_V2_TOOL_RESPONSE_CONTRACT
+  );
+}
+
+export class UnsupportedToolResponseContractError extends Error {
+  constructor(value: unknown) {
+    super(
+      `Unsupported tool response contract ${String(value)}. Supported contracts: ${V2_TOOL_RESPONSE_CONTRACT}, ${RAW_V2_TOOL_RESPONSE_CONTRACT}.`,
+    );
+    this.name = 'UnsupportedToolResponseContractError';
+  }
+}
+
+/** Missing artifact compatibility predates canonical bodies and stays V2. */
+export function normalizeToolResponseContract(
+  value: unknown,
+): ToolResponseContract {
+  if (value == null) return V2_TOOL_RESPONSE_CONTRACT;
+  if (isToolResponseContract(value)) return value;
+  throw new UnsupportedToolResponseContractError(value);
+}
+
+export function legacyRawFromToolResponseRawV2(
+  rawV2: unknown,
+  view: ToolResponseView,
+  responseMeta?: Record<string, unknown>,
+): unknown {
+  const legacyRaw =
+    view === 'data' &&
+    rawV2 &&
+    typeof rawV2 === 'object' &&
+    !Array.isArray(rawV2)
+      ? (rawV2 as Record<string, unknown>).data
+      : rawV2;
+  // Before raw-v2, an async launch without a data envelope exposed
+  // Deepline's billing summary at `toolResponse.raw.deepline_billing`.
+  // The canonical response keeps it separate from provider data, so reattach
+  // it only to this derived legacy view.
+  const deeplineBilling = responseMeta?.deepline_billing;
+  if (
+    view === 'rawV2' &&
+    deeplineBilling !== undefined &&
+    legacyRaw &&
+    typeof legacyRaw === 'object' &&
+    !Array.isArray(legacyRaw)
+  ) {
+    return {
+      ...(legacyRaw as Record<string, unknown>),
+      deepline_billing: deeplineBilling,
+    };
+  }
+  return legacyRaw;
+}
+
+export function providerMetaFromToolResponseRawV2(
+  rawV2: unknown,
+  view: ToolResponseView,
+): Record<string, unknown> | undefined {
+  if (
+    view !== 'data' ||
+    !rawV2 ||
+    typeof rawV2 !== 'object' ||
+    Array.isArray(rawV2)
+  ) {
+    return undefined;
+  }
+  const meta = (rawV2 as Record<string, unknown>).meta;
+  return meta && typeof meta === 'object' && !Array.isArray(meta)
+    ? (meta as Record<string, unknown>)
+    : undefined;
+}

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

@@ -75,7 +75,7 @@ export type ToolResultEnvelope<
   meta?: TMeta;
 };
 
-export type SerializedToolExecuteResult = {
+export type SerializedToolExecuteResultV1 = {
   __kind: 'deepline.tool_execute_result.v1';
   status: string;
   job_id?: string;
@@ -98,11 +98,36 @@ export type SerializedToolExecuteResult = {
   execution: ToolResultExecutionMetadata;
 };
 
+/**
+ * Canonical receipt form. Provider data is stored once as `rawV2`; the legacy
+ * raw/meta view is recreated from the payload-free projection descriptor.
+ */
+export type SerializedToolExecuteResultV2 = Omit<
+  SerializedToolExecuteResultV1,
+  '__kind' | 'toolResponse'
+> & {
+  __kind: 'deepline.tool_execute_result.v2';
+  toolResponse: {
+    rawV2: unknown;
+    view: 'data' | 'rawV2';
+    /** Deepline-owned additions not already represented in `rawV2.meta`. */
+    responseMeta?: Record<string, unknown>;
+  };
+};
+
+export type SerializedToolExecuteResult =
+  | SerializedToolExecuteResultV1
+  | SerializedToolExecuteResultV2;
+
 export type ToolResponseEnvelope<
   TData = unknown,
   TMeta = Record<string, unknown>,
 > = {
   raw: TData;
+  /** Complete parsed and scrubbed provider response, materialized from raw-v2. */
+  rawV2?: unknown;
+  /** Durable descriptor for deriving the legacy raw view from `rawV2`. */
+  view?: 'data' | 'rawV2';
   meta?: TMeta;
 };
 
@@ -156,8 +181,9 @@ export type ToolExecuteResultAccessors<
  * Canonical result returned by Deepline tool execution.
  *
  * The top-level object is Deepline-owned execution metadata and semantic
- * extraction state. Raw tool/provider data lives under `toolResponse.raw`;
- * response metadata lives under `toolResponse.meta`. Semantic single-value
+ * extraction state. The canonical provider response lives under
+ * `toolResponse.rawV2`; `toolResponse.raw` remains the legacy compatibility
+ * projection. Response metadata lives under `toolResponse.meta`. Semantic single-value
  * getters live under `extractedValues.<name>.get()`, and list getters live
  * under `extractedLists.<name>.get()`.
  *

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -49,10 +49,18 @@ import {
 } from '../plays/dataset';
 import { normalizeTableNamespace, sha256Hex } from '../plays/row-identity';
 import { listNameFromDeclaredPath } from './tool-result-paths';
+import {
+  legacyRawFromToolResponseRawV2,
+  providerMetaFromToolResponseRawV2,
+  type ToolResponseView,
+} from './tool-response-contract';
 
 type PathSegment = string | number | '*';
 
-const SERIALIZED_TOOL_EXECUTE_RESULT_KIND = 'deepline.tool_execute_result.v1';
+const SERIALIZED_TOOL_EXECUTE_RESULT_V1_KIND =
+  'deepline.tool_execute_result.v1';
+const SERIALIZED_TOOL_EXECUTE_RESULT_V2_KIND =
+  'deepline.tool_execute_result.v2';
 const SERIALIZED_TOOL_RESULT_LIST_PREVIEW_LIMIT = 5;
 const LIVE_TOOL_RESULT_LIST_DATASET_REGISTRY_LIMIT = 256;
 const SERIALIZED_TOOL_LIST_ROWS = Symbol('deepline.serialized_tool_list_rows');
@@ -123,6 +131,8 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 
 type V2ToolExecuteOutput = {
   raw: unknown;
+  rawV2?: unknown;
+  view?: ToolResponseView;
   meta?: Record<string, unknown>;
 };
 
@@ -131,12 +141,35 @@ function parseV2ToolExecuteOutput(
 ): V2ToolExecuteOutput | null {
   const toolResponse = data.toolResponse;
   if (isRecord(toolResponse)) {
-    const meta = isRecord(toolResponse.meta) ? toolResponse.meta : undefined;
+    const rawV2 = Object.prototype.hasOwnProperty.call(toolResponse, 'rawV2')
+      ? toolResponse.rawV2
+      : undefined;
+    const view =
+      toolResponse.view === 'data' || toolResponse.view === 'rawV2'
+        ? toolResponse.view
+        : undefined;
+    const providerMeta = providerMetaFromToolResponseRawV2(
+      rawV2,
+      view ?? 'rawV2',
+    );
+    const responseMeta = isRecord(toolResponse.responseMeta)
+      ? toolResponse.responseMeta
+      : undefined;
+    const meta = {
+      ...(isRecord(toolResponse.meta) ? toolResponse.meta : {}),
+      ...(providerMeta ?? {}),
+      ...(responseMeta ?? {}),
+    };
+    const raw = Object.prototype.hasOwnProperty.call(toolResponse, 'raw')
+      ? toolResponse.raw
+      : rawV2 === undefined
+        ? null
+        : legacyRawFromToolResponseRawV2(rawV2, view ?? 'rawV2', responseMeta);
     return {
-      raw: Object.prototype.hasOwnProperty.call(toolResponse, 'raw')
-        ? toolResponse.raw
-        : null,
-      ...(meta ? { meta } : {}),
+      raw,
+      ...(rawV2 !== undefined ? { rawV2 } : {}),
+      ...(view ? { view } : {}),
+      ...(Object.keys(meta).length > 0 ? { meta } : {}),
     };
   }
   return null;
@@ -181,7 +214,10 @@ export type ParsedToolExecuteResponse = {
   meta?: Record<string, unknown>;
   toolResponse?: {
     raw?: unknown;
+    rawV2?: unknown;
+    view?: 'data' | 'rawV2';
     meta?: Record<string, unknown>;
+    responseMeta?: Record<string, unknown>;
   };
   /** Legacy `{ data, meta }` envelope consumed by createToolExecuteResult. */
   result: unknown;
@@ -204,9 +240,17 @@ export function parseToolExecuteResponse(
     status,
     jobId: typeof body.job_id === 'string' ? body.job_id : undefined,
     meta: isRecord(body.meta) ? body.meta : undefined,
-    toolResponse: isRecord(body.toolResponse)
-      ? (body.toolResponse as ParsedToolExecuteResponse['toolResponse'])
-      : undefined,
+    toolResponse: (() => {
+      const output = parseV2ToolExecuteOutput(body);
+      return output
+        ? {
+            raw: output.raw,
+            ...(output.rawV2 !== undefined ? { rawV2: output.rawV2 } : {}),
+            ...(output.view ? { view: output.view } : {}),
+            ...(output.meta ? { meta: output.meta } : {}),
+          }
+        : undefined;
+    })(),
     result,
     metadata: parseExecuteToolMetadata(toolId, body),
   };
@@ -1135,11 +1179,20 @@ export function createToolExecuteResult<TResult = unknown>(input: {
   metadata: ToolResultMetadataInput;
   execution: ToolResultExecutionMetadata;
   meta?: Record<string, unknown>;
+  response?: {
+    rawV2?: unknown;
+    view?: 'data' | 'rawV2';
+    meta?: Record<string, unknown>;
+  };
 }): ToolExecuteResult<TResult> {
   const result = toResultEnvelope(input.result);
   const resultRoot = {
     toolResponse: {
       raw: result.data,
+      ...(input.response && 'rawV2' in input.response
+        ? { rawV2: input.response.rawV2 }
+        : {}),
+      ...(input.response?.view ? { view: input.response.view } : {}),
       ...(result.meta ? { meta: result.meta } : {}),
     },
   };
@@ -1165,6 +1218,10 @@ export function createToolExecuteResult<TResult = unknown>(input: {
   };
   const toolResponse = {
     raw: result.data,
+    ...(input.response && 'rawV2' in input.response
+      ? { rawV2: input.response.rawV2 }
+      : {}),
+    ...(input.response?.view ? { view: input.response.view } : {}),
     ...(result.meta ? { meta: result.meta } : {}),
   };
   const extractedValues = buildExtractedAccessors(targets);
@@ -1634,6 +1691,17 @@ function applySerializedListDatasets(
       listDatasets,
       listRows,
     });
+    if (Object.prototype.hasOwnProperty.call(result.toolResponse, 'rawV2')) {
+      const view = result.toolResponse.view ?? 'rawV2';
+      if (view === 'data' && isRecord(result.toolResponse.rawV2)) {
+        result.toolResponse.rawV2 = {
+          ...result.toolResponse.rawV2,
+          data: result.toolResponse.raw,
+        };
+      } else {
+        result.toolResponse.rawV2 = result.toolResponse.raw;
+      }
+    }
     Object.defineProperty(result, SERIALIZED_TOOL_LIST_ROWS, {
       value: listRows,
       enumerable: false,
@@ -1695,6 +1763,47 @@ function metadataInputFromToolExecuteResult(
   };
 }
 
+function sameJsonValue(left: unknown, right: unknown): boolean {
+  if (left === right) return true;
+  try {
+    return JSON.stringify(left) === JSON.stringify(right);
+  } catch {
+    return false;
+  }
+}
+
+function responseMetaOutsideRawV2(input: {
+  rawV2: unknown;
+  view: 'data' | 'rawV2';
+  meta: Record<string, unknown> | undefined;
+}): Record<string, unknown> | undefined {
+  if (!input.meta) return undefined;
+  const providerMeta =
+    input.view === 'data' && isRecord(input.rawV2) && isRecord(input.rawV2.meta)
+      ? input.rawV2.meta
+      : undefined;
+  if (!providerMeta) return input.meta;
+  const responseMeta = Object.fromEntries(
+    Object.entries(input.meta).filter(
+      ([key, value]) =>
+        !Object.prototype.hasOwnProperty.call(providerMeta, key) ||
+        !sameJsonValue(providerMeta[key], value),
+    ),
+  );
+  return Object.keys(responseMeta).length > 0 ? responseMeta : undefined;
+}
+
+function rawV2WithSerializedRawPreview(input: {
+  rawV2: unknown;
+  view: 'data' | 'rawV2';
+  raw: unknown;
+}): unknown {
+  if (input.view === 'data' && isRecord(input.rawV2)) {
+    return { ...input.rawV2, data: input.raw };
+  }
+  return input.raw;
+}
+
 export function serializeToolExecuteResult(
   value: ToolExecuteResult,
 ): SerializedToolExecuteResult {
@@ -1706,17 +1815,54 @@ export function serializeToolExecuteResult(
     metadata,
   });
   const targetValues = serializedTargetValuesFromResult(value);
+  const serializedRaw = serializedRawWithListPreviews({
+    raw: value.toolResponse.raw,
+    metadata,
+    listDatasets,
+  });
+  if (Object.prototype.hasOwnProperty.call(value.toolResponse, 'rawV2')) {
+    const view = value.toolResponse.view ?? 'rawV2';
+    const rawV2 = rawV2WithSerializedRawPreview({
+      rawV2: value.toolResponse.rawV2,
+      view,
+      raw:
+        view === 'data'
+          ? serializedRaw
+          : serializedRawWithListPreviews({
+              raw: value.toolResponse.rawV2,
+              metadata,
+              listDatasets,
+            }),
+    });
+    const responseMeta = responseMetaOutsideRawV2({
+      rawV2: value.toolResponse.rawV2,
+      view,
+      meta: value.toolResponse.meta,
+    });
+    return {
+      __kind: SERIALIZED_TOOL_EXECUTE_RESULT_V2_KIND,
+      status: value.status,
+      ...(typeof value.job_id === 'string' ? { job_id: value.job_id } : {}),
+      ...(isRecord(value.meta) ? { meta: value.meta } : {}),
+      toolResponse: {
+        rawV2,
+        view,
+        ...(responseMeta ? { responseMeta } : {}),
+      },
+      ...(listDatasets ? { listDatasets } : {}),
+      ...(listRows ? { listRows } : {}),
+      ...(targetValues ? { targetValues } : {}),
+      metadata,
+      execution: value._metadata.execution,
+    };
+  }
   return {
-    __kind: SERIALIZED_TOOL_EXECUTE_RESULT_KIND,
+    __kind: SERIALIZED_TOOL_EXECUTE_RESULT_V1_KIND,
     status: value.status,
     ...(typeof value.job_id === 'string' ? { job_id: value.job_id } : {}),
     ...(isRecord(value.meta) ? { meta: value.meta } : {}),
     toolResponse: {
-      raw: serializedRawWithListPreviews({
-        raw: value.toolResponse.raw,
-        metadata,
-        listDatasets,
-      }),
+      raw: serializedRaw,
       ...(value.toolResponse.meta ? { meta: value.toolResponse.meta } : {}),
     },
     ...(listDatasets ? { listDatasets } : {}),
@@ -1732,7 +1878,8 @@ export function isSerializedToolExecuteResult(
 ): value is SerializedToolExecuteResult {
   return (
     isRecord(value) &&
-    value.__kind === SERIALIZED_TOOL_EXECUTE_RESULT_KIND &&
+    (value.__kind === SERIALIZED_TOOL_EXECUTE_RESULT_V1_KIND ||
+      value.__kind === SERIALIZED_TOOL_EXECUTE_RESULT_V2_KIND) &&
     typeof value.status === 'string' &&
     isRecord(value.toolResponse) &&
     isRecord(value.metadata) &&
@@ -1743,6 +1890,46 @@ export function isSerializedToolExecuteResult(
 export function deserializeToolExecuteResult(
   value: SerializedToolExecuteResult,
 ): ToolExecuteResult {
+  if (value.__kind === SERIALIZED_TOOL_EXECUTE_RESULT_V2_KIND) {
+    const view = value.toolResponse.view;
+    const rawV2 = value.toolResponse.rawV2;
+    const providerMeta =
+      view === 'data' && isRecord(rawV2) && isRecord(rawV2.meta)
+        ? rawV2.meta
+        : undefined;
+    const meta = {
+      ...(providerMeta ?? {}),
+      ...(value.toolResponse.responseMeta ?? {}),
+    };
+    const raw = legacyRawFromToolResponseRawV2(
+      rawV2,
+      view,
+      value.toolResponse.responseMeta,
+    );
+    return applySerializedListDatasets(
+      applySerializedTargetValues(
+        createToolExecuteResult({
+          status: value.status,
+          jobId: value.job_id,
+          result: {
+            data: raw,
+            ...(Object.keys(meta).length > 0 ? { meta } : {}),
+          },
+          response: {
+            rawV2,
+            view,
+            ...(Object.keys(meta).length > 0 ? { meta } : {}),
+          },
+          metadata: value.metadata,
+          execution: value.execution,
+          meta: value.meta,
+        }),
+        value.targetValues,
+      ),
+      value.listDatasets,
+      value.listRows,
+    );
+  }
   return applySerializedListDatasets(
     applySerializedTargetValues(
       createToolExecuteResult({

package/dist/bundling-sources/shared_libs/plays/artifact-types.ts

@@ -1,4 +1,5 @@
 import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
+import type { ToolResponseContract } from '../play-runtime/tool-response-contract';
 import type { PlayAuthoringContractEdition } from './authoring-contract';
 
 export type PlayPackageImport = {
@@ -28,6 +29,8 @@ export type PlayArtifactCompatibility = {
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
   /** Missing preserves edition 1 for artifacts created before authoring contracts were pinned. */
   authoringContractEdition?: PlayAuthoringContractEdition;
+  /** Missing preserves the raw-only V2 execute response contract. */
+  toolResponseContract?: ToolResponseContract;
 };
 
 /** The only executable Play artifact contract. */

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -410,6 +410,8 @@ export type PlaySecretAuth = {
   /** Header name, set only when `kind` is `header`. */
   readonly header?: string;
 };
+/** One or more resolved authentication schemes for an outbound request. */
+export type PlaySecretAuthInput = PlaySecretAuth | readonly PlaySecretAuth[];
 /**
  * The `init` accepted by `ctx.fetch`. Same shape as `RequestInit` plus `auth`.
  *
@@ -419,9 +421,9 @@ export type PlaySecretAwareRequestInit = Omit<RequestInit, 'headers'> & {
   /** Ordinary request headers, recorded in the durable receipt. Never interpolate a secret value here — use `auth`. */
   headers?: HeadersInit;
   /**
-   * The single authenticated header for this request. One value, not a list: exactly one `ctx.secrets` auth attaches per `ctx.fetch`. An API wanting two credentialed headers at once — Supabase with both `apikey` and `Authorization` — cannot express both. Put the must-stay-secret credential in `auth`; pass a genuinely non-secret second value in `headers`. If both are secret, the request needs a server-side proxy holding one of them.
+   * One or more secret-backed authentication headers for this request. Pass a single `ctx.secrets` auth for the common case, or an array when an API requires multiple credentialed headers — for example, Supabase with both `apikey` and `Authorization`. Every secret is resolved only while the request is attached, never stored in the durable receipt. Each auth entry must target a distinct header.
    */
-  auth?: PlaySecretAuth;
+  auth?: PlaySecretAuthInput;
 };
 export type PlayLooseObject = { [key: string]: PlayLooseObject };
 
@@ -2464,6 +2466,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   'declare const SECRET_HANDLE_BRAND: unique symbol;',
   'export type SecretHandle = { readonly [SECRET_HANDLE_BRAND]: never; readonly name: string; toString(): string; toJSON(): never };',
   "export type SecretAuth = { readonly kind: 'bearer' | 'header'; readonly secret: SecretHandle; readonly header?: string };",
+  'export type SecretAuthInput = SecretAuth | readonly SecretAuth[];',
   'export type PlayInputContract<TInput> = { readonly schema: Record<string, unknown>; readonly __inputType?: TInput };',
   'export type PlayReturnObject = Record<string, unknown> & { readonly _metadata?: never };',
   'export type CsvRenameMap = Record<string, string | readonly string[]>;',
@@ -2512,7 +2515,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   `  customerDb: { query<TRow extends Record<string, unknown> = Record<string, unknown>>(statement: SqlQuery, options?: { maxRows?: ${cloudReferenceType('ctx.customerDb.query.options.maxRows')}; timeoutMs?: ${cloudReferenceType('ctx.customerDb.query.options.timeoutMs')} }): Promise<TRow[]> };`,
   `  tool<K extends string>(key: ${cloudReferenceType('ctx.tool.key')}, toolId: K, input: ${cloudReferenceType('ctx.tool.input')}, options?: { description?: ${cloudReferenceType('ctx.tool.options.description')} }): Promise<ToolExecutionOutput<K>>;`,
   '  step<T>(id: string, run: () => T | Promise<T>, options?: RuntimeStepOptions): Promise<T>;',
-  "  fetch(key: string, url: string | URL, init?: RequestInit & { headers?: HeadersInit & { 'Idempotency-Key'?: string; 'X-Idempotency-Key'?: string }; auth?: SecretAuth }, options?: FetchOptions): Promise<PlayFetchResponse>;",
+  "  fetch(key: string, url: string | URL, init?: RequestInit & { headers?: HeadersInit & { 'Idempotency-Key'?: string; 'X-Idempotency-Key'?: string }; auth?: SecretAuthInput }, options?: FetchOptions): Promise<PlayFetchResponse>;",
   '  secrets: { get(name: string): SecretHandle; bearer(secret: SecretHandle): SecretAuth; header(header: string, secret: SecretHandle): SecretAuth };',
   `  runPlay<TOutput = unknown>(key: string, playRef: ${cloudReferenceType('ctx.runPlay.playRef')}, input: ${cloudReferenceType('ctx.runPlay.input')}, options: PlayCallOptions): Promise<TOutput>;`,
   '  log(message: string): void;',

package/dist/bundling-sources/shared_libs/plays/contracts.ts

@@ -10,6 +10,11 @@ import {
   type PlayAuthoringContractEdition,
   type AdmittedPlayAuthoringContract,
 } from './authoring-contract';
+import {
+  normalizeToolResponseContract,
+  RAW_V2_TOOL_RESPONSE_CONTRACT,
+  type ToolResponseContract,
+} from '../play-runtime/tool-response-contract';
 
 export type PlayContractSource = 'ad_hoc' | 'draft' | 'published';
 
@@ -39,12 +44,15 @@ export type PlayContractCompatibilitySnapshot = {
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
   /** Missing preserves edition 1 for artifacts stored before authoring contracts were pinned. */
   authoringContractEdition?: PlayAuthoringContractEdition;
+  /** Immutable execute-result transport selected when the artifact is built. */
+  toolResponseContract?: ToolResponseContract;
 };
 
 export type NormalizedPlayContractCompatibilitySnapshot =
   PlayContractCompatibilitySnapshot & {
     toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
     authoringContractEdition: PlayAuthoringContractEdition;
+    toolResponseContract: ToolResponseContract;
   };
 
 export class UnsupportedPlayToolErrorSchemaVersionError extends Error {
@@ -94,6 +102,9 @@ export function normalizePlayContractCompatibility(
   return {
     ...compatibility,
     toolErrorSchemaVersion: TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+    toolResponseContract: normalizeToolResponseContract(
+      compatibility.toolResponseContract,
+    ),
     authoringContractEdition: normalizePlayAuthoringContractEdition(
       compatibility.authoringContractEdition,
     ),
@@ -104,6 +115,7 @@ export function buildPlayContractCompatibility(input?: {
   runtimeBackend?: string | null;
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
   authoringContractEdition?: PlayAuthoringContractEdition;
+  toolResponseContract?: ToolResponseContract;
 }): PlayContractCompatibilitySnapshot {
   return {
     apiVersion: PLAY_PUBLIC_API_VERSION,
@@ -115,6 +127,8 @@ export function buildPlayContractCompatibility(input?: {
       input?.toolErrorSchemaVersion ?? TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
     authoringContractEdition:
       input?.authoringContractEdition ?? PLAY_AUTHORING_CONTRACT_EDITION,
+    toolResponseContract:
+      input?.toolResponseContract ?? RAW_V2_TOOL_RESPONSE_CONTRACT,
   };
 }