sf-lwc-agent-script-viewer

A reference implementation for ISV partners to deliver agent configurations to customers using Agent Script and Lightning Web Components.

Why This Exists

With the retirement of new agent creation via the legacy Agentforce builder in mid-July 2026, ISV partners need a new way to deliver pre-built agent configurations to their customers. This repository provides that path.

The pattern: Instead of packaging agent templates as installable metadata, partners deliver templates as Agent Script content, displayed through a Lightning Web Component on a post-install setup page. Customers review the agent templates, copy the contents, and create a new Agent from script.

This approach:

• Fits existing partner workflows — Setup page LWCs are a well-established pattern for ISV packages
• Eliminates template overhead — No complex metadata versioning, install/upgrade issues, or atypical packaging steps
• Gives customers transparency — Admins can inspect the full agent configuration before creating it
• Simplifies upgrades — Updating an agent is comparing text, not navigating pages of settings

What's in This Repository

Directory	What It Is	Who It's For
force-app/	The core viewer LWC + parser bundle	Ship this — copy and include it in your managed package
examples/	Working demo with tile gallery, expand/collapse, "Copy Agent" button	Learn from this — reference for building your setup page
docs/	Integration guide and API reference	Read this — how to wire the component into your app

The Core Component (force-app/)

A single LWC (agentscriptViewer) that takes raw Agent Script content and renders it with syntax highlighting — line numbers, keyword coloring, word wrap, and copy-to-clipboard. It exposes an actions slot so you can inject your own buttons (like "Create Agent") into the toolbar.

The Example (examples/)

A complete post-install configuration page implementation showing multiple agent templates in a responsive tile grid. Each tile expands to show the full agent script with a prominent "Create Agent" button. This is the pattern shown in the demo GIF — partners can use it as a starting point or build their own UI.

Prerequisites

• Salesforce CLI (sf)
• Node.js v24 or later
• Git
• A Salesforce org (scratch org or sandbox) for deployment

Getting Started

1. Fork & Clone the repository (with submodules)

The parser source lives in a git submodule. You must include it when cloning so the build step can compile it into the Static Resource that powers syntax highlighting.

Option A — Clone everything in one step:

git clone --recurse-submodules git@github.com:<your-org>/sf-lwc-agent-script-viewer.git
cd sf-lwc-agent-script-viewer

Option B — If you already cloned without --recurse-submodules:

cd sf-lwc-agent-script-viewer
git submodule update --init --recursive

What is a git submodule? A submodule is a pointer to a specific commit in another Git repository. The vendor/agentscript directory contains the full source of the salesforce/agentscript repo, pinned at a known-good commit. This ensures everyone building the project uses the exact same parser version, without publishing it to npm.

2. Install dependencies

npm install

3. Deploy to a Salesforce org

The parser bundle (agentscriptParser.js) is pre-built and included in the repository. No build step is required — you can deploy immediately.

# Deploy only the core component
sf project deploy start -d force-app --target-org <your-org-alias>

# Deploy everything including the example setup page
sf project deploy start --target-org <your-org-alias>

Note: If you need to rebuild the parser bundle (e.g., after updating the submodule to a newer parser version), see Updating the parser to a newer version.

Using the Component

For component API, usage examples, and integration patterns, see [docs/INTEGRATION_GUIDE.md](docs/INTEGRATION_GUIDE.md).

Project Structure

sf-lwc-agent-script-viewer/
├── force-app/                        ← DEPLOYABLE PACKAGE (what you ship)
│   └── main/default/
│       ├── lwc/agentscriptViewer/        # The core LWC component
│       │   ├── agentscriptViewer.js
│       │   ├── agentscriptViewer.html
│       │   ├── agentscriptViewer.css
│       │   ├── tokenMap.js
│       │   └── agentscriptViewer.js-meta.xml
│       └── staticresources/
│           ├── agentscriptParser.js          # Pre-built parser (do not edit)
│           └── agentscriptParser.resource-meta.xml
│
├── examples/                         ← REFERENCE IMPLEMENTATION (learning aid)
│   └── main/default/
│       ├── lwc/agentScriptWrapper/       # Multi-agent gallery demo
│       ├── flexipages/                   # Example app pages
│       └── tabs/                         # Example custom tabs
│
├── docs/                             ← ISV DOCUMENTATION
│   ├── INTEGRATION_GUIDE.md              # How to integrate the component
│   └── API_REFERENCE.md                  # Full API surface documentation
│
├── scripts/
│   ├── bundle-parser.mjs           # esbuild script to compile the parser
│   ├── parser-entry.js             # Entry point for tree-shaking
│   └── test-bundle.mjs             # Smoke test for the bundle
├── vendor/
│   └── agentscript/                # Git submodule (parser source for highlighting)
├── package.json
└── sfdx-project.json

Key Agent Parser Files

File	Role
lwc/agentscriptViewer/tokenMap.js	Maps parser token names (e.g., keyword.block) to CSS classes (e.g., .token-keyword-block) for color rendering
staticresources/agentscriptParser.js	Compiled output — the runtime artifact loaded by the LWC to tokenize and highlight content
vendor/agentscript/	Parser source code (git submodule) — contains the grammar rules that identify tokens in .agent files for syntax highlighting
scripts/bundle-parser.mjs	Build script — compiles the parser TypeScript into a deployable JavaScript bundle using esbuild
scripts/parser-entry.js	Build entry point — imports only parseAndHighlight, tree-shaking everything else (LSP, diagnostics, etc.)

npm Scripts

Script	Description
npm run build	Rebuild parser bundle (only needed after submodule update)
npm run build:parser	(same as build)
npm run test:bundle	Smoke test the compiled parser bundle
npm test	Run LWC Jest unit tests
npm run test:all	Run bundle smoke test + Jest unit tests
npm run lint	Run ESLint on LWC/Aura JavaScript
npm run verify	Full verification: build, all tests, and lint (used by CI)
npm run prettier	Format all source files

How Syntax Highlighting Works

The viewer needs to understand AgentScript grammar — keywords like system:, config:, subagent, variable references like @actions.Foo, and more — to color-code them meaningfully. This is handled by the AgentScript parser, included as a git submodule at vendor/agentscript/.

The parser is not published to npm. By pinning it as a submodule, we guarantee a reproducible build tied to a specific version, and partners can audit exactly which code is running in their package. The parser TypeScript is pre-compiled into a single ~43 KB JavaScript file shipped as a Salesforce Static Resource (agentscriptParser.js). At runtime, the LWC loads that file and calls parseAndHighlight() to produce the color-coded output.

┌───────────────────────────────────────────────────────────────┐
│  vendor/agentscript/         (git submodule — parser source)  │
│       ↓  npm run build                                        │
│  staticresources/agentscriptParser.js   (compiled bundle)     │
│       ↓  loadScript() at runtime                              │
│  agentscriptViewer LWC      (renders highlighted tokens)      │
└───────────────────────────────────────────────────────────────┘

For details on updating the parser, pinning versions, or troubleshooting the submodule, see Working with the Git Submodule below.

Contributing & CI

If you're making changes to this repository (updating agent templates, modifying the viewer component, or upgrading the parser), a GitHub Actions workflow (.github/workflows/ci.yml) validates every push to main and every pull request.

What CI checks

Step	What it validates
Submodule checkout	Parser source is correctly pinned and accessible
npm ci	Dependencies install cleanly with no drift from lockfile
npm run build	Parser bundle compiles without errors
npm run test:bundle	Compiled parser produces correct syntax tokens
npm run test:unit	LWC component behavior (rendering, interactions, edge cases)
npm run lint	Code style and LWC best practices

The pipeline runs against Node.js 18 and 20.

Running checks locally before pushing

npm run verify

This runs build → test:all → lint in sequence — the same checks CI performs. Run this before opening a PR to catch issues early.

Working with the Git Submodule

The vendor/agentscript/ submodule is the source code for the syntax highlighting engine. Without it, the viewer renders plain monochrome text. The parser understands AgentScript grammar and produces token classifications (keyword, string, variable, comment, etc.) that the LWC maps to colors. When the AgentScript language evolves — new keywords, new block types, new syntax — updating the submodule brings those changes into the viewer's highlighting.

What is happening under the hood

The vendor/agentscript directory is not a regular folder — it is a git submodule. Git stores only a reference (a commit SHA) in the parent repository. When you check out the project, Git uses that SHA to fetch the exact version of the parser source.

Key points:

• The submodule has its own .git history, independent of this project's history.
• git status in the parent repo will show vendor/agentscript as "modified" if the submodule points to a different commit than what is recorded.
• Changes inside vendor/agentscript do not automatically get committed to the parent repo. You must explicitly update the pointer (see below).
• Updating the submodule to a newer commit gives you new syntax rules, bug fixes, or support for new AgentScript language features.

Checking which parser version you are using

cd vendor/agentscript
git log --oneline -1

This shows the pinned commit. You can also see it from the parent repo:

git submodule status

Output looks like:

 4670b96f... vendor/agentscript (heads/main)

Updating the parser to a newer version

When the upstream salesforce/agentscript repo has changes you want to pick up:

# Step 1: Enter the submodule and pull the latest changes
cd vendor/agentscript
git fetch origin
git checkout main
git pull origin main
cd ../..

# Step 2: Rebuild the parser bundle
npm run build

# Step 3: Verify the new bundle works
npm run test:bundle

# Step 4: Stage both the submodule pointer and the rebuilt bundle
git add vendor/agentscript
git add force-app/main/default/staticresources/agentscriptParser.js
git commit -m "chore: update agentscript parser to $(cd vendor/agentscript && git rev-parse --short HEAD)"

What did that do?

• Step 1 moves the submodule to the latest commit on main.
• Step 2 recompiles the parser from the new source.
• Step 3 confirms the bundle still produces correct syntax highlighting.
• Step 4 records the new submodule commit SHA and the rebuilt static resource in a single commit, keeping them in sync.

Pinning to a specific commit or tag

If you need a specific version rather than the latest:

cd vendor/agentscript
git fetch origin
git checkout <commit-sha-or-tag>
cd ../..
npm run build
npm run test:bundle
git add vendor/agentscript force-app/main/default/staticresources/agentscriptParser.js
git commit -m "chore: pin agentscript parser to <commit-sha-or-tag>"

Common submodule issues

Problem	Solution
vendor/agentscript is an empty directory	Run git submodule update --init --recursive
fatal: not a git repository inside vendor/agentscript	Run git submodule update --init from the project root
git status shows vendor/agentscript (modified content)	Someone made local changes inside the submodule. If unintentional, run cd vendor/agentscript && git checkout . to reset
git status shows vendor/agentscript (new commits)	The submodule was updated but not committed. Run git add vendor/agentscript && git commit to record it, or git submodule update to revert to the previously pinned commit
CI build fails with "submodule not found"	Ensure your CI pipeline uses git clone --recurse-submodules or runs git submodule update --init --recursive after cloning

License

See LICENSE for details.

The AgentScript parser source (vendor/agentscript) is licensed under Apache-2.0 by Salesforce, Inc.