deepline 0.3.82 → 0.3.83

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.82',
+  version: '0.3.83',
   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

@@ -18,6 +18,7 @@ import {
   reducePlayRunLedgerEvents,
   slicePositionalLogLines,
   type PlayRunLedgerEvent,
+  type PlayRunLedgerIngressEvent,
   type PlayRunLedgerSnapshot,
 } from './/run-ledger';
 import type {
@@ -149,7 +150,7 @@ type RuntimeApiRequest =
   | {
       action: 'append_run_events';
       playId: string;
-      events: PlayRunLedgerEvent[];
+      events: PlayRunLedgerIngressEvent[];
       idempotencyKey?: string;
     }
   | {
@@ -380,18 +381,42 @@ async function suppressBulkClaimResponseUntilTimeout(
   });
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
 function splitRunEventForAppRuntime(
-  event: PlayRunLedgerEvent,
-): PlayRunLedgerEvent[] {
-  if (event.type !== 'log.appended' || event.lines.length === 0) return [event];
-  const split: PlayRunLedgerEvent[] = [];
+  event: PlayRunLedgerIngressEvent,
+): PlayRunLedgerIngressEvent[] {
+  const eventType =
+    typeof event.key === 'string'
+      ? event.key
+      : typeof event.type === 'string'
+        ? event.type
+        : null;
+  const payload = isRecord(event.payload) ? event.payload : null;
+  const payloadLines = payload?.lines;
+  const payloadOwnsLines = Array.isArray(payloadLines);
+  const rawLines = payloadOwnsLines ? payloadLines : event.lines;
+  const lines = Array.isArray(rawLines)
+    ? rawLines.filter((line): line is string => typeof line === 'string')
+    : [];
+  if (eventType !== 'log.appended' || lines.length === 0) return [event];
+  const payloadChannelOffset =
+    typeof payload?.channelOffset === 'number'
+      ? payload.channelOffset
+      : undefined;
+  const eventChannelOffset =
+    typeof event.channelOffset === 'number' ? event.channelOffset : undefined;
+  const split: PlayRunLedgerIngressEvent[] = [];
+  const { lines: _outerLines, ...eventWithoutOuterLines } = event;
   let index = 0;
-  while (index < event.lines.length) {
+  while (index < lines.length) {
     const start = index;
     let bytes = 2;
-    while (index < event.lines.length) {
+    while (index < lines.length) {
       const lineBytes = appRuntimeTextEncoder.encode(
-        JSON.stringify(event.lines[index]!),
+        JSON.stringify(lines[index]!),
       ).length;
       if (
         index > start &&
@@ -402,22 +427,40 @@ function splitRunEventForAppRuntime(
       bytes += lineBytes + 1;
       index += 1;
     }
-    split.push({
-      ...event,
-      lines: event.lines.slice(start, index),
-      ...(typeof event.channelOffset === 'number'
-        ? { channelOffset: event.channelOffset + start }
-        : {}),
-    });
+    const batchLines = lines.slice(start, index);
+    split.push(
+      payload
+        ? {
+            ...eventWithoutOuterLines,
+            ...(payloadOwnsLines ? {} : { lines: batchLines }),
+            payload: {
+              ...payload,
+              ...(payloadOwnsLines ? { lines: batchLines } : {}),
+              ...(payloadChannelOffset === undefined
+                ? {}
+                : { channelOffset: payloadChannelOffset + start }),
+            },
+            ...(eventChannelOffset === undefined
+              ? {}
+              : { channelOffset: eventChannelOffset + start }),
+          }
+        : {
+            ...event,
+            lines: batchLines,
+            ...(eventChannelOffset === undefined
+              ? {}
+              : { channelOffset: eventChannelOffset + start }),
+          },
+    );
   }
   return split;
 }
 
 export function partitionRunEventsForAppRuntime(
-  events: readonly PlayRunLedgerEvent[],
-): PlayRunLedgerEvent[][] {
-  const batches: PlayRunLedgerEvent[][] = [];
-  let current: PlayRunLedgerEvent[] = [];
+  events: readonly PlayRunLedgerIngressEvent[],
+): PlayRunLedgerIngressEvent[][] {
+  const batches: PlayRunLedgerIngressEvent[][] = [];
+  let current: PlayRunLedgerIngressEvent[] = [];
   let currentBytes = 2;
   for (const event of events.flatMap(splitRunEventForAppRuntime)) {
     const eventBytes = appRuntimeTextEncoder.encode(
@@ -742,9 +785,15 @@ function appRuntimeRetryAfterMs(
     }
   } catch {}
 
-  const retryAfterSeconds = Number(response.headers.get('retry-after'));
-  return Number.isFinite(retryAfterSeconds)
-    ? Math.max(0, Math.min(retryAfterSeconds * 1_000, 30_000))
+  const retryAfter = response.headers.get('retry-after')?.trim();
+  if (!retryAfter) return null;
+  const retryAfterSeconds = Number(retryAfter);
+  if (Number.isFinite(retryAfterSeconds)) {
+    return Math.max(0, Math.min(retryAfterSeconds * 1_000, 30_000));
+  }
+  const retryAt = Date.parse(retryAfter);
+  return Number.isFinite(retryAt)
+    ? Math.max(0, Math.min(retryAt - Date.now(), 30_000))
     : null;
 }
 
@@ -997,6 +1046,8 @@ export class AppRuntimeApiResponseError extends Error {
   readonly code: string | null;
   readonly requestId: string | null;
   readonly retryable: boolean;
+  /** Server-requested delay, retained for durable callers after local retries end. */
+  readonly retryAfterMs: number | null;
   readonly detail: string;
 
   constructor(input: {
@@ -1005,6 +1056,7 @@ export class AppRuntimeApiResponseError extends Error {
     code?: string | null;
     requestId?: string | null;
     retryable: boolean;
+    retryAfterMs?: number | null;
     detail: string;
     boundaryLabel?: string;
   }) {
@@ -1020,6 +1072,10 @@ export class AppRuntimeApiResponseError extends Error {
     this.code = input.code?.trim() || null;
     this.requestId = input.requestId?.trim() || null;
     this.retryable = input.retryable;
+    this.retryAfterMs =
+      typeof input.retryAfterMs === 'number' && Number.isFinite(input.retryAfterMs)
+        ? Math.max(0, Math.floor(input.retryAfterMs))
+        : null;
     this.detail = input.detail;
   }
 }
@@ -1038,7 +1094,7 @@ const APP_RUNTIME_CAPACITY_ERROR_CODES = new Set([
  * than spending the ordinary request retry ladder.
  */
 export class AppRuntimeApiCapacityError extends AppRuntimeApiResponseError {
-  readonly retryAfterMs: number;
+  declare readonly retryAfterMs: number;
 
   constructor(input: {
     action: RuntimeApiRequest['action'];
@@ -1374,6 +1430,7 @@ async function postAppRuntimeApi<TResponse>(
         body: responseText,
         contentType: response.headers.get('content-type'),
       }),
+      retryAfterMs: appRuntimeRetryAfterMs(response, responseText),
       detail: summarizeAppRuntimeErrorBody(responseText),
       boundaryLabel,
     });
@@ -1870,7 +1927,7 @@ async function appendRunEventsViaAppRuntimeRaw(
   context: WorkerRuntimeApiContext,
   input: {
     playId: string;
-    events: PlayRunLedgerEvent[];
+    events: PlayRunLedgerIngressEvent[];
     idempotencyKey?: string;
   },
 ): Promise<void> {
@@ -1890,7 +1947,7 @@ export async function appendRunEventsViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: {
     playId: string;
-    events: PlayRunLedgerEvent[];
+    events: PlayRunLedgerIngressEvent[];
     idempotencyKey?: string;
   },
 ): Promise<void> {
@@ -1907,10 +1964,14 @@ export async function appendRunEventsViaAppRuntime(
   for (let index = batches.length - 1; index >= 0; index -= 1) {
     if (
       batches[index]!.some(
-        (event) =>
-          event.type === 'run.completed' ||
-          event.type === 'run.failed' ||
-          event.type === 'run.cancelled',
+        (event) => {
+          const key = event.key ?? event.type;
+          return (
+            key === 'run.completed' ||
+            key === 'run.failed' ||
+            key === 'run.cancelled'
+          );
+        },
       )
     ) {
       terminalBatchIndex = index;

package/dist/bundling-sources/shared_libs/play-runtime/ledger-safe-payload.ts

@@ -1,6 +1,7 @@
 import { createSecretRedactionContext } from './secret-redaction';
 import {
   assertRuntimeReceiptOutputWithinLimit,
+  inspectConvexLedgerPayload,
   jsonByteLengthUpTo,
   LEDGER_TERMINAL_RESULT_MAX_BYTES,
 } from './output-size-limits';
@@ -31,6 +32,31 @@ export function sanitizeLedgerPayload(value: unknown): unknown {
   return ledgerIngressRedactor.redact(value);
 }
 
+function opaqueLedgerPayloadSummary(
+  issue: NonNullable<ReturnType<typeof inspectConvexLedgerPayload>>,
+): Record<string, unknown> {
+  return {
+    __kind: 'deepline.opaque_ledger_payload_summary.v1',
+    reason: issue.reason,
+    ...(typeof issue.bytes === 'number' ? { bytes: issue.bytes } : {}),
+  };
+}
+
+/**
+ * Preserve unfamiliar event payloads when they fit the Convex event contract.
+ * If they do not, keep a safe diagnostic summary instead of allowing one newer
+ * producer to permanently wedge its ordered ledger outbox behind a document
+ * limit, depth, or field-name rejection.
+ */
+export function sanitizeOpaqueLedgerPayload(value: unknown): unknown {
+  const sourceIssue = inspectConvexLedgerPayload(value);
+  if (sourceIssue) return opaqueLedgerPayloadSummary(sourceIssue);
+
+  const redacted = ledgerIngressRedactor.redact(value);
+  const redactedIssue = inspectConvexLedgerPayload(redacted);
+  return redactedIssue ? opaqueLedgerPayloadSummary(redactedIssue) : redacted;
+}
+
 /** Secret-redact a receipt payload without coupling its 10 MiB cell limit to the ledger. */
 export function sanitizeRuntimeReceiptPayload(value: unknown): unknown {
   // Reject an obviously oversized source before doing redaction work, then

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger.ts

@@ -173,6 +173,12 @@ type PlayRunLedgerBaseEvent = {
   seq?: number;
   occurredAt: number;
   source: PlayRunLedgerEventSource;
+  /**
+   * Producer-owned detail. The ledger preserves this without assigning it
+   * snapshot meaning; a known event's projection reads only the fields its
+   * reducer understands.
+   */
+  payload?: unknown;
 };
 
 export type PlayRunLedgerEvent =
@@ -289,6 +295,55 @@ export type PlayRunLedgerEvent =
       observation: PlayActivityObservation;
     });
 
+/**
+ * Wire shape accepted by the Run Ledger ingress.
+ *
+ * Producers can evolve their event vocabulary independently from the current
+ * snapshot reducer. The only producer-owned identity is `key` (or the legacy
+ * `type` spelling); `payload` and all additional fields are open. The receiver
+ * authenticates the delivery and assigns trusted run/time/source fields before
+ * an unfamiliar key becomes {@link PlayRunLedgerOpaqueEvent} in storage.
+ * Keep the known {@link PlayRunLedgerEvent} union closed so reducer authors
+ * retain exhaustive type checking for the semantics they actually own.
+ */
+export type PlayRunLedgerIngressEvent = {
+  /** Preferred generic event identity. */
+  key?: string;
+  /** Backward-compatible event identity used by existing runners. */
+  type?: string;
+  /** Optional redundant target; a supplied value must match the append target. */
+  runId?: string;
+  /** Optional producer timestamp; the receiver supplies one when omitted. */
+  occurredAt?: number;
+  /** Advisory producer label; unknown labels normalize to `system`. */
+  source?: PlayRunLedgerEventSource | string;
+  /** Arbitrary producer-owned detail. */
+  payload?: unknown;
+  [field: string]: unknown;
+};
+
+/**
+ * A well-formed event whose type is not understood by this ledger version.
+ * The original type and its redacted, bounded payload are durable history;
+ * projection deliberately treats this as a strict no-op.
+ */
+export type PlayRunLedgerOpaqueEvent = PlayRunLedgerBaseEvent & {
+  type: string;
+  opaque: true;
+  payload: unknown;
+};
+
+/** A stored event accepted by this ledger version. */
+export type AcceptedPlayRunLedgerEvent =
+  | PlayRunLedgerEvent
+  | PlayRunLedgerOpaqueEvent;
+
+export function isPlayRunLedgerOpaqueEvent(
+  event: AcceptedPlayRunLedgerEvent,
+): event is PlayRunLedgerOpaqueEvent {
+  return 'opaque' in event && event.opaque === true;
+}
+
 export type PlayRunLedgerStatusPatch = {
   runId: string;
   playName?: string | null;
@@ -1102,8 +1157,14 @@ function refineTerminalSyntheticStepStart(
 
 export function reducePlayRunLedgerEvent(
   snapshot: PlayRunLedgerSnapshot,
-  event: PlayRunLedgerEvent,
+  event: AcceptedPlayRunLedgerEvent,
 ): PlayRunLedgerSnapshot {
+  // Storage compatibility is intentionally wider than reducer semantics. An
+  // unknown event is durable evidence for a newer producer, not permission to
+  // guess at run state or to advance any snapshot timestamp.
+  if (isPlayRunLedgerOpaqueEvent(event)) {
+    return snapshot;
+  }
   if (event.runId !== snapshot.runId) {
     return snapshot;
   }
@@ -1525,12 +1586,18 @@ export function reducePlayRunLedgerEvent(
           : event.observation.activityId,
       });
     }
+    default:
+      // `appendPlayRunEventsInternal` has historical callers that predate the
+      // opaque ingress envelope. Keep the reducer fail-closed even if one
+      // reaches storage with a newer raw type: it is durable history, never a
+      // reason to manufacture snapshot state or return `undefined`.
+      return snapshot;
   }
 }
 
 export function reducePlayRunLedgerEvents(
   snapshot: PlayRunLedgerSnapshot,
-  events: readonly PlayRunLedgerEvent[],
+  events: readonly AcceptedPlayRunLedgerEvent[],
 ): PlayRunLedgerSnapshot {
   return events.reduce(reducePlayRunLedgerEvent, snapshot);
 }

package/dist/cli/index.js

@@ -1225,7 +1225,7 @@ var 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.82",
+  version: "0.3.83",
   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: {
     updatePreferences: 1

package/dist/cli/index.mjs

@@ -1210,7 +1210,7 @@ var 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.82",
+  version: "0.3.83",
   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: {
     updatePreferences: 1

package/dist/index.js

@@ -832,7 +832,7 @@ var 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.82",
+  version: "0.3.83",
   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: {
     updatePreferences: 1

package/dist/index.mjs

@@ -744,7 +744,7 @@ var 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.82",
+  version: "0.3.83",
   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: {
     updatePreferences: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.82",
+  "version": "0.3.83",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",