deepline 0.1.12 → 0.1.19

package/dist/index.d.ts

@@ -264,6 +264,25 @@ interface ToolDefinition {
     resultIdentityGetters?: Record<string, string[]>;
     /** Whether the output is a direct object or wrapped in a `result` envelope. */
     rowContextShape?: 'direct' | 'result_envelope';
+    /** Search relevance score returned by ranked tool search. */
+    search_score?: number;
+    /** Search match snippets returned by ranked tool search. */
+    search_matches?: Array<{
+        field: string;
+        value: string;
+        term?: string;
+    }>;
+}
+interface ToolSearchOptions {
+    query?: string;
+    categories?: string;
+    searchTerms?: string;
+    searchMode?: 'v1' | 'v2';
+    includeSearchDebug?: boolean;
+}
+interface ToolSearchResult {
+    tools: ToolDefinition[];
+    search_fallback_to_category?: boolean;
 }
 /**
  * Extended tool metadata including pricing, samples, and failure modes.
@@ -344,6 +363,8 @@ interface PlayProgressStatus {
     totalRows?: number;
     /** Accumulated log lines from `ctx.log()`. Grows monotonically. */
     logs: string[];
+    /** Zero-based offset of the first returned log line when a tail cursor is used. */
+    logOffset?: number;
     /** Error message if the play has failed. */
     error?: string;
 }
@@ -724,6 +745,8 @@ interface StartPlayRunRequest {
     artifactStorageKey?: string;
     /** Source snapshot already validated while registering this artifact. */
     sourceCode?: string;
+    /** Source graph snapshots for local helper files included in cloud preflight. */
+    sourceFiles?: Record<string, string>;
     /** Static pipeline already produced while registering this artifact. */
     staticPipeline?: unknown;
     /** Artifact content hash already validated while registering this artifact. */
@@ -795,6 +818,9 @@ interface PlayStagedFileRef {
     bytes: number;
 }
 
+type ExecuteToolRawOptions = {
+    includeToolMetadata?: boolean;
+};
 type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
     status: string;
     job_id?: string;
@@ -805,6 +831,39 @@ type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
     billing?: Record<string, unknown>;
     [key: string]: unknown;
 };
+type RunsListOptions = {
+    play: string;
+    status?: string;
+};
+type RunsTailOptions = {
+    cursor?: string | number;
+    afterLogIndex?: number;
+    waitMs?: number;
+    terminalOnly?: boolean;
+    compact?: boolean;
+};
+type RunsLogsOptions = {
+    limit?: number;
+};
+type RunsLogsResult = {
+    runId: string;
+    totalCount: number;
+    returnedCount: number;
+    firstSequence: number | null;
+    lastSequence: number | null;
+    truncated: boolean;
+    hasMore: boolean;
+    entries: string[];
+};
+type RunsNamespace = {
+    get: (runId: string) => Promise<PlayStatus>;
+    list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
+    tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
+    logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
+    stop: (runId: string, options?: {
+        reason?: string;
+    }) => Promise<StopPlayRunResult>;
+};
 /**
  * Low-level client for the Deepline REST API.
  *
@@ -828,6 +887,7 @@ type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
 declare class DeeplineClient {
     private readonly http;
     private readonly config;
+    readonly runs: RunsNamespace;
     /**
      * @param options - Optional overrides for API key, base URL, timeout, and retries.
      * @throws {@link ConfigError} if no API key can be resolved from any source.
@@ -856,6 +916,13 @@ declare class DeeplineClient {
      * ```
      */
     listTools(): Promise<ToolDefinition[]>;
+    /**
+     * Search available tools using Deepline's ranked backend search.
+     *
+     * This is the same discovery surface used by the legacy CLI: it ranks across
+     * tool metadata, categories, agent guidance, and input schema fields.
+     */
+    searchTools(options?: ToolSearchOptions): Promise<ToolSearchResult>;
     /**
      * Get detailed metadata for a single tool.
      *
@@ -881,7 +948,8 @@ declare class DeeplineClient {
      * Top-level fields such as `status`, `job_id`, and `billing` describe the
      * Deepline execution.
      */
-    executeTool<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>): Promise<ToolExecution<TData, TMeta>>;
+    executeTool<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
+    executeToolRaw<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
     queryCustomerDb(input: {
         sql: string;
         maxRows?: number;
@@ -932,6 +1000,7 @@ declare class DeeplineClient {
     registerPlayArtifact(input: {
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -954,6 +1023,7 @@ declare class DeeplineClient {
     registerPlayArtifacts(artifacts: Array<{
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -979,6 +1049,7 @@ declare class DeeplineClient {
     compilePlayManifest(input: {
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         importedPlayDependencies?: PlayCompilerManifest[];
     }): Promise<PlayCompilerManifest>;
@@ -992,11 +1063,13 @@ declare class DeeplineClient {
     checkPlayArtifact(input: {
         name?: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
     startPlayRunFromBundle(input: {
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -1030,6 +1103,7 @@ declare class DeeplineClient {
      */
     submitPlay(code: string, csvPath: string | null, name?: string, options?: {
         sourceCode?: string;
+        sourceFiles?: Record<string, string>;
         artifact?: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -1164,6 +1238,58 @@ declare class DeeplineClient {
      * ```
      */
     listPlayRuns(playName: string): Promise<PlayRunListItem[]>;
+    /**
+     * Get a run by id using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs get <run-id> --json
+     * ```
+     */
+    getRunStatus(runId: string): Promise<PlayStatus>;
+    /**
+     * List play runs using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs list --play <play-name> --status failed --json
+     * ```
+     */
+    listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
+    /**
+     * Fetch the lightweight tail status for a run using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs tail <run-id> --json
+     * ```
+     */
+    tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
+    /**
+     * Fetch persisted logs for a run using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs logs <run-id> --limit 200 --json
+     * ```
+     */
+    getRunLogs(runId: string, options?: RunsLogsOptions): Promise<RunsLogsResult>;
+    /**
+     * Stop a run by id using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs stop <run-id> --reason "stale lock" --json
+     * ```
+     */
+    stopRun(runId: string, options?: {
+        reason?: string;
+    }): Promise<StopPlayRunResult>;
     listPlays(): Promise<PlayListItem[]>;
     searchPlays(options: {
         query: string;
@@ -1308,8 +1434,8 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.12";
-declare const SDK_API_CONTRACT = "2026-04-plays-v1";
+declare const SDK_VERSION = "0.1.19";
+declare const SDK_API_CONTRACT = "2026-05-runs-v2";
 
 /**
  * Base error class for all Deepline SDK errors.
@@ -1474,6 +1600,20 @@ type PlayDatasetBacking = {
     storage: 'r2_file';
     file: PlayExecutionFileRef;
 };
+type PlayDatasetWorkProgressSummary = {
+    total: number;
+    executed: number;
+    reused: number;
+    skipped: number;
+    pending: number;
+    failed: number;
+    degraded?: boolean;
+    duplicates?: {
+        exact?: number;
+        semantic?: number;
+        rejected?: number;
+    };
+};
 type PlayDatasetInput<T> = ReadonlyArray<T> | Iterable<T> | AsyncIterable<T> | PlayDataset<T>;
 interface PlayDataset<T> extends AsyncIterable<T> {
     readonly [PLAY_DATASET_BRAND]: true;
@@ -1499,10 +1639,65 @@ interface PlayDataset<T> extends AsyncIterable<T> {
         sourceLabel?: string | null;
         tableNamespace?: string | null;
         columns?: string[];
+        _metadata?: {
+            workProgress?: PlayDatasetWorkProgressSummary;
+        };
         preview: T[];
     };
 }
 
+type ToolResultExecutionMetadata = {
+    idempotent: true;
+    cached: boolean;
+    source: 'live' | 'checkpoint' | 'cache';
+    cacheKey?: string;
+};
+type ToolResultTargetMetadata = {
+    value: unknown;
+    path: string;
+};
+type ToolResultListMetadata = {
+    path: string;
+    count: number | null;
+    keys: Record<string, string>;
+};
+type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
+    get(): T | null;
+};
+type ToolResultListAccessor<T = Record<string, unknown>> = ToolResultListMetadata & {
+    get(): T[];
+};
+type ToolResultEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
+    data: TData;
+    meta?: TMeta;
+};
+type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> = {
+    status: string;
+    result: ToolResultEnvelope<TResult, TMeta>;
+    _metadata: {
+        toolId: string;
+        execution: ToolResultExecutionMetadata;
+        targets: Record<string, {
+            value: unknown;
+            path: string;
+        }>;
+        lists: Record<string, {
+            path: string;
+            count: number | null;
+            keys: Record<string, string>;
+        }>;
+    };
+};
+type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
+    extracted: {
+        [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
+    };
+    lists: {
+        [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
+    };
+};
+type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
+
 /**
  * Optional trigger bindings for a play.
  *
@@ -1558,25 +1753,7 @@ type PlayBindings = {
 type LoosePlayObject = {
     [key: string]: LoosePlayObject;
 };
-type ToolExtractedValue<T = unknown> = {
-    path: string;
-    get(): T | null;
-};
-type ToolResultEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
-    data: TData;
-    meta?: TMeta;
-};
-type ToolExecuteResult<TData = unknown, TMeta = Record<string, unknown>> = {
-    status: string;
-    result: ToolResultEnvelope<TData, TMeta>;
-    extracted: Record<string, ToolExtractedValue>;
-    lists: Record<string, {
-        path: string;
-        count: number | null;
-        keys: Record<string, string>;
-        get(): Record<string, unknown>[];
-    }>;
-};
+
 type ToolExecutionRequest = {
     id: string;
     tool: string;
@@ -1615,7 +1792,6 @@ type MapStepBuilder<InputRow extends object, OutputRow extends object> = {
     run(options?: {
         description?: string;
         staleAfterSeconds?: number;
-        concurrency?: number;
         key?: (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);
     }): Promise<PlayDataset<OutputRow>>;
 };