feat: add standalone Rust CLI binary (awn) for agent-native AWN interface#158
Conversation
- packages/awn-cli: Cargo project (name=awn, version synced to 1.3.1) - crypto.rs: Ed25519 signing, agentId derivation, canonicalize, domain separators — all byte-for-byte compatible with TS agent-world-sdk - PROTOCOL_VERSION derived from Cargo.toml at compile time (major.minor) - 18 tests including 4 cross-language compatibility tests verified against TS output (same seed → same agentId, canonical JSON, signature, digest) - sync-version.mjs: now syncs Cargo.toml version alongside other files - AGENTS.md: document Cargo.toml as version-bearing file Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
- load_or_create_identity: load seed from JSON or generate new keypair - File format matches TS identity.json (seed + publicKey fields) - Can load TS-generated identity files and derive same agentId - 7 tests: create, reload, cross-name isolation, TS compat, nested dirs, corrupt file handling Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
…e persistence - PeerDb: JSON peer store at $data_dir/peers.json - upsert, remove, list (sorted by lastSeen), get, find_by_capability - TOFU trust model: first-use caching, TTL-based key refresh, mismatch rejection - camelCase JSON field names matching TS peers.json format - 14 tests: CRUD, persistence, TOFU logic, capability prefix/exact search, corrupt file recovery, TS format compatibility Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
- daemon.rs: axum HTTP server on localhost for IPC, with /ipc/status, /ipc/peers, /ipc/worlds, /ipc/ping endpoints - main.rs: clap CLI with subcommands: daemon start/stop, status, peers, worlds — all with --json dual output for agent consumption - daemon fetches worlds from gateway + merges with local peer DB cache - 5 daemon integration tests (start, ping, status, peers, identity reuse) - Binary name: awn (not awn-cli) Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
- Follows CLI-Anything SKILL.md format (name/description table, command groups, installation, JSON output docs, agent usage guide) - Documents daemon start, status, peers, worlds commands - Explains --json flag for machine-readable output Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
- test.yml: new test-rust job runs cargo test on PRs (with rust-cache) - release-cli.yml: triggered by GitHub Release publish, cross-compiles awn binary for linux-x64, darwin-x64, darwin-arm64, uploads tar.gz archives to the release - AGENTS.md: update CI workflows table Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Jing-yilin
left a comment
There was a problem hiding this comment.
Codex Review
[Medium] CLI commands cannot reach daemons started on a non-default IPC port
daemon start accepts --ipc-port, but status, peers, and worlds always resolve the daemon address from AWN_IPC_PORT or the hard-coded default 8199. If the daemon is started on any other port, the follow-up commands still call 127.0.0.1:8199 and report that the daemon is not running unless the caller also exports AWN_IPC_PORT out of band. I reproduced this with cargo run -- --json daemon start --ipc-port 8207 followed by cargo run -- --json status, which failed until AWN_IPC_PORT=8207 was set. That makes the advertised --ipc-port flag effectively unusable across normal CLI invocations.
Refs: packages/awn-cli/src/main.rs:52, packages/awn-cli/src/main.rs:74, packages/awn-cli/src/main.rs:119, packages/awn-cli/src/main.rs:148, packages/awn-cli/src/main.rs:190, packages/awn-cli/src/daemon.rs:222
[Medium] awn daemon stop reports an error but still exits 0
The stop subcommand currently prints daemon stop not yet implemented and then returns success. That is particularly risky here because the bundled skill explicitly tells agents to treat exit code 0 as success and non-zero as failure, so scripts will happily continue under the false assumption that the daemon has been stopped. Until the stop path is implemented, this branch should return a non-zero exit code.
Refs: packages/awn-cli/src/main.rs:110, packages/awn-cli/src/main.rs:112, packages/awn-cli/src/main.rs:113, packages/awn-cli/skills/SKILL.md:73
Validation: cd packages/awn-cli && cargo test
- Cargo.toml: add cargo-deb metadata for .deb package building - release-cli.yml: build .deb on Linux, auto-generate Homebrew formula on release, upload .deb + tar.gz archives to GitHub Releases - install.sh: universal installer (detects OS/arch, downloads binary) - SKILL.md: document all installation methods (brew, apt, curl, cargo) Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Fixes two issues from Codex review: 1. CLI commands now discover daemon IPC port via: --ipc-port flag > AWN_IPC_PORT env > ~/.awn/daemon.port file > default The daemon writes its bound port to daemon.port on start and removes it on shutdown, so 'awn status' works after 'awn daemon start --ipc-port N' without needing out-of-band env setup. 2. 'awn daemon stop' now exits with code 1 (was 0) since it is not yet implemented. Agents relying on exit codes will correctly detect failure. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
## Summary - rename peer-facing TypeScript modules and APIs to agent/world terminology - add dedicated world db/registry storage in the plugin, SDK, and gateway - update gateway world discovery, heartbeats, and tests for worldId-as-identity plus slug support ## Validation - npm run build - npm --prefix packages/agent-world-sdk run build - node --test test/*.test.mjs --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
- peer_db.rs → agent_db.rs (PeerRecord → AgentRecord, PeerDb → AgentDb) - peers.json → agents.json (store version bumped to 3) - CLI command: awn peers → awn agents - IPC endpoint: /ipc/peers → /ipc/agents - Status output: Known peers → Known agents, Peer port → Listen port - PeersResponse → AgentsResponse, PeersQuery → AgentsQuery - SKILL.md updated to match new terminology Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2833d12 to
b40b058
Compare
Summary
Adds a standalone Rust CLI binary (
awn) underpackages/awn-cli/that provides an agent-native interface to the Agent World Network. Following the CLI-Anything philosophy: CLI is the most universal entry point for AI agents.Why
--jsonflag for structured output makes it agent-nativeWhat's included
Modules (all with full test coverage)
identity.json./ipc/status,/ipc/peers,/ipc/worlds,/ipc/pingendpoints.CLI Commands
All commands support
--jsonfor structured output.Version sync
sync-version.mjsPROTOCOL_VERSIONderived from Cargo.toml at compile time (major.minor)SKILL.md
CLI-Anything format skill definition for agent discovery.
Test Results
Atomic Commits
feat: add Rust awn CLI skeleton with wire-compatible crypto modulefeat(awn): add identity module with TS-compatible key persistencefeat(awn): add peer DB with TOFU, capability search, and TS-compatible persistencefeat(awn): add daemon with IPC + clap CLI (status, peers, worlds)docs(awn): add CLI-Anything style SKILL.md for agent discoverychore: add changeset for Rust awn CLI