@sf-explorer/agentforce-service 1.0.0

package/dist/routes/agents.js

@@ -0,0 +1,181 @@
+import { file, directory } from "@polycuber/script.cli";
+import { join } from "node:path";
+import { Agent, ScriptAgent } from "@salesforce/agents";
+import { SfProject } from "@salesforce/core";
+import { initializeContext } from "./context.js";
+export function registerAgentsRoutes(router, context) {
+    const bundlesDir = join(context.projectDir, "force-app", "main", "default", "aiAuthoringBundles");
+    async function ensureInitialized() {
+        if (!context.orgInfo) {
+            await initializeContext(context);
+        }
+    }
+    /**
+     * POST /compile
+     * 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
+     * Query: ?source=local|remote|all (default: all)
+     */
+    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",
+            });
+        }
+    });
+    /**
+     * GET /agent/: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
+     * Body: { developerName, agentContent, bundleMetaContent? }
+     */
+    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
+     * Body: { agentContent, bundleMetaContent? }
+     */
+    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",
+            });
+        }
+    });
+}

package/dist/routes/context.d.ts

@@ -0,0 +1,15 @@
+import type { AgentInstance } from "@salesforce/agents";
+import type { Connection as JSForceConnection } from "jsforce";
+import type { Connection as SfConnection } from "@salesforce/core";
+import { type OrgInfo } from "../org.js";
+/** Session ID -> agent instance (for preview sendMessage, trace, endSession) */
+export declare const sessionAgents: Map<string, AgentInstance>;
+export interface ServerContext {
+    projectDir: string;
+    orgAlias?: string;
+    orgInfo?: OrgInfo;
+    jsforceConn?: JSForceConnection;
+    sfConn?: SfConnection;
+}
+/** Initialize org connection (jsforce + @salesforce/core). Call at server startup. */
+export declare function initializeContext(context: ServerContext): Promise<void>;

package/dist/routes/context.js

@@ -0,0 +1,11 @@
+import { getOrgInfoFromCli, createJsforceConnection, createSfConnection, } from "../org.js";
+/** Session ID -> agent instance (for preview sendMessage, trace, endSession) */
+export 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);
+}

package/dist/routes/index.d.ts

@@ -0,0 +1,5 @@
+import { Router } from "express";
+import type { ServerContext } from "./context.js";
+export type { ServerContext } from "./context.js";
+export { initializeContext } from "./context.js";
+export declare function createRoutes(context: ServerContext): Router;

package/dist/routes/index.js

@@ -0,0 +1,13 @@
+import { Router } from "express";
+import { registerSessionRoutes } from "./session.js";
+import { registerAgentsRoutes } from "./agents.js";
+import { registerTestsRoutes } from "./tests.js";
+export { initializeContext } from "./context.js";
+export function createRoutes(context) {
+    const router = Router();
+    // All routes on same router - avoids sub-router mounting issues
+    registerSessionRoutes(router, context);
+    registerAgentsRoutes(router, context);
+    registerTestsRoutes(router, context);
+    return router;
+}

package/dist/routes/session.d.ts

@@ -0,0 +1,3 @@
+import type { Router } from "express";
+import type { ServerContext } from "./context.js";
+export declare function registerSessionRoutes(router: Router, context: ServerContext): void;

package/dist/routes/session.js

@@ -0,0 +1,195 @@
+import { Agent } from "@salesforce/agents";
+import { SfProject } from "@salesforce/core";
+import { initializeContext } from "./context.js";
+import { sessionAgents } from "./context.js";
+/** Normalize API response to PlannerResponse. Handles AgentTraceResponse format. */
+function normalizeTrace(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    // API may return { actions: [{ returnValue: { planId, sessionId, intent, topic, plan } }] }
+    const actions = obj.actions;
+    if (Array.isArray(actions) && actions.length > 0) {
+        const first = actions[0];
+        const rv = first?.returnValue;
+        if (rv && typeof rv.planId === "string") {
+            return {
+                type: "PlanSuccessResponse",
+                planId: rv.planId,
+                sessionId: rv.sessionId ?? "",
+                intent: rv.intent ?? "",
+                topic: rv.topic ?? "",
+                plan: Array.isArray(rv.plan) ? rv.plan : [],
+            };
+        }
+    }
+    // Already PlannerResponse format
+    if (typeof obj.planId === "string" && Array.isArray(obj.plan)) {
+        return obj;
+    }
+    return null;
+}
+export function registerSessionRoutes(router, context) {
+    async function ensureInitialized() {
+        if (!context.orgInfo) {
+            await initializeContext(context);
+        }
+    }
+    /**
+     * POST /startSession
+     * Body: { agentBundleName } for script agent OR { apiNameOrId } for production agent
+     * Optional: { useMock } - for script agents only. true = simulated (default), false = live Apex/flows.
+     */
+    router.post("/startSession", async (req, res) => {
+        try {
+            await ensureInitialized();
+            const agentBundleName = req.body.agentBundleName ?? req.body.aabName;
+            const apiNameOrId = req.body.apiNameOrId;
+            const useMock = req.body.useMock !== false; // default true (simulated)
+            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 mockMode = agentBundleName ? (useMock ? "Mock" : "Live Test") : undefined;
+            const startResponse = await agent.preview.start(mockMode);
+            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
+     * 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 }
+     */
+    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;
+            }
+            let rawTrace;
+            try {
+                rawTrace = await agent.getTrace(planId);
+            }
+            catch (apiErr) {
+                console.warn(`[trace] getTrace API failed for planId=${planId}:`, apiErr);
+                rawTrace = undefined;
+            }
+            let trace = null;
+            if (rawTrace !== undefined && rawTrace !== null) {
+                trace = normalizeTrace(rawTrace);
+            }
+            // Fallback: read from disk (script agents write traces during sendMessage)
+            if (!trace && agent.preview.getAllTraces) {
+                try {
+                    const allTraces = await agent.preview.getAllTraces();
+                    for (const t of allTraces) {
+                        const normalized = normalizeTrace(t) ?? t;
+                        if (normalized.planId === planId) {
+                            trace = normalized;
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    // getAllTraces may throw if historyDir doesn't exist
+                }
+            }
+            if (!trace) {
+                console.warn(`[trace] No trace for planId=${planId} (session=${sessionId}). Trace is only available for script agents (agentBundleName), not published agents (apiNameOrId).`);
+            }
+            res.json(trace);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Get trace failed",
+            });
+        }
+    });
+    /**
+     * POST /endSession
+     * 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",
+            });
+        }
+    });
+}

package/dist/routes/tests.d.ts

@@ -0,0 +1,3 @@
+import type { Router } from "express";
+import type { ServerContext } from "./context.js";
+export declare function registerTestsRoutes(router: Router, context: ServerContext): void;

package/dist/routes/tests.js

@@ -0,0 +1,211 @@
+import { file, directory } from "@polycuber/script.cli";
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { Agent } from "@salesforce/agents";
+import { SfProject } from "@salesforce/core";
+import { initializeContext } from "./context.js";
+import { sessionAgents } from "./context.js";
+const API_VERSION = "v63.0";
+export function registerTestsRoutes(router, context) {
+    async function ensureInitialized() {
+        if (!context.orgInfo) {
+            await initializeContext(context);
+        }
+    }
+    /**
+     * GET /tests/runs/:runId
+     * 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/${API_VERSION}/einstein/ai-evaluations/runs/${runId}/results`
+                : `/services/data/${API_VERSION}/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
+     * Query: ?dir=root|example|all (default: all)
+     */
+    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
+     */
+    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
+     * Body: { aiEvaluationDefinitionName } or { testFile, agentBundleName }
+     */
+    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/${API_VERSION}/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",
+            });
+        }
+    });
+}

package/dist/routes.d.ts

@@ -0,0 +1,14 @@
+import { Router } from "express";
+import type { Connection as JSForceConnection } from "jsforce";
+import type { Connection as SfConnection } from "@salesforce/core";
+import { type OrgInfo } from "./org.js";
+export interface ServerContext {
+    projectDir: string;
+    orgAlias?: string;
+    orgInfo?: OrgInfo;
+    jsforceConn?: JSForceConnection;
+    sfConn?: SfConnection;
+}
+/** Initialize org connection (jsforce + @salesforce/core). Call at server startup. */
+export declare function initializeContext(context: ServerContext): Promise<void>;
+export declare function createRoutes(context: ServerContext): Router;