# Version History | Version | Date | Changes | |---------|------|---------| | 2.10.0 | 2026-03-28 | **SF CLI 2.128.5 command refresh**: Updated Agent Script CLI guidance to reflect that `sf agent activate` / `sf agent deactivate` now support `--json`, documented the new `--version` flag for deterministic activation in CI/CD, and removed the invalid Agent Script packaging example that used `sf agent generate template` with `.agent` files. Added managed-packaging caveats pointing back to the current Agent Script limitation, refreshed activation examples across `SKILL.md`, `cli-guide.md`, `agent-user-setup.md`, and `customer-web-client.md`, and added explicit `BotVersion` retrieve examples for version-targeted workflows. | | 2.9.0 | 2026-03-20 | **Distilled deterministic-string and prompt-output guidance**: Added public, source-agnostic guidance that raw `@system_variables.user_input` substring checks are brittle for deterministic routing and that `contains` / `startswith` / `endswith` should not be the sole gate for control-flow-critical validation. Documented the safer prompt-template output pattern (`is_displayable: False` + `is_used_by_planner: True`) and clarified that missing prompt responses often require checking planner visibility separately from displayability. Added output-schema guidance explaining that structured outputs may require field access such as `.value`, but only when the declared schema actually exposes that field. Expanded the validator with new warning rules for raw `user_input` string matching, general string-method guard portability, prompt outputs hidden without planner visibility, and structured outputs assigned directly to scalar variables. Updated prompt-template teaching assets to use the safer output flags. | | 2.8.1 | 2026-03-19 | **Deterministic `run` scope clarification**: Tightened skill guidance so `run @actions.X` is documented as deterministic **only** when `X` resolves to a topic-level action definition with `target:`. Expanded `ASV-RUN-014` in `agentscript-syntax-validator.py` to block three real-world failure modes with one rule: (1) `run` against reasoning-only utilities like `@utils.setVariables`, (2) `run` against topic-level utilities/delegations without `target:` such as `@utils.transition` / `@topic.X`, and (3) `run` against unresolved action names. Error messaging now points authors toward direct `set` / `transition to` or LLM-invoked `reasoning.actions:` utilities, matching observed `ACTION_NOT_IN_SCOPE` builder failures. Updated `SKILL.md`, `README.md`, `instruction-resolution.md`, `actions-reference.md`, `syntax-reference.md`, and teaching asset `patterns/llm-controlled-actions.agent` so the deterministic-vs-LLM-directed distinction is explicit. | | 2.8.0 | 2026-03-13 | **Validator rule-catalog expansion**: Expanded `agentscript-syntax-validator.py` with stable `ASV-*` rule IDs across structure, config, connection, org-aware, runtime, and quality checks. Added new blockers for `else if`, nested `if`, empty conditional bodies, top-level `actions:`, linked-variable defaults/types, lifecycle `|` lines, missing target-action `outputs:`, connection route completeness, reasoning-only `run @actions.X`, and apex/connection-flow existence checks. Added new warnings for template/demo config values, multiple `available when`, `require_user_confirmation`, lifecycle `run` portability, prompt-template output displayability, large-file risk, duplicate descriptions, and sensitive-action guard suggestions. New docs: [validator-rule-catalog.md](validator-rule-catalog.md), [validator-test-matrix.md](validator-test-matrix.md), and [asset-validation-profiles.md](asset-validation-profiles.md). Added profile-aware asset harness via `assets/validation-profiles.json` + `scripts/validate-asset-profiles.py` so standalone examples, org fixtures, and partial snippets can be validated in separate lanes, with explicit allowlists for both expected blocking IDs and expected warning IDs. Asset fixes during audit: flattened nested conditionals in `deterministic-routing.agent` and `patterns/open-gate-routing.agent`, added missing `refund_amount` to `verification-gate.agent`, and removed invalid `set ... = ...` placeholder syntax from `components/escalation-setup.agent`. | | 2.7.0 | 2026-03-13 | **Field-validated insights (wave 2)**: 7 new known issues (33-39): empty list literal `[]` not supported in expressions, `is_displayable: True` causes blank response on prompt outputs, topic `description:` line breaks break script, variable names conflict with system context mappings, Draft-vs-Committed behavior divergence, object variables not editable in preview, `@context.*` not supported for NGA Service Agents (P0 accuracy fix). New patterns: `knowledge: citations_enabled` property documented, `lightning:isPII` flag added to action I/O properties, empty list comparison/reset workarounds. Added `is_displayable: True` blank response gotcha to production-gotchas.md. Updated `@context` documentation with Employee-Agent-only caveat across syntax-reference.md and SKILL.md. | | 2.6.0 | 2026-03-12 | **Field-validated insights integration**: 7 new known issues (26-32): `is_required` planner no-op, ConcurrentModificationException on partial I/O, `date` type runtime error, ANTLR parser limit for large agents, "Failed to create planner session" 500, escalation loops without availability check, citations not rendering in NGA agents. 8 new syntax patterns documented: `agent_label` config property, `visibility` variable property, `@knowledge.*` resource references (`citations_url`, `rag_feature_config_id`, `citations_enabled`), `@MessagingSession.*` and `@MessagingEndUser.*` linked variable sources, action `source` attribute for asset library, limited `run @actions.X` success observed in some `before_reasoning:` target-backed cases (not reliable enough for broad recommendation), upcoming "topic→subagent" / "action→tool" naming changes. 2 P0 accuracy gaps fixed: `is_required` is not enforced by planner (use `available when` guards), `date` type fails at runtime in action I/O (use `object` + `lightning__dateType`). Added escalation availability check pattern to fsm-architecture.md and production-gotchas.md. Updated Issue 15 cross-reference to Issue 27. | | 2.5.0 | 2026-03-11 | **Production learnings integration**: Fixed `list[object]` SObject collection mapping (`lightning__recordInfoType` not `lightning__textType`) in complex-data-types.md. Added Flow Type -> Agent Script mapping table. Added Boolean-to-String coercion hazard to production-gotchas.md. Added Flow version mismatch warning to cli-guide.md. New [metadata-lifecycle.md](metadata-lifecycle.md) — GenAiPlannerBundle versioning, Orphan-Then-Delete cleanup pattern, Flow version drift, shared Apex dependencies. Added Standard Platform Topics (Inappropriate_Content, Prompt_Injection, Reverse_Engineering, Ambiguous_Question) to fsm-architecture.md. Added Auth Gate Leak anti-pattern with fix strategies. Added Context Variable Injection patterns to testing-guide.md (YAML format, conversationHistory, Verified_Check bypass). Moved Issue 16 to Resolved, sanitized Issue 18, added Issues 21-22 (old bundles block Apex deletion, Flow version drift). Collapsed stale planner engine comparison in debugging-guide.md. Removed duplicate Three-Phase Lifecycle from testing-guide.md. Updated document map with metadata-lifecycle.md. | | 2.4.0 | 2026-03-07 | **Agent user setup & permission model**: New [agent-user-setup.md](agent-user-setup.md) reference — 6-step Service Agent provisioning workflow, Employee Agent path, auto-generated PS warning (ORM1 testing: `NextGen_*_Permissions` incomplete), custom PS XML template, end-to-end verification checklist, troubleshooting table. Updated SKILL.md (service vs employee distinction across 6 locations), cli-guide.md (PS verification queries), README.md (requirements table), known-issues.md (Issue 10 enhanced with agent-type context). | | 2.3.0 | 2026-02-20 | **CLI audit & line budget refactoring**: Fixed `--message` → `--utterance` in preview send examples (P0 bug — flag doesn't exist). Added `sf agent activate` / `sf agent deactivate` lifecycle commands. Added `--no-spec` flag for `generate authoring-bundle`. Added 12 new `generate agent-spec` flags (`--tone`, `--enrich-logs`, `--full-interview`, `--spec` for iterative refinement, `--prompt-template`, `--grounding-context`, `--force-overwrite`, `--company-website`, `--max-topics`, `--agent-user`, `--output-file`, `--company-description`). Added preview mode documentation (simulated vs live, `--use-live-actions`, `--apex-debug`, `--output-dir`, `--authoring-bundle`). Moved Minimal Working Example to references/minimal-examples.md. Compressed Deployment Checklist to pointer. Updated deployment lifecycle: Validate → Deploy → Publish → Activate → (Deactivate → Re-publish → Re-activate). Verified against SF CLI v2.123.1. | | 2.2.0 | 2026-02-17 | **TDD Validation v2.2.0 — Action metadata properties validated**: 2 new agents (Val_Action_Meta_Props, Val_IO_Meta_Props). Corrected "Features NOT Valid" table → "Feature Validity by Context" — properties ARE valid on action definitions with targets, only invalid on `@utils.transition`. Validated 9 properties: `label` (action/topic/I/O), `require_user_confirmation`, `include_in_progress_indicator`, `progress_indicator_message`, `is_required`, `is_user_input`, `is_displayable`, `is_used_by_planner`. Root cause: v1.3.0 only tested on `@utils.transition`, never on target-backed actions. Added "Action I/O Metadata Properties" section with complete property tables. Clarified reserved field names (reserved as variable names, valid as I/O metadata properties). Updated actions-reference.md (label property, Input Properties table, Output Properties expansion). Updated known-issues.md Issue 6 (compiles on target-backed actions). Updated VALIDATION.md Tier 4 + findings. Updated syntax-reference.md with Action Metadata Properties subsection. 24 validation agents total. | | 2.0.0 | 2026-02-16 | **Production learnings audit**: Fixed `<>` operator references in 3 files. Fixed config block field names. Removed false `label:` claims. Added 3 new known issues (I/O schemas, connections block, EinsteinAgentApiChannel). Added Two-Level Action System section. | | 1.9.0 | 2026-02-14 | **TDD v1.9.0 (16/16 PASS)**: 3 new agents. TDD disproved `else:` + nested `if`. `<>` not valid. Multiple `available when` IS valid. | | 1.8.0 | 2026-02-12 | **Gap analysis audit**: Added official-sources.md, known-issues.md, migration-guide.md. Verification Protocol + Self-Improvement. | | 1.7.0 | 2026-02-09 | **CRITICAL FIX**: `apex://` works directly, GenAiFunction NOT needed for Agent Script. Rewrote action sections. | | 1.6.0 | 2026-02-07 | Content migration from former sf-ai-agentforce-legacy. Created actions-reference.md (602 lines). | | 1.5.0 | 2026-02-06 | Action patterns & prompt template docs (from @kunello PR #20). | | 1.3.0 | 2026-01-20 | Lifecycle hooks validated. Features NOT Valid section (corrected in v2.2.0). | | 1.2.0 | 2026-01-20 | Gap analysis vs agent-script-recipes. Expanded Action Target Protocols. | | 1.1.0 | 2026-01-20 | "Ultimate Guide" tribal knowledge integration. | | 1.0.x | 2026-01 | Initial release through progressive testing validation. |