fix: delegate get input to orchestrator tool by haifeng-li-at-salesforce · Pull Request #132 · forcedotcom/mobile-mcp-tools

haifeng-li-at-salesforce · 2026-01-13T19:47:57Z

Changes

Adds support for delegating getInput calls to the orchestrator tool
Updates the orchestrator tool to handle getInput requests
Adds metadata support for input delegation
Includes corresponding tests and documentation updates

Files Changed

`docs/9_mcp_workflow_engine_extraction/design.md` - Documentation updates
`packages/mcp-workflow/src/common/metadata.ts` - Metadata type additions
`packages/mcp-workflow/src/services/getInputService.ts` - Service updates
`packages/mcp-workflow/src/tools/orchestrator/metadata.ts` - Orchestrator metadata
`packages/mcp-workflow/src/tools/orchestrator/orchestratorTool.ts` - Main implementation
`packages/mcp-workflow/tests/services/getInputService.test.ts` - Service tests
`packages/mcp-workflow/tests/tools/orchestrator/orchestratorTool.test.ts` - Orchestrator tests"

What issues does this PR fix or reference?

it fixes the getInput off-trail issues

jhorst11 · 2026-01-13T20:05:04Z

packages/mcp-workflow/src/tools/orchestrator/orchestratorTool.ts

have you considered rather than embedding input logic in the orchestrator, keeping it in the node itself?

here is a spike I did on "Guidance-only" nodes - it might be a bit verbose but the idea is still encapsulating the guidance within the responsible node rather than have the orchestrator be responsible for everything

jhorst11@265265c#diff-26a7cf13d2b4b7ead6b447baa60686a300769ec0ad50a81d81c36ee4d7a70c5d

I think we'll want to replicate the pattern of direct-guidance nodes beyond just input so I'm hestitant to embed this logic directly into the orchestrator tool

Totally agree. Overloading the orchestrator tool is not a good idea. This logic should live at the node level so it can be applied consistently across all nodes in the future. I’m thinking each node could support two modes: a direct guidance mode and a tool delegation mode.

The following changes have been implemented:

Added a direct guidance mode alongside the existing delegation mode. In direct guidance mode, the guidances are handled directly by the orchestrator.

Introduced NodeGuidanceData for direct guidance mode, serving as the counterpart to MCPToolInvocationData.

Added an exampleOutput field to NodeGuidanceData to improve LLM compliance and response consistency.

codecov-commenter · 2026-01-14T07:02:20Z

Codecov Report

❌ Patch coverage is 95.19231% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.29%. Comparing base (e87d017) to head (6e90fe0).

Files with missing lines	Patch %	Lines
...orkflow/src/tools/orchestrator/orchestratorTool.ts	89.13%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #132      +/-   ##
==========================================
+ Coverage   88.25%   88.29%   +0.04%     
==========================================
  Files         165      165              
  Lines        7059     7119      +60     
  Branches      994      981      -13     
==========================================
+ Hits         6230     6286      +56     
- Misses        829      833       +4

Flag	Coverage Δ
evaluation	`80.14% <ø> (ø)`
monorepo	`88.29% <95.19%> (+0.04%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

khawkins · 2026-01-15T21:53:02Z

packages/mcp-workflow/src/tools/orchestrator/orchestratorTool.ts

+You are participating in a workflow orchestration process. The orchestrator is providing
+you with direct guidance for the current task.
+
+# TASK GUIDANCE


Unless there's specific evaluation that suggests the guidance should come first, I'd prefer that we put INPUT SCHEMA and INPUT DATA before TASK GUIDANCE. It's typical practice to put the context section of a prompt earlier than the guidance itself, so that the LLM doesn't have to "go backwards" and reconsider semantics it already considered, through the lens of the "new info" that is its inputs. It just simplifies the logical processing of the semantics of the prompt.

The INPUT SCHEMA and INPUT DATA sections are removed from createDirectGuidancePrompt to reduce token usage without losing any functional information, since generateTaskGuidance is designed to be self-contained and already includes all the context the LLM needs. The test result looks solid.

They are not removed at the moment—they are 4 lines down from here. :) My suggestion here was just to define them before the TASK GUIDANCE section, instead of after.

I am not sure what happens. But it is removed in my branch

I understand your suggestions. However, after further investigation, it turns out that both INPUT_SCHEMA and INPUT_DATA are redundant.

I understand why the changes aren’t visible. In the top-left selection box, choose “Changes from all commits” to see the latest updates.

Ah, got it. I don't disagree that I think we can live without it. I was just confused because it still seemed to be there. Seems fine in the latest version.

packages/mcp-workflow/src/common/metadata.ts

… OrchestratorTool

… orchestrator

khawkins · 2026-01-16T18:20:25Z

packages/mcp-workflow/src/common/metadata.ts

I'm not clear on the design pattern here. Why are we delegating the initiation of guidance creation to the orchestrator? What part is it meant to play in owning that process? Why would we not simply seed NodeGuidanceData.taskGuidance with each node's expression of guidance.

This data structure is making a round trip back to the node that's responsible for generating guidance anyway. I'm not seeing the value in that process.

Actually, we're not even delegating responsibility to the orchestrator: we're just delegating our node class's API to a different data structure. That doesn't pass muster to me. I don't actually see value in codifying the way that nodes create guidance. I think each node can be left to its own devices as to how it needs to formulate the guidance it sends along. There is no value that I can see in a shared commonality here.

The data flow is as following:

Service (e.g., GetInputService) calls metadata.generateTaskGuidance!(input) to get the guidance string

Service populates NodeGuidanceData.taskGuidance with that string

Service calls interrupt(nodeGuidanceData) - sending everything to the orchestrator

Orchestrator receives the pre-populated NodeGuidanceData and wraps it with workflow continuation instructions via createDirectGuidancePrompt()

The orchestrator simply reads taskGuidance from the interrupt data - it doesn't generate it.

The generateTaskGuidance function exists as a single source of truth for guidance generation that can be used by both execution modes:

Direct Guidance Mode (via Services): The service calls metadata.generateTaskGuidance() and populates NodeGuidanceData.taskGuidance before interrupting

Delegate Mode (via Tools): When the tool is invoked as a separate MCP tool, it calls metadata.generateTaskGuidance() directly:

Once all remaining delegated tools (five in total) are removed, we can replace WorkflowToolMetadata with NodeGuidanceMetadata, which will live in the Node/Service.

The generateTaskGuidance function exists as a single source of truth for guidance generation that can be used by both execution modes:

My argument is that it doesn't serve sufficient purpose to create such an abstraction. The creation of guidance lives pretty concretely with the code base that implements a given agent, be it a node, service, or MCP tool. These agentic foundations are mutually exclusive from each other, which is the only scenario I could think of where we may want to consolidate this guidance.

And the reason that I'm looking for a justification of it, is to offset the penalty for the implementation: a code maintainer has to follow code around through a few different passage points to find the source of this guidance, when logically speaking you'd expect to find it "close to" the agent code base that defines it.

I think it's telling that we're not implementing this all across our existing nodes, services, and MCP tools as part of this refactor, and yet the sky is not falling from failing to do so. This to me is an abstraction that does not benefit the code base—only obfuscates it unnecessarily.

That makes total sense. I agree that the recommendation is much more intuitive; my current implementation is a bit counter-intuitive. I’ll refactor the code to move guidance creation from tool metadata into the Agent class (node/service). This change will apply specifically to the get Input and extract input services.

@khawkins The following code changes have been made. Please take another look and let me know your thoughts. Thanks!

Moving guidance generation logic from metadata classes into the services themselves (InputExtractionService and GetInputService)

Simplifying the architecture - the metadata.ts base class no longer has tool-specific functions; guidance generation is now handled directly by the services

packages/mcp-workflow/src/services/getInputService.ts

packages/mcp-workflow/src/tools/orchestrator/metadata.ts

khawkins

This looks great overall! I'd like to answer the questions around generateTaskGuidance and the minor one around the ordering in the direct guidance prompt in the orchestrator. But I think overall this is solid.

…putExtractionService

…nctions from metadata class and consolidating logic in InputExtractionService and GetInputService

khawkins

This looks good to me!

haifeng-li-at-salesforce requested a review from a team as a code owner January 13, 2026 19:47

jhorst11 reviewed Jan 13, 2026

View reviewed changes

fix: delegate get input to orchestrator tool

dbb6f8b

haifeng-li-at-salesforce force-pushed the simpleGetInput branch from 0ed63e1 to dbb6f8b Compare January 13, 2026 20:11

haifeng-li-at-salesforce added 2 commits January 13, 2026 21:25

fix: generic direct guidance in orchestrator tool

6b21c2c

fix: modify the direct guide to comply with the result schema

6e90fe0

doc: update document

86edebf

khawkins reviewed Jan 15, 2026

View reviewed changes

packages/mcp-workflow/src/common/metadata.ts Show resolved Hide resolved

haifeng-li-at-salesforce added 5 commits January 15, 2026 21:59

feat: move input extraction to orchestrator tool

92dd644

fix: add example to improve the LLM compliance

21390a1

Merge upstream/main into simpleGetInput

6663239

refactor: remove input schema and data sections from task guidance in…

416b2f2

… OrchestratorTool

test: add environment variable management for workflow state tests in…

1793561

… orchestrator

khawkins reviewed Jan 16, 2026

View reviewed changes

packages/mcp-workflow/src/services/getInputService.ts Outdated Show resolved Hide resolved

khawkins reviewed Jan 16, 2026

View reviewed changes

packages/mcp-workflow/src/tools/orchestrator/metadata.ts Outdated Show resolved Hide resolved

khawkins reviewed Jan 16, 2026

View reviewed changes

haifeng-li-at-salesforce added 2 commits January 16, 2026 13:35

refactor: simplify exampleOutput formatting in GetInputService and In…

56ced0f

…putExtractionService

refactor: streamline guidance generation by removing tool-specific fu…

9e7a7bb

…nctions from metadata class and consolidating logic in InputExtractionService and GetInputService

khawkins approved these changes Jan 20, 2026

View reviewed changes

haifeng-li-at-salesforce merged commit 79eb1bd into forcedotcom:main Jan 20, 2026
9 of 11 checks passed

khawkins mentioned this pull request Jan 26, 2026

More node guidance updates #146

Merged

Conversation

haifeng-li-at-salesforce commented Jan 13, 2026

Changes

Files Changed

What issues does this PR fix or reference?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented Jan 14, 2026

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

haifeng-li-at-salesforce Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

haifeng-li-at-salesforce Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

haifeng-li-at-salesforce Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

khawkins left a comment

Choose a reason for hiding this comment

Uh oh!

khawkins left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Comments

haifeng-li-at-salesforce Jan 16, 2026 •

edited

Loading

haifeng-li-at-salesforce Jan 16, 2026 •

edited

Loading

haifeng-li-at-salesforce Jan 17, 2026 •

edited

Loading