Yonexus.Server/TASKS.md

Yonexus.Server — Implementation Tasks

This document breaks the server-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 server config defaults
• Add config validation for:
  • followerIdentifiers
  • notifyBotToken
  • adminUserId
  • listenHost
  • listenPort
  • publicWsUrl
• 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 server-side types:
  • client record
  • active session
  • pairing state
  • heartbeat status

Phase 3 — WebSocket Service Layer

• Implement servers/wsServer.ts
• Bind WebSocket server to configured host/port
• Handle connection open/close lifecycle
• Parse inbound text frames
• Route raw inbound frames toward protocol/application dispatch
• Implement servers/sessionManager.ts
• Enforce one active session per identifier
• Replace old session on new authenticated connection

Phase 4 — Registry and Persistence

• Implement plugin/core/registry.ts
• Add in-memory registry for active and known clients
• Add persistence model for durable trust state
• Implement load-on-start behavior
• Implement save-on-change behavior
• Decide initial persistence format (likely JSON)
• Ensure sensitive fields are not logged in plaintext

Phase 5 — Builtin Protocol Routing

• Implement builtin message parser
• Implement builtin envelope validation
• Route by builtin type
• Support at minimum:
  • hello
  • pair_confirm
  • auth_request
  • heartbeat
• Return structured error responses for malformed payloads

Phase 6 — Pairing Flow

• Implement pairing code generation
• Implement pairing TTL / expiry
• Store pending pairing state in registry
• Implement Discord DM notification path using notifyBotToken
• Include identifier and pairing code in DM
• Return pair_request to client without leaking pairing code
• Validate pair_confirm
• Implement pair_success
• Implement pair_failed
• Handle admin_notification_failed

Phase 7 — Authentication Flow

• Implement proof verification logic in plugin/core/auth.ts
• Verify signature against stored public key
• Verify stored secret
• Verify timestamp freshness
• Implement nonce replay protection
• Implement handshake rate limiting
• Trigger re_pair_required on unsafe conditions
• Send auth_success on success
• Send auth_failed on failure

Phase 8 — Heartbeat and Status

• Implement plugin/core/heartbeat.ts
• Update lastHeartbeatAt on valid heartbeat
• Start periodic sweep timer
• Mark clients unstable after 7 minutes
• Mark clients offline after 11 minutes
• Send disconnect_notice before forced close
• Close socket on offline transition
• Optionally send heartbeat_ack

Phase 9 — Rule Dispatch and Messaging APIs

• Implement plugin/core/dispatch.ts
• Implement application message parse path
• Rewrite inbound client messages to include sender identifier
• Maintain rule registry
• Reject reserved rule builtin
• Reject duplicate rule registrations
• Implement sendMessageToClient(identifier, message)
• Fail cleanly when target client is offline

Phase 10 — Hooks

• Implement plugin/hooks/onGatewayStart.ts
• Implement plugin/hooks/onGatewayStop.ts
• Ensure startup initializes runtime exactly once
• Ensure shutdown cleans up sockets/timers

Phase 11 — Commands and Tools

Commands

• listClients
• showClient
• rePairClient

Tools

• sendMessageToClient
• listClientStatus
• getPairingState

Phase 12 — 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 13 — Testing

• Unit tests for config validation
• Unit tests for builtin parsing
• Unit tests for pairing logic
• Unit tests for auth verification
• Unit tests for nonce/rate-limit protection
• Integration test: first-time pairing
• Integration test: reconnect auth
• Integration test: heartbeat timeout
• Integration test: offline disconnect

Phase 14 — Hardening

• Redact secrets from logs
• Audit error messages for sensitive leakage
• Confirm persistence behavior across restart
• Review unsafe-condition handling
• Review operator-facing command/tool ergonomics

Nice-to-Have / Later

• TLS listener support
• Better operator diagnostics
• Queued outbound delivery strategy
• Admin approve/deny workflow beyond code relay