feat: add sf agent optimize commands for HEPO agent optimization

command-snapshot.json

@@ -287,6 +287,57 @@
     ],
     "plugin": "@salesforce/plugin-agent"
   },
+  {
+    "alias": [],
+    "command": "agent:optimize:accept",
+    "flagAliases": [],
+    "flagChars": ["i", "o"],
+    "flags": ["api-version", "execution-id", "flags-dir", "json", "target-org"],
+    "plugin": "@salesforce/plugin-agent"
+  },
+  {
+    "alias": [],
+    "command": "agent:optimize:results",
+    "flagAliases": [],
+    "flagChars": ["i", "o"],
+    "flags": ["api-version", "execution-id", "flags-dir", "json", "target-org"],
+    "plugin": "@salesforce/plugin-agent"
+  },
+  {
+    "alias": [],
+    "command": "agent:optimize:run",
+    "flagAliases": [],
+    "flagChars": ["i", "o", "s"],
+    "flags": ["api-version", "authoring-bundle", "flags-dir", "iterations", "json", "spec", "target-org"],
+    "plugin": "@salesforce/plugin-agent"
+  },
+  {
+    "alias": [],
+    "command": "agent:optimize:start",
+    "flagAliases": [],
+    "flagChars": ["b", "c", "o", "w"],
+    "flags": [
+      "api-version",
+      "authoring-bundle",
+      "criteria",
+      "flags-dir",
+      "json",
+      "max-iterations",
+      "target-org",
+      "target-score",
+      "test-cases",
+      "wait"
+    ],
+    "plugin": "@salesforce/plugin-agent"
+  },
+  {
+    "alias": [],
+    "command": "agent:optimize:status",
+    "flagAliases": [],
+    "flagChars": ["i", "o"],
+    "flags": ["api-version", "execution-id", "flags-dir", "json", "target-org"],
+    "plugin": "@salesforce/plugin-agent"
+  },
   {
     "alias": [],
     "command": "agent:preview",

messages/agent.optimize.accept.md

@@ -0,0 +1,21 @@
+# summary
+
+Accept and publish the results of a completed HEPO optimization.
+
+# description
+
+Sends a publish signal to the optimization workflow, deploying the best-performing agent configuration as a draft.
+
+# examples
+
+- Accept and publish an optimization result:
+
+  <%= config.bin %> <%= command.id %> --execution-id hepo:wf-abc123:run-xyz --target-org myOrg
+
+# flags.execution-id.summary
+
+Execution ID returned by `sf agent optimize start`.
+
+# error.acceptFailed
+
+Failed to accept optimization: %s

messages/agent.optimize.results.md

@@ -0,0 +1,25 @@
+# summary
+
+Get the final results of a completed HEPO optimization run.
+
+# description
+
+Returns detailed results of a completed optimization, including iteration history, score improvements, and the best agent snapshot.
+
+# examples
+
+- Get results of a completed optimization:
+
+  <%= config.bin %> <%= command.id %> --execution-id hepo:wf-abc123:run-xyz --target-org myOrg
+
+# flags.execution-id.summary
+
+Execution ID returned by `sf agent optimize start`.
+
+# error.resultsFailed
+
+Failed to get optimization results: %s
+
+# error.stillRunning
+
+Optimization %s is still running. Use `sf agent optimize status` to check progress.

messages/agent.optimize.run.md

@@ -0,0 +1,95 @@
+# summary
+
+Optimize an Agentforce agent by iteratively improving its instructions.
+
+# description
+
+Runs an optimization loop that evaluates the agent against test cases, uses an LLM to propose instruction improvements, and keeps changes that improve the score.
+
+Each iteration:
+
+1. Sends test utterances to the agent via preview
+2. Scores responses against expected outputs
+3. Proposes instruction edits via an LLM
+4. Applies edits and re-evaluates
+5. Keeps improvements, rejects regressions
+
+Uses the org's Einstein LLM to propose improvements. Falls back to ANTHROPIC_API_KEY or OPENAI_API_KEY from the environment when Einstein is not available on the org.
+
+# flags.authoring-bundle.summary
+
+Name of the authoring bundle to optimize.
+
+# flags.spec.summary
+
+Path to optimization spec file (JSON or YAML). Contains test cases with utterances and expected response keywords.
+
+# flags.iterations.summary
+
+Number of optimization iterations to run (default: 3).
+
+# examples
+
+- Optimize an agent with 3 iterations:
+
+  <%= config.bin %> <%= command.id %> --authoring-bundle MyAgent --spec test-cases.json --target-org my-org
+
+- Run 5 optimization iterations:
+
+  <%= config.bin %> <%= command.id %> --authoring-bundle MyAgent --spec test-cases.json --target-org my-org --iterations 5
+
+# output.baseline
+
+Baseline score: %s (%s/%s test cases passed)
+
+# output.iterationKeep
+
+Iteration %s: KEEP — score improved %s → %s (%s)
+
+# output.iterationReject
+
+Iteration %s: REJECT — score %s did not improve over %s (%s)
+
+# output.summary
+
+Optimization complete. Baseline: %s → Best: %s (%s iterations, %s kept)
+
+# output.noImprovement
+
+No improvements found after %s iterations. Agent unchanged.
+
+# output.alreadyPerfect
+
+All test cases already passing. Agent is fully optimized — no changes needed.
+
+# output.agentUpdated
+
+Agent file updated: %s
+
+# output.agentRestored
+
+Agent file restored to best version.
+
+# error.specNotFound
+
+Spec file not found: %s.
+
+# error.invalidSpec
+
+Invalid optimization spec: %s. Expected JSON with a "test_cases" array.
+
+# error.bundleNotFound
+
+Authoring bundle '%s' not found in the project.
+
+# error.agentFileNotFound
+
+Agent file not found in bundle '%s'. Expected <BundleName>.agent inside the authoring bundle directory.
+
+# error.llmCallFailed
+
+Einstein LLM call failed: %s.
+
+# error.previewFailed
+
+Preview session failed: %s.

messages/agent.optimize.start.md

@@ -0,0 +1,83 @@
+# summary
+
+Start a server-side HEPO optimization for an Agentforce agent.
+
+# description
+
+Starts an iterative optimization workflow on the server. The workflow evaluates the agent against test cases, proposes instruction improvements via an LLM, and keeps changes that improve the score.
+
+Unlike `sf agent optimize run` (which runs optimization client-side), this command offloads all work to the HEPO service and only polls for progress.
+
+# examples
+
+- Start optimization and wait for completion:
+
+  <%= config.bin %> <%= command.id %> --authoring-bundle ShoppingAgent --criteria criteria.yaml --target-org myOrg --wait 60
+
+- Start optimization without waiting (check status later):
+
+  <%= config.bin %> <%= command.id %> --authoring-bundle ShoppingAgent --criteria criteria.yaml --target-org myOrg
+
+- Start with custom iteration settings:
+
+  <%= config.bin %> <%= command.id %> --authoring-bundle ShoppingAgent --criteria criteria.yaml --max-iterations 15 --target-score 0.95 --target-org myOrg
+
+# flags.authoring-bundle.summary
+
+Name of the agent authoring bundle to optimize.
+
+# flags.criteria.summary
+
+Path to criteria YAML file defining scoring metrics, gates, and weights.
+
+# flags.test-cases.summary
+
+Path to test cases YAML file. If not provided, test cases from the criteria file are used.
+
+# flags.max-iterations.summary
+
+Maximum number of optimization iterations (default: 10).
+
+# flags.target-score.summary
+
+Target composite score to stop early (default: 1.0).
+
+# flags.wait.summary
+
+Minutes to wait for completion.
+
+# flags.wait.description
+
+Poll for status updates until the optimization completes or times out. Without --wait, the command returns immediately after starting.
+
+# output.started
+
+Optimization started. Execution ID: %s
+
+# output.progress
+
+Iteration %s/%s — Baseline: %s Current: %s Best: %s
+
+# output.completed
+
+Optimization completed in %s iterations. Baseline: %s → Best: %s
+
+# output.timeout
+
+Optimization still running after %s minutes. Use `sf agent optimize status --execution-id %s` to check progress.
+
+# error.startFailed
+
+Failed to start optimization: %s
+
+# error.pollFailed
+
+Failed to poll optimization status: %s
+
+# error.criteriaNotFound
+
+Criteria file not found: %s
+
+# error.invalidCriteria
+
+Invalid criteria file: %s

messages/agent.optimize.status.md

@@ -0,0 +1,21 @@
+# summary
+
+Get the status of a server-side HEPO optimization run.
+
+# description
+
+Returns the current status of a running or completed HEPO optimization, including iteration progress and score improvements.
+
+# examples
+
+- Get status of an optimization run:
+
+  <%= config.bin %> <%= command.id %> --execution-id hepo:wf-abc123:run-xyz --target-org myOrg
+
+# flags.execution-id.summary
+
+Execution ID returned by `sf agent optimize start`.
+
+# error.statusFailed
+
+Failed to get optimization status: %s

package.json

@@ -91,6 +91,10 @@
             "description": "Commands to generate agent artifacts, such as the agent spec YAML file, authoring bundle, and test spec file.",
             "external": true
           },
+          "optimize": {
+            "description": "Commands to optimize agents.",
+            "external": true
+          },
           "validate": {
             "description": "Command to validate an Agent Script file.",
             "external": true
@@ -258,5 +262,6 @@
     }
   },
   "exports": "./lib/index.js",
-  "type": "module"
+  "type": "module",
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

schemas/agent-optimize-accept.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/AgentOptimizeAcceptResult",
+  "definitions": {
+    "AgentOptimizeAcceptResult": {
+      "$ref": "#/definitions/OptimizationAcceptResult"
+    },
+    "OptimizationAcceptResult": {
+      "type": "object",
+      "properties": {
+        "executionId": {
+          "type": "string"
+        },
+        "published": {
+          "type": "boolean"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": ["executionId", "published", "message"],
+      "additionalProperties": false
+    }
+  }
+}