web-task-api 0.2.1

package/docs/design.md

@@ -0,0 +1,513 @@
+# Web Task API Design Doc
+
+## Summary
+
+Build a generalized browser-task platform inside our projects that turns websites into outcome-oriented APIs. Instead of hardcoding one adapter per site, the system runs a real browser, lets an agent choose actions from structured browser tools, validates output against a schema, and stores artifacts for replay and debugging.
+
+This MVP intentionally favors the architecture we actually want long term:
+
+- agent-first execution
+- browser as the substrate
+- recipes as optimization, not the default
+- login/profile reuse
+- task-level JSON results
+- strong traces and verification
+
+## Problem
+
+Many useful websites have no API, weak APIs, or UI-only features. Per-site scrapers and automations work short term but do not scale:
+
+- selectors break
+- every site needs its own code path
+- login/session handling becomes duplicated
+- observability and replay are inconsistent
+- unknown future websites require fresh engineering every time
+
+We want a common layer that lets our projects say:
+
+> Start from this URL, achieve this goal, return typed JSON.
+
+## Goals
+
+1. Expose a single task API for “read” and “act” use cases.
+2. Run against a real browser with persistent login profiles.
+3. Support freeform agent control without shipping per-site code first.
+4. Validate outputs against a supplied JSON schema.
+5. Persist step traces, screenshots, and final artifacts.
+6. Allow repeated high-value flows to be promoted into recipes later.
+7. Keep the runtime framework-light and provider-agnostic.
+8. Preserve browser/session state across related tasks so agents can chain work over time.
+
+## Non-goals for MVP
+
+- distributed job queue
+- multi-tenant billing/quotas
+- residential proxy/captcha infrastructure
+- human-in-the-loop approvals
+- production-grade secret vault
+- full workflow scheduling/webhooks
+
+Those are expected future layers, not blockers for proving the core architecture.
+
+## Key decisions
+
+### 0) Session continuity is a first-class product feature
+
+Users do not always want one isolated task. Real workflows look like:
+
+- open Axiom with an authenticated profile
+- inspect a token on GMGN as a guest
+- carry findings into a later action task
+
+So the product needs durable session records that survive across task runs, not just durable browser profiles.
+
+## Session architecture choices
+
+### Choice A — Stateless tasks only
+
+- every task fully self-contained
+- browser state supplied ad hoc with `profile`
+- no cross-task context
+
+Pros:
+
+- simplest implementation
+- easy horizontal scaling
+
+Cons:
+
+- weak for real agent workflows
+- hard to chain research -> action -> verification
+- no durable task memory except raw run files
+
+### Choice B — Named sessions backed by file-backed metadata and browser profiles **(chosen)**
+
+- create a session record once
+- bind optional profile, start URL, default agent config, and notes
+- append compact task history after each run
+- allow future tasks to refer to `sessionId`
+
+Pros:
+
+- simple enough for local/product usage now
+- supports guest sessions and authenticated/profile sessions
+- enables connected tasks without building a full workflow engine
+
+Cons:
+
+- file-backed state is single-machine scoped
+- not yet multi-worker safe
+
+### Choice C — Full workflow engine with long-lived browser workers
+
+- queue-backed sessions
+- pinned worker/browser lifecycle
+- richer inter-task memory and live state
+
+Pros:
+
+- strongest long-term orchestration model
+
+Cons:
+
+- too much infrastructure for this stage
+- would slow delivery of the core product
+
+### Chosen approach
+
+Choose **B** now:
+
+- it gives real cross-task continuity
+- it composes with persistent browser profiles
+- it can later evolve toward C without breaking the task API
+
+### 1) Agent-first, recipe-assisted architecture
+
+Default behavior is goal-driven browser control. Recipes are optional overlays that add hints, matching, and reusable assertions. This avoids recreating the brittle adapter trap.
+
+### 2) Thin custom orchestrator over large agent frameworks
+
+There is no universal “golden standard” agent framework that is both simple and future-proof. For the MVP we use a small internal loop:
+
+- provider adapter
+- browser tools
+- run state
+- structured task contract
+
+Why not make LangChain the core?
+
+- too much framework gravity for the moat we actually care about
+- browser/session/runtime quality matters more than chain abstractions
+- easier to keep provider compatibility with our own small interface
+
+### 3) Pluggable planner backends: CLIProxyAPI first, OpenCode optional
+
+The preferred production path uses CLIProxyAPI-managed auth and model routing, while keeping OpenCode as an optional adapter.
+
+Why this split:
+
+- OpenCode is powerful, but it is coding-native and should not be the only foundation for a general web agent platform.
+- CLIProxyAPI is a better auth/routing layer for general LLM access.
+- We still want OpenCode available where it already fits the local stack well.
+
+CLIProxy path gives:
+
+- proxy-managed auth instead of vendor-specific API keys
+- one place to swap models/providers
+- easy reuse of existing CLI/OAuth-backed setups
+
+Important nuance: CLIProxyAPI is not treated here as “one API key for one provider”. It is treated as a routing/auth layer that may expose multiple providers, multiple accounts, and model aliases behind one compatible endpoint.
+
+OpenCode path gives:
+
+- a local programmable agent runtime we already use
+- support for headless/server usage through `@opencode-ai/sdk`
+- structured JSON output via session prompt formatting
+- compatibility with existing provider routing, including CLIProxyAPI-backed setups
+
+For practical local operation, we also support an `auto` mode:
+
+- probe CLIProxy first and use it when reachable/authenticated
+- if no planner model alias is configured for CLIProxy, fall back to OpenCode instead of failing late
+- otherwise fall back to OpenCode so existing local GPT/OAuth setup still works
+
+This is specifically useful when model auth is already solved in the machine via OpenCode but we still want the product surface to stay general-web focused rather than OpenCode-centric.
+
+The code isolates this behind an `AgentAdapter` interface so other planners can still be added later.
+
+### 4) Deterministic mock agent for tests and demos
+
+We need end-to-end verification without external credentials. The MVP includes a local mock agent that can drive semantically-labeled pages and extract structured data from a fixture site. This proves the whole stack works now.
+
+### 5) Element IDs instead of exposing selectors to the model
+
+The snapshot tool returns normalized interactive elements with generated IDs. The agent acts on `elementId`, not raw selectors. Internally we still keep the selector/path mapping, but the model contract stays higher level.
+
+## System overview
+
+```text
+HTTP task request
+  -> TaskRunner
+    -> RecipeRegistry resolve/match
+    -> BrowserSession bootstrap (persistent profile + browser hardening)
+    -> Agent loop
+       -> snapshot current page
+       -> agent selects browser tool
+       -> runtime executes tool
+       -> loop until finish/fail
+    -> JSON schema validation
+    -> artifacts + run record persisted
+    -> HTTP response
+```
+
+## Main components
+
+### API server
+
+Fastify server with endpoints for:
+
+- `GET /health`
+- `GET /v1/recipes`
+- `GET /v1/sessions`
+- `POST /v1/sessions`
+- `GET /v1/sessions/:sessionId`
+- `PATCH /v1/sessions/:sessionId`
+- `POST /v1/tasks/run`
+- `GET /v1/tasks/:taskId`
+
+### Task runner
+
+Owns the end-to-end execution lifecycle:
+
+- creates run directory
+- resolves recipe and session defaults
+- starts browser session
+- drives the agent loop
+- validates output
+- stores result record and session history
+
+### Session store
+
+File-backed session records with:
+
+- session ID and name
+- guest/profile mode
+- optional bound browser profile
+- optional default start URL
+- optional default agent configuration
+- notes
+- compact recent task history
+
+### Browser session
+
+Playwright wrapper that provides structured browser tools:
+
+- navigate
+- snapshot
+- click element
+- fill element
+- press element
+- select option
+- wait for text
+- read page text
+- capture screenshot
+
+### Agent adapter
+
+Interface:
+
+- receive run state + tool results
+- return assistant tool calls
+
+Implementations:
+
+- `CliProxyAgent`
+- `OpencodeAgent`
+- `MockAgent`
+
+### Recipe registry
+
+Recipes are JSON definitions with:
+
+- id/name/description
+- URL matching hints
+- prompt augmentations
+- preferred input aliases
+- optional completion assertions
+
+Recipes do not replace the agent. They sharpen it.
+
+### File-backed run store
+
+Stores:
+
+- `runs/<taskId>/task.json`
+- `runs/<taskId>/steps.jsonl`
+- screenshots
+- raw result/metadata
+
+This is enough for local replay and debugging.
+
+## Request contract
+
+### Task request
+
+```json
+{
+  "goal": "Search for banana and return product, price, and stock.",
+  "startUrl": "http://127.0.0.1:4010/",
+  "sessionId": "d8dd1a8f-0f31-4d6b-b6bb-0ff1452b9352",
+  "profile": "default",
+  "mode": "act",
+  "input": {
+    "query": "banana"
+  },
+  "outputSchema": {
+    "type": "object",
+    "required": ["product", "price", "stock"],
+    "properties": {
+      "product": { "type": "string" },
+      "price": { "type": "string" },
+      "stock": { "type": "string" }
+    }
+  },
+  "agent": {
+    "kind": "cliproxy"
+  },
+  "limits": {
+    "maxSteps": 12,
+    "timeoutMs": 90000,
+    "headless": true
+  }
+}
+```
+
+### Task response
+
+Includes:
+
+- task ID
+- status
+- validated result
+- summary trace
+- matched recipe
+- artifact directory
+- timing metadata
+
+## Tool contract exposed to the agent
+
+The agent receives structured tools, not arbitrary code execution.
+
+### `snapshot`
+
+Returns:
+
+- current URL/title
+- text preview
+- visible interactive elements with stable `elementId`s
+- forms and semantic labels
+
+### `navigate`
+
+Navigate to a URL.
+
+### `click`
+
+Click a visible interactive element by `elementId`.
+
+### `fill`
+
+Fill an input-like element by `elementId`.
+
+### `press`
+
+Press a keyboard key against an element.
+
+### `select`
+
+Select a value on a `<select>` element.
+
+### `wait_for_text`
+
+Wait until expected text appears.
+
+### `read_page`
+
+Read full visible text in a normalized form for extraction/verification.
+
+### `finish`
+
+Return the structured result.
+
+### `fail`
+
+Abort the run with a machine-readable reason.
+
+## Safety model
+
+The MVP keeps safety simple and explicit:
+
+- tool sandbox is browser-only; no arbitrary shell/file tools exposed to the model
+- max step limit
+- wall-clock timeout
+- output schema validation
+- task trace for auditing
+- manual login bootstrap instead of storing credentials in the request
+
+## Observability
+
+Each run stores:
+
+- request metadata
+- step-level tool calls/results
+- page screenshots
+- final JSON result or failure reason
+
+This is critical because browser agents fail in ways that need replay, not just logs.
+
+## Real-world constraint discovered during validation
+
+Public targets like Dexscreener and GMGN are currently fronted by Cloudflare/bot protection from fresh headless sessions in this environment. That means a serious product cannot assume every public site is immediately automatable with a brand-new clean headless browser.
+
+So the product design now explicitly supports three continuity paths:
+
+- named persistent profiles for authenticated sites
+- `BROWSER_USER_DATA_DIR` for “use my real Chrome profile” behavior
+- session-bound browser storage for guest workflows that still need continuity across tasks
+
+The bundled GMGN/Dexscreener recipes should therefore be treated as starter recipes that depend on warmed browser state, not as guaranteed out-of-the-box site integrations. Protected-site recipes now explicitly require either a named persistent profile, `BROWSER_USER_DATA_DIR`, or a **warmed** `sessionId` so the runtime does not pretend a fresh temp browser will behave like a human’s already-warmed Chrome profile.
+
+## Planned directory structure
+
+```text
+src/
+  agents/
+  browser/
+  recipes/
+  sessions/
+  server/
+  storage/
+  tasks/
+tests/
+  fixtures/
+scripts/
+docs/
+examples/
+profiles/
+runs/
+```
+
+## Detailed implementation plan
+
+### Phase 1 — Core contracts
+
+1. Define request/response schemas.
+2. Build file-backed run store.
+3. Build recipe registry.
+4. Build Fastify app + routes.
+
+### Phase 2 — Browser runtime
+
+1. Wrap Playwright launch/context/page.
+2. Add snapshot extraction with element IDs.
+3. Add browser tools and error handling.
+4. Persist screenshots and basic metrics.
+
+### Phase 3 — Agent loop
+
+1. Define provider-neutral `AgentAdapter`.
+2. Implement CLIProxy planner adapter.
+3. Implement OpenCode adapter as an optional backend.
+4. Implement mock adapter.
+4. Add system prompt and loop orchestration.
+
+### Phase 4 — Profiles, examples, docs
+
+1. Add manual login bootstrap script.
+2. Add demo script.
+3. Add sample recipe and example request.
+4. Write README and operating notes.
+
+### Phase 5 — Session continuity
+
+1. Add file-backed session store.
+2. Add session create/read/update/list endpoints.
+3. Merge session defaults into task runs.
+4. Append compact task history back into sessions.
+
+### Phase 6 — Verification
+
+1. Create local fixture site.
+2. Run end-to-end task against fixture site.
+3. Verify schema validation and stored artifacts.
+4. Verify session-backed connected tasks.
+5. Run typecheck, tests, and build.
+
+## Future roadmap
+
+After the MVP proves the architecture, the highest-value next layers are:
+
+1. async queue + webhook completion
+2. profile/session service with encrypted secrets
+3. browser pools and worker isolation
+4. stronger DOM understanding and recovery policies
+5. proxy and anti-detection layer
+6. recipe learning/promotion from successful runs
+7. policy/approval layer for sensitive actions
+8. multi-tenant controls, quotas, and billing
+
+## Why this design is the right starting point
+
+It gives us a working generalized browser API now, without prematurely locking ourselves into:
+
+- site-specific adapters
+- heavyweight orchestration frameworks
+- infra we do not yet need
+
+At the same time, it leaves clean upgrade paths for the pieces that actually become moats later: reliability, session management, recipes, verification, and replay.
+
+## References
+
+[^1]: API Everything homepage, accessed 2026-03-26, for the core product framing of “read + act through one API.”
+[^2]: Playwright documentation and common industry practice for browser automation runtimes.
+[^3]: OpenCode SDK docs, accessed 2026-03-26, for headless server access, session prompting, and structured JSON output.

package/docs/releasing.md

@@ -0,0 +1,62 @@
+# Releasing
+
+## Versioning
+
+This project uses tagged releases.
+
+Recommended release flow:
+
+1. update `CHANGELOG.md`
+2. bump `package.json`, `server.json`, and any versioned examples or metadata together
+3. run `npm run check`
+4. commit the release
+5. push the release commit to `main`
+6. create and push a tag like `v0.2.0`
+
+```bash
+git push origin main
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+The tag is the release trigger. Once the tag is pushed, GitHub Actions owns npm publication, MCP registry publication, and GitHub release creation. This flow assumes `NPM_TOKEN` is configured for tagged releases; if it is missing, the release workflow now fails loudly instead of pretending npm publish is optional.
+
+Versioned files checked by CI:
+
+- `package.json`
+- `server.json`
+
+`src/mcp.ts` reads the runtime version from `package.json`, so there is no extra hard-coded runtime version to bump.
+
+If you forget one of the versioned files, `npm run check:meta` should fail before release. `npm run check:dist` also proves the built MCP entrypoint starts and responds before a release ships.
+
+## What GitHub Actions does
+
+- `CI`: typecheck, tests, build, metadata checks, package dry-run
+- `Release`: verify, require npm publication on tags, publish to the MCP Registry after npm propagation, and then create the GitHub release
+
+## npm
+
+Package name:
+
+```text
+web-task-api
+```
+
+Published package page:
+
+```text
+https://www.npmjs.com/package/web-task-api
+```
+
+## MCP Registry
+
+Published registry name:
+
+```text
+io.github.rich-jojo/web-task-api
+```
+
+## References
+
+[^1]: `server.json` is the MCP registry source of truth for npm package mapping and runtime environment metadata.

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "web-task-api",
+  "mcpName": "io.github.rich-jojo/web-task-api",
+  "version": "0.2.1",
+  "packageManager": "npm@10.8.2",
+  "type": "module",
+  "description": "General browser-task API that lets agents read and act on websites through a single runtime.",
+  "homepage": "https://github.com/rich-jojo/web-task-api",
+  "bugs": {
+    "url": "https://github.com/rich-jojo/web-task-api/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rich-jojo/web-task-api.git"
+  },
+  "main": "./dist/src/lib.js",
+  "exports": {
+    ".": "./dist/src/lib.js",
+    "./mcp": "./dist/src/mcp-server.js"
+  },
+  "bin": {
+    "web-task-api": "dist/src/mcp.js",
+    "web-task-api-http": "dist/src/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/design.md",
+    "docs/releasing.md",
+    "server.json",
+    "recipes"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "dev:mcp": "tsx src/mcp.ts",
+    "start": "node dist/src/index.js",
+    "start:mcp": "node dist/src/mcp.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "check:meta": "node scripts/check-metadata.mjs",
+    "check:dist": "node scripts/check-dist-mcp.mjs",
+    "check": "npm run typecheck && npm run test && npm run build && npm run check:meta && npm run check:dist",
+    "playwright:install": "playwright install chromium",
+    "profile:login": "tsx scripts/profile-login.ts",
+    "demo": "tsx scripts/demo.ts",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "browser-automation",
+    "playwright",
+    "web-tasks",
+    "structured-output",
+    "claude-code",
+    "opencode"
+  ],
+  "author": "rich-jojo",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.18.1",
+    "@opencode-ai/sdk": "1.2.27",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "dotenv": "16.4.7",
+    "fastify": "5.2.1",
+    "playwright": "1.52.0",
+    "zod": "3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.0.0",
+    "tsx": "4.19.3",
+    "typescript": "5.8.3"
+  }
+}

package/recipes/dexscreener-token-read.json

@@ -0,0 +1,19 @@
+{
+  "id": "dexscreener-token-read",
+  "name": "Dexscreener token read",
+  "description": "Read token or pair details from Dexscreener pages. Best used with a warmed persistent browser profile if anti-bot checks appear.",
+  "urlPatterns": ["dexscreener.com"],
+  "browserHints": {
+    "preferChrome": true,
+    "preferHeadful": true,
+    "preferPersistentProfile": true
+  },
+  "promptHints": [
+    "This site may present bot checks to fresh sessions; if the page is blocked, fail clearly and recommend running with a persistent profile.",
+    "Look for token, pair, chain, price, liquidity, volume, FDV, market cap, and contract address in visible page text.",
+    "Prefer read_page once the asset panel is visible instead of many small clicks."
+  ],
+  "inputAliases": {
+    "query": ["symbol", "token", "pair", "contract"]
+  }
+}

package/recipes/fixture-catalog.json

@@ -0,0 +1,14 @@
+{
+  "id": "fixture-catalog",
+  "name": "Fixture catalog demo",
+  "description": "Optimized hints for the local demo catalog site.",
+  "urlPatterns": ["/", "/result"],
+  "promptHints": [
+    "The landing page has one query field and a Search button.",
+    "The result page contains Product, Price, and Stock lines in visible text.",
+    "When those lines appear, use them to finish the task."
+  ],
+  "inputAliases": {
+    "query": ["query"]
+  }
+}

package/recipes/generic-search.json

@@ -0,0 +1,14 @@
+{
+  "id": "generic-search",
+  "name": "Generic search flow",
+  "description": "Use when a page looks like a simple search or lookup form.",
+  "urlPatterns": [],
+  "promptHints": [
+    "If there is a single obvious search or query field, fill it from the input.",
+    "After filling the query, click the main submit/search button or press Enter.",
+    "Once result details are visible, read the page and finish with structured output."
+  ],
+  "inputAliases": {
+    "query": ["search", "term", "q", "keyword"]
+  }
+}