git:20260711.db9d2ef to git:20260801.59706b8

- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

-

- This is the `apps/remote-server` workspace. See the root `CLAUDE.md` for monorepo-wide guidance. This file covers app-specific details.

-

- ## Commands

-

- ```bash

- # Development

- pnpm --filter @pulse-coder/remote-server dev # Watch mode via tsx

- pnpm --filter @pulse-coder/remote-server build # Compile to dist/index.cjs via tsup

-

- # From this directory

- npm run dev

- npm run build

- npm start # Run dist/index.cjs

-

- # PM2 (production)

- npm run pm2:start # Build + start

- npm run pm2:restart # Rebuild + restart

- npm run pm2:logs # Stream logs

- ```

-

- Helper test suites run via `pnpm --filter @pulse-coder/remote-server test` (Vitest; `pretest` builds `pulse-coder-plugin-kit` first). End-to-end behavior is still tested manually with `curl` against `/internal/agent/run`.

-

- ## Architecture

-

- ### Request lifecycle

-

- > ⚠ SECURITY: `verifyRequest()` is a real ED25519 check for **Discord** but

- > a no-op `return true` for **Feishu** (`src/adapters/feishu/adapter.ts:53-55`)

- > — the documented `FEISHU_ENCRYPT_KEY`/`FEISHU_VERIFICATION_TOKEN` are read

- > nowhere. On the default `HOST=0.0.0.0` + webhook mode this is an

- > unauthenticated ingress to a host-shell tool. This is a recorded, unfixed

- > vulnerability — see `harness/knowledge/security-posture.md §1`. The diagram

- > below shows the intended shape, NOT a guarantee that every adapter verifies.

-

- ```

- Platform webhook or /internal/agent/run

- → PlatformAdapter.verifyRequest() # Discord: ED25519 · Feishu: NO-OP (see security note above)

- → PlatformAdapter.parseIncoming() # → unified IncomingMessage

- → dispatcher.ackRequest() # Immediate 200/202 (required by Feishu/Telegram)

- → dispatchIncoming() [fire-and-forget]

- → processIncomingCommand() # Slash command handler

- → executeAgentTurn() # Engine.run() or ACP agent

- → StreamHandle callbacks → user

- ```

-

- ### Key modules

-

- | File | Role |

- |------|------|

- | `src/index.ts` | Bootstrap: stores → engine → Discord gateway → HTTP server |

- | `src/server.ts` | Hono app factory; mounts all route modules |

- | `src/core/dispatcher.ts` | Platform-agnostic webhook handler; concurrency guard via `active-run-store.ts` |

- | `src/core/agent-runner.ts` | Builds run context, invokes engine, persists session & memory logs |

- | `src/core/session-store.ts` | File-based session store at `~/.pulse-coder/remote-sessions/` |

- | `src/core/chat-commands.ts` | Slash command router (`/new`, `/clear`, `/model`, `/wt`, etc.) |

- | `src/core/clarification-queue.ts` | Async request/answer pairing for multi-turn clarification |

- | `src/core/model-config.ts` | Dynamic LLM model resolution with mtime-based caching |

- | `src/routes/internal.ts` | Loopback-only automation API (`/internal/agent/run`) |

-

- ### Platform adapters

-

- Each adapter implements four methods: `verifyRequest`, `parseIncoming`, `ackRequest`, `createStreamHandle`. Adapters live in `src/adapters/{feishu,discord,telegram,web}/`.

-

- - **Feishu**: Larksuite SDK, message dedup via LRU cache on `message_id`, card messages with progress state. **No request verification** — `verifyRequest` returns `true` (see the security note above and `harness/knowledge/security-posture.md §1`).

- - **Discord**: ED25519 signature verification, webhook interactions + Gateway WebSocket for DMs and guild @mentions.

- - **Telegram / Web**: implemented but not mounted in `server.ts` by default.

-

- ### Integrations

-

- Three plugin-kit integrations wrap engine execution via `runWithAgentContexts()`:

-

- - **Worktree** — git worktree binding state at `~/.pulse-coder/worktree-state/`

- - **Workspace** — project identity resolution at `~/.pulse-coder/workspace-state/`

- - **Memory** — semantic recall + daily logs via `pulse-coder-memory-plugin` at `~/.pulse-coder/remote-memory/`

-

- ### Custom tools (registered in `src/core/engine-singleton.ts`)

-

- `cron_job`, `deferred_demo`, `jina_ai_read`, `twitter_list_tweets`, `session_summary`, `ptc_demo_*`. Some use `defer_loading: true` (discovered only after tool search).

-

- ## Configuration

-

- Copy `.env.example` to `.env`. Minimum required variables:

-

- ```

- OPENAI_API_KEY / ANTHROPIC_API_KEY

- OPENAI_MODEL

- FEISHU_* or DISCORD_* # Whichever platform you're using

- INTERNAL_API_SECRET # Required in production

- ```

-

- Model overrides: `.pulse-coder/config.json` (cwd) or `$PULSE_CODER_MODEL_CONFIG`.

-

- ## Coding notes

- - Routes are Hono `Context` handlers — keep them thin; delegate to dispatcher or agent-runner.

- - Concurrency guard is per `platformKey`; do not bypass `active-run-store` for platform routes.

- - Internal routes (`/internal/*`) require loopback IP + Bearer token — enforce both checks when adding new internal endpoints.

- - `StreamHandle` callbacks are the only way to send output back to users; adapters own the send logic.