deepline 0.1.12 → 0.1.20

package/dist/repo/sdk/src/client.ts

@@ -56,6 +56,8 @@ import type {
   StartPlayRunRequest,
   DeletePlayResult,
   ToolDefinition,
+  ToolSearchOptions,
+  ToolSearchResult,
   ToolMetadata,
   CustomerDbQueryResult,
 } from './types.js';
@@ -63,6 +65,11 @@ import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
+
+type ExecuteToolRawOptions = {
+  includeToolMetadata?: boolean;
+};
 
 export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
   status: string;
@@ -75,6 +82,45 @@ export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
   [key: string]: unknown;
 };
 
+export type RunsListOptions = {
+  play: string;
+  status?: string;
+};
+
+export type RunsTailOptions = {
+  cursor?: string | number;
+  afterLogIndex?: number;
+  waitMs?: number;
+  terminalOnly?: boolean;
+  compact?: boolean;
+};
+
+export type RunsLogsOptions = {
+  limit?: number;
+};
+
+export type RunsLogsResult = {
+  runId: string;
+  totalCount: number;
+  returnedCount: number;
+  firstSequence: number | null;
+  lastSequence: number | null;
+  truncated: boolean;
+  hasMore: boolean;
+  entries: string[];
+};
+
+export 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>;
+};
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
@@ -140,6 +186,7 @@ function mapLegacyTemporalStatus(status: string): PlayStatus['status'] {
 export class DeeplineClient {
   private readonly http: HttpClient;
   private readonly config: ResolvedConfig;
+  readonly runs: RunsNamespace;
 
   /**
    * @param options - Optional overrides for API key, base URL, timeout, and retries.
@@ -148,6 +195,13 @@ export class DeeplineClient {
   constructor(options?: DeeplineClientOptions) {
     this.config = resolveConfig(options);
     this.http = new HttpClient(this.config);
+    this.runs = {
+      get: (runId) => this.getRunStatus(runId),
+      list: (options) => this.listRuns(options),
+      tail: (runId, options) => this.tailRun(runId, options),
+      logs: (runId, options) => this.getRunLogs(runId, options),
+      stop: (runId, options) => this.stopRun(runId, options),
+    };
   }
 
   /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
@@ -273,6 +327,34 @@ export class DeeplineClient {
     return res.tools;
   }
 
+  /**
+   * 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.
+   */
+  async searchTools(
+    options: ToolSearchOptions = {},
+  ): Promise<ToolSearchResult> {
+    const params = new URLSearchParams();
+    const query = options.query?.trim() ?? '';
+    params.set('q', query);
+    params.set(
+      'include_search_debug',
+      options.includeSearchDebug ? 'true' : 'false',
+    );
+    params.set('search_mode', options.searchMode ?? 'v2');
+    if (options.categories?.trim()) {
+      params.set('categories', options.categories.trim());
+    }
+    if (options.searchTerms?.trim()) {
+      params.set('search_terms', options.searchTerms.trim());
+    }
+    return this.http.get<ToolSearchResult>(
+      `/api/v2/integrations/list?${params.toString()}`,
+    );
+  }
+
   /**
    * Get detailed metadata for a single tool.
    *
@@ -312,13 +394,26 @@ export class DeeplineClient {
   async executeTool<TData = unknown, TMeta = Record<string, unknown>>(
     toolId: string,
     input: Record<string, unknown>,
+    options?: ExecuteToolRawOptions,
   ): Promise<ToolExecution<TData, TMeta>> {
+    const headers = options?.includeToolMetadata
+      ? { [INCLUDE_TOOL_METADATA_HEADER]: 'true' }
+      : undefined;
     return this.http.post<ToolExecution<TData, TMeta>>(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       { payload: input },
+      headers,
     );
   }
 
+  async executeToolRaw<TData = unknown, TMeta = Record<string, unknown>>(
+    toolId: string,
+    input: Record<string, unknown>,
+    options?: ExecuteToolRawOptions,
+  ): Promise<ToolExecution<TData, TMeta>> {
+    return this.executeTool<TData, TMeta>(toolId, input, options);
+  }
+
   async queryCustomerDb(input: {
     sql: string;
     maxRows?: number;
@@ -374,6 +469,7 @@ export class DeeplineClient {
         ? { artifactStorageKey: request.artifactStorageKey }
         : {}),
       ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
+      ...(request.sourceFiles ? { sourceFiles: request.sourceFiles } : {}),
       ...('staticPipeline' in request
         ? { staticPipeline: request.staticPipeline }
         : {}),
@@ -418,6 +514,7 @@ export class DeeplineClient {
         ? { artifactStorageKey: request.artifactStorageKey }
         : {}),
       ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
+      ...(request.sourceFiles ? { sourceFiles: request.sourceFiles } : {}),
       ...('staticPipeline' in request
         ? { staticPipeline: request.staticPipeline }
         : {}),
@@ -466,6 +563,7 @@ export class DeeplineClient {
   async registerPlayArtifact(input: {
     name: string;
     sourceCode: string;
+    sourceFiles?: Record<string, string>;
     artifact: Record<string, unknown>;
     compilerManifest?: PlayCompilerManifest;
     publish?: boolean;
@@ -490,6 +588,7 @@ export class DeeplineClient {
       (await this.compilePlayManifest({
         name: input.name,
         sourceCode: input.sourceCode,
+        sourceFiles: input.sourceFiles,
         artifact: input.artifact,
       }));
     return this.http.post('/api/v2/plays/artifacts', {
@@ -502,6 +601,7 @@ export class DeeplineClient {
     artifacts: Array<{
       name: string;
       sourceCode: string;
+      sourceFiles?: Record<string, string>;
       artifact: Record<string, unknown>;
       compilerManifest?: PlayCompilerManifest;
       publish?: boolean;
@@ -533,6 +633,7 @@ export class DeeplineClient {
           (await this.compilePlayManifest({
             name: artifact.name,
             sourceCode: artifact.sourceCode,
+            sourceFiles: artifact.sourceFiles,
             artifact: artifact.artifact,
           })),
       })),
@@ -545,6 +646,7 @@ export class DeeplineClient {
   async compilePlayManifest(input: {
     name: string;
     sourceCode: string;
+    sourceFiles?: Record<string, string>;
     artifact: Record<string, unknown>;
     importedPlayDependencies?: PlayCompilerManifest[];
   }): Promise<PlayCompilerManifest> {
@@ -564,6 +666,7 @@ export class DeeplineClient {
   async checkPlayArtifact(input: {
     name?: string;
     sourceCode: string;
+    sourceFiles?: Record<string, string>;
     artifact: Record<string, unknown>;
   }): Promise<PlayCheckResult> {
     return this.http.post('/api/v2/plays/check', input);
@@ -572,6 +675,7 @@ export class DeeplineClient {
   async startPlayRunFromBundle(input: {
     name: string;
     sourceCode: string;
+    sourceFiles?: Record<string, string>;
     artifact: Record<string, unknown>;
     compilerManifest?: PlayCompilerManifest;
     input?: Record<string, unknown>;
@@ -584,11 +688,13 @@ export class DeeplineClient {
       (await this.compilePlayManifest({
         name: input.name,
         sourceCode: input.sourceCode,
+        sourceFiles: input.sourceFiles,
         artifact: input.artifact,
       }));
     const registeredArtifact = await this.registerPlayArtifact({
       name: input.name,
       sourceCode: input.sourceCode,
+      sourceFiles: input.sourceFiles,
       artifact: input.artifact,
       compilerManifest,
       publish: false,
@@ -642,6 +748,7 @@ export class DeeplineClient {
     name?: string,
     options?: {
       sourceCode?: string;
+      sourceFiles?: Record<string, string>;
       artifact?: Record<string, unknown>;
       compilerManifest?: PlayCompilerManifest;
       input?: Record<string, unknown>;
@@ -669,12 +776,14 @@ export class DeeplineClient {
       (await this.compilePlayManifest({
         name,
         sourceCode,
+        sourceFiles: options?.sourceFiles,
         artifact,
       }));
 
     const registeredArtifact = await this.registerPlayArtifact({
       name,
       sourceCode,
+      sourceFiles: options?.sourceFiles,
       artifact,
       compilerManifest,
       publish: false,
@@ -916,6 +1025,134 @@ export class DeeplineClient {
     return response.runs ?? [];
   }
 
+  /**
+   * Get a run by id using the public runs resource model.
+   *
+   * This is the SDK equivalent of:
+   *
+   * ```bash
+   * deepline runs get <run-id> --json
+   * ```
+   */
+  async getRunStatus(runId: string): Promise<PlayStatus> {
+    const response = await this.http.get<Record<string, unknown>>(
+      `/api/v2/runs/${encodeURIComponent(runId)}`,
+    );
+    return normalizePlayStatus(response);
+  }
+
+  /**
+   * 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
+   * ```
+   */
+  async listRuns(options: RunsListOptions): Promise<PlayRunListItem[]> {
+    const playName = options.play.trim();
+    if (!playName) {
+      throw new Error('runs.list requires options.play.');
+    }
+    const params = new URLSearchParams({ play: playName });
+    const status = options.status?.trim();
+    if (status) {
+      params.set('status', status);
+    }
+    const response = await this.http.get<{ runs: PlayRunListItem[] }>(
+      `/api/v2/runs?${params.toString()}`,
+    );
+    return response.runs ?? [];
+  }
+
+  /**
+   * 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
+   * ```
+   */
+  async tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus> {
+    const afterLogIndex =
+      typeof options?.afterLogIndex === 'number'
+        ? options.afterLogIndex
+        : typeof options?.cursor === 'number'
+          ? options.cursor
+          : typeof options?.cursor === 'string' && options.cursor.trim()
+            ? Number(options.cursor)
+            : undefined;
+    const params = new URLSearchParams();
+    if (Number.isFinite(afterLogIndex)) {
+      params.set('afterLogIndex', String(Number(afterLogIndex)));
+    }
+    if (typeof options?.waitMs === 'number') {
+      params.set('waitMs', String(options.waitMs));
+    }
+    if (options?.terminalOnly) {
+      params.set('terminalOnly', 'true');
+    }
+    const suffix = params.toString() ? `?${params.toString()}` : '';
+    const response = await this.http.get<Record<string, unknown>>(
+      `/api/v2/runs/${encodeURIComponent(runId)}/tail${suffix}`,
+    );
+    return normalizePlayStatus(response);
+  }
+
+  /**
+   * 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
+   * ```
+   */
+  async getRunLogs(
+    runId: string,
+    options?: RunsLogsOptions,
+  ): Promise<RunsLogsResult> {
+    const status = await this.getRunStatus(runId);
+    const logs = status.progress?.logs ?? [];
+    const limit =
+      typeof options?.limit === 'number' && Number.isFinite(options.limit)
+        ? Math.max(0, Math.trunc(options.limit))
+        : 200;
+    const entries = logs.slice(Math.max(0, logs.length - limit));
+    return {
+      runId: status.runId,
+      totalCount: logs.length,
+      returnedCount: entries.length,
+      firstSequence:
+        logs.length === 0 ? null : logs.length - entries.length + 1,
+      lastSequence: logs.length === 0 ? null : logs.length,
+      truncated: logs.length > entries.length,
+      hasMore: logs.length > entries.length,
+      entries,
+    };
+  }
+
+  /**
+   * 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
+   * ```
+   */
+  async stopRun(
+    runId: string,
+    options?: { reason?: string },
+  ): Promise<StopPlayRunResult> {
+    return this.http.post<StopPlayRunResult>(
+      `/api/v2/runs/${encodeURIComponent(runId)}/stop`,
+      options?.reason ? { reason: options.reason } : {},
+    );
+  }
+
   async listPlays(): Promise<PlayListItem[]> {
     const response = await this.http.get<{ plays: PlayListItem[] }>(
       '/api/v2/plays',

package/dist/repo/sdk/src/config.ts

@@ -10,9 +10,12 @@
  * 1. `options.baseUrl` (explicit constructor argument)
  * 2. `DEEPLINE_ORIGIN_URL` environment variable
  * 3. `DEEPLINE_API_BASE_URL` environment variable
- * 4. Nearest checkout-local `.env.worktree`
- * 5. `DEEPLINE_ORIGIN_URL` from the production host auth file
- * 6. Production fallback: `https://code.deepline.com`
+ * 4. Nearest checkout-local `.env.deepline`
+ * 5. Nearest checkout-local profile file (`.env.deepline.prod`, etc.)
+ * 6. Nearest checkout-local app env file (`.env.prod`, `.env.staging`, `.env.local`, `.env`)
+ * 7. Nearest checkout-local `.env.worktree`
+ * 8. `DEEPLINE_ORIGIN_URL` from the production host auth file
+ * 9. Production fallback: `https://code.deepline.com`
  *
  * ### API Key
  * 1. `options.apiKey` (explicit constructor argument)
@@ -48,6 +51,20 @@ const DEFAULT_TIMEOUT = 60_000;
 /** Default retry count for transient failures. */
 const DEFAULT_MAX_RETRIES = 3;
 
+const ACTIVE_DEEPLINE_ENV_FILE = '.env.deepline';
+
+function isProdBaseUrl(baseUrl: string): boolean {
+  return baseUrl.trim().replace(/\/$/, '') === PROD_URL;
+}
+
+function profileNameForBaseUrl(baseUrl: string): 'prod' | 'dev' {
+  return isProdBaseUrl(baseUrl) ? 'prod' : 'dev';
+}
+
+function projectEnvStartDir(): string {
+  return process.env.DEEPLINE_PROJECT_ENV_DIR?.trim() || process.cwd();
+}
+
 /**
  * Convert a base URL to a filesystem-safe slug for per-host config storage.
  *
@@ -116,17 +133,70 @@ function parseEnvFile(filePath: string): Record<string, string> {
   return env;
 }
 
-function findNearestWorktreeEnv(startDir: string = process.cwd()): Record<string, string> {
+function findNearestEnvFile(
+  names: string[],
+  startDir: string = process.cwd(),
+): string | null {
   let current = resolve(startDir);
   while (true) {
-    const values = parseEnvFile(join(current, '.env.worktree'));
-    if (Object.keys(values).length > 0) return values;
+    for (const name of names) {
+      const filePath = join(current, name);
+      if (existsSync(filePath)) return filePath;
+    }
     const parent = dirname(current);
-    if (parent === current) return {};
+    if (parent === current) return null;
     current = parent;
   }
 }
 
+function findNearestEnv(names: string[], startDir: string = process.cwd()): Record<string, string> {
+  const filePath = findNearestEnvFile(names, startDir);
+  return filePath ? parseEnvFile(filePath) : {};
+}
+
+function findNearestWorktreeEnv(startDir: string = process.cwd()): Record<string, string> {
+  return findNearestEnv(['.env.worktree'], startDir);
+}
+
+function resolveProfileEnvFileNames(): string[] {
+  const explicitProfile =
+    process.env.DEEPLINE_ENV_PROFILE?.trim() ||
+    process.env.DEEPLINE_PROFILE?.trim() ||
+    '';
+  const names: string[] = [];
+  if (explicitProfile) names.push(`.env.deepline.${explicitProfile}`);
+  const nodeEnv = process.env.NODE_ENV?.trim();
+  if (nodeEnv === 'production') names.push('.env.deepline.prod');
+  else if (nodeEnv === 'staging') names.push('.env.deepline.staging');
+  names.push(ACTIVE_DEEPLINE_ENV_FILE);
+  return names;
+}
+
+function resolveProjectAppEnvFileNames(): string[] {
+  const nodeEnv = process.env.NODE_ENV?.trim();
+  const names: string[] = [];
+  if (nodeEnv === 'production') names.push('.env.prod');
+  if (nodeEnv === 'staging') names.push('.env.staging');
+  names.push('.env.local', '.env');
+  return names;
+}
+
+function resolveBaseUrlFromEnvValues(env: Record<string, string>): string {
+  return (
+    env.DEEPLINE_ORIGIN_URL?.trim() ||
+    env.DEEPLINE_API_BASE_URL?.trim() ||
+    ''
+  );
+}
+
+function loadProjectDeeplineEnv(): Record<string, string> {
+  return findNearestEnv(resolveProfileEnvFileNames(), projectEnvStartDir());
+}
+
+function loadProjectAppEnv(): Record<string, string> {
+  return findNearestEnv(resolveProjectAppEnvFileNames(), projectEnvStartDir());
+}
+
 function normalizeWorktreeBaseUrl(baseUrl: string, worktreeEnv = findNearestWorktreeEnv()): string {
   const trimmed = baseUrl.trim().replace(/\/$/, '');
   if (!trimmed) return trimmed;
@@ -219,6 +289,12 @@ function autoDetectBaseUrl(): string {
   const envBase = process.env.DEEPLINE_API_BASE_URL?.trim();
   if (envBase) return normalizeWorktreeBaseUrl(envBase);
 
+  const projectDeeplineBaseUrl = resolveBaseUrlFromEnvValues(loadProjectDeeplineEnv());
+  if (projectDeeplineBaseUrl) return normalizeWorktreeBaseUrl(projectDeeplineBaseUrl);
+
+  const projectAppBaseUrl = resolveBaseUrlFromEnvValues(loadProjectAppEnv());
+  if (projectAppBaseUrl) return normalizeWorktreeBaseUrl(projectAppBaseUrl);
+
   const worktreeBaseUrl = resolveWorktreeBaseUrl();
   if (worktreeBaseUrl) return worktreeBaseUrl;
 
@@ -260,11 +336,15 @@ export function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig {
   const baseUrl = normalizeWorktreeBaseUrl(requestedBaseUrl);
 
   const cliEnv = loadCliEnv(baseUrl);
+  const projectDeeplineEnv = loadProjectDeeplineEnv();
+  const projectAppEnv = loadProjectAppEnv();
 
   // Resolve API key: option > env var > SDK CLI env
   const apiKey =
     options?.apiKey?.trim() ||
     process.env.DEEPLINE_API_KEY?.trim() ||
+    projectDeeplineEnv.DEEPLINE_API_KEY ||
+    projectAppEnv.DEEPLINE_API_KEY ||
     cliEnv.DEEPLINE_API_KEY ||
     '';
 
@@ -282,4 +362,41 @@ export function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig {
   };
 }
 
-export { baseUrlSlug, loadCliEnv, loadGlobalCliEnv, parseEnvFile, autoDetectBaseUrl, PROD_URL };
+function mergeEnvFile(filePath: string, values: Record<string, string>): void {
+  const existing = existsSync(filePath) ? parseEnvFile(filePath) : {};
+  const merged = { ...existing, ...values };
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const lines = Object.entries(merged)
+    .filter(([, value]) => value !== '')
+    .map(([key, value]) => `${key}=${value}`);
+  writeFileSync(filePath, `${lines.join('\n')}\n`, 'utf-8');
+}
+
+export function saveProjectDeeplineEnvValues(
+  baseUrl: string,
+  values: Record<string, string>,
+  startDir: string = projectEnvStartDir(),
+): string[] {
+  const root = resolve(startDir);
+  const profile = profileNameForBaseUrl(baseUrl);
+  const files = [
+    join(root, ACTIVE_DEEPLINE_ENV_FILE),
+    join(root, `.env.deepline.${profile}`),
+  ];
+  if (profile === 'dev') files.push(join(root, '.env'));
+
+  for (const filePath of files) {
+    mergeEnvFile(filePath, values);
+  }
+  return files;
+}
+
+export {
+  baseUrlSlug,
+  loadCliEnv,
+  loadGlobalCliEnv,
+  parseEnvFile,
+  autoDetectBaseUrl,
+  PROD_URL,
+};

package/dist/repo/sdk/src/http.ts

@@ -179,10 +179,26 @@ export class HttpClient {
           }
 
           if (!response.ok) {
-            const msg =
+            const errorValue =
               typeof parsed === 'object' && parsed && 'error' in parsed
-                ? String((parsed as Record<string, unknown>).error)
-                : `HTTP ${response.status}`;
+                ? (parsed as Record<string, unknown>).error
+                : undefined;
+            const msg =
+              typeof errorValue === 'string'
+                ? errorValue
+                : errorValue &&
+                    typeof errorValue === 'object' &&
+                    'message' in errorValue &&
+                    typeof (errorValue as Record<string, unknown>).message ===
+                      'string'
+                  ? (errorValue as Record<string, string>).message
+                  : typeof parsed === 'object' &&
+                      parsed &&
+                      'message' in parsed &&
+                      typeof (parsed as Record<string, unknown>).message ===
+                        'string'
+                    ? (parsed as Record<string, string>).message
+                    : `HTTP ${response.status}`;
             throw new DeeplineError(msg, response.status, 'API_ERROR', {
               response: parsed,
             });
@@ -289,8 +305,16 @@ export class HttpClient {
    * @param path - API path
    * @param body - Request body (will be JSON-serialized)
    */
-  async post<T = unknown>(path: string, body: unknown): Promise<T> {
-    return this.request<T>(path, { method: 'POST', body });
+  async post<T = unknown>(
+    path: string,
+    body: unknown,
+    headers?: Record<string, string>,
+  ): Promise<T> {
+    return this.request<T>(path, {
+      method: 'POST',
+      body,
+      headers,
+    });
   }
 
   /**