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

[gokhanarkan]

Context

The canonical Agent Finder MCP protocol and schema are owned by the runtime:

• github/copilot-agent-runtime#13278, candidate and side-effect-free MCP planning APIs
• github/copilot-agent-runtime#13279, confirmed MCP apply and recovery

GitHub Copilot app and other SDK hosts need generated Rust and Node bindings for that contract rather than app-specific RPCs, vendored edits, raw JSON, or direct runtime-specific calls.

Parent coordination epic: github/copilot-ecosystem#1199

Problem

The SDK does not expose generated, versioned Agent Finder operations. Hosts need opaque generated types, typed requests/responses, and transport conformance without redefining runtime handle, cancellation, idempotency, secret-channel, policy, or failure semantics.

Ownership

Runtime owns

• Canonical operation and error schema.
• Runtime-instance handle scope, TTL, expiry, replay and single-use rules.
• Capability and protocol-version negotiation semantics.
• Cancellation boundaries before and after commit.
• Operation-key idempotency and reconciliation.
• Ephemeral secret-channel semantics and typed placeholders.
• ARD parsing, hardened retrieval, card validation, transport resolution, policy, configuration, keychain, reload, compensation, and partial-failure outcomes.

SDK owns

• Generated Rust and Node request, response, handle, capability, and outcome types from the runtime schema.
• Public generated operations for search, plan, apply, cancel, and capability discovery.
• Supported in-process and out-of-process transport plumbing and conformance.
• Generated API lifetime, side-effect, and compatibility documentation.
• Schema/codegen compatibility tests and typed failure mapping.

Scope

• Generate typed Rust and Node APIs from the canonical runtime Agent Finder schema.
• Expose opaque candidate and plan handle types without raw ARD cards or mutable configuration.
• Expose bounded search, side-effect-free plan, confirmed apply, cancel, capability, and typed outcome operations.
• Preserve runtime-defined handle, cancellation, idempotency, capability, and error semantics without duplicating them in hand-authored SDK policy.
• Support equivalent observable behaviour across supported in-process and out-of-process transports.
• Update generated protocol metadata only when required by repository conventions.
• Publish generated lifetime and side-effect documentation for callers.

Non-goals

• Defining or changing the canonical runtime protocol schema.
• Host UI, confirmation copy, keychain implementation, policy, configuration, reload, compensation, or rollback logic.
• Host-specific adapters.
• Automatic installation.
• Non-MCP package/import contracts.
• Raw JSON, any, unvalidated maps, or stringly typed operation and error boundaries.

Acceptance criteria

• Generated Rust and Node clients expose typed search, plan, apply, cancel, capability, and outcome operations from the runtime schema.
• Candidate and plan handles are opaque generated types and carry no raw card, install specification, secret, or mutable configuration data.
• Runtime-defined handle lifetime, cancellation, idempotency, capability, and error semantics are preserved exactly.
• Apply accepts the generated exact-plan, confirmation, operation-key, and typed-value contract defined by the runtime.
• Typed policy, stale, network, offline, secret, configuration, keychain, reload, compensation, partial-failure, and uncertain-state outcomes map without stringly typed codes.
• In-process and out-of-process clients have equivalent observable behaviour for supported operations.
• Generated public boundaries introduce no raw JSON or any escape hatch.
• API lifetime, side effects, cancellation, and compatibility documentation is published with the generated surfaces.

Security and privacy

• Keep raw ARD cards, install specifications, mutable configuration, and secret values outside SDK request/response payloads except for the runtime-defined ephemeral typed-value submission contract.
• Do not add generated logging or telemetry helpers that expose queries, URLs, payloads, handles, configuration, or secret metadata.
• Treat generated handles as opaque bearer capabilities and do not make them serialisable beyond the runtime-defined transport lifetime.

Testing

• Schema and generated-code compatibility tests for Rust and Node.
• In-process and out-of-process conformance tests for every generated operation and typed outcome.
• Generated handle opacity and non-portability tests.
• Transport tests for cancellation before and after commit, operation-key replay, and ambiguous connection loss using runtime-defined expectations.
• Failure-mapping tests for policy, stale, network, offline, secret, configuration, keychain, reload, compensation, partial failure, and uncertain state.
• Tests proving no raw JSON, any, unvalidated map, or stringly typed host boundary is introduced.

Dependencies

• Blocked by canonical planning/schema work: github/copilot-agent-runtime#13278
• Runtime apply implementation: github/copilot-agent-runtime#13279
• Coordination epic: github/copilot-ecosystem#1199

Supporting documentation

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