deepline 0.3.290 → 0.3.291

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

@@ -879,7 +879,7 @@ export type RunsEventSearchOptions = {
   playName?: string;
   /** Exact dotted event kind, such as `step.failed`. The catalog is discoverable with `runs logs --help`; future stored kinds are accepted too. */
   kind?: string;
-  /** JSONPath equality joined with `&&`, at most eight predicates and 512 bytes. See `runs logs --help` for fields and examples. Missing fields do not match; status is not inferred from kind. HTTP `jsonpath`, CLI `--where`. */
+  /** JSONPath equality joined with `&&`, at most eight predicates and 512 bytes. `eventId` selects an exact returned event; add `payloads` to retrieve its saved details. See `runs logs --help` for fields and examples. Missing fields do not match; status is not inferred from kind. HTTP `jsonpath`, CLI `--where`. */
   jsonpath?: string;
   /** Include available `eventPayload` details and receipt `payload` results; maximum ten events and 16 MiB. HTTP `payloads=true`, CLI `--payloads`. */
   includePayloads?: boolean;
@@ -905,7 +905,7 @@ export type RunsEventSearchEntry = {
   playName: string;
   /** Exact dotted event kind, such as `step.failed`. */
   kind: string;
-  /** Recorded log severity, or null; not a JSONPath filter field. */
+  /** Recorded log severity, or null on older events. Filter with `$.level == "error"`. */
   level: string | null;
   /** Log message preview of at most 2,048 characters, or null. Use text logs/export for the full retained line. */
   message: string | null;
@@ -933,7 +933,7 @@ export type RunsEventSearchResult = {
 export type RunsEventPayload = {
   /** Recorded terminal work outcome. */
   status: 'completed' | 'failed' | 'skipped';
-  /** Stored result data, or null when no output was retained. */
+  /** Saved result, including available sanitized call input/output details; failed-call records use kind: tool_call_evidence. Null when no output was retained. */
   output: unknown | null;
   /** Stored failure message, or null when absent. */
   error: string | null;
@@ -3320,8 +3320,10 @@ export class DeeplineClient {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `toolResponse.rawV2` field contains the complete parsed and scrubbed tool response.
-   * `toolResponse.meta` contains tool/provider metadata.
+   * The `toolResponse.rawV2` field contains the complete tool response,
+   * preserving its original nesting. Inspect `getTool().examples` for a full
+   * Deepline response example. Optional `toolResponse.responseMeta` contains
+   * response metadata.
    * Top-level fields such as `status`, `job_id`, and `billing` describe the
    * Deepline execution envelope.
    */
@@ -4346,7 +4348,7 @@ export class DeeplineClient {
       });
     } catch (error) {
       failedLogsLoaded = false;
-      const retryCommand = `deepline runs get ${runId} --log-failed --json`;
+      const retryCommand = `deepline runs logs ${runId} --failed --json`;
       const reason =
         error instanceof Error && error.message.trim()
           ? ` (${error.message.trim().slice(0, 500)})`

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

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.290',
+  version: '0.3.291',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/sdk/src/runs/overview.ts

@@ -35,7 +35,7 @@ function lifecycleActions(status: PlayStatus, id: string, state?: string) {
       : {}),
     ...(state === 'failed'
       ? {
-          getFailedLogsCmd: `deepline runs get ${id} --log-failed --json`,
+          getFailedLogsCmd: `deepline runs logs ${id} --failed --json`,
           ...(status.rerunCommand ? { rerunCmd: status.rerunCommand } : {}),
         }
       : {}),
@@ -149,7 +149,10 @@ function datasetSummary(value: unknown, conflictingPopulation: boolean) {
 }
 
 /** Action descriptions are affordances, never evidence that an action ran. */
-function actions(value: unknown, names: Record<string, string>) {
+function actions<const Names extends Record<string, string>>(
+  value: unknown,
+  names: Names,
+): Partial<Record<Names[keyof Names], string>> {
   return Object.fromEntries(
     Object.entries(record(value) ?? {}).flatMap(([name, value]) => {
       const action = record(value);
@@ -167,7 +170,7 @@ function actions(value: unknown, names: Record<string, string>) {
         ],
       ];
     }),
-  );
+  ) as Partial<Record<Names[keyof Names], string>>;
 }
 
 /**
@@ -175,7 +178,10 @@ function actions(value: unknown, names: Record<string, string>) {
  * from a server that predates it, the same derivation over the step's
  * reported status and map progress.
  */
-function stepExecution(step: RecordValue, runStatus: string): NodeExecutionState {
+function stepExecution(
+  step: RecordValue,
+  runStatus: string,
+): NodeExecutionState {
   const decoded = decodeNodeExecutionState(step.execution);
   if (decoded) return decoded;
   const progress = record(step.progress);
@@ -323,7 +329,11 @@ export function buildRunOverview(status: PlayStatus, fullStatus?: PlayStatus) {
       );
     return {
       datasetId: dataset.datasetId,
-      name: dataset.tableNamespace,
+      name:
+        dataset.tableNamespace ??
+        (typeof stepOutput?.tableNamespace === 'string'
+          ? stepOutput.tableNamespace
+          : dataset.path),
       stepId: step?.id ?? named[0]?.[1].stepId,
       rowCount: dataset.rowCount ?? null,
       ...(dataset.lifecycle ? { lifecycle: dataset.lifecycle } : {}),
@@ -456,7 +466,7 @@ export function buildRunOverview(status: PlayStatus, fullStatus?: PlayStatus) {
 function receiptAction(id: string) {
   const quotedId = `'${id.replace(/'/g, "'\\''")}'`;
   return {
-    getReceiptCmd: `deepline runs receipt ${quotedId} --key '<receipt-key>' --json`,
+    getReceiptCmd: `deepline runs logs ${quotedId} --kind receipt.completed --payloads --json`,
   };
 }
 

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

@@ -226,6 +226,24 @@ export interface ToolDefinition extends ToolExecutionMetadataFields {
   inputSchema?: Record<string, unknown>;
   /** JSON Schema describing the tool's output shape. */
   outputSchema?: Record<string, unknown>;
+  /** JSON Schema for the Deepline API execution response, including toolResponse.rawV2. */
+  responseSchema?: Record<string, unknown>;
+  /** Illustrative input and full API response examples, separate from schemas. */
+  examples?: Array<{
+    input: Record<string, unknown>;
+    inputSource: 'sample' | 'schema';
+    responseSource: 'sample' | 'schema' | 'no_result';
+    description: string;
+    response: {
+      job_id: string;
+      status: string;
+      toolResponse: {
+        rawV2: unknown;
+        view: 'data' | 'rawV2';
+        responseMeta?: Record<string, unknown>;
+      };
+    };
+  }>;
   /** User-facing pricing summary. Internal provider/settlement costs are intentionally omitted. */
   pricing?: ToolPricingSummary | null;
   /** How to use the tool well: the provider's summary and the tool's own notes. */
@@ -600,7 +618,8 @@ export interface ToolSearchResult {
  * const meta = await client.getTool('dropleads_search_people');
  * console.log(meta.displayName);              // "DropLeads People Search"
  * console.log(meta.estimatedCreditsRange);     // "1-5"
- * console.log(meta.samples);                   // { input: {...}, output: {...} }
+ * console.log(meta.examples?.[0].input);       // example input payload
+ * console.log(meta.examples?.[0].response);    // full Deepline execution response
  * ```
  */
 export interface ToolMetadata extends ToolDefinition {
@@ -632,7 +651,7 @@ export interface ToolMetadata extends ToolDefinition {
   estimateBasedOnTools?: string[];
   /** Individual step cost contributions (for composite tools). */
   stepContributions?: unknown[];
-  /** Example input/output pairs for documentation and testing. */
+  /** Tool body samples. Full execution response examples are available in examples. */
   samples?: Record<string, unknown>;
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -13,7 +13,10 @@ import type { AsyncPlayRunRef } from '../plays/authoring-contract';
 import type { PlayRowUpdate } from './/ctx-types';
 import type { PlayRunTimelineEntry } from './/live-events';
 import type { PlayDatasetBornFrom } from './/cell-provenance';
-import type { PlayLogContext } from './/log-context';
+import type {
+  PlayLogContext,
+  PlayLogMetadata,
+} from './/log-context';
 import {
   routePlayActivityObservation,
   type PlayActivityObservation,
@@ -111,6 +114,7 @@ export type RuntimeStatusUpdate = {
   liveLogs?: string[];
   /** Search-only context aligned to `liveLogs`; stripped before Convex. */
   liveLogContexts?: Array<PlayLogContext | null>;
+  liveLogMetadata?: Array<PlayLogMetadata | null>;
   liveLogIds?: Array<string | null>;
   /**
    * Monotonic count of log lines the producer ever emitted on this run's
@@ -160,6 +164,7 @@ export type RuntimeStatusUpdate = {
   terminalLogReplay?: {
     lines: string[];
     lineContexts?: Array<PlayLogContext | null>;
+    lineMetadata?: Array<PlayLogMetadata | null>;
     lineIds?: Array<string | null>;
     totalCount?: number;
     dedupeMode?: 'semantic' | 'exact';
@@ -2219,6 +2224,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
     ? slicePositionalLogLines({
         bufferLines: update.liveLogs,
         bufferContexts: update.liveLogContexts,
+        bufferMetadata: update.liveLogMetadata,
         bufferIds: update.liveLogIds,
         bufferTotalCount: update.liveLogTotalCount ?? update.liveLogs.length,
         sentCount,
@@ -2231,6 +2237,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
         ? {
             lines: update.liveLogs,
             lineContexts: update.liveLogContexts,
+            lineMetadata: update.liveLogMetadata,
             lineIds: update.liveLogIds,
             totalCount: update.liveLogTotalCount,
             producerAttempt: update.liveLogProducerAttempt,
@@ -2256,6 +2263,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
         ...logSlice,
         lines: prefix,
         lineContexts: logSlice.lineContexts?.slice(0, prefix.length),
+        lineMetadata: logSlice.lineMetadata?.slice(0, prefix.length),
         lineIds: logSlice.lineIds?.slice(0, prefix.length),
       };
   }
@@ -2268,6 +2276,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
       lastCheckpointAt: update.lastCheckpointAt ?? null,
       liveLogs: statusPatchLogSlice?.lines ?? null,
       liveLogContexts: statusPatchLogSlice?.lineContexts ?? null,
+      liveLogMetadata: statusPatchLogSlice?.lineMetadata ?? null,
       liveLogIds: statusPatchLogSlice?.lineIds ?? null,
       liveLogsChannelOffset: statusPatchLogSlice?.channelOffset ?? null,
       liveLogsProducerAttempt: update.liveLogProducerAttempt ?? null,
@@ -2354,6 +2363,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
           occurredAt: update.lastCheckpointAt ?? Date.now(),
           lines: terminalLogReplay.lines,
           lineContexts: terminalLogReplay.lineContexts,
+          lineMetadata: terminalLogReplay.lineMetadata,
           lineIds: terminalLogReplay.lineIds,
           liveLogTotalCount: terminalLogReplay.totalCount,
           dedupeMode: terminalLogReplay.dedupeMode,

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

@@ -216,7 +216,11 @@ import {
   ToolExecuteAuthScopeChangedError,
   type ToolExecuteHttpFailureOutcome,
 } from './tool-execute-retry-policy';
-import { createToolHttpError } from './tool-http-errors';
+import {
+  createToolHttpError,
+  attachToolCallFailureEvidenceFromResponse,
+  readToolCallFailureEvidence,
+} from './tool-http-errors';
 import {
   describeTransportError,
   transportGatewayOriginForDiagnostic,
@@ -255,6 +259,7 @@ import {
 } from './play-artifact-runtime-contract';
 import {
   LOG_LEVELS,
+  classifyLogLine,
   formatCtxFetchHttpFailureDiagnostic,
   tagLogEntry,
   tagLogLevel,
@@ -446,7 +451,11 @@ import {
   RunLogBuffer,
   RUNNER_LOG_CONTEXT_MAX_BYTES,
 } from './run-log-buffer';
-import { normalizePlayLogContext, type PlayLogContext } from './log-context';
+import {
+  normalizePlayLogContext,
+  type PlayLogContext,
+  type PlayLogMetadata,
+} from './log-context';
 import type { AsyncPlayRunRef } from '../plays/authoring-contract';
 import { admitAsyncPlayLineage } from './async-play-invocation';
 import {
@@ -536,6 +545,11 @@ type InlineCompositionStore = {
 };
 const inlineCompositionContext =
   new AsyncLocalStorage<InlineCompositionStore>();
+// Authored scope is async-local: concurrent steps and rows cannot steal attribution.
+const authoredStepContext = new AsyncLocalStorage<{
+  context: PlayContextImpl;
+  stepId: string;
+}>();
 const toolExecutionOverrides = new AsyncLocalStorage<{ force: boolean }>();
 const PROGRESS_HEARTBEAT_INTERVAL_MS = 1_000;
 const PURE_JS_HEARTBEAT_ROW_INTERVAL = 250;
@@ -6387,11 +6401,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ? {
                   relayReceiptOutput: {
                     receiptKey: input.resultReceiptKey,
-                    execution: toolExecutionMetadataForOutcome({
-                      kind: 'live',
-                      cacheKey: input.request.cacheKey,
-                      receiptKey: input.request.receiptKey,
-                    }),
+                    execution: {
+                      ...toolExecutionMetadataForOutcome({
+                        kind: 'live',
+                        cacheKey: input.request.cacheKey,
+                        receiptKey: input.request.receiptKey,
+                      }),
+                      resultReceiptKey: input.resultReceiptKey,
+                    },
                     metadata: await this.resolveToolResultMetadata(
                       input.dispatchToolId,
                     ),
@@ -6431,11 +6448,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           meta: execution.meta,
           billing: execution.billing,
           requestInput: input.dispatchPayload,
-          execution: toolExecutionMetadataForOutcome({
-            kind: 'live',
-            cacheKey: input.request.cacheKey,
-            receiptKey: input.request.receiptKey,
-          }),
+          execution: {
+            ...toolExecutionMetadataForOutcome({
+              kind: 'live',
+              cacheKey: input.request.cacheKey,
+              receiptKey: input.request.receiptKey,
+            }),
+            ...(!alwaysFresh && input.resultReceiptKey
+              ? { resultReceiptKey: input.resultReceiptKey }
+              : {}),
+          },
         });
         // First sub-phase of `resultDelivery`: the body was parsed above, and
         // this is the instant the row's result actually exists. Everything
@@ -7052,7 +7074,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
   private async serializeCellValue(value: unknown): Promise<unknown> {
     const serialized = isToolExecuteResult(value)
-      ? serializeToolExecuteResult(value)
+      ? serializeToolExecuteResult(value, { includeCallEvidence: false })
       : await this.serializeDatasetCells(value);
     try {
       stringifyPostgresJson(serialized);
@@ -7073,7 +7095,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const visiting = new WeakSet<object>();
     const visit = async (current: unknown): Promise<unknown> => {
       if (isToolExecuteResult(current)) {
-        return serializeToolExecuteResult(current);
+        return serializeToolExecuteResult(current, {
+          includeCallEvidence: false,
+        });
       }
       if (isPlayDataset(current)) {
         return await serializePlayDatasetCell(current, visit);
@@ -7379,7 +7403,20 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           input.metadata ??
           (await this.resolveToolResultMetadata(input.toolId)),
         execution: input.execution,
-        meta: input.meta,
+        meta: {
+          ...input.meta,
+          ...(input.execution.source === 'live' &&
+          input.requestInput &&
+          !input.meta?.callEvidence
+            ? {
+                callEvidence: {
+                  input: this.secretRedactor.redact(input.requestInput),
+                  providerRequestsUnavailable:
+                    'This response did not retain provider HTTP evidence.',
+                },
+              }
+            : {}),
+        },
         billing: input.billing,
       }),
     );
@@ -12582,6 +12619,54 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     };
   }
 
+  private async saveToolFailureEvidence(input: {
+    toolId: string;
+    callKey: string;
+    input: Record<string, unknown>;
+    error: unknown;
+    context: PlayLogContext;
+  }): Promise<string | undefined> {
+    if (!this.#options.completeRuntimeStepReceipt) return;
+    try {
+      // An immutable diagnostic record in the SAME receipt store, discovered
+      // through runtime_observability.events. It is never an executable result
+      // cache and cannot change provider admission or replay semantics.
+      const receipt = await this.completeRuntimeStepReceipt(
+        `${buildDurableToolReceiptPrefix({
+          orgId: this.#options.orgId ?? 'unknown-org',
+          toolId: 'call-evidence',
+        })}${stableDigest(`${this.currentRunId}:${crypto.randomUUID()}`)}`,
+        this.currentRunId,
+        this.secretRedactor.redact({
+          kind: 'tool_call_evidence',
+          toolId: input.toolId,
+          callKey: input.callKey,
+          status: 'failed',
+          context: input.context,
+          callEvidence: readToolCallFailureEvidence(input.error) ?? {
+            input: input.input,
+            providerRequestsUnavailable:
+              'This failure did not retain provider HTTP evidence.',
+          },
+          error:
+            serializeToolExecutionFailure(input.error) ??
+            this.formatRuntimeError(input.error),
+        }),
+        COMPLETED_RECEIPT_CACHE_INSERT_LEASE_ID,
+      );
+      if (!receipt)
+        throw new Error('Saved failure evidence was not acknowledged.');
+      return receipt.key;
+    } catch (error) {
+      // Keep the original failure and never repeat a paid operation just to
+      // repair observability. A missing record is explicit in retained logs.
+      this.runtimeLog(
+        `Saved call details unavailable: ${this.formatRuntimeError(error)}`,
+        { level: 'warn' },
+      );
+    }
+  }
+
   private async executeTool(
     key: string,
     toolId: string,
@@ -12610,13 +12695,31 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         !isPlayRowExecutionSuspendedError(error) &&
         !(error instanceof PlayRowProviderBackpressureError)
       ) {
+        const scope = authoredStepContext.getStore();
+        const savedKey = await this.saveToolFailureEvidence({
+          toolId,
+          callKey: context.call_key,
+          context: {
+            callKey: context.call_key,
+            toolId,
+            callStatus: 'failed',
+            ...(scope?.context === this ? { stepId: scope.stepId } : {}),
+            ...(context.dataset ? { dataset: context.dataset } : {}),
+            ...(context.column ? { column: context.column } : {}),
+            ...(context.row_key ? { rowKey: context.row_key } : {}),
+          },
+          input,
+          error,
+        });
         this.runtimeLog(
           JSON.stringify({
             event: 'tool_call_failed',
             ...context,
+            ...(savedKey ? { receipt_key: savedKey } : {}),
             status: 'failed',
             duration_ms: Math.max(0, Date.now() - startedAt),
           }),
+          { level: 'error' },
         );
       }
       throw error;
@@ -12627,7 +12730,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       JSON.stringify({
         event: 'tool_call_completed',
         ...context,
-        ...(execution?.receiptKey ? { receipt_key: execution.receiptKey } : {}),
+        ...(execution?.resultReceiptKey || execution?.receiptKey
+          ? { receipt_key: execution.resultReceiptKey ?? execution.receiptKey }
+          : {}),
         ...(execution?.source ? { execution_source: execution.source } : {}),
         status: toolResult?.status ?? 'completed',
         // Caller wall time includes queueing/reuse and result delivery. It is
@@ -14287,7 +14392,21 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   ): void {
     const boundedLine = boundRunLogLine(line);
     const omittedBefore = this.logBuffer.snapshot().omittedLines;
-    for (const retained of this.logBuffer.append(line, terminal, context)) {
+    const scope = authoredStepContext.getStore();
+    const classified = classifyLogLine(line);
+    const timestamp = classified.line.match(/^\[([^\]]+)\]/)?.[1];
+    const parsedAt = timestamp ? Date.parse(timestamp) : NaN;
+    const metadata: PlayLogMetadata = {
+      level: classified.level,
+      occurredAt: Number.isFinite(parsedAt) ? parsedAt : Date.now(),
+      ...(scope?.context === this ? { stepId: scope.stepId } : {}),
+    };
+    for (const retained of this.logBuffer.append(
+      line,
+      terminal,
+      context,
+      metadata,
+    )) {
       const originalLineWasRetained =
         retained === boundedLine &&
         this.logBuffer.snapshot().omittedLines === omittedBefore;
@@ -14297,6 +14416,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           ? (this.logBuffer.contexts.at(-1) ?? undefined)
           : undefined,
         this.logBuffer.ids.at(-1),
+        originalLineWasRetained
+          ? (this.logBuffer.metadata.at(-1) ?? undefined)
+          : undefined,
       );
       if (this.#options.verbose) console.log(retained);
     }
@@ -14960,42 +15082,76 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       return output;
     };
 
-    return this.executeWithRuntimeReceipt<T>(
-      'step',
-      normalizedKey,
-      this.currentRunId,
-      {
-        semanticKey: rowStore
-          ? stableDigest(
-              stableStringify({
-                scope: 'row',
-                tableNamespace: rowStore.tableNamespace ?? null,
-                rowKey: rowStore.rowKey ?? null,
-                rowId: rowStore.rowKey ? null : rowStore.rowId,
-                fieldName: rowStore.fieldName ?? null,
-                callIndex,
-                // Row scope prevents unrelated map cells from sharing a
-                // checkpoint. A supplied semantic key identifies the actual
-                // work (for example, ctx.runSteps hashes its current input),
-                // so it must refine row scope rather than being discarded.
-                semanticKey: options?.semanticKey ?? null,
-              }),
-            )
-          : options?.semanticKey,
-        staleAfterSeconds: options?.staleAfterSeconds,
-        force: this.#options.cachePolicy?.forceStepRefresh === true,
-        markSkipped: (output) => {
-          assertJsonSerializableStepOutput(normalizedKey, output);
-        },
-        execute: executeStep,
-      },
-    );
+    const observe = !rowStore;
+    const startedAt = Date.now();
+    if (observe)
+      this.emitExecutionEvent({
+        type: 'step.started',
+        stepId: normalizedKey,
+        at: startedAt,
+      });
+    try {
+      const output = await authoredStepContext.run(
+        { context: this, stepId: normalizedKey },
+        () =>
+          this.executeWithRuntimeReceipt<T>(
+            'step',
+            normalizedKey,
+            this.currentRunId,
+            {
+              semanticKey: rowStore
+                ? stableDigest(
+                    stableStringify({
+                      scope: 'row',
+                      tableNamespace: rowStore.tableNamespace ?? null,
+                      rowKey: rowStore.rowKey ?? null,
+                      rowId: rowStore.rowKey ? null : rowStore.rowId,
+                      fieldName: rowStore.fieldName ?? null,
+                      callIndex,
+                      // Row scope prevents unrelated map cells from sharing a
+                      // checkpoint. A supplied semantic key identifies the actual
+                      // work (for example, ctx.runSteps hashes its current input),
+                      // so it must refine row scope rather than being discarded.
+                      semanticKey: options?.semanticKey ?? null,
+                    }),
+                  )
+                : options?.semanticKey,
+              staleAfterSeconds: options?.staleAfterSeconds,
+              force: this.#options.cachePolicy?.forceStepRefresh === true,
+              markSkipped: (output) => {
+                assertJsonSerializableStepOutput(normalizedKey, output);
+              },
+              execute: executeStep,
+            },
+          ),
+      );
+      if (observe)
+        this.emitExecutionEvent({
+          type: 'step.completed',
+          stepId: normalizedKey,
+          at: Date.now(),
+        });
+      return output;
+    } catch (error) {
+      if (observe && !isControlledPlaySuspension(error))
+        this.emitExecutionEvent({
+          type: 'step.failed',
+          stepId: normalizedKey,
+          at: Date.now(),
+          error: buildPlayDocflowNodeErrorPreview(error, this.secretRedactor),
+        });
+      throw error;
+    }
   }
 
   getLogs(): string[] {
     return this.logBuffer.lines;
   }
 
+  getLogMetadata(): Array<PlayLogMetadata | null> {
+    return this.logBuffer.metadata.slice();
+  }
+
   getLogIds(): string[] {
     return this.logBuffer.ids.slice();
   }
@@ -15582,15 +15738,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       source: 'cache' | 'owner',
     ): Promise<void> => {
       const receiptKey = request.receiptKey!;
-      const finalResult = cloneToolExecuteResultWithExecution(
-        result,
-        toolExecutionMetadataForOutcome({
+      const finalResult = cloneToolExecuteResultWithExecution(result, {
+        ...toolExecutionMetadataForOutcome({
           kind: source === 'owner' ? 'live' : source,
           cacheKey: request.cacheKey,
           receiptKey,
           ...(source === 'owner' ? {} : { attachedToReceiptKey: receiptKey }),
         }),
-      );
+        resultReceiptKey:
+          this.mappedToolResultReceiptPolicy(request).resultReceiptKey,
+      });
       this.cacheToolResult(toolId, request.cacheKey, finalResult);
       const resolver = this.toolCallResolvers.get(request.callId);
       if (resolver) {
@@ -19305,6 +19462,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   `gateway=${transportGatewayOriginForDiagnostic(url)} attempt=${httpFailureAttempt})`,
                 { level: 'error' },
               );
+              attachToolCallFailureEvidenceFromResponse(surfacedError, text);
               throw surfacedError;
             }
 

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

@@ -11,7 +11,7 @@ import type { PlayRunContractSnapshot } from '../plays/contracts';
 import type { PlayDatasetColumnTypes } from '../play-data-plane/contracts';
 import type { PlayStructuredDefinition } from '../plays/definition';
 import type { PlayStaticPipeline } from '../plays/static-pipeline';
-import type { PlayLogContext } from './log-context';
+import type { PlayLogContext, PlayLogMetadata } from './log-context';
 import type {
   AsyncPlayRunRef,
   DurableCallStaleAfterSeconds,
@@ -514,6 +514,9 @@ export interface MapExecutionScope {
 }
 
 export type PlayExecutionEvent =
+  | { type: 'step.started'; stepId: string; at: number }
+  | { type: 'step.completed'; stepId: string; at: number }
+  | { type: 'step.failed'; stepId: string; error: string; at: number }
   | PlayActivityEvent
   | {
       type: 'docflow.node.hit';
@@ -851,7 +854,12 @@ export interface ContextOptions {
   /** Called after each durable batch completes for scheduler checkpointing. */
   onBatchComplete?: (checkpoint: PlayCheckpoint) => void;
   /** Called when the runtime emits a new execution log line. */
-  onLog?: (line: string, context?: PlayLogContext, entryId?: string) => void;
+  onLog?: (
+    line: string,
+    context?: PlayLogContext,
+    entryId?: string,
+    metadata?: PlayLogMetadata,
+  ) => void;
   /**
    * Runtime-provided HTTP transport for ctx.fetch. Node runtimes should provide
    * a transport that validates resolved IP addresses at connect time.