Node SDK transport for native AHP endpoints

[SteveSandersonMS]

Summary

Add a transport-neutral Node SDK API for native runtime AHP endpoints. Applications own their listener and forward opaque AHP messages; the SDK does not implement an AHP agent mapping.

• Endpoint registration, independent logical connections, bounded output delivery and idempotent disposal.
• Executable create/resume callbacks and endpoint-local exposure policy, supporting reentrant ordinary SDK calls and explicit error/cancellation handling.
• Unsupported-runtime errors, generated RPC contracts, reference documentation and runnable WebSocket server/client examples.

Runtime companion: https://github.com/github/copilot-agent-runtime/pull/21650. Runtime support must land before releasing this SDK API.

Runtime integration and scope

The companion brings copilotd's AHP 0.9 host and agent mapping into the runtime and connects it to existing native sessions. CLI sharing and standalone --ahp-host use that common implementation in place of the separate hosting implementations on runtime main.

The imported subset supports client-contributed tools/plugins and the AHP MCP OAuth bridge. Remote terminal/PTY services, filesystem services/watches, copilotd Mission Control mirroring and project/worktree provisioning are not included. Ordinary runtime tools and the CLI's existing Mission Control integration remain available.

Applications supply the public listener and session-policy callbacks. The runtime owns AHP state and bounded output serialization; the SDK API handles the application's endpoint connection and delivery lifecycle. No runtime-owned public listener, internal SDK client or additional runtime process is introduced.

The CLI uses the same raw ahp.* SDK protocol over an in-process connection, without importing this Node SDK package.

Coverage and examples

Add endpoint coverage for registration, opaque message forwarding, output delivery, callbacks, reentrant SDK operations, exposure restrictions, cancellation and disposal, including clear failures against unsupported runtimes.

The checked-in sample demonstrates creating and resuming sessions with an application-owned WebSocket listener and a standard AHP client. It exercises an SDK-provided tool callback, session configuration, excluded-session access and listener shutdown.

Rollout

AHP 0.9 only; this is not full copilotd parity. Both PRs remain drafts. The SDK API depends on the runtime companion and must not be released ahead of it.

[github-actions]

SDK Consistency Review — PR #2721

This PR touches only the Node.js/TypeScript SDK (nodejs/). No files in python/, go/, dotnet/, java/, or rust/ are modified.

Summary of changes

1. New createAhpEndpoint() API (nodejs/src/ahp.ts, client.ts, generated/rpc.ts) — registers a native AHP 0.9 endpoint on the existing runtime connection, letting an application multiplex an AHP-speaking transport (e.g. WebSocket) over the SDK's session management. New example files, docs (docs/ahp-endpoints.md), and tests (test/ahp.test.ts) are Node-only.
2. New SessionConfig.name option (nodejs/src/types.ts, client.ts) — an optional friendly name that opts a session into persistence before its first turn, forwarded as name in the session.create request payload.

Cross-SDK findings

1. createAhpEndpoint (experimental, explicitly Node-only by design)
The docs frame this as an experimental Node.js-owned-transport feature, and the generated RPC methods (ahp.registerEndpoint, ahp.openConnection, etc.) are marked @internal/@experimental. Given the experimental scope and that it depends on a bespoke local runtime build, this looks like an intentional, contained Node-only preview rather than an oversight — flagging for awareness only, no action expected unless the team plans wider rollout.

2. SessionConfig.name — likely a parity gap
This is a small, general-purpose addition to session creation config (not AHP-specific) and is exactly the kind of feature that's expected to be mirrored across SDKs per this repo's conventions. Checked all other SDKs' SessionConfig/create_session equivalents:

• Python create_session(...) — no name parameter (python/copilot/client.py)
• Go SessionConfig / createSessionRequest — no Name field (go/types.go)
• .NET SessionConfig — no Name property (dotnet/src/Types.cs)
• Java SessionConfig — no name field (java/sdk/src/main/java/com/github/copilot/rpc/SessionConfig.java)
• Rust SessionConfig — no name field (rust/src/types.rs)

Since name is a simple wire-forwarded string with no Node-specific mechanics, consider adding the equivalent option (name: str | None in Python, Name string in Go, Name property in .NET, name field in Java, name: Option<String> in Rust) to keep session-creation config in parity across SDKs, unless this is intentionally staged as Node-first with follow-up PRs planned for the rest.

Otherwise the PR is well-contained and doesn't introduce any inconsistent behavior versus existing shared APIs.

Generated by SDK Consistency Review Agent for #2721 · copilot · sonnet50 · 79.8 AIC · ⌖ 12.3 AIC · ⊞ 8.3K · ◷