feat(extensions)!: normalize extension version and capability negotiation

User Story

As an operator or extension author, I want every supported extension protocol to negotiate version and capabilities consistently, so that incompatible gateway and extension combinations fail clearly instead of silently degrading.

Problem Statement

Compute drivers, credential drivers, gateway interceptors, and supervisor middleware expose different version and capability shapes. Some report a free-form implementation version, some provide service metadata, and some lack protocol-version negotiation. The gateway cannot apply one compatibility policy across extension families.

Impact / Why This Matters

Operators can pair independently deployed components that connect successfully but do not understand required fields or behaviors. Each extension author invents compatibility rules, and clients cannot discover which optional capabilities are supported. Silent degradation is especially risky when a missing capability affects security or resource enforcement.

Proposed Design

Define a common extension handshake model with:

a protocol contract version distinct from the implementation/build version;
a typed or namespaced capability set;
required versus optional capability semantics;
clear rejection and diagnostic behavior for incompatible peers;
a documented gateway/extension version-skew policy; and
capability snapshots available through appropriate operator/client discovery surfaces.

Apply the common semantics to compute drivers, credential drivers, gateway interceptors, and supervisor middleware while allowing extension-specific capability payloads.

Acceptance Criteria

Every supported extension protocol reports protocol version and implementation version separately.
Every protocol can advertise optional capabilities and declare required capabilities.
The gateway rejects an extension missing a required capability with an actionable error.
Unknown optional capabilities are tolerated according to documented forward-compatibility rules.
Supported version skew is documented and covered by mixed-version tests.
Operator-visible gateway information reports negotiated extension versions/capabilities without exposing secrets.
Built-in extensions use the same negotiation path as external extensions.
Extension author documentation and migration notes include the new handshake.

Alternatives Considered

Compare semantic implementation versions in the gateway. This requires a growing feature-to-version table and conflates build identity with protocol support. Let every extension family retain its own mechanism. This preserves current inconsistency and makes a system-wide compatibility policy unenforceable.

Agent Investigation

The current protocols expose different combinations of driver_version, service_version, manifests, and capability fields. Resource-specific compute capabilities are tracked in #2902, while fail-closed gateway/supervisor feature negotiation is tracked in #2949.

Related: #2565, #2902, #2949. Source audit: https://gist.github.com/mrunalp/e80942c1544a0225ee588796a41ab30b.

This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.

🏗️ build-plan

Implementation Plan

Issue type: feat
Complexity: High
Confidence: Medium — integration points are clear; the initial public contract is fixed below for implementation.

Summary

Introduce one bidirectional extension peer-metadata model for protocol version, implementation version, supported capabilities, and peer requirements. Use the same negotiation validator for in-process and external compute drivers, credential drivers, gateway interceptors, and supervisor middleware; reject missing metadata, incompatible protocol majors, or unmet requirements during gateway startup while tolerating unknown optional capabilities.

Retain each family's typed payload beside the common metadata. Snapshot successful negotiations and expose only non-secret version/capability data through elevated gateway information and client-facing representations.

Contract Decisions

Start every family at protocol 1.0; accept same-major minor skew when requirements are satisfied and reject major-version mismatch.
Use lowercase namespaced capability identifiers under openshell.<family>.*.
Keep legacy driver_version and service_version fields populated but deprecated for a wire-compatible migration; do not reuse field tags.
Treat absent peer metadata as incompatible rather than silently assuming protocol v1.

Scope

proto/extension.proto (new): common peer metadata and typed protocol version.
proto/{compute_driver,credential_driver,gateway_interceptor,supervisor_middleware}.proto: carry gateway metadata in startup requests and extension metadata in responses/manifests.
proto/openshell.proto: add generic non-secret negotiated-extension snapshots to GetGatewayInfoResponse, preserving compute resource-capability output from feat(api): advertise portable resource capabilities from compute drivers #2902.
crates/openshell-core: protobuf-aware normalization, identifier validation, compatibility enforcement, and actionable errors.
Compute drivers: negotiate and retain metadata in ComputeRuntime::from_driver; update Docker, Podman, Kubernetes, VM, MXC, and test implementations.
Credential drivers: negotiate and retain metadata for DB credstore, Kubernetes Secrets, Vault, remote UDS, and test implementations.
Gateway interceptors: negotiate during Describe, retain snapshots, and preserve interceptor-specific bindings/provider-profile flags.
Supervisor middleware: pass gateway metadata through Describe, validate built-in and remote manifests through the same helper, and retain snapshots.
Gateway/CLI/SDK surfaces: aggregate a sorted, redacted snapshot for all four families and update client representations and generated bindings as required.
Documentation: extension-author handshake and migration guidance plus the existing extension, gateway, compute, and architecture references.

Implementation Steps

Define common {major, minor} versions, implementation identity/version, supported capabilities, and required peer capabilities.
Implement and unit-test normalization and negotiation: reject missing metadata, major mismatch, unmet requirements, malformed/duplicate/oversized names; accept same-major minor skew and unknown optional capabilities.
Integrate compute negotiation for in-process and UDS drivers without changing feat(api): advertise portable resource capabilities from compute drivers #2902's typed ResourceCapabilities payload.
Integrate credential negotiation for built-in and remote drivers; retain rather than discard capability responses.
Integrate gateway-interceptor and supervisor-middleware negotiation at Describe, routing built-ins through the same validation path.
Store immutable startup snapshots and expose a sorted, non-secret list through GetGatewayInfo.
Update CLI/SDK representations, regenerate committed bindings, and document version skew, required/optional semantics, failure behavior, and migration.
Run focused crate and SDK checks, mise run pre-commit, mise run test, and mise run ci.

Test Plan

Unit tests: common negotiation matrix and diagnostics; family startup validation; built-in implementation versions; gateway-info projection; CLI human/JSON rendering; SDK conversion/deep-copy behavior.
Integration tests: compatible external services, missing metadata, incompatible major, unmet requirements, same-major minor skew, and equivalent in-process/external negotiation for each family.
E2E tests: N/A unless e2e/ fixtures change; startup negotiation is covered by loopback/UDS integration tests and does not change sandbox infrastructure behavior.

Risks & Open Questions

New gateways reject pre-handshake extensions, so documentation must state upgrade ordering and the compatibility matrix prominently.
The middleware Describe request becomes typed rather than google.protobuf.Empty; the RPC path is stable, but extension authors must regenerate bindings.
Discovery must not expose endpoints, audiences, tokens, backend configuration, secrets, or untrusted free-form diagnostics.
feat(api): advertise portable resource capabilities from compute drivers #2902 is already implemented by PR feat(compute): advertise resource capabilities #3010; this work leaves compute resource capabilities typed and unchanged.
feat: fail-closed capability negotiation for gateway↔supervisor signals under version skew #2949 remains scoped to gateway↔sandbox-supervisor SSH behavior signals; this work does not change supervisor-session negotiation, SSH env handling, or exec gating.

Documentation Impact

Add common extension negotiation and migration/version-skew guidance.
Update gateway interceptor, supervisor middleware, compute-driver, gateway-info/config, and stable architecture boundaries as applicable.
No gateway TOML key/default or Helm rendering changes.
LSM compatibility: none; no process identity, /proc, binary execution, or inter-process visibility behavior changes.

Revision 1 — initial plan with protocol and capability-namespace decisions

🏗️ build-from-issue-agent

Implementation Complete

PR: #3352

What was built

Added a common protocol-version and capability handshake across compute drivers, credential drivers, gateway interceptors, and supervisor middleware. The gateway now rejects incompatible peers before use and reports immutable, non-secret negotiated snapshots through gateway info and the Go SDK.

Tests

Unit: 9 new Rust negotiation/initialization tests, with existing Rust and Go converter/fake-client tests expanded
Integration: existing workspace integration suites passed; no dedicated integration test files added
E2E: N/A — no files under e2e/ changed
Full verification: mise run pre-commit, mise run go:ci, mise run sdk:ts:ci, OPENSHELL_NO_BROWSER=0 mise run test, and OPENSHELL_NO_BROWSER=0 mise run ci

Docs updated

New extension negotiation contract and migration guide
Compute-driver, gateway-interceptor, supervisor-middleware, and gateway configuration references
Gateway and compute-runtime architecture overviews
Gateway-info and cluster-debugging public skills

The issue will auto-close when the PR is merged.

feat(extensions)!: normalize protocol negotiation

feat(extensions)!: normalize protocol negotiation (NVIDIA#3352)

Navigation Menu

Repository navigation

feat(extensions)!: normalize extension version and capability negotiation #3057

User Story

Problem Statement

Impact / Why This Matters

Proposed Design

Acceptance Criteria

Alternatives Considered

Agent Investigation

Implementation Plan

Summary

Contract Decisions

Scope

Implementation Steps

Test Plan

Risks & Open Questions

Documentation Impact

Implementation Complete

What was built

Tests

Docs updated

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat(extensions)!: normalize extension version and capability negotiation #3057

Description

User Story

Problem Statement

Impact / Why This Matters

Proposed Design

Acceptance Criteria

Alternatives Considered

Agent Investigation

Activity

github-actions commented on Sep 15, 2026

sjenning commented on Sep 15, 2026

Implementation Plan

Summary

Contract Decisions

Scope

Implementation Steps

Test Plan

Risks & Open Questions

Documentation Impact

sjenning commented on Sep 15, 2026

Implementation Complete

What was built

Tests

Docs updated

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions