Skip to content

Add private app extension APIs - #2574

Draft
merlynomsft wants to merge 15 commits into
mainfrom
merlynomsft-app-badge-extension-api
Draft

Add private app extension APIs#2574
merlynomsft wants to merge 15 commits into
mainfrom
merlynomsft-app-badge-extension-api

Conversation

@merlynomsft

@merlynomsft merlynomsft commented Sep 8, 2026 •
edited
Loading

Copy link
Copy Markdown

Summary

  • Add the private @github/copilot-sdk/private/app-extension entry point and defineAppExtension(async host => disposer) activation model.
  • Add typed Node and Rust identities, capability grants, contribution declarations, lifecycle cancellation, and generated private handshake contracts.
  • Expose frozen, capability-limited hosts for session presentations, app canvases, forge providers, and mediated fetch without exposing the backing CopilotSession, CopilotClient, raw JSON-RPC, credentials, generic session mutation, or unrestricted fetch.
  • Add atomic Create PR presentation/action support and optional requiredTool routing for product-session prompts.
  • Keep joinAppSessionBadges() and legacy setBadge/setBadges APIs exported as compatibility adapters; legacy badge updates preserve the current action.

Private API shape

  • host.sessionBadges.register({ contributionId, onAction? }) receives revisioned target snapshots and publishes singular or atomic ordered presentation updates.
  • AppSessionPresentation combines badge with an optional Create PR action state; setPresentation and setPresentations replace both atomically.
  • onAction receives the exact eligible snapshot target, kind: "createPullRequest", the requested draft mode, and an AbortSignal; it returns { prompt, requiredTool } or null.
  • host.canvases.register(...) supports bounded generic action descriptors and typed open/action/close callbacks for a declared contribution.
  • host.forgeProviders.register(...) exposes named provider operations for a declared contribution.
  • host.mediatedFetch.request(...) requests a host-authorized operation without receiving account credentials.
  • session.send({ prompt, requiredTool? }) forwards an optional required tool in Node and Rust.

Lifecycle and security boundaries

  • extensions.appExtension.register({ protocolVersion: 1 }) returns runtime-derived principal, capability grants, and declared contribution identities; the SDK sends no spoofable identity.
  • Registrations are contribution-scoped, race-safe, and cleaned up exactly once on explicit disposal, transport closure, or cancellation.
  • Action prompts are limited to 32 KiB and must begin with the exact # Pull Request Creation header; required tool identifiers are strictly validated.
  • The SDK exposes no generic app-host session send API. Runtime validates that requiredTool belongs to an active same-package product-session extension.
  • Presentation lifecycle resets are represented by an authenticated event with presentation: null.

Dependencies and landing order

  1. This PR — SDK contracts and private host API.
  2. github/copilot-agent-runtime#19512 — trusted private bootstrap and transport.
  3. github/github-app#14999 — app host and contribution consumers.

Validation

  • Node typecheck and build.
  • 45 focused Node unit/codegen/child-stdio transport tests.
  • ESLint on all changed Node source and test files.
  • Rust Clippy with all features and targets and warnings denied.
  • Focused Rust app-extension, presentation-event, and requiredTool transport tests.
  • Deterministic TypeScript/Rust codegen reruns.
  • The full Rust non-E2E suites passed. Full Rust E2E startup was blocked by the configured package registry lacking the locked fast-uri@3.1.7 harness dependency; affected transport coverage is green.

merlynomsft and others added 5 commits September 5, 2026 13:53
@merlynomsft
feat: add app session badge extension APIs
a33bc9b 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@merlynomsft
test: cover extension badge snapshot transport
2f7be85 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@merlynomsft
fix(node): preserve badge notification transport
a80b1cd 
Reject malformed app-session badge snapshots without allowing notification handler errors to disconnect the extension transport. Expand the real stdio regression to cover malformed casing, large coalesced frames, and fragmented frames.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@merlynomsft
feat(node): batch app session badges
7f1cdf3 
Add an atomic setBadges extension API with ordered canonical wire updates, complete preflight validation, duplicate-target rejection, and singular API compatibility.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@merlynomsft
Merge remote-tracking branch 'origin/main' into merlynomsft-app-badge…
66a16fb 
…-extension-api
@github-actions github-actions Bot mentioned this pull request Sep 8, 2026
Open
@merlynomsft
Add private app extension handshake schema
9d0595b 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@merlynomsft
Add private app extension host lifecycle
95e1726 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@merlynomsft
Add private Rust app extension identities
e81eefc 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@merlynomsft merlynomsft changed the title Add app session badge extension APIs Add private app extension APIs Sep 8, 2026
@github-actions

This comment has been minimized.

Sign in to view
@merlynomsft
Use runtime-authenticated contribution identities
381d701 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@github-actions

This comment has been minimized.

Sign in to view
@merlynomsft
Separate mediated fetch capability from contributions
d7cd388 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@github-actions

This comment has been minimized.

Sign in to view
@merlynomsft
Add app extension package allowlist config
72f2f3c 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@github-actions

This comment has been minimized.

Sign in to view
@merlynomsft
Add private app extension provider APIs
ffe8530 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@merlynomsft
Propagate app extension callback cancellation
28ea8bb 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@github-actions

This comment has been minimized.

Sign in to view
@merlynomsft
Add app extension pull request actions
a5bcf83 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@github-actions

This comment has been minimized.

Sign in to view
@merlynomsft
Match locked Node formatting
05b04fb 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b70aed5b-8c00-44fe-9312-c67ff0084b51
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

SDK Consistency Review — PR #2574

No cross-SDK consistency issues found.

This PR adds a private/internal app-extension API surface:

  • @github/copilot-sdk/private/app-extension entry point, defineAppExtension(), joinAppSessionBadges(), canvas/forge-provider registration, and mediated fetch.
  • Implemented consistently in both Node.js and Rust (new files: nodejs/src/appExtension.ts, nodejs/src/appSessionBadges.ts, nodejs/src/extensionSession.ts; rust/src/app_extension.rs, rust/src/app_session_badges.rs), plus shared codegen (scripts/codegen/app-extension-api.schema.json, rust.ts, typescript.ts).

Why this doesn't need Python/Go/.NET/Java parity right now:

  • The wire schema explicitly marks all new types "visibility": "internal", and the Node/Rust code is annotated @internal / #[doc(hidden)].
  • The PR description states this is a private handshake consumed only by GitHub's own app host (github/github-app) and CLI runtime (github/copilot-agent-runtime), not a general public feature for third-party SDK consumers.
  • The two languages implemented (Node.js, Rust) match the languages actually required by the dependent integration PRs listed in the "Dependencies and landing order" section.

API naming/shape is parallel between the two implemented languages (joinAppSessionBadges/AppSessionBadgesExtension in TS vs. app_session_badges/equivalent types in Rust), following each language's idioms. No action needed for the remaining SDKs unless/until this private surface is promoted to a public, cross-language feature.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot will automatically review once the pull request is marked ready for review

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@merlynomsft