feat(taskmarket): add approval-gated requester toolkit

AP
2mo ago
+2776-5

PR Checklist

  • The commit message follows the conventional commit guidelines.
  • Tests and documentation have been added.
  • Changesets cover both affected packages.
  • No related issue is required for this new integration.

Current behavior

VoltAgent has no native Taskmarket requester workflow. Agents cannot safely
preview, authorize, create, or review a Taskmarket bounty through VoltAgent
tools.

New behavior

Adds @voltagent/taskmarket, an approval-gated requester toolkit with five
tools:

  • immutable five-minute task preview;
  • exactly one explicitly approved creation attempt;
  • requester-owned live task status;
  • bounded, sanitized submission metadata; and
  • bounded SHA-256-verified text/JSON artifact review.

Creation checks the CLI version, wallet, Base chain ID, canonical Base USDC,
balance, legal receipt or exact accepted bundle digest, and independent host
spend ceiling. It verifies live task economics and status after creation,
consumes previews once, and makes ambiguous writes non-retryable. No accept or
reject tool is exposed.

The MCP adapter now enforces static and dynamic needsApproval policies. The
elicitation form contains the complete immutable arguments plus exact byte
length and SHA-256, rejects payloads above the 24 KiB review ceiling, and
executes an isolated mutable copy of the reviewed data. The CLI runner uses no
shell, pins the production API, inherits a strict environment allowlist,
retains only the bounded output prefix, kills POSIX descendants on timeout,
omits incomplete UTF-8 sequences at the byte ceiling, and fails closed on
Windows unless a Job Object-backed runner is injected.

Validation

  • pnpm --filter @voltagent/taskmarket lint
  • pnpm --filter @voltagent/taskmarket typecheck
  • pnpm --filter @voltagent/taskmarket test:coverage — 40 passed; 92.00% statements/lines, 80.16% branches, 90.74% functions
  • pnpm --filter @voltagent/taskmarket demo:verify — 1 passed, 29 intentionally skipped
  • pnpm --filter @voltagent/taskmarket build
  • pnpm --filter @voltagent/mcp-server typecheck
  • pnpm --filter @voltagent/mcp-server test -- --run — 18 passed
  • pnpm --filter @voltagent/mcp-server build
  • pnpm sp lint
  • Publint — only the existing repository-URL style suggestion
  • CJS and ESM export smoke tests

Exact commit: 7d27bc4

Reviewer notes

Automated review findings drove concrete hardening: order-independent tag
reconciliation, the strict preview TTL, live-open verification, nullable
in-flight transaction handling, meaningful type tests, exact MCP approval
binding, oversized-input rejection, caller-mutation isolation, Windows
fail-closed behavior, descendant termination, and exact output-prefix
retention across UTF-8 boundaries.

This contribution is also being submitted to the public Taskmarket integration
bounty at
https://taskmarket.dev/tasks/0xfb182f610d57a6c056a8cfd1c9b691a0869c1e0d67c041ac27ed9f42a9c732a1.
Review, requested changes, and merge remain entirely at VoltAgent maintainer
discretion. No live Taskmarket task or payment was created while testing this
PR.

Summary by cubic

Adds @voltagent/taskmarket, an approval-gated Taskmarket requester toolkit, and hardens @voltagent/mcp-server so approval-gated tools execute only after MCP confirmation bound to immutable, hash-verified arguments. Previously a generic approval could allow execution; now the MCP elicitation must match a SHA‑256 of the exact tool arguments, and the runner enforces strict, UTF‑8‑safe output truncation.

  • Toolkit: immutable five-minute preview (taskmarket_preview_task), approval‑gated create (taskmarket_create_task), live status, submissions, and hash‑verified text/JSON artifact review; no accept/reject tool. Preview capacity errors derive their message from the configured cap.
  • Preflight and verification: requires CLI ≥ 1.11.0, Base chain ID 8453, canonical Base USDC, requester wallet match, sufficient balance, accepted legal terms (or exact acceptedLegalBundleDigest), and a host maximumSpendUsdc ceiling; reconciles live description, reward, mode, visibility, tags (order‑agnostic), and deadline within tolerance; mismatches yield status: "unknown", retryAllowed: false with optional idempotencyKey.
  • MCP approval binding: binds approval to a SHA‑256 of immutable arguments (24 KB display limit); executes only after explicit MCP elicitation; rejects if execution inputs differ; fails closed without an elicitation bridge; honors dynamic needsApproval policies, including for read‑only tools.
  • Runtime and packaging: pins the CLI to https://api.taskmarket.dev, runs without a shell, uses a minimal env allowlist, never forwards unrelated API keys or TASKMARKET_IDEMPOTENCY_KEY, bounds output/timeouts while preserving UTF‑8 boundaries, kills descendant processes on timeout, and treats reviewed artifacts as untrusted; adds the taskmarket workspace to CI; ships CJS/ESM with docs at website/docs/integrations/taskmarket.md.

Summary by CodeRabbit

  • New Features

    • Added Taskmarket tools for previews, approval-gated task creation, status checks, submission listing, and verified artifact review.
    • Added safeguards for spending limits, preview expiry, replay protection, validation, and untrusted content.
    • Added a command-line runner with timeout, output-size, environment controls, and process-tree termination.
    • MCP tools now enforce approval policies, reject oversized review arguments, and execute only approved argument snapshots.

  • Documentation

    • Added package and integration documentation covering setup, workflows, safety behavior, and examples.

  • Tests

    • Added comprehensive coverage for validation, approvals, failures, security checks, and toolkit behavior.