deepline-plays

Deepline Plays

Quick Start

npm install -g deepline
deepline auth register --wait auto
deepline -h

Build, run and inspect

Plays and Tools

• Tool: one operation, such as looking up a profile or validating an email. Use direct tool calls for isolated spot checks.
• Play: TypeScript that expresses GTM work as code. Combine tools with custom logic—transformations, conditions and fallbacks—and process batches of data. Deepline handles provider rate limits and retries, persists progress and results, and supports recovery after failures.
• For workflows or batches: use a supplied Play, reuse or adapt a suitable prebuilt, or author one when none fits. Don't process batches by looping direct tool calls in scripts or repeated agent calls.

Workflow

• Discover/build: search and describe relevant Plays/tools; reuse a suitable prebuilt or adapt it. See authoring and the SDK reference.

• Check/pilot: inspect input mappings and run deepline plays check <file> before local-source execution. Pilot costly or unproven work within the agreed budget. Run small supplied Plays once, without a duplicate pilot or redesign.

• Run: plays run waits by default; --no-wait returns its ID immediately. Use runs tail <run-id> to follow an existing run and runs get <run-id> for status/results. After a disconnect, reconnect—don't relaunch.

• Inspect/transform: overview first, then follow the suggested commands. Play datasets persist in database tables. Prefer read-only SQL for filtering, joining, flattening and aggregating stored data before downloading. Inspect actual column types and sample values first; don't assume a JSON structure. After a type error, inspect the data rather than guessing another query. Adapt the suggested SQL, preserving its table and run filter.

  Get the run ID, physical tables and suggested SQL in one call:

  deepline runs get <run-id> --json run.id,datasets.storage,actions
  

  Check deepline runs get --help before using field selection. Older CLIs offer only bare --json; use it without a field list, or update the CLI. Save a tool contract with deepline tools describe <tool-id> --json > contract.json; tools describe does not accept --out. In Windows PowerShell 5.1, use cmd /d /c "deepline tools describe <tool-id> --json > contract.json" to keep the file UTF-8; direct PowerShell redirection writes UTF-16.

  Use the returned schema/table for <returned-table> (for example, "storage"."contact_email_waterfall_email_rows"). Copy the run-membership predicate from the suggested SQL into <returned-run-filter> (for example, _run_id = '<run-id>'); storage alone doesn't supply it. Check additional status filters and sample limits before computing whole-run totals. Use the dataset's actual columns and JSON structure:

  -- Aggregate before downloading.
  SELECT domain, COUNT(*) AS contacts, COUNT(email) AS emails_found
  FROM <returned-table>
  WHERE <returned-run-filter>
  GROUP BY domain;
  

  These are read-only projections, not changes to stored rows.

• Export: use the suggested export command for complete rows, CSV for delivery or --format json for nested evidence. The response is a file receipt—read the file. Use csv show <file> --summary for local CSV summaries.

• CLI hygiene: use -h; run deepline preflight --json as a standalone command and wait before parallel Deepline work. No head/tail truncation of CLI responses; use field selection or summaries. Preserve complete responses, separate stderr from JSON, and check exit status (pipefail for pipelines).

• Evidence: previews aren't complete results; completed runs can contain failures; nulls don't explain misses. Inspect affected rows, then use runs logs <run-id> --kind receipt.completed --payloads --json for saved tool results. Select an exact result by its returned eventId with --where. Logs reads don't execute tools. Investigate unresolved requested conditions and stop once supported. See debugging.

• Save/scope: keep deliverables in a durable project directory, preserve source files and every supplied identity, including misses and failed rows. Planning/inspection authorizes no paid execution; returned actions don't authorize retries, provider changes, publishing or external writes. Monitor access/consent remains separate. A credit shortage doesn't block otherwise accessible retained results.

Read logs and events: use deepline runs logs --help for all known kinds and filter examples. A run ID alone reads text logs; omit it or add a search flag to search events. Use --kind for run/step outcomes and --payloads for available details or saved results. Follow next.logs to page with the same UTC window. These reads execute no providers. Read Run logs and events for more recipes and SDK fields.

Write searchable customer logs: use ctx.log('Lookup finished', { context: { companyId: 'acme_123', rows: 12 } }), then filter with --where '$.context.companyId == "acme_123"'. The runtime attaches the authenticated org, Run, Play and known attempt; do not copy those into context. Customer KV cannot override that identity. Context allows eight flat scalar fields and 2 KiB per line, with a 128 KiB context budget per run. Sampling and run text limits also apply. Fetch large outputs through receipt events and --payloads, rather than logging their bodies.

Typed provider activity events also expose safe provider and operation keys for equality filters. They identify the provider and tool operation recorded by the runtime; they do not index raw request/response bodies or promise one search event per provider call.

deepline runs logs --kind run.failed --json
deepline runs logs --kind step.failed --payloads --json
deepline runs logs --kind receipt.failed --payloads --json

Use the installed command's --help before an unfamiliar flag. Skills can refresh independently of the CLI binary; an unsupported flag is a grammar or version mismatch, not evidence that the cloud operation failed. Follow an update hint when compatibility identifies a newer command, then rerun preflight before using the refreshed instructions.

Before the first Deepline fanout in a task, run deepline preflight --json as one standalone command and wait for it to finish. Never submit preflight beside another Deepline command.

The experiment methodology below applies when designing or comparing new work, not to execution-only or existing-run inspection requests.

contract → compare → exploit → recover → export → price

Ordinary TypeScript, no DSL. A SearchProgram is one function that calls a tool, a fetch, a child Play, a connector, or a local artifact and returns a typed attempt. runSearchExperiment owns the pilot, ranked waterfall, holdout, gap-only retries, and cost/coverage report.

Deliverable

Part	Contents
Result line	rows in / accepted / marginal credits per accepted row / run id
CSV	the user's exact headers, per-claim source, miss_reason on every null
Unresolved rows	in the same file; a null carries an absence receipt
Route table	initial and final waterfall, cost and completions per route
COST RECEIPT	the block run-and-export-search-experiment.py prints, verbatim
Next actions	dormant routes and what each would buy, at measured cost deltas

• Marginal, never amortized. Total ÷ successes reported 1.51 credits/email for a route whose real marginal cost was 0.21.
• Pass the printed block through. Do not recompute credits in prose.
• A catalog ceiling stops the run; it is not spend. Label it. A 120-credit ceiling truncated recovery at ~12 credits actual, and two apparent logic regressions were budget artifacts.

Read one job page

Read the row that matches this job, and only that row. Each page is complete for its job: source geometry, route ladder, pilot sizing, stop conditions.

The job	Page
Companies or people that are not rows yet	jobs/finding.md
Columns to fill on rows you already have	jobs/enriching.md
Claims that need attributable evidence	jobs/researching.md
A trigger, review gate, or external side effect	jobs/automating.md

Two lookups, consulted on a trigger rather than read up front: shared/authoring.md for Play syntax outside the scaffold, and references/debugging.md for a failed, empty, or misshapen run.

For every public definePlay/ctx.* type, binding, durable-cache rule, and runtime error, read references/sdk-reference.md. It is generated from the authoring contract and SDK source; do not duplicate that surface in this skill.

If your configuration forbids subagents, say so before starting serial work. Resolving that conflict silently cost one run ~30 minutes.

Topology

Write unit + decision + required facts + scale before touching tools. Requested fields stay required; demoting one to promote a run is not a pass. A null needs an absence receipt: materially different routes tried, typed outcomes retained.

One shape. Known rows: one experiment over the supplied rows. Open-world discovery: rows are query/page/geography/registry partitions, never remembered companies. Company → person: two sequential stages, not consensus; only companyExperiment.finalResults become contact rows. End-to-end: compare only when every program produces the same complete final row from the same seam.

Catalog

Use search commands without --json. Read the full default tools describe output before authoring; use JSON only when feeding a structured-data helper.

deepline search "<input you have -> result you need>" --type tools
deepline tools grep "<substring>"   # ranked search has returned the same
                                           # irrelevant hits for three different queries
deepline tools list <returned-category> --json
deepline tools describe <tool-id>
# Optional: extract declared getters programmatically after reading the contract.
deepline tools describe <tool-id> --json | python3 <skill-root>/scripts/show-declared-getters.py
python3 <skill-root>/scripts/show-declared-getters.py "$WORKDIR/<tool-id>.json"   # saved contract

tools describe is the authoring contract and can disagree with runtime: a declared getter has been absent, and a tool documenting one scalar has returned a full list. Bind a named declared playExpression and sentinel-probe one row before scaling. toolResponse.rawV2 is for an exact source excerpt, debugging, or an undeclared field after that probe — never a cast into an invented Company[].

Cover source classes before provider names — index, SERP, primary document, registry, event feed, first-party data, aggregator, validator. Two vendors reaching the same terminal corpus are one evidence lineage.

Record each route's pricing basis: per call, per returned result, or unknown. A confirmed-uncharged miss justifies a broader challenge wave, not a narrower one.

Build and run

python3 <skill-root>/scripts/scaffold-search-experiment.py \
  ./deepline/data/<task-slug> --name <task-slug> --input-csv <rows.csv>

Read its printed next list: it carries the four seams, tools: [...], coherenceChecks, and the company→person handoff at the point you edit them. --input-csv also writes a stratified fixture.csv. Iterate route code against that; use the full cohort only for a scored run.

Give definePlay a short, readable displayName when its identifier is unclear; the UI uses it as the title and derives a name from the identifier when absent. Keep the separate top-level description short and concrete about the Play's purpose. Catalog categories are derived from the registered tools used by the Play; do not author category metadata on the Play itself.

deepline billing balance --json
python3 <skill-root>/scripts/run-and-export-search-experiment.py \
  ./deepline/data/<task-slug>/<task-slug>.play.ts --input '{}' --out ./results.csv
python3 <skill-root>/scripts/cost-receipt.py <run-id> --scorecard <scorecard>.csv  # already-run

run-and-export does the structural check, Play check, completed Play, run-bound export of both the results dataset and the route scorecard, then the COST RECEIPT. Its {ok: true, runId, output} is the completion receipt: before it the work is a probe, and a CSV written from remembered values hides which route won.

Receipt labels:

• CUT CANDIDATE — spent credits, completed nothing. Cut it. One route at 3.95 credits/call, 200× a search, ran ten rounds for zero results because the scorecard reported no cost at all.
• NEVER REACHED — never invoked, so its zero results are not a ceiling and not a source miss. maxFallbacks bounds the dependency-closed waterfall and defaults to 2; raise it (up to 4, scaled to pool size) or drop the route.
• cached calls — reruns of the same inputs reuse tool receipts. Quote the marginal rate, not this run's total.

Quality gates precede economics; among valid results prefer fewer observed credits, then fewer calls. Never expose provider spend.

Reusing a route across jobs is an eval, not a score: freeze the contract, verifier, cases and ceiling, and stratify the case set (normal, sparse, likely-miss, collision-prone) rather than picking easy rows after seeing results. A concept is an information geometry, never a vendor.

Product friction feedback

Unless the user restricts external reporting, send one proactive deepline feedback send report per issue cluster when a Play is disproportionately slow, appears stuck through repeated status checks, or an ordinary result requires avoidable product steps. Continue the user's task after reporting; feedback is not the deliverable and does not authorize paid reproduction or session sharing.

Use judgment rather than a fixed threshold. Do not report normal provider work just because it is not instant. Report when the duration is surprising for the input size or prior comparable runs, progress stays uninformative, or the path needs avoidable discovery, conversion, ID extraction, retry, export, or manual workaround steps.

Include the goal and Play/run ID. For latency, include input size, observed duration, status transitions or polling count, and expected progress. For excess steps, include the actual path, avoidable detours, and expected direct path. Do not pass --requested for a proactive report. Omit --error-outcome when no error occurred; if an error did occur, use terminal only when it stopped the task and continued when work continued.

deepline feedback send "Goal: <goal>. Play/run: <play and run id>. Friction: <what was slow or indirect>. Observed: <duration, polling, or actual steps>. Expected: <reasonable duration, progress, or direct path>."

Subagents

One or two, only when several source geometries are plausible: same contract, one source lane each, returning a strategy card and ordinary TypeScript. The parent binds, runs, and judges. Verification fans out the same way — four defects found in four sequential rounds of eyeballing output fit in one pass over row batches.