deepline 0.3.405 → 0.3.407

package/dist/cli/{workflow-SVMVLQOF.mjs → workflow-ZMAA5VCN.mjs}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-H7HIDGZ7.mjs";
 import {
   DeeplineClient
-} from "./chunk-HG5PMETP.mjs";
+} from "./chunk-J67NU4MQ.mjs";
 import "./chunk-6IKARAYD.mjs";
 import "./chunk-JI2B4RZP.mjs";
 import "./chunk-EIMG75BT.mjs";
@@ -16,12 +16,12 @@ import {
   printJson,
   shouldEmitJson,
   sleep
-} from "./chunk-3DWMYKWU.mjs";
-import "./chunk-TPYRDAU7.mjs";
+} from "./chunk-BKC6VMYZ.mjs";
+import "./chunk-ZBCTXQ3P.mjs";
 import "./chunk-YHPYUZZX.mjs";
 import "./chunk-DLIRSHV6.mjs";
 import "./chunk-NXGCO4JB.mjs";
-import "./chunk-EKWJXPIX.mjs";
+import "./chunk-UPEOEYZ3.mjs";
 import "./chunk-WZYKRD7T.mjs";
 import "./chunk-KRD6H754.mjs";
 
@@ -1676,7 +1676,7 @@ async function transformOne(api, workflowId, outDir, publish) {
     await writeFile(file, compiled.sourceCode, "utf8");
     let published = false;
     if (publish) {
-      const { handlePlayPublish } = await import("./play-WV4UNGPR.mjs");
+      const { handlePlayPublish } = await import("./play-5Z4ROZ3P.mjs");
       const code = await handlePlayPublish([file]);
       if (code !== 0) {
         return {

package/dist/{client-Buv1_ktG.d.mts → client-6rEB46Lv.d.mts}

@@ -1,5 +1,5 @@
 /// <reference path="./text-imports.d.ts" />
-import { g as PlayCompilerManifest, ak as ToolResultBilling, Y as BillingEntitlements, ap as BillingBenefitValues } from './compiler-manifest-N77W75Py.mjs';
+import { g as PlayCompilerManifest, ak as ToolResultBilling, Y as BillingEntitlements, ap as BillingBenefitValues } from './compiler-manifest-BHnXE43X.mjs';
 import { z } from 'zod';
 import { MonitorFleetDefinition } from './monitor-fleet-contract.mjs';
 
@@ -2492,9 +2492,10 @@ interface StopPlayRunResult {
     /** True if HITL state or its same-message Slack card still needs retrying. */
     hitlCancellationPending?: boolean;
     /**
-     * True only when the scheduler and the canonical run ledger disagree (for
-     * example a terminal scheduler run whose ledger projection is pending), so
-     * the stop could not be confirmed. Never set for a queued cancellation.
+     * True only when the scheduler and the canonical run ledger disagree and
+     * the server could not confirm the stop.
+     * For example, the scheduler can report a terminal run while the ledger
+     * projection is pending. This field is never true for a queued cancellation.
      */
     staleSchedulerState?: boolean;
     /** Server-side error detail when the stop failed (`state: 'failed'`). */
@@ -6217,8 +6218,8 @@ declare class DeeplineClient {
     /**
      * Search available tools using Deepline's ranked backend search.
      *
-     * This is the same discovery surface used by the CLI: it ranks across
-     * tool metadata, categories, agent guidance, and input schema fields.
+     * The CLI uses the same search.
+     * The search ranks tool metadata, categories, agent guidance, and input schema fields.
      */
     searchTools(options?: ToolSearchOptions): Promise<ToolSearchResult>;
     /**
@@ -6256,13 +6257,12 @@ declare class DeeplineClient {
     /**
      * Describe a Deepline Agent model and its provider-specific option surface.
      *
-     * Combines live AI Gateway model metadata with Deepline's generated AI SDK
-     * provider option registry so agents can construct `providerOptions`
-     * payloads before executing `deeplineagent`.
+     * The method combines live AI Gateway model metadata with Deepline's generated registry of AI SDK provider options.
+     * Agents can use this information to construct `providerOptions` payloads before they execute `deeplineagent`.
      *
-     * The returned option schemas describe accepted provider option shapes, not
-     * guaranteed support for every model. Runtime AI SDK/Gateway errors remain
-     * authoritative for model-gated values.
+     * The returned schemas describe accepted shapes for provider options.
+     * These schemas do not guarantee that every model supports each option.
+     * Runtime AI SDK and Gateway errors determine support for model-specific values.
      *
      * @param model - Exact-case Gateway model id such as `"openai/gpt-5.6-luna"`
      * @returns Model metadata, provider option shapes, and runnable examples
@@ -6271,8 +6271,8 @@ declare class DeeplineClient {
     /**
      * Quote dynamic AI inference pricing for a concrete payload.
      *
-     * The result separates a planning estimate from a proven authorization
-     * maximum and contains Deepline credits only.
+     * The result contains a planning estimate and a separate, proven authorization maximum.
+     * Both values use Deepline credits.
      */
     quoteInferenceTool(toolId: 'ai_evaluate' | 'ai_inference' | 'deeplineagent', payload: Record<string, unknown>): Promise<InferenceQuote>;
     /**
@@ -6324,13 +6324,16 @@ declare class DeeplineClient {
      * entrypoints: the CLI, {@link Deepline.connect}, {@link submitPlay},
      * or {@link runPlay}.
      *
-     * Supported invocation surfaces intentionally share this same run contract:
-     * `deepline plays run`, repo scripts such as `bun run deepline -- plays run`,
-     * SDK context calls like `Deepline.connect().play(name).run()`, and direct
-     * `POST /api/v2/plays/run` calls all return a workflow/run id. The completed
-     * output is always retrievable from `getPlayStatus(runId).result` (or from
-     * `PlayJob.get()` for SDK context calls). Execution logs live under
-     * `progress.logs`; they are not part of the user output object.
+     * These interfaces share the run contract and return a workflow or run ID:
+     *
+     * - `deepline plays run`.
+     * - Repository scripts such as `bun run deepline -- plays run`.
+     * - SDK context calls such as `Deepline.connect().play(name).run()`.
+     * - Direct `POST /api/v2/plays/run` calls.
+     *
+     * Read completed output from `getPlayStatus(runId).result`.
+     * For SDK context calls, read output from `PlayJob.get()`.
+     * Execution logs appear under `progress.logs`. The user output object does not contain these logs.
      *
      * @param request - Play run configuration (name, code, input, etc.)
      * @returns Run metadata including the public `workflowId`
@@ -6464,9 +6467,8 @@ declare class DeeplineClient {
     /**
      * Compile a bundled play artifact into the server-side compiler manifest.
      *
-     * The manifest records imports, trigger bindings, static pipeline shape, and
-     * runtime metadata needed before a play artifact can be checked, registered,
-     * or run.
+     * The manifest records imports, trigger bindings, static pipeline shape, and runtime metadata.
+     * The compiler needs these records before it checks, registers, or runs a Play artifact.
      */
     compilePlayManifest(input: {
         name: string;
@@ -6518,8 +6520,8 @@ declare class DeeplineClient {
     /**
      * Register an already-bundled play artifact and start a run from it.
      *
-     * This is the low-level file-backed run path used by SDK/CLI packaging
-     * wrappers after local bundling has produced the runtime artifact.
+     * SDK and CLI packaging wrappers use this low-level run method for file-based Plays.
+     * Local bundling must produce the runtime artifact first.
      */
     startPlayRunFromBundle(input: {
         name: string;
@@ -6537,15 +6539,15 @@ declare class DeeplineClient {
     /**
      * Register a bundled play artifact and start a run from the live revision.
      *
-     * Convenience wrapper around {@link registerPlayArtifact} plus
-     * {@link startPlayRun}. This is the canonical file-backed path used by wrappers.
-     * The returned id can be passed to {@link getPlayStatus} to retrieve the same
-     * durable `{ result }` object that the CLI prints after `plays run` completes.
+     * This method wraps {@link registerPlayArtifact} and {@link startPlayRun}.
+     * Packaging wrappers use this method for file-based Plays.
+     * Pass the returned ID to {@link getPlayStatus}.
+     * The method returns the same durable `{ result }` object that the CLI prints after `plays run` completes.
      *
-     * @param code - Source string fallback; the bundled artifact should be passed in `options.artifact`
-     * @param csvPath - Path to input CSV file, or `null`
-     * @param name - Play name (extracted from source if omitted)
-     * @param options - Additional submission options
+     * @param code - Fallback source string. Pass the bundled artifact in `options.artifact`.
+     * @param csvPath - Path to the input CSV file, or `null`.
+     * @param name - Play name. The SDK derives it from the source when omitted.
+     * @param options - Additional submission options.
      * @returns Workflow metadata with `workflowId`
      *
      * @example
@@ -6604,9 +6606,8 @@ declare class DeeplineClient {
     /**
      * Mint short-lived presigned upload targets for staged play files.
      *
-     * Internal primitive used by {@link stagePlayFiles}. The server returns an
-     * already-staged ref (no upload needed) for content-addressed files it
-     * already holds, or a presigned PUT URL the caller uploads the body to.
+     * Internal primitive used by {@link stagePlayFiles}. For a content-addressed file already in storage, the server returns a staged reference. That file needs no upload.
+     * For other files, the server returns a presigned PUT URL. Upload the file body to that URL.
      */
     mintStagedPlayFileUploads(files: Array<{
         logicalPath: string;
@@ -6617,8 +6618,7 @@ declare class DeeplineClient {
     /**
      * Resolve staged play files by content hash without uploading bytes.
      *
-     * Missing files are returned so callers can upload only the files the server
-     * does not already have.
+     * The response identifies missing files. Callers need to upload only these files.
      */
     resolveStagedPlayFiles(files: Array<{
         logicalPath: string;
@@ -6832,11 +6832,11 @@ declare class DeeplineClient {
     /**
      * Start a fresh run from a prior run's retained input and pinned revision.
      *
-     * Every invocation sends an `Idempotency-Key`. When the caller does not
-     * supply one, a fresh key is generated once per call so the transport's own
-     * network retries converge on a single rerun. Pass the same explicit key
-     * across separate invocations to repeat an ambiguous result safely; a
-     * different key intentionally starts another rerun.
+     * Every invocation sends an `Idempotency-Key`.
+     * When the caller supplies no key, the SDK creates a fresh key once per call.
+     * The transport reuses that key for network retries, so those retries produce one rerun.
+     * Reuse an explicit key across separate invocations when the previous result is uncertain.
+     * A different key starts another rerun.
      */
     rerun(runId: string, options?: RerunOptions): Promise<RerunPlayRunResult>;
     /**
@@ -6914,8 +6914,8 @@ declare class DeeplineClient {
     /** Stop, or with `dryRun: true` only enumerate, active workspace runs. */
     stopAllRuns(options?: StopAllRunsOptions): Promise<StopAllPlayRunsResult>;
     /**
-     * List one page of callable plays; grep retains exhaustive matching results.
-     * Use listPlaysPage to retain pagination metadata.
+     * List one page of callable Plays. With grep, the method retains all matching results.
+     * Use listPlaysPage for pagination metadata.
      *
      * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
      * `origin: "owned"` for org-owned plays.
@@ -7056,8 +7056,7 @@ declare class DeeplineClient {
     /**
      * Get the full definition and state of a named play.
      *
-     * Returns the play's revision state (draft, live), recent runs,
-     * sheet processing summary, and database URL.
+     * The response includes revision state (draft or live), recent runs, a summary of sheet processing, and the database URL.
      *
      * @param name - Play name
      * @returns Complete play detail
@@ -7108,10 +7107,10 @@ declare class DeeplineClient {
     /**
      * Get a normalized play description suitable for agents and CLIs.
      *
-     * The description includes runnable examples, input/output summaries, clone
-     * guidance, revision state, and latest run metadata when available. Pass
-     * `{ pipeline: true }` to include the compiled pipeline, which can be
-     * hundreds of kilobytes and is otherwise left out.
+     * The description includes runnable examples, input and output summaries, clone guidance, and revision state.
+     * It also includes metadata for the latest run when available.
+     * Set `{ pipeline: true }` to include the compiled pipeline.
+     * The pipeline can be hundreds of kilobytes. The response omits it by default.
      */
     describePlay(name: string, options?: PlayDescriptionOptions): Promise<PlayDescription>;
     /**
@@ -7135,8 +7134,7 @@ declare class DeeplineClient {
      * Make a play revision live.
      *
      * When `revisionId` is omitted, the current working revision becomes live.
-     * The live version is what executes when the play is run by name without
-     * specifying an explicit revision.
+     * A call by Play name executes the live revision unless the caller specifies another revision.
      *
      * @param name - Play name
      * @param request - Optional explicit revision to make live
@@ -7262,9 +7260,9 @@ declare class DeeplineClient {
      */
     getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent>;
     /**
-     * What Deepline has billed each run so far (customer-visible credits, never
-     * provider spend) and whether any of its charges is still settling — the
-     * same read the dashboard's runs grid shows. `GET /api/v2/runs/billing`.
+     * Read Deepline credits billed to each run and whether charges are still settling.
+     * The response never shows provider spend. The dashboard runs grid uses the same read.
+     * HTTP endpoint: `GET /api/v2/runs/billing`.
      */
     getRunBilling(runIds: readonly string[]): Promise<RunBillingResult>;
     /**

package/dist/{client-Db1jFLpF.d.ts → client-IrPHUE5J.d.ts}

@@ -1,5 +1,5 @@
 /// <reference path="./text-imports.d.ts" />
-import { g as PlayCompilerManifest, ak as ToolResultBilling, Y as BillingEntitlements, ap as BillingBenefitValues } from './compiler-manifest-N77W75Py.js';
+import { g as PlayCompilerManifest, ak as ToolResultBilling, Y as BillingEntitlements, ap as BillingBenefitValues } from './compiler-manifest-BHnXE43X.js';
 import { z } from 'zod';
 import { MonitorFleetDefinition } from './monitor-fleet-contract.js';
 
@@ -2492,9 +2492,10 @@ interface StopPlayRunResult {
     /** True if HITL state or its same-message Slack card still needs retrying. */
     hitlCancellationPending?: boolean;
     /**
-     * True only when the scheduler and the canonical run ledger disagree (for
-     * example a terminal scheduler run whose ledger projection is pending), so
-     * the stop could not be confirmed. Never set for a queued cancellation.
+     * True only when the scheduler and the canonical run ledger disagree and
+     * the server could not confirm the stop.
+     * For example, the scheduler can report a terminal run while the ledger
+     * projection is pending. This field is never true for a queued cancellation.
      */
     staleSchedulerState?: boolean;
     /** Server-side error detail when the stop failed (`state: 'failed'`). */
@@ -6217,8 +6218,8 @@ declare class DeeplineClient {
     /**
      * Search available tools using Deepline's ranked backend search.
      *
-     * This is the same discovery surface used by the CLI: it ranks across
-     * tool metadata, categories, agent guidance, and input schema fields.
+     * The CLI uses the same search.
+     * The search ranks tool metadata, categories, agent guidance, and input schema fields.
      */
     searchTools(options?: ToolSearchOptions): Promise<ToolSearchResult>;
     /**
@@ -6256,13 +6257,12 @@ declare class DeeplineClient {
     /**
      * Describe a Deepline Agent model and its provider-specific option surface.
      *
-     * Combines live AI Gateway model metadata with Deepline's generated AI SDK
-     * provider option registry so agents can construct `providerOptions`
-     * payloads before executing `deeplineagent`.
+     * The method combines live AI Gateway model metadata with Deepline's generated registry of AI SDK provider options.
+     * Agents can use this information to construct `providerOptions` payloads before they execute `deeplineagent`.
      *
-     * The returned option schemas describe accepted provider option shapes, not
-     * guaranteed support for every model. Runtime AI SDK/Gateway errors remain
-     * authoritative for model-gated values.
+     * The returned schemas describe accepted shapes for provider options.
+     * These schemas do not guarantee that every model supports each option.
+     * Runtime AI SDK and Gateway errors determine support for model-specific values.
      *
      * @param model - Exact-case Gateway model id such as `"openai/gpt-5.6-luna"`
      * @returns Model metadata, provider option shapes, and runnable examples
@@ -6271,8 +6271,8 @@ declare class DeeplineClient {
     /**
      * Quote dynamic AI inference pricing for a concrete payload.
      *
-     * The result separates a planning estimate from a proven authorization
-     * maximum and contains Deepline credits only.
+     * The result contains a planning estimate and a separate, proven authorization maximum.
+     * Both values use Deepline credits.
      */
     quoteInferenceTool(toolId: 'ai_evaluate' | 'ai_inference' | 'deeplineagent', payload: Record<string, unknown>): Promise<InferenceQuote>;
     /**
@@ -6324,13 +6324,16 @@ declare class DeeplineClient {
      * entrypoints: the CLI, {@link Deepline.connect}, {@link submitPlay},
      * or {@link runPlay}.
      *
-     * Supported invocation surfaces intentionally share this same run contract:
-     * `deepline plays run`, repo scripts such as `bun run deepline -- plays run`,
-     * SDK context calls like `Deepline.connect().play(name).run()`, and direct
-     * `POST /api/v2/plays/run` calls all return a workflow/run id. The completed
-     * output is always retrievable from `getPlayStatus(runId).result` (or from
-     * `PlayJob.get()` for SDK context calls). Execution logs live under
-     * `progress.logs`; they are not part of the user output object.
+     * These interfaces share the run contract and return a workflow or run ID:
+     *
+     * - `deepline plays run`.
+     * - Repository scripts such as `bun run deepline -- plays run`.
+     * - SDK context calls such as `Deepline.connect().play(name).run()`.
+     * - Direct `POST /api/v2/plays/run` calls.
+     *
+     * Read completed output from `getPlayStatus(runId).result`.
+     * For SDK context calls, read output from `PlayJob.get()`.
+     * Execution logs appear under `progress.logs`. The user output object does not contain these logs.
      *
      * @param request - Play run configuration (name, code, input, etc.)
      * @returns Run metadata including the public `workflowId`
@@ -6464,9 +6467,8 @@ declare class DeeplineClient {
     /**
      * Compile a bundled play artifact into the server-side compiler manifest.
      *
-     * The manifest records imports, trigger bindings, static pipeline shape, and
-     * runtime metadata needed before a play artifact can be checked, registered,
-     * or run.
+     * The manifest records imports, trigger bindings, static pipeline shape, and runtime metadata.
+     * The compiler needs these records before it checks, registers, or runs a Play artifact.
      */
     compilePlayManifest(input: {
         name: string;
@@ -6518,8 +6520,8 @@ declare class DeeplineClient {
     /**
      * Register an already-bundled play artifact and start a run from it.
      *
-     * This is the low-level file-backed run path used by SDK/CLI packaging
-     * wrappers after local bundling has produced the runtime artifact.
+     * SDK and CLI packaging wrappers use this low-level run method for file-based Plays.
+     * Local bundling must produce the runtime artifact first.
      */
     startPlayRunFromBundle(input: {
         name: string;
@@ -6537,15 +6539,15 @@ declare class DeeplineClient {
     /**
      * Register a bundled play artifact and start a run from the live revision.
      *
-     * Convenience wrapper around {@link registerPlayArtifact} plus
-     * {@link startPlayRun}. This is the canonical file-backed path used by wrappers.
-     * The returned id can be passed to {@link getPlayStatus} to retrieve the same
-     * durable `{ result }` object that the CLI prints after `plays run` completes.
+     * This method wraps {@link registerPlayArtifact} and {@link startPlayRun}.
+     * Packaging wrappers use this method for file-based Plays.
+     * Pass the returned ID to {@link getPlayStatus}.
+     * The method returns the same durable `{ result }` object that the CLI prints after `plays run` completes.
      *
-     * @param code - Source string fallback; the bundled artifact should be passed in `options.artifact`
-     * @param csvPath - Path to input CSV file, or `null`
-     * @param name - Play name (extracted from source if omitted)
-     * @param options - Additional submission options
+     * @param code - Fallback source string. Pass the bundled artifact in `options.artifact`.
+     * @param csvPath - Path to the input CSV file, or `null`.
+     * @param name - Play name. The SDK derives it from the source when omitted.
+     * @param options - Additional submission options.
      * @returns Workflow metadata with `workflowId`
      *
      * @example
@@ -6604,9 +6606,8 @@ declare class DeeplineClient {
     /**
      * Mint short-lived presigned upload targets for staged play files.
      *
-     * Internal primitive used by {@link stagePlayFiles}. The server returns an
-     * already-staged ref (no upload needed) for content-addressed files it
-     * already holds, or a presigned PUT URL the caller uploads the body to.
+     * Internal primitive used by {@link stagePlayFiles}. For a content-addressed file already in storage, the server returns a staged reference. That file needs no upload.
+     * For other files, the server returns a presigned PUT URL. Upload the file body to that URL.
      */
     mintStagedPlayFileUploads(files: Array<{
         logicalPath: string;
@@ -6617,8 +6618,7 @@ declare class DeeplineClient {
     /**
      * Resolve staged play files by content hash without uploading bytes.
      *
-     * Missing files are returned so callers can upload only the files the server
-     * does not already have.
+     * The response identifies missing files. Callers need to upload only these files.
      */
     resolveStagedPlayFiles(files: Array<{
         logicalPath: string;
@@ -6832,11 +6832,11 @@ declare class DeeplineClient {
     /**
      * Start a fresh run from a prior run's retained input and pinned revision.
      *
-     * Every invocation sends an `Idempotency-Key`. When the caller does not
-     * supply one, a fresh key is generated once per call so the transport's own
-     * network retries converge on a single rerun. Pass the same explicit key
-     * across separate invocations to repeat an ambiguous result safely; a
-     * different key intentionally starts another rerun.
+     * Every invocation sends an `Idempotency-Key`.
+     * When the caller supplies no key, the SDK creates a fresh key once per call.
+     * The transport reuses that key for network retries, so those retries produce one rerun.
+     * Reuse an explicit key across separate invocations when the previous result is uncertain.
+     * A different key starts another rerun.
      */
     rerun(runId: string, options?: RerunOptions): Promise<RerunPlayRunResult>;
     /**
@@ -6914,8 +6914,8 @@ declare class DeeplineClient {
     /** Stop, or with `dryRun: true` only enumerate, active workspace runs. */
     stopAllRuns(options?: StopAllRunsOptions): Promise<StopAllPlayRunsResult>;
     /**
-     * List one page of callable plays; grep retains exhaustive matching results.
-     * Use listPlaysPage to retain pagination metadata.
+     * List one page of callable Plays. With grep, the method retains all matching results.
+     * Use listPlaysPage for pagination metadata.
      *
      * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
      * `origin: "owned"` for org-owned plays.
@@ -7056,8 +7056,7 @@ declare class DeeplineClient {
     /**
      * Get the full definition and state of a named play.
      *
-     * Returns the play's revision state (draft, live), recent runs,
-     * sheet processing summary, and database URL.
+     * The response includes revision state (draft or live), recent runs, a summary of sheet processing, and the database URL.
      *
      * @param name - Play name
      * @returns Complete play detail
@@ -7108,10 +7107,10 @@ declare class DeeplineClient {
     /**
      * Get a normalized play description suitable for agents and CLIs.
      *
-     * The description includes runnable examples, input/output summaries, clone
-     * guidance, revision state, and latest run metadata when available. Pass
-     * `{ pipeline: true }` to include the compiled pipeline, which can be
-     * hundreds of kilobytes and is otherwise left out.
+     * The description includes runnable examples, input and output summaries, clone guidance, and revision state.
+     * It also includes metadata for the latest run when available.
+     * Set `{ pipeline: true }` to include the compiled pipeline.
+     * The pipeline can be hundreds of kilobytes. The response omits it by default.
      */
     describePlay(name: string, options?: PlayDescriptionOptions): Promise<PlayDescription>;
     /**
@@ -7135,8 +7134,7 @@ declare class DeeplineClient {
      * Make a play revision live.
      *
      * When `revisionId` is omitted, the current working revision becomes live.
-     * The live version is what executes when the play is run by name without
-     * specifying an explicit revision.
+     * A call by Play name executes the live revision unless the caller specifies another revision.
      *
      * @param name - Play name
      * @param request - Optional explicit revision to make live
@@ -7262,9 +7260,9 @@ declare class DeeplineClient {
      */
     getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent>;
     /**
-     * What Deepline has billed each run so far (customer-visible credits, never
-     * provider spend) and whether any of its charges is still settling — the
-     * same read the dashboard's runs grid shows. `GET /api/v2/runs/billing`.
+     * Read Deepline credits billed to each run and whether charges are still settling.
+     * The response never shows provider spend. The dashboard runs grid uses the same read.
+     * HTTP endpoint: `GET /api/v2/runs/billing`.
      */
     getRunBilling(runIds: readonly string[]): Promise<RunBillingResult>;
     /**

package/dist/{compiler-manifest-N77W75Py.d.ts → compiler-manifest-BHnXE43X.d.mts}

@@ -1276,7 +1276,12 @@ type PlayAuthoringFetchResponse = {
     /** Full response body as text, with any known secret values redacted. */
     bodyText: string;
     /**
-     * The parsed body, eagerly decoded at request time. Read it as a property — `const body = res.json`, never `await res.json()`. Null when the body is empty AND when it is not valid JSON: a malformed payload is reported as null rather than thrown, so check `res.ok` and fall back to `res.bodyText` before treating null as an empty result.
+     * The runtime parses the body at request time.
+     * Read the property with `const body = res.json`. Do not call `await res.json()`.
+     * The value is null when the body is empty or is not valid JSON.
+     * Malformed JSON produces null instead of an error.
+     *
+     * Check `res.ok`. Check `res.bodyText` before you interpret null as an empty response.
      */
     json: unknown | null;
 };

package/dist/{compiler-manifest-N77W75Py.d.mts → compiler-manifest-BHnXE43X.d.ts}

@@ -1276,7 +1276,12 @@ type PlayAuthoringFetchResponse = {
     /** Full response body as text, with any known secret values redacted. */
     bodyText: string;
     /**
-     * The parsed body, eagerly decoded at request time. Read it as a property — `const body = res.json`, never `await res.json()`. Null when the body is empty AND when it is not valid JSON: a malformed payload is reported as null rather than thrown, so check `res.ok` and fall back to `res.bodyText` before treating null as an empty result.
+     * The runtime parses the body at request time.
+     * Read the property with `const body = res.json`. Do not call `await res.json()`.
+     * The value is null when the body is empty or is not valid JSON.
+     * Malformed JSON produces null instead of an error.
+     *
+     * Check `res.ok`. Check `res.bodyText` before you interpret null as an empty response.
      */
     json: unknown | null;
 };

package/dist/{index-3WOfyVhW.d.mts → index-Da_Y8z5e.d.mts}

@@ -1,5 +1,5 @@
 /// <reference path="./text-imports.d.ts" />
-import { b as PlayBundleArtifact, f as PlaySandboxRuntimeDeclaration, g as PlayCompilerManifest, h as PlayArtifactKind } from './compiler-manifest-N77W75Py.mjs';
+import { b as PlayBundleArtifact, f as PlaySandboxRuntimeDeclaration, g as PlayCompilerManifest, h as PlayArtifactKind } from './compiler-manifest-BHnXE43X.mjs';
 
 type ImportedPlayDependency = {
     filePath: string;

package/dist/{index-CtIJFTCl.d.ts → index-SODb2ROS.d.ts}

@@ -1,5 +1,5 @@
 /// <reference path="./text-imports.d.ts" />
-import { b as PlayBundleArtifact, f as PlaySandboxRuntimeDeclaration, g as PlayCompilerManifest, h as PlayArtifactKind } from './compiler-manifest-N77W75Py.js';
+import { b as PlayBundleArtifact, f as PlaySandboxRuntimeDeclaration, g as PlayCompilerManifest, h as PlayArtifactKind } from './compiler-manifest-BHnXE43X.js';
 
 type ImportedPlayDependency = {
     filePath: string;

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 /// <reference path="./text-imports.d.ts" />
-import { T as ToolExecuteResult, B as BasicToolExecuteResult, i as PlayDataset, A as AsyncPlayRunRef$1, j as PlayAuthoringColumnMap, k as PlayAuthoringColumnResolver, l as PlayAuthoringRuntimeContext, m as PlayAuthoringConditionalStepResolver, n as PlayAuthoringCsvInput, o as PlayAuthoringCsvOptions, p as PlayAuthoringDatasetBuilder, q as PlayAuthoringDatasetColumnDefinition, r as PlayAuthoringDatasetColumnRunInput, s as PlayAuthoringReferenceLike, t as PlayReturnObject$1, u as PlayAuthoringDefineConfig, v as PlayAuthoringDefinedPlay, w as PlayAuthoringFetchOptions, x as PlayAuthoringFileInput, y as PlayAuthoringAsyncCallOptions, z as PlayAuthoringBindings, C as PlayAuthoringCallExecution, D as PlayAuthoringCallOptions, E as PlayAuthoringFetchResponse, F as PlayAuthoringInputContract, G as PlayRunId$1, H as PlayAuthoringStepProgramStep, I as PlayAuthoringRuntimeStepOptions, J as PlaySqlListenerDeclaration, K as PlaySqlListenerEvent, L as PlaySqlListenerOperation, M as PlaySqlQuery, N as PlayAuthoringStepOptions, O as PlayAuthoringStepProgram, Q as PlayAuthoringStepProgramResolver, R as PlayAuthoringStepResolver, S as PlayToolExecutionRequest, U as PlayAuthoringStepProgramOptions, V as DeeplineError, W as ToolExecutionError, X as ToolExecutionErrorOptions } from './compiler-manifest-N77W75Py.mjs';
-export { Y as BillingEntitlements, Z as CtxFetchHttpError, _ as DEEPLINE_EXTRACTOR_TARGETS, $ as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, a0 as DeeplineEmailStatusGetterValue, a1 as DeeplineExtractorTarget, a2 as DeeplineGetterValue, a3 as DeeplineGetterValueMap, a4 as JOB_CHANGE_STATUS_VALUES, a5 as JobChangeStatus, a6 as PHONE_STATUS_VALUES, a7 as PhoneStatus, a8 as PlayDatasetInput, a9 as PreviousCell, aa as ProviderTransientError, ab as ProviderTransientErrorCategory, ac as ProviderUnavailableError, ad as ProviderUnavailableReason, ae as ToolExecutionErrorCategory, af as ToolExecutionErrorOrigin, ag as ToolExecutionFailureV1, ah as ToolExecutionNetworkKind, ai as ToolExecutionNetworkScope, aj as ToolExecutionPublicDetails, ak as ToolResultBilling, al as getProviderUnavailableReason, am as isDeeplineExtractorTarget, an as isProviderUnavailable, ao as isProviderWaterfallUnavailableError } from './compiler-manifest-N77W75Py.mjs';
-import { b as DeeplineClientOptions, B as BillingNamespace, T as ToolDefinition, c as ToolMetadata, E as ExecuteToolRawOptions, d as ExecutionRecovery, e as ExecutionByKeyResult, f as PlayListItem, g as PlayDetail, h as PlayRunListItem, i as PlayRevisionSummary, j as PublishPlayVersionResult, C as ClearPlayHistoryResult, k as PlayStatus, l as StopPlayRunResult, a as DeeplineClient, R as ResolvedConfig } from './client-Buv1_ktG.mjs';
-export { m as BillingCreditPool, n as BillingInvoiceEntry, o as BillingInvoicesResult, p as BillingPaymentMethodSummary, q as BillingQuoteRequest, r as BillingQuoteResult, s as BillingRecentUsageEntry, t as BillingSubscriptionCancelResult, u as BillingSubscriptionStatus, v as BillingTopUpReceipt, w as BillingTopUpResult, x as BillingUsageEvent, y as BillingUsageOptions, z as BillingUsageResult, A as ChildRunSummary, F as ClearPlayHistoryRequest, G as CreateNotificationGroupInput, H as CreateNotificationGroupResult, I as CustomerDbQueryOptions, J as CustomerDbQueryPlan, K as CustomerDbQueryResult, L as DEEPLINE_TOOL_CATEGORIES, M as DbNamespace, N as DeeplineToolCategory, O as IngestionStorageRepairResult, Q as LegacyMonitorStatusFilter, U as LiveEventEnvelope, V as MONITOR_JOB_PHASES, W as MONITOR_JOB_RECONCILIATION_STATES, X as MONITOR_JOB_STATES, Y as MonitorBatchNamespace, Z as MonitorCheckResult, _ as MonitorDefinition, $ as MonitorDeleteResult, a0 as MonitorDependents, a1 as MonitorDeployResult, a2 as MonitorDetail, a3 as MonitorFleetDeactivateOptions, a4 as MonitorFleetGetOptions, a5 as MonitorFleetReactivateOptions, a6 as MonitorFleetResult, a7 as MonitorFleetStatus, a8 as MonitorFleetSyncOptions, a9 as MonitorFleetWaitOptions, aa as MonitorFleetsNamespace, ab as MonitorJobDeployOptions, ac as MonitorJobLogsOptions, ad as MonitorJobPhase, ae as MonitorJobReconciliationState, af as MonitorJobResult, ag as MonitorJobState, ah as MonitorJobWaitOptions, ai as MonitorJobsNamespace, aj as MonitorListEntry, ak as MonitorPayload, al as MonitorReactivateResult, am as MonitorSpec, an as MonitorState, ao as MonitorStateFilter, ap as MonitorUpdateChangeSummary, aq as MonitorUpdateResult, ar as MonitorsAccessStatus, as as MonitorsAvailableOptions, at as MonitorsAvailableResult, au as MonitorsListOptions, av as MonitorsListResult, aw as MonitorsNamespace, ax as NormalizedRunEventQuery, ay as PlayActivityObservation, az as PlayActivityState, aA as PlayActivityTarget, aB as PlayCostEstimate, aC as PlayCronTriggerConfig, aD as PlayDescriptionOptions, aE as PlayLiveEvent, aF as PlayPath, aG as PlayRunActionPackage, aH as PlayRunActivityProjection, aI as PlayRunDatasetActions, aJ as PlayRunPackage, aK as PlayRunResult, aL as PlayRunRowHistoryOptions, aM as PlayRunStart, aN as PlaySettings, aO as PlaySettingsPatch, aP as PlaySettingsPathsPage, aQ as PlaySettingsResult, aR as PlaySheetRow, aS as PlaySheetRowsResult, aT as PlayTriggerConfigUpdate, aU as PlayTriggerConfigUpdateResult, aV as PlayTriggerConfigView, aW as PlayWebhookAuthConfig, aX as PlayWebhookTriggerConfig, aY as PlaysActivityResponse, aZ as PlaysListOptions, a_ as PlaysListPage, a$ as PublishPlayVersionRequest, b0 as RerunOptions, b1 as RerunPlayRunResult, b2 as RunChildrenPage, b3 as RunEventCountResult, b4 as RunEventField, b5 as RunEventFieldDescriptor, b6 as RunEventFieldOperators, b7 as RunEventFieldsResult, b8 as RunEventGroupValue, b9 as RunEventMeasure, ba as RunEventQueryCriteria, bb as RunEventQueryEvent, bc as RunEventQueryInputError, bd as RunEventQueryOptions, be as RunEventQueryPage, bf as RunEventQueryRetention, bg as RunEventScalar, bh as RunEventSummaryOptions, bi as RunEventSummaryResult, bj as RunEventWhere, bk as RunLifecycleStatus, bl as RunToolReceiptResult, bm as RunToolReceiptsResponse, bn as RunsChildrenOptions, bo as RunsEventPayload, bp as RunsEventSearchEntry, bq as RunsEventSearchOptions, br as RunsEventSearchResult, bs as RunsEventsCountResult, bt as RunsEventsCriteria, bu as RunsEventsFieldsOptions, bv as RunsEventsListOptions, bw as RunsEventsListResult, bx as RunsEventsNamespace, by as RunsEventsSummaryOptions, bz as RunsEventsSummaryResult, bA as RunsHistoryItem, bB as RunsHistoryOptions, bC as RunsHistoryPage, bD as RunsListOptions, bE as RunsListPage, bF as RunsLogCriteria, bG as RunsLogsCountResult, bH as RunsLogsNamespace, bI as RunsLogsOptions, bJ as RunsLogsQueryOptions, bK as RunsLogsQueryResult, bL as RunsLogsResult, bM as RunsLogsSummaryOptions, bN as RunsLogsSummaryResult, bO as RunsNamespace, bP as RunsTailOptions, bQ as RunsWatchOptions, bR as SearchOptions, bS as SearchResult, bT as SearchResultItem, S as SearchType, bU as StartPlayRunRequest, bV as StopAllCandidate, bW as StopAllPlayRunsDryRunResult, bX as StopAllPlayRunsResult, bY as StopAllPlayRunsStopResult, bZ as StopAllRunsOptions, b_ as ToolExecution, b$ as ToolRequestCondition, c0 as ToolRequestWarningRule, c1 as ToolSearchOptions, c2 as ToolSearchResult, c3 as WorkspaceCreateResult, c4 as WorkspacesNamespace, c5 as defineMonitor, c6 as isStopAllPlayRunsDryRunResult, c7 as planCustomerDbQuery } from './client-Buv1_ktG.mjs';
-import { b as BundledPlayFileSuccess } from './index-3WOfyVhW.mjs';
+import { T as ToolExecuteResult, B as BasicToolExecuteResult, i as PlayDataset, A as AsyncPlayRunRef$1, j as PlayAuthoringColumnMap, k as PlayAuthoringColumnResolver, l as PlayAuthoringRuntimeContext, m as PlayAuthoringConditionalStepResolver, n as PlayAuthoringCsvInput, o as PlayAuthoringCsvOptions, p as PlayAuthoringDatasetBuilder, q as PlayAuthoringDatasetColumnDefinition, r as PlayAuthoringDatasetColumnRunInput, s as PlayAuthoringReferenceLike, t as PlayReturnObject$1, u as PlayAuthoringDefineConfig, v as PlayAuthoringDefinedPlay, w as PlayAuthoringFetchOptions, x as PlayAuthoringFileInput, y as PlayAuthoringAsyncCallOptions, z as PlayAuthoringBindings, C as PlayAuthoringCallExecution, D as PlayAuthoringCallOptions, E as PlayAuthoringFetchResponse, F as PlayAuthoringInputContract, G as PlayRunId$1, H as PlayAuthoringStepProgramStep, I as PlayAuthoringRuntimeStepOptions, J as PlaySqlListenerDeclaration, K as PlaySqlListenerEvent, L as PlaySqlListenerOperation, M as PlaySqlQuery, N as PlayAuthoringStepOptions, O as PlayAuthoringStepProgram, Q as PlayAuthoringStepProgramResolver, R as PlayAuthoringStepResolver, S as PlayToolExecutionRequest, U as PlayAuthoringStepProgramOptions, V as DeeplineError, W as ToolExecutionError, X as ToolExecutionErrorOptions } from './compiler-manifest-BHnXE43X.mjs';
+export { Y as BillingEntitlements, Z as CtxFetchHttpError, _ as DEEPLINE_EXTRACTOR_TARGETS, $ as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, a0 as DeeplineEmailStatusGetterValue, a1 as DeeplineExtractorTarget, a2 as DeeplineGetterValue, a3 as DeeplineGetterValueMap, a4 as JOB_CHANGE_STATUS_VALUES, a5 as JobChangeStatus, a6 as PHONE_STATUS_VALUES, a7 as PhoneStatus, a8 as PlayDatasetInput, a9 as PreviousCell, aa as ProviderTransientError, ab as ProviderTransientErrorCategory, ac as ProviderUnavailableError, ad as ProviderUnavailableReason, ae as ToolExecutionErrorCategory, af as ToolExecutionErrorOrigin, ag as ToolExecutionFailureV1, ah as ToolExecutionNetworkKind, ai as ToolExecutionNetworkScope, aj as ToolExecutionPublicDetails, ak as ToolResultBilling, al as getProviderUnavailableReason, am as isDeeplineExtractorTarget, an as isProviderUnavailable, ao as isProviderWaterfallUnavailableError } from './compiler-manifest-BHnXE43X.mjs';
+import { b as DeeplineClientOptions, B as BillingNamespace, T as ToolDefinition, c as ToolMetadata, E as ExecuteToolRawOptions, d as ExecutionRecovery, e as ExecutionByKeyResult, f as PlayListItem, g as PlayDetail, h as PlayRunListItem, i as PlayRevisionSummary, j as PublishPlayVersionResult, C as ClearPlayHistoryResult, k as PlayStatus, l as StopPlayRunResult, a as DeeplineClient, R as ResolvedConfig } from './client-6rEB46Lv.mjs';
+export { m as BillingCreditPool, n as BillingInvoiceEntry, o as BillingInvoicesResult, p as BillingPaymentMethodSummary, q as BillingQuoteRequest, r as BillingQuoteResult, s as BillingRecentUsageEntry, t as BillingSubscriptionCancelResult, u as BillingSubscriptionStatus, v as BillingTopUpReceipt, w as BillingTopUpResult, x as BillingUsageEvent, y as BillingUsageOptions, z as BillingUsageResult, A as ChildRunSummary, F as ClearPlayHistoryRequest, G as CreateNotificationGroupInput, H as CreateNotificationGroupResult, I as CustomerDbQueryOptions, J as CustomerDbQueryPlan, K as CustomerDbQueryResult, L as DEEPLINE_TOOL_CATEGORIES, M as DbNamespace, N as DeeplineToolCategory, O as IngestionStorageRepairResult, Q as LegacyMonitorStatusFilter, U as LiveEventEnvelope, V as MONITOR_JOB_PHASES, W as MONITOR_JOB_RECONCILIATION_STATES, X as MONITOR_JOB_STATES, Y as MonitorBatchNamespace, Z as MonitorCheckResult, _ as MonitorDefinition, $ as MonitorDeleteResult, a0 as MonitorDependents, a1 as MonitorDeployResult, a2 as MonitorDetail, a3 as MonitorFleetDeactivateOptions, a4 as MonitorFleetGetOptions, a5 as MonitorFleetReactivateOptions, a6 as MonitorFleetResult, a7 as MonitorFleetStatus, a8 as MonitorFleetSyncOptions, a9 as MonitorFleetWaitOptions, aa as MonitorFleetsNamespace, ab as MonitorJobDeployOptions, ac as MonitorJobLogsOptions, ad as MonitorJobPhase, ae as MonitorJobReconciliationState, af as MonitorJobResult, ag as MonitorJobState, ah as MonitorJobWaitOptions, ai as MonitorJobsNamespace, aj as MonitorListEntry, ak as MonitorPayload, al as MonitorReactivateResult, am as MonitorSpec, an as MonitorState, ao as MonitorStateFilter, ap as MonitorUpdateChangeSummary, aq as MonitorUpdateResult, ar as MonitorsAccessStatus, as as MonitorsAvailableOptions, at as MonitorsAvailableResult, au as MonitorsListOptions, av as MonitorsListResult, aw as MonitorsNamespace, ax as NormalizedRunEventQuery, ay as PlayActivityObservation, az as PlayActivityState, aA as PlayActivityTarget, aB as PlayCostEstimate, aC as PlayCronTriggerConfig, aD as PlayDescriptionOptions, aE as PlayLiveEvent, aF as PlayPath, aG as PlayRunActionPackage, aH as PlayRunActivityProjection, aI as PlayRunDatasetActions, aJ as PlayRunPackage, aK as PlayRunResult, aL as PlayRunRowHistoryOptions, aM as PlayRunStart, aN as PlaySettings, aO as PlaySettingsPatch, aP as PlaySettingsPathsPage, aQ as PlaySettingsResult, aR as PlaySheetRow, aS as PlaySheetRowsResult, aT as PlayTriggerConfigUpdate, aU as PlayTriggerConfigUpdateResult, aV as PlayTriggerConfigView, aW as PlayWebhookAuthConfig, aX as PlayWebhookTriggerConfig, aY as PlaysActivityResponse, aZ as PlaysListOptions, a_ as PlaysListPage, a$ as PublishPlayVersionRequest, b0 as RerunOptions, b1 as RerunPlayRunResult, b2 as RunChildrenPage, b3 as RunEventCountResult, b4 as RunEventField, b5 as RunEventFieldDescriptor, b6 as RunEventFieldOperators, b7 as RunEventFieldsResult, b8 as RunEventGroupValue, b9 as RunEventMeasure, ba as RunEventQueryCriteria, bb as RunEventQueryEvent, bc as RunEventQueryInputError, bd as RunEventQueryOptions, be as RunEventQueryPage, bf as RunEventQueryRetention, bg as RunEventScalar, bh as RunEventSummaryOptions, bi as RunEventSummaryResult, bj as RunEventWhere, bk as RunLifecycleStatus, bl as RunToolReceiptResult, bm as RunToolReceiptsResponse, bn as RunsChildrenOptions, bo as RunsEventPayload, bp as RunsEventSearchEntry, bq as RunsEventSearchOptions, br as RunsEventSearchResult, bs as RunsEventsCountResult, bt as RunsEventsCriteria, bu as RunsEventsFieldsOptions, bv as RunsEventsListOptions, bw as RunsEventsListResult, bx as RunsEventsNamespace, by as RunsEventsSummaryOptions, bz as RunsEventsSummaryResult, bA as RunsHistoryItem, bB as RunsHistoryOptions, bC as RunsHistoryPage, bD as RunsListOptions, bE as RunsListPage, bF as RunsLogCriteria, bG as RunsLogsCountResult, bH as RunsLogsNamespace, bI as RunsLogsOptions, bJ as RunsLogsQueryOptions, bK as RunsLogsQueryResult, bL as RunsLogsResult, bM as RunsLogsSummaryOptions, bN as RunsLogsSummaryResult, bO as RunsNamespace, bP as RunsTailOptions, bQ as RunsWatchOptions, bR as SearchOptions, bS as SearchResult, bT as SearchResultItem, S as SearchType, bU as StartPlayRunRequest, bV as StopAllCandidate, bW as StopAllPlayRunsDryRunResult, bX as StopAllPlayRunsResult, bY as StopAllPlayRunsStopResult, bZ as StopAllRunsOptions, b_ as ToolExecution, b$ as ToolRequestCondition, c0 as ToolRequestWarningRule, c1 as ToolSearchOptions, c2 as ToolSearchResult, c3 as WorkspaceCreateResult, c4 as WorkspacesNamespace, c5 as defineMonitor, c6 as isStopAllPlayRunsDryRunResult, c7 as planCustomerDbQuery } from './client-6rEB46Lv.mjs';
+import { b as BundledPlayFileSuccess } from './index-Da_Y8z5e.mjs';
 export { BatchMonitorInput, MonitorInputIssue, MonitorSpec as MonitorInputSpec, lintMonitorBatchInput, lintMonitorSpecTemplate, renderMonitorSpecTemplate } from './monitor-input-contract.mjs';
 export { AdmittedMonitorFleetAuthoringContract, MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG, MONITOR_FLEET_AUTHORING_CONTRACT_EDITION, MONITOR_FLEET_DOCUMENTATION, MONITOR_FLEET_FRONTIER_MAX_ROWS, MONITOR_FLEET_MAX_MEMBERS, MonitorFleetAuthoringContractEdition, MonitorFleetAuthoringContractResult, MonitorFleetColumn, MonitorFleetContractIssue, MonitorFleetDefinition, MonitorFleetExpression, MonitorFleetTemplate, admitMonitorFleetAuthoringContract, defineMonitorFleet, fleetColumn, fleetKey, lintMonitorFleetInput, validateMonitorFleetDefinition } from './monitor-fleet-contract.mjs';
 import '@sinclair/typebox';
@@ -26,8 +26,8 @@ type PlayFetchResponse = PlayAuthoringFetchResponse;
  * A play can be triggered three ways, declared as the third argument to
  * {@link definePlay}:
  * - `webhook` — an inbound HTTP call (with optional legacy HMAC or Standard
- *   Webhooks signature verification);
- * - `cron` — a schedule; or
+ *   Webhooks signature verification).
+ * - `cron` — a schedule.
  * - `sqlListeners` — a **monitor**: the play runs whenever a monitor writes a new
  *   row to its output stream. This is how you build a play "on top of" a monitor
  *   (e.g. run enrichment every time a watched company posts a new job). Each
@@ -558,8 +558,8 @@ declare class DeeplineContext {
      * Run a named or prebuilt play and wait for its output.
      *
      * This is the high-level SDK equivalent of `ctx.play(name).runSync(input)`.
-     * Inside a play runtime, prefer the in-play `ctx.runPlay(key, playRef, input,
-     * options)` form so the child run is checkpointed under a stable key.
+     * Inside a Play, prefer `ctx.runPlay(key, playRef, input, options)`.
+     * The runtime checkpoints the child run under a stable key.
      *
      * @param playOrRef - Play name or prebuilt/reference object.
      * @param input - JSON input passed to the play.
@@ -610,7 +610,10 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
 /**
  * Define a play — a composable TypeScript workflow for the Deepline platform.
  *
- * The returned value is both a callable function, invoked by the Deepline runtime with a runtime context, and a named play handle carrying `.run()`, `.versions()`, `.get()` and `.publish()` for remote lifecycle management. Plays are the primary abstraction for repeatable data pipelines and execute durably, with automatic retries and timeouts.
+ * The returned value is both a callable function and a named Play handle.
+ * The Deepline runtime calls the function with a runtime context.
+ * The handle provides `.run()`, `.versions()`, `.get()`, and `.publish()` for remote lifecycle operations.
+ * Plays define repeatable data pipelines. The runtime executes them durably with automatic retries and timeouts.
  *
  * @typeParam TInput - The input type accepted by the play
  * @typeParam TOutput - The return type of the play