@sf-explorer/agentforce-service 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# @sf-explorer/agentforce-service
+
+Express server for Agentforce agent APIs. Exposes sendMessage, compile, get agent, and update agent endpoints. Initializes from `sf force:org:display --json`. Serves a bundled React UI when built.
+
+## Getting Started
+
+### Recommended: Run with npx
+
+No install required. From your Salesforce project directory:
+
+```bash
+npx @sf-explorer/agentforce-service
+npx @sf-explorer/agentforce-service /path/to/sf-project
+npx @sf-explorer/agentforce-service . --org my-org --port 3847
+```
+
+Then open http://localhost:3847 for the UI.
+
+### From source (development)
+
+**From the repo root:**
+
+```bash
+npm install
+npm run build
+npm start -- example
+```
+
+**From the server folder:**
+
+```bash
+cd server
+npm install
+npm run build
+npm start -- ../example
+```
+
+Ensure you have an authenticated Salesforce org (`sf org login web` and `sf config set target-org <alias>`).
+
+## Development (from repo)
+
+```bash
+# Build (client + server)
+npm run build
+
+# Start server
+npm start
+npm start -- ../example
+npm start -- ../example --org my-org --port 3847
+```
+
+The build outputs the client to `dist/client` and compiles TypeScript to `dist/`. The UI is served at the root URL when the server runs.
+
+### Install (optional)
+
+For a global install: `npm install -g @sf-explorer/agentforce-service`, then run `agentforce-service [projectDir] [--org alias] [--port 3847]`.
+
+## APIs
+
+### Session flow (order matters)
+
+1. **POST /api/startSession** → get `sessionId`
+2. **POST /api/sendmessage** → chat (repeat as needed); response includes `messages[].planId`
+3. **POST /api/trace** → (optional) get plan trace for a `planId` from sendmessage
+4. **POST /api/endSession** → end session when done
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/startSession` | Start agent preview (agentBundleName or apiNameOrId) |
+| POST | `/api/sendmessage` | Send message via agent.preview.send() |
+| POST | `/api/trace` | Get plan trace for a planId (from sendmessage response) |
+| POST | `/api/endSession` | End preview session |
+| POST | `/api/compile` | Compile AgentScript via ScriptAgent.compile() |
+| GET | `/api/agents` | List agents (local, remote, or all previewable) |
+| GET | `/api/agent/:developerName` | Retrieve agentscript metadata from Metadata API |
+| PUT | `/api/agent/:developerName` | Deploy an agentscript package to the org |
+| GET | `/api/tests` | List test definitions (local JSON files) |
+| GET | `/api/tests/:filename` | Retrieve test content by filename |
+| POST | `/api/tests/run` | Run test (Salesforce AI Evaluation or local JSON) |
+| GET | `/api/tests/runs/:runId` | Retrieve test run status or results |
+
+### startSession
+
+Uses `@salesforce/agents` Agent.preview.start(). Pass either `agentBundleName` (script agent) or `apiNameOrId` (production agent). For script agents, optional `useMock` (default `true`) controls simulated vs live mode.
+
+```json
+POST /api/startSession
+{ "agentBundleName": "AgentScriptDemo" }
+{ "agentBundleName": "AgentScriptDemo", "useMock": false }
+// or
+{ "apiNameOrId": "BotIdOrApiName" }
+```
+
+### sendmessage
+
+Uses `@salesforce/agents` agent.preview.send().
+
+```json
+POST /api/sendmessage
+{ "sessionId": "...", "message": "Hello" }
+```
+
+### trace
+
+Uses `@salesforce/agents` agent.getTrace(planId). planId comes from sendmessage response `messages[].planId`. Requires an active session.
+
+```json
+POST /api/trace
+{ "sessionId": "...", "planId": "..." }
+```
+
+### endSession
+
+Uses `@salesforce/agents` agent.preview.end().
+
+```json
+POST /api/endSession
+{ "sessionId": "..." }
+```
+
+### compile
+
+```json
+POST /api/compile
+{ "agentBundleName": "AgentScriptDemo" }
+```
+
+### retrieve agents
+
+```
+GET /api/agents?source=all   # all previewable (default)
+GET /api/agents?source=local # agent bundles in project
+GET /api/agents?source=remote # published bots in org
+```
+
+### get agent
+
+```
+GET /api/agent/AgentScriptDemo
+```
+
+### update agent
+
+```json
+PUT /api/agent/AgentScriptDemo
+{ "sourcePath": "/optional/path/to/bundle" }
+```
+
+If `sourcePath` is omitted, uses `{projectDir}/force-app/main/default/aiAuthoringBundles/{developerName}`.
+
+### tests
+
+List, retrieve, and run agent tests.
+
+```
+GET /api/tests?dir=all        # List test files (root + example/)
+GET /api/tests/energy-test-case.json   # Retrieve test content
+POST /api/tests/run           # Run test (see body options below)
+GET /api/tests/runs/:runId    # Get run status; ?results=true for full results
+```
+
+**Run options:**
+
+- **Salesforce AI Evaluation** – `{ "aiEvaluationDefinitionName": "MyTestDef" }` → returns `{ runId }`; poll `/api/tests/runs/:runId` for status/results.
+- **Local run** – `{ "testFile": "energy-test-case.json", "agentBundleName": "MyAgent" }` → executes test cases via preview session; returns `{ total, passed, failed, results }`.
+
+## Prerequisites
+
+- Node.js >= 18
+- Salesforce CLI (`sf`) installed and authenticated
+- A Salesforce project with `aiAuthoringBundles` (for compile/agent APIs)

package/bin/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for @sf-explorer/agentforce-service
+ * Usage: npx @sf-explorer/agentforce-service [projectDir] [--org alias] [--port 3847]
+ *
+ * Starts the server in the given folder (or cwd). Initializes from sf force:org:display.
+ */
+
+import { resolve } from "path";
+import { createServer } from "../dist/index.js";
+
+const args = process.argv.slice(2);
+let projectDir = process.cwd();
+let orgAlias;
+let port = 3847;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--org" && args[i + 1]) {
+    orgAlias = args[++i];
+  } else if (args[i] === "--port" && args[i + 1]) {
+    port = parseInt(args[++i], 10) || 3847;
+  } else if (!args[i].startsWith("-")) {
+    projectDir = resolve(process.cwd(), args[i]);
+  }
+}
+
+createServer({ projectDir, orgAlias, port }).catch((err) => {
+  console.error("Org connection failed. Server will not start.");
+  console.error("");
+  console.error(err.message);
+  console.error("");
+  console.error(
+    "To fix: authenticate an org and set it as default, e.g.:"
+  );
+  console.error("  sf org login web");
+  console.error("  sf config set target-org <alias>");
+  console.error("");
+  console.error(
+    "Or pass an org alias: npx @sf-explorer/agentforce-service . --org <alias>"
+  );
+  process.exit(1);
+});

package/dist/client/assets/index-4BXb_5Lv.css

@@ -0,0 +1 @@
+:root{font-family:JetBrains Mono,SF Mono,Fira Code,monospace;line-height:1.5;font-weight:400;color:#e2e8f0;background:#0f172a}*{box-sizing:border-box}body{margin:0;min-height:100vh}#root{max-width:1200px;margin:0 auto;padding:1.5rem}h1,h2,h3{font-weight:600;margin:0 0 .75rem}h1{font-size:1.5rem;color:#38bdf8}h2{font-size:1.1rem;color:#94a3b8}h3{font-size:.95rem}button{font-family:inherit;font-size:.85rem;padding:.5rem 1rem;border-radius:6px;border:1px solid #334155;background:#1e293b;color:#e2e8f0;cursor:pointer;transition:background .15s,border-color .15s}button:hover{background:#334155;border-color:#475569}button:disabled{opacity:.5;cursor:not-allowed}input,textarea,select{font-family:inherit;font-size:.9rem;padding:.5rem .75rem;border-radius:6px;border:1px solid #334155;background:#1e293b;color:#e2e8f0;width:100%}input:focus,textarea:focus{outline:none;border-color:#38bdf8}label{display:block;font-size:.8rem;color:#94a3b8;margin-bottom:.25rem}.card{background:#1e293b;border:1px solid #334155;border-radius:8px;padding:1rem;margin-bottom:1rem}.response{font-size:.8rem;background:#0f172a;border:1px solid #334155;border-radius:6px;padding:.75rem;margin-top:.75rem;max-height:200px;overflow:auto;white-space:pre-wrap;word-break:break-all}.response.error{border-color:#f87171;color:#fca5a5}.response.success{border-color:#34d399}.agent-script-editor{width:100%;min-height:320px;font-size:.85rem;line-height:1.5;resize:vertical;margin-top:.25rem}.form-row{display:flex;gap:.75rem;align-items:flex-end;margin-bottom:.75rem}.form-row>*{flex:1}.form-row button{flex:0 0 auto}.chat-message{margin:.5rem 0;padding:.5rem;border-radius:6px;font-size:.9rem}.chat-message.user{background:#334155;margin-left:1rem}.chat-message.agent{background:#1e3a5f;margin-right:1rem}.chat-thread{margin-bottom:1rem;display:flex;flex-direction:column;gap:.75rem}.chat-message{display:flex;flex-direction:column;gap:.5rem}.trace-toggle{margin-top:.5rem}.trace-btn{font-size:.8rem;padding:.25rem .5rem;background:transparent;border:1px solid #475569;color:#94a3b8}.trace-btn:hover{color:#38bdf8;border-color:#38bdf8}.trace-panel{margin-top:.5rem;padding:.75rem;background:#0f172a;border:1px solid #334155;border-radius:6px;font-size:.8rem;max-height:400px;overflow-y:auto}.trace-meta{display:flex;flex-wrap:wrap;gap:1rem;margin-bottom:.75rem;padding-bottom:.5rem;border-bottom:1px solid #334155;color:#94a3b8}.trace-meta span{font-size:.85rem}.trace-steps{display:flex;flex-direction:column;gap:.5rem}.trace-step{padding:.5rem;border-radius:4px;border-left:3px solid #334155;background:#1e293b}.trace-step.user-input{border-left-color:#38bdf8}.trace-step.llm{border-left-color:#a78bfa}.trace-step.topic{border-left-color:#34d399}.trace-step.reasoning{border-left-color:#fbbf24}.trace-step.function{border-left-color:#f472b6}.trace-step.planner{border-left-color:#34d399}.trace-step.event{border-left-color:#94a3b8}.trace-step.event.error{border-left-color:#f87171}.trace-step-type{display:inline-block;font-weight:600;color:#94a3b8;margin-right:.5rem;min-width:4.5rem}.trace-step-content{color:#e2e8f0}.trace-details{margin-top:.5rem;font-size:.75rem}.trace-details summary{cursor:pointer;color:#94a3b8}.trace-details pre{margin:.25rem 0 0;padding:.5rem;background:#0f172a;border-radius:4px;overflow-x:auto;white-space:pre-wrap;word-break:break-word}.trace-empty{color:#94a3b8;margin:0;font-style:italic}.status-badge{display:inline-block;padding:.2rem .5rem;border-radius:4px;font-size:.75rem}.status-badge.connected{background:#065f46;color:#6ee7b7}.status-badge.disconnected{background:#7f1d1d;color:#fca5a5}.tabs{display:flex;gap:.25rem;margin-bottom:1.5rem;border-bottom:1px solid #334155}.tab{padding:.5rem 1rem;background:transparent;border:none;border-bottom:2px solid transparent;margin-bottom:-1px;color:#94a3b8;cursor:pointer}.tab:hover{color:#e2e8f0}.tab.active{color:#38bdf8;border-bottom-color:#38bdf8}.api-docs-section{min-height:600px}.api-docs-iframe{width:100%;min-height:70vh;border:1px solid #334155;border-radius:6px;background:#fff}.session-chat .chat-thread{max-width:720px}.session-chat .form-row input{max-width:400px}.test-cases-list{display:flex;flex-direction:column;gap:1rem}.test-case-card{padding:1rem;background:#0f172a;border:1px solid #334155;border-radius:8px;display:flex;flex-direction:column;gap:.5rem}.test-case-header{display:flex;align-items:center;gap:.5rem;flex-wrap:wrap}.test-case-index{font-weight:600;color:#38bdf8;min-width:2rem}.test-case-id{font-size:.8rem;color:#64748b;background:#1e293b;padding:.15rem .4rem;border-radius:4px}.test-case-name{font-weight:500;color:#e2e8f0}.test-case-desc{font-size:.85rem;color:#94a3b8;margin:0;line-height:1.4}.test-case-messages{display:flex;flex-direction:column;gap:.35rem}.test-case-label{font-size:.75rem;color:#64748b;text-transform:uppercase;letter-spacing:.05em}.test-case-msg{font-size:.9rem;padding:.4rem .6rem;border-radius:4px;border-left:3px solid #334155}.test-case-msg.user{background:#1e293b;border-left-color:#38bdf8}.test-case-expected{font-size:.85rem;color:#a78bfa;padding:.4rem 0}.test-case-meta{font-size:.8rem;color:#64748b}.test-case-run-btn{align-self:flex-start;margin-top:.25rem;font-size:.8rem;padding:.35rem .75rem}