@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/agentforce-generate/references/agentscript-toolchain.md

@@ -0,0 +1,112 @@
+# AgentScript Compiler Setup and Provenance
+
+For every authoring, repair, or audit task with an existing `.agent` file, run
+the bundled compiler locally before target-org validation. This is the cheap,
+repeatable first pass even when the customer has an authenticated org. The
+customer should not need to clone this skills repository or modify their
+project dependencies.
+
+## Provider order
+
+Use the first working local provider and record it:
+
+1. an explicit `AGENTSCRIPT_SDK_ENTRY` override, when the user supplied one;
+2. the last successfully verified SDK in the skill-owned cache;
+3. an AgentScript SDK already installed in the customer project or skill host;
+4. the public npm package installed into the skill-owned cache;
+5. a fresh build from the public `salesforce/agentscript` source repository.
+
+After the local pass, use target-org validation when an authenticated org is
+available. The two checks are complementary: the local compiler provides fast
+feedback, while the org establishes what that deployment target accepts. Use a
+bounded static review only when no local compiler or org validation surface is
+available.
+
+An absent or unauthenticated org is not a reason to skip the local compiler.
+Local compilation does not require org access. Do not report “no org” as the
+cause of **compiler not used**; attempt the local providers below and report the
+actual setup or loading failure if none works.
+
+Compiler setup must not become an all-or-nothing gate. Try each applicable
+install provider once. If installation fails, retain the error, continue with
+the strongest remaining validation surface, and state **compiler not used**
+with the cause rather than abandoning the authoring or audit result.
+
+## Install from npm
+
+Resolve the installed `agentforce-generate` skill directory and run:
+
+```bash
+node <skill-directory>/scripts/setup-agentscript-sdk.mjs --npm --json
+```
+
+The setup script installs the pinned public
+`@sf-agentscript/agentforce` package into the user cache, not the customer
+project or global npm prefix. It then runs a compiler smoke test and records the
+resolved package version and entry point.
+
+If evidence indicates that the bundled npm pin is behind the currently
+published package, retry once with an exact newer version or `latest` and retain
+the resolved version:
+
+```bash
+node <skill-directory>/scripts/setup-agentscript-sdk.mjs \
+  --npm --version latest --force --json
+```
+
+Do not call a package current merely because `latest` resolved. Compare its
+diagnostics with the syntax under review, the public source revision when
+needed, and the deployment org before release.
+
+## Build from public source
+
+Use the source fallback when the npm package is unavailable, cannot load, or
+appears older than the syntax under review:
+
+```bash
+node <skill-directory>/scripts/setup-agentscript-sdk.mjs \
+  --source --source-ref main --force --json
+```
+
+This downloads `https://github.com/salesforce/agentscript.git` into the same
+skill-owned cache, records the exact fetched commit, installs its pinned pnpm
+dependencies, builds the Agentforce SDK and its dependencies, and runs the same
+compiler smoke test. It requires Git, either pnpm or Corepack-provided pnpm, and
+the operating-system build prerequisites required by the selected public
+source revision. A missing native build prerequisite is an installation failure
+to report and fall back from; it is not a reason to abandon the audit.
+
+Use a tag or commit with `--source-ref` when reproducibility matters. A source
+build can be newer than the deployment org; it is evidence about that source
+revision, not proof that an org accepts the same syntax.
+
+## Use and report the compiler
+
+Run the bundled indexer after setup:
+
+```bash
+node <skill-directory>/scripts/index-agent.mjs <agent-file>
+```
+
+The JSON result includes a `compiler` object. Always carry these fields into
+the audit or authoring report:
+
+- provider: ambient npm, cached npm, public source, or explicit entry;
+- exact npm package and resolved version, when applicable;
+- exact source commit, when applicable;
+- compiler entry path;
+- whether target-org validation also ran.
+
+If the indexer was not run, say so. If it failed before loading a compiler,
+report **compiler not used** and the reason. Never describe a prompt-only or
+regex inspection as compiler validation.
+
+## Overrides and cache
+
+- `AGENTSCRIPT_SDK_ENTRY` selects a specific built SDK entry file.
+- `AGENTFORCE_GENERATE_CACHE` selects a different cache root.
+- `XDG_CACHE_HOME` changes the standard cache root.
+
+The default cache is `.cache/agentforce-generate` under the current user's home
+directory. Setup writes only below the selected cache root and does not install
+global packages.

package/skills/agentforce-generate/references/architecture-patterns.md

@@ -14,7 +14,7 @@ independently required gate or post-action behavior.
 | Pattern | Use When |
 |---------|----------|
 | Single Scope | Default. One domain `start_agent` block, zero `subagent` blocks, and one compatible set of instructions, actions, authority, and escalation behavior |
-| Router-First Architecture | Multiple genuine domains require different objectives, instructions, actions, authority, or escalation behavior |
+| Router-First Architecture | Multiple genuine domains require different objectives, instructions, actions, authority, or escalation behavior; use HyperClassifier when the router is transition-only and routing latency matters |
 | Verification Gate | Sensitive data, payments, or PII require identity verification first |
 | Post-Action Re-resolution | Trusted action output must drive a named follow-up instruction, gate, or action input |
 
@@ -41,10 +41,11 @@ A central `agent_router` routes to specialized subagents. Transition paths shoul
 ```agentscript
 start_agent agent_router:
     description: "Route user requests to the appropriate subagent"
+
+    model_config:
+        model: "model://sfdc_ai__DefaultEinsteinHyperClassifier"
+
     reasoning:
-        instructions: |
-            You are a router only. Do NOT answer questions directly.
-            Always use a transition action to route immediately.
         actions:
             to_orders: @utils.transition to @subagent.order_support
                 description: "Order questions"
@@ -67,11 +68,72 @@ subagent order_support:
 
 > **Routing lives in `start_agent`** -- put classification transitions in `start_agent agent_router:`. Do NOT create a separate routing-only subagent (e.g. `main_menu`, `central_hub`) -- that duplicates the router, adds an extra LLM hop (~3-5s latency), and confuses the platform. A transition back to router is optional and should only be added when the use case requires reclassification.
 
-> **`instructions: |` in a router is probabilistic.** The LLM may respond
-> conversationally instead of emitting a transition. This is appropriate for
-> unstructured current-intent classification. Use `instructions: ->` only when
-> a named deterministic cause, such as verified authorization, selects the
-> transition; do not encode ordinary dialogue stages as state.
+### Fast routing with Einstein HyperClassifier
+
+Use HyperClassifier when the node has one job: select one transition from the
+current request and conversation context. Adding this model configuration makes
+the block a restricted router node rather than a general reasoning node:
+
+```agentscript
+model_config:
+    model: "model://sfdc_ai__DefaultEinsteinHyperClassifier"
+```
+
+It is a good fit when multiple genuine domains already justify a router and
+classification latency matters. The router selects a destination; the target
+subagent handles the request and produces the user-facing response.
+
+The restrictions are part of the design:
+
+- reasoning actions must be `@utils.transition`;
+- `before_reasoning` and `after_reasoning` are not supported;
+- it cannot classify from images;
+- it cannot fill action inputs, run domain actions, set variables, escalate, or
+  delegate to a connected agent;
+- it cannot ask a clarifying question directly. When ambiguity needs a
+  conversation, transition to a clarification or fallback subagent.
+
+Use `available when` to remove routes based on trusted runtime state before
+classification. Give every route a distinct description that states its
+positive scope and important exclusions. Treat those descriptions as the
+primary classification contract. Keep `reasoning.instructions` concise: state
+the shared routing duty, such as selecting exactly one route without answering,
+and put route-specific boundaries in the action descriptions. Add a fallback
+route only when the agent has an intended fallback behavior.
+
+An instruction-free router is structurally valid. It can preserve an optimized
+one-step routing path in runtimes where router instructions compile into a
+lifecycle hook, but use that form only when the action descriptions fully carry
+the routing contract and preview traces confirm the intended optimization.
+Instructions are not prohibited by HyperClassifier; this is a measured latency
+tradeoff, not a language requirement.
+
+When adding HyperClassifier to an existing compatible router, preserve its
+instruction block unless changing that contract is separately required. An
+`instructions: ->` block containing only `|` prompt text is valid; do not
+normalize it to `instructions: |` as part of the model-config repair merely
+because it has no runtime statements.
+
+Keep an ordinary reasoning model when the entry node must answer, clarify,
+collect information, manipulate state, invoke non-transition actions, inspect
+images, or use lifecycle hooks. HyperClassifier is an optimization for a
+compatible router, not a reason to create more subagents.
+
+Validate structure, then validate routing behavior:
+
+```bash
+sf agent validate authoring-bundle --json --api-name <BundleName> -o <OrgAlias>
+sf agent preview start --json --use-live-actions --authoring-bundle <BundleName> -o <OrgAlias>
+```
+
+Preview positive and negative examples for every route, ambiguous boundary
+utterances, follow-up turns, unavailable-route states, and the intended
+fallback. Inspect the selected transition in the trace; response text alone
+does not prove routing.
+
+Without HyperClassifier, transition actions on an ordinary reasoning node
+remain model-selected and the node can respond instead. That flexibility is
+useful when conversation at the entry node is intentional.
 
 ## Verification Gate
 
@@ -125,10 +187,11 @@ follow-up context.
 
 ## Post-Action Re-resolution
 
-The subagent re-resolves after an action completes. Persist action output only
-when a named later runtime consumer needs the exact value. Place the
-post-action check at the top of `instructions: ->` so it applies on
-re-resolution:
+The subagent can re-resolve after an action completes. Persist action output
+only when a named later runtime consumer needs the exact value. Make
+post-action and first-entry duties mutually exclusive; placing the post-action
+check first can make that ownership easier to review, but position alone does
+not exclude another fragment:
 
 ```agentscript
 variables:
@@ -138,13 +201,13 @@ subagent retention_review:
     description: "Use a returned risk score to select retention guidance"
     reasoning:
         instructions: ->
-            # POST-ACTION CHECK (at top on re-resolution)
+            # POST-ACTION CHECK (first for readability, exclusive by predicate)
             if @variables.risk_score >= 80:
-                | The returned risk score is {!@variables.risk_score}.
-                | Offer the approved retention options.
+                | Use the returned risk score {!@variables.risk_score}. Offer
+                  the approved high-risk retention options.
             else if @variables.risk_score >= 0:
-                | The returned risk score is {!@variables.risk_score}.
-                | Follow the standard retention policy.
+                | Use the returned risk score {!@variables.risk_score}. Follow
+                  the standard retention policy.
             else:
                 | Explain that a risk assessment is needed before making an offer.
         actions:

package/skills/agentforce-generate/references/common-control-flow-pitfalls.md

@@ -0,0 +1,255 @@
+# Common AgentScript Control-Flow Pitfalls
+
+Use this checklist when authoring, reviewing, debugging, or optimizing an
+AgentScript workflow. It focuses on mistakes that look reasonable in the source
+but do not mean what their formatting suggests.
+
+For an audit, use the contents below as a lookup after the initial artifact
+scan. Read the sections that match a named observation; do not delay a ranked
+finding or repair by reviewing every pitfall first.
+
+## Contents
+
+- [The simple mental model](#the-simple-mental-model)
+- [Variable visibility and condition ownership](#variable-visibility-and-condition-ownership)
+- [Prompt text that looks like code](#prompt-text-that-looks-like-code)
+- [Repeated prompt markers](#repeated-prompt-markers)
+- [Step labels without runtime state](#step-labels-without-runtime-state)
+- [Focused continuation references](#focused-continuation-references)
+- [Review checklist](#review-checklist)
+
+## The simple mental model
+
+AgentScript has three different execution surfaces:
+
+1. Deterministic constructs such as `if`, `run`, `set`, `transition to`, and
+   lifecycle hooks execute in the runtime.
+2. Text introduced by `|` becomes instructions for the model.
+3. Actions under `reasoning.actions` become tools the model may choose.
+
+Do not rely on indentation, numbering, or imperative words inside prompt text
+to behave like runtime control flow.
+
+## Variable visibility and condition ownership
+
+### Pitfall: the model is expected to read stored state
+
+The runtime can evaluate and bind `@variables.X`. The model cannot inspect the
+variable store directly. Inside `|` text, a bare variable reference contributes
+only its literal name; it does not inject the stored value. The same value could
+still be visible if it was separately interpolated or preserved in conversation
+or tool history:
+
+```agentscript
+# Model sees the characters "@variables.case_summary", not the summary value.
+| Explain @variables.case_summary to the customer.
+
+# Model receives the current value.
+| Explain this case summary: {!@variables.case_summary}
+```
+
+Do not add interpolation when the text merely names a parameter:
+
+```agentscript
+| Set next_destination to "self_service".
+```
+
+That instruction asks the model to supply a value; it does not ask the model to
+read the current value.
+
+### Pitfall: interpolation is mistaken for deterministic control
+
+```agentscript
+# BAD when this must be an exact branch
+| If {!@variables.account_status} == "blocked":
+    do the blocked-account steps.
+```
+
+The merge field reveals the value, but the model still performs the comparison
+and decides whether to comply. If the runtime fact must always select the same
+branch, use AgentScript control:
+
+```agentscript
+if @variables.account_status == "blocked":
+    | Help the customer recover access to the blocked account.
+```
+
+Keep situation-aware judgment with the model:
+
+```agentscript
+| If the user wants to speak with a human, use
+  {!@actions.escalate_to_support}.
+```
+
+Do not convert conditions mechanically. Ask whether the decision is an exact
+trusted fact with a mandatory consequence or an interpretation of natural
+language and context.
+
+## Prompt text that looks like code
+
+### Pitfall: indented prompt text appears scoped
+
+```agentscript
+if @variables.lookup_failed == True:
+    | Failure path:
+        Call {!@actions.create_ticket}.
+```
+
+The indentation after `|` formats model-visible prose. It does not place
+`create_ticket` inside the deterministic `if`.
+
+Fix:
+
+- Use the `if` to select the prompt text.
+- Use `available when` to select the action schema.
+
+```agentscript
+reasoning:
+    instructions: ->
+        if @variables.lookup_failed == True:
+            | Explain that the lookup failed. If the customer asks to create a
+              ticket, use the ticket action.
+    actions:
+        create_ticket: @actions.create_ticket
+            available when @variables.lookup_failed == True
+```
+
+### Pitfall: prompt verbs are mistaken for commands
+
+Inside a pipe block, these are ordinary words:
+
+```text
+Show | Ask | Call | Set | Stop | Continue | Go to
+```
+
+They may guide the model, but they do not:
+
+- send a response deterministically;
+- mutate a variable;
+- execute an action;
+- stop runtime resolution; or
+- transition to another subagent.
+
+Use runtime `set` and `transition to` for deterministic state-based behavior.
+Expose an action when the model should judge whether to act.
+
+### Pitfall: stronger wording is used as enforcement
+
+Repeating `MANDATORY`, `DO NOT SKIP`, or `IMMEDIATELY` does not create a runtime
+guarantee. If ordering or eligibility matters, represent it with machine-known
+state, action inputs, `available when`, deterministic action chaining, or one
+purpose-built implementation that owns the sequence.
+
+## Repeated prompt markers
+
+### Pitfall: every sentence starts a new `|` fragment
+
+Inside one contiguous prompt block, use one `|` marker and continue subsequent
+lines beneath its content:
+
+```agentscript
+reasoning:
+    instructions: ->
+        | Explain the available options.
+          Ask which option the user prefers.
+          Keep the answer concise.
+```
+
+A same-scope run of `|`-prefixed sentences is valid syntax, but each marker
+starts another prompt fragment. It does not create a stage, pause, priority, or
+control boundary. Repeating the marker adds visual noise and can make the
+resolved prompt harder to review.
+
+Start another `|` after a runtime statement or branch when a new prompt
+fragment is structurally required. Preserve existing structural indentation,
+and compile after cleanup. Treat this as a Surface readability repair unless
+prompt inspection or evaluation shows a behavioral consequence.
+
+## Step labels without runtime state
+
+### Pitfall: step numbers are treated as a workflow engine
+
+```agentscript
+if @variables.ready == True:
+    | Step 4 — Submit the request.
+```
+
+The model may see “Step 4” without Steps 1–3. AgentScript includes only the
+prompt branches that resolve true during the current reasoning iteration.
+Numbering does not prove that earlier work happened.
+
+Fix:
+
+- Remove step numbers when they are only explanatory labels.
+- If earlier work is a real prerequisite, gate the later action on trusted
+  output from that work.
+
+```agentscript
+submit: @actions.submit_request
+    available when @variables.validation_succeeded == True
+```
+
+### Pitfall: a prompt depends on missing context
+
+Each resolved prompt fragment should make sense with the other fragments that
+can accompany it in the same reachable state. Avoid instructions
+such as “continue to the next step,” “use the result above,” or “as described
+earlier” when the referenced fragment may not survive conditional resolution.
+
+Name the actual objective and relevant state in the branch:
+
+```agentscript
+if @variables.validation_succeeded == True:
+    | Validation succeeded. Submit the verified request.
+```
+
+### Pitfall: stored state is assumed to be model-visible
+
+Storing an action output in `@variables` makes it available to runtime
+conditions and later bindings. It does not automatically insert the value into
+model-facing instructions. When the model must read a stored value, inject it
+explicitly:
+
+```agentscript
+if @variables.lookup_result != "":
+    | Use this lookup result: {!@variables.lookup_result}
+```
+
+Prefer typed outputs and deterministic conditions when the value controls
+authorization, eligibility, routing, or another consequential decision.
+
+## Focused continuation references
+
+- [Action and Sequencing Pitfalls](control-flow-actions-sequencing.md) — action availability, same-turn sequences, state timing, stale results, missing producers, and overlapping conditions.
+- [Lifecycle and Side-Effect Pitfalls](control-flow-lifecycle-side-effects.md) — per-turn resets, self-transitions, same-iteration assumptions, competing owners, and response text mistaken for proof.
+
+## Review checklist
+
+For every reasoning branch:
+
+- [ ] Does the resolved prompt make sense without hidden earlier “steps”?
+- [ ] Is every stored value the model must read explicitly injected?
+- [ ] Is every exact trusted comparison owned by runtime control when its
+      consequence must not vary?
+- [ ] Are semantic intent and ambiguity left to model judgment?
+- [ ] Does the branch have one next outcome?
+- [ ] Are `Show`, `Ask`, `Call`, `Set`, and `STOP` being used only as prose?
+- [ ] Are material actions gated independently of the prompt paragraph?
+- [ ] Can any action remain available after success and repeat?
+- [ ] Does prompt text request a tool call while later deterministic logic
+      assumes that call has already happened?
+- [ ] Does the branch ask for and consume the same future answer?
+- [ ] Are ordered tool calls enforced by the runtime when order matters?
+- [ ] Is every completion flag backed by a complete, usable result?
+- [ ] Is every condition value produced on every reachable path?
+- [ ] Are typed outputs used for machine-controlled decisions?
+- [ ] Are independent conditions intentionally cumulative or provably mutually
+      exclusive, and is first-match priority expressed with an
+      `if / else if / else` chain when it matters?
+- [ ] Can lifecycle logic overwrite a legitimate later value?
+- [ ] Does state encode durable evidence rather than duplicating history or
+      representing one phase with overlapping latches?
+- [ ] Is the reasoning burden appropriate for the deployed target model?
+- [ ] Does exactly one mechanism own each external side effect?
+- [ ] Do tests inspect action availability and external results, not only final
+      model text?