[WIP] Node SDK canvas launch admission and retention - #2637

Summary

WIP Node SDK follow-up for hosts embedding canvas extensions:

• Attach a typed, connection-owned extensionLaunchProvider before the RPC handshake; require an explicit { contractVersion: 1 } before create/resume. Unsupported negotiation fails closed, while omitting the option preserves legacy behavior.
• Expose canonical client.rpc.session.retain({ sessionId }) and session.rpc.retain() with exact null acknowledgements and the session.retained event. Global retention works while create is pending, without manufacturing a conversation turn.
• Forward public enableScriptSafety in the initial create/resume request, before newly initialized extension work.
• Make cancellation teardown idempotent before registration and safe under overlapping wire/connection cancellation. Preserve synchronous resolver entry/error identity and reject late grants or stale acknowledgements.

Includes generated Node bindings, public exports, focused loopback regressions, and experimental API documentation. No dependency or CLI-pin changes, runtime implementation, release payloads, or private qualification fixtures/logs are included.

Source and release provenance

This is P1, a newly validated source publication candidate, based on dcfbb93859bea38837234a6dd82b64d545f32624 (0.0.0-dev, CLI pin 1.0.84-4). During publication preparation, five files changed from the preserved earlier R2 source: the already-qualified B2 initial-safety forwarding, B3 cancellation helper/tests, and matching README clarification. The helper and focused test file exactly match the qualified B3 source. The generated sources and generator were not changed during preparation.

This is not the separate @github/copilot-sdk@1.0.13 + B3 backport adopted by the VS Code integration. That backport starts at f13e4a2cc7e4e220974d2333142234e162a3252e, retains CLI pin 1.0.83, and has its own complete-image payload and qualification history. Its frozen bytes and native receipts are unchanged; those receipts are not relabeled as executions of this PR.

The checked-in generated changes were produced with the existing Node generator from verified CLI 1.0.84-4 schemas plus the reviewed canonical launch-v1/retain contract fragments and retained event. Using the complete older runtime schema would remove unrelated newer SDK APIs, so it was not substituted wholesale. enableScriptSafety uses the existing canonical SessionOpenOptions type.

Merge/release prerequisite: the matching runtime contracts must be reviewed/released, followed by an appropriate CLI pin and ordinary regeneration. The current pin does not supply all these additions. Running the standard pinned-release generator today will not reproduce them; the repository's codegen consistency check is expected to remain blocked by that prerequisite. This draft does not bypass the check or assert released SDK/runtime availability.

Validation boundary

Fresh on the actual P1 source/build, macOS arm64 with Node 24.18.0:

• 111 targeted Vitest cases across five files; implementation/test typecheck, existing ESM/CJS/declaration build, and focused lint/format/whitespace checks.
• Two strict Node public-package loopback runs, ESM and CommonJS, with 24 grouped cases each against resolved vscode-jsonrpc@8.2.1.
• Coverage includes initial true/false/omitted safety forwarding and early permission handling, pending-create retention, pre-registration failure, repeated stop/forceStop/disconnect, registration after disposal, overlapping cancellation, original errors, and no late-grant reuse.

Prior separately labeled R2 and 1.0.13+B3 evidence includes isolated compatible-runtime counter/SSE, no-turn retention/cold resume/offline domain persistence, and startup-negative cleanup. This publication does not claim a fresh native matrix, all extension sources/platforms/transports, production UI compatibility, or all model-driven resume combinations.

Remaining runtime and policy limits

The required order is source approval, successful retention, then an approved launch recipe. Top-level extension effects can precede joinSession or canvas open; create/resume completion is not canvas-registry readiness.

The compatible runtime keeps a disconnected launch-provider connection authoritative. A replacement on the same running runtime may be refused; the SDK propagates that refusal rather than bypassing ownership. An SDK-owned runtime restart permits fresh negotiation.

enableScriptSafety: true enables read-only shell-command classification under runtime/managed policy, not a security-policy override, blanket tool approval, or extension sandbox. It is not retroactive protection for running work. The setting is in-memory: cold omission defaults to classification disabled, while resident omission preserves the current value. Hosts requiring it must explicitly set true before each create/cold resume.