@sf-explorer/agentforce-service 1.0.0

package/dist/routes.js

@@ -0,0 +1,534 @@
+import { Router } from "express";
+import { file, directory } from "@polycuber/script.cli";
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { Agent, ScriptAgent } from "@salesforce/agents";
+import { SfProject } from "@salesforce/core";
+import { getOrgInfoFromCli, createJsforceConnection, createSfConnection, } from "./org.js";
+/** Session ID -> agent instance (for preview sendMessage) */
+const sessionAgents = new Map();
+/** Initialize org connection (jsforce + @salesforce/core). Call at server startup. */
+export async function initializeContext(context) {
+    if (context.orgInfo)
+        return;
+    context.orgInfo = getOrgInfoFromCli(context.orgAlias, context.projectDir);
+    context.jsforceConn = createJsforceConnection(context.orgInfo);
+    context.sfConn = await createSfConnection(context.orgInfo);
+}
+export function createRoutes(context) {
+    const router = Router();
+    async function ensureInitialized() {
+        if (!context.orgInfo) {
+            await initializeContext(context);
+        }
+    }
+    /**
+     * POST /startSession
+     * Start an agent preview session using @salesforce/agents
+     * Body: { agentBundleName } for script agent OR { apiNameOrId } for production agent
+     */
+    router.post("/startSession", async (req, res) => {
+        try {
+            await ensureInitialized();
+            const agentBundleName = req.body.agentBundleName ?? req.body.aabName;
+            const apiNameOrId = req.body.apiNameOrId;
+            if (!agentBundleName && !apiNameOrId) {
+                res.status(400).json({
+                    error: "Missing required field: agentBundleName (script agent) or apiNameOrId (production agent)",
+                });
+                return;
+            }
+            const project = await SfProject.resolve(context.projectDir);
+            const agent = agentBundleName
+                ? await Agent.init({
+                    connection: context.sfConn,
+                    project,
+                    aabName: agentBundleName,
+                })
+                : await Agent.init({
+                    connection: context.sfConn,
+                    project,
+                    apiNameOrId: apiNameOrId,
+                });
+            const startResponse = await agent.preview.start();
+            sessionAgents.set(startResponse.sessionId, agent);
+            res.json(startResponse);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Start session failed",
+            });
+        }
+    });
+    /**
+     * POST /sendmessage
+     * Send a message using @salesforce/agents agent.preview.send()
+     * Body: { sessionId, message }
+     */
+    router.post("/sendmessage", async (req, res) => {
+        try {
+            const { sessionId, message } = req.body;
+            if (!sessionId || !message) {
+                res.status(400).json({
+                    error: "Missing required fields: sessionId, message",
+                });
+                return;
+            }
+            const agent = sessionAgents.get(sessionId);
+            if (!agent) {
+                res.status(404).json({
+                    error: "Session not found. Call startSession first.",
+                });
+                return;
+            }
+            const sendResponse = await agent.preview.send(message);
+            res.json(sendResponse);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Send message failed",
+            });
+        }
+    });
+    /**
+     * POST /trace
+     * Get the plan trace for a given planId from an active session.
+     * Body: { sessionId, planId }
+     * planId comes from sendmessage response messages[].planId
+     */
+    router.post("/trace", async (req, res) => {
+        try {
+            const { sessionId, planId } = req.body;
+            if (!sessionId || !planId) {
+                res.status(400).json({
+                    error: "Missing required fields: sessionId, planId",
+                });
+                return;
+            }
+            const agent = sessionAgents.get(sessionId);
+            if (!agent) {
+                res.status(404).json({
+                    error: "Session not found. Call startSession first.",
+                });
+                return;
+            }
+            const trace = await agent.getTrace(planId);
+            res.json(trace ?? null);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Get trace failed",
+            });
+        }
+    });
+    /**
+     * POST /endSession
+     * End an agent preview session using @salesforce/agents
+     * Body: { sessionId }
+     */
+    router.post("/endSession", async (req, res) => {
+        try {
+            const { sessionId } = req.body;
+            if (!sessionId) {
+                res.status(400).json({ error: "Missing required field: sessionId" });
+                return;
+            }
+            const agent = sessionAgents.get(sessionId);
+            if (!agent) {
+                res.status(404).json({
+                    error: "Session not found. Call startSession first.",
+                });
+                return;
+            }
+            const endResponse = await agent.preview.end();
+            sessionAgents.delete(sessionId);
+            res.json(endResponse);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "End session failed",
+            });
+        }
+    });
+    /**
+     * POST /compile
+     * Compile an AgentScript from an aiAuthoringBundle
+     * Body: { agentBundleName }
+     */
+    router.post("/compile", async (req, res) => {
+        try {
+            await ensureInitialized();
+            const agentBundleName = req.body.agentBundleName ?? req.body.aabName;
+            if (!agentBundleName) {
+                res.status(400).json({ error: "Missing required field: agentBundleName" });
+                return;
+            }
+            const project = await SfProject.resolve(context.projectDir);
+            const scriptAgent = await Agent.init({
+                connection: context.sfConn,
+                project,
+                aabName: agentBundleName,
+            });
+            if (!(scriptAgent instanceof ScriptAgent)) {
+                res.status(400).json({
+                    error: "Agent is not a ScriptAgent (compile only supports script agents)",
+                });
+                return;
+            }
+            const result = await scriptAgent.compile();
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Compile failed",
+            });
+        }
+    });
+    /**
+     * GET /agents
+     * Retrieve list of agents. Query: ?source=local|remote|all (default: all)
+     * - local: Agent.list(project) - aabNames in project
+     * - remote: Agent.listRemote(connection) - bots in org
+     * - all: Agent.listPreviewable(connection, project) - combined
+     */
+    router.get("/agents", async (req, res) => {
+        try {
+            await ensureInitialized();
+            const source = req.query.source ?? "all";
+            const project = await SfProject.resolve(context.projectDir);
+            if (source === "local") {
+                const aabNames = await Agent.list(project);
+                res.json({ agents: aabNames, source: "local" });
+                return;
+            }
+            if (source === "remote") {
+                const bots = await Agent.listRemote(context.sfConn);
+                res.json({ agents: bots, source: "remote" });
+                return;
+            }
+            const previewable = await Agent.listPreviewable(context.sfConn, project);
+            res.json({ agents: previewable, source: "all" });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Retrieve agents failed",
+            });
+        }
+    });
+    const bundlesDir = join(context.projectDir, "force-app", "main", "default", "aiAuthoringBundles");
+    /**
+     * GET /agent/:developerName
+     * Read agent metadata (AiAuthoringBundle) directly from disk.
+     * Path: force-app/main/default/aiAuthoringBundles/{developerName}/
+     */
+    router.get("/agent/:developerName", (req, res) => {
+        try {
+            const { developerName } = req.params;
+            const bundlePath = join(bundlesDir, developerName);
+            const result = {};
+            const agentPath = join(bundlePath, `${developerName}.agent`);
+            const metaPath = join(bundlePath, `${developerName}.bundle-meta.xml`);
+            if (file.exists(agentPath)) {
+                const content = file.read.text(agentPath);
+                if (content)
+                    result[`aiAuthoringBundles/${developerName}/${developerName}.agent`] = content;
+            }
+            if (file.exists(metaPath)) {
+                const content = file.read.text(metaPath);
+                if (content)
+                    result[`aiAuthoringBundles/${developerName}/${developerName}.bundle-meta.xml`] = content;
+            }
+            if (Object.keys(result).length === 0) {
+                res.status(404).json({
+                    error: `Agent not found: ${developerName}`,
+                });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Get agent failed",
+            });
+        }
+    });
+    /**
+     * POST /agent
+     * Create a new agent by writing files to disk.
+     * Body: { developerName, agentContent, bundleMetaContent? }
+     * Path: force-app/main/default/aiAuthoringBundles/{developerName}/
+     */
+    router.post("/agent", (req, res) => {
+        try {
+            const { developerName, agentContent, bundleMetaContent } = req.body;
+            if (!developerName || !agentContent) {
+                res.status(400).json({
+                    error: "Missing required fields: developerName, agentContent",
+                });
+                return;
+            }
+            const bundlePath = join(bundlesDir, developerName);
+            if (directory.exists(bundlePath)) {
+                res.status(409).json({
+                    error: `Agent already exists: ${developerName}`,
+                });
+                return;
+            }
+            directory.make(bundlePath);
+            file.write.text(join(bundlePath, `${developerName}.agent`), agentContent);
+            if (bundleMetaContent) {
+                file.write.text(join(bundlePath, `${developerName}.bundle-meta.xml`), bundleMetaContent);
+            }
+            else {
+                const defaultMeta = `<?xml version="1.0" encoding="UTF-8"?>
+<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <bundleType>AGENT</bundleType>
+</AiAuthoringBundle>`;
+                file.write.text(join(bundlePath, `${developerName}.bundle-meta.xml`), defaultMeta);
+            }
+            res.status(201).json({ success: true, developerName });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Create agent failed",
+            });
+        }
+    });
+    /**
+     * PUT /agent/:developerName
+     * Update agent by writing files directly to disk.
+     * Body: { agentContent, bundleMetaContent? }
+     * Path: force-app/main/default/aiAuthoringBundles/{developerName}/
+     */
+    router.put("/agent/:developerName", (req, res) => {
+        try {
+            const { developerName } = req.params;
+            const { agentContent, bundleMetaContent } = req.body;
+            if (!agentContent) {
+                res.status(400).json({
+                    error: "Missing required field: agentContent",
+                });
+                return;
+            }
+            const bundlePath = join(bundlesDir, developerName);
+            if (!directory.exists(bundlePath)) {
+                res.status(404).json({
+                    error: `Agent not found: ${developerName}. Use POST /agent to create.`,
+                });
+                return;
+            }
+            file.write.text(join(bundlePath, `${developerName}.agent`), agentContent);
+            if (bundleMetaContent) {
+                file.write.text(join(bundlePath, `${developerName}.bundle-meta.xml`), bundleMetaContent);
+            }
+            res.json({ success: true, developerName });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Update agent failed",
+            });
+        }
+    });
+    const apiVersion = "v63.0";
+    /**
+     * GET /tests/runs/:runId
+     * Retrieve test run status. Query: ?results=true for full results.
+     * Must be registered before /tests/:filename so "runs" is not captured.
+     */
+    router.get("/tests/runs/:runId", async (req, res) => {
+        try {
+            await ensureInitialized();
+            const { runId } = req.params;
+            const includeResults = req.query.results === "true";
+            const path = includeResults
+                ? `/services/data/${apiVersion}/einstein/ai-evaluations/runs/${runId}/results`
+                : `/services/data/${apiVersion}/einstein/ai-evaluations/runs/${runId}`;
+            const result = await context.jsforceConn.request({
+                method: "GET",
+                url: path,
+            });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Retrieve test run failed",
+            });
+        }
+    });
+    /**
+     * GET /tests
+     * List available test definitions (local JSON files with "test" in name).
+     * Query: ?dir=root|example|all (default: all) - which dirs to scan.
+     */
+    router.get("/tests", (req, res) => {
+        try {
+            const dirFilter = req.query.dir ?? "all";
+            const tests = [];
+            const dirsToScan = dirFilter === "example"
+                ? [join(context.projectDir, "example")]
+                : dirFilter === "root"
+                    ? [context.projectDir]
+                    : [context.projectDir, join(context.projectDir, "example")];
+            for (const dir of dirsToScan) {
+                if (!directory.exists(dir))
+                    continue;
+                const entries = readdirSync(dir, { withFileTypes: true });
+                for (const e of entries) {
+                    if (e.isFile() && e.name.endsWith(".json") && /test/i.test(e.name)) {
+                        tests.push({
+                            name: e.name,
+                            path: join(dir, e.name),
+                        });
+                    }
+                }
+            }
+            res.json({ tests: tests.map((t) => ({ name: t.name, path: t.path })) });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "List tests failed",
+            });
+        }
+    });
+    /**
+     * GET /tests/:filename
+     * Retrieve test definition content by filename.
+     */
+    router.get("/tests/:filename", (req, res) => {
+        try {
+            const { filename } = req.params;
+            if (!filename || !/^[\w.-]+\.json$/i.test(filename)) {
+                res.status(400).json({ error: "Invalid filename" });
+                return;
+            }
+            const candidates = [
+                join(context.projectDir, filename),
+                join(context.projectDir, "example", filename),
+            ];
+            for (const p of candidates) {
+                if (file.exists(p)) {
+                    const content = file.read.text(p);
+                    const parsed = JSON.parse(content ?? "[]");
+                    return res.json(parsed);
+                }
+            }
+            res.status(404).json({ error: `Test not found: ${filename}` });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Retrieve test failed",
+            });
+        }
+    });
+    /**
+     * POST /tests/run
+     * Run a test. Body: { aiEvaluationDefinitionName } for Salesforce AI Evaluation,
+     * or { testFile, agentBundleName } for local run via preview session.
+     */
+    router.post("/tests/run", async (req, res) => {
+        try {
+            await ensureInitialized();
+            const { aiEvaluationDefinitionName, aiEvaluationDefinitionId, testFile, agentBundleName, } = req.body;
+            if (aiEvaluationDefinitionName || aiEvaluationDefinitionId) {
+                if (aiEvaluationDefinitionName && aiEvaluationDefinitionId) {
+                    res.status(400).json({
+                        error: "Provide exactly one: aiEvaluationDefinitionName or aiEvaluationDefinitionId",
+                    });
+                    return;
+                }
+                const body = aiEvaluationDefinitionName
+                    ? { aiEvaluationDefinitionName }
+                    : { aiEvaluationDefinitionId: aiEvaluationDefinitionId };
+                const result = (await context.jsforceConn.request({
+                    method: "POST",
+                    url: `/services/data/${apiVersion}/einstein/ai-evaluations/runs`,
+                    body: JSON.stringify(body),
+                }));
+                res.json({ runId: result.runId });
+                return;
+            }
+            if (testFile && agentBundleName) {
+                const candidates = [
+                    join(context.projectDir, testFile),
+                    join(context.projectDir, "example", testFile),
+                ];
+                let content;
+                for (const p of candidates) {
+                    if (file.exists(p)) {
+                        content = file.read.text(p);
+                        break;
+                    }
+                }
+                if (!content) {
+                    res.status(404).json({ error: `Test file not found: ${testFile}` });
+                    return;
+                }
+                const parsed = JSON.parse(content);
+                const cases = Array.isArray(parsed)
+                    ? parsed
+                    : parsed?.testSuite?.testCases ?? parsed?.testCases ?? [];
+                const flatCases = cases.flatMap((c) => {
+                    const obj = c;
+                    return Array.isArray(obj?.testCases) ? obj.testCases : [c];
+                });
+                const project = await SfProject.resolve(context.projectDir);
+                const agent = await Agent.init({
+                    connection: context.sfConn,
+                    project,
+                    aabName: agentBundleName,
+                });
+                const startRes = await agent.preview.start();
+                const sessionId = startRes.sessionId;
+                sessionAgents.set(sessionId, agent);
+                const results = [];
+                try {
+                    for (let i = 0; i < flatCases.length; i++) {
+                        const tc = flatCases[i];
+                        const utterance = tc["utterance"] ??
+                            tc.utterance ??
+                            tc.inputs?.utterance ??
+                            (Array.isArray(tc.interactions)
+                                ? tc.interactions
+                                    .map((a) => a.message)
+                                    .join(" ")
+                                : "");
+                        if (!utterance)
+                            continue;
+                        try {
+                            await agent.preview.send(utterance);
+                            results.push({ index: i + 1, utterance, passed: true });
+                        }
+                        catch (e) {
+                            results.push({
+                                index: i + 1,
+                                utterance,
+                                passed: false,
+                                error: e instanceof Error ? e.message : String(e),
+                            });
+                        }
+                    }
+                }
+                finally {
+                    await agent.preview.end();
+                    sessionAgents.delete(sessionId);
+                }
+                res.json({
+                    total: flatCases.length,
+                    passed: results.filter((r) => r.passed).length,
+                    failed: results.filter((r) => !r.passed).length,
+                    results,
+                });
+                return;
+            }
+            res.status(400).json({
+                error: "Provide aiEvaluationDefinitionName (or aiEvaluationDefinitionId) for SF run, or testFile+agentBundleName for local run",
+            });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Run test failed",
+            });
+        }
+    });
+    return router;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@sf-explorer/agentforce-service",
+  "version": "1.0.0",
+  "description": "Express server for Agentforce agent APIs - sendMessage, compile, get/update agent metadata",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentforce-service": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "npm run build:client || true && tsc",
+    "build:client": "cd ../client && npm run build",
+    "start": "node bin/cli.js",
+    "dev": "tsx src/index.ts",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "salesforce",
+    "agentforce",
+    "agents",
+    "express"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@polycuber/script.cli": "^1.0.5",
+    "@salesforce/agents": "^0.23.0",
+    "@salesforce/core": "^8.26.0",
+    "adm-zip": "^0.5.16",
+    "cors": "^2.8.6",
+    "express": "^4.21.0",
+    "jsforce": "^2.0.0-beta.22",
+    "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.0",
+    "@types/swagger-ui-express": "^4.1.8",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "prepare": "npm run build"
+}