deepline 0.1.0 → 0.1.2

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

@@ -0,0 +1,1330 @@
+/**
+ * Play definition, execution, and lifecycle management.
+ *
+ * This module provides the high-level API for defining and running plays —
+ * composable TypeScript workflows that orchestrate tool calls into repeatable
+ * pipelines. Plays run on Temporal for durable execution with automatic retries,
+ * timeouts, and full observability.
+ *
+ * ## Core concepts
+ *
+ * - **{@link definePlay}** — Define a play as a typed async function. The returned
+ *   value is both callable (for server-side execution) and has methods for
+ *   remote lifecycle management (run, get, publish, tail).
+ *
+ * - **{@link Deepline.connect}** — Create a client context for programmatic SDK
+ *   usage. Returns a {@link DeeplineContext} with tool and play handles.
+ *
+ * - **{@link PlayJob}** — Handle to a running play execution. Poll for status,
+ *   stream logs, wait for completion, or cancel.
+ *
+ * ## Usage patterns
+ *
+ * ### Define and run a play (file-backed)
+ *
+ * ```typescript
+ * // my-play.play.ts
+ * import { definePlay } from 'deepline';
+ *
+ * export default definePlay('my-play', async (ctx, input: { domain: string }) => {
+ *   ctx.log(`Looking up ${input.domain}`);
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
+ *     description: 'Look up company details by domain.',
+ *   });
+ *   return { company: company.result };
+ * });
+ * ```
+ *
+ * Then run via CLI: `deepline play run --file my-play.play.ts --watch`
+ *
+ * ### Programmatic usage
+ *
+ * ```typescript
+ * import { Deepline } from 'deepline';
+ *
+ * const ctx = await Deepline.connect();
+ * const job = await ctx.play('my-play').run({ domain: 'stripe.com' });
+ * const result = await job.get(); // Polls until complete
+ * ```
+ *
+ * ### With bindings (cron, webhook)
+ *
+ * ```typescript
+ * import { definePlay } from 'deepline';
+ *
+ * export default definePlay('daily-sync', async (ctx) => {
+ *   const data = await ctx.tools.execute({
+ *     id: 'crm_export',
+ *     tool: 'crm_export',
+ *     input: {},
+ *     description: 'Export CRM records for the daily sync.',
+ *   });
+ *   return data;
+ * }, {
+ *   cron: { schedule: '0 9 * * *', timezone: 'America/New_York' },
+ * });
+ * ```
+ *
+ * @module
+ */
+import { DeeplineClient } from './client.js';
+import { DeeplineError } from './errors.js';
+import { createToolCallResult } from './tool-output.js';
+import type { ToolCallResult } from './tool-output.js';
+import type {
+  PlayDataset,
+  PlayDatasetInput,
+} from '../../shared_libs/plays/dataset.js';
+import type {
+  DeeplineClientOptions,
+  PlayDetail,
+  ClearPlayHistoryResult,
+  PlayRevisionSummary,
+  PlayRunListItem,
+  PlayStatus,
+  PublishPlayVersionResult,
+  StopPlayRunResult,
+  ToolDefinition,
+  ToolMetadata,
+} from './types.js';
+
+/**
+ * Optional trigger bindings for a play.
+ *
+ * Plays can be triggered by webhooks (with HMAC signature verification)
+ * or cron schedules. Bindings are declared as the third argument to
+ * {@link definePlay}.
+ *
+ * @example Webhook with HMAC verification
+ * ```typescript
+ * definePlay('webhook-handler', handler, {
+ *   webhook: {
+ *     hmac: {
+ *       algorithm: 'sha256',
+ *       header: 'X-Hub-Signature-256',
+ *       secretEnv: 'WEBHOOK_SECRET',
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Cron schedule
+ * ```typescript
+ * definePlay('nightly-sync', handler, {
+ *   cron: { schedule: '0 2 * * *', timezone: 'UTC' },
+ * });
+ * ```
+ */
+export type PlayBindings = {
+  /** Optional per-run billing controls enforced by the runtime. */
+  billing?: {
+    /** Stop the run before a billed action would push total run credits above this cap. */
+    maxCreditsPerRun?: number;
+  };
+  /** Webhook trigger with optional HMAC signature verification. */
+  webhook?: {
+    hmac?: {
+      /** Hash algorithm. Currently only `'sha256'` is supported. */
+      algorithm?: 'sha256';
+      /** HTTP header containing the signature (e.g. `'X-Hub-Signature-256'`). */
+      header?: string;
+      /** Environment variable name holding the HMAC secret. */
+      secretEnv: string;
+    };
+  };
+  /** Cron schedule trigger. */
+  cron?: {
+    /** Cron expression (e.g. `'0 9 * * *'` for daily at 9am). */
+    schedule: string;
+    /** IANA timezone (e.g. `'America/New_York'`). Defaults to UTC. */
+    timezone?: string;
+  };
+};
+
+export type LoosePlayObject = {
+  [key: string]: LoosePlayObject;
+};
+
+export type ToolExecutionRequest = {
+  id: string;
+  tool: string;
+  input: Record<string, unknown>;
+  description?: string;
+};
+
+export type SdkToolExecutionRequest = {
+  tool: string;
+  input: Record<string, unknown>;
+};
+
+export type ToolExecuteResult<TResult = unknown> = {
+  status: string;
+  result: TResult;
+  _metadata: {
+    toolId: string;
+    execution: {
+      idempotent: true;
+      cached: boolean;
+      source: 'live' | 'checkpoint' | 'cache';
+      cacheKey?: string;
+    };
+    targets: Record<string, { value: unknown; path: string }>;
+    lists: Record<
+      string,
+      {
+        path: string;
+        count: number | null;
+        keys: Record<string, string>;
+      }
+    >;
+  };
+  get<T = unknown>(target: string): T | null;
+  getEmail(): string | null;
+  getPhone(): string | null;
+  getLinkedin(): string | null;
+  list<T = Record<string, unknown>>(name?: string): T[] | null;
+  listPick<const TKeys extends readonly string[]>(
+    keys: TKeys,
+    name?: string,
+  ): Array<Record<TKeys[number], unknown>> | null;
+  listKeys(name?: string): Record<string, string>;
+};
+
+export type StepResolver<Row, Value> = (
+  row: Row,
+  ctx: DeeplinePlayRuntimeContext,
+  index: number,
+) => Value | Promise<Value>;
+
+export type ConditionalStepResolver<Row, Value, Else = null> = {
+  readonly kind: 'conditional';
+  readonly when: (row: Row, index: number) => boolean | Promise<boolean>;
+  readonly run: StepResolver<Row, Value>;
+  readonly elseValue: Else;
+  else<ValueElse>(
+    value: ValueElse,
+  ): ConditionalStepResolver<Row, Value, ValueElse>;
+};
+
+export type StepProgram<Input, Output, Return = Output> = {
+  readonly kind: 'steps';
+  readonly steps: readonly PlayStepProgramStep[];
+  readonly returnResolver?: StepResolver<Output, Return>;
+  readonly __inputType?: (input: Input) => void;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver:
+      | StepResolver<Output, Value>
+      | ConditionalStepResolver<Output, Value>
+      | StepProgramResolver<Output, Value>,
+  ): StepProgram<Input, Output & Record<Name, Value>, Return>;
+  return<Value>(
+    resolver: StepResolver<Output, Value>,
+  ): StepProgram<Input, Output, Value>;
+};
+
+export type StepProgramResolver<Input, Return> = {
+  readonly kind: 'steps';
+  readonly steps: readonly PlayStepProgramStep[];
+  readonly returnResolver?: StepResolver<never, Return>;
+  readonly __inputType?: (input: Input) => void;
+};
+
+export type PlayStepProgramStep = {
+  readonly name: string;
+  readonly resolver:
+    | StepResolver<Record<string, unknown>, unknown>
+    | ConditionalStepResolver<Record<string, unknown>, unknown>
+    | StepProgramResolver<Record<string, unknown>, unknown>;
+};
+
+export type MapStepResolver<Row, Value> =
+  | StepResolver<Row, Value>
+  | ConditionalStepResolver<Row, Value>
+  | StepProgramResolver<Row, Value>;
+
+export type MapRowKey<InputRow extends object> =
+  | (keyof InputRow & string)
+  | readonly (keyof InputRow & string)[]
+  | ((row: InputRow, index: number) => string | number | readonly unknown[]);
+
+export type MapDefinitionOptions<InputRow extends object> = {
+  staleAfterSeconds?: number;
+  key?: MapRowKey<InputRow>;
+};
+
+export type MapRunOptions = {
+  description?: string;
+};
+
+export type MapStepBuilder<
+  InputRow extends object,
+  OutputRow extends object,
+> = {
+  step<Name extends string, Value>(
+    name: Name,
+    resolver: MapStepResolver<OutputRow, Value>,
+  ): MapStepBuilder<InputRow, OutputRow & Record<Name, Value>>;
+  run(options?: MapRunOptions): Promise<PlayDataset<OutputRow>>;
+};
+
+/**
+ * Runtime context available inside a play function.
+ *
+ * Provides methods for calling tools, processing data, and emitting logs.
+ * This context is injected by the Temporal worker — you never construct it directly.
+ *
+ * @example
+ * ```typescript
+ * definePlay('example', async (ctx, input: { domain: string }) => {
+ *   // Call a tool
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
+ *     description: 'Look up company details by domain.',
+ *   });
+ *
+ *   // Fan-out: process items with named steps
+ *   const enriched = await ctx
+ *     .map('companies', [{ domain: 'a.com' }, { domain: 'b.com' }], { key: 'domain' })
+ *     .step('company', (row, rowCtx) =>
+ *       rowCtx.tool({
+ *         id: 'company_search',
+ *         tool: 'test_company_search',
+ *         input: { domain: row.domain },
+ *         description: 'Look up company details by domain.',
+ *       }))
+ *     .run({ description: 'Look up company details.' });
+ *
+ *   // Load CSV data
+ *   const leads = await ctx.csv('leads.csv');
+ *
+ *   // Emit a log line (visible in `play tail`)
+ *   ctx.log(`Loaded ${await leads.count()} leads`);
+ *
+ *   // Pause execution
+ *   await ctx.sleep(1000);
+ *
+ *   // Access the raw input object
+ *   console.log(ctx.input);
+ *
+ *   return { company, enriched };
+ * });
+ * ```
+ */
+export interface DeeplinePlayRuntimeContext {
+  /**
+   * Load a CSV file as a dataset handle.
+   *
+   * The CSV must be staged or available at the given path. Each row becomes
+   * an object keyed by column headers.
+   *
+   * @typeParam T - Row type (defaults to `Record<string, unknown>`)
+   * @param path - Relative path to the CSV file
+   * The returned dataset supports `for await`, `peek()`, `count()`, and
+   * explicit `materialize()` for small result sets.
+   *
+   * @returns Parsed dataset rows
+   */
+  csv<T = Record<string, unknown>>(
+    path: string,
+    options?: { description?: string },
+  ): Promise<PlayDataset<T>>;
+
+  /**
+   * Fan-out: process each item through one or more named columns.
+   *
+   * Each key in `columns` becomes an output column. Each value is an async
+   * callback `(row, ctx) => result` that receives the current row and the
+   * play context — call tools, run waterfalls, do arbitrary logic.
+   *
+   * Items are processed in parallel (paced by the rate-limit scheduler).
+   * The first argument identifies the logical map/table namespace. Use
+   * `options.key` to pin durable row identity to stable input fields instead of
+   * hashing the full input row.
+   * `options.staleAfterSeconds` intentionally partitions the durable cache on a
+   * relative time window. Use `86400` for daily reruns; retries inside the same
+   * window still replay safely.
+   *
+   * Returns a dataset handle containing the original rows merged with the new
+   * columns. Input may be a normal array, iterable, async iterable, or another
+   * play dataset handle.
+   *
+   * @typeParam T - Row type
+   * @param key - Logical map key used to isolate row identities (e.g. `'main_table'`, `'email_lookup'`)
+   * @param items - Input rows or dataset handle
+   * @returns Dataset of rows merged with the computed column values
+   *
+   * @example Single tool per row
+   * ```typescript
+   * const results = await ctx
+   *   .map('leads', leads, { key: 'domain' })
+   *   .step('company', (row, ctx) =>
+   *     ctx.tools.execute({
+   *       id: 'company_search',
+   *       tool: 'test_company_search',
+   *       input: { domain: row.domain },
+   *       description: 'Look up company details by domain.',
+   *     }))
+   *   .run({ description: 'Look up companies.' });
+   * // [{ domain: 'stripe.com', company: { name: 'Stripe', ... } }, ...]
+   * ```
+   *
+   * @example Multiple columns with pre/post logic
+   * ```typescript
+   * const results = await ctx
+   *   .map('leads', leads, { key: 'lead_id' })
+   *   .step('company', (row, ctx) =>
+   *     ctx.tools.execute({
+   *       id: 'company_search',
+   *       tool: 'test_company_search',
+   *       input: { domain: row.domain },
+   *       description: 'Look up company details by domain.',
+   *     }))
+   *   .step('score', (row) =>
+   *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
+   *   .run({ description: 'Enrich leads.' });
+   * ```
+   */
+  map<TItem extends object>(
+    key: string,
+    items: PlayDatasetInput<TItem>,
+    options?: MapDefinitionOptions<TItem>,
+  ): MapStepBuilder<TItem, TItem>;
+
+  /** Tool execution namespace. */
+  tools: {
+    /**
+     * Execute a single tool by stable durable execution id and tool ID.
+     *
+     * @param request - Tool execution request. `id` is the durable execution id;
+     *   omit it in row/map steps when the surrounding step id is the execution id.
+     * @returns The tool's output
+     */
+    execute<TOutput = LoosePlayObject>(
+      request: ToolExecutionRequest,
+    ): Promise<ToolExecuteResult<TOutput>>;
+  };
+  /**
+   * Execute a single tool by stable durable execution id and tool ID.
+   *
+   * Shorthand for `ctx.tools.execute({ id, tool, input })`; this is the
+   * preferred spelling in row-level step programs.
+   */
+  tool<TOutput = LoosePlayObject>(
+    request: ToolExecutionRequest,
+  ): Promise<ToolExecuteResult<TOutput>>;
+  step<T>(id: string, run: () => T | Promise<T>): Promise<T>;
+  fetch(
+    key: string,
+    url: string | URL,
+    init?: RequestInit,
+  ): Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    url: string;
+    headers: Record<string, string>;
+    bodyText: string;
+    json: unknown | null;
+  }>;
+  runPlay(
+    key: string,
+    playRef: string | PlayReferenceLike,
+    input: Record<string, unknown>,
+    options: { description?: string },
+  ): Promise<Record<string, unknown>>;
+
+  /**
+   * Emit a log line visible in `play tail` and the play's progress logs.
+   *
+   * @param message - Log message (plain text)
+   */
+  log(message: string): void;
+
+  /**
+   * Pause play execution for the specified duration.
+   *
+   * Uses Temporal's durable timer — safe across worker restarts.
+   *
+   * @param ms - Duration in milliseconds
+   */
+  sleep(ms: number): Promise<void>;
+
+  /** The raw input object passed when the play was started. */
+  readonly input: Record<string, unknown>;
+}
+
+/**
+ * Handle to a running play execution.
+ *
+ * Provides methods to check status, stream logs, wait for completion,
+ * or cancel the execution.
+ *
+ * This handle is the SDK-context equivalent of `deepline play run --watch` and
+ * `POST /api/v2/plays/run`: every surface returns a run id first, then exposes
+ * the completed user output through `PlayJob.get()` or the status endpoint's
+ * `result` field. Runtime logs are available from `status().progress.logs` and
+ * are intentionally separate from the returned output object.
+ *
+ * @typeParam TOutput - The play's return type
+ *
+ * @example
+ * ```typescript
+ * const job: PlayJob = await ctx.play('my-play').run({ domain: 'stripe.com' });
+ *
+ * // Poll status
+ * const status = await job.status();
+ * console.log(status.temporalStatus); // 'RUNNING'
+ *
+ * // Stream logs until completion
+ * const finalStatus = await job.tail({
+ *   onLog: (line) => console.log(`[play] ${line}`),
+ * });
+ *
+ * // Or just wait for the result
+ * const output = await job.get();
+ *
+ * // Cancel if needed
+ * await job.cancel();
+ * ```
+ */
+export interface PlayJob<TOutput = unknown> {
+  /** Temporal workflow ID for this execution. */
+  id: string;
+
+  /** Get the current execution status (single poll). */
+  status(): Promise<PlayStatus>;
+
+  /**
+   * Stream logs and wait for completion.
+   *
+   * Polls until the play reaches a terminal state, invoking `onLog` for
+   * each new log line. Returns the final status.
+   *
+   * @param options.intervalMs - Poll interval in ms. Default: `500`.
+   * @param options.onLog - Callback for each log line. Default: `console.log`.
+   */
+  tail(options?: {
+    intervalMs?: number;
+    onLog?: (line: string) => void;
+  }): Promise<PlayStatus>;
+
+  /**
+   * Wait for the play to complete and return its output.
+   *
+   * Polls until terminal state. Throws {@link DeeplineError} if the play
+   * fails, is cancelled, or times out.
+   *
+   * @param options.intervalMs - Poll interval in ms. Default: `500`.
+   * @returns The play's return value
+   * @throws {@link DeeplineError} if the play did not complete successfully
+   */
+  get(options?: { intervalMs?: number }): Promise<TOutput>;
+
+  /** Cancel this play execution. */
+  cancel(): Promise<void>;
+
+  /** Deep-stop this play execution, including open HITL waits. */
+  stop(options?: { reason?: string }): Promise<StopPlayRunResult>;
+}
+
+/**
+ * Handle to a named play for remote lifecycle operations.
+ *
+ * Returned by {@link DeeplineContext.play} and attached to {@link DefinedPlay}.
+ * Provides methods to run, inspect, list runs, and publish a play by name.
+ *
+ * @typeParam TInput - The play's input type
+ * @typeParam TOutput - The play's return type
+ *
+ * @example
+ * ```typescript
+ * const ctx = await Deepline.connect();
+ * const play = ctx.play<{ domain: string }, Company>('company-lookup');
+ *
+ * // Get play definition
+ * const detail = await play.get();
+ * console.log(`Live: v${detail.play.currentPublishedVersion}`);
+ *
+ * // Run and wait
+ * const result = await play.runSync({ domain: 'stripe.com' });
+ *
+ * // Run async
+ * const job = await play.run({ domain: 'stripe.com' });
+ * const output = await job.get();
+ *
+ * // List recent runs
+ * const runs = await play.runs();
+ *
+ * // List saved versions
+ * const versions = await play.versions();
+ *
+ * // Publish the current draft
+ * await play.publish();
+ * ```
+ */
+export interface DeeplineNamedPlay<
+  TInput = Record<string, unknown>,
+  TOutput = unknown,
+> {
+  /** The play's name. */
+  readonly name: string;
+
+  /** Fetch the full play definition with revision history and run stats. */
+  get(): Promise<PlayDetail>;
+
+  /** List recent runs for this play. */
+  runs(): Promise<PlayRunListItem[]>;
+
+  /** List saved versions for this play (newest first). */
+  versions(): Promise<PlayRevisionSummary[]>;
+
+  /** Publish a play revision. Defaults to the current working revision. */
+  publish(options?: { revisionId?: string }): Promise<PublishPlayVersionResult>;
+
+  /**
+   * Clear run history and durable sheet/result data for this play while keeping
+   * the play definition and revisions.
+   */
+  clearHistory(options?: {
+    tableNamespaces?: string[];
+  }): Promise<ClearPlayHistoryResult>;
+
+  /**
+   * Start a new run of this play. Returns a {@link PlayJob} for monitoring.
+   *
+   * @param input - Runtime input passed to the play function
+   */
+  run(
+    input: TInput,
+    options?: { revisionId?: string },
+  ): Promise<PlayJob<TOutput>>;
+
+  /**
+   * Run this play and wait for completion.
+   *
+   * Equivalent to `play.run(input).then(job => job.get())`.
+   *
+   * @param input - Runtime input
+   * @returns The play's return value
+   */
+  runSync(input: TInput, options?: { revisionId?: string }): Promise<TOutput>;
+}
+
+export type PrebuiltPlayRef = {
+  readonly playName: string;
+  readonly name: string;
+};
+
+export type PlayReferenceLike = {
+  readonly playName?: string;
+  readonly name?: string;
+};
+
+export type {
+  PlayDataset,
+  PlayDatasetInput,
+} from '../../shared_libs/plays/dataset.js';
+
+export type PlayReturnObject = Record<string, unknown> & {
+  readonly _metadata?: never;
+};
+
+export type PlayInputContract<TInput> = {
+  readonly schema: Record<string, unknown>;
+  readonly __inputType?: TInput;
+};
+
+export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
+  id: string;
+  input: PlayInputContract<TInput>;
+  run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>;
+  bindings?: PlayBindings;
+  billing?: PlayBindings['billing'];
+};
+
+class DeeplineConditionalStepResolver<
+  Row,
+  Value,
+  ElseValue,
+> implements ConditionalStepResolver<Row, Value, ElseValue> {
+  readonly kind = 'conditional' as const;
+
+  constructor(
+    readonly when: (row: Row, index: number) => boolean | Promise<boolean>,
+    readonly run: StepResolver<Row, Value>,
+    readonly elseValue: ElseValue,
+  ) {}
+
+  else<ValueElse>(
+    value: ValueElse,
+  ): ConditionalStepResolver<Row, Value, ValueElse> {
+    return new DeeplineConditionalStepResolver(this.when, this.run, value);
+  }
+}
+
+class DeeplineStepProgram<Input, Output, ReturnValue> implements StepProgram<
+  Input,
+  Output,
+  ReturnValue
+> {
+  readonly kind = 'steps' as const;
+  declare readonly __inputType?: (input: Input) => void;
+
+  constructor(
+    readonly steps: readonly PlayStepProgramStep[],
+    readonly returnResolver?: StepResolver<Output, ReturnValue>,
+  ) {}
+
+  step<Name extends string, Value>(
+    name: Name,
+    resolver:
+      | StepResolver<Output, Value>
+      | ConditionalStepResolver<Output, Value>
+      | StepProgramResolver<Output, Value>,
+  ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue> {
+    if (!name.trim()) {
+      throw new Error(
+        'steps().step(name, ...) requires a non-empty step name.',
+      );
+    }
+    return new DeeplineStepProgram(
+      [
+        ...this.steps,
+        {
+          name,
+          resolver: resolver as PlayStepProgramStep['resolver'],
+        },
+      ],
+      this.returnResolver as StepResolver<
+        Output & Record<Name, Value>,
+        ReturnValue
+      >,
+    );
+  }
+
+  return<Value>(
+    resolver: StepResolver<Output, Value>,
+  ): StepProgram<Input, Output, Value> {
+    return new DeeplineStepProgram(this.steps, resolver);
+  }
+}
+
+export function steps<TInput>(): StepProgram<TInput, TInput, TInput> {
+  return new DeeplineStepProgram<TInput, TInput, TInput>([]);
+}
+
+export function when<Row, Value>(
+  predicate: (row: Row, index: number) => boolean | Promise<boolean>,
+  resolver: StepResolver<Row, Value>,
+): ConditionalStepResolver<Row, Value, null> {
+  return new DeeplineConditionalStepResolver(predicate, resolver, null);
+}
+
+/**
+ * A defined play: both a callable function and a named play handle.
+ *
+ * Created by {@link definePlay}. Can be:
+ * 1. Called directly as a function (for server-side Temporal execution)
+ * 2. Used as a {@link DeeplineNamedPlay} for remote lifecycle operations
+ *
+ * @typeParam TInput - The play's input type
+ * @typeParam TOutput - The play's return type
+ *
+ * @example
+ * ```typescript
+ * import { definePlay } from 'deepline';
+ *
+ * const myPlay = definePlay('my-play', async (ctx, input: { domain: string }) => {
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
+ *     description: 'Look up company details by domain.',
+ *   });
+ *   return { company: company.result };
+ * });
+ *
+ * // Type is: DefinedPlay<{ domain: string }, unknown>
+ *
+ * // Use as named play handle:
+ * const detail = await myPlay.get();
+ * const result = await myPlay.runSync({ domain: 'stripe.com' });
+ *
+ * // Access metadata:
+ * console.log(myPlay.playName); // "my-play"
+ * console.log(myPlay.bindings); // undefined (no cron/webhook)
+ * ```
+ */
+export type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((
+  ctx: DeeplinePlayRuntimeContext,
+  input: TInput,
+) => Promise<TOutput>) &
+  DeeplineNamedPlay<TInput, TOutput> & {
+    /** Optional trigger bindings (cron, webhook). */
+    readonly bindings?: PlayBindings;
+    /** The play's name (same as `.name`). */
+    readonly playName: string;
+  };
+
+type PlayMetadata = {
+  name: string;
+  bindings?: PlayBindings;
+  inputSchema?: Record<string, unknown>;
+  billing?: PlayBindings['billing'];
+};
+
+const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
+
+class DeeplinePlayJobImpl<TOutput = unknown> implements PlayJob<TOutput> {
+  readonly id: string;
+
+  constructor(
+    private readonly client: DeeplineClient,
+    runId: string,
+  ) {
+    this.id = runId;
+  }
+
+  async status(): Promise<PlayStatus> {
+    return this.client.getPlayStatus(this.id);
+  }
+
+  async tail(options?: {
+    intervalMs?: number;
+    onLog?: (line: string) => void;
+  }): Promise<PlayStatus> {
+    const intervalMs = options?.intervalMs ?? 500;
+    const onLog = options?.onLog ?? ((line: string) => console.log(line));
+    const terminalStates = 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((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+
+  async get(options?: { intervalMs?: number }): Promise<TOutput> {
+    const intervalMs = options?.intervalMs ?? 500;
+    const terminalStates = 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 as { output?: unknown } | undefined;
+        return ((payload && 'output' in payload
+          ? payload.output
+          : status.result) ?? null) as TOutput;
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+
+  async cancel(): Promise<void> {
+    await this.client.cancelPlay(this.id);
+  }
+
+  async stop(options?: { reason?: string }): Promise<StopPlayRunResult> {
+    return this.client.stopPlay(this.id, options);
+  }
+}
+
+function createNamedPlayHandle<
+  TInput = Record<string, unknown>,
+  TOutput = unknown,
+>(
+  clientFactory: () => DeeplineClient,
+  name: string,
+): DeeplineNamedPlay<TInput, TOutput> {
+  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: TInput,
+      options?: { revisionId?: string },
+    ): Promise<PlayJob<TOutput>> {
+      const client = clientFactory();
+      const started = await client.startPlayRun({
+        name,
+        ...(options?.revisionId ? { revisionId: options.revisionId } : {}),
+        input: input as Record<string, unknown>,
+      });
+      return new DeeplinePlayJobImpl<TOutput>(client, started.workflowId);
+    },
+    async runSync(
+      input: TInput,
+      options?: { revisionId?: string },
+    ): Promise<TOutput> {
+      const job = await this.run(input, options);
+      return job.get();
+    },
+  };
+}
+
+/**
+ * High-level SDK context with tool shortcuts and play handles.
+ *
+ * Created by {@link Deepline.connect}. Wraps a {@link DeeplineClient} with
+ * a friendlier API for common operations.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await Deepline.connect();
+ *
+ * // Tools
+ * const tools = await ctx.tools.list();
+ * const result = await ctx.tools.execute({
+ *   tool: 'test_company_search',
+ *   input: { domain: 'stripe.com' },
+ * });
+ *
+ * // Plays
+ * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
+ * const output = await job.get();
+ * ```
+ */
+export class DeeplineContext {
+  private readonly client: DeeplineClient;
+
+  constructor(options?: DeeplineClientOptions) {
+    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: (): Promise<ToolDefinition[]> => this.client.listTools(),
+      /** Get detailed metadata for a tool. */
+      get: (toolId: string): Promise<ToolMetadata> =>
+        this.client.getTool(toolId),
+      /** Execute a tool and return an ergonomic result wrapper. */
+      execute: async (
+        request: SdkToolExecutionRequest,
+      ): Promise<ToolCallResult> =>
+        createToolCallResult(
+          await this.client.executeTool(request.tool, request.input),
+        ),
+    };
+  }
+
+  get plays() {
+    return {
+      list: () => this.client.listPlays(),
+      get: <TInput = Record<string, unknown>, TOutput = unknown>(
+        name: string,
+      ) => this.play<TInput, TOutput>(name),
+    };
+  }
+
+  get prebuilt(): Record<string, PrebuiltPlayRef> {
+    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',
+      },
+    } satisfies Record<string, PrebuiltPlayRef>;
+    return new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (typeof prop !== 'string') return undefined;
+          if (prop in explicit) {
+            return explicit[prop as keyof typeof explicit];
+          }
+          const playName = prop.startsWith('prebuilt/')
+            ? prop
+            : `prebuilt/${prop}`;
+          return {
+            playName,
+            name: playName,
+          } satisfies PrebuiltPlayRef;
+        },
+      },
+    ) as Record<string, PrebuiltPlayRef>;
+  }
+
+  /**
+   * 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<TInput = Record<string, unknown>, TOutput = unknown>(
+    name: string,
+  ): DeeplineNamedPlay<TInput, TOutput> {
+    return createNamedPlayHandle<TInput, TOutput>(() => this.client, name);
+  }
+
+  async runPlay<TInput = Record<string, unknown>, TOutput = unknown>(
+    playOrRef: string | PlayReferenceLike,
+    input: TInput,
+  ): Promise<TOutput> {
+    const name =
+      typeof playOrRef === 'string'
+        ? playOrRef
+        : (playOrRef.playName ?? playOrRef.name ?? '');
+    return await this.play<TInput, TOutput>(name).runSync(input);
+  }
+}
+
+/**
+ * Static entry point for the Deepline SDK.
+ *
+ * @example
+ * ```typescript
+ * import { Deepline } from 'deepline';
+ *
+ * const ctx = await Deepline.connect();
+ * const tools = await ctx.tools.list();
+ * const result = await ctx.tools.execute({
+ *   tool: 'test_company_search',
+ *   input: { domain: 'stripe.com' },
+ * });
+ * ```
+ */
+export class Deepline {
+  /**
+   * 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?: DeeplineClientOptions,
+  ): Promise<DeeplineContext> {
+    return new DeeplineContext(options);
+  }
+}
+
+export function defineInput<TInput>(
+  schema: Record<string, unknown>,
+): PlayInputContract<TInput> {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    throw new Error(
+      'defineInput<T>(schema) requires a JSON-schema-like object.',
+    );
+  }
+  return { schema };
+}
+
+/**
+ * Define a play — a composable TypeScript workflow for the Deepline platform.
+ *
+ * The returned value is both:
+ * 1. **A callable function** — invoked by the Temporal worker with a runtime context
+ * 2. **A named play handle** — with `.run()`, `.versions()`, `.get()`, `.publish()`, etc. for remote lifecycle management
+ *
+ * Plays are the primary abstraction for building repeatable data pipelines.
+ * They run on Temporal for durable execution with automatic retries and timeouts.
+ *
+ * @typeParam TInput - The input type accepted by the play
+ * @typeParam TOutput - The return type of the play
+ * @param name - Unique play name (used for publishing, running by name, and CLI reference)
+ * @param fn - Async function that receives a {@link DeeplinePlayRuntimeContext} and typed input
+ * @param bindings - Optional trigger bindings (cron schedule, webhook with HMAC)
+ * @returns A {@link DefinedPlay} that is both callable and has lifecycle methods
+ *
+ * @example Basic play
+ * ```typescript
+ * import { definePlay } from 'deepline';
+ *
+ * export default definePlay('company-lookup', async (ctx, input: { domain: string }) => {
+ *   ctx.log(`Searching for ${input.domain}`);
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
+ *     description: 'Look up company details by domain.',
+ *   });
+ *   return { company: company.result };
+ * });
+ * ```
+ *
+ * @example CSV processing play
+ * ```typescript
+ * export default definePlay('bulk-enrich', async (ctx) => {
+ *   const leads = await ctx.csv('leads.csv');
+ *   ctx.log(`Processing ${leads.length} rows`);
+ *   const results = await ctx
+ *     .map('domain', leads)
+ *     .step('company', (row, ctx) =>
+ *       ctx.tools.execute({
+ *         id: 'company_search',
+ *         tool: 'test_company_search',
+ *         input: { domain: row.domain },
+ *         description: 'Look up company details by domain.',
+ *       }))
+ *     .run({ description: 'Enrich lead companies.' });
+ *   return results;
+ * });
+ * ```
+ *
+ * @example With cron binding
+ * ```typescript
+ * export default definePlay('daily-report', async (ctx) => {
+ *   const data = await ctx.tools.execute({
+ *     id: 'crm_export',
+ *     tool: 'crm_export',
+ *     input: { since: 'yesterday' },
+ *     description: 'Export yesterday CRM records.',
+ *   });
+ *   return data;
+ * }, {
+ *   cron: { schedule: '0 9 * * *', timezone: 'America/New_York' },
+ * });
+ * ```
+ *
+ * @example Programmatic lifecycle
+ * ```typescript
+ * const myPlay = definePlay('my-play', handler);
+ *
+ * // Get play definition:
+ * const detail = await myPlay.get();
+ *
+ * // Run remotely:
+ * const result = await myPlay.runSync({ domain: 'stripe.com' });
+ *
+ * // Make the current draft live:
+ * await myPlay.publish();
+ * ```
+ */
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  config: DefinePlayConfig<TInput, TOutput>,
+): DefinedPlay<TInput, TOutput>;
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  name: string,
+  fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>,
+  bindings?: PlayBindings,
+): DefinedPlay<TInput, TOutput>;
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  nameOrConfig: string | DefinePlayConfig<TInput, TOutput>,
+  maybeFn?: (
+    ctx: DeeplinePlayRuntimeContext,
+    input: TInput,
+  ) => Promise<TOutput>,
+  maybeBindings?: PlayBindings,
+): DefinedPlay<TInput, TOutput> {
+  const config =
+    typeof nameOrConfig === 'string'
+      ? {
+          name: nameOrConfig,
+          fn: maybeFn,
+          bindings: maybeBindings,
+          inputSchema: undefined,
+          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: PlayMetadata = {
+    name,
+    ...(bindings ? { bindings } : {}),
+    ...(inputSchema ? { inputSchema } : {}),
+    ...(billing ? { billing } : {}),
+  };
+  const play = fn as DefinedPlay<TInput, TOutput>;
+
+  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<TInput, TOutput>(
+    () => new DeeplineClient(),
+    name,
+  );
+  for (const key of [
+    'name',
+    'get',
+    'runs',
+    'versions',
+    'publish',
+    'run',
+    'runSync',
+  ] as const) {
+    Object.defineProperty(play, key, {
+      value: handle[key],
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+
+  return play;
+}
+
+/**
+ * Alias for {@link definePlay}. Workflows and plays share the same public
+ * Deepline SDK contract; the selected execution profile decides whether the
+ * run is backed by local Node, Temporal/Daytona, or Cloudflare Dynamic
+ * Workflows.
+ */
+export const defineWorkflow = definePlay;
+
+/**
+ * Extract play metadata from a value that may be a defined play.
+ *
+ * Used internally by the CLI and bundler to detect `definePlay()` exports
+ * and extract the play name and bindings.
+ *
+ * @param value - Any value (typically a module's default export)
+ * @returns Play metadata if the value is a defined play, `null` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getDefinedPlayMetadata } from 'deepline';
+ *
+ * const mod = await import('./my-play.play.ts');
+ * const meta = getDefinedPlayMetadata(mod.default);
+ * if (meta) {
+ *   console.log(`Play name: ${meta.name}`);
+ *   console.log(`Bindings:`, meta.bindings);
+ * }
+ * ```
+ */
+export function getDefinedPlayMetadata(value: unknown): PlayMetadata | null {
+  if (typeof value !== 'function') {
+    return null;
+  }
+  const metadata = (value as unknown as Record<PropertyKey, unknown>)[
+    PLAY_METADATA_SYMBOL
+  ];
+  if (!metadata || typeof metadata !== 'object') {
+    return null;
+  }
+  const candidate = metadata as PlayMetadata;
+  if (!candidate.name || typeof candidate.name !== 'string') {
+    return null;
+  }
+  return candidate;
+}