deepline 0.0.1 → 0.1.0

package/dist/index.js

@@ -22,11 +22,26 @@ var src_exports = {};
 __export(src_exports, {
   AuthError: () => AuthError,
   ConfigError: () => ConfigError,
+  Deepline: () => Deepline,
   DeeplineClient: () => DeeplineClient,
+  DeeplineContext: () => DeeplineContext,
   DeeplineError: () => DeeplineError,
   PROD_URL: () => PROD_URL,
   RateLimitError: () => RateLimitError,
-  resolveConfig: () => resolveConfig
+  SDK_API_CONTRACT: () => SDK_API_CONTRACT,
+  SDK_VERSION: () => SDK_VERSION,
+  createToolCallResult: () => createToolCallResult,
+  defineInput: () => defineInput,
+  definePlay: () => definePlay,
+  defineWorkflow: () => defineWorkflow,
+  extractSummaryFields: () => extractSummaryFields,
+  getDefinedPlayMetadata: () => getDefinedPlayMetadata,
+  resolveConfig: () => resolveConfig,
+  steps: () => steps,
+  tryConvertToList: () => tryConvertToList,
+  when: () => when,
+  writeCsvOutputFile: () => writeCsvOutputFile,
+  writeJsonOutputFile: () => writeJsonOutputFile
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -55,6 +70,7 @@ var AuthError = class extends DeeplineError {
   }
 };
 var RateLimitError = class extends DeeplineError {
+  /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
   retryAfterMs;
   constructor(retryAfterMs = 5e3, message) {
     super(message ?? `Rate limited. Retry after ${retryAfterMs}ms.`, 429, "RATE_LIMIT");
@@ -108,22 +124,62 @@ function parseEnvFile(filePath) {
   }
   return env;
 }
-function loadCliEnv(baseUrl) {
-  const slug = baseUrlSlug(baseUrl);
-  const envPath = (0, import_node_path.join)((0, import_node_os.homedir)(), ".local", "deepline", slug, ".env");
+function findNearestWorktreeEnv(startDir = process.cwd()) {
+  let current = (0, import_node_path.resolve)(startDir);
+  while (true) {
+    const values = parseEnvFile((0, import_node_path.join)(current, ".env.worktree"));
+    if (Object.keys(values).length > 0) return values;
+    const parent = (0, import_node_path.dirname)(current);
+    if (parent === current) return {};
+    current = parent;
+  }
+}
+function normalizeWorktreeBaseUrl(baseUrl, worktreeEnv = findNearestWorktreeEnv()) {
+  const trimmed = baseUrl.trim().replace(/\/$/, "");
+  if (!trimmed) return trimmed;
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.hostname.endsWith(".localhost") && parsed.port === "1355") {
+      const port = worktreeEnv.WORKTREE_APP_PORT || worktreeEnv.PORT;
+      if (port) return `${parsed.protocol}//localhost:${port}`;
+    }
+  } catch {
+  }
+  return trimmed;
+}
+function resolveWorktreeBaseUrl() {
+  const worktreeEnv = findNearestWorktreeEnv();
+  const declared = worktreeEnv.DEEPLINE_API_BASE_URL || worktreeEnv.WORKTREE_PUBLIC_APP_URL || worktreeEnv.APP_URL || "";
+  if (declared) return normalizeWorktreeBaseUrl(declared, worktreeEnv);
+  const port = worktreeEnv.WORKTREE_APP_PORT || worktreeEnv.PORT || "";
+  return port ? `http://localhost:${port}` : "";
+}
+function sdkCliEnvFilePath(baseUrl) {
+  const home = process.env.HOME?.trim() || (0, import_node_os.homedir)();
+  return (0, import_node_path.join)(home, ".local", "deepline", baseUrlSlug(baseUrl || PROD_URL), ".env");
+}
+function loadCliEnv(baseUrl = PROD_URL) {
+  const envPath = sdkCliEnvFilePath(baseUrl);
   return parseEnvFile(envPath);
 }
+function loadGlobalCliEnv() {
+  return loadCliEnv(PROD_URL);
+}
 function autoDetectBaseUrl() {
+  const envOrigin = process.env.DEEPLINE_ORIGIN_URL?.trim();
+  if (envOrigin) return normalizeWorktreeBaseUrl(envOrigin);
   const envBase = process.env.DEEPLINE_API_BASE_URL?.trim();
-  if (envBase) return envBase;
-  const localEnvPath = (0, import_node_path.join)((0, import_node_os.homedir)(), ".local", "deepline", "localhost-3000", ".env");
-  if ((0, import_node_fs.existsSync)(localEnvPath)) {
-    return "http://localhost:3000";
-  }
+  if (envBase) return normalizeWorktreeBaseUrl(envBase);
+  const worktreeBaseUrl = resolveWorktreeBaseUrl();
+  if (worktreeBaseUrl) return worktreeBaseUrl;
+  const globalEnv = loadGlobalCliEnv();
+  const globalOrigin = globalEnv.DEEPLINE_ORIGIN_URL?.trim();
+  if (globalOrigin) return normalizeWorktreeBaseUrl(globalOrigin);
   return PROD_URL;
 }
 function resolveConfig(options) {
-  const baseUrl = options?.baseUrl?.trim() || autoDetectBaseUrl();
+  const requestedBaseUrl = options?.baseUrl?.trim() || autoDetectBaseUrl();
+  const baseUrl = normalizeWorktreeBaseUrl(requestedBaseUrl);
   const cliEnv = loadCliEnv(baseUrl);
   const apiKey = options?.apiKey?.trim() || process.env.DEEPLINE_API_KEY?.trim() || cliEnv.DEEPLINE_API_KEY || "";
   if (!apiKey) {
@@ -133,94 +189,214 @@ function resolveConfig(options) {
   }
   return {
     apiKey,
-    baseUrl: baseUrl.replace(/\/$/, ""),
+    baseUrl,
     timeout: options?.timeout ?? DEFAULT_TIMEOUT,
     maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES
   };
 }
 
-// src/http.ts
+// src/version.ts
 var SDK_VERSION = "0.1.0";
+var SDK_API_CONTRACT = "2026-04-plays-v1";
+
+// ../shared_libs/play-runtime/coordinator-headers.ts
+var COORDINATOR_URL_OVERRIDE_HEADER = "x-deepline-coordinator-url";
+var WORKER_CALLBACK_URL_OVERRIDE_HEADER = "x-deepline-worker-callback-url";
+
+// src/http.ts
 var HttpClient = class {
   constructor(config) {
     this.config = config;
   }
   config;
-  async request(path, options) {
-    const url = `${this.config.baseUrl}${path}`;
-    const method = options?.method ?? "GET";
+  authHeaders(extra) {
     const headers = {
       "Authorization": `Bearer ${this.config.apiKey}`,
       "User-Agent": `deepline-ts-sdk/${SDK_VERSION}`,
-      ...options?.headers
+      "X-Deepline-SDK-Version": SDK_VERSION,
+      "X-Deepline-API-Contract": SDK_API_CONTRACT,
+      ...extra
     };
+    const bypassToken = typeof process !== "undefined" ? process.env?.VERCEL_PROTECTION_BYPASS_TOKEN : void 0;
+    if (bypassToken) {
+      headers["x-vercel-protection-bypass"] = bypassToken;
+    }
+    const playArtifactR2Prefix = typeof process !== "undefined" ? process.env?.DEEPLINE_PLAY_ARTIFACT_R2_PREFIX : void 0;
+    if (playArtifactR2Prefix) {
+      headers["x-deepline-play-artifact-r2-prefix"] = playArtifactR2Prefix;
+    }
+    const coordinatorUrl = typeof process !== "undefined" ? process.env?.DEEPLINE_COORDINATOR_URL : void 0;
+    if (coordinatorUrl?.trim()) {
+      headers[COORDINATOR_URL_OVERRIDE_HEADER] = coordinatorUrl.trim();
+    }
+    const workerCallbackUrl = typeof process !== "undefined" ? process.env?.DEEPLINE_WORKER_CALLBACK_URL : void 0;
+    if (workerCallbackUrl?.trim()) {
+      headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
+    }
+    return headers;
+  }
+  /**
+   * Send an HTTP request with automatic retries and error handling.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path (e.g. `"/api/v2/tools"`)
+   * @param options - HTTP method, body, headers, and timeout
+   * @returns Parsed JSON response body
+   * @throws {@link AuthError} on HTTP 401/403 (immediate, no retry)
+   * @throws {@link RateLimitError} on HTTP 429 after all retries exhausted
+   * @throws {@link DeeplineError} on other API errors or connection failures
+   */
+  async request(path, options) {
+    const baseUrl = this.config.baseUrl;
+    const url = `${baseUrl}${path}`;
+    const method = options?.method ?? "GET";
+    const headers = this.authHeaders(options?.headers);
     if (options?.body !== void 0) {
       headers["Content-Type"] = "application/json";
     }
     let lastError = null;
+    const candidateUrls = buildCandidateUrls(url);
+    let retryAfterDelayMs = null;
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
       if (attempt > 0) {
         const backoffMs = Math.min(1e3 * Math.pow(2, attempt - 1), 3e4);
-        await sleep(backoffMs);
+        const delayMs = retryAfterDelayMs === null ? backoffMs : Math.max(backoffMs, retryAfterDelayMs);
+        retryAfterDelayMs = null;
+        await sleep(delayMs);
       }
-      const controller = new AbortController();
-      const timeoutId = setTimeout(
-        () => controller.abort(),
-        options?.timeout ?? this.config.timeout
-      );
+      for (const candidateUrl of candidateUrls) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(
+          () => controller.abort(),
+          options?.timeout ?? this.config.timeout
+        );
+        try {
+          const response = await fetch(candidateUrl, {
+            method,
+            headers,
+            body: options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
+          if (response.status === 401 || response.status === 403) {
+            throw new AuthError();
+          }
+          if (response.status === 429) {
+            const retryAfter = parseRetryAfter(response);
+            lastError = new RateLimitError(retryAfter);
+            if (attempt < this.config.maxRetries) {
+              retryAfterDelayMs = retryAfter;
+              break;
+            }
+            throw lastError;
+          }
+          const body = await response.text();
+          let parsed;
+          try {
+            parsed = JSON.parse(body);
+          } catch {
+            parsed = body;
+          }
+          if (!response.ok) {
+            const msg = typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error) : `HTTP ${response.status}`;
+            throw new DeeplineError(msg, response.status, "API_ERROR", {
+              response: parsed
+            });
+          }
+          return parsed;
+        } catch (error) {
+          clearTimeout(timeoutId);
+          if (error instanceof AuthError || error instanceof DeeplineError) {
+            throw error;
+          }
+          if (error instanceof RateLimitError) {
+            lastError = error;
+            break;
+          }
+          lastError = error instanceof Error ? error : new Error(String(error));
+        }
+      }
+      if (attempt < this.config.maxRetries) continue;
+    }
+    if (lastError instanceof DeeplineError) {
+      throw lastError;
+    }
+    const errorMessage = lastError?.message ? `Unable to connect to ${baseUrl}. ${lastError.message}` : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`;
+    throw new DeeplineError(errorMessage);
+  }
+  /**
+   * Send a GET request.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path (e.g. `"/api/v2/tools"`)
+   */
+  async get(path) {
+    return this.request(path, { method: "GET" });
+  }
+  async *streamSse(path, options) {
+    const url = `${this.config.baseUrl}${path}`;
+    const method = options?.method ?? "GET";
+    const headers = this.authHeaders({
+      Accept: "text/event-stream",
+      ...options?.headers
+    });
+    if (options?.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    let lastError = null;
+    for (const candidateUrl of buildCandidateUrls(url)) {
       try {
-        const response = await fetch(url, {
+        const response = await fetch(candidateUrl, {
           method,
           headers,
           body: options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
-          signal: controller.signal
+          signal: options?.signal
         });
-        clearTimeout(timeoutId);
         if (response.status === 401 || response.status === 403) {
           throw new AuthError();
         }
-        if (response.status === 429) {
-          const retryAfter = parseRetryAfter(response);
-          lastError = new RateLimitError(retryAfter);
-          if (attempt < this.config.maxRetries) continue;
-          throw lastError;
-        }
-        const body = await response.text();
-        let parsed;
-        try {
-          parsed = JSON.parse(body);
-        } catch {
-          parsed = body;
-        }
         if (!response.ok) {
-          const msg = typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error) : `HTTP ${response.status}`;
-          throw new DeeplineError(msg, response.status, "API_ERROR", {
-            response: parsed
-          });
+          throw new DeeplineError(
+            `HTTP ${response.status}`,
+            response.status,
+            "API_ERROR"
+          );
+        }
+        if (!response.body) {
+          throw new DeeplineError("SSE response did not include a body.");
         }
-        return parsed;
+        yield* decodeSseStream(response.body);
+        return;
       } catch (error) {
-        clearTimeout(timeoutId);
         if (error instanceof AuthError || error instanceof DeeplineError) {
           throw error;
         }
-        if (error instanceof RateLimitError) {
-          lastError = error;
-          if (attempt < this.config.maxRetries) continue;
-          throw error;
-        }
         lastError = error instanceof Error ? error : new Error(String(error));
-        if (attempt < this.config.maxRetries) continue;
       }
     }
-    throw lastError ?? new DeeplineError("Request failed after retries");
-  }
-  async get(path) {
-    return this.request(path, { method: "GET" });
+    throw new DeeplineError(
+      lastError?.message ? `Unable to stream from ${this.config.baseUrl}. ${lastError.message}` : `Unable to stream from ${this.config.baseUrl}.`
+    );
   }
+  /**
+   * Send a POST request with a JSON body.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path
+   * @param body - Request body (will be JSON-serialized)
+   */
   async post(path, body) {
     return this.request(path, { method: "POST", body });
   }
+  /**
+   * Send a DELETE request.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path
+   */
+  async delete(path) {
+    return this.request(path, { method: "DELETE" });
+  }
 };
 function parseRetryAfter(response) {
   const header = response.headers.get("retry-after");
@@ -232,27 +408,218 @@ function parseRetryAfter(response) {
   }
   return 5e3;
 }
+function buildCandidateUrls(url) {
+  try {
+    const parsed = new URL(url);
+    const candidates = [url];
+    if (parsed.hostname === "localhost") {
+      const loopback = new URL(url);
+      loopback.hostname = "127.0.0.1";
+      candidates.push(loopback.toString());
+    }
+    return [...new Set(candidates)];
+  } catch {
+    return [url];
+  }
+}
+async function* decodeSseStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      const frames = buffered.split(/\r?\n\r?\n/);
+      buffered = frames.pop() ?? "";
+      for (const frame of frames) {
+        const event2 = decodeSseFrame(frame);
+        if (event2) {
+          yield event2;
+        }
+      }
+    }
+    buffered += decoder.decode();
+    const event = decodeSseFrame(buffered);
+    if (event) {
+      yield event;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function decodeSseFrame(frame) {
+  const data = frame.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice("data:".length).trimStart()).join("\n").trim();
+  if (!data) {
+    return null;
+  }
+  const parsed = JSON.parse(data);
+  if (!parsed || typeof parsed !== "object" || typeof parsed.cursor !== "string" || typeof parsed.streamId !== "string" || typeof parsed.scope !== "string" || typeof parsed.type !== "string" || typeof parsed.at !== "string") {
+    return null;
+  }
+  return parsed;
+}
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // src/client.ts
+var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+function normalizePlayStatus(raw) {
+  const status = typeof raw.status === "string" ? raw.status : typeof raw.temporalStatus === "string" ? mapLegacyTemporalStatus(raw.temporalStatus) : "running";
+  const runId = typeof raw.runId === "string" ? raw.runId : typeof raw.workflowId === "string" ? raw.workflowId : "";
+  return {
+    ...raw,
+    runId,
+    status
+  };
+}
+function mapLegacyTemporalStatus(status) {
+  switch (status.trim().toUpperCase()) {
+    case "PENDING":
+      return "queued";
+    case "COMPLETED":
+      return "completed";
+    case "FAILED":
+      return "failed";
+    case "CANCELLED":
+    case "TERMINATED":
+    case "TIMED_OUT":
+      return "cancelled";
+    case "RUNNING":
+    default:
+      return "running";
+  }
+}
 var DeeplineClient = class {
   http;
   config;
+  /**
+   * @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.
+   */
   constructor(options) {
     this.config = resolveConfig(options);
     this.http = new HttpClient(this.config);
   }
+  /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
   get baseUrl() {
     return this.config.baseUrl;
   }
-  /** List available tools. */
+  compactSchema(schema) {
+    if (!schema) return null;
+    const fields = Array.isArray(schema.fields) ? schema.fields.map(
+      (field) => field && typeof field === "object" ? {
+        name: String(field.name ?? ""),
+        type: field.type ?? void 0,
+        required: field.required ?? void 0
+      } : null
+    ).filter((field) => Boolean(field?.name)) : [];
+    return fields.length > 0 ? { fields } : schema;
+  }
+  playRunCommand(name) {
+    return `deepline plays run ${name} --input '{...}' --watch`;
+  }
+  summarizePlayListItem(play, options) {
+    const aliases = play.aliases?.length ? play.aliases : [play.name];
+    const runCommand = this.playRunCommand(play.name);
+    return {
+      name: play.name,
+      ...play.reference ? { reference: play.reference } : {},
+      ...play.displayName ? { displayName: play.displayName } : {},
+      origin: play.origin,
+      ownerType: play.ownerType,
+      canEdit: play.canEdit,
+      canClone: play.canClone,
+      aliases,
+      inputSchema: options?.compact ? this.compactSchema(play.inputSchema) : play.inputSchema ?? null,
+      outputSchema: options?.compact ? this.compactSchema(play.outputSchema) : play.outputSchema ?? null,
+      runCommand,
+      examples: [runCommand],
+      currentPublishedVersion: play.currentPublishedVersion ?? null,
+      isDraftDirty: play.isDraftDirty
+    };
+  }
+  summarizePlayDetail(detail, options) {
+    const play = detail.play;
+    return {
+      ...this.summarizePlayListItem(play, options),
+      currentPublishedVersion: play.currentPublishedVersion ?? play.liveRevision?.version ?? null,
+      latestRunId: play.latestRunId ?? detail.latestRuns[0]?.workflowId ?? null
+    };
+  }
+  // ——————————————————————————————————————————————————————————
+  // Tools
+  // ——————————————————————————————————————————————————————————
+  /**
+   * List all available tools.
+   *
+   * Returns tool definitions including ID, provider, description, input/output schemas,
+   * and list extractor paths for automatic CSV conversion.
+   *
+   * @returns Array of tool definitions
+   *
+   * @example
+   * ```typescript
+   * const tools = await client.listTools();
+   * const searchTools = tools.filter(t => t.categories.includes('search'));
+   * console.log(`Found ${searchTools.length} search tools`);
+   * ```
+   */
   async listTools() {
-    const res = await this.http.get("/api/v2/tools");
+    const res = await this.http.get(
+      "/api/v2/tools"
+    );
     return res.tools;
   }
-  /** Execute a single tool. */
+  /**
+   * Get detailed metadata for a single tool.
+   *
+   * Returns everything from {@link ToolDefinition} plus pricing info, sample
+   * inputs/outputs, failure modes, and cost estimates.
+   *
+   * @param toolId - Tool identifier (e.g. `"apollo_people_search"`)
+   * @returns Full tool metadata
+   *
+   * @example
+   * ```typescript
+   * const meta = await client.getTool('apollo_people_search');
+   * console.log(`Cost: ${meta.estimatedCreditsRange} credits`);
+   * console.log(`Input schema:`, meta.inputSchema);
+   * ```
+   */
+  async getTool(toolId) {
+    return this.http.request(
+      `/api/v2/integrations/${encodeURIComponent(toolId)}/get`,
+      {
+        method: "GET",
+        headers: {
+          "x-deepline-tool-meta-only": "1"
+        }
+      }
+    );
+  }
+  /**
+   * Execute a tool and return the extracted result.
+   *
+   * Sends the input payload to the tool and returns the `.result` field from the
+   * response. For the full response envelope (including job_id, credits, etc.),
+   * use {@link executeToolRaw}.
+   *
+   * @param toolId - Tool identifier (e.g. `"test_company_search"`)
+   * @param input - Tool-specific input parameters
+   * @returns The tool's output (shape varies by tool)
+   * @throws {@link DeeplineError} if the tool execution fails
+   *
+   * @example
+   * ```typescript
+   * const company = await client.executeTool('test_company_search', {
+   *   domain: 'stripe.com',
+   * });
+   * console.log(company); // { name: "Stripe", industry: "Financial Services", ... }
+   * ```
+   */
   async executeTool(toolId, input) {
     const res = await this.http.post(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
@@ -261,38 +628,602 @@ var DeeplineClient = class {
     return res.result ?? res;
   }
   /**
-   * Submit a play for cloud execution.
-   * Returns a workflowId. Use pollPlay() to get status.
+   * Execute a tool and return the full response envelope.
+   *
+   * Unlike {@link executeTool}, this returns the complete API response including
+   * `job_id`, `status`, `credits`, and the raw `result` object.
+   *
+   * @param toolId - Tool identifier
+   * @param input - Tool-specific input parameters
+   * @returns Full response with job metadata and result
+   *
+   * @example
+   * ```typescript
+   * const raw = await client.executeToolRaw('test_company_search', { domain: 'stripe.com' });
+   * console.log(`Job: ${raw.job_id}, Credits: ${raw.credits}`);
+   * console.log(`Result:`, raw.result);
+   * ```
+   */
+  async executeToolRaw(toolId, input) {
+    return this.http.post(
+      `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
+      { payload: input }
+    );
+  }
+  async queryCustomerDb(input) {
+    return this.http.post("/api/v2/db/query", {
+      sql: input.sql,
+      ...input.maxRows ? { max_rows: input.maxRows } : {}
+    });
+  }
+  // ——————————————————————————————————————————————————————————
+  // Plays — submission and lifecycle
+  // ——————————————————————————————————————————————————————————
+  /**
+   * Start a play run.
+   *
+   * Internal/advanced primitive. For normal callers, prefer the public
+   * entrypoints: the CLI, {@link Deepline.connect}, {@link submitPlay},
+   * or {@link runPlay}.
+   *
+   * Supported invocation surfaces intentionally share this same run contract:
+   * `deepline play run`, repo scripts such as `bun run deepline -- play run`,
+   * SDK context calls like `Deepline.connect().play(name).run()`, and direct
+   * `POST /api/v2/plays/run` calls all return a workflow/run id. The completed
+   * output is always retrievable from `getPlayStatus(runId).result` (or from
+   * `PlayJob.get()` for SDK context calls). Execution logs live under
+   * `progress.logs`; they are not part of the user output object.
+   *
+   * @param request - Play run configuration (name, code, input, etc.)
+   * @returns Workflow metadata including the `workflowId` for status polling
+   *
+   * @example
+   * ```typescript
+   * // Run a live play by name:
+   * const started = await client.startPlayRun({
+   *   name: 'email-waterfall',
+   *   input: { linkedin_url: 'https://linkedin.com/in/jdoe', domain: 'acme.com' },
+   * });
+   * console.log(`Workflow: ${started.workflowId}`);
+   *
+   * // Run an ad hoc artifact-backed play:
+   * const started2 = await client.startPlayRun({
+   *   artifactStorageKey: 'plays/v1/orgs/acme/plays/my-play/artifacts/playgraph_abc123.json',
+   * });
+   * ```
    */
-  async submitPlay(code, csvPath, name) {
+  async startPlayRun(request) {
     return this.http.post("/api/v2/plays/run", {
-      code,
-      csvPath,
-      name
+      ...request.name ? { name: request.name } : {},
+      ...request.revisionId ? { revisionId: request.revisionId } : {},
+      ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
+      ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
+      ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
+      ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
+      ...request.graphHash ? { graphHash: request.graphHash } : {},
+      ...request.runtimeArtifact ? { runtimeArtifact: request.runtimeArtifact } : {},
+      ...request.compilerManifest ? { compilerManifest: request.compilerManifest } : {},
+      ...request.inputFileUpload ? { inputFileUpload: request.inputFileUpload } : {},
+      ...request.packagedFileUploads?.length ? { packagedFileUploads: request.packagedFileUploads } : {},
+      ...request.input ? { input: request.input } : {},
+      ...request.inputFile ? { inputFile: request.inputFile } : {},
+      ...request.packagedFiles?.length ? { packagedFiles: request.packagedFiles } : {},
+      ...request.force ? { force: true } : {},
+      ...typeof request.waitForCompletionMs === "number" ? { waitForCompletionMs: request.waitForCompletionMs } : {},
+      // Profile selection is the API's job, not the CLI's. The server
+      // hardcodes workers_edge as the default; tests that want a
+      // different profile pass `request.profile` explicitly.
+      ...request.profile ? { profile: request.profile } : {}
+    });
+  }
+  async *startPlayRunStream(request, options) {
+    const body = {
+      ...request.name ? { name: request.name } : {},
+      ...request.revisionId ? { revisionId: request.revisionId } : {},
+      ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
+      ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
+      ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
+      ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
+      ...request.graphHash ? { graphHash: request.graphHash } : {},
+      ...request.runtimeArtifact ? { runtimeArtifact: request.runtimeArtifact } : {},
+      ...request.compilerManifest ? { compilerManifest: request.compilerManifest } : {},
+      ...request.inputFileUpload ? { inputFileUpload: request.inputFileUpload } : {},
+      ...request.packagedFileUploads?.length ? { packagedFileUploads: request.packagedFileUploads } : {},
+      ...request.input ? { input: request.input } : {},
+      ...request.inputFile ? { inputFile: request.inputFile } : {},
+      ...request.packagedFiles?.length ? { packagedFiles: request.packagedFiles } : {},
+      ...request.force ? { force: true } : {},
+      ...request.profile ? { profile: request.profile } : {}
+    };
+    for await (const event of this.http.streamSse(
+      "/api/v2/plays/run?stream=true",
+      {
+        method: "POST",
+        body,
+        signal: options?.signal
+      }
+    )) {
+      if (event.scope === "play") {
+        yield event;
+      }
+    }
+  }
+  /**
+   * Register a bundled play artifact.
+   *
+   * Internal/advanced primitive used by packaging flows. Public callers should
+   * prefer the CLI, {@link submitPlay}, or {@link runPlay}.
+   */
+  async registerPlayArtifact(input) {
+    const compilerManifest = input.compilerManifest ?? await this.compilePlayManifest({
+      name: input.name,
+      sourceCode: input.sourceCode,
+      artifact: input.artifact
+    });
+    return this.http.post("/api/v2/plays/artifacts", {
+      ...input,
+      compilerManifest
+    });
+  }
+  async registerPlayArtifacts(artifacts) {
+    const compiledArtifacts = await Promise.all(
+      artifacts.map(async (artifact) => ({
+        ...artifact,
+        compilerManifest: artifact.compilerManifest ?? await this.compilePlayManifest({
+          name: artifact.name,
+          sourceCode: artifact.sourceCode,
+          artifact: artifact.artifact
+        })
+      }))
+    );
+    return this.http.post("/api/v2/plays/artifacts", {
+      artifacts: compiledArtifacts
+    });
+  }
+  async compilePlayManifest(input) {
+    const response = await this.http.post("/api/v2/plays/compile-manifest", input);
+    return response.compilerManifest;
+  }
+  /**
+   * Check a bundled play artifact against the server's current play compiler.
+   *
+   * Unlike {@link registerPlayArtifact}, this does not store the artifact,
+   * publish a revision, or start a run. It is the authoritative cloud validation
+   * path used by `deepline play check`.
+   */
+  async checkPlayArtifact(input) {
+    return this.http.post("/api/v2/plays/check", input);
+  }
+  async startPlayRunFromBundle(input) {
+    const compilerManifest = input.compilerManifest ?? await this.compilePlayManifest({
+      name: input.name,
+      sourceCode: input.sourceCode,
+      artifact: input.artifact
+    });
+    const registeredArtifact = await this.registerPlayArtifact({
+      name: input.name,
+      sourceCode: input.sourceCode,
+      artifact: input.artifact,
+      compilerManifest,
+      publish: false
     });
+    if (!registeredArtifact.artifactStorageKey) {
+      throw new Error(
+        "registerPlayArtifact did not return an artifactStorageKey."
+      );
+    }
+    return this.startPlayRun({
+      name: input.name,
+      artifactStorageKey: registeredArtifact.artifactStorageKey,
+      compilerManifest,
+      ...input.input ? { input: input.input } : {},
+      ...input.inputFile ? { inputFile: input.inputFile } : {},
+      ...input.packagedFiles?.length ? { packagedFiles: input.packagedFiles } : {},
+      ...input.force ? { force: true } : {}
+    });
+  }
+  /**
+   * Register a bundled play artifact and start a run from the live revision.
+   *
+   * Convenience wrapper around {@link registerPlayArtifact} plus
+   * {@link startPlayRun}. This is the canonical file-backed path used by wrappers.
+   * The returned id can be passed to {@link getPlayStatus} to retrieve the same
+   * durable `{ result }` object that the CLI prints after `--watch` completes.
+   *
+   * @param code - Source string fallback; the bundled artifact should be passed in `options.artifact`
+   * @param csvPath - Path to input CSV file, or `null`
+   * @param name - Play name (extracted from source if omitted)
+   * @param options - Additional submission options
+   * @returns Workflow metadata with `workflowId`
+   *
+   * @example
+   * ```typescript
+   * const started = await client.submitPlay(
+   *   originalSource,
+   *   './leads.csv',
+   *   'bulk-enrich',
+   *   { artifact: bundledArtifact, input: { limit: 100 } },
+   * );
+   * ```
+   */
+  async submitPlay(code, csvPath, name, options) {
+    const runtimeInput = options?.input ? { ...options.input } : {};
+    if (csvPath) {
+      runtimeInput.file = csvPath;
+    }
+    const sourceCode = options?.sourceCode ?? code;
+    const artifact = options?.artifact;
+    if (!name?.trim()) {
+      throw new Error("submitPlay requires a play name.");
+    }
+    if (!artifact) {
+      throw new Error("submitPlay requires a bundled play artifact.");
+    }
+    const compilerManifest = options?.compilerManifest ?? await this.compilePlayManifest({
+      name,
+      sourceCode,
+      artifact
+    });
+    const registeredArtifact = await this.registerPlayArtifact({
+      name,
+      sourceCode,
+      artifact,
+      compilerManifest,
+      publish: false
+    });
+    if (!registeredArtifact.artifactStorageKey) {
+      throw new Error(
+        "registerPlayArtifact did not return an artifactStorageKey."
+      );
+    }
+    return this.startPlayRun({
+      name,
+      artifactStorageKey: registeredArtifact.artifactStorageKey,
+      sourceCode,
+      staticPipeline: registeredArtifact.staticPipeline ?? null,
+      artifactHash: typeof artifact.artifactHash === "string" ? artifact.artifactHash : void 0,
+      graphHash: typeof artifact.graphHash === "string" ? artifact.graphHash : void 0,
+      runtimeArtifact: artifact,
+      compilerManifest,
+      ...Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {},
+      ...options?.inputFile ? { inputFile: options.inputFile } : {},
+      ...options?.packagedFiles?.length ? { packagedFiles: options.packagedFiles } : {},
+      ...options?.force ? { force: true } : {}
+    });
+  }
+  /**
+   * Upload files to the staging area for use in play runs.
+   *
+   * Internal/advanced primitive used by packaging flows. Public callers should
+   * prefer the CLI, {@link submitPlay}, or {@link runPlay}.
+   *
+   * Staged files are referenced by their returned {@link PlayStagedFileRef}
+   * in subsequent {@link startPlayRun} calls via `inputFile` or `packagedFiles`.
+   *
+   * @param files - Array of files to stage (base64-encoded content)
+   * @returns Array of staged file references
+   *
+   * @example
+   * ```typescript
+   * const staged = await client.stagePlayFiles([{
+   *   logicalPath: 'data/leads.csv',
+   *   contentBase64: Buffer.from(csvContent).toString('base64'),
+   *   contentHash: sha256(csvContent),
+   *   contentType: 'text/csv',
+   *   bytes: csvContent.length,
+   * }]);
+   * // Use staged[0] as inputFile in startPlayRun
+   * ```
+   */
+  async stagePlayFiles(files) {
+    const response = await this.http.post(
+      "/api/v2/plays/files/stage",
+      { files }
+    );
+    return response.files;
   }
-  /** Poll workflow status. */
+  async resolveStagedPlayFiles(files) {
+    return this.http.post("/api/v2/plays/files/stage", { files });
+  }
+  // ——————————————————————————————————————————————————————————
+  // Plays — status and monitoring
+  // ——————————————————————————————————————————————————————————
+  /**
+   * Get the current status of a play execution.
+   *
+   * Internal/advanced primitive. Public callers should usually prefer
+   * {@link runPlay}, {@link PlayJob.get}, or `deepline play run --watch`.
+   *
+   * Poll this method until `status` reaches a terminal state:
+   * `'completed'`, `'failed'`, or `'cancelled'`.
+   *
+   * @param workflowId - Play-run id from {@link startPlayRun}
+   * @returns Current status with progress logs and partial results
+   *
+   * @example
+   * ```typescript
+   * const status = await client.getPlayStatus('play-abc123');
+   * console.log(`Status: ${status.status}`);
+   * console.log(`Logs: ${status.progress?.logs.length ?? 0} lines`);
+   * ```
+   */
   async getPlayStatus(workflowId) {
-    return this.http.get(`/api/v2/plays/run/${workflowId}`);
+    const response = await this.http.get(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}`
+    );
+    return normalizePlayStatus(response);
   }
-  /** Cancel a running play. */
+  /**
+   * Get the lightweight tail-polling status for a play execution.
+   *
+   * This is intentionally smaller than {@link getPlayStatus}: it returns the
+   * fields needed for CLI log tailing while the run is in flight, without
+   * forcing the API to rebuild final result views on every poll. Call
+   * {@link getPlayStatus} once after a terminal state for the full result.
+   */
+  async getPlayTailStatus(workflowId, options) {
+    const params = new URLSearchParams({ mode: "tail" });
+    if (typeof options?.afterLogIndex === "number") {
+      params.set("afterLogIndex", String(options.afterLogIndex));
+    }
+    if (typeof options?.waitMs === "number") {
+      params.set("waitMs", String(options.waitMs));
+    }
+    if (options?.terminalOnly) {
+      params.set("terminalOnly", "true");
+    }
+    const response = await this.http.get(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}?${params.toString()}`
+    );
+    return normalizePlayStatus(response);
+  }
+  /**
+   * Stream semantic play-run events using the same SSE feed as the dashboard.
+   *
+   * Consumers should still keep a polling fallback: SSE is the fast live-update
+   * transport, while the status endpoints remain the authoritative recovery path.
+   */
+  async *streamPlayRunEvents(workflowId, options) {
+    const headers = options?.lastEventId && options.lastEventId.trim() ? { "Last-Event-ID": options.lastEventId.trim() } : void 0;
+    const params = new URLSearchParams({ stream: "true" });
+    params.set("mode", options?.mode ?? "cli");
+    for await (const event of this.http.streamSse(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}?${params.toString()}`,
+      { signal: options?.signal, headers }
+    )) {
+      if (event.scope === "play") {
+        yield event;
+      }
+    }
+  }
+  /**
+   * Cancel a running play execution.
+   *
+   * Sends a stop request for the run.
+   *
+   * @param workflowId - Temporal workflow ID to cancel
+   *
+   * @example
+   * ```typescript
+   * await client.cancelPlay('play-abc123');
+   * ```
+   */
   async cancelPlay(workflowId) {
-    await this.http.request(`/api/v2/plays/run/${workflowId}`, { method: "DELETE" });
+    await this.http.request(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}/stop`,
+      { method: "POST" }
+    );
+  }
+  /**
+   * Stop a running play execution, including open HITL waits.
+   *
+   * @param workflowId - Temporal workflow ID to stop
+   * @param options.reason - Optional audit/debug reason
+   */
+  async stopPlay(workflowId, options) {
+    return this.http.post(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}/stop`,
+      options?.reason ? { reason: options.reason } : {}
+    );
+  }
+  /**
+   * List recent runs for a named play.
+   *
+   * Returns runs sorted by start time (newest first), including workflow IDs,
+   * status, timestamps, and metadata.
+   *
+   * @param playName - The play name to query
+   * @returns Array of run summaries (empty array if no runs exist)
+   *
+   * @example
+   * ```typescript
+   * const runs = await client.listPlayRuns('email-waterfall');
+   * for (const run of runs) {
+   *   console.log(`${run.workflowId}: ${run.status} (${run.executionTime})`);
+   * }
+   * ```
+   */
+  async listPlayRuns(playName) {
+    const encodedName = encodeURIComponent(playName);
+    const response = await this.http.get(
+      `/api/v2/plays/${encodedName}/runs`
+    );
+    return response.runs ?? [];
+  }
+  async listPlays() {
+    const response = await this.http.get(
+      "/api/v2/plays"
+    );
+    return response.plays ?? [];
+  }
+  async searchPlays(options) {
+    const query = options.query.trim().toLowerCase();
+    const terms = query.split(/\s+/).filter(Boolean);
+    const plays = await this.listPlays();
+    return plays.filter((play) => {
+      if (options.origin && (play.origin ?? "owned") !== options.origin) {
+        return false;
+      }
+      const haystack = [
+        play.name,
+        play.reference,
+        play.displayName,
+        play.origin,
+        ...play.aliases ?? [],
+        play.inputSchema ? JSON.stringify(play.inputSchema) : ""
+      ].filter(Boolean).join(" ").toLowerCase();
+      return terms.every((term) => haystack.includes(term));
+    }).map((play) => this.summarizePlayListItem(play, options));
+  }
+  /**
+   * Get the full definition and state of a named play.
+   *
+   * Returns the play's revision state (draft, live), recent runs,
+   * sheet processing summary, and database URL.
+   *
+   * @param name - Play name
+   * @returns Complete play detail
+   *
+   * @example
+   * ```typescript
+   * const detail = await client.getPlay('email-waterfall');
+   * console.log(`Live: v${detail.play.currentPublishedVersion}`);
+   * console.log(`Draft dirty: ${detail.play.isDraftDirty}`);
+   * console.log(`Total runs: ${detail.play.runCount}`);
+   * ```
+   */
+  async getPlay(name) {
+    const encodedName = encodeURIComponent(name);
+    return this.http.get(`/api/v2/plays/${encodedName}`);
+  }
+  async describePlay(name, options) {
+    const detail = await this.getPlay(name);
+    return this.summarizePlayDetail(detail, options);
+  }
+  /**
+   * Clear run history and durable sheet/result data for a play without deleting
+   * the play definition or revisions.
+   */
+  async clearPlayHistory(name, request = {}) {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post(
+      `/api/v2/plays/${encodedName}/history/clear`,
+      request
+    );
   }
   /**
-   * Run a play end-to-end: submit, poll until done, return result.
-   * onProgress is called on each poll with current status.
+   * List saved versions for a named play.
+   *
+   * Returns immutable revision snapshots newest-first, including the revision
+   * id needed for exact-version runs and live-version switching.
+   *
+   * @param name - Play name
+   * @returns Version list (newest first)
+   */
+  async listPlayVersions(name) {
+    const encodedName = encodeURIComponent(name);
+    const response = await this.http.get(
+      `/api/v2/plays/${encodedName}/versions`
+    );
+    return response.versions ?? [];
+  }
+  /**
+   * Make a play revision live.
+   *
+   * When `revisionId` is omitted, the current working revision becomes live.
+   * The live version is what executes when the play is run by name without
+   * specifying an explicit revision.
+   *
+   * @param name - Play name
+   * @param request - Optional explicit revision to make live
+   * @returns Result with the new live version number
+   *
+   * @example
+   * ```typescript
+   * const result = await client.publishPlayVersion('email-waterfall');
+   * if (result.success) {
+   *   console.log(`Live v${result.liveVersion}`);
+   * }
+   * ```
+   */
+  async publishPlayVersion(name, request = {}) {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post(
+      `/api/v2/plays/${encodedName}/live`,
+      request
+    );
+  }
+  /**
+   * Delete an org-owned play definition, including its revisions, trigger
+   * bindings, and local run records. Deepline prebuilt plays are read-only.
+   */
+  async deletePlay(name) {
+    const encodedName = encodeURIComponent(name);
+    return this.http.delete(`/api/v2/plays/${encodedName}`);
+  }
+  // ——————————————————————————————————————————————————————————
+  // Plays — high-level orchestration
+  // ——————————————————————————————————————————————————————————
+  /**
+   * Run a play end-to-end: submit, poll until terminal, return result.
+   *
+   * This is the highest-level play execution method. It submits the play,
+   * polls for status updates, and returns a structured result with logs
+   * and timing. Supports cancellation via `AbortSignal`.
+   *
+   * @param code - Source string fallback; pass the bundled artifact in `options.artifact`
+   * @param csvPath - Input CSV path, or `null`
+   * @param name - Play name
+   * @param options - Execution options
+   * @returns Final execution result with success/failure, output, logs, and duration
+   *
+   * @example
+   * ```typescript
+   * const result = await client.runPlay(bundledCode, null, 'my-play', {
+   *   input: { domain: 'stripe.com' },
+   *   onProgress: (status) => {
+   *     const logs = status.progress?.logs ?? [];
+   *     console.log(`[${status.status}] ${logs.length} log lines`);
+   *   },
+   *   pollIntervalMs: 1000,
+   * });
+   *
+   * if (result.success) {
+   *   console.log('Output:', result.result);
+   * } else {
+   *   console.error(`Failed after ${result.durationMs}ms:`, result.error);
+   * }
+   * ```
+   *
+   * @example Cancellation
+   * ```typescript
+   * const controller = new AbortController();
+   * setTimeout(() => controller.abort(), 30_000); // 30s timeout
+   *
+   * const result = await client.runPlay(code, null, 'slow-play', {
+   *   signal: controller.signal,
+   * });
+   * // result.success === false, result.error === 'Cancelled by user'
+   * ```
    */
   async runPlay(code, csvPath, name, options) {
-    const { workflowId } = await this.submitPlay(code, csvPath, name);
-    const pollInterval = options?.pollIntervalMs ?? 2e3;
+    const { workflowId } = await this.submitPlay(code, csvPath, name, {
+      input: options?.input,
+      sourceCode: options?.sourceCode,
+      artifact: options?.artifact,
+      compilerManifest: options?.compilerManifest,
+      inputFile: options?.inputFile,
+      packagedFiles: options?.packagedFiles,
+      force: options?.force
+    });
+    const pollInterval = options?.pollIntervalMs ?? 500;
     const start = Date.now();
     while (true) {
       if (options?.signal?.aborted) {
         await this.cancelPlay(workflowId);
         return {
           success: false,
-          workflowId,
+          runId: workflowId,
           logs: [],
           durationMs: Date.now() - start,
           error: "Cancelled by user"
@@ -300,33 +1231,651 @@ var DeeplineClient = class {
       }
       const status = await this.getPlayStatus(workflowId);
       options?.onProgress?.(status);
-      const terminal = ["COMPLETED", "FAILED", "CANCELLED", "TERMINATED", "TIMED_OUT"];
-      if (terminal.includes(status.temporalStatus)) {
+      if (TERMINAL_PLAY_STATUSES.has(status.status)) {
         return {
-          success: status.temporalStatus === "COMPLETED",
-          workflowId,
+          success: status.status === "completed",
+          runId: status.runId || workflowId,
           result: status.result,
           logs: status.progress?.logs ?? [],
           durationMs: Date.now() - start,
-          error: status.progress?.error ?? (status.temporalStatus !== "COMPLETED" ? status.temporalStatus : void 0)
+          error: status.progress?.error ?? (status.status !== "completed" ? status.status : void 0)
         };
       }
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
     }
   }
-  /** Health check. */
+  // ——————————————————————————————————————————————————————————
+  // Health
+  // ——————————————————————————————————————————————————————————
+  /**
+   * Check API connectivity and server health.
+   *
+   * @returns Health status with API version
+   *
+   * @example
+   * ```typescript
+   * const health = await client.health();
+   * console.log(`API: ${health.status} (${health.version})`);
+   * // { status: "ok", version: "v2" }
+   * ```
+   */
   async health() {
-    return this.http.get("/api/v2/health");
+    return this.http.get(
+      "/api/v2/health"
+    );
+  }
+};
+
+// src/tool-output.ts
+var import_node_fs2 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var PHONE_KEY_PATTERN = /(^|[_-])(phone|mobile|cell|telephone|tel)([_-]|$)|phone|mobile|telephone/i;
+function normalizeScalarString(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  return null;
+}
+function looksLikeEmail(value) {
+  const candidate = normalizeScalarString(value);
+  if (!candidate || !EMAIL_PATTERN.test(candidate)) return null;
+  return candidate;
+}
+function looksLikePhone(value) {
+  const candidate = normalizeScalarString(value);
+  if (!candidate) return null;
+  const digits = candidate.replace(/\D/g, "");
+  if (digits.length < 7 || digits.length > 16) return null;
+  return candidate;
+}
+function findEmail(value, depth = 0) {
+  if (depth > 6) return null;
+  const direct = looksLikeEmail(value);
+  if (direct) return direct;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const nested = findEmail(entry, depth + 1);
+      if (nested) return nested;
+    }
+    return null;
+  }
+  if (!isPlainObject(value)) return null;
+  for (const [key, child] of Object.entries(value)) {
+    if (/email/i.test(key)) {
+      const keyed = looksLikeEmail(child);
+      if (keyed) return keyed;
+    }
+  }
+  for (const child of Object.values(value)) {
+    const nested = findEmail(child, depth + 1);
+    if (nested) return nested;
+  }
+  return null;
+}
+function findPhone(value, depth = 0) {
+  if (depth > 6) return null;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const nested = findPhone(entry, depth + 1);
+      if (nested) return nested;
+    }
+    return null;
+  }
+  if (!isPlainObject(value)) return null;
+  for (const [key, child] of Object.entries(value)) {
+    if (PHONE_KEY_PATTERN.test(key)) {
+      const keyed = looksLikePhone(child);
+      if (keyed) return keyed;
+    }
+  }
+  for (const child of Object.values(value)) {
+    const nested = findPhone(child, depth + 1);
+    if (nested) return nested;
+  }
+  return null;
+}
+var DeeplineToolCallResult = class {
+  constructor(value) {
+    this.value = value;
+  }
+  value;
+  getEmail() {
+    return findEmail(this.value);
+  }
+  getPhone() {
+    return findPhone(this.value);
+  }
+  tryList(options) {
+    return tryConvertToList(this.value, options)?.rows ?? null;
+  }
+};
+function createToolCallResult(value) {
+  return new DeeplineToolCallResult(value);
+}
+function getByDottedPath(root, dottedPath) {
+  let current = root;
+  for (const segment of String(dottedPath || "").split(".").filter(Boolean)) {
+    if (!isPlainObject(current) || !(segment in current)) {
+      return null;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function normalizeRows(value) {
+  if (!Array.isArray(value)) return null;
+  return value.map((entry) => {
+    if (isPlainObject(entry)) return entry;
+    return { value: entry };
+  });
+}
+function candidateRoots(payload) {
+  const roots = [{ path: null, value: payload }];
+  if (isPlainObject(payload) && isPlainObject(payload.result)) {
+    roots.push({ path: "result", value: payload.result });
+    if (isPlainObject(payload.result.data)) {
+      roots.push({ path: "result.data", value: payload.result.data });
+    }
+  }
+  return roots;
+}
+function findBestArrayCandidate(value, pathPrefix = "", depth = 0) {
+  if (depth > 5) return null;
+  const directRows = normalizeRows(value);
+  const hasObjectRow = directRows?.some((row) => Object.keys(row).some((key) => key !== "value")) ?? false;
+  let best = directRows && directRows.length > 0 && hasObjectRow ? { path: pathPrefix, rows: directRows } : null;
+  if (!isPlainObject(value)) {
+    return best;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = pathPrefix ? `${pathPrefix}.${key}` : key;
+    const candidate = findBestArrayCandidate(child, childPath, depth + 1);
+    if (!candidate) continue;
+    if (!best || candidate.rows.length > best.rows.length) {
+      best = candidate;
+    }
+  }
+  return best;
+}
+function tryConvertToList(payload, options) {
+  const listExtractorPaths = Array.isArray(options?.listExtractorPaths) ? options?.listExtractorPaths.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
+  if (listExtractorPaths.length > 0) {
+    for (const root of candidateRoots(payload)) {
+      for (const extractorPath of listExtractorPaths) {
+        const resolved = getByDottedPath(root.value, extractorPath);
+        const rows = normalizeRows(resolved);
+        if (rows && rows.length > 0) {
+          const sourcePath = root.path ? `${root.path}.${extractorPath}` : extractorPath;
+          return { rows, strategy: "configured_paths", sourcePath };
+        }
+      }
+    }
+  }
+  for (const root of candidateRoots(payload)) {
+    const candidate = findBestArrayCandidate(root.value, root.path ?? "");
+    if (!candidate || candidate.rows.length === 0) continue;
+    return {
+      rows: candidate.rows,
+      strategy: "auto_detected",
+      sourcePath: candidate.path || root.path
+    };
+  }
+  return null;
+}
+function ensureOutputDir() {
+  const outputDir = (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".local", "share", "deepline", "data");
+  (0, import_node_fs2.mkdirSync)(outputDir, { recursive: true });
+  return outputDir;
+}
+function writeJsonOutputFile(payload, stem) {
+  const outputDir = ensureOutputDir();
+  const outputPath = (0, import_node_path2.join)(outputDir, `${stem}_${Date.now()}.json`);
+  (0, import_node_fs2.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
+  return outputPath;
+}
+function writeCsvOutputFile(rows, stem) {
+  const outputDir = ensureOutputDir();
+  const outputPath = (0, import_node_path2.join)(outputDir, `${stem}_${Date.now()}.csv`);
+  const seen = /* @__PURE__ */ new Set();
+  const columns = [];
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        columns.push(key);
+      }
+    }
+  }
+  const escapeCell = (value) => {
+    const normalized = value == null ? "" : typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : JSON.stringify(value);
+    if (/[",\n]/.test(normalized)) {
+      return `"${normalized.replace(/"/g, '""')}"`;
+    }
+    return normalized;
+  };
+  const lines = [];
+  lines.push(columns.map(escapeCell).join(","));
+  for (const row of rows) {
+    lines.push(columns.map((column) => escapeCell(row[column])).join(","));
+  }
+  (0, import_node_fs2.writeFileSync)(outputPath, `${lines.join("\n")}
+`, "utf-8");
+  const previewRows = rows.slice(0, 5);
+  const previewColumns = columns.slice(0, 5);
+  const preview = [
+    previewColumns.join(","),
+    ...previewRows.map((row) => previewColumns.map((column) => escapeCell(row[column])).join(","))
+  ].join("\n");
+  return {
+    path: outputPath,
+    rowCount: rows.length,
+    columns,
+    preview
+  };
+}
+function extractSummaryFields(payload) {
+  const candidates = candidateRoots(payload);
+  for (const candidate of candidates) {
+    if (!isPlainObject(candidate.value)) continue;
+    const summaryEntries = Object.entries(candidate.value).filter(([, value]) => {
+      return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+    });
+    if (summaryEntries.length === 0) continue;
+    return Object.fromEntries(summaryEntries);
+  }
+  return {};
+}
+
+// src/play.ts
+var DeeplineConditionalStepResolver = class _DeeplineConditionalStepResolver {
+  constructor(when2, run, elseValue) {
+    this.when = when2;
+    this.run = run;
+    this.elseValue = elseValue;
+  }
+  when;
+  run;
+  elseValue;
+  kind = "conditional";
+  else(value) {
+    return new _DeeplineConditionalStepResolver(this.when, this.run, value);
+  }
+};
+var DeeplineStepProgram = class _DeeplineStepProgram {
+  constructor(steps2, returnResolver) {
+    this.steps = steps2;
+    this.returnResolver = returnResolver;
+  }
+  steps;
+  returnResolver;
+  kind = "steps";
+  step(name, resolver) {
+    if (!name.trim()) {
+      throw new Error(
+        "steps().step(name, ...) requires a non-empty step name."
+      );
+    }
+    return new _DeeplineStepProgram(
+      [
+        ...this.steps,
+        {
+          name,
+          resolver
+        }
+      ],
+      this.returnResolver
+    );
+  }
+  return(resolver) {
+    return new _DeeplineStepProgram(this.steps, resolver);
+  }
+};
+function steps() {
+  return new DeeplineStepProgram([]);
+}
+function when(predicate, resolver) {
+  return new DeeplineConditionalStepResolver(predicate, resolver, null);
+}
+var PLAY_METADATA_SYMBOL = /* @__PURE__ */ Symbol.for("deepline.play.metadata");
+var DeeplinePlayJobImpl = class {
+  constructor(client, runId) {
+    this.client = client;
+    this.id = runId;
+  }
+  client;
+  id;
+  async status() {
+    return this.client.getPlayStatus(this.id);
+  }
+  async tail(options) {
+    const intervalMs = options?.intervalMs ?? 500;
+    const onLog = options?.onLog ?? ((line) => console.log(line));
+    const terminalStates = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+    let lastLogIndex = 0;
+    while (true) {
+      const status = await this.status();
+      const logs = status.progress?.logs ?? [];
+      for (let index = lastLogIndex; index < logs.length; index += 1) {
+        onLog(logs[index]);
+      }
+      lastLogIndex = logs.length;
+      if (terminalStates.has(status.status)) {
+        return status;
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, intervalMs));
+    }
+  }
+  async get(options) {
+    const intervalMs = options?.intervalMs ?? 500;
+    const terminalStates = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+    while (true) {
+      const status = await this.status();
+      if (terminalStates.has(status.status)) {
+        if (status.status !== "completed") {
+          throw new DeeplineError(
+            status.progress?.error || `Play run ${this.id} ended with ${status.status}.`
+          );
+        }
+        const payload = status.result;
+        return (payload && "output" in payload ? payload.output : status.result) ?? null;
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, intervalMs));
+    }
+  }
+  async cancel() {
+    await this.client.cancelPlay(this.id);
+  }
+  async stop(options) {
+    return this.client.stopPlay(this.id, options);
+  }
+};
+function createNamedPlayHandle(clientFactory, name) {
+  return {
+    name,
+    get: () => clientFactory().getPlay(name),
+    runs: () => clientFactory().listPlayRuns(name),
+    versions: () => clientFactory().listPlayVersions(name),
+    publish: (options) => clientFactory().publishPlayVersion(name, options),
+    clearHistory: (options) => clientFactory().clearPlayHistory(name, options),
+    async run(input, options) {
+      const client = clientFactory();
+      const started = await client.startPlayRun({
+        name,
+        ...options?.revisionId ? { revisionId: options.revisionId } : {},
+        input
+      });
+      return new DeeplinePlayJobImpl(client, started.workflowId);
+    },
+    async runSync(input, options) {
+      const job = await this.run(input, options);
+      return job.get();
+    }
+  };
+}
+var DeeplineContext = class {
+  client;
+  constructor(options) {
+    this.client = new DeeplineClient(options);
+  }
+  /**
+   * Tool operations namespace.
+   *
+   * @example
+   * ```typescript
+   * const tools = await ctx.tools.list();
+   * const meta = await ctx.tools.get('apollo_people_search');
+   * const result = await ctx.tools.execute({
+   *   tool: 'test_company_search',
+   *   input: { domain: 'stripe.com' },
+   * });
+   * const rows = result.tryList({ listExtractorPaths: ['people'] });
+   * const email = result.getEmail();
+   * ```
+   */
+  get tools() {
+    return {
+      /** List all available tools. */
+      list: () => this.client.listTools(),
+      /** Get detailed metadata for a tool. */
+      get: (toolId) => this.client.getTool(toolId),
+      /** Execute a tool and return an ergonomic result wrapper. */
+      execute: async (request) => createToolCallResult(
+        await this.client.executeTool(request.tool, request.input)
+      )
+    };
+  }
+  get plays() {
+    return {
+      list: () => this.client.listPlays(),
+      get: (name) => this.play(name)
+    };
+  }
+  get prebuilt() {
+    const explicit = {
+      companyToContact: {
+        playName: "prebuilt/company-to-contact",
+        name: "prebuilt/company-to-contact"
+      },
+      personToPhone: {
+        playName: "prebuilt/person-to-phone",
+        name: "prebuilt/person-to-phone"
+      },
+      personToEmail: {
+        playName: "prebuilt/person-to-email",
+        name: "prebuilt/person-to-email"
+      },
+      personLinkedinToEmail: {
+        playName: "prebuilt/person-linkedin-to-email",
+        name: "prebuilt/person-linkedin-to-email"
+      }
+    };
+    return new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (typeof prop !== "string") return void 0;
+          if (prop in explicit) {
+            return explicit[prop];
+          }
+          const playName = prop.startsWith("prebuilt/") ? prop : `prebuilt/${prop}`;
+          return {
+            playName,
+            name: playName
+          };
+        }
+      }
+    );
+  }
+  /**
+   * Get a named play handle for remote lifecycle operations.
+   *
+   * @typeParam TInput - Expected input type
+   * @typeParam TOutput - Expected output type
+   * @param name - Play name (as registered on the server)
+   * @returns Named play handle with run, versions, get, publish, etc.
+   *
+   * @example
+   * ```typescript
+   * const play = ctx.play<{ domain: string }>('email-waterfall');
+   * const job = await play.run({ domain: 'stripe.com' });
+   * const result = await job.get();
+   * ```
+   */
+  play(name) {
+    return createNamedPlayHandle(() => this.client, name);
+  }
+  async runPlay(playOrRef, input) {
+    const name = typeof playOrRef === "string" ? playOrRef : playOrRef.playName ?? playOrRef.name ?? "";
+    return await this.play(name).runSync(input);
+  }
+};
+var Deepline = class {
+  /**
+   * Create a connected SDK context.
+   *
+   * Resolves configuration from options, environment variables, and CLI config
+   * files. See {@link resolveConfig} for the resolution order.
+   *
+   * @param options - Optional overrides for API key, base URL, etc.
+   * @returns Ready-to-use SDK context
+   * @throws {@link ConfigError} if no API key can be resolved
+   *
+   * @example
+   * ```typescript
+   * // Auto-config (uses env vars / CLI auth):
+   * const ctx = await Deepline.connect();
+   *
+   * // Explicit config:
+   * const ctx2 = await Deepline.connect({
+   *   apiKey: 'dl_test_...',
+   *   baseUrl: 'http://localhost:3000',
+   * });
+   * ```
+   */
+  static async connect(options) {
+    return new DeeplineContext(options);
   }
 };
+function defineInput(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error(
+      "defineInput<T>(schema) requires a JSON-schema-like object."
+    );
+  }
+  return { schema };
+}
+function definePlay(nameOrConfig, maybeFn, maybeBindings) {
+  const config = typeof nameOrConfig === "string" ? {
+    name: nameOrConfig,
+    fn: maybeFn,
+    bindings: maybeBindings,
+    inputSchema: void 0,
+    billing: maybeBindings?.billing
+  } : {
+    name: nameOrConfig.id,
+    fn: nameOrConfig.run,
+    bindings: nameOrConfig.bindings,
+    inputSchema: nameOrConfig.input.schema,
+    billing: nameOrConfig.billing
+  };
+  const name = config.name;
+  const fn = config.fn;
+  const bindings = config.bindings;
+  const billing = config.billing;
+  const inputSchema = config.inputSchema;
+  if (typeof fn !== "function") {
+    throw new Error("definePlay(...) requires an async run function.");
+  }
+  if (name.includes("/")) {
+    throw new Error(
+      'definePlay(name, ...) play names cannot contain "/". Slash is reserved for qualified references like "prebuilt/example" or "self/example".'
+    );
+  }
+  const normalizedName = name.trim().replace(/[^a-z0-9]+/gi, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+  if (!normalizedName) {
+    throw new Error(
+      "definePlay(name, ...) requires a play name with at least one letter or number. Use only letters, numbers, underscores, or hyphens."
+    );
+  }
+  if (normalizedName.length > 63) {
+    throw new Error(
+      `definePlay("${name}", ...) is too long after normalization (${normalizedName.length}/63). Shorten the play name to 63 characters or fewer. Normalized value: "${normalizedName}".`
+    );
+  }
+  const metadata = {
+    name,
+    ...bindings ? { bindings } : {},
+    ...inputSchema ? { inputSchema } : {},
+    ...billing ? { billing } : {}
+  };
+  const play = fn;
+  Object.defineProperty(play, PLAY_METADATA_SYMBOL, {
+    value: metadata,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  Object.defineProperty(play, "playName", {
+    value: name,
+    enumerable: true,
+    configurable: false,
+    writable: false
+  });
+  Object.defineProperty(play, "bindings", {
+    value: bindings,
+    enumerable: true,
+    configurable: false,
+    writable: false
+  });
+  const handle = createNamedPlayHandle(
+    () => new DeeplineClient(),
+    name
+  );
+  for (const key of [
+    "name",
+    "get",
+    "runs",
+    "versions",
+    "publish",
+    "run",
+    "runSync"
+  ]) {
+    Object.defineProperty(play, key, {
+      value: handle[key],
+      enumerable: false,
+      configurable: false,
+      writable: false
+    });
+  }
+  return play;
+}
+var defineWorkflow = definePlay;
+function getDefinedPlayMetadata(value) {
+  if (typeof value !== "function") {
+    return null;
+  }
+  const metadata = value[PLAY_METADATA_SYMBOL];
+  if (!metadata || typeof metadata !== "object") {
+    return null;
+  }
+  const candidate = metadata;
+  if (!candidate.name || typeof candidate.name !== "string") {
+    return null;
+  }
+  return candidate;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,
   ConfigError,
+  Deepline,
   DeeplineClient,
+  DeeplineContext,
   DeeplineError,
   PROD_URL,
   RateLimitError,
-  resolveConfig
+  SDK_API_CONTRACT,
+  SDK_VERSION,
+  createToolCallResult,
+  defineInput,
+  definePlay,
+  defineWorkflow,
+  extractSummaryFields,
+  getDefinedPlayMetadata,
+  resolveConfig,
+  steps,
+  tryConvertToList,
+  when,
+  writeCsvOutputFile,
+  writeJsonOutputFile
 });
 //# sourceMappingURL=index.js.map