refactor(kap-server): drop the @moonshot-ai/protocol dependency (#1755)

Author: kermanx

.agents/skills/agent-core-dev/errors.md

@@ -7,7 +7,7 @@ Base classes and serialization are **centralized** in `_base/errors`; error **co
 ## Where things live
 
 - `src/_base/errors/errors.ts`: base classes — `Error2`, `ExpectedError`, `ErrorNoTelemetry`, `BugIndicatingError`, `NotImplementedError`, plus `isError2` and `unwrapErrorCause`.
-- `src/_base/errors/codes.ts`: the `ErrorDomain` contract, the `ErrorCode` type (aliased to the protocol's `KimiErrorCode`), the registry (`registerErrorDomain` / `errorInfo` / `isErrorCode`), and `CoreErrors` (`internal`, `not_implemented`).
+- `src/_base/errors/codes.ts`: the `ErrorDomain` contract, the registry (`registerErrorDomain` / `errorInfo` / `isErrorCode`), and `CoreErrors` (`internal`, `not_implemented`). The `ErrorCode` union type is derived by `#/errors` from the aggregated domain definitions.
 - `src/_base/errors/serialize.ts`: `ErrorPayload`, `isCodedError`, `toErrorPayload`, `fromErrorPayload`. Wire-facing names (`KimiErrorPayload`, `toKimiErrorPayload`) mirror the protocol and are kept as-is.
 - `src/_base/errors/unexpectedError.ts`: `onUnexpectedError` / `setUnexpectedErrorHandler` (global handler).
 - `src/<domain>/errors.ts`: the domain's `XxxErrors` descriptor (codes + retryable list + per-code info overrides), self-registered on import.
@@ -17,7 +17,7 @@ Base classes and serialization are **centralized** in `_base/errors`; error **co
 
 - **Throw a coded error, not a bare string.** `throw new Error2(ErrorCodes.X, …)`. Bare `new Error` only for unreachable guards; `BugIndicatingError` for caller bugs; `NotImplementedError('feature')` for stubs.
 - **Define codes in the owning domain**, in `<domain>/errors.ts` as an `XxxErrors` descriptor (`satisfies ErrorDomain` + `registerErrorDomain`), then wire it into the facade. Never add domain codes to `_base/errors`.
-- **One `code` per failure mode.** Codes read `domain.reason`. The valid code strings are fixed by the protocol (`KimiErrorCode` in `packages/protocol/src/events.ts`): **add new codes to the protocol first**. Renaming/removing a code is a major.
+- **One `code` per failure mode.** Codes read `domain.reason`. The valid code strings are derived from the aggregated domain definitions (`ErrorCode` in `#/errors` is computed from the `ErrorCodes` aggregate): **add new codes to the owning domain's `errors.ts`** — registration throws on cross-domain collisions. Renaming/removing a code is a major.
 - **Translate foreign errors at the boundary.** Provider/HTTP, fs, MCP errors are re-thrown as the owning domain's coded error. `_base/errors` never imports a business domain.
 - **Translation is idempotent and cause-preserving.** Translators (`toHostFsError`, `toStorageIoError`) pass through an already-translated error and always keep the original as `cause`.
 - **`details` is structured and JSON-serializable; `message` is a short human sentence.** Paths/errnos/scope/key go into `details`, not the message.
@@ -35,6 +35,6 @@ Base classes and serialization are **centralized** in `_base/errors`; error **co
 ## Red lines (this topic)
 
 - Throw a coded error with a `code`, not a bare string (except unreachable guards / `BugIndicatingError` / `NotImplementedError`).
-- Codes live in the owning domain's `errors.ts` and self-register; new codes land in the protocol first.
+- Codes live in the owning domain's `errors.ts` and self-register; new codes land in the owning domain first.
 - Translate foreign errors at the owning domain's boundary, idempotently, with `cause` and structured `details`; `_base/errors` never imports a business domain.
 - Branch on `code` across the wire, never `instanceof`.

.agents/skills/agent-core-dev/server-align.md

@@ -38,28 +38,28 @@ Pick surface → Read the v1 route (if any) → Reuse / add the protocol schema
 
 Apply the decision above. For a v1-matched endpoint, the **spec** is the protocol schema plus the existing mirror routes:
 
-- `packages/protocol/src/rest/<resource>.ts` — the wire schema you must match.
+- `packages/kap-server/src/protocol/rest-<resource>.ts` — the wire schema you must match.
 - `packages/kap-server/src/routes/<resource>.ts` — the file you are writing (create it if missing); sibling route files show the conventions.
 
 The protocol schema is the source of truth. Do not re-derive the wire shape from memory or from the v2 domain model.
 
 ### 2. Reuse (or add) the protocol schema
 
-The wire schema lives in **`@moonshot-ai/protocol`** under `packages/protocol/src/rest/<resource>.ts` (e.g. `promptSubmissionSchema`, `promptListResponseSchema`, `configResponseSchema`). Every `/api/v1` route in `packages/kap-server` imports from it — that single import is what guarantees the server speaks the same shape released clients expect.
+The wire schema lives in **`packages/kap-server/src/protocol`** under `rest-<resource>.ts` (e.g. `promptSubmissionSchema`, `promptListResponseSchema`, `configResponseSchema`) — or in the owning `agent-core-v2` domain contract when the engine's service speaks the shape. Every `/api/v1` route in `packages/kap-server` imports from it — that single import is what guarantees the server speaks the same shape released clients expect.
 
 Actions:
 
 - **Schema already in protocol** → import it in the server-v2 route and use it in `defineRoute` (`body`, `success.data`, error `dataSchema` / `detailsSchema`). Do **not** re-declare the schema inline in server-v2.
-- **Schema missing in protocol** → add it to `packages/protocol/src/rest/<resource>.ts` first, with a `rest-<resource>.test.ts`, then consume it from the route. The protocol package is the source of truth; server-v2 never owns a v1 wire schema locally.
-- **Schema exists but only v1 uses it** → move/keep it in protocol and import it into server-v2; do not fork a copy.
+- **Schema missing** → add it to `packages/kap-server/src/protocol/rest-<resource>.ts` first (or to the owning v2 domain contract if its service speaks the shape), then consume it from the route. The shared schema is the source of truth; server-v2 never re-declares a v1 wire schema inline.
+- **Schema exists but only v1 uses it** → keep it in `packages/kap-server/src/protocol` and import it into server-v2; do not fork a copy.
 
 #### Schema-fidelity rule (the hard rule)
 
 For a `/api/v1` endpoint, the request and response schemas **must be the established protocol schema** (or a strict superset):
 
 - ✅ **Adding** an optional field is allowed (`field: z.string().optional()`). Old clients ignore it; new clients may send it.
 - ❌ **Renaming** a field, **changing** its type, **tightening** its validation, or **changing its meaning** is a wire break — do not do it in a mirror route. If the v2 domain genuinely needs a different shape, that shape belongs on `/api/v2`, not on the `/api/v1` mirror.
-- ❌ Re-declaring the schema inline in server-v2 (even if it "looks identical") is forbidden — it drifts. One schema, one home: `packages/protocol`.
+- ❌ Re-declaring the schema inline in server-v2 (even if it "looks identical") is forbidden — it drifts. One schema, one home: the owning `agent-core-v2` domain contract or `packages/kap-server/src/protocol`.
 
 Self-check: "would a released v1 client get a byte-identical envelope from `packages/kap-server` for this request?" If you cannot answer yes from the shared schema, the route is wrong.
 
@@ -94,8 +94,8 @@ packages/agent-core-v2/src/<domain>Legacy/
 Skeleton (matches `prompt/`):
 
 ```ts
-// prompt.ts — contract shaped by @moonshot-ai/protocol
-import type { PromptSubmitResult, PromptSubmission } from '@moonshot-ai/protocol';
+// prompt.ts — contract shaped by the v1 wire schema (kap-server/src/protocol)
+import type { PromptSubmitResult, PromptSubmission } from '../../protocol/rest-prompt';
 import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
 
 export interface IAgentPromptService {
@@ -128,7 +128,7 @@ Conventions:
 - **Header comment** must say it is an `L7 edge adapter` and name both the v1 contract it implements and the native v2 Service it leaves untouched (see `prompt.ts`).
 - **Scope** = the lifetime of the *legacy* state it holds (the `prompt` queue is per-agent → `LifecycleScope.Agent`). Apply [orient.md](orient.md) / [design.md](design.md) normally — a LegacyService is not exempt from scope rules.
 - **Delegate, do not duplicate** business logic. The LegacyService translates the v1 contract into native-Service calls and translates results back; the real work stays in the native Service.
-- **Contract types come from `@moonshot-ai/protocol`**, so the interface cannot drift from the wire shape.
+- **Contract types come from the v1 wire schema homes** (the owning v2 domain contract or `kap-server/src/protocol`), so the interface cannot drift from the wire shape.
 
 ### 4. Wire the route / actionMap entry
 
@@ -139,9 +139,9 @@ const route = defineRoute(
   {
     method: 'POST',
     path: '/sessions/{session_id}/prompts',
-    body: promptSubmissionSchema,                 // ← from @moonshot-ai/protocol
+    body: promptSubmissionSchema,                 // ← from kap-server/src/protocol
     params: sessionIdParamSchema,
-    success: { data: promptSubmitResultSchema },  // ← from @moonshot-ai/protocol
+    success: { data: promptSubmitResultSchema },  // ← from kap-server/src/protocol
     errors: {
       [ErrorCode.SESSION_NOT_FOUND]: {},
       [ErrorCode.SESSION_BUSY]: {},
@@ -169,7 +169,7 @@ app.post(route.path, route.options, route.handler);
 The route translates domain `KimiError` codes into protocol `ErrorCode` numbers. Two registries must stay in sync:
 
 - **Domain code** — register in `agent-core-v2/src/errors.ts` (`ErrorCodes`) and throw from the Service (errors.md). Co-located domain errors go in `<domain>Legacy/errors.ts` (e.g. `prompt.not_found`, `session.busy`).
-- **Wire code** — register the matching number in `packages/protocol/src/error-codes.ts` and reference it in the route's `errors` map and `sendMappedError`.
+- **Wire code** — register the matching number in `packages/kap-server/src/protocol/error-codes.ts` and reference it in the route's `errors` map and `sendMappedError`.
 
 ```ts
 function sendMappedError(reply, requestId, err) {
@@ -202,7 +202,7 @@ Where the route mirrors v1, the test is the regression guard for the schema-fide
 ### 7. Verify
 
 - `pnpm -C packages/kap-server test` — server routes green.
-- `pnpm -C packages/protocol test` — schema tests green (incl. any new `rest-*.test.ts`).
+- `pnpm -C packages/kap-server test` — server routes green (incl. any wire-schema guards).
 - `pnpm -C packages/agent-core-v2 test` — native + Legacy Service tests green.
 - `pnpm -C packages/agent-core-v2 run lint:domain` — a LegacyService is still inside the domain layers (edge adapter, L7); it must not pull business code into the edge or invert scope direction.
 - `pnpm -C packages/server-e2e ...` when a v1 parity scenario exists.
@@ -218,9 +218,9 @@ This is the reference alignment (commits `feat(server-v2): port v1 /sessions/:si
 - `/api/v2` keeps the native shape — `prompts:submit` / `steer` / `undo` / `clear` / `cancel` map to `IAgentRPCService` (a wire facade over the v2 turn driver) in `actionMap`. The native `IAgentPromptService` is untouched.
 - `/api/v1` gets an `AgentPromptLegacyService` (`prompt/`, `LifecycleScope.Agent`) that re-implements the v1 scheduler — queue, `prompt_id`, steer/abort, auto-start-next — **on top of** the native `IAgentPromptService`. The `/api/v1` routes consume the LegacyService.
 
-**The schema.** Both surfaces import `promptSubmissionSchema` / `promptSubmitResultSchema` / `promptListResponseSchema` / `promptSteerRequestSchema` / `promptSteerResultSchema` / `promptAbortResponseSchema` from `@moonshot-ai/protocol`. The `/api/v1` and `/api/v2` routes are therefore compatible with released clients by construction; the LegacyService projects v2 turn results back into those protocol shapes.
+**The schema.** Both surfaces import `promptSubmissionSchema` / `promptSubmitResultSchema` / `promptListResponseSchema` / `promptSteerRequestSchema` / `promptSteerResultSchema` / `promptAbortResponseSchema` from the shared v1 wire schemas (see `packages/kap-server/src/protocol`). The `/api/v1` and `/api/v2` routes are therefore compatible with released clients by construction; the LegacyService projects v2 turn results back into those protocol shapes.
 
-**The errors.** v1 codes (`prompt.not_found`, `session.busy`, `prompt.already_completed`) are registered in `agent-core-v2` (`prompt/errors.ts`) and in `packages/protocol` (`error-codes.ts`), then mapped in the route's `sendMappedError` — including the idempotent `prompt.already_completed` → `40903 { data: { aborted: false } }`.
+**The errors.** v1 codes (`prompt.not_found`, `session.busy`, `prompt.already_completed`) are registered in `agent-core-v2` (`prompt/errors.ts`) and in `packages/kap-server/src/protocol` (`error-codes.ts`), then mapped in the route's `sendMappedError` — including the idempotent `prompt.already_completed` → `40903 { data: { aborted: false } }`.
 
 **The lesson.** When the v1 contract and the v2 domain disagree, add an adapter (LegacyService) at the edge; do not let the wire contract leak into the native domain. The two surfaces share the protocol schema but not the Service.
 
@@ -230,21 +230,21 @@ Before submitting a server-align change:
 
 - [ ] Surface chosen deliberately: `/api/v1` mirror for a v1-matched endpoint, `/api/v2` for a new native capability (both if needed).
 - [ ] For a `/api/v1` mirror, the route matches the established v1 contract (protocol schema + sibling routes) path-for-path, verb-for-verb, action-for-action.
-- [ ] Request and response schemas come from `@moonshot-ai/protocol` (`packages/protocol/src/rest/<resource>.ts`); no inline re-declaration in server-v2.
+- [ ] Request and response schemas come from their owning home (the `agent-core-v2` domain contract or `packages/kap-server/src/protocol`); no inline re-declaration in server-v2.
 - [ ] Existing schema fields are unchanged in name, type, and semantics; only optional fields added (if any).
 - [ ] Native v2 Service left clean; v1-only behavior isolated in a `<domain>Legacy` / `I<Domain>LegacyService` edge adapter when the semantics diverge.
 - [ ] LegacyService registered with the correct `LifecycleScope` and a header comment naming it an L7 edge adapter + the native Service it preserves.
-- [ ] Domain error codes registered in `agent-core-v2`; wire codes registered in `packages/protocol`; route maps them in `sendMappedError`, matching v1's status codes and idempotent envelopes.
+- [ ] Domain error codes registered in `agent-core-v2`; wire codes registered in `packages/kap-server/src/protocol`; route maps them in `sendMappedError`, matching v1's status codes and idempotent envelopes.
 - [ ] Route resolves the scope from the URL by `accessor.get(IX)`; no cached scope; finishes before disposal.
-- [ ] Tests assert the wire envelope + protocol shape; schema tests in `packages/protocol` added/updated.
+- [ ] Tests assert the wire envelope + protocol shape; wire-shape guards added/updated where the route mirrors v1.
 - [ ] `lint:domain` passes; the LegacyService did not invert scope or domain direction.
 
 ## Red lines (this subskill)
 
-- One wire schema, one home: `packages/protocol`. Never re-declare a v1 wire schema inline in server-v2.
+- One wire schema, one home: the owning `agent-core-v2` domain contract or `packages/kap-server/src/protocol`. Never re-declare a v1 wire schema inline in server-v2.
 - A `/api/v1` mirror route must keep every existing schema field's name, type, and semantics; only optional additions are allowed. A different shape belongs on `/api/v2`, not on the mirror.
 - Do not distort the native v2 Service to satisfy a v1 quirk — add a `<domain>Legacy` edge adapter instead. The native Service serves the v2 architecture; the LegacyService serves the wire contract.
 - A LegacyService is still a v2 Service: it follows scope, domain-direction, and DI rules. "Edge adapter" describes its role, not an exemption.
-- The protocol schema (`packages/protocol/src/rest/<resource>.ts`) plus the existing mirror routes are the spec for a `/api/v1` route — match them; do not re-derive the wire shape from the v2 domain model or from memory.
-- Register every new error code in **both** `agent-core-v2` and `packages/protocol`; an unmapped code is a wire break.
+- The established wire schema (in its owning home — the `agent-core-v2` domain contract or `packages/kap-server/src/protocol`) plus the existing mirror routes are the spec for a `/api/v1` route — match them; do not re-derive the wire shape from the v2 domain model or from memory.
+- Register every new error code in **both** `agent-core-v2` and `packages/kap-server/src/protocol/error-codes.ts`; an unmapped code is a wire break.
 - Events stream over WS (`listen`), never over the REST mirror; do not invent REST polling for something v1 pushed as an event.

.changeset/kap-server-local-wire.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Move the server's v1 wire schema definitions into the engine domains and the server package, removing the shared schema package from the v2 server stack with no behavior change.

packages/agent-core-v2/src/agent/contextMemory/messageProjection.ts

@@ -15,7 +15,7 @@
  * so REST consumers can still render the media after reload/resume.
  */
 
-import type { Message, MessageContent, MessageRole, ToolUseContent } from './wireMessage';
+import type { Message, MessageContent, MessageRole, ToolUseContent } from './protocolMessage';
 
 import type { ContextMessage } from './types';
 

…2/src/agent/contextMemory/wireMessage.ts …c/agent/contextMemory/protocolMessage.tspackages/agent-core-v2/src/agent/contextMemory/wireMessage.ts renamed to packages/agent-core-v2/src/agent/contextMemory/protocolMessage.ts packages/agent-core-v2/src/agent/contextMemory/wireMessage.ts renamed to packages/agent-core-v2/src/agent/contextMemory/protocolMessage.ts

@@ -20,7 +20,7 @@ import type { ExperimentalFeatureState } from '#/app/flag/flag';
 import type { ResumeSessionResult } from '#/agent/replayBuilder/types';
 import type { SessionMeta } from '#/session/sessionMetadata/sessionMetadata';
 import type { ContentPart } from '#/app/llmProtocol/message';
-import type { SessionWarning } from '#/app/sessionLegacy/sessionWire';
+import type { SessionWarning } from '#/app/sessionLegacy/sessionProtocol';
 import type { UsageStatus } from '#/agent/usage/usage';
 
 import type { ExportSessionPayload, ExportSessionResult } from '#/app/sessionExport/sessionExport';

packages/agent-core-v2/src/agent/rpc/core-api.ts

@@ -29,7 +29,7 @@ import type {
   OAuthLoginCancelResponse,
   OAuthLogoutResponse,
   RefreshOAuthProviderModelsResponse,
-} from './oauthWire';
+} from './oauthProtocol';
 
 export interface AuthStatus {
   readonly loggedIn: boolean;

packages/agent-core-v2/src/app/auth/auth.ts

@@ -39,7 +39,7 @@ import type {
   OAuthLoginCancelResponse,
   OAuthLogoutResponse,
   RefreshOAuthProviderModelsResponse,
-} from './oauthWire';
+} from './oauthProtocol';
 
 import { InstantiationType } from '#/_base/di/extensions';
 import { Disposable } from '#/_base/di/lifecycle';

packages/agent-core-v2/src/app/auth/authService.ts

@@ -19,7 +19,7 @@
  *   - `message.not_found`  → 40403
  */
 
-import type { Message, MessageRole } from '#/agent/contextMemory/wireMessage';
+import type { Message, MessageRole } from '#/agent/contextMemory/protocolMessage';
 
 import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';