From 007deeb2f87286c1c2ab8ed8650159f31deda2aa Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Wed, 11 Nov 2026 13:53:15 +0000 Subject: [PATCH] aitools: install skill files when a detected agent's CLI cannot run MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A detected coding agent whose CLI is not on PATH (for example a Claude Code desktop or IDE install: `~/.claude` exists, `claude` does not) used to be skipped, so the run left it with nothing. It now gets raw skill files, unless it already has the plugin. The plan decides this, so the picker label and what the run does agree, and the agent joins the one skills batch of the run: ```diff planItemFor (plugin agent, scope supported) - plugin + if CLI not on PATH, the agent is detected (config dir), and not named via --agents + if the agent already has the plugin for this scope + keep it (plugin delivery, nothing installed; outcome "kept") + else + skill files instead (skills delivery) + else + plugin ``` - "Already has the plugin": Claude Code's own `installed_plugins.json` decides (a `claude plugin uninstall` leaves the CLI's record behind); when that file exists but cannot be read, the CLI's install state for the scope decides, as it does for other agents. A global install counts only a machine-wide plugin. A project-scope install counts only a project-scope plugin of this project: its skill files are shared through the repository, while a user or local plugin is personal. For Codex and GitHub Copilot only a plugin installed by `databricks aitools` is known, so one installed another way shows every skill twice next to the skill files. - A kept plugin: install prints how to refresh it and, before the skills batch, removes raw skills an earlier run gave the agent, as a plugin install does, when the agent's own manifest shows the plugin (the CLI's record alone outlives a removal with the agent's own CLI). The picker labels it "plugin installed · CLI not found". - Skill files instead: install prints how to switch to the plugin, and after the skills install drops a stale plugin record from the CLI's install state (failure to do so is a warning). When the skills install fails after a picker selection, the recovery step re-runs the skills agents with `--skills-only`, since a named agent does not fall back. - A global-scope fallback in a directory where the agent has a project or local databricks plugin still runs, and warns that this project will see both the plugin and the global skill files. - A kept plugin counts like an installed one: the run succeeds, with telemetry outcome `NOTHING_TO_DO` when it did nothing else. - Agents named via `--agents`, and agents whose CLI is on PATH but whose `plugin` command fails, keep failing with the exact commands to run. - `aitools update` no longer tries to migrate an agent whose CLI is not on PATH from raw skills to the plugin, and no longer writes raw skills to an agent whose CLI is not on PATH and whose own manifest shows the plugin for the scope (a kept plugin has no CLI record): it removes them instead, and skips the reconcile when no agent is left that can take file skills in the scope. - New: `installer.PluginRecorded` (also used for the User-Agent tooling), `installer.ForgetPluginInstalls`, `agents.Agent.HasPluginManifestReader`, and an exported `agents.Agent.DatabricksPluginActiveIn` that reports an unreadable manifest as an error. - New acceptance test `acceptance/experimental/aitools/skills/install-non-interactive`. - Changelog fragment: `.nextchanges/cli/aitools-install-skills-fallback.md`. Co-authored-by: Isaac --- .../cli/aitools-install-skills-fallback.md | 1 + .../installed_plugins.json | 1 + .../install-non-interactive/out.test.toml | 1 + .../skills/install-non-interactive/output.txt | 64 +++ .../skills/install-non-interactive/script | 87 ++++ .../skills/install-non-interactive/test.toml | 33 ++ cmd/aitools/funnel.go | 24 +- cmd/aitools/funnel_test.go | 121 ++++- cmd/aitools/install.go | 252 +++++++++- cmd/aitools/install_test.go | 447 +++++++++++++++++- cmd/aitools/recovery.go | 40 +- cmd/aitools/recovery_test.go | 2 + cmd/aitools/update.go | 67 ++- cmd/aitools/update_test.go | 147 ++++++ libs/aitools/agents/agents.go | 5 +- libs/aitools/agents/calling.go | 2 +- libs/aitools/agents/plugins.go | 88 +++- libs/aitools/agents/plugins_test.go | 71 ++- libs/aitools/agents/skills.go | 6 +- libs/aitools/installer/plugin.go | 49 +- libs/aitools/installer/plugin_test.go | 31 ++ libs/aitools/installer/useragent.go | 27 +- 22 files changed, 1434 insertions(+), 132 deletions(-) create mode 100644 .nextchanges/cli/aitools-install-skills-fallback.md create mode 100644 acceptance/experimental/aitools/skills/install-non-interactive/installed_plugins.json create mode 100644 acceptance/experimental/aitools/skills/install-non-interactive/out.test.toml create mode 100644 acceptance/experimental/aitools/skills/install-non-interactive/output.txt create mode 100644 acceptance/experimental/aitools/skills/install-non-interactive/script create mode 100644 acceptance/experimental/aitools/skills/install-non-interactive/test.toml diff --git a/.nextchanges/cli/aitools-install-skills-fallback.md b/.nextchanges/cli/aitools-install-skills-fallback.md new file mode 100644 index 00000000000..ed776cd3574 --- /dev/null +++ b/.nextchanges/cli/aitools-install-skills-fallback.md @@ -0,0 +1 @@ +* `databricks aitools install` now installs skill files for a detected coding agent whose CLI is not on PATH (for example a Claude Code desktop or IDE install), unless it already has the plugin, says how to switch to the plugin later, and warns when the current project also has the plugin. `databricks aitools update` no longer tries to install the plugin for such an agent, and no longer writes skill files next to a plugin that such an agent already has. ([#7482](https://github.com/databricks/cli/pull/7482)) diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/installed_plugins.json b/acceptance/experimental/aitools/skills/install-non-interactive/installed_plugins.json new file mode 100644 index 00000000000..ee67a12e806 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/installed_plugins.json @@ -0,0 +1 @@ +{"plugins":{"databricks@claude-plugins-official":[{"scope":"user","version":"0.2.9"}]}} diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/out.test.toml b/acceptance/experimental/aitools/skills/install-non-interactive/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/output.txt b/acceptance/experimental/aitools/skills/install-non-interactive/output.txt new file mode 100644 index 00000000000..449731b1b16 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/output.txt @@ -0,0 +1,64 @@ + +=== no flags, no terminal: no prompts, global scope, every detected agent + +>>> [CLI] aitools install +Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'. +Installing Databricks skills for Claude Code, Cursor... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. +Claude Code has skill files + +=== a plugin installed with Claude Code itself is kept, without skill files next to it + +>>> [CLI] aitools install +Claude Code already has the databricks plugin; it was not refreshed because 'claude' is not on PATH. To refresh it, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'. +Installing Databricks skills for Cursor... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. +Claude Code has no skill files + +>>> [CLI] aitools update --force + updated test-stable v1.0.0 -> v1.0.0 +Updated 1 skill. +Claude Code has no skill files + +=== a named agent does not fall back: the failure says what to run + +>>> musterr [CLI] aitools install --agents=claude-code +Installing databricks plugin for Claude Code... +Skipped Claude Code: 'claude' is not on PATH + Install or update the Claude Code CLI so 'claude' is on PATH, then re-run 'databricks aitools install --scope=global --agents=claude-code'. Or install skill files instead: databricks aitools install --scope=global --agents=claude-code --skills-only +Error: Claude Code: 'claude' is not on PATH + +=== the suggested recovery command works + +>>> [CLI] aitools install --agents=claude-code --skills-only +Installing Databricks skills for Claude Code... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. + +=== project scope: a personal plugin does not replace the project's skill files + +>>> [CLI] aitools install --scope=project +Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=project --agents=claude-code'. +Installing Databricks skills for Claude Code... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. +Skipped Cursor: does not support project-scoped skills + To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor + +>>> [CLI] aitools update --scope=project +Skipped Cursor: does not support project-scoped skills. +Already up to date. +The project has Claude Code skill files + +=== nothing can be set up: the run fails instead of exiting 0 + +>>> musterr [CLI] aitools install --scope=project +Skipped Cursor: does not support project-scoped skills + To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor +Error: nothing was installed; follow the steps above diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/script b/acceptance/experimental/aitools/skills/install-non-interactive/script new file mode 100644 index 00000000000..bb361d77522 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/script @@ -0,0 +1,87 @@ +# Isolate HOME so parallel aitools tests don't race on a shared ~/.databricks. +sethome home + +# Agent config dirs can also be moved by environment variables. Point them all +# at the fixture HOME, so the developer's own agents are not detected and +# nothing is written outside it. +unset CLAUDE_CONFIG_DIR PI_CODING_AGENT_DIR GEMINI_CLI_HOME GOOSE_PATH_ROOT +export XDG_CONFIG_HOME="${USERPROFILE:-$HOME}/.config" +export APPDATA="${USERPROFILE:-$HOME}/AppData/Roaming" + +# Agents are also detected by their CLI binary on PATH, so drop every PATH entry +# that holds one; otherwise the developer's own agents would join the run. That +# can drop /usr/bin (and /bin on a merged-/usr system), so resolve the commands +# the script runs first. Windows also finds a command under each PATHEXT +# extension (e.g. claude.cmd), so check those names too. +mkdir_bin=$(command -v mkdir) +rm_bin=$(command -v rm) +cp_bin=$(command -v cp) +exts="" +if [ -n "${PATHEXT:-}" ]; then exts=$(printf '%s' "$PATHEXT" | tr ';' ':'); fi +filtered_path="" +IFS=: +for dir in $PATH; do + keep=1 + for bin in claude cursor-agent codex opencode copilot pi gemini goose kiro; do + if [ -x "$dir/$bin" ]; then keep=; fi + for ext in $exts; do + if [ -f "$dir/$bin$ext" ]; then keep=; fi + done + done + if [ -n "$keep" ]; then filtered_path="$filtered_path:$dir"; fi +done +unset IFS +export PATH="${filtered_path#:}" + +# Claude Code's config dir exists but its CLI is not on PATH (desktop or IDE +# install). Cursor has no plugin and gets raw skill files. +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude" "${USERPROFILE:-$HOME}/.cursor" + +check_claude_skills() { + if [ -e "${USERPROFILE:-$HOME}/.claude/skills/test-stable" ]; then echo "Claude Code has skill files"; else echo "Claude Code has no skill files"; fi +} + +title "no flags, no terminal: no prompts, global scope, every detected agent" +# Stdin is not a TTY, so the scope select and agent picker are skipped. Cursor +# gets skills; Claude Code's plugin cannot be installed without its CLI, so it +# gets skill files too, with a note on how to switch to the plugin later. +trace $CLI aitools install +check_claude_skills + +title "a plugin installed with Claude Code itself is kept, without skill files next to it" +# Claude Code records its plugins in installed_plugins.json. The run keeps the +# plugin and removes the skill files the previous run gave Claude Code, and a +# later update does not write them back. +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude/plugins" +"$cp_bin" installed_plugins.json "${USERPROFILE:-$HOME}/.claude/plugins/" +trace $CLI aitools install +check_claude_skills +trace $CLI aitools update --force +check_claude_skills +"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude/plugins" + +title "a named agent does not fall back: the failure says what to run" +trace musterr $CLI aitools install --agents=claude-code + +title "the suggested recovery command works" +trace $CLI aitools install --agents=claude-code --skills-only + +title "project scope: a personal plugin does not replace the project's skill files" +# Project skill files are shared through the repository, so a user-scope plugin +# installed with Claude Code itself later must not stop the update from +# refreshing them. Cursor only supports global skills and is skipped. +testdir=$(pwd) +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/project" +cd "${USERPROFILE:-$HOME}/project" +trace $CLI aitools install --scope=project +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude/plugins" +"$cp_bin" "$testdir/installed_plugins.json" "${USERPROFILE:-$HOME}/.claude/plugins/" +trace $CLI aitools update --scope=project +if [ -e .claude/skills/test-stable ]; then echo "The project has Claude Code skill files"; else echo "The project has no Claude Code skill files"; fi +"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude/plugins" +cd "$testdir" + +title "nothing can be set up: the run fails instead of exiting 0" +# Cursor only supports global skills, so a project-scope run has nothing to do. +"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude" +trace musterr $CLI aitools install --scope=project diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/test.toml b/acceptance/experimental/aitools/skills/install-non-interactive/test.toml new file mode 100644 index 00000000000..7afa69b4552 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/test.toml @@ -0,0 +1,33 @@ +# Mock server replaces raw.githubusercontent.com for manifest + skill files. +Env.DATABRICKS_SKILLS_BASE_URL = "$DATABRICKS_HOST" +Env.DATABRICKS_SKILLS_REF = "test-ref" + +Ignore = [ + "home", +] + +[[Server]] +Pattern = "GET /test-ref/manifest.json" +Response.Body = ''' +{ + "version": "2", + "updated_at": "2026-01-01T00:00:00Z", + "skills": { + "test-stable": { + "version": "1.0.0", + "description": "Stable test skill", + "files": ["SKILL.md"], + "repo_dir": "skills" + } + } +} +''' + +[[Server]] +Pattern = "GET /test-ref/skills/test-stable/SKILL.md" +Response.Body = '''--- +name: test-stable +--- + +# Test stable skill +''' diff --git a/cmd/aitools/funnel.go b/cmd/aitools/funnel.go index d82c315c5a9..00f0eadef30 100644 --- a/cmd/aitools/funnel.go +++ b/cmd/aitools/funnel.go @@ -178,9 +178,29 @@ func deliverySteps(outcomes []agentOutcome) []protos.AitoolsCommandStep { return steps } -// anyInstalled reports whether at least one agent was set up. +// anyInstalled reports whether at least one agent was set up: installed, or +// left with the databricks plugin it already had. func anyInstalled(outcomes []agentOutcome) bool { - return slices.ContainsFunc(outcomes, func(o agentOutcome) bool { return o.status == outcomeInstalled }) + return slices.ContainsFunc(outcomes, func(o agentOutcome) bool { + return o.status == outcomeInstalled || o.status == outcomeKept + }) +} + +// onlyKeptPlugins reports whether a run installed nothing and failed for no +// agent, because each agent it set up kept the plugin it already had. The +// funnel records such a run as NOTHING_TO_DO rather than SUCCESS. +func onlyKeptPlugins(outcomes []agentOutcome) bool { + kept := false + for _, o := range outcomes { + switch o.status { + case outcomeInstalled, outcomeFailed: + return false + case outcomeKept: + kept = true + case outcomeSkipped: + } + } + return kept } // firstFailureCategory returns the category of the first agent that failed or diff --git a/cmd/aitools/funnel_test.go b/cmd/aitools/funnel_test.go index fe4be9dd4fc..dcbfe086135 100644 --- a/cmd/aitools/funnel_test.go +++ b/cmd/aitools/funnel_test.go @@ -570,30 +570,99 @@ func TestListFunnelFailure(t *testing.T) { } } -// A plugin failure for an auto-detected agent is only a warning, but when -// nothing got installed the run fails and the funnel must not report SUCCESS. -func TestInstallFunnelDetectedPluginFailureIsNotSuccess(t *testing.T) { - isolateAgents(t) - tmp := t.TempDir() - t.Setenv("HOME", tmp) - t.Setenv("USERPROFILE", tmp) - t.Setenv("XDG_CONFIG_HOME", filepath.Join(tmp, ".config")) - fakeBinsOnPath(t, "codex") - t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") - setupPluginMock(t) - forbidSkillsInstall(t) - installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { - return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed} +// How the funnel finishes when a detected agent's plugin cannot be installed: +// its install failed, or its CLI is missing and it got skill files or kept the +// plugin it already had. +func TestInstallFunnelDetectedPluginAgents(t *testing.T) { + cases := []struct { + name string + claudeConfigDir bool // Claude Code detected by ~/.claude; its CLI is never on PATH + codexOnPath bool // Codex detected by its CLI, whose plugin install fails + pluginInstalled bool + wantErr error + wantShape []string + }{ + { + // A plugin failure for an auto-detected agent is only a warning, but + // when nothing got installed the run fails and the funnel takes the + // category from the agent's outcome. + name: "the only install failed", + codexOnPath: true, + wantErr: errNoAgentSetUp, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "FINISHED:FAILURE:PLUGIN_INSTALL_FAILED", + }, + }, + { + name: "CLI missing, skill files instead", + claudeConfigDir: true, + codexOnPath: true, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "SKILLS_INSTALLED", "FINISHED:SUCCESS:", + }, + }, + { + // The run installed nothing, but exits 0. + name: "CLI missing, plugin kept", + claudeConfigDir: true, + pluginInstalled: true, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "FINISHED:NOTHING_TO_DO:", + }, + }, + { + // A kept plugin counts like an installed one: the other agent's + // failed install is only a warning. + name: "CLI missing, plugin kept, another install failed", + claudeConfigDir: true, + codexOnPath: true, + pluginInstalled: true, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "FINISHED:SUCCESS:", + }, + }, } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + isolateAgents(t) + tmp := t.TempDir() + t.Setenv("HOME", tmp) + t.Setenv("USERPROFILE", tmp) + t.Setenv("XDG_CONFIG_HOME", filepath.Join(tmp, ".config")) + if tc.claudeConfigDir { + require.NoError(t, os.MkdirAll(filepath.Join(tmp, ".claude"), 0o755)) + } + var wantPluginCalls []pluginCall + if tc.codexOnPath { + fakeBinsOnPath(t, "codex") + wantPluginCalls = []pluginCall{{agent: agents.NameCodex}} + } else { + fakeBinsOnPath(t) + } + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + stubPluginAlreadyInstalled(t, tc.pluginInstalled) + stubLegacyCleanup(t) + setupInstallMock(t) + plugins := setupPluginMock(t) + installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { + *plugins = append(*plugins, pluginCall{agent: a.Name}) + return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed} + } - // The run installed nothing, so it exits non-zero; the FINISHED event takes - // the category from the agent's outcome. - ctx, err := runInstall(t, cmdio.MockDiscard(t.Context()), "--scope", "global") - require.ErrorIs(t, err, errNoAgentSetUp) - assert.Equal(t, []string{ - "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", - "FINISHED:FAILURE:PLUGIN_INSTALL_FAILED", - }, funnelShape(funnelEvents(ctx))) + ctx, err := runInstall(t, cmdio.MockDiscard(t.Context()), "--scope", "global") + if tc.wantErr != nil { + require.ErrorIs(t, err, tc.wantErr) + } else { + require.NoError(t, err) + } + assert.Equal(t, wantPluginCalls, *plugins, "only an agent with its CLI on PATH gets a plugin install") + assert.Equal(t, tc.wantShape, funnelShape(funnelEvents(ctx))) + }) + } } func TestAnyInstalledAndFirstFailureCategory(t *testing.T) { @@ -608,6 +677,13 @@ func TestAnyInstalledAndFirstFailureCategory(t *testing.T) { assert.False(t, anyInstalled([]agentOutcome{failed, skipped})) assert.Equal(t, protos.AitoolsErrorCategoryPluginInstallFailed, firstFailureCategory([]agentOutcome{failed, skipped})) + kept := agentOutcome{agent: codex, delivery: deliveryPlugin, status: outcomeKept, errorCategory: protos.AitoolsErrorCategoryCLINotOnPath} + assert.True(t, anyInstalled([]agentOutcome{kept, skipped}), "a kept plugin is set up") + assert.True(t, onlyKeptPlugins([]agentOutcome{kept, skipped})) + assert.False(t, onlyKeptPlugins([]agentOutcome{kept, failed}), "a kept plugin counts like an installed one next to a failed install") + assert.False(t, onlyKeptPlugins([]agentOutcome{kept, installed})) + assert.False(t, onlyKeptPlugins([]agentOutcome{skipped})) + uncategorized := agentOutcome{agent: codex, delivery: deliveryPlugin, status: outcomeFailed} assert.Equal(t, protos.AitoolsErrorCategoryUnsupportedScope, firstFailureCategory([]agentOutcome{installed, uncategorized, skipped})) assert.Equal(t, protos.AitoolsErrorCategoryUncategorized, firstFailureCategory([]agentOutcome{installed, uncategorized})) @@ -820,6 +896,7 @@ func TestUpdateFunnelWhenPluginsFail(t *testing.T) { for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { isolateCommandEnv(t) + fakeBinsOnPath(t, "copilot") dir := saveGlobalState(t, tc.skills) if tc.noPlugins { require.NoError(t, installer.SaveState(dir, &installer.InstallState{SchemaVersion: 2, Release: "v0.2.6", Skills: tc.skills})) diff --git a/cmd/aitools/install.go b/cmd/aitools/install.go index 6a13be5f7b7..62e6f43e2b8 100644 --- a/cmd/aitools/install.go +++ b/cmd/aitools/install.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "os" "runtime" "strings" @@ -27,6 +28,7 @@ var ( installPluginForAgentFn = installer.InstallPluginForAgent recordPluginInstallsFn = installer.RecordPluginInstalls cleanupLegacyFn = installer.RemoveLegacyRawSkills + pluginAlreadyInstalledFn = pluginAlreadyInstalled ) // errNoAgentsSelected is returned when the picker is confirmed with nothing @@ -96,6 +98,15 @@ type agentPlanItem struct { reason string // why the agent is skipped (deliverySkip only) skipErrorCategory protos.AitoolsErrorCategory // error category for the skip (deliverySkip only) explicit bool // named via --agents (blocking it is an error) + // cliMissing marks a detected plugin agent whose CLI is not on PATH, so the + // plugin cannot be installed: it gets skill files instead (deliverySkills), + // or keeps the plugin it already has (deliveryPlugin, nothing is installed). + cliMissing bool + // projectPlugin marks a skills fallback in a directory where the agent + // already loads a databricks plugin that does not cover the install scope: + // a project or local plugin for a global install, or a personal (user or + // local) plugin for a project install. That directory sees both. + projectPlugin bool } // agentChoice is one row in the interactive agent picker. @@ -118,7 +129,13 @@ func NewInstallCmd() *cobra.Command { By default this installs the databricks plugin through each agent's own CLI (Claude Code, Codex, GitHub Copilot). Agents without a headless plugin install -(` + strings.Join(agents.SkillsOnlyNames(), ", ") + `) get raw skill files. +(` + strings.Join(agents.SkillsOnlyNames(), ", ") + `) get raw skill files, and so does a +detected plugin agent whose CLI is not on PATH (for example a desktop or IDE +install) and is not named with --agents, unless it already has the plugin. For +Claude Code that is read from its own plugin list; for Codex and GitHub Copilot +only a plugin installed by 'databricks aitools' is known, so one installed +another way shows every skill twice next to the skill files. A named agent +whose CLI is not on PATH fails; add --skills-only to give it skill files. Escape hatches: --skills-only Force raw skill files for every agent (no plugin). @@ -296,11 +313,12 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), } } - plan := buildPlan(targetAgents, scope, skillsOnly, explicit) + plan := buildPlan(ctx, targetAgents, scope, skillsOnly, explicit) funnel.setAgents(plan) funnel.step(ctx, protos.AitoolsCommandStepAgentsSelected) // The picker selection confirms the plan; runs without the picker - // confirm it implicitly. + // confirm it implicitly. The picker labels show which agents get + // skill files instead of the plugin. funnel.step(ctx, protos.AitoolsCommandStepPlanConfirmed) if !explicit && interactive { printInstallScope(ctx, scope) @@ -328,7 +346,11 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), } switch { case runErr == nil: - // The deferred funnel.finish records SUCCESS. + // The deferred funnel.finish records SUCCESS; a kept plugin counts + // like an installed one, unless nothing else was done. + if onlyKeptPlugins(outcomes) { + funnel.finishWith(ctx, protos.AitoolsCommandOutcomeNothingToDo, protos.AitoolsErrorCategoryUnspecified) + } case topLevelFailure(runErr) == nil: // Named agents failed, or no agent was set up. A skip has no error // type of its own, so take the category from the outcomes, not runErr. @@ -433,7 +455,7 @@ func agentChoices(ctx context.Context, scope string, skillsOnly bool) []agentCho cmdio.LogString(ctx, "Detecting coding agents...") var choices []agentChoice for _, a := range agents.Registry { - item := planItemFor(a, scope, skillsOnly, false) + item := planItemFor(ctx, a, scope, skillsOnly, false) label := agentChoiceLabel(ctx, a, item, skillsOnly) cmdio.LogString(ctx, fmt.Sprintf(" %-16s %s", a.DisplayName, label)) if item.delivery == deliverySkip { @@ -454,14 +476,21 @@ func agentChoices(ctx context.Context, scope string, skillsOnly bool) []agentCho // agentChoiceLabel is the picker label: the detection state, plus the skip // reason when the agent can't be acted on in the chosen scope. Under // --skills-only every found agent gets raw skills, so it is labeled "skills". +// An agent whose CLI is missing shows the skill files it gets instead of the +// plugin, or that it keeps the plugin it already has. func agentChoiceLabel(ctx context.Context, a *agents.Agent, item agentPlanItem, skillsOnly bool) string { state := a.DisplayState(ctx) label := agentStateLabel(state) if skillsOnly && state != agents.StateNotFound { label = deliverySkills.String() } - if item.delivery == deliverySkip { + switch { + case item.delivery == deliverySkip: return label + " · " + item.reason + case item.cliMissing && item.delivery == deliverySkills: + return "skills · CLI not found" + case item.cliMissing && item.delivery == deliveryPlugin: + return "plugin installed · CLI not found" } return label } @@ -512,10 +541,10 @@ func defaultPromptAgentSelection(_ context.Context, scope string, choices []agen // buildPlan resolves the per-agent delivery and scope. Plugin-first: an agent // with a headless plugin install gets the plugin; --skills-only forces skills // everywhere; agents with no plugin always get skills. -func buildPlan(targetAgents []*agents.Agent, scope string, skillsOnly, explicit bool) []agentPlanItem { +func buildPlan(ctx context.Context, targetAgents []*agents.Agent, scope string, skillsOnly, explicit bool) []agentPlanItem { plan := make([]agentPlanItem, 0, len(targetAgents)) for _, a := range targetAgents { - plan = append(plan, planItemFor(a, scope, skillsOnly, explicit)) + plan = append(plan, planItemFor(ctx, a, scope, skillsOnly, explicit)) } return plan } @@ -523,7 +552,7 @@ func buildPlan(targetAgents []*agents.Agent, scope string, skillsOnly, explicit // planItemFor resolves the delivery and scope for a single agent in the given // install scope. It is shared by buildPlan and the interactive picker so the // picker and the plan agree on what an agent will (or won't) do. -func planItemFor(a *agents.Agent, scope string, skillsOnly, explicit bool) agentPlanItem { +func planItemFor(ctx context.Context, a *agents.Agent, scope string, skillsOnly, explicit bool) agentPlanItem { item := agentPlanItem{agent: a, explicit: explicit} switch { case skillsOnly || a.Plugin == nil: @@ -539,11 +568,31 @@ func planItemFor(a *agents.Agent, scope string, skillsOnly, explicit bool) agent } default: nativeScope, ok, reason := mapAgentScope(a, scope) - if !ok { + switch { + case !ok: item.delivery = deliverySkip item.reason = reason item.skipErrorCategory = protos.AitoolsErrorCategoryUnsupportedScope - } else { + case !explicit && !a.HasBinary(ctx) && a.Detected(ctx): + // A desktop or IDE-only install has the config dir but no CLI to + // install the plugin with, so it gets the skill files it can use + // today. If it already has the plugin, skill files next to it would + // show every skill twice, so the plugin is kept. A named agent keeps + // failing with the commands to run: --agents never changes delivery. + item.cliMissing = true + item.delivery = deliverySkills + switch { + case pluginAlreadyInstalledFn(ctx, a, scope): + item.delivery = deliveryPlugin + item.scope = nativeScope + default: + // The skill files still serve every other project (global + // scope) or the project's teammates (project scope), but a + // plugin that does not cover this scope and applies here shows + // every skill twice in this directory. + item.projectPlugin = projectPluginActive(ctx, a) + } + default: item.delivery = deliveryPlugin item.scope = nativeScope } @@ -551,6 +600,55 @@ func planItemFor(a *agents.Agent, scope string, skillsOnly, explicit bool) agent return item } +// pluginAlreadyInstalled reports whether the agent already has the databricks +// plugin for this install scope. When the CLI can read the agent's own plugin +// manifest, the manifest decides, as in agents.DatabricksTooling: a plugin +// removed with the agent's own CLI leaves the CLI's record behind. Otherwise, +// or when the manifest exists but cannot be read, the CLI's install state for +// the scope does. +func pluginAlreadyInstalled(ctx context.Context, a *agents.Agent, scope string) bool { + if a.HasPluginManifestReader() { + active, err := manifestPluginActive(ctx, a, scope) + if err == nil { + return active + } + log.Debugf(ctx, "Could not read the plugin manifest of %s, using the install state: %v", a.DisplayName, err) + } + return installer.PluginRecorded(ctx, scope, a.Name) +} + +// manifestPluginActive reports whether the agent's own plugin manifest has a +// databricks plugin that serves this install scope. A global install serves +// every project, so only a machine-wide plugin covers it. A project install is +// shared through the repository, so only a project-scope plugin of this project +// covers it: a machine-wide or local plugin is personal, and teammates would +// get neither the plugin nor the skill files. +func manifestPluginActive(ctx context.Context, a *agents.Agent, scope string) (bool, error) { + if scope != installer.ScopeProject { + return a.DatabricksPluginActiveIn(ctx, "") + } + cwd, err := os.Getwd() + if err != nil { + return false, err + } + return a.DatabricksProjectPluginIn(ctx, cwd) +} + +// projectPluginActive reports whether the agent's own manifest has a databricks +// plugin record that applies in the current directory. Called after a global +// install found no machine-wide plugin, so a match is a project or local one: +// unlike manifestPluginActive for a project install, a local plugin counts, +// since its user sees both. An unreadable manifest or working directory +// reports false. +func projectPluginActive(ctx context.Context, a *agents.Agent) bool { + cwd, err := os.Getwd() + if err != nil { + return false + } + active, err := a.DatabricksPluginActiveIn(ctx, cwd) + return err == nil && active +} + // agentPickerTitle names the install scope, so it is visible before anything // is installed. func agentPickerTitle(scope string) string { @@ -584,6 +682,9 @@ const ( outcomeInstalled outcomeStatus = "installed" outcomeSkipped outcomeStatus = "skipped" outcomeFailed outcomeStatus = "failed" + // outcomeKept is an agent whose CLI is missing but which already has the + // plugin: it is set up, though nothing was installed. + outcomeKept outcomeStatus = "kept" ) // errNoAgentSetUp is returned when no agent was set up: none was detected, or @@ -601,6 +702,62 @@ type agentErrors struct{ err error } func (e *agentErrors) Error() string { return e.err.Error() } func (e *agentErrors) Unwrap() error { return e.err } +// cliMissingOutcome is the plugin outcome of an agent whose CLI is not on PATH: +// failed when it got skill files instead, kept when it already has the plugin. +func cliMissingOutcome(it agentPlanItem, status outcomeStatus) agentOutcome { + return agentOutcome{ + agent: it.agent, + delivery: deliveryPlugin, + status: status, + errorCategory: protos.AitoolsErrorCategoryCLINotOnPath, + message: cliMissingReason(it), + } +} + +// skillsBatchRerun reports the invocation that retries the skills batch when +// it included an agent whose CLI is missing and the run named its agents (the +// picker selection). Re-running with that agent named would try its plugin, +// since --agents never changes delivery, so it re-runs the skills agents with +// --skills-only instead. ok is false when rerun already retries the batch. +func skillsBatchRerun(rerun installInvocation, skillsAgents []*agents.Agent, fallbackItems []agentPlanItem) (installInvocation, bool) { + if rerun.agents == "" || len(fallbackItems) == 0 { + return rerun, false + } + rerun.agents = joinAgentNames(skillsAgents) + rerun.skillsOnly = true + return rerun, true +} + +// skillsBatchError attaches the skillsBatchRerun recovery step to a failed +// skills batch. When there is no such step, the error is returned as is, and +// the caller attaches the step for the whole run. +func skillsBatchError(ctx context.Context, rerun installInvocation, skillsAgents []*agents.Agent, fallbackItems []agentPlanItem, err error) error { + batchRerun, ok := skillsBatchRerun(rerun, skillsAgents, fallbackItems) + if !ok { + return err + } + return withRecovery(ctx, batchRerun, err) +} + +// forgetStalePluginRecords drops the CLI's plugin records of agents that just +// got skill files instead of the plugin. They have no plugin (see +// pluginAlreadyInstalled), so a record left by a removal with the agent's own +// CLI is stale, and list and update would keep treating them as plugin agents +// and never refresh their skill files. The skills are already installed, so a +// failure here is only a warning. +func forgetStalePluginRecords(ctx context.Context, scope string, items []agentPlanItem) { + if len(items) == 0 { + return + } + names := make([]string, len(items)) + for i, it := range items { + names[i] = it.agent.Name + } + if err := installer.ForgetPluginInstalls(ctx, scope, names); err != nil { + log.Warnf(ctx, "Could not drop stale plugin records for %s: %v", strings.Join(names, ", "), err) + } +} + // topLevelFailure returns the run error when it has no per-agent entry, or nil // when the failure is already reported per agent — so a per-agent failure is not // duplicated in the top-level error/errorCategory fields. @@ -612,22 +769,29 @@ func topLevelFailure(runErr error) error { } // executePlan carries out the plan and returns each agent's outcome. Skills -// installs go through the existing skills path. Plugin installs are reported but -// never silently fall back to skills: a blocked install is a warning, unless the -// agent was explicitly named via --agents, which is an error. A run that sets up -// no agent at all is an error too, so callers never mistake it for success. The -// per-agent recovery steps repeat rerun for the agent at hand. +// installs, including those of agents whose CLI is missing, go through the +// existing skills path as one group. A failed plugin install is a warning, +// unless the agent was explicitly named via --agents, which is an error. A run +// that sets up no agent at all is an error too, so callers never mistake it for +// success. The per-agent recovery steps repeat rerun for the agent at hand. func executePlan(ctx context.Context, src installer.ManifestSource, plan []agentPlanItem, opts installer.InstallOptions, rerun installInvocation, quiet bool) ([]agentOutcome, error) { var skillsAgents []*agents.Agent - var pluginItems, skipItems []agentPlanItem + var fallbackItems, keptItems, pluginItems, skipItems []agentPlanItem skillsExplicit := false for _, it := range plan { switch it.delivery { case deliverySkills: skillsAgents = append(skillsAgents, it.agent) skillsExplicit = skillsExplicit || it.explicit + if it.cliMissing { + fallbackItems = append(fallbackItems, it) + } case deliveryPlugin: - pluginItems = append(pluginItems, it) + if it.cliMissing { + keptItems = append(keptItems, it) + } else { + pluginItems = append(pluginItems, it) + } case deliverySkip: skipItems = append(skipItems, it) } @@ -636,6 +800,39 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent var outcomes []agentOutcome var explicitErrs []error + // The plugin could not be installed for these agents. Keep that in the + // outcomes so telemetry still sees it; the skills outcome records the + // fallback. + for _, it := range fallbackItems { + if !quiet { + cmdio.LogString(ctx, cmdio.Yellow(ctx, skillsFallbackText(rerun, it))) + if it.projectPlugin { + cmdio.LogString(ctx, cmdio.Yellow(ctx, projectPluginWarning(opts.Scope, it))) + } + } + outcomes = append(outcomes, cliMissingOutcome(it, outcomeFailed)) + } + + for _, it := range keptItems { + if !quiet { + cmdio.LogString(ctx, cmdio.Yellow(ctx, pluginKeptText(rerun, it))) + } + // Raw skills an earlier run gave this agent would show every skill + // twice next to the plugin, so remove them as a plugin install does. + // This runs before the skills batch: a newer release there replaces the + // recorded checksums, and older copies would then look user-modified + // and stay. Only the agent's own manifest is proof enough: for Codex and + // Copilot the CLI's record is the only evidence, and it outlives a + // removal with the agent's own CLI, so removing the skills then would + // leave the agent with neither. + if active, err := manifestPluginActive(ctx, it.agent, opts.Scope); err == nil && active { + if err := cleanupLegacyFn(ctx, it.agent, opts.Scope); err != nil { + log.Debugf(ctx, "Legacy skill cleanup for %s failed: %v", it.agent.DisplayName, err) + } + } + outcomes = append(outcomes, cliMissingOutcome(it, outcomeKept)) + } + // A skills install runs as a group; its failure is the command's top-level // error. Plugin agents don't depend on it, so they are still attempted. var skillsErr error @@ -648,6 +845,7 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent for _, a := range skillsAgents { outcomes = append(outcomes, agentOutcome{agent: a, delivery: deliverySkills, status: outcomeInstalled}) } + forgetStalePluginRecords(ctx, opts.Scope, fallbackItems) } } @@ -718,7 +916,7 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent if errors.Is(skillsErr, installer.ErrNoSkillsResolved) { return outcomes, err } - return outcomes, errors.Join(skillsErr, err) + return outcomes, errors.Join(skillsBatchError(ctx, rerun, skillsAgents, fallbackItems, skillsErr), err) } pluginsRecorded = true } @@ -752,12 +950,14 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent } // A release with no skill this CLI can install skips the skills agents when - // the plan had plugin agents, so the plugin outcomes decide the run. A - // --skills-only run with nothing else attempted keeps the error. So does a - // run whose installed plugins were not recorded (skills without install - // state are on disk): update and uninstall could not manage them. - if errors.Is(skillsErr, installer.ErrNoSkillsResolved) && len(pluginItems) > 0 && (pluginCount == 0 || pluginsRecorded) { - recovery := installRecovery(ctx, rerun, skillsErr) + // the plan had plugin agents, installed or kept, so the plugin outcomes + // decide the run. A --skills-only run with nothing else attempted keeps the + // error. So does a run whose installed plugins were not recorded (skills + // without install state are on disk): update and uninstall could not + // manage them. + if errors.Is(skillsErr, installer.ErrNoSkillsResolved) && (len(pluginItems) > 0 || len(keptItems) > 0) && (pluginCount == 0 || pluginsRecorded) { + batchRerun, _ := skillsBatchRerun(rerun, skillsAgents, fallbackItems) + recovery := installRecovery(ctx, batchRerun, skillsErr) names := make([]string, len(skillsAgents)) for i, a := range skillsAgents { names[i] = a.DisplayName @@ -776,7 +976,7 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent // The skills error has no per-agent entry, so it stays the top-level error; // explicit per-agent failures are already in their outcomes. if skillsErr != nil { - return outcomes, skillsErr + return outcomes, skillsBatchError(ctx, rerun, skillsAgents, fallbackItems, skillsErr) } if len(explicitErrs) > 0 { return outcomes, &agentErrors{err: errors.Join(explicitErrs...)} diff --git a/cmd/aitools/install_test.go b/cmd/aitools/install_test.go index 2b9ad9ea173..f98e0697e79 100644 --- a/cmd/aitools/install_test.go +++ b/cmd/aitools/install_test.go @@ -6,6 +6,7 @@ import ( "context" "encoding/json" "errors" + "fmt" "io" "io/fs" "net/http" @@ -99,6 +100,24 @@ func setupPluginMock(t *testing.T) *[]pluginCall { return &calls } +// stubPluginAlreadyInstalled pins whether an agent counts as already having the +// plugin; the real check reads the agent's manifest under the real HOME. +func stubPluginAlreadyInstalled(t *testing.T, installed bool) { + t.Helper() + orig := pluginAlreadyInstalledFn + t.Cleanup(func() { pluginAlreadyInstalledFn = orig }) + pluginAlreadyInstalledFn = func(context.Context, *agents.Agent, string) bool { return installed } +} + +// stubLegacyCleanup skips the raw-skill cleanup that follows a plugin install; +// the test agents have no config dir for it to inspect. +func stubLegacyCleanup(t *testing.T) { + t.Helper() + orig := cleanupLegacyFn + t.Cleanup(func() { cleanupLegacyFn = orig }) + cleanupLegacyFn = func(context.Context, *agents.Agent, string) error { return nil } +} + func setupScopeMock(t *testing.T, scope string) *bool { t.Helper() orig := promptScopeSelection @@ -142,6 +161,18 @@ func fakeBinsOnPath(t *testing.T, binaries ...string) { t.Setenv("PATH", dir) } +// writeClaudeManifest writes Claude Code's installed_plugins.json under home +// with one databricks plugin record of the given scope. +func writeClaudeManifest(t *testing.T, home, scope, projectPath string) { + t.Helper() + manifest, err := json.Marshal(map[string]any{"plugins": map[string]any{ + "databricks@claude-plugins-official": []map[string]string{{"scope": scope, "projectPath": projectPath, "version": "0.2.9"}}, + }}) + require.NoError(t, err) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(home, ".claude", "plugins", "installed_plugins.json"), manifest, 0o600)) +} + func testPluginAgent(name, display, binary string) *agents.Agent { spec := &agents.PluginSpec{Marketplace: "databricks-agent-skills", ID: "databricks", Source: "databricks/databricks-agent-skills"} a := &agents.Agent{Name: name, DisplayName: display, Binary: binary, Plugin: spec} @@ -154,20 +185,21 @@ func testPluginAgent(name, display, binary string) *agents.Agent { // --- buildPlan / mapAgentScope / executePlan unit tests (no detection) --- func TestBuildPlanDeliveries(t *testing.T) { + fakeBinsOnPath(t, "claude") claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") // Cursor is a skills-only agent (no headless plugin install). cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor", Binary: "cursor-agent", SupportsProjectScope: true} opencode := &agents.Agent{Name: agents.NameOpenCode, DisplayName: "OpenCode", Binary: "opencode"} targets := []*agents.Agent{claude, cursor, opencode} - plan := buildPlan(targets, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), targets, installer.ScopeGlobal, false, false) assert.Equal(t, deliveryPlugin, plan[0].delivery) assert.Equal(t, agentScopeUser, plan[0].scope) assert.Equal(t, deliverySkills, plan[1].delivery) // Cursor -> skills assert.Equal(t, deliverySkills, plan[2].delivery) // --skills-only forces skills for every agent. - skillsPlan := buildPlan(targets, installer.ScopeGlobal, true, false) + skillsPlan := buildPlan(t.Context(), targets, installer.ScopeGlobal, true, false) for _, it := range skillsPlan { assert.Equal(t, deliverySkills, it.delivery) } @@ -253,10 +285,11 @@ func choicePreselected(t *testing.T, choices []agentChoice, name string) bool { } func TestBuildPlanProjectScopeSkipsUserOnlyAgent(t *testing.T) { + fakeBinsOnPath(t, "claude", "codex") claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") codex := testPluginAgent(agents.NameCodex, "Codex CLI", "codex") - plan := buildPlan([]*agents.Agent{claude, codex}, installer.ScopeProject, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeProject, false, false) assert.Equal(t, deliveryPlugin, plan[0].delivery) assert.Equal(t, agentScopeProject, plan[0].scope) assert.Equal(t, deliverySkip, plan[1].delivery) @@ -269,17 +302,17 @@ func TestBuildPlanProjectScopeSkipsFilesOnlyAgent(t *testing.T) { opencode := &agents.Agent{Name: agents.NameOpenCode, DisplayName: "OpenCode", Binary: "opencode"} projectSkills := &agents.Agent{Name: "proj-skills", DisplayName: "Proj", Binary: "proj", SupportsProjectScope: true} - plan := buildPlan([]*agents.Agent{opencode, projectSkills}, installer.ScopeProject, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{opencode, projectSkills}, installer.ScopeProject, false, false) assert.Equal(t, deliverySkip, plan[0].delivery) assert.Contains(t, plan[0].reason, "project-scoped skills") assert.Equal(t, deliverySkills, plan[1].delivery) // --skills-only does not rescue a project-incompatible agent. - skillsOnly := buildPlan([]*agents.Agent{opencode}, installer.ScopeProject, true, false) + skillsOnly := buildPlan(t.Context(), []*agents.Agent{opencode}, installer.ScopeProject, true, false) assert.Equal(t, deliverySkip, skillsOnly[0].delivery) // Under global scope the same agent gets skills. - globalPlan := buildPlan([]*agents.Agent{opencode}, installer.ScopeGlobal, false, false) + globalPlan := buildPlan(t.Context(), []*agents.Agent{opencode}, installer.ScopeGlobal, false, false) assert.Equal(t, deliverySkills, globalPlan[0].delivery) } @@ -302,12 +335,13 @@ func TestMapAgentScope(t *testing.T) { func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude", "codex") orig := installPluginForAgentFn origRec := recordPluginInstallsFn t.Cleanup(func() { installPluginForAgentFn = orig; recordPluginInstallsFn = origRec }) installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { if a.Name == agents.NameClaudeCode { - return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonCLINotOnPath} + return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed} } return installer.PluginRecord{Version: "0.2.6"}, nil } @@ -322,17 +356,17 @@ func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { // Non-explicit blocked install is a warning, not an error, as long as another // agent was set up; the agent's failure is still recorded in its outcome. - plan := buildPlan([]*agents.Agent{claude, codex}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.NoError(t, err) require.Len(t, outcomes, 2) assert.Equal(t, outcomeFailed, outcomes[0].status) - assert.Equal(t, protos.AitoolsErrorCategoryCLINotOnPath, outcomes[0].errorCategory) + assert.Equal(t, protos.AitoolsErrorCategoryPluginInstallFailed, outcomes[0].errorCategory) assert.Equal(t, outcomeInstalled, outcomes[1].status) // Explicit (--agents) blocked install is an error, even when another named // agent was set up. - planExplicit := buildPlan([]*agents.Agent{claude, codex}, installer.ScopeGlobal, false, true) + planExplicit := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeGlobal, false, true) _, err = executePlan(ctx, nil, planExplicit, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.Error(t, err) assert.NotErrorIs(t, err, errNoAgentSetUp) @@ -340,6 +374,7 @@ func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { func TestExecutePlanNothingInstalledIsAnError(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") orig := installPluginForAgentFn t.Cleanup(func() { installPluginForAgentFn = orig }) installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { @@ -350,7 +385,7 @@ func TestExecutePlanNothingInstalledIsAnError(t *testing.T) { // used to exit 0 with only a warning, so an agent caller believed it worked. claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) - plan := buildPlan([]*agents.Agent{claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.ErrorIs(t, err, errNoAgentSetUp) @@ -397,7 +432,7 @@ func TestExecutePlanPluginWithUnresolvedSkillsRelease(t *testing.T) { } claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") - plan := buildPlan([]*agents.Agent{claude}, installer.ScopeGlobal, false, true) + plan := buildPlan(t.Context(), []*agents.Agent{claude}, installer.ScopeGlobal, false, true) outcomes, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.NoError(t, err) require.Len(t, outcomes, 1) @@ -410,6 +445,7 @@ func TestExecutePlanPluginWithUnresolvedSkillsRelease(t *testing.T) { func TestExecutePlanNoSkillsToInstall(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") plugins := setupPluginMock(t) origSkills := installSkillsForAgentsFn origCleanup := cleanupLegacyFn @@ -424,7 +460,7 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { // Only a skills agent: the run sets up nothing and fails, like an empty // --path dump. - plan := buildPlan([]*agents.Agent{cursor}, installer.ScopeGlobal, true, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor}, installer.ScopeGlobal, true, false) _, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) require.ErrorIs(t, err, installer.ErrNoSkillsResolved) assert.Error(t, topLevelFailure(err)) @@ -432,7 +468,7 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { // A plugin was installed too: the run succeeds and Cursor is skipped with // the step. ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) - plan = buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan = buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) require.NoError(t, err) require.Len(t, *plugins, 1) @@ -446,8 +482,23 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { assert.Contains(t, stderr.String(), "Skipped Cursor: no skills to install") assert.Contains(t, stderr.String(), " No skill in this release can be installed by this CLI.") + // A kept plugin counts like an installed one: the run succeeds too. + *plugins = nil + stubPluginAlreadyInstalled(t, true) + home := t.TempDir() + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude"), 0o755)) + desktopClaude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude-desktop") + desktopClaude.ConfigDir = func(context.Context) (string, error) { return filepath.Join(home, ".claude"), nil } + plan = buildPlan(t.Context(), []*agents.Agent{cursor, desktopClaude}, installer.ScopeGlobal, false, false) + outcomes, err = executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) + require.NoError(t, err) + assert.Empty(t, *plugins) + require.Len(t, outcomes, 2) + assert.Equal(t, outcomeKept, outcomes[0].status) + assert.Equal(t, outcomeSkipped, outcomes[1].status) + // Named via --agents, the skipped skills agent is an error even so. - plan = buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, true) + plan = buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, true) _, err = executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) require.ErrorIs(t, err, installer.ErrNoSkillsResolved) assert.NoError(t, topLevelFailure(err)) @@ -455,6 +506,7 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { func TestExecutePlanNoSkillsToInstallWithPluginFailures(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") setupPluginMock(t) origSkills := installSkillsForAgentsFn t.Cleanup(func() { installSkillsForAgentsFn = origSkills }) @@ -464,7 +516,7 @@ func TestExecutePlanNoSkillsToInstallWithPluginFailures(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} inv := installInvocation{scope: installer.ScopeGlobal} - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) // The plugin install failed: the run failed to set anything up, which is a // FAILURE with the plugin's category, not "nothing to do". @@ -491,9 +543,238 @@ func TestExecutePlanNoSkillsToInstallWithPluginFailures(t *testing.T) { assert.NotErrorIs(t, err, installer.ErrNoSkillsResolved) } +// A detected plugin agent whose CLI is not on PATH (a desktop or IDE install: +// ~/.claude exists, `claude` does not) gets skill files in the same skills +// batch as the other agents, or keeps the plugin it already has. This used to +// print "Skipped Claude Code" and leave the agent with nothing. +func TestExecutePlanWhenTheCLIIsMissing(t *testing.T) { + cases := []struct { + name string + pluginInstalled bool + wantBatches [][]string + wantOutcomes []string + projectPlugin bool + manifestPlugin bool // Claude Code's own manifest shows the plugin + wantCleanup []string + wantNotice string + }{ + { + name: "skill files instead of the plugin", + wantBatches: [][]string{{agents.NameCursor, agents.NameClaudeCode}}, + // The plugin failure stays visible to telemetry next to the skills + // success. + wantOutcomes: []string{"claude-code plugin failed CLI_NOT_ON_PATH", "cursor skills installed ", "claude-code skills installed "}, + wantNotice: "Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.", + }, + { + name: "skill files instead, next to a project plugin", + projectPlugin: true, + wantBatches: [][]string{{agents.NameCursor, agents.NameClaudeCode}}, + wantOutcomes: []string{"claude-code plugin failed CLI_NOT_ON_PATH", "cursor skills installed ", "claude-code skills installed "}, + wantNotice: "Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.\nClaude Code has the databricks plugin for this project, so this project will see both the plugin and the global skill files.\n", + }, + { + name: "plugin already installed is kept", + pluginInstalled: true, + manifestPlugin: true, + wantBatches: [][]string{{agents.NameCursor}}, + wantOutcomes: []string{"claude-code plugin kept CLI_NOT_ON_PATH", "cursor skills installed "}, + // Raw skills from an earlier fallback would duplicate the plugin's. + wantCleanup: []string{agents.NameClaudeCode}, + wantNotice: "Claude Code already has the databricks plugin; it was not refreshed because 'claude' is not on PATH. To refresh it, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.", + }, + { + // Only the CLI's record says so (as for Codex and Copilot), and it + // outlives a removal with the agent's own CLI: the raw skills stay. + name: "plugin kept on the CLI's record alone", + pluginInstalled: true, + wantBatches: [][]string{{agents.NameCursor}}, + wantOutcomes: []string{"claude-code plugin kept CLI_NOT_ON_PATH", "cursor skills installed "}, + wantNotice: "Claude Code already has the databricks plugin", + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + // First: it resets the environment set below. + isolateAgents(t) + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t) + // The fallback rewrites the install state under HOME. + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + stubPluginAlreadyInstalled(t, tc.pluginInstalled) + skills := setupInstallMock(t) + plugins := setupPluginMock(t) + var cleaned []string + orig := cleanupLegacyFn + t.Cleanup(func() { cleanupLegacyFn = orig }) + cleanupLegacyFn = func(_ context.Context, a *agents.Agent, _ string) error { + cleaned = append(cleaned, a.Name) + return nil + } + + // Detected by its config dir (a desktop or IDE install). + t.Chdir(t.TempDir()) + claude := agents.ByName(agents.NameClaudeCode) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + if tc.manifestPlugin { + writeClaudeManifest(t, home, "user", "") + } + cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + // planItemFor reads the project plugin from Claude Code's manifest + // (see TestPluginAlreadyInstalledRespectsTheScope); set it here. + plan[1].projectPlugin = tc.projectPlugin + outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) + + require.NoError(t, err) + assert.Empty(t, *plugins, "no plugin install without the CLI") + var batches [][]string + for _, c := range *skills { + batches = append(batches, c.agents) + } + assert.Equal(t, tc.wantBatches, batches) + var got []string + for _, o := range outcomes { + got = append(got, fmt.Sprintf("%s %s %s %s", o.agent.Name, o.delivery, o.status, o.errorCategory)) + } + assert.Equal(t, tc.wantOutcomes, got) + assert.Equal(t, tc.wantCleanup, cleaned) + assert.Contains(t, stderr.String(), tc.wantNotice) + }) + } +} + +// After a picker selection the recovery re-run names the agents, and a named +// agent never falls back, so a failed skills batch that included an agent +// whose CLI is missing is re-run with --skills-only. +func TestExecutePlanSkillsFailureWithAFallbackAgentSuggestsSkillsOnly(t *testing.T) { + isolateAgents(t) + home := setupTestAgents(t) // ~/.claude without `claude`: a desktop install + fakeBinsOnPath(t) + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + t.Chdir(t.TempDir()) + stubPluginAlreadyInstalled(t, false) + origSkills := installSkillsForAgentsFn + t.Cleanup(func() { installSkillsForAgentsFn = origSkills }) + fetchErr := &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: 503, Err: errors.New("failed to fetch manifest: HTTP 503")} + installSkillsForAgentsFn = func(context.Context, installer.ManifestSource, []*agents.Agent, installer.InstallOptions) error { + return fetchErr + } + require.DirExists(t, filepath.Join(home, ".claude")) + + claude := agents.ByName(agents.NameClaudeCode) + cursor := agents.ByName(agents.NameCursor) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + require.True(t, plan[1].cliMissing) + + picked := installInvocation{scope: installer.ScopeGlobal, agents: "cursor,claude-code"} + _, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, picked, true) + require.ErrorIs(t, err, fetchErr) + err = withRecovery(t.Context(), picked, err) + // The value's quoting depends on the shell, so check its parts. + assert.Contains(t, err.Error(), "cursor,claude-code") + assert.Contains(t, err.Error(), " --skills-only") + + // Without a picker selection the re-run detects the same agents, which + // fall back again, so it stays as it is. + _, err = executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, true) + err = withRecovery(t.Context(), installInvocation{scope: installer.ScopeGlobal}, err) + assert.NotContains(t, err.Error(), "--skills-only") +} + +// A release with no skill this CLI can install skips the skills agents when a +// plugin was installed. After a picker selection that named a fallback agent, +// the skip's step re-runs the skills agents with --skills-only, as a failed +// skills batch does: re-run by name, the agent would try its plugin. +func TestExecutePlanNoSkillsWithAFallbackAgentSuggestsSkillsOnly(t *testing.T) { + isolateAgents(t) + setupTestAgents(t) // ~/.claude without `claude`: a desktop install + fakeBinsOnPath(t, "codex") + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + t.Chdir(t.TempDir()) + stubPluginAlreadyInstalled(t, false) + stubLegacyCleanup(t) + plugins := setupPluginMock(t) + origSkills := installSkillsForAgentsFn + t.Cleanup(func() { installSkillsForAgentsFn = origSkills }) + installSkillsForAgentsFn = func(context.Context, installer.ManifestSource, []*agents.Agent, installer.InstallOptions) error { + return installer.ErrNoSkillsResolved + } + + claude := agents.ByName(agents.NameClaudeCode) + codex := testPluginAgent(agents.NameCodex, "Codex CLI", "codex") + plan := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeGlobal, false, false) + require.True(t, plan[0].cliMissing) + + picked := installInvocation{scope: installer.ScopeGlobal, agents: "claude-code,codex"} + outcomes, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, picked, true) + require.NoError(t, err) + require.Len(t, *plugins, 1) + var skipped *agentOutcome + for i := range outcomes { + if outcomes[i].delivery == deliverySkills { + skipped = &outcomes[i] + } + } + require.NotNil(t, skipped) + assert.Equal(t, agents.NameClaudeCode, skipped.agent.Name) + assert.Contains(t, skipped.recovery, "claude-code") + assert.Contains(t, skipped.recovery, " --skills-only") + assert.NotContains(t, skipped.recovery, "codex") +} + +// The plan decides the fallback, so the picker label, the plan summary and the +// outcomes agree on it. It applies only to a detected agent whose CLI is not on +// PATH: a named agent keeps failing with the commands to run. +func TestPlanItemForAgentWithoutCLI(t *testing.T) { + cases := []struct { + name string + agent string + scope string + onPath bool + explicit bool + pluginInstalled bool + wantDelivery delivery + wantCLIMissing bool + wantLabel string + }{ + {name: "CLI on PATH", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, onPath: true, wantDelivery: deliveryPlugin, wantLabel: "plugin"}, + {name: "CLI missing", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, wantDelivery: deliverySkills, wantCLIMissing: true, wantLabel: "skills · CLI not found"}, + {name: "CLI missing, plugin installed", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, pluginInstalled: true, wantDelivery: deliveryPlugin, wantCLIMissing: true, wantLabel: "plugin installed · CLI not found"}, + {name: "CLI missing, named via --agents", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, explicit: true, wantDelivery: deliveryPlugin, wantLabel: "plugin · CLI not found"}, + {name: "CLI missing, scope unsupported", agent: agents.NameCodex, scope: installer.ScopeProject, wantDelivery: deliverySkip, wantLabel: "plugin · CLI not found · Codex CLI is user-only; project scope is not supported"}, + // Neither its config dir nor its CLI exists: the picker still lists it, + // but picking it must not write skill files for an agent that is not + // installed. + {name: "not installed", agent: agents.NameCopilot, scope: installer.ScopeGlobal, wantDelivery: deliveryPlugin, wantLabel: "not found"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + home := setupTestAgents(t) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".codex"), 0o755)) + if tc.onPath { + fakeBinsOnPath(t, "claude", "codex") + } else { + fakeBinsOnPath(t) + } + stubPluginAlreadyInstalled(t, tc.pluginInstalled) + a := agents.ByName(tc.agent) + + item := planItemFor(t.Context(), a, tc.scope, false, tc.explicit) + assert.Equal(t, tc.wantDelivery, item.delivery) + assert.Equal(t, tc.wantCLIMissing, item.cliMissing) + assert.Equal(t, tc.wantLabel, agentChoiceLabel(t.Context(), a, item, false)) + }) + } +} + func TestExecutePlanSkillsFailureStillInstallsPlugins(t *testing.T) { setupTestAgents(t) // temp HOME for the real state file below t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") plugins := setupPluginMock(t) recordPluginInstallsFn = installer.RecordPluginInstalls origSkills := installSkillsForAgentsFn @@ -517,7 +798,7 @@ func TestExecutePlanSkillsFailureStillInstallsPlugins(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) // The skills failure is still the command's error, but it no longer stops @@ -538,6 +819,7 @@ func TestExecutePlanSkillsFailureStillInstallsPlugins(t *testing.T) { func TestExecutePlanSkillsFailureKeepsUntrackedSkillsVisible(t *testing.T) { setupTestAgents(t) + fakeBinsOnPath(t, "claude") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") plugins := setupPluginMock(t) recordPluginInstallsFn = installer.RecordPluginInstalls @@ -559,7 +841,7 @@ func TestExecutePlanSkillsFailureKeepsUntrackedSkillsVisible(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.ErrorIs(t, err, fetchErr) @@ -578,6 +860,7 @@ func TestExecutePlanSkillsFailureKeepsUntrackedSkillsVisible(t *testing.T) { func TestExecutePlanSkillsAndStateWriteFailuresAreJoined(t *testing.T) { setupTestAgents(t) // temp HOME: the skills failure path reads the global skills dir t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") setupPluginMock(t) origSkills := installSkillsForAgentsFn origCleanup := cleanupLegacyFn @@ -595,7 +878,7 @@ func TestExecutePlanSkillsAndStateWriteFailuresAreJoined(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} ctx := cmdio.MockDiscard(t.Context()) - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) _, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) // Both failures reach the user, the skills one first. @@ -1340,6 +1623,132 @@ func TestInstallPickerAbortSuggestsFlags(t *testing.T) { assert.Equal(t, "user aborted\nTo install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=", err.Error()) } +// The skills fallback is skipped only when the plugin already serves the +// install's scope: a global install serves every project, so only a +// machine-wide plugin covers it, and a project or local plugin counts only for +// a project-scope install inside its own project. +func TestPluginAlreadyInstalledRespectsTheScope(t *testing.T) { + project, other := t.TempDir(), t.TempDir() + // A project install is shared through the repository, so only a + // project-scope plugin of this project covers it; a user or local plugin is + // personal. A fallback warns when this directory sees a plugin that does not + // cover the install next to the skill files: a project or local plugin for a + // global install, a user or local plugin for a project install. + cases := []struct { + name string + scope, projectPath string + wantGlobal, wantInProj bool + wantWarning bool + wantProjectWarning bool + }{ + {name: "user scope", scope: "user", wantGlobal: true, wantProjectWarning: true}, + {name: "project scope of this project", scope: "project", projectPath: project, wantInProj: true, wantWarning: true}, + {name: "local scope of this project", scope: "local", projectPath: project, wantWarning: true, wantProjectWarning: true}, + {name: "project scope of another project", scope: "project", projectPath: other}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + writeClaudeManifest(t, home, tc.scope, tc.projectPath) + t.Chdir(project) + + claude := agents.ByName(agents.NameClaudeCode) + assert.Equal(t, tc.wantGlobal, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal), "global install") + assert.Equal(t, tc.wantInProj, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeProject), "project install") + + // Without the CLI, a global install that falls back to skill files + // flags a project or local plugin of this project: it sees both. + fakeBinsOnPath(t) + item := planItemFor(t.Context(), claude, installer.ScopeGlobal, false, false) + assert.Equal(t, tc.wantWarning, item.projectPlugin, "project plugin next to a global fallback") + item = planItemFor(t.Context(), claude, installer.ScopeProject, false, false) + assert.Equal(t, tc.wantProjectWarning, item.projectPlugin, "personal plugin next to a project fallback") + }) + } +} + +// Removing the plugin with Claude Code's own CLI leaves the CLI's state record +// behind; Claude's manifest is authoritative, so the record must not keep the +// skills fallback from running. +func TestPluginAlreadyInstalledTrustsClaudesManifestOverTheState(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Chdir(t.TempDir()) + require.NoError(t, installer.RecordPluginInstalls(t.Context(), installer.ScopeGlobal, map[string]installer.PluginRecord{ + agents.NameClaudeCode: {Marketplace: "claude-plugins-official", Plugin: "databricks"}, + }, "v0.2.6")) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(home, ".claude", "plugins", "installed_plugins.json"), []byte(`{"plugins":{}}`), 0o600)) + + claude := agents.ByName(agents.NameClaudeCode) + assert.False(t, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal)) + + // The fallback install drops the stale record, so list stops reporting the + // removed plugin and update reconciles Claude Code's skill files again. + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t) + setupInstallMock(t) + ctx := cmdio.MockDiscard(t.Context()) + plan := buildPlan(t.Context(), []*agents.Agent{claude}, installer.ScopeGlobal, false, false) + _, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, true) + require.NoError(t, err) + + dir, err := installer.GlobalSkillsDir(ctx) + require.NoError(t, err) + state, err := installer.LoadState(dir) + require.NoError(t, err) + assert.NotContains(t, state.Plugins, agents.NameClaudeCode) + fileAgents, _ := excludePluginAgents(ctx, installer.ScopeGlobal, []*agents.Agent{claude}, state) + assert.Equal(t, []*agents.Agent{claude}, fileAgents) + for _, e := range buildAgentEntries(ctx, map[string]*installer.InstallState{installer.ScopeGlobal: state}) { + if e.Name == agents.NameClaudeCode { + assert.NotEqual(t, deliveryPlugin.String(), e.Installed[installer.ScopeGlobal].Delivery) + } + } +} + +// A manifest that exists but cannot be parsed says nothing about the plugin, +// so the CLI's record decides instead of dropping it. +func TestPluginAlreadyInstalledUsesTheStateWhenTheManifestIsUnreadable(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Chdir(t.TempDir()) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(home, ".claude", "plugins", "installed_plugins.json"), []byte(`{not json`), 0o600)) + + claude := agents.ByName(agents.NameClaudeCode) + assert.False(t, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal)) + require.NoError(t, installer.RecordPluginInstalls(t.Context(), installer.ScopeGlobal, map[string]installer.PluginRecord{ + agents.NameClaudeCode: {Marketplace: "claude-plugins-official", Plugin: "databricks"}, + }, "v0.2.6")) + assert.True(t, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal)) +} + +func TestPluginAlreadyInstalledReadsTheScopeState(t *testing.T) { + tmp := t.TempDir() + t.Setenv("HOME", tmp) + t.Setenv("USERPROFILE", tmp) + claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") + claude.ConfigDir = func(context.Context) (string, error) { return filepath.Join(tmp, ".claude"), nil } + ctx := t.Context() + assert.False(t, pluginAlreadyInstalled(ctx, claude, installer.ScopeGlobal)) + + dir, err := installer.GlobalSkillsDir(ctx) + require.NoError(t, err) + require.NoError(t, installer.RecordPluginInstalls(ctx, installer.ScopeGlobal, map[string]installer.PluginRecord{ + agents.NameClaudeCode: {Marketplace: "claude-plugins-official", Plugin: "databricks"}, + }, "v0.2.6")) + require.FileExists(t, filepath.Join(dir, ".state.json")) + assert.True(t, pluginAlreadyInstalled(ctx, claude, installer.ScopeGlobal)) +} + func TestInstallPathFailureHasRecoveryForThePathRun(t *testing.T) { setupTestAgents(t) t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") diff --git a/cmd/aitools/recovery.go b/cmd/aitools/recovery.go index b64988c78c0..ebb02260ca3 100644 --- a/cmd/aitools/recovery.go +++ b/cmd/aitools/recovery.go @@ -173,6 +173,10 @@ func withRecovery(ctx context.Context, inv installInvocation, err error) error { if err == nil { return nil } + // A step attached closer to the failure (see skillsBatchError) wins. + if _, ok := errors.AsType[*recoveryError](err); ok { + return err + } step := installRecovery(ctx, inv, err) if step == "" { return err @@ -453,7 +457,7 @@ func pluginFailureText(ctx context.Context, inv installInvocation, it agentPlanI return fmt.Sprintf("'%s plugin' is not available (%s)", a.Binary, blocked.Detail), fmt.Sprintf("Update the %s CLI to a version with the '%s plugin' command, then re-run %s. Or install skill files instead: %s", a.DisplayName, a.Binary, agentRerun(inv, it), skillsOnlyCommand(inv, it)) } - return fmt.Sprintf("'%s' is not on PATH", a.Binary), + return cliMissingReason(it), fmt.Sprintf("Install or update the %s CLI so '%s' is on PATH, then re-run %s. Or install skill files instead: %s", a.DisplayName, a.Binary, agentRerun(inv, it), skillsOnlyCommand(inv, it)) case blocked.Reason == installer.ReasonShimExitedWithError: // Detail carries the captured stderr and the commands that show the @@ -476,3 +480,37 @@ func skipRecovery(inv installInvocation, it agentPlanItem) string { inv.scope = installer.ScopeGlobal return "To set up " + it.agent.DisplayName + " in the global scope, run: " + installCommand(inv, it) } + +// cliMissingReason is why an agent whose CLI is not on PATH does not get the +// plugin. +func cliMissingReason(it agentPlanItem) string { + return fmt.Sprintf("'%s' is not on PATH", it.agent.Binary) +} + +// switchToPluginStep is how an agent whose CLI is missing gets the plugin later. +func switchToPluginStep(inv installInvocation, it agentPlanItem) string { + return fmt.Sprintf("install the %s CLI so '%s' is on PATH and run %s", it.agent.DisplayName, it.agent.Binary, agentRerun(inv, it)) +} + +// skillsFallbackText is the notice printed when an agent gets skill files +// instead of the plugin because its CLI is missing. +func skillsFallbackText(inv installInvocation, it agentPlanItem) string { + return fmt.Sprintf("Skipped the plugin for %s: %s. Installing skill files instead; to switch to the plugin, %s.", + it.agent.DisplayName, cliMissingReason(it), switchToPluginStep(inv, it)) +} + +// projectPluginWarning is printed when a skills fallback runs in a directory +// where the agent already loads a plugin that does not cover the install scope. +func projectPluginWarning(scope string, it agentPlanItem) string { + if scope == installer.ScopeProject { + return it.agent.DisplayName + " has a personal databricks plugin, so you will see both the plugin and this project's skill files here." + } + return it.agent.DisplayName + " has the databricks plugin for this project, so this project will see both the plugin and the global skill files." +} + +// pluginKeptText is the notice for an agent whose CLI is missing but which +// already has the plugin, so no skill files are added next to it. +func pluginKeptText(inv installInvocation, it agentPlanItem) string { + return fmt.Sprintf("%s already has the databricks plugin; it was not refreshed because %s. To refresh it, %s.", + it.agent.DisplayName, cliMissingReason(it), switchToPluginStep(inv, it)) +} diff --git a/cmd/aitools/recovery_test.go b/cmd/aitools/recovery_test.go index 430306abf9c..5c7852d865a 100644 --- a/cmd/aitools/recovery_test.go +++ b/cmd/aitools/recovery_test.go @@ -331,6 +331,8 @@ func TestRecoveryCommandsKeepTheProjectScope(t *testing.T) { notOnPath := &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "not found"} _, recovery := pluginFailureText(t.Context(), inv, item, notOnPath) assert.Equal(t, "Install or update the Claude Code CLI so 'claude' is on PATH, then re-run '"+want+"'. Or install skill files instead: "+want+" --skills-only", recovery) + assert.Contains(t, skillsFallbackText(inv, item), "run '"+want+"'.") + assert.Contains(t, pluginKeptText(inv, item), "run '"+want+"'.") timedOut := &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "timed out after 20s", TimedOut: true} _, recovery = pluginFailureText(t.Context(), inv, item, timedOut) diff --git a/cmd/aitools/update.go b/cmd/aitools/update.go index 0c23f6d02e5..bdddafbc56c 100644 --- a/cmd/aitools/update.go +++ b/cmd/aitools/update.go @@ -196,7 +196,30 @@ The command exits with code 1 when every update or check it attempts fails.`, targetAgents = mergeAgents(installed, agents.DetectProjectInstalled(cwd)) } - result, err := updateSkillsFn(ctx, src, excludePluginAgents(targetAgents, state), opts) + fileAgents, manifestPlugins := excludePluginAgents(ctx, scope, targetAgents, state) + // Raw skills an earlier install gave an agent that now has the + // plugin would show every skill twice, so remove them as + // install does when it keeps the plugin. + if !check { + for _, a := range manifestPlugins { + if err := updateCleanupLegacyFn(ctx, a, scope); err != nil { + log.Debugf(ctx, "Legacy skill cleanup for %s failed: %v", a.DisplayName, err) + } + } + } + // The plugin agents left no agent that can take file skills in + // this scope, so there is nothing to reconcile. Without this, a + // project whose only project-capable agent has the plugin would + // fail the update with "no agents support project-scoped skills". + // Without install state the reconcile still runs, for the + // "no skills or plugins installed" and legacy-install guidance. + if state != nil && len(manifestPlugins) > 0 && !slices.ContainsFunc(fileAgents, func(a *agents.Agent) bool { + return scope != installer.ScopeProject || a.SupportsProjectScope + }) { + continue + } + + result, err := updateSkillsFn(ctx, src, fileAgents, opts) if err != nil { return err } @@ -258,9 +281,13 @@ func pluginMigrationCandidatesForScope(ctx context.Context, scope string, state if !ok { continue } - // Match install's non-interactive behavior: a raw install for a plugin - // agent should attempt migration and report a skip if its CLI is missing, - // rather than silently staying on raw skills forever. + // Match install's behavior: an agent whose CLI is not on PATH keeps its + // raw skills, which update refreshes, until the CLI is there to install + // the plugin with. An agent with the CLI attempts migration and reports + // a skip if it fails, rather than silently staying on raw skills forever. + if !agent.HasBinary(ctx) { + continue + } hasRawSkills, err := hasManagedRawSkillsForAgentFn(ctx, agent, scope) if err != nil { return nil, err @@ -341,19 +368,31 @@ func mergeAgents(installed, project []*agents.Agent) []*agents.Agent { return merged } -// excludePluginAgents drops agents that are managed as plugins in this scope, so -// the file-skills reconcile never drops duplicate skill files onto a plugin agent. -func excludePluginAgents(installed []*agents.Agent, state *installer.InstallState) []*agents.Agent { - if state == nil || len(state.Plugins) == 0 { - return installed - } - out := make([]*agents.Agent, 0, len(installed)) +// excludePluginAgents splits off agents that have the plugin in this scope, so +// the file-skills reconcile never drops duplicate skill files onto a plugin +// agent. That is an agent the CLI recorded a plugin install for, or one whose +// own manifest shows a plugin serving the scope (see manifestPluginActive) while +// its CLI is missing: install keeps such a plugin, without recording it. With +// the CLI on PATH, raw skills next to the plugin are the user's choice (install +// --skills-only), so they are refreshed as before. manifestPlugins lists the +// agents excluded for their manifest. +func excludePluginAgents(ctx context.Context, scope string, installed []*agents.Agent, state *installer.InstallState) (fileAgents, manifestPlugins []*agents.Agent) { + fileAgents = make([]*agents.Agent, 0, len(installed)) for _, a := range installed { - if _, isPlugin := state.Plugins[a.Name]; !isPlugin { - out = append(out, a) + if state != nil { + if _, isPlugin := state.Plugins[a.Name]; isPlugin { + continue + } + } + if !a.HasBinary(ctx) { + if active, err := manifestPluginActive(ctx, a, scope); err == nil && active { + manifestPlugins = append(manifestPlugins, a) + continue + } } + fileAgents = append(fileAgents, a) } - return out + return fileAgents, manifestPlugins } // hasKnownPluginRecord reports whether state records a plugin for an agent this diff --git a/cmd/aitools/update_test.go b/cmd/aitools/update_test.go index 86c4aa0182e..74e869213ac 100644 --- a/cmd/aitools/update_test.go +++ b/cmd/aitools/update_test.go @@ -118,6 +118,7 @@ func testUpdateCheckPrintsPluginState(t *testing.T, version, want string) { func TestUpdateMigratesManagedRawSkillsToPlugins(t *testing.T) { noTelemetryAuth(t) setupTestAgents(t) + fakeBinsOnPath(t, "claude", "codex", "copilot") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") resetUpdatePluginSeams(t) @@ -193,6 +194,7 @@ func TestUpdateMigratesManagedRawSkillsToPlugins(t *testing.T) { func TestUpdateKeepsRawSkillsWhenPluginMigrationStateWriteFails(t *testing.T) { noTelemetryAuth(t) setupTestAgents(t) + fakeBinsOnPath(t, "claude", "codex", "copilot") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") resetUpdatePluginSeams(t) @@ -258,6 +260,7 @@ func TestUpdateKeepsRawSkillsWhenPluginMigrationStateWriteFails(t *testing.T) { func TestUpdateCheckPrintsPluginMigrationPlan(t *testing.T) { noTelemetryAuth(t) setupTestAgents(t) + fakeBinsOnPath(t, "claude", "codex", "copilot") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") resetUpdatePluginSeams(t) setupUpdateMock(t) @@ -469,3 +472,147 @@ func TestHasKnownPluginRecord(t *testing.T) { assert.False(t, hasKnownPluginRecord(&installer.InstallState{Plugins: map[string]installer.PluginRecord{"aider": {}}})) assert.True(t, hasKnownPluginRecord(&installer.InstallState{Plugins: map[string]installer.PluginRecord{"aider": {}, agents.NameCodex: {}}})) } + +// A plugin agent whose CLI is not on PATH keeps the raw skills install gave it, +// so update does not try, and fail, to migrate it to the plugin on every run. +func TestPluginMigrationCandidatesNeedTheCLI(t *testing.T) { + setupTestAgents(t) + fakeBinsOnPath(t, "codex") + resetUpdatePluginSeams(t) + hasManagedRawSkillsForAgentFn = func(context.Context, *agents.Agent, string) (bool, error) { return true, nil } + + candidates, err := pluginMigrationCandidatesForScope(t.Context(), installer.ScopeGlobal, nil) + require.NoError(t, err) + var names []string + for _, c := range candidates { + names = append(names, c.agent.Name) + } + assert.Equal(t, []string{agents.NameCodex}, names) +} + +// Install keeps a plugin installed with Claude Code's own CLI without recording +// it, so update must not write the raw skills back next to it. A project's +// skill files are shared, so at project scope only a project-scope plugin of +// this project excludes the agent; a personal (user or local) plugin does not. +func TestExcludePluginAgentsReadsTheAgentsManifest(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + project, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + t.Chdir(project) + claude := agents.ByName(agents.NameClaudeCode) + cursor := agents.ByName(agents.NameCursor) + all := []*agents.Agent{claude, cursor} + fileAgents, manifestPlugins := excludePluginAgents(t.Context(), installer.ScopeGlobal, all, nil) + assert.Equal(t, all, fileAgents) + assert.Empty(t, manifestPlugins) + + cases := []struct { + scope, projectPath string + wantGlobal bool + wantProject bool + }{ + {scope: "user", wantGlobal: true}, + {scope: "local", projectPath: project}, + {scope: "project", projectPath: project, wantProject: true}, + } + for _, tc := range cases { + writeClaudeManifest(t, home, tc.scope, tc.projectPath) + for _, c := range []struct { + cliScope string + want bool + }{{installer.ScopeGlobal, tc.wantGlobal}, {installer.ScopeProject, tc.wantProject}} { + fileAgents, manifestPlugins := excludePluginAgents(t.Context(), c.cliScope, all, nil) + if c.want { + assert.Equal(t, []*agents.Agent{cursor}, fileAgents, "%s plugin, %s update", tc.scope, c.cliScope) + assert.Equal(t, []*agents.Agent{claude}, manifestPlugins, "%s plugin, %s update", tc.scope, c.cliScope) + } else { + assert.Equal(t, all, fileAgents, "%s plugin, %s update", tc.scope, c.cliScope) + assert.Empty(t, manifestPlugins, "%s plugin, %s update", tc.scope, c.cliScope) + } + } + } + + // With the CLI on PATH, raw skills next to the plugin are the user's choice + // (install --skills-only), so they are refreshed and not removed. + writeClaudeManifest(t, home, "user", "") + fakeBinsOnPath(t, "claude") + fileAgents, manifestPlugins = excludePluginAgents(t.Context(), installer.ScopeGlobal, all, nil) + assert.Equal(t, all, fileAgents) + assert.Empty(t, manifestPlugins) + + // A recorded plugin is excluded too, without a manifest reader. + state := &installer.InstallState{Plugins: map[string]installer.PluginRecord{agents.NameCursor: {}}} + fileAgents, _ = excludePluginAgents(t.Context(), installer.ScopeGlobal, all, state) + assert.Equal(t, []*agents.Agent{claude}, fileAgents) +} + +// A project whose only project-capable agent has a project-scope plugin of its +// own has no agent to reconcile file skills for. The update used to fail with +// "no agents support project-scoped skills"; it now skips the reconcile and +// removes the raw skills an earlier install gave that agent. +func TestUpdateProjectScopeSkipsWhenOnlyPluginAgentsRemain(t *testing.T) { + noTelemetryAuth(t) + home := setupTestAgents(t) + fakeBinsOnPath(t) + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + resetUpdatePluginSeams(t) + project, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + t.Chdir(project) + writeClaudeManifest(t, home, "project", project) + + origUpdateSkills := updateSkillsFn + t.Cleanup(func() { updateSkillsFn = origUpdateSkills }) + updateSkillsFn = func(context.Context, installer.ManifestSource, []*agents.Agent, installer.UpdateOptions) (*installer.UpdateResult, error) { + require.Fail(t, "no agent is left to reconcile file skills for") + return nil, nil + } + updatePluginsFn = func(context.Context, string, string) ([]installer.PluginUpdate, error) { return nil, nil } + var cleaned []string + updateCleanupLegacyFn = func(_ context.Context, a *agents.Agent, scope string) error { + cleaned = append(cleaned, a.Name+" "+scope) + return nil + } + + ctx := cmdio.MockDiscard(t.Context()) + dir, err := installer.ProjectSkillsDir(ctx) + require.NoError(t, err) + require.NoError(t, installer.SaveState(dir, &installer.InstallState{ + SchemaVersion: 2, + Release: "v0.2.5", + Skills: map[string]string{"databricks": "0.2.5"}, + })) + + cmd := NewUpdateCmd() + cmd.SetContext(ctx) + cmd.SetArgs([]string{"--scope", "project"}) + require.NoError(t, cmd.Execute()) + assert.Equal(t, []string{agents.NameClaudeCode + " project"}, cleaned) +} + +// Without install state the reconcile still runs when every detected agent has +// the plugin and no CLI, so update keeps telling the user to run install +// instead of exiting 0 having done nothing. +func TestUpdateWithoutStateKeepsTheInstallGuidance(t *testing.T) { + noTelemetryAuth(t) + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config")) + fakeBinsOnPath(t) + t.Chdir(t.TempDir()) + resetUpdatePluginSeams(t) + writeClaudeManifest(t, home, "user", "") + updateCleanupLegacyFn = func(context.Context, *agents.Agent, string) error { return nil } + + ctx := cmdio.MockDiscard(t.Context()) + cmd := NewUpdateCmd() + cmd.SetContext(ctx) + cmd.SetArgs(nil) + err := cmd.Execute() + require.ErrorIs(t, err, installer.ErrNothingInstalled) +} diff --git a/libs/aitools/agents/agents.go b/libs/aitools/agents/agents.go index a8f59f037b0..92b11077d14 100644 --- a/libs/aitools/agents/agents.go +++ b/libs/aitools/agents/agents.go @@ -61,8 +61,9 @@ type Agent struct { // set per agent (only for formats we have verified); when nil, // DatabricksPluginVersion reports no version and DatabricksTooling falls // back to the CLI install state. New agents extend support by providing - // their own reader here. - pluginInstalls func(ctx context.Context, a *Agent) ([]pluginInstall, bool) + // their own reader here. found is false when the manifest has no databricks + // entry or does not exist; an error means it exists but could not be read. + pluginInstalls func(ctx context.Context, a *Agent) (installs []pluginInstall, found bool, err error) } // Detected reports whether the agent is installed: its config directory exists, diff --git a/libs/aitools/agents/calling.go b/libs/aitools/agents/calling.go index 6e91d7fc9f1..6bb35c3e14b 100644 --- a/libs/aitools/agents/calling.go +++ b/libs/aitools/agents/calling.go @@ -72,7 +72,7 @@ func (a *Agent) DatabricksTooling(ctx context.Context, pluginRecorded func() boo } switch { case a.pluginInstalls != nil: - if a.databricksPluginActiveIn(ctx, cwd) { + if active, _ := a.DatabricksPluginActiveIn(ctx, cwd); active { return ToolingPlugin } case a.Plugin != nil: diff --git a/libs/aitools/agents/plugins.go b/libs/aitools/agents/plugins.go index 794d5c7f4d2..bbac9c443f4 100644 --- a/libs/aitools/agents/plugins.go +++ b/libs/aitools/agents/plugins.go @@ -3,6 +3,9 @@ package agents import ( "context" "encoding/json" + "errors" + "fmt" + "io/fs" "os" "path/filepath" "strings" @@ -15,6 +18,12 @@ import ( // entry as "@" (e.g. "databricks@claude-plugins-official"). const pluginManifestFile = "installed_plugins.json" +// Claude Code's install scopes that apply only inside one project. +const ( + claudeScopeProject = "project" + claudeScopeLocal = "local" +) + // pluginInstall is one install record in an agent's plugin manifest. A plugin // installed in more than one scope has several records. Claude Code documents // the record's scope and version and what each scope covers: @@ -38,7 +47,7 @@ type pluginInstall struct { // must be resolved (see resolvePath). func (p pluginInstall) appliesTo(cwd string) bool { switch p.Scope { - case "project", "local": + case claudeScopeProject, claudeScopeLocal: if p.ProjectPath == "" || cwd == "" { return false } @@ -101,8 +110,8 @@ func (a *Agent) DatabricksPluginVersion(ctx context.Context) (string, bool) { if a.pluginInstalls == nil { return "", false } - installs, ok := a.pluginInstalls(ctx, a) - if !ok { + installs, found, err := a.pluginInstalls(ctx, a) + if err != nil || !found { return "", false } best := "" @@ -115,40 +124,87 @@ func (a *Agent) DatabricksPluginVersion(ctx context.Context) (string, bool) { return best, true } -// databricksPluginActiveIn reports whether the agent's own manifest has a +// HasPluginManifestReader reports whether the CLI can read the agent's own +// plugin manifest (Claude Code), not whether the manifest file exists. For such +// agents the manifest is authoritative: a plugin removed with the agent's own +// CLI leaves the CLI's state record behind. +func (a *Agent) HasPluginManifestReader() bool { + return a.pluginInstalls != nil +} + +// DatabricksPluginActiveIn reports whether the agent's own manifest has a // databricks plugin record that applies in cwd (see pluginInstall.appliesTo). // A plugin disabled in the agent's settings still counts. -func (a *Agent) databricksPluginActiveIn(ctx context.Context, cwd string) bool { - installs, _ := a.pluginInstalls(ctx, a) +// With cwd "", only machine-wide records (not project or local ones) count. +// cwd is resolved here, so a working directory reached through a symlink is +// matched by the directory it points to. A missing manifest reports false; an +// error means the manifest exists but could not be read, so the answer is +// unknown. +func (a *Agent) DatabricksPluginActiveIn(ctx context.Context, cwd string) (bool, error) { + if a.pluginInstalls == nil { + return false, nil + } + if cwd != "" { + cwd = resolvePath(cwd) + } + installs, _, err := a.pluginInstalls(ctx, a) + if err != nil { + return false, err + } for _, install := range installs { if install.appliesTo(cwd) { - return true + return true, nil } } - return false + return false, nil +} + +// DatabricksProjectPluginIn reports whether the agent's own manifest has a +// project-scope databricks plugin record for the project that contains cwd: +// the plugin a project shares through its repository. Machine-wide and local +// records are personal and do not count. A missing manifest reports false; an +// error means the manifest exists but could not be read. +func (a *Agent) DatabricksProjectPluginIn(ctx context.Context, cwd string) (bool, error) { + if a.pluginInstalls == nil { + return false, nil + } + cwd = resolvePath(cwd) + installs, _, err := a.pluginInstalls(ctx, a) + if err != nil { + return false, err + } + for _, install := range installs { + if install.Scope == claudeScopeProject && install.appliesTo(cwd) { + return true, nil + } + } + return false, nil } // claudePluginInstalls reads the databricks plugin's records from Claude Code's // installed_plugins.json (/plugins/), which keys each entry as // "@" (e.g. "databricks@claude-plugins-official") with one // record per install scope. The plugin can be installed from more than one -// marketplace, so the records of every databricks entry are returned. Any -// read/parse failure reports (nil, false), so an unreadable manifest reads as -// "not installed". -func claudePluginInstalls(ctx context.Context, a *Agent) ([]pluginInstall, bool) { +// marketplace, so the records of every databricks entry are returned, and found +// reports whether there is any such entry. A missing manifest is not found; a +// manifest that cannot be read or parsed returns an error. +func claudePluginInstalls(ctx context.Context, a *Agent) ([]pluginInstall, bool, error) { configDir, err := a.ConfigDir(ctx) if err != nil { - return nil, false + return nil, false, err } data, err := os.ReadFile(filepath.Join(configDir, "plugins", pluginManifestFile)) + if errors.Is(err, fs.ErrNotExist) { + return nil, false, nil + } if err != nil { - return nil, false + return nil, false, err } var manifest struct { Plugins map[string][]pluginInstall `json:"plugins"` } if err := json.Unmarshal(data, &manifest); err != nil { - return nil, false + return nil, false, fmt.Errorf("parse %s: %w", pluginManifestFile, err) } var all []pluginInstall found := false @@ -159,5 +215,5 @@ func claudePluginInstalls(ctx context.Context, a *Agent) ([]pluginInstall, bool) found = true } } - return all, found + return all, found, nil } diff --git a/libs/aitools/agents/plugins_test.go b/libs/aitools/agents/plugins_test.go index 893449ccfba..cb4c10a7f63 100644 --- a/libs/aitools/agents/plugins_test.go +++ b/libs/aitools/agents/plugins_test.go @@ -63,7 +63,8 @@ func TestDatabricksPluginVersionAcrossMarketplaces(t *testing.T) { configDir := t.TempDir() writeManifest(t, configDir, `{"plugins":{"databricks@a":[{"scope":"user","version":"0.2.9"}],"databricks@b":[{"scope":"user","version":"0.3.0"}]}}`) a := agentWithConfigDir(configDir) - installs, ok := claudePluginInstalls(t.Context(), a) + installs, ok, err := claudePluginInstalls(t.Context(), a) + require.NoError(t, err) require.True(t, ok) assert.Len(t, installs, 2) version, ok := a.DatabricksPluginVersion(t.Context()) @@ -85,13 +86,51 @@ func projectFixture(t *testing.T) (project, sub string) { // Every record counts, not only the first one the reader returns. func TestDatabricksPluginActiveInChecksEveryRecord(t *testing.T) { project, _ := projectFixture(t) - a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool) { + a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool, error) { return []pluginInstall{ {Scope: "project", ProjectPath: filepath.Join(filepath.Dir(project), "Other")}, {Scope: "user"}, - }, true + }, true, nil }} - assert.True(t, a.databricksPluginActiveIn(t.Context(), project)) + active, err := a.DatabricksPluginActiveIn(t.Context(), project) + require.NoError(t, err) + assert.True(t, active) +} + +// A working directory spelled through a symlink inside the project that points +// out of it is the directory it points to, which the project's plugin does not +// cover. +func TestDatabricksPluginActiveInResolvesTheWorkingDir(t *testing.T) { + project, _ := projectFixture(t) + outside := filepath.Join(filepath.Dir(project), "Other") + require.NoError(t, os.Mkdir(outside, 0o755)) + link := filepath.Join(project, "link") + if err := os.Symlink(outside, link); err != nil { + t.Skipf("cannot create a symlink: %v", err) + } + a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool, error) { + return []pluginInstall{{Scope: "project", ProjectPath: project}}, true, nil + }} + active, err := a.DatabricksPluginActiveIn(t.Context(), link) + require.NoError(t, err) + assert.False(t, active) + active, err = a.DatabricksPluginActiveIn(t.Context(), project) + require.NoError(t, err) + assert.True(t, active) +} + +// A missing manifest means no plugin; one that exists but cannot be parsed +// leaves the answer unknown, so the caller can consult another source. +func TestDatabricksPluginActiveInTellsAMissingManifestFromAnUnreadableOne(t *testing.T) { + configDir := t.TempDir() + a := agentWithConfigDir(configDir) + active, err := a.DatabricksPluginActiveIn(t.Context(), "") + require.NoError(t, err) + assert.False(t, active) + + writeManifest(t, configDir, `{not json`) + _, err = a.DatabricksPluginActiveIn(t.Context(), "") + assert.Error(t, err) } func TestPluginInstallAppliesToProjectOutsideWorkingDir(t *testing.T) { @@ -142,3 +181,27 @@ func TestDatabricksPluginVersionWithoutReader(t *testing.T) { assert.False(t, ok) assert.Empty(t, version) } + +// Only a project-scope record for the project that contains cwd is the +// project's own plugin; user and local records are personal. +func TestDatabricksProjectPluginIn(t *testing.T) { + project, sub := projectFixture(t) + other := filepath.Join(filepath.Dir(project), "Other") + require.NoError(t, os.Mkdir(other, 0o755)) + for _, tc := range []struct { + install pluginInstall + want bool + }{ + {pluginInstall{Scope: "project", ProjectPath: project}, true}, + {pluginInstall{Scope: "project", ProjectPath: other}, false}, + {pluginInstall{Scope: "local", ProjectPath: project}, false}, + {pluginInstall{Scope: "user"}, false}, + } { + a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool, error) { + return []pluginInstall{tc.install}, true, nil + }} + got, err := a.DatabricksProjectPluginIn(t.Context(), sub) + require.NoError(t, err) + assert.Equal(t, tc.want, got, "%+v", tc.install) + } +} diff --git a/libs/aitools/agents/skills.go b/libs/aitools/agents/skills.go index 177f0fcfdf6..ac9acdafeb4 100644 --- a/libs/aitools/agents/skills.go +++ b/libs/aitools/agents/skills.go @@ -38,7 +38,11 @@ func HasDatabricksToolingInstalled(ctx context.Context) bool { cwd = resolvePath(wd) } for _, a := range installed { - if a.pluginInstalls == nil || !a.databricksPluginActiveIn(ctx, cwd) { + if a.pluginInstalls == nil { + return false + } + // An unreadable manifest counts as no plugin, as before. + if active, _ := a.DatabricksPluginActiveIn(ctx, cwd); !active { return false } } diff --git a/libs/aitools/installer/plugin.go b/libs/aitools/installer/plugin.go index e82d590e932..d623a75c496 100644 --- a/libs/aitools/installer/plugin.go +++ b/libs/aitools/installer/plugin.go @@ -38,7 +38,8 @@ const ( // BlockedError reports that a plugin operation could not be performed for an // agent. The command layer maps Reason to a user-facing message and decides // whether to skip-with-warning or hard-fail (per the non-TTY policy). It never -// causes a silent fall back to skills. +// causes a fall back to skills: install gives skill files to an agent whose +// CLI is not on PATH when it plans the run, before any plugin install. type BlockedError struct { Agent string Reason string @@ -528,6 +529,52 @@ func RecordPluginInstalls(ctx context.Context, cliScope string, records map[stri return SaveState(dir, state) } +// PluginRecorded reports whether the CLI install state for cliScope records a +// databricks plugin install for the agent. A scope without state, or a state +// that cannot be read, has no record. +func PluginRecorded(ctx context.Context, cliScope, agentName string) bool { + dir, err := skillsDir(ctx, cliScope) + if err != nil { + return false + } + state, err := LoadState(dir) + if err != nil { + log.Debugf(ctx, "Could not load AI tools install state in %s: %v", dir, err) + return false + } + if state == nil { + return false + } + _, ok := state.Plugins[agentName] + return ok +} + +// ForgetPluginInstalls removes the plugin install records of the named agents +// from the state file for the given CLI scope, for agents that no longer have +// the plugin. Agents without a record, or a scope without state, are left as +// they are. +func ForgetPluginInstalls(ctx context.Context, cliScope string, agentNames []string) error { + dir, err := skillsDir(ctx, cliScope) + if err != nil { + return err + } + state, err := LoadState(dir) + if err != nil || state == nil { + return err + } + changed := false + for _, name := range agentNames { + if _, ok := state.Plugins[name]; ok { + delete(state.Plugins, name) + changed = true + } + } + if !changed { + return nil + } + return SaveState(dir, state) +} + // ManualPluginInstallCommands returns the commands, in order, that install the // databricks plugin through the agent's own CLI. When the headless install // fails, running them by hand shows the agent's full output. Returns nil for an diff --git a/libs/aitools/installer/plugin_test.go b/libs/aitools/installer/plugin_test.go index 8bcfb0ded69..645dec6a853 100644 --- a/libs/aitools/installer/plugin_test.go +++ b/libs/aitools/installer/plugin_test.go @@ -857,6 +857,37 @@ func TestRunAgentCmdTimeoutKeepsPartialStderr(t *testing.T) { assert.Equal(t, "timed out after 1ms: Waiting for login...", blocked.Detail) } +func TestForgetPluginInstalls(t *testing.T) { + setupTestHome(t) + t.Chdir(t.TempDir()) + ctx := t.Context() + dir, err := GlobalSkillsDir(ctx) + require.NoError(t, err) + + // No state yet: nothing to forget, and no state file is created. + require.NoError(t, ForgetPluginInstalls(ctx, ScopeGlobal, []string{agents.NameClaudeCode})) + st, err := LoadState(dir) + require.NoError(t, err) + assert.Nil(t, st) + assert.False(t, PluginRecorded(ctx, ScopeGlobal, agents.NameClaudeCode)) + + require.NoError(t, RecordPluginInstalls(ctx, ScopeGlobal, map[string]PluginRecord{ + agents.NameClaudeCode: {Marketplace: "databricks-agent-skills", Plugin: "databricks"}, + agents.NameCodex: {Marketplace: "databricks-agent-skills", Plugin: "databricks"}, + }, "v0.2.6")) + assert.True(t, PluginRecorded(ctx, ScopeGlobal, agents.NameClaudeCode)) + assert.False(t, PluginRecorded(ctx, ScopeProject, agents.NameClaudeCode), "the project scope has its own state") + + // An agent without a record is left alone; a recorded one is dropped. + require.NoError(t, ForgetPluginInstalls(ctx, ScopeGlobal, []string{agents.NameCopilot})) + require.NoError(t, ForgetPluginInstalls(ctx, ScopeGlobal, []string{agents.NameClaudeCode})) + st, err = LoadState(dir) + require.NoError(t, err) + assert.NotContains(t, st.Plugins, agents.NameClaudeCode) + assert.Contains(t, st.Plugins, agents.NameCodex) + assert.False(t, PluginRecorded(ctx, ScopeGlobal, agents.NameClaudeCode)) +} + func TestRunAgentCmdReportsTimeout(t *testing.T) { // A slow agent CLI used to be reported as "not on PATH" with whatever the // killed process left on stderr. diff --git a/libs/aitools/installer/useragent.go b/libs/aitools/installer/useragent.go index 95a7cab6492..e34eb549038 100644 --- a/libs/aitools/installer/useragent.go +++ b/libs/aitools/installer/useragent.go @@ -4,7 +4,6 @@ import ( "context" "github.com/databricks/cli/libs/aitools/agents" - "github.com/databricks/cli/libs/log" "github.com/databricks/databricks-sdk-go/useragent" ) @@ -63,27 +62,9 @@ func WithCallingAgentToolingInUserAgent(ctx context.Context) context.Context { if a == nil { return ctx } - tooling := a.DatabricksTooling(ctx, func() bool { return globalPluginRecorded(ctx, a.Name) }) + // Only the global state is read: the CLI installs plugins in project scope + // only for agents with SupportsProjectScope (see mapAgentScope in + // cmd/aitools), and those have a manifest reader. + tooling := a.DatabricksTooling(ctx, func() bool { return PluginRecorded(ctx, ScopeGlobal, a.Name) }) return useragent.InContext(ctx, callingAgentToolingUserAgentKey, tooling.String()) } - -// globalPluginRecorded reports whether the global CLI install state records a -// databricks plugin install for the agent. Only the global state is read: the -// CLI installs plugins in project scope only for agents with SupportsProjectScope -// (see mapAgentScope in cmd/aitools), and those have a manifest reader. -func globalPluginRecorded(ctx context.Context, agentName string) bool { - dir, err := GlobalSkillsDir(ctx) - if err != nil { - return false - } - state, err := LoadState(dir) - if err != nil { - log.Debugf(ctx, "Could not load AI tools install state in %s: %v", dir, err) - return false - } - if state == nil { - return false - } - _, ok := state.Plugins[agentName] - return ok -}