# 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