SDK: Surface structured Policy Helper failures

[carlorivera]

Problem

Policy Helper failures currently reach SDK consumers only through generic managed-settings state or process diagnostics. Clients cannot reliably show the helper's actionable explanation, identify fail-closed restrictions, perform a fresh scoped recovery check, or retain helper context when session creation, resume, or policy-dependent activation fails.

This SDK change depends on the additive runtime contract in github/copilot-agent-runtime#26937. The projections and APIs in this pull request require a runtime implementing that contract; older runtimes remain compatible by omitting the optional fields and method capability.

Changes

• Adds generated Node and Rust PolicyHelperFailure, PolicyHelperFailureDetail, PolicyHelperHelpLink, and PolicyHelperCapabilities projections.
• Adds optional policyHelperFailure and policyHelperCapabilities fields to ManagedSettingsResolvedData.
• Preserves forward compatibility by exposing category, failureMode, severity, reason, and optional authority as strings; helper-defined code also remains arbitrary bounded text.
• Preserves structured error.data.policyHelperFailure on session.create, session.resume, and policy-dependent activation failures without replacing the primary JSON-RPC code or message.
• Adds session.managedSettings.recheckPolicyHelper, returning the authoritative ManagedSettingsResolvedData snapshot after a fresh evaluation for the current session policy context.
• Adds explicit structuredFailure and recheck capabilities. Capability presence is authoritative; absence of policyHelperFailure alone does not establish support or recovery.
• Adds policyHelperReason: "pluginActivation" to sessionless managedSettings.resolve calls for policy-dependent activation.
• Documents capability checks, scoped recheck behavior, untrusted helper-authored content, and Rust rpc_data() extraction.

The DTO contains:

• category, failureMode, severity, and reason
• optional authority
• previousPolicyRetained
• optional helper code
• message
• optional remediation
• optional helpLink { url, label? }
• optional details[] { path?, message }
• optional diagnostic

Schema provenance

Authoritative runtime revision: a617cebec90a3566e39cdcfbb20daea1efc98d61
Runtime implementation commit: b7b80ebc085
SDK protocol version: 3

• generated/api.schema.json: ab10e6fd502ef59fcf3403ce62b8588def4613c41c311c6573ab5d0aee990938
• generated/session-events.schema.json: 8a307582a38de7a015b4bac1dca2fa16045930405789775d3d6c418c10d41a3a

The runtime checkout's SDK baseline is newer than this repository's pinned CLI 1.0.99-0. To avoid unrelated projection drift, this branch applied the exact conflict-free b7b80ebc085^..b7b80ebc085 JSON-schema delta to the pinned schemas, then regenerated Node and Rust with this repository's generators. The delta contained 10 API-schema operations and 6 session-event-schema operations, limited to the Policy Helper definitions, snapshot/result fields, resolve request, and scoped recheck RPC. Regeneration was idempotent; the generated projection diff SHA-256 was 40c3107cdfd8f30bc131c554094b3bb98d62c3f78ded9b09d69e733955dc89b3.

The completed handwritten SDK tests and documentation were reconciled back into the runtime repository in commit e34645fb5f02ae67faef6bdb63f372d22f6216e9; the runtime kept its newer generated projections authoritative.

Validation

• Node Policy Helper contract tests: 4 passed.
• Node create/resume structured RPC error-data tests: 2 passed, 238 filtered.
• npm run check:nodejs: passed formatting, ESLint, and type checking; ESLint reported 7 pre-existing warnings in unrelated tests and 0 errors.
• SDK codegen run: 443 passed, 5 expected failures, with one standalone-layout-only failure because nodejs/test/rust-codegen.test.ts expects the nested runtime path ../../../../generated/api.schema.json.
• The Rust codegen suite rerun excluding only that nested-layout case: 79 passed, 1 skipped.
• Rust focused prepared-session error tests: 2 passed.
• Rust focused Policy Helper session tests: 3 passed.
• Rust formatting and Clippy with the repository deny flags: passed.
• Full Rust non-E2E suites: 464 passed, 0 failed.
• Rust replay E2E binary: 40 passed, 235 failed, 5 ignored because the shared test/harness dependencies were unavailable (tsx missing). Installing the unchanged harness lockfile was environment-blocked: the configured package feed lacks locked ip-address@10.7.4, and public npm access returned ENOTCONN.
• git diff --check: passed.

Product impact

Node and Rust SDK clients can render actionable bounded Policy Helper failures, distinguish warning and fail-closed states, explain retained previous policy, preserve failure context on failed operations, and request an explicitly capability-gated fresh scoped recheck. Existing clients and older runtimes remain compatible with the additive optional contract.