Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .nextchanges/cli/aitools-install-recovery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* `databricks aitools install` now ends a failed install with a step to recover, in the text output and in a new `recovery` field of `--output json`. ([#7480](https://github.com/databricks/cli/pull/7480))
4 changes: 4 additions & 0 deletions acceptance/cmd/aitools/telemetry/install-failure/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Installing Databricks skills for Cursor...
Using skills version test-ref
Fetching skills manifest...
Error: skill "nonexistent" not found
Run 'databricks aitools list' to see the available skills

>>> print_telemetry
{"command":"aitools_install","exit_code":1,"aitools_command_event":{"command":"INSTALL","stage":"STARTED","interactive":false,"install_mode":"SKILLS_ONLY"}}
Expand All @@ -23,6 +24,7 @@ Installing Databricks skills for Cursor...
Using skills version missing-ref
Fetching skills manifest...
Error: skills manifest at databricks-agent-skills@missing-ref: not found
No skills release exists at the version DATABRICKS_SKILLS_REF names. Unset it, or set it to a release tag from https://github.com/databricks/databricks-agent-skills/releases, then re-run 'databricks aitools install --scope=global --agents=cursor --skills-only'

>>> print_telemetry
{"command":"aitools_install","exit_code":1,"aitools_command_event":{"command":"INSTALL","stage":"STARTED","interactive":false,"install_mode":"SKILLS_ONLY"}}
Expand All @@ -40,6 +42,7 @@ Installing Databricks skills for Cursor...
Using skills version broken-ref
Fetching skills manifest...
Error: failed to fetch manifest: HTTP 500
[DATABRICKS_HOST] returned HTTP 500, a server-side error. Wait a few minutes and re-run 'databricks aitools install --scope=global --agents=cursor --skills-only'

>>> print_telemetry
{"command":"aitools_install","exit_code":1,"aitools_command_event":{"command":"INSTALL","stage":"STARTED","interactive":false,"install_mode":"SKILLS_ONLY"}}
Expand All @@ -54,6 +57,7 @@ Error: failed to fetch manifest: HTTP 500

>>> [CLI] aitools install --skills-only --scope=project --agents=cursor
Skipped Cursor: does not support project-scoped skills
To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor --skills-only
Error: Cursor: does not support project-scoped skills

>>> print_telemetry
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@
"delivery": "skip",
"status": "skipped",
"error_category": "UNSUPPORTED_SCOPE",
"message": "does not support project-scoped skills"
"message": "does not support project-scoped skills",
"recovery": "To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor --skills-only --output json"
}
]
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,16 @@
"delivery": "skip",
"status": "skipped",
"error_category": "UNSUPPORTED_SCOPE",
"message": "does not support project-scoped skills"
"message": "does not support project-scoped skills",
"recovery": "To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor --skills-only --output json"
},
{
"name": "codex",
"delivery": "skip",
"status": "skipped",
"error_category": "UNSUPPORTED_SCOPE",
"message": "does not support project-scoped skills"
"message": "does not support project-scoped skills",
"recovery": "To set up Codex CLI in the global scope, run: databricks aitools install --scope=global --agents=codex --skills-only --output json"
}
]
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
"scope": "global",
"agents": [],
"error": "skill \"nonexistent\" not found",
"error_category": "SKILL_NOT_FOUND"
"error_category": "SKILL_NOT_FOUND",
"recovery": "Run 'databricks aitools list' to see the available skills."
}

Exit code: 1
2 changes: 1 addition & 1 deletion cmd/aitools/funnel_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,7 @@ func TestInstallFunnelEmptyPickerSelectionIsCancelled(t *testing.T) {
cmd.SetContext(ctx)
err := cmd.RunE(cmd, nil)
require.ErrorIs(t, err, errNoAgentsSelected)
assert.Equal(t, "at least one agent must be selected", err.Error())
assert.Equal(t, "at least one agent must be selected\nTo install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=<name>", err.Error())
assert.Equal(t, []string{"STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "FINISHED:CANCELLED:"}, funnelShape(funnelEvents(ctx)))
}

Expand Down
74 changes: 59 additions & 15 deletions cmd/aitools/install.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"context"
"errors"
"fmt"
"runtime"
"strings"

"github.com/charmbracelet/huh"
Expand Down Expand Up @@ -183,7 +184,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
funnel.step(ctx, protos.AitoolsCommandStepFlagsValidated)
written, err := installer.DumpSkillsToPath(ctx, src, pathFlag, opts)
if err != nil {
return err
return withRecovery(ctx, installInvocation{path: pathFlag, skills: skillsFlag, experimental: includeExperimental}, err)
}
if written == 0 {
// Every skill was filtered out (e.g. all experimental without
Expand Down Expand Up @@ -226,6 +227,18 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
}
}

// Recovery steps repeat this run with the choices made so far, so a
// copied command never widens to every agent or the global scope.
// Agents chosen by flag or in the picker are named; without a
// choice the re-run detects the same agents again.
rerun := installInvocation{
scope: scope,
skills: skillsFlag,
skillsOnly: skillsOnly,
experimental: includeExperimental,
jsonOutput: jsonMode,
}

// Validate --agents with the other flags, before the scope prompt.
var targetAgents []*agents.Agent
explicit := agentsFlag != ""
Expand All @@ -235,6 +248,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
return err
}
funnel.setTargets(targetAgents)
rerun.agents = joinAgentNames(targetAgents)
}
funnel.step(ctx, protos.AitoolsCommandStepFlagsValidated)

Expand All @@ -257,8 +271,9 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
if scope == "" {
scope, err = resolveScopeWithPrompt(ctx, interactive)
if err != nil {
return err
return withRecovery(ctx, rerun, err)
}
rerun.scope = scope
}
opts.Scope = scope
funnel.setScope(scope)
Expand All @@ -267,13 +282,16 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
if !explicit {
targetAgents, err = selectAgents(ctx, scope, skillsOnly, interactive)
if err != nil {
return err
return withRecovery(ctx, rerun, err)
}
if len(targetAgents) == 0 {
printNoAgentsMessage(ctx)
printNoAgentsMessage(ctx, rerun)
funnel.finishWith(ctx, protos.AitoolsCommandOutcomeNothingToDo, protos.AitoolsErrorCategoryUnspecified)
return nil
}
if interactive {
rerun.agents = joinAgentNames(targetAgents)
}
}

plan := buildPlan(targetAgents, scope, skillsOnly, explicit)
Expand Down Expand Up @@ -302,7 +320,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
}, classifyInstallError(topLevelFailure(runErr)), outcomes)
}()

outcomes, runErr = executePlan(ctx, src, plan, opts, jsonMode)
outcomes, runErr = executePlan(ctx, src, plan, opts, rerun, jsonMode)
for _, s := range deliverySteps(outcomes) {
funnel.step(ctx, s)
}
Expand All @@ -322,7 +340,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
}

if jsonMode {
if jerr := renderJSON(cmd.OutOrStdout(), buildInstallOutput(opts.Scope, outcomes, runErr)); jerr != nil {
if jerr := renderJSON(cmd.OutOrStdout(), buildInstallOutput(ctx, rerun, opts.Scope, outcomes, runErr)); jerr != nil {
// Rendering failed, so the JSON the caller parses is broken.
// Report the render error unless the run already failed for
// another reason.
Expand All @@ -341,7 +359,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
}
return nil
}
return runErr
return withRecovery(ctx, rerun, runErr)
},
}

Expand Down Expand Up @@ -557,6 +575,7 @@ type agentOutcome struct {
status outcomeStatus
errorCategory protos.AitoolsErrorCategory // Unspecified when status == outcomeInstalled
message string // set when skipped or failed
recovery string // next step for the user, when skipped or failed
}

type outcomeStatus string
Expand Down Expand Up @@ -589,8 +608,9 @@ 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 (exit 0),
// unless the agent was explicitly named via --agents, which is an error.
func executePlan(ctx context.Context, src installer.ManifestSource, plan []agentPlanItem, opts installer.InstallOptions, quiet bool) ([]agentOutcome, error) {
// unless the agent was explicitly named via --agents, which is an error. 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
for _, it := range plan {
Expand Down Expand Up @@ -638,18 +658,21 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent
}
rec, err := installPluginForAgentFn(ctx, it.agent, it.scope, ref)
if err != nil {
reason, recovery := pluginFailureText(ctx, rerun, it, err)
if !quiet {
cmdio.LogString(ctx, cmdio.Yellow(ctx, fmt.Sprintf("Skipped %s: %v", it.agent.DisplayName, err)))
cmdio.LogString(ctx, cmdio.Yellow(ctx, fmt.Sprintf("Skipped %s: %s", it.agent.DisplayName, reason)))
cmdio.LogString(ctx, " "+recovery)
}
outcomes = append(outcomes, agentOutcome{
agent: it.agent,
delivery: deliveryPlugin,
status: outcomeFailed,
errorCategory: classifyInstallError(err),
message: err.Error(),
recovery: recovery,
})
if it.explicit {
explicitErrs = append(explicitErrs, err)
explicitErrs = append(explicitErrs, &displayError{msg: it.agent.DisplayName + ": " + reason, err: err})
}
continue
}
Expand Down Expand Up @@ -686,15 +709,18 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent
}

for _, it := range skipItems {
recovery := skipRecovery(rerun, it)
if !quiet {
cmdio.LogString(ctx, cmdio.Yellow(ctx, "Skipped "+it.agent.DisplayName+": "+it.reason))
cmdio.LogString(ctx, " "+recovery)
}
outcomes = append(outcomes, agentOutcome{
agent: it.agent,
delivery: deliverySkip,
status: outcomeSkipped,
errorCategory: it.skipErrorCategory,
message: it.reason,
recovery: recovery,
})
if it.explicit {
explicitErrs = append(explicitErrs, fmt.Errorf("%s: %s", it.agent.DisplayName, it.reason))
Expand Down Expand Up @@ -730,6 +756,8 @@ type installOutput struct {
// also records.
Error string `json:"error,omitempty"`
ErrorCategory string `json:"error_category,omitempty"`
// Recovery is the next step for the top-level failure, local-only like Error.
Recovery string `json:"recovery,omitempty"`
}

type agentResultJSON struct {
Expand All @@ -738,16 +766,20 @@ type agentResultJSON struct {
Status string `json:"status"`
ErrorCategory string `json:"error_category,omitempty"`
Message string `json:"message,omitempty"`
Recovery string `json:"recovery,omitempty"`
}

func buildInstallOutput(scope string, outcomes []agentOutcome, runErr error) installOutput {
// buildInstallOutput builds the --output json result; the recovery steps
// repeat rerun.
func buildInstallOutput(ctx context.Context, rerun installInvocation, scope string, outcomes []agentOutcome, runErr error) installOutput {
out := installOutput{Scope: scope, Agents: make([]agentResultJSON, 0, len(outcomes))}
for _, o := range outcomes {
entry := agentResultJSON{
Name: o.agent.Name,
Delivery: o.delivery.String(),
Status: string(o.status),
Message: o.message,
Recovery: o.recovery,
}
// Only non-successful outcomes carry a category, keyed on status to match
// agentResultsField in telemetry.go so the JSON and telemetry views of the
Expand All @@ -765,10 +797,20 @@ func buildInstallOutput(scope string, outcomes []agentOutcome, runErr error) ins
if e := topLevelFailure(runErr); e != nil {
out.Error = e.Error()
out.ErrorCategory = string(classifyInstallError(e))
out.Recovery = installRecovery(ctx, rerun, e)
}
return out
}

// joinAgentNames is the --agents value that names targetAgents.
func joinAgentNames(targetAgents []*agents.Agent) string {
names := make([]string, len(targetAgents))
for i, a := range targetAgents {
names[i] = a.Name
}
return strings.Join(names, ",")
}

// resolveAgentNames parses a comma-separated list of agent names and validates
// them against the registry. Returns an error for unrecognized names.
func resolveAgentNames(_ context.Context, names string) ([]*agents.Agent, error) {
Expand Down Expand Up @@ -800,10 +842,12 @@ func resolveAgentNames(_ context.Context, names string) ([]*agents.Agent, error)
return result, nil
}

// printNoAgentsMessage prints the "no agents detected" message.
func printNoAgentsMessage(ctx context.Context) {
// printNoAgentsMessage prints the "no agents detected" message. Its commands
// repeat rerun, so a named agent is set up in the scope and mode this run used.
func printNoAgentsMessage(ctx context.Context, rerun installInvocation) {
cmdio.LogString(ctx, cmdio.Yellow(ctx, "No supported coding agents found on PATH."))
cmdio.LogString(ctx, "")
cmdio.LogString(ctx, "Supported: "+strings.Join(agents.SupportedNames(), ", ")+".")
cmdio.LogString(ctx, "Install one, then re-run 'databricks aitools install'.")
named, _ := commandText(runtime.GOOS, rerun, nil, "--agents=<name>")
cmdio.LogString(ctx, "Install one, then re-run "+rerunPhrase(runtime.GOOS, rerun)+". To set up an agent that was not detected, name it: "+named)
}
Loading
Loading