@salesforce/afv-skills 1.36.0 → 1.38.0

package/skills/agentforce-generate/references/control-flow-actions-sequencing.md

@@ -0,0 +1,198 @@
+# AgentScript Action and Sequencing Pitfalls
+
+Use this reference when action availability, ordered tool use, state timing, or
+result handling may explain a behavior defect.
+
+## Contents
+
+- [Actions that escape their intended branch](#actions-that-escape-their-intended-branch)
+- [Impossible same-turn sequences](#impossible-same-turn-sequences)
+- [State written too early](#state-written-too-early)
+- [Stale, raw, or missing action results](#stale-raw-or-missing-action-results)
+
+## Actions that escape their intended branch
+
+### Pitfall: mentioning an action under one branch is assumed to scope it
+
+Actions are defined for the reasoning scope, not nested under the visual prompt
+paragraph that mentions them. Unless gated, an action remains available while
+other branches are active.
+
+```agentscript
+reasoning:
+    instructions: ->
+        if @variables.validation_succeeded == True:
+            | Use the {!@actions.submit} action.
+    actions:
+        submit: @actions.submit_request
+```
+
+The `submit` action is still available when `validation_succeeded` is false.
+
+Fix:
+
+```agentscript
+submit: @actions.submit_request
+    available when @variables.validation_succeeded == True
+```
+
+### Pitfall: an action remains available after it succeeds
+
+If repeating an action would duplicate a write, charge, message, or external
+commitment, gate it on a result or idempotency value.
+
+```agentscript
+submit: @actions.submit_request
+    available when @variables.validation_succeeded == True
+    available when @variables.submission_id == ""
+    set @variables.submission_id = @outputs.submission_id
+```
+
+Do not depend only on prose such as “do not call this again.”
+
+## Impossible same-turn sequences
+
+### Pitfall: model-selected actions are written as imperative steps
+
+`@utils.setVariables` is a normal model-selected state-update tool. If the
+model calls it successfully, the runtime stores the values. The action does
+not itself define a turn boundary or guarantee another reasoning iteration.
+Prompt text does not execute the tool:
+
+```text
+Call the state-setting action.
+Then call the submission action.
+```
+
+The model may call either action, call both in one batch, or return text without
+calling either. The second action does not automatically follow merely because
+the prompt lists it second.
+
+Fix with the smallest suitable option:
+
+- bind current-turn values directly to the real action with `...`;
+- set trusted values deterministically before reasoning;
+- pass fixed values through a purpose-built transition or action;
+- return the required values from the first real action; or
+- combine inseparable writes into one implementation that owns the complete
+  update.
+
+### Pitfall: ask now and capture the future answer now
+
+```text
+Ask for the issue description.
+Call the capture action with the issue description.
+```
+
+The answer does not exist when the question is asked. Give that branch one
+outcome: ask. On the later turn, capture or use the answer.
+
+### Pitfall: one branch requires several model-selected tools in order
+
+The model may choose one tool, choose them in a different order, or produce a
+response before the expected sequence is complete. If the order protects
+authorization, correctness, or an external side effect, do not encode it only
+as a tool list in prompt text.
+
+Use deterministic post-action logic, gated actions with explicit intermediate
+results, or one purpose-built action that owns the sequence.
+
+## State written too early
+
+### Pitfall: “complete” means “started”
+
+Do not set:
+
+```agentscript
+set @variables.operation_completed = True
+```
+
+before the consequential action has returned a successful result.
+
+Prefer state names that match the evidence:
+
+```text
+validation_completed
+operation_requested
+operation_succeeded
+```
+
+If the runtime cannot observe the final external side effect, use a weaker name
+such as `operation_initiated` instead of claiming completion.
+
+### Pitfall: workflow state advances on failure
+
+Do not advance a stage, close a gate, or hide retry behavior merely because an
+action was attempted. Branch on the trusted action result and preserve a safe
+retry or failure path.
+
+### Pitfall: state exists only to imitate dialogue stages
+
+Avoid `current_step`, `question_asked`, or `has_greeted` when the available
+conversation history already supplies the required continuity. Add state for a
+named runtime consumer or when a value must outlive the usable history window;
+give it the reset, correction, and failure behavior relevant to its use cases.
+
+### Pitfall: one phase is represented several ways
+
+Pairs such as `q1_asking`/`q1_answered`, plus `current_step` and completion
+flags, can describe contradictory workflow positions. When deterministic
+sequencing is truly required, prefer one explicit phase value and keep separate
+state only for durable facts or trusted action inputs.
+
+Before adding state, list its producer, consumer, reset, failure behavior, and
+valid combinations with neighboring variables.
+
+## Stale, raw, or missing action results
+
+### Pitfall: “checked” is set before the result is usable
+
+Do not mark validation complete while its result still needs model-driven
+parsing:
+
+```agentscript
+set @variables.validation_output = @outputs.raw_json
+set @variables.validation_checked = True
+```
+
+Later conditions can read old or default structured values and choose the wrong
+branch. The raw output has resolved, but its derived fields have not.
+
+Fix:
+
+- Prefer typed action outputs.
+- Otherwise normalize the raw result deterministically.
+- Mark the check complete only after all branch inputs are stored.
+- If normalization must be model-driven, use an explicit reasoning boundary so
+  producing the raw result and consuming its parsed fields cannot occur in one
+  half-populated state.
+
+### Pitfall: raw JSON controls important branches
+
+Do not ask the model to extract authorization, eligibility, confirmation, or
+success flags from display-oriented text when those flags determine tool
+availability or a consequential transition. Return typed, machine-checkable
+outputs.
+
+### Pitfall: the script branches on a value no producer returns
+
+For every condition and `available when`, trace the value backward:
+
+```text
+consumer -> stored variable -> action output or deterministic assignment
+```
+
+If no reachable producer exists, the branch is dead or depends on an accidental
+default.
+
+### Pitfall: independent conditions overlap
+
+Sequential top-level condition blocks are evaluated independently. This is a
+pitfall only when predicates can overlap, leave an unintended gap, or require
+first-match priority. Complementary predicates such as `X == value` and
+`X != value` are mutually exclusive and do not overlap. When authoring new
+first-match alternatives, prefer `if / else if / else`; use independent blocks
+when multiple branches may run or mutual exclusion is explicit. Do not rewrite
+equivalent control flow in a bounded repair solely for style. Spell the clause
+`else if`; Python-style `elif` is invalid. Verify the effective prompt for each
+reachable state.

package/skills/agentforce-generate/references/control-flow-lifecycle-side-effects.md

@@ -0,0 +1,87 @@
+# AgentScript Lifecycle and Side-Effect Pitfalls
+
+Use this reference when per-turn lifecycle code, transitions, repeated
+reasoning, or competing side-effect owners may explain a behavior defect.
+
+## Lifecycle code that overwrites later work
+
+### Pitfall: `before_reasoning` resets a value every turn
+
+`before_reasoning` runs once when that subagent execution begins. A transition,
+including a self-transition, can start another subagent execution in the same
+user turn. An unconditional assignment there can erase a value captured or
+inferred earlier.
+
+Review every lifecycle assignment by asking:
+
+- Is this an initialization or an unconditional reset?
+- Can a later branch legitimately change it?
+- When and where is it cleared?
+
+Initialize only when the value is unset, or let the destination subagent own its
+own intent.
+
+### Pitfall: a transition reprocesses the same customer message
+
+A transition can start the target subagent during the same customer turn. The
+target may receive the message that completed the prior gate, not a fresh
+request. Make the target coherent for that arrival path or transition only when
+the target has enough explicit state to act safely.
+
+### Pitfall: same-iteration instructions assume a deterministic pause
+
+Deterministic lifecycle statements continue resolving after a `run` stores its
+output. A nearby `|` block adds text to the model's next prompt; it does not
+pause runtime execution so the model can act before the following `set` or
+condition.
+
+Remember the execution order:
+
+```text
+1. Resolve deterministic run, set, and if statements and assemble all | text.
+2. Send the completed prompt to the model, which may call a tool or respond.
+```
+
+For example, this is unsafe when the parsed fields still hold defaults:
+
+```agentscript
+run @actions.validate
+    set @variables.raw_result = @outputs.output
+| Parse the raw result and store the derived flags.
+set @variables.validation_checked = True
+```
+
+Use typed outputs, deterministic normalization, a purpose-built action that
+owns the operation, or an explicit reasoning boundary. A guarded
+self-transition can serve as a boundary
+when the runtime offers no smaller supported stage: the first pass stores the
+raw result and exits; re-entry builds a fresh prompt from that result; the next
+model action stores all derived fields and the completion flag together.
+Document that pattern as a phase boundary, not as a generic loop.
+
+## Competing owners for one side effect
+
+### Pitfall: two mechanisms both appear to perform the same operation
+
+Examples:
+
+- one action is named “validate and submit,” followed by another submit action;
+- an external action performs transfer, followed by a utility escalation;
+- a transition and a delegated subagent both own completion.
+
+Choose one owner for each external side effect. Document whether other actions
+prepare, validate, invoke, or verify it.
+
+### Pitfall: model text is treated as proof
+
+A promise, confirmation, or tool name in the model response is not evidence
+that an external action occurred. An instruction such as `Call
+escalate_to_live_engineer` only asks the model to select that tool. The model
+may instead answer “I'm transferring you,” and a text-only response is a valid
+reasoning result. Verify separately:
+
+```text
+configured -> available -> invoked -> executed -> effected
+```
+
+Advance consequential state only at the strongest layer the runtime can prove.

package/skills/agentforce-generate/references/examples.md

@@ -53,7 +53,7 @@ subagent greeting:
 	reasoning:
 		instructions: ->
 			| Welcome the user warmly.
-			| Ask how you can help them today.
+			  Ask how you can help them today.
 ```
 
 Companion `bundle-meta.xml` (MUST be this exact content -- no extra fields):
@@ -137,7 +137,7 @@ subagent knowledge_search:
 				| Found article {!@variables.article_id}. Here are the details.
 
 			| Search the knowledge base using the search_articles action.
-			| Present results clearly. Do not fabricate article content.
+			  Present results clearly. Do not fabricate article content.
 
 		actions:
 			search: @actions.search_articles
@@ -164,10 +164,10 @@ subagent account_support:
 					description: "Reset status"
 					is_displayable: True
 
-	reasoning:
-		instructions: ->
-			| I can help with password resets and account access.
-			| Ask for the employee's email, then use the reset_password action.
+		reasoning:
+			instructions: ->
+				| Explain that you can help with password resets and account access.
+				  Ask for the employee's email, then use the reset_password action.
 
 		actions:
 			reset: @actions.reset_password
@@ -270,14 +270,14 @@ subagent order_support:
 					description: "Tracking URL"
 					is_displayable: True
 
-	reasoning:
-		instructions: ->
-			if @variables.order_status != "":
-				| Order {!@variables.order_id} status: {!@variables.order_status}
-
-			| What is your order number? I will look it up for you.
-			| Use the get_order action to retrieve order details.
-			| Do not guess order status -- always use the action result.
+		reasoning:
+			instructions: ->
+				if @variables.order_status != "":
+					| Report order {!@variables.order_id} with exact status
+					  {!@variables.order_status}. Do not guess or paraphrase it.
+				else:
+					| Ask for the order number, then use the get_order action to
+					  retrieve the details.
 
 		actions:
 			lookup: @actions.get_order
@@ -307,11 +307,11 @@ subagent return_support:
 					description: "Return authorization ID"
 					is_displayable: True
 
-	reasoning:
-		instructions: ->
-			| I can help with your return request.
-			| Please provide your order number and the reason for the return.
-			| Use the initiate_return action to start the process -- do not fabricate return IDs.
+		reasoning:
+			instructions: ->
+				| Explain that you can help with the return. Ask for the order
+				  number and reason.
+				  Use the initiate_return action to start the process -- do not fabricate return IDs.
 
 		actions:
 			start_return: @actions.initiate_return
@@ -345,8 +345,8 @@ subagent confirmation:
 	description: "Confirm the completed action"
 	reasoning:
 		instructions: ->
-			| Your request has been processed. Reference: {!@variables.case_id}
-			| Is there anything else I can help with?
+			| Confirm that the request was processed, provide exact reference
+			  {!@variables.case_id}, and ask whether the user needs anything else.
 		actions:
 			new_request: @utils.transition to @subagent.agent_router
 				description: "Start a new request"
@@ -393,7 +393,7 @@ subagent main:
         instructions: ->
             if @variables.customer_verified == True:
                 | You are speaking with a verified customer.
-                | Help them with their request.
+                  Help them with their request.
             else:
                 | Please verify the customer's identity first.
         actions: