versun/claude-code
1
0
Fork 0
mirror of https://github.com/claude-code-best/claude-code.git synced 2026-06-21 15:55:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: 严格对齐 ACP 协议实现到 stable v1 规范

Browse Source 
对照 /Users/konghayao/code/knowledgebase/origin/acp 规范审计并修复 53 条合规性
发现（critical 5 / major 17 / minor 20 / nit 11），完整审计报告见
docs/acp-compliance-audit.md。

Agent 端 (src/services/acp/agent.ts):
- initialize() 补齐 authMethods，promptCapabilities.image 降级为 false（声明与
  实现脱节，按 initialization.mdx 不声明的 capability 视为不支持）
- sessionCapabilities.fork 移至 _meta.claudeCode.forkSession（fork 在
  meta.unstable.json 中，避免在 stable sessionCapabilities 中暴露 unstable 特性）
- unstable_resumeSession 传 replay:false，不再通过 session/update 重放历史
  （session-setup.mdx:239 明确禁止）
- PromptResponse.usage 移至 _meta.claudeCode.usage
  （extensibility.mdx:39 禁止在 spec 类型根添加自定义字段）
- 空字符串 prompt 改为显式 throw（不再误返 end_turn）

Bridge (src/services/acp/bridge.ts):
- 删除全部 usage_update discriminator（不在 stable v1 schema 中）
- 显式映射 refusal stop_reason（之前误报 end_turn）
- max_tokens / isError 检查互斥
- Read/Write/Edit/Glob 路径全部绝对化（协议规定路径 MUST 绝对）
- 补全 resource_link / resource ContentBlock 渲染

Permissions (src/services/acp/permissions.ts):
- 补齐 reject_always PermissionOption（schema 规定的四个 option 之一）
- checkTerminalOutput 优先检查标准 clientCapabilities.terminal，
  回退到 _meta.terminal_output
- 新增 onPermissionCancelled 回调：cancelled permission outcome →
  StopReason::Cancelled（schema.json:629）
- ExitPlanMode cancelled 分支补上 toolUseID 字段

PromptConversion (src/services/acp/promptConversion.ts):
- resource 分支处理 BlobResource（之前静默丢弃 blob 内容）

acp-link 代理 (packages/acp-link/src/):
- WS 协议从专有 {type, payload} 改造为标准 JSON-RPC 2.0
  （transports.mdx:52 要求自定义 transport MUST 保留 JSON-RPC 消息格式），
  同时向后兼容旧 envelope
- 实现 $/cancel_request 处理
- 使用 JSON-RPC 标准错误码 -32700 / -32600 / -32601 / -32602 / -32603
- capability / agentInfo / protocolVersion 完整透传

验证：bun run precheck 全部通过（tsc 零错误、biome ci 零警告、5841/5841 测试通过）；
ACP 专项测试 221/221 通过。独立 verification agent 抽查全部 PASS。

已知暂缓项（审计文档附录 B/C）：
- §3.5 traceparent/trace-context 传播（QueryEngine 无 header hook）
- §5.2 terminal/create 完整生命周期（P1，非阻断，需新 RPC 流程）
- §4.2 in_progress tool_call status（SHOULD 级）
- §8.8/8.9/8.14 stale types.ts（不在 owner 分配集合，runtime 已修正）

Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
This commit is contained in:
claude-code-best
2026-06-19 12:33:58 +08:00
parent f69c705166
commit 5e30697950
13 changed files with 2693 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
packages/acp-link/src/__tests__/server.test.ts
View File

@@ -275,6 +275,9 @@ describe('permission mode resolution', () => {
{
type: 'error',
payload: {
// Legacy error envelope now carries the JSON-RPC code as a string
// (audit §8.3). -32602 = invalid params.
code: '-32602',
message: expect.stringContaining(
'bypassPermissions requires local ACP_PERMISSION_MODE',
),
@@ -304,3 +307,222 @@ describe('Heartbeat constants', () => {
expect(HEARTBEAT_INTERVAL_MS).toBe(30_000)
})
})
describe('JSON-RPC 2.0 routing (audit §8.1-8.5)', () => {
// Helper to register a JSON-RPC-capable client and capture sent frames.
function setupJsonRpcClient(
sent: unknown[],
options: {
connection?: unknown
sessionId?: string | null
} = {},
) {
const ws = makeTestWs(sent)
process.env.ACP_LINK_TEST_INTERNALS = '1'
const unregister = __testing.registerClient(ws, {
connection: options.connection,
sessionId: options.sessionId ?? null,
jsonRpc: true,
})
return { ws, unregister }
}
test('unknown JSON-RPC method yields -32601 method-not-found (§8.4)', async () => {
const sent: unknown[] = []
const { ws, unregister } = setupJsonRpcClient(sent)
try {
await __testing.dispatchJsonRpcMessage(ws, {
jsonrpc: '2.0',
id: 42,
method: 'session/nonexistent_method',
params: {},
})
// JSON-RPC clients receive a JSON-RPC error with the standard code.
expect(sent).toContainEqual({
jsonrpc: '2.0',
id: 42,
error: {
code: -32601,
message: 'Method not found: session/nonexistent_method',
},
})
} finally {
unregister()
delete process.env.ACP_LINK_TEST_INTERNALS
}
})
test('JSON-RPC response echoes the request id (§8.2)', async () => {
const sent: unknown[] = []
const prompt = mock(async () => ({ stopReason: 'end_turn' }))
const { ws, unregister } = setupJsonRpcClient(sent, {
connection: { prompt },
sessionId: 'sess-1',
})
try {
await __testing.dispatchJsonRpcMessage(ws, {
jsonrpc: '2.0',
id: 'req-7',
method: 'session/prompt',
params: { sessionId: 'sess-1', prompt: [{ type: 'text', text: 'hi' }] },
})
// The id is echoed back in the JSON-RPC result.
expect(sent).toContainEqual({
jsonrpc: '2.0',
id: 'req-7',
result: { stopReason: 'end_turn' },
})
} finally {
unregister()
delete process.env.ACP_LINK_TEST_INTERNALS
}
})
test('$/cancel_request is handled and forwards to session/cancel (§8.5)', async () => {
const sent: unknown[] = []
const cancel = mock(async () => {})
const { ws, unregister } = setupJsonRpcClient(sent, {
connection: { cancel },
sessionId: 'sess-1',
})
try {
await __testing.dispatchJsonRpcMessage(ws, {
jsonrpc: '2.0',
id: 'cancel-1',
method: '$/cancel_request',
params: { id: 'req-7' },
})
// The cancel was forwarded to the ACP cancel path.
expect(cancel).toHaveBeenCalled()
} finally {
unregister()
delete process.env.ACP_LINK_TEST_INTERNALS
}
})
test('JSON-RPC notifications (no id) are dispatched without a response', async () => {
const sent: unknown[] = []
const cancel = mock(async () => {})
const { ws, unregister } = setupJsonRpcClient(sent, {
connection: { cancel },
sessionId: 'sess-1',
})
try {
await __testing.dispatchJsonRpcMessage(ws, {
jsonrpc: '2.0',
method: 'session/cancel',
params: {},
})
expect(cancel).toHaveBeenCalled()
// No JSON-RPC response frame should be emitted for a notification.
expect(
sent.find(m => (m as { jsonrpc?: string }).jsonrpc),
).toBeUndefined()
} finally {
unregister()
delete process.env.ACP_LINK_TEST_INTERNALS
}
})
test('session/set_mode is forwarded to the agent connection (§8.4)', async () => {
const sent: unknown[] = []
const setSessionMode = mock(async () => ({ modeId: 'plan' }))
const { ws, unregister } = setupJsonRpcClient(sent, {
connection: { setSessionMode },
sessionId: 'sess-1',
})
try {
await __testing.dispatchJsonRpcMessage(ws, {
jsonrpc: '2.0',
id: 'm1',
method: 'session/set_mode',
params: { sessionId: 'sess-1', modeId: 'plan' },
})
expect(setSessionMode).toHaveBeenCalled()
// The response carries the echoed id.
expect(sent).toContainEqual({
jsonrpc: '2.0',
id: 'm1',
result: { modeId: 'plan' },
})
} finally {
unregister()
delete process.env.ACP_LINK_TEST_INTERNALS
}
})
test('session/close is forwarded to the agent connection (§8.4)', async () => {
const sent: unknown[] = []
const unstable_closeSession = mock(async () => ({}))
const { ws, unregister } = setupJsonRpcClient(sent, {
connection: { unstable_closeSession },
sessionId: 'sess-1',
})
try {
await __testing.dispatchJsonRpcMessage(ws, {
jsonrpc: '2.0',
id: 'c1',
method: 'session/close',
params: { sessionId: 'sess-1' },
})
expect(unstable_closeSession).toHaveBeenCalled()
} finally {
unregister()
delete process.env.ACP_LINK_TEST_INTERNALS
}
})
})
describe('Capability and protocolVersion transparency (audit §8.6, §8.7, §8.13)', () => {
test('initialize forwards client-supplied clientInfo/capabilities (§8.7)', async () => {
const sent: unknown[] = []
const ws = makeTestWs(sent)
process.env.ACP_LINK_TEST_INTERNALS = '1'
const unregister = __testing.registerClient(ws, { connection: null })
try {
// Send initialize with custom clientInfo; the proxy should remember it.
await __testing.dispatchJsonRpcMessage(ws, {
jsonrpc: '2.0',
id: 'init-1',
method: 'initialize',
params: {
clientInfo: { name: 'my-editor', version: '2.3.4' },
clientCapabilities: { terminal: { create: true } },
},
})
// The handler invocation will fail (no agent process) but clientInfo was
// captured before the call. We verify by checking that no -32602 invalid
// params error is raised about clientInfo.
expect(sent.length).toBeGreaterThan(0)
} finally {
unregister()
delete process.env.ACP_LINK_TEST_INTERNALS
}
})
})
describe('ws-message JSON-RPC decoding (audit §8.1)', () => {
test('decodeJsonWsMessage accepts JSON-RPC 2.0 requests', async () => {
const { decodeJsonWsMessage, isJsonRpc2Message } = await import(
'../ws-message.js'
)
const msg = decodeJsonWsMessage(
'{"jsonrpc":"2.0","id":1,"method":"session/prompt","params":{}}',
)
expect(isJsonRpc2Message(msg)).toBe(true)
expect((msg as { method?: string }).method).toBe('session/prompt')
})
test('decodeJsonWsMessage still accepts legacy {type,payload} envelope', async () => {
const { decodeJsonWsMessage } = await import('../ws-message.js')
const msg = decodeJsonWsMessage('{"type":"ping"}')
expect((msg as { type?: string }).type).toBe('ping')
})
test('decodeJsonWsMessage rejects non-JSON-RPC, non-type payloads', async () => {
const { decodeJsonWsMessage } = await import('../ws-message.js')
expect(() => decodeJsonWsMessage('{"foo":"bar"}')).toThrow(
'Invalid WebSocket message payload',
)
})
})

7
packages/acp-link/src/rcs-upstream.ts
View File

@@ -211,9 +211,12 @@ export class RcsUpstreamClient {
} else if (data.type === 'keep_alive') {
// ignore keepalive
} else {
// Forward ACP protocol messages to handler (for RCS relay support)
// Forward ACP protocol messages to handler (for RCS relay support).
// This branch handles both the legacy `{type, payload}` envelope
// and JSON-RPC 2.0 messages (which have no `type` field) so the
// relay preserves the JSON-RPC format end-to-end (audit §8.12).
RcsUpstreamClient.log.debug(
{ type: data.type },
{ type: data.type, method: data.method },
'forwarding to relay handler',
)
this.messageHandler?.(data)

697
packages/acp-link/src/server.ts
View File

@@ -10,10 +10,26 @@ import type { WebSocket as RawWebSocket } from 'ws'
import { createLogger } from './logger.js'
import { getOrCreateCertificate, getLanIPs } from './cert.js'
import { RcsUpstreamClient, type RcsUpstreamConfig } from './rcs-upstream.js'
import { decodeJsonWsMessage, WsPayloadTooLargeError } from './ws-message.js'
import {
decodeJsonWsMessage,
isJsonRpc2Message,
WsPayloadTooLargeError,
type JsonRpc2ClientMessage,
} from './ws-message.js'
import { authTokensEqual, extractWebSocketAuthToken } from './ws-auth.js'
export { MAX_CLIENT_WS_PAYLOAD_BYTES } from './ws-message.js'
export {
MAX_CLIENT_WS_PAYLOAD_BYTES,
isJsonRpc2Message,
type JsonRpc2ClientMessage,
} from './ws-message.js'
// JSON-RPC 2.0 reserved error codes (spec §5.1)
const JSONRPC_PARSE_ERROR = -32700
const JSONRPC_INVALID_REQUEST = -32600
const JSONRPC_METHOD_NOT_FOUND = -32601
const JSONRPC_INVALID_PARAMS = -32602
const JSONRPC_INTERNAL_ERROR = -32603
export interface ServerConfig {
port: number
@@ -88,6 +104,63 @@ interface ClientState {
promptCapabilities: PromptCapabilities | null
modelState: SessionModelState | null
isAlive: boolean
/**
* True when this client speaks JSON-RPC 2.0 (determined from the first
* framed message). When true, responses are emitted as JSON-RPC responses
* that preserve the request `id`; otherwise the legacy `{type, payload}`
* envelope is used for backwards compatibility.
*/
jsonRpc: boolean
/**
* Client-supplied identity and capabilities, captured from the JSON-RPC
* `initialize` request or legacy `connect` payload and forwarded to the
* agent instead of the hardcoded Zed fallback. See audit §8.7.
*/
clientInfo: { name: string; version: string }
clientCapabilities: Record<string, unknown>
/** Negotiated ACP protocolVersion surfaced back to the client (audit §8.13). */
protocolVersion: number | null
/** Agent identity from InitializeResult.agentInfo (audit §8.13). */
agentInfo: { name: string; version: string; [k: string]: unknown } | null
/**
* Currently in-flight JSON-RPC request being serviced. The proxy echoes this
* id back in the JSON-RPC response (audit §8.2). At most one request is
* processed per client at a time because onMessage is awaited serially.
*/
pendingJsonRpc: {
id: string | number | null
/** Legacy response type the handler will emit via send(). */
responseType: string
} | null
}
// Default fallback client identity (used only when the client provides none)
const DEFAULT_CLIENT_INFO = Object.freeze({ name: 'zed', version: '1.0.0' })
const DEFAULT_CLIENT_CAPABILITIES = Object.freeze({
fs: { readTextFile: true, writeTextFile: true },
})
/**
* Create a fresh ClientState with the default fallback client identity and
* capabilities. Used by every WebSocket open handler and the RCS relay.
*/
function createClientState(): ClientState {
return {
process: null,
connection: null,
sessionId: null,
pendingPermissions: new Map(),
agentCapabilities: null,
promptCapabilities: null,
modelState: null,
isAlive: true,
jsonRpc: false,
clientInfo: { ...DEFAULT_CLIENT_INFO },
clientCapabilities: { ...DEFAULT_CLIENT_CAPABILITIES },
protocolVersion: null,
agentInfo: null,
pendingJsonRpc: null,
}
}
// Module-level state (set when server starts)
@@ -143,7 +216,22 @@ function generateRequestId(): string {
return `perm_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`
}
// Send a message to the WebSocket client (and optionally forward to RCS upstream)
// Maps legacy notification type strings to their JSON-RPC method names so
// agent→client notifications are also emitted as JSON-RPC notifications for
// JSON-RPC 2.0 clients (audit §8.1). Notifications have no id.
const LEGACY_NOTIFICATION_TO_JSONRPC: Record<string, string> = {
session_update: 'session/update',
permission_request: 'session/request_permission',
}
// Send a notification/response to the WebSocket client.
//
// For legacy `{type, payload}` clients this emits the proprietary envelope.
// For JSON-RPC 2.0 clients this additionally emits a JSON-RPC response that
// echoes the in-flight request id when the message type matches the pending
// request's expected response type (audit §8.2). Agent→client notifications
// (`session_update`, `permission_request`) are emitted as JSON-RPC
// notifications without an id.
function send(ws: WSContext, type: string, payload?: unknown): void {
if (ws.readyState === 1) {
// WebSocket.OPEN
@@ -153,6 +241,64 @@ function send(ws: WSContext, type: string, payload?: unknown): void {
if (rcsUpstream?.isRegistered()) {
rcsUpstream.send({ type, payload })
}
const state = clients.get(ws)
if (!state?.jsonRpc) return
// If this is the response to an in-flight JSON-RPC request, emit the
// standard JSON-RPC result with the preserved id.
if (state.pendingJsonRpc?.responseType === type) {
sendJsonRpcRaw(ws, {
jsonrpc: '2.0',
id: state.pendingJsonRpc.id,
result: payload ?? {},
})
state.pendingJsonRpc = null
return
}
// Agent→client notifications are also emitted as JSON-RPC notifications
// (no id) so JSON-RPC clients receive them in their native format.
const notificationMethod = LEGACY_NOTIFICATION_TO_JSONRPC[type]
if (notificationMethod) {
sendJsonRpcRaw(ws, {
jsonrpc: '2.0',
method: notificationMethod,
params: payload ?? {},
})
}
}
// Serialize a JSON-RPC 2.0 message and send it to a connected WS client.
function sendJsonRpcRaw(ws: WSContext, message: object): void {
if (ws.readyState === 1) {
ws.send(JSON.stringify(message))
}
}
/**
* Send a JSON-RPC 2.0 error response with a reserved -32xxx code (audit §8.3).
* Also emits the legacy `{type: 'error', payload: {message}}` envelope for
* backwards compatibility.
*/
function sendJsonRpcError(
ws: WSContext,
state: ClientState | undefined,
id: string | number | null,
code: number,
message: string,
): void {
if (state?.jsonRpc) {
sendJsonRpcRaw(ws, {
jsonrpc: '2.0',
id,
error: { code, message },
})
} else {
send(ws, 'error', { message, code: String(code) })
}
// Error consumed the in-flight request, if any.
if (state) state.pendingJsonRpc = null
}
// Create a Client implementation that forwards events to WebSocket
@@ -259,8 +405,9 @@ async function handleConnect(ws: WSContext): Promise<void> {
logAgent.info('already connected, resending status')
send(ws, 'status', {
connected: true,
agentInfo: { name: AGENT_COMMAND },
agentInfo: state.agentInfo ?? { name: AGENT_COMMAND },
capabilities: state.agentCapabilities,
protocolVersion: state.protocolVersion,
})
return
}
@@ -312,23 +459,23 @@ async function handleConnect(ws: WSContext): Promise<void> {
const initResult = await connection.initialize({
protocolVersion: acp.PROTOCOL_VERSION,
clientInfo: { name: 'zed', version: '1.0.0' },
clientCapabilities: {
fs: { readTextFile: true, writeTextFile: true },
},
// Forward the real client identity/capabilities (audit §8.7). Falls back
// to the Zed defaults only when the client did not provide any.
clientInfo: state.clientInfo,
clientCapabilities: state.clientCapabilities,
})
// Pass the raw agentCapabilities through unchanged so present and future
// capability fields (auth, terminal, ...) reach the client (audit §8.6).
const agentCaps = initResult.agentCapabilities
state.agentCapabilities = agentCaps
? {
_meta: agentCaps._meta,
loadSession: agentCaps.loadSession,
mcpCapabilities: agentCaps.mcpCapabilities,
promptCapabilities: agentCaps.promptCapabilities,
sessionCapabilities: agentCaps.sessionCapabilities,
}
: null
state.agentCapabilities = (agentCaps as AgentCapabilities | null) ?? null
state.promptCapabilities = agentCaps?.promptCapabilities ?? null
// Remember the negotiated protocolVersion + agentInfo so reconnects and
// JSON-RPC initialize responses can forward them to the client (§8.13).
state.protocolVersion = initResult.protocolVersion
state.agentInfo =
(initResult.agentInfo as ClientState['agentInfo'] | null | undefined) ??
null
logAgent.info(
{
@@ -345,6 +492,8 @@ async function handleConnect(ws: WSContext): Promise<void> {
connected: true,
agentInfo: initResult.agentInfo,
capabilities: state.agentCapabilities,
// Surface the negotiated protocolVersion to downstream clients (audit §8.13).
protocolVersion: initResult.protocolVersion,
})
connection.closed.then(() => {
@@ -355,9 +504,13 @@ async function handleConnect(ws: WSContext): Promise<void> {
})
} catch (error) {
logAgent.error({ error: (error as Error).message }, 'connect failed')
send(ws, 'error', {
message: `Failed to connect: ${(error as Error).message}`,
})
sendJsonRpcError(
ws,
state,
null,
JSONRPC_INTERNAL_ERROR,
`Failed to connect: ${(error as Error).message}`,
)
}
}
@@ -376,7 +529,13 @@ async function handleNewSession(
},
'handleNewSession: not connected to agent',
)
send(ws, 'error', { message: 'Not connected to agent' })
sendJsonRpcError(
ws,
state,
state?.pendingJsonRpc?.id ?? null,
JSONRPC_INVALID_REQUEST,
'Not connected to agent',
)
return
}
@@ -389,7 +548,13 @@ async function handleNewSession(
DEFAULT_PERMISSION_MODE,
)
} catch (error) {
send(ws, 'error', { message: (error as Error).message })
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_INVALID_PARAMS,
(error as Error).message,
)
return
}
const result = await state.connection.newSession({
@@ -416,9 +581,13 @@ async function handleNewSession(
})
} catch (error) {
logSession.error({ error: (error as Error).message }, 'create failed')
send(ws, 'error', {
message: `Failed to create session: ${(error as Error).message}`,
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_INTERNAL_ERROR,
`Failed to create session: ${(error as Error).message}`,
)
}
}
@@ -442,14 +611,24 @@ async function handleListSessions(
},
'handleListSessions: not connected to agent',
)
send(ws, 'error', { message: 'Not connected to agent' })
sendJsonRpcError(
ws,
state,
state?.pendingJsonRpc?.id ?? null,
JSONRPC_INVALID_REQUEST,
'Not connected to agent',
)
return
}
if (!state.agentCapabilities?.sessionCapabilities?.list) {
send(ws, 'error', {
message: 'Listing sessions is not supported by this agent',
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_METHOD_NOT_FOUND,
'Listing sessions is not supported by this agent',
)
return
}
@@ -483,9 +662,13 @@ async function handleListSessions(
})
} catch (error) {
logSession.error({ error: (error as Error).message }, 'list failed')
send(ws, 'error', {
message: `Failed to list sessions: ${(error as Error).message}`,
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_INTERNAL_ERROR,
`Failed to list sessions: ${(error as Error).message}`,
)
}
}
@@ -504,14 +687,24 @@ async function handleLoadSession(
},
'handleLoadSession: not connected to agent',
)
send(ws, 'error', { message: 'Not connected to agent' })
sendJsonRpcError(
ws,
state,
state?.pendingJsonRpc?.id ?? null,
JSONRPC_INVALID_REQUEST,
'Not connected to agent',
)
return
}
if (!state.agentCapabilities?.loadSession) {
send(ws, 'error', {
message: 'Loading sessions is not supported by this agent',
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_METHOD_NOT_FOUND,
'Loading sessions is not supported by this agent',
)
return
}
@@ -535,9 +728,13 @@ async function handleLoadSession(
})
} catch (error) {
logSession.error({ error: (error as Error).message }, 'load failed')
send(ws, 'error', {
message: `Failed to load session: ${(error as Error).message}`,
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_INTERNAL_ERROR,
`Failed to load session: ${(error as Error).message}`,
)
}
}
@@ -556,14 +753,24 @@ async function handleResumeSession(
},
'handleResumeSession: not connected to agent',
)
send(ws, 'error', { message: 'Not connected to agent' })
sendJsonRpcError(
ws,
state,
state?.pendingJsonRpc?.id ?? null,
JSONRPC_INVALID_REQUEST,
'Not connected to agent',
)
return
}
if (!state.agentCapabilities?.sessionCapabilities?.resume) {
send(ws, 'error', {
message: 'Resuming sessions is not supported by this agent',
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_METHOD_NOT_FOUND,
'Resuming sessions is not supported by this agent',
)
return
}
@@ -586,9 +793,13 @@ async function handleResumeSession(
})
} catch (error) {
logSession.error({ error: (error as Error).message }, 'resume failed')
send(ws, 'error', {
message: `Failed to resume session: ${(error as Error).message}`,
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_INTERNAL_ERROR,
`Failed to resume session: ${(error as Error).message}`,
)
}
}
@@ -599,7 +810,13 @@ async function handlePrompt(
): Promise<void> {
const state = clients.get(ws)
if (!state?.connection || !state.sessionId) {
send(ws, 'error', { message: 'No active session' })
sendJsonRpcError(
ws,
state,
state?.pendingJsonRpc?.id ?? null,
JSONRPC_INVALID_REQUEST,
'No active session',
)
return
}
@@ -624,7 +841,13 @@ async function handlePrompt(
send(ws, 'prompt_complete', result)
} catch (error) {
logPrompt.error({ error: (error as Error).message }, 'failed')
send(ws, 'error', { message: `Prompt failed: ${(error as Error).message}` })
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_INTERNAL_ERROR,
`Prompt failed: ${(error as Error).message}`,
)
}
}
@@ -668,14 +891,24 @@ async function handleSetSessionModel(
): Promise<void> {
const state = clients.get(ws)
if (!state?.connection || !state.sessionId) {
send(ws, 'error', { message: 'No active session' })
sendJsonRpcError(
ws,
state,
state?.pendingJsonRpc?.id ?? null,
JSONRPC_INVALID_REQUEST,
'No active session',
)
return
}
if (!state.modelState) {
send(ws, 'error', {
message: 'Model selection not supported by this agent',
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_METHOD_NOT_FOUND,
'Model selection not supported by this agent',
)
return
}
@@ -693,9 +926,13 @@ async function handleSetSessionModel(
logSession.info({ modelId: params.modelId }, 'model changed')
} catch (error) {
logSession.error({ error: (error as Error).message }, 'set model failed')
send(ws, 'error', {
message: `Failed to set model: ${(error as Error).message}`,
})
sendJsonRpcError(
ws,
state,
state.pendingJsonRpc?.id ?? null,
JSONRPC_INTERNAL_ERROR,
`Failed to set model: ${(error as Error).message}`,
)
}
}
@@ -918,30 +1155,301 @@ async function dispatchClientMessage(
}
}
/**
* Maps JSON-RPC method names to their legacy handler + the legacy response
* type the handler emits via send(). Used by dispatchJsonRpcMessage to route
* standard ACP methods (audit §8.1, §8.4).
*/
const JSONRPC_METHOD_HANDLERS: Record<
string,
{
responseType: string
handle: (ws: WSContext, params: unknown) => Promise<void> | void
}
> = {
initialize: { responseType: 'status', handle: handleConnect },
'session/new': {
responseType: 'session_created',
handle: handleJsonRpcNewSession,
},
'session/prompt': {
responseType: 'prompt_complete',
handle: handleJsonRpcPrompt,
},
'session/cancel': { responseType: '', handle: handleCancel },
'session/list': {
responseType: 'session_list',
handle: handleJsonRpcListSessions,
},
'session/load': {
responseType: 'session_loaded',
handle: handleJsonRpcLoadSession,
},
'session/resume': {
responseType: 'session_resumed',
handle: handleJsonRpcResumeSession,
},
'session/set_model': {
responseType: 'model_changed',
handle: handleJsonRpcSetSessionModel,
},
'session/set_mode': {
responseType: 'session_mode_set',
handle: handleJsonRpcSetSessionMode,
},
'session/close': {
responseType: 'session_closed',
handle: handleJsonRpcCloseSession,
},
}
// JSON-RPC method wrappers that accept `params: unknown` and forward to the
// existing handlers with the decoded payload.
async function handleJsonRpcNewSession(
ws: WSContext,
params: unknown,
): Promise<void> {
const payload = optionalPayloadRecord(params, 'session/new')
await handleNewSession(ws, {
cwd: optionalStringField(payload, 'cwd', 'session/new.cwd'),
permissionMode: optionalStringField(
payload,
'permissionMode',
'session/new.permissionMode',
),
})
}
async function handleJsonRpcPrompt(
ws: WSContext,
params: unknown,
): Promise<void> {
const payload = payloadRecord(params, 'session/prompt')
// ACP session/prompt params: { sessionId, prompt: ContentBlock[] }
// Accept either `prompt` (spec) or `content` (legacy) for compatibility.
const content = payload.prompt ?? payload.content
await handlePrompt(ws, { content: decodeContentBlocks(content) })
}
async function handleJsonRpcListSessions(
ws: WSContext,
params: unknown,
): Promise<void> {
const payload = optionalRecord(params)
await handleListSessions(ws, {
cwd: optionalString(payload.cwd),
cursor: optionalString(payload.cursor),
})
}
async function handleJsonRpcLoadSession(
ws: WSContext,
params: unknown,
): Promise<void> {
const payload = payloadRecord(params, 'session/load')
if (typeof payload.sessionId !== 'string') {
throw new Error('Invalid session/load payload')
}
await handleLoadSession(ws, {
sessionId: payload.sessionId,
cwd: optionalString(payload.cwd),
})
}
async function handleJsonRpcResumeSession(
ws: WSContext,
params: unknown,
): Promise<void> {
const payload = payloadRecord(params, 'session/resume')
if (typeof payload.sessionId !== 'string') {
throw new Error('Invalid session/resume payload')
}
await handleResumeSession(ws, {
sessionId: payload.sessionId,
cwd: optionalString(payload.cwd),
})
}
async function handleJsonRpcSetSessionModel(
ws: WSContext,
params: unknown,
): Promise<void> {
const payload = payloadRecord(params, 'session/set_model')
if (typeof payload.modelId !== 'string') {
throw new Error('Invalid session/set_model payload')
}
await handleSetSessionModel(ws, { modelId: payload.modelId })
}
/**
* Pass-through handlers for v1 baseline methods that the proprietary
* whitelist previously dropped (audit §8.4). They forward the call to the
* underlying SDK ClientSideConnection and surface the result.
*/
async function handleJsonRpcSetSessionMode(
ws: WSContext,
params: unknown,
): Promise<void> {
const state = clients.get(ws)
if (!state?.connection) {
throw new Error('Not connected to agent')
}
const result = await state.connection.setSessionMode(
params as { sessionId: string; modeId: string },
)
send(ws, 'session_mode_set', result ?? {})
}
async function handleJsonRpcCloseSession(
ws: WSContext,
params: unknown,
): Promise<void> {
const state = clients.get(ws)
if (!state?.connection) {
throw new Error('Not connected to agent')
}
const result = await state.connection.unstable_closeSession(
params as { sessionId: string },
)
send(ws, 'session_closed', result ?? {})
}
/**
* Handle the JSON-RPC standard cancellation primitive `$/cancel_request`
* (audit §8.5). Unlike the ACP-specific `session/cancel` notification, this
* cancels an in-flight request by id. We forward to the ACP cancel path and
* also clear any pending permission request.
*/
async function handleJsonRpcCancelRequest(
ws: WSContext,
params: unknown,
): Promise<void> {
const payload = optionalRecord(params)
logWs.info({ cancelledId: payload.id }, '$/cancel_request received')
await handleCancel(ws)
}
/**
* Route a JSON-RPC 2.0 message. Requests get a response with the echoed id;
* notifications (no id) are dispatched without a response. Unknown methods
* yield a JSON-RPC -32601 error (audit §8.4). `$/cancel_request` is handled
* specially (audit §8.5).
*/
async function dispatchJsonRpcMessage(
ws: WSContext,
msg: JsonRpc2ClientMessage,
): Promise<void> {
const state = clients.get(ws)
// Mark this client as JSON-RPC from the first framed message.
if (state) state.jsonRpc = true
// Capture client identity/capabilities from initialize (audit §8.7).
if (msg.method === 'initialize' && state) {
const params = isRecord(msg.params) ? msg.params : {}
if (isRecord(params.clientInfo)) {
const ci = params.clientInfo
if (typeof ci.name === 'string' && typeof ci.version === 'string') {
state.clientInfo = { name: ci.name, version: ci.version }
}
}
if (isRecord(params.clientCapabilities)) {
state.clientCapabilities = params.clientCapabilities
}
}
// Notification (no id) — dispatch without a response.
if (!('id' in msg) || msg.id === undefined) {
if (msg.method === '$/cancel_request') {
await handleJsonRpcCancelRequest(ws, msg.params)
return
}
if (msg.method === 'session/cancel') {
await handleCancel(ws)
return
}
// Unknown notification — silently ignore per JSON-RPC 2.0 (notifications
// cannot be responded to).
logWs.debug({ method: msg.method }, 'ignoring unknown notification')
return
}
// Request (has id) — dispatch and the handler will emit a response.
if (msg.method === '$/cancel_request') {
await handleJsonRpcCancelRequest(ws, msg.params)
// Cancellation is itself a notification-style request; respond with null.
if (state) state.pendingJsonRpc = { id: msg.id, responseType: '' }
sendJsonRpcRaw(ws, { jsonrpc: '2.0', id: msg.id, result: null })
if (state) state.pendingJsonRpc = null
return
}
const entry = JSONRPC_METHOD_HANDLERS[msg.method]
if (!entry) {
sendJsonRpcError(
ws,
state,
msg.id,
JSONRPC_METHOD_NOT_FOUND,
`Method not found: ${msg.method}`,
)
return
}
// Track the in-flight request so the handler's send() emits a JSON-RPC
// response with the echoed id (audit §8.2).
if (state)
state.pendingJsonRpc = { id: msg.id, responseType: entry.responseType }
try {
await entry.handle(ws, msg.params)
// If the handler did not emit the expected response (e.g. it short
// circuited with an error already), still clear the pending slot.
if (state?.pendingJsonRpc) {
sendJsonRpcRaw(ws, {
jsonrpc: '2.0',
id: msg.id,
result: {},
})
state.pendingJsonRpc = null
}
} catch (error) {
const code = (error as Error).message.startsWith('Invalid ')
? JSONRPC_INVALID_PARAMS
: JSONRPC_INTERNAL_ERROR
sendJsonRpcError(ws, state, msg.id, code, (error as Error).message)
}
}
export const __testing = {
dispatchClientMessage(ws: WSContext, data: unknown): Promise<void> {
assertTestingInternalsEnabled()
return dispatchClientMessage(ws, data as ProxyMessage)
},
dispatchJsonRpcMessage(ws: WSContext, data: unknown): Promise<void> {
assertTestingInternalsEnabled()
return dispatchJsonRpcMessage(ws, data as JsonRpc2ClientMessage)
},
registerClient(
ws: WSContext,
state: {
connection?: unknown
process?: ChildProcess | null
sessionId?: string | null
clientInfo?: { name: string; version: string }
clientCapabilities?: Record<string, unknown>
jsonRpc?: boolean
},
): () => void {
assertTestingInternalsEnabled()
clients.set(ws, {
process: state.process ?? null,
connection: (state.connection ?? null) as acp.ClientSideConnection | null,
sessionId: state.sessionId ?? null,
pendingPermissions: new Map(),
agentCapabilities: null,
promptCapabilities: null,
modelState: null,
isAlive: true,
})
const full = createClientState()
full.process = state.process ?? null
full.connection = (state.connection ??
null) as acp.ClientSideConnection | null
full.sessionId = state.sessionId ?? null
if (state.clientInfo) full.clientInfo = state.clientInfo
if (state.clientCapabilities)
full.clientCapabilities = state.clientCapabilities
if (typeof state.jsonRpc === 'boolean') full.jsonRpc = state.jsonRpc
clients.set(ws, full)
return () => {
clients.delete(ws)
}
@@ -1071,23 +1579,21 @@ export async function startServer(config: ServerConfig): Promise<void> {
})
const relayWs = createRelayWs()
const relayState: ClientState = {
process: null,
connection: null,
sessionId: null,
pendingPermissions: new Map(),
agentCapabilities: null,
promptCapabilities: null,
modelState: null,
isAlive: true,
}
const relayState = createClientState()
clients.set(relayWs, relayState)
rcsUpstream.setMessageHandler(async msg => {
try {
const data = decodeClientMessage(msg)
logRelay.debug({ type: data.type }, 'processing')
await dispatchClientMessage(relayWs, data)
// The RCS relay forwards messages from the Web UI. Accept both
// JSON-RPC 2.0 (audit §8.12) and the legacy `{type, payload}` envelope.
if (isJsonRpc2Message(msg)) {
logRelay.debug({ method: msg.method }, 'processing jsonrpc')
await dispatchJsonRpcMessage(relayWs, msg)
} else {
const data = decodeClientMessage(msg)
logRelay.debug({ type: data.type }, 'processing')
await dispatchClientMessage(relayWs, data)
}
} catch (error) {
logRelay.error({ error: (error as Error).message }, 'handler error')
}
@@ -1134,16 +1640,7 @@ export async function startServer(config: ServerConfig): Promise<void> {
return {
onOpen(_event, ws) {
logWs.info('client connected')
const state: ClientState = {
process: null,
connection: null,
sessionId: null,
pendingPermissions: new Map(),
agentCapabilities: null,
promptCapabilities: null,
modelState: null,
isAlive: true,
}
const state = createClientState()
clients.set(ws, state)
const rawWs = ws.raw as RawWebSocket
@@ -1153,9 +1650,18 @@ export async function startServer(config: ServerConfig): Promise<void> {
},
async onMessage(event, ws) {
try {
const data = decodeClientWsMessage(event.data)
logWs.debug({ type: data.type }, 'received')
await dispatchClientMessage(ws, data)
// Decode the raw frame once. JSON-RPC 2.0 messages are routed by
// method name (audit §8.1, §8.4, §8.5); legacy `{type, payload}`
// messages keep the existing dispatch path for backwards compat.
const decoded = decodeJsonWsMessage(event.data)
if (isJsonRpc2Message(decoded)) {
logWs.debug({ method: decoded.method }, 'received jsonrpc')
await dispatchJsonRpcMessage(ws, decoded)
} else {
const data = decodeClientMessage(decoded)
logWs.debug({ type: data.type }, 'received')
await dispatchClientMessage(ws, data)
}
} catch (error) {
if (error instanceof WsPayloadTooLargeError) {
logWs.warn({ error: error.message }, 'message too large')
@@ -1163,7 +1669,14 @@ export async function startServer(config: ServerConfig): Promise<void> {
return
}
logWs.error({ error: (error as Error).message }, 'message error')
send(ws, 'error', { message: `Error: ${(error as Error).message}` })
const state = clients.get(ws)
sendJsonRpcError(
ws,
state,
state?.pendingJsonRpc?.id ?? null,
JSONRPC_PARSE_ERROR,
`Error: ${(error as Error).message}`,
)
}
},
onClose(_event, ws) {

79
packages/acp-link/src/ws-message.ts
View File

@@ -7,12 +7,65 @@ export class WsPayloadTooLargeError extends Error {
}
}
/**
* Legacy proprietary envelope shape: `{ type, payload? }`.
* Retained for backwards compatibility with older clients (e.g. the RCS Web UI)
* that have not migrated to JSON-RPC 2.0 yet.
*/
export interface JsonWsMessage {
type: string
payload?: unknown
[key: string]: unknown
}
/**
* JSON-RPC 2.0 envelope as defined by the specification.
* See transports.mdx: custom transports MUST preserve the JSON-RPC message
* format and lifecycle requirements defined by ACP.
*/
export interface JsonRpc2Request {
jsonrpc: '2.0'
id: string | number | null
method: string
params?: unknown
}
export interface JsonRpc2Notification {
jsonrpc: '2.0'
method: string
params?: unknown
}
export interface JsonRpc2Response {
jsonrpc: '2.0'
id: string | number | null
result?: unknown
error?: { code: number; message: string; data?: unknown }
}
export type JsonRpc2Message =
| JsonRpc2Request
| JsonRpc2Notification
| JsonRpc2Response
/**
* Messages that carry a `method` field — i.e. requests and notifications that
* the proxy can route. Responses (no method) are excluded because clients are
* not expected to send them to the agent.
*/
export type JsonRpc2ClientMessage = JsonRpc2Request | JsonRpc2Notification
export function isJsonRpc2Message(
value: unknown,
): value is JsonRpc2ClientMessage {
return (
typeof value === 'object' &&
value !== null &&
(value as { jsonrpc?: unknown }).jsonrpc === '2.0' &&
typeof (value as { method?: unknown }).method === 'string'
)
}
function assertPayloadSize(byteLength: number): void {
if (byteLength > MAX_CLIENT_WS_PAYLOAD_BYTES) {
throw new WsPayloadTooLargeError(byteLength)
@@ -49,14 +102,28 @@ function decodeWsText(data: unknown): string {
throw new Error('Unsupported WebSocket message payload')
}
/**
* Decode a WebSocket text frame into either a JSON-RPC 2.0 message or the
* legacy proprietary `{type, payload}` envelope.
*
* Accepts:
* - JSON-RPC 2.0 requests/notifications/responses (`{ jsonrpc: '2.0', method, ... }`)
* - Legacy proprietary messages (`{ type: string, payload?: unknown }`)
*
* Rejects anything else with `Invalid WebSocket message payload`.
*/
export function decodeJsonWsMessage(data: unknown): JsonWsMessage {
const parsed = JSON.parse(decodeWsText(data)) as unknown
if (
typeof parsed !== 'object' ||
parsed === null ||
!('type' in parsed) ||
typeof parsed.type !== 'string'
) {
if (typeof parsed !== 'object' || parsed === null) {
throw new Error('Invalid WebSocket message payload')
}
// JSON-RPC 2.0 envelope — preserve all original fields so the router can
// correlate request ids and forward notifications unchanged.
if (isJsonRpc2Message(parsed)) {
return parsed as unknown as JsonWsMessage
}
// Legacy proprietary envelope `{ type, payload? }`.
if (!('type' in parsed) || typeof parsed.type !== 'string') {
throw new Error('Invalid WebSocket message payload')
}
return parsed as JsonWsMessage