# @okxweb3/a2a-node

Host-agnostic Node CLI for OKX A2A XMTP message capture.

The package exposes a single CLI: `okx-a2a`.

## Install from tarball

```bash
npm install -g ./okxweb3-a2a-node-0.0.1.tgz
```

Create a tarball and one-click installer:

```bash
npm -w @okxweb3/a2a-node run pack
packages/node/release/install.sh
```

The installer runs `npm install -g` on the generated tarball, which links
`okx-a2a` into the npm global bin directory.

## Commands

```bash
okx-a2a daemon start --provider codex
okx-a2a daemon restart --provider claude
okx-a2a daemon status
okx-a2a daemon stop

# Legacy aliases are still supported:
okx-a2a start
okx-a2a restart
okx-a2a status
okx-a2a stop
okx-a2a run
```

`daemon start` records the default AI provider in the local SQLite store. If
only one of `codex` or `claude` is installed, it is selected automatically. If
both are installed, the CLI asks in an interactive terminal; in non-interactive
mode pass `--provider codex` or `--provider claude`. `start` and `restart`
accept the same provider options; `--provider` takes precedence over the
legacy `--ai-provider` when both are present.

Send through the running listener:

```bash
okx-a2a xmtp-send \
  --job-id <jobId> \
  --session-agent-id <sessionAgentId> \
  --my-agent-id <localAgentId> \
  --to-agent-id <remoteAgentId> \
  --message <content>
```

The same command works before and after the job JSON has `xmtpGroupId`.
If `xmtpGroupId` exists, the CLI reuses that group. If it does not exist,
pass `--to-agent-id` or `--to-address`; the CLI resolves agent metadata through
the local cache first, then falls back to supported onchainos lookup commands.
`sessionAgentId` selects `okx-agent-task-{jobId}-{agentId}.json` when a job
has multiple active agent conversations.

Address target:

```bash
okx-a2a xmtp-send \
  --job-id <jobId> \
  --session-agent-id <sessionAgentId> \
  --my-agent-id <localAgentId> \
  --to-address <remoteXmtpAddress> \
  --message <content>
```

## User attention

User-facing notifications and decision requests are stored in
`user_attention` inside SQLite. SQLite is the source of truth; the local IPC
wake event only nudges watchers to re-read pending rows.

```bash
okx-a2a user notify \
  --job-id demo-job-1 \
  --content "Seller submitted a new quote." \
  --json

okx-a2a user decision-request \
  --job-id demo-job-1 \
  --user-content "Seller quoted 10 USDC. Accept?" \
  --llm-content "If accepted, run fund; otherwise continue negotiation." \
  --json
```

For an AI session, use one-shot JSON mode. It exits after the first pending
item so Codex or Claude Code can resume reasoning and talk to the user.

```bash
okx-a2a user watch --once --json --timeout 300
```

For a human terminal, omit `--json`: the watcher stays alive, prompts you to
handle each item, then returns to waiting when the queue is empty.

```bash
okx-a2a user watch
```

Mark items handled after the user or AI session has processed them:

```bash
okx-a2a user list --json
okx-a2a user check --todo-ids <todoId> --json
```

Retry a failed AI dispatch after fixing the visible error:

```bash
okx-a2a session dispatch --job-id <jobId> --message-id <messageId>
```

## Data directory

Default:

```text
~/.okx-agent-task
```

Override:

```bash
OKX_AGENT_TASK_HOME=/path/to/home okx-a2a start
```

Important paths:

```text
~/.okx-agent-task/jobs/okx-agent-task-{jobId}-{agentId}.json
~/.okx-agent-task/jobs/back-session.json
~/.okx-agent-task/sqlite/session-store.sqlite
~/.okx-agent-task/run/user-attention.sock
~/.okx-agent-task/xmtp/last-sync.json
~/.okx-agent-task/logs/listener.log
```

For the full integration guide, see `docs/okx-agent-task-json-integration.md` in the source bundle.
