mirror of https://github.com/MoonshotAI/kimi-code.git synced 2026-08-04 14:02:22 +00:00

haozhe.yang 61ef35b302 feat(server-e2e): add typed v2 ServerClient SDK with drift test

- add ServerClient under src/v2: typed /api/v2 resource tree over HTTP
  plus events over WebSocket, with core/session/agent scopes and a v1
  escape hatch for the legacy REST surface
- add resource modules (core/session/agent/events), a manifest mirroring
  the server-v2 actionMap, shared types, and transport (HttpRpc,
  rpcProxy, V2Socket)
- expose @moonshot-ai/server-v2/contract (actionMap + channel helpers)
  so the SDK drift test stays in lockstep with the server surface
- add an in-process smoke test and the vitest raw-text/hash-imports
  plugins needed to import server-v2 source from the e2e tests
- add optional bearer token support to the legacy HttpClient and document
  the two-client package layout

2026-07-02 01:06:16 +08:00

3.4 KiB

Raw Permalink Blame History

server-e2e Agent Guide

This file contains package-local rules for packages/server-e2e.

Package layout

This package ships two clients:

Legacy /api/v1 client — DaemonClient (src/client.ts), HttpClient (src/http.ts), WsClient (src/ws.ts) and the helpers under src/ (wait.ts, reverse-rpc.ts, report.ts, envelope.ts). This is the original wire-level test client; the existing test/*.test.ts cases and scenarios/*.ts scripts are built on it and must keep running unchanged. Do not break or rewrite those tests when extending the package.
server-v2 SDK — ServerClient under src/v2/. A lark-style typed client for the server-v2 /api/v2 RPC + WS surface. src/v2/resources/manifest.ts mirrors server-v2/src/transport/actionMap.ts; test/v2/actionMap.test.ts is a drift test that fails when the server surface and the manifest diverge. The legacy REST surface is reachable via ServerClient#v1.

Testing Principle

Keep observability inside each server-e2e case. Do not add a separate "observable" test or scenario as a substitute for making the existing cases explain what they drove and what the server returned.
Every live server case should print structured, case-scoped details for the flow it exercises: key REST requests, response envelopes or unwrapped responses, WebSocket handshakes / acks / replay summaries, prompt terminal frames, and error envelopes.
Prefer a shared logging helper over ad hoc console.log formatting. Logs must be visible for passing Vitest cases, so write through stdout when Vitest would otherwise capture console output.
Keep logs factual and diagnostic. Print enough detail to debug the wire contract, but avoid unrelated narration.

Workflow

When adding or changing a server-e2e case, update that case's observability at the same time.
Do not add a new scenario solely to print data that an existing scenario or Vitest case should already expose.
Run the relevant server-e2e tests against KIMI_SERVER_URL=http://127.0.0.1:58627 when a server is available, and confirm the output includes the case-scoped diagnostic blocks.
Run Docker e2e with pnpm --filter @moonshot-ai/server-e2e docker:e2e; each run must derive its Docker runner name/namespace from the current workspace to avoid cross-workspace conflicts.

Command Reference

Start a local server from the repo root before validating live cases: pnpm dev:server.
Run only the undo helper/live e2e coverage: KIMI_SERVER_URL=http://127.0.0.1:58627 pnpm --filter @moonshot-ai/server-e2e test -- test/client.test.ts -t undoSession.
Run the full server client Vitest file: KIMI_SERVER_URL=http://127.0.0.1:58627 pnpm --filter @moonshot-ai/server-e2e test -- test/client.test.ts.
Run all server-e2e Vitest tests: KIMI_SERVER_URL=http://127.0.0.1:58627 pnpm --filter @moonshot-ai/server-e2e test.
Run all executable scenarios against the local server: KIMI_SERVER_URL=http://127.0.0.1:58627 pnpm --filter @moonshot-ai/server-e2e test:scenarios.
Run the server-v2 SDK drift test (no server needed): pnpm --filter @moonshot-ai/server-e2e exec vitest run test/v2/actionMap.test.ts.
Run the server-v2 SDK smoke test (boots server-v2 in-process): pnpm --filter @moonshot-ai/server-e2e exec vitest run test/v2/smoke.test.ts.
Run type checking for this package: pnpm --filter @moonshot-ai/server-e2e typecheck.

3.4 KiB Raw Permalink Blame History