deepline 0.3.47 → 0.3.48

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

@@ -3106,6 +3106,14 @@ export class DeeplineClient {
       signal?: AbortSignal;
       lastEventId?: string;
       mode?: 'cli' | 'ui';
+      /**
+       * A run just accepted by durable scheduler admission can take a short
+       * time to appear in the asynchronous Convex read model. Callers that
+       * received that admission may opt into a bounded retry of the initial
+       * pending response; a normal arbitrary run id still fails loudly by
+       * default.
+       */
+      waitForProjection?: boolean;
     },
   ): AsyncGenerator<PlayLiveEvent> {
     const headers =
@@ -3114,12 +3122,33 @@ export class DeeplineClient {
         : undefined;
     const params = new URLSearchParams();
     params.set('mode', options?.mode ?? 'cli');
-    for await (const event of this.http.streamSse<PlayLiveEvent>(
-      `/api/v2/runs/${encodeURIComponent(workflowId)}/tail?${params.toString()}`,
-      { signal: options?.signal, headers },
-    )) {
-      if (event.scope === 'play') {
-        yield event;
+    const projectionDeadline = Date.now() + 30_000;
+    let projectionAttempt = 0;
+    for (;;) {
+      let sawEvent = false;
+      try {
+        for await (const event of this.http.streamSse<PlayLiveEvent>(
+          `/api/v2/runs/${encodeURIComponent(workflowId)}/tail?${params.toString()}`,
+          { signal: options?.signal, headers },
+        )) {
+          sawEvent = true;
+          if (event.scope === 'play') {
+            yield event;
+          }
+        }
+        return;
+      } catch (error) {
+        const projectionPending =
+          options?.waitForProjection === true &&
+          !sawEvent &&
+          error instanceof DeeplineError &&
+          (error.statusCode === 404 ||
+            (error.statusCode === 202 &&
+              error.code === 'RUN_PROJECTION_PENDING')) &&
+          Date.now() < projectionDeadline;
+        if (!projectionPending) throw error;
+        await sleep(streamReconnectDelayMs(projectionAttempt));
+        projectionAttempt += 1;
       }
     }
   }
@@ -4439,6 +4468,7 @@ export class DeeplineClient {
     for await (const event of this.streamPlayRunEvents(workflowId, {
       mode: 'cli',
       signal: options?.signal,
+      waitForProjection: true,
     })) {
       if (options?.signal?.aborted) {
         await this.cancelPlay(workflowId);

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

@@ -15,6 +15,7 @@ import {
   type ToolExecutionErrorOptions,
   type ToolExecutionNetworkKind,
   type ToolExecutionNetworkScope,
+  type ToolExecutionPublicDetails,
 } from '../../shared_libs/plays/tool-execution-error';
 
 export {
@@ -33,6 +34,7 @@ export {
   type ToolExecutionErrorOptions,
   type ToolExecutionNetworkKind,
   type ToolExecutionNetworkScope,
+  type ToolExecutionPublicDetails,
 } from '../../shared_libs/plays/tool-execution-error';
 
 /**
@@ -145,6 +147,8 @@ export class ToolRateLimitError extends RateLimitError {
   readonly networkKind: ToolExecutionError['networkKind'];
   /** Network boundary that failed, or `null` for non-network failures. */
   readonly networkScope: ToolExecutionError['networkScope'];
+  /** Explicitly allowlisted diagnostics safe for SDK callers. */
+  readonly publicDetails: ToolExecutionError['publicDetails'];
 
   /** Constructed by the SDK after a structured tool HTTP 429. */
   constructor(message: string, options: ToolExecutionErrorOptions) {
@@ -161,6 +165,7 @@ export class ToolRateLimitError extends RateLimitError {
     this.requestId = options.requestId;
     this.networkKind = options.networkKind;
     this.networkScope = options.networkScope;
+    this.publicDetails = options.publicDetails ?? null;
     this.details = options.details;
     brandAsToolExecutionError(this);
     if (isProviderTransientFailure(this)) {

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

@@ -621,7 +621,10 @@ export class HttpClient {
           signal: options?.signal,
         });
 
-        if (!response.ok) {
+        // An SSE endpoint must either establish an event stream or reject the
+        // request. A 202 JSON response is a deliberately retryable admission
+        // state, not an empty, successfully completed stream.
+        if (!response.ok || response.status === 202) {
           const body = await response.text();
           const parsed = parseResponseBody(body);
           if (

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

@@ -145,6 +145,7 @@ export type {
   ToolExecutionErrorOptions,
   ToolExecutionNetworkKind,
   ToolExecutionNetworkScope,
+  ToolExecutionPublicDetails,
 } from './errors.js';
 
 // ——— Config ———

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

@@ -199,7 +199,7 @@ export const SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: '0.3.47',
+  version: '0.3.48',
   updateSummary:
     'Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.',
   packageCapabilities: {

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

@@ -156,6 +156,7 @@ type RuntimeApiRequest =
       action: 'start_run';
       idempotencyKey?: string;
       playName: string;
+      playReference?: string | null;
       runId: string;
       artifactStorageKey?: string | null;
       artifactHash?: string | null;
@@ -172,6 +173,45 @@ type RuntimeApiRequest =
       inputSha256?: string;
       replayedFromRunId?: string | null;
     }
+  | {
+      /** Ordered projection of a Runtime Postgres/Absurd admission. */
+      action: 'project_run_created';
+      idempotencyKey?: string;
+      playName: string;
+      playReference?: string | null;
+      workflowId: string;
+      runId: string;
+      workflowFamilyKey: string;
+      definitionScope?: 'org' | 'system';
+      revisionId?: string | null;
+      artifactStorageKey?: string | null;
+      artifactHash?: string | null;
+      graphHash?: string | null;
+      runtimeBackend?: string | null;
+      schedulerBackend?: string | null;
+      schedulerSchema?: string | null;
+      executionProfile?: string | null;
+      runtimeReleaseId?: string | null;
+      runtimeDeployVersion?: string | null;
+      runtimeCallbackBaseUrl?: string | null;
+      coordinatorUrl?: string | null;
+      coordinatorWorkerName?: string | null;
+      runtimeWorkflowName?: string | null;
+      runtimeHarnessWorkerName?: string | null;
+      maxCreditsPerRun?: number | null;
+      staticPipeline?: unknown;
+      source?: 'published' | 'ad_hoc' | 'draft';
+      triggerSource?: 'webhook' | 'cron' | 'sql_listener' | 'api';
+      inputFileId?: string;
+      inputBytes?: number;
+      inputSha256?: string;
+      replayedFromRunId?: string | null;
+      secretRefs?: unknown[];
+      inputSummary?: Record<string, unknown>;
+      /** Terminal bypass used only when the causal admission projection is
+       * permanently blocked and no queued row can be projected. */
+      admissionFailure?: string;
+    }
   | ({
       action: 'save_results';
     } & RuntimeSaveResults)
@@ -668,7 +708,8 @@ function isRetryableAppRuntimeAction(
     action === 'release_runtime_step_receipt' ||
     action === 'save_results' ||
     action === 'skip_runtime_step_receipt' ||
-    action === 'start_run'
+    action === 'start_run' ||
+    action === 'project_run_created'
   );
 }
 
@@ -1925,6 +1966,7 @@ export async function startRunViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: {
     playName: string;
+    playReference?: string | null;
     runId: string;
     artifactStorageKey?: string | null;
     artifactHash?: string | null;
@@ -1949,6 +1991,24 @@ export async function startRunViaAppRuntime(
   });
 }
 
+/**
+ * Deliver the causally-first `run.created` projection after Runtime Postgres
+ * has atomically admitted the run and its Absurd task. It is safe to retry:
+ * the server preserves any existing queued, running, or terminal run.
+ */
+export async function projectRunCreatedViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: Omit<
+    Extract<RuntimeApiRequest, { action: 'project_run_created' }>,
+    'action'
+  >,
+): Promise<void> {
+  await postAppRuntimeApi<{ ok: true; status: 'queued' }>(context, {
+    action: 'project_run_created',
+    ...input,
+  });
+}
+
 export async function saveResultsViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: RuntimeSaveResults,

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backend.ts

@@ -42,7 +42,15 @@ export type { PlayRunInputPayload };
 export type PlaySchedulerSubmitInput = {
   runId: string;
   playId: string;
+  /** Canonical definition name used by the Convex read-model projector. */
+  definitionName?: string | null;
   playName: string;
+  /** Immutable display/lookup name selected at admission, if distinct. */
+  playReference?: string | null;
+  /** Definition ownership selected at admission; never re-resolve on replay. */
+  definitionScope?: 'org' | 'system' | null;
+  /** Immutable published revision selected at admission. */
+  revisionId?: string | null;
   workflowFamilyKey?: string | null;
   artifactStorageKey: string;
   /** Optional inline artifact for the Node scheduler. */
@@ -52,6 +60,10 @@ export type PlaySchedulerSubmitInput = {
   /** Immutable scheduler/worker/runner ABI snapshot (not a Git SHA). */
   runtimeProtocolVersion?: PlayRuntimeProtocolVersion | null;
   input: PlayRunInputPayload;
+  /** Immutable secret authority selected at admission; never re-resolve on projection. */
+  secretRefs?: unknown[];
+  /** Display-only, size-bounded projection of the admitted input. */
+  inputSummary?: Record<string, unknown>;
   /** Convex metadata for the exact input saved before scheduler submission. */
   inputFileId?: string;
   inputBytes?: number;
@@ -71,6 +83,8 @@ export type PlaySchedulerSubmitInput = {
     storageKey?: string;
     fileName?: string;
     logicalPath?: string;
+    storageKind?: 'r2';
+    contentHash?: string;
     contentType?: string;
     bytes?: number;
   } | null;
@@ -87,6 +101,8 @@ export type PlaySchedulerSubmitInput = {
     logicalPath?: string;
     fileName?: string;
     storageKey: string;
+    storageKind?: 'r2';
+    contentHash?: string;
     contentType?: string;
     bytes?: number;
     inlineText?: string;
@@ -136,6 +152,16 @@ export type PlaySchedulerSubmitInput = {
    */
   queuePriority?: number | null;
   executionProfile?: string | null;
+  /** Concrete Runtime Postgres namespace selected at admission. */
+  schedulerSchema?: string | null;
+  /** Immutable release tuple for the Convex read-model projection. */
+  runtimeReleaseId?: string | null;
+  runtimeCallbackBaseUrl?: string | null;
+  coordinatorWorkerName?: string | null;
+  runtimeWorkflowName?: string | null;
+  runtimeHarnessWorkerName?: string | null;
+  /** Billing admission cap from the immutable contract snapshot. */
+  maxCreditsPerRun?: number | null;
   /** runner backend to use for executing attempts */
   runtimeBackend: string;
   /**

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

@@ -103,6 +103,7 @@ class StructuredToolHttpError extends ToolExecutionError {
       retryAfterMs: input.options.retryAfterMs ?? null,
       networkKind: input.options.networkKind ?? null,
       networkScope: input.options.networkScope ?? null,
+      publicDetails: input.options.publicDetails ?? null,
     });
     this.billing = input.billing;
     this.status = input.status;
@@ -447,6 +448,7 @@ export function normalizeToolHttpErrorMessage(input: {
       (origin === 'provider' && category === 'network'
         ? 'deepline_to_provider'
         : null),
+    publicDetails: hydratedFailure?.publicDetails ?? null,
   };
   const billing = getObjectField(parsed, 'billing');
   if (isInsufficientCreditsBilling(billing)) {

package/dist/bundling-sources/shared_libs/plays/tool-execution-error.ts

@@ -84,6 +84,17 @@ export type ToolExecutionNetworkScope =
   | 'runtime_to_deepline'
   | 'deepline_to_provider';
 
+/**
+ * Bounded, primitive-only diagnostics explicitly approved for customers.
+ * Raw provider bodies, credentials, prompts, stacks, and causes never belong
+ * in this shared API/SDK/Play contract.
+ *
+ * @sdkReference errors 063
+ */
+export type ToolExecutionPublicDetails = Readonly<
+  Record<string, string | number | boolean | null>
+>;
+
 /**
  * Portable version-1 `tool_error` payload.
  *
@@ -120,6 +131,8 @@ export type ToolExecutionFailureV1 = {
   networkKind: ToolExecutionNetworkKind | null;
   /** Network boundary that failed, or `null`. */
   networkScope: ToolExecutionNetworkScope | null;
+  /** Explicitly allowlisted customer diagnostics, when present. */
+  publicDetails?: ToolExecutionPublicDetails | null;
 };
 
 /**
@@ -265,6 +278,8 @@ export class ToolExecutionError extends DeeplineError {
   readonly networkKind: ToolExecutionNetworkKind | null;
   /** Network boundary that failed, or `null` for non-network failures. */
   readonly networkScope: ToolExecutionNetworkScope | null;
+  /** Explicitly allowlisted diagnostics safe for SDK and Play callers. */
+  readonly publicDetails: ToolExecutionPublicDetails | null;
 
   /**
    * Construct a structured tool error.
@@ -290,6 +305,7 @@ export class ToolExecutionError extends DeeplineError {
     this.retryAfterMs = options.retryAfterMs;
     this.networkKind = options.networkKind;
     this.networkScope = options.networkScope;
+    this.publicDetails = options.publicDetails ?? null;
     applyBrand(this, TOOL_EXECUTION_ERROR_BRAND);
     if (isProviderTransientFailure(options)) {
       applyBrand(this, PROVIDER_TRANSIENT_ERROR_BRAND);
@@ -547,6 +563,69 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+const MAX_PUBLIC_DETAIL_ENTRIES = 20;
+const MAX_PUBLIC_DETAIL_KEY_LENGTH = 80;
+const MAX_PUBLIC_DETAIL_STRING_LENGTH = 512;
+const publicDetailsByError = new WeakMap<Error, ToolExecutionPublicDetails>();
+
+/**
+ * Normalizes the one public-detail shape at every transport boundary. Nested
+ * values are rejected to prevent accidental disclosure of provider responses.
+ */
+export function normalizeToolExecutionPublicDetails(
+  value: unknown,
+): ToolExecutionPublicDetails | null {
+  if (!isRecord(value)) return null;
+  const details: Record<string, string | number | boolean | null> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (Object.keys(details).length >= MAX_PUBLIC_DETAIL_ENTRIES) break;
+    if (
+      key.length === 0 ||
+      key.length > MAX_PUBLIC_DETAIL_KEY_LENGTH ||
+      !/^[a-z][a-zA-Z0-9_]*$/.test(key)
+    ) {
+      continue;
+    }
+    if (typeof entry === 'string') {
+      if (entry.length <= MAX_PUBLIC_DETAIL_STRING_LENGTH) details[key] = entry;
+      continue;
+    }
+    if (typeof entry === 'number') {
+      if (Number.isFinite(entry)) details[key] = entry;
+      continue;
+    }
+    if (typeof entry === 'boolean') {
+      details[key] = entry;
+      continue;
+    }
+    if (entry === null) details[key] = null;
+  }
+  return Object.keys(details).length > 0 ? details : null;
+}
+
+/**
+ * Attaches allowlisted details to an in-process error without making them
+ * enumerable. The execute boundary can later serialize them through the
+ * portable `tool_error.publicDetails` field.
+ */
+export function withToolExecutionPublicDetails<T extends Error>(
+  error: T,
+  details: unknown,
+): T {
+  const normalized = normalizeToolExecutionPublicDetails(details);
+  if (normalized) publicDetailsByError.set(error, normalized);
+  return error;
+}
+
+/** Reads details deliberately attached through `withToolExecutionPublicDetails`. */
+export function getToolExecutionPublicDetails(
+  error: unknown,
+): ToolExecutionPublicDetails | null {
+  return error instanceof Error
+    ? (publicDetailsByError.get(error) ?? null)
+    : null;
+}
+
 export function normalizeToolExecutionFailure(
   value: unknown,
 ): ToolExecutionFailureV1 | null {
@@ -565,6 +644,7 @@ export function normalizeToolExecutionFailure(
     operation,
   });
   const category = normalizeToolExecutionCategory(value.category);
+  const publicDetails = normalizeToolExecutionPublicDetails(value.publicDetails);
   const trustworthy =
     origin !== 'unknown' &&
     category !== 'unknown' &&
@@ -583,6 +663,7 @@ export function normalizeToolExecutionFailure(
     retryAfterMs: finiteNonNegativeInteger(value.retryAfterMs),
     networkKind: normalizeNetworkKind(value.networkKind),
     networkScope: normalizeNetworkScope(value.networkScope),
+    ...(publicDetails ? { publicDetails } : {}),
   };
 }
 
@@ -604,6 +685,7 @@ export function serializeToolExecutionFailure(
     retryAfterMs: error.retryAfterMs,
     networkKind: error.networkKind,
     networkScope: error.networkScope,
+    publicDetails: error.publicDetails,
   });
 }
 

package/dist/bundling-sources/shared_libs/tool-execution-error.ts

@@ -84,6 +84,17 @@ export type ToolExecutionNetworkScope =
   | 'runtime_to_deepline'
   | 'deepline_to_provider';
 
+/**
+ * Bounded, primitive-only diagnostics explicitly approved for customers.
+ * Raw provider bodies, credentials, prompts, stacks, and causes never belong
+ * in this shared API/SDK/Play contract.
+ *
+ * @sdkReference errors 063
+ */
+export type ToolExecutionPublicDetails = Readonly<
+  Record<string, string | number | boolean | null>
+>;
+
 /**
  * Portable version-1 `tool_error` payload.
  *
@@ -120,6 +131,8 @@ export type ToolExecutionFailureV1 = {
   networkKind: ToolExecutionNetworkKind | null;
   /** Network boundary that failed, or `null`. */
   networkScope: ToolExecutionNetworkScope | null;
+  /** Explicitly allowlisted customer diagnostics, when present. */
+  publicDetails?: ToolExecutionPublicDetails | null;
 };
 
 /**
@@ -265,6 +278,8 @@ export class ToolExecutionError extends DeeplineError {
   readonly networkKind: ToolExecutionNetworkKind | null;
   /** Network boundary that failed, or `null` for non-network failures. */
   readonly networkScope: ToolExecutionNetworkScope | null;
+  /** Explicitly allowlisted diagnostics safe for SDK and Play callers. */
+  readonly publicDetails: ToolExecutionPublicDetails | null;
 
   /**
    * Construct a structured tool error.
@@ -290,6 +305,7 @@ export class ToolExecutionError extends DeeplineError {
     this.retryAfterMs = options.retryAfterMs;
     this.networkKind = options.networkKind;
     this.networkScope = options.networkScope;
+    this.publicDetails = options.publicDetails ?? null;
     applyBrand(this, TOOL_EXECUTION_ERROR_BRAND);
     if (isProviderTransientFailure(options)) {
       applyBrand(this, PROVIDER_TRANSIENT_ERROR_BRAND);
@@ -547,6 +563,69 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+const MAX_PUBLIC_DETAIL_ENTRIES = 20;
+const MAX_PUBLIC_DETAIL_KEY_LENGTH = 80;
+const MAX_PUBLIC_DETAIL_STRING_LENGTH = 512;
+const publicDetailsByError = new WeakMap<Error, ToolExecutionPublicDetails>();
+
+/**
+ * Normalizes the one public-detail shape at every transport boundary. Nested
+ * values are rejected to prevent accidental disclosure of provider responses.
+ */
+export function normalizeToolExecutionPublicDetails(
+  value: unknown,
+): ToolExecutionPublicDetails | null {
+  if (!isRecord(value)) return null;
+  const details: Record<string, string | number | boolean | null> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (Object.keys(details).length >= MAX_PUBLIC_DETAIL_ENTRIES) break;
+    if (
+      key.length === 0 ||
+      key.length > MAX_PUBLIC_DETAIL_KEY_LENGTH ||
+      !/^[a-z][a-zA-Z0-9_]*$/.test(key)
+    ) {
+      continue;
+    }
+    if (typeof entry === 'string') {
+      if (entry.length <= MAX_PUBLIC_DETAIL_STRING_LENGTH) details[key] = entry;
+      continue;
+    }
+    if (typeof entry === 'number') {
+      if (Number.isFinite(entry)) details[key] = entry;
+      continue;
+    }
+    if (typeof entry === 'boolean') {
+      details[key] = entry;
+      continue;
+    }
+    if (entry === null) details[key] = null;
+  }
+  return Object.keys(details).length > 0 ? details : null;
+}
+
+/**
+ * Attaches allowlisted details to an in-process error without making them
+ * enumerable. The execute boundary can later serialize them through the
+ * portable `tool_error.publicDetails` field.
+ */
+export function withToolExecutionPublicDetails<T extends Error>(
+  error: T,
+  details: unknown,
+): T {
+  const normalized = normalizeToolExecutionPublicDetails(details);
+  if (normalized) publicDetailsByError.set(error, normalized);
+  return error;
+}
+
+/** Reads details deliberately attached through `withToolExecutionPublicDetails`. */
+export function getToolExecutionPublicDetails(
+  error: unknown,
+): ToolExecutionPublicDetails | null {
+  return error instanceof Error
+    ? (publicDetailsByError.get(error) ?? null)
+    : null;
+}
+
 export function normalizeToolExecutionFailure(
   value: unknown,
 ): ToolExecutionFailureV1 | null {
@@ -565,6 +644,7 @@ export function normalizeToolExecutionFailure(
     operation,
   });
   const category = normalizeToolExecutionCategory(value.category);
+  const publicDetails = normalizeToolExecutionPublicDetails(value.publicDetails);
   const trustworthy =
     origin !== 'unknown' &&
     category !== 'unknown' &&
@@ -583,6 +663,7 @@ export function normalizeToolExecutionFailure(
     retryAfterMs: finiteNonNegativeInteger(value.retryAfterMs),
     networkKind: normalizeNetworkKind(value.networkKind),
     networkScope: normalizeNetworkScope(value.networkScope),
+    ...(publicDetails ? { publicDetails } : {}),
   };
 }
 
@@ -604,6 +685,7 @@ export function serializeToolExecutionFailure(
     retryAfterMs: error.retryAfterMs,
     networkKind: error.networkKind,
     networkScope: error.networkScope,
+    publicDetails: error.publicDetails,
   });
 }