deepline 0.3.409 → 0.3.411

package/dist/cli/{chunk-PBZYY7VZ.mjs → chunk-UAEVKAUR.mjs}

@@ -3,8 +3,10 @@ import {
   RAW_V2_TOOL_RESPONSE_CONTRACT,
   legacyRawFromToolResponseRawV2,
   providerMetaFromToolResponseRawV2
-} from "./chunk-6IKARAYD.mjs";
+} from "./chunk-L2VKAASU.mjs";
 import {
+  CLI_PLAY_RUN_START_STREAM_PATH,
+  CliPlayAdmissionUnsupportedError,
   PLAY_RUN_START_STREAM_PATH,
   decodePlayRunPublicStatus,
   isPlayRunPackage,
@@ -13,27 +15,29 @@ import {
   preparePlayRunAdmission,
   stagePlayFiles,
   startPlayRun
-} from "./chunk-JI2B4RZP.mjs";
+} from "./chunk-KCC3FKIW.mjs";
 import {
   describePlayDetail,
   describePlayListItem
 } from "./chunk-EIMG75BT.mjs";
 import {
+  ATOMIC_TOOL_EXECUTE_SUPPORTED_HEADER,
   COORDINATOR_INTERNAL_TOKEN_HEADER,
   HttpClient,
   RETAINED_PIPELINE_RECEIVERS_HEADER,
   RUNTIME_ENVIRONMENT_TOKEN_HEADER,
+  SDK_API_MAJOR,
   resolveConfig
-} from "./chunk-2PRO2JTX.mjs";
+} from "./chunk-E52TKKVI.mjs";
 import {
   CustomerDbQueryOutcomeUnknownError
-} from "./chunk-YHPYUZZX.mjs";
+} from "./chunk-MAMVGOSC.mjs";
 import {
   DeeplineError,
   TOOL_EXECUTION_ERROR_SCHEMA_HEADER,
   TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
   ToolExecutionError
-} from "./chunk-NXGCO4JB.mjs";
+} from "./chunk-E4IXDAZI.mjs";
 
 // src/pagination.ts
 async function* iterateCursorPages(fetchPage) {
@@ -77,7 +81,7 @@ function requireBillingIdempotencyKey(value) {
 }
 
 // src/db/query.ts
-function planCustomerDbQuery(input) {
+function planCustomerDbQuery(input, maxRetries = 3) {
   if (typeof input.sql !== "string" || !input.sql.trim())
     throw new DeeplineError("sql must not be empty.", 400, "INVALID_SQL");
   if (input.operationKey !== void 0 && typeof input.operationKey !== "string")
@@ -118,13 +122,13 @@ function planCustomerDbQuery(input) {
       recovery: operationKey === void 0 ? "unkeyed_unknown_outcome" : "original_operation_key"
     },
     transport: {
-      maxRetries: 0,
-      urlFailover: "disabled"
+      maxRetries: operationKey === void 0 ? 0 : maxRetries,
+      urlFailover: operationKey === void 0 ? "disabled" : "loopback_only"
     }
   };
 }
-async function queryCustomerDatabase(http, input) {
-  const plan = planCustomerDbQuery(input);
+async function queryCustomerDatabase(http, input, maxRetries) {
+  const plan = planCustomerDbQuery(input, maxRetries);
   let result;
   try {
     result = await http.post(
@@ -189,6 +193,156 @@ function resolveLookupClientTimeoutMs(toolId) {
   return lookupClientTimeouts.get(toolId.trim().toLowerCase());
 }
 
+// ../play-runtime/execute-server-timing.ts
+var EXECUTE_SERVER_TIMING_STAGES = [
+  "auth",
+  "rate_limit",
+  "catalog",
+  // Local preparation accumulates compilation/hooks/pricing inside catalog
+  // and executor loading before the final provider permit. Do not add it to
+  // catalog or total. Credential selection excludes charge admission.
+  "credential_plan",
+  "provider_prepare",
+  "charge_open",
+  // Charge admission substages. `charge_open` keeps its original meaning — the
+  // TOTAL of all charge-admission work — so an existing reader is unchanged and
+  // these four explain work inside it. The authorization action adapter splits
+  // its wall into snapshot, remaining action time and application retry gaps.
+  // Absent stages are unobserved, not confident zero durations.
+  // - `charge_eligibility`    canonical wallet and cap authorization snapshot
+  // - `charge_cap_preflight`  legacy standalone cap work (zero in current path)
+  // - `charge_open_mutation`  remaining action wall, including transport and
+  //                           failed attempts; legacy name, not mutation CPU
+  // - `charge_retry_wait`     elapsed gaps before application RPC retries;
+  //                           native Convex logs attribute internal OCC retries
+  "charge_eligibility",
+  "charge_cap_preflight",
+  "charge_open_mutation",
+  "charge_retry_wait",
+  // Billing completion slices explain the full stage, including transport.
+  // Handoff headers/body are nested within billing_handoff, not additive.
+  "billing_settle",
+  "billing_price",
+  "billing_precision",
+  "billing_caps",
+  "billing_catalog",
+  "billing_witness",
+  "billing_handoff",
+  "billing_handoff_rpc",
+  "billing_handoff_headers",
+  "billing_handoff_after_headers",
+  // Process-wide activity over the RPC interval, including concurrent work.
+  // These overlap the wall clocks above; they are not request-attributed CPU.
+  "billing_handoff_process_cpu",
+  "billing_handoff_event_loop_active",
+  "billing_handoff_event_loop_idle",
+  "fixture_load",
+  "execute",
+  "identity",
+  "usage_schedule",
+  // Managed AI inference slices: `ai_prepare` includes request preparation and
+  // contains `ai_billing_authorize`; `ai_provider_work_start` is the durable
+  // pre-call transition; `ai_gateway_first_output` is the time to the first
+  // model-output part (excluding SDK control chunks); and
+  // `ai_gateway_stream_wall` is the end-to-end SDK stream
+  // collection wall. Stream wall includes awaited finish callbacks, so evidence
+  // persistence and settlement overlap it. First-output and stream wall both
+  // include Gateway/network/upstream time; neither claims provider-internal
+  // model time.
+  "ai_prepare",
+  "ai_billing_authorize",
+  "ai_provider_work_start",
+  "ai_gateway_first_output",
+  "ai_gateway_stream_wall",
+  "ai_generation_evidence_persist",
+  "ai_billing_settlement",
+  "ai_output_canonicalization",
+  "ai_result_persist",
+  // Provider HTTP slices are only nonzero for calls that take this path:
+  // admission; `provider_fetch_headers` until response headers arrive (or
+  // `provider_fetch_error_wait` for a rejected fetch); retry backoff; body
+  // read, JSON parse, result transform and output normalization are separate.
+  "provider_admission",
+  "provider_fetch_headers",
+  "provider_fetch_error_wait",
+  "provider_retry_wait",
+  "provider_body_read",
+  "provider_json_parse",
+  "provider_result_transform",
+  "provider_output_normalization",
+  "total",
+  // The execution gateway preserves these disjoint stages beside the app
+  // handler's stages. They are deliberately part of this small, additive
+  // response diagnostic contract: a long sandbox-to-headers wall is otherwise
+  // incorrectly reduced to "network" after the app handler reports quickly.
+  "auth_launch",
+  "auth_verify",
+  "body_parse",
+  "dispatch_pool",
+  "dispatch_callback",
+  // The execution relay measures its own upstream fetch. `upstream_headers`
+  // contains the app handler's `total`; subtracting those two clocks leaves
+  // only the Vercel/platform-or-transit boundary, never a made-up provider
+  // latency. `upstream_body` follows headers while the relay buffers the
+  // bounded response before it returns to the runner.
+  "upstream_headers",
+  "upstream_body"
+];
+var PUBLIC_EXECUTE_SERVER_TIMING_STAGES = [
+  // Route total includes lazy execution-module loading. The handler's
+  // public_total keeps its existing meaning so older readers remain valid.
+  "public_load",
+  "public_route",
+  // Core and recovery initialization overlap authentication. Their wall is
+  // included in public_total; these stages are not additive.
+  "public_core_load",
+  "public_recovery_load",
+  "public_auth",
+  "public_claim",
+  "public_claim_headers",
+  "public_claim_after_headers",
+  "public_core",
+  "public_prepare",
+  "public_r2",
+  "public_complete",
+  "public_complete_headers",
+  "public_complete_after_headers",
+  "public_total"
+];
+var ALL_EXECUTE_SERVER_TIMING_STAGES = /* @__PURE__ */ (() => [
+  ...EXECUTE_SERVER_TIMING_STAGES,
+  ...PUBLIC_EXECUTE_SERVER_TIMING_STAGES
+])();
+function parseExecuteServerTiming(header) {
+  if (typeof header !== "string" || !header.trim()) return null;
+  const durations = /* @__PURE__ */ new Map();
+  for (const rawEntry of header.split(",")) {
+    const parts = rawEntry.split(";");
+    const name = parts[0]?.trim().toLowerCase();
+    if (!name) continue;
+    for (const parameter of parts.slice(1)) {
+      const separator = parameter.indexOf("=");
+      if (separator < 0) continue;
+      const key = parameter.slice(0, separator).trim().toLowerCase();
+      if (key !== "dur") continue;
+      const value = parameter.slice(separator + 1).trim().replace(/^"|"$/g, "");
+      const parsed = value === "" ? Number.NaN : Number(value);
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        durations.set(name, parsed);
+      }
+    }
+  }
+  const timing = Object.fromEntries(
+    ALL_EXECUTE_SERVER_TIMING_STAGES.map((stage) => [
+      stage,
+      durations.get(stage) ?? null
+    ])
+  );
+  return ALL_EXECUTE_SERVER_TIMING_STAGES.some(
+    (stage) => timing[stage] !== null
+  ) ? timing : null;
+}
+
 // ../integration-contracts/theirstack/execution-policy.ts
 var THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS = 135e3;
 var THEIRSTACK_SLOW_JOB_SEARCH_CLIENT_TIMEOUT_MS = 6e4 + THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS + 15e3;
@@ -430,13 +584,6 @@ var ToolCalls = class {
       inputSnapshot,
       this.configuredRequestTimeoutMs
     );
-    if (idempotencyKey !== void 0) {
-      await this.lookupExecutionByKey(
-        idempotencyKey,
-        timeoutMs,
-        options?.cliInvocationId
-      );
-    }
     const isApifySync = toolId.trim().toLowerCase() === "apify_run_actor_sync";
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: RAW_V2_EXECUTE_RESPONSE_CONTRACT,
@@ -463,38 +610,91 @@ var ToolCalls = class {
       if (recovery === "running" || recovery === "outcome_unknown") return;
       const state = isRecord(body) ? body.status : null;
       const terminal = state === "completed" || state === "failed" || state === "cancelled" ? state : state === "canceled" ? "cancelled" : failure ? "failed" : null;
-      if (terminal)
-        options?.onResponseReceived?.({
+      if (!terminal || !options?.onResponseReceived) return;
+      const reportObservationFailure = () => console.error("[tools.execute] response observation failed");
+      try {
+        const notification = options.onResponseReceived({
           receivedAtMs: lastResponse.receivedAtMs,
           httpStatus: lastResponse.httpStatus,
           state: terminal
         });
+        void Promise.resolve(notification).catch(reportObservationFailure);
+      } catch {
+        reportObservationFailure();
+      }
     };
-    const request = async (requestTimeoutMs) => {
-      lastResponse = null;
-      try {
-        return await this.http.post(
-          `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
-          {
-            payload: inputSnapshot,
-            ...metadataSnapshot ? { metadata: metadataSnapshot } : {}
-          },
-          headers,
-          {
-            timeout: requestTimeoutMs,
-            maxRetries: idempotencyKey ? 0 : options?.maxRetries ?? 0,
-            retryApiErrors: options?.retryApiErrors === true,
-            exactUrlOnly: true,
-            toolId,
-            idempotencyKey,
-            onResponse: () => {
-              lastResponse = null;
-            },
-            onResponseBody: (observation) => {
-              lastResponse = observation;
+    const legacyEndpoint = `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`;
+    let useLegacyEndpoint = idempotencyKey === void 0;
+    const atomicToolOnly = options?.atomicToolOnly === true;
+    const dispatchRequest = async (requestTimeoutMs) => {
+      let recoverySupported = false;
+      let atomicToolsSupported = false;
+      const post = () => this.http.post(
+        atomicToolOnly ? `/api/v2/tools/${encodeURIComponent(toolId)}/execute` : useLegacyEndpoint ? legacyEndpoint : `/api/v2/executions/by-key/${encodeURIComponent(idempotencyKey)}?tool_id=${encodeURIComponent(toolId)}`,
+        {
+          payload: inputSnapshot,
+          ...metadataSnapshot ? { metadata: metadataSnapshot } : {}
+        },
+        headers,
+        {
+          timeout: requestTimeoutMs,
+          maxRetries: idempotencyKey ? 0 : options?.maxRetries ?? 0,
+          ...atomicToolOnly && !idempotencyKey && options?.maxRetries === void 0 ? { executePolicyMaxRetries: 2 } : {},
+          retryApiErrors: atomicToolOnly || options?.retryApiErrors === true,
+          retryFromExecutePolicy: atomicToolOnly,
+          exactUrlOnly: true,
+          toolId,
+          idempotencyKey,
+          onResponse: (response2) => {
+            lastResponse = null;
+            atomicToolsSupported = response2.headers.get(ATOMIC_TOOL_EXECUTE_SUPPORTED_HEADER) === "true";
+            recoverySupported = response2.headers.get("X-Deepline-Idempotency-Supported") === "true";
+            if (options?.onServerTiming) {
+              try {
+                const notification = options.onServerTiming(
+                  parseExecuteServerTiming(
+                    response2.headers.get("server-timing")
+                  )
+                );
+                void Promise.resolve(notification).catch(() => void 0);
+              } catch {
+              }
             }
+          },
+          onResponseBody: (observation) => {
+            lastResponse = observation;
+          }
+        }
+      );
+      try {
+        return await post();
+      } catch (error) {
+        if (atomicToolOnly) {
+          if (!atomicToolsSupported && !recoverySupported && !(error instanceof ToolExecutionError) && error instanceof DeeplineError && (error.statusCode === 404 || error.statusCode === 405)) {
+            throw new DeeplineError(
+              "This server does not support atomic tool execution.",
+              error.statusCode,
+              "ATOMIC_TOOL_EXECUTE_UNSUPPORTED"
+            );
           }
+          throw error;
+        }
+        if (useLegacyEndpoint || recoverySupported || !(error instanceof DeeplineError) || error.statusCode !== 404 && error.statusCode !== 405)
+          throw error;
+        lastResponse = null;
+        await this.lookupExecutionByKey(
+          idempotencyKey,
+          requestTimeoutMs,
+          options?.cliInvocationId
         );
+        useLegacyEndpoint = true;
+        return post();
+      }
+    };
+    const request = async (requestTimeoutMs) => {
+      lastResponse = null;
+      try {
+        return await dispatchRequest(requestTimeoutMs);
       } catch (error) {
         observeTerminal({ error });
         throw error;
@@ -639,6 +839,309 @@ var ToolCalls = class {
   }
 };
 
+// ../play-runtime/runtime-environment.ts
+var PLAY_RUNTIME_ENVIRONMENTS = ["preview"];
+var PLAY_RUNTIME_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]{0,30}$/;
+var PLAY_RUNTIME_SANDBOX_PLACEMENT_POLICY_PATTERN = /^[a-z][a-z0-9_]*@[1-9][0-9]*$/;
+function normalizePlayRuntimeNamespace(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return PLAY_RUNTIME_NAMESPACE_PATTERN.test(normalized) ? normalized : null;
+}
+function normalizePlayRuntimeSandboxPlacementPolicy(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return PLAY_RUNTIME_SANDBOX_PLACEMENT_POLICY_PATTERN.test(normalized) ? normalized : null;
+}
+function normalizePlayRuntimeSelection(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value;
+  if (Object.keys(record).some(
+    (key) => key !== "environment" && key !== "namespace" && key !== "backend" && key !== "sandboxPlacementPolicy"
+  ) || record.environment !== "preview") {
+    return null;
+  }
+  const namespace = normalizePlayRuntimeNamespace(record.namespace);
+  if (!namespace) return null;
+  const sandboxPlacementPolicy = record.sandboxPlacementPolicy === void 0 ? void 0 : normalizePlayRuntimeSandboxPlacementPolicy(
+    record.sandboxPlacementPolicy
+  );
+  if (record.sandboxPlacementPolicy !== void 0 && sandboxPlacementPolicy === null) {
+    return null;
+  }
+  if (record.backend !== void 0 && record.backend !== PLAY_RUNTIME_BACKENDS.daytona && record.backend !== PLAY_RUNTIME_BACKENDS.modal) {
+    return null;
+  }
+  return {
+    environment: "preview",
+    namespace,
+    ...record.backend === void 0 ? {} : { backend: record.backend },
+    ...sandboxPlacementPolicy ? { sandboxPlacementPolicy } : {}
+  };
+}
+function normalizePlayRuntimeEnvironment(value) {
+  return typeof value === "string" && PLAY_RUNTIME_ENVIRONMENTS.includes(value) ? value : null;
+}
+
+// src/plays/client.ts
+function normalizePlayRunIntegrationMode(value) {
+  if (value === "live" || value === "eval_stub" || value === "fixture") {
+    return value;
+  }
+  return void 0;
+}
+function resolvePlayRunIntegrationMode(request, env) {
+  return normalizePlayRunIntegrationMode(
+    request.integrationMode ?? env.DEEPLINE_EVAL_INTEGRATION_MODE
+  );
+}
+function resolvePlayRunRuntimeSelection(request, env) {
+  if (request.runtime !== void 0) {
+    const runtime = normalizePlayRuntimeSelection(request.runtime);
+    if (!runtime) {
+      throw new DeeplineError(
+        'runtime must be { environment: "preview", namespace, backend?: "daytona" | "modal", sandboxPlacementPolicy?: "policy_name@1" } with namespace matching ^[a-z][a-z0-9-]{0,30}$.',
+        void 0,
+        "INVALID_RUNTIME_SELECTION"
+      );
+    }
+    return runtime;
+  }
+  const configured = env.DEEPLINE_RUNTIME_ENVIRONMENT?.trim();
+  const configuredNamespace = env.DEEPLINE_RUNTIME_NAMESPACE?.trim();
+  const configuredToken = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  const configuredPlacementPolicy = env.DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY?.trim();
+  if (!configured) {
+    if (configuredNamespace || configuredToken || configuredPlacementPolicy) {
+      const present = [];
+      if (configuredNamespace) present.push("DEEPLINE_RUNTIME_NAMESPACE");
+      if (configuredToken) present.push("DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN");
+      if (configuredPlacementPolicy) {
+        present.push("DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY");
+      }
+      const isPlural = present.length > 1;
+      throw new DeeplineError(
+        [
+          `Incomplete play runtime selection: ${present.join(" and ")} ${isPlural ? "are" : "is"} set but DEEPLINE_RUNTIME_ENVIRONMENT is not.`,
+          "Preview routing requires DEEPLINE_RUNTIME_ENVIRONMENT=preview together with DEEPLINE_RUNTIME_NAMESPACE; the token alone authorizes nothing.",
+          `If you did not export ${isPlural ? "these" : "this"} yourself, ${isPlural ? "they were" : "it was"} most likely auto-loaded from a .env or .env.local in the current directory (bun loads those automatically, and in a git worktree .env.local is usually a symlink to the main checkout).`,
+          `To run against the app-native runtime, clear ${isPlural ? "them" : "it"} for this command: ${present.map((name) => `${name}=`).join(" ")} <your deepline command>`
+        ].join("\n"),
+        void 0,
+        "INVALID_RUNTIME_ENVIRONMENT"
+      );
+    }
+    return void 0;
+  }
+  const environment = normalizePlayRuntimeEnvironment(configured);
+  if (!environment) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_ENVIRONMENT supports only explicit preview selection. Received "${configured}". Omit it to use the app-native runtime.`,
+      void 0,
+      "INVALID_RUNTIME_ENVIRONMENT"
+    );
+  }
+  const namespace = normalizePlayRuntimeNamespace(configuredNamespace);
+  if (!namespace) {
+    throw new DeeplineError(
+      "DEEPLINE_RUNTIME_NAMESPACE is required for preview and must match ^[a-z][a-z0-9-]{0,30}$.",
+      void 0,
+      "INVALID_RUNTIME_NAMESPACE"
+    );
+  }
+  const configuredBackendValue = env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
+  const configuredBackend = configuredBackendValue === "daytona" || configuredBackendValue === "modal" ? configuredBackendValue : void 0;
+  if (configuredBackendValue && !configuredBackend) {
+    throw new DeeplineError(
+      `DEEPLINE_PLAY_RUNNER_BACKEND must be daytona or modal for preview runtime selection. Received "${configuredBackendValue}".`,
+      void 0,
+      "INVALID_RUNTIME_BACKEND"
+    );
+  }
+  if (configuredPlacementPolicy && !normalizePlayRuntimeSandboxPlacementPolicy(configuredPlacementPolicy)) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY must be a versioned placement policy id such as daytona_only@1. Received "${configuredPlacementPolicy}".`,
+      void 0,
+      "INVALID_RUNTIME_SANDBOX_PLACEMENT_POLICY"
+    );
+  }
+  return {
+    environment,
+    namespace,
+    ...configuredBackend ? { backend: configuredBackend } : {},
+    ...configuredPlacementPolicy ? { sandboxPlacementPolicy: configuredPlacementPolicy } : {}
+  };
+}
+function resolveStartPlayRunRequest(request, env) {
+  const integrationMode = resolvePlayRunIntegrationMode(request, env);
+  const testPolicyOverrides = request.testPolicyOverrides ?? parseEnvTestPolicyOverrides(env);
+  const runtime = resolvePlayRunRuntimeSelection(request, env);
+  const resolved = { ...request };
+  delete resolved.integrationMode;
+  delete resolved.runtime;
+  delete resolved.testPolicyOverrides;
+  if (integrationMode) resolved.integrationMode = integrationMode;
+  if (runtime) resolved.runtime = runtime;
+  if (testPolicyOverrides) resolved.testPolicyOverrides = testPolicyOverrides;
+  return { request: resolved, runtime };
+}
+function runtimeSelectionHeaders(runtime, env) {
+  if (!runtime) return void 0;
+  const token = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  if (!token) {
+    throw new DeeplineError(
+      "DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN is required for explicit preview runtime selection.",
+      void 0,
+      "RUNTIME_ENVIRONMENT_TOKEN_REQUIRED"
+    );
+  }
+  const receivers = env.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS?.trim();
+  return {
+    [RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
+    ...receivers ? { [RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}
+  };
+}
+function normalizeTestPolicyOverrides(value, source) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  throw new DeeplineError(
+    `${source} must be a JSON object.`,
+    void 0,
+    "INVALID_TEST_POLICY_OVERRIDES"
+  );
+}
+function parseEnvTestPolicyOverrides(env) {
+  const raw = env.DEEPLINE_TEST_POLICY_OVERRIDES;
+  const trimmed = raw?.trim();
+  if (!trimmed) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : "";
+    throw new DeeplineError(
+      `DEEPLINE_TEST_POLICY_OVERRIDES must be valid JSON.${detail}`,
+      void 0,
+      "INVALID_TEST_POLICY_OVERRIDES"
+    );
+  }
+  return normalizeTestPolicyOverrides(parsed, "DEEPLINE_TEST_POLICY_OVERRIDES");
+}
+function isRecord2(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function normalizePlayStatus(raw) {
+  const runPackage = isPlayRunPackage(raw) ? raw : isPlayRunPackage(raw.package) ? raw.package : null;
+  const packageRun = runPackage?.run;
+  const rawStatus = typeof raw.status === "string" ? raw.status : typeof packageRun?.status === "string" ? packageRun.status : null;
+  const status = decodePlayRunPublicStatus(rawStatus);
+  if (!status) {
+    throw new Error(
+      `Invalid play run lifecycle status in API response: ${JSON.stringify(rawStatus)}.`
+    );
+  }
+  const runId = typeof raw.runId === "string" ? raw.runId : typeof raw.workflowId === "string" ? raw.workflowId : packageRun?.id ?? "";
+  const legacyOverview = runPackage?.overview ?? raw.overview;
+  const runStatus = runPackage?.runStatus ?? raw.runStatus;
+  return {
+    ...raw,
+    runId,
+    ...isRecord2(legacyOverview) ? {
+      overview: legacyOverview
+    } : {},
+    ...isRecord2(runStatus) ? { runStatus } : {},
+    ...runPackage ? {
+      package: runPackage,
+      outputs: runPackage.outputs
+    } : {},
+    status
+  };
+}
+var PlayClient = class {
+  constructor(http, environment = process.env) {
+    this.http = http;
+    this.environment = environment;
+  }
+  async startPlayRun(request, options) {
+    const resolved = resolveStartPlayRunRequest(request, this.environment);
+    const headers = runtimeSelectionHeaders(resolved.runtime, this.environment);
+    return startPlayRun(
+      this.http,
+      resolved.request,
+      options?.cliAdmission ? { ...headers, "X-Deepline-API-Major": String(SDK_API_MAJOR) } : headers,
+      options
+    );
+  }
+  async getPlayStatus(workflowId, options) {
+    const params = new URLSearchParams();
+    if (options?.billing === false) {
+      params.set("billing", "false");
+    }
+    if (options?.full === true) {
+      params.set("full", "true");
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    const response = await this.http.get(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}${query}`
+    );
+    return normalizePlayStatus(response);
+  }
+  async cancelPlay(workflowId) {
+    await this.http.request(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
+      { method: "POST" }
+    );
+  }
+  async stopPlay(workflowId, options) {
+    return this.http.post(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
+      options?.reason ? { reason: options.reason } : {}
+    );
+  }
+  async listPlayRuns(playName) {
+    const encodedName = encodeURIComponent(playName);
+    const response = await this.http.get(
+      `/api/v2/plays/${encodedName}/runs`
+    );
+    return response.runs ?? [];
+  }
+  async getPlay(name, options) {
+    const encodedName = encodeURIComponent(name);
+    const query = options?.source ? `?include=source&revision=${encodeURIComponent(options.source)}` : options?.guidance ? "?include=guidance" : "";
+    return this.http.get(`/api/v2/plays/${encodedName}${query}`);
+  }
+  async clearPlayHistory(name, request = {}) {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post(
+      `/api/v2/plays/${encodedName}/history/clear`,
+      request
+    );
+  }
+  async listPlayVersions(name, options) {
+    const encodedName = encodeURIComponent(name);
+    const suffix = options?.full ? "?full=true" : "";
+    const response = await this.http.get(
+      `/api/v2/plays/${encodedName}/versions${suffix}`
+    );
+    return response.versions ?? [];
+  }
+  async publishPlayVersion(name, request = {}) {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post(
+      `/api/v2/plays/${encodedName}/live`,
+      request
+    );
+  }
+};
+function createPlayClient(options) {
+  const config = resolveConfig(options);
+  return new PlayClient(
+    new HttpClient(config),
+    config.environment ?? process.env
+  );
+}
+
 // ../product-notifications/contract.ts
 var PRODUCT_NOTIFICATION_EVENT_CATALOG = [
   {
@@ -846,6 +1349,9 @@ function stripLeadingTimestamp(line) {
 
 // src/runs/read-errors.ts
 function isTransientPlayRunReadError(error) {
+  if (error instanceof DeeplineError && error.code === "PLAY_START_OUTCOME_UNKNOWN") {
+    return false;
+  }
   if (error instanceof DeeplineError && error.code === "PLAY_STREAM_NETWORK_ABORTED") {
     return true;
   }
@@ -1886,57 +2392,15 @@ var TERMINAL_RESERVE_BYTES = 64 * 1024;
 var encoder = new TextEncoder();
 
 // ../play-runtime/secret-redaction.ts
-var SECRET_REDACTION_PLACEHOLDER = "[REDACTED_SECRET]";
-var BEARER_TOKEN_RE = /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/g;
-var BASIC_CREDENTIAL_RE = /\bBasic\s+[A-Za-z0-9+/]{4,}={0,2}\b/g;
-var JWT_RE = /\b[A-Za-z0-9_-]{8,16384}\.[A-Za-z0-9_-]{1,16384}\.[A-Za-z0-9_-]{8,16384}\b/g;
-var EMAIL_LOCAL_CHAR_RE = /[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]/;
-var EMAIL_DOMAIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?\.[A-Za-z]{2,63}\b/;
-function isEmailLocalPart(value, start, end) {
-  let localStart = start;
-  while (localStart > 0 && EMAIL_LOCAL_CHAR_RE.test(value[localStart - 1])) {
-    localStart -= 1;
-  }
-  let localEnd = end;
-  while (localEnd < value.length && EMAIL_LOCAL_CHAR_RE.test(value[localEnd])) {
-    localEnd += 1;
-  }
-  return localStart < localEnd && localEnd - localStart <= 64 && value[localEnd] === "@" && EMAIL_DOMAIN_RE.test(value.slice(localEnd + 1));
-}
-function redactTokenUnlessEmail(match, offset, source) {
-  return isEmailLocalPart(source, offset, offset + match.length) ? match : SECRET_REDACTION_PLACEHOLDER;
-}
-var PRIVATE_KEY_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g;
 var SENSITIVE_FIELD_NAME = "authorization|cookie|password|(?:client[_-]?)?secret|(?:access|refresh)[_-]?token|(?:x[_-]?)?api[_-]?key|private[_-]?key|token|credentials";
-var COMMON_SECRET_RE = /\b(?:[prs]k_(?:live|test)_|(?:pat|ghp|github_pat)_|xox[baprs]-)[A-Za-z0-9_./+=:-]{12,}\b/gi;
-var GENERIC_PREFIXED_SECRET_RE = /\b(?:key|token|secret|api[_-]?key)_[A-Za-z0-9_./+=:-]{12,}\b/gi;
-var URL_SECRET_VALUE_RE = /\b(?:[spr]k|pat|ghp|github_pat|xox)[A-Za-z0-9_./+=:-]{12,}\b/i;
-var GENERIC_SECRET_ASSIGNMENT_RE = /\b(?:api[_-]?key|token|secret|password)\b\s*[:=]\s*["']?[^"',\s]{12,}["']?/gi;
-var HIGH_ENTROPY_ASSIGNMENT_RE = /\b(?:api[_-]?key|token|secret|password|authorization|(?:access|refresh)[_-]?token)\b\s*[:=]\s*["']?[^"',\s]{16,}["']?/gi;
-var SENSITIVE_URL_PARAM_RE = /[?#&](?:\w*(?:key|token)|secret|password|authorization|credential|signature|sig)(?:=|$)/i;
 var SENSITIVE_FIELD_NAME_RE = new RegExp(
   `(^|[._-])(?:${SENSITIVE_FIELD_NAME})$`,
   "i"
 );
-var SENSITIVE_FIELD_NAME_CACHE_MAX_ENTRIES = 4096;
-var sensitiveFieldNameCache = /* @__PURE__ */ new Map();
-function isSensitiveFieldName(key) {
-  const cached = sensitiveFieldNameCache.get(key);
-  if (cached !== void 0) return cached;
-  const sensitive = SENSITIVE_FIELD_NAME_RE.test(key);
-  if (sensitiveFieldNameCache.size >= SENSITIVE_FIELD_NAME_CACHE_MAX_ENTRIES) {
-    sensitiveFieldNameCache.clear();
-  }
-  sensitiveFieldNameCache.set(key, sensitive);
-  return sensitive;
-}
 var SERIALIZED_SECRET_FIELD_RE = new RegExp(
   `"(${SENSITIVE_FIELD_NAME})"\\s*:\\s*(?:"[^"\\\\]*"|\\{[^{}]*\\})`,
   "gi"
 );
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 var REDACTION_TRIGGER_RE = new RegExp(
   [
     // Sensitive field names, in object keys and in `name=`/`"name":` text.
@@ -1971,147 +2435,6 @@ var REDACTION_TRIGGER_RE = new RegExp(
   ].join("|"),
   "i"
 );
-function mightContainRedactableSecret(value) {
-  return REDACTION_TRIGGER_RE.test(value);
-}
-function redactSecretLikeString(value) {
-  if (!mightContainRedactableSecret(value)) return value;
-  const serializedRedacted = value.replace(
-    SERIALIZED_SECRET_FIELD_RE,
-    `"$1":"${SECRET_REDACTION_PLACEHOLDER}"`
-  );
-  const trimmed = serializedRedacted.trim();
-  if (/^https?:\/\/\S+$/i.test(trimmed)) {
-    if (/^https?:\/\/[^/?#@]+@/i.test(trimmed) || SENSITIVE_URL_PARAM_RE.test(trimmed)) {
-      return SECRET_REDACTION_PLACEHOLDER;
-    }
-    if (!URL_SECRET_VALUE_RE.test(serializedRedacted)) {
-      return serializedRedacted;
-    }
-  }
-  return serializedRedacted.replace(PRIVATE_KEY_RE, SECRET_REDACTION_PLACEHOLDER).replace(BEARER_TOKEN_RE, `Bearer ${SECRET_REDACTION_PLACEHOLDER}`).replace(BASIC_CREDENTIAL_RE, `Basic ${SECRET_REDACTION_PLACEHOLDER}`).replace(JWT_RE, redactTokenUnlessEmail).replace(COMMON_SECRET_RE, redactTokenUnlessEmail).replace(GENERIC_PREFIXED_SECRET_RE, redactTokenUnlessEmail).replace(GENERIC_SECRET_ASSIGNMENT_RE, SECRET_REDACTION_PLACEHOLDER).replace(HIGH_ENTROPY_ASSIGNMENT_RE, (match) => {
-    const separator = match.includes("=") ? "=" : ":";
-    const [key] = match.split(separator, 1);
-    return `${key.trim()}${separator}${SECRET_REDACTION_PLACEHOLDER}`;
-  });
-}
-function createSecretRedactionContext(initialValues = []) {
-  const exactSecrets = /* @__PURE__ */ new Set();
-  const exactSecretMatchers = /* @__PURE__ */ new Map();
-  function register(value) {
-    if (value.length > 0) exactSecrets.add(value);
-  }
-  function matchersForSecret(secret) {
-    const cached = exactSecretMatchers.get(secret);
-    if (cached) return cached;
-    const literals = [secret];
-    try {
-      const encoded = encodeURIComponent(secret);
-      if (encoded !== secret) literals.push(encoded);
-    } catch {
-    }
-    const built = literals.map((literal) => ({
-      literal,
-      matcher: new RegExp(escapeRegExp(literal), "g")
-    }));
-    exactSecretMatchers.set(secret, built);
-    return built;
-  }
-  for (const value of initialValues) register(value);
-  function containsRegisteredSecret(value, {
-    includeEncoded = false,
-    minimumLength = 1
-  } = {}) {
-    for (const secret of exactSecrets) {
-      if (secret.length < minimumLength) continue;
-      if (value.includes(secret)) return true;
-      if (includeEncoded) {
-        try {
-          const encoded = encodeURIComponent(secret);
-          if (encoded !== secret && value.includes(encoded)) return true;
-        } catch {
-        }
-      }
-    }
-    return false;
-  }
-  function matchesRegisteredSecret(value) {
-    return exactSecrets.has(value);
-  }
-  function redactRegisteredSecrets(value) {
-    if (exactSecrets.size === 0) return value;
-    let output = value;
-    for (const secret of exactSecrets) {
-      for (const { literal, matcher } of matchersForSecret(secret)) {
-        if (!output.includes(literal)) continue;
-        matcher.lastIndex = 0;
-        output = output.replace(matcher, SECRET_REDACTION_PLACEHOLDER);
-      }
-    }
-    return output;
-  }
-  function redactString(value) {
-    const output = redactRegisteredSecrets(value);
-    return redactSecretLikeString(output);
-  }
-  function redact(value) {
-    if (typeof value === "string") return redactString(value);
-    if (Array.isArray(value)) {
-      let changed = false;
-      const next = new Array(value.length);
-      for (let index = 0; index < value.length; index += 1) {
-        const entry = value[index];
-        const redacted = redact(entry);
-        next[index] = redacted;
-        if (redacted !== entry) changed = true;
-      }
-      return changed ? next : value;
-    }
-    if (value && typeof value === "object") {
-      const prototype = Object.getPrototypeOf(value);
-      let changed = prototype !== Object.prototype && prototype !== null;
-      const source = value;
-      const keys = Object.keys(source);
-      const redactedValues = new Array(keys.length);
-      for (let index = 0; index < keys.length; index += 1) {
-        const key = keys[index];
-        const entry = source[key];
-        const redacted = isSensitiveFieldName(key) ? SECRET_REDACTION_PLACEHOLDER : redact(entry);
-        redactedValues[index] = redacted;
-        if (redacted !== entry) changed = true;
-      }
-      if (!changed) return value;
-      return Object.fromEntries(
-        keys.map((key, index) => [key, redactedValues[index]])
-      );
-    }
-    return value;
-  }
-  function redactKnownSecrets(value) {
-    if (typeof value === "string") return redactRegisteredSecrets(value);
-    if (Array.isArray(value)) {
-      return value.map((entry) => redactKnownSecrets(entry));
-    }
-    if (value && typeof value === "object") {
-      return Object.fromEntries(
-        Object.entries(value).map(([key, entry]) => [
-          key,
-          redactKnownSecrets(entry)
-        ])
-      );
-    }
-    return value;
-  }
-  return {
-    register,
-    containsRegisteredSecret,
-    matchesRegisteredSecret,
-    redactRegisteredSecrets,
-    redactString,
-    redactKnownSecrets,
-    redact
-  };
-}
 
 // ../play-runtime/output-size-limits.ts
 var TERMINAL_RUN_RESULT_MAX_BYTES = 6 * 1024 * 1024;
@@ -2127,9 +2450,6 @@ var RUNTIME_RECEIPT_WRITER_TARGET_BATCH_BYTES = 8 * 1024 * 1024;
 var RUNNER_POST_TERMINAL_DIAGNOSTIC_MAX_BYTES = 64 * 1024;
 var JSON_SIZE_LIMIT_REACHED = Symbol("JSON_SIZE_LIMIT_REACHED");
 
-// ../play-runtime/ledger-safe-payload.ts
-var ledgerIngressRedactor = createSecretRedactionContext();
-
 // ../play-runtime/docflow-node-io.ts
 var utf8Encoder = new TextEncoder();
 var PLAY_DATASET_BRAND = Symbol.for("deepline.play.dataset");
@@ -2550,6 +2870,8 @@ function diffPlayRunStreamEvents(input) {
 
 // src/runs/watch-polling.ts
 var RUN_WATCH_POLL_INTERVAL_MS = 2e3;
+var RUN_WATCH_STARTUP_POLL_INTERVAL_MS = 500;
+var RUN_WATCH_STARTUP_WINDOW_MS = 6e3;
 function waitForNextPoll(ms, signal) {
   if (signal?.aborted) {
     return Promise.resolve(false);
@@ -2576,7 +2898,16 @@ function readSnapshotResponse(response, runId) {
   ) || typeof snapshot.totalLogCount !== "number" || !Array.isArray(snapshot.nodeStates)) {
     throw new Error(`Run watch returned an invalid snapshot for ${runId}.`);
   }
-  return { runId, snapshot };
+  if (record.terminalStatus !== void 0 && (!record.terminalStatus || typeof record.terminalStatus !== "object" || Array.isArray(record.terminalStatus) || !isTerminalPlayRunLiveStatus(snapshot.status))) {
+    throw new Error(
+      `Run watch returned an invalid terminal status for ${runId}.`
+    );
+  }
+  return {
+    runId,
+    snapshot,
+    ...record.terminalStatus !== void 0 ? { terminalStatus: record.terminalStatus } : {}
+  };
 }
 async function backfillRotatedLogTail(input) {
   if (!input.previous.runSignature || input.snapshot.logsUnavailable) {
@@ -2613,25 +2944,70 @@ async function backfillRotatedLogTail(input) {
 }
 async function* watchRunEvents(options) {
   const { http, runId, signal } = options;
-  const path = `/api/v2/runs/${encodeURIComponent(runId)}?watchSnapshot=true`;
+  const params = new URLSearchParams({ watchSnapshot: "true" });
+  if (options.deferLogs) params.set("deferLogs", "true");
+  if (options.omitTerminalLogs) params.set("omitTerminalLogs", "true");
+  if (options.terminalStatus) {
+    params.set(
+      "terminalStatus",
+      options.terminalStatus.full ? "full" : "compact"
+    );
+    if (options.terminalStatus.billing === false)
+      params.set("billing", "false");
+    if (options.terminalStatus.runStatus)
+      params.set("terminalRunStatus", "true");
+  }
+  const path = `/api/v2/runs/${encodeURIComponent(runId)}?${params}`;
   const streamId = `play-run-watch:${runId}`;
-  const pollIntervalMs = options.pollIntervalMs ?? RUN_WATCH_POLL_INTERVAL_MS;
+  const watchStartedAt = Date.now();
   let previous = EMPTY_PLAY_RUN_STREAM_DIFF_STATE;
   let consecutiveFailures = 0;
   let outageNoticeSent = false;
+  let pollCount = 0;
   while (!signal?.aborted) {
     const pollStartedAt = Date.now();
+    const poll = ++pollCount;
+    const pollIntervalMs = options.pollIntervalMs ?? (pollStartedAt - watchStartedAt < RUN_WATCH_STARTUP_WINDOW_MS ? RUN_WATCH_STARTUP_POLL_INTERVAL_MS : RUN_WATCH_POLL_INTERVAL_MS);
     let snapshot;
+    let terminalStatus;
+    let responseStatus;
+    let serverTiming;
+    let pollReported = false;
+    const reportPoll = () => {
+      if (!options.onPoll || pollReported) return;
+      pollReported = true;
+      try {
+        options.onPoll({
+          poll,
+          durationMs: Date.now() - pollStartedAt,
+          ...responseStatus !== void 0 ? { status: responseStatus } : {},
+          ...serverTiming ? { serverTiming } : {}
+        });
+      } catch {
+      }
+    };
     try {
-      const response = await http.get(path, { signal });
-      snapshot = await backfillRotatedLogTail({
+      const response = await http.get(path, {
+        signal,
+        ...options.onPoll ? {
+          onResponse: (response2) => {
+            responseStatus = response2.status;
+            serverTiming = response2.headers.get("server-timing") ?? void 0;
+          }
+        } : {}
+      });
+      const parsed = readSnapshotResponse(response, runId);
+      terminalStatus = parsed.terminalStatus;
+      snapshot = options.deferLogs ? parsed.snapshot : await backfillRotatedLogTail({
         http,
         runId,
-        snapshot: readSnapshotResponse(response, runId).snapshot,
+        snapshot: parsed.snapshot,
         previous,
         signal
       });
+      reportPoll();
     } catch (error) {
+      reportPoll();
       if (signal?.aborted) {
         return;
       }
@@ -2647,7 +3023,7 @@ async function* watchRunEvents(options) {
           reason
         });
         options.onNotice?.(
-          `[watch] run snapshot request failed; retrying every ${pollIntervalMs / 1e3}s (${reason})`
+          `[watch] run snapshot request failed; retrying snapshot polling (${reason})`
         );
         outageNoticeSent = true;
       }
@@ -2665,6 +3041,9 @@ async function* watchRunEvents(options) {
       outageNoticeSent = false;
     }
     consecutiveFailures = 0;
+    if (terminalStatus) {
+      await options.terminalStatus?.onStatus(terminalStatus, snapshot.status);
+    }
     const diff = diffPlayRunStreamEvents({
       streamId,
       snapshot,
@@ -2687,51 +3066,34 @@ async function* watchRunEvents(options) {
   }
 }
 
-// ../play-runtime/runtime-environment.ts
-var PLAY_RUNTIME_ENVIRONMENTS = ["preview"];
-var PLAY_RUNTIME_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]{0,30}$/;
-var PLAY_RUNTIME_SANDBOX_PLACEMENT_POLICY_PATTERN = /^[a-z][a-z0-9_]*@[1-9][0-9]*$/;
-function normalizePlayRuntimeNamespace(value) {
-  if (typeof value !== "string") return null;
-  const normalized = value.trim();
-  return PLAY_RUNTIME_NAMESPACE_PATTERN.test(normalized) ? normalized : null;
-}
-function normalizePlayRuntimeSandboxPlacementPolicy(value) {
-  if (typeof value !== "string") return null;
-  const normalized = value.trim();
-  return PLAY_RUNTIME_SANDBOX_PLACEMENT_POLICY_PATTERN.test(normalized) ? normalized : null;
-}
-function normalizePlayRuntimeSelection(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const record = value;
-  if (Object.keys(record).some(
-    (key) => key !== "environment" && key !== "namespace" && key !== "backend" && key !== "sandboxPlacementPolicy"
-  ) || record.environment !== "preview") {
-    return null;
-  }
-  const namespace = normalizePlayRuntimeNamespace(record.namespace);
-  if (!namespace) return null;
-  const sandboxPlacementPolicy = record.sandboxPlacementPolicy === void 0 ? void 0 : normalizePlayRuntimeSandboxPlacementPolicy(
-    record.sandboxPlacementPolicy
+// src/client.ts
+function invalidToolDiscoveryResponse() {
+  return new DeeplineError(
+    "The server returned an invalid tool discovery response.",
+    502,
+    "INVALID_TOOL_DISCOVERY_RESPONSE"
   );
-  if (record.sandboxPlacementPolicy !== void 0 && sandboxPlacementPolicy === null) {
-    return null;
-  }
-  if (record.backend !== void 0 && record.backend !== PLAY_RUNTIME_BACKENDS.daytona && record.backend !== PLAY_RUNTIME_BACKENDS.modal) {
-    return null;
-  }
-  return {
-    environment: "preview",
-    namespace,
-    ...record.backend === void 0 ? {} : { backend: record.backend },
-    ...sandboxPlacementPolicy ? { sandboxPlacementPolicy } : {}
-  };
 }
-function normalizePlayRuntimeEnvironment(value) {
-  return typeof value === "string" && PLAY_RUNTIME_ENVIRONMENTS.includes(value) ? value : null;
+function readToolCategorySummaries(value) {
+  if (!Array.isArray(value)) throw invalidToolDiscoveryResponse();
+  const seen = /* @__PURE__ */ new Set();
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || !("name" in item) || typeof item.name !== "string" || !item.name.trim() || seen.has(item.name) || !("count" in item) || typeof item.count !== "number" || !Number.isSafeInteger(item.count) || item.count < 0) {
+      throw invalidToolDiscoveryResponse();
+    }
+    seen.add(item.name);
+    return { name: item.name, count: item.count };
+  });
+}
+function summarizeToolCategories(tools) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    for (const category of tool.categories ?? []) {
+      counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+  }
+  return [...counts].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
 }
-
-// src/client.ts
 var MAX_NOTIFICATION_GROUP_CREATE_TARGETS = 50;
 function parseNotificationGroupTarget(value) {
   const normalized = value.trim();
@@ -2776,123 +3138,6 @@ var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 var REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY = 3;
 var REGISTER_PLAY_ARTIFACTS_MAX_BATCH_COUNT = 3;
 var REGISTER_PLAY_ARTIFACTS_MAX_BATCH_BYTES = 25e5;
-function normalizePlayRunIntegrationMode(value) {
-  if (value === "live" || value === "eval_stub" || value === "fixture") {
-    return value;
-  }
-  return void 0;
-}
-function resolvePlayRunIntegrationMode(request, env) {
-  return normalizePlayRunIntegrationMode(
-    request.integrationMode ?? env.DEEPLINE_EVAL_INTEGRATION_MODE
-  );
-}
-function resolvePlayRunRuntimeSelection(request, env) {
-  if (request.runtime !== void 0) {
-    const runtime = normalizePlayRuntimeSelection(request.runtime);
-    if (!runtime) {
-      throw new DeeplineError(
-        'runtime must be { environment: "preview", namespace, backend?: "daytona" | "modal", sandboxPlacementPolicy?: "policy_name@1" } with namespace matching ^[a-z][a-z0-9-]{0,30}$.',
-        void 0,
-        "INVALID_RUNTIME_SELECTION"
-      );
-    }
-    return runtime;
-  }
-  const configured = env.DEEPLINE_RUNTIME_ENVIRONMENT?.trim();
-  const configuredNamespace = env.DEEPLINE_RUNTIME_NAMESPACE?.trim();
-  const configuredToken = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
-  const configuredPlacementPolicy = env.DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY?.trim();
-  if (!configured) {
-    if (configuredNamespace || configuredToken || configuredPlacementPolicy) {
-      const present = [];
-      if (configuredNamespace) present.push("DEEPLINE_RUNTIME_NAMESPACE");
-      if (configuredToken) present.push("DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN");
-      if (configuredPlacementPolicy) {
-        present.push("DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY");
-      }
-      const isPlural = present.length > 1;
-      throw new DeeplineError(
-        [
-          `Incomplete play runtime selection: ${present.join(" and ")} ${isPlural ? "are" : "is"} set but DEEPLINE_RUNTIME_ENVIRONMENT is not.`,
-          "Preview routing requires DEEPLINE_RUNTIME_ENVIRONMENT=preview together with DEEPLINE_RUNTIME_NAMESPACE; the token alone authorizes nothing.",
-          `If you did not export ${isPlural ? "these" : "this"} yourself, ${isPlural ? "they were" : "it was"} most likely auto-loaded from a .env or .env.local in the current directory (bun loads those automatically, and in a git worktree .env.local is usually a symlink to the main checkout).`,
-          `To run against the app-native runtime, clear ${isPlural ? "them" : "it"} for this command: ${present.map((name) => `${name}=`).join(" ")} <your deepline command>`
-        ].join("\n"),
-        void 0,
-        "INVALID_RUNTIME_ENVIRONMENT"
-      );
-    }
-    return void 0;
-  }
-  const environment = normalizePlayRuntimeEnvironment(configured);
-  if (!environment) {
-    throw new DeeplineError(
-      `DEEPLINE_RUNTIME_ENVIRONMENT supports only explicit preview selection. Received "${configured}". Omit it to use the app-native runtime.`,
-      void 0,
-      "INVALID_RUNTIME_ENVIRONMENT"
-    );
-  }
-  const namespace = normalizePlayRuntimeNamespace(configuredNamespace);
-  if (!namespace) {
-    throw new DeeplineError(
-      "DEEPLINE_RUNTIME_NAMESPACE is required for preview and must match ^[a-z][a-z0-9-]{0,30}$.",
-      void 0,
-      "INVALID_RUNTIME_NAMESPACE"
-    );
-  }
-  const configuredBackendValue = env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
-  const configuredBackend = configuredBackendValue === "daytona" || configuredBackendValue === "modal" ? configuredBackendValue : void 0;
-  if (configuredBackendValue && !configuredBackend) {
-    throw new DeeplineError(
-      `DEEPLINE_PLAY_RUNNER_BACKEND must be daytona or modal for preview runtime selection. Received "${configuredBackendValue}".`,
-      void 0,
-      "INVALID_RUNTIME_BACKEND"
-    );
-  }
-  if (configuredPlacementPolicy && !normalizePlayRuntimeSandboxPlacementPolicy(configuredPlacementPolicy)) {
-    throw new DeeplineError(
-      `DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY must be a versioned placement policy id such as daytona_only@1. Received "${configuredPlacementPolicy}".`,
-      void 0,
-      "INVALID_RUNTIME_SANDBOX_PLACEMENT_POLICY"
-    );
-  }
-  return {
-    environment,
-    namespace,
-    ...configuredBackend ? { backend: configuredBackend } : {},
-    ...configuredPlacementPolicy ? { sandboxPlacementPolicy: configuredPlacementPolicy } : {}
-  };
-}
-function resolveStartPlayRunRequest(request, env) {
-  const integrationMode = resolvePlayRunIntegrationMode(request, env);
-  const testPolicyOverrides = request.testPolicyOverrides ?? parseEnvTestPolicyOverrides(env);
-  const runtime = resolvePlayRunRuntimeSelection(request, env);
-  const resolved = { ...request };
-  delete resolved.integrationMode;
-  delete resolved.runtime;
-  delete resolved.testPolicyOverrides;
-  if (integrationMode) resolved.integrationMode = integrationMode;
-  if (runtime) resolved.runtime = runtime;
-  if (testPolicyOverrides) resolved.testPolicyOverrides = testPolicyOverrides;
-  return { request: resolved, runtime };
-}
-function runtimeSelectionHeaders(runtime, env) {
-  if (!runtime) return void 0;
-  const token = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
-  if (!token) {
-    throw new DeeplineError(
-      "DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN is required for explicit preview runtime selection.",
-      void 0,
-      "RUNTIME_ENVIRONMENT_TOKEN_REQUIRED"
-    );
-  }
-  const receivers = env.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS?.trim();
-  return {
-    [RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
-    ...receivers ? { [RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}
-  };
-}
 function isolatedCiRuntimeEventReadHeaders(env) {
   const schema = env.DEEPLINE_RUNTIME_SCHEDULER_SCHEMA?.trim();
   if (env.DEEPLINE_SYNTHETIC_RUN?.trim() !== "1" || !schema || !/^fly_absurd_pr_\d+_\d+(?:_\d+)?$/.test(schema)) {
@@ -2908,33 +3153,6 @@ function isolatedCiRuntimeEventReadHeaders(env) {
   }
   return { [COORDINATOR_INTERNAL_TOKEN_HEADER]: token };
 }
-function normalizeTestPolicyOverrides(value, source) {
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    return value;
-  }
-  throw new DeeplineError(
-    `${source} must be a JSON object.`,
-    void 0,
-    "INVALID_TEST_POLICY_OVERRIDES"
-  );
-}
-function parseEnvTestPolicyOverrides(env) {
-  const raw = env.DEEPLINE_TEST_POLICY_OVERRIDES;
-  const trimmed = raw?.trim();
-  if (!trimmed) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch (error) {
-    const detail = error instanceof Error ? ` ${error.message}` : "";
-    throw new DeeplineError(
-      `DEEPLINE_TEST_POLICY_OVERRIDES must be valid JSON.${detail}`,
-      void 0,
-      "INVALID_TEST_POLICY_OVERRIDES"
-    );
-  }
-  return normalizeTestPolicyOverrides(parsed, "DEEPLINE_TEST_POLICY_OVERRIDES");
-}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -3042,7 +3260,7 @@ var MONITOR_JOB_RECONCILIATION_STATES = [
   "partial",
   "mismatched"
 ];
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isPrebuiltPlayDescription(play) {
@@ -3053,33 +3271,6 @@ function preferPrebuiltPlayDescriptions(plays) {
     (left, right) => Number(right.play.pinned) - Number(left.play.pinned) || Number(isPrebuiltPlayDescription(right.play)) - Number(isPrebuiltPlayDescription(left.play)) || left.index - right.index
   ).map(({ play }) => play);
 }
-function normalizePlayStatus(raw) {
-  const runPackage = isPlayRunPackage(raw) ? raw : isPlayRunPackage(raw.package) ? raw.package : null;
-  const packageRun = runPackage?.run;
-  const rawStatus = typeof raw.status === "string" ? raw.status : typeof packageRun?.status === "string" ? packageRun.status : null;
-  const status = decodePlayRunPublicStatus(rawStatus);
-  if (!status) {
-    throw new Error(
-      `Invalid play run lifecycle status in API response: ${JSON.stringify(rawStatus)}.`
-    );
-  }
-  const runId = typeof raw.runId === "string" ? raw.runId : typeof raw.workflowId === "string" ? raw.workflowId : packageRun?.id ?? "";
-  const legacyOverview = runPackage?.overview ?? raw.overview;
-  const runStatus = runPackage?.runStatus ?? raw.runStatus;
-  return {
-    ...raw,
-    runId,
-    ...isRecord2(legacyOverview) ? {
-      overview: legacyOverview
-    } : {},
-    ...isRecord2(runStatus) ? { runStatus } : {},
-    ...runPackage ? {
-      package: runPackage,
-      outputs: runPackage.outputs
-    } : {},
-    status
-  };
-}
 function readStringArray(value) {
   return Array.isArray(value) ? value.filter((line) => typeof line === "string") : [];
 }
@@ -3125,7 +3316,7 @@ function updatePlayLiveStatusState(state, event) {
   }
   const runId = typeof payload.runId === "string" && payload.runId ? payload.runId : isPlayRunPackage(payload) ? payload.run.id : state.runId;
   const status = playLiveRunStatus(event) ?? state.status;
-  const progressPayload = isRecord2(payload.progress) ? payload.progress : {};
+  const progressPayload = isRecord3(payload.progress) ? payload.progress : {};
   if (event.type === "play.run.final_status" && state.logs.length === 0 && state.lastLogSeq === 0) {
     const payloadLogs = readStringArray(payload.logs);
     const progressLogs = readStringArray(progressPayload.logs);
@@ -3175,6 +3366,7 @@ function playRunResultFromStatus(status, startedAt, fallbackRunId) {
 var DeeplineClient = class _DeeplineClient {
   http;
   toolCalls;
+  playClient;
   config;
   environment;
   /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
@@ -3200,6 +3392,7 @@ var DeeplineClient = class _DeeplineClient {
     this.config = resolveConfig(options);
     this.environment = this.config.environment ?? process.env;
     this.http = new HttpClient(this.config);
+    this.playClient = new PlayClient(this.http, this.environment);
     this.toolCalls = new ToolCalls(
       this.http,
       this.config.timeout,
@@ -3240,7 +3433,7 @@ var DeeplineClient = class _DeeplineClient {
     };
     this.db = {
       query: (input) => this.queryDb(input),
-      planQuery: (input) => planCustomerDbQuery(input)
+      planQuery: (input) => planCustomerDbQuery(input, this.config.maxRetries)
     };
     this.billing = {
       quote: (input) => this.http.post("/api/v2/billing/quote", input),
@@ -3421,6 +3614,45 @@ var DeeplineClient = class _DeeplineClient {
     );
     return res.tools;
   }
+  /** List category counts without downloading tool definitions. */
+  async listToolCategories() {
+    const response = await this.http.get(
+      "/api/v2/tools?view=categories&compact=true"
+    );
+    if (response.view === "categories") {
+      return readToolCategorySummaries(response.categories);
+    }
+    if (response.view === void 0 && Array.isArray(response.tools)) {
+      return summarizeToolCategories(response.tools);
+    }
+    throw invalidToolDiscoveryResponse();
+  }
+  /** Read one complete category and its live category counts in one request. */
+  async listToolsInCategory(category, options) {
+    const normalizedCategory = category.trim();
+    if (!normalizedCategory || category.includes(",")) {
+      throw new DeeplineError(
+        "Provide one non-empty tool category.",
+        400,
+        "INVALID_TOOL_CATEGORY"
+      );
+    }
+    const params = new URLSearchParams({
+      view: "category",
+      categories: normalizedCategory,
+      compact: options?.compact === true ? "true" : "false"
+    });
+    const response = await this.http.get(
+      `/api/v2/tools?${params}`
+    );
+    if (!Array.isArray(response.tools) || response.view !== "category" && response.view !== void 0) {
+      throw invalidToolDiscoveryResponse();
+    }
+    return {
+      tools: response.tools,
+      categories: response.view === "category" ? readToolCategorySummaries(response.categories) : await this.listToolCategories()
+    };
+  }
   /** List discoverable providers without requiring a local plugin catalog. */
   async listProviders(options) {
     const suffix = options?.changed ? "?changed=true" : "";
@@ -3559,7 +3791,7 @@ var DeeplineClient = class _DeeplineClient {
     return this.executeTool(toolId, input, options);
   }
   async queryDb(input) {
-    return queryCustomerDatabase(this.http, input);
+    return queryCustomerDatabase(this.http, input, this.config.maxRetries);
   }
   /**
    * Run a bounded SQL query against the current mutable customer database.
@@ -3625,13 +3857,7 @@ var DeeplineClient = class _DeeplineClient {
    * ```
    */
   async startPlayRun(request, options) {
-    const resolved = resolveStartPlayRunRequest(request, this.environment);
-    return startPlayRun(
-      this.http,
-      resolved.request,
-      runtimeSelectionHeaders(resolved.runtime, this.environment),
-      options?.onSubmission
-    );
+    return this.playClient.startPlayRun(request, options);
   }
   /**
    * Prepare a tenant-scoped start intent without executing it. Its stream
@@ -3665,17 +3891,22 @@ var DeeplineClient = class _DeeplineClient {
           );
         }
         submitted = true;
-        for await (const event of http.streamSse(
-          PLAY_RUN_START_STREAM_PATH,
-          {
+        const streamPath = options?.cliAdmission ? CLI_PLAY_RUN_START_STREAM_PATH : PLAY_RUN_START_STREAM_PATH;
+        try {
+          for await (const event of http.streamSse(streamPath, {
             method: "POST",
             body: JSON.parse(bodyJson),
             headers,
             signal: streamOptions?.signal,
             exactUrlOnly: true
+          })) {
+            if (event.scope === "play") yield event;
+          }
+        } catch (error) {
+          if (options?.cliAdmission && error instanceof DeeplineError && (error.statusCode === 404 || error.statusCode === 405)) {
+            throw new CliPlayAdmissionUnsupportedError(error.statusCode);
           }
-        )) {
-          if (event.scope === "play") yield event;
+          throw error;
         }
       }
     };
@@ -3991,27 +4222,35 @@ var DeeplineClient = class _DeeplineClient {
    * ```
    */
   async getPlayStatus(workflowId, options) {
-    const params = new URLSearchParams();
-    if (options?.billing === false) {
-      params.set("billing", "false");
-    }
-    if (options?.full === true) {
-      params.set("full", "true");
-    }
-    const query = params.size > 0 ? `?${params.toString()}` : "";
-    const response = await this.http.get(
-      `/api/v2/runs/${encodeURIComponent(workflowId)}${query}`
-    );
-    return normalizePlayStatus(response);
+    return this.playClient.getPlayStatus(workflowId, options);
   }
-  /** Poll authenticated run snapshots every two seconds and emit changed events. */
+  /**
+   * Poll authenticated snapshots and emit changes; `deferLogs` delays terminal logs; `omitTerminalLogs` skips them.
+   */
   async *watchRunEvents(workflowId, options) {
     for await (const event of watchRunEvents({
       http: this.http,
       runId: workflowId,
       signal: options?.signal,
       onNotice: options?.onNotice,
-      onRetry: options?.onRetry
+      onRetry: options?.onRetry,
+      deferLogs: options?.deferLogs,
+      omitTerminalLogs: options?.omitTerminalLogs,
+      onPoll: options?.onPoll,
+      ...options?.terminalStatus ? {
+        terminalStatus: {
+          ...options.terminalStatus,
+          onStatus: async (raw, expectedStatus) => {
+            const status = normalizePlayStatus(raw);
+            if (status.runId !== workflowId || status.status !== expectedStatus) {
+              throw new Error(
+                `Run watch returned a mismatched terminal status for ${workflowId}.`
+              );
+            }
+            await options.terminalStatus?.onStatus(status);
+          }
+        }
+      } : {}
     })) {
       yield event;
     }
@@ -4051,10 +4290,17 @@ var DeeplineClient = class _DeeplineClient {
   /** Poll snapshots to terminal status and return the durable package. */
   async watchRunToTerminal(runId, options) {
     let terminalObserved = false;
+    let terminalStatus = null;
     for await (const event of this.watchRunEvents(runId, {
       signal: options?.signal,
       onNotice: options?.onNotice,
-      onRetry: options?.onRetry ?? options?.onReconnect
+      onRetry: options?.onRetry ?? options?.onReconnect,
+      terminalStatus: {
+        runStatus: true,
+        onStatus: (status) => {
+          terminalStatus = status;
+        }
+      }
     })) {
       options?.onEvent?.(event);
       if (isTerminalPlayRunLifecycleStatus(playLiveRunStatus(event))) {
@@ -4064,7 +4310,7 @@ var DeeplineClient = class _DeeplineClient {
     if (options?.signal?.aborted) {
       throw new DeeplineError("Run watch aborted.", void 0, "ABORTED");
     }
-    const refreshed = await this.getRunStatus(runId);
+    const refreshed = terminalStatus ?? await this.getRunStatus(runId);
     if (terminalObserved || isTerminalPlayRunLifecycleStatus(refreshed.status)) {
       return refreshed;
     }
@@ -4101,10 +4347,7 @@ var DeeplineClient = class _DeeplineClient {
    * ```
    */
   async cancelPlay(workflowId) {
-    await this.http.request(
-      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
-      { method: "POST" }
-    );
+    return this.playClient.cancelPlay(workflowId);
   }
   /**
    * Stop a running play execution, including open HITL waits.
@@ -4113,10 +4356,7 @@ var DeeplineClient = class _DeeplineClient {
    * @param options.reason - Optional audit/debug reason
    */
   async stopPlay(workflowId, options) {
-    return this.http.post(
-      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
-      options?.reason ? { reason: options.reason } : {}
-    );
+    return this.playClient.stopPlay(workflowId, options);
   }
   /**
    * List recent runs for a named play.
@@ -4136,11 +4376,7 @@ var DeeplineClient = class _DeeplineClient {
    * ```
    */
   async listPlayRuns(playName) {
-    const encodedName = encodeURIComponent(playName);
-    const response = await this.http.get(
-      `/api/v2/plays/${encodedName}/runs`
-    );
-    return response.runs ?? [];
+    return this.playClient.listPlayRuns(playName);
   }
   // ---------------------------------------------------------------------------
   // Legacy workflows (double-shipped). Thin pass-throughs over the live cloud
@@ -5281,9 +5517,7 @@ var DeeplineClient = class _DeeplineClient {
    * ```
    */
   async getPlay(name, options) {
-    const encodedName = encodeURIComponent(name);
-    const query = options?.source ? `?include=source&revision=${encodeURIComponent(options.source)}` : options?.guidance ? "?include=guidance" : "";
-    return this.http.get(`/api/v2/plays/${encodedName}${query}`);
+    return this.playClient.getPlay(name, options);
   }
   /** Read one trigger inventory page without loading run histories. */
   async listPlayTriggerInventory(options) {
@@ -5329,11 +5563,7 @@ var DeeplineClient = class _DeeplineClient {
    * the play definition or revisions.
    */
   async clearPlayHistory(name, request = {}) {
-    const encodedName = encodeURIComponent(name);
-    return this.http.post(
-      `/api/v2/plays/${encodedName}/history/clear`,
-      request
-    );
+    return this.playClient.clearPlayHistory(name, request);
   }
   /**
    * List saved versions for a named play.
@@ -5345,12 +5575,7 @@ var DeeplineClient = class _DeeplineClient {
    * @returns Version list (newest first)
    */
   async listPlayVersions(name, options) {
-    const encodedName = encodeURIComponent(name);
-    const suffix = options?.full ? "?full=true" : "";
-    const response = await this.http.get(
-      `/api/v2/plays/${encodedName}/versions${suffix}`
-    );
-    return response.versions ?? [];
+    return this.playClient.listPlayVersions(name, options);
   }
   /**
    * Make a play revision live.
@@ -5371,11 +5596,7 @@ var DeeplineClient = class _DeeplineClient {
    * ```
    */
   async publishPlayVersion(name, request = {}) {
-    const encodedName = encodeURIComponent(name);
-    return this.http.post(
-      `/api/v2/plays/${encodedName}/live`,
-      request
-    );
+    return this.playClient.publishPlayVersion(name, request);
   }
   /**
    * Move an org-owned play to Trash. This disables its active triggers while
@@ -6496,6 +6717,8 @@ export {
   requireBillingIdempotencyKey,
   planCustomerDbQuery,
   validateExecutionIdempotencyKey,
+  normalizePlayStatus,
+  createPlayClient,
   PRODUCT_NOTIFICATION_EVENT_CATALOG,
   resolveLegacySlackNotification,
   RUN_EVENT_SEARCH_KIND_VALUES,