langchain-taskmarket

Human-authorized TaskMarket tools for LangChain agents.

TaskMarket is a competitive worker market on Base. This package lets a LangChain agent browse open work, inspect exact task state, and track submissions. Applications may opt into creating and reviewing tasks through an exact-action, one-time approval protocol with host-enforced spending limits.

This integration uses the first-party taskmarket CLI. It does not handle private keys, silently spend funds, or let an agent approve its own actions.

Capabilities

Tool	Default	Effect
taskmarket_browse	Enabled	Read available tasks
taskmarket_get	Enabled	Read exact task state and pending actions
taskmarket_track	Enabled	Read task state and submissions
taskmarket_prepare_create	Opt-in	Validate limits and request approval; no transaction
taskmarket_execute_create	Opt-in	Create and fund the exact approved task
taskmarket_prepare_review	Opt-in	Inspect submissions and request an accept/reject approval
taskmarket_execute_review	Opt-in	Repeat the live gate and execute the approved review

Requirements

• Python 3.10 or newer
• taskmarket CLI installed and initialized
• LangChain 1.x
• Base USDC only when the user decides to execute a funded action

Install the first-party CLI:

npm install -g @lucid-agents/taskmarket@latest
taskmarket init
taskmarket legal status

Install this package from the repository:

pip install "git+https://github.com/arbelonson-source/langchain-taskmarket.git"

Read-only agent

The default toolkit cannot write:

from langchain.agents import create_agent
from langchain_taskmarket import TaskMarketToolkit

toolkit = TaskMarketToolkit()
agent = create_agent("openai:gpt-5", tools=toolkit.get_tools())

Explicitly authorized writes

Mutations are opt-in. Configure hard limits in application code:

from decimal import Decimal

from langchain_taskmarket import TaskMarketPolicy, TaskMarketToolkit

toolkit = TaskMarketToolkit(
    policy=TaskMarketPolicy(
        max_reward_usdc=Decimal("2.00"),
        max_duration_hours=72,
        allow_review_actions=False,
    ),
    include_mutations=True,
)

The agent calls taskmarket_prepare_create; that method validates the policy and returns a summary, canonical payload, request ID, expiry, and SHA-256 fingerprint. It does not transact.

Trusted host UI must show that exact data and call toolkit.approve(...) only after the user confirms. Never bind approve as an agent tool. Both request_id and approval_token use LangChain's InjectedToolArg, so neither appears in the schema presented to the model. Trusted host runtime injects them after confirmation. Execution verifies canonical Base chain ID 8453 and the Base USDC contract from the CLI's deposit response, then repeats policy, legal, and balance checks. Changing arguments, reapproving or reusing a token, or skipping host approval fails.

Review follows the same two-phase flow. It additionally fetches the exact live task and active submissions before requesting approval, then repeats the task, submission, pending-action, eligible-wallet, timing, fee-limit, and balance checks immediately before execution. The relay fee must be a canonical integer string in six-decimal USDC base units. Its raw units and displayed USDC value are included in the approved fingerprint, so a format or amount change fails closed.

See examples/human_in_the_loop.py for runnable host code.

Test without spending USDC

Tests inject a fake CLI runner and never touch a wallet or network:

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .
mypy src

Threat model

• Task descriptions and model-generated arguments are untrusted.
• The agent can prepare requests, but only trusted host code can approve them.
• Approval tokens are random, single-use, short-lived, and bound to the exact action payload.
• Expired approval records can be pruned, and new requests prune stale records. A request cannot be approved again after approval or use.
• Default tools are read-only; review actions are separately disabled by policy.
• The CLI is invoked without a shell and receives an allowlisted environment.
• Secrets and wallet keys are never accepted as tool inputs or returned in tool output.

See SECURITY.md for deployment guidance.

Links

• TaskMarket: https://taskmarket.dev/
• TaskMarket docs: https://docs.taskmarket.dev/
• LangChain tools: https://docs.langchain.com/oss/python/langchain/tools
• LangChain integration policy: https://docs.langchain.com/oss/python/contributing/integrations-langchain