Yonexus.Client/TASKS.md

Yonexus.Client — Implementation Tasks

This document breaks the client-side work into actionable tasks.

Phase 0 — Repository Skeleton

• Create required directories:
  • plugin/
  • plugin/core/
  • plugin/hooks/
  • plugin/commands/
  • plugin/tools/
  • skills/
  • servers/
  • scripts/
• Create required files:
  • plugin/index.ts
  • plugin/openclaw.plugin.json
  • scripts/install.mjs
• Keep protocol/ submodule intact and documented

Phase 1 — Manifest and Entry Wiring

• Write initial plugin/openclaw.plugin.json
• Define client config defaults
• Add config validation for:
  • mainHost
  • identifier
  • notifyBotToken
  • adminUserId
• Implement plugin/index.ts as wiring-only entrypoint
• Register hooks / commands / tools from plugin/index.ts

Phase 2 — Core Runtime Foundation

• Implement structured error definitions in plugin/core/errors.ts
• Implement config loader / validator
• Implement runtime container/bootstrap module
• Define shared client-side types:
  • local state
  • connection state
  • pairing state
  • auth state

Phase 3 — Local Identity and Persistence

• Implement plugin/core/localState.ts
• Define local persisted state format
• Implement load-on-start behavior
• Implement save-on-change behavior
• Decide initial persistence format (likely JSON)
• Implement plugin/core/keys.ts
• Generate Ed25519 keypair on first run
• Persist private/public key locally
• Ensure private key is never logged or transmitted incorrectly

Phase 4 — Client Runtime Service

• Implement servers/clientRuntime.ts
• Open WebSocket connection to mainHost
• Handle socket open/close lifecycle
• Parse inbound text frames
• Broker inbound frames to builtin/application dispatch
• Implement reconnect with backoff

Phase 5 — Builtin Protocol Routing

• Implement builtin message parser
• Implement builtin envelope validation
• Route by builtin type
• Support at minimum:
  • hello_ack
  • pair_request
  • pair_success
  • pair_failed
  • auth_success
  • auth_failed
  • re_pair_required
  • heartbeat_ack
• Return or log structured errors for malformed payloads

Phase 6 — Connection Bootstrap

• Send initial hello after socket open
• Populate hasSecret
• Populate hasKeyPair
• Populate publicKey
• Populate protocol version
• Handle server hello_ack

Phase 7 — Pairing Flow

• Implement plugin/core/pairing.ts
• Enter pairing state when server requires pairing
• Surface pairing metadata to operator/runtime
• Accept human-provided pairing code
• Send pair_confirm
• Handle pair_success
• Persist secret after successful pairing
• Handle pair_failed
• Retry pairing when appropriate

Phase 8 — Authentication Flow

• Implement plugin/core/auth.ts
• Build canonical proof payload from secret + nonce + timestamp
• Sign proof payload with local private key
• Send auth_request
• Handle auth_success
• Handle auth_failed
• Handle re_pair_required
• Clear local trust when forced to re-pair

Phase 9 — Heartbeat

• Implement plugin/core/heartbeat.ts
• Start heartbeat loop after auth success
• Send heartbeat every 5 minutes
• Stop heartbeat on disconnect
• Handle optional heartbeat_ack

Phase 10 — Rule Dispatch and Messaging APIs

• Implement plugin/core/dispatch.ts
• Implement application message parse path
• Maintain rule registry
• Reject reserved rule builtin
• Reject duplicate rule registrations
• Implement sendMessageToServer(message)
• Fail cleanly when not authenticated

Phase 11 — Hooks

• Implement plugin/hooks/onGatewayStart.ts
• Implement plugin/hooks/onGatewayStop.ts
• Ensure startup initializes client runtime exactly once
• Ensure shutdown stops heartbeat and closes socket

Phase 12 — Commands and Tools

Commands

• showStatus
• reconnect
• resetTrust

Tools

• sendMessageToServer
• getConnectionState

Phase 13 — Install Script

• Implement scripts/install.mjs
• Support --install
• Support --uninstall
• Support --openclaw-profile-path <path>
• Validate build output exists before install
• Copy runtime-ready files into plugin directory

Phase 14 — Testing

• Unit tests for config validation
• Unit tests for local state load/save
• Unit tests for key generation/signing
• Unit tests for builtin parsing
• Integration test: first-time pairing
• Integration test: reconnect auth
• Integration test: heartbeat loop start/stop
• Integration test: forced re-pair

Phase 15 — Hardening

• Redact secrets/private keys from logs
• Audit error messages for sensitive leakage
• Confirm reconnect behavior is stable
• Review backoff strategy
• Review operator-facing command/tool ergonomics

Nice-to-Have / Later

• Better local diagnostics
• Operator-friendly pairing UX helpers
• Optional local debug trace mode
• More advanced retry policies