Add is_alive liveness-probe API across SDKs (decouple liveness from typed ping deserialization)
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 48/100
- Issue type
- Feature
- Clarity
- Clearly specified
- Activity status
- Quiet
- Domain
- api, backend-api-design, documentation
Research direction
Start with the Client ping entry points named in rust/src/lib.rs:1676, nodejs/src/client.ts:1032, go/client.go:1317, dotnet/src/Client.cs:874, and the equivalent Python client, then inspect @github/copilot/schemas/api.schema.json. Run the SDK tests and add coverage for a valid JSON-RPC response whose ping body fails strict deserialization. Done means each Client has the language-appropriate liveness method, existing typed ping APIs remain unchanged, and each SDK documents the distinction.
Written by the indexing model from the issue text.
Description
Summary
The Copilot CLI host (github/github-app) had to work around a deserialization failure in our SDK's typed ping() API on the session-resume / warm-CLI-pool / liveness-probe paths. See github/github-app#5461 for the workaround.
Their fix introduces a ping_cli_compat(&client) helper that drops to the raw client.call("ping", json!({})) so the result body is never deserialized — they only care whether the JSON-RPC round trip succeeded.
We should give them (and everyone doing liveness checks) a first-class primitive instead of forcing them to bypass our typed API.
Root cause
Across all five SDKs, ping() deserializes the response into a typed body:
- Rust:
Client::ping(&self) -> Result<PingResponse, Error>(rust/src/lib.rs:1676) - Node:
client.ping()returning{message, timestamp, protocolVersion?}(nodejs/src/client.ts:1032) - Go:
client.Ping(ctx, msg) (*PingResponse, error)(go/client.go:1317) - .NET:
client.PingAsync(...) : Task<PingResponse>(dotnet/src/Client.cs:874) - Python: equivalent typed return
The authoritative PingResult schema (@github/copilot/schemas/api.schema.json) requires message, timestamp (date-time string), and protocolVersion (integer > 0). The Rust hand-written PingResponse softens this with #[serde(default)] and Option<u32>, but that only helps for missing fields — wrong types (e.g. null timestamp, integer-shape drift) still fail. Same brittleness exists across the other SDKs.
ping is used by hosts as a liveness check (warm-pool reuse, resumed-session aliveness, retrier "is the cached client still alive" probes). These paths straddle CLI version boundaries — a resumed older CLI process can answer with a slightly different ping body shape, and the entire liveness check fails even though the RPC itself succeeded.
This is exactly the wrong failure mode for a health check: the consumer asked "is the CLI reachable?" and we answered "no" because of a body-shape mismatch.
Proposed fix
Add a dedicated liveness-probe API to every SDK Client:
- Sends the
pingJSON-RPC call. - Returns success based solely on JSON-RPC success — never deserializes the result body.
- Composable with caller-supplied timeouts — no baked-in timeout, so each host (startup probe, warm-pool, resume probe, background keepalive) sets its own budget.
ping()and generatedrpc.ping()stay strict and schema-faithful. Callers who actually want the typed data keep getting it; schema drift continues to surface there as a real error.
Per-language names:
| SDK | API |
|---|---|
| Rust | Client::is_alive(&self) -> bool |
| Node | client.isAlive(): Promise<boolean> |
| Python | client.is_alive() -> bool |
| Go | client.IsAlive(ctx context.Context) bool |
| .NET | client.IsAliveAsync(ct) : Task<bool> |
After this lands, the github/github-app workaround helper goes away and call sites become e.g. existing.is_alive().await.
Rejected alternatives
- Loosen
ping()itself. Considered and rejected.ping()is a typed schema-backed API; if it silently swallows malformed bodies, the contract becomes ambiguous (did the caller want liveness, or the ping data?). It also masks real CLI/schema drift in the API most likely to catch it. - Loosen the generated
rpc.ping(PingRequest). Same reasoning, more so — generated APIs must remain schema-faithful.is_aliveis the explicit escape hatch. - "Fix it only in the CLI." The CLI should still honor the schema, and we should investigate any drift. But liveness checks fundamentally straddle version boundaries, so the SDK needs a body-agnostic primitive regardless.
Acceptance criteria
- New
is_alive/IsAlive/isAlivemethod on the Rust, Node, Python, Go, and .NETClienttypes. - Method calls the
pingJSON-RPC method and returns success purely on RPC success, ignoring the response body. - Existing
ping()/rpc.ping()typed APIs unchanged. - Docs in each SDK clearly distinguish "use
is_alivefor liveness/warm-pool/resume checks" from "useping()when you want the typed response." - Tests cover the case where the CLI returns a
pingbody that fails strict deserialization but is otherwise a valid JSON-RPC success —is_alivereturnstrue,ping()returns an error. - Once shipped, the workaround in github/github-app#5461 is removed.
Design review
Reviewed and agreed with GPT-5.5; consensus on:
- Separate
is_aliveAPI (not looseningping). - Keep generated
rpc.pingstrict. - No baked-in timeout; caller composes timeouts.
- Name
is_aliveclearly communicates intent ("RPC round trip succeeded") and beatsping_raw/ping_check.
- Dominant language
- Java
- Stars
- 10.5k
- Forks
- 1.5k
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 130
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github/copilot-sdk
-
agentic-workflows
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
github/copilot-sdk#2760 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
github/copilot-sdk#2759 ·
-
documentation
Difficulty 1/5 Under an hour Newbie friendliness 85/100
github/copilot-sdk#2758 ·
-
agentic-workflows
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
github/copilot-sdk#2709 · 1 comment ·
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
github/copilot-sdk#2673 ·
All issues in github/copilot-sdk
Similar issues
-
awaiting triage bug Causes friction Hop Gui P1 P2 Transforms
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
apache/flink-agents#1152 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
jenkinsci/blueocean-plugin#5417 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
objectionary/eo-graphs#75 ·