Repository navigation
aitools: install hints for non-Claude coding agents #7586
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
07a831d
735415e
a057fdd
2bb6ce5
84c0701
2ee18a1
6664c2d
11c9532
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| * When Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose or Kiro run the CLI without Databricks skills installed for that agent, the CLI now prints a one-line hint to install them with `databricks aitools install --agents <agent> --scope global`, previously shown only to Claude Code. ([#7586](https://github.com/databricks/cli/pull/7586)) |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| --- | ||
| name: databricks-core | ||
| description: Fixture marking Databricks skills as installed for Gemini CLI. | ||
| --- |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| Cloud = false |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
|
|
||
| === Codex is hinted once per thread | ||
|
|
||
| >>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> CODEX_CI=1 CODEX_THREAD_ID=thread-2 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Cursor exposes no session id, so it is hinted once per machine | ||
|
|
||
| >>> CURSOR_AGENT=1 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents cursor --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> CURSOR_AGENT=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Copilot CLI maps to the copilot registry agent | ||
|
|
||
| >>> COPILOT_CLI=1 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents copilot --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Gemini CLI with its own Databricks skills is not hinted | ||
|
|
||
| >>> GEMINI_CLI=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Agents the CLI cannot install for are not hinted | ||
|
|
||
| >>> WINDSURF_AGENT=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> VSCODE_AGENT=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Nested agents are not hinted | ||
|
|
||
| >>> CODEX_CI=1 CURSOR_AGENT=1 CODEX_THREAD_ID=thread-3 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # aitools commands skip the install hint; version exercises it without auth or network. | ||
| sethome ./home | ||
| unset XDG_CONFIG_HOME GEMINI_CLI_HOME CODEX_THREAD_ID | ||
|
|
||
| title "Codex is hinted once per thread" | ||
| trace CODEX_CI=1 CODEX_THREAD_ID=thread-1 $CLI version | ||
| trace CODEX_CI=1 CODEX_THREAD_ID=thread-1 $CLI version | ||
| trace CODEX_CI=1 CODEX_THREAD_ID=thread-2 $CLI version | ||
|
|
||
| title "Cursor exposes no session id, so it is hinted once per machine" | ||
| trace CURSOR_AGENT=1 $CLI version | ||
| trace CURSOR_AGENT=1 $CLI version | ||
|
|
||
| title "Copilot CLI maps to the copilot registry agent" | ||
| trace COPILOT_CLI=1 $CLI version | ||
|
|
||
| title "Gemini CLI with its own Databricks skills is not hinted" | ||
| sethome ./gemini-home | ||
| trace GEMINI_CLI=1 $CLI version | ||
| sethome ./home | ||
|
|
||
| title "Agents the CLI cannot install for are not hinted" | ||
| trace WINDSURF_AGENT=1 $CLI version | ||
| trace VSCODE_AGENT=1 $CLI version | ||
|
|
||
| title "Nested agents are not hinted" | ||
| trace CODEX_CI=1 CURSOR_AGENT=1 CODEX_THREAD_ID=thread-3 $CLI version |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # The throttle markers live in the file cache, which a host could disable. | ||
| Env.DATABRICKS_CACHE_ENABLED = "true" | ||
| Ignore = ["home"] |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -76,8 +76,8 @@ const ( | |
| // degrades to per-command. | ||
| claudeSessionEnv = "CLAUDE_CODE_SESSION_ID" | ||
|
|
||
| // hintCacheComponent names the cache bucket holding per-session "already | ||
| // hinted" markers. | ||
| // hintCacheComponent names the cache bucket holding "already hinted" | ||
| // markers (per session, or per agent on this machine). | ||
| hintCacheComponent = "aitools-hint" | ||
| ) | ||
|
|
||
|
|
@@ -94,17 +94,35 @@ type agentHint struct { | |
| installed func(ctx context.Context) bool | ||
|
|
||
| // text is the model-facing recommendation, printed at most once per | ||
| // hintSessionTTL per session (see sessionEnv), together with native. | ||
| // hintSessionTTL per session (see sessionEnv), or per agent on this machine | ||
| // when there is no session id (see fallbackKey), together with native. | ||
| text string | ||
|
|
||
| // textKind tags the hint-shown event logged when text prints. | ||
| textKind protos.AitoolsHintKind | ||
|
|
||
| // sessionEnv names the env var carrying the agent's session id, which keys | ||
| // the throttle for both lines. Empty, or unset at runtime, means no | ||
| // throttle. | ||
| // the throttle for both lines. When it is empty or unset at runtime, | ||
| // fallbackKey keys the throttle instead. | ||
| sessionEnv string | ||
|
|
||
| // sessionKeyPrefix namespaces the session id in the throttle key, so one | ||
| // agent's marker never silences another agent that reuses the same id. | ||
| // Empty for Claude Code, whose key stays the raw session id so its | ||
| // throttle is unchanged. | ||
| sessionKeyPrefix string | ||
|
|
||
| // fallbackKey keys the throttle when there is no session id, so the hint | ||
| // prints at most once per hintSessionTTL on this machine. Empty means no | ||
| // throttle without a session id (Claude Code). | ||
| fallbackKey string | ||
|
|
||
| // durableThrottle prints the text only once its throttle marker is | ||
| // persisted (see claimHintMarker), so an unwritable cache can't turn the | ||
| // hint into a line on every command. False for Claude Code, whose marker | ||
| // write stays best-effort so its existing throttle behaviour is unchanged. | ||
| durableThrottle bool | ||
|
|
||
| // native returns a line the agent itself acts on (for Claude Code, its | ||
| // plugin install prompt), or "" when none applies to this invocation. It | ||
| // shares the text's per-session throttle. Nil for agents without one. | ||
|
|
@@ -116,7 +134,7 @@ type agentHint struct { | |
|
|
||
| // hintForAgent returns the hint for an agent, keyed by its | ||
| // useragent.AgentProvider() value, or nil when that agent is not hinted. | ||
| func hintForAgent(provider string) *agentHint { | ||
| func hintForAgent(provider string, pluginRecorded PluginRecordedFunc) *agentHint { | ||
| switch provider { | ||
| case claudeAgentProvider: | ||
| return &agentHint{ | ||
|
|
@@ -128,10 +146,21 @@ func hintForAgent(provider string) *agentHint { | |
| nativeKind: protos.AitoolsHintKindClaudeCodeNative, | ||
| } | ||
| default: | ||
| if a := AgentForProvider(provider); a != nil { | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nice to have] |
||
| return agentInstallHint(a, pluginRecorded) | ||
| } | ||
| return nil | ||
| } | ||
| } | ||
|
|
||
| // isHintedAgent reports whether MaybeHint hints the agent with this | ||
| // useragent.AgentProvider() value. It defers to hintForAgent so both follow | ||
| // the same dispatch; pluginRecorded is only read when the hint's installed | ||
| // check runs, so none is needed here. | ||
| func isHintedAgent(provider string) bool { | ||
| return hintForAgent(provider, nil) != nil | ||
| } | ||
|
|
||
| // nativeLine returns the agent-native line due for this invocation, or "". | ||
| func (h *agentHint) nativeLine(ctx context.Context) string { | ||
| if h.native == nil { | ||
|
|
@@ -146,12 +175,15 @@ func (h *agentHint) nativeLine(ctx context.Context) string { | |
| // docker token` credential helpers, a CLI process the CLI started itself, when | ||
| // there is no output stream, and once the tooling is present. | ||
| // Both lines, the agent-native one (if any) and the model-facing text, and | ||
| // their hint-shown events are throttled together per session. | ||
| // their hint-shown events are throttled together per session, or per agent on | ||
| // this machine for agents without a session id (fallbackKey). | ||
| // pluginRecorded reads the CLI install record for agents whose plugin has no | ||
| // manifest reader here (see Agent.DatabricksTooling). | ||
| // Best-effort: it never fails the command. Besides the stderr lines, it logs a | ||
| // telemetry event for each hint line shown, which makes a command that resolved | ||
| // auth upload telemetry at exit. | ||
| func MaybeHint(ctx context.Context, cmd *cobra.Command) { | ||
| hint := hintForAgent(useragent.AgentProvider()) | ||
| func MaybeHint(ctx context.Context, cmd *cobra.Command, pluginRecorded PluginRecordedFunc) { | ||
| hint := hintForAgent(useragent.AgentProvider(), pluginRecorded) | ||
| if hint == nil { | ||
| return | ||
| } | ||
|
|
@@ -168,22 +200,34 @@ func MaybeHint(ctx context.Context, cmd *cobra.Command) { | |
| return | ||
| } | ||
| // Check the throttle before the filesystem probe, so a throttled session | ||
| // skips the plugin/skills detection. The throttle token is written only | ||
| // after the hint prints, so an already-installed environment never burns | ||
| // it. | ||
| if alreadyHintedThisSession(ctx, hint.sessionEnv) { | ||
| // skips the plugin/skills detection. The marker is written only once a hint | ||
| // is due, so an already-installed environment never burns it. | ||
| key := hint.throttleKey(ctx) | ||
| if alreadyHintedThisSession(ctx, key) { | ||
| return | ||
| } | ||
| if hint.installed(ctx) { | ||
| return | ||
| } | ||
| if !hint.claim(ctx, key) { | ||
| return | ||
| } | ||
| if native := hint.nativeLine(ctx); native != "" { | ||
| cmdio.LogString(ctx, native) | ||
| logHintShown(ctx, hint.nativeKind) | ||
| } | ||
| cmdio.LogString(ctx, hint.text) | ||
| logHintShown(ctx, hint.textKind) | ||
| recordSessionHint(ctx, hint.sessionEnv) | ||
| } | ||
|
|
||
| // claim records the throttle key and reports whether the hint may print. A | ||
| // durable throttle allows it only once the marker has persisted. | ||
| func (h *agentHint) claim(ctx context.Context, key string) bool { | ||
| if h.durableThrottle { | ||
| return claimHintMarker(ctx, key) | ||
| } | ||
| recordSessionHint(ctx, key) | ||
| return true | ||
| } | ||
|
|
||
| // claudeNativeHintLine returns claudeNativeHint when Claude Code itself spawned | ||
|
|
@@ -271,29 +315,35 @@ func claudeToolingInstalled(ctx context.Context) bool { | |
| return tooling != ToolingNone | ||
| } | ||
|
|
||
| // alreadyHintedThisSession reports whether the session named by sessionEnv was | ||
| // hinted within the last hintSessionTTL. With no session id it returns false | ||
| // so the hint fires per command. | ||
| func alreadyHintedThisSession(ctx context.Context, sessionEnv string) bool { | ||
| session := sessionID(ctx, sessionEnv) | ||
| if session == "" { | ||
| // throttleKey returns the cache key throttling the hint: the session id behind | ||
| // sessionKeyPrefix, else fallbackKey. "" means no throttle. | ||
| func (h *agentHint) throttleKey(ctx context.Context) string { | ||
| if session := sessionID(ctx, h.sessionEnv); session != "" { | ||
| return h.sessionKeyPrefix + session | ||
| } | ||
| return h.fallbackKey | ||
| } | ||
|
|
||
| // alreadyHintedThisSession reports whether the throttle key was hinted within | ||
| // the last hintSessionTTL. With no key it returns false so the hint fires per | ||
| // command. | ||
| func alreadyHintedThisSession(ctx context.Context, key string) bool { | ||
| if key == "" { | ||
| return false | ||
| } | ||
| c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil) | ||
| _, seen := cache.Get[bool](ctx, c, session) | ||
| _, seen := cache.Get[bool](ctx, c, key) | ||
| return seen | ||
| } | ||
|
|
||
| // recordSessionHint marks the session named by sessionEnv as hinted, so later | ||
| // commands in the same session stay quiet until the marker expires | ||
| // (hintSessionTTL). No-op when the session id is unset. | ||
| func recordSessionHint(ctx context.Context, sessionEnv string) { | ||
| session := sessionID(ctx, sessionEnv) | ||
| if session == "" { | ||
| // recordSessionHint marks the throttle key as hinted, so later commands stay | ||
| // quiet until the marker expires (hintSessionTTL). No-op when the key is "". | ||
| func recordSessionHint(ctx context.Context, key string) { | ||
| if key == "" { | ||
| return | ||
| } | ||
| c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil) | ||
| cache.Put(ctx, c, session, true) | ||
| cache.Put(ctx, c, key, true) | ||
| } | ||
|
|
||
| // sessionID returns the value of sessionEnv, or "" when the agent has no | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| package agents | ||
|
|
||
| import ( | ||
| "context" | ||
|
|
||
| "github.com/databricks/cli/libs/cache" | ||
| "github.com/databricks/cli/libs/telemetry/protos" | ||
| ) | ||
|
|
||
| // agentSessionEnv names the env var a non-Claude agent sets to a per-session id | ||
| // in the shells it spawns. Only verified variables are listed; an agent missing | ||
| // here is throttled per machine instead (see agentInstallHint). | ||
| var agentSessionEnv = map[string]string{ | ||
| // Set by codex-cli (0.166.0) for every shell tool call, next to CODEX_CI: | ||
| // https://github.com/openai/codex/blob/main/codex-rs/core/src/exec_env.rs | ||
| NameCodex: "CODEX_THREAD_ID", | ||
| } | ||
|
|
||
| // PluginRecordedFunc reports whether the CLI install state records a | ||
| // databricks plugin install for the named agent. The installer package owns | ||
| // that state and provides it (installer.PluginRecorded for the global scope). | ||
| type PluginRecordedFunc func(ctx context.Context, agentName string) bool | ||
|
|
||
| // agentInstallHint returns the hint for a non-Claude registry agent. The text | ||
| // is hintText plus --agents and --scope. An agent caller never sees install's | ||
| // prompts (installPromptsSupported), so --agents is what matters: it targets | ||
| // the calling agent even when it isn't detected on this machine, instead of | ||
| // every detected one. --scope global only makes the non-interactive default | ||
| // explicit. | ||
| // | ||
| // The hint is gated on the agent's own tooling (Agent.DatabricksTooling, with | ||
| // pluginRecorded as the plugin source for Codex and Copilot). A plugin | ||
| // installed outside `databricks aitools install` (with the Codex or Copilot | ||
| // CLI, or from Cursor itself) leaves no trace there, so those users are | ||
| // hinted; the throttle bounds that to once per session or per TTL. | ||
| func agentInstallHint(a *Agent, pluginRecorded PluginRecordedFunc) *agentHint { | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nice to have] For Codex and Copilot,
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good idea. Leaving it for a follow-up: it makes the hint text depend on PATH, and |
||
| return &agentHint{ | ||
| installed: func(ctx context.Context) bool { | ||
| recorded := func() bool { return pluginRecorded(ctx, a.Name) } | ||
| return a.DatabricksTooling(ctx, recorded) != ToolingNone | ||
| }, | ||
| text: hintText + " --agents " + a.Name + " --scope global", | ||
| textKind: protos.AitoolsHintKindAgentInstallText, | ||
| sessionEnv: agentSessionEnv[a.Name], | ||
| sessionKeyPrefix: a.Name + ":session:", | ||
| fallbackKey: a.Name + ":machine", | ||
| durableThrottle: true, | ||
| } | ||
| } | ||
|
|
||
| // claimHintMarker writes the throttle marker to the user cache and reports | ||
| // whether it reads back. libs/cache silently drops writes it can't make (e.g. | ||
| // a read-only home in an agent sandbox), and without a kept marker the hint | ||
| // would repeat on every command, so the caller then skips it. A sandbox that | ||
| // can't write the user cache can't run the install either. The same holds with | ||
| // caching turned off (DATABRICKS_CACHE_ENABLED=false): nothing persists, so | ||
| // these agents get no hint. | ||
| func claimHintMarker(ctx context.Context, key string) bool { | ||
| c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil) | ||
| cache.Put(ctx, c, key, true) | ||
| _, ok := cache.Get[bool](ctx, c, key) | ||
| return ok | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[nit] The
throttleKeycomment (hint.go:305) says Claude's key "is the raw id and must not change". Butcache.NewCachestores markers under a per-CLI-version directory, and nothing else reads this bucket, so prefixing Claude's key would break nothing. With the same<agent>:session:<id>key for Claude,throttleKeycould derive the prefix from the agent name, andsessionKeyPrefixcould go. At minimum, the comment should drop that reason. ThedurableThrottlecomment also has a stray line break ("False for" / "Claude Code").