@taprun/sdk — TypeScript SDK for Tap

Compile your AI agent's browser-acting trajectory into a deterministic program that replays at zero LLM tokens, with built-in drift verification.

npm install @taprun/sdk

5-line example

import { run, doctor } from "@taprun/sdk";

const rows = await run("hn/top");           // execute a compiled tap
console.log((rows as any[])[0].title);

const verdict = await doctor("hn/top");     // cross-validate against authoritative
console.log((verdict as any).status);       // 'ok' / 'broken' / 'stale'

What is Tap

Tap is the missing layer between your LLM agent and the websites it needs to act on. The compile-once / run-forever / diff-the-drift pattern in three primitives:

• forge — compile a browser trajectory into a deterministic .tap.json plan (one-shot AI cost, then 0 forever).
• run — replay the plan, no LLM in the loop.
• doctor — independently verify the plan still produces what it claims (drift detection without re-running your agent).

This SDK is a thin subprocess wrapper around the tap CLI binary.

Prerequisites

The tap CLI must be installed:

brew install LeonTing1010/tap/tap     # macOS
# Linux/Windows: see https://taprun.dev/install?utm_source=npm&utm_medium=package&utm_campaign=sdk-ts

Override the binary path via TAPRUN_BIN=/path/to/tap.

Compile from a browser-use trajectory

import { forge } from "@taprun/sdk";
// after `await agent.run()` from browser-use:
await forge({
  trajectory: agent.history,        // AgentHistoryList object, JSON string, or path
  site: "ycombinator",
  name: "homepage",
});
// writes ~/.tap/taps/ycombinator/homepage.tap.json — replays at 0 LLM tokens.

v1 compiles the navigation skeleton (go_to_url, click_element, input_text, scroll, wait, done). extract_content steps throw with a remediation pointing to tap forge <url> to compile the extraction half via Tier 0 sources (RSS / JSON-LD / agents.json / OpenAPI). Stagehand and Anthropic tool-use formats land in a follow-up.

API

import {
  run,        // tapId -> parsed rows
  doctor,     // tapId -> verdict
  verify,     // alias for doctor
  forge,      // url|description|{trajectory,site,name} -> compiled tap
  list,       // [site?] -> available taps
  show,       // tapId -> source + manifest + fingerprint
  stats,      // K(t) telemetry snapshot
  which,      // diagnostic — resolved tap binary path or null
  TapError,
  TapNotFoundError,
} from "@taprun/sdk";

All async functions throw TapError on non-zero CLI exit, or TapNotFoundError if the binary can't be located.

Latency

Each call is one process spawn (~30–100 ms warm). Fine for batch agent jobs; for hot loops use tap mcp start and call via MCP instead — the runtime stays resident.

Status

Alpha. API intentionally minimal while we collect integration feedback (browser-use, Stagehand, Anthropic SDK users). Surface stabilizes at 0.2.

Links

• Docs: https://taprun.dev/docs?utm_source=npm&utm_medium=package&utm_campaign=sdk-ts-docs
• CLI source: https://github.com/LeonTing1010/tap
• Issues: https://github.com/LeonTing1010/tap/issues

MIT License (this SDK wrapper). The tap CLI binary it shells out to is proprietary — see https://taprun.dev.