deepline 0.3.246 → 0.3.248

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

@@ -4,6 +4,7 @@ import type {
   PlaySettingsPathsPage,
 } from '../../shared_libs/plays/settings-contract';
 import { iterateCursorPages } from './pagination.js';
+import { playInputExampleArgs } from './plays/input-example.js';
 /**
  * The main API client for interacting with the Deepline platform.
  *
@@ -114,6 +115,7 @@ import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
 import {
+  COORDINATOR_INTERNAL_TOKEN_HEADER,
   RUNTIME_ENVIRONMENT_TOKEN_HEADER,
   RETAINED_PIPELINE_RECEIVERS_HEADER,
 } from '../../shared_libs/play-runtime/coordinator-headers.js';
@@ -414,6 +416,29 @@ function runtimeSelectionHeaders(
   };
 }
 
+/** The isolated PR estate needs its existing internal credential to read its pinned scheduler scope. */
+function isolatedCiRuntimeEventReadHeaders():
+  | Record<string, string>
+  | undefined {
+  const schema = process.env.DEEPLINE_RUNTIME_SCHEDULER_SCHEMA?.trim();
+  if (
+    process.env.DEEPLINE_SYNTHETIC_RUN?.trim() !== '1' ||
+    !schema ||
+    !/^fly_absurd_pr_\d+_\d+(?:_\d+)?$/.test(schema)
+  ) {
+    return undefined;
+  }
+  const token = process.env.DEEPLINE_INTERNAL_TOKEN?.trim();
+  if (!token) {
+    throw new DeeplineError(
+      'DEEPLINE_INTERNAL_TOKEN is required for isolated CI runtime event reads.',
+      undefined,
+      'RUNTIME_EVENT_INTERNAL_TOKEN_REQUIRED',
+    );
+  }
+  return { [COORDINATOR_INTERNAL_TOKEN_HEADER]: token };
+}
+
 function normalizeTestPolicyOverrides(
   value: unknown,
   source: string,
@@ -691,6 +716,54 @@ export type RunsLogsResult = {
   logsTruncated?: boolean;
 };
 
+/** Bounded org-scoped search over durable Play runtime observations. */
+export type RunsEventSearchOptions = {
+  /** Inclusive UTC timestamp; defaults to one hour before the request. */
+  since?: string;
+  /** Exclusive UTC timestamp; defaults to the request time. */
+  until?: string;
+  /** Optional run filter. Omit to search across the active organization. */
+  runId?: string;
+  playName?: string;
+  kind?: string;
+  /** Flat equality predicate in the supported PostgreSQL JSONPath subset. */
+  jsonpath?: string;
+  /** Include receipt-backed outputs, capped to ten events and 16 MiB total. */
+  includePayloads?: boolean;
+  limit?: number;
+  cursor?: string;
+  /** Explicit Preview selection requires the existing runtime credential. */
+  runtime?: PlayRuntimeSelection;
+};
+
+export type RunsEventSearchEntry = {
+  eventId: string;
+  occurredAt: string;
+  ingestedAt: string;
+  runId: string;
+  playName: string;
+  kind: string;
+  level: string | null;
+  message: string | null;
+  searchDoc: Record<string, unknown>;
+  /** Optional full result, included only when explicitly requested. */
+  payload?: RunsEventPayload | null;
+};
+
+export type RunsEventSearchResult = {
+  events: RunsEventSearchEntry[];
+  nextCursor: string | null;
+  since: string;
+  until: string;
+};
+
+export type RunsEventPayload = {
+  status: 'completed' | 'failed' | 'skipped';
+  output: unknown | null;
+  error: string | null;
+  errorPayload: unknown | null;
+};
+
 /** Server page cap for GET /api/v2/runs/:runId/logs (ADR-0009). */
 const RUN_LOGS_PAGE_LIMIT = 1_000;
 
@@ -768,6 +841,11 @@ export type PlaySecretCheck = {
  * @sdkReference client 020 client.runs
  */
 export type RunsNamespace = {
+  /** Read retained tool results associated with a run, in supplied key order. Never executes tools. */
+  getReceipts: (
+    runId: string,
+    options: { keys: string[] },
+  ) => Promise<import('./runs/receipts').RunToolReceiptsResponse>;
   /** Get current run status by public run id. */
   get: (runId: string, options?: RunsGetOptions) => Promise<PlayStatus>;
   /**
@@ -795,6 +873,10 @@ export type RunsNamespace = {
   tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
   /** Fetch persisted log lines for a run. */
   logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
+  /** Search recent durable runtime events across runs in the active organization. */
+  searchEvents: (
+    options?: RunsEventSearchOptions,
+  ) => Promise<RunsEventSearchResult>;
   /** Export persisted rows for a runtime-sheet dataset/table namespace. */
   exportDatasetRows: (input: {
     playName: string;
@@ -2680,8 +2762,13 @@ export class DeeplineClient {
   constructor(options?: DeeplineClientOptions) {
     this.config = resolveConfig(options);
     this.http = new HttpClient(this.config);
-    this.toolCalls = new ToolCalls(this.http, this.config.timeout);
+    this.toolCalls = new ToolCalls(
+      this.http,
+      this.config.timeout,
+      options?.timeout,
+    );
     this.runs = {
+      getReceipts: (runId, options) => this.getRunReceipts(runId, options),
       get: (runId, options) => this.getRunStatus(runId, options),
       status: (runId) => this.getRunLifecycleStatus(runId),
       list: (options) => this.listRuns(options),
@@ -2689,6 +2776,7 @@ export class DeeplineClient {
       watch: (runId, options) => this.watchRunToTerminal(runId, options),
       tail: (runId, options) => this.tailRun(runId, options),
       logs: (runId, options) => this.getRunLogs(runId, options),
+      searchEvents: (options) => this.searchRunEvents(options),
       input: (runId) => this.getRunInput(runId),
       rerun: (runId, options) => this.rerun(runId, options),
       exportDatasetRows: (input) => this.getPlaySheetRows(input),
@@ -2863,19 +2951,10 @@ export class DeeplineClient {
   }
 
   private playRunCommand(
-    play: Pick<PlayListItem, 'name' | 'reference'>,
-    options?: { csvInput?: Record<string, unknown> | null },
+    play: Pick<PlayListItem, 'name' | 'reference' | 'inputSchema'>,
   ): string {
     const target = play.reference || play.name;
-    if (options?.csvInput) {
-      const inputField =
-        typeof options.csvInput.inputField === 'string' &&
-        options.csvInput.inputField.trim()
-          ? options.csvInput.inputField.trim()
-          : 'csv';
-      return `deepline plays run ${target} --input '${JSON.stringify({ [inputField]: 'leads.csv' })}' --watch`;
-    }
-    return `deepline plays run ${target} --input '{...}' --watch`;
+    return `deepline plays run ${target}${playInputExampleArgs(play.inputSchema)} --watch`;
   }
 
   private starterPlayPath(
@@ -2926,7 +3005,7 @@ export class DeeplineClient {
       play.currentRevision?.description?.trim() ||
       play.liveRevision?.description?.trim() ||
       null;
-    const runCommand = this.playRunCommand(play, { csvInput });
+    const runCommand = this.playRunCommand(play);
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
@@ -4593,6 +4672,50 @@ export class DeeplineClient {
     return { ...response, runs: response.runs ?? [] };
   }
 
+  /** Read batches rather than silently truncating a long key list. */
+  async getRunReceipts(
+    runId: string,
+    options: { keys: string[] },
+  ): Promise<import('./runs/receipts').RunToolReceiptsResponse> {
+    if (
+      !options.keys.length ||
+      options.keys.some(
+        (key) =>
+          typeof key !== 'string' ||
+          !key.trim() ||
+          key.length > 2048 ||
+          /[\r\n\0]/.test(key),
+      )
+    ) {
+      throw Object.assign(
+        new Error(
+          'Supply nonempty receipt keys, at most 2048 characters each.',
+        ),
+        { exitCode: 2 },
+      );
+    }
+    const receipts: import('./runs/receipts').RunToolReceiptResult[] = [];
+    for (let offset = 0; offset < options.keys.length; offset += 100) {
+      const keys = options.keys.slice(offset, offset + 100);
+      const result = await this.http.post<
+        import('./runs/receipts').RunToolReceiptsResponse
+      >(`/api/v2/runs/${encodeURIComponent(runId)}/receipts/results`, { keys });
+      if (
+        result.runId !== runId ||
+        result.receipts.length !== keys.length ||
+        result.receipts.some(
+          (receipt, index) => receipt.receiptKey !== keys[index],
+        )
+      ) {
+        throw new Error(
+          'Receipt response does not match the requested run and keys.',
+        );
+      }
+      receipts.push(...result.receipts);
+    }
+    return { runId, receipts };
+  }
+
   /** Get the exact original input retained for a run. This is intentionally separate from status. */
   async getRunInput(runId: string): Promise<{
     runId: string;
@@ -4662,6 +4785,7 @@ export class DeeplineClient {
       const failedLimit = Math.min(RUNS_FAILED_LOG_LIMIT, requestedLimit);
       const page = await this.http.get<RunLogsPageResponse>(
         `/api/v2/runs/${encodeURIComponent(runId)}/logs?view=failed&limit=${failedLimit}`,
+        { retryApiErrors: true },
       );
       return {
         runId: page.runId,
@@ -4691,6 +4815,7 @@ export class DeeplineClient {
     const fetchPage = (afterSeq: number, pageLimit: number) =>
       this.http.get<RunLogsPageResponse>(
         `/api/v2/runs/${encodeURIComponent(runId)}/logs?afterSeq=${afterSeq}&limit=${pageLimit}`,
+        { retryApiErrors: true },
       );
     // Probe for the run's stored extent, then read the LAST `limit` stored
     // lines (matching the historical tail-slice semantics), paginating in
@@ -4730,6 +4855,45 @@ export class DeeplineClient {
     };
   }
 
+  /** Search bounded, structured runtime history without requiring a run id. */
+  async searchRunEvents(
+    options: RunsEventSearchOptions = {},
+  ): Promise<RunsEventSearchResult> {
+    const now = Date.now();
+    const params = new URLSearchParams({
+      since: options.since ?? new Date(now - 60 * 60 * 1000).toISOString(),
+      until: options.until ?? new Date(now).toISOString(),
+    });
+    if (options.runId) params.set('runId', options.runId);
+    if (options.playName) params.set('playName', options.playName);
+    if (options.kind) params.set('kind', options.kind);
+    if (options.jsonpath) params.set('jsonpath', options.jsonpath);
+    if (options.includePayloads) params.set('payloads', 'true');
+    if (options.limit !== undefined) params.set('limit', String(options.limit));
+    if (options.cursor) params.set('cursor', options.cursor);
+    let headers: Record<string, string> | undefined;
+    if (options.runtime !== undefined) {
+      const runtime = normalizePlayRuntimeSelection(options.runtime);
+      if (!runtime) {
+        throw new DeeplineError(
+          'runs.searchEvents runtime must be a valid Preview selection.',
+          undefined,
+          'INVALID_RUNTIME_SELECTION',
+        );
+      }
+      params.set('runtime', 'preview');
+      params.set('namespace', runtime.namespace);
+      if (runtime.backend) params.set('backend', runtime.backend);
+      headers = runtimeSelectionHeaders(runtime);
+    } else {
+      headers = isolatedCiRuntimeEventReadHeaders();
+    }
+    return this.http.get<RunsEventSearchResult>(
+      `/api/v2/runs/events?${params.toString()}`,
+      { headers, retryApiErrors: true },
+    );
+  }
+
   /**
    * Export persisted runtime-sheet rows for a play dataset/table namespace.
    *

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

@@ -136,6 +136,10 @@ export type {
   PlaysListPage,
   RunsLogsOptions,
   RunsLogsResult,
+  RunsEventSearchOptions,
+  RunsEventSearchEntry,
+  RunsEventSearchResult,
+  RunsEventPayload,
   RunsNamespace,
   RunsWatchOptions,
   RunsTailOptions,
@@ -350,3 +354,7 @@ export type {
   JobChangeStatus,
   PhoneStatus,
 } from './play.js';
+export type {
+  RunToolReceiptResult,
+  RunToolReceiptsResponse,
+} from './runs/receipts.js';

package/dist/bundling-sources/sdk/src/plays/input-example.ts

@@ -0,0 +1,40 @@
+/** Shared, contract-derived arguments for check/describe/search run examples. */
+export function playInputExampleArgs(
+  schema: Record<string, unknown> | null | undefined,
+): string {
+  if (!schema) return " --input '@<input.json>'";
+  // Do not guess required inputs hidden behind a reference or intersection.
+  if (schema.$ref || schema.allOf) return " --input '@<input.json>'";
+  const csv = schema.csvInput as { inputField?: unknown } | undefined;
+  const csvField = typeof csv?.inputField === 'string' ? csv.inputField : null;
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const csvOnlyRequired = required.every((key) => key === csvField);
+  const alternatives = schema.oneOf ?? schema.anyOf;
+  const hasCsvAlternative =
+    Array.isArray(alternatives) &&
+    alternatives.some((branch) => {
+      if (!branch || typeof branch !== 'object') return false;
+      const keys = (branch as { required?: unknown }).required;
+      return (
+        Array.isArray(keys) &&
+        keys.includes(csvField) &&
+        keys.every((key) => key === csvField)
+      );
+    });
+  // Only advertise the universally supported CSV shorthand. Other field names
+  // may collide with execution flags (e.g. file/name); JSON is unambiguous.
+  if (csvField && csvOnlyRequired && (!alternatives || hasCsvAlternative)) {
+    if (csvField === 'csv') return " --csv '<contacts.csv>'";
+    const value = JSON.stringify({ [csvField]: '<contacts.csv>' });
+    return ` --input '${value.replace(/'/g, "'\\''")}'`;
+  }
+  if (
+    Array.isArray(schema.required) &&
+    !required.length &&
+    !csv &&
+    !alternatives
+  ) {
+    return '';
+  }
+  return " --input '@<input.json>'";
+}

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

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.246',
+  version: '0.3.248',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {