From aff3b0a39b7e4308d1cb005603a7730dbc44ab3b Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Wed, 1 Apr 2026 01:56:30 +0000
Subject: [PATCH] add implementation task breakdown

---
 TASKS.md | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 TASKS.md

diff --git a/TASKS.md b/TASKS.md
new file mode 100644
index 0000000..cf67ce8
--- /dev/null
+++ b/TASKS.md
@@ -0,0 +1,183 @@
+# 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