Expose runtime-supervised AHP hosts through the Node SDK

[SteveSandersonMS]

Summary

Adds experimental Node and Rust APIs for a runtime-supervised AHP host. The existing runtime launches copilotd-lite, reusing copilotd's complete AHP server with a separate SDK participant—not a second runtime.

The requesting SDK connection owns the host. Disposal, owner disconnect, and runtime shutdown close the listener and reap the child without deleting sessions. Handles expose the host ID, URL, PID, optional token, and explicit async disposal; optional exit callbacks run at most once.

Usage

Node

import { CopilotClient } from "@github/copilot-sdk";

await using client = new CopilotClient();
await client.start();
const host = await client.startAhpHost({
    onExit: (exit) => console.log(exit.reason),
});

// Connect an AHP client using host.url and host.token; do not log the token.
// Keep client alive while hosting. Client disposal also stops the host.
// To stop hosting earlier: await host.dispose();

Rust

use github_copilot_sdk::{AhpHostOptions, Client, ClientOptions};

let client = Client::start(ClientOptions::default()).await?;
let host = client.start_ahp_host(
    AhpHostOptions::new().with_on_exit(|exit| println!("{:?}", exit.reason)),
).await?;

// Connect an AHP client using host.url and host.token.as_deref().
// Keep client alive while hosting; dropping the handle does not stop it.
// To stop hosting earlier: host.dispose().await?;
client.stop().await?;

Listener options: hostname, port, token, and requireConnectionToken (Rust: matching with_* builders). Defaults are 127.0.0.1, an OS-allocated port, and a generated required token. Explicit non-loopback binding is supported. Disabling connection-token auth returns no token and cannot be combined with a supplied token; separate AHP resource authentication remains intact. No per-host working-directory override.

Validation

• Node 8/8 and Rust 9/9 real-AHP E2Es pass against both local source builds and the same assembled candidate, sharing existing inference snapshots.
• Packaged live-inference smoke passes: AHP streaming, SDK coexistence, and listener/child cleanup.
• Focused API, generated-binding, type, and lint checks pass.

Dependencies and scope

Companion drafts: host #1292, runtime #22049. Requires their runtime/host artifacts; release publication, acquisition credentials, version pins, platform jobs, and AHP CI activation follow separately. Local validation is Linux x64, not signed cross-platform release evidence.

Application create/resume callbacks and projection migration are out of scope. Lite's GHES shell-credential support is deferred to runtime #22077; traditional copilotd is unchanged.

Draft—do not merge.

[github-actions]

Cross-SDK Consistency Review

This PR (draft, "do not merge") adds the experimental runtime-supervised AHP host feature. I compared the Node.js and Rust implementations against Go, .NET, Python, and Java.

Findings

Scope matches the stated intent — no action needed.

• The PR description explicitly scopes this to Node and Rust only ("Adds experimental Node and Rust APIs for a runtime-supervised AHP host"), and both implement the feature consistently:

  • client.startAhpHost(options) (Node) / client.start_ahp_host(options) (Rust) — parallel naming per language convention (camelCase vs snake_case).
  • Both expose hostname, port, token, requireConnectionToken/require_connection_token, and an optional exit callback (onExit / on_exit) fired at most once, with the same ownerDisconnected semantics on connection loss.
  • Both return a small handle (AhpHost) exposing hostId/host_id, url, pid, token, and an explicit async dispose().
  • Disconnection/cleanup handling (disconnectHosts() in Node, the dispatcher's owner-disconnect branch in Rust) is functionally equivalent.

• Go, .NET, and Python only receive regenerated low-level RPC types (HostStartRequest, HostDisposeRequest, HostExitedNotification, ServerHostApi/Rpc.Host, etc.) as a side effect of the shared codegen scripts — there is no high-level convenience wrapper (StartAhpHost, start_ahp_host) added for these languages yet, and none for Java (no Java files touched by this PR at all).

• This asymmetry is called out by the author in "Dependencies and scope" as intentional for this draft, with follow-up work (release pins, CI activation) gating a broader rollout.

Suggestion (non-blocking, for follow-up)

When this experimental API is promoted beyond Node/Rust, consider tracking parity work for Go, .NET, Python, and Java convenience wrappers (StartAhpHost/start_ahp_host/startAhpHost) mirroring the same option set and exit-callback semantics, so the low-level bindings already generated here don't stay unused in those SDKs.

No inline comments added — the current PR is internally consistent with its declared Node+Rust-only scope.

Generated by SDK Consistency Review Agent for #2738 · copilot · sonnet50 · 56.9 AIC · ⌖ 11.6 AIC · ⊞ 7.8K · ◷

[SteveSandersonMS]

Superseded by https://github.com/github/copilot-agent-runtime/pull/22049 after the SDK sources moved into that repository. All changes through 0fce9d4, including Node/Rust AHP handles and Rust owner-disconnect callback parity, are preserved under src/sdk in runtime commit 6e1d3112; final runtime PR head is 52cdb800. Monorepo path/provenance adaptations are included. Node 8/8 and Rust 9/9 real-AHP E2Es pass against both source and assembled candidate artifacts. Closing this PR without merging; the combined runtime PR remains a draft.