From 78da22654285e96579640ac883a2f680b69ae874 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 11:56:52 -0800 Subject: [PATCH] docs(plan): add 3-phase roadmap for remaining OpenClaw parity gaps --- ...26-02-16-openclaw-gap-next-steps-3phase.md | 182 ++++++++++++++++++ docs/plans/state.json | 7 + 2 files changed, 189 insertions(+) create mode 100644 docs/plans/2026-02-16-openclaw-gap-next-steps-3phase.md diff --git a/docs/plans/2026-02-16-openclaw-gap-next-steps-3phase.md b/docs/plans/2026-02-16-openclaw-gap-next-steps-3phase.md new file mode 100644 index 0000000..ce77140 --- /dev/null +++ b/docs/plans/2026-02-16-openclaw-gap-next-steps-3phase.md @@ -0,0 +1,182 @@ +# OpenClaw Gap Next Steps — 3-Phase Implementation Plan + +**Date:** 2026-02-16 +**Parent analysis:** `docs/plans/2026-02-06-openclaw-feature-gap-analysis.md` +**Related roadmap:** `docs/plans/2026-02-15-openclaw-gap-roadmap.md` + +## Goal + +Close the highest-impact remaining OpenClaw parity gaps that still affect day-to-day Flynn operator value, while keeping scope incremental and testable. + +## Prioritization Rationale + +1. Queue behavior parity improves real-world reliability under bursty chats. +2. Channel reach adds immediate user-facing utility with bounded engineering cost. +3. Protocol/app foundation unlocks companion-node and canvas-class features without committing to full mobile/mac app scope yet. + +## Phase 1 — Queue Policy Parity v2 (P1) + +### Scope + +- Extend current lane queue controls to include: + - `followup` mode semantics. + - `steer_backlog` semantics. + - lane debounce support. + - overflow summarize behavior. +- Add runtime control surface for queue policy per session. + +### File-Level Tasks + +- `src/gateway/lane-queue.ts` + - Add additional queue modes (`followup`, `steer_backlog`). + - Add debounce handling and summarize-on-overflow strategy. + - Add typed enqueue options for policy and enqueue metadata. +- `src/gateway/handlers/agent.ts` + - Resolve new queue mode values from config/session overrides. + - Add response payloads for summarized drops/interruption notices. +- `src/commands/builtin/index.ts` + - Add `/queue` command group for inspect/set/reset queue behavior in current session. +- `src/session/manager.ts` + - Persist per-session queue overrides (`queue.mode`, `queue.debounce_ms`, etc.). +- `src/config/schema.ts` + - Add new queue keys and validation (`debounce_ms`, summarize settings). +- `src/gateway/handlers/config.ts` + - Expose queue config fields in runtime config patch API (if applicable). +- `README.md` + - Document queue modes and `/queue` command usage. +- `docs/api/PROTOCOL.md` + - Update queue and cancellation behavior sections. + +### Test Checklist + +- `src/gateway/lane-queue.test.ts` + - [ ] `followup` behavior under active+pending workloads. + - [ ] `steer_backlog` replacement behavior across multiple pending entries. + - [ ] debounce behavior timing and ordering. + - [ ] summarize overflow behavior and payload integrity. +- `src/gateway/handlers/agent.test.ts` + - [ ] queue policy resolution for new modes and debounce. + - [ ] session override precedence over channel/global config. +- `src/commands/builtin/*.test.ts` + - [ ] `/queue` parse and execution behavior. +- `src/config/schema.test.ts` + - [ ] new queue schema defaults and validation errors. + +### Acceptance Criteria + +- Bursty same-session request streams behave deterministically with selected mode. +- Operators can inspect/change queue behavior per session without restart. +- Queue policy behavior is visible in docs and auditable. + +## Phase 2 — Channel Reach Expansion (Mattermost First) (P2) + +### Scope + +- Add first additional high-value missing channel using existing adapter architecture. +- Mattermost is first due to enterprise overlap with existing Slack/Teams patterns. +- Keep LINE/Feishu/Zalo as follow-on adapters after Mattermost stabilizes. + +### File-Level Tasks + +- `src/channels/mattermost/adapter.ts` + - Implement channel adapter with connect/disconnect/send/onMessage. + - Support allowlists and mention gating consistent with other adapters. +- `src/channels/mattermost/index.ts` + - Export adapter + types. +- `src/channels/index.ts` + - Register adapter export. +- `src/daemon/channels.ts` + - Wire config -> adapter construction and registry registration. +- `src/config/schema.ts` + - Add `mattermost` config block (token/webhook/team/channel constraints). +- `src/gateway/handlers/services.ts` + - Add services reporting entry for Mattermost. +- `README.md` + - Add setup section and config example. +- `docs/architecture/CONTRIBUTOR_MAP.md` + - Update channel map and ownership notes. + +### Test Checklist + +- `src/channels/mattermost/adapter.test.ts` + - [ ] inbound normalization and sender/session IDs. + - [ ] outbound send path. + - [ ] allowlist and mention gating. + - [ ] reconnect behavior and error handling. +- `src/config/schema.test.ts` + - [ ] mattermost schema defaults/validation. +- `src/daemon/channels.test.ts` + - [ ] adapter wiring and enable/disable lifecycle. +- `src/gateway/handlers/services.test.ts` + - [ ] channel presence/status reporting. + +### Acceptance Criteria + +- Mattermost operates end-to-end with same safety model as existing channels. +- Docs and diagnostics are sufficient for first-time setup. +- No regressions in existing channel startup/wiring tests. + +## Phase 3 — Companion Node + Capability Negotiation Foundation (P3) + +### Scope + +- Build protocol/runtime foundation for future companion apps and advanced surfaces. +- Do not build full macOS/iOS/Android nodes in this phase. +- Deliver capability discovery, version negotiation, and node role model. + +### File-Level Tasks + +- `src/gateway/protocol.ts` + - Add capability/version negotiation types (`protocol.version`, feature flags). + - Add `node.register`, `node.capabilities.get` RPC schema. +- `src/gateway/server.ts` + - Track node-role connections and scoped auth constraints. +- `src/gateway/router.ts` + - Route and validate node-specific RPC calls. +- `src/gateway/handlers/system.ts` + - Add capability introspection endpoint(s). +- `src/config/schema.ts` + - Add optional node policy config (`gateway.nodes.allowed_roles`, feature gates). +- `src/gateway/auth.ts` + - Add scoped auth checks for node-role methods. +- `docs/api/PROTOCOL.md` + - Document negotiation handshake and node method contracts. +- `README.md` + - Add node foundation section and constraints. + +### Test Checklist + +- `src/gateway/protocol.test.ts` + - [ ] validation for negotiation and node method payloads. +- `src/gateway/server.test.ts` + - [ ] node registration lifecycle. + - [ ] role-based method allow/deny behavior. +- `src/gateway/handlers/system.test.ts` + - [ ] capability introspection output correctness. +- `src/gateway/auth.test.ts` + - [ ] node-role scope enforcement. +- Integration tests: + - [ ] backward compatibility for non-node clients with old flow. + +### Acceptance Criteria + +- Gateway supports explicit capability/version negotiation. +- Node connections can be constrained by role and method scope. +- Existing WebChat/TUI clients remain fully compatible. + +## Cross-Phase Delivery Rules + +- Keep each phase behind config flags where behavior risk is non-trivial. +- Land in small atomic commits with docs and tests in the same commit. +- Update `docs/plans/state.json` after each phase completion. +- Run at least: + - `pnpm test:run` for touched suites. + - `pnpm typecheck`. + - `pnpm build` for protocol/runtime touching phases. + +## Suggested Execution Order + +1. Phase 1 (Queue parity v2). +2. Phase 2 (Mattermost adapter). +3. Phase 3 (Node/capability foundation). + diff --git a/docs/plans/state.json b/docs/plans/state.json index 146adff..e5add47 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -32,6 +32,13 @@ ], "test_status": "pnpm test:run src/gateway/lane-queue.test.ts src/gateway/handlers/agent.test.ts src/config/schema.test.ts + pnpm typecheck passing" }, + "openclaw-gap-next-steps-3phase": { + "status": "planned", + "date": "2026-02-16", + "updated": "2026-02-16", + "summary": "Defined a concrete 3-phase implementation plan for remaining high-impact OpenClaw parity work: queue policy parity v2, channel reach expansion (Mattermost first), and companion-node capability negotiation foundation.", + "file": "2026-02-16-openclaw-gap-next-steps-3phase.md" + }, "docs-gateway-auth-config-keys": { "status": "completed", "date": "2026-02-15",