Expose typed Agent Finder search, plan, and apply APIs in Copilot SDK

[gokhanarkan]

Context

The shared Agent Finder MCP import authority is tracked in github/copilot-ecosystem#1199. GitHub Copilot app and other SDK hosts need a generated contract for that authority rather than app-specific RPCs or vendored edits.

The 2026-07-21 product meeting established search, plan, apply, and cancellation as distinct phases. Hosts receive opaque handles and typed outcomes while the runtime retains ARD parsing, card retrieval, policy, configuration, keychain, reload, and rollback authority.

Problem

The SDK does not expose a generated, versioned Agent Finder import contract. Without one, hosts would need raw JSON, any, stringly typed RPCs, or direct runtime-specific calls, which would duplicate security-sensitive logic and make in-process and out-of-process behaviour diverge.

The app cannot safely edit its vendored SDK surface directly. The API must be defined and released from the SDK source of truth.

Scope

• Add generated typed Rust and Node APIs for Agent Finder search, plan, apply, and cancel operations.
• Define typed request and response models for bounded search, candidate summaries, plan requirements, apply outcomes, cancellation, and capability discovery.
• Represent candidates and plans only through opaque handles. Do not expose raw ARD cards, raw install specifications, secret values, or mutable configuration through the SDK boundary.
• Document capability negotiation, protocol and API versioning, handle lifetime, connection scope, expiry, cancellation, single-use rules, and idempotency.
• Define typed failures for unsupported capability, invalid or stale handle, policy rejection, network and offline state, secret collection, configuration mutation, keychain, reload, rollback, and partial rollback.
• Preserve the runtime as the authority for ARD parsing, hardened retrieval, transport resolution, managed policy, secret-field definitions, configuration, keychain, reload, and rollback.
• Generate the public Rust and Node surfaces and update protocol-version metadata as required by repository conventions.
• Support both in-process and out-of-process transports with equivalent semantics.

Non-goals

• Host-side parsing of ARD or MCP cards.
• Raw JSON, any, unvalidated maps, or stringly typed operation and error boundaries.
• UI components, confirmation copy, keychain implementation, or configuration mutation in the SDK.
• Automatic installation.
• Defining package and install contracts for non-MCP ARD resource kinds.

Acceptance criteria

• Generated Rust and Node clients expose typed search, plan, apply, cancel, capability, and outcome APIs.
• Candidate and plan handles are opaque and documented as connection-scoped, time-bounded, and non-portable.
• Apply idempotency and single-use behaviour are explicit and testable.
• Capability and version negotiation let hosts fail safely when the runtime does not support the contract.
• Policy, stale, network, offline, secret, configuration, keychain, reload, rollback, and partial rollback failures are distinct typed outcomes.
• No generated public boundary exposes raw ARD JSON, raw card data, install specifications, secrets, or stringly typed error codes.
• In-process and out-of-process clients have equivalent observable behaviour.
• API and protocol lifetime documentation is published with the generated surfaces.

Security/Privacy

• Keep queries bounded and results limited to inert typed metadata required for display.
• Keep secrets entirely outside SDK request/response payloads except for a host-controlled ephemeral secret-submission channel defined by the runtime contract.
• Do not include queries, URLs, card payloads, configuration, handles, or secret metadata in generated logging or telemetry helpers.
• Treat handles as bearer capabilities scoped to the originating connection and reject replay or cross-connection use.

Testing

• Generated-code and schema compatibility tests for Rust and Node.
• In-process and out-of-process contract tests for search, plan, apply, cancel, capabilities, version negotiation, and typed outcomes.
• Handle expiry, replay, cross-connection, cancellation, and idempotency tests.
• Failure mapping tests for policy, stale, network, offline, secret, configuration, keychain, reload, rollback, and partial rollback paths.
• Tests proving raw JSON and untyped host boundaries are not introduced.

Dependencies

• Shared backend coordination: github/copilot-ecosystem#1199
• Runtime implementation must define the canonical operation and outcome schema before generated APIs are finalised.

Supporting Documentation

• Agent Finder CLI support epic: github/copilot-ecosystem#1109
• Runtime built-in skill PR: github/copilot-agent-runtime#12575
• Runtime /plugins search PR: github/copilot-agent-runtime#12672