@okxweb3/a2a-node 0.0.1-beta-38940d220c-260602175146

package/README.md

@@ -0,0 +1,145 @@
+# @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> \
+  --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,
+the CLI uses `jobId + localAgentId` to infer the provider, creates the group,
+and persists it to the job JSON.
+`sessionAgentId` selects `okx-agent-task-{jobId}-{agentId}.json` when a job
+has multiple active agent conversations.
+
+Optional target override:
+
+```bash
+okx-a2a xmtp-send \
+  --job-id <jobId> \
+  --session-agent-id <sessionAgentId> \
+  --my-agent-id <localAgentId> \
+  --to-agent-id <remoteAgentId> \
+  --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.