AGENT_TOOLFLOW

This project exposes deterministic CLI operations intended for LLM/agent orchestration. The agent conversation UX can vary; the backend/tool flow should remain explicit and stable.

Goal

• Be the execution layer ("pickaxes"), not the chat layer.

• Let any agent discover capabilities, validate intent, create orders, and monitor status.

Commands

• pnpm cli agent:capabilities

• pnpm cli agent:schemas

• pnpm cli agent:swap:plan

• pnpm cli agent:swap:quote

• pnpm cli agent:swap:create

• pnpm cli agent:swap:execute

• pnpm cli agent:swap:status

• pnpm cli agent:support:create

• pnpm agent:rpc (HTTP JSON-RPC server)

All agent commands return JSON with:

• ok

• operation

• state

• missingInputs

• validationErrors

• nextActions

• data

For correlation and stateless runs:

• --request-id <id> echoes into responses.

• --stateless disables local state read/write.

• --idempotency-key <key> is supported on agent:swap:create and agent:swap:execute.

JSON-RPC Transport

Start:

pnpm agent:rpc

Endpoints:

• GET /health

• POST /rpc

Auth:

• Optional token header: x-agent-rpc-token: <AGENT_RPC_TOKEN>

JSON-RPC methods:

• swapper.capabilities

• swapper.schemas

• swapper.swap.plan

• swapper.swap.quote

• swapper.swap.create

• swapper.swap.execute

• swapper.swap.status

• swapper.support.create

Example JSON-RPC call:

{
  "jsonrpc": "2.0",
  "id": "req-1001",
  "method": "swapper.swap.execute",
  "params": {
    "direction": "x2u",
    "chain": "arbitrum",
    "amount": "0.8",
    "to": "0x1111111111111111111111111111111111111111",
    "idempotency-key": "swap_user123_req1001"
  }
}

Canonical Swap Flow (XMR -> USDC or USDC -> XMR)

1

Discovery

Call agent:capabilities.

2

Intent normalization

Call agent:swap:plan with any known fields.

If state=needs_input or state=needs_destination, collect missing fields from user.

3

Price

Call agent:swap:quote.

4

Order creation

Call agent:swap:create.

• Read data.fundingInstructions and ask user to send exact funds.

• Use idempotency-key to make retries safe.

• If key is reused with different payload, state becomes idempotency_conflict.

• Optional shortcut: call agent:swap:execute to do quote+create in one step.

5

Status loop

Poll with agent:swap:status until terminal:

• completed

• terminal_failure

6

Failure fallback

If terminal failure, call agent:support:create.

Important Design Notes

• Agents do not need custody to operate: create order first, then request user funding using deposit instructions.

• Destination address is required before order creation.

• Session provenance is explicit in payloads (sessionSource).

• The tool only exposes execution primitives; agent dialogue policy is out of scope.

LLM Agent Spec (Scrape-Friendly)

Machine-readable spec file: docs/LLM_AGENT_SPEC.json

{
  "transport": "jsonrpc 2.0",
  "rpc_url": "http://127.0.0.1:8790/rpc",
  "health_url": "http://127.0.0.1:8790/health",
  "methods": [
    "swapper.capabilities",
    "swapper.schemas",
    "swapper.swap.plan",
    "swapper.swap.quote",
    "swapper.swap.create",
    "swapper.swap.execute",
    "swapper.swap.status",
    "swapper.support.create"
  ],
  "idempotency": {
    "fields": ["idempotency-key"],
    "applies_to": ["swapper.swap.create", "swapper.swap.execute"]
  }
}

Example User-Agent-US Workflow

1

User -> Agent

"Swap 0.8 XMR to USDC."

2

Agent -> Us (swapper.swap.plan)

params: { "direction":"x2u", "chain":"arbitrum", "amount":"0.8" }

3

Us -> Agent

state: needs_destination next action: ask destination address.

4

Agent -> User

"Where should I send the USDC on Arbitrum?"

5

User -> Agent

"Send to 0xabc...1234"

6

Agent -> Us (swapper.swap.execute)

params include:

• direction=x2u

• chain=arbitrum

• amount=0.8

• to=0xabc...1234

• idempotency-key=swap_user123_20260212_01

7

Us -> Agent

state: waiting_for_funding data:

• order.orderId

• fundingInstructions.depositAddress

• fundingInstructions.amountDisplay

• fundingInstructions.expiresAt

8

Agent -> User

"Please send exactly X XMR to address Y before expiry Z."

9

Agent -> Us (swapper.swap.status, loop)

Poll until completed or terminal_failure.

10

Us -> Agent

• completed -> final success payload.

• terminal_failure -> agent should call swapper.support.create.

11

Agent -> User

• Success: "Swap complete. USDC delivered."

• Failure: "Swap failed/expired/refunded. I opened support ticket ."