feat(serve): protocol version and capabilities in health

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- `lich serve` `health` also returns `protocol_version` (`1`, bumped only on
+  breaking changes) and `capabilities: { methods, notifications }` (#144).
+  `methods` lists `prompt.*` only when the server has an Agent.
 - `lich serve` queues frames per session on each connection instead of
   per connection (#144). A long `prompt.submit` no longer holds up other
   sessions or session-less frames such as `health` on the same socket. Frames

docs/architecture/serve.md

@@ -42,14 +42,21 @@ method `event` (no `id`).
 
 | Method | Params | Result |
 | --- | --- | --- |
-| `health` | `{}` | `{ status: "ok", version }` (`LICH_VERSION`) |
+| `health` | `{}` | `{ status: "ok", version, protocol_version, capabilities }` |
 | `session.create` | `{ label?, source }` | `{ session_id }` |
 | `session.list` | `{}` | `{ sessions: [{ id, mtime_ms }, ...] }` |
 | `session.clear` | `{ session_id }` | `{ session_id }` |
 | `session.resume` | `{ id, source? }` | `{ session_id, resumed_id, message_count }` |
 | `prompt.submit` | `{ session_id, text }` | reply, usage, `session_path`, `stopped_reason`, … |
 | `prompt.abort` | `{ session_id }` | `{ session_id, aborted }` |
 
+`health` reports `version` (`LICH_VERSION`), `protocol_version`
+(`SERVE_PROTOCOL_VERSION`, currently `1`) and
+`capabilities: { methods, notifications }`. `protocol_version` changes only
+on breaking changes; new features are added to `capabilities`, so clients
+check it before calling a method. `methods` lists `prompt.submit` and
+`prompt.abort` only when the server has an Agent.
+
 `health` and `session.list` have no param fields. Typed clients still send
 `params: {}`, because `ServeRequest` requires `params`. JSON-RPC 2.0 also
 allows omitting `params`; serve handlers accept that omission the same as `{}`.
@@ -113,7 +120,6 @@ same WebSocket that issued `prompt.submit` while the call is still in flight.
 - Origin allowlisting is deferred until Electron’s page origin policy is decided;
   do not assume `file://` / `app://` behavior here.
 - Frame size capped at ~1 MiB (`maxPayload`).
-- `health` returns `{ status: "ok", version }` (`LICH_VERSION` from `src/version.ts`).
 - Frames are queued per session within a connection: frames whose
   `params.session_id` match are handled in arrival order and get in-order
   replies, while other sessions, and frames that name no session (such as

src/index.ts

@@ -63,6 +63,7 @@ export {
   SERVE_METHODS,
   SERVE_NOTIFICATION_EVENT,
   SERVE_ERROR_CODES,
+  SERVE_PROTOCOL_VERSION,
 } from "./serve/protocol.js";
 export type {
   HealthParams,
@@ -78,6 +79,7 @@ export type {
   PromptAbortResult,
   PromptSubmitParams,
   PromptSubmitResult,
+  ServeCapabilities,
   ServeEventNotification,
   ServeEventParams,
   ServeMethod,

src/serve/protocol.ts

@@ -24,6 +24,12 @@ export const SERVE_NOTIFICATION_EVENT = "event" as const;
 
 export type ServeNotificationMethod = typeof SERVE_NOTIFICATION_EVENT;
 
+/**
+ * Wire protocol version reported by `health`. Bumped only on breaking changes;
+ * additive features show up in `capabilities` instead.
+ */
+export const SERVE_PROTOCOL_VERSION = 1;
+
 export type JsonRpcId = string | number;
 
 export interface JsonRpcRequest<M extends string = string, P = unknown> {
@@ -75,7 +81,19 @@ export type HealthParams = Record<string, never>;
 
 export interface HealthResult {
   status: "ok";
+  /** Lich release (`LICH_VERSION`). */
   version: string;
+  /** `SERVE_PROTOCOL_VERSION` of this server. */
+  protocol_version: number;
+  capabilities: ServeCapabilities;
+}
+
+/** What this server answers, so clients can check before calling. */
+export interface ServeCapabilities {
+  /** Methods served; `prompt.*` only when the server has an Agent. */
+  methods: ServeMethod[];
+  /** Server → client notification methods. */
+  notifications: ServeNotificationMethod[];
 }
 
 export interface SessionCreateParams {

src/serve/rpc.ts

@@ -10,7 +10,12 @@ import type {
   JsonRpcSuccess,
   ServeMethod,
 } from "./protocol.js";
-import { SERVE_ERROR_CODES, SERVE_METHODS } from "./protocol.js";
+import {
+  SERVE_ERROR_CODES,
+  SERVE_METHODS,
+  SERVE_NOTIFICATION_EVENT,
+  SERVE_PROTOCOL_VERSION,
+} from "./protocol.js";
 import type { ServeEventNotify, ServePromptService } from "./prompts.js";
 import type { ServeSessionStore } from "./sessions.js";
 
@@ -78,7 +83,17 @@ async function dispatch_method(
     if (params !== undefined && is_empty_params(params) !== true) {
       return error_response(id, SERVE_ERROR_CODES.INVALID_PARAMS, "Invalid params");
     }
-    const result: HealthResult = { status: "ok", version: context.version };
+    const result: HealthResult = {
+      status: "ok",
+      version: context.version,
+      protocol_version: SERVE_PROTOCOL_VERSION,
+      capabilities: {
+        methods: SERVE_METHODS.filter(
+          (name) => context.prompts !== undefined || name.startsWith("prompt.") !== true,
+        ),
+        notifications: [SERVE_NOTIFICATION_EVENT],
+      },
+    };
     return { jsonrpc: "2.0", id: id as JsonRpcId, result };
   }
   if (method === "session.create") {

test/serve_cli.test.ts

@@ -165,7 +165,7 @@ describe("bun src/cli.ts serve boot", () => {
     expect(result).toEqual({
       jsonrpc: "2.0",
       id: 1,
-      result: { status: "ok", version: LICH_VERSION },
+      result: expect.objectContaining({ status: "ok", version: LICH_VERSION, protocol_version: 1 }),
     });
     child.kill("SIGTERM");
     await wait_exit(child);

test/serve_rpc.test.ts

@@ -130,7 +130,7 @@ describe("serve rpc framing", () => {
     expect(null_id.body).toEqual({
       jsonrpc: "2.0",
       id: null,
-      result: { status: "ok", version: "9.9.9" },
+      result: expect.objectContaining({ status: "ok", version: "9.9.9" }),
     });
 
     const null_params = await dispatch(
@@ -140,7 +140,7 @@ describe("serve rpc framing", () => {
     expect(null_params.body).toEqual({
       jsonrpc: "2.0",
       id: 3,
-      result: { status: "ok", version: "9.9.9" },
+      result: expect.objectContaining({ status: "ok", version: "9.9.9" }),
     });
   });
 

test/serve_transport.test.ts

@@ -9,6 +9,8 @@ import path from "node:path";
 import { Writable } from "node:stream";
 import WebSocket from "ws";
 import { LICH_VERSION } from "../src/index.js";
+import type { ServePromptService } from "../src/serve/prompts.js";
+import { SERVE_METHODS, SERVE_PROTOCOL_VERSION, type HealthResult } from "../src/serve/protocol.js";
 import { handle_serve_rpc_message } from "../src/serve/rpc.js";
 import { create_serve_server, type ServeServer } from "../src/serve/server.js";
 import { create_serve_session_store } from "../src/serve/sessions.js";
@@ -91,7 +93,7 @@ afterEach(async () => {
 });
 
 describe("serve rpc health", () => {
-  it("returns status and version for health", async () => {
+  it("returns status, versions and capabilities for health", async () => {
     const sessions = create_serve_session_store(path.join(await make_temp_dir("serve-health"), "s"));
     const raw = await handle_serve_rpc_message(
       JSON.stringify({ jsonrpc: "2.0", id: 1, method: "health", params: {} }),
@@ -100,10 +102,28 @@ describe("serve rpc health", () => {
     expect(JSON.parse(raw ?? "")).toEqual({
       jsonrpc: "2.0",
       id: 1,
-      result: { status: "ok", version: "9.9.9" },
+      result: {
+        status: "ok",
+        version: "9.9.9",
+        protocol_version: SERVE_PROTOCOL_VERSION,
+        capabilities: {
+          methods: ["health", "session.create", "session.list", "session.clear", "session.resume"],
+          notifications: ["event"],
+        },
+      },
     });
   });
 
+  it("lists prompt methods in health only when an agent is configured", async () => {
+    const sessions = create_serve_session_store(path.join(await make_temp_dir("serve-health-agent"), "s"));
+    const raw = await handle_serve_rpc_message(
+      JSON.stringify({ jsonrpc: "2.0", id: 1, method: "health", params: {} }),
+      { version: "9.9.9", sessions, prompts: {} as ServePromptService },
+    );
+    const body = JSON.parse(raw ?? "") as { result: HealthResult };
+    expect(body.result.capabilities.methods).toEqual([...SERVE_METHODS]);
+  });
+
   it("returns agent-not-configured for prompt.submit without an agent", async () => {
     const sessions = create_serve_session_store(path.join(await make_temp_dir("serve-stub"), "s"));
     const raw = await handle_serve_rpc_message(
@@ -146,7 +166,7 @@ describe("serve websocket transport", () => {
     expect(result).toEqual({
       jsonrpc: "2.0",
       id: 1,
-      result: { status: "ok", version: LICH_VERSION },
+      result: expect.objectContaining({ status: "ok", version: LICH_VERSION }),
     });
   });