deepline 0.1.265 → 0.1.267

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

@@ -1,4 +1,4 @@
-import { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
+import { SDK_API_CONTRACT, SDK_API_MAJOR, SDK_VERSION } from './version.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -87,6 +87,7 @@ function compatibilityCacheKey(
     baseUrl: baseUrl.replace(/\/$/, ''),
     version: SDK_VERSION,
     apiContract: SDK_API_CONTRACT,
+    apiMajor: SDK_API_MAJOR,
     command: command?.trim() || null,
     skillsVersion: skillsVersion ?? null,
   });
@@ -186,6 +187,7 @@ export async function checkSdkCompatibility(
       headers: {
         'User-Agent': `deepline-ts-sdk/${SDK_VERSION}`,
         'X-Deepline-SDK-Version': SDK_VERSION,
+        'X-Deepline-API-Major': String(SDK_API_MAJOR),
         'X-Deepline-API-Contract': SDK_API_CONTRACT,
       },
       signal: controller.signal,

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

@@ -12,9 +12,10 @@
  *
  * Edit THIS file by hand only for deliberate release decisions:
  *   - minor/major version bumps (set `version`),
- *   - `apiContract` cutovers (see `docs/sdk-runtime-compatibility.md`),
+ *   - API-major cutovers (set `contracts.api.currentMajor`; leave `version` to the
+ *     publish-time patch selector),
  *   - support-window moves (`minimumSupported` / `deprecatedBelow`).
- * The automation never touches `apiContract`, `minimumSupported`, or
+ * The automation never touches API compatibility policy, `minimumSupported`, or
  * `deprecatedBelow`.
  *
  * Everything else derives from these values:
@@ -35,6 +36,37 @@
 
 export type SdkReleaseChannel = 'latest' | 'next' | 'beta';
 
+/**
+ * The named public protocols. These are intentionally independent:
+ *
+ * - `api` is the HTTP SDK/CLI protocol. It is additive within a major.
+ * - `playArtifact` is the immutable client-bundled Play payload ABI.
+ * - `release` controls promotion/publishing; it is not a client protocol.
+ *
+ * Do not use an SDK package version or a date string as an artifact ABI.
+ */
+export type DeeplineContractPolicy = {
+  api: {
+    name: 'sdk-http-api';
+    currentMajor: number;
+    supportedMajors: readonly number[];
+    /** Transitional value for installed SDKs that only send the old header. */
+    legacyWireIds: readonly string[];
+  };
+  playArtifact: {
+    name: 'play-artifact-runtime';
+    currentVersion: number;
+    supportedVersions: readonly number[];
+  };
+  release: {
+    name: 'production-sdk-release';
+    /** npm may publish only from the active, healthy Production SHA. */
+    publishFrom: 'latest-successful-production-deployment';
+    /** A newer merge cancels an in-flight decision; reconciliation picks the last healthy SHA. */
+    coalesce: 'latest-healthy';
+  };
+};
+
 export type SdkSupportPolicy = {
   /**
    * Anything strictly below this returns `status: "unsupported"` from
@@ -57,6 +89,8 @@ export type SdkSupportPolicy = {
     minimumSupported: string;
     reason: string;
   }>;
+  /** Previously published wire contracts that remain supported. */
+  compatibleApiContracts?: readonly string[];
   /**
    * Published package versions that must keep working for direct SDK tool
    * callers. CI installs each package from npm and exercises `tools.get` and
@@ -77,12 +111,8 @@ export type SdkRelease = {
    * publish time (auto-bump); edit by hand only for minor/major releases.
    */
   version: string;
-  /**
-   * SDK/API contract identifier. Bump on incompatible protocol or schema
-   * changes between the installed SDK/CLI and the Deepline backend.
-   * See `docs/sdk-runtime-compatibility.md`.
-   */
-  apiContract: string;
+  /** Named compatibility policies. This is the only authored contract policy. */
+  contracts: DeeplineContractPolicy;
   /** Public support policy reported by `/api/v2/sdk/compat`. */
   supportPolicy: SdkSupportPolicy;
 };
@@ -125,8 +155,31 @@ export const SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: '0.1.265',
-  apiContract: '2026-07-admin-cli-local-cutover',
+  version: '0.1.267',
+  contracts: {
+    api: {
+      name: 'sdk-http-api',
+      // API v2 is append-only. A breaking public request/response change needs
+      // v3 and an explicit v2 support-window decision, never a patch release.
+      currentMajor: 2,
+      supportedMajors: [2],
+      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      legacyWireIds: [
+        '2026-07-admin-cli-local-cutover',
+        '2026-07-native-monitor-launch-hard-cutover',
+      ],
+    },
+    playArtifact: {
+      name: 'play-artifact-runtime',
+      currentVersion: 2,
+      supportedVersions: [1, 2],
+    },
+    release: {
+      name: 'production-sdk-release',
+      publishFrom: 'latest-successful-production-deployment',
+      coalesce: 'latest-healthy',
+    },
+  },
   supportPolicy: {
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.219',

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

@@ -677,6 +677,64 @@ export interface PlayStatus {
   };
   /** Exact ordinary `plays run` command that can rerun a failed execution. */
   rerunCommand?: string;
+  /**
+   * Projected settled-charge billing for the run. Returned by `runs.get`.
+   * `totalCredits`/`providerEvents` describe THIS run only; `rollup` (present
+   * with `--full`) carries the true subtree cost including ctx.runPlay children.
+   * Deepline credits only — provider spend is never exposed.
+   */
+  billing?: RunBillingSummary;
+  /**
+   * True subtree cost in Deepline credits (this run + every descendant run),
+   * mirrored to the top level for convenience. Present only with `--full`.
+   */
+  billingTotalCreditsRollup?: number;
+  /** Deepline credits attributable to descendant runs only. Present with `--full`. */
+  billingChildCredits?: number;
+  /** True when the child-run billing rollup could not be fully resolved. */
+  billingRollupIncomplete?: boolean;
+  /** Durable summaries of ctx.runPlay children, returned by `runs.get --full`. */
+  childRuns?: ChildRunSummary[];
+}
+
+/** One ctx.runPlay child run exposed on the parent's `--full` payload. */
+export interface ChildRunSummary {
+  runId: string;
+  playName?: string | null;
+  status: string;
+  parentRunId?: string | null;
+  rootRunId?: string | null;
+  createdAt?: number | null;
+  startedAt?: number | null;
+  finishedAt?: number | null;
+}
+
+/**
+ * Rolled-up billing for a run subtree, projected from settled Charge Lifecycle
+ * facts. Deepline credits only — never provider spend.
+ */
+export interface RunBillingSummary {
+  runId: string;
+  /** THIS run's own charges (parent-only; excludes descendant runs). */
+  totalCalls: number;
+  totalCredits: number;
+  providerEvents: number;
+  computeEvents: number;
+  /** Subtree rollup including descendant ctx.runPlay runs. Present with `--full`. */
+  rollup?: {
+    totalCreditsRollup: number;
+    childCredits: number;
+    ownCredits: number;
+    totalCallsRollup: number;
+    providerEventsRollup: number;
+    computeEventsRollup: number;
+    childProviderEvents: number;
+    childComputeEvents: number;
+    descendantRunCount: number;
+    rollupComplete: boolean;
+    rollupError?: string;
+  };
+  [key: string]: unknown;
 }
 
 export type LiveEventScope = 'play' | 'agent';

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

@@ -3,4 +3,8 @@
 import { SDK_RELEASE } from './release.js';
 
 export const SDK_VERSION: string = SDK_RELEASE.version;
-export const SDK_API_CONTRACT: string = SDK_RELEASE.apiContract;
+/** Numbered SDK HTTP API major sent by current SDK/CLI clients. */
+export const SDK_API_MAJOR: number = SDK_RELEASE.contracts.api.currentMajor;
+/** @deprecated Transitional wire id for pre-major-header SDKs only. */
+export const SDK_API_CONTRACT: string =
+  SDK_RELEASE.contracts.api.legacyWireIds[0] ?? `api-v${SDK_API_MAJOR}`;

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

@@ -51,6 +51,7 @@ import {
   isRetryableSecretResolutionStatus,
   secretResolutionRetryDecision,
   SECRET_RESOLUTION_MAX_ATTEMPTS,
+  SECRET_RESOLUTION_ATTEMPT_TIMEOUT_MS,
   type SecretResolutionRetryDecision,
 } from './secret-resolution-retry-policy';
 import {
@@ -307,6 +308,16 @@ const TOOL_BATCH_COALESCE_WINDOW_MS = 5;
 const TOOL_RETRY_AFTER_FALLBACK_MS = 1_000;
 const TOOL_RETRY_HEARTBEAT_INTERVAL_MS = 30_000;
 const DEEPLINEAGENT_TOOL_RUNTIME_TIMEOUT_MS = 15 * 60 * 1000;
+// Every runtime-API tool fetch needs a client-side deadline. Without one, a
+// stalled execute request (e.g. a credential-less call whose gateway connection
+// hangs before the fast 403 can return) leaves the row "1 in flight" for minutes
+// until the outer run deadline, violating loud-failure. The integrations execute
+// route caps server work at maxDuration=900s, so this ceiling sits just above it:
+// a healthy server (including the fast INTEGRATION_CREDENTIALS_MISSING 403) always
+// responds first, and only a genuinely stuck socket trips the abort — surfacing as
+// a bounded, repairable transport failure that row-isolation settles per row
+// instead of hanging the whole run.
+const DEFAULT_TOOL_RUNTIME_TIMEOUT_MS = 15 * 60 * 1000 + 30_000;
 const FETCH_TRANSPORT_MAX_ATTEMPTS = 3;
 const FETCH_TRANSPORT_RETRY_DELAY_MS = 100;
 // cloudflared returns this branded HTML when its connection to the local app
@@ -493,13 +504,17 @@ export function resolveToolRuntimeTimeoutMs(
     return Math.max(1, Math.ceil(requestedTimeoutMs));
   }
   const normalized = toolId.trim().toLowerCase();
+  // Long-inference tools keep their explicit 15-minute budget. Every other tool
+  // gets the default ceiling so no runtime-API fetch is ever unbounded — a
+  // missing-credential or otherwise stuck request fails loudly and fast within
+  // the deadline instead of hanging "1 in flight".
   return normalized === 'deeplineagent' ||
     normalized === 'deeplineagent_deeplineagent' ||
     normalized === 'ai_inference' ||
     normalized === 'deeplineagent_ai_inference' ||
     normalized === 'aiinference'
     ? DEEPLINEAGENT_TOOL_RUNTIME_TIMEOUT_MS
-    : undefined;
+    : DEFAULT_TOOL_RUNTIME_TIMEOUT_MS;
 }
 
 function isDeeplineDeveloperTunnelOrigin502(input: {
@@ -1586,6 +1601,10 @@ export class PlayContextImpl {
         try {
           response = await fetch(url, {
             method: 'POST',
+            // Bound the control-plane call so a stalled connection aborts and is
+            // caught below as a transport failure instead of hanging the tool
+            // call "1 in flight" forever.
+            signal: AbortSignal.timeout(SECRET_RESOLUTION_ATTEMPT_TIMEOUT_MS),
             headers: {
               Authorization: `Bearer ${this.#options.executorToken}`,
               'Content-Type': 'application/json',
@@ -5413,13 +5432,13 @@ export class PlayContextImpl {
           this.rowStates.get(idx)?.results.set(fieldName, cellValue);
           const currentCellMeta =
             this.activeMapCellMeta?.get(rowKey)?.[fieldName];
-          const currentCellStatus =
+          const currentCellRecord =
             currentCellMeta &&
             typeof currentCellMeta === 'object' &&
-            !Array.isArray(currentCellMeta) &&
-            'status' in currentCellMeta
-              ? (currentCellMeta as { status?: unknown }).status
+            !Array.isArray(currentCellMeta)
+              ? (currentCellMeta as { status?: unknown; reused?: unknown })
               : null;
+          const currentCellStatus = currentCellRecord?.status ?? null;
           if (currentCellStatus === 'skipped') {
             if (
               shouldPersistMapCellField(fieldName) &&
@@ -5436,13 +5455,25 @@ export class PlayContextImpl {
             }
             continue;
           }
+          // A cell whose underlying durable work was fully satisfied from
+          // content-addressed receipts recorded a `cached`/`reused` cell-meta
+          // marker while the body ran (see resolveRequestsFromReceipt). Emitting
+          // an unconditional `completed` here would clobber that marker to a
+          // non-reused `completed`, so the run's per-column `cached` counter
+          // reads 0 on a full-reuse rerun even though provider spend was 0.
+          // Preserve the reuse signal so `columnStats.cached` reflects real
+          // receipt reuse consistent with the near-zero provider spend.
+          const cellWasReused =
+            currentCellStatus === 'cached' &&
+            currentCellRecord?.reused === true;
           this.emitScopedFieldMetaUpdate({
             rowId: idx,
             key: rowKey,
             tableNamespace: normalizedTableNamespace,
             fieldName,
-            status: 'completed',
-            stage: 'completed',
+            status: cellWasReused ? 'cached' : 'completed',
+            stage: cellWasReused ? 'cached' : 'completed',
+            ...(cellWasReused ? { reused: true } : {}),
             completedAt: Date.now(),
             dataPatch: shouldPersistMapCellField(fieldName)
               ? { [fieldName]: cellValue }

package/dist/bundling-sources/shared_libs/play-runtime/csv-rename.ts

@@ -44,6 +44,29 @@ function sourceAliases(target: string, aliases: string | readonly string[]) {
   return [target, ...(Array.isArray(aliases) ? aliases : [aliases])];
 }
 
+/**
+ * `required` is a HEADER-presence guarantee, not a per-row non-null check.
+ *
+ * A required target is satisfied when at least one of its source aliases exists
+ * as a column in the CSV row (present in the header), regardless of whether this
+ * particular row's cell is blank. Blank cells in a present column are DATA, not a
+ * schema violation: they must flow through to the dataset so `onRowError` (or the
+ * play's own branching) governs them per row, never guillotine the whole run.
+ * Only a column that is entirely absent from the CSV is a `required` violation.
+ */
+function hasAliasColumnPresent(
+  lookup: Map<string, unknown>,
+  target: string,
+  sourceNames: string | readonly string[],
+): boolean {
+  for (const alias of sourceAliases(target, sourceNames)) {
+    if (lookup.has(alias) || lookup.has(normalizeCsvHeader(alias))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export function applyCsvRenameProjection<T extends Record<string, unknown>>(
   rows: readonly T[],
   options?: CsvRenameOptions,
@@ -52,11 +75,26 @@ export function applyCsvRenameProjection<T extends Record<string, unknown>>(
     ...(options?.rename ?? {}),
     ...(options?.columns ?? {}),
   };
+  const required = new Set(options?.required ?? []);
+
   if (Object.keys(aliases).length === 0) {
+    // No rename/alias projection requested. `required` is still a
+    // header-presence guarantee: assert each required column exists in the CSV
+    // (checked against the first row's shape), then pass rows through untouched.
+    // A present-but-blank cell is data, never a `required` violation.
+    if (required.size > 0 && rows.length > 0) {
+      const lookup = buildRowLookup(rows[0]!);
+      for (const target of required) {
+        if (!hasAliasColumnPresent(lookup, target, target)) {
+          throw new Error(
+            `ctx.csv(..., { required }) is missing required column "${target}". ` +
+              `Add a "${target}" column to the CSV header.`,
+          );
+        }
+      }
+    }
     return [...rows];
   }
-
-  const required = new Set(options?.required ?? []);
   return rows.map((row, index) => {
     const lookup = buildRowLookup(row);
     const projectedFields = new Set<string>();
@@ -88,9 +126,17 @@ export function applyCsvRenameProjection<T extends Record<string, unknown>>(
         } else {
           projected[target] = selected;
         }
-      } else if (required.has(target)) {
+      } else if (
+        required.has(target) &&
+        !hasAliasColumnPresent(lookup, target, sourceNames)
+      ) {
+        // The column is entirely absent from the CSV header — a schema/config
+        // error that is identical for every row. A present-but-blank cell is
+        // data and must NOT trip this: it flows through so onRowError can
+        // isolate that row instead of failing the whole run.
         throw new Error(
-          `ctx.csv(..., { rename }) row ${index + 1} is missing required column "${target}".`,
+          `ctx.csv(..., { required }) is missing required column "${target}". ` +
+            `Add a "${target}" column (or one of its aliases) to the CSV header.`,
         );
       }
     }

package/dist/bundling-sources/shared_libs/play-runtime/dataset-lifecycle-log.ts

@@ -0,0 +1,30 @@
+type DatasetLogIdentity = {
+  path: string;
+  tableNamespace: string;
+};
+
+/**
+ * Dataset paths identify runtime state. They are not CLI export selectors: a
+ * returned result field (for example `result.rows`) is the supported export
+ * handle. Keep this distinction explicit in operator logs.
+ */
+export function formatDatasetRegistrationLog(input: {
+  dataset: DatasetLogIdentity;
+  rows: number;
+}): string {
+  if (input.rows === 0) {
+    return `Dataset ${input.dataset.path} registered (0 rows); export unavailable: empty dataset`;
+  }
+  return `Dataset ${input.dataset.path} registered (${input.rows} rows); awaiting terminal persistence`;
+}
+
+export function formatDatasetAvailabilityLog(input: {
+  runId: string;
+  dataset: DatasetLogIdentity;
+  persistedRows: number;
+}): string {
+  if (input.persistedRows === 0) {
+    return `Dataset ${input.dataset.path} available: 0 persisted rows; export unavailable: empty dataset`;
+  }
+  return `Dataset ${input.dataset.path} available: ${input.persistedRows} persisted rows; inspect deepline runs get ${input.runId} --full --json for the verified export action`;
+}

package/dist/bundling-sources/shared_libs/play-runtime/secret-resolution-retry-policy.ts

@@ -1,5 +1,11 @@
 export const SECRET_RESOLUTION_MAX_ATTEMPTS = 3;
 export const SECRET_RESOLUTION_MAX_RETRY_AFTER_MS = 2_000;
+// Per-attempt client deadline for the secret-resolution gateway call. This is an
+// internal control-plane fetch (resolve a named secret), not provider work, so it
+// must return quickly. Without a bound, a stalled connection hangs the tool call
+// "1 in flight" indefinitely; an abort here is caught as a transport failure and
+// retried/failed loudly via secretResolutionRetryDecision.
+export const SECRET_RESOLUTION_ATTEMPT_TIMEOUT_MS = 30_000;
 
 const SECRET_RESOLUTION_RETRY_JITTER_CAPS_MS = [100, 250] as const;