158b8a8ead
- web host boots CommandService + command-goal; session.prompt intercepts a lone text block starting with '/' and executes it as a command (unknown -> RPC unknown-command, usage error -> RPC command-error, so the composer restores the draft and shows the error strip) instead of sending it to the model — symmetric with the ACP adapter - prompt response carries command result text on the wire for future UI - api-proxy also lands the host-side goals RPC handlers
118 lines
4.5 KiB
TypeScript
118 lines
4.5 KiB
TypeScript
/**
|
|
* Four-quadrant RPC message model. Channels and messages are
|
|
* decoupled: HTTP is the client→server physical channel, SSE the server→client one; logical
|
|
* messages are channel-independent, and the wire full form is a four-member discriminated union.
|
|
* api/ contract layer: zero Node dependencies, importable from the browser.
|
|
*/
|
|
|
|
import type { z as zCore } from 'zod'
|
|
type ZodIssue = zCore.core.$ZodIssue
|
|
import type { Branded } from '@deepseek-ai/dsh-brand'
|
|
import type { SessionId } from '@deepseek-ai/dsh-session/types'
|
|
|
|
/**
|
|
* Message correlation id: the initiator mints it on a request; a response
|
|
* echoes the matching request's rpcId and never mints a new one.
|
|
*/
|
|
export type RpcId = Branded<'rpc-id'>
|
|
|
|
/**
|
|
* Brands a string as RpcId (same precedent as core `SessionId()`). Minted by the initiator:
|
|
* client-request → client mints; server-request → host mints (answerable frames get a stable
|
|
* logical id, pure pushes mint a fresh one each time).
|
|
* @param id - Raw id string (implementations mint UUIDs; tests may pass fixtures).
|
|
* @returns The same string, branded (compile-time cast, zero runtime cost).
|
|
*/
|
|
export function RpcId(id: string): RpcId {
|
|
return id as RpcId
|
|
}
|
|
|
|
/** Error code → details type map (a second table isomorphic to RpcMethodMap). New code = one row here + one branch in the error schema. */
|
|
export interface RpcErrorDetailsMap {
|
|
'bad-request': { issues: ZodIssue[] }
|
|
'session-not-found': { sessionId: SessionId }
|
|
'agent-busy': { reason: string }
|
|
/** A known slash command reported a usage/state error; the message is the command's own text. */
|
|
'command-error': {}
|
|
/** A leading-/ prompt named no registered command; the message names the token. */
|
|
'unknown-command': {}
|
|
'internal': {}
|
|
}
|
|
|
|
/** Closed error-code union (the keys of RpcErrorDetailsMap). */
|
|
export type RpcErrorCode = keyof RpcErrorDetailsMap
|
|
|
|
/**
|
|
* Distributive union expanded from the map: code is the discriminant, so
|
|
* `switch (error.code)` narrows details. details is required (internal uses an explicit {}).
|
|
*/
|
|
export type RpcError = {
|
|
[C in RpcErrorCode]: { code: C; message: string; details: RpcErrorDetailsMap[C] }
|
|
}[RpcErrorCode]
|
|
|
|
/** Business success/failure result: the result slot of a unary response; methods never throw business errors. */
|
|
export type RpcResult<T> = { ok: true; value: T } | { ok: false; error: RpcError }
|
|
|
|
/**
|
|
* Signature-layer narrow form, request side (domain-interface view, shared by
|
|
* both directions): rpcId is explicit in the signature, never mixed into the
|
|
* business payload; the type tag and method are filled in by the carrier layer.
|
|
*/
|
|
export interface RpcRequest<P> {
|
|
rpcId: RpcId
|
|
payload: P
|
|
}
|
|
|
|
/** Signature-layer narrow form, response side: rpcId always echoes the matching request. */
|
|
export interface RpcResponse<T> {
|
|
rpcId: RpcId
|
|
result: RpcResult<T>
|
|
}
|
|
|
|
// ---- Wire full forms: four named members of a discriminated union (discriminant = the four `type` literals) ----
|
|
|
|
/** Call initiated by the client (wire carrier: POST /api/<method> body). */
|
|
export interface ClientRequest {
|
|
type: 'client-request'
|
|
rpcId: RpcId
|
|
method: string
|
|
payload: unknown
|
|
}
|
|
|
|
/** Response to a ClientRequest (wire carrier: the HTTP response body of that POST); rpcId echoed. */
|
|
export interface ServerResponse {
|
|
type: 'server-response'
|
|
rpcId: RpcId
|
|
result: RpcResult<unknown>
|
|
}
|
|
|
|
/**
|
|
* Message initiated by the server (wire carrier: SSE frame). Answerable interactions
|
|
* (approval/question requested — stable rpcId, reused on replay) and pure pushes
|
|
* (session/event etc. — rpcId identifies that one push) share this shape; whether a
|
|
* response is expected is determined statically by method (a strict dichotomy, no third kind).
|
|
*/
|
|
export interface ServerRequest {
|
|
type: 'server-request'
|
|
rpcId: RpcId
|
|
method: string
|
|
payload: unknown
|
|
}
|
|
|
|
/** Response to a ServerRequest (wire carrier: POST /api/respond body); rpcId echoed, never minted anew. */
|
|
export interface ClientResponse {
|
|
type: 'client-response'
|
|
rpcId: RpcId
|
|
result: RpcResult<unknown>
|
|
}
|
|
|
|
/** Authoritative wire full-form union; narrow via `switch (message.type)`. */
|
|
export type RpcMessage = ClientRequest | ServerResponse | ServerRequest | ClientResponse
|
|
|
|
/**
|
|
* Carrier receipt (not an RpcMessage — it belongs to the carrier layer, same
|
|
* discipline as "HTTP status describes only the carrier"): the HTTP response
|
|
* body of the POST carrying a client-response. Late/duplicate responses yield not-pending.
|
|
*/
|
|
export type RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }
|