W-20926508: replace local assets to global assets

.cursor/skills/agent-pr-review/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: agent-pr-review
+description: Review pull requests in plugin-agent using GitHub CLI. Use for "review PR", "code review", or "gh pr view".
+---
+
+# Agent PR Review (plugin-agent)
+
+## Required
+
+- `gh` CLI required (no git-only fallback)
+
+## Working directory
+
+- repo root (parent of this `.cursor`)
+
+## Commands
+
+- `gh pr view <PR_NUMBER> --json title,number,body,files,commits,additions,deletions,changedFiles,baseRefName,headRefName,author,labels`
+- `gh pr diff <PR_NUMBER>`
+
+## Review checklist
+
+- correctness, security, regressions
+- error handling, edge cases
+- tests cover changes or note gaps
+- input validation, API misuse
+- command messages have entries in messages dir
+- errors not swallowed; rethrown errors set original as cause
+- suggest code reuse
+- suggest output improvements for agent use (esp. `--json`)
+
+## Output format
+
+- Findings first, severity order (Critical → High → Medium → Low)
+- cite files/snippets
+- Questions/Assumptions if needed
+- Summary last, brief

CHANGELOG.md

@@ -1,3 +1,21 @@
+## [1.32.1](https://github.com/salesforcecli/plugin-agent/compare/1.32.0...1.32.1) (2026-03-11)
+
+### Bug Fixes
+
+- add --version flag to agent activate/deactivate ([af07c24](https://github.com/salesforcecli/plugin-agent/commit/af07c242b57b3265dc686e19e421715f4ac84684))
+- add guard for empty available versions and unit tests ([7dea3e4](https://github.com/salesforcecli/plugin-agent/commit/7dea3e488162f2ae90ad68944f900524ee871f17))
+- deactivate only one version anywyays ([4fe0098](https://github.com/salesforcecli/plugin-agent/commit/4fe0098c24a9bce63ff10b37b740cd6a846936c5))
+- edit ([c165ee9](https://github.com/salesforcecli/plugin-agent/commit/c165ee9f9bbf72c737ee9949bc93983d5e28e86c))
+- sort version choices descending so latest appears first ([bf3e742](https://github.com/salesforcecli/plugin-agent/commit/bf3e7423e939a5b41bf8f2dedd2619b356316ade))
+- usability, errors, tests ([a6dd2a7](https://github.com/salesforcecli/plugin-agent/commit/a6dd2a7109ffbecd46d618c77f70014c59fc4dc3))
+
+# [1.32.0](https://github.com/salesforcecli/plugin-agent/compare/1.31.3...1.32.0) (2026-03-09)
+
+### Features
+
+- add comprehensive contextVariables validation, tests, and documentation ([2f27bed](https://github.com/salesforcecli/plugin-agent/commit/2f27bedb7aae05ca2254f2b18f63c8d4d073dc26))
+- **run-eval:** whitelist state/setupSessionContext, translate contextVariables, preserve outputs ([610c1e9](https://github.com/salesforcecli/plugin-agent/commit/610c1e93be3e64c89f6f7b91b71ecf9176bacc91))
+
 ## [1.31.3](https://github.com/salesforcecli/plugin-agent/compare/1.31.2...1.31.3) (2026-03-08)
 
 ### Bug Fixes

README.md

@@ -85,13 +85,17 @@ Activate an agent in an org.
 
 ```
 USAGE
-  $ sf agent activate -o <value> [--json] [--flags-dir <value>] [--api-version <value>] [-n <value>]
+  $ sf agent activate -o <value> [--json] [--flags-dir <value>] [--api-version <value>] [-n <value>] [--version
+    <value>]
 
 FLAGS
-  -n, --api-name=<value>     API name of the agent to activate.
+  -n, --api-name=<value>     API name of the agent to activate; if not specified, the command provides a list that you
+                             choose from.
   -o, --target-org=<value>   (required) Username or alias of the target org. Not required if the `target-org`
                              configuration variable is already set.
       --api-version=<value>  Override the api version used for api requests made by this command
+      --version=<value>      Version number of the agent to activate; if not specified, the command provides a list that
+                             you choose from.
 
 GLOBAL FLAGS
   --flags-dir=<value>  Import flag values from a directory.
@@ -100,23 +104,29 @@ GLOBAL FLAGS
 DESCRIPTION
   Activate an agent in an org.
 
-  Activating an agent makes it immediately available to your users. An agent must be active before you can preview it
-  with the "agent preview" CLI command or VS Code.
+  Activating an agent makes it immediately available to your users. A published agent must be active before you can
+  preview it with the "agent preview" CLI command or VS Code. Agents can have multiple versions; only one version can be
+  active at a time.
 
-  You must know the agent's API name to activate it; you can either be prompted for it or you can specify it with the
-  --api-name flag. Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup.
+  If you run the command without the --api-name or --version flags, the command provides a list of agent API names and
+  versions for you to choose from. Use the flags to specify the exact agent and version without being prompted. If you
+  use the --json flag and not --version, then the latest agent version is automatically activated.
+
+  The value of the --version flag is always a number, corresponding to the "vX" part of the "BotVersion" metadata in
+  your project. For example, if you have a force-app/main/default/bots/My_Agent/v4.botVersion-meta.xml file in your
+  project, then you activate this version with the "--version 4" flag.
 
 EXAMPLES
-  Activate an agent in your default target org by being prompted:
+  Activate an agent in your default target org by being prompted for both its API name and version:
 
     $ sf agent activate
 
-  Activate an agent with API name Resort_Manager in the org with alias "my-org":
+  Activate version 2 of an agent with API name Resort_Manager in the org with alias "my-org":
 
-    $ sf agent activate --api-name Resort_Manager --target-org my-org
+    $ sf agent activate --api-name Resort_Manager --version 2 --target-org my-org
 ```
 
-_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/activate.ts)_
+_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/activate.ts)_
 
 ## `sf agent create`
 
@@ -183,7 +193,7 @@ EXAMPLES
     $ sf agent create --name "Resort Manager" --spec specs/resortManagerAgent.yaml --preview
 ```
 
-_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/create.ts)_
+_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/create.ts)_
 
 ## `sf agent deactivate`
 
@@ -194,7 +204,8 @@ USAGE
   $ sf agent deactivate -o <value> [--json] [--flags-dir <value>] [--api-version <value>] [-n <value>]
 
 FLAGS
-  -n, --api-name=<value>     API name of the agent to deactivate.
+  -n, --api-name=<value>     API name of the agent to deactivate; if not specified, the command provides a list that you
+                             choose from.
   -o, --target-org=<value>   (required) Username or alias of the target org. Not required if the `target-org`
                              configuration variable is already set.
       --api-version=<value>  Override the api version used for api requests made by this command
@@ -210,8 +221,8 @@ DESCRIPTION
   topics or actions, you must deactivate it. You can't preview an agent with the "agent preview" CLI command or VS Code
   if it's deactivated.
 
-  You must know the agent's API name to deactivate it; you can either be prompted for it or you can specify it with the
-  --api-name flag. Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup.
+  If you run the command without the --api-name flag, the command provides a list of agent API names for you to choose
+  from. Use the flag to specify the exact agent without being prompted.
 
 EXAMPLES
   Deactivate an agent in your default target org by being prompted:
@@ -223,7 +234,7 @@ EXAMPLES
     $ sf agent deactivate --api-name Resort_Manager --target-org my-org
 ```
 
-_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/deactivate.ts)_
+_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/deactivate.ts)_
 
 ## `sf agent generate agent-spec`
 
@@ -330,7 +341,7 @@ EXAMPLES
     $ sf agent generate agent-spec --tone formal --agent-user resortmanager@myorg.com
 ```
 
-_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/generate/agent-spec.ts)_
+_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/generate/agent-spec.ts)_
 
 ## `sf agent generate authoring-bundle`
 
@@ -407,7 +418,7 @@ EXAMPLES
       other-package-dir/main/default --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/generate/authoring-bundle.ts)_
+_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/generate/authoring-bundle.ts)_
 
 ## `sf agent generate template`
 
@@ -455,7 +466,7 @@ EXAMPLES
       force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1
 ```
 
-_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/generate/template.ts)_
+_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/generate/template.ts)_
 
 ## `sf agent generate test-spec`
 
@@ -494,6 +505,10 @@ DESCRIPTION
   - (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a
   conversation history.
 
+  You can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as
+  CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual
+  information.
+
   When your test spec is ready, you then run the "agent test create" command to actually create the test in your org and
   synchronize the metadata with your DX project. The metadata type for an agent test is AiEvaluationDefinition.
 
@@ -516,7 +531,7 @@ EXAMPLES
       force-app//main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml
 ```
 
-_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/generate/test-spec.ts)_
+_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/generate/test-spec.ts)_
 
 ## `sf agent preview`
 
@@ -589,7 +604,7 @@ EXAMPLES
     $ sf agent preview --use-live-actions --apex-debug --output-dir transcripts/my-preview
 ```
 
-_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/preview.ts)_
+_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/preview.ts)_
 
 ## `sf agent preview end`
 
@@ -644,7 +659,7 @@ EXAMPLES
     $ sf agent preview end --authoring-bundle My_Local_Agent
 ```
 
-_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/preview/end.ts)_
+_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/preview/end.ts)_
 
 ## `sf agent preview send`
 
@@ -702,7 +717,7 @@ EXAMPLES
     $ sf agent preview send --utterance "what can you help me with?" --authoring-bundle My_Local_Agent
 ```
 
-_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/preview/send.ts)_
+_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/preview/send.ts)_
 
 ## `sf agent preview sessions`
 
@@ -735,7 +750,7 @@ EXAMPLES
     $ sf agent preview sessions
 ```
 
-_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/preview/sessions.ts)_
+_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/preview/sessions.ts)_
 
 ## `sf agent preview start`
 
@@ -792,7 +807,7 @@ EXAMPLES
     $ sf agent preview start --api-name My_Published_Agent
 ```
 
-_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/preview/start.ts)_
+_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/preview/start.ts)_
 
 ## `sf agent publish authoring-bundle`
 
@@ -841,7 +856,7 @@ EXAMPLES
     $ sf agent publish authoring-bundle --api-name MyAuthoringbundle --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/publish/authoring-bundle.ts)_
+_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/publish/authoring-bundle.ts)_
 
 ## `sf agent test create`
 
@@ -896,7 +911,7 @@ EXAMPLES
     $ sf agent test create --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview
 ```
 
-_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/test/create.ts)_
+_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/test/create.ts)_
 
 ## `sf agent test list`
 
@@ -931,7 +946,7 @@ EXAMPLES
     $ sf agent test list --target-org my-org
 ```
 
-_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/test/list.ts)_
+_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/test/list.ts)_
 
 ## `sf agent test results`
 
@@ -997,7 +1012,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/test/results.ts)_
+_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/test/results.ts)_
 
 ## `sf agent test resume`
 
@@ -1070,7 +1085,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/test/resume.ts)_
+_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/test/resume.ts)_
 
 ## `sf agent test run`
 
@@ -1144,7 +1159,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/test/run.ts)_
+_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/test/run.ts)_
 
 ## `sf agent validate authoring-bundle`
 
@@ -1191,6 +1206,6 @@ EXAMPLES
     $ sf agent validate authoring-bundle --api-name MyAuthoringBundle --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.31.3/src/commands/agent/validate/authoring-bundle.ts)_
+_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.1/src/commands/agent/validate/authoring-bundle.ts)_
 
 <!-- commandsstop -->

command-snapshot.json

@@ -4,7 +4,7 @@
     "command": "agent:activate",
     "flagAliases": [],
     "flagChars": ["n", "o"],
-    "flags": ["api-name", "api-version", "flags-dir", "json", "target-org"],
+    "flags": ["api-name", "api-version", "flags-dir", "json", "target-org", "version"],
     "plugin": "@salesforce/plugin-agent"
   },
   {

messages/agent.activate.md

@@ -4,23 +4,29 @@ Activate an agent in an org.
 
 # description
 
-Activating an agent makes it immediately available to your users. An agent must be active before you can preview it with the "agent preview" CLI command or VS Code.
+Activating an agent makes it immediately available to your users. A published agent must be active before you can preview it with the "agent preview" CLI command or VS Code. Agents can have multiple versions; only one version can be active at a time.
 
-You must know the agent's API name to activate it; you can either be prompted for it or you can specify it with the --api-name flag. Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup.
+If you run the command without the --api-name or --version flags, the command provides a list of agent API names and versions for you to choose from. Use the flags to specify the exact agent and version without being prompted. If you use the --json flag and not --version, then the latest agent version is automatically activated.
+
+The value of the --version flag is always a number, corresponding to the "vX" part of the "BotVersion" metadata in your project. For example, if you have a force-app/main/default/bots/My_Agent/v4.botVersion-meta.xml file in your project, then you activate this version with the "--version 4" flag.
 
 # examples
 
-- Activate an agent in your default target org by being prompted:
+- Activate an agent in your default target org by being prompted for both its API name and version:
 
   <%= config.bin %> <%= command.id %>
 
-- Activate an agent with API name Resort_Manager in the org with alias "my-org":
+- Activate version 2 of an agent with API name Resort_Manager in the org with alias "my-org":
 
-  <%= config.bin %> <%= command.id %> --api-name Resort_Manager --target-org my-org
+  <%= config.bin %> <%= command.id %> --api-name Resort_Manager --version 2 --target-org my-org
 
 # flags.api-name.summary
 
-API name of the agent to activate.
+API name of the agent to activate; if not specified, the command provides a list that you choose from.
+
+# flags.version.summary
+
+Version number of the agent to activate; if not specified, the command provides a list that you choose from.
 
 # error.missingRequiredFlags
 

messages/agent.activation.md

@@ -13,3 +13,7 @@ Agent %s has been deleted and can't be activated.
 # error.agentIsDefault
 
 Agent %s is the default Agentforce agent in your org and you can't change its activation status.
+
+# error.noVersionsAvailable
+
+No versions available to %s. All versions are already in the target state.

messages/agent.deactivate.md

@@ -6,7 +6,7 @@ Deactivate an agent in an org.
 
 Deactivating an agent makes it unavailable to your users. To make changes to an agent, such as adding or removing topics or actions, you must deactivate it. You can't preview an agent with the "agent preview" CLI command or VS Code if it's deactivated.
 
-You must know the agent's API name to deactivate it; you can either be prompted for it or you can specify it with the --api-name flag. Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup.
+If you run the command without the --api-name flag, the command provides a list of agent API names for you to choose from. Use the flag to specify the exact agent without being prompted.
 
 # examples
 
@@ -20,7 +20,7 @@ You must know the agent's API name to deactivate it; you can either be prompted
 
 # flags.api-name.summary
 
-API name of the agent to deactivate.
+API name of the agent to deactivate; if not specified, the command provides a list that you choose from.
 
 # error.missingRequiredFlags