deepline 0.2.57 → 0.2.59

package/README.md

@@ -1,358 +1,49 @@
-# Deepline V2 SDK + CLI
+# Deepline
 
-TypeScript SDK and CLI for Deepline plays, tools, and enrichment.
+Deepline gives your coding agent the GTM data it needs to do useful work.
 
-## Dev workflow
+Give it a list of people or companies and ask it to find contact details,
+LinkedIn profiles, hiring signals, job postings, or a company's tech stack. It
+can enrich a CSV, research a market, or help you build a prospect list from
+Claude Code, Codex, or your terminal.
 
-### Prerequisites
+## What you can ask Deepline to do
 
-```bash
-bun run dev          # starts Next.js + Convex + Temporal + worker
-```
-
-Wait for health: `curl http://localhost:3000/api/v2/health`
+- Find the right people at a list of companies.
+- Add work emails, phone numbers, and LinkedIn profiles to a CSV.
+- Find companies that match your ideal customer profile.
+- Research a market, its companies, and their recent signals.
 
-### Auth (one-time)
+## Install
 
 ```bash
-./cli-env sdk-worktree deepline auth register
+npm install -g deepline@latest
+deepline setup --json
 ```
 
-Opens browser for approval. Stores SDK CLI auth in `~/.local/deepline/<host-slug>/.env`.
-
-Check status: `./cli-env sdk-worktree deepline auth status --json`
-
-### Making changes
-
-Edit any file in `sdk/src/` and re-run. No build step needed — `deepline-dev.ts` runs source directly via Bun.
-
-```bash
-# Edit sdk/src/cli/commands/play.ts
-# Then immediately:
-./cli-env sdk-worktree deepline plays run --file my-play.play.ts --watch
-```
-
-The root `package.json` has an alias, `bun run deepline`, that runs the same
-source CLI without selecting a host. Use `./cli-env sdk-worktree deepline ...`
-for local app/worktree development so the binary and `DEEPLINE_HOST_URL` move
-together.
-
-### When you need to build
+Setup opens your browser so you can sign in, then installs Deepline's skills
+for your coding agent. If global skill setup is unavailable, Deepline retries
+with project-local skills automatically.
 
-Only two cases require `npm run sdk:build`:
+## Use it with an agent
 
-1. **`npx --package=./sdk -- deepline`** — the path used by integration tests
-2. **Testing the published artifact** — verifying `dist/cli/index.mjs` works
-
-```bash
-cd sdk && bun run build    # or: npm run sdk:build from root
-```
-
-The published npm package is intentionally thin: it ships the SDK, CLI, and the
-minimal local play bundler required for `plays run --file`, `plays publish`, and
-`enrich`, without shipping Convex or broad app/provider source snapshots.
-
-## Env files
-
-| File                                 | Set by              | Contains                                |
-| ------------------------------------ | ------------------- | --------------------------------------- |
-| `~/.local/deepline/<host-slug>/.env` | SDK `auth register` | `DEEPLINE_HOST_URL`, `DEEPLINE_API_KEY` |
-| `.env.deepline`                      | Developer/agent     | `DEEPLINE_HOST_URL`, `DEEPLINE_API_KEY` |
-
-The SDK CLI env contract is only `DEEPLINE_HOST_URL` and `DEEPLINE_API_KEY`.
-Do not route the SDK CLI through `.env`, `.env.local`, or `.env.worktree`.
-
-Config resolution order:
+Paste this into Claude Code, Codex, or another coding agent:
 
 ```text
-host: explicit SDK option -> DEEPLINE_HOST_URL -> nearest .env.deepline -> Cowork workspace .env.deepline -> saved production auth -> https://code.deepline.com
-key:  explicit SDK option -> DEEPLINE_API_KEY -> matching nearest .env.deepline -> matching Cowork workspace .env.deepline -> saved auth for the resolved host
-```
-
-## CLI commands
-
-```bash
-./cli-env sdk-worktree deepline health
-./cli-env sdk-worktree deepline auth register
-./cli-env sdk-worktree deepline auth status
-./cli-env sdk-worktree deepline tools list
-./cli-env sdk-worktree deepline tools get test_rate_limit
-./cli-env sdk-worktree deepline tools describe test_rate_limit
-./cli-env sdk-worktree deepline tools execute test_rate_limit --input '{"key":"stripe.com"}'
-./cli-env sdk-worktree deepline plays run my-play.play.ts --input '{}' --watch
-./cli-env sdk-worktree deepline plays run company-lookup --input '{}' --watch
-./cli-env sdk-worktree deepline plays get company-lookup --json
-./cli-env sdk-worktree deepline plays versions company-lookup --json
-./cli-env sdk-worktree deepline runs list --play company-lookup --status failed --json
-./cli-env sdk-worktree deepline runs get run_123 --json
-./cli-env sdk-worktree deepline runs tail run_123 --json
-./cli-env sdk-worktree deepline runs stop run_123 --reason "no longer needed" --json
-./cli-env sdk-worktree deepline plays publish my-play.play.ts --latest --json
-./cli-env sdk-worktree deepline update
-```
-
-`tools describe` is the compact tool contract, `tools get` is a compatibility
-alias for `tools describe`, and `tools execute` runs an atomic tool. The SDK CLI
-does not expose the legacy `tools run` alias. Unknown `plays run` flags such as
-`--limit 5` are passed into the play input object. CSV file inputs should be
-passed through `--input`, matching the play contract, for example
-`--input '{"file":"leads.csv"}'` for `ctx.csv(input.file)`.
-
-## Public play entrypoints
-
-These are the public ways to run plays. They intentionally map to the external
-surfaces we exercise in CI:
-
-1. CLI
-   - Repo-local Bun/source CLI: `bun sdk/bin/deepline-dev.ts plays run ...`
-   - Repo script alias: `bun run deepline -- plays run ...`
-   - Installed CLI: `deepline plays run ...`
-2. Programmatic SDK convenience client
-   - `client.runPlay(...)`
-   - `client.runs.get(runId)`
-   - `client.runs.list({ play: name })`
-   - `client.runs.tail(runId)`
-   - `client.runs.stop(runId, { reason })`
-3. Connected SDK context (outside a running play)
-   - `ctx.play(name).run(...)`
-   - `ctx.play(name).runSync(...)`
-   - `ctx.runPlay(name, input)`
-4. Raw HTTP API
-   - `POST /api/v2/plays/run`
-   - `GET /api/v2/runs/:runId`
-   - `GET /api/v2/runs/:runId/tail`
-5. In-play composition
-   - `ctx.runPlay(key, playRef, input, { description })`
-   - Org-owned `playRef` accepts a bare name, `self/<play>`, or the canonical
-     `<orgSlug>/<play>` returned by `plays get`.
-
-Internal / advanced only:
-
-- `registerPlayArtifact()`
-- `stagePlayFiles()`
-- `startPlayRun()`
-- `getPlayStatus()`
-- `getPlayTailStatus()`
-- `listPlayRuns()`
-- `stopPlay()`
-
-Those low-level primitives are still available for callers that explicitly need
-to own the package-submit-poll flow, but they are not the primary public SDK
-surface.
-
-## SDK usage (programmatic)
-
-```typescript
-import { Deepline, definePlay } from 'deepline';
-
-const ctx = await Deepline.connect();
-
-// Tools
-const tools = await ctx.tools.list();
-const toolResult = await ctx.tools.execute('test_company_search', {
-  domain: 'stripe.com',
-});
-const company = toolResult.toolOutput.raw;
-
-// Named play (already live)
-const job = await ctx.play('my-play').run({ domain: 'example.com' });
-const status = await job.status();
-const output = await job.get(); // polls until complete
-
-// Define + run a play
-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.toolOutput.raw };
-});
-
-const detail = await myPlay.get();
-const playResult = await myPlay.runSync({ domain: 'example.com' });
-```
-
-## Testing
-
-```bash
-# Unit tests (no server needed)
-bun run vitest run tests/lib/plays tests/api/plays-get-route.test.ts
-
-# SDK + CLI integration (needs running dev server)
-bash scripts/test-sdk-play-cli.sh
-
-# V2 plays e2e — all free test tools, real Temporal (needs running dev server)
-bun tests/v2-plays/runner.ts --top 10
-bun tests/v2-plays/runner.ts --shard 1/4
-bun tests/v2-plays/runner.ts --file tests/v2-plays/plays/07-waterfall-basic.play.ts
-```
-
-## Repro: rate limit handling (end-to-end)
-
-Full sequence from zero to hitting + surviving rate limits via v2 plays.
-
-### 1. Install + auth
-
-```bash
-# Production
-bash <(curl -fsSL https://deepline.com/api/v2/sdk/install)
-
-# Local dev (no install needed)
-bun run dev   # start server
-bun sdk/bin/deepline-dev.ts auth register
-```
-
-### 2. Write a play that hammers the rate-limited test tool
-
-```bash
-cat > rate-limit-repro.play.ts << 'TS'
-import { definePlay } from 'deepline';
-
-// test_rate_limit has a 5 req/s shared window — this play fires 20 calls
-// to force 429s and prove the runtime retries + backs off correctly.
-export default definePlay('rate-limit-repro', async (ctx) => {
-  const items = Array.from({ length: 20 }, (_, i) => ({
-    key: `probe-${i}`,
-    row_number: i + 1,
-  }));
-
-  const results = await ctx.dataset('rate_limit_probes', items)
-  .withColumn("result", (row, ctx) =>
-      ctx.tools.execute({
-        id: 'rate_limit_probe',
-        tool: 'test_rate_limit',
-        input: {
-        key: 'redis-shared-scenario',
-        row_number: row.row_number,
-      },
-        description: 'Exercise the shared rate-limit retry path.',
-      }))
-  .run();
-
-  return { total: results.length, results };
-});
-TS
-```
-
-### 3. Run it
-
-```bash
-# Dev
-bun sdk/bin/deepline-dev.ts plays run --file rate-limit-repro.play.ts --watch
-
-# Production
-deepline plays run --file rate-limit-repro.play.ts --watch
+Set up https://code.deepline.com/INSTALL.md
 ```
 
-### 4. Fallback variant (multi-step with rate limits)
+Once setup is complete, tell your agent what you want to do:
 
-Use `steps()` with `{ runIf }` options to express row-level fallback sequences.
-Skipped conditional steps yield `null`.
+- "Find 5 NYC CTOs with work emails."
+- "Enrich the contacts in leads.csv."
+- "Upload a CSV of accounts and add emails, phones, LinkedIn profiles, job postings, or tech stack."
+- "Research this market and the companies in it."
 
-```bash
-cat > rate-limit-waterfall.play.ts << 'TS'
-import { definePlay, steps } from 'deepline';
-
-export default definePlay('rate-limit-waterfall', async (ctx) => {
-  const leads = Array.from({ length: 24 }, (_, i) => ({
-    lead_id: `lead-${String(i + 1).padStart(3, '0')}`,
-    row_number: i + 1,
-  }));
-
-  const probeFallback = steps<{ lead_id: string; row_number: number }>()
-    .step("primary_probe", (row, ctx) =>
-      ctx.tools.execute({
-        id: 'rate_limit_probe',
-        tool: 'test_rate_limit',
-        input: {
-          key: 'redis-shared-scenario',
-          lead_id: row.lead_id,
-          row_number: row.row_number,
-        },
-        description: 'Exercise primary rate-limit behavior.',
-      }))
-    .step(
-      "backup_probe",
-      (row, ctx) =>
-        ctx.tools.execute({
-          id: 'rate_limit_probe_backup',
-          tool: 'test_rate_limit',
-          input: {
-            key: 'redis-shared-scenario',
-            lead_id: row.lead_id,
-            row_number: row.row_number,
-          },
-          description: 'Exercise fallback rate-limit behavior.',
-        }),
-      { runIf: (row) => !row.primary_probe },
-    )
-    .return((row) => row.primary_probe ?? row.backup_probe ?? null);
-
-  // Fan out over leads — each gets a row-level fallback sequence
-  const results = await ctx.dataset('leads', leads)
-    .withColumn("probe", probeFallback)
-    .run();
-
-  return results;
-});
-TS
-```
+## Check your setup
 
 ```bash
-bun sdk/bin/deepline-dev.ts plays run --file rate-limit-waterfall.play.ts --watch
+deepline doctor --json
 ```
 
-### What to expect
-
-- `test_rate_limit` has a Redis-backed rate limit: **5 req/s, 3 max concurrency**.
-- The SDK HTTP client auto-retries 429s with exponential backoff (1s → 2s → 4s, capped at 30s, up to 4 attempts).
-- The play rate limit scheduler (`PlayRateLimitScheduler`) paces tool calls using `queue_hint` metadata from rate limit definitions.
-- All 20/24 rows should complete — no terminal rate limit errors in the output.
-- The waterfall variant proves that short-circuiting (skipping later steps when earlier steps match) works correctly under rate pressure.
-
-### V1 equivalent
-
-The v1 repro scripts use `deepline enrich` (Python CLI) with `--with` JSON specs. The v2 plays replace this with typed TypeScript — same backend rate limit infrastructure, better DX.
-
-```bash
-# V1 (still works)
-scripts/repro-rate-limit-enrich.sh redis_429
-scripts/repro-rate-limit-enrich.sh redis_429_waterfall
-```
-
-## Prebuilt plays
-
-V2 prebuilt play sources are authored directly in `src/lib/plays/v2/`. After
-editing them, regenerate the committed Workers and share-page artifacts:
-
-```bash
-bun scripts/regen.ts prebuilt-share-pages
-```
-
-## File structure
-
-```
-sdk/
-  bin/deepline-dev.ts           # Dev entry (bun, no build, points at localhost)
-  src/
-    index.ts                    # Public exports
-    config.ts                   # Config + env resolution
-    http.ts                     # Fetch client with retries
-    client.ts                   # DeeplineClient (tools, plays API)
-    play.ts                     # definePlay, Deepline.connect, job handles
-    types.ts                    # TypeScript interfaces
-    errors.ts                   # DeeplineError, AuthError, RateLimitError
-    cli/
-      index.ts                  # CLI router
-      commands/
-        auth.ts                 # auth register/status
-        play.ts                 # plays run/get/tail/runs/publish
-        tools.ts                # tools list/describe/execute
-        enrich.ts               # CSV enrichment (delegates to Python CLI)
-    plays/
-      bundle-play-file.ts       # esbuild bundler for .play.ts files
-      local-file-discovery.ts   # ctx.csv() file resolution + packaging
-  dist/                         # Build output (gitignored)
-```
+Need help? Visit [code.deepline.com](https://code.deepline.com).

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

@@ -160,7 +160,7 @@ export const SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: '0.2.57',
+  version: '0.2.59',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/cli/index.js

@@ -1044,7 +1044,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.57",
+  version: "0.2.59",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -37051,7 +37051,7 @@ var install_commands_default = {
     npx_binary: "npx",
     npx_add_args_template: [
       "--yes",
-      "skills@latest",
+      "skills@1.5.18",
       "add",
       "{skills_index_url}",
       "--agent",
@@ -37072,6 +37072,9 @@ var install_commands_default = {
 // src/cli/install-commands.ts
 var INSTALL_COMMANDS = install_commands_default;
 var DEFAULT_SKILL_AGENTS = INSTALL_COMMANDS.skills.default_agents;
+var SKILLS_NPX_PACKAGE = INSTALL_COMMANDS.skills.npx_add_args_template.find(
+  (arg) => arg.startsWith("skills@")
+) ?? "skills@1.5.18";
 var DEFAULT_V1_SKILL_NAMES = [
   "build-tam",
   "clay-to-deepline",
@@ -37278,7 +37281,7 @@ function buildSkillsPlan(input2) {
       args: [
         "exec",
         "--yes",
-        "--package=skills@latest",
+        `--package=${SKILLS_NPX_PACKAGE}`,
         "--",
         "skills",
         "remove",
@@ -37294,7 +37297,7 @@ function buildSkillsPlan(input2) {
       args: [
         "exec",
         "--yes",
-        "--package=skills@latest",
+        `--package=${SKILLS_NPX_PACKAGE}`,
         "--",
         "skills",
         "add",
@@ -37350,7 +37353,7 @@ function runProcess(command, args, cwd) {
     child.once("error", reject);
     child.once("close", (code) => {
       if (code && stderr.trim()) {
-        process.stderr.write(`skills@latest exited ${code}.
+        process.stderr.write(`${SKILLS_NPX_PACKAGE} exited ${code}.
 `);
       }
       resolve19(code ?? 1);
@@ -37535,7 +37538,7 @@ function registerSkillsCommand(program) {
     `
 Notes:
   This command removes and reinstalls only Deepline-managed skill names using
-  skills@latest. Local scope writes into the resolved persistent project.
+  skills@1.5.18. Local scope writes into the resolved persistent project.
 
 Examples:
   deepline skills --json
@@ -38854,7 +38857,7 @@ function reportSetupPhaseFailure(input2) {
       failedPhase: input2.phase,
       retry,
       statePath,
-      next: retry.command,
+      next: input2.next ?? retry.command,
       ...input2.extra ?? {}
     },
     { json: input2.json }
@@ -39103,7 +39106,7 @@ async function runSetupCommand(options) {
           json: options.json,
           extra: {
             persistentPath: globalCli.persistentPath,
-            fallback: "https://code.deepline.com/SKILL.md"
+            fallback: "https://code.deepline.com/INSTALL.md"
           }
         });
       }
@@ -39168,6 +39171,14 @@ async function runSetupCommand(options) {
     );
     skillsPayload = parseCapturedJson(skills.stdout);
     if (skills.exitCode !== 0) {
+      if (scope === "global") {
+        phases.skills = { status: "failed", code: "SKILLS_INSTALL_FAILED" };
+        persistSetupProgress({ baseUrl, scope, root, phases });
+        process.stderr.write(
+          "Global skill setup failed. Trying project-local skills instead.\n"
+        );
+        return runSetupCommand({ scope: "local", json: options.json });
+      }
       return reportSetupPhaseFailure({
         baseUrl,
         scope,
@@ -39178,6 +39189,7 @@ async function runSetupCommand(options) {
         exitCode: skills.exitCode,
         message: typeof skillsPayload?.message === "string" ? skillsPayload.message : "Deepline skills could not be installed.",
         json: options.json,
+        next: `! ${setupResumeCommand(baseUrl, scope)}`,
         extra: { detail: skillsPayload }
       });
     }

package/dist/cli/index.mjs

@@ -1030,7 +1030,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.57",
+  version: "0.2.59",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -37131,7 +37131,7 @@ var install_commands_default = {
     npx_binary: "npx",
     npx_add_args_template: [
       "--yes",
-      "skills@latest",
+      "skills@1.5.18",
       "add",
       "{skills_index_url}",
       "--agent",
@@ -37152,6 +37152,9 @@ var install_commands_default = {
 // src/cli/install-commands.ts
 var INSTALL_COMMANDS = install_commands_default;
 var DEFAULT_SKILL_AGENTS = INSTALL_COMMANDS.skills.default_agents;
+var SKILLS_NPX_PACKAGE = INSTALL_COMMANDS.skills.npx_add_args_template.find(
+  (arg) => arg.startsWith("skills@")
+) ?? "skills@1.5.18";
 var DEFAULT_V1_SKILL_NAMES = [
   "build-tam",
   "clay-to-deepline",
@@ -37358,7 +37361,7 @@ function buildSkillsPlan(input2) {
       args: [
         "exec",
         "--yes",
-        "--package=skills@latest",
+        `--package=${SKILLS_NPX_PACKAGE}`,
         "--",
         "skills",
         "remove",
@@ -37374,7 +37377,7 @@ function buildSkillsPlan(input2) {
       args: [
         "exec",
         "--yes",
-        "--package=skills@latest",
+        `--package=${SKILLS_NPX_PACKAGE}`,
         "--",
         "skills",
         "add",
@@ -37430,7 +37433,7 @@ function runProcess(command, args, cwd) {
     child.once("error", reject);
     child.once("close", (code) => {
       if (code && stderr.trim()) {
-        process.stderr.write(`skills@latest exited ${code}.
+        process.stderr.write(`${SKILLS_NPX_PACKAGE} exited ${code}.
 `);
       }
       resolve19(code ?? 1);
@@ -37615,7 +37618,7 @@ function registerSkillsCommand(program) {
     `
 Notes:
   This command removes and reinstalls only Deepline-managed skill names using
-  skills@latest. Local scope writes into the resolved persistent project.
+  skills@1.5.18. Local scope writes into the resolved persistent project.
 
 Examples:
   deepline skills --json
@@ -38942,7 +38945,7 @@ function reportSetupPhaseFailure(input2) {
       failedPhase: input2.phase,
       retry,
       statePath,
-      next: retry.command,
+      next: input2.next ?? retry.command,
       ...input2.extra ?? {}
     },
     { json: input2.json }
@@ -39191,7 +39194,7 @@ async function runSetupCommand(options) {
           json: options.json,
           extra: {
             persistentPath: globalCli.persistentPath,
-            fallback: "https://code.deepline.com/SKILL.md"
+            fallback: "https://code.deepline.com/INSTALL.md"
           }
         });
       }
@@ -39256,6 +39259,14 @@ async function runSetupCommand(options) {
     );
     skillsPayload = parseCapturedJson(skills.stdout);
     if (skills.exitCode !== 0) {
+      if (scope === "global") {
+        phases.skills = { status: "failed", code: "SKILLS_INSTALL_FAILED" };
+        persistSetupProgress({ baseUrl, scope, root, phases });
+        process.stderr.write(
+          "Global skill setup failed. Trying project-local skills instead.\n"
+        );
+        return runSetupCommand({ scope: "local", json: options.json });
+      }
       return reportSetupPhaseFailure({
         baseUrl,
         scope,
@@ -39266,6 +39277,7 @@ async function runSetupCommand(options) {
         exitCode: skills.exitCode,
         message: typeof skillsPayload?.message === "string" ? skillsPayload.message : "Deepline skills could not be installed.",
         json: options.json,
+        next: `! ${setupResumeCommand(baseUrl, scope)}`,
         extra: { detail: skillsPayload }
       });
     }

package/dist/index.js

@@ -763,7 +763,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.57",
+  version: "0.2.59",
   contracts: {
     api: {
       name: "sdk-http-api",

package/dist/index.mjs

@@ -689,7 +689,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.57",
+  version: "0.2.59",
   contracts: {
     api: {
       name: "sdk-http-api",

package/package.json

@@ -1,12 +1,8 @@
 {
   "name": "deepline",
-  "version": "0.2.57",
-  "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
+  "version": "0.2.59",
+  "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deeplineai/deepline.git"
-  },
   "homepage": "https://code.deepline.com",
   "keywords": [
     "deepline",