Add ExecPlan: translate tool schemas per backend (2.3.3)#73
Draft
leynos wants to merge 1 commit into
Draft
Conversation
This new document outlines the detailed plan to bridge the gap between canonical Model Context Protocol (MCP) tool definitions and backend-specific tool schema translation in the Corbusier system. It establishes the translation seam, defines constraints, risks, tolerances, and a staged implementation roadmap for delivering automatic backend-specific tool schema translation and validation. The execplan covers design, testing strategies, domain boundaries, decision logs, and expected outcomes, serving as a comprehensive guide to implement roadmap item 2.3.3. Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
Contributor
Reviewer's GuideAdds a new execution plan document describing how to implement backend-specific translation of canonical MCP tool schemas within the agent backend/orchestrator, including architecture constraints, risks, and a staged (A–G) implementation and testing strategy. Sequence diagram for turn execution with backend-specific tool schema translationsequenceDiagram
actor Caller
participant AgentTurnOrchestratorService
participant ToolDiscoveryPort
participant ToolRegistryCatalogue
participant AgentRuntimePort
participant RuntimeAdapter
participant ToolRouterPort
Caller->>AgentTurnOrchestratorService: ExecuteAgentTurnRequest
AgentTurnOrchestratorService->>ToolDiscoveryPort: list_canonical_tools(backend_id, conversation_id)
ToolDiscoveryPort->>ToolRegistryCatalogue: fetch_mcp_tools(conversation_id)
ToolRegistryCatalogue-->>ToolDiscoveryPort: Vec<McpToolDefinition>
ToolDiscoveryPort-->>AgentTurnOrchestratorService: Vec<CanonicalToolDto>
AgentTurnOrchestratorService->>AgentRuntimePort: prepare_runtime_request(TurnExecutionRequest, Vec<CanonicalToolDto>)
AgentRuntimePort->>RuntimeAdapter: translate_tools_and_build_request(TurnExecutionRequest, Vec<CanonicalToolDto>)
RuntimeAdapter-->>AgentRuntimePort: PreparedRuntimeTurnRequest or TranslationError
alt translation_success
AgentRuntimePort-->>AgentTurnOrchestratorService: PreparedRuntimeTurnRequest
AgentTurnOrchestratorService->>AgentRuntimePort: execute_turn(PreparedRuntimeTurnRequest)
AgentRuntimePort->>RuntimeAdapter: execute_turn(PreparedRuntimeTurnRequest)
RuntimeAdapter-->>AgentRuntimePort: TurnResult with tool_calls
AgentRuntimePort-->>AgentTurnOrchestratorService: TurnResult
loop each_emitted_tool_call
AgentTurnOrchestratorService->>ToolRouterPort: route_tool_call(canonical_tool_name, payload)
ToolRouterPort->>ToolRegistryCatalogue: dispatch_and_execute_tool_call
ToolRegistryCatalogue-->>ToolRouterPort: ToolCallResult
ToolRouterPort-->>AgentTurnOrchestratorService: ToolCallResult
end
AgentTurnOrchestratorService-->>Caller: TurnResult with tool_call_outcomes
else translation_failure
AgentRuntimePort-->>AgentTurnOrchestratorService: TranslationError
AgentTurnOrchestratorService-->>Caller: ErrorResponse(TranslationError)
end
Class diagram for planned tool schema translation contractsclassDiagram
class McpToolDefinition {
+String name
+String description
+JsonSchema input_schema
+JsonSchema output_schema
}
class CanonicalToolDto {
+String name
+String description
+JsonSchema input_schema
+JsonSchema output_schema
}
class TranslatedToolEnvelope {
+String canonical_name
+BackendToolPayload backend_payload
+bool is_supported
}
class TurnExecutionRequest {
+Uuid conversation_id
+String prompt
+Vec<ToolCall> tool_calls
}
class PreparedRuntimeTurnRequest {
+Uuid conversation_id
+String prompt
+Vec<ToolCall> tool_calls
+Vec<TranslatedToolEnvelope> available_tools
}
class TranslationError {
+TranslationErrorKind kind
+String message
}
class TranslationErrorKind {
<<enumeration>>
UnsupportedCanonicalShape
BackendIncompatible
InfrastructureFailure
}
class ToolDiscoveryPort {
+Vec<CanonicalToolDto> list_canonical_tools(Uuid conversation_id, BackendId backend_id)
}
class AgentRuntimePort {
+PreparedRuntimeTurnRequest prepare_runtime_request(TurnExecutionRequest request, Vec<CanonicalToolDto> canonical_tools) TranslationError
+TurnResult execute_turn(PreparedRuntimeTurnRequest prepared_request) RuntimeError
}
class ToolRouterPort {
+ToolCallResult route_tool_call(String canonical_tool_name, ToolCallPayload payload)
}
class AgentTurnOrchestratorService {
+TurnResult execute_turn(ExecuteAgentTurnRequest request)
-PreparedRuntimeTurnRequest prepare_request(TurnExecutionRequest request)
}
class ExecuteAgentTurnRequest {
+Uuid conversation_id
+String prompt
}
class BackendId {
+String backend_name
}
class TurnResult
class ToolCall
class ToolCallPayload
class ToolCallResult
class BackendToolPayload
class RuntimeError
class JsonSchema
class Uuid
McpToolDefinition <.. CanonicalToolDto : mapped_from
CanonicalToolDto --> JsonSchema
ToolDiscoveryPort --> CanonicalToolDto
ToolDiscoveryPort --> BackendId
AgentRuntimePort --> PreparedRuntimeTurnRequest
AgentRuntimePort --> CanonicalToolDto
AgentRuntimePort --> TranslationError
AgentRuntimePort --> TurnResult
AgentRuntimePort --> RuntimeError
AgentTurnOrchestratorService --> ToolDiscoveryPort
AgentTurnOrchestratorService --> AgentRuntimePort
AgentTurnOrchestratorService --> ToolRouterPort
AgentTurnOrchestratorService --> TurnExecutionRequest
AgentTurnOrchestratorService --> PreparedRuntimeTurnRequest
AgentTurnOrchestratorService --> TurnResult
PreparedRuntimeTurnRequest --> TranslatedToolEnvelope
TranslatedToolEnvelope --> BackendToolPayload
TranslationError --> TranslationErrorKind
ToolRouterPort --> ToolCallResult
ToolRouterPort --> ToolCallPayload
Flow diagram for execution plan stages A–Gflowchart TD
A["Stage A: establish seam and add failing tests"] --> B["Stage B: add domain and port contracts"]
B --> C["Stage C: implement backend-specific translation in runtime adapters"]
C --> D["Stage D: wire translation into orchestration and tool discovery"]
D --> E["Stage E: complete full test matrix (unit, integration, BDD)"]
E --> F["Stage F: update design docs, user guide, roadmap"]
F --> G["Stage G: run validation gates and capture evidence"]
subgraph TestingFocus
A
E
G
end
subgraph DesignAndContracts
B
C
D
F
end
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new execution plan document for roadmap item 2.3.3: Translate tool schemas per backend. This plan outlines the purpose, constraints, tolerances, risks, and a staged approach to translating canonical MCP tool definitions into backend-specific schemas, enabling automated translation within the orchestration flow without manual glue.
Changes
Rationale
Key content (high level)
Plan of work (stages at a glance)
Testing and validation approach
Documentation impact
Risks and dependencies (high level)
How to review
Notes for maintainers
◳ Generated by DevBoxer ◰
ℹ️ Tag @devboxerhub to ask questions and address PR feedback
📎 Task: https://www.devboxer.com/task/e1241ba7-4c85-4c65-8dd5-3929499256c2
Summary by Sourcery
Documentation: