diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..3eaa8bc --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,79 @@ +# HANDOFF + +## What this project is + +`reply-end-controls` is a Telegram-only interaction-control feature. + +Its purpose is to add reply-end buttons to assistant replies: + +- `A. 繼續` +- `B. 就這樣吧，不需要額外處理` + +The buttons are meant to: + +- capture user intent about whether a conversation should continue +- persist that choice +- influence later assistant behavior + +## What already works + +In `openclawtest`, the Telegram + OpenClaw PoC has already proven: + +- buttons can be attached to assistant replies +- button clicks can be received as callback queries +- callback state can be persisted +- button UI can update +- acknowledgement replies can be sent +- stop/continue can influence later behavior + +## What environment this currently targets + +- Telegram only +- OpenClaw runtime in `openclawtest` + +This is not yet a clean cross-agent installable package. It is a successful PoC being pushed toward a cleaner reusable path. + +## Where to start reading + +Read these files first: + +1. `README.md` +2. `telegram-v1-design.md` +3. `telegram-openclaw-poc-plan.md` +4. `reports/telegram-openclaw-poc-success.md` +5. `reports/openclaw-patch-inventory.md` +6. `reports/openclaw-patch-mapping-matrix.md` +7. `reports/next-phase-implementation-plan.md` +8. `reports/agent-consumable-minimum.md` + +## Repo structure + +- `src/core/` - reusable state/policy/callback logic +- `src/telegram/` - Telegram-specific helper logic +- `src/adapters/` - OpenClaw-facing state bridge code +- `src/runtime/` - runtime helper layer for current PoC behavior +- `scripts/` - apply / rollback and helper scripts +- `tests/` - current unit tests +- `reports/` - design notes, PoC success, pluginization reports + +## What is still fragile + +- the live OpenClaw integration still uses runtime patching +- the feature is not yet a clean installable plugin package +- acceptance still includes human verification steps on Telegram UI + +## If you are the next agent + +Your likely next step is not to rediscover the idea. + +Your likely next step is to make the current PoC easier to consume by: + +- reducing runtime patching +- tightening the apply/verify/rollback path +- making the adapter seam cleaner + +## Important constraint + +Do not mix this project with the governance project. + +They are separate workstreams. diff --git a/INTEGRATION.md b/INTEGRATION.md new file mode 100644 index 0000000..08b59fa --- /dev/null +++ b/INTEGRATION.md @@ -0,0 +1,65 @@ +# INTEGRATION + +## Current integration model + +The current working integration path is: + +1. patch OpenClaw Telegram runtime +2. restart the `openclawtest` gateway +3. send a real Telegram assistant reply +4. verify button rendering, callback handling, and state persistence + +## Runtime files currently involved + +See: + +- `reports/openclaw-patch-inventory.md` + +## Apply + +Current patch apply script: + +- `scripts/apply-openclaw-poc-patch.sh ` + +Example target dir in `openclawtest`: + +```bash +/home/openclawtest/.nvm/versions/node/v22.22.2/lib/node_modules/openclaw/dist +``` + +## Rollback + +Rollback script: + +- `scripts/rollback-openclaw-poc-patch.sh ` + +This expects backup files created by the apply script. + +## Verify + +At minimum, verify these behaviors in Telegram: + +1. assistant replies show both buttons +2. clicking `continue` updates UI and writes state +3. clicking `stop` updates UI and writes state +4. later turns are influenced by stop/continue state + +## Current persisted files in PoC mode + +- `~/.openclaw/reply-end-controls.json` +- `~/.openclaw/reply-end-debug.log` + +## Current adapter-related repo modules + +- `src/adapters/openclaw.ts` +- `src/adapters/openclaw-state-file.ts` +- `src/runtime/openclaw-telegram-bridge.ts` +- `src/runtime/openclaw-telegram-poc.ts` + +These do not yet replace the runtime patch end-to-end, but they are the current repo-side ownership points for the logic. + +## Known limitation + +The current integration path is reproducible, but not yet clean enough to call a final plugin package. + +That is the next direction of work. diff --git a/reports/agent-consumable-minimum.md b/reports/agent-consumable-minimum.md new file mode 100644 index 0000000..01b7eea --- /dev/null +++ b/reports/agent-consumable-minimum.md @@ -0,0 +1,102 @@ +# Agent-Consumable Minimum + +## Purpose + +Define the minimum bar for saying `reply-end-controls` is ready for another AI agent to use directly, rather than merely continue developing. + +## Current state + +The project is already: + +- understandable by another agent +- reproducible as a Telegram/OpenClaw PoC +- documented well enough for engineering handoff + +But it is not yet at the point where another agent can simply adopt it as a clean integration without understanding the current patch model. + +## Minimum bar for direct consumption + +Another AI agent should be able to: + +1. understand what the feature does +2. understand what environment it targets +3. apply it without hand-editing runtime files +4. verify it works +5. roll it back if needed + +## Required deliverables + +### 1. Clear integration entrypoint + +There must be a single obvious entrypoint explaining: + +- what to install +- what to patch +- what scripts to run +- what runtime assumptions exist + +### 2. Apply path + +Another agent must be able to apply the current PoC without inventing its own patch process. + +Current direction: + +- `scripts/apply-openclaw-poc-patch.sh` + +### 3. Verify path + +Another agent must be able to verify: + +- buttons appear +- callback is received +- state is written +- stop/continue affect later behavior + +Current direction: + +- acceptance instructions +- PoC reports + +### 4. Rollback path + +Another agent must be able to revert the patch safely. + +Current direction: + +- `scripts/rollback-openclaw-poc-patch.sh` + +### 5. Integration contract + +Another agent should not need to reverse-engineer the feature from raw runtime patches. + +It should have direct access to: + +- state model +- callback contract +- Telegram rendering rules +- OpenClaw adapter assumptions + +## Missing pieces before this bar is truly met + +The main gaps are: + +- no single `HANDOFF.md` or `INTEGRATION.md` entrypoint yet +- the current implementation still relies on runtime patching rather than a clean installable integration unit +- acceptance is still partly human-driven instead of fully scripted + +## Recommended next tasks + +1. add `HANDOFF.md` +2. add `INTEGRATION.md` +3. add a user-facing apply/verify/rollback flow description +4. tighten the acceptance steps into a smaller repeatable checklist + +## Completion rule + +We can say the project is ready for another agent to directly use when: + +- the repo contains a single handoff entrypoint +- patch application is reproducible +- patch rollback is reproducible +- verification steps are explicit and bounded +- the other agent does not need to inspect OpenClaw runtime internals before getting started