relay-stack-playbook

name	relay-stack-playbook
description	Use when working on this repository's relay stack: Codex app-server protocol translation, relayd, relay-wrapper, Feishu bot integration, VS Code remote integration, or real-stack debugging around /list, /attach, /use, thread routing, helper/internal traffic, and missing Feishu replies. Summarizes the correct execution order, validation steps, and common failure modes specific to this project.

relay-stack-playbook

Use this skill for changes or debugging involving:

• relayd
• relay-wrapper
• Feishu inbound/outbound behavior
• VS Code remote integration
• Codex app-server protocol translation
• /list, /attach, /use, /stop, thread routing, queue state, missing replies

Fast path

For tiny or state-light repo tasks that only touch orchestrator/projector/unit-test behavior, do not run real-stack diagnostics by default. Use only the layer split from this playbook, read the touched code, and run focused tests.

Escalate to the full checks below when the task depends on live relayd state, gateway delivery, wrapper/native protocol frames, daemon logs, localhost status, missing Feishu replies, or cross-layer behavior that unit tests cannot explain.

Core rules

• Start from runtime evidence, not the first plausible fix.
• Split the problem by layer before editing code:
  • wrapper: native protocol translation and explicit annotation
  • server/orchestrator: product state, queue, thread routing, render decisions
  • feishu gateway: inbound action parsing and outbound delivery
• The wrapper must annotate helper/internal traffic; it must not silently swallow real runtime lifecycle events.
• Helper lifecycle must be correlated by protocol ids such as request id -> result.thread.id and request id -> result.turn.id. Do not use "same thread" or timing heuristics.
• Product visibility decisions belong in the server layer, not in the wrapper.
• Do not trust mocks unless they match real frames captured from logs.

Full real-stack checks

When the task is a real-stack debug or has escalated beyond the fast path, gather these facts in order:

0. Prefer the repo helper script first.

   • Run ./scripts/relay/collect-diagnostics.sh.
   • It captures the fixed low-level evidence in one pass:
     • proxy env
     • service status
     • process and port checks
     • /api/admin/bootstrap-state
     • /v1/status
     • recent relayd logs

1. Check relay runtime state.

   • Read relayd status.
   • Verify actual processes and listening ports.

2. Query /v1/status from localhost without proxy interference.

   • Prefer the raw local socket command in references/commands.md.
   • Confirm:
     • instance is online
     • ObservedFocusedThreadID, ActiveThreadID, ActiveTurnID
     • surface count
     • attached instance id
     • selected thread id
     • dispatch mode
     • active and queued queue items

3. Read recent relayd logs.

   • Look for:
     • relay instance connected
     • relay instance disconnected
     • gateway apply failed
     • port bind failures

4. If VS Code shows the result but Feishu does not:

   • wrapper -> relay path is at least partially working
   • inspect relay surface state and gateway failures first

5. If /list or /attach seems to work but later text goes nowhere:

   • verify inbound menu events and text messages resolve to the same surfaceSessionID
   • check whether surfaces=0 or whether the current chat is attached to a different surface

Change strategy

• For protocol changes, update docs and implementation together.
• Add or update tests at the same time as the fix.
• Prefer fixing the whole failing chain in one pass:
  • translator unit tests
  • orchestrator state tests
  • wrapper integration tests
  • harness end-to-end tests
• Do not stop after a local unit test passes if the user-reported runtime symptom is still unexplained.

Common mistakes in this repo

• Reusing helper traffic templates as normal chat defaults.
• Hiding helper lifecycle in the wrapper instead of marking it and filtering later.
• Debugging only from mocks even when the real protocol already disagrees.
• Treating a proxy-intercepted curl response as a real localhost response.
• Restarting services during manual reproduction and then reasoning from stale Feishu/VS Code state.
• Changing only one layer in a multi-layer bug and assuming the visible behavior will follow.
• Trusting "started" output from service control without checking the actual process and ports.

Validation

• Clear proxy variables before local tests and localhost checks.
• Prefer ./scripts/relay/collect-diagnostics.sh for fixed evidence collection, then use the lower-level commands in references/commands.md when you need a narrower repro.
• After protocol or state-machine edits, run:
  • go test ./...
• When the bug is user-visible, verify the exact symptom path:
  • Feishu input
  • relay state change
  • wrapper/native activity
  • Feishu output or gateway failure

References

• For commands and symptom-driven checks, read references/commands.md.