Tool Execution Workflow

End-to-End Flow Diagram

Explorer user interface (UI) / MCP Browser Client
        |
        | callTool(name, input)
        v
Ploinky Router -> AgentServer (/mcp)
        |
        | spawn command from mcp-config.json
        v
/code/soplang-tool.sh (TOOL_NAME=...)
        |
        | read JSON payload from stdin
        | deriveInvocation(toolName, payload)
        v
Node wrapper runtime
        |
        | register SOPLang plugins
        | register AchillesSkills plugin
        | register SoplangBuilder plugin
        | discover skills and register as SOPLang commands
        v
targetPlugin[targetMethod](...params)
        |
        | optional workspace.forceSave() (tool specific)
        | workspace.shutDown() (always at wrapper exit)
        v
JSON result -> MCP response -> Explorer user interface

Detailed Execution Stages

1. Dispatch: AgentServer reads soplangAgent/mcp-config.json and executes /code/soplang-tool.sh for the selected tool.
2. Input bootstrap: wrapper reads stdin payload ({ tool, input, metadata }) and validates required env variables like TOOL_NAME.
3. Invocation mapping: tool name is mapped to plugin method by plugins/lib/toolInvocation.mjs.
4. Plugin registration: SOPLang core plugins are loaded, then AchillesSkills and SoplangBuilder are registered.
5. Skill registration: Achilles skill catalog is discovered and each skill is registered as a SOPLang command (same process lifetime).
6. Method execution: selected plugin method executes and returns JSON payload to stdout.
7. Persistence finalize: some tools call workspace.forceSave() during execution; wrapper then calls workspace.shutDown() before process exit.

Persistence Notes

For document sync, the core implementation performs workspace.forceSave() after sync to persist state updates. Independently of tool type, wrapper-level shutdown executes workspace.shutDown() to close persistence cleanly.