@salesforce/magen-mcp-workflow 0.0.1

package/dist/tools/base/abstractWorkflowTool.js

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { AbstractTool } from './abstractTool.js';
+import { WORKFLOW_PROPERTY_NAMES, } from '../../common/metadata.js';
+/**
+ * Abstract base class for all workflow-participating tools.
+ *
+ * Workflow tools return guidance prompts that instruct the LLM to invoke the
+ * orchestrator tool next, along with the necessary workflow state data.
+ *
+ * The orchestrator tool itself extends AbstractTool directly, as it controls
+ * the workflow rather than participating in it.
+ */
+export class AbstractWorkflowTool extends AbstractTool {
+    orchestratorToolId;
+    constructor(server, toolMetadata, orchestratorToolId, // ID of the orchestrator managing this workflow
+    loggerComponentName, logger) {
+        super(server, toolMetadata, loggerComponentName, logger);
+        this.orchestratorToolId = orchestratorToolId;
+    }
+    /**
+     * Utility method for tools to add post-invocation instructions
+     * that guide the LLM back to the orchestrator for workflow continuation.
+     *
+     * This does NOT invoke the orchestrator - it creates guidance prompts that
+     * instruct the LLM to invoke the orchestrator tool next.
+     *
+     * @param prompt The main tool response prompt
+     * @param workflowStateData Workflow state data to round-trip back to orchestrator
+     * @param resultSchema The optional result schema to format the LLM's output.
+     *                     If not provided, uses the tool's default result schema.
+     * @returns Complete prompt with post-invocation instructions
+     */
+    finalizeWorkflowToolOutput(prompt, workflowStateData, resultSchema) {
+        let resultSchemaToUse = resultSchema ?? this.toolMetadata.resultSchema;
+        if (!(typeof resultSchemaToUse === 'string')) {
+            resultSchemaToUse = JSON.stringify(zodToJsonSchema(resultSchemaToUse));
+        }
+        // Create guidance instructions that tell the LLM to invoke the orchestrator next
+        const postInstructions = `
+
+# Post-Tool-Invocation Instructions
+
+## 1. Format the results from the execution of your task
+
+The output of your task should conform to the following JSON schema:
+
+\`\`\`json
+${resultSchemaToUse}
+\`\`\`
+
+A string representation of this JSON schema can also be found in the \`resultSchema\`
+field of this tool's output schema.
+
+## 2. Invoke the next tool to continue the workflow
+
+You MUST initiate the following actions to proceed with the in-progress workflow you are
+participating in.
+
+### 2.1. Invoke the \`${this.orchestratorToolId}\` tool
+
+Invoke the \`${this.orchestratorToolId}\` tool to continue the workflow.
+
+### 2.2 Provide input values to the tool
+
+Provide the following input values to the \`${this.orchestratorToolId}\` tool:
+
+- \`${WORKFLOW_PROPERTY_NAMES.userInput}\`: The structured results from the execution of your task, as specified in the first Post-Tool-Invocation step.
+- \`${WORKFLOW_PROPERTY_NAMES.workflowStateData}\`: ${JSON.stringify(workflowStateData)}
+
+This will continue the workflow orchestration process.
+`;
+        const promptForLLM = prompt + postInstructions;
+        const result = {
+            promptForLLM,
+            resultSchema: resultSchemaToUse,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result),
+                },
+            ],
+            structuredContent: result,
+        };
+    }
+}
+//# sourceMappingURL=abstractWorkflowTool.js.map

package/dist/tools/base/abstractWorkflowTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstractWorkflowTool.js","sourceRoot":"","sources":["../../../src/tools/base/abstractWorkflowTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAGL,uBAAuB,GAIxB,MAAM,0BAA0B,CAAC;AAGlC;;;;;;;;GAQG;AACH,MAAM,OAAgB,oBAMpB,SAAQ,YAAuB;IACZ,kBAAkB,CAAS;IAE9C,YACE,MAAiB,EACjB,YAAuB,EACvB,kBAA0B,EAAE,gDAAgD;IAC5E,mBAA4B,EAC5B,MAAe;QAEf,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,CAAC,CAAC;QACzD,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;OAYG;IACO,0BAA0B,CAClC,MAAc,EACd,iBAAoC,EACpC,YAAiD;QAEjD,IAAI,iBAAiB,GAAG,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC;QACvE,IAAI,CAAC,CAAC,OAAO,iBAAiB,KAAK,QAAQ,CAAC,EAAE,CAAC;YAC7C,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC,CAAC;QACzE,CAAC;QAED,iFAAiF;QACjF,MAAM,gBAAgB,GAAG;;;;;;;;;EAS3B,iBAAiB;;;;;;;;;;;wBAWK,IAAI,CAAC,kBAAkB;;eAEhC,IAAI,CAAC,kBAAkB;;;;8CAIQ,IAAI,CAAC,kBAAkB;;MAE/D,uBAAuB,CAAC,SAAS;MACjC,uBAAuB,CAAC,iBAAiB,OAAO,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC;;;CAGtF,CAAC;QAEE,MAAM,YAAY,GAAG,MAAM,GAAG,gBAAgB,CAAC;QAC/C,MAAM,MAAM,GAA0B;YACpC,YAAY;YACZ,YAAY,EAAE,iBAAiB;SAChC,CAAC;QACF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;iBAC7B;aACF;YACD,iBAAiB,EAAE,MAAM;SAC1B,CAAC;IACJ,CAAC;CACF"}

package/dist/tools/base/index.d.ts

@@ -0,0 +1,2 @@
+export { AbstractTool } from './abstractTool.js';
+export { AbstractWorkflowTool } from './abstractWorkflowTool.js';

package/dist/tools/base/index.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+export { AbstractTool } from './abstractTool.js';
+export { AbstractWorkflowTool } from './abstractWorkflowTool.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/base/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/base/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/tools/orchestrator/config.d.ts

@@ -0,0 +1,55 @@
+import { StateGraph } from '@langchain/langgraph';
+import { Logger } from '../../logging/logger.js';
+import { WorkflowStateManager } from '../../checkpointing/workflowStateManager.js';
+/**
+ * Orchestrator configuration interface
+ *
+ * Example usage:
+ * ```
+ * const MyWorkflowState = Annotation.Root({ messages: Annotation<string[]> });
+ * const workflow = new StateGraph(MyWorkflowState)
+ *   .addNode('start', (state) => ({ messages: ['Started'] }))
+ *   .addEdge(START, 'start')
+ *   .addEdge('start', END);
+ *
+ * const config: OrchestratorConfig = {
+ *   toolId: 'my-orchestrator',
+ *   title: 'My Orchestrator',
+ *   description: 'Orchestrates my workflow',
+ *   workflow,
+ * };
+ * ```
+ */
+export interface OrchestratorConfig {
+    /** Unique tool identifier for MCP registration */
+    toolId: string;
+    /** Extended tool title for display */
+    title: string;
+    /** Tool description for documentation */
+    description: string;
+    /**
+     * The LangGraph StateGraph workflow definition (uncompiled)
+     *
+     * Note: StateGraph generic types are inferred from construction and don't need
+     * to be specified here. The orchestrator will compile the workflow at runtime
+     * with the appropriate checkpointer.
+     */
+    workflow: StateGraph<any, any, any, any, any, any, any, any>;
+    /**
+     * Workflow state manager for checkpointing and persistence
+     *
+     * Optional - if not provided, a default WorkflowStateManager will be created
+     * with production environment settings.
+     *
+     * Provide a custom instance to:
+     * - Use test environment (in-memory state, no file I/O)
+     * - Customize well-known directory paths
+     * - Inject a mock for testing
+     */
+    stateManager?: WorkflowStateManager;
+    /**
+     * Logger instance for workflow operations
+     * Optional - defaults to logger using wellKnownDirectory for log files
+     */
+    logger?: Logger;
+}

package/dist/tools/orchestrator/config.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+export {};
+//# sourceMappingURL=config.js.map

package/dist/tools/orchestrator/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/tools/orchestrator/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/tools/orchestrator/index.d.ts

@@ -0,0 +1,3 @@
+export { type OrchestratorConfig } from './config.js';
+export { type OrchestratorInput, type OrchestratorOutput, type OrchestratorToolMetadata, ORCHESTRATOR_INPUT_SCHEMA, ORCHESTRATOR_OUTPUT_SCHEMA, createOrchestratorToolMetadata, } from './metadata.js';
+export { OrchestratorTool } from './orchestratorTool.js';

package/dist/tools/orchestrator/index.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+export { ORCHESTRATOR_INPUT_SCHEMA, ORCHESTRATOR_OUTPUT_SCHEMA, createOrchestratorToolMetadata, } from './metadata.js';
+export { OrchestratorTool } from './orchestratorTool.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/orchestrator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/orchestrator/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/tools/orchestrator/metadata.d.ts

@@ -0,0 +1,55 @@
+import z from 'zod';
+import { ToolMetadata } from '../../common/metadata.js';
+import type { OrchestratorConfig } from './config.js';
+/**
+ * Orchestrator input schema
+ *
+ * Note: The workflow state data is optional/defaulted because the orchestrator
+ * can start new workflows (where it doesn't exist yet) or continue existing ones.
+ */
+export declare const ORCHESTRATOR_INPUT_SCHEMA: z.ZodObject<{
+    userInput: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    workflowStateData: z.ZodDefault<z.ZodObject<{
+        thread_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        thread_id: string;
+    }, {
+        thread_id: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    workflowStateData: {
+        thread_id: string;
+    };
+    userInput?: Record<string, unknown> | undefined;
+}, {
+    workflowStateData?: {
+        thread_id: string;
+    } | undefined;
+    userInput?: Record<string, unknown> | undefined;
+}>;
+export type OrchestratorInput = z.infer<typeof ORCHESTRATOR_INPUT_SCHEMA>;
+/**
+ * Orchestrator output schema - natural language orchestration prompt
+ */
+export declare const ORCHESTRATOR_OUTPUT_SCHEMA: z.ZodObject<{
+    orchestrationInstructionsPrompt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    orchestrationInstructionsPrompt: string;
+}, {
+    orchestrationInstructionsPrompt: string;
+}>;
+export type OrchestratorOutput = z.infer<typeof ORCHESTRATOR_OUTPUT_SCHEMA>;
+/**
+ * Orchestrator tool metadata type
+ * The metadata for the orchestrator tool (inputs/outputs)
+ */
+export type OrchestratorToolMetadata = ToolMetadata<typeof ORCHESTRATOR_INPUT_SCHEMA, typeof ORCHESTRATOR_OUTPUT_SCHEMA>;
+/**
+ * Factory function to create orchestrator tool metadata from configuration
+ * Takes the consumer-provided config and creates the tool metadata with
+ * standardized input/output schemas.
+ *
+ * @param config - The orchestrator configuration
+ * @returns Tool metadata with the specified toolId, title, description
+ */
+export declare function createOrchestratorToolMetadata(config: OrchestratorConfig): OrchestratorToolMetadata;

package/dist/tools/orchestrator/metadata.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import z from 'zod';
+import { WORKFLOW_PROPERTY_NAMES, WORKFLOW_STATE_DATA_SCHEMA, } from '../../common/metadata.js';
+/**
+ * Orchestrator input schema
+ *
+ * Note: The workflow state data is optional/defaulted because the orchestrator
+ * can start new workflows (where it doesn't exist yet) or continue existing ones.
+ */
+export const ORCHESTRATOR_INPUT_SCHEMA = z.object({
+    [WORKFLOW_PROPERTY_NAMES.userInput]: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('User input - can be any data structure from initial request or previously executed MCP tool'),
+    [WORKFLOW_PROPERTY_NAMES.workflowStateData]: WORKFLOW_STATE_DATA_SCHEMA.default({
+        thread_id: '',
+    }).describe('Opaque workflow state data. Do not populate unless explicitly instructed to do so.'),
+});
+/**
+ * Orchestrator output schema - natural language orchestration prompt
+ */
+export const ORCHESTRATOR_OUTPUT_SCHEMA = z.object({
+    orchestrationInstructionsPrompt: z
+        .string()
+        .describe('The prompt describing the next workflow action for the LLM to execute.'),
+});
+/**
+ * Factory function to create orchestrator tool metadata from configuration
+ * Takes the consumer-provided config and creates the tool metadata with
+ * standardized input/output schemas.
+ *
+ * @param config - The orchestrator configuration
+ * @returns Tool metadata with the specified toolId, title, description
+ */
+export function createOrchestratorToolMetadata(config) {
+    return {
+        toolId: config.toolId,
+        title: config.title,
+        description: config.description,
+        inputSchema: ORCHESTRATOR_INPUT_SCHEMA,
+        outputSchema: ORCHESTRATOR_OUTPUT_SCHEMA,
+    };
+}
+//# sourceMappingURL=metadata.js.map

package/dist/tools/orchestrator/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../../src/tools/orchestrator/metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,CAAC,MAAM,KAAK,CAAC;AACpB,OAAO,EAEL,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAGlC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,CAAC,uBAAuB,CAAC,SAAS,CAAC,EAAE,CAAC;SACnC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CACP,6FAA6F,CAC9F;IACH,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,EAAE,0BAA0B,CAAC,OAAO,CAAC;QAC9E,SAAS,EAAE,EAAE;KACd,CAAC,CAAC,QAAQ,CAAC,oFAAoF,CAAC;CAClG,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,+BAA+B,EAAE,CAAC;SAC/B,MAAM,EAAE;SACR,QAAQ,CAAC,wEAAwE,CAAC;CACtF,CAAC,CAAC;AAaH;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAA0B;IAE1B,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,yBAAyB;QACtC,YAAY,EAAE,0BAA0B;KACzC,CAAC;AACJ,CAAC"}

package/dist/tools/orchestrator/orchestratorTool.d.ts

@@ -0,0 +1,39 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AbstractTool } from '../base/abstractTool.js';
+import { OrchestratorConfig } from './config.js';
+import { OrchestratorInput, OrchestratorToolMetadata } from './metadata.js';
+/**
+ * Orchestrator Tool
+ *
+ * Orchestrates workflow execution using LangGraph.js for deterministic state management
+ * and human-in-the-loop patterns for agentic task execution.
+ *
+ * The orchestrator accepts a configured StateGraph and manages:
+ * - Thread-based session management
+ * - Workflow interrupts and resumptions
+ * - LLM orchestration prompts for tool invocation
+ *
+ * All state management and checkpointing responsibilities are delegated to WorkflowStateManager.
+ */
+export declare class OrchestratorTool extends AbstractTool<OrchestratorToolMetadata> {
+    private readonly config;
+    private readonly stateManager;
+    constructor(server: McpServer, config: OrchestratorConfig);
+    /**
+     * Handle orchestrator requests - manages workflow state and execution
+     */
+    handleRequest: (input: OrchestratorInput) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        structuredContent: {
+            orchestrationInstructionsPrompt: string;
+        };
+    }>;
+    private processRequest;
+    /**
+     * Create orchestration prompt for LLM with embedded tool invocation data and workflow state
+     */
+    private createOrchestrationPrompt;
+}

package/dist/tools/orchestrator/orchestratorTool.js

@@ -0,0 +1,186 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { Command } from '@langchain/langgraph';
+import { createWorkflowLogger } from '../../logging/logger.js';
+import { AbstractTool } from '../base/abstractTool.js';
+import { WORKFLOW_PROPERTY_NAMES, } from '../../common/metadata.js';
+import { WorkflowStateManager } from '../../checkpointing/workflowStateManager.js';
+import { createOrchestratorToolMetadata, } from './metadata.js';
+/**
+ * Generate unique thread ID for workflow sessions
+ */
+function generateUniqueThreadId() {
+    return `mmw-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+}
+/**
+ * Orchestrator Tool
+ *
+ * Orchestrates workflow execution using LangGraph.js for deterministic state management
+ * and human-in-the-loop patterns for agentic task execution.
+ *
+ * The orchestrator accepts a configured StateGraph and manages:
+ * - Thread-based session management
+ * - Workflow interrupts and resumptions
+ * - LLM orchestration prompts for tool invocation
+ *
+ * All state management and checkpointing responsibilities are delegated to WorkflowStateManager.
+ */
+export class OrchestratorTool extends AbstractTool {
+    config;
+    stateManager;
+    constructor(server, config) {
+        // Use provided logger or create workflow logger with component name
+        const effectiveLogger = config.logger || createWorkflowLogger('OrchestratorTool');
+        super(server, createOrchestratorToolMetadata(config), 'OrchestratorTool', effectiveLogger);
+        this.config = config;
+        // Initialize state manager (use provided or create default for production)
+        this.stateManager =
+            config.stateManager || new WorkflowStateManager({ environment: 'production' });
+    }
+    /**
+     * Handle orchestrator requests - manages workflow state and execution
+     */
+    handleRequest = async (input) => {
+        this.logger.debug('Orchestrator tool called with input', input);
+        try {
+            const result = await this.processRequest(input);
+            this.logger.debug('Orchestrator returning result', result);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            this.logger.error('Error in orchestrator tool execution', error);
+            throw error;
+        }
+    };
+    async processRequest(input) {
+        // Generate or use existing thread ID for workflow session
+        let threadId = '';
+        try {
+            const parsedInput = this.toolMetadata.inputSchema.parse(input);
+            threadId = parsedInput.workflowStateData.thread_id;
+        }
+        catch (error) {
+            this.logger.error('Error parsing orchestrator input. Starting a new workflow.', error);
+        }
+        if (threadId === '') {
+            threadId = generateUniqueThreadId();
+        }
+        const workflowStateData = { thread_id: threadId };
+        this.logger.info('Processing orchestrator request', {
+            threadId,
+            hasUserInput: !!input.userInput,
+            isResumption: !!input.workflowStateData?.thread_id,
+        });
+        // Thread configuration for LangGraph
+        const threadConfig = { configurable: { thread_id: threadId } };
+        // Get checkpointer from state manager
+        const checkpointer = await this.stateManager.createCheckpointer();
+        // Compile workflow with checkpointer
+        const compiledWorkflow = this.config.workflow.compile({ checkpointer });
+        // Check for interrupted workflow state
+        this.logger.debug('Checking for interrupted workflow state');
+        let graphState = await compiledWorkflow.getState(threadConfig);
+        const interruptedTask = graphState.tasks.find(task => task.interrupts.length > 0);
+        let result;
+        if (interruptedTask) {
+            this.logger.info('Resuming interrupted workflow', {
+                taskId: interruptedTask.id,
+                interrupts: interruptedTask.interrupts.length,
+            });
+            // Resume workflow with user input from previous tool execution
+            result = await compiledWorkflow.invoke(new Command({ resume: input.userInput }), threadConfig);
+        }
+        else {
+            // Start new workflow session
+            this.logger.info('Starting new workflow execution');
+            result = await compiledWorkflow.invoke({
+                userInput: input.userInput,
+            }, threadConfig);
+        }
+        this.logger.debug('Processing workflow result');
+        graphState = await compiledWorkflow.getState(threadConfig);
+        if (graphState.next.length > 0) {
+            // There are more nodes to execute.
+            const mcpToolInvocationData = '__interrupt__' in result
+                ? result.__interrupt__[0].value
+                : undefined;
+            if (!mcpToolInvocationData) {
+                this.logger.error('Workflow completed without expected MCP tool invocation.');
+                throw new Error('FATAL: Unexpected workflow state without an interrupt');
+            }
+            this.logger.info('Invoking next MCP tool', {
+                toolName: mcpToolInvocationData.llmMetadata?.name,
+            });
+            // Create orchestration prompt
+            const orchestrationPrompt = this.createOrchestrationPrompt(mcpToolInvocationData, workflowStateData);
+            // Save the workflow state.
+            await this.stateManager.saveCheckpointerState(checkpointer);
+            return {
+                orchestrationInstructionsPrompt: orchestrationPrompt,
+            };
+        }
+        // Workflow completed.
+        return {
+            orchestrationInstructionsPrompt: 'The workflow has concluded. No further workflow actions are forthcoming.',
+        };
+    }
+    /**
+     * Create orchestration prompt for LLM with embedded tool invocation data and workflow state
+     */
+    createOrchestrationPrompt(mcpToolInvocationData, workflowStateData) {
+        return `
+# Your Role
+
+You are participating in a workflow orchestration process. The current
+(\`${this.toolMetadata.toolId}\`) MCP server tool is the orchestrator, and is sending
+you instructions on what to do next. These instructions describe the next participating
+MCP server tool to invoke, along with its input schema and input values.
+
+# Your Task
+
+Invoke the following MCP server tool:
+
+**MCP Server Tool Name**: ${mcpToolInvocationData.llmMetadata?.name}
+**MCP Server Tool Input Schema**:
+\`\`\`json
+${JSON.stringify(zodToJsonSchema(mcpToolInvocationData.llmMetadata?.inputSchema))}
+\`\`\`
+**MCP Server Tool Input Values**:
+\`\`\`json
+${JSON.stringify(mcpToolInvocationData.input)}
+\`\`\`
+
+## Additional Input: \`${WORKFLOW_PROPERTY_NAMES.workflowStateData}\`
+
+\`${WORKFLOW_PROPERTY_NAMES.workflowStateData}\` is an additional input parameter that is
+specified in the input schema above, and should be passed to the next MCP server tool
+invocation, with the following object value:
+
+\`\`\`json
+${JSON.stringify(workflowStateData)}
+\`\`\`
+
+This represents opaque workflow state data that should be round-tripped back to the
+\`${this.toolMetadata.toolId}\` MCP server tool orchestrator at the completion of the
+next MCP server tool invocation, without modification. These instructions will be further
+specified by the next MCP server tool invocation.
+
+The MCP server tool you invoke will respond with its output, along with further
+instructions for continuing the workflow.
+`;
+    }
+}
+//# sourceMappingURL=orchestratorTool.js.map

package/dist/tools/orchestrator/orchestratorTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestratorTool.js","sourceRoot":"","sources":["../../../src/tools/orchestrator/orchestratorTool.ts"],"names":[],"mappings":"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"}

package/dist/tools/utilities/getInput/factory.d.ts

@@ -0,0 +1,43 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Logger } from '../../../logging/logger.js';
+import { GetInputTool } from './tool.js';
+/**
+ * Configuration options for creating a Get Input Tool
+ */
+export interface GetInputToolOptions {
+    /**
+     * The tool ID to use for the get input tool
+     */
+    toolId: string;
+    /**
+     * Orchestrator tool ID that this tool reports back to
+     * @required
+     */
+    orchestratorToolId: string;
+    /**
+     * Optional logger instance for tool operations
+     */
+    logger?: Logger;
+}
+/**
+ * Factory function to create a Get Input Tool with configurable tool ID
+ *
+ * @param server - The MCP server instance
+ * @param options - Configuration options for the tool
+ * @returns A configured Get Input Tool instance ready for registration
+ *
+ * @example
+ * // Simple case - single MCP server
+ * const getInputTool = createGetInputTool(server, {
+ *   toolId: 'magen-get-input',
+ *   orchestratorToolId: 'my-orchestrator',
+ * });
+ *
+ * @example
+ * // Multi-server environment - avoid collisions
+ * const getInputTool = createGetInputTool(server, {
+ *   toolId: 'mobile-magen-get-input',
+ *   orchestratorToolId: 'mobile-orchestrator',
+ * });
+ */
+export declare function createGetInputTool(server: McpServer, options: GetInputToolOptions): GetInputTool;

package/dist/tools/utilities/getInput/factory.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { GetInputTool } from './tool.js';
+/**
+ * Factory function to create a Get Input Tool with configurable tool ID
+ *
+ * @param server - The MCP server instance
+ * @param options - Configuration options for the tool
+ * @returns A configured Get Input Tool instance ready for registration
+ *
+ * @example
+ * // Simple case - single MCP server
+ * const getInputTool = createGetInputTool(server, {
+ *   toolId: 'magen-get-input',
+ *   orchestratorToolId: 'my-orchestrator',
+ * });
+ *
+ * @example
+ * // Multi-server environment - avoid collisions
+ * const getInputTool = createGetInputTool(server, {
+ *   toolId: 'mobile-magen-get-input',
+ *   orchestratorToolId: 'mobile-orchestrator',
+ * });
+ */
+export function createGetInputTool(server, options) {
+    return new GetInputTool(server, options.toolId, options.orchestratorToolId, options.logger);
+}
+//# sourceMappingURL=factory.js.map

package/dist/tools/utilities/getInput/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../../src/tools/utilities/getInput/factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAuBzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,OAA4B;IAChF,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AAC9F,CAAC"}

package/dist/tools/utilities/getInput/index.d.ts

@@ -0,0 +1,3 @@
+export * from './tool.js';
+export * from './metadata.js';
+export * from './factory.js';

package/dist/tools/utilities/getInput/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+export * from './tool.js';
+export * from './metadata.js';
+export * from './factory.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/utilities/getInput/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/tools/utilities/getInput/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}