refactor: move the RPC wire codec to devframe/internal

`createRpcWireCodec` / `peekRpcWireFrame` / `RpcWireCodec` are
cross-transport plumbing, not user API — they rode onto the public
`devframe/rpc` surface through the serialization module's star export.
Move them to their own module surfaced only via `devframe/internal`
(explicitly unstable), where custom transport implementations reach
them.

Also add an AGENTS.md convention: be very strict about adding or
changing public APIs — prefer devframe/internal for shared plumbing,
watch what rides along star-exported barrels, and treat every tsnapi
snapshot diff as an API-design decision.

Author: antfubot

AGENTS.md

@@ -38,6 +38,7 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 
 ## Conventions
 
+- **Be very strict about the public API surface.** Every exported symbol on a published subpath is a contract users can depend on — additions and changes must be deliberate, not a side effect of where code happens to live. Before exporting anything new, ask whether it needs to be public at all: helpers shared between first-party packages and transports belong on **`devframe/internal`** (explicitly unstable, can change in any minor release), and module-local code should simply not be exported. Barrel files that `export *` make accidental exposure easy — when adding to a star-exported module, check what rides along. The `tsnapi` snapshots under `tests/__snapshots__/tsnapi/` guard the entire surface: review every snapshot diff as an API-design decision, never regenerate it as a chore, and treat a `TSNAPI_ALLOW_BREAKING` update as something that needs the same scrutiny as the breaking change itself.
 - RPC functions must use `defineRpcFunction`; always namespace IDs `devframes:plugin:<slug>:<fn-name>` (matching the plugin's `@devframes/plugin-<slug>` package name).
 - **Stay validator-neutral.** `devframe` and every `@devframes/*` package must not introduce a preferred schema validator dependency — no `valibot`, `zod`, `arktype`, etc. in their runtime `dependencies`. `args`/`returns`/flag schemas are typed against [Standard Schema](https://standardschema.dev/) (`@standard-schema/spec`, types-only); first-party code that needs to author a schema uses the built-in zero-dep `devframe/utils/simple-schema` builder (deliberately minimal — not a general validator). JSON-schema conversion uses each schema's own Standard JSON Schema converter (`~standard.jsonSchema`, implemented by e.g. zod 4) when present and degrades to a permissive object otherwise — no converter library and no vendor dependency is required. Docs, by contrast, should point *users* at a real validator for their own integrations — recommend **valibot** (lightest) or **zod** (worth reusing if they already pull it via the JSON-render or MCP integrations).
 - Shared state via `devframe/utils/shared-state`; keep values serializable.

packages/devframe/src/internal/index.ts

@@ -14,6 +14,10 @@
 // - `registerDevframeInstance` / `listLiveDevframeInstances` — the instance
 //   registry: a custom host advertises itself; a devtool (the inspect plugin's
 //   Instances tab, the connector) enumerates what's running.
+// - `createRpcWireCodec` / `peekRpcWireFrame` — the per-connection wire
+//   codec (strict-JSON ⇄ structured-clone dispatch) and envelope peeker the
+//   built-in WS/SSE transports share; a custom transport implementation
+//   reuses them to speak the identical wire protocol.
 // - `createH3DevframeHost` — the node/standalone `DevframeHost` implementation
 //   (filesystem storage paths + origin resolution) passed to `createHostContext`.
 // - `createInstanceShell` — the shared machinery behind `initDevframe` and
@@ -42,3 +46,5 @@ export type {
 export { createContextRpcServer } from '../node/rpc-core'
 export type { ContextRpcServer, CreateContextRpcServerOptions } from '../node/rpc-core'
 export { normalizeHttpServerUrl } from '../node/utils'
+export { createRpcWireCodec, peekRpcWireFrame } from '../rpc/wire-codec'
+export type { RpcWireCodec } from '../rpc/wire-codec'

packages/devframe/src/rpc/serialization.ts

@@ -1,5 +1,3 @@
-import type { RpcFunctionDefinitionAny } from './types'
-import { structuredCloneParse, structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { diagnostics } from './diagnostics'
 
 /**
@@ -84,79 +82,6 @@ export function strictJsonStringify(value: unknown, fnName: string = ''): string
   })
 }
 
-/** The per-connection `serialize`/`deserialize` pair for a live RPC wire. */
-export interface RpcWireCodec {
-  serialize: (msg: any) => string
-  deserialize: (raw: string) => any
-}
-
-const EMPTY_WIRE_DEFS: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>> = new Map()
-
-/**
- * Build the per-connection wire codec every live transport (WS server, WS
- * client, SSE server, SSE client) shares: per-method dispatch between strict
- * JSON (methods declared `jsonSerializable: true`) and `s:`-prefixed
- * structured-clone (everything else, including all error envelopes), with a
- * request-id → method map so a response independently picks the same
- * encoder as its request. One codec per connection — request-id spaces
- * don't collide across connections.
- */
-export function createRpcWireCodec(
-  definitions: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>> = EMPTY_WIRE_DEFS,
-): RpcWireCodec {
-  // Maps an incoming request id to its method name so the matching
-  // outgoing response can look the method back up in `definitions` and
-  // pick the right encoder.
-  const pendingRequestMethods = new Map<string, string>()
-  return {
-    serialize: (msg: any): string => {
-      let method: string | undefined
-      if (msg.t === 'q') {
-        method = msg.m
-      }
-      else {
-        method = pendingRequestMethods.get(msg.i)
-        pendingRequestMethods.delete(msg.i)
-      }
-      // `jsonSerializable` constrains the return-value path (args + return).
-      // Error envelopes (`{ t: 's', i, e }`) carry a thrown value — fall back
-      // to structured-clone so they round-trip instead of crashing the serializer.
-      // Detect via `'e' in msg` so `throw undefined` still routes through SC.
-      const isErrorResponse = msg.t === 's' && 'e' in msg
-      const useJson = !isErrorResponse && !!method && definitions.get(method)?.jsonSerializable === true
-      if (useJson)
-        return strictJsonStringify(msg, method ?? '')
-      return `${STRUCTURED_CLONE_PREFIX}${structuredCloneStringify(msg)}`
-    },
-    deserialize: (raw: string): any => {
-      const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
-        ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
-        : JSON.parse(raw)
-      if (msg.t === 'q' && msg.i && msg.m)
-        pendingRequestMethods.set(msg.i, msg.m)
-      return msg
-    },
-  }
-}
-
-/**
- * Peek at a wire frame's birpc envelope without engaging a codec's
- * request-id bookkeeping — used by the SSE transport to route a frame
- * (park a POST for its response / answer with a bare 202) before it is
- * handed to birpc proper.
- */
-export function peekRpcWireFrame(raw: string): { t?: string, i?: string } {
-  try {
-    const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
-      ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
-      : JSON.parse(raw)
-    return { t: msg?.t, i: msg?.i }
-  }
-  catch {
-    return {}
-  }
-}
-
 function nonJsonAt(fnName: string, type: string, parent: unknown, key: string): Error {
   const path = formatPath(parent, key)
   return diagnostics.DF0020({ name: fnName || '<anonymous>', type, path })

packages/devframe/src/rpc/transports/sse-client.ts

@@ -1,7 +1,7 @@
 import type { ChannelOptions } from 'birpc'
 import type { RpcFunctionDefinitionAny } from '../types'
 import { DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_SSE_SESSION_HEADER } from 'devframe/constants'
-import { createRpcWireCodec } from '../serialization'
+import { createRpcWireCodec } from '../wire-codec'
 
 export interface SseRpcChannelOptions {
   /** Resolved `http(s)://` URL of the SSE endpoint. */

packages/devframe/src/rpc/transports/sse-server.ts

@@ -3,7 +3,7 @@ import type { RpcFunctionDefinitionAny } from '../types'
 import type { DevframeNodeRpcSessionMeta, DevframeRpcConnection } from './session'
 import type { WsOriginRegistry } from './ws-server'
 import { DEVFRAME_SSE_SESSION_HEADER } from 'devframe/constants'
-import { createRpcWireCodec, peekRpcWireFrame } from '../serialization'
+import { createRpcWireCodec, peekRpcWireFrame } from '../wire-codec'
 import { createRpcSessionMeta } from './session'
 import { isAllowedOrigin } from './ws-server'
 

packages/devframe/src/rpc/transports/ws-client.ts

@@ -1,7 +1,7 @@
 import type { ChannelOptions } from 'birpc'
 import type { RpcFunctionDefinitionAny } from '../types'
 import { DEVFRAME_AUTH_TOKEN_QUERY_PARAM } from 'devframe/constants'
-import { createRpcWireCodec } from '../serialization'
+import { createRpcWireCodec } from '../wire-codec'
 
 export interface WsRpcChannelOptions {
   url: string

packages/devframe/src/rpc/transports/ws-server.ts

@@ -13,7 +13,7 @@ import { createServer as createHttpsServer } from 'node:https'
 import crossws from 'crossws/adapters/node'
 import { DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM } from 'devframe/constants'
 import { randomToken, timingSafeEqual } from 'devframe/utils/crypto-token'
-import { createRpcWireCodec } from '../serialization'
+import { createRpcWireCodec } from '../wire-codec'
 import { createRpcSessionMeta } from './session'
 
 export type {

packages/devframe/src/rpc/wire-codec.ts

@@ -0,0 +1,87 @@
+import type { RpcFunctionDefinitionAny } from './types'
+import { structuredCloneParse, structuredCloneStringify } from 'devframe/utils/structured-clone'
+import { strictJsonStringify, STRUCTURED_CLONE_PREFIX } from './serialization'
+
+/**
+ * The per-connection `serialize`/`deserialize` pair for a live RPC wire.
+ *
+ * @internal
+ * implementations; not part of the stable public API.
+ */
+export interface RpcWireCodec {
+  serialize: (msg: any) => string
+  deserialize: (raw: string) => any
+}
+
+const EMPTY_WIRE_DEFS: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>> = new Map()
+
+/**
+ * Build the per-connection wire codec every live transport (WS server, WS
+ * client, SSE server, SSE client) shares: per-method dispatch between strict
+ * JSON (methods declared `jsonSerializable: true`) and `s:`-prefixed
+ * structured-clone (everything else, including all error envelopes), with a
+ * request-id → method map so a response independently picks the same
+ * encoder as its request. One codec per connection — request-id spaces
+ * don't collide across connections.
+ *
+ * @internal
+ * implementations; not part of the stable public API.
+ */
+export function createRpcWireCodec(
+  definitions: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>> = EMPTY_WIRE_DEFS,
+): RpcWireCodec {
+  // Maps an incoming request id to its method name so the matching
+  // outgoing response can look the method back up in `definitions` and
+  // pick the right encoder.
+  const pendingRequestMethods = new Map<string, string>()
+  return {
+    serialize: (msg: any): string => {
+      let method: string | undefined
+      if (msg.t === 'q') {
+        method = msg.m
+      }
+      else {
+        method = pendingRequestMethods.get(msg.i)
+        pendingRequestMethods.delete(msg.i)
+      }
+      // `jsonSerializable` constrains the return-value path (args + return).
+      // Error envelopes (`{ t: 's', i, e }`) carry a thrown value — fall back
+      // to structured-clone so they round-trip instead of crashing the serializer.
+      // Detect via `'e' in msg` so `throw undefined` still routes through SC.
+      const isErrorResponse = msg.t === 's' && 'e' in msg
+      const useJson = !isErrorResponse && !!method && definitions.get(method)?.jsonSerializable === true
+      if (useJson)
+        return strictJsonStringify(msg, method ?? '')
+      return `${STRUCTURED_CLONE_PREFIX}${structuredCloneStringify(msg)}`
+    },
+    deserialize: (raw: string): any => {
+      const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
+        ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
+        : JSON.parse(raw)
+      if (msg.t === 'q' && msg.i && msg.m)
+        pendingRequestMethods.set(msg.i, msg.m)
+      return msg
+    },
+  }
+}
+
+/**
+ * Peek at a wire frame's birpc envelope without engaging a codec's
+ * request-id bookkeeping — used by the SSE transport to route a frame
+ * (park a POST for its response / answer with a bare 202) before it is
+ * handed to birpc proper.
+ *
+ * @internal
+ * implementations; not part of the stable public API.
+ */
+export function peekRpcWireFrame(raw: string): { t?: string, i?: string } {
+  try {
+    const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
+      ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
+      : JSON.parse(raw)
+    return { t: msg?.t, i: msg?.i }
+  }
+  catch {
+    return {}
+  }
+}

tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts

@@ -9,6 +9,10 @@ export interface CreateH3DevframeHostOptions {
   appName: string;
   workspaceRoot?: string;
 }
+export interface RpcWireCodec {
+  serialize: (_: any) => string;
+  deserialize: (_: string) => any;
+}
 // #endregion
 
 // #region Types
@@ -46,7 +50,12 @@ export declare class DevframeAgentHost implements DevframeAgentHost$1 {
 // #region Functions
 export declare function coerceAgentPositionalArgs(_: unknown, _: readonly unknown[] | undefined, _?: AgentArgsFallback): unknown[];
 export declare function createH3DevframeHost(_: CreateH3DevframeHostOptions): DevframeHost;
+export declare function createRpcWireCodec(_?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>): RpcWireCodec;
 export declare function normalizeHttpServerUrl(_: string, _: number | string): string;
+export declare function peekRpcWireFrame(_: string): {
+  t?: string;
+  i?: string;
+};
 // #endregion
 
 // #region Other

tests/__snapshots__/tsnapi/devframe/internal.snapshot.js

@@ -6,9 +6,11 @@ export { coerceAgentPositionalArgs }
 export { createContextRpcServer }
 export { createH3DevframeHost }
 export { createInstanceShell }
+export { createRpcWireCodec }
 export { DevframeAgentHost }
 export { listLiveDevframeInstances }
 export { normalizeHttpServerUrl }
+export { peekRpcWireFrame }
 export { registerDevframeInstance }
 export { resolveInstanceRegister }
 export { samePath }