Agent Wormhole

Agent Wormhole opens a temporary encrypted passage for agent handoffs. The payload can be claimed once, then the channel collapses.

Before First Use

This skill executes the @builtbyecho/agent-wormhole npm package. Before running any agent-wormhole or npx @builtbyecho/agent-wormhole command for the first time in a session, tell the user:

About to install/run @builtbyecho/agent-wormhole (v0.1.2) from npm. It is an encrypted one-time-handoff CLI that writes payloads to a local .agent-wormholes/ directory and (for holder/paid opens) calls storage.builtbyecho.xyz and the Bankr x402 endpoint. It does NOT sign transactions or access private keys.

Proceed? (y/n)

Wait for explicit confirmation before the first invocation. Subsequent calls in the same session do not need to re-prompt.

Pin the version when invoking via npx:

npx -p @builtbyecho/agent-wormhole@0.1.2 agent-wormhole <args>

Quick Commands

From a project that has the package installed:

agent-wormhole send --text "mission brief" --ttl 10m
agent-wormhole send --file ./artifact.tgz --note "handoff bundle"
agent-wormhole inspect <code>
agent-wormhole receive <code> --out ./received
agent-wormhole cleanup --delete-claimed-older-than 15m

For one-off use without installing globally:

npx -p @builtbyecho/agent-wormhole@0.1.2 agent-wormhole send --text "mission brief"

Mental Model

Codes are id.secret.
id locates stored metadata.
secret derives the AES-256-GCM decrypt key and is not stored.
Default TTL is 10 minutes.
Max TTL is 24 hours unless explicitly configured lower.
Default max payload is 5 MB.
Receipts are written for opens and claims.

Access Paths

Local CLI/library opens record access.path = local.
Direct API holder opens require an EIP-191 signature from a wallet holding at least 50,000,000 ECHO on Base and record access.path = echo_holder.
Bankr x402 paid opens are handled by agent-wormhole-open and record access.path = x402_paid.
Claiming is free.

Live Endpoints

Direct holder/API route: https://storage.builtbyecho.xyz/agent-wormhole
Bankr x402 paid open: https://x402.bankr.bot/0x2a16625fad3b0d840ac02c7c59edea3781e340ae/agent-wormhole-open
Self-hosted local service default: http://127.0.0.1:8791

Verification

From the package root:

npm test
node --check src/cli.js
node --check src/index.js
node --check src/server.js
npm pack --json --dry-run

For live health:

curl -sS https://storage.builtbyecho.xyz/agent-wormhole/health

For Bankr status, check both registry and execution:

bankr --config "$BANKR_OWNER_CONFIG" x402 list
bankr x402 schema https://x402.bankr.bot/0x2a16625fad3b0d840ac02c7c59edea3781e340ae/agent-wormhole-open
bankr --config "$BANKR_PAYER_CONFIG" x402 call -X POST -d '{"payload":"dGVzdA=="}' --max-payment 0.01 -y --raw https://x402.bankr.bot/0x2a16625fad3b0d840ac02c7c59edea3781e340ae/agent-wormhole-open

Set BANKR_OWNER_CONFIG to the endpoint owner/operator config and BANKR_PAYER_CONFIG to a separate payer config. Do not treat registry active status alone as proof that paid x402 execution works. A real paid call from a non-owner wallet is the proof.

Safety

Do not paste wormhole codes into public channels unless the user explicitly wants the payload claimable by anyone there.
Do not log plaintext secrets or payloads.
Prefer short TTLs for secrets.
Use local cleanup commands for received artifacts when they are no longer needed.
Do not test Bankr paid endpoints with the same wallet that owns/deployed the endpoint.

agent-wormhole