From 009fa08b11dea4704efaf8d2d35f59fae3a66d62 Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Tue, 17 Nov 2026 15:32:36 +0000 Subject: [PATCH 1/8] Send X-Databricks-Skills-Invoked from --skills-invoked / DATABRICKS_SKILLS_INVOKED Agent skills that drive a CLI call can list themselves in the DATABRICKS_SKILLS_INVOKED environment variable (or a hidden --skills-invoked flag, which wins). The CLI normalizes the list and sends it as X-Databricks-Skills-Invoked on Databricks API requests. Invalid entries are dropped silently, with debug logging only. The value is resolved once in the root PersistentPreRunE and stored in the command context. Every SDK config site applies a header hook that chains any existing hook, so liteswap keeps working. The files client gets the header through a wrapping transport. Co-authored-by: Isaac --- acceptance/cmd/skills-invoked/databricks.yml | 2 + acceptance/cmd/skills-invoked/out.test.toml | 1 + acceptance/cmd/skills-invoked/output.txt | 125 +++++++++++++++++++ acceptance/cmd/skills-invoked/script | 35 ++++++ acceptance/cmd/skills-invoked/test.toml | 7 ++ bundle/config/workspace.go | 2 + cmd/api/api.go | 2 + cmd/root/auth.go | 11 +- cmd/root/root.go | 2 + cmd/root/skills_invoked.go | 30 +++++ cmd/root/skills_invoked_test.go | 39 ++++++ libs/filer/files_client.go | 4 + libs/liteswap/liteswap.go | 13 +- libs/liteswap/liteswap_test.go | 44 +++++++ libs/skillsinvoked/skills.go | 105 ++++++++++++++++ libs/skillsinvoked/skills_test.go | 123 ++++++++++++++++++ 16 files changed, 542 insertions(+), 3 deletions(-) create mode 100644 acceptance/cmd/skills-invoked/databricks.yml create mode 100644 acceptance/cmd/skills-invoked/out.test.toml create mode 100644 acceptance/cmd/skills-invoked/output.txt create mode 100644 acceptance/cmd/skills-invoked/script create mode 100644 acceptance/cmd/skills-invoked/test.toml create mode 100644 cmd/root/skills_invoked.go create mode 100644 cmd/root/skills_invoked_test.go create mode 100644 libs/liteswap/liteswap_test.go create mode 100644 libs/skillsinvoked/skills.go create mode 100644 libs/skillsinvoked/skills_test.go diff --git a/acceptance/cmd/skills-invoked/databricks.yml b/acceptance/cmd/skills-invoked/databricks.yml new file mode 100644 index 00000000000..a89cdadb769 --- /dev/null +++ b/acceptance/cmd/skills-invoked/databricks.yml @@ -0,0 +1,2 @@ +bundle: + name: skills-invoked diff --git a/acceptance/cmd/skills-invoked/out.test.toml b/acceptance/cmd/skills-invoked/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/skills-invoked/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/skills-invoked/output.txt b/acceptance/cmd/skills-invoked/output.txt new file mode 100644 index 00000000000..b4af00b90f4 --- /dev/null +++ b/acceptance/cmd/skills-invoked/output.txt @@ -0,0 +1,125 @@ + +=== Env var sends the header on a workspace GET + +>>> [CLI] current-user me + +>>> print_requests.py --get //scim/v2/Me +{ + "headers": { + "X-Databricks-Skills-Invoked": [ + "databricks-core,databricks:databricks-jobs" + ] + }, + "method": "GET", + "path": "/api/2.0/preview/scim/v2/Me" +} + +=== Env var sends the header on a bundle-free GET + +>>> [CLI] clusters list + +>>> print_requests.py --get //clusters/list +{ + "headers": { + "X-Databricks-Skills-Invoked": [ + "databricks-core" + ] + }, + "method": "GET", + "path": "/api/2.1/clusters/list" +} + +=== Env var sends the header on databricks api + +>>> [CLI] api get /api/2.0/clusters/list + +>>> print_requests.py --get //clusters/list +{ + "headers": { + "X-Databricks-Skills-Invoked": [ + "databricks-core" + ] + }, + "method": "GET", + "path": "/api/2.0/clusters/list" +} + +=== Env var sends the header on the files API used by fs + +>>> [CLI] fs mkdir dbfs:/Volumes/main/default/vol + +>>> [CLI] fs ls dbfs:/Volumes/main/default/vol + +>>> print_requests.py --get //fs/directories +{ + "method": "PUT", + "path": "/api/2.0/fs/directories/Volumes/main/default/vol" +} +{ + "headers": { + "X-Databricks-Skills-Invoked": [ + "databricks-core" + ] + }, + "method": "GET", + "path": "/api/2.0/fs/directories/Volumes/main/default/vol" +} + +=== Env var sends the header from bundle commands + +>>> [CLI] bundle validate + +>>> print_requests.py --get //scim/v2/Me +{ + "headers": { + "X-Databricks-Skills-Invoked": [ + "databricks-core" + ] + }, + "method": "GET", + "path": "/api/2.0/preview/scim/v2/Me" +} + +=== Flag wins over env var + +>>> [CLI] current-user me --skills-invoked from-flag + +>>> print_requests.py --get //scim/v2/Me +{ + "headers": { + "X-Databricks-Skills-Invoked": [ + "from-flag" + ] + }, + "method": "GET", + "path": "/api/2.0/preview/scim/v2/Me" +} + +=== Invalid entries are dropped and the rest is normalized + +>>> [CLI] current-user me + +>>> print_requests.py --get //scim/v2/Me +{ + "headers": { + "X-Databricks-Skills-Invoked": [ + "databricks-core,databricks:databricks-jobs" + ] + }, + "method": "GET", + "path": "/api/2.0/preview/scim/v2/Me" +} + +=== No header when unset + +>>> [CLI] current-user me + +>>> print_requests.py --get //scim/v2/Me +{ + "method": "GET", + "path": "/api/2.0/preview/scim/v2/Me" +} + +=== Flag is hidden from help + +>>> [CLI] --help diff --git a/acceptance/cmd/skills-invoked/script b/acceptance/cmd/skills-invoked/script new file mode 100644 index 00000000000..d98debf7894 --- /dev/null +++ b/acceptance/cmd/skills-invoked/script @@ -0,0 +1,35 @@ +title "Env var sends the header on a workspace GET" +DATABRICKS_SKILLS_INVOKED=databricks-core,databricks:databricks-jobs trace $CLI current-user me > /dev/null +trace print_requests.py --get //scim/v2/Me + +title "Env var sends the header on a bundle-free GET" +DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI clusters list > /dev/null +trace print_requests.py --get //clusters/list + +title "Env var sends the header on databricks api" +DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI api get /api/2.0/clusters/list > /dev/null +trace print_requests.py --get //clusters/list + +title "Env var sends the header on the files API used by fs" +trace $CLI fs mkdir dbfs:/Volumes/main/default/vol +DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI fs ls dbfs:/Volumes/main/default/vol > /dev/null +trace print_requests.py --get //fs/directories + +title "Env var sends the header from bundle commands" +DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI bundle validate > /dev/null +trace print_requests.py --get //scim/v2/Me + +title "Flag wins over env var" +DATABRICKS_SKILLS_INVOKED=from-env trace $CLI current-user me --skills-invoked from-flag > /dev/null +trace print_requests.py --get //scim/v2/Me + +title "Invalid entries are dropped and the rest is normalized" +DATABRICKS_SKILLS_INVOKED=' Databricks-Core , bad name!,,databricks-core,databricks:databricks-jobs ' trace $CLI current-user me > /dev/null +trace print_requests.py --get //scim/v2/Me + +title "No header when unset" +trace $CLI current-user me > /dev/null +trace print_requests.py --get //scim/v2/Me | contains.py "!X-Databricks-Skills-Invoked" + +title "Flag is hidden from help" +trace $CLI --help | contains.py "!skills-invoked" > /dev/null diff --git a/acceptance/cmd/skills-invoked/test.toml b/acceptance/cmd/skills-invoked/test.toml new file mode 100644 index 00000000000..df326944a2b --- /dev/null +++ b/acceptance/cmd/skills-invoked/test.toml @@ -0,0 +1,7 @@ +RecordRequests = true +IncludeRequestHeaders = ["X-Databricks-Skills-Invoked"] +Ignore = [".databricks"] + +[[Server]] +Pattern = "GET /api/2.0/clusters/list" +Response.Body = '{}' diff --git a/bundle/config/workspace.go b/bundle/config/workspace.go index bed0d0bf69d..9636cdd3ce5 100644 --- a/bundle/config/workspace.go +++ b/bundle/config/workspace.go @@ -8,6 +8,7 @@ import ( "github.com/databricks/cli/libs/auth" "github.com/databricks/cli/libs/databrickscfg" "github.com/databricks/cli/libs/liteswap" + "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/databricks-sdk-go/marshal" @@ -173,6 +174,7 @@ func (w *Workspace) Config(ctx context.Context) *config.Config { WorkspaceID: w.WorkspaceID, } liteswap.Apply(ctx, cfg) + skillsinvoked.Apply(cfg) for k := range config.ConfigAttributes { attr := &config.ConfigAttributes[k] diff --git a/cmd/api/api.go b/cmd/api/api.go index 2caf2ccb95d..61df220d3c3 100644 --- a/cmd/api/api.go +++ b/cmd/api/api.go @@ -18,6 +18,7 @@ import ( "github.com/databricks/cli/libs/databrickscfg/profile" "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/flags" + "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go/client" "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" @@ -105,6 +106,7 @@ func makeCommand(method string) *cobra.Command { // Skips the default profile when DATABRICKS_HOST is set (#5616). root.ResolveDefaultProfile(cmd.Context(), cfg) + skillsinvoked.Apply(cfg) api, err := client.New(cfg) if err != nil { return err diff --git a/cmd/root/auth.go b/cmd/root/auth.go index d7eae4ec0f1..3fe68aa3709 100644 --- a/cmd/root/auth.go +++ b/cmd/root/auth.go @@ -15,6 +15,7 @@ import ( "github.com/databricks/cli/libs/liteswap" "github.com/databricks/cli/libs/log" "github.com/databricks/cli/libs/logdiag" + "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" @@ -174,7 +175,9 @@ func accountClientOrPrompt(ctx context.Context, cfg *config.Config, allowPrompt // The picked profile resolves into its own config, not the caller's cfg. // Return the client (even on failure) so the caller renders errors against // that config rather than the original, otherwise-empty one. - a, err = databricks.NewAccountClient(&databricks.Config{Profile: profile}) + pcfg := &config.Config{Profile: profile} + skillsinvoked.Apply(pcfg) + a, err = databricks.NewAccountClient((*databricks.Config)(pcfg)) if err == nil { err = a.Config.Authenticate(emptyHttpRequest(ctx)) } @@ -239,6 +242,7 @@ func MustAccountClient(cmd *cobra.Command, args []string) error { cfg.Credentials = auth.CredentialsWithoutRefresh() } liteswap.Apply(ctx, cfg) + skillsinvoked.Apply(cfg) bindHostMetadataLogger(ctx, cfg) // The command-line profile flag takes precedence over DATABRICKS_CONFIG_PROFILE. @@ -356,7 +360,9 @@ func workspaceClientOrPrompt(ctx context.Context, cfg *config.Config, allowPromp // The picked profile resolves into its own config, not the caller's cfg. // Return the client (even on failure) so the caller renders errors against // that config rather than the original, otherwise-empty one. - w, err = databricks.NewWorkspaceClient(&databricks.Config{Profile: profile}) + pcfg := &config.Config{Profile: profile} + skillsinvoked.Apply(pcfg) + w, err = databricks.NewWorkspaceClient((*databricks.Config)(pcfg)) if err == nil { err = w.Config.Authenticate(emptyHttpRequest(ctx)) } @@ -372,6 +378,7 @@ func MustWorkspaceClient(cmd *cobra.Command, args []string) error { cfg.Credentials = auth.CredentialsWithoutRefresh() } liteswap.Apply(ctx, cfg) + skillsinvoked.Apply(cfg) bindHostMetadataLogger(ctx, cfg) // The command-line profile flag takes precedence over DATABRICKS_CONFIG_PROFILE. diff --git a/cmd/root/root.go b/cmd/root/root.go index a988c22d285..e3c43bd122f 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -50,6 +50,7 @@ func newRootCommand(ctx context.Context) *cobra.Command { initProfileFlag(cmd) initEnvironmentFlag(cmd) initTargetFlag(cmd) + initSkillsInvokedFlag(cmd) // Deprecated flag. Warn if it is specified. initProgressLoggerFlag(cmd, logFlags) @@ -87,6 +88,7 @@ func newRootCommand(ctx context.Context) *cobra.Command { ctx = installer.WithAiDevKitInUserAgent(ctx) ctx = installer.WithCallingAgentToolingInUserAgent(ctx) ctx = InjectTestPidToUserAgent(ctx) + ctx = withSkillsInvoked(ctx, cmd) cmd.SetContext(ctx) // Recommend installing Databricks AI tooling to the calling coding agent diff --git a/cmd/root/skills_invoked.go b/cmd/root/skills_invoked.go new file mode 100644 index 00000000000..bc1710e3661 --- /dev/null +++ b/cmd/root/skills_invoked.go @@ -0,0 +1,30 @@ +package root + +import ( + "context" + + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/skillsinvoked" + "github.com/spf13/cobra" +) + +// envSkillsInvoked is the primary channel: skills prefix commands with it, and +// older CLIs silently ignore unknown environment variables. +const envSkillsInvoked = "DATABRICKS_SKILLS_INVOKED" + +const flagSkillsInvoked = "skills-invoked" + +func initSkillsInvokedFlag(cmd *cobra.Command) { + cmd.PersistentFlags().String(flagSkillsInvoked, "", "comma-separated agent skills that invoked this command") + cmd.PersistentFlags().MarkHidden(flagSkillsInvoked) +} + +// withSkillsInvoked stores the skills that drove cmd in ctx. The flag wins over +// the environment variable when both are set. +func withSkillsInvoked(ctx context.Context, cmd *cobra.Command) context.Context { + raw := env.Get(ctx, envSkillsInvoked) + if f := cmd.Flag(flagSkillsInvoked); f != nil && f.Value.String() != "" { + raw = f.Value.String() + } + return skillsinvoked.WithSkills(ctx, skillsinvoked.Parse(ctx, raw)) +} diff --git a/cmd/root/skills_invoked_test.go b/cmd/root/skills_invoked_test.go new file mode 100644 index 00000000000..0f69a4d8d7b --- /dev/null +++ b/cmd/root/skills_invoked_test.go @@ -0,0 +1,39 @@ +package root + +import ( + "testing" + + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/skillsinvoked" + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestWithSkillsInvokedFlagAndEnvPrecedence(t *testing.T) { + tests := []struct { + name string + env string + flags []string + want []string + }{ + {"neither", "", nil, nil}, + {"env only", "from-env", nil, []string{"from-env"}}, + {"flag only", "", []string{"--skills-invoked", "from-flag"}, []string{"from-flag"}}, + {"flag wins over env", "from-env", []string{"--skills-invoked", "from-flag"}, []string{"from-flag"}}, + {"invalid flag does not fall back to env", "from-env", []string{"--skills-invoked", "!!"}, nil}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + cmd := &cobra.Command{Use: "test"} + initSkillsInvokedFlag(cmd) + require.NoError(t, cmd.ParseFlags(tt.flags)) + + ctx := t.Context() + if tt.env != "" { + ctx = env.Set(ctx, envSkillsInvoked, tt.env) + } + assert.Equal(t, tt.want, skillsinvoked.FromContext(withSkillsInvoked(ctx, cmd))) + }) + } +} diff --git a/libs/filer/files_client.go b/libs/filer/files_client.go index 25f8e8de344..873cb2421f7 100644 --- a/libs/filer/files_client.go +++ b/libs/filer/files_client.go @@ -14,6 +14,7 @@ import ( "github.com/databricks/cli/libs/databrickscfg/profile" "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/sdk-go/core/apierr" @@ -248,6 +249,9 @@ func newFilesAPIClient(ctx context.Context, cfg *config.Config) (*files.Client, client.WithCredentials(configCredentials{cfg: cfg}), client.WithoutConfigFile(), client.WithoutEnv(), + // The files client does not go through cfg.Headers. The transport wraps the + // same default transport the client would otherwise use. + client.WithHTTPClient(&http.Client{Transport: skillsinvoked.Transport(http.DefaultTransport)}), } // The workspace routing header is needed on unified ("SPOG") hosts; the CLI's // "none" sentinel means "no workspace ID", so it is not forwarded. diff --git a/libs/liteswap/liteswap.go b/libs/liteswap/liteswap.go index c83ec0b7b3b..bb81525f305 100644 --- a/libs/liteswap/liteswap.go +++ b/libs/liteswap/liteswap.go @@ -2,6 +2,7 @@ package liteswap import ( "context" + "net/http" "github.com/databricks/cli/libs/env" "github.com/databricks/databricks-sdk-go/config" @@ -16,7 +17,17 @@ func Apply(ctx context.Context, cfg *config.Config) { if target == "" { return } - cfg.Headers = config.StaticHeaders(map[string]string{ + traffic := config.StaticHeaders(map[string]string{ "x-databricks-traffic-id": "testenv://liteswap/" + target, }) + // Keep any header hook already set on cfg, such as the skills-invoked one. + prev := cfg.Headers + cfg.Headers = func(r *http.Request) error { + if prev != nil { + if err := prev(r); err != nil { + return err + } + } + return traffic(r) + } } diff --git a/libs/liteswap/liteswap_test.go b/libs/liteswap/liteswap_test.go new file mode 100644 index 00000000000..8dd57706047 --- /dev/null +++ b/libs/liteswap/liteswap_test.go @@ -0,0 +1,44 @@ +package liteswap_test + +import ( + "net/http" + "testing" + + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/liteswap" + "github.com/databricks/cli/libs/skillsinvoked" + "github.com/databricks/databricks-sdk-go/config" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestApplyComposesWithSkillsInvoked(t *testing.T) { + ctx := env.Set(t.Context(), liteswap.TargetVariable, "dms") + ctx = skillsinvoked.WithSkills(ctx, []string{"databricks-core"}) + + tests := []struct { + name string + apply func(*config.Config) + }{ + {"liteswap then skills", func(cfg *config.Config) { + liteswap.Apply(ctx, cfg) + skillsinvoked.Apply(cfg) + }}, + {"skills then liteswap", func(cfg *config.Config) { + skillsinvoked.Apply(cfg) + liteswap.Apply(ctx, cfg) + }}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + cfg := &config.Config{} + tt.apply(cfg) + + req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api", nil) + require.NoError(t, err) + require.NoError(t, cfg.Headers(req)) + assert.Equal(t, "testenv://liteswap/dms", req.Header.Get("x-databricks-traffic-id")) + assert.Equal(t, "databricks-core", req.Header.Get(skillsinvoked.Header)) + }) + } +} diff --git a/libs/skillsinvoked/skills.go b/libs/skillsinvoked/skills.go new file mode 100644 index 00000000000..4b010f1ecfc --- /dev/null +++ b/libs/skillsinvoked/skills.go @@ -0,0 +1,105 @@ +// Package skillsinvoked sends the agent skills that drove a CLI call to +// Databricks in the X-Databricks-Skills-Invoked header. +package skillsinvoked + +import ( + "context" + "net/http" + "regexp" + "slices" + "strings" + "sync" + + "github.com/databricks/cli/libs/log" + "github.com/databricks/databricks-sdk-go/config" +) + +// Header is the request header that lists the skills that drove the call. +const Header = "X-Databricks-Skills-Invoked" + +const ( + maxSkills = 20 + maxSkillLength = 64 +) + +// skillNamePattern matches plugin-scoped or plain skill names such as +// "databricks-core" or "databricks:databricks-core". +var skillNamePattern = sync.OnceValue(func() *regexp.Regexp { + return regexp.MustCompile(`^[a-z0-9][a-z0-9_.:-]*$`) +}) + +type skillsKey struct{} + +// Parse normalizes a comma-separated list of skill names. Entries are trimmed +// and lowercased, and empty, invalid, or over-long entries are dropped. Duplicates +// are removed and the list is capped at maxSkills. Dropped entries are logged at +// debug level only, because telemetry must never fail or warn a command. +func Parse(ctx context.Context, raw string) []string { + var skills []string + for entry := range strings.SplitSeq(raw, ",") { + name := strings.ToLower(strings.TrimSpace(entry)) + switch { + case name == "": + case len(name) > maxSkillLength || !skillNamePattern().MatchString(name): + log.Debugf(ctx, "dropping invalid skills-invoked entry %q", entry) + case slices.Contains(skills, name): + case len(skills) == maxSkills: + log.Debugf(ctx, "dropping skills-invoked entry %q: more than %d skills", name, maxSkills) + default: + skills = append(skills, name) + } + } + return skills +} + +// WithSkills returns a context that carries the skills that drove the command. +func WithSkills(ctx context.Context, skills []string) context.Context { + return context.WithValue(ctx, skillsKey{}, skills) +} + +// FromContext returns the skills stored by WithSkills, or nil if there are none. +func FromContext(ctx context.Context) []string { + skills, _ := ctx.Value(skillsKey{}).([]string) + return skills +} + +// Apply sets the header on every request made by cfg. The header is read from +// each request's context, so the command context must reach the request. A +// header hook already set on cfg (for example by liteswap) keeps running first. +func Apply(cfg *config.Config) { + prev := cfg.Headers + cfg.Headers = func(r *http.Request) error { + if prev != nil { + if err := prev(r); err != nil { + return err + } + } + setHeader(r) + return nil + } +} + +// Transport wraps base so that it sets the header on requests whose context +// carries skills. Use it for clients that do not go through config.Config.Headers. +func Transport(base http.RoundTripper) http.RoundTripper { + return roundTripper{base: base} +} + +type roundTripper struct { + base http.RoundTripper +} + +func (t roundTripper) RoundTrip(r *http.Request) (*http.Response, error) { + if len(FromContext(r.Context())) > 0 { + r = r.Clone(r.Context()) + setHeader(r) + } + return t.base.RoundTrip(r) +} + +// setHeader sets the header on r when its context carries skills. +func setHeader(r *http.Request) { + if skills := FromContext(r.Context()); len(skills) > 0 { + r.Header.Set(Header, strings.Join(skills, ",")) + } +} diff --git a/libs/skillsinvoked/skills_test.go b/libs/skillsinvoked/skills_test.go new file mode 100644 index 00000000000..84ddc0d41f4 --- /dev/null +++ b/libs/skillsinvoked/skills_test.go @@ -0,0 +1,123 @@ +package skillsinvoked + +import ( + "net/http" + "strings" + "testing" + + "github.com/databricks/databricks-sdk-go/config" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestParse(t *testing.T) { + tests := []struct { + name string + raw string + want []string + }{ + {"empty", "", nil}, + {"single", "databricks-core", []string{"databricks-core"}}, + {"multiple", "a,b,c", []string{"a", "b", "c"}}, + {"trims and lowercases", " Databricks-Core , JOBS ", []string{"databricks-core", "jobs"}}, + {"drops empty entries", ",,a,,", []string{"a"}}, + {"plugin scoped name", "databricks:databricks-core", []string{"databricks:databricks-core"}}, + {"allows underscore dot and colon", "a_b.c:d-e", []string{"a_b.c:d-e"}}, + {"drops invalid characters", "ok,bad name,semi;colon,a/b", []string{"ok"}}, + {"drops leading punctuation", "-a,.b,:c,_d", nil}, + {"dedupes preserving first occurrence", "b,a,b,a,c", []string{"b", "a", "c"}}, + {"dedupes after normalization", "Core,core, CORE", []string{"core"}}, + {"drops entry longer than 64 bytes", strings.Repeat("a", 65) + ",ok", []string{"ok"}}, + {"keeps entry of exactly 64 bytes", strings.Repeat("a", 64), []string{strings.Repeat("a", 64)}}, + {"caps at 20 entries", strings.Join(skillNames(25), ","), skillNames(20)}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + assert.Equal(t, tt.want, Parse(t.Context(), tt.raw)) + }) + } +} + +// skillNames returns n distinct valid skill names. +func skillNames(n int) []string { + names := make([]string, 0, n) + for i := range n { + names = append(names, "skill"+strings.Repeat("x", i)) + } + return names +} + +func TestApplySetsHeaderFromContext(t *testing.T) { + cfg := &config.Config{} + Apply(cfg) + + ctx := WithSkills(t.Context(), []string{"a", "b"}) + req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api", nil) + require.NoError(t, err) + require.NoError(t, cfg.Headers(req)) + assert.Equal(t, "a,b", req.Header.Get(Header)) +} + +func TestApplyNoHeaderWhenEmpty(t *testing.T) { + cfg := &config.Config{} + Apply(cfg) + + req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api", nil) + require.NoError(t, err) + require.NoError(t, cfg.Headers(req)) + assert.Empty(t, req.Header.Values(Header)) +} + +func TestApplyKeepsExistingHeaders(t *testing.T) { + cfg := &config.Config{Headers: config.StaticHeaders(map[string]string{"X-Other": "1"})} + Apply(cfg) + + ctx := WithSkills(t.Context(), []string{"a"}) + req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api", nil) + require.NoError(t, err) + require.NoError(t, cfg.Headers(req)) + assert.Equal(t, "1", req.Header.Get("X-Other")) + assert.Equal(t, "a", req.Header.Get(Header)) +} + +type roundTripFunc func(*http.Request) (*http.Response, error) + +func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { + return f(r) +} + +func TestTransportSetsHeaderWithoutMutatingRequest(t *testing.T) { + var sent *http.Request + base := roundTripFunc(func(r *http.Request) (*http.Response, error) { + sent = r + return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil + }) + client := &http.Client{Transport: Transport(base)} + + ctx := WithSkills(t.Context(), []string{"databricks:jobs"}) + req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api/2.0/fs/files", nil) + require.NoError(t, err) + resp, err := client.Do(req) + require.NoError(t, err) + resp.Body.Close() + + assert.Equal(t, "databricks:jobs", sent.Header.Get(Header)) + assert.Empty(t, req.Header.Values(Header)) +} + +func TestTransportNoHeaderWhenEmpty(t *testing.T) { + var sent *http.Request + base := roundTripFunc(func(r *http.Request) (*http.Response, error) { + sent = r + return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil + }) + client := &http.Client{Transport: Transport(base)} + + req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api", nil) + require.NoError(t, err) + resp, err := client.Do(req) + require.NoError(t, err) + resp.Body.Close() + + assert.Empty(t, sent.Header.Values(Header)) +} From 1fa2490b49e3dee1ec9aeb597092649ec5cdc2e0 Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Wed, 18 Nov 2026 10:52:33 +0000 Subject: [PATCH 2/8] Tighten skills-invoked comments and leave liteswap unchanged Every SDK config site applies liteswap before skillsinvoked, and skillsinvoked.Apply chains the existing header hook, so liteswap does not need to change. Shorten doc comments to the contract and the reasons. Co-authored-by: Isaac --- cmd/root/skills_invoked.go | 10 ++++---- libs/filer/files_client.go | 3 +-- libs/liteswap/liteswap.go | 13 +--------- libs/liteswap/liteswap_test.go | 44 ---------------------------------- libs/skillsinvoked/skills.go | 40 +++++++++++++------------------ 5 files changed, 24 insertions(+), 86 deletions(-) delete mode 100644 libs/liteswap/liteswap_test.go diff --git a/cmd/root/skills_invoked.go b/cmd/root/skills_invoked.go index bc1710e3661..9b555418b24 100644 --- a/cmd/root/skills_invoked.go +++ b/cmd/root/skills_invoked.go @@ -8,8 +8,8 @@ import ( "github.com/spf13/cobra" ) -// envSkillsInvoked is the primary channel: skills prefix commands with it, and -// older CLIs silently ignore unknown environment variables. +// Agent skills set envSkillsInvoked rather than the flag because older CLIs +// reject unknown flags but ignore unknown environment variables. const envSkillsInvoked = "DATABRICKS_SKILLS_INVOKED" const flagSkillsInvoked = "skills-invoked" @@ -20,11 +20,11 @@ func initSkillsInvokedFlag(cmd *cobra.Command) { } // withSkillsInvoked stores the skills that drove cmd in ctx. The flag wins over -// the environment variable when both are set. +// the environment variable. func withSkillsInvoked(ctx context.Context, cmd *cobra.Command) context.Context { raw := env.Get(ctx, envSkillsInvoked) - if f := cmd.Flag(flagSkillsInvoked); f != nil && f.Value.String() != "" { - raw = f.Value.String() + if v := cmd.Flag(flagSkillsInvoked).Value.String(); v != "" { + raw = v } return skillsinvoked.WithSkills(ctx, skillsinvoked.Parse(ctx, raw)) } diff --git a/libs/filer/files_client.go b/libs/filer/files_client.go index 873cb2421f7..866f466f9b8 100644 --- a/libs/filer/files_client.go +++ b/libs/filer/files_client.go @@ -249,8 +249,7 @@ func newFilesAPIClient(ctx context.Context, cfg *config.Config) (*files.Client, client.WithCredentials(configCredentials{cfg: cfg}), client.WithoutConfigFile(), client.WithoutEnv(), - // The files client does not go through cfg.Headers. The transport wraps the - // same default transport the client would otherwise use. + // files/v2 doesn't use cfg.Headers. http.DefaultTransport is its default. client.WithHTTPClient(&http.Client{Transport: skillsinvoked.Transport(http.DefaultTransport)}), } // The workspace routing header is needed on unified ("SPOG") hosts; the CLI's diff --git a/libs/liteswap/liteswap.go b/libs/liteswap/liteswap.go index bb81525f305..c83ec0b7b3b 100644 --- a/libs/liteswap/liteswap.go +++ b/libs/liteswap/liteswap.go @@ -2,7 +2,6 @@ package liteswap import ( "context" - "net/http" "github.com/databricks/cli/libs/env" "github.com/databricks/databricks-sdk-go/config" @@ -17,17 +16,7 @@ func Apply(ctx context.Context, cfg *config.Config) { if target == "" { return } - traffic := config.StaticHeaders(map[string]string{ + cfg.Headers = config.StaticHeaders(map[string]string{ "x-databricks-traffic-id": "testenv://liteswap/" + target, }) - // Keep any header hook already set on cfg, such as the skills-invoked one. - prev := cfg.Headers - cfg.Headers = func(r *http.Request) error { - if prev != nil { - if err := prev(r); err != nil { - return err - } - } - return traffic(r) - } } diff --git a/libs/liteswap/liteswap_test.go b/libs/liteswap/liteswap_test.go deleted file mode 100644 index 8dd57706047..00000000000 --- a/libs/liteswap/liteswap_test.go +++ /dev/null @@ -1,44 +0,0 @@ -package liteswap_test - -import ( - "net/http" - "testing" - - "github.com/databricks/cli/libs/env" - "github.com/databricks/cli/libs/liteswap" - "github.com/databricks/cli/libs/skillsinvoked" - "github.com/databricks/databricks-sdk-go/config" - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" -) - -func TestApplyComposesWithSkillsInvoked(t *testing.T) { - ctx := env.Set(t.Context(), liteswap.TargetVariable, "dms") - ctx = skillsinvoked.WithSkills(ctx, []string{"databricks-core"}) - - tests := []struct { - name string - apply func(*config.Config) - }{ - {"liteswap then skills", func(cfg *config.Config) { - liteswap.Apply(ctx, cfg) - skillsinvoked.Apply(cfg) - }}, - {"skills then liteswap", func(cfg *config.Config) { - skillsinvoked.Apply(cfg) - liteswap.Apply(ctx, cfg) - }}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - cfg := &config.Config{} - tt.apply(cfg) - - req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api", nil) - require.NoError(t, err) - require.NoError(t, cfg.Headers(req)) - assert.Equal(t, "testenv://liteswap/dms", req.Header.Get("x-databricks-traffic-id")) - assert.Equal(t, "databricks-core", req.Header.Get(skillsinvoked.Header)) - }) - } -} diff --git a/libs/skillsinvoked/skills.go b/libs/skillsinvoked/skills.go index 4b010f1ecfc..ca8c64bd55a 100644 --- a/libs/skillsinvoked/skills.go +++ b/libs/skillsinvoked/skills.go @@ -14,7 +14,7 @@ import ( "github.com/databricks/databricks-sdk-go/config" ) -// Header is the request header that lists the skills that drove the call. +// Header lists the skills that drove the call. const Header = "X-Databricks-Skills-Invoked" const ( @@ -22,18 +22,17 @@ const ( maxSkillLength = 64 ) -// skillNamePattern matches plugin-scoped or plain skill names such as -// "databricks-core" or "databricks:databricks-core". +// skillNamePattern also allows plugin-scoped names such as "databricks:databricks-core". var skillNamePattern = sync.OnceValue(func() *regexp.Regexp { return regexp.MustCompile(`^[a-z0-9][a-z0-9_.:-]*$`) }) type skillsKey struct{} -// Parse normalizes a comma-separated list of skill names. Entries are trimmed -// and lowercased, and empty, invalid, or over-long entries are dropped. Duplicates -// are removed and the list is capped at maxSkills. Dropped entries are logged at -// debug level only, because telemetry must never fail or warn a command. +// Parse normalizes a comma-separated list of skill names: entries are trimmed, +// lowercased and deduplicated, invalid ones are dropped, and at most maxSkills +// are kept. Invalid input is only logged at debug level because this is +// telemetry and must never fail or warn a command. func Parse(ctx context.Context, raw string) []string { var skills []string for entry := range strings.SplitSeq(raw, ",") { @@ -57,15 +56,15 @@ func WithSkills(ctx context.Context, skills []string) context.Context { return context.WithValue(ctx, skillsKey{}, skills) } -// FromContext returns the skills stored by WithSkills, or nil if there are none. +// FromContext returns the skills stored by WithSkills. func FromContext(ctx context.Context) []string { skills, _ := ctx.Value(skillsKey{}).([]string) return skills } -// Apply sets the header on every request made by cfg. The header is read from -// each request's context, so the command context must reach the request. A -// header hook already set on cfg (for example by liteswap) keeps running first. +// Apply sets the header on every request made with cfg, keeping any header +// hook already on cfg (such as liteswap's). The value comes from the request +// context, so it is only sent when the command context reaches the request. func Apply(cfg *config.Config) { prev := cfg.Headers cfg.Headers = func(r *http.Request) error { @@ -74,13 +73,14 @@ func Apply(cfg *config.Config) { return err } } - setHeader(r) + if skills := FromContext(r.Context()); len(skills) > 0 { + r.Header.Set(Header, strings.Join(skills, ",")) + } return nil } } -// Transport wraps base so that it sets the header on requests whose context -// carries skills. Use it for clients that do not go through config.Config.Headers. +// Transport wraps base to set the header, for clients that don't use config.Config.Headers. func Transport(base http.RoundTripper) http.RoundTripper { return roundTripper{base: base} } @@ -90,16 +90,10 @@ type roundTripper struct { } func (t roundTripper) RoundTrip(r *http.Request) (*http.Response, error) { - if len(FromContext(r.Context())) > 0 { - r = r.Clone(r.Context()) - setHeader(r) - } - return t.base.RoundTrip(r) -} - -// setHeader sets the header on r when its context carries skills. -func setHeader(r *http.Request) { if skills := FromContext(r.Context()); len(skills) > 0 { + // A RoundTripper must not modify the caller's request. + r = r.Clone(r.Context()) r.Header.Set(Header, strings.Join(skills, ",")) } + return t.base.RoundTrip(r) } From 954546c7beb203960bbc9581929108b0a8cc1184 Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Wed, 18 Nov 2026 11:22:17 +0000 Subject: [PATCH 3/8] Keep the skills-invoked header within 1024 bytes The HTTP access log truncates the header at 1024 bytes. Stop adding names before the joined value would exceed that, so a partial name is never logged. Co-authored-by: Isaac --- libs/skillsinvoked/skills.go | 18 ++++++++++++++---- libs/skillsinvoked/skills_test.go | 12 ++++++++++++ 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/libs/skillsinvoked/skills.go b/libs/skillsinvoked/skills.go index ca8c64bd55a..c6f224910a8 100644 --- a/libs/skillsinvoked/skills.go +++ b/libs/skillsinvoked/skills.go @@ -20,6 +20,9 @@ const Header = "X-Databricks-Skills-Invoked" const ( maxSkills = 20 maxSkillLength = 64 + // The HTTP access log truncates the header at 1024 bytes, so stop before + // that rather than log a partial name. + maxHeaderLength = 1024 ) // skillNamePattern also allows plugin-scoped names such as "databricks:databricks-core". @@ -31,21 +34,28 @@ type skillsKey struct{} // Parse normalizes a comma-separated list of skill names: entries are trimmed, // lowercased and deduplicated, invalid ones are dropped, and at most maxSkills -// are kept. Invalid input is only logged at debug level because this is -// telemetry and must never fail or warn a command. +// are kept, joining to at most maxHeaderLength bytes. Invalid input is only +// logged at debug level because this is telemetry and must never fail or warn +// a command. func Parse(ctx context.Context, raw string) []string { var skills []string + size := 0 for entry := range strings.SplitSeq(raw, ",") { name := strings.ToLower(strings.TrimSpace(entry)) + added := len(name) + if len(skills) > 0 { + added++ // comma separator + } switch { case name == "": case len(name) > maxSkillLength || !skillNamePattern().MatchString(name): log.Debugf(ctx, "dropping invalid skills-invoked entry %q", entry) case slices.Contains(skills, name): - case len(skills) == maxSkills: - log.Debugf(ctx, "dropping skills-invoked entry %q: more than %d skills", name, maxSkills) + case len(skills) == maxSkills || size+added > maxHeaderLength: + log.Debugf(ctx, "dropping skills-invoked entry %q: over %d skills or %d bytes", name, maxSkills, maxHeaderLength) default: skills = append(skills, name) + size += added } } return skills diff --git a/libs/skillsinvoked/skills_test.go b/libs/skillsinvoked/skills_test.go index 84ddc0d41f4..f5e9060242e 100644 --- a/libs/skillsinvoked/skills_test.go +++ b/libs/skillsinvoked/skills_test.go @@ -1,6 +1,7 @@ package skillsinvoked import ( + "fmt" "net/http" "strings" "testing" @@ -30,6 +31,7 @@ func TestParse(t *testing.T) { {"drops entry longer than 64 bytes", strings.Repeat("a", 65) + ",ok", []string{"ok"}}, {"keeps entry of exactly 64 bytes", strings.Repeat("a", 64), []string{strings.Repeat("a", 64)}}, {"caps at 20 entries", strings.Join(skillNames(25), ","), skillNames(20)}, + {"caps joined length at 1024 bytes", strings.Join(longNames(20), ","), longNames(15)}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { @@ -47,6 +49,16 @@ func skillNames(n int) []string { return names } +// longNames returns n distinct 64-byte skill names; 15 of them join to 974 +// bytes and a 16th would make 1039. +func longNames(n int) []string { + names := make([]string, 0, n) + for i := range n { + names = append(names, fmt.Sprintf("%02d", i)+strings.Repeat("x", maxSkillLength-2)) + } + return names +} + func TestApplySetsHeaderFromContext(t *testing.T) { cfg := &config.Config{} Apply(cfg) From 5de7d1b9d08bd6523b2b590c563c4179a4ce6ce2 Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Wed, 18 Nov 2026 12:33:49 +0000 Subject: [PATCH 4/8] Drop the --skills-invoked flag and respect the telemetry opt-out Only DATABRICKS_SKILLS_INVOKED is read now, so the feature can be removed later without changing the CLI's interface. No header is sent when DATABRICKS_CLI_DISABLE_TELEMETRY is set. Review fixes: - Acceptance test: MSYS_NO_PATHCONV=1 for the leading-slash api get so it passes on Windows, call the modeled /api/2.1/clusters/list and drop the stub, and unset a host DATABRICKS_SKILLS_INVOKED in acceptance_test.go. - Unit test always sets the env vars in the context so a host value can't leak in. - `auth profiles` validation calls and the SSH HTTP/1.1 release client now send the header. - The files/v2 client applies the whole cfg.Headers hook in its transport, so liteswap's traffic header reaches it too; skillsinvoked.Transport is gone. Co-authored-by: Isaac --- acceptance/acceptance_test.go | 4 ++ acceptance/cmd/skills-invoked/output.txt | 23 +++------ acceptance/cmd/skills-invoked/script | 11 ++--- acceptance/cmd/skills-invoked/test.toml | 4 -- cmd/auth/profiles.go | 2 + cmd/root/root.go | 3 +- cmd/root/skills_invoked.go | 27 ++++------- cmd/root/skills_invoked_test.go | 33 +++++-------- experimental/ssh/internal/client/releases.go | 2 + libs/filer/files_client.go | 24 ++++++++-- libs/filer/files_client_test.go | 49 ++++++++++++++++++++ libs/skillsinvoked/skills.go | 18 ------- libs/skillsinvoked/skills_test.go | 42 ----------------- 13 files changed, 112 insertions(+), 130 deletions(-) diff --git a/acceptance/acceptance_test.go b/acceptance/acceptance_test.go index b7fbab91a1f..70f5886f7cc 100644 --- a/acceptance/acceptance_test.go +++ b/acceptance/acceptance_test.go @@ -292,6 +292,10 @@ func testAccept(t *testing.T, inprocessMode bool, selectedTests []string, skipTo // from the host shell would move the venv the localenv tests expect. os.Unsetenv("UV_PROJECT_ENVIRONMENT") //nolint:usetesting // t.Setenv cannot unset + // Agent skills export DATABRICKS_SKILLS_INVOKED, so a host value would add + // the X-Databricks-Skills-Invoked header to recorded requests. + os.Unsetenv("DATABRICKS_SKILLS_INVOKED") //nolint:usetesting // t.Setenv cannot unset + if !requirePrerequisites(t) { // Don't run the suite against a stale toolchain; the failed subtest // has already marked the parent test as failed. diff --git a/acceptance/cmd/skills-invoked/output.txt b/acceptance/cmd/skills-invoked/output.txt index b4af00b90f4..235d5c1552d 100644 --- a/acceptance/cmd/skills-invoked/output.txt +++ b/acceptance/cmd/skills-invoked/output.txt @@ -31,7 +31,7 @@ === Env var sends the header on databricks api ->>> [CLI] api get /api/2.0/clusters/list +>>> [CLI] api get /api/2.1/clusters/list >>> print_requests.py --get //clusters/list { @@ -41,7 +41,7 @@ ] }, "method": "GET", - "path": "/api/2.0/clusters/list" + "path": "/api/2.1/clusters/list" } === Env var sends the header on the files API used by fs @@ -80,37 +80,32 @@ "path": "/api/2.0/preview/scim/v2/Me" } -=== Flag wins over env var +=== Invalid entries are dropped and the rest is normalized ->>> [CLI] current-user me --skills-invoked from-flag +>>> [CLI] current-user me >>> print_requests.py --get //scim/v2/Me { "headers": { "X-Databricks-Skills-Invoked": [ - "from-flag" + "databricks-core,databricks:databricks-jobs" ] }, "method": "GET", "path": "/api/2.0/preview/scim/v2/Me" } -=== Invalid entries are dropped and the rest is normalized +=== No header when unset >>> [CLI] current-user me >>> print_requests.py --get //scim/v2/Me { - "headers": { - "X-Databricks-Skills-Invoked": [ - "databricks-core,databricks:databricks-jobs" - ] - }, "method": "GET", "path": "/api/2.0/preview/scim/v2/Me" } -=== No header when unset +=== No header when telemetry is disabled >>> [CLI] current-user me @@ -119,7 +114,3 @@ "method": "GET", "path": "/api/2.0/preview/scim/v2/Me" } - -=== Flag is hidden from help - ->>> [CLI] --help diff --git a/acceptance/cmd/skills-invoked/script b/acceptance/cmd/skills-invoked/script index d98debf7894..5b27e1293c3 100644 --- a/acceptance/cmd/skills-invoked/script +++ b/acceptance/cmd/skills-invoked/script @@ -7,7 +7,7 @@ DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI clusters list > /dev/null trace print_requests.py --get //clusters/list title "Env var sends the header on databricks api" -DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI api get /api/2.0/clusters/list > /dev/null +DATABRICKS_SKILLS_INVOKED=databricks-core MSYS_NO_PATHCONV=1 trace $CLI api get /api/2.1/clusters/list > /dev/null trace print_requests.py --get //clusters/list title "Env var sends the header on the files API used by fs" @@ -19,10 +19,6 @@ title "Env var sends the header from bundle commands" DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI bundle validate > /dev/null trace print_requests.py --get //scim/v2/Me -title "Flag wins over env var" -DATABRICKS_SKILLS_INVOKED=from-env trace $CLI current-user me --skills-invoked from-flag > /dev/null -trace print_requests.py --get //scim/v2/Me - title "Invalid entries are dropped and the rest is normalized" DATABRICKS_SKILLS_INVOKED=' Databricks-Core , bad name!,,databricks-core,databricks:databricks-jobs ' trace $CLI current-user me > /dev/null trace print_requests.py --get //scim/v2/Me @@ -31,5 +27,6 @@ title "No header when unset" trace $CLI current-user me > /dev/null trace print_requests.py --get //scim/v2/Me | contains.py "!X-Databricks-Skills-Invoked" -title "Flag is hidden from help" -trace $CLI --help | contains.py "!skills-invoked" > /dev/null +title "No header when telemetry is disabled" +DATABRICKS_SKILLS_INVOKED=databricks-core DATABRICKS_CLI_DISABLE_TELEMETRY=1 trace $CLI current-user me > /dev/null +trace print_requests.py --get //scim/v2/Me | contains.py "!X-Databricks-Skills-Invoked" diff --git a/acceptance/cmd/skills-invoked/test.toml b/acceptance/cmd/skills-invoked/test.toml index df326944a2b..bacd40cc189 100644 --- a/acceptance/cmd/skills-invoked/test.toml +++ b/acceptance/cmd/skills-invoked/test.toml @@ -1,7 +1,3 @@ RecordRequests = true IncludeRequestHeaders = ["X-Databricks-Skills-Invoked"] Ignore = [".databricks"] - -[[Server]] -Pattern = "GET /api/2.0/clusters/list" -Response.Body = '{}' diff --git a/cmd/auth/profiles.go b/cmd/auth/profiles.go index e65b11371b7..2c03e68b17c 100644 --- a/cmd/auth/profiles.go +++ b/cmd/auth/profiles.go @@ -14,6 +14,7 @@ import ( "github.com/databricks/cli/libs/databrickscfg/profile" "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/log" + "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/databricks-sdk-go/service/iam" @@ -60,6 +61,7 @@ func (c *profileMetadata) Load(ctx context.Context, configFilePath string, skipV HTTPTimeoutSeconds: timeoutSeconds, RetryTimeoutSeconds: timeoutSeconds, } + skillsinvoked.Apply(cfg) if skipValidate { // EnsureResolved fetches /.well-known/databricks-config to enrich // the config, so without this stub a skip-validate listing still makes diff --git a/cmd/root/root.go b/cmd/root/root.go index e3c43bd122f..1bf3f00bf3e 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -50,7 +50,6 @@ func newRootCommand(ctx context.Context) *cobra.Command { initProfileFlag(cmd) initEnvironmentFlag(cmd) initTargetFlag(cmd) - initSkillsInvokedFlag(cmd) // Deprecated flag. Warn if it is specified. initProgressLoggerFlag(cmd, logFlags) @@ -88,7 +87,7 @@ func newRootCommand(ctx context.Context) *cobra.Command { ctx = installer.WithAiDevKitInUserAgent(ctx) ctx = installer.WithCallingAgentToolingInUserAgent(ctx) ctx = InjectTestPidToUserAgent(ctx) - ctx = withSkillsInvoked(ctx, cmd) + ctx = withSkillsInvoked(ctx) cmd.SetContext(ctx) // Recommend installing Databricks AI tooling to the calling coding agent diff --git a/cmd/root/skills_invoked.go b/cmd/root/skills_invoked.go index 9b555418b24..ffc20878fc0 100644 --- a/cmd/root/skills_invoked.go +++ b/cmd/root/skills_invoked.go @@ -5,26 +5,19 @@ import ( "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/skillsinvoked" - "github.com/spf13/cobra" + "github.com/databricks/cli/libs/telemetry" ) -// Agent skills set envSkillsInvoked rather than the flag because older CLIs -// reject unknown flags but ignore unknown environment variables. +// envSkillsInvoked is an env var rather than a flag so it can be removed +// without breaking the CLI's interface, and because older CLIs ignore unknown +// env vars but reject unknown flags. const envSkillsInvoked = "DATABRICKS_SKILLS_INVOKED" -const flagSkillsInvoked = "skills-invoked" - -func initSkillsInvokedFlag(cmd *cobra.Command) { - cmd.PersistentFlags().String(flagSkillsInvoked, "", "comma-separated agent skills that invoked this command") - cmd.PersistentFlags().MarkHidden(flagSkillsInvoked) -} - -// withSkillsInvoked stores the skills that drove cmd in ctx. The flag wins over -// the environment variable. -func withSkillsInvoked(ctx context.Context, cmd *cobra.Command) context.Context { - raw := env.Get(ctx, envSkillsInvoked) - if v := cmd.Flag(flagSkillsInvoked).Value.String(); v != "" { - raw = v +// withSkillsInvoked stores the skills from envSkillsInvoked in ctx, unless the +// user opted out of telemetry. +func withSkillsInvoked(ctx context.Context) context.Context { + if telemetry.Disabled(ctx) { + return ctx } - return skillsinvoked.WithSkills(ctx, skillsinvoked.Parse(ctx, raw)) + return skillsinvoked.WithSkills(ctx, skillsinvoked.Parse(ctx, env.Get(ctx, envSkillsInvoked))) } diff --git a/cmd/root/skills_invoked_test.go b/cmd/root/skills_invoked_test.go index 0f69a4d8d7b..a635e0eff7a 100644 --- a/cmd/root/skills_invoked_test.go +++ b/cmd/root/skills_invoked_test.go @@ -5,35 +5,26 @@ import ( "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/skillsinvoked" - "github.com/spf13/cobra" "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" ) -func TestWithSkillsInvokedFlagAndEnvPrecedence(t *testing.T) { +func TestWithSkillsInvoked(t *testing.T) { tests := []struct { - name string - env string - flags []string - want []string + name string + skills string + disableTelemetry string + want []string }{ - {"neither", "", nil, nil}, - {"env only", "from-env", nil, []string{"from-env"}}, - {"flag only", "", []string{"--skills-invoked", "from-flag"}, []string{"from-flag"}}, - {"flag wins over env", "from-env", []string{"--skills-invoked", "from-flag"}, []string{"from-flag"}}, - {"invalid flag does not fall back to env", "from-env", []string{"--skills-invoked", "!!"}, nil}, + {"unset", "", "", nil}, + {"set", "databricks-core,databricks-jobs", "", []string{"databricks-core", "databricks-jobs"}}, + {"telemetry disabled", "databricks-core", "1", nil}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - cmd := &cobra.Command{Use: "test"} - initSkillsInvokedFlag(cmd) - require.NoError(t, cmd.ParseFlags(tt.flags)) - - ctx := t.Context() - if tt.env != "" { - ctx = env.Set(ctx, envSkillsInvoked, tt.env) - } - assert.Equal(t, tt.want, skillsinvoked.FromContext(withSkillsInvoked(ctx, cmd))) + // Always set both: an empty value in the context overrides the host environment. + ctx := env.Set(t.Context(), envSkillsInvoked, tt.skills) + ctx = env.Set(ctx, "DATABRICKS_CLI_DISABLE_TELEMETRY", tt.disableTelemetry) + assert.Equal(t, tt.want, skillsinvoked.FromContext(withSkillsInvoked(ctx))) }) } } diff --git a/experimental/ssh/internal/client/releases.go b/experimental/ssh/internal/client/releases.go index def34ce363c..da6b116dfc8 100644 --- a/experimental/ssh/internal/client/releases.go +++ b/experimental/ssh/internal/client/releases.go @@ -69,6 +69,8 @@ func newHTTP11WorkspaceClient(src *config.Config) (*databricks.WorkspaceClient, } } cfg.HTTPTransport = newHTTP11Transport(src) + // Headers is a func, not a config attribute, so the loop above doesn't copy it. + cfg.Headers = src.Headers return databricks.NewWorkspaceClient((*databricks.Config)(cfg)) } diff --git a/libs/filer/files_client.go b/libs/filer/files_client.go index 866f466f9b8..289cc0710fe 100644 --- a/libs/filer/files_client.go +++ b/libs/filer/files_client.go @@ -14,7 +14,6 @@ import ( "github.com/databricks/cli/libs/databrickscfg/profile" "github.com/databricks/cli/libs/env" - "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/sdk-go/core/apierr" @@ -240,6 +239,24 @@ func newTransferClient(n int) *http.Client { return &http.Client{Transport: transport} } +// headersTransport applies a config.Config.Headers hook to each request. +type headersTransport struct { + base http.RoundTripper + headers func(*http.Request) error +} + +func (t headersTransport) RoundTrip(r *http.Request) (*http.Response, error) { + if t.headers == nil { + return t.base.RoundTrip(r) + } + // A RoundTripper must not modify the caller's request. + r = r.Clone(r.Context()) + if err := t.headers(r); err != nil { + return nil, err + } + return t.base.RoundTrip(r) +} + // newFilesAPIClient builds the files/v2 client from the CLI's already resolved // config, reusing its auth instead of re-reading a profile. cfg is passed by // pointer because config.Config embeds a sync.Mutex and must not be copied. @@ -249,8 +266,9 @@ func newFilesAPIClient(ctx context.Context, cfg *config.Config) (*files.Client, client.WithCredentials(configCredentials{cfg: cfg}), client.WithoutConfigFile(), client.WithoutEnv(), - // files/v2 doesn't use cfg.Headers. http.DefaultTransport is its default. - client.WithHTTPClient(&http.Client{Transport: skillsinvoked.Transport(http.DefaultTransport)}), + // files/v2 doesn't call cfg.Headers, so apply it in the transport. + // http.DefaultTransport is what files/v2 uses by default. + client.WithHTTPClient(&http.Client{Transport: headersTransport{base: http.DefaultTransport, headers: cfg.Headers}}), } // The workspace routing header is needed on unified ("SPOG") hosts; the CLI's // "none" sentinel means "no workspace ID", so it is not forwarded. diff --git a/libs/filer/files_client_test.go b/libs/filer/files_client_test.go index 0d621d3e542..790b783d834 100644 --- a/libs/filer/files_client_test.go +++ b/libs/filer/files_client_test.go @@ -6,6 +6,7 @@ import ( "fmt" "io" "io/fs" + "net/http" "os" "path/filepath" "strings" @@ -18,6 +19,7 @@ import ( "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/testserver" "github.com/databricks/databricks-sdk-go" + "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/sdk-go/core/ops" files "github.com/databricks/sdk-go/files/v2" "github.com/stretchr/testify/assert" @@ -337,3 +339,50 @@ func TestFilesClientStopsRetryingAfterLimit(t *testing.T) { assert.ErrorContains(t, err, "AWS S3 is throttling requests") assert.Equal(t, filesMaxRetries+1, requests) } + +type roundTripFunc func(*http.Request) (*http.Response, error) + +func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { + return f(r) +} + +func TestHeadersTransport(t *testing.T) { + tests := []struct { + name string + headers func(*http.Request) error + want string + }{ + {"no hook", nil, ""}, + {"hook sets header", config.StaticHeaders(map[string]string{"X-Test": "1"}), "1"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var sent *http.Request + base := roundTripFunc(func(r *http.Request) (*http.Response, error) { + sent = r + return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil + }) + req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api/2.0/fs/files", nil) + require.NoError(t, err) + + resp, err := headersTransport{base: base, headers: tt.headers}.RoundTrip(req) + require.NoError(t, err) + resp.Body.Close() + + assert.Equal(t, tt.want, sent.Header.Get("X-Test")) + assert.Empty(t, req.Header.Values("X-Test"), "caller's request must not be modified") + }) + } +} + +func TestHeadersTransportReturnsHookError(t *testing.T) { + base := roundTripFunc(func(r *http.Request) (*http.Response, error) { + t.Fatal("base transport must not be called") + return nil, nil + }) + req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api", nil) + require.NoError(t, err) + + _, err = headersTransport{base: base, headers: func(*http.Request) error { return errors.New("boom") }}.RoundTrip(req) + assert.EqualError(t, err, "boom") +} diff --git a/libs/skillsinvoked/skills.go b/libs/skillsinvoked/skills.go index c6f224910a8..c2ccbaec26f 100644 --- a/libs/skillsinvoked/skills.go +++ b/libs/skillsinvoked/skills.go @@ -89,21 +89,3 @@ func Apply(cfg *config.Config) { return nil } } - -// Transport wraps base to set the header, for clients that don't use config.Config.Headers. -func Transport(base http.RoundTripper) http.RoundTripper { - return roundTripper{base: base} -} - -type roundTripper struct { - base http.RoundTripper -} - -func (t roundTripper) RoundTrip(r *http.Request) (*http.Response, error) { - if skills := FromContext(r.Context()); len(skills) > 0 { - // A RoundTripper must not modify the caller's request. - r = r.Clone(r.Context()) - r.Header.Set(Header, strings.Join(skills, ",")) - } - return t.base.RoundTrip(r) -} diff --git a/libs/skillsinvoked/skills_test.go b/libs/skillsinvoked/skills_test.go index f5e9060242e..7a80c057f52 100644 --- a/libs/skillsinvoked/skills_test.go +++ b/libs/skillsinvoked/skills_test.go @@ -91,45 +91,3 @@ func TestApplyKeepsExistingHeaders(t *testing.T) { assert.Equal(t, "1", req.Header.Get("X-Other")) assert.Equal(t, "a", req.Header.Get(Header)) } - -type roundTripFunc func(*http.Request) (*http.Response, error) - -func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { - return f(r) -} - -func TestTransportSetsHeaderWithoutMutatingRequest(t *testing.T) { - var sent *http.Request - base := roundTripFunc(func(r *http.Request) (*http.Response, error) { - sent = r - return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil - }) - client := &http.Client{Transport: Transport(base)} - - ctx := WithSkills(t.Context(), []string{"databricks:jobs"}) - req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api/2.0/fs/files", nil) - require.NoError(t, err) - resp, err := client.Do(req) - require.NoError(t, err) - resp.Body.Close() - - assert.Equal(t, "databricks:jobs", sent.Header.Get(Header)) - assert.Empty(t, req.Header.Values(Header)) -} - -func TestTransportNoHeaderWhenEmpty(t *testing.T) { - var sent *http.Request - base := roundTripFunc(func(r *http.Request) (*http.Response, error) { - sent = r - return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil - }) - client := &http.Client{Transport: Transport(base)} - - req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api", nil) - require.NoError(t, err) - resp, err := client.Do(req) - require.NoError(t, err) - resp.Body.Close() - - assert.Empty(t, sent.Header.Values(Header)) -} From 6268ba7b3ee59e3aa007e4c24c08e152fe687d0b Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Wed, 18 Nov 2026 12:35:43 +0000 Subject: [PATCH 5/8] Test that headersTransport returns the hook's error Co-authored-by: Isaac --- libs/filer/files_client_test.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/libs/filer/files_client_test.go b/libs/filer/files_client_test.go index 790b783d834..8810a295fbd 100644 --- a/libs/filer/files_client_test.go +++ b/libs/filer/files_client_test.go @@ -383,6 +383,7 @@ func TestHeadersTransportReturnsHookError(t *testing.T) { req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api", nil) require.NoError(t, err) - _, err = headersTransport{base: base, headers: func(*http.Request) error { return errors.New("boom") }}.RoundTrip(req) + resp, err := headersTransport{base: base, headers: func(*http.Request) error { return errors.New("boom") }}.RoundTrip(req) //nolint:bodyclose // no response on error + assert.Nil(t, resp) assert.EqualError(t, err, "boom") } From 395a3c92398bb1da6dcaf68774ad9585c3c85aa1 Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Wed, 18 Nov 2026 12:45:50 +0000 Subject: [PATCH 6/8] Send invoked skills as user-agent pairs instead of a header DATABRICKS_SKILLS_INVOKED now adds one skill/ pair per skill to the user agent, next to the other user-agent dimensions in cmd/root. The SDK already sends context user-agent pairs on every request, so the per-client header hooks (auth, bundles, api, auth profiles, SSH releases, files/v2) are reverted. The DECO usage pipeline parses repeated keys into unified_user_agent.other_info_multi, as it does for aitools/. Names are limited to [a-z0-9_.-], a subset of what the SDK accepts in a user agent value. This is experimental tracking and is commented as such. Co-authored-by: Isaac --- acceptance/acceptance_test.go | 4 +- acceptance/cmd/skills-invoked/output.txt | 94 ++------------------ acceptance/cmd/skills-invoked/script | 36 ++++---- acceptance/cmd/skills-invoked/test.toml | 2 +- bundle/config/workspace.go | 2 - cmd/api/api.go | 2 - cmd/auth/profiles.go | 2 - cmd/root/auth.go | 11 +-- cmd/root/root.go | 2 +- cmd/root/skills_invoked.go | 23 ----- cmd/root/skills_invoked_test.go | 30 ------- cmd/root/user_agent_skills.go | 72 +++++++++++++++ cmd/root/user_agent_skills_test.go | 72 +++++++++++++++ experimental/ssh/internal/client/releases.go | 2 - libs/filer/files_client.go | 21 ----- libs/filer/files_client_test.go | 50 ----------- libs/skillsinvoked/skills.go | 91 ------------------- libs/skillsinvoked/skills_test.go | 93 ------------------- 18 files changed, 172 insertions(+), 437 deletions(-) delete mode 100644 cmd/root/skills_invoked.go delete mode 100644 cmd/root/skills_invoked_test.go create mode 100644 cmd/root/user_agent_skills.go create mode 100644 cmd/root/user_agent_skills_test.go delete mode 100644 libs/skillsinvoked/skills.go delete mode 100644 libs/skillsinvoked/skills_test.go diff --git a/acceptance/acceptance_test.go b/acceptance/acceptance_test.go index 085de5ed2a5..e8d3ad4b21f 100644 --- a/acceptance/acceptance_test.go +++ b/acceptance/acceptance_test.go @@ -293,8 +293,8 @@ func testAccept(t *testing.T, inprocessMode bool, selectedTests []string, skipTo // from the host shell would move the venv the localenv tests expect. os.Unsetenv("UV_PROJECT_ENVIRONMENT") //nolint:usetesting // t.Setenv cannot unset - // Agent skills export DATABRICKS_SKILLS_INVOKED, so a host value would add - // the X-Databricks-Skills-Invoked header to recorded requests. + // Agent skills set DATABRICKS_SKILLS_INVOKED (experimental skill tracking), + // so a host value would add skill/ pairs to recorded user agents. os.Unsetenv("DATABRICKS_SKILLS_INVOKED") //nolint:usetesting // t.Setenv cannot unset if !requirePrerequisites(t) { diff --git a/acceptance/cmd/skills-invoked/output.txt b/acceptance/cmd/skills-invoked/output.txt index 235d5c1552d..6f17ed00b8a 100644 --- a/acceptance/cmd/skills-invoked/output.txt +++ b/acceptance/cmd/skills-invoked/output.txt @@ -1,116 +1,36 @@ -=== Env var sends the header on a workspace GET +=== Env var adds the skills to the user agent on a workspace GET >>> [CLI] current-user me >>> print_requests.py --get //scim/v2/Me -{ - "headers": { - "X-Databricks-Skills-Invoked": [ - "databricks-core,databricks:databricks-jobs" - ] - }, - "method": "GET", - "path": "/api/2.0/preview/scim/v2/Me" -} -=== Env var sends the header on a bundle-free GET - ->>> [CLI] clusters list - ->>> print_requests.py --get //clusters/list -{ - "headers": { - "X-Databricks-Skills-Invoked": [ - "databricks-core" - ] - }, - "method": "GET", - "path": "/api/2.1/clusters/list" -} - -=== Env var sends the header on databricks api +=== Env var adds the skills on databricks api >>> [CLI] api get /api/2.1/clusters/list >>> print_requests.py --get //clusters/list -{ - "headers": { - "X-Databricks-Skills-Invoked": [ - "databricks-core" - ] - }, - "method": "GET", - "path": "/api/2.1/clusters/list" -} - -=== Env var sends the header on the files API used by fs - ->>> [CLI] fs mkdir dbfs:/Volumes/main/default/vol - ->>> [CLI] fs ls dbfs:/Volumes/main/default/vol - ->>> print_requests.py --get //fs/directories -{ - "method": "PUT", - "path": "/api/2.0/fs/directories/Volumes/main/default/vol" -} -{ - "headers": { - "X-Databricks-Skills-Invoked": [ - "databricks-core" - ] - }, - "method": "GET", - "path": "/api/2.0/fs/directories/Volumes/main/default/vol" -} - -=== Env var sends the header from bundle commands + +=== Env var adds the skills from bundle commands >>> [CLI] bundle validate >>> print_requests.py --get //scim/v2/Me -{ - "headers": { - "X-Databricks-Skills-Invoked": [ - "databricks-core" - ] - }, - "method": "GET", - "path": "/api/2.0/preview/scim/v2/Me" -} === Invalid entries are dropped and the rest is normalized >>> [CLI] current-user me >>> print_requests.py --get //scim/v2/Me -{ - "headers": { - "X-Databricks-Skills-Invoked": [ - "databricks-core,databricks:databricks-jobs" - ] - }, - "method": "GET", - "path": "/api/2.0/preview/scim/v2/Me" -} - -=== No header when unset + +=== No skills when unset >>> [CLI] current-user me >>> print_requests.py --get //scim/v2/Me -{ - "method": "GET", - "path": "/api/2.0/preview/scim/v2/Me" -} -=== No header when telemetry is disabled +=== No skills when telemetry is disabled >>> [CLI] current-user me >>> print_requests.py --get //scim/v2/Me -{ - "method": "GET", - "path": "/api/2.0/preview/scim/v2/Me" -} diff --git a/acceptance/cmd/skills-invoked/script b/acceptance/cmd/skills-invoked/script index 5b27e1293c3..b5635f0a135 100644 --- a/acceptance/cmd/skills-invoked/script +++ b/acceptance/cmd/skills-invoked/script @@ -1,32 +1,26 @@ -title "Env var sends the header on a workspace GET" -DATABRICKS_SKILLS_INVOKED=databricks-core,databricks:databricks-jobs trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me +# Experimental skill-usage tracking: DATABRICKS_SKILLS_INVOKED adds skill/ pairs to the user agent. +# Only the pairs are asserted; the rest of the user agent varies by machine. -title "Env var sends the header on a bundle-free GET" -DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI clusters list > /dev/null -trace print_requests.py --get //clusters/list +title "Env var adds the skills to the user agent on a workspace GET" +DATABRICKS_SKILLS_INVOKED=databricks-core,databricks-jobs trace $CLI current-user me > /dev/null +trace print_requests.py --get //scim/v2/Me | contains.py " skill/databricks-core skill/databricks-jobs" > /dev/null -title "Env var sends the header on databricks api" +title "Env var adds the skills on databricks api" DATABRICKS_SKILLS_INVOKED=databricks-core MSYS_NO_PATHCONV=1 trace $CLI api get /api/2.1/clusters/list > /dev/null -trace print_requests.py --get //clusters/list +trace print_requests.py --get //clusters/list | contains.py " skill/databricks-core" > /dev/null -title "Env var sends the header on the files API used by fs" -trace $CLI fs mkdir dbfs:/Volumes/main/default/vol -DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI fs ls dbfs:/Volumes/main/default/vol > /dev/null -trace print_requests.py --get //fs/directories - -title "Env var sends the header from bundle commands" -DATABRICKS_SKILLS_INVOKED=databricks-core trace $CLI bundle validate > /dev/null -trace print_requests.py --get //scim/v2/Me +title "Env var adds the skills from bundle commands" +DATABRICKS_SKILLS_INVOKED=databricks-dabs trace $CLI bundle validate > /dev/null +trace print_requests.py --get //scim/v2/Me | contains.py " skill/databricks-dabs" > /dev/null title "Invalid entries are dropped and the rest is normalized" DATABRICKS_SKILLS_INVOKED=' Databricks-Core , bad name!,,databricks-core,databricks:databricks-jobs ' trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me +trace print_requests.py --get //scim/v2/Me | contains.py " skill/databricks-core" "!skill/databricks-core skill/" "!bad" "!databricks:" > /dev/null -title "No header when unset" +title "No skills when unset" trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me | contains.py "!X-Databricks-Skills-Invoked" +trace print_requests.py --get //scim/v2/Me | contains.py "!skill/" > /dev/null -title "No header when telemetry is disabled" +title "No skills when telemetry is disabled" DATABRICKS_SKILLS_INVOKED=databricks-core DATABRICKS_CLI_DISABLE_TELEMETRY=1 trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me | contains.py "!X-Databricks-Skills-Invoked" +trace print_requests.py --get //scim/v2/Me | contains.py "!skill/" > /dev/null diff --git a/acceptance/cmd/skills-invoked/test.toml b/acceptance/cmd/skills-invoked/test.toml index bacd40cc189..a92f32d6760 100644 --- a/acceptance/cmd/skills-invoked/test.toml +++ b/acceptance/cmd/skills-invoked/test.toml @@ -1,3 +1,3 @@ RecordRequests = true -IncludeRequestHeaders = ["X-Databricks-Skills-Invoked"] +IncludeRequestHeaders = ["User-Agent"] Ignore = [".databricks"] diff --git a/bundle/config/workspace.go b/bundle/config/workspace.go index 9636cdd3ce5..bed0d0bf69d 100644 --- a/bundle/config/workspace.go +++ b/bundle/config/workspace.go @@ -8,7 +8,6 @@ import ( "github.com/databricks/cli/libs/auth" "github.com/databricks/cli/libs/databrickscfg" "github.com/databricks/cli/libs/liteswap" - "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/databricks-sdk-go/marshal" @@ -174,7 +173,6 @@ func (w *Workspace) Config(ctx context.Context) *config.Config { WorkspaceID: w.WorkspaceID, } liteswap.Apply(ctx, cfg) - skillsinvoked.Apply(cfg) for k := range config.ConfigAttributes { attr := &config.ConfigAttributes[k] diff --git a/cmd/api/api.go b/cmd/api/api.go index 61df220d3c3..2caf2ccb95d 100644 --- a/cmd/api/api.go +++ b/cmd/api/api.go @@ -18,7 +18,6 @@ import ( "github.com/databricks/cli/libs/databrickscfg/profile" "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/flags" - "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go/client" "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" @@ -106,7 +105,6 @@ func makeCommand(method string) *cobra.Command { // Skips the default profile when DATABRICKS_HOST is set (#5616). root.ResolveDefaultProfile(cmd.Context(), cfg) - skillsinvoked.Apply(cfg) api, err := client.New(cfg) if err != nil { return err diff --git a/cmd/auth/profiles.go b/cmd/auth/profiles.go index 2c03e68b17c..e65b11371b7 100644 --- a/cmd/auth/profiles.go +++ b/cmd/auth/profiles.go @@ -14,7 +14,6 @@ import ( "github.com/databricks/cli/libs/databrickscfg/profile" "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/log" - "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/databricks-sdk-go/service/iam" @@ -61,7 +60,6 @@ func (c *profileMetadata) Load(ctx context.Context, configFilePath string, skipV HTTPTimeoutSeconds: timeoutSeconds, RetryTimeoutSeconds: timeoutSeconds, } - skillsinvoked.Apply(cfg) if skipValidate { // EnsureResolved fetches /.well-known/databricks-config to enrich // the config, so without this stub a skip-validate listing still makes diff --git a/cmd/root/auth.go b/cmd/root/auth.go index 3fe68aa3709..d7eae4ec0f1 100644 --- a/cmd/root/auth.go +++ b/cmd/root/auth.go @@ -15,7 +15,6 @@ import ( "github.com/databricks/cli/libs/liteswap" "github.com/databricks/cli/libs/log" "github.com/databricks/cli/libs/logdiag" - "github.com/databricks/cli/libs/skillsinvoked" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" @@ -175,9 +174,7 @@ func accountClientOrPrompt(ctx context.Context, cfg *config.Config, allowPrompt // The picked profile resolves into its own config, not the caller's cfg. // Return the client (even on failure) so the caller renders errors against // that config rather than the original, otherwise-empty one. - pcfg := &config.Config{Profile: profile} - skillsinvoked.Apply(pcfg) - a, err = databricks.NewAccountClient((*databricks.Config)(pcfg)) + a, err = databricks.NewAccountClient(&databricks.Config{Profile: profile}) if err == nil { err = a.Config.Authenticate(emptyHttpRequest(ctx)) } @@ -242,7 +239,6 @@ func MustAccountClient(cmd *cobra.Command, args []string) error { cfg.Credentials = auth.CredentialsWithoutRefresh() } liteswap.Apply(ctx, cfg) - skillsinvoked.Apply(cfg) bindHostMetadataLogger(ctx, cfg) // The command-line profile flag takes precedence over DATABRICKS_CONFIG_PROFILE. @@ -360,9 +356,7 @@ func workspaceClientOrPrompt(ctx context.Context, cfg *config.Config, allowPromp // The picked profile resolves into its own config, not the caller's cfg. // Return the client (even on failure) so the caller renders errors against // that config rather than the original, otherwise-empty one. - pcfg := &config.Config{Profile: profile} - skillsinvoked.Apply(pcfg) - w, err = databricks.NewWorkspaceClient((*databricks.Config)(pcfg)) + w, err = databricks.NewWorkspaceClient(&databricks.Config{Profile: profile}) if err == nil { err = w.Config.Authenticate(emptyHttpRequest(ctx)) } @@ -378,7 +372,6 @@ func MustWorkspaceClient(cmd *cobra.Command, args []string) error { cfg.Credentials = auth.CredentialsWithoutRefresh() } liteswap.Apply(ctx, cfg) - skillsinvoked.Apply(cfg) bindHostMetadataLogger(ctx, cfg) // The command-line profile flag takes precedence over DATABRICKS_CONFIG_PROFILE. diff --git a/cmd/root/root.go b/cmd/root/root.go index 2e9e1c3dbd2..0f1c9a90515 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -88,7 +88,7 @@ func newRootCommand(ctx context.Context) *cobra.Command { ctx = installer.WithAiDevKitInUserAgent(ctx) ctx = installer.WithCallingAgentToolingInUserAgent(ctx) ctx = InjectTestPidToUserAgent(ctx) - ctx = withSkillsInvoked(ctx) + ctx = withSkillsInUserAgent(ctx) cmd.SetContext(ctx) // Recommend installing Databricks AI tooling to the calling coding agent diff --git a/cmd/root/skills_invoked.go b/cmd/root/skills_invoked.go deleted file mode 100644 index ffc20878fc0..00000000000 --- a/cmd/root/skills_invoked.go +++ /dev/null @@ -1,23 +0,0 @@ -package root - -import ( - "context" - - "github.com/databricks/cli/libs/env" - "github.com/databricks/cli/libs/skillsinvoked" - "github.com/databricks/cli/libs/telemetry" -) - -// envSkillsInvoked is an env var rather than a flag so it can be removed -// without breaking the CLI's interface, and because older CLIs ignore unknown -// env vars but reject unknown flags. -const envSkillsInvoked = "DATABRICKS_SKILLS_INVOKED" - -// withSkillsInvoked stores the skills from envSkillsInvoked in ctx, unless the -// user opted out of telemetry. -func withSkillsInvoked(ctx context.Context) context.Context { - if telemetry.Disabled(ctx) { - return ctx - } - return skillsinvoked.WithSkills(ctx, skillsinvoked.Parse(ctx, env.Get(ctx, envSkillsInvoked))) -} diff --git a/cmd/root/skills_invoked_test.go b/cmd/root/skills_invoked_test.go deleted file mode 100644 index a635e0eff7a..00000000000 --- a/cmd/root/skills_invoked_test.go +++ /dev/null @@ -1,30 +0,0 @@ -package root - -import ( - "testing" - - "github.com/databricks/cli/libs/env" - "github.com/databricks/cli/libs/skillsinvoked" - "github.com/stretchr/testify/assert" -) - -func TestWithSkillsInvoked(t *testing.T) { - tests := []struct { - name string - skills string - disableTelemetry string - want []string - }{ - {"unset", "", "", nil}, - {"set", "databricks-core,databricks-jobs", "", []string{"databricks-core", "databricks-jobs"}}, - {"telemetry disabled", "databricks-core", "1", nil}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - // Always set both: an empty value in the context overrides the host environment. - ctx := env.Set(t.Context(), envSkillsInvoked, tt.skills) - ctx = env.Set(ctx, "DATABRICKS_CLI_DISABLE_TELEMETRY", tt.disableTelemetry) - assert.Equal(t, tt.want, skillsinvoked.FromContext(withSkillsInvoked(ctx))) - }) - } -} diff --git a/cmd/root/user_agent_skills.go b/cmd/root/user_agent_skills.go new file mode 100644 index 00000000000..1d1fcff0062 --- /dev/null +++ b/cmd/root/user_agent_skills.go @@ -0,0 +1,72 @@ +package root + +import ( + "context" + "regexp" + "slices" + "strings" + "sync" + + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/log" + "github.com/databricks/cli/libs/telemetry" + "github.com/databricks/databricks-sdk-go/useragent" +) + +// Experimental skill-usage tracking: agent skills prefix CLI calls with this +// env var so their names reach the user agent. It may change or be removed +// without notice. It is an env var rather than a flag so removing it doesn't +// change the CLI's interface, and because older CLIs ignore unknown env vars +// but reject unknown flags. +const skillsInvokedEnvVar = "DATABRICKS_SKILLS_INVOKED" + +// skillUserAgentKey is repeated once per skill: "skill/databricks-core skill/databricks-jobs". +const skillUserAgentKey = "skill" + +const ( + maxSkills = 20 + maxSkillLength = 64 +) + +// skillNamePattern is a subset of what the SDK accepts in a user agent value, +// so a valid name can never make useragent.InContext panic. +var skillNamePattern = sync.OnceValue(func() *regexp.Regexp { + return regexp.MustCompile(`^[a-z0-9][a-z0-9_.-]*$`) +}) + +// parseSkills normalizes a comma-separated list of skill names: entries are +// trimmed, lowercased and deduplicated, invalid ones are dropped, and at most +// maxSkills are kept. Invalid input is only logged at debug level because this +// is telemetry and must never fail or warn a command. +func parseSkills(ctx context.Context, raw string) []string { + var skills []string + for entry := range strings.SplitSeq(raw, ",") { + name := strings.ToLower(strings.TrimSpace(entry)) + switch { + case name == "": + case len(name) > maxSkillLength || !skillNamePattern().MatchString(name): + log.Debugf(ctx, "dropping invalid %s entry %q", skillsInvokedEnvVar, entry) + case slices.Contains(skills, name): + case len(skills) == maxSkills: + log.Debugf(ctx, "dropping %s entry %q: more than %d skills", skillsInvokedEnvVar, name, maxSkills) + default: + skills = append(skills, name) + } + } + return skills +} + +// withSkillsInUserAgent adds one skill/ pair per skill in +// skillsInvokedEnvVar (experimental tracking), unless the user opted out of +// telemetry. +func withSkillsInUserAgent(ctx context.Context) context.Context { + if telemetry.Disabled(ctx) { + return ctx + } + for _, skill := range parseSkills(ctx, env.Get(ctx, skillsInvokedEnvVar)) { + // Each skill adds its own pair to the same context; this is accumulation, + // not the accidental nesting fatcontext flags. + ctx = useragent.InContext(ctx, skillUserAgentKey, skill) //nolint:fatcontext + } + return ctx +} diff --git a/cmd/root/user_agent_skills_test.go b/cmd/root/user_agent_skills_test.go new file mode 100644 index 00000000000..2f3ab3d9699 --- /dev/null +++ b/cmd/root/user_agent_skills_test.go @@ -0,0 +1,72 @@ +package root + +import ( + "strings" + "testing" + + "github.com/databricks/cli/libs/env" + "github.com/databricks/databricks-sdk-go/useragent" + "github.com/stretchr/testify/assert" +) + +func TestParseSkills(t *testing.T) { + tests := []struct { + name string + raw string + want []string + }{ + {"empty", "", nil}, + {"single", "databricks-core", []string{"databricks-core"}}, + {"multiple", "a,b,c", []string{"a", "b", "c"}}, + {"trims and lowercases", " Databricks-Core , JOBS ", []string{"databricks-core", "jobs"}}, + {"drops empty entries", ",,a,,", []string{"a"}}, + {"allows underscore and dot", "a_b.c-d", []string{"a_b.c-d"}}, + {"drops characters the user agent rejects", "ok,bad name,a:b,a/b,a+b", []string{"ok"}}, + {"drops leading punctuation", "-a,.b,_c", nil}, + {"dedupes preserving first occurrence", "b,a,b,a,c", []string{"b", "a", "c"}}, + {"dedupes after normalization", "Core,core, CORE", []string{"core"}}, + {"drops entry longer than 64 bytes", strings.Repeat("a", 65) + ",ok", []string{"ok"}}, + {"keeps entry of exactly 64 bytes", strings.Repeat("a", 64), []string{strings.Repeat("a", 64)}}, + {"caps at 20 entries", strings.Join(skillNames(25), ","), skillNames(20)}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + assert.Equal(t, tt.want, parseSkills(t.Context(), tt.raw)) + }) + } +} + +// skillNames returns n distinct valid skill names. +func skillNames(n int) []string { + names := make([]string, 0, n) + for i := range n { + names = append(names, "skill"+strings.Repeat("x", i)) + } + return names +} + +func TestWithSkillsInUserAgent(t *testing.T) { + tests := []struct { + name string + skills string + disableTelemetry string + want string + }{ + {"unset", "", "", ""}, + {"set", "databricks-core,databricks-jobs", "", "skill/databricks-core skill/databricks-jobs"}, + {"telemetry disabled", "databricks-core", "1", ""}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Always set both: an empty value in the context overrides the host environment. + ctx := env.Set(t.Context(), skillsInvokedEnvVar, tt.skills) + ctx = env.Set(ctx, "DATABRICKS_CLI_DISABLE_TELEMETRY", tt.disableTelemetry) + ua := useragent.FromContext(withSkillsInUserAgent(ctx)) + if tt.want == "" { + assert.NotContains(t, ua, "skill/") + } else { + assert.Contains(t, ua, tt.want) + } + }) + } +} diff --git a/experimental/ssh/internal/client/releases.go b/experimental/ssh/internal/client/releases.go index da6b116dfc8..def34ce363c 100644 --- a/experimental/ssh/internal/client/releases.go +++ b/experimental/ssh/internal/client/releases.go @@ -69,8 +69,6 @@ func newHTTP11WorkspaceClient(src *config.Config) (*databricks.WorkspaceClient, } } cfg.HTTPTransport = newHTTP11Transport(src) - // Headers is a func, not a config attribute, so the loop above doesn't copy it. - cfg.Headers = src.Headers return databricks.NewWorkspaceClient((*databricks.Config)(cfg)) } diff --git a/libs/filer/files_client.go b/libs/filer/files_client.go index 289cc0710fe..25f8e8de344 100644 --- a/libs/filer/files_client.go +++ b/libs/filer/files_client.go @@ -239,24 +239,6 @@ func newTransferClient(n int) *http.Client { return &http.Client{Transport: transport} } -// headersTransport applies a config.Config.Headers hook to each request. -type headersTransport struct { - base http.RoundTripper - headers func(*http.Request) error -} - -func (t headersTransport) RoundTrip(r *http.Request) (*http.Response, error) { - if t.headers == nil { - return t.base.RoundTrip(r) - } - // A RoundTripper must not modify the caller's request. - r = r.Clone(r.Context()) - if err := t.headers(r); err != nil { - return nil, err - } - return t.base.RoundTrip(r) -} - // newFilesAPIClient builds the files/v2 client from the CLI's already resolved // config, reusing its auth instead of re-reading a profile. cfg is passed by // pointer because config.Config embeds a sync.Mutex and must not be copied. @@ -266,9 +248,6 @@ func newFilesAPIClient(ctx context.Context, cfg *config.Config) (*files.Client, client.WithCredentials(configCredentials{cfg: cfg}), client.WithoutConfigFile(), client.WithoutEnv(), - // files/v2 doesn't call cfg.Headers, so apply it in the transport. - // http.DefaultTransport is what files/v2 uses by default. - client.WithHTTPClient(&http.Client{Transport: headersTransport{base: http.DefaultTransport, headers: cfg.Headers}}), } // The workspace routing header is needed on unified ("SPOG") hosts; the CLI's // "none" sentinel means "no workspace ID", so it is not forwarded. diff --git a/libs/filer/files_client_test.go b/libs/filer/files_client_test.go index 8810a295fbd..0d621d3e542 100644 --- a/libs/filer/files_client_test.go +++ b/libs/filer/files_client_test.go @@ -6,7 +6,6 @@ import ( "fmt" "io" "io/fs" - "net/http" "os" "path/filepath" "strings" @@ -19,7 +18,6 @@ import ( "github.com/databricks/cli/libs/env" "github.com/databricks/cli/libs/testserver" "github.com/databricks/databricks-sdk-go" - "github.com/databricks/databricks-sdk-go/config" "github.com/databricks/sdk-go/core/ops" files "github.com/databricks/sdk-go/files/v2" "github.com/stretchr/testify/assert" @@ -339,51 +337,3 @@ func TestFilesClientStopsRetryingAfterLimit(t *testing.T) { assert.ErrorContains(t, err, "AWS S3 is throttling requests") assert.Equal(t, filesMaxRetries+1, requests) } - -type roundTripFunc func(*http.Request) (*http.Response, error) - -func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { - return f(r) -} - -func TestHeadersTransport(t *testing.T) { - tests := []struct { - name string - headers func(*http.Request) error - want string - }{ - {"no hook", nil, ""}, - {"hook sets header", config.StaticHeaders(map[string]string{"X-Test": "1"}), "1"}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - var sent *http.Request - base := roundTripFunc(func(r *http.Request) (*http.Response, error) { - sent = r - return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil - }) - req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api/2.0/fs/files", nil) - require.NoError(t, err) - - resp, err := headersTransport{base: base, headers: tt.headers}.RoundTrip(req) - require.NoError(t, err) - resp.Body.Close() - - assert.Equal(t, tt.want, sent.Header.Get("X-Test")) - assert.Empty(t, req.Header.Values("X-Test"), "caller's request must not be modified") - }) - } -} - -func TestHeadersTransportReturnsHookError(t *testing.T) { - base := roundTripFunc(func(r *http.Request) (*http.Response, error) { - t.Fatal("base transport must not be called") - return nil, nil - }) - req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api", nil) - require.NoError(t, err) - - resp, err := headersTransport{base: base, headers: func(*http.Request) error { return errors.New("boom") }}.RoundTrip(req) //nolint:bodyclose // no response on error - assert.Nil(t, resp) - assert.EqualError(t, err, "boom") -} diff --git a/libs/skillsinvoked/skills.go b/libs/skillsinvoked/skills.go deleted file mode 100644 index c2ccbaec26f..00000000000 --- a/libs/skillsinvoked/skills.go +++ /dev/null @@ -1,91 +0,0 @@ -// Package skillsinvoked sends the agent skills that drove a CLI call to -// Databricks in the X-Databricks-Skills-Invoked header. -package skillsinvoked - -import ( - "context" - "net/http" - "regexp" - "slices" - "strings" - "sync" - - "github.com/databricks/cli/libs/log" - "github.com/databricks/databricks-sdk-go/config" -) - -// Header lists the skills that drove the call. -const Header = "X-Databricks-Skills-Invoked" - -const ( - maxSkills = 20 - maxSkillLength = 64 - // The HTTP access log truncates the header at 1024 bytes, so stop before - // that rather than log a partial name. - maxHeaderLength = 1024 -) - -// skillNamePattern also allows plugin-scoped names such as "databricks:databricks-core". -var skillNamePattern = sync.OnceValue(func() *regexp.Regexp { - return regexp.MustCompile(`^[a-z0-9][a-z0-9_.:-]*$`) -}) - -type skillsKey struct{} - -// Parse normalizes a comma-separated list of skill names: entries are trimmed, -// lowercased and deduplicated, invalid ones are dropped, and at most maxSkills -// are kept, joining to at most maxHeaderLength bytes. Invalid input is only -// logged at debug level because this is telemetry and must never fail or warn -// a command. -func Parse(ctx context.Context, raw string) []string { - var skills []string - size := 0 - for entry := range strings.SplitSeq(raw, ",") { - name := strings.ToLower(strings.TrimSpace(entry)) - added := len(name) - if len(skills) > 0 { - added++ // comma separator - } - switch { - case name == "": - case len(name) > maxSkillLength || !skillNamePattern().MatchString(name): - log.Debugf(ctx, "dropping invalid skills-invoked entry %q", entry) - case slices.Contains(skills, name): - case len(skills) == maxSkills || size+added > maxHeaderLength: - log.Debugf(ctx, "dropping skills-invoked entry %q: over %d skills or %d bytes", name, maxSkills, maxHeaderLength) - default: - skills = append(skills, name) - size += added - } - } - return skills -} - -// WithSkills returns a context that carries the skills that drove the command. -func WithSkills(ctx context.Context, skills []string) context.Context { - return context.WithValue(ctx, skillsKey{}, skills) -} - -// FromContext returns the skills stored by WithSkills. -func FromContext(ctx context.Context) []string { - skills, _ := ctx.Value(skillsKey{}).([]string) - return skills -} - -// Apply sets the header on every request made with cfg, keeping any header -// hook already on cfg (such as liteswap's). The value comes from the request -// context, so it is only sent when the command context reaches the request. -func Apply(cfg *config.Config) { - prev := cfg.Headers - cfg.Headers = func(r *http.Request) error { - if prev != nil { - if err := prev(r); err != nil { - return err - } - } - if skills := FromContext(r.Context()); len(skills) > 0 { - r.Header.Set(Header, strings.Join(skills, ",")) - } - return nil - } -} diff --git a/libs/skillsinvoked/skills_test.go b/libs/skillsinvoked/skills_test.go deleted file mode 100644 index 7a80c057f52..00000000000 --- a/libs/skillsinvoked/skills_test.go +++ /dev/null @@ -1,93 +0,0 @@ -package skillsinvoked - -import ( - "fmt" - "net/http" - "strings" - "testing" - - "github.com/databricks/databricks-sdk-go/config" - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" -) - -func TestParse(t *testing.T) { - tests := []struct { - name string - raw string - want []string - }{ - {"empty", "", nil}, - {"single", "databricks-core", []string{"databricks-core"}}, - {"multiple", "a,b,c", []string{"a", "b", "c"}}, - {"trims and lowercases", " Databricks-Core , JOBS ", []string{"databricks-core", "jobs"}}, - {"drops empty entries", ",,a,,", []string{"a"}}, - {"plugin scoped name", "databricks:databricks-core", []string{"databricks:databricks-core"}}, - {"allows underscore dot and colon", "a_b.c:d-e", []string{"a_b.c:d-e"}}, - {"drops invalid characters", "ok,bad name,semi;colon,a/b", []string{"ok"}}, - {"drops leading punctuation", "-a,.b,:c,_d", nil}, - {"dedupes preserving first occurrence", "b,a,b,a,c", []string{"b", "a", "c"}}, - {"dedupes after normalization", "Core,core, CORE", []string{"core"}}, - {"drops entry longer than 64 bytes", strings.Repeat("a", 65) + ",ok", []string{"ok"}}, - {"keeps entry of exactly 64 bytes", strings.Repeat("a", 64), []string{strings.Repeat("a", 64)}}, - {"caps at 20 entries", strings.Join(skillNames(25), ","), skillNames(20)}, - {"caps joined length at 1024 bytes", strings.Join(longNames(20), ","), longNames(15)}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - assert.Equal(t, tt.want, Parse(t.Context(), tt.raw)) - }) - } -} - -// skillNames returns n distinct valid skill names. -func skillNames(n int) []string { - names := make([]string, 0, n) - for i := range n { - names = append(names, "skill"+strings.Repeat("x", i)) - } - return names -} - -// longNames returns n distinct 64-byte skill names; 15 of them join to 974 -// bytes and a 16th would make 1039. -func longNames(n int) []string { - names := make([]string, 0, n) - for i := range n { - names = append(names, fmt.Sprintf("%02d", i)+strings.Repeat("x", maxSkillLength-2)) - } - return names -} - -func TestApplySetsHeaderFromContext(t *testing.T) { - cfg := &config.Config{} - Apply(cfg) - - ctx := WithSkills(t.Context(), []string{"a", "b"}) - req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api", nil) - require.NoError(t, err) - require.NoError(t, cfg.Headers(req)) - assert.Equal(t, "a,b", req.Header.Get(Header)) -} - -func TestApplyNoHeaderWhenEmpty(t *testing.T) { - cfg := &config.Config{} - Apply(cfg) - - req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "https://example.test/api", nil) - require.NoError(t, err) - require.NoError(t, cfg.Headers(req)) - assert.Empty(t, req.Header.Values(Header)) -} - -func TestApplyKeepsExistingHeaders(t *testing.T) { - cfg := &config.Config{Headers: config.StaticHeaders(map[string]string{"X-Other": "1"})} - Apply(cfg) - - ctx := WithSkills(t.Context(), []string{"a"}) - req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.test/api", nil) - require.NoError(t, err) - require.NoError(t, cfg.Headers(req)) - assert.Equal(t, "1", req.Header.Get("X-Other")) - assert.Equal(t, "a", req.Header.Get(Header)) -} From d6888e287fe76d100e5aea6f2e135b492ac0badb Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Wed, 18 Nov 2026 14:19:01 +0000 Subject: [PATCH 7/8] Bound skill user-agent pairs to 128 bytes and tidy the tests The usage logs that feed skill analytics cap the user agent at 512 characters, and the SDK appends auth/, agent/ and other pairs after the skills. Replace the 20-skill cap with a 128-byte budget for all " skill/" pairs so those pairs survive, with boundary tests. Also: - Link the databricks-core skill that sets DATABRICKS_SKILLS_INVOKED. - Move the unit tests to package root_test via export_test.go, and rename the disallowed-characters case. - Acceptance: pin DATABRICKS_CLI_DISABLE_TELEMETRY empty so a host opt-out can't hide the skills, and keep request dumps in LOG.* files. Co-authored-by: Isaac --- acceptance/cmd/skills-invoked/script | 21 ++++++---- acceptance/cmd/skills-invoked/test.toml | 2 + cmd/root/export_test.go | 8 ++++ cmd/root/user_agent_skills.go | 30 +++++++++----- cmd/root/user_agent_skills_test.go | 53 ++++++++++++++++++------- 5 files changed, 82 insertions(+), 32 deletions(-) diff --git a/acceptance/cmd/skills-invoked/script b/acceptance/cmd/skills-invoked/script index b5635f0a135..12c530226a1 100644 --- a/acceptance/cmd/skills-invoked/script +++ b/acceptance/cmd/skills-invoked/script @@ -1,26 +1,33 @@ # Experimental skill-usage tracking: DATABRICKS_SKILLS_INVOKED adds skill/ pairs to the user agent. -# Only the pairs are asserted; the rest of the user agent varies by machine. +# The rest of the user agent varies by machine, so each request dump goes to a LOG.* file (kept for +# diagnosis, excluded from the diff) and only the pairs are asserted. title "Env var adds the skills to the user agent on a workspace GET" DATABRICKS_SKILLS_INVOKED=databricks-core,databricks-jobs trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me | contains.py " skill/databricks-core skill/databricks-jobs" > /dev/null +trace print_requests.py --get //scim/v2/Me > LOG.me +contains.py " skill/databricks-core skill/databricks-jobs" < LOG.me > /dev/null title "Env var adds the skills on databricks api" DATABRICKS_SKILLS_INVOKED=databricks-core MSYS_NO_PATHCONV=1 trace $CLI api get /api/2.1/clusters/list > /dev/null -trace print_requests.py --get //clusters/list | contains.py " skill/databricks-core" > /dev/null +trace print_requests.py --get //clusters/list > LOG.api +contains.py " skill/databricks-core" < LOG.api > /dev/null title "Env var adds the skills from bundle commands" DATABRICKS_SKILLS_INVOKED=databricks-dabs trace $CLI bundle validate > /dev/null -trace print_requests.py --get //scim/v2/Me | contains.py " skill/databricks-dabs" > /dev/null +trace print_requests.py --get //scim/v2/Me > LOG.bundle +contains.py " skill/databricks-dabs" < LOG.bundle > /dev/null title "Invalid entries are dropped and the rest is normalized" DATABRICKS_SKILLS_INVOKED=' Databricks-Core , bad name!,,databricks-core,databricks:databricks-jobs ' trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me | contains.py " skill/databricks-core" "!skill/databricks-core skill/" "!bad" "!databricks:" > /dev/null +trace print_requests.py --get //scim/v2/Me > LOG.normalized +contains.py " skill/databricks-core" "!skill/databricks-core skill/" "!bad" "!databricks:" < LOG.normalized > /dev/null title "No skills when unset" trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me | contains.py "!skill/" > /dev/null +trace print_requests.py --get //scim/v2/Me > LOG.unset +contains.py "!skill/" < LOG.unset > /dev/null title "No skills when telemetry is disabled" DATABRICKS_SKILLS_INVOKED=databricks-core DATABRICKS_CLI_DISABLE_TELEMETRY=1 trace $CLI current-user me > /dev/null -trace print_requests.py --get //scim/v2/Me | contains.py "!skill/" > /dev/null +trace print_requests.py --get //scim/v2/Me > LOG.disabled +contains.py "!skill/" < LOG.disabled > /dev/null diff --git a/acceptance/cmd/skills-invoked/test.toml b/acceptance/cmd/skills-invoked/test.toml index a92f32d6760..20c9a4261c6 100644 --- a/acceptance/cmd/skills-invoked/test.toml +++ b/acceptance/cmd/skills-invoked/test.toml @@ -1,3 +1,5 @@ RecordRequests = true IncludeRequestHeaders = ["User-Agent"] Ignore = [".databricks"] +# A host opt-out would otherwise remove the skills the positive cases assert. +Env.DATABRICKS_CLI_DISABLE_TELEMETRY = "" diff --git a/cmd/root/export_test.go b/cmd/root/export_test.go index c5142696dde..b220e086b90 100644 --- a/cmd/root/export_test.go +++ b/cmd/root/export_test.go @@ -6,6 +6,14 @@ import ( "github.com/spf13/cobra" ) +// Experimental skill-usage tracking, see user_agent_skills.go. +var ( + ParseSkills = parseSkills + WithSkillsInUserAgent = withSkillsInUserAgent + SkillsInvokedEnvVar = skillsInvokedEnvVar + MaxSkillsUserAgentLength = maxSkillsUserAgentLength +) + // BuildAll builds every command in t and returns the root command, for tests // that walk the whole tree. func BuildAll(ctx context.Context, t *Tree) *cobra.Command { diff --git a/cmd/root/user_agent_skills.go b/cmd/root/user_agent_skills.go index 1d1fcff0062..5e726a13696 100644 --- a/cmd/root/user_agent_skills.go +++ b/cmd/root/user_agent_skills.go @@ -13,19 +13,26 @@ import ( "github.com/databricks/databricks-sdk-go/useragent" ) -// Experimental skill-usage tracking: agent skills prefix CLI calls with this -// env var so their names reach the user agent. It may change or be removed -// without notice. It is an env var rather than a flag so removing it doesn't -// change the CLI's interface, and because older CLIs ignore unknown env vars -// but reject unknown flags. +// Experimental skill-usage tracking: the databricks-core agent skill +// (https://github.com/databricks/databricks-agent-skills/tree/main/skills/databricks-core) +// tells agents to prefix CLI calls with this env var, set to the comma-separated +// bare names of the skills they loaded. It may change or be removed without +// notice. It is an env var rather than a flag so removing it doesn't change the +// CLI's interface, and because older CLIs ignore unknown env vars but reject +// unknown flags. const skillsInvokedEnvVar = "DATABRICKS_SKILLS_INVOKED" // skillUserAgentKey is repeated once per skill: "skill/databricks-core skill/databricks-jobs". const skillUserAgentKey = "skill" const ( - maxSkills = 20 maxSkillLength = 64 + + // maxSkillsUserAgentLength bounds all " skill/" pairs together. The + // usage logs that feed skill analytics cap the user agent at 512 characters, + // and the SDK appends auth/, agent/ and other pairs after these, so the + // skills must leave room for them. + maxSkillsUserAgentLength = 128 ) // skillNamePattern is a subset of what the SDK accepts in a user agent value, @@ -35,22 +42,25 @@ var skillNamePattern = sync.OnceValue(func() *regexp.Regexp { }) // parseSkills normalizes a comma-separated list of skill names: entries are -// trimmed, lowercased and deduplicated, invalid ones are dropped, and at most -// maxSkills are kept. Invalid input is only logged at debug level because this +// trimmed, lowercased and deduplicated, invalid ones are dropped, and names are +// kept in order while their pairs fit in maxSkillsUserAgentLength. Invalid input is only logged at debug level because this // is telemetry and must never fail or warn a command. func parseSkills(ctx context.Context, raw string) []string { var skills []string + size := 0 for entry := range strings.SplitSeq(raw, ",") { name := strings.ToLower(strings.TrimSpace(entry)) + pairSize := len(" "+skillUserAgentKey+"/") + len(name) switch { case name == "": case len(name) > maxSkillLength || !skillNamePattern().MatchString(name): log.Debugf(ctx, "dropping invalid %s entry %q", skillsInvokedEnvVar, entry) case slices.Contains(skills, name): - case len(skills) == maxSkills: - log.Debugf(ctx, "dropping %s entry %q: more than %d skills", skillsInvokedEnvVar, name, maxSkills) + case size+pairSize > maxSkillsUserAgentLength: + log.Debugf(ctx, "dropping %s entry %q: skills exceed %d user agent bytes", skillsInvokedEnvVar, name, maxSkillsUserAgentLength) default: skills = append(skills, name) + size += pairSize } } return skills diff --git a/cmd/root/user_agent_skills_test.go b/cmd/root/user_agent_skills_test.go index 2f3ab3d9699..39f1bf73a39 100644 --- a/cmd/root/user_agent_skills_test.go +++ b/cmd/root/user_agent_skills_test.go @@ -1,15 +1,43 @@ -package root +package root_test import ( + "fmt" "strings" "testing" + "github.com/databricks/cli/cmd/root" "github.com/databricks/cli/libs/env" "github.com/databricks/databricks-sdk-go/useragent" "github.com/stretchr/testify/assert" ) +// skillNames returns n distinct skill names of exactly length bytes. +func skillNames(n, length int) []string { + names := make([]string, 0, n) + for i := range n { + prefix := fmt.Sprintf("s%02d", i) + names = append(names, prefix+strings.Repeat("x", length-len(prefix))) + } + return names +} + +// pairsSize is the length of " skill/" for every name. +func pairsSize(names []string) int { + size := 0 + for _, name := range names { + size += len(" skill/") + len(name) + } + return size +} + func TestParseSkills(t *testing.T) { + // 22-byte names make 29-byte pairs: four fill 116 bytes, a fifth would make 145. + fourFit := skillNames(4, 22) + fiveTooMany := skillNames(5, 22) + // 57- and 49-byte names make 64- and 56-byte pairs (120 bytes), so " skill/c" + // lands exactly on 128 and nothing more fits. + exact := []string{strings.Repeat("a", 57), strings.Repeat("b", 49), "c"} + tests := []struct { name string raw string @@ -21,30 +49,25 @@ func TestParseSkills(t *testing.T) { {"trims and lowercases", " Databricks-Core , JOBS ", []string{"databricks-core", "jobs"}}, {"drops empty entries", ",,a,,", []string{"a"}}, {"allows underscore and dot", "a_b.c-d", []string{"a_b.c-d"}}, - {"drops characters the user agent rejects", "ok,bad name,a:b,a/b,a+b", []string{"ok"}}, + {"drops disallowed skill-name characters", "ok,bad name,a:b,a/b,a+b", []string{"ok"}}, {"drops leading punctuation", "-a,.b,_c", nil}, {"dedupes preserving first occurrence", "b,a,b,a,c", []string{"b", "a", "c"}}, {"dedupes after normalization", "Core,core, CORE", []string{"core"}}, {"drops entry longer than 64 bytes", strings.Repeat("a", 65) + ",ok", []string{"ok"}}, {"keeps entry of exactly 64 bytes", strings.Repeat("a", 64), []string{strings.Repeat("a", 64)}}, - {"caps at 20 entries", strings.Join(skillNames(25), ","), skillNames(20)}, + {"keeps pairs within the budget", strings.Join(fourFit, ","), fourFit}, + {"drops pairs over the budget", strings.Join(fiveTooMany, ","), fiveTooMany[:4]}, + {"fills the budget exactly", strings.Join(exact, ",") + ",d", exact}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - assert.Equal(t, tt.want, parseSkills(t.Context(), tt.raw)) + got := root.ParseSkills(t.Context(), tt.raw) + assert.Equal(t, tt.want, got) + assert.LessOrEqual(t, pairsSize(got), root.MaxSkillsUserAgentLength) }) } } -// skillNames returns n distinct valid skill names. -func skillNames(n int) []string { - names := make([]string, 0, n) - for i := range n { - names = append(names, "skill"+strings.Repeat("x", i)) - } - return names -} - func TestWithSkillsInUserAgent(t *testing.T) { tests := []struct { name string @@ -59,9 +82,9 @@ func TestWithSkillsInUserAgent(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { // Always set both: an empty value in the context overrides the host environment. - ctx := env.Set(t.Context(), skillsInvokedEnvVar, tt.skills) + ctx := env.Set(t.Context(), root.SkillsInvokedEnvVar, tt.skills) ctx = env.Set(ctx, "DATABRICKS_CLI_DISABLE_TELEMETRY", tt.disableTelemetry) - ua := useragent.FromContext(withSkillsInUserAgent(ctx)) + ua := useragent.FromContext(root.WithSkillsInUserAgent(ctx)) if tt.want == "" { assert.NotContains(t, ua, "skill/") } else { From b1c946be4fe47a6f73dbc86c9e926b2103f8faf3 Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Wed, 18 Nov 2026 14:42:46 +0000 Subject: [PATCH 8/8] Raise the skills user-agent budget to fit five skills 128 bytes fit only two of the longest current skill names. 225 bytes fits five of the longest (45-byte " skill/" pairs) and still leaves room under the 512-character usage-log cap for the rest of the CLI's user agent, which is about 200 characters. Co-authored-by: Isaac --- cmd/root/user_agent_skills.go | 11 ++++++----- cmd/root/user_agent_skills_test.go | 17 +++++++++-------- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/cmd/root/user_agent_skills.go b/cmd/root/user_agent_skills.go index 5e726a13696..4892d07295b 100644 --- a/cmd/root/user_agent_skills.go +++ b/cmd/root/user_agent_skills.go @@ -28,11 +28,12 @@ const skillUserAgentKey = "skill" const ( maxSkillLength = 64 - // maxSkillsUserAgentLength bounds all " skill/" pairs together. The - // usage logs that feed skill analytics cap the user agent at 512 characters, - // and the SDK appends auth/, agent/ and other pairs after these, so the - // skills must leave room for them. - maxSkillsUserAgentLength = 128 + // maxSkillsUserAgentLength bounds all " skill/" pairs together. It + // fits five of the longest current skill names (45-byte pairs). The usage + // logs that feed skill analytics cap the user agent at 512 characters, and + // the rest of the CLI's user agent (auth/, agent/ and other pairs, some + // appended after these) takes about 200, so the skills must leave room for it. + maxSkillsUserAgentLength = 225 ) // skillNamePattern is a subset of what the SDK accepts in a user agent value, diff --git a/cmd/root/user_agent_skills_test.go b/cmd/root/user_agent_skills_test.go index 39f1bf73a39..fee8a9ae864 100644 --- a/cmd/root/user_agent_skills_test.go +++ b/cmd/root/user_agent_skills_test.go @@ -31,12 +31,13 @@ func pairsSize(names []string) int { } func TestParseSkills(t *testing.T) { - // 22-byte names make 29-byte pairs: four fill 116 bytes, a fifth would make 145. - fourFit := skillNames(4, 22) - fiveTooMany := skillNames(5, 22) - // 57- and 49-byte names make 64- and 56-byte pairs (120 bytes), so " skill/c" - // lands exactly on 128 and nothing more fits. - exact := []string{strings.Repeat("a", 57), strings.Repeat("b", 49), "c"} + // 38-byte names (the longest current skill) make 45-byte pairs: five fill + // 225 bytes exactly and a sixth doesn't fit. + fiveFit := skillNames(5, 38) + sixTooMany := skillNames(6, 38) + // 64-, 64-, 64- and 22-byte pairs make 214 bytes, so " skill/abcd" (11) + // lands exactly on 225 and nothing more fits. + exact := []string{strings.Repeat("a", 57), strings.Repeat("b", 57), strings.Repeat("c", 57), "databricks-core", "abcd"} tests := []struct { name string @@ -55,8 +56,8 @@ func TestParseSkills(t *testing.T) { {"dedupes after normalization", "Core,core, CORE", []string{"core"}}, {"drops entry longer than 64 bytes", strings.Repeat("a", 65) + ",ok", []string{"ok"}}, {"keeps entry of exactly 64 bytes", strings.Repeat("a", 64), []string{strings.Repeat("a", 64)}}, - {"keeps pairs within the budget", strings.Join(fourFit, ","), fourFit}, - {"drops pairs over the budget", strings.Join(fiveTooMany, ","), fiveTooMany[:4]}, + {"keeps five of the longest skill names", strings.Join(fiveFit, ","), fiveFit}, + {"drops pairs over the budget", strings.Join(sixTooMany, ","), sixTooMany[:5]}, {"fills the budget exactly", strings.Join(exact, ",") + ",d", exact}, } for _, tt := range tests {