diff --git a/.nextchanges/cli/air-skill-hint.md b/.nextchanges/cli/air-skill-hint.md new file mode 100644 index 00000000000..9636ef450a6 --- /dev/null +++ b/.nextchanges/cli/air-skill-hint.md @@ -0,0 +1 @@ +* On `databricks air` subcommands, Claude Code now gets an install hint that names the `databricks-ai-runtime` skill, what it covers, and how to preview it with `databricks aitools install --path`, instead of the generic install hint; other commands and other agents' hints are unchanged, and `databricks air --help` lists the skill and the preview too. ([#7622](https://github.com/databricks/cli/pull/7622)) diff --git a/acceptance/air/help/output.txt b/acceptance/air/help/output.txt index 6f75b4afcc6..b28ae42bd82 100644 --- a/acceptance/air/help/output.txt +++ b/acceptance/air/help/output.txt @@ -43,6 +43,10 @@ Learn more: Quickstart (AWS) https://docs.databricks.com/aws/en/machine-learning/ai-runtime/quickstart Quickstart (Azure) https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/quickstart Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime + Teaches coding agents the workload YAML, GPU types, secrets, + and how to follow and debug runs. + Preview the skill databricks aitools install --path --skills databricks-ai-runtime + Writes the skill files to without installing anything. === list help diff --git a/acceptance/air/image-push/output.txt b/acceptance/air/image-push/output.txt index 07d4a23b770..0868e4fd0d9 100644 --- a/acceptance/air/image-push/output.txt +++ b/acceptance/air/image-push/output.txt @@ -218,7 +218,7 @@ pull --platform linux/amd64 example/image:v1 >>> databricks air images push -p docker-test -s example/image:v1 --catalog main --schema training -Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install +Tip: install the databricks-ai-runtime skill for workload configuration and run debugging: databricks aitools install --skills-only --skills databricks-ai-runtime. To preview it first, replace --skills-only with --path . Warning: This feature is in Preview. APIs may change, and the workspace must enable the Preview features. Pushing example/image:v1 as main.training.image:v1 using profile docker-test Configured Docker credential helper for [WORKSPACE_ID].container.us-west-2.localhost @@ -233,7 +233,7 @@ Now you can set `environment.unity_catalog_image = main.training.image:v1` in yo >>> musterr databricks air images push -p pat-test -s example/image:v1 --catalog main --schema training -Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install +Tip: install the databricks-ai-runtime skill for workload configuration and run debugging: databricks aitools install --skills-only --skills databricks-ai-runtime. To preview it first, replace --skills-only with --path . Warning: This feature is in Preview. APIs may change, and the workspace must enable the Preview features. Pushing example/image:v1 as main.training.image:v1 using profile pat-test Error: configure Docker authentication: run auth docker configure: exit status 1: Error: profile "pat-test" uses auth_type "pat". Docker credential helper requires a profile created by databricks auth login diff --git a/cmd/air/air.go b/cmd/air/air.go index 07f4c9281a5..b774160b544 100644 --- a/cmd/air/air.go +++ b/cmd/air/air.go @@ -23,6 +23,10 @@ Learn more: Quickstart (AWS) https://docs.databricks.com/aws/en/machine-learning/ai-runtime/quickstart Quickstart (Azure) https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/quickstart Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime + Teaches coding agents the workload YAML, GPU types, secrets, + and how to follow and debug runs. + Preview the skill databricks aitools install --path --skills databricks-ai-runtime + Writes the skill files to without installing anything. ` // Spec declares the air command. diff --git a/cmd/air/air_test.go b/cmd/air/air_test.go index 15877be56fe..f74305c26cc 100644 --- a/cmd/air/air_test.go +++ b/cmd/air/air_test.go @@ -55,6 +55,11 @@ func TestHelpFooterOnlyOnAirCommand(t *testing.T) { cmd.HelpFunc()(cmd, nil) assert.Contains(t, airOut.String(), "Learn more:") assert.Contains(t, airOut.String(), "databricks air run -h config") + // The footer is where `air` and `air --help` recommend the agent skill + // (help never reaches the pre-run hook that prints the install hint). + assert.Contains(t, airOut.String(), "databricks aitools install --skills-only --skills databricks-ai-runtime") + assert.Contains(t, airOut.String(), "Teaches coding agents the workload YAML") + assert.Contains(t, airOut.String(), "databricks aitools install --path --skills databricks-ai-runtime") list := findSubcommand(t, cmd, "list") var listOut bytes.Buffer diff --git a/cmd/air/hint_test.go b/cmd/air/hint_test.go new file mode 100644 index 00000000000..65390a4bd8b --- /dev/null +++ b/cmd/air/hint_test.go @@ -0,0 +1,90 @@ +package aircmd + +import ( + "bytes" + "context" + "testing" + + "github.com/databricks/cli/cmd/root" + "github.com/databricks/cli/internal/testutil" + "github.com/databricks/cli/libs/aitools/agents" + "github.com/databricks/cli/libs/cmdio" + "github.com/databricks/cli/libs/env" + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// airUnderRoot mounts the real air tree under a root whose pre-run hook only +// records that it ran, mirroring where cmd/root calls agents.MaybeHint. +func airUnderRoot(ctx context.Context, preRunCalled *bool) (*cobra.Command, *cobra.Command) { + dummy := &cobra.Command{Use: "databricks"} + dummy.AddGroup(&cobra.Group{ID: "development", Title: "Developer Tools"}) + dummy.PersistentPreRunE = func(cmd *cobra.Command, args []string) error { + *preRunCalled = true + return nil + } + air := root.NewCommand(ctx, Spec) + dummy.AddCommand(air) + return dummy, air +} + +// TestBareAirAndHelpShowFooterWithoutPreRun pins why the footer, not the +// dynamic hint, is the recommendation surface for `air` and `air --help`. +func TestBareAirAndHelpShowFooterWithoutPreRun(t *testing.T) { + for _, args := range [][]string{{"air"}, {"air", "--help"}} { + t.Run(args[len(args)-1], func(t *testing.T) { + preRunCalled := false + root, _ := airUnderRoot(t.Context(), &preRunCalled) + var out bytes.Buffer + root.SetOut(&out) + root.SetErr(&out) + root.SetArgs(args) + require.NoError(t, root.Execute()) + assert.False(t, preRunCalled, "help must not run the pre-run hook") + assert.Contains(t, out.String(), "Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime") + assert.Contains(t, out.String(), "Preview the skill databricks aitools install --path --skills databricks-ai-runtime") + }) + } +} + +// TestRunnableAirCommandsGetSkillHint walks the real air tree, so a new +// subcommand is covered without listing it here. +func TestRunnableAirCommandsGetSkillHint(t *testing.T) { + testutil.SetAgentEnv(t, "CLAUDECODE", "1") + _, air := airUnderRoot(t.Context(), new(bool)) + assert.False(t, air.Runnable(), "bare air renders help; the footer covers it") + + var runnable []string + var walk func(c *cobra.Command) + walk = func(c *cobra.Command) { + for _, sub := range c.Commands() { + if sub.Runnable() { + runnable = append(runnable, sub.CommandPath()) + } + walk(sub) + } + } + walk(air) + for _, name := range []string{"run", "get", "list", "logs", "cancel", "convert-to-dabs"} { + assert.Contains(t, runnable, "databricks air "+name) + } + + var visit func(c *cobra.Command) + visit = func(c *cobra.Command) { + for _, sub := range c.Commands() { + if sub.Runnable() { + t.Run(sub.CommandPath(), func(t *testing.T) { + t.Chdir(t.TempDir()) + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + ctx = env.WithUserHomeDir(ctx, t.TempDir()) + ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", t.TempDir()) + agents.MaybeHint(ctx, sub, func(context.Context, string) bool { return false }) + assert.Contains(t, stderr.String(), "install the databricks-ai-runtime skill") + }) + } + visit(sub) + } + } + visit(air) +} diff --git a/libs/aitools/agents/calling.go b/libs/aitools/agents/calling.go index 629554bce29..a0bfe24d7af 100644 --- a/libs/aitools/agents/calling.go +++ b/libs/aitools/agents/calling.go @@ -62,8 +62,10 @@ func (t Tooling) String() string { // record. For Codex and Copilot, pluginRecorded (the CLI install state) is the // only plugin source, so it misses plugins installed with the agent's own CLI // and includes plugins later removed with it. The shared skills store is not consulted: it cannot attribute skills. -// The install hint uses it too, so Claude Code is hinted exactly when it loads -// no Databricks tooling. +// The install hint's airSkillAvailable (used on `databricks air` subcommands) +// differs on purpose: it looks for the AI Runtime skill only (the plugin +// counts either way), so another Databricks skill never silences a hint about +// that one. func (a *Agent) DatabricksTooling(ctx context.Context, pluginRecorded func() bool) Tooling { // An unknown working directory skips the project lookups below. cwd := "" diff --git a/libs/aitools/agents/hint.go b/libs/aitools/agents/hint.go index f3c49839721..89008c8162d 100644 --- a/libs/aitools/agents/hint.go +++ b/libs/aitools/agents/hint.go @@ -2,6 +2,8 @@ package agents import ( "context" + "os" + "path/filepath" "strings" "time" @@ -21,6 +23,16 @@ const ( // after thorough testing. hintText = "Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install" + // airSkillName is the agent skill for `databricks air`. + airSkillName = "databricks-ai-runtime" + + // airHintText recommends the AI Runtime skill on the commands it helps with. + // It names the skill and what it buys the agent, so a coding agent can tell + // the hint is about the task at hand rather than generic setup, and offers a + // --path preview so the agent can read the skill without installing anything. + airHintText = "Tip: install the " + airSkillName + " skill for workload configuration and run debugging: databricks aitools install --skills-only --skills " + airSkillName + + ". To preview it first, replace --skills-only with --path ." + // claudeAgentProvider is the useragent.AgentProvider() value for Claude Code. // The SDK maps the CLAUDECODE env var to this product name. // https://github.com/databricks/databricks-sdk-go/blob/main/useragent/agent.go @@ -49,6 +61,12 @@ const ( // unattended runs. ciEnv = "CI" + // airCommandName is the top-level command whose runnable subcommands swap + // the generic install hint for the AI Runtime skill recommendation. Bare + // `databricks air` and `--help` render help without running the pre-run + // hook; the air help footer carries the same recommendation there. + airCommandName = "air" + // authCommandName and tokenCommandName name `databricks auth token`, the // credential helper the SDKs and Terraform run. They embed its stderr // mid-line in their own errors, where Claude Code can't strip the native @@ -174,6 +192,28 @@ func hintForAgent(provider string, pluginRecorded PluginRecordedFunc) *agentHint } } +// hintForCommand returns the hint due for cmd. On a runnable `databricks air` +// subcommand Claude Code gets the AI Runtime skill recommendation instead of +// the generic install hint: the skill is what helps with air work, and naming +// it lets the agent tell the hint is about the task at hand rather than +// generic setup. The plugin suggestion (native) is shared with the generic +// hint. Other agents keep their generic install hint everywhere: the aitools +// installer has no per-agent AI Runtime variant to offer them. +func hintForCommand(cmd *cobra.Command, provider string, pluginRecorded PluginRecordedFunc) *agentHint { + hint := hintForAgent(provider, pluginRecorded) + if hint != nil && provider == claudeAgentProvider && isAIRSubcommand(cmd) { + return &agentHint{ + installed: airSkillAvailable, + text: airHintText, + textKind: protos.AitoolsHintKindInstallText, + sessionEnv: claudeSessionEnv, + native: claudeNativeHintLine, + nativeKind: protos.AitoolsHintKindClaudeCodeNative, + } + } + return hint +} + // isHintedAgent reports whether MaybeHint hints the agent with this // useragent.AgentProvider() value. It defers to hintForAgent so both follow // the same dispatch; pluginRecorded is only read when the hint's installed @@ -191,11 +231,16 @@ func (h *agentHint) nativeLine(ctx context.Context) string { } // MaybeHint recommends installing the Databricks AI tooling when a supported -// agent drives the CLI without it installed. It is a no-op for human callers, -// unsupported agents, hint-exempt commands (isHintExemptCommand), the `auth -// token` and `auth docker token` credential helpers, a CLI process the CLI -// started itself, when there is no output stream, and once the tooling is -// present. +// agent drives the CLI without it installed. On a runnable `databricks air` +// subcommand Claude Code instead gets the AI Runtime skill recommendation, +// which names the skill, what it covers, and how to preview it: an agent +// running air has an AI Runtime task for that skill to help with. It is a +// no-op for human callers, unsupported agents, hint-exempt commands +// (isHintExemptCommand), the `auth token` and `auth docker token` credential +// helpers, a CLI process the CLI started itself, when there is no output +// stream, and once the tooling is present. Bare `databricks air` and +// `--help` render help without running the pre-run hook; the air help footer +// carries the same recommendation there. // The agent-native line (if any) and the model-facing text are throttled // independently, per session or, for agents without a session id, per agent // on this machine (fallbackKey). Both hint-shown events follow the text's @@ -206,7 +251,7 @@ func (h *agentHint) nativeLine(ctx context.Context) string { // telemetry event for each hint line shown, which makes a command that resolved // auth upload telemetry at exit. func MaybeHint(ctx context.Context, cmd *cobra.Command, pluginRecorded PluginRecordedFunc) { - hint := hintForAgent(useragent.AgentProvider(), pluginRecorded) + hint := hintForCommand(cmd, useragent.AgentProvider(), pluginRecorded) if hint == nil { return } @@ -353,6 +398,19 @@ func isHintExemptCommand(cmd *cobra.Command) bool { return false } +// isAIRSubcommand reports whether cmd sits under the top-level air command +// (`databricks air list`, `databricks air pools list`, ...), excluding air +// itself. Matching on the top-level ancestor keeps hidden aliases such as +// `databricks experimental air` out. +func isAIRSubcommand(cmd *cobra.Command) bool { + for c := cmd; c.HasParent(); c = c.Parent() { + if !c.Parent().HasParent() { + return c != cmd && c.Name() == airCommandName + } + } + return false +} + // claudeToolingInstalled reports whether Claude Code has Databricks AI tooling // in its own locations (see Agent.DatabricksTooling): the databricks plugin, or // databricks skills in Claude's skills dirs. Skills present only in the shared @@ -379,6 +437,54 @@ func claudeToolingInstalled(ctx context.Context) bool { return tooling != ToolingNone } +// airSkillAvailable reports whether Claude Code has the AI Runtime skill in a +// location it loads for the current working directory: the databricks plugin +// (which bundles every Databricks skill) installed for every project or for +// this one, or a databricks-ai-runtime skill dir in Claude's own skills dir or +// in the project skills dir of cwd or a parent up to the repository root. +// Other Databricks skills do not count: they don't cover air, and this hint +// recommends installing exactly this skill. Skills in the shared +// ~/.databricks/aitools/skills store don't count either, because Claude Code +// doesn't load them from there (see DatabricksTooling). Any read/parse failure +// reports false, so an unreadable state errs toward hinting. +func airSkillAvailable(ctx context.Context) bool { + claude := ByName(NameClaudeCode) + if claude == nil { + // claude-code is always in the registry; this guard keeps the hint + // best-effort rather than panicking in a persistent pre-run hook. + return false + } + cwd := "" + if wd, err := os.Getwd(); err == nil { + cwd = resolvePath(wd) + } + if claude.pluginInstalls != nil { + if active, _ := claude.DatabricksPluginActiveIn(ctx, cwd); active { + log.Debugf(ctx, "Databricks plugin active for Claude Code in %q; skipping AI Runtime skill hint", cwd) + return true + } + } + if dir, err := claude.SkillsDir(ctx); err == nil && airSkillDirInstalled(dir) { + return true + } + if claude.SupportsProjectScope && cwd != "" { + for _, dir := range projectDirs(cwd) { + if airSkillDirInstalled(claude.ProjectSkillsDir(dir)) { + return true + } + } + } + return false +} + +// airSkillDirInstalled reports whether dir holds the AI Runtime skill as a +// directory. Stat follows the symlinks the installer may leave in place of +// copies. +func airSkillDirInstalled(dir string) bool { + info, err := os.Stat(filepath.Join(dir, airSkillName)) + return err == nil && info.IsDir() +} + // throttleKey returns the cache key throttling the hint: the session id behind // sessionKeyPrefix, else fallbackKey. "" means no throttle. func (h *agentHint) throttleKey(ctx context.Context) string { diff --git a/libs/aitools/agents/hint_agents_test.go b/libs/aitools/agents/hint_agents_test.go index 73c42aaf6d1..412699386f3 100644 --- a/libs/aitools/agents/hint_agents_test.go +++ b/libs/aitools/agents/hint_agents_test.go @@ -326,3 +326,20 @@ func TestMaybeHint_DisabledCacheSkipsHint(t *testing.T) { assert.Empty(t, telemetry.BufferedEvents(ctx)) } } + +// Non-Claude agents keep their generic install hint on `databricks air` +// subcommands too: the aitools installer has no per-agent AI Runtime variant +// to offer them, so the air scoping only changes Claude Code's hint. +func TestMaybeHint_AgentInstallHintUnchangedOnAIR(t *testing.T) { + for _, a := range Registry { + if a.Name == NameClaudeCode { + continue + } + t.Run(a.Name, func(t *testing.T) { + setAgentEnv(t, agentDetectEnv[a.Name]) + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + MaybeHint(ctx, airCmd(), noPluginRecorded) + assert.Equal(t, agentInstallHint(a, noPluginRecorded).text+"\n", stderr.String()) + }) + } +} diff --git a/libs/aitools/agents/hint_test.go b/libs/aitools/agents/hint_test.go index c3f092e1eae..e49a77cbc9f 100644 --- a/libs/aitools/agents/hint_test.go +++ b/libs/aitools/agents/hint_test.go @@ -446,6 +446,21 @@ func TestMaybeHint_NativeHint(t *testing.T) { wantStderr: wantNativeHint + "\n" + hintText + "\n", cmd: func() *cobra.Command { return authDockerCmd("configure [PROFILE]") }, }, + { + // On air subcommands the text is the AI Runtime skill line. + name: "air command prints native then air text", + env: map[string]string{claudeChildSessionEnv: "1"}, + wantStderr: wantNativeHint + "\n" + airHintText + "\n", + cmd: func() *cobra.Command { return airCmd() }, + }, + { + name: "air command with the skill installed prints nothing", + env: map[string]string{claudeChildSessionEnv: "1"}, + cmd: func() *cobra.Command { return airCmd() }, + setup: func(t *testing.T, home string) { + writeClaudeSkill(t, home, airSkillName) + }, + }, { // air images push runs `auth docker configure` and embeds its // output in an error; the child must add nothing to it. @@ -770,6 +785,263 @@ func TestMaybeHint_InstalledLogsNothing(t *testing.T) { assert.Empty(t, telemetry.BufferedEvents(ctx)) } +// --- AI Runtime skill hint on air subcommands --- + +func airCmd() *cobra.Command { return commandAt("air list") } + +// writeProjectPluginManifest writes a manifest with one project-scope install +// covering projectPath. Marshaled, not interpolated, so Windows paths with +// backslashes stay valid JSON. +func writeProjectPluginManifest(t *testing.T, home, projectPath string) { + manifest, err := json.Marshal(map[string]any{ + "plugins": map[string]any{ + "databricks@claude-plugins-official": []any{map[string]string{ + "scope": "project", + "projectPath": projectPath, + }}, + }, + }) + require.NoError(t, err) + writePluginManifest(t, home, string(manifest)) +} + +// assertAIRHinted checks for exactly the AI Runtime skill line and one +// hint-shown event of kind INSTALL_TEXT. +func assertAIRHinted(t *testing.T, ctx context.Context, stderr *bytes.Buffer) { + t.Helper() + assert.Equal(t, airHintText+"\n", stderr.String()) + assert.Equal(t, []protos.AitoolsHintKind{protos.AitoolsHintKindInstallText}, hintKinds(t, ctx)) +} + +// assertNothingHinted checks for no hint line and no telemetry event. +func assertNothingHinted(t *testing.T, ctx context.Context, stderr *bytes.Buffer) { + t.Helper() + assert.Empty(t, stderr.String()) + assert.Empty(t, hintKinds(t, ctx)) +} + +func TestAIRHintText(t *testing.T) { + // The hint names the skill, says what it is for, and offers both the install + // and a no-install preview, on one line. + assert.Contains(t, airHintText, "install the databricks-ai-runtime skill") + assert.Contains(t, airHintText, "workload configuration and run debugging") + assert.Contains(t, airHintText, "databricks aitools install --skills-only --skills databricks-ai-runtime") + assert.Contains(t, airHintText, "replace --skills-only with --path ") + assert.NotContains(t, airHintText, "\n") +} + +// TestMaybeHint_NonAIRCommandsKeepGenericHint pins the scoping: outside air, +// Claude Code gets the generic install hint it always got, never the AI +// Runtime skill line. +func TestMaybeHint_NonAIRCommandsKeepGenericHint(t *testing.T) { + setClaudeAgent(t) + for _, path := range []string{ + "clusters list", "jobs list", "bundle deploy", "workspace list", + // The bare air node only renders help (the footer carries the tip), and + // the hidden alias points users at `databricks air`; neither is an air + // subcommand, so they keep the generic hint. + "air", + "experimental air", + } { + t.Run(path, func(t *testing.T) { + ctx, stderr := claudeCtx(t, t.TempDir()) + ctx = telemetry.WithNewLogger(ctx) + MaybeHint(ctx, commandAt(path), noPluginRecorded) + assert.Equal(t, hintText+"\n", stderr.String()) + assert.Equal(t, []protos.AitoolsHintKind{protos.AitoolsHintKindInstallText}, hintKinds(t, ctx)) + assert.NotContains(t, stderr.String(), airHintText) + }) + } +} + +// Hint-exempt non-air commands stay exactly as main keeps them: no hint of +// either kind. auth profiles is here because it was the original complaint +// this PR's scoping answers; main's exemption list now covers it. +func TestMaybeHint_ExemptNonAIRCommandsSilent(t *testing.T) { + setClaudeAgent(t) + for _, path := range []string{ + "auth profiles", "current-user me", "version", + } { + t.Run(path, func(t *testing.T) { + ctx, stderr := claudeCtx(t, t.TempDir()) + ctx = telemetry.WithNewLogger(ctx) + MaybeHint(ctx, commandAt(path), noPluginRecorded) + assert.Empty(t, stderr.String()) + assert.Empty(t, hintKinds(t, ctx)) + }) + } +} + +// Every runnable air subcommand, at any depth, gets the skill-specific hint. +func TestMaybeHint_AIRSubcommandsHint(t *testing.T) { + setClaudeAgent(t) + for _, path := range []string{ + "air run", "air get", "air list", "air logs", "air cancel", + "air convert-to-dabs", "air images", "air images push", "air pools", "air pools list", + } { + t.Run(path, func(t *testing.T) { + ctx, stderr := claudeCtx(t, t.TempDir()) + ctx = telemetry.WithNewLogger(ctx) + MaybeHint(ctx, commandAt(path), noPluginRecorded) + assertAIRHinted(t, ctx, stderr) + }) + } +} + +// Only the databricks-ai-runtime skill itself, in a location Claude Code loads +// for this working directory, silences the skill hint. +func TestMaybeHint_AIRSkillDetection(t *testing.T) { + for _, tc := range []struct { + name string + setup func(t *testing.T, home, cwd string) + wantHint bool + }{ + {"nothing installed", func(t *testing.T, home, cwd string) {}, true}, + {"skill in Claude's own skills dir", func(t *testing.T, home, cwd string) { + writeClaudeSkill(t, home, airSkillName) + }, false}, + {"skill in the project skills dir", func(t *testing.T, home, cwd string) { + require.NoError(t, os.MkdirAll(filepath.Join(cwd, ".claude", "skills", airSkillName), 0o755)) + }, false}, + {"other databricks skills only", func(t *testing.T, home, cwd string) { + writeClaudeSkill(t, home, "databricks") + writeClaudeSkill(t, home, "databricks-jobs") + }, true}, + {"a file named like the skill", func(t *testing.T, home, cwd string) { + dir := filepath.Join(home, ".claude", "skills") + require.NoError(t, os.MkdirAll(dir, 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(dir, airSkillName), nil, 0o600)) + }, true}, + {"shared canonical store", func(t *testing.T, home, cwd string) { + writeCanonicalSkill(t, home, airSkillName) + }, true}, + {"shared legacy store", func(t *testing.T, home, cwd string) { + require.NoError(t, os.MkdirAll(filepath.Join(home, LegacySkillsDir, airSkillName), 0o755)) + }, true}, + {"plugin for this project", func(t *testing.T, home, cwd string) { + writeProjectPluginManifest(t, home, cwd) + }, false}, + {"plugin for an unrelated project", func(t *testing.T, home, cwd string) { + writeProjectPluginManifest(t, home, t.TempDir()) + }, true}, + } { + t.Run(tc.name, func(t *testing.T) { + // A fresh project per case: the project-skills fixtures write into + // the working directory and must not leak between cases. + setClaudeAgent(t) + home := t.TempDir() + ctx, stderr := claudeCtx(t, home) + ctx = telemetry.WithNewLogger(ctx) + cwd, err := os.Getwd() + require.NoError(t, err) + tc.setup(t, home, cwd) + + MaybeHint(ctx, airCmd(), noPluginRecorded) + if tc.wantHint { + assertAIRHinted(t, ctx, stderr) + } else { + assertNothingHinted(t, ctx, stderr) + } + }) + } +} + +// A project-scoped skill at the repository root still counts when the CLI runs +// in a subdirectory, as Claude Code loads it there. +func TestMaybeHint_AIRSkillInRepositoryRoot(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + ctx, stderr := claudeCtx(t, home) + ctx = telemetry.WithNewLogger(ctx) + root, err := os.Getwd() + require.NoError(t, err) + require.NoError(t, os.MkdirAll(filepath.Join(root, ".claude", "skills", airSkillName), 0o755)) + sub := filepath.Join(root, "training", "configs") + require.NoError(t, os.MkdirAll(sub, 0o755)) + t.Chdir(sub) + + MaybeHint(ctx, airCmd(), noPluginRecorded) + assertNothingHinted(t, ctx, stderr) +} + +func TestAIRSkillAvailable_LogsPluginDetection(t *testing.T) { + // Clears the host's CLAUDE_CONFIG_DIR, which would move the manifest. + testutil.SetAgentEnv(t) + t.Chdir(t.TempDir()) + home := t.TempDir() + writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"version":"0.2.6"}]}}`) + + // Capture debug output by installing a text logger on the context. + var buf bytes.Buffer + handler := slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: log.LevelDebug}) + ctx := log.NewContext(t.Context(), slog.New(handler)) + ctx = env.WithUserHomeDir(ctx, home) + + assert.True(t, airSkillAvailable(ctx)) + + assert.Contains(t, buf.String(), "Databricks plugin active for Claude Code") + assert.Contains(t, buf.String(), "skipping AI Runtime skill hint") +} + +// With a session id the first hinted command is the only one; without one +// (older Claude Code) every air command is hinted. The throttle is shared with +// the generic hint, so a hint already shown on a non-air command also silences +// the air one for the rest of the session. +func TestMaybeHint_AIRSessionThrottle(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + cacheDir := t.TempDir() + newCtx := func() (context.Context, *bytes.Buffer) { + ctx, stderr := claudeCtx(t, home) + ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", cacheDir) + ctx = env.Set(ctx, claudeSessionEnv, "session-abc") + ctx = telemetry.WithNewLogger(ctx) + return ctx, stderr + } + + ctx1, stderr1 := newCtx() + MaybeHint(ctx1, airCmd(), noPluginRecorded) + assertAIRHinted(t, ctx1, stderr1) + + // Same session, second air command: stays quiet. + ctx2, stderr2 := newCtx() + MaybeHint(ctx2, commandAt("air run"), noPluginRecorded) + assertNothingHinted(t, ctx2, stderr2) + + // Another session: the air hint prints again. + ctx3, stderr3 := newCtx() + ctx3 = env.Set(ctx3, claudeSessionEnv, "session-def") + MaybeHint(ctx3, commandAt("air run"), noPluginRecorded) + assertAIRHinted(t, ctx3, stderr3) + + // A generic hint shown on a non-air command consumes the same session's + // marker, so a later air command stays quiet. + ctx4, stderr4 := newCtx() + ctx4 = env.Set(ctx4, claudeSessionEnv, "session-ghi") + MaybeHint(ctx4, commandAt("clusters list"), noPluginRecorded) + assert.Equal(t, hintText+"\n", stderr4.String()) + ctx5, stderr5 := newCtx() + ctx5 = env.Set(ctx5, claudeSessionEnv, "session-ghi") + MaybeHint(ctx5, airCmd(), noPluginRecorded) + assertNothingHinted(t, ctx5, stderr5) +} + +func TestHintForCommand(t *testing.T) { + air := hintForCommand(airCmd(), claudeAgentProvider, noPluginRecorded) + require.NotNil(t, air) + assert.Equal(t, airHintText, air.text) + + // Outside air Claude Code keeps the generic hint. + regular := hintForCommand(regularCmd(), claudeAgentProvider, noPluginRecorded) + require.NotNil(t, regular) + assert.Equal(t, hintText, regular.text) + + // Other agents are untouched on air subcommands. + cursor := hintForCommand(airCmd(), "cursor", noPluginRecorded) + require.NotNil(t, cursor) + assert.Equal(t, agentInstallHint(ByName(NameCursor), noPluginRecorded).text, cursor.text) +} + // writeProjectSkill creates a project-scoped Claude skill symlink. func writeProjectSkill(t *testing.T, project, name string) { canonical := filepath.Join(project, ".databricks", "aitools", "skills", name)